@zenera/cli 1.1.24 → 1.1.26

package/dist/commands/inspect.d.ts

@@ -1,14 +1,64 @@
 import type { Command } from '../command.ts';
-import { type NodeDetail } from '../trace.ts';
+import { type RunPaths, type SessionPaths } from '../session.ts';
+import { type NodeDetail, type Trace, type TraceEntry } from '../trace.ts';
+interface Flags {
+    project?: string;
+    session?: string;
+    run?: string;
+    dir?: string;
+    memory?: string;
+    model?: string;
+    part?: string[];
+    'question-file'?: string;
+    full?: boolean;
+    raw?: boolean;
+    open?: boolean;
+    rebuild?: boolean;
+    'no-timing'?: boolean;
+    'no-style'?: boolean;
+}
 export declare const inspect: Command;
+/** The `--part` names that match no part of any of these nodes. */
+export declare function missingParts(found: readonly NodeDetail[], want: readonly string[]): string[];
 /**
  * Which parts print in full: everything `--part` names, or everything but
- * `request`. A prefix matches, so `--part call` catches `call run_command (…)`.
+ * the bulky ones. A prefix matches, so `--part call` catches `call run_command (…)`.
+ * A name that matches nothing is an error only when no name matches at all.
  */
 export declare function wholeParts(found: readonly NodeDetail[], values: {
     part?: string[];
     full?: boolean;
 }): (name: string) => boolean;
+/**
+ * One recorded call, put back to a model with a question on the end.
+ *
+ * `node` shows what the model was given; this asks the model what it made of
+ * it. Everything it sees is what it saw at the time, so an answer naming the
+ * skill that steered it is checkable against the same node.
+ */
+export declare function replayableCalls(trace: Trace): {
+    entry: TraceEntry;
+    node: import("@zenera/neo").LlmCallNode;
+}[];
+export declare function renderAskExchange(question: string, answer: string, columns?: number): string[];
+export declare function repeatQuestions(initial: string, next: () => Promise<string>, answer: (question: string) => Promise<void>): Promise<void>;
+/** The question: the words on the line, or the whole of `--question-file` (`-` is stdin). */
+export declare function readQuestion(words: readonly string[], file: string | undefined, cwd: string): Promise<string>;
 /** One node, framed so a payload cannot be mistaken for the next node. */
 export declare function renderNode(node: NodeDetail, whole?: (name: string) => boolean): string;
+export interface Located {
+    project: string;
+    session: SessionPaths;
+    run: RunPaths;
+}
+/**
+ * Which run, by whichever handle the caller has.
+ *
+ * A directory is the handle a *program* holds: `zen run --json` reports one,
+ * and asking it to be taken apart into a project, a session and a run before
+ * it can be used again would be work for nothing. A person holds an id, or
+ * nothing at all and gets asked.
+ */
+export declare function locate(cwd: string, values: Pick<Flags, 'project' | 'session' | 'run' | 'dir'>, positional: string | undefined, asking: boolean): Promise<Located>;
+export {};
 //# sourceMappingURL=inspect.d.ts.map

package/dist/commands/inspect.js

@@ -1,8 +1,9 @@
-import { assertState, buildRunReport, FilePayloadStore, memoryDir, MemoryStore, PayloadResolver, projectRegistry, readProjectConfig, renderReportHtml, } from '@zenera/neo';
+import { assertState, buildRunReport, FilePayloadStore, memoryDir, MemoryStore, PayloadResolver, projectRegistry, readProjectConfig, renderReportHtml, SANDBOX_MOUNT, text, } from '@zenera/neo';
 import { spawn } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { readFile, writeFile } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
 import { parse } from "../args.js";
 import { buildDiagnostic, parseRecordedRequest, pickModel } from "../ask.js";
 import { loadProjectEnv } from "../env.js";
@@ -11,7 +12,10 @@ import { sessionIds } from "../projects.js";
 import { project as resolveProject } from "../resolve.js";
 import { display, listRuns, listSessions, newestRun, readRunMeta, requireSession, runPaths, runPathsAt, sessionPaths, } from "../session.js";
 import { nodeDetail, parseNodeIds, traceIndex, traceMermaid, traceOf, } from "../trace.js";
-import { ago, bold, bytes, choose, cyan, dim, invalidError, isInteractive, json, note, usageError, write, writeAll, yellow, } from "../term.js";
+import { formatMarkdown } from "../tui/markdown.js";
+import { boxWidth } from "../tui/wrap.js";
+import { ago, bold, bytes, choose, cyan, dim, invalidError, isInteractive, json, note, pad, ask as prompt, readStdin, usageError, write, writeAll, yellow, } from "../term.js";
+import { appendUsage } from "../usage.js";
 const USAGE = 'zen inspect [report|graph|node|ask] [run] [--dir <run dir>] [--open]';
 const SUBCOMMANDS = ['report', 'graph', 'node', 'ask'];
 // ---------------------------------------------------------------------------
@@ -44,7 +48,8 @@ export const inspect = {
         '  report                 Build and print the path to report.html. Default.',
         '  graph                  The whole run as one Mermaid flowchart, on stdout.',
         '  node <id...>           Those nodes of the graph in full. Ranges: n5..n9.',
-        '  ask <id> <question>    Put a question to the model that made that call.',
+        '  ask <id> <question>    One answer on stdout, then exit. Never prompts.',
+        '  ask [<id>]             A conversation at a terminal. Prompts for the rest.',
         '',
         '  --project <name|dir>   Which project. Defaults to the one you are in.',
         '  --session <id>         Which session. Defaults to the newest that ran.',
@@ -52,15 +57,17 @@ export const inspect = {
         '  --dir <dir>            A run directory, as `zen run --json` reports it.',
         '  --memory <dir>         Read this memory instead of the project’s.',
         '  --model <ref>          Answer `ask` with this model instead of the run’s.',
+        '  --question-file <path> Read the `ask` question from a file; `-` is stdin.',
         '  --part <name>          Print this part of a node in full. Repeatable.',
         '  --full                 Print every part, the recorded `request` included.',
+        '  --raw                  With one node and one --part: that part alone, unframed.',
         '  --rebuild              Build report.html again from the run state.',
         '  --open                 Open the report in a browser.',
         '  --no-timing            Leave the clock off the graph.',
         '  --no-style             Leave the colours off the graph. Shorter to read.',
         '',
-        'With no arguments: asks which session and run, or takes the newest of',
-        'each when there is nothing to ask on.',
+        'With no run named, report, graph and node ask which session and run at',
+        'a terminal, and take the newest of each when there is nothing to ask on.',
         '',
         '`graph` is written to be read by a model. Nodes are declared in the',
         'order they happened, with ids `n1`, `n2`, …; every edge is collected in',
@@ -79,12 +86,38 @@ export const inspect = {
         '',
         '  zen inspect node n11 --part thinking --part text --dir <run dir>',
         '',
+        'An `llm_call` also carries two parts read out of its request, printed',
+        'only when named: `tools`, the tool names that call was offered, and',
+        '`messages`, the conversation it saw, one clipped line per message.',
+        '`--raw` prints one part with nothing around it, for a pipe:',
+        '',
+        '  zen inspect node n11 --part tools --dir <run dir>',
+        "  zen inspect node n11 --part request --raw --dir <run dir> | jq '.messages'",
+        '',
         '`ask` replays one `llm_call` — its system prompt, its messages, its tool',
         'schemas — to a model, with your question on the end and tool calling off.',
         'It is told the run is over and that it may quote its own instructions, so',
-        'the answer names the prompt or skill behind the behaviour:',
+        'the answer names the prompt or skill behind the behaviour. It has two',
+        'modes, and which one is decided by whether the question is given:',
+        '',
+        'One-shot — a question on the line, in --question-file, or --json. For a',
+        'script or a model: no banner, no prompt, no picker; stdout is the answer',
+        'and nothing else. Name the run with --dir, --run or --session, or the',
+        'newest is taken.',
         '',
         '  zen inspect ask n11 "why run python -c when the skill says npm test?"',
+        '  zen inspect ask n11 --question-file q.md --dir <run dir>',
+        '',
+        'A question with quotes, backticks or several lines goes in a file, so no',
+        'shell ever parses it.',
+        '',
+        'Interactive — no question. For a person at a terminal: asks for whatever',
+        'is not named (session, run, LLM call), then the question, and keeps the',
+        'conversation going until an empty question. Without a terminal it is an',
+        'error, never a wait.',
+        '',
+        '  zen inspect ask',
+        '  zen inspect ask n11 --dir <run dir>',
         '',
         'All of it, at length: .github/skills/zen-cli/references/inspect.md',
     ],
@@ -97,7 +130,9 @@ export const inspect = {
             memory: { type: 'string' },
             model: { type: 'string' },
             part: { type: 'string', multiple: true },
+            'question-file': { type: 'string' },
             full: { type: 'boolean' },
+            raw: { type: 'boolean' },
             open: { type: 'boolean' },
             rebuild: { type: 'boolean' },
             'no-timing': { type: 'boolean' },
@@ -117,8 +152,13 @@ export const inspect = {
             return await nodes(at, values, rest, ctx.json);
         }
         if (what === 'ask') {
-            const at = await locate(ctx.cwd, values, undefined, asking);
-            return await ask(at, values, rest, ctx.json);
+            // Given a question it is one-shot; only a bare `ask` converses.
+            const oneShot = ctx.json || values['question-file'] !== undefined || rest.length > 1;
+            if (!oneShot && !(asking && process.stdout.isTTY)) {
+                throw usageError('interactive `ask` needs a terminal; give the node id and a question', 'zen inspect ask n11 --question-file q.md --dir <run dir>');
+            }
+            const at = await locate(ctx.cwd, values, undefined, !oneShot);
+            return await ask(at, values, rest, ctx.cwd, ctx.json, !oneShot);
         }
         const at = await locate(ctx.cwd, values, rest[0], asking);
         if (what === 'graph') {
@@ -209,18 +249,42 @@ async function nodes(at, values, ids, asJson) {
         return;
     }
     const whole = wholeParts(found, values);
-    writeAll(preamble(run.id, found, whole, trace.entries.length));
+    if (values.raw) {
+        const [node] = found;
+        const hits = node?.parts.filter((p) => whole(p.name)) ?? [];
+        if (found.length !== 1 || values.part?.length !== 1 || hits.length !== 1) {
+            throw usageError('--raw prints one part of one node', hits.length > 1
+                ? `name one: ${hits.map((p) => `--part ${flag(p.name)}`).join(', ')}`
+                : 'zen inspect node n11 --part request --raw --dir <run dir>');
+        }
+        const { text } = hits[0];
+        process.stdout.write(text.endsWith('\n') ? text : `${text}\n`);
+        return;
+    }
+    writeAll([
+        ...preamble(run.id, found, whole, trace.entries.length),
+        ...missingParts(found, values.part ?? []).map((name) => `# no part starts with "${name}" in these nodes`),
+    ]);
     for (const node of found) {
         write(renderNode(node, whole));
     }
-    note(dim(`the rest of the run: ${cyan(`zen inspect graph --dir ${run.dir}`)}`));
-    note(dim(`why it did this: ${cyan(`zen inspect ask ${found[0]?.id ?? 'n1'} "…" --dir ${run.dir}`)}`));
+    // A model reading this already has the commands; only a person needs reminding.
+    if (process.stderr.isTTY) {
+        note(dim(`the rest of the run: ${cyan(`zen inspect graph --dir ${run.dir}`)}`));
+        note(dim(`why it did this: ${cyan(`zen inspect ask ${found[0]?.id ?? 'n1'} "…" --dir ${run.dir}`)}`));
+    }
+}
+/** Parts `node` names with their size instead of printing, unless asked for. */
+const BULKY = new Set(['request', 'messages', 'tools']);
+/** The `--part` names that match no part of any of these nodes. */
+export function missingParts(found, want) {
+    const names = found.flatMap((n) => n.parts.map((p) => p.name));
+    return want.filter((asked) => !names.some((name) => name.startsWith(asked)));
 }
-/** The part `--part` leaves out unless it is asked for by name. */
-const BULKY = 'request';
 /**
  * Which parts print in full: everything `--part` names, or everything but
- * `request`. A prefix matches, so `--part call` catches `call run_command (…)`.
+ * the bulky ones. A prefix matches, so `--part call` catches `call run_command (…)`.
+ * A name that matches nothing is an error only when no name matches at all.
  */
 export function wholeParts(found, values) {
     if (values.full) {
@@ -228,13 +292,12 @@ export function wholeParts(found, values) {
     }
     const want = values.part ?? [];
     if (!want.length) {
-        return (name) => name !== BULKY;
+        return (name) => !BULKY.has(name);
     }
-    const names = [...new Set(found.flatMap((n) => n.parts.map((p) => p.name)))];
-    for (const asked of want) {
-        if (!names.some((name) => name.startsWith(asked))) {
-            throw usageError(`no part starts with "${asked}" in ${found.length === 1 ? found[0]?.id : 'these nodes'}`, names.length ? `they carry: ${names.join(', ')}` : 'they carry no payloads');
-        }
+    const missing = missingParts(found, want);
+    if (missing.length === want.length) {
+        const names = [...new Set(found.flatMap((n) => n.parts.map((p) => p.name)))];
+        throw usageError(`no part starts with "${want[0]}" in ${found.length === 1 ? found[0]?.id : 'these nodes'}`, names.length ? `they carry: ${names.join(', ')}` : 'they carry no payloads');
     }
     return (name) => want.some((asked) => name.startsWith(asked));
 }
@@ -245,14 +308,82 @@ export function wholeParts(found, values) {
  * it. Everything it sees is what it saw at the time, so an answer naming the
  * skill that steered it is checkable against the same node.
  */
-async function ask(at, values, rest, asJson) {
+export function replayableCalls(trace) {
+    return trace.entries.flatMap((entry) => entry.node.type === 'llm_call' && entry.node.request ? [{ entry, node: entry.node }] : []);
+}
+const ASK_BOX = { tl: '╭', tr: '╮', bl: '╰', br: '╯', h: '─', v: '│' };
+function askPanel(title, text, outer, border) {
+    const inner = outer - 4;
+    const rule = ASK_BOX.h.repeat(Math.max(1, outer - title.length - 5));
+    return [
+        border(`${ASK_BOX.tl}${ASK_BOX.h} ${title} ${rule}${ASK_BOX.tr}`),
+        ...formatMarkdown(text, inner).map((line) => `${border(ASK_BOX.v)} ${pad(line, inner)} ${border(ASK_BOX.v)}`),
+        border(`${ASK_BOX.bl}${ASK_BOX.h.repeat(outer - 2)}${ASK_BOX.br}`),
+    ];
+}
+export function renderAskExchange(question, answer, columns = 80) {
+    const outer = boxWidth(`${question}\n\n${answer}`, columns);
+    return [
+        '',
+        ...askPanel('Question', question, outer, cyan),
+        '',
+        ...askPanel('Answer', answer, outer, dim),
+        '',
+    ];
+}
+export async function repeatQuestions(initial, next, answer) {
+    let question = initial;
+    while (question) {
+        await answer(question);
+        question = (await next()).trim();
+    }
+}
+/** The question: the words on the line, or the whole of `--question-file` (`-` is stdin). */
+export async function readQuestion(words, file, cwd) {
+    const typed = words.join(' ').trim();
+    if (file === undefined) {
+        return typed;
+    }
+    if (typed) {
+        throw usageError('give the question either as words or as --question-file, not both', 'zen inspect ask n11 --question-file q.md');
+    }
+    if (file === '-') {
+        return (await readStdin()) ?? '';
+    }
+    try {
+        return (await readFile(resolve(cwd, file), 'utf8')).trim();
+    }
+    catch (err) {
+        throw invalidError(`cannot read question file ${file}: ${err.code ?? err}`, 'write the question to that path first');
+    }
+}
+async function ask(at, values, rest, cwd, asJson, interactive) {
     const { project, session, run } = at;
-    const [id, ...words] = rest;
-    const query = words.join(' ').trim();
-    if (!id || !query) {
+    const trace = traceOf(await readState(run));
+    let [id, ...words] = rest;
+    if (!id && interactive) {
+        const calls = replayableCalls(trace);
+        if (calls.length === 0) {
+            throw invalidError(`run ${run.id} has no recorded LLM call to replay`, 'only runs that record requests can be asked about');
+        }
+        const entry = await choose('Which LLM call?', calls.map((candidate) => ({
+            label: `${candidate.entry.key} ${candidate.node.model}`,
+            detail: [
+                candidate.node.agent,
+                candidate.node.toolCalls.length
+                    ? `calls ${candidate.node.toolCalls.map((call) => call.name).join(', ')}`
+                    : '',
+                candidate.entry.branch ? `branch ${candidate.entry.branch}` : '',
+            ]
+                .filter(Boolean)
+                .join('  '),
+            value: candidate.entry,
+        })));
+        id = entry.key;
+    }
+    if (!id) {
         throw usageError('ask takes one node id and a question', 'zen inspect ask n11 "why did you run python -c instead of the tests?"');
     }
-    const trace = traceOf(await readState(run));
     let wanted;
     try {
         wanted = parseNodeIds([id], trace.byKey);
@@ -272,6 +403,15 @@ async function ask(at, values, rest, asJson) {
         throw invalidError(`${entry.key} did not record the request that produced it`, 'only a run made by this CLI records requests; an SDK run needs ' +
             '`runner({ recordRequests: true })`');
     }
+    const query = interactive
+        ? await prompt('Question (empty to finish)?')
+        : await readQuestion(words, values['question-file'], cwd);
+    if (!query && interactive) {
+        return;
+    }
+    if (!query) {
+        throw usageError('ask takes one node id and a question', 'zen inspect ask n11 "why did you run python -c instead of the tests?"');
+    }
     const payloads = new PayloadResolver(new FilePayloadStore({ dir: session.blobs, id: 'file' }));
     // Deliberately not the preview fallback `node` uses: a truncated request is
     // not the call that happened, and an answer about it would be about nothing.
@@ -292,8 +432,32 @@ async function ask(at, values, rest, asJson) {
             'a second opinion, not the model looking at itself'));
     }
     const model = projectRegistry(config).model(picked.ref);
-    const res = await model.generate(buildDiagnostic({ request: recorded, answer, toolCalls, query }));
+    const record = async (call) => {
+        const startedAt = new Date();
+        const res = await call();
+        appendUsage(project, {
+            kind: 'ask',
+            ts: new Date().toISOString(),
+            runDir: run.dir,
+            node: entry.key,
+            nodeAgent: node.agent,
+            nodeModel: node.model,
+            model: picked.label,
+            usage: res.usage,
+            startedAt: startedAt.toISOString(),
+            durationMs: Date.now() - startedAt.getTime(),
+        });
+        return res;
+    };
+    const generate = (question) => record(() => model.generate(buildDiagnostic({ request: recorded, answer, toolCalls, query: question })));
+    const usage = (res) => {
+        note(dim(`${bold(entry.key)} ${picked.label}` +
+            (res.usage
+                ? ` · ${res.usage.inputTokens} in, ${res.usage.outputTokens} out`
+                : '')));
+    };
     if (asJson) {
+        const res = await generate(query);
         json({
             session: session.id,
             run: run.id,
@@ -306,9 +470,28 @@ async function ask(at, values, rest, asJson) {
         });
         return;
     }
-    write(res.text);
-    note(dim(`${bold(entry.key)} ${picked.label}` +
-        (res.usage ? ` · ${res.usage.inputTokens} in, ${res.usage.outputTokens} out` : '')));
+    if (!interactive) {
+        write((await generate(query)).text);
+        return;
+    }
+    let conversation;
+    await repeatQuestions(query, () => prompt('Question (empty to finish)?'), async (question) => {
+        if (!conversation) {
+            conversation = buildDiagnostic({
+                request: recorded,
+                answer,
+                toolCalls,
+                query: question,
+            });
+        }
+        else {
+            conversation.messages.push({ role: 'user', content: [text(question)] });
+        }
+        const res = await record(() => model.generate(conversation));
+        conversation.messages.push({ role: 'assistant', content: res.text });
+        writeAll(renderAskExchange(question, res.text, process.stdout.columns ?? 80));
+        usage(res);
+    });
 }
 /**
  * A part name as it can be typed back. The tool-call parts are named
@@ -371,7 +554,7 @@ export function renderNode(node, whole = () => true) {
  * it can be used again would be work for nothing. A person holds an id, or
  * nothing at all and gets asked.
  */
-async function locate(cwd, values, positional, asking) {
+export async function locate(cwd, values, positional, asking) {
     // A run id is a stamp and never has a separator in it, so a positional
     // with one is unambiguously a path.
     const asPath = positional?.includes('/') ? positional : undefined;
@@ -469,7 +652,13 @@ async function pickRun(session, asked, asking) {
 async function rebuild(session, run, store) {
     const state = await readState(run);
     const payloads = new PayloadResolver(new FilePayloadStore({ dir: session.blobs, id: 'file' }));
-    const report = await buildRunReport(state, payloads, { title: run.id, memory: store });
+    const { workspace } = await readRunMeta(run);
+    const report = await buildRunReport(state, payloads, {
+        title: run.id,
+        memory: store,
+        // The run never recorded a `workdir:`, so the default name is the guess.
+        mounts: workspace ? [{ at: SANDBOX_MOUNT, href: pathToFileURL(workspace).href }] : [],
+    });
     await writeFile(run.report, renderReportHtml(report), 'utf8');
 }
 /**