harness

type Adapter ¶

type Adapter interface {
	Probe(context.Context) (Info, error)
	Run(context.Context, Launch, Emit) (Result, error)
}

Adapter probes its executable and runs one isolated agent turn.

type Clarification ¶

type Clarification struct {
	ID   string `json:"id"`
	Text string `json:"text"`
}

Clarification is a bounded product question that can be answered by a caller before resuming the existing harness session.

type Credential ¶ added in v0.2.8

type Credential struct {
	Kind  CredentialKind
	Value string
	// Environment is what else the identity brings to the launch: further
	// credentials the caller wants the turn to run with, exported into the
	// child's environment under the names given (a GitHub token as GH_TOKEN,
	// say). They travel, live and die exactly as Value does — per launch, in
	// memory, never on disk — and the runner has already refused every name
	// outside its allow-list, so an adapter sees only credential names.
	Environment []EnvironmentVariable
}

Credential is the caller's harness identity for ONE launch.

It is dispatch data, not enrollment: the coordinator sends it with every start and resume, the runner keeps it in memory for the life of the attempt and never writes it to durable state, and an adapter puts it in front of its child for exactly one turn. That is what makes a runner a shared machine rather than a shared billable identity — nothing on the host authenticates to a model provider on its own.

It carries no json tags because it must never be serialized: every wire shape that could hold one (the runner's StartRequest, its durable journal) strips it before anything is written down.

func (c Credential) Empty() bool

type CredentialKind ¶ added in v0.2.8

type CredentialKind string

CredentialKind names which harness identity a launch carries, and therefore how the adapter hands it to its child. The kinds are harness-specific on purpose: an adapter that is given a credential it cannot use must refuse it rather than guess.

const (
	// CredentialClaudeOAuth is a `claude setup-token` value, injected as
	// CLAUDE_CODE_OAUTH_TOKEN.
	CredentialClaudeOAuth CredentialKind = "claude-oauth"
	// CredentialClaudeAPIKey is an Anthropic API key, injected as
	// ANTHROPIC_API_KEY.
	CredentialClaudeAPIKey CredentialKind = "claude-apikey"
	// CredentialCodexAuth is a Codex login session file, materialized as the
	// home's auth.json for the duration of one launch.
	CredentialCodexAuth CredentialKind = "codex-auth"
)

type Emit ¶

type Emit func(Event) error

Emit receives adapter events. Implementations must treat an error as a terminal failure and stop producing events for the launch.

type EnvironmentConfig ¶ added in v0.2.25

type EnvironmentConfig struct {
	PathPrepend []string          `json:"pathPrepend,omitempty"`
	Variables   map[string]string `json:"variables,omitempty"`
}

EnvironmentConfig is local operator policy, never part of a task request. Values are literal: no shell evaluation, tilde expansion, or env-file loading.

func LoadEnvironmentConfig(path string, optional bool) (EnvironmentConfig, error)

func (e EnvironmentConfig) Apply(base []string) []string

func (e EnvironmentConfig) Validate() error

func (e EnvironmentConfig) ValidateForWorktreeRoot(worktreeRoot string) error

type EnvironmentVariable ¶ added in v0.2.16

type EnvironmentVariable struct {
	Name  string
	Value string
}

EnvironmentVariable is one name=value an identity brings to a launch.

type Event ¶

type Event struct {
	Type          string          `json:"type"`
	SessionID     string          `json:"sessionID,omitempty"`
	TurnID        string          `json:"turnID,omitempty"`
	Message       string          `json:"message,omitempty"`
	Data          json.RawMessage `json:"data,omitempty"`
	Clarification *Clarification  `json:"clarification,omitempty"`
}

Event is a bounded adapter event forwarded to the runner state engine.

type Info ¶

type Info struct {
	Name        string   `json:"name"`
	SandboxMode string   `json:"sandboxMode,omitempty"`
	Version     string   `json:"version"`
	Ready       bool     `json:"ready"`
	Reasons     []string `json:"reasons,omitempty"`
}

Info describes an adapter's executable and readiness state.

type Launch ¶

type Launch struct {
	AttemptID       string `json:"attemptID"`
	Workdir         string `json:"workdir"`
	SessionID       string `json:"sessionID,omitempty"`
	Instructions    string `json:"instructions"`
	Model           string `json:"model,omitempty"`
	ReasoningEffort string `json:"reasoningEffort,omitempty"`
	// Credential is the identity this turn runs as. It is never serialized.
	Credential Credential `json:"-"`
	// Permissions, when set, is how this launch reaches a human for a tool call
	// the permission mode does not pre-approve. nil means there is nobody to
	// ask, and an adapter must then keep its harness from prompting at all —
	// which is what every caller that predates this field gets, unchanged.
	Permissions PermissionAsker `json:"-"`
}

Launch identifies one worker attempt and the thread turn it should execute.

SessionID, when set, is the harness session this turn continues. It may be a session an earlier ATTEMPT created — that is how a conversation spans turns — so an adapter must resume it rather than assume it owns it.

type PermissionAsker ¶ added in v0.2.8

type PermissionAsker interface {
	AskPermission(ctx context.Context, request PermissionRequest) (PermissionVerdict, error)
}

PermissionAsker is how an adapter reaches a human mid-turn. The runner implements it; an adapter calls it and BLOCKS, because the tool call it is answering is blocked too.

AskPermission returns only when there is a verdict or when ctx is done. A ctx-done return must be treated as a denial by the adapter rather than as an error that fails the turn: the turn is being cancelled, and a permission call left hanging would keep the harness child alive after everything else has been torn down.

type PermissionRequest ¶ added in v0.2.8

type PermissionRequest struct {
	// ID is stable for one session and one tool call, and a resume must echo
	// it. It is the same fencing a Clarification has, for the same reason: a
	// verdict that arrives for a request the harness is no longer waiting on
	// must be refused rather than applied to whatever is waiting now.
	ID string `json:"id"`
	// Tool is the harness tool name the call is for, e.g. "Bash" or "WebFetch".
	Tool string `json:"tool"`
	// Input is a bounded JSON rendering of the tool's input, exactly as the
	// harness proposed it. It is what the human is shown and what the verdict
	// authorizes — that call, those arguments.
	Input string `json:"input,omitempty"`
}

PermissionRequest is one harness permission prompt waiting on a human.

type PermissionVerdict ¶ added in v0.2.8

type PermissionVerdict struct {
	Allow   bool   `json:"allow"`
	Message string `json:"message,omitempty"`
}

PermissionVerdict is a human's answer to a PermissionRequest.

A denial is a real answer, not a failure: it goes back to the harness, which continues the turn and can explain itself or take another route. Message is what the harness is told, and it is the only place the human's words reach the model.

type Result ¶

type Result struct {
	Phase         string         `json:"phase"`
	SessionID     string         `json:"sessionID,omitempty"`
	Blocker       string         `json:"blocker,omitempty"`
	Clarification *Clarification `json:"clarification,omitempty"`
}

Result is the terminal state of one adapter launch.