harness

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Oct 29, 2026 License: AGPL-3.0 Imports: 5 Imported by: 0

Documentation

Overview

Package harness is the seam between the run pipeline and the coding-agent CLIs it drives (design/workstreams/agent/LLD/harness-adapters.md): the Adapter interface each harness implements (Codex in AGT-S1-T03, Claude Code in AGT-S1-T04, the scriptable fake in harness/fake), the Workspace the pipeline prepares for it, and the EventSink it reports progress, usage and rate limits to.

Index

Constants

View Source
const (
	KindTurn    = "turn"
	KindTool    = "tool"
	KindMessage = "message"
	KindError   = "error"
)

Progress event kinds.

View Source
const (
	LimitTurns     = "maxTurns"
	LimitWallClock = "maxWallClock"
	LimitCost      = "maxCostUSD"
)

Limit names.

View Source
const MaxSummary = 500

MaxSummary bounds a ProgressEvent's summary; full detail goes to the transcript.

View Source
const Placeholder = "factory-placeholder-not-a-credential"

Placeholder is the one placeholder credential a VM workspace carries where a tool refuses to start without one (CLAUDE_CODE_OAUTH_TOKEN, GH_TOKEN, codex's auth.json). It matches none of the transcript redactor's token patterns, and the gateway replaces whatever value it finds, so it never has to recognise this one.

Variables

This section is empty.

Functions

func IsLimit

func IsLimit(err error) bool

IsLimit reports whether err is (or wraps) a *LimitError.

Types

type Adapter

type Adapter interface {
	// Name is the harness's name: codex, claude-code.
	Name() string
	// Capabilities is static per adapter version: the effort mapping and features.
	Capabilities() v1alpha1.AdapterCapabilities
	// Prepare lays out the harness's own config in the workspace: the scratch config dir,
	// the skills in its layout, the MCP wiring.
	Prepare(ctx context.Context, ws Workspace, t v1alpha1.Task) error
	// Run runs the harness on prompt with t's resolved harness config and limits.
	Run(ctx context.Context, ws Workspace, t v1alpha1.Task, prompt string, sink EventSink) (Raw, error)
	// Repair asks the harness, in the same session where it can, to emit a valid Result only:
	// problems are the validation errors of the previous one.
	Repair(ctx context.Context, ws Workspace, problems []string, sink EventSink) (Raw, error)
}

Adapter drives one harness. The pipeline calls Prepare once, then Run, then at most one Repair when the Result was invalid. Run and Repair return when the harness exits or ctx is done; the pipeline cancels ctx on a limit (wall-clock, turns, cost) or a rate limit.

type EventSink

type EventSink interface {
	// Progress is one progress line.
	Progress(ProgressEvent)
	// Usage is usage since the previous call (a delta).
	Usage(UsageDelta)
	// RateLimited says the harness's plan limit is hit until the given time (zero when
	// unknown): the pipeline stops the run and hands the task back as throttled.
	RateLimited(until time.Time)
}

EventSink takes what a harness reports while it runs. Implementations are safe for concurrent use.

type LimitError

type LimitError struct {
	// Limit is maxTurns, maxWallClock or maxCostUSD.
	Limit  string
	Detail string
}

LimitError is returned by Run or Repair when the harness itself stopped on a limit (its own --max-turns, a budget flag).

func (*LimitError) Error

func (e *LimitError) Error() string

type Mount

type Mount struct {
	// Repo is owner/name; Ref the branch, tag or commit asked for ("" = default branch).
	Repo string
	Ref  string
	// Dir is the checkout.
	Dir      string
	Writable bool
}

Mount is one checked-out repo.

type ProgressEvent

type ProgressEvent struct {
	Kind    string
	Summary string
	At      time.Time
}

ProgressEvent is one normalised progress line. Each KindTurn event counts one turn against limits.maxTurns.

type Raw

type Raw struct {
	// Result is the harness's structured output, when it has one. The pipeline prefers the
	// file at Workspace.Result ($FACTORY_RESULT) when the run wrote it.
	Result []byte
	// Transcript is the harness's stream log as JSON Lines (one JSON value per line); lines
	// that aren't JSON are kept as text. It is redacted before upload.
	Transcript []byte
}

Raw is what one Run or Repair produced.

type Skill

type Skill struct {
	// Name is the skill's folder name; Plugin the plugin it belongs to.
	Name   string
	Plugin string
	// Dir is skills/<plugin>/skills/<name> (it holds SKILL.md); the plugin's root is
	// skills/<plugin>.
	Dir string
}

Skill is one materialised skill.

type UsageDelta

type UsageDelta struct {
	InputTokens  int64
	OutputTokens int64
	CostUSD      *float64
}

UsageDelta is usage since the previous report. CostUSD is nil for subscription runs.

type Workspace

type Workspace struct {
	// Root is workRoot/<taskID>, mode 0700.
	Root string
	// Repo is the primary checkout (repo/): the rw repo, or the task repo read-only. Empty
	// when the task checks nothing out.
	Repo string
	// RepoWritable is whether the harness may write Repo (a rw mount, or a checkout other
	// than read-only). Nothing in the VM enforces it: claude's write tools and PreToolUse hook
	// follow it, and codex is told in AGENTS.md (the gateway refuses the push either way).
	RepoWritable bool
	// Mounts are every checked-out repo, the primary first.
	Mounts []Mount
	// WorkDir is where the harness runs: Repo, else the first mount, else Root.
	WorkDir string
	// Skills is skills/: the selected ccf-skills, materialised as plugin directories
	// (<plugin>/.claude-plugin/plugin.json, the plugin's other root files such as bin/ and
	// rules/, and <plugin>/skills/<skill>/SKILL.md for the selected skills only). Each
	// plugin's bin/ is on Env's PATH, after Bin.
	Skills string
	// SkillList is every materialised skill.
	SkillList []Skill
	// Out is out/ ($FACTORY_OUT); Result is out/result.json ($FACTORY_RESULT).
	Out    string
	Result string
	// Schema is the JSON Schema file the Result must match (for --output-schema and
	// --json-schema).
	Schema string
	// Home is the harness's scratch HOME; Tmp its TMPDIR; Bin holds the `factory` CLI and
	// is first on PATH.
	Home string
	Tmp  string
	Bin  string
	// Env is the harness's whole environment (KEY=value), already reduced to the
	// allow-list: adapters append their own (CODEX_HOME, CLAUDE_CONFIG_DIR) and nothing from
	// the owner's environment.
	Env []string
	// Preamble is the headless preamble, also prepended to the prompt; adapters may put it
	// in the system prompt (AGENTS.md, --append-system-prompt).
	Preamble string
}

Workspace is the scratch directory the pipeline prepared for one run (run-pipeline.md §Steps 1): every path is absolute and inside Root.

Directories

Path Synopsis
Package claudecode is the Claude Code CLI harness adapter (design/workstreams/agent/LLD/ harness-adapters.md §Claude Code).
Package claudecode is the Claude Code CLI harness adapter (design/workstreams/agent/LLD/ harness-adapters.md §Claude Code).
Package clirun is what the harness adapters (codex, claudecode) share to drive a coding agent's CLI: running it in its own process group and killing the whole group when the run ends, splitting its stdout into lines for the stream parser, keeping a bounded transcript and stderr tail, and the text helpers their parsers need (rate-limit resets, versions, summaries).
Package clirun is what the harness adapters (codex, claudecode) share to drive a coding agent's CLI: running it in its own process group and killing the whole group when the run ends, splitting its stdout into lines for the stream parser, keeping a bounded transcript and stderr tail, and the text helpers their parsers need (rate-limit resets, versions, summaries).
Package codex is the Codex CLI harness adapter (design/workstreams/agent/LLD/ harness-adapters.md §Codex).
Package codex is the Codex CLI harness adapter (design/workstreams/agent/LLD/ harness-adapters.md §Codex).
Package fake is a scriptable harness.Adapter for pipeline and worker tests (harness-adapters.md §Fake adapter): scripted progress, usage and results, a scripted repair turn, and ways to simulate a rate limit or a run that only ends when it's stopped.
Package fake is a scriptable harness.Adapter for pipeline and worker tests (harness-adapters.md §Fake adapter): scripted progress, usage and results, a scripted repair turn, and ways to simulate a rate limit or a run that only ends when it's stopped.
Package harnesstest has what the harness adapters' tests share: a recording EventSink and an end-to-end rig that runs the real run pipeline against an in-process smart-HTTP git server and dispatcher.
Package harnesstest has what the harness adapters' tests share: a recording EventSink and an end-to-end rig that runs the real run pipeline against an in-process smart-HTTP git server and dispatcher.

Jump to

Keyboard shortcuts

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