Help us shape the future of Go! Take the 2026 Go Developer Survey

backend

package
v0.2.24 Latest Latest
Warning

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

 Go to latest Published: Nov 3, 2026 License: MIT Imports: 75 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 (
	// ErrInvalidRevertMessage is a saved message ID undo cannot read.
	ErrInvalidRevertMessage = errors.New("invalid revert message ID")
	// ErrRevertMessageGone is an undo target the conversation does not hold.
	ErrRevertMessageGone = errors.New("revert message is no longer in the session")
)
View Source 
var ErrRemoteSession = errors.New("a remote OpenCode session's history stays on its server")

ErrRemoteSession refuses to delete a remote OpenCode session's history, which its server keeps.

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 harness.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 EasyUploadDir added in v0.2.20 

func EasyUploadDir(cfg *config.Config, conversationID string) string

EasyUploadDir is the folder, relative to the workspace, that keeps the uploads to an easy agent's chat conversationID: in the runtime directory, which reload keeps, named as a turn variable is in a workingDirectory.

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) (harness.Agents, harness.Skills, error)

LoadRuntimeDefinitions loads harness 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 TabConversation added in v0.2.9 

func TabConversation(path string) string

TabConversation is the conversation a /s/ or /oc/ tab path opens, as the Web's decodeSessionId reads it, which takes legacy URI-encoded IDs too; else "".

Types

type BoardLane added in v0.2.19 

type BoardLane struct {
	Chats []SidebarChat
	Total int
}

BoardLane is a Dashboard lane: up to 200 of its chats, newest arrival first, and how many chats it holds.

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 harness.ChildKey, entry *harness.SessionEntry) error

AppendChildEntry saves a permission review turn under b's conversation ID plus key, a hidden review history of its parent. It is no record: under a Slack thread, cron run, or External MCP run it expires as a private history does, and otherwise only with its family.

func (*Bridge) AwaitSubagent added in v0.1.44 

func (b *Bridge) AwaitSubagent(ctx context.Context, key, callKey string) (string, harness.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, responseID string, phase harness.TurnPhase, applied []string) ([]harness.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, whose source the prompt's turn keeps; a hidden producer turn records the prompt privately instead.

func (*Bridge) Stop 

func (b *Bridge) Stop()

Stop cancels bridge activity. It leaves an active turn to the cancellation of the bridge's context, which every caller with a running turn has already started: canceling the turn here could get there first and replace that cause, turning a shutdown that lets running calls finish into an interrupt that kills them.

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 *harness.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 cron run a Web chat continues, else the creating entry's source
	// conversation, attributed as ObserveTranscript does.
	CreatingSource string
	// ProducerAgent is the agent of the cron run Run locates.
	ProducerAgent string
	// Run locates CreatingSource when it is a cron run, nil otherwise.
	Run *protocol.CronRun
}

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

type Config 

type Config struct {
	ConversationID, Agent string
	RequestRestart        runtimeRestarter
	RequestReload         runtimeReloader
	UserQuestionAsker     protocol.UserQuestionAsker
	SessionService        *SessionService
	// Secrets fetches an easy agent's secretsARN for each of its turns.
	Secrets config.SecretFetcher
}

Config controls one rocketcode bridge conversation.

type ConversationKind added in v0.2.0 

type ConversationKind string

ConversationKind is what a conversation is, stored by the code that creates it. Web lists only Web chats and Slack threads. 

const (
	KindWebChat        ConversationKind = "web_chat"
	KindSlackThread    ConversationKind = "slack_thread"
	KindCronRun        ConversationKind = "cron_run"
	KindOneOffCronRun  ConversationKind = "one_off_cron_run"
	KindExternalMCPRun ConversationKind = "external_mcp_run"
	KindSubagent       ConversationKind = "subagent"
	KindReview         ConversationKind = "review"
	KindShadow         ConversationKind = "shadow"
	KindRemote         ConversationKind = "remote"
)

The conversation kinds, as the conversations table stores them.

type CronRunSource added in v0.1.27 

type CronRunSource struct {
	ConversationID       string
	SourceConversationID string
	// Run locates the source run by its stored definition path and start time.
	Run protocol.CronRun
}

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 Delegation added in v0.2.0 

type Delegation struct {
	ID, Parent, CallID string
	// Legacy reports a history saved under its call ID alone, before delegations had their own key.
	Legacy bool
	Kind   ConversationKind
}

Delegation is a direct child history that a call of Parent started.

type ExternalMCPSessionState 

type ExternalMCPSessionState struct {
	Agent                 string            `json:"agent,omitempty"`
	PrivateConversationID string            `json:"private_conversation_id,omitempty"`
	ManagedConversationID string            `json:"managed_conversation_id,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) (<-chan struct{}, []func(context.Context) error, error)
	ValidateAssets(*config.Config, string) error
}

FrontendAssembler constructs Slack and MCP frontends for a running backend.

type GoalState 

type GoalState struct {
	Objective string    `json:"objective,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"`
	// PrincipalName and PrincipalEmail name the person who set the goal.
	PrincipalName  string `json:"principal_name,omitempty"`
	PrincipalEmail string `json:"principal_email,omitempty"`
	// Origin is the trusted origin header of the turn that set the goal, which its continuations keep.
	Origin string `json:"origin,omitempty"`
}

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 []Delegation
	// Lineage is the conversations it nests under, from its top-level conversation down, then itself.
	Lineage []SidebarSession
	// Reviews are the Delegations that are permission reviews.
	Reviews     []string
	Shadows     []protocol.ShadowBinding
	Eligible    bool
	Predecessor string
	// Floor is the newest message undo must keep (revertStateDB), or "".
	Floor 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
	Conversation string
	Space        string
}

Page is one Hosted Page file or Page Data entry. Pages leaves Body empty. Conversation is the OpenCode session that owns the page, empty for an agent's page; Space is that session's space name, read only.

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
	Run             *protocol.CronRun
	SyncDestination string
	Cronjob         *protocol.CronjobMessage
}

RawRunProgress carries the conversation and 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 runtimeRefresher
	CronJobs          runtimeRefresher

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

AttachSlack makes Slack 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) ContinueRun added in v0.2.0 

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

ContinueRun has a conversation show, and search find, a hidden run's history before its own, taking the run's preview when it first does, and adopts the run when it reports to no conversation. Nothing is copied, and continuing again changes nothing.

func (*Runtime) CreateConversation added in v0.1.0 

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

CreateConversation records an explicit ID, a Web chat or a cron run, 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) EditQueueItem added in v0.1.63 

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

EditQueueItem changes only the text of a queued or held input that has not been claimed.

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) OpenCodeMCP added in v0.2.11 

func (r *Runtime) OpenCodeMCP() http.Handler

OpenCodeMCP serves, at /opencode/{name}/mcp, the MCP tools coding server name offers its OpenCode sessions: each call acts on the RocketClaw session of the OpenCode session its _meta names, so an agent tags its own session and publishes Hosted Pages that go with it. Callers authenticate as that coding server, with its configured password.

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 and the cron jobs. 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) SandboxError added in v0.2.24 

func (r *Runtime) SandboxError() string

SandboxError is the Web's notice about emulated shells: why they cannot run, that they are getting ready, or "" when they can or no agent uses one.

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) 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 SearchScope added in v0.1.62 

type SearchScope int

SearchScope is what a session search's free text matches. 

const (
	// SearchFields matches names, rooms, previews, agents, session labels,
	// servers, folders and origins.
	SearchFields SearchScope = iota
	// SearchMessages matches the fields and message text.
	SearchMessages
	// SearchFilters applies only the filters and leaves free text to the
	// caller, which matches it against the titles it shows.
	SearchFilters
)

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
	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 string, goal *GoalState) error

BeginGoal records a new active goal for a managed conversation.

func (*SessionService) Board added in v0.2.19 

func (s *SessionService) Board(ctx context.Context, username, spaceID string, dashboards [][]string, slack slackLookup) ([][]BoardLane, error)

Board sorts the chats of space spaceID into the lanes of each Dashboard, given in lane order as session search queries whose free text matches fields only. The space holds the chats born there, those without a Birth Space whose agent's space has its name ignoring case, and those with neither; an unknown space holds none. Each chat goes to its Dashboard's first lane it matches. Chats are as SidebarChats yields them, with username's unread marks.

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. A nonempty id restricts the inventory to that conversation.

func (*SessionService) ClaimCronSchedule 

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

ClaimCronSchedule moves one due scheduled cron trigger to nextDue and reports whether it runs: it is skipped while a turn of a run of the same file is running.

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) ConversationKind added in v0.2.0 

func (s *SessionService) ConversationKind(ctx context.Context, id string) (kind ConversationKind, found bool, err error)

ConversationKind returns what conversation id is, and whether it is recorded at all.

func (*SessionService) CreateOpenCodeSession added in v0.1.47 

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

CreateOpenCodeSession creates a root session in directory on server name, lists it at once in the Web space spaceID names, if any, 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) CronRun added in v0.2.0 

func (s *SessionService) CronRun(ctx context.Context, conversationID string) (path string, run bool, err error)

CronRun reports whether conversationID is a cron run, recorded or not, and the definition path of the cron run it is or, as a Web chat, continues; empty when that is unknown.

func (*SessionService) CronRunSources added in v0.1.27 

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

CronRunSources returns, in one query, every recorded cron run with saved history or a running, failed, or stopped turn, paired with itself, and with each recorded conversation people may see whose effective history holds output of the run: the chat it reports to and chats continuing it. Sessions under a run and copied entries are not consulted. Only each chat's own revert cutoff applies; runs cannot revert.

func (*SessionService) Delegations added in v0.1.11 

func (s *SessionService) Delegations(ctx context.Context, conversationID, sourceConversationID string, from, before int64) ([]Delegation, 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. In a conversation with a revert floor, it removes only what undo can (revertFloorSuffix).

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, and the pages of OpenCode sessions there are deleted with it. Its Shared tabs move to the first space left, keeping when they were added; one shared there already stays once. 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(ctx context.Context, conversationID, id string) (removed bool, owner string, err error)

DeleteThreadQueueItem deletes conversationID's queued item id and, in the same statement, settles the reply of the session write it was as removed. It reports whether it deleted the item, and the reply's owner to wake, if any.

func (*SessionService) DueCronSchedules 

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

DueCronSchedules returns observed scheduled cron definitions due at now.

func (*SessionService) EditSharedSearch added in v0.2.14 

func (s *SessionService) EditSharedSearch(ctx context.Context, space, path string, base, search []byte) (bool, error)

EditSharedSearch replaces the page of the Search tab path in space's Shared tabs with search when the saved page is still base, the page the edit was made from, and reports whether it did. One no longer shared stays unshared.

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) ForkOpenCodeSession added in v0.2.8 

func (s *SessionService) ForkOpenCodeSession(ctx context.Context, name string, server config.OpenCodeConfig, source, before string) (string, error)

ForkOpenCodeSession forks before a remote message and records the result before its tab saves. OpenCode v2 packages/server/src/handlers/session.ts returns the same Session.Info as creation.

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) 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) MuteTab added in v0.2.9 

func (s *SessionService) MuteTab(ctx context.Context, username, path string, until *time.Time) error

MuteTab mutes path's session for username until until, or until unmuted when until is nil. A path that names no session stores nothing.

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 the Web chat the session shows in, the private conversation the session runs in, and their 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 *TabState, 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. Saves never write unread_at: a closed tab stays while unread. A session tab names its conversation under the path marks use, and one of a session that does not exist is dropped.

func (*SessionService) SaveTopShelf added in v0.2.21 

func (s *SessionService) SaveTopShelf(ctx context.Context, username string, shelf []byte) error

SaveTopShelf replaces username's Top Shelf with shelf, as the Web saves it.

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) ([]MessageSearchHit, 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.

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, 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, username, query string, scope SearchScope, slack slackLookup) (*SessionSearch, error)

SearchSessions reads query in Web's session search language and finds, among SidebarChats, those passing the filters whose scope's text holds the needle; SearchMessages also finds those with message hits. Without a sort: term they keep sidebar order, chats with hits first; with one, they follow summary time. Either way, chats whose whole model is a model: value come first. Rows carry username's unread marks; an empty username is no person.

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) ShareTab added in v0.2.9 

func (s *SessionService) ShareTab(ctx context.Context, space, path string, search []byte) error

ShareTab adds path to space's Shared tabs under the path SaveTabState saves it as, with search, a Search page's JSON. A tab already shared there keeps its place and page; a missing space or session stores nothing.

func (*SessionService) SharedTabs added in v0.2.9 

func (s *SessionService) SharedTabs(ctx context.Context) ([]SharedTab, error)

SharedTabs lists every space's Shared tabs, oldest added first.

func (*SessionService) SidebarChats added in v0.1.27 

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

SidebarChats yields the sidebar's chats, or only those of chats when not nil, with their room, resolved through slack once per channel, cron and username's unread marks.

func (*SessionService) SlackChannelIDs added in v0.1.0 

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

SlackChannelIDs lists the distinct channels of recorded Slack threads.

func (*SessionService) SlackThread added in v0.2.0 

func (s *SessionService) SlackThread(ctx context.Context, conversationID string) (channelID, threadTS string, err error)

SlackThread returns the Slack channel and thread conversationID was stored with: both for a Slack thread, empty for a conversation that is none.

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

SyncCronSchedules replaces observed scheduled cron definitions, keeping the next due time of those already observed.

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. Each server's event stream keeps its running shells, reconnecting an interval after it drops and every openCodeShellsEvery; shells that start or end while it is down show at the next connection.

func (*SessionService) TabMutes added in v0.2.9 

func (s *SessionService) TabMutes(ctx context.Context, username string) ([]TabMute, error)

TabMutes lists username's mutes that have not ended, by the path SaveTabState saves each tab as.

func (*SessionService) TabState added in v0.1.53 

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

TabState returns username's saved Web tab state and its revision; the zero state 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 harness.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) TopShelf added in v0.2.21 

func (s *SessionService) TopShelf(ctx context.Context, username string) ([]byte, error)

TopShelf returns username's Top Shelf as the Web saved it, nil when none is saved.

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) UnmuteTab added in v0.2.9 

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

UnmuteTab unmutes path's session for username.

func (*SessionService) UnshareTab added in v0.2.9 

func (s *SessionService) UnshareTab(ctx context.Context, space, path string) ([]byte, error)

UnshareTab takes path out of space's Shared tabs and returns the Search page it held, nil for other tabs.

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. Remote names also update the OpenCode title.

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 a Web chat, or updates a recorded conversation's agent and creator.

func (*SessionService) ViewSession added in v0.2.2 

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

ViewSession records that username has conversationID in view now, which clears their mark on it and ends their view of every other session. A conversationID naming no conversation writes nothing.

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 SharedTab added in v0.2.9 

type SharedTab struct {
	Space, Path string
	Search      []byte
}

SharedTab is one tab in a space's Shared group, which every Web user sees. Search is a Search tab's one page as JSON, which everyone in the space sees and edits, and nil for other tabs.

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; empty for other chats.
	Room string
	// Cron reports a chat a cron run created; CronName is that job's stem.
	Cron     bool
	CronName string
}

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

type SidebarSession added in v0.1.0 

type SidebarSession struct {
	Conversation protocol.Conversation
	Kind         ConversationKind
	// RemoteSession is a remote OpenCode session's own ID on its server, empty for any other session.
	RemoteSession string
	Summary       *protocol.SessionSummary
	Running       bool
	// Background reports work that can wake the session after its turn: a running Background Job,
	// its own or a hidden run's reporting to it, a running turn of a hidden run reporting to it, or
	// a remote OpenCode session's running child session or shell command.
	Background bool
	// Asking reports a session waiting on a person: a running turn's unanswered Web question, or a
	// remote OpenCode session's pending form or permission request, its own or a child session's.
	Asking     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
	// SlackChannel is the channel of a Slack thread, empty for any other session.
	SlackChannel string
	// CronPath is the definition path of the cron run a Web chat continues, empty for any other session.
	CronPath string
	// Reply is a remote OpenCode session's newest assistant text, read when its last seen turn ended.
	Reply string
	// Model is a remote OpenCode session's selected model, "<provider>/<model>"; its
	// Conversation.Agent is its selected agent. Both are empty until it has them.
	// SearchSessions fills a RocketClaw chat's Model with its agent's configured model.
	Model string
	// UnreadAt is when a turn the listing person sent into ended unseen, zero once read.
	UnreadAt time.Time
	// Origin holds the facts that decide its chat origin, as ChatOriginFacts reads them.
	Origin ChatOriginFacts
	// Work is the chat's work state, and StateSince when the turn defining it started, or its last
	// update when idle. A Private Producer Conversation's turns count as those of the chat it reports to.
	Work       WorkState
	StateSince time.Time
	// Queued reports waiting turns other than scheduled reminders.
	Queued bool
	// External reports an External MCP binding, the chat's own or a run's reporting to it.
	External bool
	// ArrivedAt is when the chat's newest running or waiting turn was created, else its last update:
	// delivered turns are deleted.
	ArrivedAt time.Time
}

SidebarSession combines a recorded conversation with its optional durable summary.

func (*SidebarSession) Label added in v0.2.0 

func (row *SidebarSession) Label() string

Label is what Web calls the chat when it has no name or preview.

type Space added in v0.1.53 

type Space struct{ ID, Name string }

Space is a Web space every person shares.

type Tab added in v0.2.2 

type Tab struct {
	Path         string
	Preview      bool
	Group, Space string
	Search       []byte
}

Tab is one open Web tab; Group and Space are the ids of its group and space. Search is a Search tab's page as JSON, which only the Web reads, and nil for other tabs.

type TabGroup added in v0.2.2 

type TabGroup struct {
	ID, Name, Color string
	Collapsed       bool
}

TabGroup is one Web tab group.

type TabMute added in v0.2.9 

type TabMute struct {
	Path  string
	Until *time.Time
}

TabMute is a session tab whose desktop notifications a person muted until Until, or until unmuted when Until is nil.

type TabState added in v0.2.2 

type TabState struct {
	Tabs        []Tab
	Groups      []TabGroup
	Space       string
	Last        map[string]string
	SharedOrder []string
}

TabState is one person's Web tabs and groups in strip order, the space they are in, the last active tab of each space by space id, and their own order of Shared tabs by path.

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.

type WorkState added in v0.2.19 

type WorkState string

WorkState is the first of asking (see SidebarSession.Asking), running work and queued turns a chat has, else idle. 

const (
	WorkIdle     WorkState = "idle"
	WorkNeedsYou WorkState = "needs_you"
	WorkRunning  WorkState = "running"
	WorkQueued   WorkState = "queued"
)

The work states.

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.