@zenera/cli 1.1.24 → 1.1.26

package/dist/sandbox.d.ts

@@ -39,6 +39,8 @@ export interface SandboxInputs {
      * promise it does not keep.
      */
     env?: readonly string[];
+    /** `false` overrides every `persist:` in the config, the agents' included */
+    persist?: boolean;
 }
 export declare function buildSandbox(opts: SandboxInputs): SandboxSetup;
 /**

package/dist/sandbox.js

@@ -3,7 +3,7 @@ import { mkdirSync } from 'node:fs';
 import { basename, join } from 'node:path';
 import { resolveBuild } from "./image.js";
 import { credentials } from "./keys.js";
-import { ensurePodmanReady } from "./podman.js";
+import { assertLocks, ensurePodmanReady } from "./podman.js";
 import { warn } from "./term.js";
 // ---------------------------------------------------------------------------
 // The sandbox, as this CLI wires it
@@ -71,6 +71,7 @@ export function buildSandbox(opts) {
         ...(opts.config.sandbox ?? {}),
         ...((opts.image ?? build?.tag) ? { image: opts.image ?? build?.tag } : {}),
         ...(opts.keys === false ? { keys: false } : {}),
+        ...(opts.persist === false ? { persist: false } : {}),
     };
     const home = join(opts.session.data, 'sandbox', 'home');
     const mounts = [{ host: home, at: HOME }, ...(opts.mounts ?? [])];
@@ -81,18 +82,22 @@ export function buildSandbox(opts) {
     // Skills and assets are mounted read-only, and a python script run from a
     // read-only directory fails on writing its own `__pycache__` — a confusing
     // error about a file nobody asked for.
-    const extra = { HOME, PYTHONDONTWRITEBYTECODE: '1', ...(keys?.env ?? {}) };
+    // `ZENERA_AGENT` tells a `zen` run by `run_command` that no person is there.
+    const extra = { HOME, PYTHONDONTWRITEBYTECODE: '1', ZENERA_AGENT: '1', ...(keys?.env ?? {}) };
     const spec = toSpec(base, extra, secretsOf(keys?.secrets, opts.env));
     const agents = {};
     for (const agent of opts.config.agents) {
         if (agent.sandbox) {
             const merged = merge(base, agent.sandbox);
+            if (opts.persist === false) {
+                merged.persist = false;
+            }
             // An agent that opts out gets neither the variables nor the mount,
             // but the mount is on the pool and cannot be taken back per agent —
             // so the variable is what actually decides, and without it the file
             // sitting there is not a credential anything will look for.
             const own = merged.keys === false ? undefined : keys;
-            agents[agent.name] = toSpec(merged, { HOME, PYTHONDONTWRITEBYTECODE: '1', ...(own?.env ?? {}) }, own && secretsOf(own.secrets, opts.env));
+            agents[agent.name] = toSpec(merged, { HOME, PYTHONDONTWRITEBYTECODE: '1', ZENERA_AGENT: '1', ...(own?.env ?? {}) }, own && secretsOf(own.secrets, opts.env));
         }
     }
     const pool = new SandboxPool({
@@ -201,6 +206,8 @@ export async function preflight(setup, yes) {
         memory: setup.spec.memory,
         yes,
     });
+    // A resumed session restarts its own stopped container, which needs no lock.
+    await assertLocks(1, { reuses: setup.pool.for().name });
     READY.add(setup.image);
 }
 /** Best-effort teardown: losing a container must never lose a run. */

package/dist/scaffold.d.ts

@@ -1,3 +1,4 @@
+export declare const TEMPLATES: string;
 /**
  * The project files that are ours rather than the project's.
  *
@@ -19,18 +20,24 @@ export declare const SHARED_RULES: readonly string[];
  * scaffold wrote, rather than a second definition of "this version".
  */
 export declare function ownVersion(): string;
+type Vars = Record<string, string>;
+export interface CopyOptions {
+    /** values for the `{{...}}` in any template under this tree */
+    vars?: Vars;
+    /** leave a file that is already there alone rather than replacing it */
+    keep?: boolean;
+}
 /**
- * Writes the editor's files under `dir`, replacing what is there. They are
- * ours: they say how the editor is to treat a directory the agents write into,
- * and they describe the file formats of the version of `zen` in hand, so the
- * current answer is the only one worth having and a stale one is worse than
- * none. Returns the relative paths written.
+ * Copies one template directory into `dir` at `rel`, depth first, sorted so the
+ * list it returns is the same on every machine. Only a `.tmpl` is read as text;
+ * everything else is copied byte for byte. A file already holding those bytes
+ * is left alone and not listed.
  */
-export declare function editorFiles(dir: string): string[];
+export declare function copyTree(from: string, dir: string, rel: string, opts: CopyOptions): string[];
 /**
  * Replaces every file in a project that nobody is meant to be maintaining:
  * `SHARED_RULES` in the project tree, and the editor tree whole. Returns the
- * relative paths written, project files first.
+ * relative paths that actually changed, project files first.
  *
  * This is the other half of `keep: true`. A scaffold never overwrites, which is
  * right for the files a project goes on to make its own and wrong for the ones
@@ -83,4 +90,5 @@ export interface Scaffolded {
  * the first set under twice as many lines about the second.
  */
 export declare function scaffold(opts: ScaffoldOptions): Scaffolded;
+export {};
 //# sourceMappingURL=scaffold.d.ts.map

package/dist/scaffold.js

@@ -1,6 +1,7 @@
-import { chmodSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from 'node:fs';
 import { dirname, join, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { editorFiles } from "./meta/editor.js";
 // ---------------------------------------------------------------------------
 // Scaffolding
 //
@@ -18,7 +19,6 @@ import { fileURLToPath } from 'node:url';
 //
 // The trees are copied whole and nothing enumerates them, so adding a file to
 // a new project is adding a file to `templates/project/` and nothing else.
-// `MEMORY_RULES` is the single exception, and it is named below.
 //
 // What is there is deliberately close to empty: a template full of
 // commented-out options is a template nobody reads and everybody deletes. The
@@ -30,7 +30,7 @@ import { fileURLToPath } from 'node:url';
 // standing next to the files that implement it, which is the shape every
 // change to the project is then made in.
 // ---------------------------------------------------------------------------
-const TEMPLATES = fileURLToPath(new URL('../templates', import.meta.url));
+export const TEMPLATES = fileURLToPath(new URL('../templates', import.meta.url));
 /** The suffix on a file with `{{...}}` in it, dropped when the file lands. */
 const TEMPLATE = '.tmpl';
 /** How to use file tools: a house rules file, landing under `agents/`. */
@@ -54,8 +54,6 @@ const FORK_RULES = join('agents', 'fork-instructions.md');
  * own beside them.
  */
 export const SHARED_RULES = [FILE_RULES, FORK_RULES, MEMORY_RULES, TOOL_RULES];
-/** The same bytes, kept in the `zen-memory` skill to restore or diff against. */
-const MEMORY_REFERENCE = join('.github', 'skills', 'zen-memory', 'references', 'memory-instructions.md');
 /**
  * This `zen`'s own version, which the scaffold pins the sandbox's tools to.
  * The publishable packages move in lockstep, so one number covers them all.
@@ -144,12 +142,22 @@ function target(name) {
     }
     return DOTFILES[name] ?? name;
 }
+/** Writes `body` to `path` unless those are already its bytes; true if it wrote. */
+function writeIfChanged(path, body) {
+    const bytes = typeof body === 'string' ? Buffer.from(body) : body;
+    if (existsSync(path) && readFileSync(path).equals(bytes)) {
+        return false;
+    }
+    writeFileSync(path, bytes);
+    return true;
+}
 /**
  * Copies one template directory into `dir` at `rel`, depth first, sorted so the
  * list it returns is the same on every machine. Only a `.tmpl` is read as text;
- * everything else is copied byte for byte.
+ * everything else is copied byte for byte. A file already holding those bytes
+ * is left alone and not listed.
  */
-function copyTree(from, dir, rel, opts) {
+export function copyTree(from, dir, rel, opts) {
     const written = [];
     mkdirSync(join(dir, rel), { recursive: true });
     const entries = readdirSync(from, { withFileTypes: true });
@@ -167,73 +175,21 @@ function copyTree(from, dir, rel, opts) {
         const body = entry.name.endsWith(TEMPLATE)
             ? render(readFileSync(source, 'utf8'), opts.vars ?? {})
             : readFileSync(source);
-        writeFileSync(join(dir, child), body);
+        const changed = writeIfChanged(join(dir, child), body);
         // The bytes are copied, not the file, so a script arrives unrunnable.
-        if (child.endsWith('.sh')) {
+        if (child.endsWith('.sh') || child.endsWith('.mjs')) {
             chmodSync(join(dir, child), 0o755);
         }
-        written.push(child);
+        if (changed) {
+            written.push(child);
+        }
     }
     return written;
 }
-// ---------------------------------------------------------------------------
-// Telling the editor which instructions are not for it
-//
-// The project's house rules are `agents/instructions.md`, deliberately not
-// `AGENTS.md`: every coding assistant now reads that name out of an open
-// folder and feeds it to itself as always-on instructions, and `zen open`
-// opens exactly this directory. A name nobody else claims means the two are
-// never confused, and `chat.useAgentsMdFile` no longer has to be switched off
-// to keep them apart.
-//
-// They sit under `agents/` because there is rarely only one of them. Anything
-// named `agents/<topic>-instructions.md` is read too, in filename order, so a
-// subject that is true for every agent but is about one capability — memory,
-// say — gets its own document instead of another section in a file that keeps
-// growing.
-//
-// `chat.useNestedAgentsMdFiles` is still written. It is already false by
-// default, but it is opt-in globally, and this is a directory the agent itself
-// writes into — someone who turned it on would otherwise have the editor pick
-// up whatever `AGENTS.md` a run happened to leave behind. It is a *restricted*
-// setting, so it applies only in a trusted workspace; that is the right way
-// round, since an untrusted folder is not one to run agents in either.
-//
-// `agents/instructions.md` addresses the *project's* agents. The editor's
-// assistant still needs a brief of its own, and what it needs to know is how
-// this kind of project is put together — the file formats, how a prompt is
-// written, when to add a skill rather than an agent. That is what the
-// `.github/` tree is: the standing brief, plus the prompt files and skills the
-// editor picks up from the same place.
-// ---------------------------------------------------------------------------
-/**
- * Writes the editor's files under `dir`, replacing what is there. They are
- * ours: they say how the editor is to treat a directory the agents write into,
- * and they describe the file formats of the version of `zen` in hand, so the
- * current answer is the only one worth having and a stale one is worse than
- * none. Returns the relative paths written.
- */
-export function editorFiles(dir) {
-    const written = copyTree(join(TEMPLATES, 'editor'), dir, '', {});
-    // The one file that belongs to both trees. It is a project file first —
-    // house rules reaching every agent that can see the graph — and it is
-    // written once and edited from then on, like every other project file. But
-    // a project whose copy drifted, or that deleted it and turned memory back
-    // on later, needs somewhere to get the current text from, and the editor
-    // tree is replaced on every `init` and `open`. Copying the same bytes into
-    // the skill's references is what makes `diff` between the two mean
-    // something, and what stops a second copy of these rules existing in the
-    // repository to fall out of step with the first.
-    const reference = join(dir, MEMORY_REFERENCE);
-    mkdirSync(dirname(reference), { recursive: true });
-    copyFileSync(join(TEMPLATES, 'project', MEMORY_RULES), reference);
-    written.push(MEMORY_REFERENCE);
-    return written;
-}
 /**
  * Replaces every file in a project that nobody is meant to be maintaining:
  * `SHARED_RULES` in the project tree, and the editor tree whole. Returns the
- * relative paths written, project files first.
+ * relative paths that actually changed, project files first.
  *
  * This is the other half of `keep: true`. A scaffold never overwrites, which is
  * right for the files a project goes on to make its own and wrong for the ones
@@ -245,8 +201,9 @@ export function refreshShared(dir) {
     for (const rel of SHARED_RULES) {
         const path = join(dir, rel);
         mkdirSync(dirname(path), { recursive: true });
-        copyFileSync(join(TEMPLATES, 'project', rel), path);
-        written.push(rel);
+        if (writeIfChanged(path, readFileSync(join(TEMPLATES, 'project', rel)))) {
+            written.push(rel);
+        }
     }
     written.push(...editorFiles(dir));
     return written;

package/dist/session.js

@@ -1,9 +1,9 @@
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { hostname } from 'node:os';
+import { claimLock, ownLock } from '@zenera/neo';
+import { existsSync, mkdirSync, rmSync } from 'node:fs';
 import { basename, dirname, join, relative, resolve } from 'node:path';
 import { readJson, writeJson } from "./home.js";
 import { isStamp, stamp, stampInstant } from "./ids.js";
-import { alive, isBusy, runIds, sessionIds, sessionsDir } from "./projects.js";
+import { isBusy, runIds, sessionIds, sessionsDir } from "./projects.js";
 import { CliError, EXIT, invalidError, usageError } from "./term.js";
 export function sessionPaths(projectDir, id) {
     if (!isStamp(id)) {
@@ -85,24 +85,7 @@ export function requireSession(projectDir, id) {
     return p;
 }
 export function acquire(p) {
-    const lock = { pid: process.pid, host: hostname(), startedAt: new Date().toISOString() };
-    const body = `${JSON.stringify(lock, null, 2)}\n`;
-    try {
-        // 'wx' fails when the file exists — the create and the check are one
-        // operation, so two `zen run`s racing cannot both win.
-        writeFileSync(p.lock, body, { flag: 'wx' });
-    }
-    catch (err) {
-        if (err.code !== 'EEXIST') {
-            throw err;
-        }
-        const held = current(p);
-        if (held && alive(held.pid) && held.host === hostname()) {
-            throw new CliError(`session ${p.id} is already running (pid ${held.pid})`, EXIT.failed, 'wait for it, or start another with --new');
-        }
-        // Stale, or from another machine's run that cannot be verified here.
-        writeFileSync(p.lock, body);
-    }
+    claimLock(p.lock, ownLock(), (held) => new CliError(`session ${p.id} is already running (pid ${held.pid})`, EXIT.failed, 'wait for it, or start another with --new'), 2);
     let released = false;
     const release = () => {
         if (released) {
@@ -113,14 +96,6 @@ export function acquire(p) {
     };
     return { release };
 }
-function current(p) {
-    try {
-        return JSON.parse(readFileSync(p.lock, 'utf8'));
-    }
-    catch {
-        return undefined;
-    }
-}
 export function runPaths(session, id) {
     if (!isStamp(id)) {
         throw usageError(`"${id}" is not a run id`);

package/dist/term.d.ts

@@ -73,6 +73,8 @@ export declare function warn(message: string): void;
 /** What this run calls itself, in the process table and on the terminal's tab. */
 export declare function title(text: string): void;
 export declare function fail(message: string, hint?: string): void;
+/** An agent's terminal can be a real pty (VS Code Copilot's is), so TTY checks alone miss it. */
+export declare function drivenByAgent(): boolean;
 export declare function isInteractive(): boolean;
 export declare function deferBanner(print: () => void): void;
 export declare function ask(question: string, fallback?: string): Promise<string>;

package/dist/term.js

@@ -230,8 +230,16 @@ export function fail(message, hint) {
 // a stdin that will never answer. A CLI that hangs in CI is worse than one that
 // fails in CI, because only one of the two tells you which flag you forgot.
 // ---------------------------------------------------------------------------
+/** An agent's terminal can be a real pty (VS Code Copilot's is), so TTY checks alone miss it. */
+export function drivenByAgent() {
+    const own = process.env['ZENERA_AGENT'];
+    if (own !== undefined) {
+        return own !== '' && own !== '0';
+    }
+    return Boolean(process.env['AI_AGENT'] || process.env['COPILOT_AGENT']);
+}
 export function isInteractive() {
-    return Boolean(process.stdin.isTTY && process.stderr.isTTY);
+    return Boolean(process.stdin.isTTY && process.stderr.isTTY) && !drivenByAgent();
 }
 // A banner is for whoever is sitting there, and the only proof that anyone is
 // sitting there is that we are about to ask them something. Commands whose
@@ -244,7 +252,8 @@ export function deferBanner(print) {
 }
 function requireTty(what, flag) {
     if (!isInteractive()) {
-        throw usageError(`cannot ask for ${what} without a terminal`, `pass ${flag} instead`);
+        const why = drivenByAgent() ? 'when an agent is running zen' : 'without a terminal';
+        throw usageError(`cannot ask for ${what} ${why}`, `pass ${flag} instead`);
     }
     const banner = pending;
     pending = undefined;

package/dist/trace.d.ts

@@ -81,4 +81,9 @@ export interface NodeDetail {
  */
 export declare function parseNodeIds(words: readonly string[], known: Map<string, unknown>): string[];
 export declare function nodeDetail(trace: Trace, ids: readonly string[], payloads: PayloadResolver): Promise<NodeDetail[]>;
+/**
+ * The two questions a recorded request is usually opened for, answered without
+ * printing it: which tools the call was offered, and what conversation it saw.
+ */
+export declare function requestParts(json: string): NodePart[];
 //# sourceMappingURL=trace.d.ts.map

package/dist/trace.js

@@ -1,4 +1,4 @@
-import { coveredIds, totalUsage, } from '@zenera/neo';
+import { contentToText, coveredIds, totalUsage, } from '@zenera/neo';
 import { format } from "./narrate.js";
 import { describeCall, summarise } from "./tui/wrap.js";
 // ---------------------------------------------------------------------------
@@ -387,6 +387,53 @@ function tally(entries) {
         .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
         .map(([name, n]) => `${safe(name, 40)} x${n}`);
 }
+const WRITES = new Set(['write_file', 'apply_patch', 'copy_file', 'move_file']);
+/**
+ * What the run did with memory, zeros included. The `tools` row only lists
+ * calls that happened, and a commit that never happened is the commonest
+ * memory finding there is: absent from a list, a reader does not see it.
+ */
+function memoryRows(entries, bound) {
+    let recalls = 0;
+    let recalled = 0;
+    let commits = 0;
+    let committed = 0;
+    let files = 0;
+    let written = 0;
+    const calls = new Map();
+    for (const { node: n } of entries) {
+        if (n.type === 'memory_recall') {
+            recalls++;
+            recalled += n.nodes.length;
+        }
+        else if (n.type === 'memory_op' && n.op === 'commit') {
+            commits++;
+            committed += n.nodes.length;
+            files += n.files;
+        }
+        else if (n.type === 'tool_call') {
+            calls.set(n.name, (calls.get(n.name) ?? 0) + 1);
+            if (WRITES.has(n.name)) {
+                written++;
+            }
+        }
+    }
+    const used = (name) => calls.get(name) ?? 0;
+    const reads = used('memory_search') + used('memory_grep') + used('memory_load');
+    if (!bound && !recalls && !reads && !commits) {
+        return [];
+    }
+    const label = bound ? '' : 'memory';
+    const lines = [
+        row(label, `recall ${recalls} (${recalled} nodes) · search ${used('memory_search')} · ` +
+            `grep ${used('memory_grep')} · load ${used('memory_load')} · ` +
+            `commit ${commits} (${committed} nodes, ${files} files)`),
+    ];
+    if (!commits && written) {
+        lines.push(row('', `nothing committed after ${written} workspace file writes`));
+    }
+    return lines;
+}
 function elapsed(entries) {
     const stamps = entries.map((e) => e.endMs).filter((t) => t !== null);
     return stamps.length < 2 ? '' : span(Math.max(...stamps) - Math.min(...stamps));
@@ -441,6 +488,7 @@ function header(state, trace, opts) {
         ...(opts.dir ? [row('dir', safe(opts.dir, 200))] : []),
         ...(opts.workspace ? [row('workspace', safe(opts.workspace, 200))] : []),
         ...(opts.memory ? [row('memory', safe(opts.memory, 200))] : []),
+        ...memoryRows(entries, Boolean(opts.memory)),
         row('agent', `${safe(state.agentName, 40)} · started as ${safe(state.spec.startAgent, 40)}`),
         row('phase', state.error ? `${state.phase} — ${safe(state.error, 200)}` : state.phase),
         row('nodes', `${entries.length} · ${kinds.get('llm_call') ?? 0} llm · ` +
@@ -473,10 +521,13 @@ function header(state, trace, opts) {
     if (hidden) {
         lines.push(row('compacted', `${hidden} nodes are marked "hidden by" a later summary`), row('', 'they still ran; the model simply stopped seeing them'));
     }
-    lines.push('%%', row('reading', 'nN is a node id · t+ counts from the start of the turn'), row('', 'dotted edges are fork/join and calls answered out of order'), row('', 'nodes are declared in run order; every edge is in one block below'), row('detail', `zen inspect node n1 n2 n5..n9${where}`), 
+    lines.push(
+    // Never a bare `%%`: Mermaid only strips a comment line with something
+    // after the marker, and leaves the rest to the parser, which rejects it.
+    '%% ---', row('reading', 'nN is a node id · t+ counts from the start of the turn'), row('', 'dotted edges are fork/join and calls answered out of order'), row('', 'nodes are declared in run order; every edge is in one block below'), row('detail', `zen inspect node n1 n2 n5..n9${where}`), 
     // Named here because this is where the question forms. A reader who has
     // just found the node they distrust will not go looking for a verb.
-    row('why', `zen inspect ask n5 "why did you do that?"${where}`), '%%');
+    row('why', `zen inspect ask n5 "why did you do that?"${where}`), '%% ---');
     return lines;
 }
 export function traceMermaid(state, opts = {}) {
@@ -668,12 +719,61 @@ export async function nodeDetail(trace, ids, payloads) {
         ts: e.node.ts,
         label: labelOf(e.node, {}),
         facts: factsOf(e.node),
-        parts: (named.get(e) ?? []).map((part) => ({
-            name: part.name,
-            text: part.literal ?? blobs.get(part.payload?.sha256 ?? '') ?? '(unresolved)',
-        })),
+        parts: (named.get(e) ?? []).flatMap((part) => {
+            const text = part.literal ?? blobs.get(part.payload?.sha256 ?? '') ?? '(unresolved)';
+            return part.name === 'request'
+                ? [{ name: part.name, text }, ...requestParts(text)]
+                : [{ name: part.name, text }];
+        }),
     }));
 }
+/** Longest a message or a tool result runs in `messages` before it is clipped. */
+const MESSAGE_CLIP = 400;
+const clip = (s, n = MESSAGE_CLIP) => {
+    const flat = s.replace(/\s+/g, ' ').trim();
+    return flat.length <= n ? flat : `${flat.slice(0, n)} … (+${flat.length - n} chars)`;
+};
+/**
+ * The two questions a recorded request is usually opened for, answered without
+ * printing it: which tools the call was offered, and what conversation it saw.
+ */
+export function requestParts(json) {
+    let req;
+    try {
+        req = JSON.parse(json);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    if (Array.isArray(req.messages)) {
+        const lines = req.messages.map((m) => {
+            switch (m.role) {
+                case 'system':
+                    return `[system] ${clip(m.content, 200)}`;
+                case 'user':
+                    return `[user] ${clip(contentToText(m.content))}`;
+                case 'assistant':
+                    return [
+                        `[assistant${m.agent ? ` @${m.agent}` : ''}] ${clip(m.content) || '(no text)'}`,
+                        ...(m.toolCalls ?? []).map((c) => `    -> ${c.name} ${clip(c.args, 300)} #${c.id}`),
+                    ].join('\n');
+                case 'tool':
+                    return `[tool ${m.name} #${m.callId}${m.isError ? ' ERROR' : ''}] ${clip(m.content)}`;
+                default:
+                    return `[${m.role ?? '?'}]`;
+            }
+        });
+        out.push({ name: 'messages', text: lines.join('\n') });
+    }
+    if (Array.isArray(req.tools)) {
+        const names = req.tools
+            .map((t) => t?.name)
+            .filter((n) => typeof n === 'string');
+        out.push({ name: 'tools', text: names.join('\n') });
+    }
+    return out;
+}
 const GONE = '(the blob is not in this session’s store; only the preview survives)';
 async function resolve(payloads, p) {
     try {

package/dist/tui/app.js

@@ -9,6 +9,7 @@ import { History } from "../history.js";
 import { format } from "../narrate.js";
 import { display } from "../session.js";
 import { CliError } from "../term.js";
+import { hostUrls, hyperlink, hyperlinks, linkBlock, mountsOf } from "./links.js";
 import { resolveTheme, THEMES } from "./theme.js";
 import { ACTIVITY_ROWS, answerWidth, blocksOf, BOX_CHROME, boxWidth, BRANCH_ROWS, branchRows, budgetOf, CHROME_ROWS, clip, describeCall, gistOf, gridOf, summarise, THINKING_ROWS, TIME_COL, unmarked, windowOf, } from "./wrap.js";
 const BANNER = { key: 'banner' };
@@ -30,6 +31,9 @@ const FRAME_MS = 100;
 // A context rather than props only because every part of the view wants it.
 const ThemeContext = React.createContext(THEMES.dark);
 const useTheme = () => useContext(ThemeContext);
+const LinksContext = React.createContext(undefined);
+/** Without hyperlinks the only way to reach the file is to print where it is. */
+const shownText = (text, links) => links && !links.osc8 ? hostUrls(text, links.mounts) : text;
 function Row({ line }) {
     const theme = useTheme();
     const style = theme.line[line.kind];
@@ -87,7 +91,10 @@ function Call({ line }) {
  */
 function Spans({ spans }) {
     const theme = useTheme();
-    return (_jsx(_Fragment, { children: spans.map((s, i) => (_jsx(Text, { bold: s.bold === true, italic: s.italic === true, underline: s.href !== undefined && s.href !== '', ...(s.code ? { color: theme.code.color } : {}), children: s.text }, i))) }));
+    const links = useContext(LinksContext);
+    return (_jsx(_Fragment, { children: spans.map((s, i) => (_jsx(Text, { bold: s.bold === true, italic: s.italic === true, underline: s.href !== undefined && s.href !== '', ...(s.code ? { color: theme.code.color } : {}), children: links?.osc8 && s.href?.startsWith('file:')
+                ? hyperlink(s.href, s.text)
+                : s.text }, i))) }));
 }
 /**
  * One block of an answer.
@@ -128,11 +135,13 @@ function BlockView({ block, gap, width, }) {
  * answer and boxing each of them turns the transcript into a stack of frames;
  * the box means *this is the answer*, and it only means that if it is rare.
  */
-function Answer({ text, boxed }) {
+function Answer({ text: said, boxed }) {
     const theme = useTheme();
+    const links = useContext(LinksContext);
     const { stdout } = useStdout();
+    const text = shownText(said, links);
     const width = boxWidth(text, stdout?.columns ?? 80);
-    const blocks = blocksOf(text);
+    const blocks = blocksOf(text).map((b) => (links?.osc8 ? linkBlock(b, links.mounts) : b));
     const inner = width - (boxed ? 4 : GUTTER);
     const body = blocks.map((block, i) => (
     // Items of one list are one thing; a blank row between them is two
@@ -145,6 +154,10 @@ function Answer({ text, boxed }) {
 function App({ engine, options, theme }) {
     const { exit } = useApp();
     const { stdout } = useStdout();
+    const [links] = useState(() => ({
+        mounts: mountsOf(engine.files),
+        osc8: hyperlinks(),
+    }));
     const [lines, setLines] = useState([]);
     const [live, setLive] = useState('');
     const [thinking, setThinking] = useState('');
@@ -651,7 +664,7 @@ function App({ engine, options, theme }) {
             recall(1);
         }
     });
-    return (_jsx(ThemeContext.Provider, { value: theme, children: _jsxs(Box, { flexDirection: "column", children: [_jsx(Static, { items: [BANNER, ...lines], children: (item) => isBanner(item) ? (_jsx(Header, { engine: engine, readOnly: options.readOnly, started: options.started }, item.key)) : (_jsx(Row, { line: item }, item.key)) }), _jsxs(Box, { flexDirection: "column", justifyContent: "flex-end", height: busy ? grown.current : undefined, overflow: "hidden", children: [_jsx(Branches, { boxes: fitted.boxes, spin: spin, frame: frame, columns: columns }), streaming && budget.thinking ? (_jsx(Reasoning, { text: thinking, columns: columns, frame: frame, live: musing })) : null, _jsx(Activity, { rows: fitted.trunk, hidden: fitted.hidden, frame: frame }), live ? _jsx(Streaming, { text: live, columns: columns, rows: textRows }) : null] }), _jsx(Footer, { agent: agent, busy: busy, spin: spin, frame: frame, running: mine, forked: branches.current.size, step: step, model: model, stats: stats, inflight: inflight, reasoning: musing && streaming }), busy ? null : (_jsxs(Box, { children: [_jsx(Text, { color: theme.accent, children: "\u203A " }), _jsx(TextInput, { defaultValue: draft, placeholder: "Ask something\u2026 (\u2191 for history, /help for commands)", onChange: remember, onSubmit: submit }, generation)] }))] }) }));
+    return (_jsx(ThemeContext.Provider, { value: theme, children: _jsx(LinksContext.Provider, { value: links, children: _jsxs(Box, { flexDirection: "column", children: [_jsx(Static, { items: [BANNER, ...lines], children: (item) => isBanner(item) ? (_jsx(Header, { engine: engine, readOnly: options.readOnly, started: options.started }, item.key)) : (_jsx(Row, { line: item }, item.key)) }), _jsxs(Box, { flexDirection: "column", justifyContent: "flex-end", height: busy ? grown.current : undefined, overflow: "hidden", children: [_jsx(Branches, { boxes: fitted.boxes, spin: spin, frame: frame, columns: columns }), streaming && budget.thinking ? (_jsx(Reasoning, { text: thinking, columns: columns, frame: frame, live: musing })) : null, _jsx(Activity, { rows: fitted.trunk, hidden: fitted.hidden, frame: frame }), live ? _jsx(Streaming, { text: live, columns: columns, rows: textRows }) : null] }), _jsx(Footer, { agent: agent, busy: busy, spin: spin, frame: frame, running: mine, forked: branches.current.size, step: step, model: model, stats: stats, inflight: inflight, reasoning: musing && streaming }), busy ? null : (_jsxs(Box, { children: [_jsx(Text, { color: theme.accent, children: "\u203A " }), _jsx(TextInput, { defaultValue: draft, placeholder: "Ask something\u2026 (\u2191 for history, /help for commands)", onChange: remember, onSubmit: submit }, generation)] }))] }) }) }));
 }
 function Header({ engine, readOnly, started, }) {
     const theme = useTheme();
@@ -952,7 +965,8 @@ function Reasoning({ text, columns, frame, live, }) {
     const gist = gistOf(text, columns - GUTTER - 2);
     return (_jsx(Box, { height: 1, paddingLeft: GUTTER, overflow: "hidden", children: _jsx(Text, { wrap: "truncate-end", children: live ? (_jsx(Shimmer, { text: gist, frame: frame, color: theme.thinking.color })) : (_jsx(Text, { color: theme.thinking.color, children: gist })) }) }));
 }
-function Streaming({ text, columns, rows }) {
+function Streaming({ text: said, columns, rows }) {
+    const text = shownText(said, useContext(LinksContext));
     // The same width the finished answer will take, so landing it reflows
     // nothing: what is on screen is what stays there.
     //

package/dist/tui/links.d.ts

@@ -0,0 +1,27 @@
+import type { Workspace } from '@zenera/neo';
+import type { Block, Span } from './wrap.ts';
+export interface Mounts {
+    /** every name a tree is reached by, longest first */
+    names: readonly string[];
+    /** the host path an agent path names, or nothing when it is in no tree */
+    resolve(path: string): string | undefined;
+}
+/** Exactly the trees the file tools reach, under the same containment rule. */
+export declare function mountsOf(files: Workspace): Mounts;
+/** The host `file:` url a mounted path names, or nothing. */
+export declare function mountUrl(token: string, mounts: Mounts): string | undefined;
+/**
+ * The same spans with the same text, mounted paths carrying a host `href`.
+ *
+ * Only `href` changes, so every width measured from `span.text` still holds.
+ */
+export declare function linkSpans(spans: readonly Span[], mounts: Mounts): Span[];
+/** A block whose prose and cells link their mounted paths; a fence is left alone. */
+export declare function linkBlock(block: Block, mounts: Mounts): Block;
+/** For a terminal with no hyperlinks: every `file:///<mount>/…` url, rewritten to the host. */
+export declare function hostUrls(text: string, mounts: Mounts): string;
+/** `text` as an OSC 8 hyperlink to `href`. */
+export declare function hyperlink(href: string, text: string): string;
+/** Whether this terminal turns OSC 8 into a link; an unknown one is assumed not to. */
+export declare function hyperlinks(env?: NodeJS.ProcessEnv): boolean;
+//# sourceMappingURL=links.d.ts.map