Help us shape the future of Go! Take the 2026 Go Developer Survey

headless

package
v0.239.0-rc.8 Latest Latest
Warning

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

 Go to latest Published: Oct 31, 2026 License: Apache-2.0 Imports: 43 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Run 

func Run(cfg *config.Config, opts Options, newServices func() Services) (err error)

Run executes one headless task. newServices builds the composition root; it is called only after the flags validate, so a bad --format or --mode never starts any service.

Types

type Interrupts added in v0.221.0 

type Interrupts interface {
	Note(id, reason string)
	Forget(id string)
}

Interrupts is the registry a run's interrupts are noted under, so the worker answering a resume knows which broker each interrupt belongs to. A nil one belongs to an unattended run, where nothing answers the resume.

type Options 

type Options struct {
	Model           string
	Task            string
	Files           []string
	NoSave          bool
	SessionID       string
	RequireApproval bool
	Heartbeat       bool
	Remote          bool
	ResultFile      string
	Format          string
	Mode            string
	Serve           bool
	KeepAlive       bool
	PromptOnly      bool
}

Options carries the headless command's flag values.

type Panel added in v0.219.0 

type Panel struct {
	// contains filtered or unexported fields
}

Panel answers the panel frames a session worker reads on stdin: listings, model and mode switches, direct tool requests and the conversation snapshot. Each reply is one JSON line on out, one Write per line.

func NewPanel added in v0.219.0 

func NewPanel(deps PanelDeps, out io.Writer) *Panel

NewPanel builds the panel units, one per frame family, each holding only the dependencies it uses.

func (*Panel) Handle added in v0.219.0 

func (p *Panel) Handle(line []byte) bool

Handle answers one stdin line and reports whether the panel consumed it. A run input's messages are recorded in the shell history but left for the turn loop, and an approval_response is consumed only when it answers a tool_request.

type PanelDeps added in v0.219.0 

type PanelDeps struct {
	Conversations convdomain.ConversationRepository
	Skills        agentdomain.SkillsService
	Tools         agentdomain.ToolService
	Approval      agentdomain.ApprovalPolicy
	Models        convdomain.ModelService
	Modes         agentdomain.AgentModeState
	History       storage.ShellHistoryStorage
	Storage       storage.ConversationStorage
	DefaultModel  string
}

PanelDeps are the collaborators the panel units use, all from the worker's own container, so every answer is scoped to the worker's project dir.

type Prompt added in v0.239.0 

type Prompt struct {
	InterruptID string
	Event       agentdomain.ChatEvent
}

Prompt is one interrupt a suspended run waits on, as the event the chat TUI answers on its ResponseChan. Event is nil for an interrupt of an unknown reason, which the client can only cancel.

type Publish added in v0.219.0 

type Publish func(event agentdomain.ChatEvent) (agui.Published, bool)

Publish maps a chat event to the run state or activity its owner publishes for it. It reports false for an event it does not own.

type RunDecoder added in v0.239.0 

type RunDecoder struct {
	// contains filtered or unexported fields
}

RunDecoder turns the AG-UI frames of a thread's runs back into the agent ChatEvents the chat TUI renders, the inverse of RunEncoder. It follows one client request across a suspended run and its continuations, and tolerates attaching mid-run.

func NewRunDecoder added in v0.239.0 

func NewRunDecoder(requestID string) *RunDecoder

NewRunDecoder builds the decoder for the client request requestID, the id every decoded event carries.

func (*RunDecoder) Decode added in v0.239.0 

func (d *RunDecoder) Decode(frame []byte) ([]agentdomain.ChatEvent, RunEnd)

Decode turns one frame into the events it stands for and reports where it leaves the run. Frames outside a run's vocabulary decode to nothing.

func (*RunDecoder) Prompts added in v0.239.0 

func (d *RunDecoder) Prompts() []Prompt

Prompts are the interrupts the run suspended on, valid after Decode reported RunSuspended.

type RunEncoder added in v0.219.0 

type RunEncoder struct {
	// contains filtered or unexported fields
}

RunEncoder renders one agent run on the AG-UI protocol: it maps each ChatEvent to the AG-UI events of the run it writes, and an approval or a question suspends the run with the interrupt outcome and continues on the run the answer opens.

func NewRunEncoder added in v0.219.0 

func NewRunEncoder(w io.Writer, deps RunEncoderDeps) *RunEncoder

NewRunEncoder builds the encoder for one run over w. History, when non-empty, is emitted as MESSAGES_SNAPSHOT right after RUN_STARTED, so the run continues an existing conversation. Approvals and questions broker IPC decisions for gated tool calls and questions (nil channels reject or dismiss immediately). Startup drains the boot progress the run opens with, and Interrupt notes the interrupts the run raises so resume entries find their broker.

func (*RunEncoder) AcceptedPlan added in v0.239.0 

func (r *RunEncoder) AcceptedPlan() (string, bool)

AcceptedPlan reports the plan the user accepted during the run, which the caller executes in a fresh session.

func (*RunEncoder) Finish added in v0.219.0 

func (r *RunEncoder) Finish() error

Finish writes the current run's one terminal event, RUN_FINISHED carrying the usage and the session extras or the failure the run ended with. It returns the run error for the caller's exit code and telemetry.

func (*RunEncoder) Handle added in v0.219.0 

func (r *RunEncoder) Handle(event agentdomain.ChatEvent)

Handle renders one agent ChatEvent into the run's AG-UI stream.

func (*RunEncoder) Start added in v0.219.0 

func (r *RunEncoder) Start(threadID, runID string)

Start frames the run: RUN_STARTED, the MESSAGES_SNAPSHOT of the restored history when the run continues an existing conversation, and the boot progress recorded before the run opened.

type RunEncoderDeps added in v0.221.0 

type RunEncoderDeps struct {
	Model     string
	Repo      convdomain.ConversationRepository
	History   []convdomain.ConversationEntry
	Jobs      func() []scheddomain.TrackedJob
	Approvals <-chan ipc.ApprovalResponse
	Questions <-chan ipc.UserQuestionResponse
	Plans     <-chan ipc.PlanApprovalResponse
	Modes     agentdomain.AgentModeState
	Startup   *startupNotes
	Interrupt Interrupts
	Publish   []Publish
}

RunEncoderDeps are the collaborators of one run's encoder.

type RunEnd added in v0.239.0 

type RunEnd int

RunEnd is where a decoded frame leaves the run a RunDecoder follows. 

const (
	RunOpen RunEnd = iota
	RunResumed
	RunSuspended
	RunFinished
	RunCancelled
	RunFailed
)

type Services added in v0.207.0 

type Services interface {
	RouteBrowserRequests(request func(ctx context.Context, id string, frame json.RawMessage) (json.RawMessage, error))
	SetUINotifier(n agentdomain.UINotifier)
	Shutdown(ctx context.Context) error
	StartScreenshotServer(sessionID string) *computerinfra.ScreenshotServer
	GetGatewaySupervisor() *gateway.Supervisor
	GetAgentSupervisor() a2adomain.AgentSupervisor
	GetAgentService() agentdomain.AgentService
	GetMCPSupervisor() mcpdomain.Supervisor
	GetToolRegistry() *tools.Registry
	GetToolService() agentdomain.ToolService
	GetFileService() agentdomain.FileService
	GetImageService() agentdomain.ImageService
	GetModelService() convdomain.ModelService
	GetConversationRepository() convdomain.ConversationRepository
	GetMessageQueue() convdomain.MessageQueue
	GetSessionRollover() convdomain.SessionRollover
	GetStateStore() *statemanager.Store
	GetShortcutRegistry() *shortcuts.Registry
	GetBackgroundTaskRegistry() scheddomain.BackgroundTaskRegistry
	GetTelemetryRecorder() *telemetry.Recorder
	NewPanel(out io.Writer) *Panel
}

Services is the slice of the composition root a headless run uses. cmd/headless supplies the *container.ServiceContainer.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.