runtime

package
v0.40.0 Latest Latest
Warning

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

Go to latest
Published: Sep 3, 2026 License: Apache-2.0 Imports: 32 Imported by: 0

Documentation

Index

Constants

View Source
const DefaultAgentPrompt = "Run the agent task"

DefaultAgentPrompt is the prompt handed to the agent CLI when RunParams does not override it. It is deliberately content-free: the actual task comes from the agent definition selected with --agent, so every runtime adapter can pass the same string.

View Source
const DefaultDebugLogName = "agent-debug.log"

DefaultDebugLogName is the local debug-log filename for runtimes that do not implement DebugLogNamer.

Variables

This section is empty.

Functions

func AgentDefinitionModel added in v0.40.0

func AgentDefinitionModel(path string) string

AgentDefinitionModel reads the frontmatter `model:` from a Claude-style agent definition. It returns "" when the file has no frontmatter, names no model, or cannot be read or parsed: the caller then falls back to the runtime default, which is what the run does today when nothing names a model. A definition that cannot be read at all fails the run later, in Bootstrap, with a better message than this function could give.

func DebugLogNameFor added in v0.37.0

func DebugLogNameFor(candidates ...any) string

DebugLogNameFor returns the debug-log filename from the first candidate that implements DebugLogNamer with a non-empty name (callers pass the Backend's Runtime and TranscriptHandler), falling back to DefaultDebugLogName.

func EffectiveModel added in v0.40.0

func EffectiveModel(runModel, agentModel string) string

EffectiveModel returns the model a run will actually ask the runtime for: the value the runner resolved (flag > env > agents: entry > harness `model:`), or, when the runner resolved none, the agent definition's frontmatter `model:`. An empty result means neither named one and the runtime's own default applies.

This is the single fallback chain. PiRuntime.Run builds `--model` from it and NeedsOpenAIProvider decides from it whether the run needs the OpenAI run-scoped provider, so the two cannot disagree about which model a run will call — a disagreement would either strand a frontmatter-pinned OpenAI agent without a credential or attach a live OpenAI credential to a run that never calls OpenAI (#6920).

func NeedsOpenAIProvider added in v0.40.0

func NeedsOpenAIProvider(backend, runModel, agentModel string) bool

NeedsOpenAIProvider reports whether a run on the named backend with the given effective model needs the OpenAI run-scoped provider — the runner creates one only then, so a harness may declare the openai provider for every runtime without forcing an OpenAI credential on runs that never call OpenAI (#6920).

codex speaks only the OpenAI Responses API, so it always needs one. pi is multi-provider: it needs one exactly when the effective model resolves to its openai provider, which is the same resolution buildPiRunCommand gates on (provider prefix, the FULLSEND_PI_PROVIDER default for a bare id). Every other backend — Claude Code on Vertex, the test runtimes — needs none.

runModel is what the runner resolved (flag > env > agents: entry > harness `model:`) and agentModel the agent definition's frontmatter `model:`; both are passed rather than one pre-resolved value so a caller cannot resolve them differently from the runtime's own launch path — see EffectiveModel.

func PiOpenAIAuthSeed added in v0.38.0

func PiOpenAIAuthSeed(configDir string) string

PiOpenAIAuthSeed is the POSIX sh fragment that writes the placeholder the sandbox environment carries for OPENAI_API_KEY into pi's auth.json under configDir (atomically, via rename — pi locks and re-reads the file). It runs at iteration start, before the agent-writable .env is sourced, and the runner re-runs it through `sandbox exec` after every credential refresh, once the sandbox has observed the new generation: an exec'd shell's environment holds the current placeholder, so the runner never needs to know the opaque revision. A value that is not a gateway placeholder fails the run: a real key in the sandbox environment would mean the provider path was bypassed, and forwarding it would defeat the design.

func WantsClaudeMDBridge added in v0.37.0

func WantsClaudeMDBridge(rt Runtime) bool

WantsClaudeMDBridge reports whether rt wants the CLAUDE.md→AGENTS.md bridge file; false for runtimes that do not implement ContextBridger.

Types

type AgentEvent added in v0.31.0

type AgentEvent interface {
	// contains filtered or unexported methods
}

AgentEvent is the normalized event interface for runtime-agnostic rendering. Each concrete event type implements this with a no-op marker method.

type Backend

type Backend struct {
	Runtime
	Transcripts TranscriptHandler
}

Backend pairs the active runtime with its transcript/debug artifact handler.

func Default

func Default() Backend

Default returns the Claude Code backend. Prefer ResolveFromConfig for org-aware selection.

func Resolve added in v0.30.0

func Resolve(name string) (Backend, error)

Resolve returns the agent backend for the given runtime name.

func ResolveForAgent added in v0.38.0

func ResolveForAgent(agents []config.AgentEntry, repoRuntime, agent string) (Backend, bool, error)

ResolveForAgent selects the runtime backend for one agent: the agents: entry's runtime when set, else repoRuntime (the repo-wide runtime: key, "claude" when empty). The boolean reports whether the per-agent entry decided. Both values are validated against config.ValidRuntimes so an agents: entry cannot activate a stub runtime any more than the repo-wide key can.

func ResolveFromConfig added in v0.30.0

func ResolveFromConfig(cfg config.OrgConfigReader) (Backend, error)

ResolveFromConfig selects the runtime backend from org config defaults. The runtime name is validated against config.ValidRuntimes before resolution so that stub runtimes registered in Resolve for dev/testing cannot be activated through config files.

func ResolveFromPerRepoConfig added in v0.30.0

func ResolveFromPerRepoConfig(cfg config.PerRepoConfigReader) (Backend, error)

ResolveFromPerRepoConfig selects the runtime backend from per-repo config. The runtime name is validated against config.ValidRuntimes before resolution so that stub runtimes registered in Resolve for dev/testing cannot be activated through config files.

type BehaviourOpResult added in v0.30.0

type BehaviourOpResult struct {
	Description string `json:"description"`
	Success     bool   `json:"success"`
	Error       string `json:"error,omitempty"`
}

BehaviourOpResult records the outcome of one scripted operation.

type BehaviourOperation added in v0.30.0

type BehaviourOperation struct {
	Description string `yaml:"description" json:"description"`
	Op          string `yaml:"op" json:"op"`
	Args        string `yaml:"args" json:"args"`
	Content     string `yaml:"content,omitempty" json:"content,omitempty"`
}

BehaviourOperation is a single scripted step for the dummy runtime.

type BehaviourResults added in v0.30.0

type BehaviourResults struct {
	Operations []BehaviourOpResult `json:"operations"`
}

BehaviourResults is written to output/behaviour-results.json in the sandbox.

type BehaviourScript added in v0.30.0

type BehaviourScript struct {
	Ops []BehaviourOperation `yaml:"ops"`
}

BehaviourScript is the YAML committed to .fullsend/behaviour/current-scenario.yaml.

func LoadBehaviourScript added in v0.30.0

func LoadBehaviourScript(path string) (*BehaviourScript, error)

LoadBehaviourScript reads and parses a behaviour scenario script from disk.

type BootstrapInput

type BootstrapInput interface {
	SandboxName() string
	// AgentPath returns the local filesystem path to the agent definition file.
	// For cached agents this may be a content-addressed path with a generic basename.
	AgentPath() string
	// AgentName returns the logical agent name (e.g. "review") used to construct
	// the destination filename as {name}.md inside the sandbox. Populated from
	// the CLI positional argument; must not be empty in production (enforced by
	// cobra arg validation in cmd/fullsend).
	AgentName() string
	SkillDirs() []string
	PluginDirs() []string
}

BootstrapInput is the portable contract every runtime needs to provision agent content into the sandbox. Implementations live outside this package (runner adapter, tests).

type ClaudeRuntime

type ClaudeRuntime struct{}

ClaudeRuntime implements Runtime using the Claude Code CLI.

func (ClaudeRuntime) Bootstrap

func (r ClaudeRuntime) Bootstrap(input BootstrapInput) error

func (ClaudeRuntime) ClearIterationArtifacts

func (r ClaudeRuntime) ClearIterationArtifacts(sandboxName string) error

ClearIterationArtifacts terminates processes the previous iteration left running (see killStrayProcesses), then removes its outputs and transcripts so artifacts are per-iteration.

func (ClaudeRuntime) ConfigDir

func (ClaudeRuntime) ConfigDir() string

func (ClaudeRuntime) DebugLogName added in v0.37.0

func (ClaudeRuntime) DebugLogName() string

DebugLogName implements DebugLogNamer: the local artifact for --debug output.

func (ClaudeRuntime) EmitTranscriptErrors

func (ClaudeRuntime) EmitTranscriptErrors(w io.Writer, summaries []TranscriptError)

func (ClaudeRuntime) EnvExports

func (r ClaudeRuntime) EnvExports() []string

func (ClaudeRuntime) ExtractDebugLog

func (r ClaudeRuntime) ExtractDebugLog(sandboxName, localPath, debug string) error

func (ClaudeRuntime) ExtractTranscripts

func (r ClaudeRuntime) ExtractTranscripts(sandboxName, agentLabel, outputDir string) error

func (ClaudeRuntime) Name

func (ClaudeRuntime) Name() string

func (ClaudeRuntime) NeedsClaudeMDBridge added in v0.37.0

func (ClaudeRuntime) NeedsClaudeMDBridge() bool

NeedsClaudeMDBridge implements ContextBridger. Claude Code auto-loads CLAUDE.md but not AGENTS.md, so AGENTS.md-only repos need the pointer file.

func (ClaudeRuntime) ParseTranscriptErrors

func (ClaudeRuntime) ParseTranscriptErrors(transcriptDir string) []TranscriptError

func (ClaudeRuntime) ParseTranscriptFile added in v0.27.0

func (ClaudeRuntime) ParseTranscriptFile(path string) (TranscriptError, bool)

func (ClaudeRuntime) Run

func (ClaudeRuntime) Run(ctx context.Context, params RunParams, printer *ui.Printer, start time.Time, metrics *RunMetrics) (int, error)

func (ClaudeRuntime) System added in v0.25.0

func (ClaudeRuntime) System() string

System returns the OTEL GenAI `gen_ai.system` vendor for Claude Code's models.

func (ClaudeRuntime) WorkspaceDir

func (ClaudeRuntime) WorkspaceDir() string

type CodexRuntime added in v0.40.0

type CodexRuntime struct{}

CodexRuntime drives the Codex agent runtime (openai/codex, CLI `codex`, pinned in the sandbox image by CODEX_VERSION). Bootstrap (codex_bootstrap.go) translates the Claude-style agent definition into a runner-owned config.toml and installs the sandbox hook scripts behind an adapter codex invokes from hooks.json (codex_config.go); Run (codex_run.go) executes `codex exec --json` against a run-scoped OpenAI provider whose bearer token comes from a runner-seeded file, and normalizes the stream via parseCodexStream (codex_progress.go); transcripts are codex's rollout session JSONL files (codex_transcript.go). Selectable with `runtime: codex` in per-repo config or on an `agents:` entry (#6920, ADR 0099).

func (CodexRuntime) Bootstrap added in v0.40.0

func (r CodexRuntime) Bootstrap(input BootstrapInput) error

Bootstrap prepares the runner-owned codex config directory for one agent run: the agent body as developer_instructions in config.toml, the auth script for the run-scoped OpenAI provider, skills, the hook scripts plus the fullsend adapter and hooks.json when the harness enables security, and the manifest Run reads. It also preflights the pinned codex binary so a broken image fails here rather than as a silent zero-turn run.

func (CodexRuntime) ClearIterationArtifacts added in v0.40.0

func (r CodexRuntime) ClearIterationArtifacts(sandboxName string) error

ClearIterationArtifacts terminates processes the previous iteration left running (see killStrayProcesses), then removes its outputs, the rollout sessions and the debug log so transcripts and output files are per-iteration.

func (CodexRuntime) ConfigDir added in v0.40.0

func (CodexRuntime) ConfigDir() string

ConfigDir returns the codex config directory inside the sandbox. It is exported to the agent process as CODEX_HOME (see EnvExports) and lives outside the cloned repo tree so the target repo cannot pre-seed it and workspace resets do not clear it. It is not a permission boundary: the agent process runs as the same user, so the runner-written files under it must be checksum-guarded before each launch rather than trusted.

func (CodexRuntime) DebugLogName added in v0.40.0

func (CodexRuntime) DebugLogName() string

DebugLogName implements DebugLogNamer: the local artifact for codex's stderr trace output.

func (CodexRuntime) EmitTranscriptErrors added in v0.40.0

func (CodexRuntime) EmitTranscriptErrors(w io.Writer, summaries []TranscriptError)

func (CodexRuntime) EnvExports added in v0.40.0

func (r CodexRuntime) EnvExports() []string

EnvExports pins codex's config location to the runner-owned path. codex refuses to start when CODEX_HOME does not exist, so Bootstrap must create the directory as well; the sandbox image bakes the same value as an ENV default for ad-hoc invocations (images/sandbox/Containerfile). codex keeps its other hygiene settings (update check, analytics, telemetry) in config.toml rather than the environment, so there is nothing else here.

func (CodexRuntime) ExtractDebugLog added in v0.40.0

func (r CodexRuntime) ExtractDebugLog(sandboxName, localPath, debug string) error

ExtractDebugLog downloads the stderr capture Run writes when debug is on. codex exec has no debug flag of its own: its tracing goes to stderr behind the RUST_LOG filter, and Run redirects that to this file.

It gets the same pattern redaction as the other artifacts. codex logs at error level by default and raises to whatever RUST_LOG asks for, so this file carries request bodies, hook output and command text — the same material output.jsonl does, and it is uploaded the same way.

func (CodexRuntime) ExtractTranscripts added in v0.40.0

func (r CodexRuntime) ExtractTranscripts(sandboxName, agentLabel, outputDir string) error

ExtractTranscripts downloads codex's rollout session files (written under the runner-owned $CODEX_HOME/sessions/YYYY/MM/DD/, one per thread) into outputDir as <agentLabel>-<basename>, with the same path containment as the Claude and pi handlers.

Only `.jsonl` is collected. codex writes the running session's rollout uncompressed and compresses older ones in place (codex-rs/thread-store/src/local/helpers.rs), so a `.jsonl.zst` is never the current iteration's transcript — and the sessions directory is agent-writable, so trusting that suffix meant a plaintext file *named* `x.jsonl.zst` shipped as an artifact that codexRedactFile declined to rewrite. Extension is not evidence of content: the suffix is excluded and every candidate's first line must parse as a codex rollout envelope before it is kept.

ClearIterationArtifacts empties the sessions directory between iterations, so in practice this finds the current run's rollout.

func (CodexRuntime) Name added in v0.40.0

func (CodexRuntime) Name() string

func (CodexRuntime) OpenAIAuthFile added in v0.40.0

func (r CodexRuntime) OpenAIAuthFile() string

OpenAIAuthFile implements runtime.OpenAICredentialSeeder: the runner-owned file codex's auth command prints. codex caches the token for refresh_interval_ms and then re-runs the command, so re-seeding this file is what lets a running iteration follow a credential refresh — the same role pi's auth.json plays, and for the same reason (OpenShell 0.0.115 pins a revision-scoped placeholder to the generation it was issued for and refuses the unrevisioned alias, so the process environment cannot carry a placeholder that survives a refresh; a file the process re-reads can).

func (CodexRuntime) OpenAIAuthSeed added in v0.40.0

func (r CodexRuntime) OpenAIAuthSeed() string

OpenAIAuthSeed implements runtime.OpenAICredentialSeeder: the POSIX sh fragment that writes the placeholder the sandbox environment carries for OPENAI_API_KEY into the token file, atomically via rename so the auth command never reads a half-written file.

It runs at iteration start, before the agent-writable .env is sourced, and the runner re-runs it through `sandbox exec` after every credential refresh once the sandbox has observed the new generation: an exec'd shell's environment holds the current placeholder, so the runner never needs to know the opaque revision. A value that is not a gateway placeholder fails the run — a real key in the sandbox environment would mean the provider path was bypassed, and forwarding it would defeat the design (ADR 0092).

func (CodexRuntime) ParseTranscriptErrors added in v0.40.0

func (CodexRuntime) ParseTranscriptErrors(transcriptDir string) []TranscriptError

ParseTranscriptErrors scans every JSONL file in transcriptDir and reports those whose run ended in error.

Only the tee'd `exec --json` capture (output.jsonl) yields a verdict: codex's rollout session files are a different envelope, which parseCodexTranscriptFile recognises and skips rather than misreading. That is the same division pi has — the stream capture is the runner's exit-code override input — with the difference that pi can also judge its session files. Classifying a rollout is tracked for a follow-up; the run's verdict does not depend on it, because Run already returns 1 on a stream-reported error.

func (CodexRuntime) ParseTranscriptFile added in v0.40.0

func (CodexRuntime) ParseTranscriptFile(path string) (TranscriptError, bool)

ParseTranscriptFile is the runner's exit-0 override input: the tee'd `exec --json` stream.

func (CodexRuntime) Run added in v0.40.0

func (r CodexRuntime) Run(ctx context.Context, params RunParams, printer *ui.Printer, start time.Time, metrics *RunMetrics) (int, error)

Run executes one agent iteration and normalizes codex's `exec --json` stream into AgentEvents. codex exits 0 on a failed turn and on an interrupted one, so the stream's verdict overrides the exit code, as it does for pi.

func (CodexRuntime) System added in v0.40.0

func (CodexRuntime) System() string

System returns the OTEL GenAI gen_ai.system value. Unlike pi and opencode, codex serves a single model vendor — it speaks the OpenAI Responses API and has no Vertex, Anthropic or Gemini path — so the system is the vendor ("openai"), not the runtime name.

func (CodexRuntime) WorkspaceDir added in v0.40.0

func (CodexRuntime) WorkspaceDir() string

type ContextBridger added in v0.37.0

type ContextBridger interface {
	NeedsClaudeMDBridge() bool
}

ContextBridger is an optional Runtime extension for runtimes that only auto-load CLAUDE.md (not AGENTS.md) into their system context. When it reports true and the target repo has AGENTS.md but no CLAUDE.md, the runner injects a minimal CLAUDE.md pointer so the agent is not context-blind. Runtimes that read AGENTS.md natively should not implement it (or return false).

type DebugLogNamer added in v0.37.0

type DebugLogNamer interface {
	DebugLogName() string
}

DebugLogNamer is an optional extension a runtime or TranscriptHandler implements to name the local debug-log artifact the runner writes per iteration (e.g. "claude-debug.log"). Runtimes without it get DefaultDebugLogName.

type DummyPlaybackRuntime added in v0.39.0

type DummyPlaybackRuntime struct {
	ExecFn      sandboxExecFunc
	UploadFn    sandboxUploadFunc
	GitCommitFn gitCommitFunc
	ForgeAPIFn  forgeAPIFunc
}

DummyPlaybackRuntime replays canned agent results from an ordered playlist. Each invocation serves the result at the current index, writes result.json to output/agent-result.json, copies any companion files into the workspace, and advances the index via a git commit+push.

ExecFn, UploadFn, GitCommitFn, and ForgeAPIFn are optional test overrides; production uses sandbox.Exec, sandbox.Upload, a real git commit+push, and exec.CommandContext for forge API calls.

func (DummyPlaybackRuntime) Bootstrap added in v0.39.0

func (r DummyPlaybackRuntime) Bootstrap(input BootstrapInput) error

func (DummyPlaybackRuntime) ClearIterationArtifacts added in v0.39.0

func (r DummyPlaybackRuntime) ClearIterationArtifacts(sandboxName string) error

ClearIterationArtifacts sweeps stray processes (dummy-playback execs run in the real sandbox, so it gets the same between-iteration hygiene as the agent runtimes), then removes the previous iteration's output.

func (DummyPlaybackRuntime) ConfigDir added in v0.39.0

func (DummyPlaybackRuntime) ConfigDir() string

func (DummyPlaybackRuntime) EmitTranscriptErrors added in v0.39.0

func (DummyPlaybackRuntime) EmitTranscriptErrors(w io.Writer, summaries []TranscriptError)

func (DummyPlaybackRuntime) EnvExports added in v0.39.0

func (DummyPlaybackRuntime) EnvExports() []string

func (DummyPlaybackRuntime) ExtractDebugLog added in v0.39.0

func (DummyPlaybackRuntime) ExtractDebugLog(_ string, _ string, _ string) error

func (DummyPlaybackRuntime) ExtractTranscripts added in v0.39.0

func (DummyPlaybackRuntime) ExtractTranscripts(_ string, _ string, _ string) error

func (DummyPlaybackRuntime) Name added in v0.39.0

func (DummyPlaybackRuntime) ParseTranscriptErrors added in v0.39.0

func (DummyPlaybackRuntime) ParseTranscriptErrors(_ string) []TranscriptError

func (DummyPlaybackRuntime) ParseTranscriptFile added in v0.39.0

func (DummyPlaybackRuntime) ParseTranscriptFile(_ string) (TranscriptError, bool)

func (DummyPlaybackRuntime) Run added in v0.39.0

func (r DummyPlaybackRuntime) Run(ctx context.Context, params RunParams, printer *ui.Printer, _ time.Time, _ *RunMetrics) (int, error)

func (DummyPlaybackRuntime) System added in v0.39.0

func (DummyPlaybackRuntime) System() string

func (DummyPlaybackRuntime) WorkspaceDir added in v0.39.0

func (DummyPlaybackRuntime) WorkspaceDir() string

type DummyRuntime added in v0.30.0

type DummyRuntime struct {
	ExecFn         sandboxExecFunc
	UploadFn       sandboxUploadFunc
	WriteResultsFn writeBehaviourResultsFunc
}

DummyRuntime executes scripted operations in the real OpenShell sandbox. ExecFn, UploadFn, and WriteResultsFn are optional test overrides; production uses sandbox.Exec, sandbox.Upload, and writeBehaviourResults.

func (DummyRuntime) Bootstrap added in v0.30.0

func (r DummyRuntime) Bootstrap(input BootstrapInput) error

func (DummyRuntime) ClearIterationArtifacts added in v0.30.0

func (r DummyRuntime) ClearIterationArtifacts(sandboxName string) error

ClearIterationArtifacts sweeps stray processes (the dummy runtime's ops run in the real sandbox, so it gets the same between-iteration hygiene as the agent runtimes), then removes the previous iteration's output.

func (DummyRuntime) ConfigDir added in v0.30.0

func (DummyRuntime) ConfigDir() string

func (DummyRuntime) EmitTranscriptErrors added in v0.30.0

func (DummyRuntime) EmitTranscriptErrors(w io.Writer, summaries []TranscriptError)

func (DummyRuntime) EnvExports added in v0.30.0

func (DummyRuntime) EnvExports() []string

func (DummyRuntime) ExtractDebugLog added in v0.30.0

func (DummyRuntime) ExtractDebugLog(_ string, _ string, _ string) error

func (DummyRuntime) ExtractTranscripts added in v0.30.0

func (DummyRuntime) ExtractTranscripts(_ string, _ string, _ string) error

func (DummyRuntime) Name added in v0.30.0

func (DummyRuntime) Name() string

func (DummyRuntime) ParseTranscriptErrors added in v0.30.0

func (DummyRuntime) ParseTranscriptErrors(_ string) []TranscriptError

func (DummyRuntime) ParseTranscriptFile added in v0.30.0

func (DummyRuntime) ParseTranscriptFile(_ string) (TranscriptError, bool)

func (DummyRuntime) Run added in v0.30.0

func (r DummyRuntime) Run(ctx context.Context, params RunParams, printer *ui.Printer, _ time.Time, _ *RunMetrics) (int, error)

func (DummyRuntime) System added in v0.30.0

func (DummyRuntime) System() string

func (DummyRuntime) WorkspaceDir added in v0.30.0

func (DummyRuntime) WorkspaceDir() string

type ErrorEvent added in v0.31.0

type ErrorEvent struct {
	ErrorType string
	Message   string
}

ErrorEvent is emitted when the runtime reports an error.

type EventRenderer added in v0.31.0

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

EventRenderer renders normalized AgentEvent values to a Printer. It tracks block state (text/thinking) so transitions between event types produce clean output boundaries.

func NewEventRenderer added in v0.31.0

func NewEventRenderer(printer *ui.Printer) *EventRenderer

NewEventRenderer creates a renderer that writes to the given printer.

func (*EventRenderer) Handle added in v0.31.0

func (r *EventRenderer) Handle(evt AgentEvent)

Handle dispatches a single AgentEvent to the appropriate rendering method.

type InitEvent added in v0.31.0

type InitEvent struct {
	Model   string
	Version string
}

InitEvent is emitted once at stream start with runtime metadata.

type OpenAICredentialSeeder added in v0.40.0

type OpenAICredentialSeeder interface {
	OpenAIAuthSeed() string
	OpenAIAuthFile() string
}

OpenAICredentialSeeder is implemented by runtimes that read the OpenAI credential placeholder from a runner-owned file the runner re-seeds after every refresh (ADR 0092). OpenAIAuthSeed returns the POSIX sh fragment that writes the sandbox's current OPENAI_API_KEY placeholder into that file, failing closed when the value is not a gateway placeholder; OpenAIAuthFile returns the file's absolute sandbox path, used to verify the seed after a refresh.

The placeholder cannot simply be read from the process environment: it is revision-scoped on OpenShell 0.0.110+ and pinned to the credential generation it was issued for, so a process started before a refresh holds a placeholder the gateway will no longer resolve. A file the agent process re-reads per request is what lets a running iteration follow a refresh.

A runtime that returns "" from OpenAIAuthSeed is treated as having no seeder: the run-scoped provider is still created and refreshed, but no in-sandbox re-seed is attempted. Runtimes with no OpenAI path at all (Claude Code, dummy) do not implement the interface.

type OpenCodeRuntime added in v0.37.0

type OpenCodeRuntime struct{}

OpenCodeRuntime is a stub implementation of the Runtime and TranscriptHandler interfaces for the OpenCode agent runtime. All methods are no-ops or return not-implemented errors. Subsequent PRs will fill in stream parsing, bootstrap, run execution, and transcript extraction.

func (OpenCodeRuntime) Bootstrap added in v0.37.0

func (OpenCodeRuntime) Bootstrap(_ BootstrapInput) error

func (OpenCodeRuntime) ClearIterationArtifacts added in v0.37.0

func (OpenCodeRuntime) ClearIterationArtifacts(_ string) error

ClearIterationArtifacts is a no-op while Run is a stub: nothing has run in the sandbox, so there is nothing to clear. When Run is implemented this must sweep stray sandbox processes (clearStrayProcesses, see killStrayProcesses) before removing the iteration's files, like the other runtimes — the Runtime interface documents that as part of the contract.

func (OpenCodeRuntime) ConfigDir added in v0.37.0

func (OpenCodeRuntime) ConfigDir() string

ConfigDir returns the opencode config directory inside the sandbox. Provisional — verify opencode's config discovery before implementing Bootstrap (#1260). Consider placing config outside the agent-writable workspace (like Claude's /sandbox/claude-config) to prevent the agent from rewriting its own runtime config.

func (OpenCodeRuntime) EmitTranscriptErrors added in v0.37.0

func (OpenCodeRuntime) EmitTranscriptErrors(w io.Writer, summaries []TranscriptError)

func (OpenCodeRuntime) EnvExports added in v0.37.0

func (OpenCodeRuntime) EnvExports() []string

func (OpenCodeRuntime) ExtractDebugLog added in v0.37.0

func (OpenCodeRuntime) ExtractDebugLog(_, _, _ string) error

func (OpenCodeRuntime) ExtractTranscripts added in v0.37.0

func (OpenCodeRuntime) ExtractTranscripts(_, _, _ string) error

func (OpenCodeRuntime) Name added in v0.37.0

func (OpenCodeRuntime) Name() string

func (OpenCodeRuntime) ParseTranscriptErrors added in v0.37.0

func (OpenCodeRuntime) ParseTranscriptErrors(_ string) []TranscriptError

func (OpenCodeRuntime) ParseTranscriptFile added in v0.37.0

func (OpenCodeRuntime) ParseTranscriptFile(_ string) (TranscriptError, bool)

func (OpenCodeRuntime) Run added in v0.37.0

func (OpenCodeRuntime) System added in v0.37.0

func (OpenCodeRuntime) System() string

System returns the OTEL GenAI gen_ai.system value. OpenCode is multi-provider (Anthropic, OpenAI, Google, etc.), so the system is the runtime itself rather than a single model vendor. The actual model vendor may be capturable from opencode's stream/export events in a future PR once the event schema is confirmed (see #1935).

func (OpenCodeRuntime) WorkspaceDir added in v0.37.0

func (OpenCodeRuntime) WorkspaceDir() string

type PiRuntime added in v0.37.0

type PiRuntime struct{}

PiRuntime drives the pi agent runtime (earendil-works/pi, CLI `pi`, pinned in the sandbox image). Bootstrap (pi_bootstrap.go) translates the Claude-style agent definition and installs the sandbox hook scripts behind a pi extension; Run (pi_run.go) executes `pi --print --mode json` and normalizes the stream via parsePiStream (pi_progress.go); transcripts are pi's session JSONL files (pi_transcript.go). Selected per org/repo with `runtime: pi` (#6464).

func (PiRuntime) Bootstrap added in v0.37.0

func (r PiRuntime) Bootstrap(input BootstrapInput) error

Bootstrap prepares the runner-owned pi config directory for one agent run: agent body as APPEND_SYSTEM.md, locked-down settings.json, skills, the hook scripts plus the fullsend hook extension when the harness enables security, and the manifest Run reads. It also preflights the pinned pi binary so a broken image fails here rather than as a silent zero-turn run.

func (PiRuntime) ClearIterationArtifacts added in v0.37.0

func (r PiRuntime) ClearIterationArtifacts(sandboxName string) error

ClearIterationArtifacts terminates processes the previous iteration left running (see killStrayProcesses), then removes its outputs and sessions so transcripts and output files are per-iteration.

func (PiRuntime) ConfigDir added in v0.37.0

func (PiRuntime) ConfigDir() string

ConfigDir returns the pi config directory inside the sandbox. It is exported to the agent process as PI_CODING_AGENT_DIR (see EnvExports) and lives outside the cloned repo tree so the target repo cannot pre-seed it and workspace resets do not clear it. It is not a permission boundary: the agent process runs as the same user and pi loads extensions from <dir>/extensions/, which is why Run passes --no-extensions and names the runner-supplied extensions explicitly. Session JSONL storage is <dir>/sessions (PI_CODING_AGENT_SESSION_DIR, also passed as --session-dir).

func (PiRuntime) DebugLogName added in v0.37.0

func (PiRuntime) DebugLogName() string

DebugLogName implements DebugLogNamer.

func (PiRuntime) EmitTranscriptErrors added in v0.37.0

func (PiRuntime) EmitTranscriptErrors(w io.Writer, summaries []TranscriptError)

func (PiRuntime) EnvExports added in v0.37.0

func (r PiRuntime) EnvExports() []string

EnvExports pins pi's config and session locations to runner-owned paths and disables all startup network traffic (update checks, package update checks, telemetry). PI_OFFLINE does not affect the inference call itself; PI_TELEMETRY=0 additionally drops pi's provider attribution headers. Var names/semantics per earendil-works/pi docs/environment-variables.md (PI_CODING_AGENT_DIR, PI_CODING_AGENT_SESSION_DIR, PI_OFFLINE, PI_SKIP_VERSION_CHECK, PI_TELEMETRY) — re-verify against that doc when PI_VERSION moves. The sandbox image bakes the same values as ENV defaults for ad-hoc invocations (images/sandbox/Containerfile).

func (PiRuntime) ExtractDebugLog added in v0.37.0

func (r PiRuntime) ExtractDebugLog(sandboxName, localPath, debug string) error

ExtractDebugLog downloads pi's stderr capture written when --debug is set.

func (PiRuntime) ExtractTranscripts added in v0.37.0

func (r PiRuntime) ExtractTranscripts(sandboxName, agentLabel, outputDir string) error

ExtractTranscripts downloads pi's session JSONL files (written under the runner-owned sessions dir, possibly nested by working directory) into outputDir as <agentLabel>-<basename>, with the same path containment as the Claude handler.

func (PiRuntime) Name added in v0.37.0

func (PiRuntime) Name() string

func (PiRuntime) OpenAIAuthFile added in v0.40.0

func (r PiRuntime) OpenAIAuthFile() string

OpenAIAuthFile implements OpenAICredentialSeeder: pi's auth.json inside the sandbox, which the runner greps for the new placeholder to confirm a re-seed landed.

func (PiRuntime) OpenAIAuthSeed added in v0.40.0

func (r PiRuntime) OpenAIAuthSeed() string

OpenAIAuthSeed implements OpenAICredentialSeeder: the fragment that seeds pi's auth.json with the sandbox's current OPENAI_API_KEY placeholder. The runner runs it through `sandbox exec` after every credential refresh; Run emits the same fragment at iteration start.

func (PiRuntime) ParseTranscriptErrors added in v0.37.0

func (PiRuntime) ParseTranscriptErrors(transcriptDir string) []TranscriptError

ParseTranscriptErrors scans every JSONL file in transcriptDir (the extracted session files and, when present, the tee'd output.jsonl) and reports those whose last run ended in error.

func (PiRuntime) ParseTranscriptFile added in v0.37.0

func (PiRuntime) ParseTranscriptFile(path string) (TranscriptError, bool)

ParseTranscriptFile is the runner's exit-0 override input: the tee'd --mode json stream. It also understands pi session files so ParseTranscriptErrors can use it on extracted sessions.

func (PiRuntime) Run added in v0.37.0

func (r PiRuntime) Run(ctx context.Context, params RunParams, printer *ui.Printer, start time.Time, metrics *RunMetrics) (int, error)

Run executes one agent iteration and normalizes pi's --mode json stream into AgentEvents. pi exits 0 on model error in json mode, so the stream's verdict overrides the exit code (#2786/#5361).

func (PiRuntime) System added in v0.37.0

func (PiRuntime) System() string

System returns the OTEL GenAI gen_ai.system value. Pi is multi-provider (anthropic, google-vertex, community extensions), so the system is the runtime itself rather than a single model vendor (same precedent as OpenCodeRuntime).

func (PiRuntime) WorkspaceDir added in v0.37.0

func (PiRuntime) WorkspaceDir() string

type PlaybackEntry added in v0.39.0

type PlaybackEntry struct {
	// Result is the subdirectory name under .fullsend/results/ that contains
	// this entry's result.json and optional companion files.
	Result string
}

PlaybackEntry is a single entry in a playback playlist, used by the Gherkin step definitions to build the playlist before committing it.

type Playlist added in v0.39.0

type Playlist struct {
	Current int      `yaml:"current"`
	Results []string `yaml:"results"`
}

Playlist is the YAML committed to .fullsend/results/playlist.yaml. Results are 1-indexed: current=1 serves results[0].

type ResultEvent added in v0.31.0

type ResultEvent struct {
	NumTurns                 int
	TotalCostUSD             float64
	IsError                  bool
	ErrorMessage             string
	Subtype                  string
	InputTokens              int
	OutputTokens             int
	ReasoningTokens          int
	CacheCreationInputTokens int
	CacheReadInputTokens     int
}

ResultEvent is emitted once at stream end with final metrics.

type RetryEvent added in v0.31.0

type RetryEvent struct {
	Attempt    int
	MaxRetries int
	DelayMs    int
	Error      string
}

RetryEvent is emitted when the runtime retries an API call.

type RunMetrics

type RunMetrics struct {
	ToolCalls                atomic.Int32
	NumTurns                 int     `json:"num_turns"`
	TotalCostUSD             float64 `json:"total_cost_usd"`
	InputTokens              int     `json:"input_tokens"`
	OutputTokens             int     `json:"output_tokens"`
	ReasoningTokens          int     `json:"reasoning_tokens"`
	CacheCreationInputTokens int     `json:"cache_creation_input_tokens"`
	CacheReadInputTokens     int     `json:"cache_read_input_tokens"`
	Model                    string  `json:"model"`
}

RunMetrics collects execution statistics from stream parsing.

type RunParams

type RunParams struct {
	SandboxName   string
	AgentBaseName string
	Model         string
	Effort        string
	// FallbackModels is the ordered overload/retirement fallback chain
	// (FULLSEND_FALLBACK_MODELS). Claude Code passes it as --fallback-model;
	// runtimes without the capability ignore it with a warning.
	FallbackModels []string
	RepoDir        string
	FullsendDir    string
	PluginDirs     []string
	Debug          string
	// HooksSettingsPath, if set, is passed as --settings so Claude Code
	// loads the runner's hook wiring regardless of its working directory.
	HooksSettingsPath string
	Timeout           time.Duration
	OutputPath        string           // if set, tee stream-json stdout to this file
	OnEvent           func(AgentEvent) // if non-nil, called with normalized events during Run
	// Prompt overrides DefaultAgentPrompt. The validation loop sets it on a
	// retry iteration to inject the previous iteration's failure so the agent
	// can self-correct instead of re-running blindly. See #1050, #6494.
	//
	// Every Runtime implementation MUST honour this field, falling back to
	// DefaultAgentPrompt when it is empty. A runtime that ignores it turns
	// validation_loop.feedback_mode into a silent no-op for every harness
	// that selects that runtime, which is indistinguishable from the blind
	// retries this field exists to remove. Runtime support is tracked in the
	// key support matrix in docs/runtimes.md.
	Prompt string
	// Forge is the forge platform identifier ("github" or "gitlab").
	// Empty defaults to "github". Used by runtimes that need
	// forge-specific environment variable resolution.
	Forge string
}

RunParams configures a single agent invocation inside the sandbox.

type Runtime

type Runtime interface {
	Name() string
	// System returns the OTEL GenAI `gen_ai.system` value (the model vendor) for
	// this runtime, e.g. "anthropic". Kept on the runtime so telemetry stays
	// runtime-agnostic rather than hardcoding a vendor in the CLI (ADR 0050).
	System() string
	ConfigDir() string
	WorkspaceDir() string
	EnvExports() []string
	Bootstrap(input BootstrapInput) error
	Run(ctx context.Context, params RunParams, printer *ui.Printer, start time.Time, metrics *RunMetrics) (exitCode int, err error)
	ClearIterationArtifacts(sandboxName string) error
}

Runtime is an agent execution backend (LLM tool-use loop) inside the sandbox.

type SandboxHooksBootstrap added in v0.37.0

type SandboxHooksBootstrap interface {
	SandboxHookConfig() security.SandboxHookConfig
}

SandboxHooksBootstrap is an optional BootstrapInput extension carrying the runtime-neutral sandbox tool hook configuration (Tirith, SSRF, canary, secret redaction, ...). Runtimes type-assert for it in Bootstrap and, when present, install the hook scripts from security.HookFiles and wire them through their native mechanism (Claude Code: settings.json; other runtimes: their own plugin/extension) following security.HookPlan. Runtimes that do not implement it install no sandbox tool hooks — see docs/runtimes.md.

type TextEvent added in v0.31.0

type TextEvent struct {
	Text string
}

TextEvent carries an incremental assistant text delta.

type ThinkingEvent added in v0.31.0

type ThinkingEvent struct {
	Text string
}

ThinkingEvent carries an incremental thinking text delta.

type TokensEvent added in v0.31.0

type TokensEvent struct {
	InputTokens     int
	OutputTokens    int
	ReasoningTokens int
	CacheRead       int
	CacheWrite      int
}

TokensEvent carries incremental token usage counters.

type ToolUseEvent added in v0.31.0

type ToolUseEvent struct {
	Name    string
	Summary string
}

ToolUseEvent is emitted when a tool invocation completes. Name is the raw tool name from the runtime stream. Summary is a one-line context string from extractSafeContext; it is empty for tools not recognized by that function.

type TranscriptError

type TranscriptError struct {
	Source       string
	IsError      bool
	ErrorMessage string
	Subtype      string
}

TranscriptError holds extracted error information from a runtime transcript.

func (TranscriptError) DisplayMessage added in v0.37.0

func (te TranscriptError) DisplayMessage() string

DisplayMessage returns the sanitized, bounded message for a transcript error: ErrorMessage with ANSI escapes, control characters, and GHA workflow command markers stripped, or the subtype fallback when it sanitizes to empty (both fields are omitempty in the transcript). ErrorMessage is truncated at parse time; Subtype is not, so the fallback applies the same truncateError bound before sanitizing. Every sink that renders a transcript error — GHA annotations, the CLI console, span status and events — goes through this one method so the treatments agree.

type TranscriptHandler

type TranscriptHandler interface {
	ExtractTranscripts(sandboxName, agentLabel, outputDir string) error
	ExtractDebugLog(sandboxName, localPath, debug string) error
	ParseTranscriptErrors(transcriptDir string) []TranscriptError
	// ParseTranscriptFile parses a single JSONL transcript or output file
	// and returns the last result event, if any. Use this to check a tee'd
	// output.jsonl for is_error:true without scanning an entire directory.
	ParseTranscriptFile(path string) (TranscriptError, bool)
	EmitTranscriptErrors(w io.Writer, summaries []TranscriptError)
}

TranscriptHandler extracts runtime conversation artifacts from the sandbox and surfaces errors in operator-facing logs (e.g. GitHub Actions annotations). Implementations are runtime-specific (Claude stream-json today).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL