harnessbridge

package
v0.0.8 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 15, 2026 License: MIT Imports: 45 Imported by: 0

Documentation

Overview

Package harnessbridge owns the rocketcode library bridge.

Index

Constants

View Source
const (
	GoalStatusActive          = "active"
	GoalStatusProgress        = "progress"
	GoalStatusComplete        = "complete"
	GoalStatusBlocked         = "blocked"
	GoalStatusStopped         = "stopped"
	GoalStatusBudgetExhausted = "budget_exhausted"
)

GoalStatusActive and related constants are persisted goal-loop statuses.

View Source
const RawRunExposedToolName = rawRunToolName

RawRunExposedToolName is the tool cron prompts use for human-visible output.

Variables

View Source
var ErrGoalAlreadyActive = errors.New("goal already active")

ErrGoalAlreadyActive reports that a conversation already has an active goal.

View Source
var ErrStateStoreLocked = errors.New("rocketclaw state store is locked")

ErrStateStoreLocked reports that another RocketClaw process owns the state store.

Functions

func DeleteSessionIn

func DeleteSessionIn(ctx context.Context, workspace, workDir, conversationID string) (int64, error)

DeleteSessionIn removes all entries for one conversation ID in workDir and returns deleted rows.

func DiscordResponseCheckpointKey

func DiscordResponseCheckpointKey(channelID, messageID string) string

DiscordResponseCheckpointKey returns the stable key for one posted Discord AI response message.

func DiscordThreadConversationID

func DiscordThreadConversationID(threadID string) string

DiscordThreadConversationID returns the stable conversation ID for a Discord thread.

func DiscordThreadTarget added in v0.0.7

func DiscordThreadTarget(conversationID string) (threadID string, ok bool)

DiscordThreadTarget returns the Discord thread ID for a Discord thread conversation ID.

func ExternalMCPAgentsIn

func ExternalMCPAgentsIn(workspace, workDir string) ([]string, error)

ExternalMCPAgentsIn returns agents externally selectable through MCP in workDir.

func RecoverSessionDBIfCorrupt

func RecoverSessionDBIfCorrupt(ctx context.Context, workspace, workDir string) (bool, error)

RecoverSessionDBIfCorrupt recovers a corrupt existing state DB before daemon startup proceeds.

func SessionDBPathIn

func SessionDBPathIn(workspace, workDir string) string

SessionDBPathIn returns the SQLite database path for rocketcode session inspection in workDir.

func SlackResponseCheckpointKey

func SlackResponseCheckpointKey(channelID, messageTS string) string

SlackResponseCheckpointKey returns the stable key for one posted Slack AI response message.

func SlackThreadConversationID

func SlackThreadConversationID(channelID, threadTS string) string

SlackThreadConversationID returns the stable conversation ID for a Slack thread.

func SlackThreadTarget added in v0.0.7

func SlackThreadTarget(conversationID string) (channelID, threadTS string, ok bool)

SlackThreadTarget returns the Slack channel and thread timestamp for a Slack thread conversation ID.

func ValidateGoalCheckScriptStart added in v0.0.7

func ValidateGoalCheckScriptStart(cfg *config.Config, agentName, script string) error

ValidateGoalCheckScriptStart validates a goal check script before goal persistence.

Types

type Bridge

type Bridge struct {
	// contains filtered or unexported fields
}

Bridge forwards rocketclaw messages into one turn-lived rocketcode run per turn.

func NewConversation

func NewConversation(cfg *config.Config, bus *events.Bus, bridgeConfig *Config, logger *slog.Logger) *Bridge

NewConversation constructs a rocketcode bridge for one conversation.

func (*Bridge) InterruptActiveTurn added in v0.0.7

func (b *Bridge) InterruptActiveTurn() *events.InboundMessage

InterruptActiveTurn interrupts current work and clears queued work for this bridge.

func (*Bridge) ResetScheduledMessages

func (b *Bridge) ResetScheduledMessages() error

ResetScheduledMessages deletes pending scheduled prompts for this conversation.

func (*Bridge) ScheduleMessage

func (b *Bridge) ScheduleMessage(delay time.Duration, message string, recurring bool) error

ScheduleMessage schedules one delayed prompt for this conversation.

func (*Bridge) SeedResponseThread

func (b *Bridge) SeedResponseThread(ctx context.Context, checkpoint events.ResponseCheckpoint, _ string) error

SeedResponseThread initializes an empty thread session from a main-session response checkpoint.

func (*Bridge) SeedThreadFromCron

func (b *Bridge) SeedThreadFromCron(ctx context.Context, seedText string) error

SeedThreadFromCron initializes an empty Slack thread session from cron output.

func (*Bridge) SeedThreadFromMain

func (b *Bridge) SeedThreadFromMain(ctx context.Context) error

SeedThreadFromMain initializes an empty thread session from current main-session context.

func (*Bridge) Start

func (b *Bridge) Start(ctx context.Context) error

Start begins forwarding and handling messages for the conversation.

func (*Bridge) Stop

func (b *Bridge) Stop() error

Stop cancels bridge activity.

func (*Bridge) Submit

func (b *Bridge) Submit(ctx context.Context, msg *events.InboundMessage) error

Submit enqueues one inbound message for this conversation.

func (*Bridge) Summarize

func (b *Bridge) Summarize(ctx context.Context, prompt string) (string, error)

Summarize asks the conversation to produce a short summary.

func (*Bridge) WaitIdle

func (b *Bridge) WaitIdle(ctx context.Context) error

WaitIdle waits until queued bridge work has drained.

type Config

type Config struct {
	ConversationID, Agent string
	ConsumeSharedInbound  bool
	OutputTargets         []events.OutputTarget
	RequestRestart        func(context.Context, string) (string, error)
	SessionService        *SessionService
}

Config controls one rocketcode bridge conversation.

type ExternalMCPSessionState

type ExternalMCPSessionState struct {
	Agent          string `json:"agent,omitempty"`
	ConversationID string `json:"conversation_id,omitempty"`
}

ExternalMCPSessionState maps an external MCP conversation ID to its private session.

type GoalRequest added in v0.0.7

type GoalRequest struct {
	Objective, CheckScript string
	MaxTurns               int
}

GoalRequest is one parsed text-connector goal start request.

func ParseGoalRequest added in v0.0.7

func ParseGoalRequest(text string) (GoalRequest, string, bool)

ParseGoalRequest parses a text-connector goal trigger. The boolean reports whether the text was a goal trigger.

type GoalState added in v0.0.7

type GoalState struct {
	Objective   string    `json:"objective,omitempty"`
	CheckScript string    `json:"check_script,omitempty"`
	MaxTurns    int       `json:"max_turns,omitempty"`
	TurnsUsed   int       `json:"turns_used,omitempty"`
	Status      string    `json:"status,omitempty"`
	Note        string    `json:"note,omitempty"`
	CreatedAt   time.Time `json:"created_at,omitzero"`
	UpdatedAt   time.Time `json:"updated_at,omitzero"`
}

GoalState records one active or terminal managed-thread goal loop.

type ObservedSessionEntry

type ObservedSessionEntry struct {
	ID    int64
	Entry harness.SessionEntry
}

ObservedSessionEntry is one stored rocketcode entry with its SQLite row ID.

func ObserveSessionEntries

func ObserveSessionEntries(ctx context.Context, dbPath, conversationID string, lastID int64) ([]ObservedSessionEntry, error)

ObserveSessionEntries returns replay entries and their row IDs after lastID.

type PrimaryTextRouter added in v0.0.7

type PrimaryTextRouter interface {
	StartThread(ctx context.Context, agent string, preSeed bool, target events.TextConversationTarget, inbound *events.InboundMessage) error
	StartGoalInThread(ctx context.Context, agent, objective, checkScript string, maxTurns int, target events.TextConversationTarget, inbound *events.InboundMessage) error
	InterruptThread(target events.TextConversationTarget) (*events.InboundMessage, error)
	RegisterCronThread(ctx context.Context, target events.TextConversationTarget, agent, seedText string) error
	PrepareThreadReply(target events.TextConversationTarget) (bool, error)
	PrepareResponseThreadReply(target events.TextConversationTarget) (bool, error)
	SubmitThreadReply(ctx context.Context, target events.TextConversationTarget, inbound *events.InboundMessage) (bool, error)
	SubmitResponseThreadReply(ctx context.Context, target events.TextConversationTarget, inbound *events.InboundMessage) (bool, error)
	SummarizeThread(ctx context.Context, target events.TextConversationTarget) (bool, error)
	RecordResponseCheckpoint(target events.TextConversationTarget, checkpoint events.ResponseCheckpoint) error
}

PrimaryTextRouter routes primary text connector conversations to app-owned bridges.

type PruneStateStats

type PruneStateStats struct {
	Threads, ResponseCheckpoints, ExternalMCPSessions int
	SessionRows                                       int64
}

PruneStateStats reports how much stale persisted state was removed.

type RawRunProgress

type RawRunProgress struct {
	SessionService *SessionService
	ConversationID string

	Thinking, Message      func(context.Context, string) error
	ScheduleMessage        func(time.Duration, string, bool) error
	ResetScheduledMessages func() error
	RequestRestart         func(context.Context, string) (string, error)
}

RawRunProgress controls raw rocketcode run persistence and receives observable output.

type RawRunResult

type RawRunResult struct {
	Text, VerbatimMessage string
	Attachments           []events.OutboundAttachment
}

RawRunResult is the observable result of one non-publishing raw rocketcode turn.

func RunRawWithProgress

func RunRawWithProgress(ctx context.Context, cfg *config.Config, agent, prompt string, logger *slog.Logger, progress *RawRunProgress) (RawRunResult, error)

RunRawWithProgress executes a raw rocketcode turn and reports optional progress.

type ResponseCheckpointState

type ResponseCheckpointState struct {
	ConversationID string `json:"conversation_id,omitempty"`
	SessionEntryID int64  `json:"session_entry_id,omitempty"`
	ResponseID     string `json:"response_id,omitempty"`
	Model          string `json:"model,omitempty"`
	AssistantText  string `json:"assistant_text,omitempty"`
}

ResponseCheckpointState records enough metadata to seed a response-rooted thread.

type ScheduledMessageState

type ScheduledMessageState struct {
	ConversationID string        `json:"conversation_id,omitempty"`
	Agent          string        `json:"agent,omitempty"`
	Message        string        `json:"message,omitempty"`
	DueAt          time.Time     `json:"due_at,omitzero"`
	Recurring      bool          `json:"recurring,omitempty"`
	Interval       time.Duration `json:"interval,omitempty"`
}

ScheduledMessageState records one pending delayed system prompt.

type SessionListOptions added in v0.0.7

type SessionListOptions struct {
	Since time.Time
	Until time.Time
	Limit int
}

SessionListOptions bounds read-only session summary inspection.

type SessionService

type SessionService struct {
	// contains filtered or unexported fields
}

SessionService owns runtime SQLite session and state access inside one rocketclaw process.

func NewSessionServiceIn

func NewSessionServiceIn(workspace, workDir string) (*SessionService, error)

NewSessionServiceIn starts a runtime-owned SQLite session service in workDir.

func (*SessionService) AccountGoalTurn added in v0.0.7

func (s *SessionService) AccountGoalTurn(conversationID string) (GoalState, bool, error)

AccountGoalTurn increments one active goal turn and applies budget exhaustion.

func (*SessionService) ActiveGoals added in v0.0.7

func (s *SessionService) ActiveGoals() (map[string]GoalState, error)

ActiveGoals returns persisted active goals keyed by conversation ID.

func (*SessionService) AppendEntryID

func (s *SessionService) AppendEntryID(ctx context.Context, conversationID string, entry *harness.SessionEntry) (int64, error)

AppendEntryID appends one entry through the runtime service and returns its row ID.

func (*SessionService) ApplyPendingRestartNotifications

func (s *SessionService) ApplyPendingRestartNotifications(ctx context.Context) error

ApplyPendingRestartNotifications appends one developer notice to pending requester sessions.

func (*SessionService) BeginGoal added in v0.0.7

func (s *SessionService) BeginGoal(conversationID, objective, checkScript string, maxTurns int) error

BeginGoal records a new active goal for a managed conversation.

func (*SessionService) CheckpointWAL

func (s *SessionService) CheckpointWAL(ctx context.Context) (WALCheckpointStats, error)

CheckpointWAL checkpoints and truncates the SQLite WAL through the runtime service handle.

func (*SessionService) Goal added in v0.0.7

func (s *SessionService) Goal(conversationID string) (GoalState, bool, error)

Goal returns the persisted goal state for a conversation.

func (*SessionService) Load

func (s *SessionService) Load() (State, error)

Load returns the current persisted session state.

func (*SessionService) MarkRestartRequester

func (s *SessionService) MarkRestartRequester(ctx context.Context, conversationID string) error

MarkRestartRequester records that conversationID should see the post-restart notice.

func (*SessionService) MarkThreadSeeded

func (s *SessionService) MarkThreadSeeded(conversationID, seedKey string) error

MarkThreadSeeded records the response checkpoint used to seed a text thread.

func (*SessionService) ObserveEntries

func (s *SessionService) ObserveEntries(ctx context.Context, conversationID string, lastID int64) ([]ObservedSessionEntry, error)

ObserveEntries loads observed session entries through the runtime service.

func (*SessionService) PruneStateBefore

func (s *SessionService) PruneStateBefore(ctx context.Context, cutoff time.Time) (PruneStateStats, error)

PruneStateBefore removes expired thread and external-session state.

func (*SessionService) Stop

Stop closes the runtime service and its SQLite handle.

func (*SessionService) StopGoal added in v0.0.7

func (s *SessionService) StopGoal(conversationID string) error

StopGoal marks an active goal stopped.

func (*SessionService) UpdateGoalStatus added in v0.0.7

func (s *SessionService) UpdateGoalStatus(conversationID, status, note string) (GoalState, error)

UpdateGoalStatus records a model-controlled goal status update.

func (*SessionService) UpsertExternalMCPSession

func (s *SessionService) UpsertExternalMCPSession(externalConversationID string, session ExternalMCPSessionState) error

UpsertExternalMCPSession records an external MCP conversation ID mapping.

func (*SessionService) UpsertResponseCheckpoint

func (s *SessionService) UpsertResponseCheckpoint(key string, checkpoint ResponseCheckpointState) error

UpsertResponseCheckpoint records a response checkpoint.

func (*SessionService) UpsertThread

func (s *SessionService) UpsertThread(conversationID, agent string) error

UpsertThread records or updates a text-thread bridge entry.

func (*SessionService) Vacuum

func (s *SessionService) Vacuum(ctx context.Context) (VacuumStats, error)

Vacuum runs incremental SQLite vacuum through the runtime service handle.

type SessionSummary

type SessionSummary struct {
	ConversationID, LastUserMessage, LastAssistantMessage string
	Turns                                                 int
	LastUpdated                                           time.Time
}

SessionSummary is the compact observable state of one rocketcode session.

func ListSessionsInOptions added in v0.0.7

func ListSessionsInOptions(ctx context.Context, workspace, workDir string, options SessionListOptions) ([]SessionSummary, error)

ListSessionsInOptions returns summaries for stored rocketcode sessions in workDir.

type State

type State struct {
	Threads                     map[string]ThreadState             `json:"threads,omitempty"`
	ResponseCheckpoints         map[string]ResponseCheckpointState `json:"response_checkpoints,omitempty"`
	ExternalMCPSessions         map[string]ExternalMCPSessionState `json:"external_mcp_sessions,omitempty"`
	ScheduledMessages           map[string]ScheduledMessageState   `json:"scheduled_messages,omitempty"`
	Goals                       map[string]GoalState               `json:"goals,omitempty"`
	PendingRestartNotifications map[string]bool                    `json:"pending_restart_notifications,omitempty"`
}

State is the persisted rocketclaw session state.

type StateStoreLock

type StateStoreLock struct {
	// contains filtered or unexported fields
}

StateStoreLock holds advisory ownership of the RocketClaw state store.

func AcquireStateStoreLock

func AcquireStateStoreLock(workspace, workDir string) (*StateStoreLock, error)

AcquireStateStoreLock acquires non-blocking advisory ownership of the state store.

func (*StateStoreLock) Close

func (l *StateStoreLock) Close() error

Close releases the state-store lock.

type ThreadState

type ThreadState struct {
	Agent              string `json:"agent,omitempty"`
	SeededFromResponse string `json:"seeded_from_response,omitempty"`
}

ThreadState is the persisted state for one text-thread bridge.

type VacuumStats

type VacuumStats struct {
	DBExists                         bool
	BeforePageCount, BeforeFreePages int64
	AfterPageCount, AfterFreePages   int64
}

VacuumStats reports SQLite page counts before and after vacuuming.

type WALCheckpointStats

type WALCheckpointStats struct {
	Busy, LogFrames, CheckpointedFrames int64
}

WALCheckpointStats reports the outcome of a SQLite WAL checkpoint.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL