Documentation
¶
Index ¶
- Constants
- func AgentDefinitionModel(path string) string
- func DebugLogNameFor(candidates ...any) string
- func EffectiveModel(runModel, agentModel string) string
- func NeedsOpenAIProvider(backend, runModel, agentModel string, configAliases map[string]string) bool
- func PiOpenAIAuthSeed(configDir string) string
- func TerminateStrayProcesses(sandboxName string, w io.Writer)
- func WantsClaudeMDBridge(rt Runtime) bool
- type AgentEvent
- type Backend
- func Default() Backend
- func Resolve(name string) (Backend, error)
- func ResolveForAgent(agents []config.AgentEntry, repoRuntime, agent string) (Backend, bool, error)
- func ResolveFromConfig(cfg config.OrgConfigReader) (Backend, error)
- func ResolveFromPerRepoConfig(cfg config.PerRepoConfigReader) (Backend, error)
- type BehaviourOpResult
- type BehaviourOperation
- type BehaviourResults
- type BehaviourScript
- type BootstrapInput
- type ClaudeRuntime
- func (r ClaudeRuntime) Bootstrap(input BootstrapInput) error
- func (r ClaudeRuntime) ClearIterationArtifacts(sandboxName string) error
- func (ClaudeRuntime) ConfigDir() string
- func (ClaudeRuntime) DebugLogName() string
- func (ClaudeRuntime) EmitTranscriptErrors(w io.Writer, summaries []TranscriptError)
- func (r ClaudeRuntime) EnvExports() []string
- func (r ClaudeRuntime) ExtractDebugLog(sandboxName, localPath, debug string) error
- func (r ClaudeRuntime) ExtractTranscripts(sandboxName, agentLabel, outputDir string) error
- func (ClaudeRuntime) Name() string
- func (ClaudeRuntime) NeedsClaudeMDBridge() bool
- func (ClaudeRuntime) ParseTranscriptErrors(transcriptDir string) []TranscriptError
- func (ClaudeRuntime) ParseTranscriptFile(path string) (TranscriptError, bool)
- func (ClaudeRuntime) Run(ctx context.Context, params RunParams, printer *ui.Printer, start time.Time, ...) (int, error)
- func (ClaudeRuntime) System() string
- func (ClaudeRuntime) WorkspaceDir() string
- type CodexRuntime
- func (r CodexRuntime) Bootstrap(input BootstrapInput) error
- func (r CodexRuntime) ClearIterationArtifacts(sandboxName string) error
- func (CodexRuntime) ConfigDir() string
- func (CodexRuntime) DebugLogName() string
- func (CodexRuntime) EmitTranscriptErrors(w io.Writer, summaries []TranscriptError)
- func (r CodexRuntime) EnvExports() []string
- func (r CodexRuntime) ExtractDebugLog(sandboxName, localPath, debug string) error
- func (r CodexRuntime) ExtractTranscripts(sandboxName, agentLabel, outputDir string) error
- func (CodexRuntime) Name() string
- func (r CodexRuntime) OpenAIAuthFile() string
- func (r CodexRuntime) OpenAIAuthSeed() string
- func (CodexRuntime) ParseTranscriptErrors(transcriptDir string) []TranscriptError
- func (CodexRuntime) ParseTranscriptFile(path string) (TranscriptError, bool)
- func (r CodexRuntime) Run(ctx context.Context, params RunParams, printer *ui.Printer, start time.Time, ...) (int, error)
- func (CodexRuntime) System() string
- func (CodexRuntime) WorkspaceDir() string
- type ContextBridger
- type DebugLogNamer
- type DummyPlaybackRuntime
- func (r DummyPlaybackRuntime) Bootstrap(input BootstrapInput) error
- func (r DummyPlaybackRuntime) ClearIterationArtifacts(sandboxName string) error
- func (DummyPlaybackRuntime) ConfigDir() string
- func (DummyPlaybackRuntime) EmitTranscriptErrors(w io.Writer, summaries []TranscriptError)
- func (DummyPlaybackRuntime) EnvExports() []string
- func (DummyPlaybackRuntime) ExtractDebugLog(_ string, _ string, _ string) error
- func (DummyPlaybackRuntime) ExtractTranscripts(_ string, _ string, _ string) error
- func (DummyPlaybackRuntime) Name() string
- func (DummyPlaybackRuntime) ParseTranscriptErrors(_ string) []TranscriptError
- func (DummyPlaybackRuntime) ParseTranscriptFile(_ string) (TranscriptError, bool)
- func (r DummyPlaybackRuntime) Run(ctx context.Context, params RunParams, printer *ui.Printer, _ time.Time, ...) (int, error)
- func (DummyPlaybackRuntime) System() string
- func (DummyPlaybackRuntime) WorkspaceDir() string
- type DummyRuntime
- func (r DummyRuntime) Bootstrap(input BootstrapInput) error
- func (r DummyRuntime) ClearIterationArtifacts(sandboxName string) error
- func (DummyRuntime) ConfigDir() string
- func (DummyRuntime) EmitTranscriptErrors(w io.Writer, summaries []TranscriptError)
- func (DummyRuntime) EnvExports() []string
- func (DummyRuntime) ExtractDebugLog(_ string, _ string, _ string) error
- func (DummyRuntime) ExtractTranscripts(_ string, _ string, _ string) error
- func (DummyRuntime) Name() string
- func (DummyRuntime) ParseTranscriptErrors(_ string) []TranscriptError
- func (DummyRuntime) ParseTranscriptFile(_ string) (TranscriptError, bool)
- func (r DummyRuntime) Run(ctx context.Context, params RunParams, printer *ui.Printer, _ time.Time, ...) (int, error)
- func (DummyRuntime) System() string
- func (DummyRuntime) WorkspaceDir() string
- type ErrorEvent
- type EventRenderer
- type InitEvent
- type ModelUsage
- type OpenAICredentialSeeder
- type OpenCodeRuntime
- func (OpenCodeRuntime) Bootstrap(_ BootstrapInput) error
- func (OpenCodeRuntime) ClearIterationArtifacts(_ string) error
- func (OpenCodeRuntime) ConfigDir() string
- func (OpenCodeRuntime) EmitTranscriptErrors(w io.Writer, summaries []TranscriptError)
- func (OpenCodeRuntime) EnvExports() []string
- func (OpenCodeRuntime) ExtractDebugLog(_, _, _ string) error
- func (OpenCodeRuntime) ExtractTranscripts(_, _, _ string) error
- func (OpenCodeRuntime) Name() string
- func (OpenCodeRuntime) ParseTranscriptErrors(_ string) []TranscriptError
- func (OpenCodeRuntime) ParseTranscriptFile(_ string) (TranscriptError, bool)
- func (OpenCodeRuntime) Run(_ context.Context, _ RunParams, _ *ui.Printer, _ time.Time, _ *RunMetrics) (int, error)
- func (OpenCodeRuntime) System() string
- func (OpenCodeRuntime) WorkspaceDir() string
- type PiRuntime
- func (r PiRuntime) Bootstrap(input BootstrapInput) error
- func (r PiRuntime) ClearIterationArtifacts(sandboxName string) error
- func (PiRuntime) ConfigDir() string
- func (PiRuntime) DebugLogName() string
- func (PiRuntime) EmitTranscriptErrors(w io.Writer, summaries []TranscriptError)
- func (r PiRuntime) EnvExports() []string
- func (r PiRuntime) ExtractDebugLog(sandboxName, localPath, debug string) error
- func (r PiRuntime) ExtractTranscripts(sandboxName, agentLabel, outputDir string) error
- func (PiRuntime) Name() string
- func (r PiRuntime) OpenAIAuthFile() string
- func (r PiRuntime) OpenAIAuthSeed() string
- func (PiRuntime) ParseTranscriptErrors(transcriptDir string) []TranscriptError
- func (PiRuntime) ParseTranscriptFile(path string) (TranscriptError, bool)
- func (r PiRuntime) Run(ctx context.Context, params RunParams, printer *ui.Printer, start time.Time, ...) (int, error)
- func (PiRuntime) System() string
- func (PiRuntime) WorkspaceDir() string
- type PlaybackEntry
- type Playlist
- type PluginInput
- type ResultEvent
- type RetryEvent
- type RunMetrics
- type RunParams
- type Runtime
- type SandboxHooksBootstrap
- type TextEvent
- type ThinkingEvent
- type TokensEvent
- type ToolUseEvent
- type TranscriptError
- type TranscriptHandler
Constants ¶
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.
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
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
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
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, configAliases map[string]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. configAliases is the repo's models.aliases (nil if unset), threaded through so an alias remapped to an openai id resolves to the same provider here as it does in buildPiRunCommand.
func PiOpenAIAuthSeed ¶ added in v0.38.0
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 TerminateStrayProcesses ¶ added in v0.42.0
TerminateStrayProcesses sweeps the sandbox after the runner ended an iteration at its budget. OpenShell's exec timeout drops the relay and leaves the command running under PID 1, so without this the agent keeps spending and writing until the sandbox is deleted (#7042). Warning-only, like the between-iteration sweep.
func WantsClaudeMDBridge ¶ added in v0.37.0
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 ResolveForAgent ¶ added in v0.38.0
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
// Plugins returns the harness's declared plugin directories (ADR 0094),
// each tagged with the runtime format it is in. A runtime loads the
// entries of its own kind and names and skips the rest.
Plugins() []PluginInput
// ModelAliases returns the per-repo model alias overrides from
// .fullsend/config.yaml (models.aliases). A nil map means no overrides.
// Used by the pi runtime to thread the overrides into sub-agent dispatch
// so children resolve aliases the same way the parent does (#7020).
ModelAliases() map[string]string
// AgentSubagents returns the per-agent subagents map from the merged
// config agents: entry for this run's agent. Keys are persona names
// (or "default"); values are model references (nil = tombstone).
// Used by the pi runtime to resolve each persona's model (#7031).
AgentSubagents() map[string]*string
// ParentModel returns the model this run's agent actually runs on --
// after the agents: entry, --model and the alias remap -- or "" when
// the caller does not know it. The pi runtime adds it to the set a
// persona's model is checked against, so a persona pinned to the
// parent's own model is accepted even when that model is outside the
// alias table (#7031).
ParentModel() 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) 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) Name() string
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) 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) 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
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 ModelUsage ¶ added in v0.42.0
type ModelUsage struct {
Requests int `json:"requests"`
InputTokens int `json:"input_tokens"`
OutputTokens int `json:"output_tokens"`
CacheCreationInputTokens int `json:"cache_creation_input_tokens"`
CacheReadInputTokens int `json:"cache_read_input_tokens"`
CostUSD float64 `json:"cost_usd"`
}
ModelUsage is one model's token and cost contribution to a run. Requests counts the agent invocations attributed to the model (one for the parent iteration, one per sub-agent call).
func (*ModelUsage) Add ¶ added in v0.42.0
func (u *ModelUsage) Add(other ModelUsage)
Add accumulates other into u.
type OpenAICredentialSeeder ¶ added in v0.40.0
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.
Egress note for whoever lands it: opencode is exec'd directly, like Claude Code, not wrapped by node. The opencode-ai npm package ships bin/opencode.exe as a shell stub that postinstall.mjs replaces (link or copy) with the platform binary opencode-linux-x64/bin/opencode; with --ignore-scripts the stub stays. Whichever file the Containerfile ends up exec'ing is the name the inference profiles' binaries: globs must carry (**/opencode.exe or **/opencode), and runtimeEgressBinaries in internal/cli must list it, or every run dies on its first model call with policy_denied (fullsend#6971).
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) 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
ClearIterationArtifacts terminates processes the previous iteration left running (see killStrayProcesses), then removes its outputs and sessions so transcripts and output files are per-iteration. The sessions glob also takes the sub-agent session dirs (sessions/agent-<seq>/); the Agent extension's usage file lives outside them and is named explicitly, or a retry would re-count the first iteration's children.
func (PiRuntime) ConfigDir ¶ added in v0.37.0
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
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
EnvExports pins pi's config and session locations to runner-owned paths, disables all startup network traffic (update checks, package update checks, telemetry) and disables the module loader's on-disk transpile cache. 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).
JITI_FS_CACHE is not pi's own variable but jiti's, the loader pi imports every `-e` module through (createJiti in core/extensions/loader.ts passes no fsCache, so jiti resolves it from JITI_FS_CACHE, then JITI_CACHE, then true). jiti probes for a node_modules directory next to the module that created it — the bundled chunk under <pi>/dist/bundle/chunks/ in the published package, so <pi>/dist/bundle/chunks/node_modules/.cache/jiti — and falls back to $TMPDIR/jiti; in the sandbox image pi is root-installed and ships no such directory, so it is /tmp/jiti — writable by the agent and persistent across iterations. A cache entry is validated only against a ` /* v9-<hash of the source> */` trailer, so a body rewritten with the trailer left in place executes while the source file is untouched: that is a way around both the extension tree-hash preflight (piExtensionsGuard) and the hook adapter's SHA-256 check (piHooksGuard), neither of which can see it. Setting the variable to false makes jiti ignore any planted entry and create no cache directory at all (verified on pi 0.84.4, and jiti is still 2.7.0 at the pinned 0.85.0 — internal/runtime/testdata/pi/jiti-cache-check.sh reproduces both halves). Run re-exports these after the agent-writable .env is sourced, so the agent cannot switch the cache back on, and harness validation reserves the JITI_* family from extension env.
The cache is one lever of several: the rest of jiti's environment (JITI_ALIAS above all, which remaps a module specifier to another file) is cleared outright right after .env, on every provider path — see piLoaderEnvNames in pi_run.go.
func (PiRuntime) ExtractDebugLog ¶ added in v0.37.0
ExtractDebugLog downloads pi's stderr capture written when --debug is set.
func (PiRuntime) ExtractTranscripts ¶ added in v0.37.0
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. Sub-agent sessions (sessions/agent-<seq>/, written by the children fullsend-agent.js spawns) are saved as <agentLabel>-sub<seq>-<basename>, and the extension's usage file alongside them.
func (PiRuntime) OpenAIAuthFile ¶ added in v0.40.0
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
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
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
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
Playlist is the YAML committed to .fullsend/results/playlist.yaml. Results are 1-indexed: current=1 serves results[0].
type PluginInput ¶ added in v0.42.0
type PluginInput struct {
Name string
Path string
Kind pluginformat.Kind
Env map[string]string
PiArgs []string
}
PluginInput is one declared plugin: a host directory to upload, the sandbox name it is uploaded as, the format the directory is in, and the environment and pi options the harness gave it. Name is optional — the path basename is used when empty.
func (PluginInput) SandboxName ¶ added in v0.42.0
func (p PluginInput) SandboxName() string
SandboxName is the directory name the plugin takes in the sandbox: Name when set, else the path basename.
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
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"`
// PerModelUsage breaks the totals above down by the model spec that
// spent them. Runtimes that dispatch sub-agents (pi's Agent tool) fill
// it with one entry per child model plus the parent's own, so a run
// whose cost is dominated by children is legible in metrics.json;
// runtimes without sub-agents leave it nil and the totals stand alone.
PerModelUsage map[string]ModelUsage `json:"per_model_usage,omitempty"`
}
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 are the sandbox-side directories Claude Code is pointed at
// with --plugin-dir, one per Claude-format plugin the runner uploaded.
PluginDirs []string
// Plugins are the harness's declared plugins (host paths and formats),
// the same list Bootstrap received. PiRuntime.Run re-hashes the pi-format
// entries to render the sandbox preflight; other runtimes ignore them.
Plugins []PluginInput
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
// ModelAliases holds per-repo model alias overrides from
// .fullsend/config.yaml models.aliases (#6882). When a harness or
// agent model value is an alias key present in this map, the
// runtime translates it to the mapped id before passing it to the
// underlying CLI. An empty or nil map means no overrides; the
// runtime's compiled-in alias table is used as-is.
ModelAliases map[string]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
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 ¶
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).
Source Files
¶
- bootstrap.go
- claude.go
- claude_progress.go
- claude_transcript.go
- codex.go
- codex_bootstrap.go
- codex_config.go
- codex_integrity.go
- codex_progress.go
- codex_redact.go
- codex_run.go
- codex_transcript.go
- dummy.go
- dummy_playback.go
- event.go
- model.go
- openai_seeder.go
- opencode.go
- opencode_progress.go
- pi.go
- pi_agent.go
- pi_bootstrap.go
- pi_extensions.go
- pi_personas.go
- pi_progress.go
- pi_run.go
- pi_subagents.go
- pi_transcript.go
- registry.go
- renderer.go
- runtime.go
- sandbox_hooks_bootstrap.go
- sanitize.go
- stray_processes.go
- transcript.go