runner

type Adapter string

type AgentStartError struct {
	// Agent is the adapter/harness identity (claude-code, codex, gh-copilot).
	Agent string
	// Binary is the CLI that was invoked or looked up.
	Binary string
	// Reason is why the agent did not run.
	Reason AgentStartReason
	// ExitCode is the CLI's exit code for the auth case; 0 when unavailable.
	ExitCode int
	// Detail is the auth signature that matched (auth case); empty otherwise.
	Detail string
	// Cause is the underlying exec error (unavailable case); nil otherwise.
	Cause error
}

type AgentStartReason string

type AgentTelemetry struct {
	// SessionID is the platform session UUID when the runner captured one.
	SessionID string
	// Harness is the agent platform identifier (claude-code, codex, ...).
	Harness string
	// Model is the model ID the run used; populated when the CLI reports it.
	Model string
	// Retries is how many times the runner had to re-invoke the agent.
	Retries int
	// Tokens is the run's token usage; nil when the runner captured none.
	// Absent token data is first-class — the rubric renormalizes.
	Tokens *scoring.TokenUsage
}

type FakeRunner struct {
	// Result is returned from every Run call.
	Result Result
	// Err is returned from every Run call; when non-nil the harness treats the
	// invocation as a launch failure (Result is still returned alongside it,
	// matching the real adapters' error contract).
	Err error

	// Calls counts how many times Run was invoked.
	Calls int
	// LastSpec and LastInstance capture the most recent Run arguments so a
	// consumer can assert the harness wired the sandbox and task through.
	LastSpec     *eval.TaskSpec
	LastInstance *sandbox.Instance
}

type Result struct {
	// Stdout is the captured standard output of the agent process.
	Stdout []byte
	// Stderr is the captured standard error of the agent process.
	Stderr []byte
	// ExitCode is the process exit code (0 = success).
	ExitCode int
	// Duration is wall-clock time from exec start to process exit.
	Duration time.Duration
	// Telemetry holds the identity and usage data the adapter extracted.
	Telemetry AgentTelemetry
}

type Runner interface {
	// Run invokes the agent with the task prompt inside instance.Workdir,
	// appending instance.Env to the subprocess environment. The returned
	// Result carries stdout, stderr, exit code, wall time, and any telemetry
	// the adapter could extract. A non-zero exit code is NOT itself a Go
	// error — it is encoded in Result.ExitCode so the harness can
	// distinguish "the agent ran but produced wrong output" from "we could
	// not launch the agent at all".
	Run(ctx context.Context, spec *eval.TaskSpec, instance *sandbox.Instance) (Result, error)
}