@kynetic-ai/spec 0.9.1 → 0.11.0

package/dist/cli/commands/agent.js

@@ -0,0 +1,831 @@
+/**
+ * kspec agent commands — manage and run agents.
+ *
+ * Provides subcommands for listing agent definitions, running one-shot
+ * invocations, and managing the dispatch engine lifecycle via the daemon.
+ *
+ * AC: @cli-agent-commands ac-1 through ac-10
+ * AC: @trait-json-output ac-1 through ac-6
+ * AC: @trait-semantic-exit-codes ac-1 through ac-8
+ * AC: @trait-error-guidance ac-1 through ac-6
+ * AC: @trait-dry-run ac-1 through ac-6
+ * AC: @trait-filterable-list ac-1 through ac-8
+ */
+import chalk from "chalk";
+import { initContext, loadMetaContext, } from "../../parser/index.js";
+import { runInvocation } from "../../agent-runtime/invocation.js";
+import { buildPromptWithSkills } from "../../agent-runtime/prompts.js";
+import { resolveAdapter } from "../../agents/adapters.js";
+import { EXIT_CODES } from "../exit-codes.js";
+import { error, info, output, success, warn, isJsonMode } from "../output.js";
+import { parseIntOption } from "../validators.js";
+import { PidFileManager } from "../pid-utils.js";
+import { errors } from "../../strings/errors.js";
+import { requestEndLoop } from "../../sessions/index.js";
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+/**
+ * Get the daemon URL from the PID file manager.
+ * Returns null if the daemon is not running.
+ * AC: @cli-agent-commands ac-10
+ */
+function getDaemonUrl() {
+    const pidManager = new PidFileManager();
+    if (!pidManager.isDaemonRunning())
+        return null;
+    try {
+        const port = pidManager.readPort();
+        return { url: `http://localhost:${port}`, port };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Format dispatch rules summary for display.
+ */
+function formatDispatchRules(agent) {
+    if (!agent.dispatch || agent.dispatch.length === 0) {
+        return "(none)";
+    }
+    return agent.dispatch.map((r) => {
+        const filterParts = [];
+        if (r.filter?.automation)
+            filterParts.push(`automation=${r.filter.automation}`);
+        if (r.filter?.tags?.length)
+            filterParts.push(`tags=${r.filter.tags.join(",")}`);
+        if (r.filter?.priority !== undefined)
+            filterParts.push(`priority=${r.filter.priority}`);
+        const filterStr = filterParts.length > 0 ? ` [${filterParts.join(", ")}]` : "";
+        return `${r.on}${filterStr}`;
+    }).join(", ");
+}
+// ─── Command Registration ─────────────────────────────────────────────────────
+/**
+ * Register the kspec agent command family.
+ * AC: @cli-agent-commands ac-1 through ac-10
+ */
+export function registerAgentCommands(program) {
+    const agent = program
+        .command("agent")
+        .description("Manage and run agents");
+    // ─── kspec agent list ─────────────────────────────────────────────────────
+    // AC: @cli-agent-commands ac-1
+    // AC: @trait-filterable-list ac-1 through ac-8
+    agent
+        .command("list")
+        .description("List all agent definitions")
+        .option("--json", "Output as JSON")
+        .option("--status <status>", "Filter by automation status (eligible|ineligible)")
+        .option("--tag <tag>", "Filter by tag (repeatable)", (val, arr) => [...arr, val], [])
+        .option("--limit <n>", "Maximum number of results")
+        .option("--offset <n>", "Skip first N results")
+        .option("--count", "Output only the count")
+        .action(async (opts) => {
+        try {
+            const ctx = await initContext();
+            if (!ctx.manifestPath) {
+                error(errors.project.noKspecProject);
+                process.exit(EXIT_CODES.VALIDATION_FAILED);
+            }
+            const meta = await loadMetaContext(ctx);
+            let agents = meta.agents;
+            // AC: @trait-filterable-list ac-1 - automation status filter
+            if (opts.status) {
+                agents = agents.filter((a) => a.automation === opts.status);
+            }
+            // AC: @trait-filterable-list ac-2 - tag filter
+            const tags = opts.tag ?? [];
+            if (tags.length > 0) {
+                agents = agents.filter((a) => {
+                    const agentTags = a.tags ?? [];
+                    return tags.every((t) => agentTags.includes(t));
+                });
+            }
+            const total = agents.length;
+            // AC: @trait-filterable-list ac-8 - count mode
+            if (opts.count) {
+                output({ count: total }, () => {
+                    console.log(total);
+                });
+                return;
+            }
+            // AC: @trait-filterable-list ac-3, ac-4 - pagination
+            // AC: @trait-semantic-exit-codes ac-2 - invalid numeric input exits with validation error
+            let limit = total;
+            if (opts.limit !== undefined) {
+                const parsed = parseIntOption(opts.limit, {
+                    min: 0,
+                    max: Number.MAX_SAFE_INTEGER,
+                    name: "Limit",
+                });
+                if (!parsed.ok) {
+                    error(`Invalid --limit value: ${parsed.error}`, { suggestion: "Example: --limit 10" });
+                    process.exit(EXIT_CODES.VALIDATION_FAILED);
+                }
+                limit = parsed.value;
+            }
+            let offset = 0;
+            if (opts.offset !== undefined) {
+                const parsed = parseIntOption(opts.offset, {
+                    min: 0,
+                    max: Number.MAX_SAFE_INTEGER,
+                    name: "Offset",
+                });
+                if (!parsed.ok) {
+                    error(`Invalid --offset value: ${parsed.error}`, { suggestion: "Example: --offset 5" });
+                    process.exit(EXIT_CODES.VALIDATION_FAILED);
+                }
+                offset = parsed.value;
+            }
+            const paginated = agents.slice(offset, offset + limit);
+            // AC: @trait-semantic-exit-codes ac-5 - empty result set exits 0
+            // AC: @trait-filterable-list ac-6 - empty list with informative message
+            if (paginated.length === 0) {
+                output({ items: [], total, offset, limit }, () => {
+                    if (opts.status || tags.length > 0) {
+                        console.log("No agents match the specified filters.");
+                    }
+                    else {
+                        console.log("No agent definitions found.");
+                    }
+                });
+                return;
+            }
+            // AC: @trait-json-output ac-1 through ac-5
+            output({
+                items: paginated.map((a) => ({
+                    id: a.id,
+                    name: a.name,
+                    adapter: a.adapter ?? "claude-agent-acp",
+                    dispatch: a.dispatch ?? [],
+                    concurrency: a.concurrency ?? { max_concurrent: 1 },
+                })),
+                total,
+                offset,
+                limit,
+            }, () => {
+                // AC: @trait-filterable-list ac-7 - summary with total and filter state
+                const filterDesc = [
+                    opts.status ? `status=${opts.status}` : "",
+                    tags.length > 0 ? `tags=${tags.join(",")}` : "",
+                ].filter(Boolean).join(", ");
+                const summaryStr = filterDesc ? ` (filtered: ${filterDesc})` : "";
+                console.log(chalk.bold(`Agents${summaryStr}: ${paginated.length} of ${total}`));
+                console.log();
+                for (const a of paginated) {
+                    console.log(`  ${chalk.cyan(a.id)}  ${chalk.gray(a.adapter ?? "claude-agent-acp")}`);
+                    console.log(`    ${chalk.gray("dispatch:")} ${formatDispatchRules(a)}`);
+                    console.log(`    ${chalk.gray("concurrency:")} max ${a.concurrency?.max_concurrent ?? 1}`);
+                }
+            });
+        }
+        catch (err) {
+            error("Failed to list agents", err);
+            process.exit(EXIT_CODES.ERROR);
+        }
+    });
+    // ─── kspec agent run ──────────────────────────────────────────────────────
+    // AC: @cli-agent-commands ac-2, ac-3, ac-7, ac-8
+    // AC: @trait-dry-run ac-1 through ac-6
+    agent
+        .command("run <agent-id> [prompt]")
+        .description("Run a one-shot agent invocation")
+        .option("--task <ref>", "Task reference to target")
+        .option("--timeout <minutes>", "Timeout in minutes (overrides agent default)")
+        .option("--budget <n>", "Budget override (max tasks)")
+        .option("--adapter <id>", "Adapter override")
+        .option("--dry-run", "Show prompt without spawning agent")
+        .option("--json", "Output as JSON")
+        .action(async (agentId, prompt, opts) => {
+        try {
+            const ctx = await initContext();
+            if (!ctx.manifestPath) {
+                error(errors.project.noKspecProject);
+                process.exit(EXIT_CODES.VALIDATION_FAILED);
+            }
+            const meta = await loadMetaContext(ctx);
+            const agentDef = meta.agents.find((a) => a.id === agentId);
+            // AC: @trait-error-guidance ac-3 - not found error with suggestion
+            if (!agentDef) {
+                error(`Agent "${agentId}" not found.`, {
+                    suggestion: `Check available agents with: kspec agent list`,
+                });
+                process.exit(EXIT_CODES.VALIDATION_FAILED);
+            }
+            // Resolve the effective adapter
+            const adapterId = opts.adapter ?? agentDef.adapter ?? "claude-agent-acp";
+            const adapter = resolveAdapter(adapterId);
+            // Build the prompt
+            const taskRef = opts.task;
+            const basePrompt = prompt ?? (taskRef
+                ? `Work on task ${taskRef} according to your configuration and skills.`
+                : `Run as requested.`);
+            // Note: buildPromptWithSkills is called here for the dry-run preview path.
+            // runInvocation also calls buildPromptWithSkills internally, so we pass basePrompt
+            // to runInvocation (not fullPrompt) to avoid double-expansion.
+            const fullPromptForPreview = await buildPromptWithSkills({
+                basePrompt,
+                skillIds: agentDef.skills ?? [],
+                specDir: ctx.specDir,
+                adapterId,
+            });
+            // AC: @trait-dry-run ac-1, ac-2, ac-3 - dry run shows prompt, no changes
+            if (opts.dryRun) {
+                // Pre-compute overrides so dry-run reflects what the actual invocation would use
+                // AC: @cli-agent-commands ac-7 - overrides are visible in dry-run output
+                // AC: @trait-semantic-exit-codes ac-2 - validate numeric inputs even in dry-run
+                let dryTimeoutOverride;
+                if (opts.timeout) {
+                    const parsed = parseIntOption(opts.timeout, { min: 1, max: 10080, name: "Timeout" });
+                    if (!parsed.ok) {
+                        error(`Invalid --timeout value: ${parsed.error}`, { suggestion: "Example: --timeout 30" });
+                        process.exit(EXIT_CODES.VALIDATION_FAILED);
+                    }
+                    dryTimeoutOverride = parsed.value;
+                }
+                let dryBudgetOverride;
+                if (opts.budget) {
+                    const parsed = parseIntOption(opts.budget, { min: 1, max: 99999, name: "Budget" });
+                    if (!parsed.ok) {
+                        error(`Invalid --budget value: ${parsed.error}`, { suggestion: "Example: --budget 10" });
+                        process.exit(EXIT_CODES.VALIDATION_FAILED);
+                    }
+                    dryBudgetOverride = parsed.value;
+                }
+                const effectiveTimeoutMinutes = dryTimeoutOverride ?? agentDef.budget?.timeout_minutes;
+                const effectiveMaxTasks = dryBudgetOverride ?? agentDef.budget?.max_tasks;
+                // AC: @trait-dry-run ac-6 - JSON output includes dry_run field
+                output({
+                    dry_run: true,
+                    agent_id: agentId,
+                    adapter: adapterId,
+                    task_ref: taskRef ?? null,
+                    timeout_minutes: effectiveTimeoutMinutes ?? null,
+                    max_tasks: effectiveMaxTasks ?? null,
+                    prompt: fullPromptForPreview,
+                }, () => {
+                    console.log(chalk.yellow("DRY RUN - No agent will be spawned"));
+                    console.log();
+                    console.log(chalk.gray(`Agent:   ${agentId}`));
+                    console.log(chalk.gray(`Adapter: ${adapterId}`));
+                    if (taskRef) {
+                        console.log(chalk.gray(`Task:    ${taskRef}`));
+                    }
+                    if (effectiveTimeoutMinutes !== undefined) {
+                        console.log(chalk.gray(`Timeout: ${effectiveTimeoutMinutes} min`));
+                    }
+                    console.log();
+                    console.log(chalk.gray("--- Prompt that would be sent ---"));
+                    console.log(fullPromptForPreview);
+                    console.log(chalk.gray("--- End prompt ---"));
+                });
+                return;
+            }
+            // AC: @cli-agent-commands ac-2 - one-shot invocation with task binding
+            // AC: @cli-agent-commands ac-3 - one-shot invocation with custom prompt (no task binding)
+            // AC: @cli-agent-commands ac-7 - CLI overrides agent defaults
+            let timeoutOverride;
+            if (opts.timeout) {
+                const parsed = parseIntOption(opts.timeout, { min: 1, max: 10080, name: "Timeout" });
+                if (!parsed.ok) {
+                    error(`Invalid --timeout value: ${parsed.error}`, { suggestion: "Example: --timeout 30" });
+                    process.exit(EXIT_CODES.VALIDATION_FAILED);
+                }
+                timeoutOverride = parsed.value;
+            }
+            let budgetOverride;
+            if (opts.budget) {
+                const parsed = parseIntOption(opts.budget, { min: 1, max: 99999, name: "Budget" });
+                if (!parsed.ok) {
+                    error(`Invalid --budget value: ${parsed.error}`, { suggestion: "Example: --budget 10" });
+                    process.exit(EXIT_CODES.VALIDATION_FAILED);
+                }
+                budgetOverride = parsed.value;
+            }
+            const effectiveAgent = {
+                ...agentDef,
+                adapter: adapterId,
+                budget: timeoutOverride !== undefined || budgetOverride !== undefined
+                    ? {
+                        ...agentDef.budget,
+                        timeout_minutes: timeoutOverride ?? agentDef.budget?.timeout_minutes,
+                        max_tasks: budgetOverride ?? agentDef.budget?.max_tasks,
+                    }
+                    : agentDef.budget,
+            };
+            console.log(chalk.gray(`Running agent "${agentId}"...`));
+            // AC: @cli-agent-commands ac-12 — stream text to stdout in interactive mode
+            // AC: @cli-agent-commands ac-11 — suppress streaming in --json mode
+            let didStream = false;
+            const onUpdate = isJsonMode()
+                ? undefined
+                : (update) => {
+                    if (update.sessionUpdate === "agent_message_chunk" &&
+                        update.content.type === "text") {
+                        process.stdout.write(update.content.text);
+                        didStream = true;
+                    }
+                };
+            // AC: @cli-agent-commands ac-3 - no task binding when --task not provided
+            // Pass basePrompt (not fullPromptForPreview) — runInvocation expands skills internally
+            const result = await runInvocation({
+                agent: effectiveAgent,
+                specDir: ctx.specDir,
+                cwd: ctx.rootDir,
+                taskRef: taskRef ?? undefined,
+                prompt: basePrompt,
+                trigger: "manual",
+                onUpdate,
+            });
+            // Ensure summary starts on its own line after streamed content
+            if (didStream)
+                process.stdout.write("\n");
+            output({
+                outcome: result.outcome,
+                session_id: result.session.id,
+                duration_ms: result.durationMs,
+                stop_reason: result.stopReason,
+            }, () => {
+                if (result.outcome === "success") {
+                    success(`Agent invocation completed`, {
+                        session: result.session.id,
+                        duration: `${Math.round(result.durationMs / 1000)}s`,
+                    });
+                }
+                else {
+                    error(`Agent invocation ${result.outcome}: ${result.error ?? "unknown"}`);
+                }
+            });
+            if (result.outcome !== "success") {
+                process.exit(EXIT_CODES.ERROR);
+            }
+        }
+        catch (err) {
+            error("Failed to run agent", err);
+            process.exit(EXIT_CODES.ERROR);
+        }
+    });
+    // ─── kspec agent status ───────────────────────────────────────────────────
+    // AC: @cli-agent-commands ac-6
+    agent
+        .command("status")
+        .description("Show active and queued agent invocations")
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        try {
+            const daemonConn = getDaemonUrl();
+            // AC: @trait-error-guidance ac-1, ac-2
+            if (!daemonConn) {
+                error("Daemon is not running. Cannot retrieve agent status.", { suggestion: "Start the daemon with: kspec serve" });
+                process.exit(EXIT_CODES.ERROR);
+            }
+            const ctx = await initContext();
+            const headers = {};
+            if (ctx.rootDir) {
+                headers["X-Kspec-Dir"] = ctx.rootDir;
+            }
+            const response = await fetch(`${daemonConn.url}/api/agent/dispatch/status`, { headers });
+            if (!response.ok) {
+                error(`Daemon returned error: ${response.status} ${response.statusText}`);
+                process.exit(EXIT_CODES.ERROR);
+            }
+            // AC: @cli-agent-commands ac-6
+            const data = await response.json();
+            output(data, () => {
+                console.log(chalk.bold("Agent Status"));
+                console.log();
+                console.log(`  Dispatch engine: ${data.running ? chalk.green("running") : chalk.gray("stopped")}`);
+                console.log(`  Active invocations: ${chalk.cyan(String(data.activeInvocations))}`);
+                console.log(`  Queued invocations: ${chalk.cyan(String(data.queuedInvocations))}`);
+                const invocations = data.invocations ?? [];
+                if (invocations.length > 0) {
+                    console.log();
+                    console.log(chalk.bold("Active:"));
+                    for (const inv of invocations) {
+                        const elapsed = Math.round(inv.elapsedMs / 1000);
+                        const taskStr = inv.taskRef ? `  task: ${chalk.yellow(inv.taskRef)}` : "";
+                        console.log(`  ${chalk.cyan(inv.agentId)}  ${chalk.gray(inv.agentName)}`);
+                        console.log(`    session: ${chalk.gray(inv.sessionId)}  elapsed: ${elapsed}s${taskStr}`);
+                    }
+                }
+                const queuedItems = data.queued ?? [];
+                if (queuedItems.length > 0) {
+                    console.log();
+                    console.log(chalk.bold("Queued:"));
+                    for (const q of queuedItems) {
+                        const wait = Math.round(q.waitMs / 1000);
+                        const taskStr = q.taskRef ? `  task: ${chalk.yellow(q.taskRef)}` : "";
+                        console.log(`  ${chalk.cyan(q.agentId)}  ${chalk.gray(q.agentName)}`);
+                        console.log(`    waiting: ${wait}s${taskStr}`);
+                    }
+                }
+            });
+        }
+        catch (err) {
+            error("Failed to get agent status", err);
+            process.exit(EXIT_CODES.ERROR);
+        }
+    });
+    // ─── kspec agent dispatch ─────────────────────────────────────────────────
+    const dispatch = agent
+        .command("dispatch")
+        .description("Manage the agent dispatch engine");
+    // AC: @cli-agent-commands ac-4
+    // AC: @cli-agent-commands ac-10
+    dispatch
+        .command("start")
+        .description("Start the dispatch engine (daemon must be running)")
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        try {
+            const daemonConn = getDaemonUrl();
+            // AC: @cli-agent-commands ac-10 - error when daemon not running
+            if (!daemonConn) {
+                error("Daemon is not running. The dispatch engine requires the daemon.", { suggestion: "Start the daemon first with: kspec serve" });
+                process.exit(EXIT_CODES.ERROR);
+            }
+            const ctx = await initContext();
+            const headers = {
+                "Content-Type": "application/json",
+            };
+            if (ctx.rootDir) {
+                headers["X-Kspec-Dir"] = ctx.rootDir;
+            }
+            const response = await fetch(`${daemonConn.url}/api/agent/dispatch/start`, {
+                method: "POST",
+                headers,
+            });
+            if (!response.ok) {
+                const body = await response.text();
+                error(`Failed to start dispatch engine: ${response.status} - ${body}`);
+                process.exit(EXIT_CODES.ERROR);
+            }
+            const data = await response.json();
+            output(data, () => {
+                if (data.started) {
+                    success("Dispatch engine started");
+                }
+                else {
+                    console.log(chalk.yellow(`Dispatch engine: ${data.reason ?? "already running"}`));
+                }
+            });
+        }
+        catch (err) {
+            error("Failed to start dispatch engine", err);
+            process.exit(EXIT_CODES.ERROR);
+        }
+    });
+    // AC: @cli-agent-commands ac-5
+    dispatch
+        .command("stop")
+        .description("Stop the dispatch engine gracefully")
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        try {
+            const daemonConn = getDaemonUrl();
+            if (!daemonConn) {
+                error("Daemon is not running.", { suggestion: "Start the daemon with: kspec serve" });
+                process.exit(EXIT_CODES.ERROR);
+            }
+            const ctx = await initContext();
+            const headers = {
+                "Content-Type": "application/json",
+            };
+            if (ctx.rootDir) {
+                headers["X-Kspec-Dir"] = ctx.rootDir;
+            }
+            const response = await fetch(`${daemonConn.url}/api/agent/dispatch/stop`, {
+                method: "POST",
+                headers,
+            });
+            if (!response.ok) {
+                const body = await response.text();
+                error(`Failed to stop dispatch engine: ${response.status} - ${body}`);
+                process.exit(EXIT_CODES.ERROR);
+            }
+            const data = await response.json();
+            output(data, () => {
+                if (data.stopped) {
+                    success("Dispatch engine stopped");
+                }
+                else {
+                    console.log(chalk.yellow(`Dispatch engine: ${data.reason ?? "not running"}`));
+                }
+            });
+        }
+        catch (err) {
+            error("Failed to stop dispatch engine", err);
+            process.exit(EXIT_CODES.ERROR);
+        }
+    });
+    // AC: @cli-agent-commands ac-9
+    dispatch
+        .command("status")
+        .description("Show dispatch engine status and loaded agents")
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        try {
+            const daemonConn = getDaemonUrl();
+            if (!daemonConn) {
+                // Daemon not running — show as disabled
+                output({ running: false, activeInvocations: 0, queuedInvocations: 0, agents: [] }, () => {
+                    console.log(chalk.bold("Dispatch Status"));
+                    console.log();
+                    console.log(`  Dispatch engine: ${chalk.gray("not available (daemon offline)")}`);
+                    console.log(chalk.gray("  Start daemon with: kspec serve"));
+                });
+                return;
+            }
+            const ctx = await initContext();
+            const headers = {};
+            if (ctx.rootDir) {
+                headers["X-Kspec-Dir"] = ctx.rootDir;
+            }
+            // Get dispatch status
+            const statusResponse = await fetch(`${daemonConn.url}/api/agent/dispatch/status`, { headers });
+            if (!statusResponse.ok) {
+                error(`Daemon returned error: ${statusResponse.status}`);
+                process.exit(EXIT_CODES.ERROR);
+            }
+            const statusData = await statusResponse.json();
+            // Get loaded agents
+            let agents = [];
+            try {
+                const meta = await loadMetaContext(ctx);
+                agents = meta.agents.map((a) => ({ id: a.id, name: a.name }));
+            }
+            catch {
+                // Meta may not be available
+            }
+            const fullData = { ...statusData, agents };
+            output(fullData, () => {
+                console.log(chalk.bold("Dispatch Status"));
+                console.log();
+                console.log(`  Engine:             ${statusData.running ? chalk.green("enabled") : chalk.yellow("disabled")}`);
+                console.log(`  Active invocations: ${chalk.cyan(String(statusData.activeInvocations))}`);
+                console.log(`  Queued invocations: ${chalk.cyan(String(statusData.queuedInvocations))}`);
+                console.log();
+                console.log(chalk.bold("Loaded Agents:"));
+                if (agents.length === 0) {
+                    console.log(chalk.gray("  (none defined)"));
+                }
+                else {
+                    for (const a of agents) {
+                        console.log(`  ${chalk.cyan(a.id)}  ${chalk.gray(a.name)}`);
+                    }
+                }
+            });
+        }
+        catch (err) {
+            error("Failed to get dispatch status", err);
+            process.exit(EXIT_CODES.ERROR);
+        }
+    });
+    // ─── kspec agent dispatch watch ───────────────────────────────────────────
+    // AC: @cli-agent-commands ac-13 through ac-18
+    dispatch
+        .command("watch")
+        .description("Stream agent text output from the dispatch engine in real time")
+        .option("--agent <name>", "Only show output from this agent")
+        .option("--session <id>", "Only show output from this session")
+        .option("--retries <n>", "Number of reconnect attempts on disconnect (default 5)", "5")
+        .action(async (opts) => {
+        const DEFAULT_RETRIES = 5;
+        const RETRY_BASE_MS = 1000;
+        const MAX_RETRY_MS = 30_000;
+        // AC: @cli-agent-commands ac-15 — error when daemon not running
+        const daemonConn = getDaemonUrl();
+        if (!daemonConn) {
+            error("Daemon is not running. The watch command requires the daemon.");
+            info("Suggestion: Start the daemon with: kspec serve");
+            // AC: @cli-agent-commands ac-15 — exit code 3
+            process.exit(EXIT_CODES.NOT_FOUND);
+            return;
+        }
+        const parsedRetries = parseIntOption(opts.retries, {
+            min: 0,
+            max: Number.MAX_SAFE_INTEGER,
+            name: "Retries",
+        });
+        if (!parsedRetries.ok) {
+            error(`Invalid --retries value: ${parsedRetries.error}`, {
+                suggestion: "Example: --retries 5",
+            });
+            process.exit(EXIT_CODES.VALIDATION_FAILED);
+            return;
+        }
+        const retryLimit = parsedRetries.value;
+        const agentFilter = opts.agent;
+        const sessionFilter = opts.session;
+        const streamStates = new Map();
+        let activeStreamKey = null;
+        let outputAtLineStart = true;
+        function getStreamState(streamKey) {
+            let state = streamStates.get(streamKey);
+            if (!state) {
+                state = { hasRenderedBody: false, spacerPending: false };
+                streamStates.set(streamKey, state);
+            }
+            return state;
+        }
+        function writeRaw(text) {
+            if (!text)
+                return;
+            process.stdout.write(text);
+            outputAtLineStart = text.endsWith("\n");
+        }
+        function writeSpeakerText(text) {
+            if (!text)
+                return;
+            writeRaw(text);
+        }
+        function ensureLineBreak() {
+            if (!outputAtLineStart) {
+                writeRaw("\n");
+            }
+        }
+        function startSpeakerSection(streamKey, prefix) {
+            if (activeStreamKey === streamKey)
+                return;
+            if (activeStreamKey) {
+                ensureLineBreak();
+            }
+            writeRaw(`${prefix}\n`);
+            activeStreamKey = streamKey;
+        }
+        function queuePrefixedChunk(streamKey, prefix, text) {
+            if (!text)
+                return;
+            const switchingSpeaker = activeStreamKey !== null && activeStreamKey !== streamKey;
+            startSpeakerSection(streamKey, prefix);
+            const state = getStreamState(streamKey);
+            if (switchingSpeaker) {
+                // Marker change already separates context; don't carry stale spacer
+                // into the top of a newly active speaker section.
+                state.spacerPending = false;
+            }
+            else if (state.spacerPending && state.hasRenderedBody) {
+                ensureLineBreak();
+                writeRaw("\n");
+                state.spacerPending = false;
+            }
+            writeSpeakerText(text);
+            state.hasRenderedBody = true;
+        }
+        function markMessageBoundary(streamKey) {
+            // Boundary signals are stream-local; ignore inactive streams.
+            if (activeStreamKey !== streamKey)
+                return;
+            const state = getStreamState(streamKey);
+            ensureLineBreak();
+            // Coalesce repeated boundary events into one pending spacer.
+            if (state.hasRenderedBody) {
+                state.spacerPending = true;
+            }
+        }
+        function formatSessionIdForDisplay(sessionId) {
+            // AC: @cli-agent-commands ac-17 — shorten session ULID in watch prefix.
+            return sessionId ? sessionId.slice(0, 8) : "";
+        }
+        // Resolve project dir for WebSocket project binding
+        let projectDir;
+        try {
+            const ctx = await initContext();
+            projectDir = ctx.rootDir;
+        }
+        catch {
+            // non-fatal: WebSocket will use daemon default
+        }
+        let retryCount = 0;
+        let shouldReconnect = true;
+        function connect() {
+            const wsUrl = new URL(`ws://localhost:${daemonConn.port}/ws`);
+            if (projectDir) {
+                wsUrl.searchParams.set("project", projectDir);
+            }
+            // AC: @cli-agent-commands ac-15 — Node 22+ has global WebSocket
+            const ws = new WebSocket(wsUrl.toString());
+            ws.onopen = () => {
+                retryCount = 0;
+                // Subscribe to agents topic
+                ws.send(JSON.stringify({
+                    action: "subscribe",
+                    request_id: "watch-subscribe",
+                    payload: { topics: ["agents"] },
+                }));
+            };
+            ws.onmessage = (event) => {
+                let msg;
+                try {
+                    msg = JSON.parse(event.data);
+                }
+                catch {
+                    return;
+                }
+                // AC: @cli-agent-commands ac-18 — fail fast on subscribe handshake rejection.
+                if (msg.ack === true && msg.request_id === "watch-subscribe") {
+                    if (msg.success === false) {
+                        shouldReconnect = false;
+                        const reasonParts = [msg.error, msg.details]
+                            .filter((value) => typeof value === "string" && value.length > 0);
+                        const reason = reasonParts.length > 0 ? ` (${reasonParts.join(": ")})` : "";
+                        if (activeStreamKey) {
+                            ensureLineBreak();
+                        }
+                        error(`Failed to subscribe to daemon agent output stream${reason}.`);
+                        info("Suggestion: Verify daemon logs for subscribe errors, then restart with: kspec serve");
+                        process.exit(EXIT_CODES.NOT_FOUND);
+                    }
+                    return;
+                }
+                // AC: @cli-agent-commands ac-13 — stream text with per-line [agent-id session-id] prefixes
+                if (msg.event === "agent_text_chunk" && msg.data) {
+                    const data = msg.data;
+                    const sessionId = data.session_id ?? "";
+                    const agentId = data.agent_id ?? "";
+                    const text = data.text ?? "";
+                    // AC: @cli-agent-commands ac-16 — filter by agent/session if specified
+                    if (agentFilter && agentId !== agentFilter)
+                        return;
+                    if (sessionFilter && sessionId !== sessionFilter)
+                        return;
+                    const streamKey = `${agentId}\u0000${sessionId}`;
+                    const displaySessionId = formatSessionIdForDisplay(sessionId);
+                    const prefix = `[${agentId} ${displaySessionId}]`;
+                    // Match old Ralph rendering semantics: empty chunk marks message end.
+                    if (text.length === 0) {
+                        markMessageBoundary(streamKey);
+                        return;
+                    }
+                    queuePrefixedChunk(streamKey, prefix, text);
+                }
+            };
+            ws.onerror = () => {
+                // error event fires before close, handled in onclose
+            };
+            ws.onclose = () => {
+                if (!shouldReconnect)
+                    return;
+                if (activeStreamKey) {
+                    ensureLineBreak();
+                }
+                if (retryCount >= retryLimit) {
+                    // AC: @cli-agent-commands ac-14 — exit code 3 when retries exhausted
+                    error(`WebSocket connection lost and reconnection failed after ${retryLimit} attempt(s).`);
+                    info("Suggestion: Verify the daemon is still running with: kspec serve");
+                    process.exit(EXIT_CODES.NOT_FOUND);
+                    return;
+                }
+                retryCount++;
+                const backoffMs = Math.min(RETRY_BASE_MS * Math.pow(2, retryCount - 1), MAX_RETRY_MS);
+                // AC: @cli-agent-commands ac-14 — print reconnecting message
+                process.stderr.write(`[watch] Connection lost. Reconnecting in ${Math.round(backoffMs / 1000)}s (attempt ${retryCount}/${retryLimit})...\n`);
+                setTimeout(connect, backoffMs);
+            };
+        }
+        connect();
+        // Keep process alive (WebSocket is non-blocking in Node)
+        // Users interrupt with Ctrl+C
+        await new Promise(() => { });
+    });
+    // ─── kspec agent end-loop ─────────────────────────────────────────────────
+    // AC: @ralph-replacement ac-1 — equivalent to kspec ralph end-loop
+    // AC: @session-end-loop-signal ac-signal
+    agent
+        .command("end-loop")
+        .description("Signal the agent dispatch engine to stop after current iteration")
+        .option("--reason <reason>", "Reason for ending the loop")
+        .action(async (options) => {
+        try {
+            const ctx = await initContext();
+            const sessionId = process.env.KSPEC_SESSION_ID;
+            if (!sessionId) {
+                // AC: @trait-error-guidance ac-1, ac-2
+                warn("No active agent session detected (KSPEC_SESSION_ID not set).");
+                info("This command requires an active session. It is designed to be called by agents during a dispatch invocation.");
+                info("Suggestion: Ensure KSPEC_SESSION_ID is set, or start a session with: kspec session create");
+                process.exit(EXIT_CODES.VALIDATION_FAILED);
+                return;
+            }
+            // Write end-loop state to session
+            const updated = await requestEndLoop(ctx.specDir, sessionId, options.reason);
+            if (!updated) {
+                // AC: @trait-error-guidance ac-1, ac-2
+                error(`Session not found: ${sessionId}`);
+                info("Suggestion: Check session ID with: kspec session log list");
+                process.exit(EXIT_CODES.NOT_FOUND);
+                return;
+            }
+            success("Loop end signal sent");
+            if (options.reason) {
+                info(`Reason: ${options.reason}`);
+            }
+        }
+        catch (err) {
+            // AC: @trait-error-guidance ac-1
+            error("Failed to signal end-loop", err);
+            process.exit(EXIT_CODES.ERROR);
+        }
+    });
+}
+//# sourceMappingURL=agent.js.map