Agent Adapters

type Agent interface {
    // Name returns the agent's identifier (e.g., "claude", "codex").
    // Names must be lowercase and contain only alphanumeric characters
    // and hyphens.
    Name() string

    // Run executes a prompt and returns the result.
    // The context is used for cancellation and timeout.
    Run(ctx context.Context, opts RunOpts) (*RunResult, error)

    // CheckPrerequisites verifies that the agent CLI is installed and
    // accessible on $PATH. Returns a descriptive error when missing.
    CheckPrerequisites() error

    // ParseRateLimit examines agent output for rate-limit signals.
    // Returns rate-limit info and true if a limit was detected.
    ParseRateLimit(output string) (*RateLimitInfo, bool)

    // DryRunCommand returns the command string that would be executed
    // without running it. Used for --dry-run mode.
    DryRunCommand(opts RunOpts) string
}

type RunOpts struct {
    Prompt       string            // Prompt text to send to the agent
    PromptFile   string            // Path to a file containing the prompt (used when Prompt is large)
    WorkDir      string            // Working directory for the subprocess
    Model        string            // Override the configured model
    OutputFormat string            // Output format: "text", "json", "stream-json"
    StreamEvents chan<- StreamEvent // Channel for real-time JSONL events (stream-json mode)
    ExtraEnv     []string          // Additional environment variables
}

type RunResult struct {
    Stdout   string        // Captured standard output
    Stderr   string        // Captured standard error
    ExitCode int           // Process exit code
    Duration time.Duration // Wall-clock time of the subprocess
}

# Install via npm (official method)
npm install -g @anthropic-ai/claude-code

# Verify
claude --version

[agents.claude]
command         = "claude"                # Default: "claude"
model           = "claude-sonnet-4-6"    # Passed as --model
effort          = "high"                 # Sets CLAUDE_CODE_EFFORT_LEVEL env var
prompt_template = "implement"            # Template name in prompts/
allowed_tools   = "Edit,Write,Bash"      # Passed as --allowedTools

claude --permission-mode accept --print --model <model> \
       --allowedTools <tools> [--prompt-file <file>|--] \
       < <prompt>

claude --output-format stream-json ...

# Install via npm
npm install -g @openai/codex

# Verify
codex --version

[agents.codex]
command = "codex"     # Default: "codex"
model   = "o4-mini"  # Passed as --model

codex exec --sandbox --ephemeral -a never --model <model> \
           [--prompt <text>|--prompt-file <file>]

// ErrNotImplemented is returned by the Gemini adapter's Run and
// CheckPrerequisites methods until the adapter is fully implemented.
var ErrNotImplemented = errors.New("gemini adapter not yet implemented")

type ProviderState struct {
    IsLimited   bool
    ResetAt     time.Time
    WaitCount   int
    LastMessage string
    UpdatedAt   time.Time
}

type BackoffConfig struct {
    DefaultWait  time.Duration // Default wait when no reset time is available (default: 60s)
    MaxWaits     int           // Maximum wait cycles before giving up (default: 5)
    JitterFactor float64       // Random jitter fraction added to wait (default: 0.1)
}

registry := agent.NewRegistry()
registry.Register(agent.NewClaudeAgent(claudeCfg, logger))
registry.Register(agent.NewCodexAgent(codexCfg, logger))

ag, err := registry.Get("claude")

package agent

import (
    "context"
    "fmt"
    "os/exec"
)

var _ Agent = (*MyAgent)(nil)

type MyAgent struct {
    config AgentConfig
}

func NewMyAgent(cfg AgentConfig) *MyAgent {
    return &MyAgent{config: cfg}
}

func (a *MyAgent) Name() string { return "my-agent" }

func (a *MyAgent) Run(ctx context.Context, opts RunOpts) (*RunResult, error) {
    // Build and run the CLI subprocess
    cmd := exec.CommandContext(ctx, a.config.Command, "--prompt", opts.Prompt)
    out, err := cmd.CombinedOutput()
    if err != nil {
        return nil, fmt.Errorf("my-agent: %w", err)
    }
    return &RunResult{Stdout: string(out), ExitCode: 0}, nil
}

func (a *MyAgent) CheckPrerequisites() error {
    if _, err := exec.LookPath(a.config.Command); err != nil {
        return fmt.Errorf("my-agent CLI not found: %w", err)
    }
    return nil
}

func (a *MyAgent) ParseRateLimit(output string) (*RateLimitInfo, bool) {
    // Return nil, false if the agent does not enforce rate limits
    return nil, false
}

func (a *MyAgent) DryRunCommand(opts RunOpts) string {
    return fmt.Sprintf("%s --prompt %q", a.config.Command, opts.Prompt[:min(len(opts.Prompt), 80)])
}