@zenera/engine 0.0.0-stage → 1.1.39

package/dist/engine.js

@@ -0,0 +1,315 @@
+import { AgentRunner, FilePayloadStore, SANDBOX_MOUNT, SKILLS_MOUNT, Workspace, assertState, buildRunReport, exaTools, fileTools, lastText, loadProject, memoryDir, readProjectConfig, renderReportHtml, sandboxTools, turns, } from '@zenera/neo';
+import { existsSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { auditModels, describeIssue } from "./audit.js";
+import { loadProjectEnv } from "./env.js";
+import { EXIT, EngineError, invalidError, stderrLogger } from "./errors.js";
+import { readJson, writeJson } from "./home.js";
+import { KeyStore, assertUsable } from "./keys.js";
+import { projectMounts } from "./projects.js";
+import { buildSandbox, prepareHome, teardown, usesSandbox, } from "./sandbox.js";
+import { acquire, createRun, readSessionMeta, writeRunMeta, writeSessionMeta, } from "./session.js";
+/**
+ * Wires the library to a session directory. Every store is file-backed and
+ * rooted inside `.data/`, so a session is self-contained: copy the directory
+ * and the whole conversation, its memory and its blobs travel with it.
+ */
+export async function openEngine(opts) {
+    const logger = opts.logger ?? stderrLogger;
+    const onIssue = opts.onIssue ?? ((issue) => logger.warn(describeIssue(issue)));
+    // Before the keyring, so the project's own file wins over the machine's
+    // keys, and before the load, so `${VAR}` in agents.yaml can name anything
+    // in it. The real environment still beats both.
+    const env = loadProjectEnv(opts.project.dir);
+    const keys = await KeyStore.open();
+    keys.materialize();
+    assertUsable(keys);
+    // Said before the load, because the load stops at the first model it cannot
+    // build: one SDK's words about one model, when the useful answer is which
+    // of the project's models are reachable and which are not.
+    for (const issue of auditModels(opts.project.dir, keys)) {
+        if (!opts.quiet) {
+            onIssue(issue);
+        }
+    }
+    const meta = await readSessionMeta(opts.session);
+    const workspace = resolve(meta.workspace);
+    const payloads = new FilePayloadStore({ dir: opts.session.blobs, 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
+    // selects them: a project that names `sandbox:*` against an empty tool list
+    // fails to load with "unknown tool", which would be a lie.
+    let sandbox;
+    let project;
+    let files;
+    let memory;
+    try {
+        const { root, config } = readProjectConfig(opts.project.dir);
+        // Naming a directory declares the graph, but it cannot bind anyone to
+        // it — so say when the run is pointed at a memory no agent will touch.
+        if (opts.memoryDir && !opts.quiet && !config.agents.some((a) => a.memory)) {
+            logger.warn('--memory names a directory no agent uses — none has `memory: true`');
+        }
+        memory = memoryDir(root, config, opts.memoryDir);
+        // Assets and the skill catalog are mounted for both, under one name.
+        const mounts = projectMounts(root, config, opts.memoryDir);
+        sandbox = buildSandbox({
+            config,
+            root,
+            session: opts.session,
+            workspace,
+            readOnly: opts.readOnly,
+            image: opts.image,
+            keys: opts.keys,
+            env: env?.names,
+            mounts,
+            ...(opts.disposable ? { persist: false } : {}),
+        });
+        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.
+                ...fileTools(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:*`
+                // loads on a machine that cannot yet search, and says so on the
+                // turn that tried.
+                ...exaTools(),
+            ],
+            skillsAt: SKILLS_MOUNT,
+            memory: opts.memory,
+            memoryDir: opts.memoryDir,
+            memoryReadOnly: opts.memoryReadOnly,
+            payloads,
+            resolveFile: (path) => files.within(path),
+        });
+    }
+    catch (err) {
+        throw invalidError(err instanceof Error ? err.message : String(err), `while loading ${opts.project.dir}`);
+    }
+    // Asked here rather than at the first `run_command`, so a host with no
+    // container engine costs an error instead of a round trip. Nothing is
+    // started: the container itself waits until something actually runs.
+    if (usesSandbox(project)) {
+        prepareHome(sandbox);
+        await opts.preflight?.(sandbox, opts.yes);
+    }
+    // `recordRequests` is what makes the report show the exact bytes sent
+    // rather than a reconstruction. It costs state size, and a CLI run is
+    // written to disk once and inspected by a human — exactly the case the
+    // library leaves it off for by default.
+    //
+    // `--model` becomes the runner's fallback rather than an alias, so it
+    // overrides the config's `model:` without touching agents that pinned one.
+    const runner = project.runner({
+        recordRequests: true,
+        model: opts.model ? project.models.model(opts.model) : undefined,
+    });
+    const state = await loadState(opts.session);
+    const lock = acquire(opts.session);
+    return {
+        project,
+        runner,
+        name: opts.project.name,
+        workspace,
+        workspaceMount: sandbox.spec.workdir ?? SANDBOX_MOUNT,
+        files,
+        readOnly: Boolean(opts.readOnly),
+        session: opts.session,
+        memory,
+        state,
+        sandbox,
+        lock,
+        graph: opts.graph,
+        close: async () => {
+            await teardown(sandbox.pool, logger);
+            // A host-supplied graph is the host's to release.
+            if (!opts.memory) {
+                project.close();
+            }
+            lock.release();
+        },
+    };
+}
+async function loadState(session) {
+    if (!existsSync(session.state)) {
+        return undefined;
+    }
+    const json = await readJson(session.state, undefined);
+    try {
+        return assertState(json);
+    }
+    catch {
+        throw invalidError(`${session.state} is not a usable run state`, 'start a fresh session with --new');
+    }
+}
+/** Every tree the agent can see, the workspace first. */
+export function mounts(engine) {
+    return [
+        { host: engine.workspace, at: engine.workspaceMount, readOnly: engine.readOnly },
+        ...engine.sandbox.mounts.map((m) => ({
+            host: m.host,
+            at: m.at,
+            readOnly: Boolean(m.readOnly),
+        })),
+    ];
+}
+/**
+ * What one finished run looks like to a program: `zen run --json` prints it,
+ * and a batch writes one beside every item. The same function on purpose — a
+ * batch whose items were shaped differently would make every consumer of a
+ * single run a special case.
+ */
+export function envelope(engine, outcome) {
+    return {
+        session: { id: engine.session.id, dir: engine.session.dir },
+        run: {
+            id: outcome.run.id,
+            dir: outcome.run.dir,
+            input: outcome.run.input,
+            output: outcome.run.output,
+            state: outcome.run.state,
+            meta: outcome.run.meta,
+            ...(outcome.report ? { report: outcome.report } : {}),
+            ...(outcome.graph ? { graph: outcome.graph } : {}),
+        },
+        mounts: mounts(engine),
+        agent: outcome.result.agent,
+        stopReason: outcome.result.stopReason,
+        durationMs: outcome.durationMs,
+        usage: outcome.result.usage,
+        output: outcome.text,
+    };
+}
+/**
+ * One turn. The session's state decides whether this starts a run or continues
+ * one — which is the whole of what `resume` used to be, and why it is not a
+ * command.
+ */
+export async function runEngine(engine, input, onEvent, signal) {
+    const startedAt = new Date();
+    const stream = engine.state
+        ? engine.runner.send(engine.state, input, { signal })
+        : engine.runner.run(engine.project.entry, input, { signal });
+    if (onEvent) {
+        for await (const event of stream) {
+            onEvent(event);
+        }
+    }
+    const result = await stream.final();
+    const durationMs = Date.now() - startedAt.getTime();
+    engine.state = result.state;
+    const outcome = await record(engine, input, result, startedAt, durationMs);
+    if (result.stopReason === 'failed') {
+        throw new EngineError(result.state.error ?? 'the run failed', EXIT.failed, `report: ${outcome.run.report}`);
+    }
+    return outcome;
+}
+/**
+ * Everything a finished turn leaves behind. The session state is written first:
+ * if the report fails to render, the conversation is still resumable, which is
+ * the ordering that loses least.
+ */
+async function record(engine, input, result, startedAt, durationMs) {
+    const { session } = engine;
+    writeJson(session.state, result.state, 0o644);
+    const meta = await readSessionMeta(session);
+    meta.lastRunAt = new Date().toISOString();
+    meta.title ??= title(input);
+    writeSessionMeta(session, meta);
+    const run = createRun(session);
+    const text = await lastText(result.state, engine.runner.services.payloads);
+    await writeFile(run.input, `${asText(input)}\n`, 'utf8');
+    await writeFile(run.output, `${text}\n`, 'utf8');
+    writeJson(run.state, result.state, 0o644);
+    let report;
+    try {
+        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,
+            mounts: [
+                { at: engine.workspaceMount, href: pathToFileURL(engine.files.root).href },
+                ...engine.files.mounts.map((m) => ({ at: m.at, href: pathToFileURL(m.host).href })),
+            ],
+        });
+        await writeFile(run.report, renderReportHtml(built), 'utf8');
+        report = run.report;
+    }
+    catch {
+        // A report is a convenience. Losing it must not lose the run.
+    }
+    // The same trajectory for the other reader. `report.html` is for a person;
+    // this is what `zen inspect graph` prints, written down while the state is
+    // already in hand — a batch of a hundred items is otherwise a hundred more
+    // commands to run before anything can be read.
+    let graph;
+    try {
+        if (engine.graph) {
+            await writeFile(run.graph, engine.graph(result.state, {
+                runId: run.id,
+                dir: run.dir,
+                workspace: engine.workspace,
+                memory: engine.memory,
+            }), 'utf8');
+            graph = run.graph;
+        }
+    }
+    catch {
+        // Same rule as the report: a view of the run is not the run.
+    }
+    writeRunMeta(run, {
+        version: 1,
+        id: run.id,
+        session: session.id,
+        startedAt: startedAt.toISOString(),
+        finishedAt: new Date().toISOString(),
+        durationMs,
+        agent: result.agent,
+        stopReason: result.stopReason,
+        turns: turns(result.state),
+        usage: result.usage,
+        workspace: engine.workspace,
+        memory: engine.memory,
+        error: result.state.error,
+    });
+    return { run, result, text, durationMs, report, graph };
+}
+function asText(input) {
+    if (typeof input === 'string') {
+        return input;
+    }
+    return input
+        .map((part) => {
+        if (typeof part === 'string') {
+            return part;
+        }
+        if ('text' in part && typeof part.text === 'string') {
+            return part.text;
+        }
+        // A media shorthand is a single key; naming it is more useful in a
+        // transcript than printing the url or the base64 behind it.
+        return `[${Object.keys(part)[0] ?? 'part'}]`;
+    })
+        .join('\n');
+}
+/** A session's label in a picker: the first thing that was ever asked of it. */
+function title(input) {
+    const text = asText(input).replace(/\s+/g, ' ').trim();
+    return text.length > 60 ? `${text.slice(0, 57)}…` : text;
+}
+//# sourceMappingURL=engine.js.map

package/dist/env.d.ts

@@ -0,0 +1,20 @@
+/** The file, relative to the project directory. */
+export declare const ENV_FILE = ".env";
+export interface ProjectEnv {
+    /** the file it was read from */
+    path: string;
+    /** every name the file declares, whether or not its value won */
+    names: string[];
+}
+/**
+ * Reads `<dir>/.env` into `process.env`, without overwriting anything already
+ * set, and returns the names it found. A project with no such file is not a
+ * problem to report — most have none — so the answer is simply `undefined`.
+ *
+ * The names are returned in full, including the ones the environment already
+ * answered: the variable is in play either way, and the sandbox forwards by
+ * name, so what it needs to know is which names matter and not which of the
+ * two sources supplied them.
+ */
+export declare function loadProjectEnv(dir: string): ProjectEnv | undefined;
+//# sourceMappingURL=env.d.ts.map

package/dist/env.js

@@ -0,0 +1,65 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { parseEnv } from 'node:util';
+import { FILE_ENVS } from "./keys.js";
+// ---------------------------------------------------------------------------
+// The project's `.env`
+//
+// A project is a directory, and some of what it needs to run is particular to
+// it: the token for the service it talks to, the base url of the environment
+// it talks to it in. The keyring answers "what can this machine pay for"; this
+// answers "what does this project need", and the two are different questions
+// often enough to be worth two places.
+//
+// Precedence is the same one everything else here uses — the real environment
+// always wins. What is already set in the shell is left alone, this file fills
+// the gaps, and the keyring fills whatever is still missing after that. So a
+// variable exported for one command still overrides the file, which is the
+// behaviour anybody typing `FOO=bar zen run` is expecting.
+//
+// The names, not the values, are what leaves this module: they are what the
+// sandbox forwards, and forwarding by name is what keeps a secret out of an
+// argv. See `forwarded()` in sandbox.ts for the rest of that story.
+// ---------------------------------------------------------------------------
+/** The file, relative to the project directory. */
+export const ENV_FILE = '.env';
+/**
+ * Reads `<dir>/.env` into `process.env`, without overwriting anything already
+ * set, and returns the names it found. A project with no such file is not a
+ * problem to report — most have none — so the answer is simply `undefined`.
+ *
+ * The names are returned in full, including the ones the environment already
+ * answered: the variable is in play either way, and the sandbox forwards by
+ * name, so what it needs to know is which names matter and not which of the
+ * two sources supplied them.
+ */
+export function loadProjectEnv(dir) {
+    const path = join(dir, ENV_FILE);
+    if (!existsSync(path)) {
+        return undefined;
+    }
+    const names = [];
+    for (const [name, value] of Object.entries(parseEnv(readFileSync(path, 'utf8')))) {
+        if (value === undefined) {
+            continue;
+        }
+        names.push(name);
+        // An empty string is not an answer: tools test for absence, and a
+        // commented-out line someone half-filled in should not shadow a key
+        // the keyring has.
+        if (!process.env[name]) {
+            process.env[name] = located(dir, name, value);
+        }
+    }
+    return { path, names };
+}
+/**
+ * A service-account file is normally kept beside the `.env` that names it, so
+ * a relative path there means relative to the *project* — not to wherever the
+ * command happened to be run, which is what both the Google SDK and podman's
+ * bind mount would otherwise make of it.
+ */
+function located(dir, name, value) {
+    return FILE_ENVS.includes(name) && !isAbsolute(value) ? resolve(dir, value) : value;
+}
+//# sourceMappingURL=env.js.map

package/dist/errors.d.ts

@@ -0,0 +1,28 @@
+export declare const EXIT: {
+    readonly ok: 0;
+    readonly failed: 1;
+    readonly usage: 2;
+    readonly invalid: 3;
+    readonly credentials: 4;
+    readonly sandbox: 5;
+};
+export type ExitCode = (typeof EXIT)[keyof typeof EXIT];
+/**
+ * An error that already knows what it means. Anything else reaching the top is
+ * a bug, which is the distinction a caller needs: a wrong request and a wrong
+ * answer are not the same failure.
+ */
+export declare class EngineError extends Error {
+    readonly code: ExitCode;
+    readonly hint?: string;
+    constructor(message: string, code?: ExitCode, hint?: string);
+}
+export declare const usageError: (m: string, hint?: string) => EngineError;
+export declare const invalidError: (m: string, hint?: string) => EngineError;
+export declare const credentialError: (m: string, hint?: string) => EngineError;
+export interface Logger {
+    warn(message: string): void;
+}
+/** Plain lines on stderr, for a host that did not say where warnings go. */
+export declare const stderrLogger: Logger;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -0,0 +1,41 @@
+// ---------------------------------------------------------------------------
+// Errors and warnings
+//
+// The engine runs under a terminal and under a server, so it never prints and
+// never exits. An error carries a code a CLI turns into an exit status and a
+// server turns into an HTTP status; a warning goes to whatever `Logger` the
+// host handed in.
+// ---------------------------------------------------------------------------
+export const EXIT = {
+    ok: 0,
+    failed: 1,
+    usage: 2,
+    invalid: 3,
+    credentials: 4,
+    sandbox: 5,
+};
+/**
+ * An error that already knows what it means. Anything else reaching the top is
+ * a bug, which is the distinction a caller needs: a wrong request and a wrong
+ * answer are not the same failure.
+ */
+export class EngineError extends Error {
+    code;
+    hint;
+    constructor(message, code = EXIT.failed, hint) {
+        super(message);
+        this.name = 'EngineError';
+        this.code = code;
+        this.hint = hint;
+    }
+}
+export const usageError = (m, hint) => new EngineError(m, EXIT.usage, hint);
+export const invalidError = (m, hint) => new EngineError(m, EXIT.invalid, hint);
+export const credentialError = (m, hint) => new EngineError(m, EXIT.credentials, hint);
+/** Plain lines on stderr, for a host that did not say where warnings go. */
+export const stderrLogger = {
+    warn: (message) => {
+        process.stderr.write(`warning ${message}\n`);
+    },
+};
+//# sourceMappingURL=errors.js.map

package/dist/home.d.ts

@@ -0,0 +1,35 @@
+export declare function home(): string;
+export declare const paths: {
+    home: typeof home;
+    projects: () => string;
+    keys: () => string;
+    keyDir: () => string;
+    gym: () => string;
+    /** what the meta agent runs on, which is a choice about a tool, not a project */
+    meta: () => string;
+    /** work already done and worth keeping: vectors, parses, model listings */
+    cache: () => string;
+};
+/** Creates a directory owner-only, and leaves an existing one's mode alone. */
+export declare function ensureDir(dir: string, mode?: number): string;
+export declare function ensureHome(): string;
+/**
+ * Refuses to read a credential file that anyone else can read, the way `ssh`
+ * does. A world-readable key is not a warning-level event: warnings are
+ * ignored, and the whole point of the store is that the secret is not lying
+ * around in the open.
+ *
+ * Windows reports a mode that means nothing here, so the check is POSIX-only.
+ */
+export declare function assertPrivate(path: string): void;
+export declare function readJson<T>(path: string, fallback: T): Promise<T>;
+/**
+ * Write to a sibling and rename. A crash then leaves either the old file or the
+ * new one, never a half-written registry — which matters more here than it
+ * looks, because the alternative is a corrupt `keys.json` locking someone out
+ * of every provider at once.
+ *
+ * Synchronous on purpose: this is also called from exit paths.
+ */
+export declare function writeJson(path: string, value: unknown, mode?: number): void;
+//# sourceMappingURL=home.d.ts.map

package/dist/home.js

@@ -0,0 +1,112 @@
+import { randomUUID } from 'node:crypto';
+import { chmodSync, mkdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { EngineError, EXIT } from "./errors.js";
+// ---------------------------------------------------------------------------
+// The home directory
+//
+// ~/.zenera/neo holds exactly two kinds of thing: credentials, which belong to
+// the machine and never to a project, and an index of where projects are, which
+// is a convenience and is allowed to be wrong.
+//
+// `ZENERA_HOME` moves the whole tree. That is what makes any of this testable
+// and what lets CI start from an empty one.
+// ---------------------------------------------------------------------------
+const DIR_MODE = 0o700;
+const FILE_MODE = 0o600;
+export function home() {
+    const override = process.env.ZENERA_HOME?.trim();
+    return override ? override : join(homedir(), '.zenera', 'neo');
+}
+export const paths = {
+    home,
+    projects: () => join(home(), 'projects.json'),
+    keys: () => join(home(), 'keys.json'),
+    keyDir: () => join(home(), 'keys'),
+    gym: () => join(home(), 'gym'),
+    /** what the meta agent runs on, which is a choice about a tool, not a project */
+    meta: () => join(home(), 'meta.json'),
+    /** work already done and worth keeping: vectors, parses, model listings */
+    cache: () => join(home(), 'cache'),
+};
+/** Creates a directory owner-only, and leaves an existing one's mode alone. */
+export function ensureDir(dir, mode = DIR_MODE) {
+    mkdirSync(dir, { recursive: true, mode });
+    return dir;
+}
+export function ensureHome() {
+    return ensureDir(home());
+}
+// ---------------------------------------------------------------------------
+// Permissions
+// ---------------------------------------------------------------------------
+/**
+ * Refuses to read a credential file that anyone else can read, the way `ssh`
+ * does. A world-readable key is not a warning-level event: warnings are
+ * ignored, and the whole point of the store is that the secret is not lying
+ * around in the open.
+ *
+ * Windows reports a mode that means nothing here, so the check is POSIX-only.
+ */
+export function assertPrivate(path) {
+    if (process.platform === 'win32') {
+        return;
+    }
+    let mode;
+    try {
+        mode = statSync(path).mode;
+    }
+    catch {
+        return; // absent is fine; it will be created with the right mode
+    }
+    const open = mode & 0o077;
+    if (open !== 0) {
+        const octal = (mode & 0o777).toString(8).padStart(3, '0');
+        throw new EngineError(`permissions ${octal} on ${path} are too open`, EXIT.credentials, `run: chmod 600 ${path}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// JSON files
+// ---------------------------------------------------------------------------
+export async function readJson(path, fallback) {
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            return fallback;
+        }
+        throw err;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new EngineError(`${path} is not valid JSON`, EXIT.invalid, 'fix or delete the file');
+    }
+}
+/**
+ * Write to a sibling and rename. A crash then leaves either the old file or the
+ * new one, never a half-written registry — which matters more here than it
+ * looks, because the alternative is a corrupt `keys.json` locking someone out
+ * of every provider at once.
+ *
+ * Synchronous on purpose: this is also called from exit paths.
+ */
+export function writeJson(path, value, mode = FILE_MODE) {
+    ensureDir(dirname(path));
+    const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode });
+        chmodSync(tmp, mode);
+        renameSync(tmp, path);
+    }
+    catch (err) {
+        rmSync(tmp, { force: true });
+        throw err;
+    }
+}
+//# sourceMappingURL=home.js.map

package/dist/ids.d.ts

@@ -0,0 +1,12 @@
+export declare function stamp(now?: Date): string;
+/**
+ * Ids arrive from `--session` and `--run` and become path segments, so they are
+ * checked rather than trusted. The shape has no `.` and no separator, which
+ * makes traversal unrepresentable rather than merely rejected.
+ */
+export declare function isStamp(value: string): boolean;
+/** Human-readable form of a stamp: `2026-08-25 14:30:12`. */
+export declare function stampDate(id: string): string;
+/** ISO instant a stamp names, for `ago()`. Local time in, local time out. */
+export declare function stampInstant(id: string): string | undefined;
+//# sourceMappingURL=ids.d.ts.map

package/dist/ids.js

@@ -0,0 +1,44 @@
+import { randomBytes } from 'node:crypto';
+// ---------------------------------------------------------------------------
+// Identifiers
+//
+// `YYYYMMDD-HHMMSS-xxxx`, local time, four hex characters of entropy.
+//
+// Sortable as a plain string, readable without a decoder, and collision-free
+// when two runs start inside the same second. An epoch integer gives up the
+// first two properties and a uuid gives up all three.
+// ---------------------------------------------------------------------------
+const STAMP = /^\d{8}-\d{6}-[0-9a-f]{4}$/;
+export function stamp(now = new Date()) {
+    const p = (n, w = 2) => String(n).padStart(w, '0');
+    const date = `${now.getFullYear()}${p(now.getMonth() + 1)}${p(now.getDate())}`;
+    const time = `${p(now.getHours())}${p(now.getMinutes())}${p(now.getSeconds())}`;
+    return `${date}-${time}-${randomBytes(2).toString('hex')}`;
+}
+/**
+ * Ids arrive from `--session` and `--run` and become path segments, so they are
+ * checked rather than trusted. The shape has no `.` and no separator, which
+ * makes traversal unrepresentable rather than merely rejected.
+ */
+export function isStamp(value) {
+    return STAMP.test(value);
+}
+/** Human-readable form of a stamp: `2026-08-25 14:30:12`. */
+export function stampDate(id) {
+    if (!isStamp(id)) {
+        return id;
+    }
+    const [d, t] = id.split('-');
+    return (`${d.slice(0, 4)}-${d.slice(4, 6)}-${d.slice(6, 8)} ` +
+        `${t.slice(0, 2)}:${t.slice(2, 4)}:${t.slice(4, 6)}`);
+}
+/** ISO instant a stamp names, for `ago()`. Local time in, local time out. */
+export function stampInstant(id) {
+    if (!isStamp(id)) {
+        return undefined;
+    }
+    const [d, t] = id.split('-');
+    const at = new Date(Number(d.slice(0, 4)), Number(d.slice(4, 6)) - 1, Number(d.slice(6, 8)), Number(t.slice(0, 2)), Number(t.slice(2, 4)), Number(t.slice(4, 6)));
+    return Number.isNaN(at.getTime()) ? undefined : at.toISOString();
+}
+//# sourceMappingURL=ids.js.map