@compilr-dev/cli 0.4.0 → 0.5.1

package/dist/repl-v2.d.ts

@@ -0,0 +1,554 @@
+/**
+ * REPL V2 - New Terminal UI based REPL
+ *
+ * Uses TerminalUI with:
+ * - Persistent footer (todo list + input prompt)
+ * - Overlay system for commands
+ * - Real agent integration (or simulation mode for testing)
+ *
+ * Can be run standalone: npx tsx src/repl-v2.ts
+ * Or imported and used with a real agent from index.ts
+ */
+import type { Agent } from '@compilr-dev/sdk';
+import type { AgentTeam } from './multi-agent/index.js';
+import { type PermissionResult, type PermissionOverlayV2Options } from './ui/overlay/impl/permission-overlay-v2.js';
+import { type AskUserSimpleOptionsV2, type AskUserSimpleResultV2 } from './ui/overlay/impl/ask-user-simple-overlay-v2.js';
+import { type GuardrailConfirmOptionsV2, type GuardrailConfirmResultV2 } from './ui/overlay/impl/guardrail-overlay-v2.js';
+import { type AskUserOptionsV2, type AskUserResultV2 } from './ui/overlay/impl/ask-user-overlay-v2.js';
+import { type IterationLimitOptionsV2, type IterationLimitResultV2 } from './ui/overlay/impl/iteration-limit-overlay-v2.js';
+export interface DelegateOverlayOptions {
+    agentId: string;
+    agentDisplayName: string;
+    task: string;
+    reason?: string;
+}
+export interface DelegateOverlayResult {
+    approved: boolean;
+}
+export interface ReplV2Options {
+    /** Agent instance (optional - uses simulation if not provided) */
+    agent?: Agent;
+    /** Multi-agent team (optional - for team management) */
+    team?: AgentTeam;
+    /** Agent factory function for creating new agents (for team switching) */
+    agentFactory?: (config: Record<string, unknown>, systemPromptAddition?: string, useMinimalSystemPrompt?: boolean, noTools?: boolean) => Promise<Agent>;
+    /** Current model ID */
+    model?: string;
+    /** Current provider */
+    provider?: string;
+    /** CLI version */
+    version?: string;
+    /** Update available info (if any) */
+    updateAvailable?: {
+        current: string;
+        latest: string;
+    } | null;
+    /** Initial project name */
+    projectName?: string;
+    /**
+     * Callback invoked when TerminalUI is ready.
+     * Allows index.ts to set up permission overlay callback.
+     */
+    onUIReady?: (showPermissionOverlay: (options: PermissionOverlayV2Options) => Promise<PermissionResult | null>) => void;
+    /**
+     * Callback invoked when text buffer flush function is ready.
+     * Allows index.ts to flush accumulated agent text before showing overlays.
+     */
+    onTextBufferReady?: (flushTextBuffer: () => void) => void;
+    /**
+     * Callback invoked when ask_user_simple overlay is ready.
+     * Allows index.ts to use V2 overlay for agent questions.
+     */
+    onAskUserSimpleReady?: (showOverlay: (options: AskUserSimpleOptionsV2) => Promise<AskUserSimpleResultV2>) => void;
+    /**
+     * Callback invoked when guardrail overlay is ready.
+     * Allows index.ts to use V2 overlay for guardrail confirmations.
+     */
+    onGuardrailReady?: (showOverlay: (options: GuardrailConfirmOptionsV2) => Promise<GuardrailConfirmResultV2>) => void;
+    /**
+     * Callback invoked when ask_user overlay is ready.
+     * Allows index.ts to use V2 overlay for multi-question forms.
+     */
+    onAskUserReady?: (showOverlay: (options: AskUserOptionsV2) => Promise<AskUserResultV2>) => void;
+    /**
+     * Callback invoked when iteration_limit overlay is ready.
+     * Allows index.ts to use V2 overlay for iteration limit prompts.
+     */
+    onIterationLimitReady?: (showOverlay: (options: IterationLimitOptionsV2) => Promise<IterationLimitResultV2>) => void;
+    /**
+     * Callback invoked when agent finishes processing.
+     * Allows index.ts to apply deferred actions like suggestions.
+     */
+    onAgentFinish?: () => void;
+    /**
+     * Callback invoked when suggestion setter is ready.
+     * Allows index.ts to set suggestions on the V2 UI.
+     */
+    onSuggestionReady?: (setSuggestion: (action: string | null) => void) => void;
+    /**
+     * Callback invoked when subagent tracking is ready.
+     * Allows index.ts to forward subagent events to LiveRegion for live rendering.
+     * Now uses toolUseId for direct correlation (no more FIFO queue matching).
+     */
+    onSubagentReady?: (callbacks: {
+        onStart: (toolUseId: string, agentType: string, description: string) => void;
+        onToolUse: (toolUseId: string, toolName: string, summary?: string) => void;
+        onEnd: (toolUseId: string, success: boolean, tokenCount: number, error?: string) => void;
+    }) => void;
+    /**
+     * Function to clear subagent tracking state in agent.ts between runs.
+     * Called at the start of each agent run to prevent stale data.
+     */
+    clearSubagentTracking?: () => void;
+    /**
+     * Whether to show the onboarding wizard on startup.
+     * Set to true for first-run experience.
+     */
+    showOnboarding?: boolean;
+    /**
+     * Whether to show the login overlay on startup.
+     * Set to true when user is not authenticated.
+     */
+    showLogin?: boolean;
+    /**
+     * Callback invoked when delegate overlay is ready.
+     * Allows index.ts to use V2 overlay for delegation approval.
+     */
+    onDelegateReady?: (showOverlay: (options: DelegateOverlayOptions) => Promise<DelegateOverlayResult>) => void;
+    /**
+     * Callback to get and clear pending delegation.
+     * Returns the pending delegation info if any, and clears it.
+     */
+    onPendingDelegation?: () => {
+        agentId: string;
+        task: string;
+    } | null;
+    /**
+     * Callback invoked when background agent tracking is ready.
+     * Allows index.ts to check if an agent is running in background and route
+     * permission requests to the pending requests queue.
+     *
+     * Phase 3b: Background Agents
+     */
+    onBackgroundAgentReady?: (callbacks: {
+        isBackgroundAgent: (agentId?: string) => boolean;
+        getActiveBackgroundAgentId: () => string | null;
+        getBackgroundAgentInfo: (agentId: string) => {
+            mascot: string;
+        } | null;
+    }) => void;
+    /**
+     * Auth-only mode: Only allow /login, /logout, /exit commands.
+     * Used when user is not authenticated.
+     */
+    authOnly?: boolean;
+    /**
+     * Callback invoked when background delegation support is ready.
+     * Allows index.ts to run background delegations via the REPL.
+     *
+     * Phase 3d-beta: Coordinator Mode
+     */
+    onBackgroundDelegationReady?: (runDelegation: (agentId: string, message: string) => 'running' | 'queued' | null) => void;
+    /**
+     * Callback invoked when terminal session is registered.
+     * Passes the session ID so index.ts can set sessionPrefix for IPC.
+     */
+    onSessionRegistered?: (sessionId: string) => void;
+    /**
+     * Callback invoked when the team is replaced during session restore.
+     * Allows index.ts to update sharedState.team so delegation handlers
+     * see the restored team (with all agents) instead of the initial one.
+     */
+    onTeamReplaced?: (newTeam: AgentTeam) => void;
+}
+/**
+ * Options for switchAgent().
+ * Controls which operations are performed during a switch.
+ */
+export interface SwitchAgentOptions {
+    /** Demote current foreground agent to background if busy (default: true) */
+    demoteCurrentIfBusy?: boolean;
+    /** Update foreground session tracking (default: true) */
+    trackSession?: boolean;
+    /** Record agent switch in telemetry (default: true) */
+    recordTelemetry?: boolean;
+}
+/**
+ * Result of a switchAgent() call.
+ */
+export interface SwitchAgentResult {
+    /** The team agent that was switched to */
+    teamAgent: {
+        id: string;
+        displayName: string;
+        mascot: string;
+        agent: Agent | null;
+        toolFilter?: string[] | null;
+    };
+    /** The agent ID that was demoted to background, or null */
+    demotedAgentId: string | null;
+}
+export declare class ReplV2 {
+    private agent?;
+    private team?;
+    private readonly agentFactory?;
+    private readonly model;
+    private readonly provider;
+    private readonly version;
+    private readonly updateAvailable;
+    private readonly projectName;
+    private readonly sessions;
+    private foregroundAgentId;
+    private readonly agentMessageQueues;
+    private currentSession;
+    private ui;
+    private readonly onUIReady?;
+    private readonly onTextBufferReady?;
+    private readonly onAskUserSimpleReady?;
+    private readonly onGuardrailReady?;
+    private readonly onAskUserReady?;
+    private readonly onIterationLimitReady?;
+    private readonly onAgentFinish?;
+    private readonly onSuggestionReady?;
+    private readonly onSubagentReady?;
+    private readonly clearSubagentTracking?;
+    private readonly showOnboarding;
+    private readonly showLogin;
+    private readonly onDelegateReady?;
+    private readonly onPendingDelegation?;
+    private readonly onBackgroundAgentReady?;
+    private readonly onBackgroundDelegationReady?;
+    private readonly onSessionRegistered?;
+    private readonly onTeamReplaced?;
+    private readonly authOnly;
+    private restoredSessionInfo;
+    private currentExecutingBackgroundAgentId;
+    private readonly startTime;
+    private sessionInputTokens;
+    private sessionOutputTokens;
+    private sessionRequests;
+    private textAccumulator;
+    private readonly bashAbortControllers;
+    constructor(options?: ReplV2Options);
+    /**
+     * Flush accumulated agent text to the UI.
+     * Called externally (e.g., before showing permission overlay) to ensure
+     * agent's "I'll do X" message appears before the overlay.
+     */
+    private flushTextBuffer;
+    /**
+     * Get the mascot expression for the currently active agent.
+     * Returns the team agent's mascot if active, otherwise default neutral.
+     */
+    private getActiveAgentMascot;
+    /**
+     * Start a new agent session (foreground or background).
+     * For foreground: sets currentSession and foregroundAgentId
+     * For background: only adds to sessions map
+     */
+    private startSession;
+    /**
+     * End an agent session.
+     * Removes from sessions map, clears currentSession if foreground,
+     * and processes any queued messages for this agent.
+     */
+    private endSession;
+    /**
+     * Get a session by agent ID.
+     */
+    private getSession;
+    /**
+     * Get all background sessions (non-foreground).
+     */
+    private getBackgroundSessions;
+    /**
+     * Check if an agent has a running session.
+     */
+    private hasActiveSession;
+    /**
+     * Check if any background agents are running.
+     */
+    private hasBackgroundAgents;
+    /**
+     * Queue a message for an agent that is currently busy.
+     * Returns the queue position (1-based).
+     */
+    private queueMessage;
+    /**
+     * Get the number of messages queued for an agent.
+     */
+    private getQueueLength;
+    /**
+     * Clear all queued messages for an agent.
+     * Returns the number of messages that were cleared.
+     */
+    private clearQueue;
+    /**
+     * Clear all message queues for all agents.
+     * Returns the total number of messages cleared.
+     */
+    private clearAllQueues;
+    /**
+     * Process the next message in an agent's queue.
+     * Called after an agent completes a task.
+     */
+    private processAgentQueue;
+    /**
+     * Get detailed info about background sessions (for /bg overlay).
+     * Phase 3c: Background Status & Control
+     */
+    private getBackgroundSessionsInfo;
+    /**
+     * Send the current foreground agent to background without aborting it.
+     * The agent continues running; the user regains the input prompt.
+     * Returns the agent ID that was sent to background, or null if no foreground session.
+     */
+    private sendForegroundToBackground;
+    /**
+     * Consolidated agent-switching method.
+     *
+     * Performs ALL operations needed to switch the foreground to a different agent:
+     * 1. Demote current foreground agent to background (if busy + different agent)
+     * 2. team.switchTo(agentId)
+     * 3. Update this.agent reference
+     * 4. Update meta-tool filter
+     * 5. Update footer UI
+     * 6. Update foreground session tracking (restore agentRunning/spinner)
+     * 7. Record telemetry
+     *
+     * Callers handle their own messaging (different styles/wording per context).
+     */
+    private switchAgent;
+    /**
+     * Bring a background agent to foreground.
+     * Validates the agent has a background session, then delegates to switchAgent().
+     * Phase 3c: Background Status & Control
+     */
+    private bringAgentToForeground;
+    /**
+     * Kill/cancel a background agent.
+     * Phase 3c: Background Status & Control
+     */
+    private killAgent;
+    /**
+     * Get mascot label for an agent (for output labeling).
+     * Format: "[◈_◈] $arch" - mascot followed by agent reference
+     */
+    private getAgentMascotLabel;
+    /**
+     * Auto-expand conversation filter if user is sending to an agent not in the filter.
+     * Shows info message when filter is expanded.
+     * @returns true if filter was expanded, false otherwise
+     */
+    private autoExpandFilterIfNeeded;
+    /**
+     * Regex to detect PLAN_READY marker in agent text.
+     * Format: [PLAN_READY:plan_id:plan_name]
+     */
+    private static readonly PLAN_READY_REGEX;
+    /**
+     * Check if text contains PLAN_READY marker and extract plan info.
+     */
+    private detectPlanReady;
+    /**
+     * Handle plan approval flow.
+     * Shows the approval overlay and handles the user's choice.
+     */
+    private handlePlanApproval;
+    /**
+     * Restore the agent from a previous state.
+     * Called by /resume command to swap in a restored agent.
+     */
+    restoreAgent(newAgent: Agent): void;
+    /**
+     * Get the current agent instance.
+     * Used by commands that need to serialize/checkpoint the agent state.
+     */
+    getAgent(): Agent | undefined;
+    /**
+     * Start the REPL.
+     */
+    start(): void;
+    /**
+     * Handle login flow: show branded login overlay, then continue to onboarding or normal startup.
+     */
+    private handleLoginFlow;
+    /**
+     * Handle startup sequence: session restoration first, then menu if applicable.
+     * This ensures proper ordering of startup overlays.
+     */
+    private handleStartupSequence;
+    /**
+     * Restore a persisted team for a given terminal prefix.
+     * Replaces the current (fresh) team with the one from disk.
+     * Returns true if a team was restored.
+     */
+    private restoreTeamForPrefix;
+    /**
+     * Auto-restore session silently (for 'auto' mode).
+     * Restores both conversation history AND team roster.
+     * Called at startup when projectSessionMode='auto'.
+     *
+     * Behavior depends on whether other terminals are active on the same project:
+     * - Single terminal: silently restore the most recent available session + claim it
+     * - Multiple terminals: fall back to 'ask' mode (show overlay)
+     */
+    private autoRestoreSession;
+    /**
+     * When this terminal has no session but other terminals do, show the resume
+     * overlay so the user can pick one or start fresh.
+     */
+    private offerOtherTerminalSessions;
+    /**
+     * Parse session ID format for startup flow (duplicates session handler logic
+     * to avoid circular import).
+     */
+    private parseCurrentSessionIdForStartup;
+    /**
+     * Handle session mode prompt at startup when projectSessionMode='ask'.
+     * Shows overlay to let user choose how to handle existing session.
+     */
+    private handleSessionModePrompt;
+    /**
+     * Apply the user's session mode choice.
+     */
+    private handleSessionModeResult;
+    /**
+     * Show the onboarding wizard for first-time users.
+     * Called on first run, or manually via /init command.
+     */
+    private showOnboardingWizard;
+    /**
+     * Stop the REPL.
+     * Aborts all running sessions (foreground and background).
+     */
+    /** Set MCP loading state on the footer status bar. */
+    setMCPLoading(loading: boolean, toolCount?: number): void;
+    stop(): void;
+    /**
+     * Print just the logo to the scrolling area.
+     * Used for dashboard mode where hints are not needed.
+     */
+    private printLogo;
+    /**
+     * Print full welcome message for REPL mode.
+     */
+    private printWelcome;
+    private createCommandContext;
+    private handleCommand;
+    /**
+     * Process queued agent messages.
+     * Commands can queue messages to invoke the agent programmatically.
+     */
+    private processAgentMessageQueue;
+    private processInput;
+    /**
+     * Process input in background mode.
+     * Starts the agent without blocking, allowing user to continue with foreground work.
+     *
+     * @param agentId - The agent to run in background
+     * @param input - The message to send to the agent
+     */
+    private processInputBackground;
+    /**
+     * Parse $name prefix from input.
+     * Returns the agent ID, remaining input, and whether this is a background request.
+     * Returns null if the agent doesn't exist.
+     *
+     * Examples:
+     *   "$arch Design the API" → { agentId: 'arch', remainingInput: 'Design the API', isBackground: false }
+     *   "$arch Design the API &" → { agentId: 'arch', remainingInput: 'Design the API', isBackground: true }
+     *   "$pm /backlog" → { agentId: 'pm', remainingInput: '/backlog', isBackground: false }
+     *   "$arch" → { agentId: 'arch', remainingInput: '', isBackground: false }
+     */
+    private parseAgentPrefix;
+    /**
+     * Resolve $agent mention references in input and inject context.
+     *
+     * This handles mid-sentence mentions like:
+     *   "What did $arch propose for the API?"
+     *   "Based on $pm's plan, estimate the timeline"
+     *
+     * The resolved context is prepended to the message before sending to the agent.
+     */
+    private resolveAndInjectMentions;
+    /**
+     * Handle memory note input ("# note") - V2 compatible version
+     */
+    private handleMemoryInputV2;
+    /**
+     * Handle bash command ("!ls", "!git status", etc.)
+     * Runs the command directly and displays output.
+     * Special handling for 'cd' to change the CLI's working directory.
+     */
+    private handleBashCommand;
+    private processQueue;
+    private runAgentReal;
+    /**
+     * Format completion events into a structured message for the coordinator.
+     * Groups events by agent and includes task, result summary, and artifact info.
+     */
+    private formatCompletionMessage;
+    /**
+     * Check and process delegation completions for an agent that just finished.
+     * Marks all running delegations for this agent as completed or failed,
+     * then attempts to auto-resume the coordinator if idle.
+     *
+     * @param agentId - The agent that just finished
+     * @param error - If present, the agent failed with this error
+     */
+    private checkDelegationCompletion;
+    /**
+     * Auto-resume the coordinator if it's idle and there are pending completion events.
+     * If the coordinator is busy, events stay in queue for deferred delivery.
+     *
+     * Must be async to properly await switchAgent before running the coordinator.
+     * Called fire-and-forget from checkDelegationCompletion — this ensures the
+     * background agent's endSession() runs independently (no session conflicts).
+     */
+    private maybeResumeCoordinator;
+    /**
+     * Run an agent in background (Phase 3 - Background Agents).
+     * Similar to runAgentReal but:
+     * - Creates a background session (isBackground: true)
+     * - Labels all output with agent mascot
+     * - Doesn't block the caller
+     * - Shows completion notification when done
+     *
+     * @param agentId - The agent ID to run
+     * @param userMessage - The message to send to the agent
+     */
+    private runAgentBackground;
+    /**
+     * Handle pending delegation after agent finishes.
+     * If a delegation was approved during the agent run, switch to the
+     * target agent and inject the task as a user message.
+     */
+    private handlePendingDelegation;
+    /**
+     * Auto-save the current session and team state.
+     * Called after each successful agent response.
+     *
+     * Saves two things:
+     * 1. Default agent's session state (for /resume - conversation history)
+     * 2. Team state (for team persistence - all agent states including roles)
+     */
+    private autoSaveSession;
+    private formatToolParams;
+    /**
+     * Extract content and summary from tool result.
+     * Delegates to tool-formatters module.
+     */
+    private extractToolResult;
+    private runAgentSimulation;
+    private sleep;
+    /**
+     * Print per-turn summary (tokens, duration, tool calls)
+     */
+    private printTurnSummary;
+    /**
+     * Cancel the foreground session.
+     * Background agents continue running.
+     */
+    private cancelSession;
+}