Documentation
¶
Overview ¶
Package harness is the runner's own model loop: it sends a conversation to a model, runs the tool calls the model asks for through the run's one tool gateway, and repeats until the model answers.
The harness has no tool of its own and reaches nothing but the model and the gateway. It reports what it does as events (package proto) and keeps the conversation in an append-only log (package convo), so a process that is started again on the same conversation carries on from what was recorded.
Index ¶
Constants ¶
const ( // ExitAnswered: the turn ended with the model's answer. ExitAnswered = 0 // ExitFailed: a failure ended the turn; an error event says which. ExitFailed = 1 // ExitUsage: the command line, the configuration or the task could // not be used; nothing was sent to the model. ExitUsage = 2 // ExitIncomplete: the turn ended with no whole answer (the answer // stopped at the output limit, or the step limit was reached). ExitIncomplete = 3 )
Exit codes of Run.
Variables ¶
var ErrStopped = errors.New("the turn was stopped")
ErrStopped is the cause a turn's context is cancelled with to stop the turn: the turn then ends as interrupted, with every open call given a result, where any other cancellation ends it as a failure.
Functions ¶
func Run ¶
func Run(ctx context.Context, args []string, stdin io.Reader, stdout, stderr io.Writer, env Env) int
Run is the harness's one-shot mode: one prompt on one conversation, with events on stdout and anything else on stderr.
run --config FILE --conversation ID
Stdin carries the runner's commands, one JSON object a line: first the prompt, then an accept or a continue for each turn_ending event the harness writes. A stdin that ends is an accept: with no one to ask, a turn ends on the model's answer.
A conversation that already exists is carried on: the prompt is added to what was recorded.
func Serve ¶
func Serve(ctx context.Context, args []string, stdin io.Reader, stdout, stderr io.Writer, env Env) int
Serve is the harness's session mode: any number of turns, on a conversation the runner opens, with events on stdout and anything else on stderr.
serve --config FILE
Stdin carries the runner's commands, one JSON object a line. The first is an open, which names the conversation and is answered with a ready event. Each prompt then runs one turn, which ends with a turn_end event; between turns a compact replaces the conversation with a summary of it. While a turn is under way the runner may steer it or interrupt it, and answers the harness's questions: a permit or a deny for each permission event, and an accept or a continue for each turn_ending event. A command that cannot be taken as things stand is answered with a command_refused warning, and the session goes on.
A stdin that ends is the end of the session: a turn under way is stopped, and Serve returns ExitAnswered.
Types ¶
type Harness ¶
type Harness struct {
// Gate, when set, is asked before a turn ends on the model's answer.
// It is called before the turn_ending event is written, and what it
// returns waits for the runner's answer: a message to go on with, or ""
// to end the turn.
Gate func() func(ctx context.Context) (string, error)
// Permit, when set, is asked before a call is offered to the gateway.
// It is called before the permission event is written, and what it
// returns waits for the runner's answer: whether the call may run.
Permit func(callID string) func(ctx context.Context) (bool, error)
// OnTurnEnd, when set, is called just before a turn's turn_end event,
// or the warning that ends a compaction the runner asked for, is
// written: from then on the turn or the compaction does nothing more.
OnTurnEnd func()
// Now is the clock; time.Now unless a test sets another.
Now func() time.Time
// contains filtered or unexported fields
}
Harness runs turns of one conversation.
func (*Harness) Compact ¶
Compact replaces the conversation with a summary of it because the runner asked, between turns. It writes exactly one warning that says how it went, compaction or compaction_failed, with the reason request. On an error the conversation is as it was.
func (*Harness) Prompt ¶
Prompt adds text to the conversation as the runner's message and runs the turn it starts. It returns why the turn ended, one of proto's End constants, having written the turn_end event. The error is non-nil only when the turn ended for a failure, which an error event has reported.
A ctx cancelled with ErrStopped as its cause stops the turn: it ends as interrupted, which is no failure.
func (*Harness) Start ¶
Start opens the conversation, creating it when it does not exist, reads the gateway's tools the first time it is called, and writes the ready event. Called again, between turns, it leaves the conversation it was in for the one named; when that one cannot be opened, it stays where it was.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package convo is a conversation's record: an append-only file of one JSON entry a line, and the messages a model request is built from, which are a pure function of that file.
|
Package convo is a conversation's record: an append-only file of one JSON entry a line, and the messages a model request is built from, which are a pure function of that file. |
|
Package llm is the harness's view of a model: one request in, a stream of pieces and one whole reply out, whatever wire API carries them.
|
Package llm is the harness's view of a model: one request in, a stream of pieces and one whole reply out, whatever wire API carries them. |
|
Package mcp is the harness's client of its one tool source: an MCP server reached over streamable HTTP with a bearer token.
|
Package mcp is the harness's client of its one tool source: an MCP server reached over streamable HTTP with a bearer token. |
|
Package proto is the contract between the runner and its own harness: the configuration the runner renders for a run, and the events the harness writes back, one JSON object a line.
|
Package proto is the contract between the runner and its own harness: the configuration the runner renders for a run, and the events the harness writes back, one JSON object a line. |