Codewalkers/src/agent/types.ts

/**
 * Agent Module Types
 *
 * Port interface for agent lifecycle management.
 * AgentManager is the PORT. Implementations are ADAPTERS.
 */

export type AgentStatus = 'idle' | 'running' | 'waiting_for_input' | 'stopped' | 'crashed';

/**
 * Agent operation mode.
 *
 * - execute: Standard task execution (default)
 * - discuss: Gather context through questions, output decisions
 * - breakdown: Decompose initiative into phases
 * - decompose: Decompose phase into individual tasks
 */
export type AgentMode = 'execute' | 'discuss' | 'breakdown' | 'decompose';

/**
 * Options for spawning a new agent
 */
export interface SpawnAgentOptions {
  /** Human-readable name for the agent (e.g., 'gastown', 'chinatown') */
  name: string;
  /** Task ID to assign to agent */
  taskId: string;
  /** Initial prompt/instruction for the agent */
  prompt: string;
  /** Optional working directory (defaults to worktree path) */
  cwd?: string;
  /** Agent operation mode (defaults to 'execute') */
  mode?: AgentMode;
}

/**
 * Represents a Claude agent instance
 */
export interface AgentInfo {
  /** Unique identifier for this agent */
  id: string;
  /** Human-readable name for the agent */
  name: string;
  /** Task this agent is working on */
  taskId: string;
  /** Claude CLI session ID for resumption (null until first run completes) */
  sessionId: string | null;
  /** WorktreeManager worktree ID */
  worktreeId: string;
  /** Current status (waiting_for_input = paused on AskUserQuestion) */
  status: AgentStatus;
  /** Current operation mode */
  mode: AgentMode;
  /** When the agent was created */
  createdAt: Date;
  /** Last activity timestamp */
  updatedAt: Date;
}

/**
 * Result from agent execution
 */
export interface AgentResult {
  /** Whether the task completed successfully */
  success: boolean;
  /** Result message or error description */
  message: string;
  /** Files modified during execution */
  filesModified?: string[];
}

/**
 * Individual question item with unique ID for answer matching
 */
export interface QuestionItem {
  /** Unique identifier for matching answers */
  id: string;
  /** The question being asked */
  question: string;
  /** Optional predefined options for the question */
  options?: Array<{ label: string; description?: string }>;
  /** Whether multiple options can be selected */
  multiSelect?: boolean;
}

/**
 * Pending questions when agent is waiting for input
 */
export interface PendingQuestions {
  /** Array of questions the agent is asking */
  questions: QuestionItem[];
}

/**
 * AgentManager Port Interface
 *
 * Manages Claude agent lifecycle - spawn, stop, list, resume.
 *
 * Covers requirements:
 * - AGENT-01: Spawn new agent with task assignment
 * - AGENT-02: Stop running agent
 * - AGENT-03: List all agents with status
 * - AGENT-04: Resume agent session
 * - AGENT-05: Background mode (implementation detail)
 */
export interface AgentManager {
  /**
   * Spawn a new agent to work on a task.
   *
   * Creates isolated worktree, starts Claude SDK session,
   * and begins executing the prompt.
   *
   * @param options - Spawn configuration
   * @returns Agent info with session ID for later resumption
   */
  spawn(options: SpawnAgentOptions): Promise<AgentInfo>;

  /**
   * Stop a running agent.
   *
   * Gracefully stops the agent's work. Worktree is preserved
   * for potential resumption.
   *
   * @param agentId - Agent to stop
   */
  stop(agentId: string): Promise<void>;

  /**
   * List all agents with their current status.
   *
   * @returns Array of all agents
   */
  list(): Promise<AgentInfo[]>;

  /**
   * Get a specific agent by ID.
   *
   * @param agentId - Agent ID
   * @returns Agent if found, null otherwise
   */
  get(agentId: string): Promise<AgentInfo | null>;

  /**
   * Get a specific agent by name.
   *
   * @param name - Agent name (human-readable)
   * @returns Agent if found, null otherwise
   */
  getByName(name: string): Promise<AgentInfo | null>;

  /**
   * Resume an agent that's waiting for input.
   *
   * Used when agent paused on questions and user provides responses.
   * Uses stored session ID to continue with full context.
   * Agent must be in 'waiting_for_input' status.
   *
   * @param agentId - Agent to resume
   * @param answers - Map of question ID to user's answer
   */
  resume(agentId: string, answers: Record<string, string>): Promise<void>;

  /**
   * Get the result of an agent's work.
   *
   * Only available after agent completes or stops.
   *
   * @param agentId - Agent ID
   * @returns Result if available, null if agent still running
   */
  getResult(agentId: string): Promise<AgentResult | null>;

  /**
   * Get pending questions for an agent waiting for input.
   *
   * Only available when agent status is 'waiting_for_input'.
   *
   * @param agentId - Agent ID
   * @returns Pending questions if available, null otherwise
   */
  getPendingQuestions(agentId: string): Promise<PendingQuestions | null>;
}