agent

package
v0.17.0 Latest Latest
Warning

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

Go to latest
Published: Nov 2, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package agent defines the interface every coding-agent CLI is driven through.

Index

Constants

This section is empty.

Variables

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.

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.

func All

func All() []Adapter

All returns every adapter this binary can drive.

func Get

func Get(name string) (Adapter, bool)

Get returns the adapter named name.

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 New added in v0.11.0

func New() *ClaudeCode

New returns a Claude Code adapter.

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

type InvokeSpec struct {
	Prompt string
	Model  string
	Exec   Exec
}

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.

type RawStream

type RawStream = io.Reader

RawStream is an agent's native output, verbatim.

type Result

type Result struct {
	Events []Event
	Meta   Meta
}

Result is a parsed session.

Jump to

Keyboard shortcuts

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