Documentation
¶
Overview ¶
Package oneshot runs one turn from the command line and exits.
A run reaches a controller, opens the session for a workspace, sends one message, and streams the session's frames until that message's turn ends. When no controller is running it starts one inside the process for the run and stops it afterwards; see Connect.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrQuestionUnanswerable = errors.New(
"the agent asked a question and no terminal is attached to answer it",
)
ErrQuestionUnanswerable reports that the agent asked a question while no terminal was attached to answer it, so the run cancelled the turn.
Functions ¶
func NormalizeAgentSpace ¶
NormalizeAgentSpace expands the docker shorthand to docker:default and leaves every other name to the controller to check.
func Run ¶
func Run( ctx context.Context, options Options, ) (controlclient.TurnResult, error)
Run runs one turn and reports how it ended. It returns an error when the run could not reach a controller, open the session, or stream the turn, and ErrQuestionUnanswerable alongside the cancelled result when the agent asked a question nobody could answer.
Types ¶
type ConnectFunc ¶
type ConnectFunc func(ctx context.Context) (Connection, error)
ConnectFunc reaches the controller a run uses.
type Connection ¶
type Connection struct {
Client *controlclient.Client
// Close stops the controller when the run started it and does nothing
// when the run borrowed a running one.
Close func(context.Context) error
}
Connection is the controller a run talks to and how to let it go.
func Connect ¶
func Connect(ctx context.Context) (Connection, error)
Connect uses the controller already answering at PEEN_HTTP_LISTEN_ADDRESS, and leaves it running afterwards. With none answering it starts a controller inside this process that serves its API on an in-memory listener, so it opens no port and nothing outside the process can reach it, and Close stops it.
type Options ¶
type Options struct {
// Workspace is the absolute directory the session works in.
Workspace string
// AgentSpace is where the agent runs: control, docker, or
// docker:<profile>, where docker means docker:default. A new session is
// created in it, and an existing session in another agent space is moved
// to it before the turn. Empty keeps the session's agent space, or the
// controller's default for a new one.
AgentSpace string
// System runs the turn in the system session. Workspace and AgentSpace
// then mean nothing.
System bool
// Message is the turn's message.send data: the prompt and the per-turn
// model, reasoning effort, and system prompt.
Message wsapi.MessageSendData
Output OutputFormat
Stdout io.Writer
Stderr io.Writer
// Answers supplies the user's answer to a question the agent asks, one
// line per answer. Nil means no terminal is attached, and a question
// cancels the turn with ErrQuestionUnanswerable.
Answers io.Reader
// Interrupt receives once for each interrupt. Before the turn starts it
// abandons the run; during the turn it asks the controller to cancel the
// turn, and the run keeps streaming until the controller confirms.
Interrupt <-chan struct{}
// Connect reaches the controller. Nil uses Connect.
Connect ConnectFunc
}
Options configures one run.
type OutputFormat ¶
type OutputFormat string
OutputFormat selects how a run writes the session's frames.
const ( // OutputFormatJSONL writes every frame exactly as the controller sent // it, one JSON object per line, so another program can rebuild the // session's view from it. OutputFormatJSONL OutputFormat = "jsonl" // OutputFormatText writes the reply to stdout and the model's thinking, // tool calls, child agents, and failures to stderr. OutputFormatText OutputFormat = "text" )
func ParseOutputFormat ¶
func ParseOutputFormat(name string) (OutputFormat, error)
ParseOutputFormat validates a format name.