backend

package
v0.1.53 Latest Latest
Warning

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

 Go to latest Published: Oct 19, 2026 License: MIT Imports: 70 Imported by: 0

Documentation

Overview

Package backend owns conversation execution, later-work, and cron.

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.

Variables

View Source 
var ErrRestartRequested = errors.New("restart requested")

ErrRestartRequested indicates rocketclaw should exit so a supervisor can restart it.

View Source 
var ErrSpaceRejected = errors.New("another space has that name, or it is the last space")

ErrSpaceRejected reports a space name another space has, ignoring case, or deleting the last space.

View Source 
var ErrTagNotAllowed = errors.New("the session's agent does not allow this tag")

ErrTagNotAllowed reports a manual tag a RocketClaw session's agent does not allow.

Functions

func AgentTags added in v0.1.47 

func AgentTags(agents rocketcode.Agents) map[string][]string

AgentTags lists, per agent with tag groups, the tags people may set on its sessions.

func DecideOrigin added in v0.1.27 

func DecideOrigin(facts *ChatOriginFacts) (origin any, text string)

DecideOrigin applies the origin rules to stored facts and returns the origin with the lowercased text origin search matches; a nil origin means none.

func ExternalMCPAgentsIn 

func ExternalMCPAgentsIn(cfg *config.LockedConfig, runtimeDir string) ([]string, error)

ExternalMCPAgentsIn returns agents externally selectable through MCP in runtimeDir.

func GenerateHandoff added in v0.1.3 

func GenerateHandoff(ctx context.Context, locked *config.LockedConfig, agent, transcript string) (document string, err error)

GenerateHandoff summarizes a snapshot without running tools or changing its session.

func LoadRuntimeDefinitions 

func LoadRuntimeDefinitions(cfg *config.LockedConfig, runtimeDir string) (rocketcode.Agents, rocketcode.Skills, error)

LoadRuntimeDefinitions loads RocketCode definitions from runtimeDir without starting a run.

func MentionedIDs added in v0.1.27 

func MentionedIDs(hits []MessageSearchHit, mentions map[string]string) []string

MentionedIDs returns, sorted, the IDs of mentions whose prefix a hit's lowercased text holds.

func PromptPrincipal added in v0.1.40 

func PromptPrincipal(header string) string

PromptPrincipal reads the top-level principal attribute of a recorded prompt header.

func ReplayInputMessageRoleText added in v0.1.0 

func ReplayInputMessageRoleText(item *responses.ResponseInputItemUnionParam, raw json.RawMessage) (role, text string, ok bool, err error)

ReplayInputMessageRoleText projects a stored message into its display role and text.

func Run 

func Run(ctx context.Context, cfg *config.Config, configPath string, logger *slog.Logger, assemble FrontendAssembler) error

Run starts rocketclaw and blocks until the context is canceled or a fatal error occurs.

func ValidateGoalCheckScriptStart 

func ValidateGoalCheckScriptStart(locked *config.LockedConfig, 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.LockedConfig, publisher protocol.OutboundPublisher, bridgeCfg *Config, logger *slog.Logger) *Bridge

NewConversation constructs a rocketcode bridge for one conversation.

func (*Bridge) AppendChildEntry added in v0.1.44 

func (b *Bridge) AppendChildEntry(ctx context.Context, key string, entry *rocketcode.SessionEntry) error

AppendChildEntry saves a guardrail or permission review turn under b's conversation ID plus key.

func (*Bridge) AwaitSubagent added in v0.1.44 

func (b *Bridge) AwaitSubagent(ctx context.Context, key, callKey string) (string, rocketcode.ReplayAttribution, error)

AwaitSubagent waits for the turn of the subagent session at b's conversation ID plus key that runs the write of the task call callKey.

func (*Bridge) Drain added in v0.1.33 

func (b *Bridge) Drain(ctx context.Context, phase rocketcode.TurnPhase, applied []string) ([]rocketcode.PromptInput, error)

Drain commits the offered input before advancing any consumed state. A bound child instead reads its parent's stream and waits at the final-answer boundary.

func (*Bridge) InterruptActiveTurn 

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

InterruptActiveTurn interrupts current work without discarding waiting work.

func (*Bridge) PickLaterWork 

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

PickLaterWork submits the next saved queue or due schedule for this conversation.

func (*Bridge) ResetScheduledMessages 

func (b *Bridge) ResetScheduledMessages(origin *protocol.InboundMessage) error

ResetScheduledMessages deletes pending scheduled prompts for this conversation, privately for a hidden producer turn, as ScheduleMessage does.

func (*Bridge) Run added in v0.1.14 

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

Run handles the conversation's unfinished active turn, then its requests, until ctx is canceled or the bridge stops.

func (*Bridge) ScheduleMessage 

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

ScheduleMessage schedules one delayed prompt for this conversation. origin is the inbound of the asking turn; a hidden producer turn records the prompt privately instead.

func (*Bridge) Stop 

func (b *Bridge) Stop() error

Stop cancels bridge activity.

func (*Bridge) Submit 

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

Submit enqueues one inbound message for this conversation.

func (*Bridge) SwitchAgent 

func (b *Bridge) SwitchAgent(agent string)

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

func (*Bridge) WriteSubagent added in v0.1.44 

func (b *Bridge) WriteSubagent(ctx context.Context, write *rocketcode.SubagentWrite) (bool, error)

WriteSubagent delivers write into the subagent session at b's conversation ID plus write.Key, as rocketclaw_sessions_write delivers into a session, after starting the session when new and switching it to write.Agent. A replayed write delivers nothing again.

type ChatOriginFacts added in v0.1.14 

type ChatOriginFacts struct {
	ConversationID         string
	CreatedBy              ThreadCreator
	ExternalConversationID string
	Binding                ExternalMCPSessionState
	// CreatingSource is the creating entry's source conversation, attributed as ObserveTranscript does.
	CreatingSource string
	// ProducerAgent is the agent of the cron run that may have created the conversation.
	ProducerAgent string
}

ChatOriginFacts are the stored facts that decide a conversation's chat origin.

type Config 

type Config struct {
	ConversationID, Agent string
	RequestRestart        func(string) (string, error)
	RequestReload         runtimeReloader
	UserQuestionAsker     protocol.UserQuestionAsker
	SessionService        *SessionService
}

Config controls one rocketcode bridge conversation.

type CronRun added in v0.1.27 

type CronRun struct {
	Stem string
	At   time.Time
	// contains filtered or unexported fields
}

CronRun is a cron run parsed from its source conversation ID.

func ParseCronRun added in v0.1.27 

func ParseCronRun(source string) (CronRun, bool)

ParseCronRun parses a cron or one-off cron run source conversation ID.

type CronRunSource added in v0.1.27 

type CronRunSource struct {
	ConversationID       string
	SourceConversationID string
}

CronRunSource pairs a conversation with the cron run conversation its effective history came from.

type CronScheduleState 

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"`
	PrivateConversationID string            `json:"private_conversation_id,omitempty"`
	ManagedConversationID string            `json:"managed_conversation_id,omitempty"`
	SlackChannel          string            `json:"slack_channel,omitempty"`
	OriginPairs           map[string]string `json:"origin_pairs,omitempty"`
}

ExternalMCPSessionState binds an external MCP conversation ID to private and managed sessions.

type FrontendAssembler added in v0.1.0 

type FrontendAssembler interface {
	Assemble(*Runtime) (SlackFrontend, <-chan struct{}, []func(context.Context) error, error)
	ValidateAssets(*config.Config, string, []string) error
}

FrontendAssembler constructs Slack and MCP frontends for a running backend.

type GoalState 

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 HistoryInventory added in v0.1.17 

type HistoryInventory struct {
	ConversationID string            `json:"conversation_id"`
	Source         string            `json:"source"`
	Entries        map[string]string `json:"entries"`
	From           int64             `json:"from,omitempty"`
	Oldest         int64             `json:"oldest,omitempty"`
	Marker         string            `json:"revert_message_id,omitempty"`
	Shadows        string            `json:"shadows,omitempty"`
}

HistoryInventory follows a stateless saved-entry view, not an event cursor.

type HistorySnapshot added in v0.1.17 

type HistorySnapshot struct {
	Inventory   HistoryInventory
	Entries     []ObservedSessionEntry
	Delegations []string
	Shadows     []protocol.ShadowBinding
	Eligible    bool
	Predecessor string
	Reset       bool
}

HistorySnapshot keeps cutoff, page bounds, payloads and delegation links coherent.

type KeyedConversationLocks 

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

KeyedConversationLocks serializes work per conversation id.

func NewKeyedConversationLocks 

func NewKeyedConversationLocks() *KeyedConversationLocks

NewKeyedConversationLocks constructs an empty lock set.

func (*KeyedConversationLocks) Lock 

func (l *KeyedConversationLocks) Lock(key string) func()

Lock serializes one conversation id and returns the unlock function.

type MessageSearchHit added in v0.1.24 

type MessageSearchHit struct {
	ConversationID, Role, Text string
	// MessageID is History's "<entry ID>:<replay index>", empty for a stopped or failed turn.
	MessageID string
}

MessageSearchHit is a user or assistant message as History shows it.

type ObservedSessionEntry 

type ObservedSessionEntry struct {
	ID       int64
	Entry    harness.SessionEntry
	Key      string
	Revision string
	// SourceConversationID identifies the surviving source row of a synced entry.
	SourceConversationID string
	Synced               bool
	Active               bool
	Terminal             protocol.Terminal
}

ObservedSessionEntry carries saved or checkpoint metadata and an optional payload.

type Page added in v0.1.52 

type Page struct {
	Agent       string
	Kind        PageKind
	Name        string
	ContentType string
	Body        []byte
	Size        int
	UpdatedAt   time.Time
}

Page is one Hosted Page file or Page Data entry. Pages leaves Body empty.

type PageKind added in v0.1.52 

type PageKind string

PageKind separates an agent's Hosted Page files from its Page Data entries. 

const (
	PageFile PageKind = "file"
	PageData PageKind = "data"
)

The page kinds.

type PruneStateStats 

type PruneStateStats struct {
	Threads, ExternalMCPSessions int
	SessionRows                  int64
}

PruneStateStats reports how much stale persisted state was removed.

type QuestionNotPendingError added in v0.1.27 

type QuestionNotPendingError struct{ ConversationID, QuestionID string }

QuestionNotPendingError reports an answer to a question no Web turn waits on, or one already answered.

func (*QuestionNotPendingError) Error added in v0.1.27 

func (e *QuestionNotPendingError) Error() string

type RawRunProgress 

type RawRunProgress struct {
	ConversationID  string
	SyncDestination string
	Cronjob         *protocol.CronjobMessage
	TextChannel     string
}

RawRunProgress carries the conversation and Slack destination for one cron run.

type Runtime 

type Runtime struct {
	Cfg               *config.LockedConfig
	Log               *slog.Logger
	RunCtx            context.Context
	Sessions          *SessionService
	ExternalMCPUsers  map[string]string
	ExternalMCPAgents externalMCPAgents

	TextRouter protocol.PrimaryTextRouter
	// contains filtered or unexported fields
}

Runtime is the backend after construction, before frontends.

func (*Runtime) AnswerQuestion added in v0.1.27 

func (r *Runtime) AnswerQuestion(ctx context.Context, conversationID, questionID string, answer protocol.AskUserQuestionAnswer) error

AnswerQuestion saves the answer to the Web question questionID of conversationID and wakes the turn waiting on it. The first answer wins: an answer to a question no Web turn of that conversation waits on, which includes one already answered, fails with *QuestionNotPendingError.

func (*Runtime) AttachSlack 

func (r *Runtime) AttachSlack(slack SlackFrontend)

AttachSlack makes Slack the cron report root sender and the session search's Slack lookup.

func (*Runtime) BackgroundJobs added in v0.1.19 

func (r *Runtime) BackgroundJobs(ctx context.Context, conversationID string) ([]protocol.BackgroundJob, bool, error)

BackgroundJobs lists the Background Jobs shown at conversationID and reports whether MoveToBackground has a running call to move there.

func (*Runtime) ClearRevert added in v0.1.17 

func (r *Runtime) ClearRevert(ctx context.Context, conversationID string) error

ClearRevert restores the whole suffix without changing any viewer's draft.

func (*Runtime) CompletionNotes added in v0.1.19 

func (r *Runtime) CompletionNotes(ctx context.Context, history string, jobIDs []string) ([]protocol.BackgroundJob, error)

CompletionNotes returns, in finish order, the jobs whose Completion Notes a system input saved at history delivers, by the job IDs it stored, with each note's text.

func (*Runtime) CreateConversation added in v0.1.0 

func (r *Runtime) CreateConversation(ctx context.Context, conversation protocol.Conversation) error

CreateConversation records an explicit ID without changing existing selection.

func (*Runtime) DeleteQueueItem added in v0.1.0 

func (r *Runtime) DeleteQueueItem(ctx context.Context, conversationID, id string) (bool, error)

DeleteQueueItem drops one waiting steer or enqueue so it never runs.

func (*Runtime) ListConversations added in v0.1.0 

func (r *Runtime) ListConversations(ctx context.Context) (conversations []protocol.Conversation, err error)

ListConversations returns recorded conversations, never discovered pair IDs.

func (*Runtime) MoveToBackground added in v0.1.19 

func (r *Runtime) MoveToBackground(ctx context.Context, conversationID string) (bool, error)

MoveToBackground moves every running execute and task call of the conversation's allowed agents into the background and reports whether any moved. Its running turn learns at its next step which of its own calls moved, and a moved script's pending question is withdrawn.

func (*Runtime) PendingQuestions added in v0.1.27 

func (r *Runtime) PendingQuestions(ctx context.Context, conversationID string) ([]protocol.AskUserQuestionRequest, error)

PendingQuestions lists, in key order, the unanswered questions saved by conversationID's Web turns. A question stays listed while its turn resumes after a restart.

func (*Runtime) PopQueueItem added in v0.1.0 

func (r *Runtime) PopQueueItem(ctx context.Context, conversationID, id string) (bool, error)

PopQueueItem releases held work at the end of the ordinary queue.

func (*Runtime) PromoteQueueItem added in v0.1.0 

func (r *Runtime) PromoteQueueItem(ctx context.Context, conversationID, id string) (bool, error)

PromoteQueueItem claims one persisted enqueue and submits it as a steer, keeping its principal.

func (*Runtime) PublishOutbound added in v0.1.0 

func (r *Runtime) PublishOutbound(ctx context.Context, message *protocol.OutboundMessage) error

PublishOutbound completes delivery through live consumers, never a private request response stream. Each consumer receives an independent rendering copy.

func (*Runtime) QueueItems added in v0.1.0 

func (r *Runtime) QueueItems(conversationID string) ([]protocol.ThreadQueueItem, error)

QueueItems returns persisted waiting work plus uninjected active steers.

func (*Runtime) Reload 

func (r *Runtime) Reload(reason string) (string, error)

Reload validates and replaces runtime assets, then refreshes External MCP agents. It uses the startup configuration, never rereading the configuration file.

func (*Runtime) ReorderQueueItems added in v0.1.0 

func (r *Runtime) ReorderQueueItems(conversationID string, ids []string) error

ReorderQueueItems writes persisted enqueue positions in the given ID order.

func (*Runtime) RunTurn added in v0.1.0 

func (r *Runtime) RunTurn(ctx context.Context, inbound *protocol.InboundMessage) error

RunTurn waits for the submitted work's processing and terminal handling.

func (*Runtime) StageRevert added in v0.1.17 

func (r *Runtime) StageRevert(ctx context.Context, conversationID, before string) (marker, prompt string, err error)

StageRevert settles the recorded bridge before changing its cutoff. Like packages/app/src/session/revert.ts, interruption is not effect rollback. before is a saved message ID, or the Web input ID of a message whose turn has not saved it, as when that turn is running.

func (*Runtime) StartGoal added in v0.1.12 

func (r *Runtime) StartGoal(ctx context.Context, inbound *protocol.InboundMessage, goal protocol.GoalRequest) error

StartGoal records an active goal on a recorded conversation and submits its first turn without waiting for the goal loop.

func (*Runtime) StashQueueItem added in v0.1.0 

func (r *Runtime) StashQueueItem(ctx context.Context, conversationID string, item *protocol.ThreadQueueItem) error

StashQueueItem persists waiting work and offers it to the conversation bridge.

func (*Runtime) StopBackgroundJob added in v0.1.19 

func (r *Runtime) StopBackgroundJob(ctx context.Context, conversationID, jobID string) (bool, error)

StopBackgroundJob stops, for the user, a running Background Job listed at conversationID.

func (*Runtime) Subscribe added in v0.1.0 

func (r *Runtime) Subscribe(ctx context.Context) iter.Seq[protocol.Event]

Subscribe registers a live-only event consumer. History is read separately.

func (*Runtime) SwitchConversationAgent added in v0.1.0 

func (r *Runtime) SwitchConversationAgent(conversationID, agent string) (bool, error)

SwitchConversationAgent persists selection and updates the existing live bridge. Frontends validate their current human/producer policy before calling it.

func (*Runtime) SyncConversation added in v0.1.0 

func (r *Runtime) SyncConversation(ctx context.Context, source, destination string) error

SyncConversation exposes surviving source work in an existing destination. The producer's own occupancy is not a competing destination turn.

func (*Runtime) WorkflowDescriptions added in v0.1.12 

func (r *Runtime) WorkflowDescriptions() (descriptions []protocol.WorkflowDescription, err error)

WorkflowDescriptions lists the saved workflows a human can start with $workflow.

type SearchKey added in v0.1.27 

type SearchKey string

SearchKey is the lowercased key of a session search filter term.

type SearchTerm added in v0.1.27 

type SearchTerm struct {
	Key         SearchKey
	Text, Value string
	Start, End  int
}

SearchTerm is a filter term of a session search query: its text, decoded value (lowercased for is: and sort:), and UTF-16 offsets in the query.

type SessionField added in v0.1.27 

type SessionField string

SessionField names the field of a found chat whose text holds the needle.

type SessionMatch added in v0.1.27 

type SessionMatch struct {
	Chat  SidebarChat
	Field SessionField
	Text  string
}

SessionMatch is a chat a session search found and the field whose text holds the needle; an empty Field means only message text did.

type SessionSearch added in v0.1.27 

type SessionSearch struct {
	Terms []SearchTerm
	// Text is the query without its terms; Needle is Text lowercased.
	Text, Needle string
	Matches      []SessionMatch
	Hits         []MessageSearchHit
	// MentionIDs are the Slack user and group IDs whose mention a hit holds.
	MentionIDs                       []string
	IndexComplete, SummariesComplete bool
	Principals                       []string
}

SessionSearch is how a session search read its query and what it found.

type SessionService 

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

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

func NewSessionServiceIn 

func NewSessionServiceIn(ctx context.Context, cfg *config.Config, logger *slog.Logger) (*SessionService, error)

NewSessionServiceIn starts a runtime-owned PostgreSQL session service.

func (*SessionService) ActiveGoalThreads 

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

ActiveGoalThreads returns managed thread state for conversations with active goals.

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) AttachmentMetadata added in v0.1.0 

func (s *SessionService) AttachmentMetadata(ctx context.Context, conversationID, id string, uploadOnly bool) (protocol.OutboundAttachment, error)

AttachmentMetadata loads stored metadata without transferring the file bytes. Callers must authorize the reference within its producer scope.

func (*SessionService) BeginGoal 

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

BeginGoal records a new active goal for a managed conversation.

func (*SessionService) Changes added in v0.1.12 

func (s *SessionService) Changes(ctx context.Context, conversationID string) iter.Seq2[protocol.ConversationChange, error]

Changes registers before yielding an initial refresh, then waits for committed changes to this conversation. Breaking iteration or cancelling ctx discards the listening connection rather than returning LISTEN state to the pool.

func (*SessionService) ChannelFact added in v0.1.0 

func (s *SessionService) ChannelFact(ctx context.Context, workspaceID, channelID string) (name string, found bool, err error)

ChannelFact returns a stored Slack name, never derived channel policy.

func (*SessionService) ChatOriginFacts added in v0.1.14 

func (s *SessionService) ChatOriginFacts(ctx context.Context, id string) iter.Seq2[ChatOriginFacts, error]

ChatOriginFacts yields, in one query, origin facts for every conversation people may see: cron runs and private External MCP conversations are omitted. The creating entry is read only where it can decide the origin: not for Slack threads cron did not create, nor for web:cron: and web:one-off-cron: chats, whose ID names the run. A nonempty id restricts the inventory to that conversation.

func (*SessionService) ClaimCronSchedule 

func (s *SessionService) ClaimCronSchedule(due CronScheduleState, nextDue, now time.Time) (relativePath string, claimed bool, err error)

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

func (*SessionService) ClaimScheduledMessage 

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

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

func (*SessionService) CompleteCronRun 

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

CompleteCronRun clears per-file scheduled cron running state.

func (*SessionService) CreateOpenCodeSession added in v0.1.47 

func (s *SessionService) CreateOpenCodeSession(ctx context.Context, name string, server config.OpenCodeConfig, directory string) (string, error)

CreateOpenCodeSession creates a root session in directory on server name, lists it at once, and returns its conversation ID.

func (*SessionService) CreateSpace added in v0.1.53 

func (s *SessionService) CreateSpace(ctx context.Context, name string) error

CreateSpace adds a space named name.

func (*SessionService) CronRunSources added in v0.1.27 

func (s *SessionService) CronRunSources(ctx context.Context) ([]CronRunSource, error)

CronRunSources returns, in one query, every cron run with effective history (including checkpoints) paired with itself, and with each conversation people may see whose effective history holds its synced output, following chained syncs. Managed conversations are never delegation children, so only their own revert cutoff applies.

func (*SessionService) Delegations added in v0.1.11 

func (s *SessionService) Delegations(ctx context.Context, conversationID, sourceConversationID string, from, before int64) ([]string, error)

Delegations returns saved direct child histories referenced by this transcript, including unchanged entries omitted from a delta's readable payloads. Only saved entries in [from, before) count; zero before means no upper bound and includes checkpoints, matching ObserveTranscript.

func (*SessionService) DeletePage added in v0.1.52 

func (s *SessionService) DeletePage(ctx context.Context, agent string, kind PageKind, name string) (bool, error)

DeletePage removes the page and reports whether it existed.

func (*SessionService) DeleteSession added in v0.1.0 

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

DeleteSession removes all entries for one conversation ID and returns deleted rows.

func (*SessionService) DeleteSpace added in v0.1.53 

func (s *SessionService) DeleteSpace(ctx context.Context, id string) error

DeleteSpace deletes space id unless it is the last space. Sessions born there lose their birth space. Locking every space, in id order, makes concurrent deletes take turns, so two cannot remove the last two.

func (*SessionService) DeleteThreadQueueItem 

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

DeleteThreadQueueItem deletes one Enqueued Slack Message.

func (*SessionService) DueCronSchedules 

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

DueCronSchedules returns observed scheduled cron definitions due at now.

func (*SessionService) ExternalMCPSession 

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

ExternalMCPSession returns a persisted external MCP session mapping.

func (*SessionService) ExternalMCPSessionByConversationID 

func (s *SessionService) ExternalMCPSessionByConversationID(conversationID string) (externalConversationID string, session ExternalMCPSessionState, ok bool, err error)

ExternalMCPSessionByConversationID returns the public ID and binding for either session ID.

func (*SessionService) ForkConversation added in v0.1.3 

func (s *SessionService) ForkConversation(ctx context.Context, source string, destination protocol.Conversation, before string) (string, error)

ForkConversation copies a recorded prefix and returns the excluded user prompt. OpenCode V2: packages/app/src/session/commands/fork-dialog.tsx uses an exclusive message boundary; packages/tui/src/routes/session/dialog-fork.tsx also allows all.

func (*SessionService) Goal 

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

Goal returns the persisted goal state for a conversation.

func (*SessionService) HasActiveTurn added in v0.1.14 

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

HasActiveTurn reports whether the conversation has a running or undelivered turn.

func (*SessionService) InputAttachments added in v0.1.24 

func (s *SessionService) InputAttachments(ctx context.Context, producer, text string) (string, []protocol.OutboundAttachment, error)

InputAttachments strips trailing upload references and returns their metadata in text order, including actual owners of surviving correlated shadow inputs.

func (*SessionService) ListSessions added in v0.1.0 

func (s *SessionService) ListSessions(ctx context.Context, conversationIDs []string) ([]protocol.SessionSummary, error)

ListSessions returns summaries for the requested stored rocketcode sessions.

func (*SessionService) LoadAttachment added in v0.1.0 

func (s *SessionService) LoadAttachment(ctx context.Context, conversationID, id string, uploadOnly bool) (protocol.OutboundAttachment, error)

LoadAttachment requires the producer scope; callers must authorize its reference. uploadOnly restricts prompt consumption to files acquired through upload.

func (*SessionService) LoadTurnStep added in v0.1.14 

func (s *SessionService) LoadTurnStep(ctx context.Context, conversationID, key string) (value json.RawMessage, found bool, err error)

LoadTurnStep returns one recorded step of a conversation's turns.

func (*SessionService) ObserveEntries 

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

ObserveEntries loads observed session entries through the runtime service.

func (*SessionService) ObserveHistory added in v0.1.17 

func (s *SessionService) ObserveHistory(ctx context.Context, id, source string, from, before int64, limit int, prior *HistoryInventory) (view HistorySnapshot, err error)

ObserveHistory reads every part of a followed view from one database snapshot.

func (*SessionService) ObserveTranscript added in v0.1.12 

func (s *SessionService) ObserveTranscript(ctx context.Context, conversationID string, from, before int64, revisions map[string]string) ([]ObservedSessionEntry, error)

ObserveTranscript returns the ordered inventory from one database snapshot, with payloads only for keys whose fingerprints differ from revisions. Nil revisions requests all payloads. A saved logical turn supersedes its checkpoint. Turn keys are producer-scoped and stable across checkpoint completion. Checkpoints stay after the saved row visible when first persisted, preserving ID order. Rows are limited to positions in [from, before); zero before means no upper bound and also includes every running checkpoint. Positive before reads a settled page, so running checkpoints are excluded. Source attribution matches ObserveEntries; authorization belongs to the caller. Fingerprints describe readable content, not the transaction IDs yielded by Changes.

func (*SessionService) Page added in v0.1.52 

func (s *SessionService) Page(ctx context.Context, agent string, kind PageKind, name string) (Page, bool, error)

Page returns the stored page and whether it exists.

func (*SessionService) Pages added in v0.1.52 

func (s *SessionService) Pages(ctx context.Context, agent string) ([]Page, error)

Pages lists agent's pages, or every agent's when agent is empty, ordered by agent, kind, and name.

func (*SessionService) PruneStateBefore 

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

PruneStateBefore removes thread and external-session state that expired before cutoff. It never interrupts work: each candidate is deleted in its own short transaction only while its family is idle and still expired, and is otherwise left for a later pass. It waits a tenth of pace after each check and pace after each deletion, so a background pass stays light on the store.

func (*SessionService) PutPage added in v0.1.52 

func (s *SessionService) PutPage(ctx context.Context, page *Page) error

PutPage stores page, replacing any page with the same agent, kind, and name.

func (*SessionService) PutScheduledMessage 

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

PutScheduledMessage persists one scheduled message.

func (*SessionService) PutThreadQueueItem 

func (s *SessionService) PutThreadQueueItem(id string, item *protocol.ThreadQueueItem) error

PutThreadQueueItem persists one Enqueued Slack Message.

func (*SessionService) RecordChannelFact added in v0.1.0 

func (s *SessionService) RecordChannelFact(ctx context.Context, workspaceID, channelID, name string, observedAt time.Time) error

RecordChannelFact keeps the newest observation. Nanoseconds preserve ordering even when a lookup and rename occur within one PostgreSQL timestamp microsecond.

func (*SessionService) RegisterExternalMCPConversation 

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

RegisterExternalMCPConversation atomically persists a managed conversation and its public binding.

func (*SessionService) RemoveExternalMCPConversation 

func (s *SessionService) RemoveExternalMCPConversation(externalConversationID string) error

RemoveExternalMCPConversation removes a failed newly-created conversation and all of its durable state.

func (*SessionService) RenameSpace added in v0.1.53 

func (s *SessionService) RenameSpace(ctx context.Context, id, name string) error

RenameSpace renames space id to name.

func (*SessionService) ReplayAttachments added in v0.1.0 

func (s *SessionService) ReplayAttachments(ctx context.Context, conversationID string, root *os.Root, raw json.RawMessage, calls map[string]string) ([]protocol.OutboundAttachment, error)

ReplayAttachments resolves metadata for successful attach-tool output, never arbitrary paths. calls belongs to one producer and survives entry boundaries during history projection.

func (*SessionService) ResetCronSchedules 

func (s *SessionService) ResetCronSchedules() error

ResetCronSchedules clears scheduled cron state at daemon observation start.

func (*SessionService) ResetScheduledMessages 

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

ResetScheduledMessages deletes pending scheduled messages for one conversation.

func (*SessionService) ResetVoiceConversation added in v0.1.36 

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

ResetVoiceConversation forgets username's current voice conversation while it is still conversationID.

func (*SessionService) RevertAttachmentMetadata added in v0.1.17 

func (s *SessionService) RevertAttachmentMetadata(ctx context.Context, conversationID, id string) (protocol.OutboundAttachment, error)

RevertAttachmentMetadata authorizes only an upload referenced by the current staged user boundary. It never exposes the rest of the hidden replay.

func (*SessionService) RevertState added in v0.1.17 

func (s *SessionService) RevertState(ctx context.Context, conversationID string) (marker string, eligible bool, predecessor string, err error)

RevertState reports the durable cutoff and capability from physical origin facts. Empty effective history must not erase a conversation's origin.

func (*SessionService) SaveAttachment added in v0.1.0 

func (s *SessionService) SaveAttachment(ctx context.Context, conversationID, turnID string, attachment *protocol.OutboundAttachment, upload bool) error

SaveAttachment stores immutable original bytes before publishing a reference. turnID names the turn whose final reply sends the file, or is empty.

func (*SessionService) SaveTabState added in v0.1.53 

func (s *SessionService) SaveTabState(ctx context.Context, username string, state []byte, revision int64) (bool, error)

SaveTabState replaces username's saved Web tab state when it was made from the saved revision, and reports whether it did.

func (*SessionService) SaveTurnStep added in v0.1.14 

func (s *SessionService) SaveTurnStep(ctx context.Context, conversationID, key string, value json.RawMessage) error

SaveTurnStep records one step of a conversation's turns; the turn's finish removes it.

func (*SessionService) ScheduledMessages 

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

ScheduledMessages returns all persisted scheduled messages.

func (*SessionService) ScheduledMessagesForConversation 

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

ScheduledMessagesForConversation returns persisted scheduled messages for one conversation.

func (*SessionService) SearchMessages added in v0.1.24 

func (s *SessionService) SearchMessages(ctx context.Context, needle string, tagPrefixes []string) (hits []MessageSearchHit, complete bool, err error)

SearchMessages returns, in chat then history order, the messages of chats Web shows whose lowercased text contains needle or one of tagPrefixes, which the caller lowercased with strings.ToLower. Messages a pending undo hides are left out. complete reports that every chat Web shows is indexed.

func (*SessionService) SearchMessagesMentioning added in v0.1.27 

func (s *SessionService) SearchMessagesMentioning(ctx context.Context, needle string, slack slackLookup) (hits []MessageSearchHit, mentions map[string]string, complete bool, err error)

SearchMessagesMentioning is SearchMessages for needle and the mentions of the Slack users and groups slack finds for it; mentions maps their IDs to the lowercased mention prefixes.

func (*SessionService) SearchSessions added in v0.1.27 

func (s *SessionService) SearchSessions(ctx context.Context, query string, messages bool, slack slackLookup) (*SessionSearch, error)

SearchSessions reads query in Web's session search language and finds, among SidebarChats, those passing the filters whose fields hold the needle and, when messages is set, those with message hits. Without a sort: term they keep sidebar order, chats with hits first; with one, they follow summary time.

func (*SessionService) SetThreadAgentIfExists 

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

SetThreadAgentIfExists updates a managed conversation agent without creating a thread.

func (*SessionService) ShadowParent added in v0.1.33 

func (s *SessionService) ShadowParent(ctx context.Context, id string) (string, error)

ShadowParent resolves comparison history (including delegations) through its explicit binding and a private producer's recorded visible destination.

func (*SessionService) SidebarChats added in v0.1.27 

func (s *SessionService) SidebarChats(ctx context.Context, slack slackLookup) iter.Seq2[SidebarChat, error]

SidebarChats yields SidebarSessions with their room, resolved through slack once per channel, cron and origin.

func (*SessionService) SidebarSessions added in v0.1.0 

func (s *SessionService) SidebarSessions(ctx context.Context) iter.Seq2[SidebarSession, error]

SidebarSessions yields pinned records first, then recent-first, bytewise-ID order. Conversations without stored history are omitted until their first entry arrives, except while a turn runs: then its prompt is the preview and its start the update time. Breaking iteration or cancelling ctx closes the database rows.

func (*SessionService) SlackChannelIDs added in v0.1.0 

func (s *SessionService) SlackChannelIDs(ctx context.Context) ([]string, error)

SlackChannelIDs lists the distinct channels of recorded managed Slack threads.

func (*SessionService) Spaces added in v0.1.53 

func (s *SessionService) Spaces(ctx context.Context) ([]Space, error)

Spaces lists the Web spaces, oldest first.

func (*SessionService) StartVoiceConversation added in v0.1.36 

func (s *SessionService) StartVoiceConversation(ctx context.Context, username, conversationID, agent string) error

StartVoiceConversation makes conversationID, started with agent, username's current voice conversation unless one is already current; the current one then wins.

func (*SessionService) Stop 

func (s *SessionService) Stop() error

Stop closes the runtime service and its database handle.

func (*SessionService) StopGoal 

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

StopGoal marks an active goal stopped.

func (*SessionService) SyncCronSchedules 

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

SyncCronSchedules replaces observed scheduled cron definitions.

func (*SessionService) SyncOpenCode added in v0.1.47 

func (s *SessionService) SyncOpenCode(ctx context.Context, servers map[string]config.OpenCodeConfig)

SyncOpenCode keeps each configured server's newest root sessions in the store every interval until ctx ends. A failed poll writes nothing, so that server's rows age into offline. At start and then daily, it also drops stored sessions the server no longer has.

func (*SessionService) TabState added in v0.1.53 

func (s *SessionService) TabState(ctx context.Context, username string) (state []byte, revision int64, err error)

TabState returns username's saved Web tab state and its revision; nil and 0 when none is saved.

func (*SessionService) Thread 

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

Thread returns the persisted managed conversation state.

func (*SessionService) ThreadQueueForConversation 

func (s *SessionService) ThreadQueueForConversation(conversationID string) ([]protocol.ThreadQueueItem, error)

ThreadQueueForConversation returns Enqueued Slack Messages in stack order.

func (*SessionService) ToggleManualTag added in v0.1.47 

func (s *SessionService) ToggleManualTag(ctx context.Context, agents rocketcode.Agents, id, tag string) error

ToggleManualTag toggles a tag a person chose. A remote OpenCode session takes any tag; a RocketClaw session takes only a tag its agent allows, which clears the rest of its group.

func (*SessionService) TranscriptPage added in v0.1.12 

func (s *SessionService) TranscriptPage(ctx context.Context, conversationID string, before int64, limit int) (start, oldest int64, err error)

TranscriptPage returns the saved-entry ID that starts the newest limit entries before (zero for no bound), or zero when fewer exist, and the conversation's oldest saved-entry ID, which changes only when history is cleared.

func (*SessionService) TurnAttachments added in v0.1.31 

func (s *SessionService) TurnAttachments(ctx context.Context, conversationID, turnID string) ([]protocol.OutboundAttachment, error)

TurnAttachments returns, in the order they were attached, the files turnID's final reply sends, naming the owner of those its subagent sessions attached.

func (*SessionService) UpdateConversationDetails added in v0.1.0 

func (s *SessionService) UpdateConversationDetails(ctx context.Context, conversationID string, pinned *bool, name *string) (bool, error)

UpdateConversationDetails changes shared display metadata without touching history. Nil fields are left unchanged.

func (*SessionService) UpdateGoalStatus 

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

UpdateGoalStatus records a model-controlled goal status update.

func (*SessionService) UpdateVoiceSettings added in v0.1.36 

func (s *SessionService) UpdateVoiceSettings(ctx context.Context, username string, agent, voice *string, transcript *bool) error

UpdateVoiceSettings stores the given settings for username; a nil one keeps its value.

func (*SessionService) UpsertExternalMCPSession 

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

UpsertExternalMCPSession records an external MCP conversation ID mapping.

func (*SessionService) UpsertThread 

func (s *SessionService) UpsertThread(conversationID string, thread ThreadState) error

UpsertThread records or updates a text-thread bridge entry.

func (*SessionService) VoiceSettings added in v0.1.36 

func (s *SessionService) VoiceSettings(ctx context.Context, username string) (VoiceSettings, error)

VoiceSettings returns username's voice settings, or the defaults when none are stored.

type SidebarChat added in v0.1.27 

type SidebarChat struct {
	Session SidebarSession
	// Room is a Slack thread's stored channel name, or its channel ID when unknown;
	// RoomAgents are the agents that room allows. Both are empty for other chats.
	Room       string
	RoomAgents []string
	// Cron reports a chat a cron run created; CronName is that job's stem.
	Cron     bool
	CronName string
	// Origin is the lowercased origin text, empty without an origin.
	Origin string
}

SidebarChat is a sidebar row with the room, cron and origin Web shows for it.

type SidebarSession added in v0.1.0 

type SidebarSession struct {
	Conversation protocol.Conversation
	Summary      *protocol.SessionSummary
	Running      bool
	Pinned       bool
	Name         string
	ForkedFrom   string
	Tags         []string
	// Server names the remote OpenCode server of a synced session, empty for RocketClaw's own.
	Server    string
	Directory string
	Offline   bool
	// SpaceID is the Web space the session was born in, empty for none.
	SpaceID string
}

SidebarSession combines a recorded conversation with its optional durable summary.

type SlackFrontend 

type SlackFrontend interface {
	Start(context.Context) error
	Stop(context.Context) error
	SendCronjobRoot(context.Context, *protocol.OutboundMessage) (protocol.TextConversationTarget, error)
	EditCronjobRootFooter(ctx context.Context, msg *protocol.OutboundMessage, root protocol.TextConversationTarget, conversationID string) error
	SidebarChannelAgentChoices(context.Context, string) (string, []string, error)
	SlackTagsMatching(context.Context, string) []string
}

SlackFrontend is the Slack surface cmd constructs.

type Space added in v0.1.53 

type Space struct{ ID, Name string }

Space is a Web space every person shares.

type ThreadCreator 

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"`
	CreatedBy ThreadCreator `json:"created_by,omitempty"`
	// contains filtered or unexported fields
}

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

type VoiceSettings added in v0.1.36 

type VoiceSettings struct {
	ConversationID string
	Agent          string
	Voice          string
	Transcript     bool
}

VoiceSettings is one person's Web voice state: their current voice conversation (empty when none), the agent for their next one, their voice, and the transcript view.

Source Files

View all Source files

Directories

Path Synopsis
Package harnessbridgetest holds test helpers for backend.
 Package harnessbridgetest holds test helpers for backend.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.