session

package
v0.7.59 Latest Latest
Warning

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

Go to latest
Published: Nov 13, 2026 License: MIT Imports: 5 Imported by: 0

Documentation

Overview

Package session is the interactive run API: what a chat surface — the CLI's TUI, the desktop app — talks to. It sees a text channel and a read-only file drop, both recorded as receipts, and nothing that could widen the plan's capabilities: turns are prompts to the harness, inputs land under the staged /inputs directory, and the engine ends the session on the operator's budgets whatever the surface does.

Index

Constants

View Source
const StopInterrupted = "interrupted"

StopInterrupted is the StopReason of a turn Interrupt stopped.

Variables

View Source
var ErrBusy = errors.New("a turn is in flight; send again when its answer arrives")

ErrBusy is a Send refused because another turn is in flight: a session that more than one driver attaches to answers it rather than queue the turn.

View Source
var ErrCannotSteer = errors.New("this harness takes no message while a turn is in flight")

ErrCannotSteer is returned by Steer when the session's harness takes a message only between turns.

View Source
var ErrEnded = errors.New("session has ended")

ErrEnded is returned by Send and AddInput once the session has ended.

View Source
var ErrInterrupted = errors.New("the turn was stopped")

ErrInterrupted is returned by Send when Interrupt stopped the turn before the harness finished it. The turn's assistant_turn carries what the agent had said by then, with StopReason StopInterrupted.

View Source
var ErrNoTurn = errors.New("no turn is in flight")

ErrNoTurn is returned by Interrupt and Steer when no turn is in flight.

Functions

This section is empty.

Types

type Answerer added in v0.7.1

type Answerer interface {
	Answer(ctx context.Context, id string, yes bool) error
}

Answerer is a session a client can answer a question of.

type EndReason

type EndReason string

EndReason is why a session ended.

const (
	// EndFinished: the user asked for the final result and got it.
	EndFinished EndReason = "finished"
	// EndQuit: the user ended the session without asking for a result.
	EndQuit EndReason = "quit"
	// EndIdle: no user turn within the idle timeout.
	EndIdle EndReason = "idle_timeout"
	// EndWall: the session's wall-clock cap.
	EndWall EndReason = "wall_timeout"
	// EndUserTurns: the user-turn cap.
	EndUserTurns EndReason = "max_user_turns"
	// EndToolBudget: the tool-call (turn) budget.
	EndToolBudget EndReason = "tool_budget"
	// EndCostBudget: the cost budget.
	EndCostBudget EndReason = "cost_budget"
	// EndPlanLimit: the person's plan refused the model's calls for its
	// usage limit.
	EndPlanLimit EndReason = "plan_limit"
	// EndOrgPolicy: a policy of the person's organization at the model
	// vendor refused the run.
	EndOrgPolicy EndReason = "org_policy"
	// EndOutOfCredits: the model's provider refused the calls because the
	// paying account has no credits left.
	EndOutOfCredits EndReason = "out_of_credits"
	// EndHarness: the harness exited on its own.
	EndHarness EndReason = "harness_exit"
	// EndCancelled: the caller's context ended.
	EndCancelled EndReason = "cancelled"
)

type Event

type Event struct {
	Kind Kind      `json:"kind"`
	Time time.Time `json:"time"`
	// Text is the message text (turns, chunks), the tool name (tool calls),
	// or the error text.
	Text string `json:"text,omitempty"`
	// Question is a question's id (KindQuestion).
	Question string `json:"question,omitempty"`
	// Synthetic marks a user turn the runner composed (an input notice).
	Synthetic bool `json:"synthetic,omitempty"`
	// Task is, on a user turn a persistent agent's heartbeat sent, the id
	// of the task it was for: the turn is the agent's own, not the
	// person's, and a chat draws it as such.
	Task string `json:"task,omitempty"`
	// Messenger is, on a user turn a persistent agent's messenger sent, the
	// messenger's kind (telegram): the person wrote it there.
	Messenger string `json:"messenger,omitempty"`
	// Upkeep marks, on a user turn, a persistent agent's upkeep: the turn
	// is the runner's, sent before its conversation is compacted or its
	// memory is tidied, and a chat draws it as such.
	Upkeep bool `json:"upkeep,omitempty"`
	// StopReason is the harness's reason for ending an assistant turn.
	StopReason string `json:"stopReason,omitempty"`
	// Path and Digest describe an added input (agent-side path).
	Path   string `json:"path,omitempty"`
	Digest string `json:"digest,omitempty"`
	// Reason says why the session ended.
	Reason EndReason `json:"reason,omitempty"`
	// Token usage for usage events.
	InputTokens  int64 `json:"inputTokens,omitempty"`
	OutputTokens int64 `json:"outputTokens,omitempty"`
	// TotalTokens is context tokens from a harness that gives no input/output
	// split (docker-agent's usage_update; the per-update delta).
	TotalTokens int64   `json:"totalTokens,omitempty"`
	CostUSD     float64 `json:"costUsd,omitempty"`
	// ContextTokens and ContextLimit are, on a usage event, the
	// conversation's size after the harness's latest request and the
	// model's window, where the harness says them; zero is unknown.
	ContextTokens int64 `json:"contextTokens,omitempty"`
	ContextLimit  int64 `json:"contextLimit,omitempty"`
	// ContextCompacted says, on a usage event, that the harness has just
	// compacted the conversation itself; ContextTokens is then its size
	// after, zero when the harness did not say.
	ContextCompacted bool `json:"contextCompacted,omitempty"`
	// Raw is the harness's own message, when there was one.
	Raw json.RawMessage `json:"raw,omitempty"`
}

Event is one thing that happened in the session.

type Interrupter added in v0.6.1004

type Interrupter interface {
	// Interrupt stops the turn in flight and returns once it has ended,
	// or with ErrNoTurn when there is none.
	Interrupt(ctx context.Context) error
}

Interrupter is a Session that can stop the turn in flight without ending the session: the harness is told to stop, the turn ends, and the next Send is taken as usual.

type Kind

type Kind string

Kind classifies session events; every kind is a line in events.ndjson.

const (
	// KindUserTurn is a user (or synthetic runner) message sent to the harness.
	KindUserTurn Kind = "user_turn"
	// KindAssistantText is a streamed chunk of assistant text.
	KindAssistantText Kind = "assistant_text"
	// KindAssistantTurn closes a turn: the full assistant text and stop reason.
	KindAssistantTurn Kind = "assistant_turn"
	// KindToolCall is one tool call the harness made through the gateway.
	KindToolCall Kind = "tool_call"
	// KindUsage carries the harness's token usage for a turn (or, for a
	// harness that reports only context tokens, one usage update).
	KindUsage Kind = "usage"
	// KindPermissionGranted records an in-harness permission request the
	// runner allowed — a gateway tool.
	KindPermissionGranted Kind = "permission_granted"
	// KindPermissionDenied records an in-harness permission request the
	// runner refused — a tool outside the gateway's catalog.
	KindPermissionDenied Kind = "permission_denied"
	// KindInputAdded records a file added to /inputs mid-run.
	KindInputAdded Kind = "input_added"
	// KindIntake records the non-secret intake answers the run started with.
	KindIntake Kind = "intake"
	// KindSteer is a message handed to the harness while a turn was in
	// flight: the person's, or with Synthetic the runner's own (a notice of
	// an added file). The turn goes on; no turn opens or closes with it.
	KindSteer Kind = "steer"
	// KindSteered says the harness has put the messages it was handed into
	// the conversation at this point of the turn: after the results of the
	// calls it was running, or where the model would otherwise have ended
	// its answer.
	KindSteered Kind = "steered"
	// KindSessionEnd is the last event; Reason says why.
	KindSessionEnd Kind = "session_end"
	// KindError is a harness-reported error.
	KindError Kind = "error"
	// KindOther is anything else the harness said, kept for the record.
	KindOther Kind = "other"
	// KindNotice is the runner's word to the person about the session, which
	// a chat shows them and the harness never sees: a check of a persistent
	// agent's share folder, a change it is restarting with.
	KindNotice Kind = "notice"
	// KindQuestion is a question the runner puts to the person for an agent:
	// Question is its id, Text the question. A client that can answer
	// sends an answer naming the id (protocol.Answer); the first answer is
	// the one taken.
	KindQuestion Kind = "question"
	// KindTell is a persistent agent's message to the person from a turn
	// of its own: Text is the message, Task the task whose turn sent it. A
	// chat shows it as the agent's message, apart from the turn's work,
	// and the harness never sees it as a turn.
	KindTell Kind = "tell"
)

type Session

type Session interface {
	// Events streams everything that happens, in order; closed after End.
	Events() <-chan Event
	// Send delivers one user turn and returns when the harness ends it
	// (the assistant_turn event). One turn at a time.
	Send(ctx context.Context, text string) error
	// AddInput copies a regular host file into the run's read-only inputs
	// and tells the agent.
	AddInput(ctx context.Context, hostPath string) error
	// End finishes the session: with finish, the agent is asked for its
	// final result first (only when the release declares an output
	// schema). Receipts and the envelope are written, the sandbox torn
	// down. Safe to call after a budget ended the session.
	End(ctx context.Context, finish bool) (*receipt.Envelope, error)
	// Ended reports whether the session is over and why.
	Ended() (bool, EndReason)
}

Session is one interactive run.

type Steerer added in v0.7.56

type Steerer interface {
	// Steer hands text to the turn in flight and returns once the harness
	// has been given it. With no turn in flight it returns ErrNoTurn, and
	// the caller sends the text as a turn; on a harness that cannot take
	// one, an error that is ErrCannotSteer. The person's message counts
	// as one of the session's user messages.
	Steer(ctx context.Context, text string) error
}

Steerer is a Session whose turn in flight can be sent a message: the harness adds it to the conversation after the results of the calls it is running, or when the model next answers with no call, and the turn goes on with it. The message is recorded as a steer event, and a steered event marks where it joined.

Directories

Path Synopsis
Package protocol is the session protocol: an interactive session driven by a program rather than a person, over pipes and with no terminal.
Package protocol is the session protocol: an interactive session driven by a program rather than a person, over pipes and with no terminal.

Jump to

Keyboard shortcuts

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