harnessbridge

package
v0.0.27 Latest Latest
Warning

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

Go to latest
Published: Jul 5, 2026 License: MIT Imports: 51 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, runtimeDir, conversationID string) (int64, error)

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

func ExternalMCPAgentsIn

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

ExternalMCPAgentsIn returns agents externally selectable through MCP in runtimeDir.

func SessionDBPathIn

func SessionDBPathIn(workspace, runtimeDir string) string

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

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.

func ValidateRuntimeDefinitions added in v0.0.25

func ValidateRuntimeDefinitions(workspace, runtimeDir string) error

ValidateRuntimeDefinitions loads RocketCode definitions from runtimeDir without starting a run.

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) error

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

func (*Bridge) SeedThreadFromConversation added in v0.0.16

func (b *Bridge) SeedThreadFromConversation(ctx context.Context, sourceConversationID string) error

SeedThreadFromConversation initializes an empty thread session from source conversation context.

func (*Bridge) SeedThreadFromCron

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

SeedThreadFromCron initializes an empty thread session from cron output.

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) SwitchAgent added in v0.0.11

func (b *Bridge) SwitchAgent(agent string)

SwitchAgent changes the agent used for future turns in this conversation.

func (*Bridge) WaitIdle

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

WaitIdle waits until queued bridge work has drained.

type CheckAndRecoverSessionDBResult added in v0.0.27

type CheckAndRecoverSessionDBResult struct {
	DBExists  bool
	Healthy   bool
	Recovered bool
}

CheckAndRecoverSessionDBResult reports the manual state-store check outcome.

func CheckAndRecoverSessionDB added in v0.0.27

func CheckAndRecoverSessionDB(ctx context.Context, workspace, runtimeDir string, logger *slog.Logger) (CheckAndRecoverSessionDBResult, error)

CheckAndRecoverSessionDB checks and recovers the state DB for the fc check command.

type Config

type Config struct {
	ConversationID, Agent string
	ConsumeSharedInbound  bool
	OutputTargets         []events.OutputTarget
	RequestRestart        func(context.Context, string) (string, error)
	RequestReload         func(context.Context, string) (string, error)
	AskUserQuestion       func(context.Context, *events.AskUserQuestionRequest) (events.AskUserQuestionAnswer, error)
	StartNewThread        func(context.Context, *events.StartNewThreadRequest) (events.StartNewThreadResult, error)
	SessionService        *SessionService
}

Config controls one rocketcode bridge conversation.

type CronScheduleRun added in v0.0.25

type CronScheduleRun struct {
	ScheduleID   string
	RelativePath string
	DueAt        time.Time
}

CronScheduleRun is a claimed scheduled cron run.

type CronScheduleState added in v0.0.25

type CronScheduleState struct {
	ScheduleID   string
	RelativePath string
	NextDue      time.Time
}

CronScheduleState records one observed scheduled cron trigger.

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
	ThreadAgent(target events.TextConversationTarget) (agent string, handled bool, err error)
	SwitchThreadAgent(target events.TextConversationTarget, agent string) (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)
	RequestReload          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) (result RawRunResult, err 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, 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, runtimeDir string, logger *slog.Logger) (*SessionService, error)

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

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) ActiveGoalThreads added in v0.0.25

func (s *SessionService) ActiveGoalThreads() (map[string]ThreadState, error)

ActiveGoalThreads returns managed thread state for conversations with active goals.

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) ClaimCronSchedule added in v0.0.25

func (s *SessionService) ClaimCronSchedule(due CronScheduleState, nextDue, now time.Time) (CronScheduleRun, bool, error)

ClaimCronSchedule verifies one due scheduled cron trigger and records per-file running state.

func (*SessionService) ClaimScheduledMessage added in v0.0.25

func (s *SessionService) ClaimScheduledMessage(id, conversationID string, dueAt, now time.Time) (ScheduledMessageState, bool, error)

ClaimScheduledMessage verifies one due scheduled message and advances recurring messages atomically.

func (*SessionService) CompleteCronRun added in v0.0.25

func (s *SessionService) CompleteCronRun(relativePath string, now time.Time) error

CompleteCronRun clears per-file scheduled cron running state.

func (*SessionService) DeleteScheduledMessage added in v0.0.25

func (s *SessionService) DeleteScheduledMessage(id string) error

DeleteScheduledMessage deletes one scheduled message.

func (*SessionService) DueCronSchedules added in v0.0.25

func (s *SessionService) DueCronSchedules(now time.Time, limit int) ([]CronScheduleState, error)

DueCronSchedules returns observed scheduled cron definitions due at now.

func (*SessionService) ExternalMCPSession added in v0.0.25

func (s *SessionService) ExternalMCPSession(externalConversationID string) (ExternalMCPSessionState, bool, error)

ExternalMCPSession returns a persisted external MCP session mapping.

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) MarkRestartRequester

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

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

func (*SessionService) MarkThreadCreatedBy added in v0.0.16

func (s *SessionService) MarkThreadCreatedBy(conversationID string, createdBy ThreadCreator) error

MarkThreadCreatedBy records the creator class for origin-restricted managed conversations.

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) PutScheduledMessage added in v0.0.25

func (s *SessionService) PutScheduledMessage(id string, message *ScheduledMessageState) error

PutScheduledMessage persists one scheduled message.

func (*SessionService) ResetCronSchedules added in v0.0.25

func (s *SessionService) ResetCronSchedules() error

ResetCronSchedules clears scheduled cron state at daemon observation start.

func (*SessionService) ResetScheduledMessages added in v0.0.25

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

ResetScheduledMessages deletes pending scheduled messages for one conversation.

func (*SessionService) ResponseCheckpoint added in v0.0.25

func (s *SessionService) ResponseCheckpoint(key string) (ResponseCheckpointState, bool, error)

ResponseCheckpoint returns a persisted response checkpoint.

func (*SessionService) ScheduledMessages added in v0.0.25

func (s *SessionService) ScheduledMessages() (map[string]ScheduledMessageState, error)

ScheduledMessages returns all persisted scheduled messages.

func (*SessionService) ScheduledMessagesForConversation added in v0.0.25

func (s *SessionService) ScheduledMessagesForConversation(conversationID string) (map[string]ScheduledMessageState, error)

ScheduledMessagesForConversation returns persisted scheduled messages for one conversation.

func (*SessionService) SetThreadAgentIfExists added in v0.0.25

func (s *SessionService) SetThreadAgentIfExists(conversationID, agent string) (bool, error)

SetThreadAgentIfExists updates a managed conversation agent without creating a thread.

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) SyncCronSchedules added in v0.0.25

func (s *SessionService) SyncCronSchedules(schedules []CronScheduleState, now time.Time) error

SyncCronSchedules replaces observed scheduled cron definitions.

func (*SessionService) Thread added in v0.0.25

func (s *SessionService) Thread(conversationID string) (ThreadState, bool, error)

Thread returns the persisted managed conversation state.

func (*SessionService) ThreadForSeed added in v0.0.25

func (s *SessionService) ThreadForSeed(seedConversationID string) (conversationID string, thread ThreadState, ok bool, err error)

ThreadForSeed returns the first managed conversation seeded from seedConversationID.

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, runtimeDir string, options SessionListOptions) ([]SessionSummary, error)

ListSessionsInOptions returns summaries for stored rocketcode sessions in runtimeDir.

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, runtimeDir 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 ThreadCreator added in v0.0.16

type ThreadCreator string

ThreadCreator records which subsystem created a managed text conversation.

const ThreadCreatedByCron ThreadCreator = "cron"

ThreadCreatedByCron marks managed conversations created for cron output.

type ThreadState

type ThreadState struct {
	Agent              string        `json:"agent,omitempty"`
	SeededFromResponse string        `json:"seeded_from_response,omitempty"`
	CreatedBy          ThreadCreator `json:"created_by,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