agent

Documentation

Index

• Constants
• Variables
• type Agent
• type Message
• type PermissionInfo
• type PromptType
• type Response

Constants

const ResponseBufSize = 64

ResponseBufSize is the per-user response channel buffer size.

Variables

var ErrNoSession = errors.New("no active session")

ErrNoSession is returned when an operation requires an active session but none exists.

Types

type Agent

type Agent interface {
	Name() string
	// Send sends a message to the user's agent session. Non-blocking.
	// Responses arrive asynchronously via the channel returned by Subscribe.
	Send(ctx context.Context, userID string, msg Message) error
	// Control sends a control action (confirm/deny/select). Non-blocking.
	// Returns handled=true if there was an active prompt that consumed the action.
	// Returns handled=false if no prompt was active (caller should treat input as normal message).
	Control(ctx context.Context, userID string, action types.Action) (handled bool, err error)
	// Subscribe returns a channel that receives all responses for a user.
	// Created on first call, persists until Close.
	Subscribe(userID string) <-chan *Response
	// Restart restarts the user's session with new flags.
	Restart(ctx context.Context, userID string, flags map[string]string) (bool, error)
	// RawInput sends text directly to the agent's terminal (bypasses MCP).
	RawInput(ctx context.Context, userID string, input string) error
	// RespawnSession switches the user's session to a different working directory.
	// Idempotent: no-op if already running in the given workDir.
	// resumeOpt: "" = fresh session, "continue" = most recent, "<id>" = resume specific session.
	RespawnSession(ctx context.Context, userID, workDir, resumeOpt string) (changed bool, err error)
	// CLICommands returns the agent's CLI command whitelist (e.g. /model, /fast).
	CLICommands() []string
	// ActiveSessions returns all active session IDs (senderIDs).
	ActiveSessions() []string
	Close(userID string) error
	CloseAll() error
}

Agent is an AI backend (Claude Code, Codex, etc.).

type Message

type Message struct {
	Text       string            // formatted text (includes media path annotations)
	MediaFiles []types.MediaFile // attached media files (local paths)
}

Message is sent to the agent for processing.

type PermissionInfo

type PermissionInfo struct {
	ToolName     string
	Description  string
	InputPreview string
}

PermissionInfo carries details about a permission request from the agent.

type PromptType

type PromptType int

PromptType indicates whether a response requires user interaction.

const (
	PromptNone PromptType = iota

	PromptPermission  // permission approval needed
	PromptInteractive // terminal interactive prompt (numbered options, y/n)
	PromptElicitation // MCP elicitation request (accept/decline)
	PromptTUIMenu     // TUI cursor menu from agent CLI command (/model, /fast)
)

type Response

type Response struct {
	Text       string          // reply text
	Files      []string        // file paths extracted from the reply
	Prompt     PromptType      // whether this response is a prompt requiring user action
	PromptText string          // raw prompt content (from runtime capture)
	Options    []string        // available options ["1","2","3"] or ["yes","no"]
	Permission *PermissionInfo // set when Prompt is PromptPermission or PromptElicitation
}

Response is the agent's reply.