@compilr-dev/cli 0.5.0 → 0.5.2

package/dist/prompts/plan-mode-prompt.js

@@ -0,0 +1,95 @@
+/**
+ * Plan Mode System Prompt Addition
+ *
+ * Appended to the system prompt when Plan Mode is active.
+ * Instructs the agent to explore, create plans, and wait for approval.
+ */
+export const PLAN_MODE_PROMPT = `## PLAN MODE ACTIVE
+
+You are currently in **Plan Mode**. In this mode, you must:
+
+1. **Gather Context from Database FIRST**:
+   - Use \`project_document_get\` to read PRD and architecture docs
+   - Use \`workitem_query\` to read backlog items
+   - Use \`plan_list\` to see existing plans
+   - Only read actual source files when you need specific implementation details
+
+2. **Ask Questions**: Use \`ask_user\` to clarify requirements, constraints, and preferences. Don't assume.
+
+3. **Create a Plan**: Use \`plan_create\` to document your approach before implementing:
+   - Name: kebab-case, descriptive (e.g., "auth-jwt-migration")
+   - Content: Follow the standard plan format (Context, Goals, Steps, Verification)
+   - Link to work item if one was mentioned
+
+4. **Request Approval**: After creating the plan, summarize it and ask for approval:
+   - List 3-5 key points
+   - Mention files that will be modified
+   - End with: "Ready for your review. [PLAN_READY:plan_id:plan_name]"
+
+5. **Wait for Approval**: Do NOT implement until the user approves the plan.
+
+6. **Track Status**: After approval, update the plan status:
+   - Use \`plan_update\` with status: 'approved' when user approves
+   - Use \`plan_update\` with status: 'in_progress' when you start implementing
+   - Use \`plan_update\` with status: 'completed' when all steps are done
+
+### Plan Format
+
+Use this structure when creating plans:
+
+\`\`\`markdown
+# Plan: [Name]
+
+## Context
+[Why this plan exists, what problem it solves]
+[Link to work item if applicable]
+
+## Goals
+- [ ] Primary goal 1
+- [ ] Primary goal 2
+
+## Approach
+[High-level description of the implementation approach]
+
+## Steps
+1. **Step 1 Title**
+   - Details about step 1
+   - Files to modify: \`src/foo.ts\`
+
+2. **Step 2 Title**
+   - Details about step 2
+
+## Verification
+- [ ] How to verify completion
+- [ ] Tests pass
+\`\`\`
+
+### DO NOT in Plan Mode:
+- Skip planning for non-trivial tasks
+- Make code changes without an approved plan
+- Assume requirements without asking
+- Read files in .compilr/requirements/ (use project_document_get instead)
+- Scan the filesystem before checking database for project docs
+
+### Available Plan Tools:
+- \`plan_create\` - Create a new plan (starts as 'draft')
+- \`plan_update\` - Update plan content or status
+- \`plan_get\` - Get plan details by ID or name
+- \`plan_list\` - List plans for the project
+- \`plan_delete\` - Delete a plan
+`;
+/**
+ * Get the plan mode prompt for a specific active plan (if any)
+ */
+export function getPlanModePrompt(activePlanId, activePlanName) {
+    let prompt = PLAN_MODE_PROMPT;
+    if (activePlanId && activePlanName) {
+        prompt += `\n### Current Active Plan
+
+You are continuing work on plan **"${activePlanName}"** (ID: ${String(activePlanId)}).
+
+Use \`plan_get\` with plan_id: ${String(activePlanId)} to load the plan details and continue from where you left off.
+`;
+    }
+    return prompt;
+}

package/dist/repl-helpers.js

@@ -5,8 +5,9 @@
  * and improve maintainability. These functions support the REPL but don't
  * depend on REPL instance state.
  */
-import { builtinSkills } from '@compilr-dev/agents';
+import { builtinSkills, platformSkills } from '@compilr-dev/sdk';
 import { codingSkills } from '@compilr-dev/agents-coding';
+import { factorySkills } from '@compilr-dev/factory';
 import * as fs from 'fs';
 import * as path from 'path';
 import { findBacklogPath, parseBacklogItems } from './tools/backlog.js';
@@ -202,7 +203,9 @@ export function hasBacklogItems(backlogPath) {
  * Get skill prompt by name from builtinSkills or codingSkills.
  */
 export function getSkillPrompt(name) {
-    const skill = builtinSkills.find((s) => s.name === name)
+    const skill = platformSkills.find((s) => s.name === name)
+        ?? factorySkills.find((s) => s.name === name)
+        ?? builtinSkills.find((s) => s.name === name)
         ?? codingSkills.find((s) => s.name === name);
     return skill?.prompt ?? null;
 }

package/dist/repl-v2.d.ts

@@ -9,21 +9,40 @@
  * 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/agents';
+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;
     /**
@@ -81,13 +100,106 @@ export interface ReplV2Options {
      * 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 readonly agent?;
+    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?;
@@ -100,11 +212,23 @@ export declare class ReplV2 {
     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.
@@ -112,13 +236,194 @@ export declare class ReplV2 {
      * 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.
@@ -137,12 +442,98 @@ export declare class ReplV2 {
      */
     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.
@@ -151,5 +542,13 @@ export declare class ReplV2 {
     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;
 }