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

package/dist/debug/verdict.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verdict.js","sourceRoot":"","sources":["../../src/debug/verdict.ts"],"names":[],"mappings":"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"}

package/dist/debug/watch.d.ts

@@ -0,0 +1,23 @@
+import { type RunSnapshot } from "./diff.js";
+/** Minimal shape of `fs.watch`, narrowed to what the loop uses. */
+export type FileWatcher = (path: string, onChange: () => void) => {
+    close: () => void;
+};
+export interface WatchLoopInit<T> {
+    /** The file whose saves trigger a re-run. */
+    file: string;
+    /** The run already performed, so the first diff has something to compare to. */
+    first: T;
+    run: () => Promise<T>;
+    snapshot: (result: T) => RunSnapshot;
+    /** Label for the status transition line, e.g. `server` or `stage`. */
+    statusLabel?: string;
+    log: (line: string) => void;
+    /** Resolves to stop watching. Defaults to the first SIGINT. */
+    stop?: Promise<void>;
+    debounceMs?: number;
+    watchFile?: FileWatcher;
+}
+/** Watch `file`, re-running and diffing until the stop signal resolves. */
+export declare function runWatchLoop<T>(init: WatchLoopInit<T>): Promise<void>;
+//# sourceMappingURL=watch.d.ts.map

package/dist/debug/watch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.d.ts","sourceRoot":"","sources":["../../src/debug/watch.ts"],"names":[],"mappings":"AAaA,OAAO,EAAwB,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAEnE,mEAAmE;AACnE,MAAM,MAAM,WAAW,GAAG,CACxB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,IAAI,KACjB;IAAE,KAAK,EAAE,MAAM,IAAI,CAAA;CAAE,CAAC;AAE3B,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,KAAK,EAAE,CAAC,CAAC;IACT,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;IACtB,QAAQ,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,WAAW,CAAC;IACrC,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,+DAA+D;IAC/D,IAAI,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,WAAW,CAAC;CACzB;AAaD,2EAA2E;AAC3E,wBAAsB,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CA0C3E"}

package/dist/debug/watch.js

@@ -0,0 +1,68 @@
+/**
+ * The watch loop `nodetool debug --watch` and `nodetool app build --watch`
+ * share: re-run on save, diff the new run against the last one, print only what
+ * moved.
+ *
+ * The loop owns the awkward parts — debouncing an editor's write burst, never
+ * running two passes at once, surviving a run that throws — and nothing else.
+ * What a run means is the caller's: it supplies `run` and a projection into
+ * {@link RunSnapshot}, which is what the differ compares. The watcher and the
+ * stop signal are injectable so the loop is testable without touching the file
+ * system or the process.
+ */
+import { watch } from "node:fs";
+import { diffRuns, formatDiff } from "./diff.js";
+const defaultWatcher = (path, onChange) => watch(path, onChange);
+function sigintStop(log) {
+    return new Promise((resolve) => {
+        process.on("SIGINT", () => {
+            log("\nStopped watching.");
+            resolve();
+        });
+    });
+}
+/** Watch `file`, re-running and diffing until the stop signal resolves. */
+export async function runWatchLoop(init) {
+    const log = init.log;
+    log(`\nWatching ${init.file} — edit to re-run, Ctrl-C to stop.`);
+    let previous = init.snapshot(init.first);
+    let running = false;
+    let pending = false;
+    let timer = null;
+    const rerun = async () => {
+        if (running) {
+            pending = true;
+            return;
+        }
+        running = true;
+        try {
+            const next = init.snapshot(await init.run());
+            const diff = diffRuns(previous, next);
+            previous = next;
+            log(`\n── re-run @ ${new Date().toLocaleTimeString()} ──`);
+            log(formatDiff(diff, init.statusLabel));
+        }
+        catch (e) {
+            log(`Re-run failed: ${String(e)}`);
+        }
+        finally {
+            running = false;
+            if (pending) {
+                pending = false;
+                await rerun();
+            }
+        }
+    };
+    const debounceMs = init.debounceMs ?? 200;
+    const watcher = (init.watchFile ?? defaultWatcher)(init.file, () => {
+        // Debounce editor write bursts (one save → several change events).
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => void rerun(), debounceMs);
+    });
+    await (init.stop ?? sigintStop(log));
+    if (timer)
+        clearTimeout(timer);
+    watcher.close();
+}
+//# sourceMappingURL=watch.js.map

package/dist/debug/watch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.js","sourceRoot":"","sources":["../../src/debug/watch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAoB,MAAM,WAAW,CAAC;AAwBnE,MAAM,cAAc,GAAgB,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AAE9E,SAAS,UAAU,CAAC,GAA2B;IAC7C,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QACnC,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE;YACxB,GAAG,CAAC,qBAAqB,CAAC,CAAC;YAC3B,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,2EAA2E;AAC3E,MAAM,CAAC,KAAK,UAAU,YAAY,CAAI,IAAsB;IAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;IACrB,GAAG,CAAC,cAAc,IAAI,CAAC,IAAI,oCAAoC,CAAC,CAAC;IAEjE,IAAI,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACzC,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,KAAK,GAAyC,IAAI,CAAC;IAEvD,MAAM,KAAK,GAAG,KAAK,IAAmB,EAAE;QACtC,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,GAAG,IAAI,CAAC;YACf,OAAO;QACT,CAAC;QACD,OAAO,GAAG,IAAI,CAAC;QACf,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;YAC7C,MAAM,IAAI,GAAG,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;YACtC,QAAQ,GAAG,IAAI,CAAC;YAChB,GAAG,CAAC,iBAAiB,IAAI,IAAI,EAAE,CAAC,kBAAkB,EAAE,KAAK,CAAC,CAAC;YAC3D,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;QAC1C,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,GAAG,CAAC,kBAAkB,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACrC,CAAC;gBAAS,CAAC;YACT,OAAO,GAAG,KAAK,CAAC;YAChB,IAAI,OAAO,EAAE,CAAC;gBACZ,OAAO,GAAG,KAAK,CAAC;gBAChB,MAAM,KAAK,EAAE,CAAC;YAChB,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,GAAG,CAAC;IAC1C,MAAM,OAAO,GAAG,CAAC,IAAI,CAAC,SAAS,IAAI,cAAc,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE;QACjE,mEAAmE;QACnE,IAAI,KAAK;YAAE,YAAY,CAAC,KAAK,CAAC,CAAC;QAC/B,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,KAAK,KAAK,EAAE,EAAE,UAAU,CAAC,CAAC;IACrD,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,IAAI,CAAC,IAAI,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;IACrC,IAAI,KAAK;QAAE,YAAY,CAAC,KAAK,CAAC,CAAC;IAC/B,OAAO,CAAC,KAAK,EAAE,CAAC;AAClB,CAAC"}

package/dist/diagnose.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Pure failure-diagnosis aggregator for `nodetool agent diagnose <job_id>`.
+ *
+ * When a run fails the cause is scattered across the job record, the structured
+ * processing-message stream, and the OpenTelemetry trace. `diagnoseRun` folds
+ * those three sources into one `DiagnosisReport` that names the failing
+ * node/step, the error, the last `llm.chat`/`llm.stream` span at or before the
+ * failure (with tokens, model, and a truncated response), a memory snapshot, and
+ * a deterministic "likely fix locus" pointing at where to start.
+ *
+ * The function is pure and deterministic — it only reads its inputs and never
+ * touches the filesystem, env, or clock. The CLI wiring in
+ * `commands/agent.ts` gathers the real inputs and calls it. Keep all I/O out of
+ * this module so it stays unit-testable under the CLI vitest stub setup, which
+ * stubs every `@nodetool-ai/*` runtime package — only `import type` is used.
+ */
+import type { ProcessingMessage } from "@nodetool-ai/protocol";
+/** A failed run/job record, as returned by `jobs.get` (subset we read). */
+export interface DiagnoseJob {
+    id: string;
+    status?: string;
+    error?: string | null;
+    workflowId?: string | null;
+}
+/**
+ * One OpenTelemetry span, loosely typed. Structurally compatible with the debug
+ * harness `TraceSpan`, but only the fields the diagnoser reads are required so
+ * callers can pass either parsed JSONL lines or richer span objects.
+ */
+/** An OpenTelemetry attribute value, as the trace JSONL carries it. */
+export type SpanAttributeValue = string | number | boolean | null | Array<string | number | boolean | null>;
+export interface TraceSpanLite {
+    name: string;
+    span_id?: string;
+    parent_span_id?: string | null;
+    start_time_ms?: number;
+    end_time_ms?: number;
+    attributes?: Record<string, SpanAttributeValue>;
+    status?: {
+        code?: string;
+        message?: string;
+    };
+}
+/**
+ * Everything `diagnoseRun` needs. Every field is optional so the diagnoser
+ * degrades gracefully when a source is unavailable (it reports what was
+ * missing rather than crashing).
+ */
+export interface DiagnoseInputs {
+    job?: DiagnoseJob;
+    /** Processing messages from the run (e.g. a bundle's messages.jsonl). */
+    messages?: ReadonlyArray<ProcessingMessage | Record<string, unknown>>;
+    /** Trace spans (e.g. a parsed trace.jsonl). */
+    spans?: ReadonlyArray<TraceSpanLite>;
+    /** A memory/state snapshot captured at failure. */
+    memory?: Record<string, unknown>;
+}
+/** The node or step the run failed on. */
+interface FailureSite {
+    /** Where the failure was identified. */
+    kind: "node" | "step" | "job" | "unknown";
+    /** Node id, when a failing node was found. */
+    nodeId: string | null;
+    /** Node type, when known (e.g. "nodetool.text.Concatenate"). */
+    nodeType: string | null;
+    /** Node display name, when known. */
+    nodeName: string | null;
+    /** Step id, when the failure came from an agent step. */
+    stepId: string | null;
+    /** Step instructions/title, when known. */
+    stepLabel: string | null;
+}
+/** Summary of the last LLM call before the failure. */
+interface LastLlmSummary {
+    /** Span name — "llm.chat" or "llm.stream". */
+    name: string;
+    provider: string | null;
+    model: string | null;
+    inputTokens: number | null;
+    outputTokens: number | null;
+    totalTokens: number | null;
+    costUsd: number | null;
+    /** Truncated `llm.response.content` from the span attributes. */
+    responsePreview: string | null;
+    durationMs: number | null;
+    /** Span status code, when present (e.g. "ERROR"). */
+    statusCode: string | null;
+}
+/** Compact view of the memory/state snapshot at failure. */
+interface MemorySnapshot {
+    /** Number of top-level keys. */
+    keyCount: number;
+    /** Top-level keys (capped). */
+    keys: string[];
+    /** Per-key one-line value previews (capped, truncated). */
+    preview: Record<string, string>;
+}
+/** A heuristic pointer at where to start fixing. */
+interface FixLocus {
+    /** One-line, human-readable starting point. */
+    summary: string;
+    /** Failing node type, when derivable. */
+    nodeType: string | null;
+    /** Model implicated by the last LLM call, when derivable. */
+    model: string | null;
+    /** Concrete hints (prompt/model/file references) extracted from the error. */
+    hints: string[];
+}
+export interface DiagnosisReport {
+    /** True when no failure could be identified from any source. */
+    ok: boolean;
+    jobId: string | null;
+    jobStatus: string | null;
+    /** The node/step the run failed on. */
+    failure: FailureSite;
+    /** The failure message, normalized to a single string. */
+    error: string | null;
+    /** The last llm.chat/llm.stream span at or before the failure. */
+    lastLlm: LastLlmSummary | null;
+    /** Memory/state snapshot summary, when a snapshot was supplied. */
+    memory: MemorySnapshot | null;
+    /** Where to start fixing. Null only when there's no failure. */
+    fixLocus: FixLocus | null;
+    /** Sources that were absent — surfaced so callers see partial coverage. */
+    missing: string[];
+}
+/**
+ * Aggregate a failed run's job record, message stream, and trace spans into a
+ * single `DiagnosisReport`. Deterministic and side-effect-free.
+ */
+export declare function diagnoseRun(inputs: DiagnoseInputs): DiagnosisReport;
+/**
+ * Render a `DiagnosisReport` as a plain-text block for the terminal. Kept here
+ * (not in the CLI command) so the formatting is unit-testable and dependency-
+ * free; the command adds color separately if desired.
+ */
+export declare function renderDiagnosis(report: DiagnosisReport): string;
+export {};
+//# sourceMappingURL=diagnose.d.ts.map

package/dist/diagnose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnose.d.ts","sourceRoot":"","sources":["../src/diagnose.ts"],"names":[],"mappings":"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"}

package/dist/diagnose.js

@@ -0,0 +1,418 @@
+/**
+ * Pure failure-diagnosis aggregator for `nodetool agent diagnose <job_id>`.
+ *
+ * When a run fails the cause is scattered across the job record, the structured
+ * processing-message stream, and the OpenTelemetry trace. `diagnoseRun` folds
+ * those three sources into one `DiagnosisReport` that names the failing
+ * node/step, the error, the last `llm.chat`/`llm.stream` span at or before the
+ * failure (with tokens, model, and a truncated response), a memory snapshot, and
+ * a deterministic "likely fix locus" pointing at where to start.
+ *
+ * The function is pure and deterministic — it only reads its inputs and never
+ * touches the filesystem, env, or clock. The CLI wiring in
+ * `commands/agent.ts` gathers the real inputs and calls it. Keep all I/O out of
+ * this module so it stays unit-testable under the CLI vitest stub setup, which
+ * stubs every `@nodetool-ai/*` runtime package — only `import type` is used.
+ */
+import { isFiniteNumber, isObjectLike, isString } from "./predicates.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const RESPONSE_PREVIEW_MAX = 500;
+const VALUE_PREVIEW_MAX = 120;
+const MEMORY_KEY_LIMIT = 40;
+const FAILED_NODE_STATUSES = new Set(["error", "failed"]);
+/** Job statuses that mean the run did not succeed. */
+const FAILED_JOB_STATUSES = new Set(["failed", "error", "cancelled"]);
+const LLM_SPAN_NAMES = new Set(["llm.chat", "llm.stream"]);
+function str(v) {
+    return isString(v) ? v : null;
+}
+function num(v) {
+    return isFiniteNumber(v) ? v : null;
+}
+function truncate(s, max) {
+    const oneLine = s.replace(/\s+/g, " ").trim();
+    return oneLine.length > max ? `${oneLine.slice(0, max)}…[${oneLine.length} chars]` : oneLine;
+}
+/** First non-empty string among the candidates. */
+function firstString(...candidates) {
+    for (const c of candidates) {
+        const s = str(c);
+        if (s && s.trim().length > 0)
+            return s;
+    }
+    return null;
+}
+const NO_SITE = {
+    kind: "unknown",
+    nodeId: null,
+    nodeType: null,
+    nodeName: null,
+    stepId: null,
+    stepLabel: null
+};
+/**
+ * Scan the message stream for the first failure. A failing `node_update`
+ * (status error/failed) wins; otherwise a failed `task_update`/`step_result`
+ * (an agent step); otherwise a top-level `error` message. The scan keeps the
+ * earliest failure so the report points at the root cause, not a downstream
+ * cascade.
+ */
+function scanMessages(messages) {
+    let nodeFailure = null;
+    let nodeError = null;
+    let stepFailure = null;
+    let stepError = null;
+    let topError = null;
+    let jobError = null;
+    for (const raw of messages) {
+        const msg = raw;
+        switch (msg.type) {
+            case "node_update": {
+                const status = str(msg.status);
+                if (status && FAILED_NODE_STATUSES.has(status) && !nodeFailure) {
+                    nodeFailure = {
+                        kind: "node",
+                        nodeId: str(msg.node_id),
+                        nodeType: str(msg.node_type),
+                        nodeName: str(msg.node_name),
+                        stepId: null,
+                        stepLabel: null
+                    };
+                    nodeError = firstString(msg.error) ?? status;
+                }
+                break;
+            }
+            case "task_update": {
+                const event = str(msg.event);
+                const task = msg.task ?? {};
+                const step = msg.step ?? {};
+                const failed = event === "step_failed" ||
+                    str(step.status) === "failed" ||
+                    str(task.status) === "failed";
+                if (failed && !stepFailure) {
+                    stepFailure = {
+                        kind: "step",
+                        nodeId: str(msg.node_id),
+                        nodeType: null,
+                        nodeName: firstString(task.title, task.name),
+                        stepId: firstString(step.id),
+                        stepLabel: firstString(step.instructions, step.name, task.title)
+                    };
+                    stepError = firstString(step.error, task.error);
+                }
+                break;
+            }
+            case "step_result": {
+                const stepErr = firstString(msg.error);
+                if (stepErr && !stepFailure) {
+                    const step = msg.step ?? {};
+                    stepFailure = {
+                        kind: "step",
+                        nodeId: null,
+                        nodeType: null,
+                        nodeName: null,
+                        stepId: firstString(step.id),
+                        stepLabel: firstString(step.instructions, step.name)
+                    };
+                    stepError = stepErr;
+                }
+                break;
+            }
+            case "job_update": {
+                const status = str(msg.status);
+                if (status && FAILED_JOB_STATUSES.has(status)) {
+                    jobError ??= firstString(msg.error, msg.message);
+                }
+                break;
+            }
+            case "error": {
+                topError ??= firstString(msg.message);
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    // Precedence: a failing node is the most specific locus, then an agent step,
+    // then a job/top-level error with no attributable node.
+    if (nodeFailure) {
+        return {
+            failure: nodeFailure,
+            error: nodeError ?? stepError ?? topError ?? jobError,
+            failedAtMs: null,
+            found: true
+        };
+    }
+    if (stepFailure) {
+        return {
+            failure: stepFailure,
+            error: stepError ?? topError ?? jobError,
+            failedAtMs: null,
+            found: true
+        };
+    }
+    const looseError = topError ?? jobError;
+    if (looseError) {
+        return {
+            failure: { ...NO_SITE, kind: "job" },
+            error: looseError,
+            failedAtMs: null,
+            found: true
+        };
+    }
+    return { failure: NO_SITE, error: null, failedAtMs: null, found: false };
+}
+// ---------------------------------------------------------------------------
+// Last LLM span at/before the failure
+// ---------------------------------------------------------------------------
+function spanAttr(span, key) {
+    return span.attributes ? span.attributes[key] : undefined;
+}
+/**
+ * Pick the last `llm.chat`/`llm.stream` span that started at or before the
+ * failure. When no failure time is known, the last LLM span in trace order is
+ * used. Ties on start time resolve to the later end time (and otherwise the
+ * later position in the array), so the most recent call wins deterministically.
+ */
+function selectLastLlmSpan(spans, failedAtMs) {
+    let best = null;
+    let bestStart = Number.NEGATIVE_INFINITY;
+    let bestEnd = Number.NEGATIVE_INFINITY;
+    for (const span of spans) {
+        if (!LLM_SPAN_NAMES.has(span.name))
+            continue;
+        const start = num(span.start_time_ms);
+        if (failedAtMs !== null && start !== null && start > failedAtMs)
+            continue;
+        const startKey = start ?? Number.NEGATIVE_INFINITY;
+        const endKey = num(span.end_time_ms) ?? startKey;
+        // `>=` so a later array position with an equal key still wins (trace order).
+        if (best === null || startKey > bestStart || (startKey === bestStart && endKey >= bestEnd)) {
+            best = span;
+            bestStart = startKey;
+            bestEnd = endKey;
+        }
+    }
+    return best;
+}
+function summarizeLlmSpan(span) {
+    const provider = firstString(spanAttr(span, "gen_ai.system"), spanAttr(span, "agent.provider")) ?? null;
+    const model = firstString(spanAttr(span, "gen_ai.request.model"), spanAttr(span, "gen_ai.response.model"), spanAttr(span, "agent.model")) ?? null;
+    const responseRaw = str(spanAttr(span, "llm.response.content"));
+    const start = num(span.start_time_ms);
+    const end = num(span.end_time_ms);
+    return {
+        name: span.name,
+        provider,
+        model,
+        inputTokens: num(spanAttr(span, "gen_ai.usage.input_tokens")),
+        outputTokens: num(spanAttr(span, "gen_ai.usage.output_tokens")),
+        totalTokens: num(spanAttr(span, "gen_ai.usage.total_tokens")),
+        costUsd: num(spanAttr(span, "gen_ai.usage.cost_usd")),
+        responsePreview: responseRaw ? truncate(responseRaw, RESPONSE_PREVIEW_MAX) : null,
+        durationMs: start !== null && end !== null ? end - start : null,
+        statusCode: span.status?.code ?? null
+    };
+}
+// ---------------------------------------------------------------------------
+// Memory snapshot
+// ---------------------------------------------------------------------------
+function summarizeMemory(memory) {
+    const keys = Object.keys(memory);
+    const shown = keys.slice(0, MEMORY_KEY_LIMIT);
+    const preview = {};
+    for (const k of shown) {
+        const v = memory[k];
+        let s;
+        if (isString(v))
+            s = v;
+        else if (v === null || v === undefined)
+            s = String(v);
+        else if (isObjectLike(v))
+            s = Array.isArray(v) ? `array(${v.length})` : "{…}";
+        else
+            s = String(v);
+        preview[k] = truncate(s, VALUE_PREVIEW_MAX);
+    }
+    return { keyCount: keys.length, keys: shown, preview };
+}
+// ---------------------------------------------------------------------------
+// Fix locus heuristic
+// ---------------------------------------------------------------------------
+/** Extract concrete file/prompt/model hints from an error string. */
+function extractHints(error, model) {
+    const hints = [];
+    if (!error)
+        return hints;
+    const lower = error.toLowerCase();
+    // File path references (./foo.ts, /abs/path, src/x.json).
+    const fileMatch = error.match(/(?:\.{0,2}\/)?[\w.-]+\/[\w./-]+\.\w+/);
+    if (fileMatch)
+        hints.push(`file: ${fileMatch[0]}`);
+    if (/\bprompt\b/.test(lower) || /system\s*prompt/.test(lower)) {
+        hints.push("prompt: review the node/agent prompt");
+    }
+    if (/\bmodel\b/.test(lower) || /\bcontext\s*length\b/.test(lower) || /\btoken/.test(lower)) {
+        hints.push(model ? `model: ${model}` : "model: check the model id/limits");
+    }
+    if (/\bapi[\s_-]?key\b/.test(lower) || /unauthorized|401|forbidden|403/.test(lower)) {
+        hints.push("auth: missing/invalid API key or permissions");
+    }
+    if (/timeout|timed out|etimedout/.test(lower)) {
+        hints.push("timeout: increase the run/request timeout or retry");
+    }
+    if (/rate.?limit|429/.test(lower)) {
+        hints.push("rate-limit: back off or lower concurrency");
+    }
+    return hints;
+}
+function buildFixLocus(failure, error, lastLlm) {
+    const model = lastLlm?.model ?? null;
+    const hints = extractHints(error, model);
+    const where = failure.kind === "node"
+        ? `node ${failure.nodeName ?? failure.nodeId ?? "?"}` +
+            (failure.nodeType ? ` (${failure.nodeType})` : "")
+        : failure.kind === "step"
+            ? `agent step ${failure.stepLabel ?? failure.stepId ?? "?"}`
+            : failure.kind === "job"
+                ? "the job (no node attributed)"
+                : "the run";
+    const errPart = error ? ` — ${truncate(error, 160)}` : "";
+    const summary = `Start at ${where}${errPart}`;
+    return {
+        summary,
+        nodeType: failure.nodeType,
+        model,
+        hints
+    };
+}
+// ---------------------------------------------------------------------------
+// diagnoseRun
+// ---------------------------------------------------------------------------
+/**
+ * Aggregate a failed run's job record, message stream, and trace spans into a
+ * single `DiagnosisReport`. Deterministic and side-effect-free.
+ */
+export function diagnoseRun(inputs) {
+    const { job, messages, spans, memory } = inputs;
+    const missing = [];
+    // ---- Failure site + error -------------------------------------------------
+    let findings = { failure: NO_SITE, error: null, failedAtMs: null, found: false };
+    if (messages && messages.length > 0) {
+        findings = scanMessages(messages);
+    }
+    else {
+        missing.push("messages");
+    }
+    // The job record can supply (or override-fill) the error and status even when
+    // the message stream named the failing node.
+    const jobStatus = job?.status ?? null;
+    const jobError = firstString(job?.error);
+    const jobFailed = jobStatus ? FAILED_JOB_STATUSES.has(jobStatus) : false;
+    let { failure, error } = findings;
+    let found = findings.found;
+    if (!found && (jobFailed || jobError)) {
+        failure = { ...NO_SITE, kind: "job" };
+        error = jobError;
+        found = true;
+    }
+    else if (found && !error && jobError) {
+        error = jobError;
+    }
+    if (!job)
+        missing.push("job");
+    // ---- Last LLM span --------------------------------------------------------
+    let lastLlm = null;
+    if (spans && spans.length > 0) {
+        const span = selectLastLlmSpan(spans, findings.failedAtMs);
+        if (span)
+            lastLlm = summarizeLlmSpan(span);
+        else
+            missing.push("llm-span");
+    }
+    else {
+        missing.push("trace");
+    }
+    // ---- Memory snapshot ------------------------------------------------------
+    let memorySnapshot = null;
+    if (memory && Object.keys(memory).length > 0) {
+        memorySnapshot = summarizeMemory(memory);
+    }
+    else {
+        missing.push("memory");
+    }
+    // ---- Verdict --------------------------------------------------------------
+    const ok = !found;
+    const fixLocus = ok ? null : buildFixLocus(failure, error, lastLlm);
+    return {
+        ok,
+        jobId: job?.id ?? null,
+        jobStatus,
+        failure: ok ? NO_SITE : failure,
+        error: ok ? null : error,
+        lastLlm,
+        memory: memorySnapshot,
+        fixLocus,
+        missing
+    };
+}
+// ---------------------------------------------------------------------------
+// Human-readable rendering
+// ---------------------------------------------------------------------------
+/**
+ * Render a `DiagnosisReport` as a plain-text block for the terminal. Kept here
+ * (not in the CLI command) so the formatting is unit-testable and dependency-
+ * free; the command adds color separately if desired.
+ */
+export function renderDiagnosis(report) {
+    const lines = [];
+    const id = report.jobId ?? "(unknown job)";
+    if (report.ok) {
+        lines.push(`✓ No failure detected for ${id}.`);
+        if (report.jobStatus)
+            lines.push(`  status: ${report.jobStatus}`);
+        if (report.missing.length > 0) {
+            lines.push(`  sources missing: ${report.missing.join(", ")}`);
+        }
+        return lines.join("\n");
+    }
+    lines.push(`✗ Diagnosis for ${id}${report.jobStatus ? ` (${report.jobStatus})` : ""}`);
+    const f = report.failure;
+    const site = f.kind === "node"
+        ? `node ${f.nodeName ?? f.nodeId ?? "?"}${f.nodeType ? ` [${f.nodeType}]` : ""}`
+        : f.kind === "step"
+            ? `step ${f.stepLabel ?? f.stepId ?? "?"}`
+            : f.kind === "job"
+                ? "job (no node attributed)"
+                : "unknown";
+    lines.push(`  failure: ${site}`);
+    lines.push(`  error:   ${report.error ?? "(none reported)"}`);
+    if (report.lastLlm) {
+        const l = report.lastLlm;
+        const tok = l.inputTokens !== null || l.outputTokens !== null
+            ? ` tokens=${l.inputTokens ?? "?"}/${l.outputTokens ?? "?"}`
+            : "";
+        lines.push(`  last LLM (${l.name}): ${l.provider ?? "?"}/${l.model ?? "?"}${tok}` +
+            (l.statusCode ? ` status=${l.statusCode}` : ""));
+        if (l.responsePreview)
+            lines.push(`    response: ${l.responsePreview}`);
+    }
+    else {
+        lines.push("  last LLM: (no trace span available)");
+    }
+    if (report.memory) {
+        lines.push(`  memory: ${report.memory.keyCount} key(s): ${report.memory.keys.join(", ")}`);
+    }
+    if (report.fixLocus) {
+        lines.push(`  → ${report.fixLocus.summary}`);
+        for (const hint of report.fixLocus.hints)
+            lines.push(`    • ${hint}`);
+    }
+    if (report.missing.length > 0) {
+        lines.push(`  sources missing: ${report.missing.join(", ")}`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=diagnose.js.map