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

sessioncmd

package
v0.44.0 Latest Latest
Warning

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

 Go to latest Published: Oct 25, 2026 License: Apache-2.0 Imports: 35 Imported by: 0

Documentation

Overview

Package sessioncmd implements the session-scoped commands an agent uses to talk to its running manager: naming the session, declaring review targets, and operating managed terminals. The CLI subcommands and the MCP server share this layer so validation and behavior stay identical.

Index

Constants

View Source 
const (
	DefaultReservationTTL = 30 * time.Minute
	MaxReservationTTL     = 4 * time.Hour
)
View Source 
const (
	DefaultWaitTimeout = 50 * time.Second
	// MaxWaitTimeout is generous, but clients cut a call short on their own
	// schedule: Codex CLI stops at 60s by default. A caller asking for more
	// gets it only where its own client allows it.
	MaxWaitTimeout = 5 * time.Minute

	WaitReached  = "reached"
	WaitTimedOut = "timed_out"
	WaitDied     = "died"
)

Waiting on another session is one parked tool call instead of a polling loop that reads a pane, and a screen read per tick is what makes an orchestrating agent expensive.

View Source 
const ExitMayHaveReached = 3

ExitMayHaveReached is the CLI's exit status for a prompt whose paste had started when the send failed, so a manager on another machine knows the prompt may sit in the pane and does not offer it again.

View Source 
const SnapshotVersion = 1

SnapshotVersion is the envelope shape another manager reads over SSH. A change a reader of the previous shape would misread bumps it.

Variables

This section is empty.

Functions

func AgentRunning added in v0.34.0 

func AgentRunning(driver *tmux.Driver, sessID string) (bool, error)

AgentRunning reports whether a live pane still holds an agent: the pane's own pid is its shell, so anything under it is the agent. A sample that could not be read counts as running, because typing a command into a pane that turns out to hold an agent puts the text in its composer.

func FollowConversation added in v0.42.0 

func FollowConversation(st *store.Store, hookManager *hooks.Manager, reader *conversation.Reader, sess store.Session, style string) (store.Session, error)

FollowConversation moves a session onto the conversation its CLI's own state says the agent is on, for the CLIs that report no switch themselves and keep that state while the agent runs. Only state the agent this launch started left counts. reader keeps what it has read between calls.

func FollowTelemetry added in v0.42.0 

func FollowTelemetry(configDir string, args []string) error

FollowTelemetry runs beside a gemini agent its launch started. It reads the telemetry file the launch pointed gemini at, records the conversation it names and empties it, so the file stays small and the row follows switches with no manager running. It ends after a last read once the agent has quit. A hangup or interrupt meant for the pane's agent leaves it running, since gemini can outlive its pane.

func FormatAfterTurn added in v0.40.0 

func FormatAfterTurn(result AfterTurn) string

FormatAfterTurn tells the agent what happens to it, in the order it acts on: what is pending, and whether anything is running to carry it out.

func FormatArchiveState added in v0.31.0 

func FormatArchiveState(session Session) string

FormatArchiveState reads the verb off the row the call returned, so neither front says "archived" about a row that came back active.

func FormatGroupList added in v0.31.0 

func FormatGroupList(groups []Group) string

func FormatGroupRemoval added in v0.31.0 

func FormatGroupRemoval(removal GroupRemoval) string

func FormatMessageState added in v0.31.0 

func FormatMessageState(state MessageState) string

func FormatReleased added in v0.31.0 

func FormatReleased(count int) string

func FormatReservation added in v0.31.0 

func FormatReservation(reservation Reservation) string

func FormatReservations added in v0.31.0 

func FormatReservations(reservations []Reservation) string

func FormatReserveResult added in v0.31.0 

func FormatReserveResult(result ReserveResult) string

func FormatSendResult added in v0.31.0 

func FormatSendResult(result SendResult, targetID string) string

func FormatSession added in v0.31.0 

func FormatSession(session Session) string

func FormatSessionList added in v0.31.0 

func FormatSessionList(sessions []Session) string

func FormatSessionScreen added in v0.31.0 

func FormatSessionScreen(screen SessionScreen) string

func FormatTask added in v0.31.0 

func FormatTask(task Task) string

func FormatTaskList added in v0.31.0 

func FormatTaskList(tasks []Task) string

func FormatTerminal added in v0.31.0 

func FormatTerminal(terminal Terminal) string

func FormatTerminalInput added in v0.31.0 

func FormatTerminalInput(input TerminalInput) string

func FormatTerminalList added in v0.31.0 

func FormatTerminalList(terminals []Terminal) string

func FormatTerminalScreen added in v0.31.0 

func FormatTerminalScreen(screen TerminalScreen) string

func FormatWaitResult added in v0.31.0 

func FormatWaitResult(result WaitResult) string

func InjectPickerKeys added in v0.35.0 

func InjectPickerKeys(driver *tmux.Driver, sessID string, tool config.Tool)

InjectPickerKeys opens a picker that exists only inside a running TUI. The keys wait for the caret to rest on the tool's composer row, since a tool drawing inline (agy) leaves its last frame, composer and all, in the pane it exited.

func ProactiveCoordination added in v0.40.0 

func ProactiveCoordination(configDir string) (bool, error)

ProactiveCoordination reads the coordination mode the user picked in Settings. A config dir without a store has never run the manager, as on a fresh install asked for help, so it keeps the default.

func RelaunchInPane added in v0.34.0 

func RelaunchInPane(driver *tmux.Driver, st *store.Store, hookManager *hooks.Manager, sessID string, tool config.Tool) (store.Session, error)

RelaunchInPane starts a session's tool again inside the shell its pane already holds, so the pane keeps everything its last life left there. The session environment rides along inline because a pane opened by an older manager holds a shell that was never given it. It returns the row it relaunched, read after the agent quit, since that agent may have reported a switch the caller's copy predates.

func Rename 

func Rename(ctx context.Context, configDir, sessionID, name string) (string, error)

Rename waits for the manager's poll because the manager owns the database and the tmux label: a name it cannot give the session comes back as the reason, and a name no manager is running to apply is reported as queued rather than as done.

func RenameWorktreeBranch added in v0.43.0 

func RenameWorktreeBranch(gitDrv *git.Driver, st worktreeRenameStore, sess *store.Session, name string) error

RenameWorktreeBranch keeps a managed branch aligned with its session's display name without moving the directory of a live process.

func RequireCaller added in v0.40.0 

func RequireCaller(sessionID string) error

RequireCaller refuses an empty caller for a front that must act as a session.

func ReviewBase 

func ReviewBase(configDir, sessionID, cwd, ref string) (string, error)

ReviewBase records the base ref the session's branch scope diffs against, resolved in the repo holding cwd. An empty ref clears the override.

func ReviewComment added in v0.32.0 

func ReviewComment(configDir, sessionID, commentID string, handled bool) (string, error)

func ReviewRepo 

func ReviewRepo(configDir, sessionID, target string) (string, error)

ReviewRepo records the repo a session is working in, so review opens there instead of guessing from the working directory.

func ReviewScope added in v0.10.3 

func ReviewScope(configDir, sessionID, scope string) (string, error)

ReviewScope records the diff scope the review screen should open with for this session: uncommitted, branch (vs target), last_commit, or staged.

func SessionLabel added in v0.43.0 

func SessionLabel(group, name string) string

SessionLabel renders a session's identity for the tmux status bar.

func SettleConversation added in v0.42.0 

func SettleConversation(st *store.Store, hookManager *hooks.Manager, sess store.Session, style string, paneGone bool, wait time.Duration) (store.Session, error)

SettleConversation moves a session onto the conversation its CLI names only as it closes, once the agent has quit. Hermes rewrites its terminal's crumb on close, which is the only place a /branch or /resume shows. paneGone says the session's pane no longer exists. wait is how long to give an agent still closing; past it the row stays as it was.

func ShellName added in v0.31.0 

func ShellName(toolName, parentID, fallbackSuffix string, sessions []store.Session) string

ShellName names a terminal after the session it hangs under, so a row says which session opened it rather than four random digits. A terminal with no session over it falls back to those digits, and one joining terminals already named for that session counts up. Both the list's T and the terminal tools name through here, so a shell reads the same whichever opened it.

func SnapshotRelaunch added in v0.35.0 

func SnapshotRelaunch(st *store.Store, sess store.Session, tool config.Tool, agentSessionID string) error

func TrackConversation added in v0.42.0 

func TrackConversation(configDir string, args []string, stdin io.Reader) error

TrackConversation records the conversation a running agent reports it is on, for the launch named in its environment. The agent's own hook runs it, with the id given directly or as a field of the hook's JSON input. Outside a managed session, in a pane an earlier manager launched without a launch stamp, and for any process but the agent its launch started, it does nothing.

Types

type AfterTurn added in v0.40.0 

type AfterTurn struct {
	Pending      string `` /* 128-byte string literal not displayed */
	Replaced     string `json:"replaced,omitempty" jsonschema:"the action this call replaced"`
	Canceled     string `json:"canceled,omitempty" jsonschema:"the action this call withdrew"`
	ManagerAwake bool   `` /* 148-byte string literal not displayed */
}

AfterTurn is what the calling session left for the manager to do to it once its turn ends.

type ArchiveOwner added in v0.43.0 

type ArchiveOwner interface {
	Archive(ArchiveRequest) (Session, error)
}

type ArchiveRequest added in v0.43.0 

type ArchiveRequest struct {
	CallerID string
	TargetID string
	Archived bool
	Words    Vocabulary
}

type ArchiveResult added in v0.43.0 

type ArchiveResult struct {
	GroupChanged bool
	Sessions     []store.Session
	GroupPath    string
	Archived     bool
	LabelError   error
}

type ArchiveSelection added in v0.43.0 

type ArchiveSelection struct {
	Sessions  []store.Session
	GroupPath string
}

type Backend added in v0.43.0 

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

Backend binds command services to exactly one local runtime. OpenBackend owns a lazily opened store; BorrowBackend uses the caller's runtime and never closes it.

func BorrowBackend added in v0.43.0 

func BorrowBackend(runtime Runtime) (*Backend, error)

func OpenBackend added in v0.43.0 

func OpenBackend(configDir string) *Backend

func (*Backend) Close added in v0.43.0 

func (b *Backend) Close() error

Close releases only a runtime opened by this backend. It is safe to call more than once and is a no-op for borrowed runtimes.

func (*Backend) Connections added in v0.43.0 

func (b *Backend) Connections() ([]store.Connection, error)

Connections reads the SSH connections from this backend's store, for the same reason as ProactiveCoordination.

func (*Backend) Lifecycle added in v0.43.0 

func (b *Backend) Lifecycle() (*Lifecycle, error)

func (*Backend) ProactiveCoordination added in v0.43.0 

func (b *Backend) ProactiveCoordination() (bool, error)

ProactiveCoordination reads the coordination mode from this backend's already-open store. Long-lived MCP owners must not open a second store to decide which instructions they serve.

func (*Backend) Rename added in v0.43.0 

func (b *Backend) Rename(ctx context.Context, sessionID, name string) (string, error)

func (*Backend) ReviewBase added in v0.43.0 

func (b *Backend) ReviewBase(sessionID, cwd, ref string) (string, error)

func (*Backend) ReviewComment added in v0.43.0 

func (b *Backend) ReviewComment(sessionID, commentID string, handled bool) (string, error)

func (*Backend) ReviewRepo added in v0.43.0 

func (b *Backend) ReviewRepo(sessionID, target string) (string, error)

func (*Backend) ReviewScope added in v0.43.0 

func (b *Backend) ReviewScope(sessionID, scope string) (string, error)

func (*Backend) WithStore added in v0.43.0 

func (b *Backend) WithStore(use func(*store.Store) error) error

WithStore runs use on this backend's store, for the same reason as ProactiveCoordination.

type CreateSessionOptions added in v0.31.0 

type CreateSessionOptions struct {
	Tool string
	Name string
	// Nil inherits the calling session's group; a pointer to an empty string
	// deliberately targets the root group.
	Group     *string
	Directory string
	Prompt    string
	Preset    string
	// Nil inherits the group's spawn-in-worktree choice, then the global
	// setting.
	Worktree *bool
	// Model, Effort and Profile ride every later launch of the session.
	Model   string
	Effort  string
	Profile string
}

type CreateTerminalOptions added in v0.28.0 

type CreateTerminalOptions struct {
	// Nil inherits the calling session's group; a pointer to an empty string
	// deliberately targets the root group.
	Group     *string
	Directory string
	Nest      *bool
}

type DeleteResult added in v0.43.0 

type DeleteResult struct {
	Deleted       []store.Session
	RemovedGroups []string
	Notice        string
}

type DeleteSelection added in v0.43.0 

type DeleteSelection struct {
	Sessions     []store.Session
	GroupPath    string
	ArchivedOnly bool
}

type EndAfterTurnResult added in v0.43.0 

type EndAfterTurnResult struct {
	Action   string
	Sessions []store.Session
}

EndAfterTurnResult names what EndAfterTurn did, so the manager can mirror it in memory without reading the rows back.

type Group added in v0.31.0 

type Group struct {
	Path      string `json:"path" jsonschema:"full group path, slash separated; pass this value as a group argument"`
	Directory string `json:"directory,omitempty" jsonschema:"group's default working directory, inherited by sessions created in it"`
	Worktree  string `json:"worktree,omitempty" jsonschema:"group's spawn-in-worktree choice: on, off, or empty to inherit"`
	Archived  bool   `json:"archived" jsonschema:"whether the group is archived"`
	Sessions  int    `json:"sessions" jsonschema:"number of active agent sessions directly in this group"`
}

type GroupRemoval added in v0.31.0 

type GroupRemoval struct {
	Removed []string `json:"removed" jsonschema:"group paths that no longer exist, the named group and anything nested under it"`
	Moved   []string `json:"moved,omitempty" jsonschema:"ids of sessions that were filed under those groups and now sit in the root group"`
}

GroupRemoval is what deleting a group did, since a fleet that filed work under one wants to know where its sessions went.

type InboxMaintenance added in v0.43.0 

type InboxMaintenance interface {
	MaintainInbox() error
}

type InboxOwner added in v0.43.0 

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

func NewInboxOwner added in v0.43.0 

func NewInboxOwner(st *store.Store) *InboxOwner

func (*InboxOwner) MaintainInbox added in v0.43.0 

func (owner *InboxOwner) MaintainInbox() error

type LaunchRequest added in v0.43.0 

type LaunchRequest struct {
	Session          store.Session
	Tool             config.Tool
	BaseCommand      string
	Pane             PaneSize
	BesideSessionID  string
	RollbackWorktree bool
}

type LaunchResult added in v0.43.0 

type LaunchResult struct {
	Session    store.Session
	LabelError error
}

type Lifecycle added in v0.43.0 

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

Lifecycle owns the ordered store, tmux, hook, and worktree effects shared by the interactive manager and session-scoped commands. Its runtime is borrowed; closing resources remains the composing process's responsibility.

func NewLifecycle added in v0.43.0 

func NewLifecycle(runtime Runtime) (*Lifecycle, error)

func (*Lifecycle) ArchiveForHuman added in v0.43.0 

func (l *Lifecycle) ArchiveForHuman(selection ArchiveSelection) (ArchiveResult, error)

ArchiveForHuman preserves the interactive action: capture every live pane before ending any of them, then archive the selected rows or group.

func (*Lifecycle) Capture added in v0.43.0 

func (l *Lifecycle) Capture(cfg config.Config, snapshot func(string, string) error) *Lifecycle

Capture borrows the same bound resources and operation policies with an independently supplied configuration and snapshot writer for one dispatch. The caller owns copying configuration values it may later mutate.

func (*Lifecycle) DeleteForHuman added in v0.43.0 

func (l *Lifecycle) DeleteForHuman(selection DeleteSelection) (DeleteResult, error)

DeleteForHuman owns the destructive effects after the UI has confirmed them. Child terminals go first so a partial failure never leaves a row pointing at a parent that is already gone.

func (*Lifecycle) EndAfterTurn added in v0.43.0 

func (l *Lifecycle) EndAfterTurn(id string) (EndAfterTurnResult, error)

EndAfterTurn archives or kills a session whose turn ended after it asked for that, taking the same steps the archive and kill keys take. A request the row no longer carries, or a session that started a new turn since the pass that reported it, is left alone and returns an empty Action.

func (*Lifecycle) Kill added in v0.43.0 

func (l *Lifecycle) Kill(sess store.Session) (store.Session, error)

Kill leaves the row and conversation intact for revive. Pane capture is best effort, but a captured frame must be persisted before the pane dies.

func (*Lifecycle) Launch added in v0.43.0 

func (l *Lifecycle) Launch(request LaunchRequest) (LaunchResult, error)

Launch creates the pane before its row and rolls the pane back if the row cannot be persisted. A label failure is returned separately because the UI reports it while agent commands historically treat it as cosmetic.

func (*Lifecycle) Restart added in v0.43.0 

func (l *Lifecycle) Restart(sess store.Session, pane PaneSize) (RelaunchResult, error)

func (*Lifecycle) RestoreForHuman added in v0.43.0 

func (l *Lifecycle) RestoreForHuman(selection ArchiveSelection, pane PaneSize) (ArchiveResult, error)

func (*Lifecycle) Revive added in v0.43.0 

func (l *Lifecycle) Revive(listed store.Session, pane PaneSize) (RelaunchResult, error)

Revive relaunches a dead session or an agent that quit to its shell. The row is read again first, since the listed copy can predate the last conversation the agent reported, and the agent's last conversation is settled before the revive command is built.

func (*Lifecycle) SetArchivedForSession added in v0.43.0 

func (l *Lifecycle) SetArchivedForSession(callerID, targetID string, archived bool, words Vocabulary) (Session, error)

SetArchivedForSession implements agent-command archive policy: one target, no self-archive, and no pane termination.

func (*Lifecycle) Spawn added in v0.43.0 

func (l *Lifecycle) Spawn(request SpawnRequest) (LaunchResult, error)

Spawn is the one path a new session takes, from the manager and from the CLI: it opens the worktree the request asks for, fills the row from the launch plan, and launches it, handing the worktree back if that fails.

type Mailbox added in v0.43.0 

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

func NewMailbox added in v0.43.0 

func NewMailbox(configDir string) *Mailbox

func (*Mailbox) Rename added in v0.43.0 

func (m *Mailbox) Rename(ctx context.Context, id, name string) (string, error)

func (*Mailbox) ReviewBase added in v0.43.0 

func (m *Mailbox) ReviewBase(id, cwd, ref string) (string, error)

func (*Mailbox) ReviewComment added in v0.43.0 

func (m *Mailbox) ReviewComment(id, comment string, handled bool) (string, error)

func (*Mailbox) ReviewRepo added in v0.43.0 

func (m *Mailbox) ReviewRepo(id, target string) (string, error)

func (*Mailbox) ReviewScope added in v0.43.0 

func (m *Mailbox) ReviewScope(id, scope string) (string, error)

type MayHaveReachedError added in v0.43.0 

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

MayHaveReachedError is a send whose paste may have reached the pane.

func (*MayHaveReachedError) Error added in v0.43.0 

func (e *MayHaveReachedError) Error() string

func (*MayHaveReachedError) Unwrap added in v0.43.0 

func (e *MayHaveReachedError) Unwrap() error

type MessageState added in v0.31.0 

type MessageState struct {
	MessageID   int64  `json:"message_id"`
	SessionID   string `json:"session_id" jsonschema:"session the message was addressed to"`
	Body        string `json:"body"`
	State       string `` /* 339-byte string literal not displayed */
	DeliveredAt string `json:"delivered_at,omitempty" jsonschema:"RFC3339 time the message reached the prompt"`
	Reason      string `json:"reason,omitempty" jsonschema:"why the message is in that state, and what to do about it"`
}

type PaneSize added in v0.43.0 

type PaneSize struct {
	Width  int
	Height int
}

type RelaunchResult added in v0.43.0 

type RelaunchResult struct {
	Session      store.Session
	LaunchedAt   time.Time
	ReusedPane   bool
	Degraded     bool
	LabelError   error
	Conversation string
}

type Reservation added in v0.31.0 

type Reservation struct {
	Pattern   string `json:"pattern" jsonschema:"path or glob the lease covers"`
	Mode      string `json:"mode" jsonschema:"exclusive (nobody else edits these paths) or shared (others may read or also edit)"`
	SessionID string `json:"session_id" jsonschema:"session holding the lease"`
	Holder    string `json:"holder" jsonschema:"name of the session holding the lease"`
	Note      string `json:"note,omitempty" jsonschema:"what the holder is doing there"`
	ExpiresIn string `json:"expires_in" jsonschema:"time left before the lease lapses on its own"`
	Mine      bool   `json:"mine" jsonschema:"whether the calling session holds it"`
}

type ReserveResult added in v0.31.0 

type ReserveResult struct {
	Reserved  []Reservation `json:"reserved" jsonschema:"leases this session now holds"`
	Conflicts []Reservation `` /* 200-byte string literal not displayed */
}

type Runtime added in v0.43.0 

type Runtime struct {
	Config   config.Config
	Store    *store.Store
	Driver   *tmux.Driver
	Hooks    *hooks.Manager
	Git      *git.Driver
	Snapshot func(string, string) error
}

Runtime is the already-open local workspace used by a long-lived owner. The caller retains ownership of borrowed dependencies.

type SendResult added in v0.31.0 

type SendResult struct {
	MessageID     int64 `json:"message_id" jsonschema:"pass to message_status to see whether it arrived"`
	QueuePosition int   `json:"queue_position" jsonschema:"this message's place in the recipient's queue; 1 means it is next"`
	ManagerAwake  bool  `` /* 144-byte string literal not displayed */
}

type Session added in v0.31.0 

type Session struct {
	ID        string `json:"id" jsonschema:"agent session id"`
	Name      string `json:"name" jsonschema:"session name shown in Agent Manager"`
	Tool      string `json:"tool" jsonschema:"agent CLI the session runs"`
	Group     string `json:"group" jsonschema:"group path holding the session; empty is the root"`
	Directory string `json:"directory" jsonschema:"session's current working directory, or its launch directory when stopped"`
	Status    string `json:"status" jsonschema:"Agent Manager status: starting, working, waiting, finished, idle, errored or dead"`
	Running   bool   `json:"running" jsonschema:"whether the session currently has a live tmux pane"`
	Archived  bool   `json:"archived" jsonschema:"whether the session is archived out of the active list"`
	Branch    string `json:"branch,omitempty" jsonschema:"branch of the worktree Agent Manager created for this session, when it has one"`
	Self      bool   `json:"self" jsonschema:"whether this row is the calling session itself"`
}

type SessionOwner added in v0.43.0 

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

func NewSessionOwner added in v0.43.0 

func NewSessionOwner(cfg config.Config, st *store.Store, driver *tmux.Driver) *SessionOwner

func (*SessionOwner) Archive added in v0.43.0 

func (owner *SessionOwner) Archive(request ArchiveRequest) (Session, error)

type SessionScreen added in v0.31.0 

type SessionScreen struct {
	Session Session `json:"session"`
	Output  string  `json:"output" jsonschema:"plain text currently visible in the session pane"`
}

type Sessions added in v0.31.0 

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

func NewSessions added in v0.31.0 

func NewSessions(configDir string, words Vocabulary) *Sessions

func NewSessionsWithArchiveOwner added in v0.43.0 

func NewSessionsWithArchiveOwner(configDir string, words Vocabulary, owner ArchiveOwner) *Sessions

func NewSessionsWithBackend added in v0.43.0 

func NewSessionsWithBackend(backend *Backend, words Vocabulary) *Sessions

func (*Sessions) Archive added in v0.31.0 

func (s *Sessions) Archive(sessionID, targetID string, archived bool) (Session, error)

Archive parks a session out of the active list, or restores it. A live pane keeps running; archiving only changes where the row is filed, and the last screen is captured first so an archived row still shows one.

func (*Sessions) CancelAfterTurn added in v0.40.0 

func (s *Sessions) CancelAfterTurn(sessionID string) (AfterTurn, error)

CancelAfterTurn withdraws whichever end the calling session has pending.

func (*Sessions) ClaimTask added in v0.31.0 

func (s *Sessions) ClaimTask(sessionID, taskID string) (Task, error)

ClaimTask takes a named task, or the oldest unblocked one when no id is given. A task another session already holds is refused rather than stolen: the loser of the race finds out instead of duplicating work.

func (*Sessions) Create added in v0.31.0 

func (s *Sessions) Create(sessionID string, opts CreateSessionOptions) (Session, error)

func (*Sessions) CreateGroup added in v0.31.0 

func (s *Sessions) CreateGroup(sessionID, path, directory string) (Group, error)

CreateGroup adds a group under an existing parent, so sessions spawned later can be filed into it. Directory becomes the group's inherited default working directory.

func (*Sessions) CreateTask added in v0.31.0 

func (s *Sessions) CreateTask(sessionID, title, body string, dependsOn []string) (Task, error)

func (*Sessions) DeleteGroup added in v0.31.0 

func (s *Sessions) DeleteGroup(sessionID, path string) (GroupRemoval, error)

DeleteGroup removes a group and the groups nested under it. Sessions filed there move to the root rather than going with it: an agent tidying up the group it opened for a finished fleet is not asking to destroy whatever is still running in it.

func (*Sessions) DeleteTask added in v0.31.0 

func (s *Sessions) DeleteTask(sessionID, taskID string) error

func (*Sessions) EndAfterTurn added in v0.40.0 

func (s *Sessions) EndAfterTurn(sessionID, action string) (AfterTurn, error)

EndAfterTurn asks the manager to archive or kill the calling session once the turn making this call ends. Ending it now would cut off the reply the agent is still writing, and the agent cannot outlive its own kill to finish the bookkeeping, so the manager does it.

func (*Sessions) ExpandSaved added in v0.43.0 

func (s *Sessions) ExpandSaved(name, text string) (string, error)

ExpandSaved resolves a saved prompt in front of text. An empty name returns the trimmed text. A missing name refuses the send.

func (*Sessions) FinishTask added in v0.31.0 

func (s *Sessions) FinishTask(sessionID, taskID string) (Task, error)

func (*Sessions) Groups added in v0.31.0 

func (s *Sessions) Groups(sessionID string) ([]Group, error)

func (*Sessions) Kill added in v0.31.0 

func (s *Sessions) Kill(sessionID, targetID string) (Session, error)

Kill stops a session's pane and leaves its row dead, keeping the last screen so the manager can still show it and a revive can resume the conversation it held.

func (*Sessions) List added in v0.31.0 

func (s *Sessions) List(sessionID string) ([]Session, error)

func (*Sessions) MessageStatus added in v0.31.0 

func (s *Sessions) MessageStatus(sessionID string, messageID int64) (MessageState, error)

MessageStatus reports what happened to a message this session sent.

func (*Sessions) Read added in v0.31.0 

func (s *Sessions) Read(sessionID, targetID string) (SessionScreen, error)

func (*Sessions) ReadStyled added in v0.43.0 

func (s *Sessions) ReadStyled(sessionID, targetID string) (SessionScreen, error)

ReadStyled is Read with the screen's escape sequences kept, for a manager painting it over SSH in its colors.

func (*Sessions) ReleaseFiles added in v0.31.0 

func (s *Sessions) ReleaseFiles(sessionID string, patterns []string) (int, error)

ReleaseFiles drops this session's leases once it is done editing.

func (*Sessions) ReleaseTask added in v0.31.0 

func (s *Sessions) ReleaseTask(sessionID, taskID string) (Task, error)

func (*Sessions) Reservations added in v0.31.0 

func (s *Sessions) Reservations(sessionID string) ([]Reservation, error)

Reservations lists every live lease, so an agent can see what the rest of the fleet is editing before it starts.

func (*Sessions) Reserve added in v0.31.0 

func (s *Sessions) Reserve(sessionID string, patterns []string, mode, note string, ttl time.Duration) (ReserveResult, error)

Reserve declares that this session is working on a set of paths. The lease is advisory and expires on its own, so an agent that dies never holds the repo hostage. Overlapping leases are reported rather than refused: the point is that both agents find out in time to talk.

func (*Sessions) Revive added in v0.31.0 

func (s *Sessions) Revive(sessionID, targetID string) (Session, error)

Revive relaunches a dead session under its old id, keeping its name, group and history, and resuming the conversation it held where the tool can.

func (*Sessions) Send added in v0.31.0 

func (s *Sessions) Send(sessionID, targetID, message string) (SendResult, error)

Send queues a message for another agent. It is deliberately not typed into the pane here: several tools keep their input line drawn under an approval dialog, so a message sent the moment it is written would answer that dialog. The manager's poller types it in once the target is at rest.

func (*Sessions) SendFrom added in v0.43.0 

func (s *Sessions) SendFrom(sessionID, senderName, targetID, message string) (SendResult, error)

SendFrom queues a message from a caller with no session on this machine, such as an agent on another one, under the name it gives. Nothing here can carry a reply back, and the envelope says so.

func (*Sessions) Snapshot added in v0.43.0 

func (s *Sessions) Snapshot(sessionID string) (Snapshot, error)

Snapshot lists this host's sessions and terminals, archived ones too, from a single read of the sessions table, so a terminal never names a parent row the same snapshot lacks.

func (*Sessions) Tasks added in v0.31.0 

func (s *Sessions) Tasks(sessionID string) ([]Task, error)

Tasks is the shared work list every session in the manager can see and claim from, so a fleet coordinates without one agent brokering handoffs.

func (*Sessions) Type added in v0.43.0 

func (s *Sessions) Type(sessionID, targetID, prompt string) (Session, error)

Type submits a prompt in an agent's pane now, as the user, the way the quick bar does: no envelope, no queue, no wait for the agent to be at rest. It is the quick bar of a manager on another machine, so it serves only a caller with no session here; a session sends, which waits.

func (*Sessions) Wait added in v0.31.0 

func (s *Sessions) Wait(ctx context.Context, sessionID, targetID string, until []string, timeout time.Duration) (WaitResult, error)

Wait parks until the target session reaches one of the given states, or the timeout expires. A timeout is an outcome rather than a failure: the caller gets the session's current state and decides what to do with it.

type Snapshot added in v0.43.0 

type Snapshot struct {
	Version      int        `json:"version"`
	ManagerAwake bool       `json:"manager_awake"`
	Sessions     []Session  `json:"sessions"`
	Terminals    []Terminal `json:"terminals"`
	Groups       []Group    `json:"groups"`
}

Snapshot is one host's inventory as another manager sees it: every row in list order, its groups, and whether a manager is awake to deliver queued messages there.

type SpawnRequest added in v0.43.0 

type SpawnRequest struct {
	Session  store.Session
	Tool     config.Tool
	Plan     launch.Plan
	Pane     PaneSize
	Worktree *WorktreeRequest
}

type Task added in v0.31.0 

type Task struct {
	ID        string   `json:"id" jsonschema:"task id to claim, finish or release"`
	Title     string   `json:"title" jsonschema:"one-line summary of the work"`
	Body      string   `json:"body,omitempty" jsonschema:"full instruction for whoever claims it"`
	State     string   `json:"state" jsonschema:"pending, in_progress or done"`
	Owner     string   `json:"owner,omitempty" jsonschema:"session id holding the claim"`
	OwnerName string   `json:"owner_name,omitempty" jsonschema:"name of the session holding the claim"`
	DependsOn []string `json:"depends_on,omitempty" jsonschema:"task ids that must be done before this one can be claimed"`
	BlockedBy []string `` /* 136-byte string literal not displayed */
	Blocked   bool     `json:"blocked" jsonschema:"whether unfinished dependencies currently stop this task being claimed"`
	Mine      bool     `json:"mine" jsonschema:"whether the calling session holds the claim"`
}

type Terminal added in v0.28.0 

type Terminal struct {
	ID         string `json:"id" jsonschema:"managed terminal session id"`
	Name       string `json:"name" jsonschema:"terminal name shown in Agent Manager"`
	Group      string `json:"group" jsonschema:"group path holding the terminal; empty is the root"`
	Directory  string `json:"directory" jsonschema:"terminal's current working directory, or its launch directory when stopped"`
	Status     string `json:"status" jsonschema:"stored Agent Manager status"`
	Running    bool   `json:"running" jsonschema:"whether the terminal currently has a live tmux pane"`
	ParentID   string `json:"parent_id" jsonschema:"id of the parent session when nested; empty when un-nested"`
	ParentName string `json:"parent_name" jsonschema:"name of the parent session when nested; empty when un-nested"`
	Archived   bool   `json:"archived,omitempty" jsonschema:"whether the terminal is archived out of the active list"`
}

type TerminalInput added in v0.31.0 

type TerminalInput struct {
	TerminalID string `json:"terminal_id"`
	Sent       string `json:"sent" jsonschema:"input kind sent: command or keys"`
}

TerminalInput is what one send put into a terminal. Which of the two kinds went in is decided here, where the dispatch happens, so neither front reads it back off its own arguments.

type TerminalScreen added in v0.28.0 

type TerminalScreen struct {
	Terminal Terminal `json:"terminal"`
	Output   string   `json:"output" jsonschema:"plain text currently visible in the terminal pane"`
}

type Terminals added in v0.28.0 

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

func NewTerminals added in v0.28.0 

func NewTerminals(configDir string, words Vocabulary) *Terminals

func NewTerminalsWithBackend added in v0.43.0 

func NewTerminalsWithBackend(backend *Backend, words Vocabulary) *Terminals

func (*Terminals) Close added in v0.30.0 

func (t *Terminals) Close(sessionID, terminalID string) error

func (*Terminals) Create added in v0.28.0 

func (t *Terminals) Create(sessionID string, opts CreateTerminalOptions) (Terminal, error)

func (*Terminals) List added in v0.28.0 

func (t *Terminals) List(sessionID string) ([]Terminal, error)

func (*Terminals) Read added in v0.28.0 

func (t *Terminals) Read(sessionID, terminalID string) (TerminalScreen, error)

func (*Terminals) ReadStyled added in v0.43.0 

func (t *Terminals) ReadStyled(sessionID, terminalID string) (TerminalScreen, error)

ReadStyled is Read with the screen's escape sequences kept.

func (*Terminals) Send added in v0.28.0 

func (t *Terminals) Send(sessionID, terminalID, command string, keys []string) (TerminalInput, error)

type Vocabulary added in v0.31.0 

type Vocabulary struct {
	ListSessions   string
	ListTerminals  string
	ListTasks      string
	ListGroups     string
	CreateGroup    string
	CreateTerminal string
	SpawnTool      string
	SpawnModel     string
	SpawnEffort    string
	SpawnProfile   string
	Revive         string
	Restore        string
	Send           string
	Read           string
	ArchiveSelf    string
	KillSelf       string
}

Vocabulary is how one front spells the actions these errors send a caller after. Both fronts drive this layer, but an agent holds only one of them: a session whose CLI carries no MCP client has the subcommands and nothing else, so naming a tool at it points at something it cannot call.

func CLIVocabulary added in v0.31.0 

func CLIVocabulary() Vocabulary

CLIVocabulary spells them as the subcommands an agent runs from its shell.

func MCPVocabulary added in v0.31.0 

func MCPVocabulary() Vocabulary

MCPVocabulary spells the actions as the tools an MCP client sees.

type WaitResult added in v0.31.0 

type WaitResult struct {
	Session      Session `json:"session"`
	Reached      bool    `json:"reached" jsonschema:"true when the session reached one of the awaited states"`
	Outcome      string  `` /* 135-byte string literal not displayed */
	Waited       string  `json:"waited" jsonschema:"how long the wait lasted"`
	ManagerAwake bool    `` /* 171-byte string literal not displayed */
}

type WorktreeRequest added in v0.43.0 

type WorktreeRequest struct {
	Base  string
	Fetch bool
}

WorktreeRequest asks Spawn for the session's own checkout of the repository its Cwd is in.

Source Files

View all Source files

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.