agents

Documentation

Overview

Package agents owns the daemon's compile-time agent identity catalog.

This package intentionally imports only the standard library. Feature domains (skills, usage, transcripts, hooks) register their own providers against ID values; the catalog never imports those domains.

Index

• Constants
• Variables
• func HasCapability(id ID, cap Capability) bool
• func LaunchLine(id ID, mode, cwd, value string) (string, error)
• func LaunchLineWith(id ID, mode, cwd, value string, opts LaunchOptions) (string, error)
• func ShellQuote(s string) string
• func ValidSessionID(id string) bool
• func ValidateID(id ID) error
• type Capability
• type Definition
  • func All() []Definition
  • func Lookup(id ID) (Definition, bool)
• type ID
  • func AutoPick(detected, enabled []ID) ID
  • func MatchArgv(command string) ID
  • func MatchProcess(name string) ID
• type KnownCLIAgent
• type LaunchOptions

Constants

const ExitSentinelShell = " ; printf '\\e]rmote-agent-exit\\a'"

ExitSentinelShell marks the return from an agent process in a PTY.

Variables

var KnownCLIAgents = []KnownCLIAgent{
	{ID: "openclaude", DisplayName: "OpenClaude", BinaryName: "openclaude", YoloArgs: "--dangerously-skip-permissions", AutoPickPriority: 50},
	{ID: "mimo-code", DisplayName: "MiMo Code", BinaryName: "mimo", YoloArgs: "", AutoPickPriority: 80},
	{ID: "ante", DisplayName: "Ante", BinaryName: "ante", YoloArgs: "--yolo", AutoPickPriority: 90},
	{ID: "trae", DisplayName: "Trae", BinaryName: "traecli", YoloArgs: "--yolo", AutoPickPriority: 100},
	{ID: "omp", DisplayName: "OMP", BinaryName: "omp", YoloArgs: "", AutoPickPriority: 120},
	{ID: "goose", DisplayName: "Goose", BinaryName: "goose", YoloArgs: "", AutoPickPriority: 150},
	{ID: "amp", DisplayName: "Amp", BinaryName: "amp", YoloArgs: "--dangerously-allow-all", AutoPickPriority: 160},
	{ID: "kilo", DisplayName: "Kilocode", BinaryName: "kilo", YoloArgs: "", AutoPickPriority: 170},
	{ID: "kiro", DisplayName: "Kiro", BinaryName: "kiro", YoloArgs: "--trust-all-tools", AutoPickPriority: 180},
	{ID: "crush", DisplayName: "Charm", BinaryName: "crush", YoloArgs: "--yolo", AutoPickPriority: 190},
	{ID: "aug", DisplayName: "Auggie", BinaryName: "aug", YoloArgs: "", AutoPickPriority: 200},
	{ID: "autohand", DisplayName: "Autohand Code", BinaryName: "autohand", YoloArgs: "--unrestricted", AutoPickPriority: 210},
	{ID: "cline", DisplayName: "Cline", BinaryName: "cline", YoloArgs: "--auto-approve true", AutoPickPriority: 220},
	{ID: "codebuff", DisplayName: "Codebuff", BinaryName: "codebuff", YoloArgs: "", AutoPickPriority: 230},
	{ID: "command-code", DisplayName: "Command Code", BinaryName: "command-code", YoloArgs: "--yolo", AutoPickPriority: 240},
	{ID: "continue", DisplayName: "Continue", BinaryName: "continue", YoloArgs: "--allow \"*\"", AutoPickPriority: 250},
	{ID: "droid", DisplayName: "Droid", BinaryName: "droid", YoloArgs: "", AutoPickPriority: 270},
	{ID: "kimi", DisplayName: "Kimi", BinaryName: "kimi", YoloArgs: "--yolo", AutoPickPriority: 280},
	{ID: "mistral-vibe", DisplayName: "Mistral Vibe", BinaryName: "mistral-vibe", YoloArgs: "--agent auto-approve", AutoPickPriority: 290},
	{ID: "rovo", DisplayName: "Rovo Dev", BinaryName: "rovo", YoloArgs: "--yolo", AutoPickPriority: 310},
	{ID: "hermes", DisplayName: "Hermes", BinaryName: "hermes", YoloArgs: "--yolo", AutoPickPriority: 320},
	{ID: "devin", DisplayName: "Devin", BinaryName: "devin", YoloArgs: "--permission-mode bypass", AutoPickPriority: 330},
	{ID: "openclaw", DisplayName: "OpenClaw", BinaryName: "openclaw", YoloArgs: "", AutoPickPriority: 340},
}

KnownCLIAgents lists coding-agent CLIs recognized for future adoption, in the recommended auto-pick order (lower priority = preferred default). To adopt one, create a Definition file (see claude.go) with verified Boot/Fresh/Resume grammar + capabilities, and remove the matching entry here. Binary names default to the ID where the release binary name was not confirmed; a few agents expose bypass via an env var rather than a flag (YoloArgs empty) — confirm at adoption.

Functions

func HasCapability

func HasCapability(id ID, cap Capability) bool

HasCapability reports whether id claims cap.

func LaunchLine

func LaunchLine(id ID, mode, cwd, value string) (string, error)

LaunchLine returns a trusted invocation for the catalogued agent. mode is boot, fresh, or resume. Unknown agents fail closed. LaunchOptions is empty (no model/effort, no bypass).

func LaunchLineWith

func LaunchLineWith(id ID, mode, cwd, value string, opts LaunchOptions) (string, error)

LaunchLineWith is the launch builder with full LaunchOptions. When opts.Bypass is true and the agent defines YoloArgs, the bypass flag is appended before the exit sentinel. When opts.Model or opts.Effort are non-empty, each agent's closure appends the appropriate flags (ShellQuoted). Resume also honors bypass so a reattached session keeps the same permission posture. YoloArgs is a trusted compile-time constant, so raw append into the PTY-written line is safe.

func ShellQuote

func ShellQuote(s string) string

func ValidSessionID

func ValidSessionID(id string) bool

func ValidateID

func ValidateID(id ID) error

ValidateID rejects malformed IDs before they become route or persistence keys.

Types

type Capability

type Capability string

Capability names are open strings. Unknown capabilities are ignored by clients; catalog conformance validates the capabilities implemented here.

const (
	CapLaunch        Capability = "launch"
	CapResume        Capability = "resume"
	CapProcessDetect Capability = "process_detect"
	CapImagePaste    Capability = "image_paste"
	CapCommitMessage Capability = "commit_message"
	CapSkills        Capability = "skills"
	CapUsage         Capability = "usage"
	CapQuota         Capability = "quota"
	CapHooks         Capability = "hooks"
	CapSystemPrompt  Capability = "system_prompt" // agent accepts a hidden appended system prompt (LaunchOptions.SystemPrompt)
)

type Definition

type Definition struct {
	ID          ID
	DisplayName string
	// Color is a brand/accent hex (e.g. "#4285F4") surfaced via /api/agents so
	// clients can render a per-agent badge color from a single source of truth.
	// Empty = client picks a fallback. Approximate, not official brand RGB.
	Color string
	// Badge is the short tab/card glyph (e.g. "AGY"). Empty = derive from the ID
	// (first 2 letters, uppercased) in agentsupport. Set when the ID's prefix is
	// ambiguous or not how users recognize the agent (e.g. antigravity → "AGY",
	// not "AN").
	Badge        string
	BinaryNames  []string
	Capabilities []Capability
	Boot         func(cwd string, opts LaunchOptions) string
	Fresh        func(cwd, prompt string, opts LaunchOptions) string
	Resume       func(cwd, sessionID string, opts LaunchOptions) string

	// Detection enrichment: trusted facts driving foreground process matching
	// (MatchProcess) and install checks (agentsupport.Snapshot), so adding an
	// agent needs no per-switch edits across the codebase.
	//
	// DetectAliases are extra exact basenames identifying the same agent.
	// DetectVersioned additionally accepts "<id>-<digit…>" release binaries
	// (e.g. grok-0.2.112-macos-aarch64); the digit guard excludes non-versioned
	// sidecars like a hypothetical grok-agent-runtime.
	// DetectPackages are package-manager package names (npm scopes, PyPI names)
	// used by MatchArgv to resolve interpreter-wrapped launches — e.g.
	// "npx @anthropic-ai/claude-code" or "uvx aider-chat" — where the process
	// basename is the interpreter (node/uvx), not the agent. MatchArgv scans
	// the tokens after an interpreter for these substrings, so a launch that
	// never exposes the agent's binary name is still recognized.
	DetectAliases             []string
	DetectVersioned           bool
	DetectPackages            []string
	DetectRequiredCommands    []string // companion binaries that must also be installed
	DetectUnsupportedRuntimes []string // GOOS values (e.g. "windows") where detection is suppressed

	// AutoPickPriority ranks this agent for empty-default selection (lower wins).
	// Zero excludes it from auto-pick.
	AutoPickPriority int

	// YoloArgs is the agent's bypass-permissions flag string (e.g. Claude's
	// "--dangerously-skip-permissions"). It is appended to a fresh launch line
	// ONLY when the user opts the agent into bypass mode (agentsupport state);
	// default launches are unaffected. These are trusted compile-time constants
	// appended to a PTY-written shell line.
	YoloArgs string

	// PasteReadyMarker is the literal byte sequence the iOS paste gate awaits,
	// after the bracketed-paste handshake (ESC[?2004h), before pasting a
	// "send to agent" draft into this agent's composer. Empty = use the
	// quiescence timer (the default). Example: codex sets "›" (its composer
	// glyph). Marker agents disable the quiet window (it fires too early in the
	// silent gap between the handshake and the composer mounting).
	PasteReadyMarker string
}

Definition contains trusted, compile-time facts only. It must not contain shell templates supplied by users or callbacks into feature domains.

A Definition is either launchable (CapLaunch + CapResume + Boot/Fresh/Resume) or detection-only (CapProcessDetect alone). Boot/Fresh/Resume, YoloArgs, and PasteReadyMarker apply only to launchable agents and are left zero on a detection-only Definition; see validateDefinition.

func All

func All() []Definition

All returns a stable copy of the catalog, excluding the shell.

func Lookup

func Lookup(id ID) (Definition, bool)

Lookup returns a catalog definition for id.

type ID

type ID string

ID is the stable wire, persistence, and registry key for an agent.

const (
	Shell  ID = "shell"
	Claude ID = "claude"
	Codex  ID = "codex"
	Grok   ID = "grok"
	// Antigravity is Google's CLI (`agy`, brew cask `antigravity-cli`); see
	// antigravity.go. Launchable but hookless (no hooks system).
	Antigravity ID = "antigravity"

	// Pi is the earendil-works pi coding-agent CLI (`pi`; npm
	// @earendil-works/pi-coding-agent). Launchable but hookless — its "hooks"
	// are programmatic JS/TS extension lifecycle events, not declarative
	// PreToolUse/PostToolUse shell-command hooks, so it claims no CapHooks and
	// the installer has no pi adapter. See pi.go.
	Pi ID = "pi"

	// Detection-only agents: recognized in a pane by foreground process match,
	// but not launchable from rmote until their CLI grammar is independently
	// verified. See the detection-only Definition variant (validateDefinition).
	Aider    ID = "aider"
	OpenCode ID = "opencode"
	QwenCode ID = "qwen-code"
	Cursor   ID = "cursor" // agent CLI binary is "cursor-agent" (see cursor.go)
	Copilot  ID = "copilot"
)

func AutoPick

func AutoPick(detected, enabled []ID) ID

AutoPick returns the preferred agent among the intersection of detected (installed) and enabled IDs, or "" if none qualify. Lower AutoPickPriority wins; 0 excludes an agent from auto-pick. Ties break by ID (All() is ID-sorted) for determinism.

func MatchArgv

func MatchArgv(command string) ID

MatchArgv maps a full process command line (as reported by `ps -o command=`) to an agent ID, or "" if no agent is recognized. It generalizes MatchProcess (which matches a single basename) by also resolving:

• leading env assignments: `FOO=bar claude` → claude;
• interpreter-wrapped launches: `npx @anthropic-ai/claude-code`, `uvx aider-chat`, `node /path/to/@openai/codex/bin/codex.js`.

Only agents claiming CapProcessDetect participate (MatchProcess enforces this for the direct path); only agents with DetectPackages can be resolved through an interpreter. Agents are scanned in stable ID order (All() is ID-sorted) so the match is deterministic.

func MatchProcess

func MatchProcess(name string) ID

MatchProcess maps a trusted process basename to an agent ID. Only agents claiming CapProcessDetect participate; an agent without it is never matched, so a tab never relabels to it from a stray process name.

type KnownCLIAgent

type KnownCLIAgent struct {
	ID               ID
	DisplayName      string
	BinaryName       string
	YoloArgs         string
	AutoPickPriority int
}

KnownCLIAgent is reference metadata for a coding-agent CLI that has not yet been adopted as a full catalog Definition. It captures the trusted facts needed to promote the agent later (display name, binary, bypass flag, auto- pick priority). Launch/resume grammar and feature capabilities are intentionally omitted — those must be verified against the agent's real CLI at adoption time. Entries here are NOT registered in the live catalog (All/Lookup) and never affect runtime behavior; they are a lookup table for future expansion.

type LaunchOptions

type LaunchOptions struct {
	Model        string // e.g. "claude-opus-5"
	Effort       string // e.g. "medium" — passed as --effort (Claude only)
	SystemPrompt string // hidden instruction, appended to the system prompt (CapSystemPrompt only)
	Bypass       bool   // from agentsupport.BypassEnabled, never from request
}

LaunchOptions carries per-profile model/effort selection and the bypass flag. Model and Effort are appended to the agent's launch line as CLI flags when non-empty. SystemPrompt is appended via the agent's hidden system-prompt channel when it has CapSystemPrompt (Claude: --append-system-prompt) — used to deliver orchestration instructions (e.g. "reply to the summoner") without cluttering the visible task prompt. Bypass is sourced exclusively from agentsupport state server-side — never from API request bodies.