agent

package
v0.21.2 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 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

View Source
const (
	ProviderAnthropic        = "anthropic"
	ProviderOpenAI           = "openai"
	ProviderOpenRouter       = "openrouter"
	ProviderOpenAICompatible = "openai-compatible"
)

Provider types, the same strings the server stores.

View Source
const (
	DefaultAnthropicURL  = "https://api.anthropic.com"
	DefaultOpenAIURL     = "https://api.openai.com/v1"
	DefaultOpenRouterURL = "https://openrouter.ai/api/v1"
)

Default endpoints. Anthropic's is the host the Messages API appends /v1 to; the others are the base /chat/completions is appended to.

View Source
const BaseURLEnv = "SKAEL_PROVIDER_BASE_URL"

BaseURLEnv carries the endpoint into the sandbox. Its _BASE_URL suffix is what adds the host to the session's egress allowlist.

View Source
const OpenCodeVersion = "1.19.5"

OpenCodeVersion is the OpenCode release the sandbox image installs. A run records it as its agent version, so a score is never compared across releases of the harness. imagespec's Dockerfiles must install this version; a test pins the two together.

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.

--auto: isolation is the sandbox's job, not the CLI's. Without it OpenCode rejects every tool call that would ask for permission, and a headless session scores zero with nothing naming the cause.

func ModelRef added in v0.20.0

func ModelRef(model string) string

ModelRef is the -m value for a model on the session's provider.

func SessionEnv added in v0.20.0

func SessionEnv(b Backend) ([]string, error)

SessionEnv is the environment one session needs: OpenCode's config, which defines a single provider and model, and the key it references.

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 Backend added in v0.20.0

type Backend struct {
	Type    string
	BaseURL string
	Key     string
	// AuthHeader sends the key in this header instead of as a bearer token.
	// Only an openai-compatible provider uses it.
	AuthHeader string
	Model      string
	Cost       *Cost
}

Backend is one provider and model a session runs against.

func (Backend) Endpoint added in v0.20.0

func (b Backend) Endpoint() string

Endpoint is the base URL a provider type uses when none is set.

type Caps

type Caps struct {
	EventTier               string
	ModelFlag               string
	SkillDir                string
	SupportsSkillInvocation bool
}

Caps describes what an adapter can do.

type Cost added in v0.20.0

type Cost struct {
	Input      float64 `json:"input"`
	Output     float64 `json:"output"`
	CacheRead  float64 `json:"cache_read,omitempty"`
	CacheWrite float64 `json:"cache_write,omitempty"`
}

Cost is a model's price in US dollars per million tokens.

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
	// CostUSD is what the provider charged, as the harness priced it. Zero
	// when the model had no price in the session config.
	CostUSD float64
	IsError bool
	// Error is the harness's own message for the first error it reported.
	Error string
}

Meta is session-level telemetry reported alongside the trajectory.

type OpenCode added in v0.20.0

type OpenCode struct{}

OpenCode adapts the OpenCode CLI, the one harness every panel session runs in.

func New added in v0.11.0

func New() *OpenCode

New returns the OpenCode adapter.

func (*OpenCode) Caps added in v0.20.0

func (a *OpenCode) Caps() Caps

Caps reports OpenCode's capabilities.

func (*OpenCode) InstallSkill added in v0.20.0

func (a *OpenCode) InstallSkill(workspace, bundlePath string) error

InstallSkill copies a skill bundle into the workspace's project-local skill directory.

func (*OpenCode) Invoke added in v0.20.0

func (a *OpenCode) Invoke(ctx context.Context, s InvokeSpec) (RawStream, error)

Invoke runs one headless session and returns the native stream verbatim.

func (*OpenCode) Name added in v0.20.0

func (a *OpenCode) Name() string

Name identifies the adapter in reports and panel matrices.

func (*OpenCode) Parse added in v0.20.0

func (a *OpenCode) Parse(r RawStream) (*Result, error)

Parse converts an OpenCode JSON stream into normalized events. Malformed lines are skipped, not fatal.

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