protocol

package
v0.6.1009 Latest Latest
Warning

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

Go to latest
Published: Oct 30, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package protocol is the session protocol: an interactive session driven by a program rather than a person, over pipes and with no terminal. Commands arrive as JSON lines on one stream, the session's events leave as JSON lines on another, and the session itself is the unchanged session.Session every other surface drives — the TUI, the desktop, agentry-mcp — so the protocol can say nothing a chat could not.

The commands, one JSON object per line, each exactly one of:

{"send":{"text":"…"}}       one user turn
{"add":{"path":"…"}}        a regular file the driver staged in Options.InputsDir
{"end":{"finish":true}}     ask for the final result, then end (the TUI's /finish)
{"end":{"finish":false}}    end without one (the TUI's /quit)

End of input is an end without a result. Every event line is one session.Event exactly as the session emitted it, redacted as it reaches events.ndjson, with the harness's raw message left out. A command the protocol refuses is answered with an event of kind "error" carrying Refused, the class of the refusal; a refusal never ends the session and is not a session event, so the receipts do not record it.

Index

Constants

View Source
const (
	// MaxLine bounds one command line. A longer line is refused, and the
	// protocol reads on from the next one.
	MaxLine = 1 << 20
	// MaxBehind is how far the events reader may fall behind before the
	// protocol stops writing to it. The session never waits for the reader:
	// its events channel feeds the pump that enforces the budgets, and a
	// session held up by a reader that stopped reading would never end.
	MaxBehind = 16 << 20
)

Variables

This section is empty.

Functions

func Serve

func Serve(ctx context.Context, s session.Session, in io.Reader, events io.Writer, opts Options) (*receipt.Envelope, error)

Serve drives s from the commands on in and writes its events to events until the session is over, then ends it and returns End's envelope and error. It returns when an end command arrives, when in reaches its end, when the session ends by itself (a budget, the idle or wall cap, the harness exiting), or when ctx is done. Every event is written by the time it returns, unless the reader fell MaxBehind or stopped taking them; Options.OnDropped says so when that happens.

Types

type Add

type Add struct {
	Path string `json:"path"`
}

Add names a regular file, directly in Options.InputsDir, to copy into the run's read-only inputs. A relative path is taken in that directory.

type Command

type Command struct {
	Send *Send `json:"send,omitempty"`
	Add  *Add  `json:"add,omitempty"`
	End  *End  `json:"end,omitempty"`
}

Command is one line of input: exactly one of its members is set.

type End

type End struct {
	Finish bool `json:"finish"`
}

End ends the session; Finish asks the agent for its final result first.

type Event

type Event struct {
	session.Event
	// Refused is set on an error event the protocol wrote about a command
	// it refused; it is empty on every event the session emitted.
	Refused Refusal `json:"refused,omitempty"`
}

Event is one line of output: a session event, or a refusal.

type Options

type Options struct {
	// OpeningTurn says the session was started with a task, which it sends
	// as its first user turn by itself: a send is refused until that turn
	// ends, as it would be for a turn the driver sent. Set it only when the
	// session does send one (a non-blank task), or no send is taken until
	// the session's first turn of any kind.
	OpeningTurn bool
	// InputsDir is where the driver stages the files it adds. An add must
	// name a regular file directly in it; with none, every add is refused.
	// The TUI's /add takes any path a person types; a path a program sends
	// is held to the directory that program said it would use.
	InputsDir string
	// OnUsage, when set, is called with the session's running usage totals
	// after every usage event — the autonomous run's engine.Params.OnUsage
	// contract, so a driver meters a session as it meters a run.
	OnUsage func(receipt.Usage)
	// OnDropped, when set, is called once if the events reader fell
	// MaxBehind or failed, after which it is written nothing more.
	OnDropped func()
}

Options configure Serve.

type Refusal

type Refusal string

Refusal classifies a refused command, the value of Event.Refused.

const (
	// RefusedMalformed: the line is not one JSON object naming exactly one
	// command with its fields, or it is longer than MaxLine.
	RefusedMalformed Refusal = "malformed"
	// RefusedUnknown: the line names a command the protocol does not have.
	RefusedUnknown Refusal = "unknown_command"
	// RefusedBusy: a send arrived while a turn was in flight.
	RefusedBusy Refusal = "busy"
	// RefusedInput: the named file is not a regular file directly in the
	// inputs directory, the session was given no inputs directory, or the
	// session would not take it (a name already staged, unreadable).
	RefusedInput Refusal = "input_refused"
)

type Send

type Send struct {
	Text string `json:"text"`
}

Send is one user turn.

Jump to

Keyboard shortcuts

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