driver

type Agent ¶

type Agent interface {
	Spawn(context.Context, Turn) (Stream, error)
}

Agent starts one turn with a foreign agent.

type Closer ¶

type Closer interface {
	Close() error
}

Closer is optionally implemented by agents that own long-lived resources spanning turns. The backend invokes Close exactly once after the command pump exits, whether it exits from command.Shutdown or loop-context cancellation. Drivers that spawn a new CLI process per turn do not need to implement Closer.

type DecodeError ¶

type DecodeError struct{ Cause error }

DecodeError reports that a foreign-agent stream could not be decoded.

func (e *DecodeError) Error() string

func (e *DecodeError) Unwrap() error

type Event ¶

type Event struct {
	Kind          Kind
	SessionID     string
	Text          string
	ToolUseID     string
	ToolName      string
	IsError       bool
	ResultPreview string
	Message       *content.AIMessage
	ErrText       string
}

Event is the normalized event union emitted by a Stream.

type ExitError ¶

type ExitError struct{ Code int }

ExitError reports a non-successful foreign-agent process exit.

func (e *ExitError) Error() string

type History ¶

type History struct {
	Available bool
	Steps     []content.AgenticMessages
}

History is the complete authoritative history available from a Stream.

type HistoryError ¶

type HistoryError struct{ Cause error }

HistoryError reports that authoritative history could not be read or decoded.

func (e *HistoryError) Error() string

func (e *HistoryError) Unwrap() error

type Kind ¶

type Kind uint8

Kind identifies a normalized foreign-agent event.

const (
	KindInit Kind = iota
	KindTextDelta
	KindThinkingDelta
	KindToolUse
	KindToolResult
	KindStepComplete
	KindTerminalOK
	KindTerminalError
	// KindModelFacingError carries a bounded, sanitized protocol failure that
	// is safe to expose to the model. Keeping it distinct from KindTerminalError
	// prevents ordinary provider failures from becoming model-facing.
	KindModelFacingError
)

type Observation ¶

type Observation interface {
	Kind() ObservationKind
	Sequence() uint64
	// contains filtered or unexported methods
}

Observation is the ordered, provider-neutral view consumed by a backend. Implementations are sealed so adapters cannot inject observations that do not carry one of the normalized payloads below.

type ObservationKind ¶

type ObservationKind uint8

ObservationKind identifies the normalized observation family in an ordered stream. The values correspond to ACP prompt completion, session update, and steering response observations.

const (
	ObservationPrompt ObservationKind = iota
	ObservationUpdate
	ObservationSteer
)

func (k ObservationKind) Valid() bool

type OrderedStream ¶

type OrderedStream interface {
	// Observations returns the stream-owned ordered projection. A stream selects
	// exactly one projection before production starts: legacy Events or this
	// channel. The inactive projection is closed and carries no traffic.
	Observations() <-chan Observation
}

OrderedStream is an optional stream capability. It does not replace the existing Stream.Events channel: legacy consumers may continue to consume normalized Event values, while a steering-aware backend type-asserts OrderedStream and consumes one observation channel as its authoritative prompt/update/steer order.

The observation channel is owned by the stream implementation. It is read only by consumers and is closed exactly once after the stream has finished producing observations; consumers must not close it. Stream.Close remains the lifecycle operation and remains idempotent. Every Steerer.Steer call produces exactly one SteerObservation for every call accepted by the steering actor, including accepted calls ending in a typed error or a pre-admission result. A call rejected before actor admission (for example by a bounded reservation lane) produces no observation. A producer emits observations in nondecreasing ReceiveSequence order. Multiple translated observations may share one receive sequence; their channel order is the tie-breaker and consumers must not reorder equal-sequence observations. Sequence reports an effective order key: raw ReceiveSequence is preserved for protocol facts, while observations without transport sequence receive a strictly increasing adapter-owned key.

type PermissionPosture ¶

type PermissionPosture uint8

PermissionPosture is the typed, non-interactive permission mode passed to an agent.

const (
	PostureDefault PermissionPosture = iota
	PostureAcceptEdits
)

type Posture ¶

type Posture string

Posture is a neutral, secret-free access posture translated by each harness driver. PostureReadOnly permits reads, searches, and non-mutating command execution only; mutation and network access are denied by configuration and the permission handler. PostureWorkspaceWrite permits workspace file mutation and commands inside the session workspace.

const (
	PostureReadOnly       Posture = "read-only"
	PostureWorkspaceWrite Posture = "workspace-write"
)

func (p Posture) Valid() bool

type PromptObservation ¶

type PromptObservation struct {
	// StopReason is an adapter-normalized stop classification. It remains a
	// string at this provider-neutral boundary because concrete ACP stop
	// vocabularies do not belong in driver contracts.
	StopReason string
	// Message is the assembled assistant transcript for this prompt, when the
	// adapter has one. Keeping it on the prompt observation lets ordered
	// consumers commit the final answer without a second legacy event path.
	Message          *content.AIMessage
	WriteAdmitted    bool
	ReceiveSequence  uint64
	ResponseSequence uint64
	OrderSequence    uint64
	Err              error
}

PromptObservation is one normalized prompt completion. It mirrors ACP's PromptResult transport facts while leaving provider stop-reason vocabulary at the adapter boundary. Err is bounded/typed by the adapter when a prompt completion failed before a result was available.

func (PromptObservation) Kind() ObservationKind

func (o PromptObservation) Sequence() uint64

type SpawnError ¶

type SpawnError struct{ Cause error }

SpawnError reports that a foreign agent could not be started.

func (e *SpawnError) Error() string

func (e *SpawnError) Unwrap() error

type SteerAdmissionError ¶

type SteerAdmissionError struct{}

SteerAdmissionError reports that the fixed steering-observation reservation lane was full before the request entered the actor mailbox. Its text is intentionally bounded and does not include provider or request details.

func (*SteerAdmissionError) Error() string

func (*SteerAdmissionError) Unwrap() error

type SteerObservation ¶

type SteerObservation struct {
	SteerResult
	Err error
}

SteerObservation is one ordered steering response. Embedding SteerResult keeps admission and receive-order facts available without a second mutable representation.

func (SteerObservation) Kind() ObservationKind

func (o SteerObservation) Sequence() uint64

type SteerOutcome ¶

type SteerOutcome string

SteerOutcome is the closed, provider-neutral classification of one steering attempt. Unknown values are invalid and must be treated as ambiguous by a driver adapter rather than guessed.

const (
	SteerOutcomeInjected             SteerOutcome = "injected"
	SteerOutcomeFallbackRequired     SteerOutcome = "fallback_required"
	SteerOutcomeUnsupported          SteerOutcome = "unsupported"
	SteerOutcomeAdmissionUnknown     SteerOutcome = "admission_unknown"
	SteerOutcomeDeliveryUnknown      SteerOutcome = "delivery_unknown"
	SteerOutcomeDeliveredUntrackable SteerOutcome = "delivered_untrackable"
)

func (o SteerOutcome) RetrySafe() bool

func (o SteerOutcome) Valid() bool

type SteerRequest ¶

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

SteerRequest is an immutable, validated prompt for an optional active-turn steering operation. Its prompt is retained privately and every accessor returns a deep copy, including mutable byte payloads and nested tool-result blocks.

func NewSteerRequest(prompt []content.Block) (SteerRequest, error)

func (r SteerRequest) Prompt() []content.Block

func (r SteerRequest) Validate() error

type SteerResult ¶

type SteerResult struct {
	Outcome          SteerOutcome
	Reason           string
	WriteAdmitted    bool
	ReceiveSequence  uint64
	ResponseSequence uint64
	OrderSequence    uint64
}

SteerResult is the transport-normalized result of one steering attempt. WriteAdmitted is true once the request crossed the adapter writer boundary; ReceiveSequence and ResponseSequence identify the monotonic inbound response order. A zero sequence means no inbound response was observed.

func (r SteerResult) Validate() error

type Steerer ¶

type Steerer interface {
	Steer(context.Context, SteerRequest) (SteerResult, error)
}

Steerer is an optional capability for agents that can inject a message into an active turn while retaining a host-owned fallback path. Agent implementations that do not support steering remain valid: callers must discover this interface with a type assertion and queue a normal turn when it is absent.

The context is runtime-owned. In particular, any bounded acknowledgement deadline belongs in that context (or the enclosing runtime policy), never in SteerRequest, so model-facing request values cannot control it.

type Stream ¶

type Stream interface {
	Events() <-chan Event
	History() (History, error)
	Close() error
}

Stream is the live normalized event stream and its authoritative history.

type Turn ¶

type Turn struct {
	SystemPrompt string
	ForeignSID   string
	StartNew     bool
	Input        []content.Block
	Cwd          string
	Posture      PermissionPosture
}

Turn is one turn's input to a foreign agent.

type UpdateObservation ¶

type UpdateObservation struct {
	Event           Event
	ReceiveSequence uint64
	OrderSequence   uint64
}

UpdateObservation is one normalized update translated from an ACP session notification. One notification may produce multiple observations, each carrying the same receive sequence so an ordered backend never relies on competing goroutine arrival order.

func (UpdateObservation) Kind() ObservationKind

func (o UpdateObservation) Sequence() uint64