headless

package
v0.70.2 Latest Latest
Warning

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

 Go to latest Published: Jul 24, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package headless drives a Claude Code agent in headless stream-json mode (`claude -p --output-format stream-json`) instead of an interactive PTY. It parses the typed event stream for status and the terminal result cost/usage envelope. See docs/design/2026-07-13-headless-stream-json-design.md (#1075).

v1 runs the one-shot control-channel form: `claude -p --output-format stream-json --input-format stream-json --verbose`. The prompt is delivered as an initial stdin user message (not a positional arg), and stdin stays open so graith can issue an `interrupt` control request. Graith does not request or service native approvals; an unexpected inbound `can_use_tool` request is diagnosed and denied immediately because headless mode has no agent TUI. Stdin closes on the terminal `result` so the process exits, preserving one-shot semantics. See issue #1136 (Phase 4).

The control protocol is an SDK-internal contract, not a documented CLI API, so everything is written defensively (unknown message types ignored, malformed data lines skipped) and the whole feature is gated behind an experimental flag by the daemon. The wire shapes here are pinned to the forms empirically verified against claude 2.1.211 — notably the *asymmetric* request-id placement (see below).

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Opts 

type Opts struct {
	ID         string
	Command    string
	Args       []string
	Dir        string
	Env        map[string]string
	LogPath    string
	MaxLogSize int64

	// Processing limits (issue #1250). Each is optional: a zero/non-positive
	// value falls back to the matching package default, so direct callers and
	// tests that leave them unset keep the historical behaviour.
	//
	// MaxLineBytes bounds a single stream-json line read from stdout.
	// ControlTimeout bounds a synchronous control request round-trip.
	// InterruptTimeout bounds the interrupt control round-trip.
	// PreviewBytes bounds the scrollback tail rendered by the preview/snapshot.
	MaxLineBytes     int
	ControlTimeout   time.Duration
	InterruptTimeout time.Duration
	PreviewBytes     int

	// Prompt is the initial turn, sent as a stream-json user message on stdin
	// right after launch (the control-channel launch takes no positional
	// prompt). It should be non-empty: with the control channel and no
	// positional prompt, an empty prompt gives the CLI no turn to run, so it
	// blocks on stdin and never reaches a result (the daemon guards against this
	// at session creation).
	Prompt string

	// Control reports whether the process was launched with the stdin control
	// channel (`--input-format stream-json`). When true, Interrupt issues an
	// `interrupt` control request and stdin is closed on the terminal result so
	// the one-shot process exits; when false, Interrupt falls back to SIGINT.
	Control bool
}

Opts configures a headless session launch. It mirrors the fields pty.SessionOpts needs, plus the initial prompt.

type ResultEnvelope 

type ResultEnvelope struct {
	IsError     bool            `json:"is_error"`
	TotalCost   float64         `json:"total_cost_usd"`
	NumTurns    int             `json:"num_turns"`
	DurationMS  int64           `json:"duration_ms"`
	DurationAPI int64           `json:"duration_api_ms"`
	Usage       json.RawMessage `json:"usage"`
	Text        string          `json:"result"`
	At          time.Time       `json:"-"`
}

ResultEnvelope is the terminal `result` message: the structured cost/usage summary the design feeds into token accounting (#644). A one-shot headless session emits exactly one of these.

type Session 

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

Session is a headless stream-json agent process. It satisfies the daemon's SessionDriver surface so the session manager can hold it interchangeably with a *pty.Session.

func New 

func New(opts Opts) (*Session, error)

New launches a headless session: starts the process with piped stdin/stdout/stderr and starts the read/stderr/wait goroutines. It returns an error if the process fails to start. (v1 one-shot mode does not perform an initialize handshake — that belongs to the deferred bidirectional control phase.)

func (*Session) Attach 

func (s *Session) Attach(w io.Writer)

func (*Session) BytesRead 

func (s *Session) BytesRead() int64

BytesRead reports total stream-json output bytes consumed this session.

func (*Session) Close 

func (s *Session) Close()

func (*Session) ContextUsage 

func (s *Session) ContextUsage() (json.RawMessage, error)

ContextUsage issues a get_context_usage control request and returns the raw response payload.

func (*Session) CreatedAt 

func (s *Session) CreatedAt() time.Time

CreatedAt returns when this headless session was launched.

func (*Session) Detach 

func (s *Session) Detach()

func (*Session) DetachWriter 

func (s *Session) DetachWriter(w io.Writer)

func (*Session) Done 

func (s *Session) Done() <-chan struct{}

func (*Session) ExitCode 

func (s *Session) ExitCode() int

func (*Session) ExitSignal 

func (s *Session) ExitSignal() syscall.Signal

func (*Session) Exited 

func (s *Session) Exited() bool

func (*Session) ForceKill 

func (s *Session) ForceKill() error

func (*Session) Interrupt 

func (s *Session) Interrupt(_ int, _ time.Duration) error

Interrupt interrupts the running agent. With the control channel enabled it issues an `interrupt` control request (clean, acknowledged), falling back to a SIGINT to the process group if the control round-trip fails (channel wedged, timed out, or process already exited). Without the control channel it sends SIGINT directly. The count/delay arguments exist only for SessionDriver compatibility (the control interrupt is a single acknowledged request).

func (*Session) Kill 

func (s *Session) Kill() error

func (*Session) LastOutputAt 

func (s *Session) LastOutputAt() time.Time

func (*Session) PeakRSSBytes 

func (s *Session) PeakRSSBytes() int64

PeakRSSBytes is not tracked for headless sessions.

func (*Session) Pgid 

func (s *Session) Pgid() int

Pgid returns the process-group id graith signals on Kill/ForceKill. Like *pty.Session, a headless session is started with Setsid, so the child is a group leader and its PGID equals its PID. Returns 0 when the pid is unknown. Part of the SessionDriver interface (issue #1104).

func (*Session) ProcessPID 

func (s *Session) ProcessPID() int

func (*Session) RecentlyAdopted 

func (s *Session) RecentlyAdopted(time.Duration) bool

RecentlyAdopted is always false: headless sessions are not adopted across daemon restart (their stdout pipe can't be re-read); the daemon resumes them.

func (*Session) ScreenPreview 

func (s *Session) ScreenPreview() string

ScreenPreview returns a plain-text tail of the rendered scrollback. A headless session has no terminal screen emulator, so the overlay preview and the screen_preview control message degrade to the recent rendered output.

func (*Session) ScreenSnapshot 

func (s *Session) ScreenSnapshot() grpty.ScreenCapture

ScreenSnapshot returns a ScreenCapture whose Frame is the scrollback tail, so callers expecting a PTY snapshot get something sensible for a headless session.

func (*Session) ScrollbackFile 

func (s *Session) ScrollbackFile() *grpty.Scrollback

func (*Session) Snapshot 

func (s *Session) Snapshot() Snapshot

Snapshot returns the current structured status + last result envelope.

func (*Session) WasAdopted 

func (s *Session) WasAdopted() bool

WasAdopted is always false: headless sessions are not adopted across daemon restart (their stdout pipe can't be re-read).

func (*Session) WriteInput 

func (s *Session) WriteInput(data []byte) error

WriteInput sends the bytes as a stream-json user message (a new turn).

func (*Session) WriteInputAndSubmit 

func (s *Session) WriteInputAndSubmit(data []byte) error

WriteInputAndSubmit is identical to WriteInput for headless: a user message is a complete, submitted turn (there is no separate submit key).

type Snapshot 

type Snapshot struct {
	Status   Status
	ToolName string
	Result   *ResultEnvelope
	Degraded bool // reader hit malformed control frames / decode failures
}

Snapshot is the structured status the daemon reads off a headless driver in place of PTY scraping.

type Status 

type Status string

Status is the coarse agent status graith tracks, mirroring the strings the detector/hook path uses so the daemon can treat headless and PTY sessions uniformly. 

const (
	StatusActive  Status = "active"
	StatusReady   Status = "ready"
	StatusStopped Status = "stopped"
)

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.