Documentation
¶
Overview ¶
Package agent defines the interface every coding-agent CLI is driven through.
Index ¶
Constants ¶
const ( ProviderAnthropic = "anthropic" ProviderOpenAI = "openai" ProviderOpenRouter = "openrouter" ProviderOpenAICompatible = "openai-compatible" )
Provider types, the same strings the server stores.
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.
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.
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 ¶
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 SessionEnv ¶ added in v0.20.0
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.
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.
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 ¶
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 (*OpenCode) InstallSkill ¶ added in v0.20.0
InstallSkill copies a skill bundle into the workspace's project-local skill directory.
func (*OpenCode) Invoke ¶ added in v0.20.0
Invoke runs one headless session and returns the native stream verbatim.