@nodetool-ai/cli 0.7.0-rc.23 → 0.8.1

package/dist/nodetool.js

@@ -13,49 +13,107 @@
  *   nodetool settings show
  */
 import { program } from "commander";
+import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import { dirname, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
 import { createInterface } from "node:readline";
-import { createTRPCClient, httpBatchLink } from "@trpc/client";
-import superjson from "superjson";
 import { workflowToDsl } from "@nodetool-ai/dsl";
-import { initDb, Workflow, Secret, getSecret } from "@nodetool-ai/models";
-import { getDefaultDbPath } from "@nodetool-ai/config";
-import { WorkflowRunner } from "@nodetool-ai/kernel";
-import { NodeRegistry } from "@nodetool-ai/node-sdk";
+import { initDb, Workflow, Asset, Secret, getSecret } from "@nodetool-ai/models";
+import { readCachedHfModels, searchCachedHfModels } from "@nodetool-ai/huggingface";
+import { initMasterKey } from "@nodetool-ai/security";
+import { installLocalModelInterfaces } from "./local-model-interfaces.js";
+import { getDefaultDbPath, getDefaultAssetsPath } from "@nodetool-ai/config";
+import { ExecutionSession, isExecutionPreflightError } from "@nodetool-ai/execution";
+import { NodeRegistry, createGraphNodeTypeResolver } from "@nodetool-ai/node-sdk";
 import { registerBaseNodes } from "@nodetool-ai/base-nodes";
 import { registerElevenLabsNodes } from "@nodetool-ai/elevenlabs-nodes";
+import { registerMinimaxNodes } from "@nodetool-ai/minimax-nodes";
 import { registerTransformersJsNodes } from "@nodetool-ai/transformers-js-nodes";
 import { registerFalNodes } from "@nodetool-ai/fal-nodes";
 import { registerReplicateNodes } from "@nodetool-ai/replicate-nodes";
-import { ProcessingContext, initTelemetry } from "@nodetool-ai/runtime";
+import { registerReveNodes } from "@nodetool-ai/reve-nodes";
+import { registerHuggingFaceNodes } from "@nodetool-ai/huggingface-nodes";
+import { ProcessingContext, createLocalWorkspace, initTelemetry, onPythonBridgeCreated } from "@nodetool-ai/runtime";
+import { FileStorageAdapter } from "@nodetool-ai/storage";
+import { mkdirSync } from "node:fs";
+import { addSupervisorOptions, createSupervisorHandle, parseSupervisorFlags, printSupervisedSummary, recordSupervisorCost, streamInterventionLines } from "./supervisor.js";
 import { registerPackageCommands } from "./commands/package.js";
-import { registerDeployCommands, registerListGcpOptions } from "./commands/deploy.js";
+import { registerPackCommands } from "./commands/packs.js";
+import { registerDeployCommands } from "./commands/deploy.js";
 import { registerHfCommands } from "./commands/models-hf.js";
+import { registerWorkerCommands } from "./commands/worker.js";
+import { installWorkerActivityHeartbeat } from "@nodetool-ai/compute";
 import { registerRecommendedCommand } from "./commands/models-recommended.js";
 import { registerAgentCommands } from "./commands/agent.js";
+import { registerDbCommands } from "./commands/db.js";
+import { registerDebugCommands } from "./commands/debug.js";
+import { registerAppCommands } from "./commands/app.js";
+import { registerAppsCommands } from "./commands/apps.js";
+import { registerValidateCommand } from "./commands/validate.js";
+import { registerTimelineCommands } from "./commands/timeline.js";
+import { registerSketchCommands } from "./commands/sketch.js";
+import { registerJsScriptCommands } from "./commands/js-script.js";
+import { registerReliabilityCommands } from "./commands/reliability.js";
+import { registerNodeCommands } from "./commands/node.js";
+import { registerGenerateCommand } from "./commands/generate.js";
+import { registerEvalCommand } from "./commands/eval.js";
+import { registerJtbdCommand } from "./commands/jtbd.js";
+import { registerAffectedCommand } from "./commands/affected.js";
+import { registerHarnessCommands } from "./commands/harness.js";
+import { registerCollectionCommands } from "./commands/collections.js";
+import { registerCostsCommands } from "./commands/costs.js";
+import { registerGenerationsCommands } from "./commands/generations.js";
+import { registerGameCommands } from "./commands/game.js";
+import { registerAuthCommands } from "./commands/auth.js";
+import { registerTelegramCommands } from "./commands/telegram.js";
+import { registerResourceReadCommands } from "./commands/resource-read.js";
+import { createApiClient } from "./api-client.js";
+import { listAllModels, listConfiguredProviderInfo, listOllamaModels, listProviderModels } from "./providers.js";
+import { isString } from "./predicates.js";
+import { printTable, asJson } from "./commands/output.js";
+import { printCommandError } from "./command-errors.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
+/**
+ * The CLI's own version, read from its package.json rather than repeated here.
+ * A literal drifts silently: it sat at "0.1.0" across every 0.7.0-rc release,
+ * so `nodetool --version` told users nothing about what they had installed.
+ */
+const CLI_VERSION = createRequire(import.meta.url)("../package.json").version;
 // ---------------------------------------------------------------------------
 // DB setup (for secrets commands)
 // ---------------------------------------------------------------------------
-async function setupDb() {
+// The local single-user id every direct-DB command runs as, matching the
+// `workflows run` / `secrets` commands and the stdio MCP server.
+import { resolveLocalSecret } from "./local-secrets.js";
+const LOCAL_USER_ID = "1";
+// Open the local SQLite database for a read-only command. Unlike setupDb() this
+// skips master-key unlocking (no secret decryption needed to list/read rows),
+// so it never emits a keychain warning. Idempotent — initDb() is a no-op once
+// a connection is open.
+function ensureDb() {
     initDb(getDefaultDbPath());
 }
+async function setupDb() {
+    ensureDb();
+    // Resolve the master encryption key from keychain / env / AWS so that
+    // both encryption (Secret.upsert) and decryption (Secret.getDecryptedValue)
+    // use the same persistent key. Without this, a fresh process would
+    // auto-generate a one-shot key inside `getMasterKey()`, encrypt with it,
+    // then lose it on exit — and the next launch could not decrypt.
+    try {
+        await initMasterKey();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`Could not unlock the secret store: ${msg}\n` +
+            `Tip: set SECRETS_MASTER_KEY or grant keychain access.\n`);
+    }
+}
 // ---------------------------------------------------------------------------
 // API clients
 // ---------------------------------------------------------------------------
-function createApiClient(apiUrl) {
-    return createTRPCClient({
-        links: [
-            httpBatchLink({
-                url: `${apiUrl}/trpc`,
-                transformer: superjson
-            })
-        ]
-    });
-}
 // REST GET (text) — used for the DSL export endpoint which stays REST
 // because it returns a TypeScript source string rather than JSON.
 async function apiGetText(apiUrl, path) {
@@ -64,28 +122,105 @@ async function apiGetText(apiUrl, path) {
         throw new Error(`HTTP ${res.status}: ${await res.text()}`);
     return res.text();
 }
-// ---------------------------------------------------------------------------
-// Table printer
-// ---------------------------------------------------------------------------
-function printTable(rows, columns) {
-    if (rows.length === 0) {
-        console.log("(no results)");
-        return;
+// This CLI's package version, stamped into exported bundle manifests.
+function cliVersion() {
+    try {
+        const req = createRequire(import.meta.url);
+        return req("../package.json").version;
     }
-    const cols = columns ?? Object.keys(rows[0]);
-    const widths = cols.map((c) => Math.max(c.length, ...rows.map((r) => String(r[c] ?? "").length)));
-    const sep = widths.map((w) => "─".repeat(w + 2)).join("┼");
-    const header = cols.map((c, i) => ` ${c.padEnd(widths[i])} `).join("│");
-    console.log(header);
-    console.log(sep);
-    for (const row of rows) {
-        console.log(cols
-            .map((c, i) => ` ${String(row[c] ?? "").padEnd(widths[i])} `)
-            .join("│"));
+    catch {
+        // Version is best-effort metadata; omit it if the file can't be read.
+        return undefined;
     }
 }
-function asJson(data) {
-    console.log(JSON.stringify(data, null, 2));
+// Download asset bytes from a running server, used by the export commands to
+// resolve `asset://` / `/api/storage/` (and optionally http) refs into bytes.
+function makeAssetFetcher(apiUrl) {
+    return async (ref) => {
+        let url = null;
+        if (ref.startsWith("asset://")) {
+            const id = ref.slice("asset://".length);
+            const bareId = id.replace(/\.[^.]+$/, "");
+            try {
+                const meta = await fetch(`${apiUrl}/api/assets/${encodeURIComponent(bareId)}`);
+                if (meta.ok) {
+                    const j = (await meta.json());
+                    if (j.get_url) {
+                        url = j.get_url.startsWith("/")
+                            ? `${apiUrl}${j.get_url}`
+                            : j.get_url;
+                    }
+                }
+            }
+            catch {
+                // Metadata lookup failed — fall back to the storage route below.
+            }
+            url ??= `${apiUrl}/api/storage/${encodeURIComponent(id)}`;
+        }
+        else if (ref.includes("/api/storage/")) {
+            url = /^https?:\/\//.test(ref)
+                ? ref
+                : `${apiUrl}${ref.startsWith("/") ? ref : `/${ref}`}`;
+        }
+        else if (/^https?:\/\//.test(ref)) {
+            url = ref;
+        }
+        if (!url)
+            return null;
+        const res = await fetch(url);
+        if (!res.ok)
+            return null;
+        return new Uint8Array(await res.arrayBuffer());
+    };
+}
+// Resolve asset bytes from the local assets directory, so the export commands
+// work by id without a running server. `asset://<key>` is tried verbatim as a
+// storage key first (that's how import-bundle writes refs), then via the DB
+// record to derive `<id>.<ext>` from the content type. Remote http(s) refs
+// still fetch over the network.
+async function makeLocalAssetFetcher() {
+    const { getAssetFileName } = await import("@nodetool-ai/websocket");
+    const storage = new FileStorageAdapter(getDefaultAssetsPath());
+    return async (ref) => {
+        if (ref.startsWith("asset://")) {
+            const raw = ref.slice("asset://".length);
+            const direct = await storage.retrieve(`/api/storage/${raw}`);
+            if (direct)
+                return direct;
+            const bareId = raw.replace(/\.[^.]+$/, "");
+            const asset = await Asset.find(LOCAL_USER_ID, bareId);
+            if (!asset)
+                return null;
+            const key = getAssetFileName(asset.id, asset.content_type);
+            return storage.retrieve(`/api/storage/${key}`);
+        }
+        if (ref.includes("/api/storage/")) {
+            const local = await storage.retrieve(ref);
+            if (local)
+                return local;
+        }
+        if (/^https?:\/\//.test(ref)) {
+            const res = await fetch(ref);
+            if (!res.ok)
+                return null;
+            return new Uint8Array(await res.arrayBuffer());
+        }
+        return null;
+    };
+}
+// Asset and timeline persistence for every context any command builds, here
+// rather than per-entrance: `debug` wired none while `workflows run` wired
+// four, so one workflow saved an image under one command and threw under the
+// other. The interfaces touch the database only when a node calls them, so
+// installing them before `setupDb()` is safe.
+await installLocalModelInterfaces();
+/**
+ * What to print when a run command fails. A preflight refusal already reads as
+ * a complete explanation — printing the error class in front of it only buries
+ * the secret name the user has to go set.
+ */
+function describeRunFailure(error) {
+    return isExecutionPreflightError(error) ? error.message : String(error);
 }
 // ---------------------------------------------------------------------------
 // info
@@ -93,11 +228,18 @@ function asJson(data) {
 program
     .name("nodetool")
     .description("NodeTool CLI")
-    .version("0.1.0")
+    .version(CLI_VERSION)
     .option("--trace-file <path>", "Append every LLM/agent/workflow span as JSONL to <path>")
     .option("--trace-stdout [format]", "Stream spans to stdout: 'pretty' (default) or 'json' (JSONL)")
     .option("--no-trace-stdout", "Disable stdout span output (overrides NODETOOL_TRACE_STDOUT)")
-    .hook("preAction", async (thisCommand) => {
+    .hook("preAction", async (thisCommand, actionCommand) => {
+    // With `--trace`, the `debug` command owns telemetry: it routes spans into
+    // its bundle's trace.jsonl via its own initTelemetry call. Initializing here
+    // first would win the one-shot init and drop that file sink, so skip it.
+    // Without `--trace`, fall through so the global --trace-file/--trace-stdout
+    // flags still work for a debug run.
+    if (actionCommand?.name() === "debug" && actionCommand.opts()["trace"])
+        return;
     const opts = thisCommand.opts();
     await initTelemetry({
         ...(opts.traceFile && { traceFile: opts.traceFile }),
@@ -111,7 +253,7 @@ function parseTraceStdout(v) {
         return false;
     if (v === true)
         return "pretty";
-    if (typeof v === "string") {
+    if (isString(v)) {
         const lower = v.toLowerCase();
         if (lower === "false" || lower === "0" || lower === "no")
             return false;
@@ -125,33 +267,49 @@ function parseTraceStdout(v) {
 // ---------------------------------------------------------------------------
 // run — execute a TypeScript/JavaScript DSL workflow file
 // ---------------------------------------------------------------------------
-program
+addSupervisorOptions(program
     .command("run <dsl-file>")
     .description("Run a TypeScript/JavaScript DSL workflow file")
-    .option("--json", "Output results as JSON (default: pretty-print)")
-    .action(async (dslFile, opts) => {
+    .option("--json", "Output results as JSON (default: pretty-print)")).action(async (dslFile, opts) => {
     try {
         const { resolve } = await import("node:path");
         const { runDslFile } = await import("./run-dsl.js");
         const { registerBaseNodes } = await import("@nodetool-ai/base-nodes");
         const { NodeRegistry } = await import("@nodetool-ai/node-sdk");
         registerBaseNodes(NodeRegistry.global);
+        const supervisorConfig = parseSupervisorFlags(opts);
         const absolutePath = resolve(dslFile);
-        const results = await runDslFile(absolutePath);
+        let results;
+        let interventions = [];
+        if (supervisorConfig) {
+            // The supervisor's provider key comes from the secret store, and its
+            // spend is written to the local ledger — both need the DB.
+            await setupDb();
+            const { runDslFileSupervised } = await import("./run-dsl-supervised.js");
+            const run = await runDslFileSupervised(absolutePath, supervisorConfig, opts.json === true);
+            results = run.results;
+            interventions = run.interventions;
+        }
+        else {
+            results = await runDslFile(absolutePath);
+        }
+        const { printRunJson, previewJson } = await import("./run-json.js");
         if (opts.json) {
-            console.log(JSON.stringify(results, null, 2));
+            // A supervised run reports what the supervisor did alongside the
+            // outputs; an unsupervised one keeps the bare results shape.
+            await printRunJson(supervisorConfig ? { results, interventions } : results);
         }
         else {
             for (const [workflowName, outputs] of Object.entries(results)) {
                 console.log(`\n${workflowName}:`);
                 for (const [key, value] of Object.entries(outputs)) {
-                    console.log(`  ${key}: ${JSON.stringify(value)}`);
+                    console.log(`  ${key}: ${previewJson(value)}`);
                 }
             }
         }
     }
     catch (e) {
-        console.error(String(e));
+        console.error(describeRunFailure(e));
         process.exit(1);
     }
 });
@@ -171,7 +329,7 @@ program
         "HF_TOKEN"
     ];
     const data = {
-        version: "0.1.0",
+        version: CLI_VERSION,
         node_version: process.version,
         platform: process.platform,
         arch: process.arch,
@@ -224,7 +382,8 @@ program
 // ---------------------------------------------------------------------------
 program
     .command("chat")
-    .description("Start interactive chat (TUI)")
+    .description("Start fullscreen chat")
+    .helpOption(false)
     .option("-p, --provider <provider>", "LLM provider")
     .option("-m, --model <model>", "Model ID")
     .option("-a, --agent", "Agent mode")
@@ -233,17 +392,17 @@ program
     .option("--tools <tools>", "Comma-separated enabled tools")
     .allowUnknownOption()
     .action((_opts, cmd) => {
-    const chatPath = resolve(__dirname, "index.js");
+    const chatPath = resolve(__dirname, import.meta.url.endsWith(".ts") ? "index.ts" : "index.js");
     const args = cmd.args;
     const rawArgs = process.argv;
     // Re-run with the chat entry point, forwarding all flags after "chat"
     const chatIdx = rawArgs.indexOf("chat");
     const forwarded = chatIdx >= 0 ? rawArgs.slice(chatIdx + 1) : args;
-    const result = spawnSync("node", [chatPath, ...forwarded], {
+    const result = spawnSync(process.execPath, [...process.execArgv, chatPath, ...forwarded], {
         stdio: "inherit",
         env: { ...process.env }
     });
-    process.exit(result.status ?? 0);
+    process.exit(result.status ?? 1);
 });
 // ---------------------------------------------------------------------------
 // workflows
@@ -251,86 +410,56 @@ program
 const workflows = program
     .command("workflows")
     .description("Workflow management");
-workflows
-    .command("list")
-    .description("List workflows")
-    .option("--api-url <url>", "API base URL", process.env["NODETOOL_API_URL"] ?? "http://localhost:7777")
-    .option("--limit <n>", "Max results", "100")
-    .option("--json", "Output as JSON")
-    .action(async (opts) => {
-    try {
-        const client = createApiClient(opts.apiUrl);
-        const data = await client.workflows.list.query({
-            limit: Number.parseInt(opts.limit, 10)
-        });
-        const rows = data.workflows;
-        if (opts.json) {
-            asJson(rows);
-            return;
-        }
-        printTable(rows.map((r) => ({
-            id: r["id"],
-            name: r["name"],
-            updated_at: r["updated_at"]
-        })));
-    }
-    catch (e) {
-        console.error(String(e));
-        process.exit(1);
-    }
-});
-workflows
-    .command("get <workflow_id>")
-    .description("Get a workflow by ID")
-    .option("--api-url <url>", "API base URL", process.env["NODETOOL_API_URL"] ?? "http://localhost:7777")
-    .option("--json", "Output as JSON")
-    .action(async (workflowId, opts) => {
-    try {
-        const client = createApiClient(opts.apiUrl);
-        const data = await client.workflows.get.query({ id: workflowId });
-        if (opts.json) {
-            asJson(data);
-            return;
-        }
-        const w = data;
-        printTable([
-            {
-                id: w["id"],
-                name: w["name"],
-                description: w["description"],
-                updated_at: w["updated_at"]
-            }
-        ]);
-    }
-    catch (e) {
-        console.error(String(e));
-        process.exit(1);
-    }
-});
-workflows
+addSupervisorOptions(workflows
     .command("run <workflow_id_or_file>")
     .description("Run a workflow by ID, JSON file, or TypeScript DSL file")
     .option("--params <json>", "JSON params string")
     .option("--json", "Output as JSON")
-    .action(async (idOrFile, opts) => {
+    .option("--asset-output-mode <mode>", "How media outputs are materialized: native | raw | data_uri | workspace | storage_url | temp_url", "native")
+    .option("--workspace <dir>", "Workspace directory for workspace-mode asset output (default: ./nodetool-output)")
+    .option("--trigger-event <json>", 'Wake a trigger node as the scheduler/webhook adapter would: \'{"node_id":"watch","payload":{"path":"/tmp/a.csv","event":"created"}}\'. ' +
+    "Without it a webhook, file-watch or manual trigger has no event to " +
+    "emit and the run stalls until its timeout — so this is the only way " +
+    "to exercise a trigger-driven workflow from the CLI.")).action(async (idOrFile, opts) => {
     try {
+        const supervisorConfig = parseSupervisorFlags(opts);
         await setupDb();
         let graph;
         let workflowId = null;
         const params = opts.params
             ? JSON.parse(opts.params)
             : {};
+        // A trigger node emits from `emitTriggerEvent`, not `genProcess`, and
+        // only when the run carries an event addressed to it. The kernel has
+        // always accepted one (`RunJobRequest.trigger_event`); nothing on the
+        // CLI could supply it, so a webhook or file-watch workflow could be
+        // validated but never executed. `input_id` defaults because every
+        // caller would otherwise invent the same throwaway id.
+        const triggerEvent = opts.triggerEvent
+            ? (() => {
+                const parsed = JSON.parse(opts.triggerEvent);
+                if (!parsed.node_id) {
+                    throw new Error('--trigger-event needs a "node_id" naming the trigger node to wake.');
+                }
+                return {
+                    node_id: parsed.node_id,
+                    payload: parsed.payload ?? {},
+                    input_id: parsed.input_id ?? `cli-${Date.now()}`
+                };
+            })()
+            : null;
         // Determine if argument is a file path or workflow ID
         if (idOrFile.endsWith(".json") ||
             idOrFile.endsWith(".ts") ||
             idOrFile.endsWith(".tsx") ||
             idOrFile.includes("/") ||
             idOrFile.includes("\\")) {
+            /** A DSL/JSON workflow file: the graph, optionally wrapped. */
             let raw;
             if (idOrFile.endsWith(".ts") || idOrFile.endsWith(".tsx")) {
                 // Execute DSL file via tsx and capture JSON output
-                const { execSync } = await import("node:child_process");
-                const output = execSync(`npx tsx "${resolve(idOrFile)}"`, {
+                const { execFileSync } = await import("node:child_process");
+                const output = execFileSync("npx", ["tsx", resolve(idOrFile)], {
                     encoding: "utf8",
                     cwd: dirname(resolve(idOrFile)),
                     timeout: 30000
@@ -347,7 +476,6 @@ workflows
                 Object.assign(params, raw.params);
         }
         else {
-            // Load from database
             const wf = await Workflow.get(idOrFile);
             if (!wf)
                 throw new Error(`Workflow not found: ${idOrFile}`);
@@ -357,42 +485,132 @@ workflows
         if (!graph?.nodes || !graph?.edges) {
             throw new Error("Invalid workflow: missing nodes or edges");
         }
-        // Normalize graph: convert node.data → node.properties (kernel format)
-        graph.nodes = graph.nodes.map((n) => {
-            if (n.properties === undefined && n.data !== undefined) {
-                const { data, ...rest } = n;
-                return { ...rest, properties: data };
-            }
-            return n;
-        });
-        // Set up node registry
+        // Editor-only nodes (Comment, Group, Reroute) and the data→properties
+        // rename are handled by `ExecutionSession.create` below, which runs
+        // the graph through `normalizeGraph` (@nodetool-ai/execution) — no
+        // need to duplicate that here.
         const registry = new NodeRegistry();
         registerBaseNodes(registry);
         registerElevenLabsNodes(registry);
+        registerMinimaxNodes(registry);
         registerTransformersJsNodes(registry);
         registerFalNodes(registry);
         registerReplicateNodes(registry);
-        // Create processing context with secret resolver
+        registerReveNodes(registry);
+        registerHuggingFaceNodes(registry);
         const jobId = `job-${Date.now()}`;
+        // Resolve asset URIs (e.g. /api/storage/<key>) against the local
+        // assets directory, so workflows referencing stored assets run the
+        // same decode path the server does.
+        // Apply the workflow's assigned workspace (if any) so file ops and
+        // workspace-driving nodes land in the same directory as a server run.
+        const { resolveWorkflowWorkspace } = await import("@nodetool-ai/websocket");
+        const assignedWorkspace = workflowId
+            ? await resolveWorkflowWorkspace(workflowId, "1")
+            : null;
+        const ASSET_OUTPUT_MODES = [
+            "native",
+            "raw",
+            "data_uri",
+            "workspace",
+            "storage_url",
+            "temp_url"
+        ];
+        const assetOutputMode = (opts.assetOutputMode ??
+            "native");
+        if (!ASSET_OUTPUT_MODES.includes(assetOutputMode)) {
+            throw new Error(`Unknown --asset-output-mode "${assetOutputMode}". ` +
+                `Expected one of: ${ASSET_OUTPUT_MODES.join(", ")}`);
+        }
+        // `--workspace <dir>` wins, then whatever the workflow is assigned.
+        // `workspace` asset mode writes each output into <workspace>/assets, so
+        // it needs somewhere to write even when the run has no saved workflow (a
+        // JSON or DSL file target). Fall back to ./nodetool-output so a bare
+        // `workflows run file.json --asset-output-mode workspace` produces files
+        // in the current directory rather than failing.
+        const overrideWorkspaceDir = opts.workspace ??
+            (assignedWorkspace
+                ? null
+                : assetOutputMode === "workspace"
+                    ? resolve(process.cwd(), "nodetool-output")
+                    : null);
+        if (overrideWorkspaceDir) {
+            mkdirSync(overrideWorkspaceDir, { recursive: true });
+        }
+        const runWorkspace = overrideWorkspaceDir
+            ? createLocalWorkspace(overrideWorkspaceDir)
+            : assignedWorkspace;
+        const assetStorage = new FileStorageAdapter(getDefaultAssetsPath());
         const context = new ProcessingContext({
             jobId,
             workflowId,
             userId: "1",
-            secretResolver: getSecret
-        });
-        // Run workflow
-        const runner = new WorkflowRunner(jobId, {
-            resolveExecutor: (node) => {
-                if (!registry.has(node.type))
-                    throw new Error(`Unknown node type: ${node.type}`);
-                return registry.resolve(node);
-            },
-            executionContext: context
+            secretResolver: resolveLocalSecret,
+            storage: assetStorage,
+            assetOutputMode,
+            workspace: runWorkspace
         });
-        console.error(`Running workflow${workflowId ? ` ${workflowId}` : ""}...`);
-        const result = await runner.run({ job_id: jobId, workflow_id: workflowId ?? undefined, params }, graph);
+        const supervisor = supervisorConfig
+            ? await createSupervisorHandle({
+                config: supervisorConfig,
+                context
+            })
+            : null;
+        console.error(`Running workflow${workflowId ? ` ${workflowId}` : ""}` +
+            (supervisor
+                ? ` supervised by ${supervisor.providerId}/${supervisor.model}`
+                : "") +
+            "...");
+        // ExecutionSession owns graph hydration, Python-bridge connection
+        // (NODETOOL_WORKER_URL/NODETOOL_WORKER_TOKEN → remote worker; unset →
+        // local stdio worker; pure-TS graphs get none), and executor
+        // resolution (registry → Python bridge → throw).
+        const sessionOptions = {
+            graph,
+            registry,
+            // Registry alone hydrates node flags but not `propertyTypes`, and
+            // correlation analysis reads list-ness only from that map — so a
+            // saved workflow (which never carries it) had every list handle
+            // read as non-list, and legal fan-in into one was rejected before
+            // any node ran. The resolver fills it from node metadata.
+            resolveNodeType: createGraphNodeTypeResolver(registry).resolveNodeType,
+            jobId,
+            workflowId,
+            params,
+            context
+        };
+        if (triggerEvent) {
+            sessionOptions.triggerEvent = triggerEvent;
+        }
+        // Message capture is retention, so it stays off unless a supervised
+        // run needs the stream to print its `⛨` lines as they happen.
+        if (supervisor) {
+            sessionOptions.supervisor = supervisor.handle;
+            sessionOptions.captureMessages = true;
+        }
+        const session = await ExecutionSession.create(sessionOptions);
+        const interventionLines = supervisor
+            ? streamInterventionLines(session.messages)
+            : Promise.resolve();
+        const result = await session.result;
+        await interventionLines;
+        supervisor?.handle.close();
+        const interventions = result.interventions ?? [];
+        if (supervisor && interventions.length > 0) {
+            await recordSupervisorCost({
+                interventions,
+                jobId,
+                workflowId,
+                userId: "1",
+                providerId: supervisor.providerId,
+                model: supervisor.model
+            });
+        }
+        const { printRunJson, previewJson } = await import("./run-json.js");
         if (opts.json) {
-            console.log(JSON.stringify(result, null, 2));
+            await printRunJson(result, {
+                outputDir: resolve(process.cwd(), "nodetool-output", jobId)
+            });
         }
         else {
             console.log(`Status: ${result.status}`);
@@ -402,22 +620,23 @@ workflows
                 if (Array.isArray(outputs) && outputs.length > 0) {
                     console.log(`\nNode ${nodeId}:`);
                     for (const out of outputs) {
-                        console.log(`  ${JSON.stringify(out).slice(0, 200)}`);
+                        console.log(`  ${previewJson(out, 200)}`);
                     }
                 }
             }
+            printSupervisedSummary(interventions);
         }
         process.exit(result.status === "completed" ? 0 : 1);
     }
     catch (e) {
-        console.error(String(e));
+        console.error(describeRunFailure(e));
         process.exit(1);
     }
 });
 workflows
     .command("export-dsl <workflow_id_or_file>")
-    .description("Export a workflow as TypeScript DSL code")
-    .option("--api-url <url>", "API base URL", process.env["NODETOOL_API_URL"] ?? "http://localhost:7777")
+    .description("Export a workflow as TypeScript DSL code (local DB by id; --api-url for remote)")
+    .option("--api-url <url>", "Fetch the workflow from a remote server instead of the local database", process.env["NODETOOL_API_URL"])
     .option("-o, --output <file>", "Write the exported DSL to a file")
     .action(async (idOrFile, opts) => {
     try {
@@ -429,12 +648,22 @@ workflows
             const raw = JSON.parse(readFileSync(idOrFile, "utf8"));
             const graph = (raw.graph ?? raw);
             source = workflowToDsl(graph, {
-                workflowName: typeof raw.name === "string" ? raw.name : null
+                workflowName: isString(raw.name) ? raw.name : null
             });
         }
-        else {
+        else if (opts.apiUrl) {
             source = await apiGetText(opts.apiUrl, `/api/workflows/${idOrFile}/dsl-export`);
         }
+        else {
+            ensureDb();
+            const wf = await Workflow.find(LOCAL_USER_ID, idOrFile);
+            if (!wf)
+                throw new Error(`Workflow not found: ${idOrFile}`);
+            const graph = wf.getGraph();
+            source = workflowToDsl(graph, {
+                workflowName: isString(wf.name) ? wf.name : null
+            });
+        }
         if (opts.output) {
             const { writeFile } = await import("node:fs/promises");
             await writeFile(opts.output, source, "utf8");
@@ -444,157 +673,275 @@ workflows
         console.log(source);
     }
     catch (e) {
-        console.error(String(e));
+        printCommandError(e);
         process.exit(1);
     }
 });
-// ---------------------------------------------------------------------------
-// jobs
-// ---------------------------------------------------------------------------
-const jobs = program.command("jobs").description("Job management");
-jobs
-    .command("list")
-    .description("List jobs")
-    .option("--api-url <url>", "API base URL", process.env["NODETOOL_API_URL"] ?? "http://localhost:7777")
-    .option("--workflow-id <id>", "Filter by workflow ID")
-    .option("--limit <n>", "Max results", "100")
-    .option("--json", "Output as JSON")
-    .action(async (opts) => {
+workflows
+    .command("export-example <workflow_id_or_file>")
+    .description("Export a workflow as a shipped template: materialize its assets into the " +
+    "package's constant asset dir (package:// refs) and write the example JSON")
+    .option("--api-url <url>", "Fetch the workflow and asset bytes from a remote server instead of the local DB/assets", process.env["NODETOOL_API_URL"])
+    .option("--package <name>", "Owning package", "nodetool-base")
+    .option("--assets-dir <dir>", "Root holding <package>/<file> constant assets (defaults to the monorepo base-nodes assets dir)")
+    .option("--examples-dir <dir>", "Directory the example JSON is written under, as <dir>/<package>/<name>.json")
+    .option("-o, --output <file>", "Write the example JSON to this exact path")
+    .option("--include-remote", "Also materialize http(s) and local-file refs (off by default)")
+    .action(async (idOrFile, opts) => {
     try {
-        const client = createApiClient(opts.apiUrl);
-        const data = await client.jobs.list.query({
-            limit: Number.parseInt(opts.limit, 10),
-            ...(opts.workflowId ? { workflow_id: opts.workflowId } : {})
-        });
-        const rows = data.jobs;
-        if (opts.json) {
-            asJson(rows);
-            return;
+        const { readFileSync } = await import("node:fs");
+        const { mkdir, writeFile } = await import("node:fs/promises");
+        const { join } = await import("node:path");
+        const { materializeWorkflowConstantAssets } = await import("@nodetool-ai/websocket");
+        let name = "";
+        let description = "";
+        let tags = [];
+        let graph;
+        const isFile = idOrFile.endsWith(".json") ||
+            idOrFile.includes("/") ||
+            idOrFile.includes("\\");
+        if (isFile) {
+            const raw = JSON.parse(readFileSync(idOrFile, "utf8"));
+            name = isString(raw.name) ? raw.name : "workflow";
+            description =
+                isString(raw.description) ? raw.description : "";
+            tags = Array.isArray(raw.tags)
+                ? raw.tags.filter((t) => typeof t === "string")
+                : [];
+            graph = (raw.graph ?? raw);
         }
-        printTable(rows.map((r) => ({
-            id: r["id"],
-            status: r["status"],
-            workflow_id: r["workflow_id"],
-            started_at: r["started_at"]
-        })));
-    }
-    catch (e) {
-        console.error(String(e));
-        process.exit(1);
-    }
-});
-jobs
-    .command("get <job_id>")
-    .description("Get a job by ID")
-    .option("--api-url <url>", "API base URL", process.env["NODETOOL_API_URL"] ?? "http://localhost:7777")
-    .option("--json", "Output as JSON")
-    .action(async (jobId, opts) => {
-    try {
-        const client = createApiClient(opts.apiUrl);
-        const data = await client.jobs.get.query({ id: jobId });
-        if (opts.json) {
-            asJson(data);
-            return;
+        else if (opts.apiUrl) {
+            const client = createApiClient(opts.apiUrl);
+            const wf = (await client.workflows.get.query({
+                id: idOrFile
+            }));
+            name = isString(wf.name) ? wf.name : "workflow";
+            description =
+                isString(wf.description) ? wf.description : "";
+            tags = Array.isArray(wf.tags)
+                ? wf.tags.filter((t) => typeof t === "string")
+                : [];
+            graph = wf.graph;
         }
-        const j = data;
-        printTable([
-            {
-                id: j["id"],
-                status: j["status"],
-                workflow_id: j["workflow_id"],
-                error: j["error"] ?? ""
-            }
-        ]);
+        else {
+            ensureDb();
+            const wf = await Workflow.find(LOCAL_USER_ID, idOrFile);
+            if (!wf)
+                throw new Error(`Workflow not found: ${idOrFile}`);
+            name = isString(wf.name) ? wf.name : "workflow";
+            description =
+                isString(wf.description) ? wf.description : "";
+            tags = Array.isArray(wf.tags)
+                ? wf.tags.filter((t) => typeof t === "string")
+                : [];
+            graph = wf.getGraph();
+        }
+        if (!graph?.nodes) {
+            throw new Error("Workflow has no graph to export");
+        }
+        const repoRoot = resolve(__dirname, "..", "..", "..");
+        const baseNodesDir = join(repoRoot, "packages", "base-nodes", "nodetool");
+        const assetsRoot = opts.assetsDir ?? join(baseNodesDir, "assets");
+        const examplesDir = opts.examplesDir ?? join(baseNodesDir, "examples");
+        const fetchAssetBytes = opts.apiUrl
+            ? makeAssetFetcher(opts.apiUrl.replace(/\/+$/, ""))
+            : await makeLocalAssetFetcher();
+        const materializeOptions = {
+            packageName: opts.package,
+            assetsRoot,
+            fetchAssetBytes
+        };
+        if (opts.includeRemote) {
+            materializeOptions.includeRemote = true;
+        }
+        const result = await materializeWorkflowConstantAssets(graph, materializeOptions);
+        const slug = name
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, "-")
+            .replace(/^-+|-+$/g, "");
+        const example = {
+            id: slug || "workflow",
+            access: "public",
+            name,
+            description,
+            tags,
+            package_name: opts.package,
+            graph: result.graph
+        };
+        // Sanitize the on-disk filename separately from the display name so
+        // names with path separators can't escape the examples directory.
+        const safeFileName = name.replace(/[^A-Za-z0-9._-]+/g, "_").replace(/^[._]+/, "") ||
+            "workflow";
+        const outPath = opts.output ??
+            join(examplesDir, opts.package, `${safeFileName}.json`);
+        await mkdir(dirname(outPath), { recursive: true });
+        await writeFile(outPath, JSON.stringify(example, null, 2) + "\n", "utf8");
+        for (const a of result.exported) {
+            console.error(`  asset ${a.source} → ${a.packageUri} (${a.byteLength} bytes)`);
+        }
+        for (const s of result.skipped) {
+            console.error(`  warning: could not resolve asset ${s} (left as-is)`);
+        }
+        console.log(outPath);
     }
     catch (e) {
-        console.error(String(e));
+        printCommandError(e);
         process.exit(1);
     }
 });
-// ---------------------------------------------------------------------------
-// assets
-// ---------------------------------------------------------------------------
-const assets = program.command("assets").description("Asset management");
-assets
-    .command("list")
-    .description("List assets")
-    .option("--api-url <url>", "API base URL", process.env["NODETOOL_API_URL"] ?? "http://localhost:7777")
-    .option("--query <q>", "Search query")
-    .option("--content-type <type>", "Filter by content type")
-    .option("--limit <n>", "Max results", "100")
-    .option("--json", "Output as JSON")
-    .action(async (opts) => {
+workflows
+    .command("export-bundle <workflow_id_or_file...>")
+    .description("Export one or more workflows as a portable .nodetool bundle (zip): the " +
+    "graphs plus the bytes of every asset they reference, in a single file")
+    .option("--api-url <url>", "Fetch the workflow and asset bytes from a remote server instead of the local DB/assets", process.env["NODETOOL_API_URL"])
+    .option("-o, --output <file>", "Output path (default: <name>.nodetool)")
+    .option("--include-remote", "Also embed http(s) and local-file refs (off by default)")
+    .action(async (idsOrFiles, opts) => {
     try {
-        const client = createApiClient(opts.apiUrl);
-        const data = await client.assets.list.query({
-            page_size: Number.parseInt(opts.limit, 10),
-            ...(opts.contentType ? { content_type: opts.contentType } : {})
+        const { readFileSync } = await import("node:fs");
+        const { writeFile } = await import("node:fs/promises");
+        const { packWorkflowsBundle } = await import("@nodetool-ai/websocket");
+        const toBundleWf = (raw) => ({
+            name: isString(raw.name) ? raw.name : "workflow",
+            description: isString(raw.description) ? raw.description : "",
+            tags: Array.isArray(raw.tags)
+                ? raw.tags.filter((t) => typeof t === "string")
+                : [],
+            run_mode: raw.run_mode ?? null,
+            settings: raw.settings ?? null,
+            graph: (raw.graph ?? raw)
         });
-        // Note: --query isn't forwarded because assets.list has no server-side
-        // search; keep local filtering until the tRPC schema exposes one.
-        let rows = data.assets;
-        if (opts.query) {
-            const q = String(opts.query).toLowerCase();
-            rows = rows.filter((r) => String(r["name"] ?? "").toLowerCase().includes(q));
+        const useServer = Boolean(opts.apiUrl);
+        const apiUrl = opts.apiUrl?.replace(/\/+$/, "") ?? "";
+        if (!useServer)
+            ensureDb();
+        const workflowsToPack = [];
+        for (const idOrFile of idsOrFiles) {
+            const isFile = idOrFile.endsWith(".json") ||
+                idOrFile.includes("/") ||
+                idOrFile.includes("\\");
+            let raw;
+            if (isFile) {
+                raw = JSON.parse(readFileSync(idOrFile, "utf8"));
+            }
+            else if (useServer) {
+                raw = (await createApiClient(apiUrl).workflows.get.query({
+                    id: idOrFile
+                }));
+            }
+            else {
+                const found = await Workflow.find(LOCAL_USER_ID, idOrFile);
+                if (!found)
+                    throw new Error(`Workflow not found: ${idOrFile}`);
+                raw = { ...found, graph: found.getGraph() };
+            }
+            const wf = toBundleWf(raw);
+            if (!wf.graph?.nodes) {
+                throw new Error(`Workflow '${idOrFile}' has no graph to export`);
+            }
+            workflowsToPack.push(wf);
         }
-        if (opts.json) {
-            asJson(rows);
-            return;
+        const packOptions = {
+            workflows: workflowsToPack,
+            fetchAssetBytes: useServer
+                ? makeAssetFetcher(apiUrl)
+                : await makeLocalAssetFetcher(),
+            nodetoolVersion: cliVersion()
+        };
+        if (opts.includeRemote) {
+            packOptions.includeRemote = true;
         }
-        printTable(rows.map((r) => ({
-            id: r["id"],
-            name: r["name"],
-            content_type: r["content_type"],
-            size: r["size"]
-        })));
+        const { bytes, manifest, skipped } = await packWorkflowsBundle(packOptions);
+        const defaultBase = workflowsToPack.length === 1
+            ? workflowsToPack[0].name.replace(/[^A-Za-z0-9._-]+/g, "_")
+            : `${workflowsToPack.length}-workflows`;
+        const outPath = opts.output ?? `${defaultBase}.nodetool`;
+        await writeFile(outPath, bytes);
+        for (const a of manifest.assets) {
+            console.error(`  embedded ${a.file} (${a.bytes} bytes)`);
+        }
+        for (const s of skipped) {
+            console.error(`  warning: could not resolve asset ${s} (left as-is)`);
+        }
+        console.error(`  bundled ${manifest.workflows.length} workflow(s), ${manifest.assets.length} asset(s)`);
+        console.log(outPath);
     }
     catch (e) {
-        console.error(String(e));
+        printCommandError(e);
         process.exit(1);
     }
 });
-assets
-    .command("get <asset_id>")
-    .description("Get an asset by ID")
-    .option("--api-url <url>", "API base URL", process.env["NODETOOL_API_URL"] ?? "http://localhost:7777")
-    .option("--json", "Output as JSON")
-    .action(async (assetId, opts) => {
+workflows
+    .command("import-bundle <bundle_file>")
+    .description("Import a .nodetool bundle into the local library: store its assets and " +
+    "create the workflows with refs rewritten to the imported assets")
+    .option("--json", "Output the created workflows as JSON")
+    .action(async (bundleFile, opts) => {
     try {
-        const client = createApiClient(opts.apiUrl);
-        const data = await client.assets.get.query({ id: assetId });
+        const { readFileSync } = await import("node:fs");
+        const { randomUUID } = await import("node:crypto");
+        const { extname } = await import("node:path");
+        const { importWorkflowBundle } = await import("@nodetool-ai/websocket");
+        await setupDb();
+        const storage = new FileStorageAdapter(getDefaultAssetsPath());
+        const zip = new Uint8Array(readFileSync(bundleFile));
+        const result = await importWorkflowBundle(zip, {
+            storeAsset: async ({ bytes, fileName, contentType }) => {
+                const id = randomUUID();
+                const key = `${id}${extname(fileName)}`;
+                await storage.store(key, bytes, contentType);
+                return { uri: `asset://${key}`, assetId: id };
+            }
+        });
+        const created = [];
+        for (const wf of result.workflows) {
+            created.push(await Workflow.create({
+                user_id: "1",
+                name: wf.name,
+                description: wf.description ?? "",
+                tags: wf.tags ?? [],
+                access: "private",
+                graph: wf.graph,
+                run_mode: wf.run_mode ?? "workflow",
+                settings: wf.settings ?? null
+            }));
+        }
+        for (const s of result.missing) {
+            console.error(`  warning: bundle asset ${s} was missing from the archive`);
+        }
+        for (const m of result.checksumMismatches) {
+            console.error(`  warning: ${m}`);
+        }
+        console.error(`  imported ${created.length} workflow(s) and ${result.imported.length} asset(s) into local storage`);
         if (opts.json) {
-            asJson(data);
-            return;
+            asJson(created);
         }
-        const a = data;
-        printTable([
-            {
-                id: a["id"],
-                name: a["name"],
-                content_type: a["content_type"],
-                size: a["size"],
-                url: a["url"]
+        else {
+            for (const c of created) {
+                console.log(String(c.id));
             }
-        ]);
+        }
     }
     catch (e) {
-        console.error(String(e));
+        printCommandError(e, opts.json);
         process.exit(1);
     }
 });
 // ---------------------------------------------------------------------------
-// models
+// jobs / assets — the read commands are registered from commands/resource-read.ts
 // ---------------------------------------------------------------------------
+const jobs = program.command("jobs").description("Job management");
+const assets = program.command("assets").description("Asset management");
+registerResourceReadCommands({ workflows, jobs, assets }, { ensureDb, localUserId: LOCAL_USER_ID });
 const models = program.command("models").description("Model management");
-const modelKinds = ["llm", "image", "tts", "asr", "video", "embedding"];
-const byProviderRoute = {
-    llm: "llmByProvider",
-    image: "imageByProvider",
-    tts: "ttsByProvider",
-    asr: "asrByProvider",
-    video: "videoByProvider",
-    embedding: "embeddingByProvider"
-};
+const modelKinds = [
+    "llm",
+    "image",
+    "tts",
+    "asr",
+    "video",
+    "embedding"
+];
 function modelRow(m) {
     return {
         id: m["id"],
@@ -606,14 +953,20 @@ function modelRow(m) {
 }
 models
     .command("list")
-    .description("List all models (recommended + provider + HF cached)")
-    .option("--api-url <url>", "API base URL", process.env["NODETOOL_API_URL"] ?? "http://localhost:7777")
+    .description("List all models (recommended + provider + HF cached); local by default, --api-url for remote")
+    .option("--api-url <url>", "Query a remote server instead of local providers/cache", process.env["NODETOOL_API_URL"])
     .option("--json", "Output as JSON")
     .action(async (opts) => {
     try {
-        const client = createApiClient(opts.apiUrl);
-        const data = await client.models.all.query();
-        const rows = data;
+        let rows;
+        if (opts.apiUrl) {
+            const client = createApiClient(opts.apiUrl);
+            rows = await client.models.all.query();
+        }
+        else {
+            await setupDb();
+            rows = await listAllModels();
+        }
         if (opts.json) {
             asJson(rows);
             return;
@@ -621,19 +974,18 @@ models
         printTable(rows.map(modelRow));
     }
     catch (e) {
-        console.error(String(e));
+        printCommandError(e, opts.json);
         process.exit(1);
     }
 });
 models
     .command("providers")
     .description("List configured providers and their capabilities")
-    .option("--api-url <url>", "API base URL", process.env["NODETOOL_API_URL"] ?? "http://localhost:7777")
     .option("--json", "Output as JSON")
     .action(async (opts) => {
+    await setupDb();
     try {
-        const client = createApiClient(opts.apiUrl);
-        const data = await client.models.providers.query();
+        const data = await listConfiguredProviderInfo();
         if (opts.json) {
             asJson(data);
             return;
@@ -644,7 +996,7 @@ models
         })));
     }
     catch (e) {
-        console.error(String(e));
+        printCommandError(e, opts.json);
         process.exit(1);
     }
 });
@@ -652,42 +1004,67 @@ registerRecommendedCommand(models);
 registerHfCommands(models);
 models
     .command("ollama")
-    .description("List Ollama models")
-    .option("--api-url <url>", "API base URL", process.env["NODETOOL_API_URL"] ?? "http://localhost:7777")
+    .description("List Ollama models (queries the local daemon; --api-url for remote)")
+    .option("--api-url <url>", "Query a remote server instead of the local Ollama daemon", process.env["NODETOOL_API_URL"])
     .option("--json", "Output as JSON")
     .action(async (opts) => {
     try {
-        const client = createApiClient(opts.apiUrl);
-        const data = await client.models.ollama.query();
-        const rows = data;
+        let rows;
+        if (opts.apiUrl) {
+            const client = createApiClient(opts.apiUrl);
+            rows = await client.models.ollama.query();
+        }
+        else {
+            await setupDb();
+            rows = await listOllamaModels();
+        }
         if (opts.json) {
             asJson(rows);
             return;
         }
-        printTable(rows);
+        printTable(rows.map(modelRow));
     }
     catch (e) {
-        console.error(String(e));
+        printCommandError(e, opts.json);
         process.exit(1);
     }
 });
 models
     .command("huggingface")
-    .description("List HuggingFace cached models")
-    .option("--api-url <url>", "API base URL", process.env["NODETOOL_API_URL"] ?? "http://localhost:7777")
+    .description("List HuggingFace cached models (scans the local cache; --api-url for remote)")
+    .option("--api-url <url>", "Query a remote server instead of the local HuggingFace cache", process.env["NODETOOL_API_URL"])
     .option("--query <q>", "Search query")
     .option("--type <t>", "Filter by HF model type")
     .option("--json", "Output as JSON")
     .action(async (opts) => {
     try {
-        const client = createApiClient(opts.apiUrl);
-        const data = opts.query || opts.type
-            ? await client.models.huggingfaceSearch.query({
-                ...(opts.query ? { query: String(opts.query) } : {}),
-                ...(opts.type ? { type: String(opts.type) } : {})
-            })
-            : await client.models.huggingfaceList.query();
-        const rows = data;
+        let rows;
+        if (opts.apiUrl) {
+            const client = createApiClient(opts.apiUrl);
+            if (opts.query || opts.type) {
+                const search = {};
+                if (opts.query) {
+                    search.query = String(opts.query);
+                }
+                if (opts.type) {
+                    search.type = String(opts.type);
+                }
+                rows = await client.models.huggingfaceSearch.query(search);
+            }
+            else {
+                rows = await client.models.huggingfaceList.query();
+            }
+        }
+        else if (opts.query || opts.type) {
+            // Wrap a bare query in wildcards so it matches as a substring, the same
+            // normalization the server's huggingfaceSearch applies.
+            const rawQuery = opts.query ? String(opts.query) : undefined;
+            const query = rawQuery && !rawQuery.includes("*") ? `*${rawQuery}*` : rawQuery;
+            rows = await searchCachedHfModels(query ? [query] : undefined, opts.type ? [String(opts.type)] : undefined);
+        }
+        else {
+            rows = await readCachedHfModels();
+        }
         if (opts.json) {
             asJson(rows);
             return;
@@ -695,14 +1072,13 @@ models
         printTable(rows.map(modelRow));
     }
     catch (e) {
-        console.error(String(e));
+        printCommandError(e, opts.json);
         process.exit(1);
     }
 });
 models
     .command("by-provider <provider>")
     .description(`List models for a provider. --kind one of: ${modelKinds.join(", ")}`)
-    .option("--api-url <url>", "API base URL", process.env["NODETOOL_API_URL"] ?? "http://localhost:7777")
     .option("--kind <kind>", "Model kind", "llm")
     .option("--json", "Output as JSON")
     .action(async (provider, opts) => {
@@ -711,11 +1087,9 @@ models
         console.error(`Invalid --kind '${opts.kind}'. Must be one of: ${modelKinds.join(", ")}`);
         process.exit(1);
     }
+    await setupDb();
     try {
-        const client = createApiClient(opts.apiUrl);
-        const route = byProviderRoute[kind];
-        const data = await client.models[route].query({ provider });
-        const rows = data;
+        const rows = await listProviderModels(provider, kind);
         if (opts.json) {
             asJson(rows);
             return;
@@ -723,7 +1097,75 @@ models
         printTable(rows.map(modelRow));
     }
     catch (e) {
-        console.error(String(e));
+        printCommandError(e, opts.json);
+        process.exit(1);
+    }
+});
+// ---------------------------------------------------------------------------
+// storage
+// ---------------------------------------------------------------------------
+const storage = program
+    .command("storage")
+    .description("Maintain the asset storage backend");
+storage
+    .command("migrate-keys")
+    .description("Move asset objects under their owner's prefix (<userId>/<assetId>.<ext>)")
+    .option("--dry-run", "Report what would move without writing anything")
+    .option("--user-id <id>", "Migrate only this user's objects")
+    .option("--json", "Output the report as JSON")
+    .action(async (opts) => {
+    await setupDb();
+    const { migrateStorageKeys, formatMigrateKeysReport } = await import("./commands/storage.js");
+    try {
+        const migrateOptions = {
+            dryRun: Boolean(opts.dryRun)
+        };
+        if (opts.userId) {
+            migrateOptions.userId = opts.userId;
+        }
+        const report = await migrateStorageKeys(migrateOptions);
+        if (opts.json) {
+            console.log(JSON.stringify(report, null, 2));
+        }
+        else {
+            console.log(formatMigrateKeysReport(report, Boolean(opts.dryRun)));
+        }
+        if (report.failed > 0)
+            process.exit(1);
+    }
+    catch (e) {
+        printCommandError(e, opts.json);
+        process.exit(1);
+    }
+});
+workflows
+    .command("migrate-code-inputs")
+    .description("Rewrite saved Code node bodies to read declared inputs off `inputs`")
+    .option("--dry-run", "Report what would change without writing anything")
+    .option("--user-id <id>", "Migrate only this user's workflows")
+    .option("--json", "Output the report as JSON")
+    .action(async (opts) => {
+    await setupDb();
+    const { migrateCodeInputs, formatMigrateCodeInputsReport } = await import("./commands/migrate-code-inputs.js");
+    try {
+        const migrateOptions = {
+            dryRun: Boolean(opts.dryRun)
+        };
+        if (opts.userId) {
+            migrateOptions.userId = opts.userId;
+        }
+        const report = await migrateCodeInputs(migrateOptions);
+        if (opts.json) {
+            console.log(JSON.stringify(report, null, 2));
+        }
+        else {
+            console.log(formatMigrateCodeInputsReport(report, Boolean(opts.dryRun)));
+        }
+        if (report.failed > 0)
+            process.exit(1);
+    }
+    catch (e) {
+        printCommandError(e, opts.json);
         process.exit(1);
     }
 });
@@ -748,7 +1190,7 @@ secrets
         printTable(items.map((s) => ({ key: s.key, updated_at: s.updated_at ?? "" })));
     }
     catch (e) {
-        console.error(String(e));
+        printCommandError(e);
         process.exit(1);
     }
 });
@@ -780,7 +1222,7 @@ secrets
         console.log(`Secret '${key}' stored.`);
     }
     catch (e) {
-        console.error(String(e));
+        printCommandError(e);
         process.exit(1);
     }
 });
@@ -799,7 +1241,7 @@ secrets
         console.log(value);
     }
     catch (e) {
-        console.error(String(e));
+        printCommandError(e);
         process.exit(1);
     }
 });
@@ -888,7 +1330,10 @@ mcp
             projects[home] = globalProject;
             config["projects"] = projects;
             writeFileSync(claudeConfigPath, JSON.stringify(config, null, 2) + "\n");
-            results.push({ target: "Claude Code", status: `Installed → ${claudeConfigPath}` });
+            results.push({
+                target: "Claude Code",
+                status: `Installed → ${claudeConfigPath}`
+            });
         }
         catch (e) {
             results.push({ target: "Claude Code", status: `Error: ${e}` });
@@ -927,7 +1372,10 @@ mcp
                 content = mcpBlock + "\n";
             }
             writeFileSync(codexConfigPath, content);
-            results.push({ target: "Codex", status: `Installed → ${codexConfigPath}` });
+            results.push({
+                target: "Codex",
+                status: `Installed → ${codexConfigPath}`
+            });
         }
         catch (e) {
             results.push({ target: "Codex", status: `Error: ${e}` });
@@ -950,7 +1398,10 @@ mcp
             };
             config["mcp"] = mcpConfig;
             writeFileSync(opencodeConfigPath, JSON.stringify(config, null, 2) + "\n");
-            results.push({ target: "OpenCode", status: `Installed → ${opencodeConfigPath}` });
+            results.push({
+                target: "OpenCode",
+                status: `Installed → ${opencodeConfigPath}`
+            });
         }
         catch (e) {
             results.push({ target: "OpenCode", status: `Error: ${e}` });
@@ -1078,7 +1529,11 @@ mcp
                 });
             }
             else {
-                results.push({ target: "Claude Code", status: "Not installed", url: "" });
+                results.push({
+                    target: "Claude Code",
+                    status: "Not installed",
+                    url: ""
+                });
             }
         }
         else {
@@ -1086,7 +1541,11 @@ mcp
         }
     }
     catch {
-        results.push({ target: "Claude Code", status: "Error reading config", url: "" });
+        results.push({
+            target: "Claude Code",
+            status: "Error reading config",
+            url: ""
+        });
     }
     // Codex
     try {
@@ -1110,7 +1569,11 @@ mcp
         }
     }
     catch {
-        results.push({ target: "Codex", status: "Error reading config", url: "" });
+        results.push({
+            target: "Codex",
+            status: "Error reading config",
+            url: ""
+        });
     }
     // OpenCode
     try {
@@ -1125,7 +1588,11 @@ mcp
                 });
             }
             else {
-                results.push({ target: "OpenCode", status: "Not installed", url: "" });
+                results.push({
+                    target: "OpenCode",
+                    status: "Not installed",
+                    url: ""
+                });
             }
         }
         else {
@@ -1133,22 +1600,91 @@ mcp
         }
     }
     catch {
-        results.push({ target: "OpenCode", status: "Error reading config", url: "" });
+        results.push({
+            target: "OpenCode",
+            status: "Error reading config",
+            url: ""
+        });
     }
     console.log("\nNodeTool MCP Integration Status\n");
     printTable(results);
     console.log();
 });
+mcp
+    .command("serve")
+    .description("Run the NodeTool MCP server over stdio for an external agent " +
+    "(Claude Code, Codex, …). All logging goes to stderr; stdout is the " +
+    "MCP protocol channel.")
+    .action(async () => {
+    try {
+        const { createMcpServer, createMcpStdioTransport, forwardMcpStdioToLocalServer } = await import("@nodetool-ai/websocket");
+        if (await forwardMcpStdioToLocalServer()) {
+            process.stderr.write("NodeTool MCP forwarding to the local API server.\n");
+            return;
+        }
+        await setupDb();
+        // A local TS-node registry powers list_nodes / search_nodes /
+        // validate_workflow without spinning up a Python worker.
+        const registry = new NodeRegistry();
+        registerBaseNodes(registry);
+        registerElevenLabsNodes(registry);
+        registerMinimaxNodes(registry);
+        registerTransformersJsNodes(registry);
+        registerFalNodes(registry);
+        registerReplicateNodes(registry);
+        registerReveNodes(registry);
+        registerHuggingFaceNodes(registry);
+        // stdio serves exactly one local user; "1" is the local single-user id.
+        const server = createMcpServer({
+            registry,
+            agentToolsScope: { userId: "1", source: "stdio-local" }
+        });
+        const transport = createMcpStdioTransport();
+        await server.connect(transport);
+        process.stderr.write("NodeTool MCP server ready on stdio.\n");
+        // The stdio transport keeps the event loop alive until the client
+        // closes the connection.
+    }
+    catch (e) {
+        printCommandError(e);
+        process.exit(1);
+    }
+});
 // ---------------------------------------------------------------------------
 // package
 // ---------------------------------------------------------------------------
 registerPackageCommands(program);
+registerPackCommands(program);
+registerWorkerCommands(program);
+// Any command that opens a remote Python bridge keeps the attached worker's
+// idle clock fresh, so the reaper doesn't pause a GPU that is mid-job.
+installWorkerActivityHeartbeat(onPythonBridgeCreated);
 // ---------------------------------------------------------------------------
-// deploy / list-gcp-options — registered from commands/deploy.ts
+// deploy — registered from commands/deploy.ts
 // ---------------------------------------------------------------------------
 registerDeployCommands(program);
-registerListGcpOptions(program);
 registerAgentCommands(program);
+registerDbCommands(program);
+registerDebugCommands(program);
+registerAppCommands(program);
+registerAppsCommands(program);
+registerValidateCommand(program);
+registerTimelineCommands(program);
+registerSketchCommands(program);
+registerGameCommands(program);
+registerJsScriptCommands(program);
+registerReliabilityCommands(program);
+registerNodeCommands(program);
+registerGenerateCommand(program);
+registerEvalCommand(program);
+registerJtbdCommand(program, setupDb);
+registerAffectedCommand(program);
+registerHarnessCommands(program);
+registerCollectionCommands(program);
+registerCostsCommands(program);
+registerGenerationsCommands(program);
+registerAuthCommands(program);
+registerTelegramCommands(program);
 // ---------------------------------------------------------------------------
 program.parse();
 //# sourceMappingURL=nodetool.js.map