@smithers-orchestrator/cli 0.20.3 → 0.21.0

package/src/index.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env bun
 import { setJsonMode } from "./util/logger.ts";
+import { findFirstPositionalIndex, parseMcpSurfaceArgv, rewriteBareResumeFlagArgv } from "./argv-utils.js";
+import { CLI_JSON_ARGUMENT_MAX_BYTES, parseJsonArgument, parseJsonInput } from "./json-args.js";
 import { resolve, dirname, basename } from "node:path";
 import { pathToFileURL } from "node:url";
-import { readFileSync, existsSync, openSync, statSync, mkdirSync, writeFileSync } from "node:fs";
+import { readFileSync, existsSync, openSync, statSync } from "node:fs";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { Effect, Fiber } from "effect";
 import { Cli, Mcp as IncurMcp, z } from "incur";
@@ -39,7 +41,18 @@ import { listAccounts, removeAccount } from "@smithers-orchestrator/accounts";
 import { runAgentAdd, pingAccount } from "./agent-commands/runAgentAdd.js";
 import { agentAddWizard } from "./agent-commands/agentAddWizard.js";
 import { initWorkflowPack, getWorkflowFollowUpCtas } from "./workflow-pack.js";
-import { discoverWorkflows, resolveWorkflow, createWorkflowFile } from "./workflows.js";
+import { discoverWorkflows, resolveWorkflow, createWorkflowFile, renderWorkflowSkill, writeWorkflowSkillFiles } from "./workflows.js";
+import {
+    assertEvalRunIdsAvailable,
+    assertEvalReportWritable,
+    buildEvalPlan,
+    buildEvalReport,
+    evaluateEvalCaseResult,
+    loadEvalCases,
+    renderEvalPlan,
+    renderEvalReport,
+    writeEvalReport,
+} from "./eval-suite.js";
 import { ask } from "./ask.js";
 import { runScheduler } from "./scheduler.js";
 import { resumeRunDetached } from "./resume-detached.js";
@@ -47,6 +60,7 @@ import { formatCliAgentCapabilityDoctorReport, getCliAgentCapabilityDoctorReport
 import { parseDurationMs, supervisorLoopEffect, } from "./supervisor.js";
 import { WATCH_MIN_INTERVAL_MS, runWatchLoop, watchIntervalSecondsToMs, } from "./watch.js";
 import { createSemanticMcpServer } from "./mcp/semantic-server.js";
+import { parseTokenScopes, readSmithersTokenStore, smithersTokenStorePath, writeSmithersTokenStore, } from "./token-store.js";
 import pc from "picocolors";
 import crypto from "node:crypto";
 import React from "react";
@@ -105,43 +119,9 @@ function readPackageVersion() {
         return "unknown";
     }
 }
-function smithersTokenStorePath() {
-    return process.env.SMITHERS_TOKEN_STORE ?? resolve(process.env.HOME ?? process.cwd(), ".smithers", "tokens.json");
-}
-function readSmithersTokenStore() {
-    const path = smithersTokenStorePath();
-    if (!existsSync(path)) {
-        return { tokens: {} };
-    }
-    try {
-        const parsed = JSON.parse(readFileSync(path, "utf8"));
-        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-            return { tokens: {} };
-        }
-        const tokens = parsed.tokens && typeof parsed.tokens === "object" && !Array.isArray(parsed.tokens)
-            ? parsed.tokens
-            : {};
-        return { tokens };
-    }
-    catch {
-        return { tokens: {} };
-    }
-}
-function writeSmithersTokenStore(store) {
-    const path = smithersTokenStorePath();
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, `${JSON.stringify(store, null, 2)}\n`, { mode: 0o600 });
-}
-function parseTokenScopes(raw) {
-    return raw
-        .split(/[,\s]+/)
-        .map((scope) => scope.trim())
-        .filter(Boolean);
-}
 const CLI_ARGUMENT_MAX_LENGTH = 4096;
 const CLI_IDENTIFIER_MAX_LENGTH = 256;
 const CLI_TEXT_ARGUMENT_MAX_LENGTH = 64 * 1024;
-const CLI_JSON_ARGUMENT_MAX_BYTES = 1024 * 1024;
 const CLI_HANDLER_BOUNDS_WRAPPED = Symbol("smithers.cliHandlerBoundsWrapped");
 /**
  * @param {string} path
@@ -240,55 +220,6 @@ function wrapCliCommandHandlersWithInputBounds(commands) {
         entry[CLI_HANDLER_BOUNDS_WRAPPED] = true;
     }
 }
-/**
- * @param {string | undefined} raw
- * @param {string} label
- * @param {FailFn} fail
- */
-function parseJsonInput(raw, label, fail) {
-    if (!raw)
-        return undefined;
-    try {
-        return JSON.parse(raw);
-    }
-    catch (err) {
-        return fail({
-            code: "INVALID_JSON",
-            message: `Invalid JSON for ${label}: ${err?.message ?? String(err)}`,
-            exitCode: 4,
-        });
-    }
-}
-/**
- * @param {string | undefined} raw
- * @param {FailFn} fail
- * @returns {Record<string, string | number | boolean> | undefined}
- */
-function parseAnnotations(raw, fail) {
-    const parsed = parseJsonInput(raw, "annotations", fail);
-    if (parsed === undefined)
-        return undefined;
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-        return fail({
-            code: "INVALID_ANNOTATIONS",
-            message: "Run annotations must be a flat JSON object of string/number/boolean values",
-            exitCode: 4,
-        });
-    }
-    /** @type {Record<string, string | number | boolean>} */
-    const annotations = {};
-    for (const [key, value] of Object.entries(parsed)) {
-        if (!["string", "number", "boolean"].includes(typeof value)) {
-            return fail({
-                code: "INVALID_ANNOTATIONS",
-                message: `Run annotation ${key} must be a string, number, or boolean`,
-                exitCode: 4,
-            });
-        }
-        annotations[key] = /** @type {string | number | boolean} */ (value);
-    }
-    return annotations;
-}
 /**
  * @param {string | undefined} status
  */
@@ -1308,6 +1239,24 @@ const upOptions = z.object({
     authToken: z.string().optional().describe("Bearer token for HTTP auth (or set SMITHERS_API_KEY)"),
     metrics: z.boolean().default(true).describe("Expose /metrics endpoint (with --serve)"),
 });
+const evalOptions = z.object({
+    cases: z.string().describe("JSON or JSONL eval case file"),
+    suite: z.string().optional().describe("Stable suite ID used in run IDs and report paths"),
+    runLabel: z.string().optional().describe("Run label appended to eval run IDs; defaults to current UTC timestamp plus a nonce"),
+    dryRun: z.boolean().default(false).describe("Plan the suite without launching runs"),
+    concurrency: z.number().int().min(1).max(16).default(1).describe("Number of eval cases to run at once"),
+    maxCases: z.number().int().min(1).optional().describe("Run only the first N cases"),
+    report: z.string().optional().describe("Write report JSON to this path"),
+    force: z.boolean().default(false).describe("Overwrite an existing eval report"),
+    includeOutput: z.boolean().default(true).describe("Include workflow outputs in the report"),
+    maxConcurrency: z.number().int().min(1).optional().describe("Per-workflow max task concurrency"),
+    root: z.string().optional().describe("Tool sandbox root directory"),
+    log: z.boolean().default(true).describe("Enable NDJSON event log file output"),
+    logDir: z.string().optional().describe("NDJSON event logs directory"),
+    allowNetwork: z.boolean().default(false).describe("Allow bash tool network requests"),
+    maxOutputBytes: z.number().int().min(1).optional().describe("Max bytes a single tool call can return"),
+    toolTimeoutMs: z.number().int().min(1).optional().describe("Max wall-clock time per tool call in ms"),
+});
 const superviseOptions = z.object({
     dryRun: z.boolean().default(false).describe("Show which stale runs would be resumed, without acting"),
     interval: z.string().default("10s").describe("Poll interval (e.g. 10s, 30s, 1m)"),
@@ -1347,7 +1296,7 @@ const chatOptions = z.object({
     stderr: z.boolean().default(true).describe("Include agent stderr output"),
 });
 const chatCreateOptions = z.object({
-    agent: z.enum(["claude-code", "codex", "gemini"]).describe("CLI agent engine to launch"),
+    agent: z.enum(["claude-code", "codex", "antigravity", "gemini"]).describe("CLI agent engine to launch"),
     cwd: z.string().optional().describe("Working directory for the chat session (default: current directory)"),
 });
 const inspectArgs = z.object({
@@ -1438,6 +1387,13 @@ const workflowPathArgs = z.object({
 const workflowDoctorArgs = z.object({
     name: z.string().optional().describe("Workflow ID"),
 });
+const workflowSkillArgs = z.object({
+    name: z.string().optional().describe("Workflow ID, or omit to generate skills for all workflows"),
+});
+const workflowSkillOptions = z.object({
+    output: z.string().optional().describe("Output file for one workflow, or output directory for all workflows"),
+    force: z.boolean().default(false).describe("Overwrite existing skill files"),
+});
 const workflowRunOptions = upOptions.extend({
     prompt: z.string().optional().describe("Prompt text mapped to input.prompt when --input is omitted"),
 });
@@ -1455,6 +1411,54 @@ function normalizeWorkflowRunOptions(options) {
         root: options.root ?? ".",
     };
 }
+function formatRequestedJsonOutput() {
+    for (let index = 0; index < process.argv.length; index += 1) {
+        const arg = process.argv[index];
+        if (arg === "--format") {
+            const value = process.argv[index + 1];
+            return value === "json" || value === "jsonl";
+        }
+        if (arg === "--format=json" || arg === "--format=jsonl") {
+            return true;
+        }
+    }
+    return false;
+}
+function defaultEvalRunLabel() {
+    const timestamp = new Date().toISOString().replace(/[-:TZ.]/g, "").slice(0, 14);
+    return `${timestamp}-${crypto.randomUUID().slice(0, 8)}`;
+}
+/**
+ * @param {string} workflowInput
+ */
+function resolveWorkflowPathForEval(workflowInput) {
+    const asPath = resolve(process.cwd(), workflowInput);
+    if (existsSync(asPath)) {
+        return workflowInput;
+    }
+    return resolveWorkflow(workflowInput, process.cwd()).entryFile;
+}
+/**
+ * @template T
+ * @template R
+ * @param {T[]} items
+ * @param {number} limit
+ * @param {(item: T, index: number) => Promise<R>} worker
+ * @returns {Promise<R[]>}
+ */
+async function runWithLimit(items, limit, worker) {
+    const results = new Array(items.length);
+    let cursor = 0;
+    const workerCount = Math.min(limit, items.length);
+    await Promise.all(Array.from({ length: workerCount }, async () => {
+        while (cursor < items.length) {
+            const index = cursor;
+            cursor += 1;
+            results[index] = await worker(items[index], index);
+        }
+    }));
+    return results;
+}
 /**
  * @param {string} intervalRaw
  * @param {string} staleThresholdRaw
@@ -1515,8 +1519,42 @@ function normalizeEventsQuery(options) {
 async function executeUpCommand(c, workflowPath, options, fail) {
     try {
         const resolvedWorkflowPath = resolve(process.cwd(), workflowPath);
-        const input = parseJsonInput(options.input, "input", fail) ?? {};
-        const annotations = parseAnnotations(options.annotations, fail);
+        let input;
+        let annotations;
+        try {
+            input = parseJsonArgument(options.input, "input") ?? {};
+            const parsedAnnotations = parseJsonArgument(options.annotations, "annotations");
+            if (parsedAnnotations === undefined) {
+                annotations = undefined;
+            }
+            else if (!parsedAnnotations || typeof parsedAnnotations !== "object" || Array.isArray(parsedAnnotations)) {
+                return fail({
+                    code: "INVALID_ANNOTATIONS",
+                    message: "Run annotations must be a flat JSON object of string/number/boolean values",
+                    exitCode: 4,
+                });
+            }
+            else {
+                annotations = {};
+                for (const [key, value] of Object.entries(parsedAnnotations)) {
+                    if (!["string", "number", "boolean"].includes(typeof value)) {
+                        return fail({
+                            code: "INVALID_ANNOTATIONS",
+                            message: `Run annotation ${key} must be a string, number, or boolean`,
+                            exitCode: 4,
+                        });
+                    }
+                    annotations[key] = /** @type {string | number | boolean} */ (value);
+                }
+            }
+        }
+        catch (err) {
+            return fail({
+                code: err instanceof SmithersError ? err.code : "INVALID_JSON",
+                message: err?.message ?? String(err),
+                exitCode: 4,
+            });
+        }
         const { resume, resumeRunId } = normalizeResumeOption(options.resume);
         const runId = options.runId ?? resumeRunId;
         // Detached mode: spawn ourselves as a background process
@@ -1526,9 +1564,9 @@ async function executeUpCommand(c, workflowPath, options, fail) {
             if (runId)
                 childArgs.push("--run-id", runId);
             if (options.input)
-                childArgs.push("--input", options.input);
+                childArgs.push("--input", options.input === "-" ? JSON.stringify(input) : options.input);
             if (options.annotations)
-                childArgs.push("--annotations", options.annotations);
+                childArgs.push("--annotations", options.annotations === "-" ? JSON.stringify(annotations ?? {}) : options.annotations);
             if (options.maxConcurrency)
                 childArgs.push("--max-concurrency", String(options.maxConcurrency));
             if (options.root)
@@ -1611,6 +1649,13 @@ async function executeUpCommand(c, workflowPath, options, fail) {
                 exitCode: 4,
             });
         }
+        if (Boolean(options.resumeClaimOwner) !== Boolean(options.resumeClaimHeartbeat)) {
+            return fail({
+                code: "INVALID_RESUME_CLAIM",
+                message: "--resume-claim-owner and --resume-claim-heartbeat must be provided together.",
+                exitCode: 4,
+            });
+        }
         const workflow = await loadWorkflow(workflowPath);
         ensureSmithersTables(workflow.db);
         if (options.hot) {
@@ -1644,13 +1689,6 @@ async function executeUpCommand(c, workflowPath, options, fail) {
         const logDir = options.log ? options.logDir : null;
         const onProgress = buildProgressReporter();
         const abort = setupAbortSignal();
-        if (Boolean(options.resumeClaimOwner) !== Boolean(options.resumeClaimHeartbeat)) {
-            return fail({
-                code: "INVALID_RESUME_CLAIM",
-                message: "--resume-claim-owner and --resume-claim-heartbeat must be provided together.",
-                exitCode: 4,
-            });
-        }
         const resumeClaim = options.resumeClaimOwner && options.resumeClaimHeartbeat
             ? {
                 claimOwnerId: options.resumeClaimOwner,
@@ -1870,6 +1908,49 @@ const workflowCli = Cli.create({
             });
         }
     },
+})
+    .command("inspect", {
+    description: "Show workflow metadata and an agent-facing skill preview.",
+    args: workflowPathArgs,
+    run(c) {
+        const workflow = resolveWorkflow(c.args.name, process.cwd());
+        return c.ok({
+            workflow,
+            skillPreview: renderWorkflowSkill(workflow, { root: process.cwd() }),
+        });
+    },
+})
+    .command("skills", {
+    description: "Generate agent-facing skill docs for local workflows.",
+    args: workflowSkillArgs,
+    options: workflowSkillOptions,
+    run(c) {
+        const fail = (opts) => {
+            commandExitOverride = opts.exitCode ?? 1;
+            return c.error(opts);
+        };
+        try {
+            return c.ok(writeWorkflowSkillFiles(process.cwd(), {
+                workflowId: c.args.name ?? "all",
+                output: c.options.output,
+                force: c.options.force,
+            }));
+        }
+        catch (err) {
+            if (err instanceof SmithersError) {
+                return fail({
+                    code: err.code,
+                    message: err.message,
+                    exitCode: 4,
+                });
+            }
+            return fail({
+                code: "WORKFLOW_SKILLS_FAILED",
+                message: err?.message ?? String(err),
+                exitCode: 1,
+            });
+        }
+    },
 })
     .command("doctor", {
     description: "Inspect workflow discovery, preload files, and detected agents.",
@@ -2039,7 +2120,7 @@ const agentsCli = Cli.create({
     description: "Register a Smithers agent account (interactive wizard, or non-interactive via flags).",
     options: z.object({
         provider: z.enum([
-            "claude-code", "codex", "gemini", "kimi",
+            "claude-code", "antigravity", "codex", "gemini", "kimi",
             "anthropic-api", "openai-api", "gemini-api",
         ]).optional().describe("Provider id; omit to launch the interactive wizard"),
         label: z.string().optional().describe("Unique label, e.g. 'claude-work'"),
@@ -2301,10 +2382,10 @@ let lastDevtoolsCommandOutcome;
  * friendly typed error the helper already wrote to stderr (finding #2).
  *
  * @param {"tree"|"diff"|"output"|"rewind"} cmd
- * @param {{ args: any; options: any; ok: (d?: unknown) => unknown }} c
+ * @param {{ args: any; options: any }} c
  * @param {() => Promise<number>} handler
  */
-async function runDevtoolsCommandWithTelemetry(cmd, c, handler) {
+async function* runDevtoolsCommandWithTelemetry(cmd, c, handler) {
     const startedAt = Date.now();
     let exitCode = 0;
     try {
@@ -2362,9 +2443,8 @@ async function runDevtoolsCommandWithTelemetry(cmd, c, handler) {
             // best-effort metrics.
         }
     }
-    // Return c.ok(undefined) so incur does not emit an additional
-    // envelope on stdout (finding #2).
-    return c.ok(undefined);
+    // This is an empty stream so Incur does not emit an additional envelope
+    // or framework CTA on stdout after the helper has already written output.
 }
 
 /**
@@ -2623,6 +2703,141 @@ const cli = Cli.create({
         };
         return executeUpCommand(c, c.args.workflow, c.options, fail);
     },
+})
+    // =========================================================================
+    // smithers eval <workflow>
+    // =========================================================================
+    .command("eval", {
+    description: "Run a workflow over a JSON/JSONL eval suite and write a regression report.",
+    args: workflowArgs,
+    options: evalOptions,
+    alias: { cases: "c", suite: "s", dryRun: "n", concurrency: "j", report: "r" },
+    async run(c) {
+        const fail = (opts) => {
+            commandExitOverride = opts.exitCode ?? 1;
+            return c.error(opts);
+        };
+        try {
+            const workflowPath = resolveWorkflowPathForEval(c.args.workflow);
+            const loadedCases = loadEvalCases(process.cwd(), c.options.cases, {
+                maxCases: c.options.maxCases,
+            });
+            const plan = buildEvalPlan({
+                suiteId: c.options.suite,
+                runLabel: c.options.runLabel ?? defaultEvalRunLabel(),
+                workflowPath,
+                casesPath: c.options.cases,
+                loadedCases,
+            });
+            const wantsStructured = c.format === "json" || c.format === "jsonl" || formatRequestedJsonOutput();
+            if (c.options.dryRun) {
+                if (wantsStructured) {
+                    return c.ok({ suite: plan });
+                }
+                process.stdout.write(`${renderEvalPlan(plan)}\n`);
+                return c.ok(undefined);
+            }
+            assertEvalReportWritable(process.cwd(), plan.suiteId, {
+                path: c.options.report,
+                force: c.options.force,
+            });
+            const workflow = await loadWorkflow(workflowPath);
+            ensureSmithersTables(workflow.db);
+            await assertEvalRunIdsAvailable(new SmithersDb(workflow.db), plan.cases);
+            setupSqliteCleanup(workflow);
+            const schema = resolveSchema(workflow.db);
+            const resolvedWorkflowPath = resolve(process.cwd(), workflowPath);
+            const rootDir = c.options.root ? resolve(process.cwd(), c.options.root) : dirname(resolvedWorkflowPath);
+            const logDir = c.options.log ? c.options.logDir : null;
+            const abort = setupAbortSignal();
+            const startedAtMs = Date.now();
+            const results = await runWithLimit(plan.cases, c.options.concurrency, async (testCase) => {
+                const caseStartedAtMs = Date.now();
+                process.stderr.write(`[eval:${plan.suiteId}] ${testCase.id} -> ${testCase.runId}\n`);
+                try {
+                    const result = await Effect.runPromise(runWorkflow(workflow, {
+                        input: testCase.input,
+                        runId: testCase.runId,
+                        workflowPath: resolvedWorkflowPath,
+                        maxConcurrency: c.options.maxConcurrency,
+                        rootDir,
+                        logDir,
+                        allowNetwork: c.options.allowNetwork,
+                        maxOutputBytes: c.options.maxOutputBytes,
+                        toolTimeoutMs: c.options.toolTimeoutMs,
+                        annotations: {
+                            suiteId: plan.suiteId,
+                            caseId: testCase.id,
+                            ...testCase.annotations,
+                        },
+                        signal: abort.signal,
+                    }));
+                    const output = await loadOutputs(workflow.db, schema, testCase.runId);
+                    const durationMs = Date.now() - caseStartedAtMs;
+                    const evaluation = evaluateEvalCaseResult(testCase, {
+                        ...result,
+                        output,
+                    });
+                    return {
+                        caseId: testCase.id,
+                        runId: testCase.runId,
+                        expectedStatus: testCase.expected.status,
+                        status: result.status,
+                        passed: evaluation.passed,
+                        assertions: evaluation.assertions,
+                        durationMs,
+                        input: testCase.input,
+                        ...(c.options.includeOutput ? { output } : {}),
+                        metadata: testCase.metadata,
+                    };
+                }
+                catch (err) {
+                    const errorMessage = err?.message ?? String(err);
+                    const durationMs = Date.now() - caseStartedAtMs;
+                    const evaluation = evaluateEvalCaseResult(testCase, {
+                        status: "error",
+                        error: err,
+                    });
+                    return {
+                        caseId: testCase.id,
+                        runId: testCase.runId,
+                        expectedStatus: testCase.expected.status,
+                        status: "error",
+                        passed: evaluation.passed,
+                        assertions: evaluation.assertions,
+                        durationMs,
+                        input: testCase.input,
+                        error: errorMessage,
+                        metadata: testCase.metadata,
+                    };
+                }
+            });
+            const finishedAtMs = Date.now();
+            let report = buildEvalReport({
+                plan,
+                results,
+                startedAtMs,
+                finishedAtMs,
+            });
+            const reportPath = writeEvalReport(process.cwd(), report, {
+                path: c.options.report,
+                force: c.options.force,
+            });
+            report = { ...report, reportPath };
+            process.exitCode = report.summary.failed > 0 ? 1 : 0;
+            if (wantsStructured) {
+                return c.ok({ eval: report });
+            }
+            process.stdout.write(`${renderEvalReport(report)}\n`);
+            return c.ok(undefined);
+        }
+        catch (err) {
+            if (err instanceof SmithersError) {
+                return fail({ code: err.code, message: err.message, exitCode: 4 });
+            }
+            return fail({ code: "EVAL_FAILED", message: err?.message ?? String(err), exitCode: 1 });
+        }
+    },
 })
     // =========================================================================
     // smithers supervise
@@ -3429,8 +3644,8 @@ const cli = Cli.create({
     // =========================================================================
     // smithers inspect <run_id>
     // =========================================================================
-    .command("inspect", {
-    description: "Output detailed state of a run: steps, agents, approvals, and outputs.",
+.command("inspect", {
+    description: "Output detailed run state, including steps, agents, approvals, and outputs.",
     args: inspectArgs,
     options: inspectOptions,
     alias: { watch: "w", interval: "i" },
@@ -4356,8 +4571,8 @@ const cli = Cli.create({
     // =========================================================================
     // smithers timetravel <workflow>
     // =========================================================================
-    .command("timetravel", {
-    description: "Time-travel to a previous task state: revert filesystem, reset DB, and optionally resume.",
+.command("timetravel", {
+    description: "Time-travel to a previous task state by reverting filesystem state, resetting DB state, and optionally resuming.",
     args: workflowArgs,
     options: z.object({
         runId: z.string().describe("Run ID"),
@@ -4488,7 +4703,7 @@ const cli = Cli.create({
         question: z.string().optional().describe("The question to ask"),
     }),
     options: z.object({
-        agent: z.enum(["claude", "codex", "gemini", "kimi", "pi"]).optional().describe("Explicitly select which agent CLI to use"),
+        agent: z.enum(["claude", "codex", "antigravity", "gemini", "kimi", "pi"]).optional().describe("Explicitly select which agent CLI to use"),
         listAgents: z.boolean().default(false).describe("List detected agents plus their bootstrap mode and exit"),
         dumpPrompt: z.boolean().default(false).describe("Print the generated system prompt and exit"),
         toolSurface: z.enum(["semantic", "raw"]).default("semantic").describe("Choose which Smithers MCP tool surface to expose"),
@@ -4641,7 +4856,7 @@ const cli = Cli.create({
     // rewrites raw `--json` → `-j` for these commands so it lands as a
     // command option, not a format directive.
     alias: { json: "j" },
-    async run(c) {
+    run(c) {
         return runDevtoolsCommandWithTelemetry("tree", c, async () => {
             const { runTreeOnce, runTreeWatch } = await import("./tree.js");
             const { adapter, cleanup } = await findAndOpenDb();
@@ -4707,7 +4922,7 @@ const cli = Cli.create({
         color: z.enum(["auto", "always", "never"]).default("auto").describe("Colorize output"),
     }),
     alias: { json: "j" },
-    async run(c) {
+    run(c) {
         return runDevtoolsCommandWithTelemetry("diff", c, async () => {
             const { runDiffOnce } = await import("./diff.js");
             const { adapter, cleanup } = await findAndOpenDb();
@@ -4746,7 +4961,7 @@ const cli = Cli.create({
         pretty: z.boolean().default(false).describe("Schema-ordered render"),
     }),
     alias: { json: "j" },
-    async run(c) {
+    run(c) {
         return runDevtoolsCommandWithTelemetry("output", c, async () => {
             const { runOutputOnce } = await import("./output.js");
             const { adapter, cleanup } = await findAndOpenDb();
@@ -4782,7 +4997,7 @@ const cli = Cli.create({
         json: z.boolean().default(false).describe("Emit JumpResult JSON"),
     }),
     alias: { json: "j" },
-    async run(c) {
+    run(c) {
         return runDevtoolsCommandWithTelemetry("rewind", c, async () => {
             const { runRewindOnce } = await import("./rewind.js");
             const { adapter, cleanup } = await findAndOpenDb();
@@ -4990,10 +5205,10 @@ wrapCliCommandHandlersWithInputBounds(cliCommands);
 // Main
 // ---------------------------------------------------------------------------
 const KNOWN_COMMANDS = new Set([
-    "init", "up", "supervise", "down", "ps", "logs", "events", "chat", "inspect", "node", "why", "approve", "deny",
-    "cancel", "graph", "revert", "scores", "observability", "workflow", "ask", "cron", "chat-create",
-    "replay", "diff", "fork", "timeline", "memory", "openapi", "token", "agents", "alerts",
-    "tree", "output", "rewind", "gui",
+    ...cliCommands.keys(),
+    "completions",
+    "mcp",
+    "skills",
 ]);
 /**
  * Rewrite `smithers .` or `smithers <path>` (when path looks like a directory) to `smithers gui <path>`.
@@ -5032,54 +5247,15 @@ function resolveCliColor(mode, stream) {
     if (process.env.NO_COLOR !== undefined && process.env.NO_COLOR.length > 0) return false;
     return Boolean(stream.isTTY);
 }
-const BUILTIN_FLAGS_WITH_VALUES = new Set([
-    "--format",
-    "--filter-output",
-    "--token-limit",
-    "--token-offset",
-]);
 const WORKFLOW_UTILITY_COMMANDS = new Set([
     "run",
     "list",
     "path",
     "create",
+    "inspect",
+    "skills",
     "doctor",
 ]);
-/**
- * @param {string | undefined} value
- * @returns {McpSurface}
- */
-function normalizeMcpSurface(value) {
-    const surface = value?.trim().toLowerCase();
-    if (surface === undefined || surface.length === 0) {
-        throw new Error("Missing value for --surface. Expected semantic, raw, or both.");
-    }
-    if (surface === "semantic" || surface === "raw" || surface === "both") {
-        return surface;
-    }
-    throw new Error(`Invalid --surface value: ${value}. Expected semantic, raw, or both.`);
-}
-/**
- * @param {string[]} argv
- */
-function parseMcpSurfaceArgv(argv) {
-    let surface = "semantic";
-    const filtered = [];
-    for (let index = 0; index < argv.length; index++) {
-        const arg = argv[index];
-        if (arg === "--surface") {
-            surface = normalizeMcpSurface(argv[index + 1]);
-            index += 1;
-            continue;
-        }
-        if (arg.startsWith("--surface=")) {
-            surface = normalizeMcpSurface(arg.slice("--surface=".length));
-            continue;
-        }
-        filtered.push(arg);
-    }
-    return { surface, argv: filtered };
-}
 /**
  * @param {ReturnType<typeof createSemanticMcpServer>} server
  */
@@ -5104,22 +5280,6 @@ function registerRawToolsOnMcpServer(server) {
         });
     }
 }
-/**
- * @param {string[]} argv
- * @returns {number}
- */
-function findFirstPositionalIndex(argv, startIndex = 0) {
-    for (let index = startIndex; index < argv.length; index++) {
-        const arg = argv[index];
-        if (!arg.startsWith("-")) {
-            return index;
-        }
-        if (BUILTIN_FLAGS_WITH_VALUES.has(arg)) {
-            index++;
-        }
-    }
-    return -1;
-}
 /**
  * @param {string[]} argv
  */
@@ -5193,6 +5353,54 @@ function argvRequestsJsonMode(argv) {
     }
     return false;
 }
+/**
+ * Some commands own stdout completely and promise a raw JSON document even
+ * without `--format json`. Run those before Incur can append framework CTAs
+ * such as the stale-skills reminder, which would make stdout unparsable.
+ *
+ * @param {string[]} argv
+ * @returns {boolean}
+ */
+function runRawJsonAgentCommandIfMatched(argv) {
+    const positionals = [];
+    let jsonOutput = false;
+    for (let index = 0; index < argv.length; index++) {
+        const arg = argv[index];
+        if (arg === "--json") {
+            jsonOutput = true;
+            continue;
+        }
+        if (arg === "--format") {
+            if (argv[index + 1] !== "json") {
+                return false;
+            }
+            jsonOutput = true;
+            index += 1;
+            continue;
+        }
+        if (arg === "--format=json") {
+            jsonOutput = true;
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            return false;
+        }
+        positionals.push(arg);
+    }
+    if (positionals.length !== 2 || positionals[0] !== "agents") {
+        return false;
+    }
+    if (positionals[1] === "capabilities") {
+        process.stdout.write(`${JSON.stringify(getCliAgentCapabilityReport(), null, 2)}\n`);
+        process.exit(0);
+    }
+    if (positionals[1] === "doctor" && jsonOutput) {
+        const report = getCliAgentCapabilityDoctorReport();
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+        process.exit(report.ok ? 0 : 1);
+    }
+    return false;
+}
 /**
  * @param {string[]} argv
  */
@@ -5240,17 +5448,6 @@ function rewriteEventsJsonFlagArgv(argv) {
     }
     return argv.map((arg) => (arg === "--json" ? "-j" : arg));
 }
-/**
- * Incur treats union-typed options as value-bearing flags, so a bare
- * `--resume --run-id value` would consume `--run-id` as the resume value.
- *
- * @param {string[]} argv
- */
-function rewriteBareResumeFlagArgv(argv) {
-    return argv.map((arg, index) => arg === "--resume" && (argv[index + 1] === undefined || argv[index + 1]?.startsWith("-"))
-        ? "--resume=true"
-        : arg);
-}
 /**
  * @param {unknown} value
  */
@@ -5276,10 +5473,10 @@ function normalizeResumeOption(value) {
 const CHAT_CREATE_PROMPT = [
     "Start an interactive chat session with the user and help them directly.",
     "Stay in this conversation until the user is done.",
-    'When you are completely finished and want to hand control back to Smithers, end your final response with an empty JSON object in a ```json fence: {}.',
+    'When you are completely finished and want to hand control back to Smithers, return ONLY this raw JSON object with no prose, markdown, or code fence: {}.',
 ].join("\n\n");
 /**
- * @param {"claude-code" | "codex" | "gemini"} agentId
+ * @param {"claude-code" | "codex" | "antigravity" | "gemini"} agentId
  * @param {string} cwd
  */
 async function createChatAgent(agentId, cwd) {
@@ -5288,7 +5485,7 @@ async function createChatAgent(agentId, cwd) {
             const { ClaudeCodeAgent } = await import("@smithers-orchestrator/agents/ClaudeCodeAgent");
             return new ClaudeCodeAgent({
                 cwd,
-                model: "claude-opus-4-6",
+                model: "claude-opus-4-7",
             });
         }
         case "codex": {
@@ -5299,6 +5496,12 @@ async function createChatAgent(agentId, cwd) {
                 skipGitRepoCheck: true,
             });
         }
+        case "antigravity": {
+            const { AntigravityAgent } = await import("@smithers-orchestrator/agents/AntigravityAgent");
+            return new AntigravityAgent({
+                cwd,
+            });
+        }
         case "gemini": {
             const { GeminiAgent } = await import("@smithers-orchestrator/agents/GeminiAgent");
             return new GeminiAgent({
@@ -5309,7 +5512,7 @@ async function createChatAgent(agentId, cwd) {
     }
 }
 /**
- * @param {"claude-code" | "codex" | "gemini"} agentId
+ * @param {"claude-code" | "codex" | "antigravity" | "gemini"} agentId
  * @param {string} cwd
  * @returns {Promise<import("@smithers-orchestrator/components/SmithersWorkflow").SmithersWorkflow<any>>}
  */
@@ -5395,6 +5598,9 @@ async function main() {
     if (argvRequestsJsonMode(argv)) {
         setJsonMode(true);
     }
+    if (runRawJsonAgentCommandIfMatched(argv)) {
+        return;
+    }
     // Finding #1: pre-validate argv for devtools commands so missing-args
     // / invalid-flag errors go to stderr with exit 1 (not incur's
     // remap-to-4 VALIDATION_ERROR envelope on stdout).
@@ -5411,6 +5617,12 @@ async function main() {
             ...argv.slice(firstPositionalIndex),
         ];
     }
+    const commandIndex = findFirstPositionalIndex(argv);
+    const command = commandIndex >= 0 ? argv[commandIndex] : undefined;
+    if (command && !KNOWN_COMMANDS.has(command)) {
+        console.error(`Unknown command: ${command}`);
+        process.exit(4);
+    }
     argv = rewriteBareResumeFlagArgv(argv);
     // --mcp mode: the MCP server needs to stay alive listening on stdin.
     if (argv.includes("--mcp")) {