kandev/apps/backend/internal/agent/agents/agent.go

// Package agents defines the Agent interface and supporting types.
// Each agent (Auggie, Claude Code, Codex, etc.) implements this interface
// in its own file, consolidating identity, discovery, models, protocol,
// execution, and runtime configuration in one place.
package agents

import (
	"context"
	"errors"
	"time"

	"github.com/kandev/kandev/pkg/agent"
)

// ErrNotSupported is returned when an agent does not support an operation.
var ErrNotSupported = errors.New("not supported by this agent")

// Agent is the core interface for all coding agents.
//
// Models are no longer part of this interface — they come from the host utility
// capability cache (which probes each ACP agent at boot to learn its models and
// modes via session/new). See internal/agent/hostutility.
type Agent interface {
	// --- Identity ---
	ID() string
	Name() string
	DisplayName() string
	Description() string
	Enabled() bool
	DisplayOrder() int // lower = higher priority in listings

	// --- Assets ---
	Logo(variant LogoVariant) []byte // nil if unavailable

	// --- Discovery ---
	IsInstalled(ctx context.Context) (*DiscoveryResult, error)

	// --- Execution ---
	BuildCommand(opts CommandOptions) Command

	// --- Permissions ---
	PermissionSettings() map[string]PermissionSetting

	// --- Runtime ---
	Runtime() *RuntimeConfig

	// --- Remote Auth ---
	// RemoteAuth returns the auth methods this agent supports in remote environments.
	// Returns nil if the agent has no remote auth configuration.
	RemoteAuth() *RemoteAuth

	// --- Installation ---
	// InstallScript returns shell commands to pre-install the agent CLI in remote environments.
	// Returns empty string if no installation is needed.
	InstallScript() string
}

// InferenceAgent is an optional capability marker for agents that support
// one-shot LLM inference via the host utility manager. The actual model list
// is populated dynamically from the ACP probe — agents no longer declare a
// static model list.
type InferenceAgent interface {
	// InferenceConfig returns the configuration for one-shot inference.
	InferenceConfig() *InferenceConfig
}

// PassthroughAgent is an optional capability for agents that support CLI passthrough mode.
type PassthroughAgent interface {
	PassthroughConfig() PassthroughConfig
	BuildPassthroughCommand(opts PassthroughOptions) Command
}

// LoginCommand describes an interactive CLI command for authenticating with
// an agent. The kandev backend runs this under a PTY so the UI can render a
// terminal and route keystrokes to the underlying process.
type LoginCommand struct {
	// Cmd is the command + args to spawn, e.g. []string{"claude", "auth", "login"}.
	Cmd []string
	// Description renders above the terminal as a one-line hint, e.g.
	// "Authenticate with your Anthropic account."
	Description string
}

// LoginAgent is an optional capability for agents that need an interactive
// login flow (browser OAuth callback, token prompt, etc.). Implement it to
// surface a "Login" button in the UI that opens a PTY-backed terminal running
// LoginCommand().
type LoginAgent interface {
	LoginCommand() *LoginCommand
}

// IsPassthroughOnly returns true if the agent only supports passthrough mode
// and should not have interactive MCP tools (e.g. ask_user_question) registered.
func IsPassthroughOnly(a Agent) bool {
	_, ok := a.(*TUIAgent)
	return ok
}

// LogoVariant selects light or dark logo.
type LogoVariant int

const (
	LogoLight LogoVariant = iota
	LogoDark
)

// DiscoveryResult is the result of checking if an agent is installed.
type DiscoveryResult struct {
	Available         bool
	MatchedPath       string
	SupportsMCP       bool
	MCPConfigPaths    []string
	InstallationPaths []string
	Capabilities      DiscoveryCapabilities
}

// DiscoveryCapabilities describes what the agent supports.
type DiscoveryCapabilities struct {
	SupportsSessionResume bool
	SupportsShell         bool
	SupportsWorkspaceOnly bool
}

// CommandOptions are passed to BuildCommand.
type CommandOptions struct {
	Model               string
	SessionID           string // for --resume flag
	ResumeAtMessageUUID string // for --resume-session-at flag (truncate conversation)
	AutoApprove         bool
	PermissionPolicy    string          // "autonomous", "supervised", "plan"
	PermissionValues    map[string]bool // e.g. {"allow_indexing": true}
	AgentType           string          // for --agent flag (e.g. "task" for subagent)
	// CLIFlagTokens are user-configured CLI flag argv tokens derived from
	// AgentProfile.CLIFlags (only Enabled entries, shell-tokenised). Appended
	// verbatim to the built command by every agent's BuildCommand.
	CLIFlagTokens []string
}

// PassthroughOptions are passed to BuildPassthroughCommand.
type PassthroughOptions struct {
	Model            string
	SessionID        string          // ACP session ID; resumes a specific session via --resume <id>
	Prompt           string          // initial prompt for new sessions
	Resume           bool            // generic "continue last session" (e.g. -c, --resume latest)
	PermissionValues map[string]bool // e.g. {"auto_approve": true}
	WorkDir          string
	// CLIFlagTokens are user-configured CLI flag argv tokens derived from
	// AgentProfile.CLIFlags (only Enabled entries, shell-tokenised). Appended
	// verbatim to the built passthrough command, mirroring CommandOptions.
	CLIFlagTokens []string
}

// RuntimeConfig holds Docker / standalone runtime settings.
type RuntimeConfig struct {
	Image          string
	Tag            string
	Cmd            Command
	Entrypoint     Command
	WorkingDir     string
	Env            map[string]string
	RequiredEnv    []string
	Mounts         []MountTemplate
	ResourceLimits ResourceLimits
	SessionConfig  SessionConfig
	Protocol       agent.Protocol
	ModelFlag      Param  // e.g. NewParam("--model", "{model}")
	WorkspaceFlag  string // e.g. "--workspace-root"
	AssumeMcpSse   bool   // Override: assume agent supports SSE MCP servers even if not advertised
}

// MountTemplate defines a mount with template variables.
type MountTemplate struct {
	Source   string `json:"source"`
	Target   string `json:"target"`
	ReadOnly bool   `json:"read_only"`
}

// ResourceLimits defines resource constraints.
type ResourceLimits struct {
	MemoryMB int64         `json:"memory_mb"`
	CPUCores float64       `json:"cpu_cores"`
	Timeout  time.Duration `json:"timeout"`
}

// SessionConfig defines session resumption behaviour.
type SessionConfig struct {
	NativeSessionResume     bool
	HistoryContextInjection bool // Opt-in: inject conversation history on session resume for agents without native resume
	ResumeFlag              Param
	CanRecover              *bool
	SessionDirTemplate      string
	SessionDirTarget        string
	ForkSessionCmd          Command
	ContinueSessionCmd      Command
}

// SupportsRecovery returns whether the agent supports session recovery.
// Returns true by default if CanRecover is not explicitly set.
func (c SessionConfig) SupportsRecovery() bool {
	if c.CanRecover == nil {
		return true
	}
	return *c.CanRecover
}

// PermissionApplyMethodCLIFlag is the PermissionSetting.ApplyMethod sentinel
// for permission flags that map to a CLI argument on the agent subprocess.
// A typo in any one caller (e.g. "cli-flag") silently breaks the seed and
// filter chain across agents, so the literal lives in exactly one place.
const PermissionApplyMethodCLIFlag = "cli_flag"

// PermissionSetting defines metadata for a permission setting option.
type PermissionSetting struct {
	Supported    bool   `json:"supported"`
	Default      bool   `json:"default"`
	Label        string `json:"label"`
	Description  string `json:"description"`
	ApplyMethod  string `json:"apply_method,omitempty"`
	CLIFlag      string `json:"cli_flag,omitempty"`
	CLIFlagValue string `json:"cli_flag_value,omitempty"`
}

// PassthroughConfig defines configuration for CLI passthrough mode.
type PassthroughConfig struct {
	Supported         bool
	Label             string
	Description       string
	PassthroughCmd    Command
	ModelFlag         Param
	PromptFlag        Param
	PromptPattern     string
	IdleTimeout       time.Duration
	BufferMaxBytes    int64
	StatusDetector    string
	CheckInterval     time.Duration
	StabilityWindow   time.Duration
	ResumeFlag        Param // generic "continue last session" (e.g. NewParam("-c"), NewParam("--resume", "latest"))
	SessionResumeFlag Param // resume a specific session by ID (e.g. NewParam("--resume"))
	WaitForTerminal   bool
}

// DefaultBufferMaxBytes is the default maximum buffer size for passthrough mode (2 MB).
const DefaultBufferMaxBytes int64 = 2 * 1024 * 1024

// DefaultResourceLimits is the standard resource limit set shared by most agents.
var DefaultResourceLimits = ResourceLimits{
	MemoryMB: 4096, CPUCores: 2.0, Timeout: time.Hour,
}

// InferenceConfig describes how an agent executes one-shot prompts via ACP.
type InferenceConfig struct {
	// Supported indicates the agent can do one-shot inference.
	Supported bool
	// Command is the ACP command for one-shot inference.
	// e.g., ["npx", "-y", "@agentclientprotocol/claude-agent-acp"]
	Command Command
	// ModelFlag is the flag template for specifying the model (e.g., ["--model", "{model}"]).
	ModelFlag Param
}

// InferenceModel describes a model available for inference.
type InferenceModel struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description"`
	IsDefault   bool   `json:"is_default"`
}

// RemoteAuth describes all auth methods an agent supports for remote environments.
type RemoteAuth struct {
	Methods []RemoteAuthMethod `json:"methods"`
}

// RemoteAuthMethod describes one way an agent can authenticate in a remote environment.
type RemoteAuthMethod struct {
	// Type is "env" (set env var via secret) or "files" (copy local files to remote).
	Type string `json:"type"`
	// EnvVar is the environment variable name (for type="env").
	EnvVar string `json:"env_var,omitempty"`
	// SetupHint is a UI hint for the user (for type="env").
	SetupHint string `json:"setup_hint,omitempty"`
	// SourceFiles maps OS name to relative paths from home dir (for type="files").
	// Keys: "darwin", "linux", "windows".
	SourceFiles map[string][]string `json:"source_files,omitempty"`
	// TargetRelDir is the target directory relative to the remote user home (for type="files").
	TargetRelDir string `json:"target_rel_dir,omitempty"`
	// Label is a UI label for the file copy option (for type="files").
	Label string `json:"label,omitempty"`
	// SetupScript is an optional shell script that runs on the remote after the
	// env var is resolved. Used to bootstrap credential files from env vars.
	// Only meaningful for type="env". Can reference the env var by name.
	SetupScript string `json:"setup_script,omitempty"`
}

// Command is a domain value type representing a CLI command with arguments.
// Serialize to []string only at system boundaries (process exec, Docker API, JSON DTOs).
type Command struct {
	args []string
}

// NewCommand creates a Command from the given arguments.
func NewCommand(args ...string) Command {
	return Command{args: append([]string{}, args...)}
}

// Args returns the raw string slice for serialization at system boundaries.
func (c Command) Args() []string {
	return c.args
}

// IsEmpty reports whether the command has no arguments.
func (c Command) IsEmpty() bool {
	return len(c.args) == 0
}

// With returns a CmdBuilder seeded with this command's arguments,
// allowing fluent extension without mutating the original.
func (c Command) With() *CmdBuilder {
	return &CmdBuilder{args: append([]string{}, c.args...)}
}

// Param is a command fragment — one or more pre-split CLI arguments
// (flags, flag+value pairs, templates with placeholders).
// Composed into a Command via CmdBuilder methods.
type Param struct {
	args []string
}

// NewParam creates a Param from the given arguments.
func NewParam(args ...string) Param {
	return Param{args: append([]string{}, args...)}
}

// Args returns the raw string slice.
func (p Param) Args() []string { return p.args }

// IsEmpty reports whether the param has no arguments.
func (p Param) IsEmpty() bool { return len(p.args) == 0 }