Documentation
¶
Overview ¶
Package agent defines the interface every coding-agent CLI is driven through.
Index ¶
Constants ¶
This section is empty.
Variables ¶
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.
Functions ¶
func Argv ¶ added in v0.11.0
func Argv(s InvokeSpec) ([]string, error)
Argv is the command line one evaluation session runs. Exported so the flags are pinned by a test without needing a CLI or daemon.
--permission-mode bypassPermissions: isolation is the sandbox's job, not the CLI's. The narrower acceptEdits prompts for Bash, so a headless session has every shell command denied and scores zero with nothing naming the cause.
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.
type Caps ¶
type Caps struct {
EventTier string
ModelFlag string
SkillDir string
// AuthDirs are host paths the sandbox mounts read-only for subscription
// auth. Local-development convenience only — does not work on headless
// workers, and carries nothing on macOS where the CLI uses the Keychain.
AuthDirs []string
// AuthEnv is preferred over AuthDirs: it works on a headless host with no
// interactive login. The runner forwards any of these that are set.
AuthEnv []string
SupportsSkillInvocation bool
}
Caps describes what an adapter can do.
type ClaudeCode ¶ added in v0.11.0
type ClaudeCode struct{}
ClaudeCode adapts the Claude Code CLI.
func (*ClaudeCode) Caps ¶ added in v0.11.0
func (a *ClaudeCode) Caps() Caps
Caps reports Claude Code's capabilities.
func (*ClaudeCode) InstallSkill ¶ added in v0.11.0
func (a *ClaudeCode) InstallSkill(workspace, bundlePath string) error
InstallSkill copies a skill bundle into the workspace's project-local skill directory.
func (*ClaudeCode) Invoke ¶ added in v0.11.0
func (a *ClaudeCode) Invoke(ctx context.Context, s InvokeSpec) (RawStream, error)
Invoke runs one headless session and returns the native stream verbatim.
func (*ClaudeCode) Name ¶ added in v0.11.0
func (a *ClaudeCode) Name() string
Name identifies the adapter in reports and panel matrices.
func (*ClaudeCode) Parse ¶ added in v0.11.0
func (a *ClaudeCode) Parse(r RawStream) (*Result, error)
Parse converts a Claude Code stream-json stream into normalized events. Malformed lines are skipped, not fatal. Events before the first timestamp are backfilled with it; a stream with no timestamp at all keeps the zero time.Time rather than a fabricated one.
type Event ¶ added in v0.11.0
type Event struct {
Seq int `json:"seq"`
TS time.Time `json:"ts"`
Type EventType `json:"type"`
Name string `json:"name,omitempty"`
Paths []string `json:"paths,omitempty"`
// ExitCode is a pointer so 0 is distinguishable from "not reported".
ExitCode *int `json:"exit_code,omitempty"`
}
Event is one normalized step in an agent's trajectory.
type EventType ¶ added in v0.11.0
type EventType string
EventType is the normalized event vocabulary every adapter maps onto.
const ( TypeMessage EventType = "message" TypeToolCall EventType = "tool_call" TypeToolResult EventType = "tool_result" TypeShell EventType = "shell" TypeFileRead EventType = "file_read" TypeFileWrite EventType = "file_write" TypeSkillRead EventType = "skill_read" TypeAskUser EventType = "ask_user" TypeOpaque EventType = "opaque" )
type Exec ¶
type Exec interface {
Exec(ctx context.Context, argv []string, stdout, stderr io.Writer) (exitCode int, err error)
}
Exec runs one command in a sandbox. Adapters build argv and hand it here; they never exec on the host. The executor rather than the sandbox, so flags stay in the adapter and containers stay out of it.
type InvokeSpec ¶
InvokeSpec is one session request. Workspace and timeout live on the sandbox.
type Meta ¶
type Meta struct {
AgentVersion string
Model string
InputTokens int64
OutputTokens int64
DurationMS int64
NumTurns int
VisibleSkills []string
PermissionDenials []string
RateLimited bool
// RateLimitUtilization is the highest window utilization seen, 0 when never
// reported, so an approaching limit is visible before it fails sessions.
RateLimitUtilization float64
RateLimitWindow string
IsError bool
}
Meta is session-level telemetry reported alongside the trajectory.