@zenera/cli 1.1.0 → 1.1.2

package/dist/podman.d.ts

@@ -1,7 +1,13 @@
 import { runProcess } from '@zenera/neo';
+import type { ResolvedBuild } from './image.ts';
+import { CliError } from './term.ts';
 export interface PodmanOptions {
     /** the image the project needs on disk before the first run */
     image?: string;
+    /** a Dockerfile to build into `image`, instead of a registry to pull it from */
+    build?: ResolvedBuild;
+    /** build even when the tag is already on disk; `zen sandbox pull` */
+    rebuild?: boolean;
     /** machine size, when one has to be created */
     cpus?: number;
     /** MiB */
@@ -28,12 +34,36 @@ export interface PodmanStatus {
     imagePresent?: boolean;
 }
 export declare function ensurePodmanReady(opts?: PodmanOptions): Promise<void>;
+/**
+ * Builds the project's Dockerfile under its tag.
+ *
+ * Run every time rather than skipped when the tag already exists, because the
+ * tag is a hash of the Dockerfile and its context and the engine's layer cache
+ * is a hash of the same thing plus the base image. Asking it is cheap, and it
+ * is the only thing that notices when `FROM node:24` starts meaning a different
+ * node:24.
+ */
+/**
+ * A build that ran and failed, rather than a host that could not be asked.
+ *
+ * The difference is invisible at the command line — both stop the run and
+ * print why — but it decides everything for `zen check`: a Dockerfile that
+ * does not build is a broken project, and a laptop without podman on it is
+ * not. Only one of them is an error.
+ */
+export declare class BuildError extends CliError {
+}
 /** What `zn sandbox status` prints. Changes nothing, and never throws. */
 export declare function podmanStatus(opts?: PodmanOptions): Promise<PodmanStatus>;
 export interface OwnedContainer {
     name: string;
     /** podman's own word: `running`, `exited`, `created`, `paused` */
     state: string;
+    /** the session that owns it, from the `zenera.key` label */
+    key?: string;
+    createdAt?: string;
+    /** bytes written on top of the image; only present when `sizes` is asked for */
+    size?: number;
 }
 /**
  * Containers this CLI created, whatever session they belong to, and whether
@@ -41,6 +71,32 @@ export interface OwnedContainer {
  * *stopped* container behind, and a listing that only showed running ones
  * would say nothing is there while the disk says otherwise.
  */
-export declare function ownedContainers(engine?: string, exec?: import("@zenera/neo").Runner): Promise<OwnedContainer[]>;
+export declare function ownedContainers(engine?: string, exec?: import("@zenera/neo").Runner, opts?: {
+    sizes?: boolean;
+}): Promise<OwnedContainer[]>;
 export declare function removeContainers(names: readonly string[], engine?: string, exec?: import("@zenera/neo").Runner): Promise<void>;
+export interface DiskLine {
+    count: number;
+    active: number;
+    size: number;
+    reclaimable: number;
+}
+export interface EngineDisk {
+    images: DiskLine;
+    containers: DiskLine;
+    volumes: DiskLine;
+    /** the filesystem images and layers are kept on — inside the machine, if there is one */
+    store?: {
+        used: number;
+        capacity: number;
+    };
+    /** the machine's disk image, as it costs this host; absent on Linux */
+    image?: {
+        name: string;
+        path: string;
+        allocated: number;
+    };
+}
+/** What the engine is using. Never throws: a disk report is not worth a crash. */
+export declare function engineDisk(engine?: string, exec?: import("@zenera/neo").Runner): Promise<EngineDisk | undefined>;
 //# sourceMappingURL=podman.d.ts.map

package/dist/podman.js

@@ -1,10 +1,14 @@
-import { platform } from 'node:os';
 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";
 const DEFAULT_MACHINE_CPUS = 2;
 const DEFAULT_MACHINE_MEMORY = 2048;
 /** Starting a virtual machine and pulling an image are both slow on purpose. */
 const SLOW_MS = 600_000;
+/** ...and a build from a cold cache is slower than either. */
+const BUILD_MS = 900_000;
 // One process asks once. Several agents starting containers in the same run
 // must not each decide to boot a virtual machine.
 const settled = new Map();
@@ -62,7 +66,10 @@ async function preflight(opts) {
     }
     // 4. The image, so the first command is not a five-minute pull that looks
     //    like a hung model.
-    if (opts.image) {
+    if (opts.build) {
+        await build(engine, opts.build, run, opts.rebuild);
+    }
+    else if (opts.image) {
         const present = await call(['image', 'exists', opts.image], 30_000);
         if (present.code !== 0) {
             note(dim(`pulling ${opts.image} — this happens once`));
@@ -158,6 +165,52 @@ function parseMachines(stdout) {
     }
 }
 // ---------------------------------------------------------------------------
+// The image
+// ---------------------------------------------------------------------------
+/**
+ * Builds the project's Dockerfile under its tag.
+ *
+ * Run every time rather than skipped when the tag already exists, because the
+ * tag is a hash of the Dockerfile and its context and the engine's layer cache
+ * is a hash of the same thing plus the base image. Asking it is cheap, and it
+ * is the only thing that notices when `FROM node:24` starts meaning a different
+ * node:24.
+ */
+/**
+ * A build that ran and failed, rather than a host that could not be asked.
+ *
+ * The difference is invisible at the command line — both stop the run and
+ * print why — but it decides everything for `zen check`: a Dockerfile that
+ * does not build is a broken project, and a laptop without podman on it is
+ * not. Only one of them is an error.
+ */
+export class BuildError extends CliError {
+}
+/**
+ * Builds the project's Dockerfile under its tag, unless that tag is already on
+ * disk.
+ *
+ * Skipping is safe here in a way it would not be for an ordinary tag, because
+ * this one is a hash of the Dockerfile and its context: the image existing
+ * *means* the content is unchanged. What it does not cover is a moved base
+ * image — `podman build` defaults to `--pull=missing` and reuses whatever
+ * `FROM node:24` resolved to last time — so `zen sandbox pull` forces the
+ * build, and `--pull` is where that would be fixed if it ever needs to be.
+ */
+async function build(engine, spec, run, force = false) {
+    if (!force) {
+        const present = await run(engine, ['image', 'exists', spec.tag], { timeoutMs: 30_000 });
+        if (present.code === 0) {
+            return;
+        }
+    }
+    note(dim(`building ${spec.tag} from ${spec.dockerfile}`));
+    const built = await stream(engine, ['build', '--tag', spec.tag, '--file', spec.dockerfile, spec.context], run, 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');
+    }
+}
+// ---------------------------------------------------------------------------
 // Reporting
 // ---------------------------------------------------------------------------
 /** What `zn sandbox status` prints. Changes nothing, and never throws. */
@@ -210,19 +263,41 @@ function safeMachines(stdout) {
  * *stopped* container behind, and a listing that only showed running ones
  * would say nothing is there while the disk says otherwise.
  */
-export async function ownedContainers(engine = 'podman', exec = runProcess) {
-    const res = await exec(engine, ['ps', '--all', '--filter', 'label=zenera=1', '--format', '{{.Names}}\t{{.State}}'], { timeoutMs: 30_000 }).catch(() => undefined);
+export async function ownedContainers(engine = 'podman', exec = runProcess, opts = {}) {
+    const args = ['ps', '--all', '--filter', 'label=zenera=1', '--format', 'json'];
+    // Asked for by name only: podman works a size out by diffing the layer,
+    // which costs more than everything else `status` does put together.
+    if (opts.sizes) {
+        args.push('--size');
+    }
+    const res = await exec(engine, args, { timeoutMs: 120_000 }).catch(() => undefined);
     if (!res || res.code !== 0) {
         return [];
     }
-    return res.stdout
-        .split('\n')
-        .map((l) => l.trim())
-        .filter(Boolean)
-        .map((line) => {
-        const [name, state] = line.split('\t');
-        return { name, state: state?.trim() || 'unknown' };
-    });
+    return parseContainers(res.stdout);
+}
+/** Newest first, which is the order someone reading a list of them wants. */
+function parseContainers(stdout) {
+    let raw;
+    try {
+        raw = JSON.parse(stdout.trim() || '[]');
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    return raw
+        .map((c) => ({
+        name: c.Names?.[0] ?? '',
+        state: c.State?.trim() || 'unknown',
+        key: c.Labels?.['zenera.key'],
+        createdAt: c.Created ? new Date(c.Created * 1000).toISOString() : undefined,
+        size: c.Size?.rwSize,
+    }))
+        .filter((c) => c.name)
+        .sort((a, b) => (b.createdAt ?? '').localeCompare(a.createdAt ?? ''));
 }
 export async function removeContainers(names, engine = 'podman', exec = runProcess) {
     if (names.length === 0) {
@@ -230,6 +305,91 @@ export async function removeContainers(names, engine = 'podman', exec = runProce
     }
     await exec(engine, ['rm', '--force', '--volumes', ...names], { timeoutMs: 120_000 });
 }
+/** What the engine is using. Never throws: a disk report is not worth a crash. */
+export async function engineDisk(engine = 'podman', exec = runProcess) {
+    const call = (args) => exec(engine, args, { timeoutMs: 120_000 }).catch(() => undefined);
+    const res = await call(['system', 'df', '--format', 'json']);
+    if (!res || res.code !== 0) {
+        return undefined;
+    }
+    let raw;
+    try {
+        raw = JSON.parse(res.stdout.trim() || '[]');
+    }
+    catch {
+        return undefined;
+    }
+    const rows = Array.isArray(raw) ? raw : [];
+    const pick = (type) => {
+        const row = rows.find((r) => r.Type === type);
+        return {
+            count: row?.TotalCount ?? row?.Total ?? 0,
+            active: row?.Active ?? 0,
+            size: row?.RawSize ?? 0,
+            reclaimable: row?.RawReclaimable ?? 0,
+        };
+    };
+    const info = await call([
+        'info',
+        '--format',
+        '{{.Store.GraphRootUsed}}\t{{.Store.GraphRootAllocated}}',
+    ]);
+    const [used, capacity] = (info?.code === 0 ? info.stdout.trim() : '').split('\t').map(Number);
+    return {
+        images: pick('Images'),
+        containers: pick('Containers'),
+        volumes: pick('Local Volumes'),
+        store: used > 0 && capacity > 0 ? { used, capacity } : undefined,
+        image: platform() === 'linux' ? undefined : await machineImage(engine, exec),
+    };
+}
+/**
+ * What the machine costs the host, which is not what it says it costs: the
+ * disk image is created sparse at its full size, so only its allocated blocks
+ * are real, and blocks freed inside the machine are not handed back until
+ * something trims them. That is why this can exceed the machine's own `used`.
+ *
+ * The path is not something podman will tell us — `machine inspect` stopped
+ * carrying it — so this is the documented default location and nothing is
+ * reported when the file is not there.
+ */
+async function machineImage(engine, exec) {
+    const listed = await exec(engine, ['machine', 'list', '--format', 'json'], {
+        timeoutMs: 30_000,
+    }).catch(() => undefined);
+    if (!listed || listed.code !== 0) {
+        return undefined;
+    }
+    const machines = safeMachines(listed.stdout);
+    const name = (machines.find((m) => m.Default) ?? machines[0])?.Name;
+    if (!name) {
+        return undefined;
+    }
+    const base = join(process.env.XDG_DATA_HOME || join(homedir(), '.local', 'share'), 'containers', 'podman', 'machine');
+    for (const provider of children(base)) {
+        for (const file of children(join(base, provider))) {
+            if (!file.startsWith(name) || !/\.(raw|qcow2|img)$/.test(file)) {
+                continue;
+            }
+            const path = join(base, provider, file);
+            try {
+                return { name, path, allocated: statSync(path).blocks * 512 };
+            }
+            catch {
+                return undefined;
+            }
+        }
+    }
+    return undefined;
+}
+function children(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
 // ---------------------------------------------------------------------------
 /**
  * Long steps print as they go. A five-minute pull with no output is
@@ -248,6 +408,11 @@ async function stream(bin, args, run, timeoutMs = SLOW_MS) {
 function first(res) {
     return (res.stderr.trim() || res.stdout.trim()).split('\n')[0] ?? '';
 }
+/** A build says what went wrong on its last line, not its first. */
+function last(res) {
+    const lines = (res.stderr.trim() || res.stdout.trim()).split('\n').filter((l) => l.trim());
+    return lines.slice(-2).join(' — ');
+}
 function sandboxError(message, hint) {
     return new CliError(message, EXIT.sandbox, hint);
 }

package/dist/projects.d.ts

@@ -1,3 +1,4 @@
+import { type ProjectConfig, type SandboxMount } from '@zenera/neo';
 /** Whether a directory is a project: whether the loader has something to read. */
 export declare function isProjectDir(dir: string): boolean;
 /** A project resolved on disk. */
@@ -6,6 +7,16 @@ export interface Project {
     /** what it is called: the registry's name, or the directory's own */
     name: string;
 }
+/**
+ * The trees a run mounts besides the workspace itself.
+ *
+ * One array, handed to the file tools and to the container both, because the
+ * two have to agree on the name: a path `run_command` prints has to be a path
+ * `read_file` takes. Everything here is read-only — material an agent consults
+ * and does not edit — and the paths are resolved, because the podman machine on
+ * macOS shares the real path or nothing.
+ */
+export declare function projectMounts(root: string, config: ProjectConfig): SandboxMount[];
 /** Walks up from `start` looking for a project configuration. */
 export declare function findUp(start: string): Promise<Project | undefined>;
 export declare function openDir(dir: string): Promise<Project>;
@@ -59,6 +70,13 @@ export declare const sessionsDir: (projectDir: string) => string;
 /** Session ids, oldest first. Only well-formed stamps count as sessions. */
 export declare function sessionIds(projectDir: string): string[];
 export declare function runIds(sessionDir: string): string[];
+/**
+ * What a tree occupies, in allocated blocks rather than in bytes, because a
+ * sparse file costs what it was given and not what it claims. Symlinks are
+ * counted and never followed: a link out of the tree is not part of it, and
+ * one that points back in would otherwise be counted twice — or forever.
+ */
+export declare function dirSize(dir: string): number;
 /** True when a session's lock names a process that is still alive. */
 export declare function isBusy(sessionDir: string): boolean;
 /**

package/dist/projects.js

@@ -1,4 +1,5 @@
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { ASSETS_MOUNT, assetsDir, skillDirs, skillMounts, SKILLS_MOUNT, } from '@zenera/neo';
+import { existsSync, lstatSync, 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";
@@ -25,6 +26,29 @@ const CONFIG_NAMES = ['agents.yaml', 'agents.yml', 'agents/agents.yaml', 'agents
 export function isProjectDir(dir) {
     return CONFIG_NAMES.some((name) => existsSync(join(dir, name)));
 }
+/**
+ * The trees a run mounts besides the workspace itself.
+ *
+ * One array, handed to the file tools and to the container both, because the
+ * two have to agree on the name: a path `run_command` prints has to be a path
+ * `read_file` takes. Everything here is read-only — material an agent consults
+ * and does not edit — and the paths are resolved, because the podman machine on
+ * macOS shares the real path or nothing.
+ */
+export function projectMounts(root, config) {
+    const mounts = [];
+    const assets = assetsDir(root, config);
+    if (assets) {
+        mounts.push({ host: realpathSync(assets), at: ASSETS_MOUNT, readOnly: true });
+    }
+    // The catalog goes in whole, at fixed names, before anything is loaded: a
+    // container's mounts are decided when it is created, so a skill folder
+    // cannot be added at the moment `skill_load` asks for it.
+    for (const dir of skillMounts(skillDirs(root, config), SKILLS_MOUNT)) {
+        mounts.push({ host: realpathSync(dir.path), at: dir.at, readOnly: true });
+    }
+    return mounts;
+}
 // ---------------------------------------------------------------------------
 // The project directory
 // ---------------------------------------------------------------------------
@@ -201,6 +225,41 @@ function stampedChildren(dir) {
         .map((e) => e.name)
         .sort();
 }
+/**
+ * What a tree occupies, in allocated blocks rather than in bytes, because a
+ * sparse file costs what it was given and not what it claims. Symlinks are
+ * counted and never followed: a link out of the tree is not part of it, and
+ * one that points back in would otherwise be counted twice — or forever.
+ */
+export function dirSize(dir) {
+    let total = 0;
+    const stack = [dir];
+    while (stack.length > 0) {
+        const at = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(at, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const path = join(at, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(path);
+                continue;
+            }
+            try {
+                total += lstatSync(path).blocks * 512;
+            }
+            catch {
+                // Gone between the listing and the stat: a live session is
+                // writing, which is normal and not worth failing a report for.
+            }
+        }
+    }
+    return total;
+}
 /** True when a session's lock names a process that is still alive. */
 export function isBusy(sessionDir) {
     const path = join(sessionDir, '.lock');

package/dist/sandbox.d.ts

@@ -1,10 +1,13 @@
-import { SandboxPool, type AgentProject, type ProjectConfig, type SandboxSpec } from '@zenera/neo';
+import { SandboxPool, type AgentProject, type ProjectConfig, type SandboxMount, type SandboxSpec } from '@zenera/neo';
+import { type ResolvedBuild } from './image.ts';
 import type { SessionPaths } from './session.ts';
 export interface SandboxSetup {
     pool: SandboxPool;
     /** the resolved base spec, for `zn sandbox status` and the image pre-warm */
     spec: SandboxSpec;
     image: string;
+    /** the Dockerfile behind `image`, when it came from one */
+    build?: ResolvedBuild;
     /** host side of the container's `$HOME`, created only if it is ever needed */
     home: string;
 }
@@ -12,7 +15,15 @@ export interface SandboxInputs {
     config: ProjectConfig;
     session: SessionPaths;
     workspace: string;
+    /** the project directory, which `build:` paths are relative to */
+    root: string;
     readOnly?: boolean;
+    /**
+     * Trees to mount besides the workspace and the home — the project's assets
+     * and its skill catalog. The same array goes to the file tools, so a path
+     * a command prints is a path `read_file` accepts.
+     */
+    mounts?: readonly SandboxMount[];
     /** `--image` */
     image?: string;
 }

package/dist/sandbox.js

@@ -1,6 +1,7 @@
+import { DEFAULT_SANDBOX_IMAGE, SANDBOX_GROUP, SandboxPool, } from '@zenera/neo';
 import { mkdirSync } from 'node:fs';
 import { join } from 'node:path';
-import { DEFAULT_SANDBOX_IMAGE, SANDBOX_GROUP, SandboxPool, } from '@zenera/neo';
+import { resolveBuild } from "./image.js";
 import { ensurePodmanReady } from "./podman.js";
 import { warn } from "./term.js";
 // ---------------------------------------------------------------------------
@@ -23,14 +24,25 @@ import { warn } from "./term.js";
 /** Where the persistent home lives, inside the container. */
 const HOME = '/home/agent';
 export function buildSandbox(opts) {
-    const base = { ...(opts.config.sandbox ?? {}), ...(opts.image ? { image: opts.image } : {}) };
+    // An explicit --image is an answer, so there is nothing left to build.
+    const build = opts.image ? undefined : resolveBuild(opts.root, opts.config.sandbox);
+    const base = {
+        ...(opts.config.sandbox ?? {}),
+        ...((opts.image ?? build?.tag) ? { image: opts.image ?? build?.tag } : {}),
+    };
     const home = join(opts.session.data, 'sandbox', 'home');
-    const mounts = [{ host: home, at: HOME }];
-    const spec = toSpec(base, { HOME });
+    const mounts = [{ host: home, at: HOME }, ...(opts.mounts ?? [])];
+    // 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 spec = toSpec(base, { HOME, PYTHONDONTWRITEBYTECODE: '1' });
     const agents = {};
     for (const agent of opts.config.agents) {
         if (agent.sandbox) {
-            agents[agent.name] = toSpec({ ...base, ...agent.sandbox }, { HOME });
+            agents[agent.name] = toSpec(merge(base, agent.sandbox), {
+                HOME,
+                PYTHONDONTWRITEBYTECODE: '1',
+            });
         }
     }
     const pool = new SandboxPool({
@@ -41,7 +53,23 @@ export function buildSandbox(opts) {
         readOnly: opts.readOnly,
         mounts,
     });
-    return { pool, spec, image: spec.image ?? DEFAULT_SANDBOX_IMAGE, home };
+    return { pool, spec, image: spec.image ?? DEFAULT_SANDBOX_IMAGE, build, home };
+}
+/**
+ * An agent's overrides on the project's block. `image` and `build` answer the
+ * same question, so naming either one drops the other: a plain spread would
+ * leave an agent's `image` sitting next to the project's `build`, and the
+ * schema forbids exactly that combination when it is written down.
+ */
+function merge(base, agent) {
+    const merged = { ...base, ...agent };
+    if (agent.image !== undefined) {
+        delete merged.build;
+    }
+    if (agent.build !== undefined) {
+        delete merged.image;
+    }
+    return merged;
 }
 /**
  * Config names a variable; this reads it. A name that is not set on this host
@@ -87,6 +115,7 @@ export async function preflight(setup, yes) {
     mkdirSync(setup.home, { recursive: true });
     await ensurePodmanReady({
         image: setup.image,
+        build: setup.build,
         cpus: setup.spec.cpus,
         memory: setup.spec.memory,
         yes,

package/dist/scaffold.d.ts

@@ -11,6 +11,12 @@ export declare function editorSettings(dir: string): string;
  * one is the only one worth having. Returns the relative paths written.
  */
 export declare function copilotInstructions(dir: string): string[];
+/**
+ * Writes `sandbox/`, the Dockerfile the scaffolded `agents.yaml` builds. Unlike
+ * the editor files this becomes the project's own — it is meant to be edited —
+ * so anything already there is left alone.
+ */
+export declare function sandboxTemplate(dir: string): string[];
 export interface ScaffoldOptions {
     /** the project directory */
     dir: string;

package/dist/scaffold.js

@@ -1,4 +1,4 @@
-import { mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 // ---------------------------------------------------------------------------
@@ -65,14 +65,26 @@ version: 1
 
 ${MODEL_SECTION(model, options)}
 
-# The container \`sandbox:*\` commands run in. \`persist: true\` keeps it between
-# runs instead of throwing it away, so what the agent installs is still there
-# next time — otherwise only /workspace and its home directory survive, and an
-# \`apt-get\` or a root \`pip install\` is repeated on every run. \`zen sandbox
+# Anything in assets/ is mounted read-only at /assets for every agent: they can
+# read, list and search it, and no tool can change it. It is a convention, so
+# the folder is enough — set \`assets: <path>\` only to keep the material
+# somewhere else in this project.
+
+# The container \`sandbox:*\` commands run in. \`build:\` names a Dockerfile to
+# build instead of an image to pull, so anything this project always needs is
+# in the image rather than installed by an agent on every run — put it in
+# sandbox/Dockerfile. Swap the whole block for \`image: <ref>\` to pull a
+# published one instead; the two cannot both be set.
+#
+# \`persist: true\` keeps the container between runs rather than throwing it
+# away, so what an agent installs for itself is still there next time —
+# otherwise only /workspace and its home directory survive. \`zen sandbox
 # clean\` removes the ones left behind. Everything else has a default; see the
-# sandbox: block in docs/agents-yaml.md to size or pin the image.
+# sandbox: block in docs/agents-yaml.md to size it.
 sandbox:
     persist: true
+    build:
+        dockerfile: sandbox/Dockerfile
 
 agents:
     - name: default
@@ -111,6 +123,19 @@ const GITIGNORE = `# Sessions hold run state, memory, blobs and whatever the age
 # None of it is source.
 sessions/
 `;
+const ASSETS_README = `# assets
+
+Everything in this folder is mounted at /assets when an agent runs. Every agent
+in this project can read, list and search it, and no tool of theirs can change
+it — so this is where reference material goes: handbooks, specifications,
+schemas, worked examples, the style guide the output is supposed to follow.
+
+It is the project's own files that agents get without being asked. The
+workspace they are pointed at is the work; this is what they consult while
+doing it.
+
+Delete this file once there is something here to read.
+`;
 // ---------------------------------------------------------------------------
 // Telling the editor which instructions are not for it
 //
@@ -163,6 +188,7 @@ export function editorSettings(dir) {
 // adding a skill or a prompt file is adding a file there and nothing else.
 // ---------------------------------------------------------------------------
 const GITHUB_TEMPLATE = fileURLToPath(new URL('../templates/.github', import.meta.url));
+const SANDBOX_TEMPLATE = fileURLToPath(new URL('../templates/sandbox', import.meta.url));
 /**
  * Writes the `.github/` tree under `dir`, replacing what is there — it
  * describes the file formats of the version of `zen` in hand, so the current
@@ -171,11 +197,19 @@ const GITHUB_TEMPLATE = fileURLToPath(new URL('../templates/.github', import.met
 export function copilotInstructions(dir) {
     return copyTree(GITHUB_TEMPLATE, dir, '.github');
 }
+/**
+ * Writes `sandbox/`, the Dockerfile the scaffolded `agents.yaml` builds. Unlike
+ * the editor files this becomes the project's own — it is meant to be edited —
+ * so anything already there is left alone.
+ */
+export function sandboxTemplate(dir) {
+    return copyTree(SANDBOX_TEMPLATE, dir, 'sandbox', { keep: true });
+}
 /**
  * Copies one template directory into `dir` at `rel`, depth first, sorted so
  * the list it returns is the same on every machine.
  */
-function copyTree(from, dir, rel) {
+function copyTree(from, dir, rel, opts) {
     const written = [];
     mkdirSync(join(dir, rel), { recursive: true });
     const entries = readdirSync(from, { withFileTypes: true });
@@ -183,12 +217,14 @@ function copyTree(from, dir, rel) {
     for (const entry of entries) {
         const child = join(rel, entry.name);
         if (entry.isDirectory()) {
-            written.push(...copyTree(join(from, entry.name), dir, child));
+            written.push(...copyTree(join(from, entry.name), dir, child, opts));
+            continue;
         }
-        else {
-            writeFileSync(join(dir, child), readFileSync(join(from, entry.name)));
-            written.push(child);
+        if (opts?.keep && existsSync(join(dir, child))) {
+            continue;
         }
+        writeFileSync(join(dir, child), readFileSync(join(from, entry.name)));
+        written.push(child);
     }
     return written;
 }
@@ -211,7 +247,9 @@ export function scaffold(opts) {
     put('INSTRUCTIONS.md', INSTRUCTIONS_MD);
     put('agents.yaml', AGENTS_YAML(opts.model, opts.modelOptions, opts.web));
     put(join('agents', 'prompts', 'default.md'), PROMPT);
+    put(join('assets', 'README.md'), ASSETS_README);
     put('.gitignore', GITIGNORE);
+    written.push(...sandboxTemplate(opts.dir));
     // The project directory is what `zen open` opens, so this is where the
     // editor actually reads them.
     written.push(editorSettings(opts.dir), ...copilotInstructions(opts.dir));

package/dist/term.d.ts

@@ -66,4 +66,6 @@ export declare function choose<T>(title: string, choices: readonly Choice<T>[]):
 export declare function readStdin(): Promise<string | undefined>;
 export declare function ago(iso: string | undefined): string;
 export declare function count(n: number, singular: string, plural?: string): string;
+/** Powers of 1000, as the container engine prints them, so the two agree. */
+export declare function bytes(n: number): string;
 //# sourceMappingURL=term.d.ts.map