proto

package
v0.7.58-dev.4 Latest Latest
Warning

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

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

Documentation

Overview

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.

Both sides compile this package, so a field one side writes is a field the other reads. Version moves when a field changes meaning or goes away.

Index

Constants

View Source
const (
	// APIAnthropic is the Anthropic Messages API.
	APIAnthropic = "anthropic"
	// APIChat is OpenAI-style Chat Completions, as OpenAI-compatible
	// servers speak it.
	APIChat = "chat-completions"
	// APIResponses is the OpenAI Responses API.
	APIResponses = "openai-responses"
	// APIGemini is the Gemini API's generateContent.
	APIGemini = "gemini"
)

Wire APIs a model is reached by.

View Source
const (
	// TypeReady is the first event: the harness has read its
	// configuration and the gateway's tools.
	TypeReady = "ready"
	// TypeText is a piece of the model's answer.
	TypeText = "text"
	// TypeReasoning is a piece of the model's reasoning.
	TypeReasoning = "reasoning"
	// TypeToolCall says the harness is about to run a call.
	TypeToolCall = "tool_call"
	// TypeToolResult is a call's result.
	TypeToolResult = "tool_result"
	// TypeUsage is one model request's token count.
	TypeUsage = "usage"
	// TypeWarning is something the harness did that the runner counts.
	TypeWarning = "warning"
	// TypeError is a failure, with its class.
	TypeError = "error"
	// TypeTurnEnding says the model answered with no call left to run, and
	// asks the runner whether the turn ends there. The harness waits for
	// the runner's accept or continue command.
	TypeTurnEnding = "turn_ending"
	// TypeTurnEnd closes a prompt. Every prompt gets exactly one.
	TypeTurnEnd = "turn_end"
	// TypePermission asks the runner whether a call may run, in a session.
	// CallID and Tool name the call. The harness waits for the runner's
	// permit or deny command.
	TypePermission = "permission"
	// TypeSteered says messages the runner sent while a turn was under way,
	// or between turns, are now part of the conversation. Count is how many.
	TypeSteered = "steered"
)

Event types.

View Source
const (
	// WarnLoopNudge: the model repeated a call and was told to reach its
	// goal another way. Tool names the call, Count how often it repeated.
	WarnLoopNudge = "loop_nudge"
	// WarnLengthRecovery: a reply cut off at the output limit was taken out
	// of what the model is sent, and the model was told. Reason is what was
	// cut, one of the Cut constants.
	WarnLengthRecovery = "length_recovery"
	// WarnColdClear: old tool results were replaced by placeholders. Count
	// is how many.
	WarnColdClear = "cold_clear"
	// WarnCompaction: the conversation was replaced by a summary. Reason is
	// why, one of the Compaction constants.
	WarnCompaction = "compaction"
	// WarnCompactionFailed: a summary could not be made, and the
	// conversation was left as it was. Reason is why one was wanted.
	WarnCompactionFailed = "compaction_failed"
	// WarnRetry: a model request failed and is sent again. Class is the
	// failure's, Count the attempt.
	WarnRetry = "retry"
	// WarnCommandRefused: a command of the runner's could not be taken as
	// things stood (a prompt while a turn is under way, an answer to nothing
	// asked). Reason is the command's type. The session goes on.
	WarnCommandRefused = "command_refused"
)

Codes of warning.

View Source
const (
	CutAnswer    = "answer"
	CutReasoning = "reasoning"
	CutToolCall  = "tool call"
)

What the output limit cut off (a length_recovery warning's reason).

View Source
const (
	// CompactionThreshold: it reached the configured share of the window.
	CompactionThreshold = "threshold"
	// CompactionOverflow: the server refused it as too long.
	CompactionOverflow = "overflow"
	// CompactionRequest: the runner asked for it with a compact command.
	CompactionRequest = "request"
)

Why a conversation was summarised (a compaction warning's reason).

View Source
const (
	// CmdPrompt starts a turn with Text as the runner's message.
	CmdPrompt = "prompt"
	// CmdAccept answers turn_ending: the turn ends.
	CmdAccept = "accept"
	// CmdContinue answers turn_ending: the turn goes on, with Text as a
	// message to the model.
	CmdContinue = "continue"

	// CmdOpen opens the conversation named Conversation, creating it when
	// there is none, and is answered with a ready event or an error. It is
	// taken between turns only. A session's first command is an open.
	CmdOpen = "open"
	// CmdSteer adds Text to the conversation as the runner's message while
	// a turn is under way: after the results of the calls being run, or
	// when the model next answers with no call. Between turns it is kept
	// and goes ahead of the next prompt.
	CmdSteer = "steer"
	// CmdInterrupt stops the turn under way. Every call left open is given
	// a result that says so, and the turn ends as interrupted. With no turn
	// under way it does nothing.
	CmdInterrupt = "interrupt"
	// CmdPermit and CmdDeny answer a permission event for the call CallID
	// names. A denied call is not run: the denial is its result, and the
	// turn goes on.
	CmdPermit = "permit"
	CmdDeny   = "deny"
	// CmdCompact replaces the open conversation with a summary of it,
	// between turns. It is answered with a compaction warning whose reason
	// is request, or, when no summary was made and the conversation is as
	// it was, with a compaction_failed warning of that reason. An interrupt
	// gives it up.
	CmdCompact = "compact"
)

Commands the runner writes to the harness, one JSON object a line.

View Source
const (
	// EndAnswered: the model answered with no call left to run.
	EndAnswered = "answered"
	// EndAnswerCut: the model's answer stopped at the output limit.
	EndAnswerCut = "answer_cut"
	// EndError: a failure ended the turn; an error event precedes it.
	EndError = "error"
	// EndMaxSteps: the configuration's step limit was reached.
	EndMaxSteps = "max_steps"
	// EndInterrupted: the runner stopped the turn. Text is what the model
	// had written of the reply it was stopped in.
	EndInterrupted = "interrupted"
)

Why a turn ended.

View Source
const (
	// ClassOverflow: the server refused the conversation as too long.
	ClassOverflow = "overflow"
	// ClassCapacity: the server is overloaded or unavailable.
	ClassCapacity = "capacity"
	// ClassRateLimit: the server asked the client to slow down.
	ClassRateLimit = "rate_limit"
	// ClassCredits: the account that pays has nothing left.
	ClassCredits = "credits"
	// ClassAuth: the server refused the key.
	ClassAuth = "auth"
	// ClassRequest: the server refused the request as malformed.
	ClassRequest = "request"
	// ClassTransport: the connection failed or the stream broke.
	ClassTransport = "transport"
	// ClassServer: any other failure of the model's server.
	ClassServer = "server"
	// ClassGateway: the tool gateway could not be reached or refused.
	ClassGateway = "gateway"
	// ClassHarness: a fault of the harness's own.
	ClassHarness = "harness"
)

Classes of error.

View Source
const MinResultBytes = 1024

MinResultBytes is the least results.maxBytes may be: room for the notice and a useful start of the result.

View Source
const Version = 2

Version is the contract's version. A harness refuses a configuration of another version, and stamps its own on every event.

Variables

This section is empty.

Functions

This section is empty.

Types

type ColdClear

type ColdClear struct {
	// AfterSeconds is how long the server's cache of a conversation lives.
	AfterSeconds int `json:"afterSeconds"`
	// KeepTurns is how many turns before the current one keep their
	// results, and KeepBrowser how many of the newest results of
	// BrowserTools stay wherever they fall.
	KeepTurns    int      `json:"keepTurns"`
	KeepBrowser  int      `json:"keepBrowser"`
	BrowserTools []string `json:"browserTools,omitempty"`
	// MinBytes is the smallest result worth clearing: a shorter one stays
	// where it is, since its placeholder would save next to nothing and the
	// replies written with it would be left with no sign of what they rest
	// on. A result of BrowserTools goes whatever its size, because it is
	// out of date; so does one that carries an image.
	MinBytes int `json:"minBytes,omitempty"`
}

ColdClear is the clearing of old tool results. It is done on a turn's first request, and only when the last reply is older than AfterSeconds: the server then reads the whole conversation afresh whatever it holds.

type Command

type Command struct {
	Type string `json:"type"`
	Text string `json:"text,omitempty"`
	// Conversation is the id of the conversation to open (open).
	Conversation string `json:"conversation,omitempty"`
	// CallID names the call a permit or a deny answers.
	CallID string `json:"callId,omitempty"`
}

Command is one line the runner writes.

type Compaction

type Compaction struct {
	// Threshold is the share of the model's window at which the
	// conversation is summarised, above 0 and below 1. With no window in
	// the configuration, the one a server's refusal states, or the size it
	// refused, is used once there has been a refusal.
	Threshold float64 `json:"threshold"`
	// Checkpoint is what the summary must keep, in the runner's words.
	Checkpoint string `json:"checkpoint,omitempty"`
	// Notes names where the agent keeps its notes, as the summary's last
	// sentence says it to the agent. One line.
	Notes string `json:"notes,omitempty"`
}

Compaction is when and how a conversation is replaced by a summary.

type Config

type Config struct {
	Version int   `json:"version"`
	Model   Model `json:"model"`
	// System is the system prompt.
	System  string  `json:"system"`
	Gateway Gateway `json:"gateway"`
	// SessionDir is the folder that holds one log file a conversation.
	SessionDir string `json:"sessionDir"`
	// MaxSteps ends a turn after this many model requests. Zero is no
	// limit of the harness's own; the runner's budgets still apply.
	MaxSteps int `json:"maxSteps,omitempty"`

	// Results bounds what one tool result may hold.
	Results *Results `json:"results,omitempty"`
	// Scrub removes secret-shaped values from tool arguments and results.
	Scrub *Scrub `json:"scrub,omitempty"`
	// Loop answers a repeated call with a message to the model.
	Loop *Loop `json:"loop,omitempty"`
	// LengthRecoveries is how many replies cut off at the output limit one
	// turn goes on from. Zero ends the turn at the first.
	LengthRecoveries int `json:"lengthRecoveries,omitempty"`
	// ColdClear replaces old tool results once the server's cache of the
	// conversation has expired.
	ColdClear *ColdClear `json:"coldClear,omitempty"`
	// Compaction replaces a conversation that nears the model's window, or
	// that the server refused as too long, with a summary of it.
	Compaction *Compaction `json:"compaction,omitempty"`
	// Retry sends a model request again after a failure that may pass.
	Retry *Retry `json:"retry,omitempty"`
}

Config is everything the harness is told about a run. It names where secrets are found and never holds one.

func DecodeConfig

func DecodeConfig(r io.Reader) (Config, error)

DecodeConfig reads a configuration strictly: an unknown field, a second document or another version is an error.

func (Config) Encode

func (c Config) Encode() ([]byte, error)

Encode renders a configuration as the bytes the harness reads. The same configuration always renders to the same bytes.

type Event

type Event struct {
	// V is the contract's version.
	V int `json:"v"`
	// Seq numbers the events of one process from 1, with no gap.
	Seq int64 `json:"seq"`
	// Type is one of the Type constants.
	Type string `json:"type"`

	// Text is a piece of the answer (text) or of the reasoning
	// (reasoning), a tool's output (tool_result), the words of a warning
	// or an error, or the whole final answer (turn_end).
	Text string `json:"text,omitempty"`

	// CallID, Tool and Arguments describe a call (tool_call); CallID and
	// Tool name the call a result answers (tool_result) or the call the
	// runner is asked about (permission).
	CallID    string          `json:"callId,omitempty"`
	Tool      string          `json:"tool,omitempty"`
	Arguments json.RawMessage `json:"arguments,omitempty"`
	// Failed marks a result whose tool reported an error, or that the
	// harness wrote because the call was not run.
	Failed bool `json:"failed,omitempty"`
	// Unchanged marks a result that held content passed to the model as
	// the tool sent it and left out of Text.
	Unchanged bool `json:"unchanged,omitempty"`

	// Usage is set on a usage event. On the ready event of a conversation
	// that already held a message it says where the conversation stands:
	// its size, the model's window and what it has cost.
	Usage *Usage `json:"usage,omitempty"`

	// Code names a warning, one of the Warn constants. Count is the figure
	// the code's comment gives it, or how many messages a steered event
	// counts.
	Code  string `json:"code,omitempty"`
	Count int    `json:"count,omitempty"`
	// Class is an error's class, one of the Class constants. Status is
	// the HTTP status the server answered with, zero when there was none.
	// RetryAfterSeconds is the wait the server asked for.
	Class             string `json:"class,omitempty"`
	Status            int    `json:"status,omitempty"`
	RetryAfterSeconds int    `json:"retryAfterSeconds,omitempty"`

	// Reason says why a turn ended, one of the End constants, or what a
	// warning's code says it is.
	Reason string `json:"reason,omitempty"`
	// Conversation is the id of the conversation (ready, turn_end).
	Conversation string `json:"conversation,omitempty"`
	// Continued says the conversation already held a message when it was
	// opened (ready).
	Continued bool `json:"continued,omitempty"`
	// Tools is the names of the tools the model is offered (ready).
	Tools []string `json:"tools,omitempty"`
}

Event is one line the harness writes. Type says which fields are set.

type Gateway

type Gateway struct {
	URL string `json:"url"`
	// TokenEnv names the environment variable that holds the bearer.
	TokenEnv string `json:"tokenEnv"`
}

Gateway is the one source of tools: an MCP server over streamable HTTP.

type Loop

type Loop struct {
	// Repeats is how many times in a row the same call, with the same
	// arguments, is made before the message.
	Repeats int `json:"repeats"`
	// CycleRepeats is how many times in a row the same sequence of two to
	// MaxPeriod calls is made before the message. Zero looks for no
	// sequence.
	CycleRepeats int `json:"cycleRepeats,omitempty"`
	MaxPeriod    int `json:"maxPeriod,omitempty"`
}

Loop is when a repeated call is answered with a message.

type Model

type Model struct {
	// API is the wire API, one of the API constants.
	API string `json:"api"`
	// Name is the model's id as its server knows it.
	Name string `json:"name"`
	// BaseURL is the server's address with no trailing slash. Empty is
	// the API's own.
	BaseURL string `json:"baseUrl,omitempty"`
	// KeyEnv names the environment variable that holds the key. Empty is
	// a server that takes none, which only Chat Completions allows.
	KeyEnv string `json:"keyEnv,omitempty"`
	// MaxOutputTokens is the most output asked of one request. Zero leaves
	// the limit to the server, which the Anthropic API does not allow.
	MaxOutputTokens int `json:"maxOutputTokens,omitempty"`
	// ContextWindow is the model's window in tokens, zero when unknown.
	ContextWindow int `json:"contextWindow,omitempty"`
	// Sampling is sent with every request; a field left out is the
	// server's own default. Chat Completions only.
	Sampling *Sampling `json:"sampling,omitempty"`
	// ExtraBody is a JSON object whose members are added to every
	// request's body as they are (a server's own switches, such as its
	// chat template's arguments). Chat Completions only.
	ExtraBody json.RawMessage `json:"extraBody,omitempty"`
	// ReplayReasoning sends the model's earlier reasoning back with each
	// assistant message, for a model whose template expects it. Chat
	// Completions only; the Anthropic API always takes its own back.
	ReplayReasoning bool `json:"replayReasoning,omitempty"`
	// Prices is what the model's provider charges, when the runner knows.
	// With it the harness reports what the conversation has cost.
	Prices *Prices `json:"prices,omitempty"`
}

Model says how the model is reached.

type Prices

type Prices struct {
	// Input is input the server reads fresh, CacheRead input it reads
	// from its cache, CacheWrite input it writes to it.
	Input      float64 `json:"input"`
	CacheRead  float64 `json:"cacheRead"`
	CacheWrite float64 `json:"cacheWrite"`
	// Output is output, reasoning included.
	Output float64 `json:"output"`
}

Prices is a model's prices in US dollars a million tokens.

type Results

type Results struct {
	// MaxBytes is the most text one result may hold. A longer one keeps its
	// start, cut at a line where it can be, and ends with a notice that says
	// how much was left out.
	MaxBytes int `json:"maxBytes"`
}

Results is the result policy.

type Retry

type Retry struct {
	// Attempts is how many times a failed request is sent again.
	Attempts int `json:"attempts"`
	// BaseSeconds is the wait before the first of them; each later wait is
	// twice the one before, and none is longer than MaxSeconds. A wait the
	// server asks for is kept instead when it is no longer than MaxSeconds;
	// a longer one ends the retries.
	BaseSeconds int `json:"baseSeconds"`
	MaxSeconds  int `json:"maxSeconds"`
	// IdleSeconds ends a request whose reply has sent nothing for this
	// long, as a failure of the connection. Zero sets no limit.
	IdleSeconds int `json:"idleSeconds,omitempty"`
}

Retry is the retry policy of a model request.

type Sampling

type Sampling struct {
	Temperature       *float64 `json:"temperature,omitempty"`
	TopP              *float64 `json:"topP,omitempty"`
	TopK              *int64   `json:"topK,omitempty"`
	MinP              *float64 `json:"minP,omitempty"`
	PresencePenalty   *float64 `json:"presencePenalty,omitempty"`
	RepetitionPenalty *float64 `json:"repetitionPenalty,omitempty"`
}

Sampling is the sampling a model is asked to use.

type Scrub

type Scrub struct {
	// Unchanged names the tools whose results are passed on as they are:
	// the ones that return the person's own inputs.
	Unchanged []string `json:"unchanged,omitempty"`
}

Scrub is the secret scrub. Every call's arguments are scrubbed before the tool is given them, and every tool's result before the model is.

type Usage

type Usage struct {
	// Input is the input the server read fresh, CacheRead what it read
	// from its cache, CacheWrite what it wrote to it. The three do not
	// overlap; their sum is the size of the request.
	Input      int64 `json:"input"`
	CacheRead  int64 `json:"cacheRead"`
	CacheWrite int64 `json:"cacheWrite"`
	// Output is the output, reasoning included.
	Output int64 `json:"output"`
	// ContextTokens is the size of the conversation as of this request:
	// its input, cached or not. ContextLimit is the model's window, zero
	// when the configuration gave none.
	ContextTokens int64 `json:"contextTokens"`
	ContextLimit  int64 `json:"contextLimit,omitempty"`
	// Compacted marks the request that wrote a summary the conversation was
	// then replaced by. ContextTokens is then an estimate of the
	// conversation's size after it.
	Compacted bool `json:"compacted,omitempty"`
	// CostUSD is what the whole conversation has cost so far, this request
	// included, at the configuration's prices; absent when it gave none.
	// It is a running total of the conversation, not of the process: a
	// harness started again on a conversation goes on from what the
	// earlier requests cost.
	CostUSD float64 `json:"costUsd,omitempty"`
}

Usage is the token count of one model request.

Jump to

Keyboard shortcuts

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