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

package/dist/commands/agent.js

@@ -1,21 +1,35 @@
 /**
- * `nodetool agent` — load YAML agent configs and run them with full trace output.
+ * `nodetool agent` — run one CodeAct turn over the default toolbelt, with full
+ * trace output.
+ *
+ * The loop is the chat's loop: the belt is assembled by `buildCliAgentBelt`
+ * and the turn by `createCliCodeActTurn`, both shared with `--stdin` chat, so
+ * the provider is offered `execute_code` and the toolbelt lives in the sandbox.
+ * `create_plan` and `execute_plan` are on the belt, so an objective that wants
+ * a plan gets one and the `planning_update` / `task_update` events stream.
  *
  * Subcommands:
- *   nodetool agent run <yaml-file> [--objective "..."] [--mode loop|plan|multi-agent]
- *   nodetool agent test <yaml-file>     # validate config + dry list of tools/provider
- *   nodetool agent list <dir>           # list YAML configs in a directory
+ *   nodetool agent run --objective "..."   # objective may also come from stdin
+ *   nodetool agent diagnose <job_id>       # aggregate a failed run into a report
  */
 import * as fs from "node:fs";
 import * as fsp from "node:fs/promises";
 import * as path from "node:path";
-import * as yaml from "js-yaml";
 import chalk from "chalk";
-import { ProcessingContext } from "@nodetool-ai/runtime";
-import { MultiModeAgent, FindModelTool, GenerateImageTool, EditImageTool, GenerateVideoTool, AnimateImageTool, GenerateSpeechTool, TranscribeAudioTool, EmbedTextTool, ReadFileTool, WriteFileTool, ListDirectoryTool, EditFileTool, GlobTool, GrepTool, DownloadFileTool, HttpRequestTool, GoogleSearchTool, GoogleNewsTool, GoogleImagesTool, BrowserTool, ScreenshotTool, RunCodeTool, CalculatorTool, ExtractPDFTextTool, ConvertPDFToMarkdownTool, ConvertDocumentTool, StatisticsTool, GeometryTool, ConversionTool, OpenAIWebSearchTool, OpenAIImageGenerationTool, OpenAITextToSpeechTool, DataForSEOSearchTool, DataForSEONewsTool, SearchEmailTool, ArchiveEmailTool, getAllMcpTools } from "@nodetool-ai/agents";
-import { initDb, getSecret } from "@nodetool-ai/models";
+import { RUN_BUDGET_CONTEXT_KEY } from "@nodetool-ai/runtime";
+import { PERMISSION_GATE_CONTEXT_KEY } from "@nodetool-ai/agents";
+import { processChat } from "@nodetool-ai/chat";
+import { initDb } from "@nodetool-ai/models";
 import { getDefaultDbPath, configureLogging } from "@nodetool-ai/config";
 import { createProvider, buildConfiguredProviders } from "../providers.js";
+import { buildFullRegistry } from "../node-registry.js";
+import { buildCliToolbelt } from "../agent-toolbelt.js";
+import { applySystemPrompt, buildCliAgentBelt, createCliCodeActTurn, loadCliSkillCatalog } from "../chat-codeact.js";
+import { createChatContext } from "../chat-context.js";
+import { budgetStopReason, budgetSummaryLine, createCliRunBudget } from "../run-budget.js";
+import { createCliPermissionGate, parsePermissionMode, PERMISSION_MODE_NAMES } from "../permission-gate.js";
+import { diagnoseRun, renderDiagnosis } from "../diagnose.js";
+import { isRecord, isString } from "../predicates.js";
 const PROVIDER_ALIASES = {
     google: "gemini",
     googleai: "gemini",
@@ -31,94 +45,6 @@ function expandTilde(p) {
     }
     return p;
 }
-/**
- * FindModelTool that injects YAML-declared preferences as defaults when the
- * LLM omits explicit hints.
- */
-class PreferringFindModelTool extends FindModelTool {
-    prefs;
-    constructor(providers, prefs) {
-        super(providers);
-        this.prefs = prefs;
-    }
-    async process(context, params) {
-        const merged = { ...params };
-        const capability = typeof params["capability"] === "string"
-            ? params["capability"]
-            : undefined;
-        if (typeof merged["provider_hint"] !== "string" &&
-            this.prefs.preferredProviders &&
-            this.prefs.preferredProviders.length > 0) {
-            merged["provider_hint"] = this.prefs.preferredProviders[0];
-        }
-        if (capability && !merged["model_hint"]) {
-            const pref = this.prefs.preferredModels?.[capability];
-            if (pref && pref.length > 0) {
-                merged["model_hint"] = pref;
-            }
-        }
-        return super.process(context, merged);
-    }
-}
-function buildToolMap(providers, prefs = {}) {
-    const m = {
-        find_model: new PreferringFindModelTool(providers ?? {}, prefs),
-        generate_image: new GenerateImageTool(),
-        edit_image: new EditImageTool(),
-        generate_video: new GenerateVideoTool(),
-        animate_image: new AnimateImageTool(),
-        generate_speech: new GenerateSpeechTool(),
-        transcribe_audio: new TranscribeAudioTool(),
-        embed_text: new EmbedTextTool(),
-        read_file: new ReadFileTool(),
-        write_file: new WriteFileTool(),
-        edit_file: new EditFileTool(),
-        list_directory: new ListDirectoryTool(),
-        glob: new GlobTool(),
-        grep: new GrepTool(),
-        download_file: new DownloadFileTool(),
-        http_request: new HttpRequestTool(),
-        google_search: new GoogleSearchTool(),
-        google_news: new GoogleNewsTool(),
-        google_images: new GoogleImagesTool(),
-        browser: new BrowserTool(),
-        screenshot: new ScreenshotTool(),
-        run_code: new RunCodeTool(),
-        calculator: new CalculatorTool(),
-        statistics: new StatisticsTool(),
-        geometry: new GeometryTool(),
-        conversion: new ConversionTool(),
-        extract_pdf_text: new ExtractPDFTextTool(),
-        convert_pdf_to_markdown: new ConvertPDFToMarkdownTool(),
-        convert_document: new ConvertDocumentTool(),
-        openai_web_search: new OpenAIWebSearchTool(),
-        openai_image_generation: new OpenAIImageGenerationTool(),
-        openai_text_to_speech: new OpenAITextToSpeechTool(),
-        dataseo_search: new DataForSEOSearchTool(),
-        dataseo_news: new DataForSEONewsTool(),
-        search_email: new SearchEmailTool(),
-        archive_email: new ArchiveEmailTool()
-    };
-    for (const tool of getAllMcpTools({ providers })) {
-        m[tool.name] = tool;
-    }
-    return m;
-}
-function resolveTools(names, providers, prefs = {}) {
-    if (!names || names.length === 0)
-        return { tools: [], unknown: [] };
-    const map = buildToolMap(providers, prefs);
-    const tools = [];
-    const unknown = [];
-    for (const name of names) {
-        const tool = map[name];
-        if (tool)
-            tools.push(tool);
-        else
-            unknown.push(name);
-    }
-    return { tools, unknown };
-}
 function shorten(s, n = 200) {
     const oneLine = s.replace(/\s+/g, " ").trim();
     return oneLine.length > n ? oneLine.slice(0, n) + "…" : oneLine;
@@ -156,8 +82,10 @@ function traceEvent(msg, opts) {
             break;
         }
         case "step_result": {
-            const tag = msg.is_task_result ? chalk.green("result★") : chalk.green("step✓ ");
-            const preview = typeof msg.result === "string"
+            const tag = msg.is_task_result
+                ? chalk.green("result★")
+                : chalk.green("step✓ ");
+            const preview = isString(msg.result)
                 ? shorten(msg.result, 200)
                 : shorten(JSON.stringify(msg.result ?? null), 200);
             process.stderr.write(`${t} ${tag}  ${preview}\n`);
@@ -166,7 +94,7 @@ function traceEvent(msg, opts) {
             break;
         }
         case "chunk":
-            if (opts.verbose && msg.content) {
+            if (opts.verbose && isString(msg.content)) {
                 process.stderr.write(`${t} ${chalk.gray("chunk")}    ${shorten(msg.content, 80)}\n`);
             }
             break;
@@ -180,16 +108,8 @@ function traceEvent(msg, opts) {
     }
 }
 // ---------------------------------------------------------------------------
-// Loaders
+// run subcommand
 // ---------------------------------------------------------------------------
-async function loadAgentYaml(file) {
-    const raw = await fsp.readFile(file, "utf-8");
-    const parsed = yaml.load(raw);
-    if (!parsed || typeof parsed !== "object") {
-        throw new Error(`YAML did not parse to an object: ${file}`);
-    }
-    return parsed;
-}
 async function readObjectiveFromStdin() {
     if (process.stdin.isTTY)
         return null;
@@ -200,7 +120,20 @@ async function readObjectiveFromStdin() {
     const text = Buffer.concat(chunks).toString("utf-8").trim();
     return text || null;
 }
-async function runAgentCommand(file, opts) {
+/** The text the run answers with: the last assistant message that carries any. */
+function finalAssistantText(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const message = messages[i];
+        if (message.role !== "assistant")
+            continue;
+        if (isString(message.content) && message.content.trim()) {
+            return message.content;
+        }
+    }
+    return null;
+}
+/** Exit code for the process: 0 when the turn finished without an error. */
+export async function runAgentCommand(opts) {
     // Quiet the runtime's INFO logger so it doesn't interleave the trace.
     // Users who want raw logs can set NODETOOL_LOG_LEVEL=info before running.
     if (!process.env["NODETOOL_LOG_LEVEL"]) {
@@ -214,253 +147,339 @@ async function runAgentCommand(file, opts) {
     catch {
         /* fallback to env vars */
     }
-    const cfg = await loadAgentYaml(file);
-    // Resolve provider/model (CLI flags override YAML)
-    const providerId = opts.provider ?? normalizeProvider(cfg.model?.provider ?? "");
-    if (!providerId) {
-        throw new Error("No provider specified. Set `model.provider` in YAML or use --provider.");
+    if (!opts.provider) {
+        throw new Error("No provider specified. Use --provider <id>.");
     }
-    const modelId = opts.model ?? cfg.model?.id;
+    const providerId = normalizeProvider(opts.provider);
+    const modelId = opts.model;
     if (!modelId) {
-        throw new Error("No model specified. Set `model.id` in YAML or use --model.");
+        throw new Error("No model specified. Use --model <id>.");
     }
-    // Resolve objective: --objective > stdin > YAML default
-    const stdinObjective = await readObjectiveFromStdin();
-    const objective = opts.objective ?? stdinObjective ?? cfg.objective;
+    const objective = opts.objective ?? (await readObjectiveFromStdin());
     if (!objective) {
-        throw new Error("No objective provided. Use --objective \"...\", pipe via stdin, or set `objective:` in YAML.");
+        throw new Error('No objective provided. Use --objective "..." or pipe it via stdin.');
     }
     // Configured providers (for find_model + media tool dispatch)
     const configuredProviders = await buildConfiguredProviders();
-    // Preferences from YAML (preferred_providers, preferred_models)
-    const prefs = {};
-    if (Array.isArray(cfg.preferred_providers)) {
-        prefs.preferredProviders = cfg.preferred_providers.filter((x) => typeof x === "string");
-    }
-    if (cfg.preferred_models && typeof cfg.preferred_models === "object") {
-        prefs.preferredModels = {};
-        for (const [cap, val] of Object.entries(cfg.preferred_models)) {
-            const list = typeof val === "string" ? [val] : Array.isArray(val) ? val : [];
-            const cleaned = list.filter((x) => typeof x === "string");
-            if (cleaned.length > 0)
-                prefs.preferredModels[cap] = cleaned;
-        }
-    }
-    // Tools
-    const { tools, unknown } = resolveTools(cfg.tools, configuredProviders, prefs);
-    if (unknown.length > 0) {
-        process.stderr.write(chalk.yellow(`warn: ignoring unknown tools: ${unknown.join(", ")}\n`));
-    }
-    // Workspace
-    const workspaceDir = expandTilde(opts.workspace ?? cfg.workspace?.path ?? process.cwd());
-    if (cfg.workspace?.auto_create !== false) {
-        try {
-            fs.mkdirSync(workspaceDir, { recursive: true });
-        }
-        catch {
-            /* ignore */
-        }
+    const workspaceDir = expandTilde(opts.workspace ?? process.cwd());
+    try {
+        fs.mkdirSync(workspaceDir, { recursive: true });
     }
-    // Mode
-    const modeArg = (opts.mode ?? cfg.mode ?? "plan");
-    if (!["loop", "plan", "multi-agent"].includes(modeArg)) {
-        throw new Error(`Invalid mode: ${modeArg}. Use loop|plan|multi-agent.`);
+    catch {
+        /* ignore — an existing dir is the common case */
     }
     const provider = await createProvider(providerId);
-    // Header
-    if (!opts.json) {
-        process.stderr.write(chalk.bold(`\n▸ ${cfg.name ?? path.basename(file)}\n`) +
-            chalk.gray(`  provider=${providerId} model=${modelId} mode=${modeArg} tools=${tools.length}\n`) +
-            chalk.gray(`  objective: ${shorten(objective, 200)}\n\n`));
-    }
-    const planningModel = cfg.planning_agent?.enabled === false ? modelId : cfg.planning_agent?.model?.id ?? modelId;
-    // Build the effective system prompt: user prompt + a preferences block so
-    // the LLM also "knows" which providers/models to favor (in addition to the
-    // hint injection inside FindModelTool).
-    const prefLines = [];
-    if (prefs.preferredProviders && prefs.preferredProviders.length > 0) {
-        prefLines.push(`Preferred providers (in order): ${prefs.preferredProviders.join(", ")}.`);
+    const context = await createChatContext({ workspaceDir });
+    // Hand the context the instances already configured above, so a tool that
+    // dispatches by provider id gets this run's provider rather than resolving a
+    // second one of its own.
+    for (const [id, configured] of Object.entries(configuredProviders)) {
+        context.registerProvider(id, configured);
     }
-    if (prefs.preferredModels) {
-        for (const [cap, list] of Object.entries(prefs.preferredModels)) {
-            prefLines.push(`Preferred ${cap} model: ${list.join(" or ")}.`);
+    const traceOpts = {
+        json: !!opts.json,
+        verbose: !!opts.verbose
+    };
+    const emit = (message) => {
+        traceEvent(message, traceOpts);
+    };
+    // The run's gate, built once. `readObjectiveFromStdin` already returned null
+    // on a TTY, so the same test says whether anyone is there to answer a
+    // prompt: an objective that arrived down a pipe leaves nobody at the
+    // keyboard, and the run gates headless with the notice below.
+    const gate = createCliPermissionGate({
+        hostName: "nodetool agent run",
+        mode: parsePermissionMode(opts.permissionMode),
+        interactive: process.stdin.isTTY === true,
+        // In `--json` the notice and any prompt ride the event stream, so it stays
+        // one JSON object per line.
+        write: (text) => {
+            if (opts.json) {
+                emit({
+                    type: "log_update",
+                    node_id: "agent",
+                    node_name: "permissions",
+                    content: text,
+                    severity: "info"
+                });
+            }
+            else {
+                process.stderr.write(chalk.gray(`${text}\n`));
+            }
         }
-    }
-    const effectiveSystemPrompt = prefLines.length > 0
-        ? `${cfg.system_prompt ?? ""}\n\n# Model Preferences\n${prefLines.join("\n")}\nUse these when calling find_model unless they cannot satisfy the request.`.trim()
-        : cfg.system_prompt;
-    const agent = new MultiModeAgent({
-        name: cfg.name ?? "yaml-agent",
-        objective,
+    });
+    // Loops this command never constructs — an `AgentNode` reached through
+    // `run_node`, a JS script — read the gate off the context rather than
+    // building an ungated run of their own (`gateFromContext`, invariant I-1).
+    context.set(PERMISSION_GATE_CONTEXT_KEY, gate);
+    // The bounds this run shares downward, created once (invariant I-2). The
+    // same channel the gate takes: a loop this command never constructs reads
+    // the budget off the context instead of opening an allowance of its own.
+    const budget = await createCliRunBudget({
+        ...(opts.costCap !== undefined && { costCap: opts.costCap }),
+        ...(opts.timeout !== undefined && { timeout: opts.timeout })
+    });
+    context.set(RUN_BUDGET_CONTEXT_KEY, budget);
+    // One belt, every run. A narrowing flag made each invocation its own
+    // configuration — the thing YAML configs were removed for — and an agent
+    // run that behaves differently from the last one is not reproducible.
+    const belt = buildCliAgentBelt({
+        baseTools: buildCliToolbelt(configuredProviders, buildFullRegistry()),
         provider,
         model: modelId,
-        mode: modeArg,
-        tools,
-        systemPrompt: effectiveSystemPrompt,
-        maxTokenLimit: cfg.max_tokens,
-        maxIterations: cfg.max_iterations,
-        maxSteps: cfg.max_steps,
-        planningModel
+        forwardMessage: emit,
+        gate,
+        // An objective is a job, not a conversation: the two plan capabilities are
+        // on the belt so the model can decompose one and run the DAG itself.
+        planning: true,
+        budget
     });
-    const ctx = new ProcessingContext({
-        jobId: `agent-${Date.now()}`,
-        userId: "1",
-        workspaceDir,
-        secretResolver: getSecret
-    });
-    for (const [id, p] of Object.entries(configuredProviders)) {
-        ctx.registerProvider(id, p);
+    if (!opts.json) {
+        process.stderr.write(chalk.bold(`\n▸ agent\n`) +
+            chalk.gray(`  provider=${providerId} model=${modelId} tools=${belt.length}\n`) +
+            chalk.gray(`  objective: ${shorten(objective, 200)}\n\n`));
     }
-    const traceOpts = {
-        json: !!opts.json,
-        verbose: !!opts.verbose
-    };
-    let finalText = null;
+    const turn = createCliCodeActTurn({
+        tools: belt,
+        context,
+        skillCatalog: await loadCliSkillCatalog(context.userId),
+        // Calls the sandbox makes have no provider tool-call id of their own.
+        onToolCall: ({ name, args }) => {
+            emit({ type: "tool_call_update", name, args });
+        }
+    });
+    const messages = [];
+    applySystemPrompt(messages, turn.systemPrompt);
     let errored = false;
     try {
-        for await (const msg of agent.execute(ctx)) {
-            traceEvent(msg, traceOpts);
-            if (msg.type === "step_result") {
-                const sr = msg;
-                if (sr.is_task_result) {
-                    finalText =
-                        typeof sr.result === "string"
-                            ? sr.result
-                            : JSON.stringify(sr.result, null, 2);
+        await processChat({
+            userInput: objective,
+            messages,
+            model: modelId,
+            provider,
+            context,
+            tools: turn.tools,
+            turnBudget: budget,
+            maxIterations: opts.maxIterations === undefined ? undefined : Number(opts.maxIterations),
+            callbacks: {
+                onChunk: (content) => {
+                    emit({ type: "chunk", content, done: false });
+                },
+                onToolCall: (call) => {
+                    emit({
+                        type: "tool_call_update",
+                        name: call.name,
+                        args: call.args,
+                        tool_call_id: call.id
+                    });
+                },
+                onToolResult: (call, result) => {
+                    emit({
+                        type: "tool_result_update",
+                        node_id: "agent",
+                        name: call.name,
+                        tool_call_id: call.id,
+                        result: isRecord(result) ? result : { value: result }
+                    });
                 }
             }
-            else if (msg.type === "error") {
-                errored = true;
-            }
-        }
+        });
     }
     catch (e) {
         errored = true;
-        process.stderr.write(chalk.red(`\nagent failed: ${String(e)}\n`));
-    }
-    if (finalText === null) {
-        const r = agent.getResults();
-        if (r != null) {
-            finalText = typeof r === "string" ? r : JSON.stringify(r, null, 2);
+        const message = e instanceof Error ? e.message : String(e);
+        emit({ type: "error", message });
+        if (!opts.json) {
+            process.stderr.write(chalk.red(`\nagent failed: ${message}\n`));
         }
     }
+    const finalText = finalAssistantText(messages);
     if (!opts.json)
         process.stderr.write(chalk.bold("\n— result —\n"));
     if (finalText)
         process.stdout.write(finalText + "\n");
-    process.exit(errored ? 1 : 0);
-}
-// ---------------------------------------------------------------------------
-// test subcommand — validate config without running
-// ---------------------------------------------------------------------------
-async function testAgentCommand(file) {
-    if (!process.env["NODETOOL_LOG_LEVEL"]) {
-        process.env["NODETOOL_LOG_LEVEL"] = "error";
-    }
-    configureLogging();
-    try {
-        initDb(getDefaultDbPath());
+    // What the whole run — this loop plus every sub-agent and node it started —
+    // committed against the shared cap.
+    const summary = budgetSummaryLine(budget);
+    if (opts.json) {
+        emit({
+            type: "log_update",
+            node_id: "agent",
+            node_name: "budget",
+            content: summary,
+            severity: "info"
+        });
+    }
+    else {
+        process.stderr.write(chalk.gray(`\n${summary}\n`));
+    }
+    // A ceiling ended the run, not the model finishing its answer. Said nowhere,
+    // the two are indistinguishable from an empty transcript (invariant I-3), so
+    // the reason is reported before anything else about how the run ended.
+    const stopReason = budgetStopReason(budget);
+    if (!errored && stopReason) {
+        emit({ type: "error", message: stopReason });
+        if (!opts.json) {
+            process.stderr.write(chalk.red(`\nagent stopped: ${stopReason}\n`));
+        }
+        return 1;
+    }
+    // A run that ended on a tool call or a contentless assistant turn produced
+    // no answer. Writing nothing and exiting 0 is indistinguishable from an
+    // empty-but-successful result, so it fails instead (invariant I-3).
+    if (!errored && !finalText) {
+        const message = "agent produced no answer: the turn ended without a final assistant message";
+        emit({ type: "error", message });
+        if (!opts.json) {
+            process.stderr.write(chalk.red(`\nagent failed: ${message}\n`));
+        }
+        return 1;
     }
-    catch {
-        /* fallback to env vars */
+    return errored ? 1 : 0;
+}
+/** Parse a JSONL file into one parsed object per non-blank line. */
+async function readJsonl(file) {
+    const text = await fsp.readFile(file, "utf-8");
+    const out = [];
+    for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            // SAFETY: each caller names the record shape its own bundle file was
+            // written with — this reader only splits lines and parses JSON.
+            out.push(JSON.parse(trimmed));
+        }
+        catch {
+            // Skip partial/corrupt lines (e.g. a crash mid-write).
+        }
     }
-    const cfg = await loadAgentYaml(file);
-    const issues = [];
-    const okLines = [];
-    okLines.push(`name: ${cfg.name ?? "(unset)"}`);
-    okLines.push(`description: ${cfg.description ?? "(unset)"}`);
-    const provider = cfg.model?.provider;
-    if (!provider)
-        issues.push("missing model.provider");
-    else
-        okLines.push(`provider: ${provider} → ${normalizeProvider(provider)}`);
-    if (!cfg.model?.id)
-        issues.push("missing model.id");
-    else
-        okLines.push(`model: ${cfg.model.id}`);
-    okLines.push(`mode: ${cfg.mode ?? "plan (default)"}`);
-    okLines.push(`system_prompt: ${cfg.system_prompt ? `${cfg.system_prompt.length} chars` : "(none)"}`);
-    const { tools, unknown } = resolveTools(cfg.tools);
-    okLines.push(`tools resolved: ${tools.map((t) => t.name).join(", ") || "(none)"}`);
-    if (unknown.length > 0)
-        issues.push(`unknown tools: ${unknown.join(", ")}`);
-    // Check provider can be instantiated
-    if (provider) {
+    return out;
+}
+/** First existing path among the candidates, or null. */
+function firstExisting(candidates) {
+    for (const p of candidates) {
         try {
-            await createProvider(normalizeProvider(provider));
-            okLines.push(`provider instantiation: ok`);
+            if (fs.statSync(p).isFile())
+                return p;
         }
-        catch (e) {
-            issues.push(`provider instantiation failed: ${String(e)}`);
+        catch {
+            // Not a readable file — try the next candidate.
         }
     }
-    process.stdout.write(chalk.bold(`\n▸ ${path.basename(file)}\n\n`));
-    for (const line of okLines)
-        process.stdout.write(`  ${chalk.green("✓")} ${line}\n`);
-    for (const issue of issues)
-        process.stdout.write(`  ${chalk.red("✗")} ${issue}\n`);
-    process.stdout.write("\n");
-    process.exit(issues.length > 0 ? 1 : 0);
+    return null;
 }
-// ---------------------------------------------------------------------------
-// list subcommand
-// ---------------------------------------------------------------------------
-async function listAgentsCommand(dir) {
-    const abs = path.resolve(expandTilde(dir));
+/**
+ * Locate a debug bundle directory for a job id. The `debug` command writes
+ * bundles to `nodetool-debug/<id>-<timestamp>/`; we pick the most recent dir
+ * whose name starts with the id, relative to cwd.
+ */
+function findDebugBundle(jobId) {
+    const root = path.join(process.cwd(), "nodetool-debug");
     let entries;
     try {
-        entries = await fsp.readdir(abs, { withFileTypes: true });
+        entries = fs.readdirSync(root, { withFileTypes: true });
     }
-    catch (e) {
-        process.stderr.write(`Cannot read ${abs}: ${String(e)}\n`);
-        process.exit(1);
+    catch {
+        return null;
     }
-    const yamls = entries.filter((e) => e.isFile() && (e.name.endsWith(".yaml") || e.name.endsWith(".yml")));
-    if (yamls.length === 0) {
-        process.stdout.write(`(no YAML configs in ${abs})\n`);
-        return;
+    const matches = entries
+        .filter((e) => e.isDirectory() && e.name.startsWith(`${jobId}-`))
+        .map((e) => path.join(root, e.name))
+        .sort();
+    return matches.length > 0 ? matches[matches.length - 1] : null;
+}
+/** Fetch a job record over the tRPC API; null when unreachable/not found. */
+async function fetchJob(apiUrl, jobId) {
+    try {
+        const { createApiClient } = await import("../api-client.js");
+        const client = createApiClient(apiUrl);
+        const data = await client.jobs.get.query({ id: jobId });
+        return {
+            id: isString(data["id"]) ? data["id"] : jobId,
+            status: isString(data["status"]) ? data["status"] : undefined,
+            error: isString(data["error"]) ? data["error"] : null,
+            workflowId: isString(data["workflow_id"]) ? data["workflow_id"] : null
+        };
+    }
+    catch {
+        // Server unreachable or job missing — diagnose degrades on a null job.
+        return null;
     }
-    for (const e of yamls) {
-        const file = path.join(abs, e.name);
+}
+async function diagnoseCommand(jobId, opts) {
+    const apiUrl = opts.apiUrl ?? process.env["NODETOOL_API_URL"] ?? "http://localhost:7777";
+    const inputs = {};
+    // Job record (best-effort over the API).
+    const job = await fetchJob(apiUrl, jobId);
+    if (job)
+        inputs.job = job;
+    else
+        inputs.job = { id: jobId };
+    // Messages + trace from a debug bundle (when one exists for this job).
+    const bundle = findDebugBundle(jobId);
+    if (bundle) {
+        const messagesPath = firstExisting([
+            path.join(bundle, "server", "messages.jsonl")
+        ]);
+        if (messagesPath) {
+            try {
+                inputs.messages = await readJsonl(messagesPath);
+            }
+            catch {
+                // Unreadable — leave messages unset so the report flags it missing.
+            }
+        }
+    }
+    // Trace spans: --trace-file > NODETOOL_TRACE_FILE > the bundle's trace.jsonl.
+    const tracePath = firstExisting([
+        opts.traceFile,
+        process.env["NODETOOL_TRACE_FILE"],
+        bundle ? path.join(bundle, "server", "trace.jsonl") : undefined
+    ].filter((p) => p != null));
+    if (tracePath) {
         try {
-            const cfg = await loadAgentYaml(file);
-            process.stdout.write(`${chalk.bold(e.name)}  ${chalk.gray(cfg.model?.provider ?? "?")}/${chalk.gray(cfg.model?.id ?? "?")}\n  ${cfg.description ?? "(no description)"}\n`);
+            inputs.spans = await readJsonl(tracePath);
         }
-        catch (err) {
-            process.stdout.write(`${e.name}  ${chalk.red("invalid: " + String(err))}\n`);
+        catch {
+            // Unreadable — report flags trace as missing.
         }
     }
+    const report = diagnoseRun(inputs);
+    if (opts.json) {
+        process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+    }
+    else {
+        process.stdout.write(renderDiagnosis(report) + "\n");
+    }
+    process.exit(report.ok ? 0 : 1);
 }
 // ---------------------------------------------------------------------------
 // Registration
 // ---------------------------------------------------------------------------
 export function registerAgentCommands(program) {
-    const agent = program.command("agent").description("Run YAML-defined agents");
+    const agent = program
+        .command("agent")
+        .description("Run the agent loop from the command line");
     agent
-        .command("run <yaml-file>")
-        .description("Run an agent from a YAML config (objective via --objective or stdin)")
-        .option("-o, --objective <text>", "Objective for the agent (overrides stdin/yaml default)")
-        .option("--mode <mode>", "Override mode: loop|plan|multi-agent")
-        .option("-p, --provider <id>", "Override provider")
-        .option("-m, --model <id>", "Override model")
-        .option("-w, --workspace <path>", "Override workspace dir")
+        .command("run")
+        .description("Run an agent over the default toolbelt (objective via --objective or stdin)")
+        .option("-o, --objective <text>", "Objective for the agent")
+        .option("-p, --provider <id>", "Provider id")
+        .option("-m, --model <id>", "Model id")
+        .option("-w, --workspace <path>", "Workspace dir (default: cwd)")
+        .option("--max-iterations <n>", "Tool-calling rounds in the turn (default 25)")
+        .option("--permission-mode <mode>", `Permission mode (${PERMISSION_MODE_NAMES.join(" | ")}); on a TTY the ` +
+        "default asks before each write, execute or external call")
+        .option("--cost-cap <usd>", "Ceiling on provider spend for the whole run, shared by every loop it " +
+        "starts; 0 lifts it (default: NODETOOL_AGENT_TURN_COST_CAP_USD)")
+        .option("--timeout <s>", "Wall-clock bound on the run in seconds; 0 leaves it no time at all " +
+        "(default: NODETOOL_AGENT_TURN_DEADLINE_MS)")
         .option("--json", "Emit each event as a JSON line on stderr")
         .option("-v, --verbose", "Include chunk/other low-level events in trace")
-        .action(async (file, opts) => {
-        try {
-            await runAgentCommand(file, opts);
-        }
-        catch (e) {
-            process.stderr.write(chalk.red(`error: ${String(e)}\n`));
-            process.exit(1);
-        }
-    });
-    agent
-        .command("test <yaml-file>")
-        .description("Validate an agent YAML config (provider, model, tools)")
-        .action(async (file) => {
+        .action(async (opts) => {
         try {
-            await testAgentCommand(file);
+            process.exit(await runAgentCommand(opts));
         }
         catch (e) {
             process.stderr.write(chalk.red(`error: ${String(e)}\n`));
@@ -468,11 +487,14 @@ export function registerAgentCommands(program) {
         }
     });
     agent
-        .command("list <dir>")
-        .description("List YAML agent configs in a directory")
-        .action(async (dir) => {
+        .command("diagnose <job_id>")
+        .description("Aggregate a failed run (failing node/step, error, last LLM call, memory) into one report")
+        .option("--json", "Emit the DiagnosisReport as JSON")
+        .option("--trace-file <path>", "Trace JSONL to read the last llm.chat span from (else NODETOOL_TRACE_FILE or the debug bundle)")
+        .option("--api-url <url>", "API base URL for the job lookup")
+        .action(async (jobId, opts) => {
         try {
-            await listAgentsCommand(dir);
+            await diagnoseCommand(jobId, opts);
         }
         catch (e) {
             process.stderr.write(chalk.red(`error: ${String(e)}\n`));