agent

package
v0.10.0 Latest Latest
Warning

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

Go to latest
Published: Aug 6, 2026 License: Apache-2.0 Imports: 6 Imported by: 0

Documentation

Overview

Package agent defines the interface every coding-agent CLI is driven through. Adding an agent means implementing this interface and recording a stream fixture; no scoring code changes.

Index

Constants

This section is empty.

Variables

View Source
var ErrInstallNotImplemented = errors.New("agent: InstallSkill not implemented")

ErrInstallNotImplemented is returned by adapters whose skill installation path is not built yet. Installing a skill requires knowledge of the agent's filesystem layout, which is why it is distinct from ErrInvokeNotImplemented.

View Source
var ErrInvokeNotImplemented = errors.New("agent: Invoke not implemented")

ErrInvokeNotImplemented is returned by adapters whose Invoke path is not built yet. Invoking an agent requires a sandbox, so it lands with the sandbox rather than with the parsers.

View Source
var ErrNoExecutor = errors.New("agent: Invoke needs an executor; a session must run in a sandbox")

ErrNoExecutor is returned when Invoke is called with no Exec. Failing closed is deliberate: an adapter that fell back to exec.Command would run an untrusted skill on the host.

View Source
var ErrParseNotImplemented = errors.New("agent: Parse not implemented — no recorded stream fixture for this CLI")

ErrParseNotImplemented is returned by adapters that have no verified stream fixture yet. Adapters fail closed: returning an empty Result would read downstream as a session in which the agent did nothing, scoring a working skill as a failure.

Functions

func Register

func Register(a Adapter)

Register adds an adapter. Called from adapter package init functions.

Types

type Adapter

type Adapter interface {
	Name() string
	Caps() Caps
	InstallSkill(workspace, bundlePath string) error
	Invoke(ctx context.Context, s InvokeSpec) (RawStream, error)
	Parse(r RawStream) (*Result, error)
}

Adapter drives one agent CLI.

func All

func All() []Adapter

All returns every registered adapter, ordered by name for stable output.

func Get

func Get(name string) (Adapter, bool)

Get returns the adapter registered under name.

type Caps

type Caps struct {
	// EventTier is "A" when the stream distinguishes individual tool calls and
	// their results, "B" when it only reports messages.
	EventTier string
	// ModelFlag is the CLI flag that selects a model, e.g. "--model".
	ModelFlag string
	// SkillDir is where a skill bundle installs, relative to the workspace.
	SkillDir string
	// AuthDirs are host paths the sandbox mounts read-only so subscription auth
	// works inside the container. This is a local-development convenience for
	// a machine that already has an interactive login — it does not work on a
	// headless worker with no such login, and it carries nothing on macOS for
	// a CLI that keeps its token in the Keychain rather than on disk.
	AuthDirs []string
	// AuthEnv names the environment variables this adapter's CLI understands
	// for authentication — names only, never values. The runner forwards any
	// of these that are set in the worker's own environment into the sandbox.
	// This is the preferred mechanism: it works on a headless host with no
	// interactive login, unlike AuthDirs above. Per-adapter by design, since
	// each agent CLI has its own.
	AuthEnv []string
	// SupportsSkillInvocation reports whether the stream exposes an explicit
	// skill-invocation event. When false, activation must be inferred from a
	// read of the skill's SKILL.md, which cannot distinguish read from invoked.
	SupportsSkillInvocation bool
}

Caps describes what an adapter can do, so the orchestrator can plan a panel without special-casing agent names.

type Exec

type Exec interface {
	Exec(ctx context.Context, argv []string, stdout, stderr io.Writer) (exitCode int, err error)
}

Exec runs one command somewhere an adapter does not choose. Adapters build argv and hand it here; they never exec on the host, because the entire point of running a skill under evaluation is that it runs in a sandbox. Passing the executor in rather than the sandbox keeps flags in the adapter and containers out of it — and makes argv assertable without a daemon.

type InvokeSpec

type InvokeSpec struct {
	Prompt string
	Model  string
	// Exec is where the CLI runs. Required.
	Exec Exec
}

InvokeSpec is one agent session request. Workspace, a session-level Timeout, and the installed skill's name are deliberately not here: the sandbox already knows the workspace and enforces the timeout (both are baked into Exec's underlying sandbox.RunSpec by the runner before Invoke is ever called), and no adapter names the skill in its own invocation — a field an adapter never reads but the runner always populates looks like a bound or a behavior it is not, which is exactly the trap for the next adapter author this exists to remove.

type Meta

type Meta struct {
	AgentVersion      string
	Model             string
	InputTokens       int64
	OutputTokens      int64
	DurationMS        int64
	NumTurns          int
	VisibleSkills     []string
	PermissionDenials []string
	RateLimited       bool
	IsError           bool
}

Meta is everything a parsed stream reports about the session itself, as opposed to the trajectory. Token counts feed Efficiency, VisibleSkills feeds trigger precision, and AgentVersion is recorded per run so a score can be attributed to a specific CLI build.

type RawStream

type RawStream = io.Reader

RawStream is an agent's native output, verbatim.

type Result

type Result struct {
	Events []trajectory.Event
	Meta   Meta
}

Result is a parsed session.

Directories

Path Synopsis
Package claudecode adapts the Claude Code CLI.
Package claudecode adapts the Claude Code CLI.
Package codex reserves the Codex CLI adapter.
Package codex reserves the Codex CLI adapter.
Package cursor reserves the Cursor CLI adapter.
Package cursor reserves the Cursor CLI adapter.
Package opencode reserves the OpenCode CLI adapter.
Package opencode reserves the OpenCode CLI adapter.

Jump to

Keyboard shortcuts

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