@zenera/cli 1.1.11 → 1.1.14

package/dist/commands/memory.js

@@ -0,0 +1,375 @@
+import { ALL_AGENTS, buildMemoryReport, hostPath, memoryDir, MemoryIndex, MemoryStore, readProjectConfig, renderMemoryHtml, } from '@zenera/neo';
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import { isAbsolute, join, resolve } from 'node:path';
+import { parse } from "../args.js";
+import { project as resolveProject } from "../resolve.js";
+import { ago, bold, bytes, confirm, count, cyan, dim, green, isInteractive, json, note, table, usageError, write, writeAll, yellow, } from "../term.js";
+const USAGE = 'zen memory [stats|ls|show|export|forget] [args] [options]';
+const SUBCOMMANDS = ['stats', 'ls', 'show', 'export', 'forget'];
+/** Enough to see the shape of it; the rest is a number. */
+const LISTED = 30;
+// ---------------------------------------------------------------------------
+// zen memory
+//
+// The graph from outside the agents, and the reason it needs a command is that
+// there is otherwise no way to answer the question memory always eventually
+// raises: *why did it recall that?* Recall is masked, ranked and truncated by
+// design, so what an agent sees is never the whole picture — and when the
+// picture is what is wrong, you need the part that was hidden.
+//
+// So everything here reads the graph unmasked. That is safe because it is
+// local: this command is a person at a terminal in the project directory, not
+// an agent inside a run, and the mask exists to keep agents apart rather than
+// to keep secrets from the person who owns the files.
+//
+// Nothing here contacts a model. The store is opened without an embedder, so
+// inspection is free and works offline; the price is that `ls` filters by text
+// rather than by meaning, which is the right trade for a debugging tool.
+// ---------------------------------------------------------------------------
+export const memory = {
+    summary: 'What the agents remember, and getting rid of it.',
+    usage: USAGE,
+    details: [
+        '  stats                  Size, vocabulary, and whether it is embedded.',
+        '  ls                     Nodes, newest first. Changes nothing.',
+        '  show <id>              One node in full, with what it links to.',
+        '  export [file]          The whole graph as one HTML page.',
+        '  forget <id...>         Remove nodes, their vectors and their files.',
+        '',
+        '  --project <name|dir>   Which project. Defaults to the one you are in.',
+        '  --kind <name>          Only this kind of node.',
+        '  --audience <name>      Only nodes committed under this label.',
+        '  --files                Only nodes that remember a file.',
+        '  --stale                Only nodes something has superseded.',
+        '  --limit <n>            Rows to list. Default 30.',
+        '  --out <file>           Where `export` writes. Default memory.html.',
+        '  --open                 Open the exported page.',
+        '  --yes                  Do not ask before removing.',
+        '',
+        'Everything here reads the graph *unmasked* — every audience, including',
+        'what no agent can see. That is the point: when a mask is the thing',
+        'that is wrong, the hidden part is what you need to look at.',
+        '',
+        '`export` is the one to reach for. It writes a single self-contained',
+        'page: the node list on the left, the graph in the middle, and whatever',
+        'you click on the right, file contents and all.',
+    ],
+    run: async (ctx) => {
+        const { values, positionals } = parse(ctx.args, {
+            project: { type: 'string' },
+            kind: { type: 'string' },
+            audience: { type: 'string' },
+            files: { type: 'boolean' },
+            stale: { type: 'boolean' },
+            limit: { type: 'string' },
+            out: { type: 'string' },
+            open: { type: 'boolean' },
+            yes: { type: 'boolean' },
+        }, USAGE);
+        const what = positionals[0] ?? 'stats';
+        if (!SUBCOMMANDS.includes(what)) {
+            throw usageError(`unknown subcommand: ${what}`, USAGE);
+        }
+        const rest = positionals.slice(1);
+        const opened = await open(ctx.cwd, values.project);
+        try {
+            switch (what) {
+                case 'stats':
+                    return stats(opened, ctx.json);
+                case 'ls':
+                    return list(opened, values, ctx.json);
+                case 'show':
+                    return show(opened, rest, ctx.json);
+                case 'export':
+                    return await write_(opened, rest, values, ctx.cwd, ctx.json);
+                default:
+                    return await forget(opened, rest, values, ctx.json);
+            }
+        }
+        finally {
+            opened.store.release();
+        }
+    },
+};
+/**
+ * The store, opened directly rather than through `loadProject`. Loading the
+ * project would resolve models and read every prompt file to inspect a graph
+ * that needs none of it — and would fail on a project whose credentials are
+ * missing, which is exactly when someone is debugging.
+ */
+async function open(cwd, want) {
+    const project = await resolveProject({ cwd, project: want });
+    const { config } = readProjectConfig(project.dir);
+    const dir = memoryDir(project.dir, config);
+    if (!dir) {
+        throw usageError(`${project.name} has no memory`, 'give an agent `memory: true` in agents.yaml, or add a `memory:` block');
+    }
+    if (!existsSync(join(dir, 'manifest.json'))) {
+        throw usageError(`${project.name} has a memory configured but nothing in it yet`, 'it is written the first time an agent commits something');
+    }
+    return { store: await MemoryStore.open(dir), dir, project: project.name };
+}
+// ---------------------------------------------------------------------------
+// stats
+// ---------------------------------------------------------------------------
+function stats(o, asJson) {
+    const nodes = o.store.graph.nodes();
+    const edges = o.store.graph.edges();
+    const stale = o.store.graph.superseded();
+    const vectors = o.store.vectors;
+    const files = nodes.filter((n) => n.file);
+    const byKind = tally(nodes.map((n) => n.kind));
+    const byRelation = tally(edges.map((e) => e.relation));
+    const byAudience = tally(nodes.flatMap((n) => n.audience));
+    if (asJson) {
+        json({
+            dir: o.dir,
+            nodes: nodes.length,
+            edges: edges.length,
+            superseded: stale.size,
+            files: {
+                count: files.length,
+                bytes: files.reduce((t, n) => t + (n.file?.bytes ?? 0), 0),
+            },
+            embedding: o.store.embedding,
+            vectors: vectors ? { rows: vectors.rows, dims: vectors.dims } : undefined,
+            kinds: byKind,
+            relations: byRelation,
+            audiences: byAudience,
+        });
+        return;
+    }
+    if (!nodes.length) {
+        note(`nothing remembered yet ${dim(o.dir)}`);
+        return;
+    }
+    write(bold(o.project) + dim(' · ' + o.dir));
+    write();
+    writeAll(table([
+        [dim('nodes'), String(nodes.length)],
+        [dim('edges'), String(edges.length)],
+        [dim('superseded'), String(stale.size)],
+        [
+            dim('files'),
+            files.length
+                ? `${files.length} · ${bytes(files.reduce((t, n) => t + (n.file?.bytes ?? 0), 0))}`
+                : '0',
+        ],
+        [
+            dim('embedding'),
+            o.store.embedding
+                ? `${o.store.embedding.model} ${dim(o.store.embedding.dimensions + 'd')}`
+                : yellow('none — recall falls back to term overlap'),
+        ],
+        [dim('vectors'), vectors ? `${vectors.rows} rows` : dim('—')],
+    ]));
+    // A node without a vector cannot be found by meaning, only by luck. It is
+    // the one silent failure this store has, so it is called out by name.
+    if (vectors && vectors.rows < nodes.length) {
+        write();
+        note(yellow(`${count(nodes.length - vectors.rows, 'node')} with no vector`));
+    }
+    section('kinds', byKind);
+    section('relations', byRelation);
+    section('audiences', byAudience);
+}
+function section(title, counts) {
+    const rows = Object.entries(counts).sort((a, b) => b[1] - a[1]);
+    if (!rows.length) {
+        return;
+    }
+    write();
+    write(dim(title));
+    writeAll(table(rows.map(([k, n]) => [`  ${cyan(k)}`, String(n)])));
+}
+function tally(values) {
+    const out = {};
+    for (const v of values) {
+        out[v] = (out[v] ?? 0) + 1;
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// ls
+// ---------------------------------------------------------------------------
+function list(o, flags, asJson) {
+    const stale = o.store.graph.superseded();
+    const limit = Number(flags.limit ?? LISTED);
+    if (!Number.isInteger(limit) || limit < 1) {
+        throw usageError(`--limit wants a positive whole number, got ${flags.limit}`, USAGE);
+    }
+    const all = o.store.graph
+        .nodes()
+        .filter((n) => !flags.kind || n.kind === flags.kind)
+        .filter((n) => !flags.audience || n.audience.includes(flags.audience))
+        .filter((n) => !flags.files || n.file)
+        .filter((n) => !flags.stale || stale.has(n.id))
+        .sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+    if (asJson) {
+        json({ total: all.length, nodes: all.slice(0, limit) });
+        return;
+    }
+    if (!all.length) {
+        note('nothing matches');
+        return;
+    }
+    writeAll(table(all
+        .slice(0, limit)
+        .map((n) => [
+        cyan(n.id),
+        n.kind,
+        n.file ? dim('⎘ ' + n.file.format) : '',
+        clip(n.text, 56),
+        dim(ago(n.createdAt)),
+        stale.has(n.id) ? yellow('superseded') : '',
+    ])));
+    if (all.length > limit) {
+        write();
+        note(dim(`${all.length - limit} more — raise --limit, or use \`zen memory export\``));
+    }
+}
+// ---------------------------------------------------------------------------
+// show
+// ---------------------------------------------------------------------------
+function show(o, ids, asJson) {
+    const id = ids[0];
+    if (!id || ids.length > 1) {
+        throw usageError('show takes exactly one id', 'zen memory show <id>');
+    }
+    const node = o.store.graph.get(id);
+    if (!node) {
+        throw usageError(`no node ${id}`, 'list them with `zen memory ls`');
+    }
+    const links = o.store.graph.neighbors(id);
+    if (asJson) {
+        json({ node, links, file: node.file ? hostPath(o.dir, node.file) : undefined });
+        return;
+    }
+    write(bold(node.id) + ' ' + cyan(node.kind));
+    write();
+    writeAll(table([
+        [dim('revision'), String(node.revision)],
+        [dim('used'), `${node.useCount}× · last ${ago(node.lastUsedAt)}`],
+        [dim('created'), `${node.createdAt} ${dim(ago(node.createdAt))}`],
+        [dim('updated'), node.updatedAt],
+        [dim('audience'), node.audience.join(', ')],
+    ]));
+    write();
+    write(node.text);
+    if (node.metadata) {
+        write();
+        write(dim('metadata'));
+        write(JSON.stringify(node.metadata, null, 2));
+    }
+    if (node.file) {
+        write();
+        write(dim('file'));
+        writeAll(table([
+            [dim('  path'), hostPath(o.dir, node.file)],
+            [dim('  size'), bytes(node.file.bytes)],
+            [dim('  sha256'), node.file.sha256],
+        ]));
+    }
+    write();
+    write(dim(`links (${links.length})`));
+    if (!links.length) {
+        note(dim('  nothing points here and it points nowhere'));
+        return;
+    }
+    writeAll(table(links.map((e) => {
+        const out = e.source === id;
+        const other = out ? e.target : e.source;
+        return [
+            `  ${out ? '→' : '←'} ${yellow(e.relation)}`,
+            cyan(other),
+            clip(o.store.graph.get(other)?.text ?? '', 48),
+        ];
+    })));
+}
+// ---------------------------------------------------------------------------
+// export
+// ---------------------------------------------------------------------------
+async function write_(o, rest, flags, cwd, asJson) {
+    if (rest.length > 1) {
+        throw usageError('export takes at most one file name', 'zen memory export [file]');
+    }
+    const named = rest[0] ?? flags.out ?? 'memory.html';
+    const target = isAbsolute(named) ? named : resolve(cwd, named);
+    const report = await buildMemoryReport(o.store, { title: `${o.project} · memory` });
+    await writeFile(target, renderMemoryHtml(report), 'utf8');
+    if (asJson) {
+        json({ path: target, nodes: report.nodes.length, edges: report.edges.length });
+    }
+    else {
+        note(`${green('wrote')} ${target} ${dim(`· ${count(report.nodes.length, 'node')}, ${count(report.edges.length, 'edge')}`)}`);
+    }
+    if (flags.open) {
+        reveal(target);
+    }
+}
+/**
+ * Handing a path to the platform opener. `spawn` without a shell, so the path
+ * is an argument rather than something a shell gets to interpret.
+ */
+function reveal(target) {
+    const command = process.platform === 'darwin'
+        ? 'open'
+        : process.platform === 'win32'
+            ? 'explorer'
+            : 'xdg-open';
+    spawn(command, [target], { stdio: 'ignore', detached: true }).unref();
+}
+// ---------------------------------------------------------------------------
+// forget
+// ---------------------------------------------------------------------------
+/**
+ * The only destructive thing here, and it is deliberately not the way to fix a
+ * memory that turned out wrong — that is a new node and a `SUPERSEDES` edge,
+ * which keeps the reason it changed. This is for what should never have been
+ * written down: it takes the node, its vector and its file bytes together.
+ */
+async function forget(o, ids, flags, asJson) {
+    if (!ids.length) {
+        throw usageError('forget takes at least one id', 'zen memory forget <id...>');
+    }
+    const found = [];
+    for (const id of ids) {
+        const node = o.store.graph.get(id);
+        if (!node) {
+            throw usageError(`no node ${id}`, 'list them with `zen memory ls`');
+        }
+        found.push(node);
+    }
+    if (!flags.yes) {
+        if (!isInteractive()) {
+            throw usageError('refusing to remove without confirmation', 'pass --yes');
+        }
+        writeAll(table(found.map((n) => [cyan(n.id), n.kind, clip(n.text, 56)])));
+        write();
+        if (!(await confirm(`Forget ${count(found.length, 'node')}?`))) {
+            note('nothing removed');
+            return;
+        }
+    }
+    // The vector and the bytes go with the node, which `MemoryIndex` already
+    // guarantees; `sees` is every audience in the graph, because this command
+    // is the person who owns the files rather than an agent inside a run.
+    const index = new MemoryIndex({ store: o.store });
+    await index.forget(found.map((n) => n.id), [ALL_AGENTS, ...new Set(o.store.graph.nodes().flatMap((n) => n.audience))]);
+    if (asJson) {
+        json({ forgotten: found.map((n) => n.id) });
+    }
+    else {
+        note(`${green('forgot')} ${count(found.length, 'node')}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Shared
+// ---------------------------------------------------------------------------
+function clip(text, n) {
+    const one = text.replace(/\s+/g, ' ').trim();
+    return one.length > n ? one.slice(0, n - 1) + '…' : one;
+}
+//# sourceMappingURL=memory.js.map

package/dist/engine.js

@@ -1,4 +1,4 @@
-import { AgentRunner, FileMemoryStore, FilePayloadStore, SANDBOX_MOUNT, SKILLS_MOUNT, assertState, buildRunReport, exaTools, lastText, loadProject, readProjectConfig, renderReportHtml, sandboxTools, turns, workspaceTools, } from '@zenera/neo';
+import { AgentRunner, FilePayloadStore, SANDBOX_MOUNT, SKILLS_MOUNT, Workspace, assertState, buildRunReport, exaTools, lastText, loadProject, readProjectConfig, renderReportHtml, sandboxTools, turns, workspaceTools, } from '@zenera/neo';
 import { existsSync } from 'node:fs';
 import { writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
@@ -27,7 +27,6 @@ export async function open(opts) {
     const meta = await readSessionMeta(opts.session);
     const workspace = resolve(meta.workspace);
     const payloads = new FilePayloadStore({ dir: opts.session.blobs, id: 'file' });
-    const memory = [new FileMemoryStore({ dir: opts.session.memory, id: 'file' })];
     // The config is read before the project is loaded because the sandbox is
     // configured by it and the tools have to exist before selectors can be
     // resolved against them. They are always registered, whether or not anyone
@@ -35,6 +34,7 @@ export async function open(opts) {
     // fails to load with "unknown tool", which would be a lie.
     let sandbox;
     let project;
+    let files;
     try {
         const { root, config } = readProjectConfig(opts.project.dir);
         // Assets and the skill catalog are mounted for both, under one name.
@@ -49,17 +49,21 @@ export async function open(opts) {
             keys: opts.keys,
             mounts,
         });
+        const workspaceOptions = {
+            root: workspace,
+            readOnly: opts.readOnly,
+            mount: sandbox.spec.workdir ?? SANDBOX_MOUNT,
+            mounts,
+        };
+        // The same view the file tools have, so a path the agent just wrote
+        // resolves the same way when it asks memory to keep a copy.
+        files = new Workspace(workspaceOptions);
         project = await loadProject(opts.project.dir, {
             tools: [
                 // Both groups are pointed at one directory, so both are told the
                 // one name for it: whatever `run_command` prints a path as,
                 // `read_file` accepts.
-                ...workspaceTools({
-                    root: workspace,
-                    readOnly: opts.readOnly,
-                    mount: sandbox.spec.workdir ?? SANDBOX_MOUNT,
-                    mounts,
-                }),
+                ...workspaceTools(workspaceOptions),
                 ...sandboxTools(sandbox.pool),
                 // Registered whether or not a key exists: the credential is
                 // read when a tool is called, so a project that names `exa:*`
@@ -69,7 +73,7 @@ export async function open(opts) {
             ],
             skillsAt: SKILLS_MOUNT,
             payloads,
-            memory,
+            resolveFile: (path) => files.within(path),
         });
     }
     catch (err) {
@@ -105,6 +109,7 @@ export async function open(opts) {
         lock,
         close: async () => {
             await teardown(sandbox.pool);
+            project.close();
             lock.release();
         },
     };
@@ -167,6 +172,7 @@ async function record(engine, input, result, startedAt, durationMs) {
         const built = await buildRunReport(result.state, engine.runner.services.payloads, {
             title: `${engine.name} · ${run.id}`,
             architecture: await engine.runner.describe(),
+            memory: engine.runner.services.memory?.store,
         });
         await writeFile(run.report, renderReportHtml(built), 'utf8');
         report = run.report;

package/dist/main.js

@@ -151,5 +151,14 @@ async function usage(name) {
     write(`  -C, --directory <d> ${dim('Act as if run in <d>.')}`);
     write(`\n${dim(`Start with ${cyan(`${NAME} init`)}, then ${cyan(`${NAME} run`)}.`)}`);
 }
+// `zen memory ls | head` closes the pipe while we are still writing to it, and
+// an unhandled EPIPE turns that ordinary shell idiom into a stack trace. The
+// reader having left is not our error, so we stop quietly.
+process.stdout.on('error', (err) => {
+    if (err.code !== 'EPIPE') {
+        throw err;
+    }
+    process.exit(0);
+});
 process.exitCode = await main(process.argv.slice(2));
 //# sourceMappingURL=main.js.map

package/dist/podman.js

@@ -2,7 +2,7 @@ import { runProcess, SandboxError } from '@zenera/neo';
 import { readdirSync, statSync } from 'node:fs';
 import { homedir, platform } from 'node:os';
 import { join } from 'node:path';
-import { CliError, confirm, dim, EXIT, isInteractive, note } from "./term.js";
+import { CliError, confirm, dim, EXIT, isInteractive, note, progress } from "./term.js";
 const DEFAULT_MACHINE_CPUS = 2;
 const DEFAULT_MACHINE_MEMORY = 2048;
 /** Starting a virtual machine and pulling an image are both slow on purpose. */
@@ -73,7 +73,7 @@ async function preflight(opts) {
         const present = await call(['image', 'exists', opts.image], 30_000);
         if (present.code !== 0) {
             note(dim(`pulling ${opts.image} — this happens once`));
-            const pulled = await stream(engine, ['pull', opts.image], run);
+            const pulled = await stream(engine, ['pull', opts.image], run, 'pulling');
             if (pulled.code !== 0) {
                 throw sandboxError(`could not pull ${opts.image}`, first(pulled) || 'check the image name and your network');
             }
@@ -99,7 +99,7 @@ async function install(engine, opts, run) {
         throw sandboxError('podman is not installed', how);
     }
     note(dim('installing podman — this takes a few minutes'));
-    const done = await stream('brew', ['install', 'podman'], run);
+    const done = await stream('brew', ['install', 'podman'], run, 'installing podman');
     if (done.code !== 0) {
         throw sandboxError('could not install podman', first(done) || how);
     }
@@ -127,7 +127,7 @@ async function machine(engine, call, opts, run) {
         const cpus = String(opts.cpus ?? DEFAULT_MACHINE_CPUS);
         const memory = String(opts.memory ?? DEFAULT_MACHINE_MEMORY);
         note(dim(`initialising the podman machine (${cpus} cpus, ${memory} MiB) — once per host`));
-        const created = await stream(engine, ['machine', 'init', '--cpus', cpus, '--memory', memory], run);
+        const created = await stream(engine, ['machine', 'init', '--cpus', cpus, '--memory', memory], run, 'initialising the machine');
         if (created.code !== 0) {
             throw sandboxError('could not create the podman machine', first(created));
         }
@@ -143,7 +143,7 @@ async function machine(engine, call, opts, run) {
         args.push(chosen.Name);
     }
     note(dim('starting the podman machine'));
-    const started = await stream(engine, args, run, SLOW_MS);
+    const started = await stream(engine, args, run, 'starting the machine', SLOW_MS);
     if (started.code !== 0 && !/already running/i.test(started.stderr)) {
         throw sandboxError('could not start the podman machine', first(started));
     }
@@ -197,8 +197,8 @@ async function build(engine, spec, run, force = false) {
     }
     note(dim(`${force ? 'rebuilding' : 'building'} the sandbox image from ${spec.dockerfile}`));
     note(dim('  the agent runs its commands inside a container, so the image is needed first'));
-    note(dim('  this takes a few minutes; later runs reuse it until the Dockerfile changes'));
-    const built = await stream(engine, ['build', '--tag', spec.tag, '--file', spec.dockerfile, spec.context], run, BUILD_MS);
+    note(dim('  this takes a few minutes; later runs reuse it'));
+    const built = await stream(engine, ['build', '--tag', spec.tag, '--file', spec.dockerfile, spec.context], run, 'building the sandbox image', BUILD_MS);
     if (built.code !== 0) {
         throw new BuildError(`could not build ${spec.dockerfile}`, EXIT.sandbox, last(built) || 'run the build by hand to see what the engine says');
     }
@@ -384,13 +384,20 @@ function children(dir) {
     }
 }
 // ---------------------------------------------------------------------------
+const SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const FRAME_MS = 100;
 /**
  * Long steps print as they go. A five-minute pull with no output is
  * indistinguishable from a hang, and the one thing worse than waiting is not
  * knowing whether you are waiting.
+ *
+ * The engine's own output is buffered until it exits, so while the step runs
+ * the only honest thing to show is that it is still running: a spinner and a
+ * clock, both of which have to move without any event to move them. Off
+ * without a terminal — a CI log wants one line per fact, not ten a second.
  */
-async function stream(bin, args, run, timeoutMs = SLOW_MS) {
-    const res = await run(bin, args, { timeoutMs });
+async function stream(bin, args, run, label, timeoutMs = SLOW_MS) {
+    const res = await ticking(label, run(bin, args, { timeoutMs }));
     for (const line of res.stderr.split('\n').slice(-3)) {
         if (line.trim()) {
             note(dim(`  ${line.trim()}`));
@@ -398,6 +405,33 @@ async function stream(bin, args, run, timeoutMs = SLOW_MS) {
     }
     return res;
 }
+async function ticking(label, work) {
+    if (!process.stderr.isTTY) {
+        return work;
+    }
+    const bar = progress();
+    const startedAt = Date.now();
+    let frame = 0;
+    const timer = setInterval(() => {
+        const spin = SPINNER[frame++ % SPINNER.length];
+        bar.update(dim(`  ${spin} ${label}  ${elapsed(Date.now() - startedAt)}`));
+    }, FRAME_MS);
+    timer.unref();
+    try {
+        return await work;
+    }
+    finally {
+        clearInterval(timer);
+        bar.done();
+    }
+}
+function elapsed(ms) {
+    const total = Math.floor(ms / 1000);
+    const seconds = total % 60;
+    return total < 60
+        ? `${seconds}s`
+        : `${Math.floor(total / 60)}m ${String(seconds).padStart(2, '0')}s`;
+}
 function first(res) {
     return (res.stderr.trim() || res.stdout.trim()).split('\n')[0] ?? '';
 }

package/dist/projects.js

@@ -1,5 +1,5 @@
-import { ASSETS_MOUNT, assetsDir, skillDirs, skillMounts, SKILLS_MOUNT, } from '@zenera/neo';
-import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
+import { ASSETS_MOUNT, assetsDir, FILES_DIR, MEMORY_MOUNT, memoryDir, skillDirs, skillMounts, SKILLS_MOUNT, } from '@zenera/neo';
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
 import { paths, readJson, writeJson } from "./home.js";
 import { isStamp } from "./ids.js";
@@ -47,6 +47,14 @@ export function projectMounts(root, config) {
     for (const dir of skillMounts(skillDirs(root, config), SKILLS_MOUNT)) {
         mounts.push({ host: realpathSync(dir.path), at: dir.at, readOnly: true });
     }
+    const memory = memoryDir(root, config);
+    if (memory) {
+        // Created here because the mount is decided before the project is
+        // loaded, and podman would refuse a source that does not exist yet.
+        const files = join(memory, FILES_DIR);
+        mkdirSync(files, { recursive: true });
+        mounts.push({ host: realpathSync(files), at: MEMORY_MOUNT, readOnly: true });
+    }
     return mounts;
 }
 // ---------------------------------------------------------------------------

package/dist/scaffold.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 // ---------------------------------------------------------------------------
@@ -22,6 +22,12 @@ import { fileURLToPath } from 'node:url';
 // What is there is deliberately close to empty: a template full of
 // commented-out options is a template nobody reads and everybody deletes. The
 // one agent works as written, and every other knob is in `docs/`.
+//
+// `SPECIFICATION.md` is the exception, and is written out in full. It states
+// what the project that was just scaffolded is for and what it may do, and it
+// is *true as written* — so the first thing anyone sees is a specification
+// 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));
 /** The suffix on a file with `{{...}}` in it, dropped when the file lands. */
@@ -42,6 +48,11 @@ function ownVersion() {
  * it — which is how an optional block leaves nothing behind. Anywhere else it
  * takes a word. A name nothing supplies throws, so a typo in a template is a
  * failing test rather than a `{{provider}}` sitting in somebody's agents.yaml.
+ *
+ * Only the value is trimmed at the end, never the start, so a fragment that has
+ * to be a paragraph of its own carries its own blank line as its first line.
+ * That way the template needs no blank line around the placeholder, and dropping
+ * the fragment leaves the surrounding paragraphs exactly as they were.
  */
 function render(text, vars) {
     const value = (name) => {
@@ -123,6 +134,10 @@ function copyTree(from, dir, rel, opts) {
             ? render(readFileSync(source, 'utf8'), opts.vars ?? {})
             : readFileSync(source);
         writeFileSync(join(dir, child), body);
+        // The bytes are copied, not the file, so a script arrives unrunnable.
+        if (child.endsWith('.sh')) {
+            chmodSync(join(dir, child), 0o755);
+        }
         written.push(child);
     }
     return written;
@@ -176,7 +191,13 @@ export function scaffold(opts) {
         keep: true,
         vars: {
             model: modelSection(opts.model, opts.modelOptions),
+            modelRef: opts.model,
             exa: opts.web ? part('exa.yaml') : '',
+            // The same capability stated three times, because the grant, the
+            // specification of it and the instruction to use it are read by
+            // different readers — and a tool nothing says to use is not one.
+            web: opts.web ? part('exa.spec.md') : '',
+            webPrompt: opts.web ? part('exa.prompt.md') : '',
             version: ownVersion(),
         },
     });