harness

package
v0.7.57-dev.1 Latest Latest
Warning

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

Go to latest
Published: Nov 12, 2026 License: MIT Imports: 24 Imported by: 0

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

View Source
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

View Source
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 Env

type Env func(name string) string

Env reads the process's environment. It is a parameter so a test can supply one.

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 New

func New(cfg proto.Config, model llm.Client, src ToolSource, out io.Writer) *Harness

New makes a harness that writes its events to out.

func (*Harness) Close

func (h *Harness) Close() error

Close closes the conversation's log.

func (*Harness) Compact

func (h *Harness) Compact(ctx context.Context) error

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

func (h *Harness) Prompt(ctx context.Context, text string) (string, error)

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

func (h *Harness) Start(ctx context.Context, conversation string) error

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.

func (*Harness) Steer

func (h *Harness) Steer(text string)

Steer hands the harness a message of the runner's for the conversation. A turn under way takes it after the results of the calls it is running, or when the model next answers with no call; with no turn under way it goes ahead of the next prompt. It may be called at any time.

type ToolSource

type ToolSource interface {
	Initialize(ctx context.Context) error
	ListTools(ctx context.Context) ([]mcp.Tool, error)
	CallTool(ctx context.Context, name string, arguments json.RawMessage) (*mcp.Result, error)
}

ToolSource is where the tools come from. *mcp.Client is one.

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.

Jump to

Keyboard shortcuts

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