oneshot

package
v0.45.2 Latest Latest
Warning

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

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

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

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

func NormalizeAgentSpace(name string) string

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.

Jump to

Keyboard shortcuts

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