Documentation
¶
Index ¶
- Constants
- func DebugLogNameFor(candidates ...any) string
- func WantsClaudeMDBridge(rt Runtime) bool
- type AgentEvent
- type Backend
- 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 ContextBridger
- type DebugLogNamer
- 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 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 (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 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 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 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 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
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 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 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
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 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
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 removes the previous iteration's outputs and sessions so transcripts and output files are per-iteration.
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 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
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.
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 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"`
}
RunMetrics collects execution statistics from stream parsing.
type RunParams ¶
type RunParams struct {
SandboxName string
AgentBaseName string
Model string
Effort 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
}
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).