@smithers-orchestrator/cli 0.20.1 → 0.20.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@smithers-orchestrator/cli",
-  "version": "0.20.1",
-  "description": "Smithers command-line interface, TUI, MCP server, and local workflow tools",
+  "version": "0.20.4",
+  "description": "Smithers command-line interface, MCP server, and local workflow tools",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -25,8 +25,6 @@
     "@effect/workflow": "^0.18.0",
     "@clack/prompts": "^0.10.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@opentui/core": "^0.1.100",
-    "@opentui/react": "^0.1.100",
     "cron-parser": "^5.5.0",
     "drizzle-orm": "^0.45.2",
     "effect": "^3.21.1",
@@ -34,21 +32,21 @@
     "picocolors": "^1.1.1",
     "react": "^19.2.5",
     "zod": "^4.3.6",
-    "@smithers-orchestrator/accounts": "0.20.1",
-    "@smithers-orchestrator/agents": "0.20.1",
-    "@smithers-orchestrator/components": "0.20.1",
-    "@smithers-orchestrator/db": "0.20.1",
-    "@smithers-orchestrator/devtools": "0.20.1",
-    "@smithers-orchestrator/driver": "0.20.1",
-    "@smithers-orchestrator/engine": "0.20.1",
-    "@smithers-orchestrator/errors": "0.20.1",
-    "@smithers-orchestrator/memory": "0.20.1",
-    "@smithers-orchestrator/observability": "0.20.1",
-    "@smithers-orchestrator/openapi": "0.20.1",
-    "@smithers-orchestrator/protocol": "0.20.1",
-    "@smithers-orchestrator/scheduler": "0.20.1",
-    "@smithers-orchestrator/server": "0.20.1",
-    "@smithers-orchestrator/time-travel": "0.20.1"
+    "@smithers-orchestrator/accounts": "0.20.4",
+    "@smithers-orchestrator/agents": "0.20.4",
+    "@smithers-orchestrator/components": "0.20.4",
+    "@smithers-orchestrator/db": "0.20.4",
+    "@smithers-orchestrator/devtools": "0.20.4",
+    "@smithers-orchestrator/driver": "0.20.4",
+    "@smithers-orchestrator/errors": "0.20.4",
+    "@smithers-orchestrator/observability": "0.20.4",
+    "@smithers-orchestrator/protocol": "0.20.4",
+    "@smithers-orchestrator/scheduler": "0.20.4",
+    "@smithers-orchestrator/engine": "0.20.4",
+    "@smithers-orchestrator/server": "0.20.4",
+    "@smithers-orchestrator/time-travel": "0.20.4",
+    "@smithers-orchestrator/memory": "0.20.4",
+    "@smithers-orchestrator/openapi": "0.20.4"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/agent-detection.js

@@ -91,7 +91,7 @@ const AGENT_VARIANTS = [
         displayName: "Claude Sonnet",
         constructor: {
             importName: "ClaudeCodeAgent",
-            expr: 'new SmithersClaudeCodeAgent({ model: "claude-sonnet-4-6", cwd: process.cwd() })',
+            expr: 'new SmithersClaudeCodeAgent({ model: "claude-sonnet-4-7", cwd: process.cwd() })',
         },
     },
 ];
@@ -108,7 +108,7 @@ const TIER_PREFERENCES = {
 const CONSTRUCTORS = {
     claude: {
         importName: "ClaudeCodeAgent",
-        expr: 'new SmithersClaudeCodeAgent({ model: "claude-opus-4-6", cwd: process.cwd() })',
+        expr: 'new SmithersClaudeCodeAgent({ model: "claude-opus-4-7", cwd: process.cwd() })',
     },
     codex: {
         importName: "CodexAgent",

package/src/event-categories.js

@@ -8,6 +8,7 @@ const EVENT_CATEGORY_BY_TYPE = {
     RunAutoResumeSkipped: "run",
     RunStarted: "run",
     RunStatusChanged: "run",
+    RunStateChanged: "run",
     RunFinished: "run",
     RunFailed: "run",
     RunCancelled: "run",
@@ -49,6 +50,7 @@ const EVENT_CATEGORY_BY_TYPE = {
     RevertFinished: "revert",
     TimeTravelStarted: "revert",
     TimeTravelFinished: "revert",
+    TimeTravelJumped: "revert",
     WorkflowReloadDetected: "workflow",
     WorkflowReloaded: "workflow",
     WorkflowReloadFailed: "workflow",
@@ -67,6 +69,9 @@ const EVENT_CATEGORY_BY_TYPE = {
     TimerCreated: "timer",
     TimerFired: "timer",
     TimerCancelled: "timer",
+    AgentTraceEvent: "agent",
+    AgentTraceSummary: "agent",
+    AgentSessionEvent: "agent",
 };
 const CATEGORY_ALIASES = {
     agent: "agent",

package/src/find-db.js

@@ -15,16 +15,16 @@ import { SmithersError } from "@smithers-orchestrator/errors";
 export function findSmithersDb(from) {
     let dir = resolve(from ?? process.cwd());
     const root = resolve("/");
-    while (true) {
+    while (dir !== root) {
         const candidate = resolve(dir, "smithers.db");
         if (existsSync(candidate))
             return candidate;
-        const parent = dirname(dir);
-        if (parent === dir || dir === root) {
-            throw new SmithersError("CLI_DB_NOT_FOUND", "No smithers.db found. Run this command from a directory containing a smithers.db, or use 'smithers up <workflow>' to start a run first.");
-        }
-        dir = parent;
+        dir = dirname(dir);
     }
+    const rootCandidate = resolve(root, "smithers.db");
+    if (existsSync(rootCandidate))
+        return rootCandidate;
+    throw new SmithersError("CLI_DB_NOT_FOUND", "No smithers.db found. Run this command from a directory containing a smithers.db, or use 'smithers up <workflow>' to start a run first.");
 }
 /**
  * @param {number} ms

package/src/index.js

@@ -484,6 +484,41 @@ function isRunStatusTerminal(status) {
         status !== "waiting-timer" &&
         status !== "waiting-event");
 }
+/**
+ * Fetch a docs file from smithers.sh and write it to stdout.
+ * Honors --json (global) by emitting `{ url, content }`.
+ *
+ * @param {{ error: Function; ok: Function; format?: string; options?: { json?: boolean } }} c
+ * @param {string} url
+ * @param {string} errorCode
+ */
+async function printSmithersDocs(c, url, errorCode) {
+    let body;
+    try {
+        const res = await fetch(url);
+        if (!res.ok) {
+            return c.error({
+                code: errorCode,
+                message: `Failed to fetch ${url}: HTTP ${res.status}`,
+                exitCode: 1,
+            });
+        }
+        body = await res.text();
+    }
+    catch (err) {
+        return c.error({
+            code: errorCode,
+            message: `Failed to fetch ${url}: ${err?.message ?? String(err)}`,
+            exitCode: 1,
+        });
+    }
+    const wantsJson = Boolean(c.options?.json) || c.format === "json";
+    if (wantsJson) {
+        return c.ok({ url, content: body });
+    }
+    process.stdout.write(body.endsWith("\n") ? body : `${body}\n`);
+    return c.ok(undefined);
+}
 /**
  * @param {string | undefined} format
  * @param {unknown} payload
@@ -2266,10 +2301,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 {
@@ -2327,9 +2362,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.
 }
 
 /**
@@ -2551,8 +2585,8 @@ const cli = Cli.create({
                                 { command: "workflow run implement", description: "Run the implementation workflow" },
                             ]
                             : [
-                                { command: "tui", description: "Open the interactive dashboard" },
                                 { command: "workflow list", description: "View all available workflows" },
+                                { command: "workflow run implement", description: "Run the implementation workflow" },
                             ],
                     },
                 });
@@ -2641,49 +2675,6 @@ const cli = Cli.create({
             cleanup();
         }
     },
-})
-    // =========================================================================
-    // smithers tui
-    // =========================================================================
-    .command("tui", {
-    description: "Open the interactive Smithers observability dashboard",
-    async run(c) {
-        const fail = (opts) => {
-            commandExitOverride = opts.exitCode ?? 1;
-            return c.error(opts);
-        };
-        let cleanup;
-        let renderer;
-        try {
-            const db = await findAndOpenDb(undefined, {
-                timeoutMs: 5000,
-                intervalMs: 100,
-            });
-            const adapter = db.adapter;
-            cleanup = db.cleanup;
-            const { createCliRenderer } = await import("@opentui/core");
-            const { createRoot } = await import("@opentui/react");
-            const { TuiApp } = await import("./tui/app.jsx");
-            const React = await import("react");
-            renderer = await createCliRenderer({ exitOnCtrlC: false });
-            const root = createRoot(renderer);
-            await new Promise((resolve) => {
-                root.render(React.createElement(TuiApp, {
-                    adapter,
-                    onExit: () => resolve(true),
-                }));
-            });
-            return c.ok(undefined);
-        }
-        catch (err) {
-            return fail({ code: "TUI_FAILED", message: err?.message ?? String(err), exitCode: 1 });
-        }
-        finally {
-            if (renderer)
-                renderer.destroy();
-            cleanup?.();
-        }
-    }
 })
     // =========================================================================
     // smithers ps
@@ -3437,8 +3428,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" },
@@ -4364,8 +4355,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"),
@@ -4649,7 +4640,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();
@@ -4715,7 +4706,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();
@@ -4754,7 +4745,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();
@@ -4790,7 +4781,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();
@@ -4966,6 +4957,22 @@ const cli = Cli.create({
             return c.error({ code: "GUI_LAUNCH_FAILED", message: err?.message ?? String(err), exitCode: 1 });
         }
     },
+})
+    // =========================================================================
+    // smithers docs / smithers docs-full
+    // Print the published llms.txt / llms-full.txt from smithers.sh.
+    // =========================================================================
+    .command("docs", {
+    description: "Print llms.txt (concise docs index for LLMs) from smithers.sh.",
+    async run(c) {
+        return printSmithersDocs(c, "https://smithers.sh/llms.txt", "DOCS_FETCH_FAILED");
+    },
+})
+    .command("docs-full", {
+    description: "Print llms-full.txt (full docs bundle for LLMs) from smithers.sh.",
+    async run(c) {
+        return printSmithersDocs(c, "https://smithers.sh/llms-full.txt", "DOCS_FULL_FETCH_FAILED");
+    },
 })
     .command(workflowCli)
     .command(cronCli)
@@ -5185,6 +5192,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
  */
@@ -5268,7 +5323,7 @@ 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
@@ -5280,7 +5335,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": {
@@ -5387,6 +5442,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).

package/src/mcp/semantic-tools.js

@@ -601,8 +601,7 @@ async function listAllEvents(adapter, runId) {
             break;
         events.push(...batch);
         lastSeq = batch[batch.length - 1].seq;
-        if (batch.length < 1_000)
-            break;
+        if (batch.length < 1_000) break;
     }
     return events;
 }

package/src/node-detail.js

@@ -89,12 +89,7 @@ function parseErrorSummary(raw) {
         if (message) {
             return { message, detail: parsed };
         }
-        try {
-            return { message: JSON.stringify(parsed), detail: parsed };
-        }
-        catch {
-            return { message: String(parsed), detail: parsed };
-        }
+        return { message: JSON.stringify(parsed), detail: parsed };
     }
     return { message: String(parsed), detail: parsed };
 }

package/src/watch.js

@@ -110,7 +110,7 @@ export async function runWatchLoop(options) {
             tickCount += 1;
             latest = await options.fetch();
             await renderSnapshot(latest, false);
-            if (options.isTerminal?.(latest)) {
+            if (options.isTerminal?.(latest))
                 return {
                     intervalMs,
                     tickCount,
@@ -118,7 +118,6 @@ export async function runWatchLoop(options) {
                     reachedTerminal: true,
                     lastData: latest,
                 };
-            }
         }
     }
     finally {

package/src/why-diagnosis.js

@@ -461,8 +461,7 @@ function computeSignalName(node, descriptor, attempts, events) {
             correlationId ??
                 parseString(payload.correlationId) ??
                 null;
-        if (signalName && correlationId)
-            break;
+        if (signalName && correlationId) break;
     }
     return { signalName, correlationId };
 }

package/src/workflow-pack.js

@@ -133,7 +133,6 @@ function renderPackageJson(versions) {
         dependencies: {
             react: versions.reactVersion,
             "react-dom": versions.reactDomVersion,
-            skills: "github:mattpocock/skills",
             "smithers-orchestrator": smithersSpec,
             zod: versions.zodVersion,
         },
@@ -184,7 +183,7 @@ function renderAgentScaffoldFiles() {
                 '// Built-in Claude Code CLI agent (cliEngine: "claude-code").',
                 "// Tweak `model`, `cwd`, or uncomment extra options below to match your setup.",
                 "export const ClaudeCodeAgent = new SmithersClaudeCodeAgent({",
-                '  model: "claude-opus-4-6",',
+                '  model: "claude-opus-4-7",',
                 "  cwd: process.cwd(),",
                 '  // systemPrompt: "Add shared instructions for every Claude run.",',
                 "  // timeoutMs: 10 * 60 * 1000,",
@@ -280,9 +279,10 @@ function renderPrompts() {
                 "",
                 "Reviewer: {props.reviewer}",
                 "",
-                "Review the following request and respond with a concise JSON object.",
-                "Be a very thorough reviewer who only accepts production ready tested",
-                "code.",
+                "Review the following request and return ONLY the required JSON object.",
+                "Do not include prose, markdown, headings, commentary, or code fences.",
+                "The first character of your response must be `{` and the last character must be `}`.",
+                "Be a very thorough reviewer who only accepts production ready tested code.",
                 "",
                 "REQUEST:",
                 "{props.prompt}",
@@ -290,6 +290,8 @@ function renderPrompts() {
                 "REQUIRED OUTPUT:",
                 "{props.schema}",
                 "",
+                "Return ONLY raw JSON matching the required output schema.",
+                "",
             ].join("\n"),
         },
         {
@@ -413,6 +415,17 @@ function renderPrompts() {
                 "",
             ].join("\n"),
         },
+        {
+            path: ".smithers/prompts/grill-me.mdx",
+            contents: [
+                "Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.",
+                "",
+                "Ask the questions one at a time.",
+                "",
+                "If a question can be answered by exploring the codebase, explore the codebase instead.",
+                "",
+            ].join("\n"),
+        },
         {
             path: ".smithers/prompts/write-a-prd.mdx",
             contents: [
@@ -1185,7 +1198,7 @@ function renderComponents() {
                 "/** @jsxImportSource smithers-orchestrator */",
                 'import { Loop, Sequence, Task, type AgentLike, type OutputTarget } from "smithers-orchestrator";',
                 'import { z } from "zod/v4";',
-                'import GrillMeSkill from "skills/grill-me/SKILL.md";',
+                'import GrillMeSkill from "../prompts/grill-me.mdx";',
                 'import AskUserInstructions from "../prompts/ask-user-instructions.mdx";',
                 "",
                 "export const grillOutputSchema = z.looseObject({",
@@ -3211,7 +3224,7 @@ function renderWorkflows() {
                 "            return (",
                 "              <Worktree",
                 "                key={ticket.slug}",
-                "                path={`.worktrees/${ticket.slug}`}",
+            '                path={resolve(process.cwd(), ".worktrees", ticket.slug)}',
                 "                branch={`ticket/${ticket.slug}`}",
                 "              >",
                 "                <Sequence>",
@@ -3417,10 +3430,9 @@ export function initWorkflowPack(options = {}) {
     };
 }
 /**
- * Install `.smithers/` workspace deps so git-specifier packages like
- * `github:mattpocock/skills` — which Bun's runtime auto-install doesn't fetch —
- * are available the first time a workflow runs. Failures here don't fail init:
- * the scaffold is on disk, the user can always re-run `bun install` by hand.
+ * Install `.smithers/` workspace deps so the first workflow run isn't blocked
+ * on a cold install. Failures here don't fail init: the scaffold is on disk,
+ * the user can always re-run `bun install` by hand.
  *
  * @param {string} rootDir
  * @param {boolean} skip