externagent

type Adapter interface {
	// Name is the CLI's stable identifier (for example "codex"), used in the model
	// spec that selects it and recorded on the run.
	Name() string
	// Detect probes whether the CLI is installed, logged in, and new enough to be
	// constrained. It runs the CLI's own version and auth probes and never starts an
	// episode.
	Detect(ctx context.Context) (Readiness, error)
	// Command builds the subprocess invocation for one episode: the argv that locks
	// the CLI's native execution down (read-only, native effects denied) and points
	// its MCP client at the bridge, plus how the turn and the final message are
	// carried. It does not run anything.
	Command(ep Episode) (Invocation, error)
	// Parse turns one line of the CLI's stdout into zero or more typed events. A line
	// it does not recognize yields an attested progress event rather than an error, so
	// an unfamiliar line is recorded, not dropped.
	Parse(line []byte) ([]Event, error)
}

type Bridge struct {
	// Name is the MCP server name the CLI registers the bridge under. Tool names the
	// CLI reports may be namespaced by it, which the driver maps back to real tool
	// identities for capability matching.
	Name string
	// URL is the streamable-HTTP endpoint the CLI connects to, on the loopback
	// interface. It is the address the child uses, which is not always the address the
	// bridge listens on: where the child runs in its own network namespace, this is an
	// in-namespace address the sandbox forwards to the listening one (see ForwardTo).
	URL string
	// ForwardTo is the host-loopback address the sandbox forwards the child's URL to when
	// the child cannot reach the host loopback directly (a separate network namespace). It
	// is empty when the child reaches URL directly (a shared network stack), and is set by
	// the runner from what the spawner reports, so the spawner knows to stand up the forward.
	ForwardTo string
	// Token is the bearer token the CLI must present, so another local process cannot
	// drive the bridge. The adapter passes it to the CLI through an environment
	// variable rather than an argument, keeping it out of the process table.
	Token string
	// TokenEnv is the environment variable the CLI reads the bearer token from.
	TokenEnv string
}

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

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

type ConformanceReport struct {
	Results  []ProbeResult
	Steering Steering
}

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

type Episode struct {
	Input   string
	Workdir string
	Model   string
	System  string
	Bridge  Bridge
	// Probes are conformance instructions folded into the turn the harness reads. Their
	// compliance is checked against the episode's own event stream once it finishes.
	Probes []string
	// Session, when set, is a conversation the CLI already holds (a Session an earlier
	// episode reported), which this episode continues instead of opening a fresh one. It
	// is how an interactive session gives the harness the context of its own earlier
	// turns: the CLI kept that conversation, and only the CLI can. Empty starts a new
	// conversation. An adapter whose CLI cannot continue a conversation ignores it, so
	// the turn still runs, with only this turn's input.
	Session string
}

type Event struct {
	Kind     EventKind
	Text     string
	Usage    Usage
	Err      string
	Terminal bool // for EventError: the failure is terminal, not worth retrying
	Tier     Tier
	Raw      json.RawMessage

	// Tool is the tool a bridge call named (EventBridgeCall), and Server the bridge it
	// named it on. A call to another MCP server is not ours and is not counted as bridged.
	Tool   string
	Server string
	// Args is the arguments a bridge call carried, verbatim, so a conformance probe can
	// look for the nonce it asked the harness to echo.
	Args json.RawMessage
	// Command is the command line the CLI reported running natively (EventNativeCommand).
	Command string
	// Status is the CLI's terminal status for the call or command it reported: completed,
	// failed, declined, or in_progress. A started call and its completion are two events,
	// so counting one status avoids double counting.
	Status string
	// Session is the conversation id the CLI announced for this episode, when it
	// announces one. Both bundled harnesses open their stream with it (claude's init
	// event, codex's thread.started), and both accept it back to continue that same
	// conversation. Carrying it is what lets a multi-turn session hand the CLI its own
	// context instead of replaying a transcript the CLI never wrote.
	Session string
}

type EventKind int

type Invocation struct {
	Path            string
	Args            []string
	Env             []string
	Stdin           string
	LastMessageFile string
}

type Probe struct {
	// Name identifies the probe on the record and in the drift report.
	Name string
	// Instruction is the text handed to the harness. It must ask for something observable
	// in the event stream, since a probe that cannot fail proves nothing.
	Instruction string
	// Required marks a probe whose failure makes the session unsafe to trust rather than
	// merely degraded. A required probe that fails refuses the run.
	Required bool
	// contains filtered or unexported fields
}

type ProbeResult struct {
	Name     string
	Passed   bool
	Required bool
}

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

type Process interface {
	Stdout() io.Reader
	Wait() error
}

type Program struct {
	// Path is the absolute path of the native executable to launch.
	Path string
	// ReadableDirs are the directories the confined child is granted read and execute
	// access on so it can load the executable and the helper binaries shipped beside it.
	ReadableDirs []string
}

type Readiness struct {
	// Available is true when the CLI is installed and answered a version probe.
	Available bool
	// LoggedIn is true when the CLI holds usable credentials (a subscription session
	// or an API key), so an episode would not stall on an auth prompt.
	LoggedIn bool
	// Version is the CLI's reported version, recorded on the run and used to refuse a
	// build too old to constrain.
	Version string
	// Reason is a one-line, actionable message when the CLI is not ready to run (for
	// example, an instruction to log in). It is empty when Ready is true.
	Reason string
	// Refuse marks a hard refusal the driver must not start on (a too-old CLI, a
	// missing lockdown knob) as distinct from a recoverable onboarding prompt (not yet
	// logged in). A refusal is terminal; an onboarding prompt is not.
	Refuse bool
}

type Recorder interface {
	// Record persists one attested event. An error is reported by the caller and does not
	// fail the episode: losing the harness's account of a line is a gap in the record, not
	// a reason to abandon a run whose effects are still enforced and recorded.
	Record(ctx context.Context, ev Event) error
}

type Result struct {
	Text     string
	Usage    Usage
	Failed   bool
	Err      string
	Terminal bool
	Tiers    map[Tier]int
	// Conformance is how the harness answered the episode's probes and how it chose its
	// tools. It is the evidence that the run's instructions took, rather than the
	// assumption that they did.
	Conformance ConformanceReport
	// Session is the conversation id the CLI announced, empty when it announced none.
	// Handing it back on a later Episode continues that conversation, which is how a
	// multi-turn session keeps the harness's own context across turns.
	Session string
}

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

type SandboxConfig struct {
	// AllowedHosts is the destination-name allowlist for an episode's egress: the
	// external provider's API and auth endpoints, the only names the confined child may
	// reach out to. It is a name gate on the egress proxy ("deny all egress except these
	// providers"): a name not on the list is denied, and a listed name that resolves to a
	// private or rebinding address is denied too (the address gate still applies). An
	// entry beginning with a dot (".example.com") matches any subdomain. The loopback MCP
	// bridge is not listed here: it is not reached through the egress proxy at all. Where the
	// child shares the host's network stack it dials the bridge's host loopback directly;
	// where the child is confined to its own network namespace it dials an in-namespace
	// address the sandbox forwards to the bridge (see the loopback forward in Start). Either
	// way the bridge stays reachable while the internet does not. An empty list permits no
	// egress at all beyond the bridge (deny-all), enough for an offline detection run but not
	// a live episode. These are supplied by the adapter, so no provider name is baked into
	// this generic host.
	AllowedHosts []string
	// AuthDir is the external CLI's credential and config home (its OAuth token lives
	// there), which sits outside the episode workspace. The confined child is granted
	// read (and traverse) on it for the life of the episode and the grant is revoked on
	// teardown, so the credential stays in its home directory and is never copied into the
	// workspace, the vault, or the record. Empty grants no extra read. On Linux and macOS
	// a read-only host already permits the read, so this takes effect only where the
	// confinement denies reads by default (a Windows AppContainer).
	AuthDir string
	// AuthEnv is the environment variable the external CLI reads to find its credential
	// and config home (CODEX_HOME for codex). The confined child inherits none of the
	// host's environment, so it has no HOME or USERPROFILE to derive that home from and
	// would look for its credentials somewhere that does not exist, reporting itself
	// logged out on a host where it is logged in. Granting AuthDir makes the directory
	// readable; naming it here is what makes the child look in it. Empty passes no
	// variable.
	AuthEnv string
	// AuthSeedPaths names individual source files, by absolute path, that together make up
	// the CLI's credential and config home. It is the multi-source counterpart of AuthDir
	// plus AuthSeedFiles: where those copy named files out of one directory, this gathers
	// files that live in different directories (or under a home the confined child has no
	// way to derive) into one directory holding exactly their base names and nothing else.
	// A CLI whose credential and config are split across two locations (Claude Code keeps
	// its config in the home directory and its OAuth token in a subdirectory) is given one
	// directory it can be pointed at, for both detection and an episode. When set it takes
	// precedence over AuthSeedFiles; AuthEnv still names the variable that points the child
	// at the assembled directory, and a source file that does not exist is skipped so a
	// partially configured CLI assembles what it has and detection reports the rest as
	// not-ready. Like the AuthSeedFiles copy, the assembled directory is a per-episode home
	// the run writes and deletes, so a token the harness refreshes lives only in the copy
	// and the host credential is never made writable to it.
	AuthSeedPaths []string
	// AuthSeedFiles names the files inside AuthDir that an episode's credential home must
	// contain (for codex: the OAuth token and the CLI's own config). Naming them switches
	// an episode from pointing the child straight at AuthDir to giving it a per-episode
	// copy of just these files, in a writable directory outside the workspace that the run
	// creates and deletes.
	//
	// An episode needs this because the CLI writes its own home as it runs (a session
	// rollout, a log, a PATH shim) and every confinement tier denies writes outside the
	// workspace, so pointing it at a read-only AuthDir fails partway through the episode.
	// The two obvious fixes are both worse. Granting write on the host's AuthDir hands an
	// untrusted harness the credential file it authenticates with, to corrupt or replace,
	// and leaves whatever it wrote behind after the run. Putting the home inside the
	// workspace copies the OAuth token into the tree the record captures. The per-episode
	// copy has neither problem: the child can write all it likes, it writes only a copy
	// that dies with the episode, and the copy sits outside the recorded workspace.
	//
	// The cost is that a token the CLI refreshes mid-episode is refreshed only in the copy,
	// so the host's credential stays as it was; the refresh token it was issued from
	// remains valid, so the next episode still authenticates. Empty keeps the read-only
	// AuthDir behaviour (correct for a detection probe, which writes nothing).
	AuthSeedFiles []string
	// ProgramDirs are the directories holding the external CLI's own executable and the
	// helper binaries shipped beside it. The confined child is granted read (and execute)
	// on them for the life of the launch and the grant is revoked on teardown. Without it
	// the child cannot load the very program it is meant to run: confinement is
	// default-deny for reads where the platform enforces it, and the CLI lives outside the
	// episode workspace. They come from resolving the CLI to its native executable (see
	// LocateCodex), so a launcher script's interpreter, which may sit under a system-owned
	// directory an unprivileged process cannot grant at all, never enters the confinement.
	// Empty grants no extra read, which is correct where the confinement leaves the host
	// filesystem readable.
	ProgramDirs []string
	// HostReadable selects the confinement tier that confines the child's writes to the
	// episode workspace but leaves the host filesystem readable to it (see
	// sandbox.WithHostReadable). It is set for a CLI whose runtime cannot start under a
	// deny-by-default read posture: the codex CLI is a Rust program, and every Rust program
	// that canonicalizes a path fails inside a Windows AppContainer, whose token cannot
	// perform the final step that maps a file handle back to a DOS path. The weakening is
	// real (the harness can read the host user's files) and bounded (it can still write
	// nothing outside the workspace, and its egress is still gated), so it is named per
	// backend rather than defaulted, and the tier that ran is recorded on the episode. On
	// Linux and macOS the kernel tier already leaves the host readable, so this changes
	// nothing there.
	HostReadable bool
	// MinContainment is the floor the host must actually enforce or an episode is refused
	// rather than run less contained (refuse-rather-than-downgrade: an untrusted harness
	// never silently drops to a weaker boundary). The zero value is treated as
	// sandbox.ContainmentKernel, the boundary for semi-trusted, model-authored code over a
	// shared kernel; a caller can raise it (a microVM tier) but not lower it below the
	// kernel floor by leaving it zero.
	MinContainment sandbox.Containment
	// ProbeTimeout caps how long a detection probe may run before it is killed, so a
	// hung CLI cannot stall detection. Zero applies no cap beyond the caller's context.
	ProbeTimeout time.Duration
}

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

type Spawner interface {
	// Probe runs path with args to completion and returns its combined output. A
	// non-nil error means the command could not be run or exited non-zero, which
	// detection reads as "not present" or "not ready".
	Probe(ctx context.Context, path string, args ...string) (string, error)
	// Start launches one episode's subprocess and returns its live stdout and a wait
	// handle. The process is bound to ctx: a cancellation (a halt or shutdown) kills it.
	Start(ctx context.Context, ep Episode, inv Invocation) (Process, error)
}

type Steering struct {
	// BridgeCalls is how many tool calls the harness made on the run's own bridge, where
	// the dispatch waist admitted, contained, braked, and recorded each one.
	BridgeCalls int
	// ForeignCalls is how many tool calls the harness made on some other MCP server. The
	// run neither serves nor governs those, so they are counted apart from its own.
	ForeignCalls int
	// NativeCommands is how many commands or file edits the harness ran with its own
	// built-in tools rather than the bridged ones.
	NativeCommands int
	// NativeDeclined is how many of those native attempts the CLI's own sandbox refused
	// (a declined command, a failed patch). Each is a turn the harness spent learning it
	// cannot act natively, which better steering would not have spent.
	NativeDeclined int
}

type Tier int

type Usage struct {
	InputTokens  int
	OutputTokens int
}