@zenera/cli 1.1.0

package/dist/resolve.js

@@ -0,0 +1,138 @@
+import { existsSync } from 'node:fs';
+import { relative, resolve, sep } from 'node:path';
+import { stamp } from "./ids.js";
+import * as Projects from "./projects.js";
+import { createSession, listSessions, requireSession, sessionPaths, } from "./session.js";
+import { ago, choose, confirm, dim, isInteractive, usageError, warn, yellow } from "./term.js";
+// ---------------------------------------------------------------------------
+// Project
+// ---------------------------------------------------------------------------
+export async function project(want) {
+    if (want.project) {
+        return Projects.open(want.project);
+    }
+    const here = await Projects.current(want.cwd);
+    if (here) {
+        return here;
+    }
+    const registry = await Projects.Registry.open();
+    const known = registry.entries.filter((e) => existsSync(e.path));
+    if (known.length === 0) {
+        throw usageError('not inside a project, and none are registered', 'create one: zen init');
+    }
+    if (!isInteractive()) {
+        throw usageError('not inside a project', 'name one with --project');
+    }
+    const chosen = await choose('Which project?', known.map((e) => ({ label: e.name, detail: e.path, value: e })));
+    return Projects.openDir(chosen.path);
+}
+// ---------------------------------------------------------------------------
+// Session
+// ---------------------------------------------------------------------------
+export async function target(want) {
+    const found = await project(want);
+    const dir = found.dir;
+    if (want.session && want.fresh) {
+        throw usageError('--session and --new contradict each other');
+    }
+    if (want.session) {
+        return {
+            project: found,
+            session: requireSession(dir, want.session),
+            created: false,
+        };
+    }
+    if (!want.fresh) {
+        const existing = await pickExisting(dir);
+        if (existing) {
+            return { project: found, session: existing, created: false };
+        }
+    }
+    return { project: found, session: await create(dir, want), created: true };
+}
+/**
+ * Resuming is the default: the common case is continuing what you were doing.
+ * With one session it is taken without asking; with several, the others are
+ * offered, because "the most recent" is only usually what you meant.
+ *
+ * A session that has never run has nothing to continue — it is indistinguishable
+ * from a fresh one, so it is left out rather than offered as a choice.
+ */
+async function pickExisting(projectDir) {
+    const sessions = (await listSessions(projectDir)).filter((s) => s.runs > 0 || s.busy);
+    if (sessions.length === 0) {
+        return undefined;
+    }
+    if (!isInteractive()) {
+        return sessionPaths(projectDir, sessions[0].id);
+    }
+    const choice = await choose('Session', [
+        ...sessions.map((s) => ({
+            label: s.title ?? s.id,
+            detail: `${s.id}  ${ago(s.lastRunAt ?? s.createdAt)}  ` +
+                `${s.runs} run${s.runs === 1 ? '' : 's'}${s.busy ? yellow('  running') : ''}`,
+            value: s.id,
+        })),
+        { label: dim('New session…'), value: undefined },
+    ]);
+    return choice ? sessionPaths(projectDir, choice) : undefined;
+}
+/**
+ * The id is minted before anything is written, so the workspace question can be
+ * asked against the real paths — and so a cancelled answer leaves no directory
+ * behind.
+ */
+async function create(projectDir, want) {
+    const id = stamp();
+    const planned = sessionPaths(projectDir, id);
+    const workspace = await chooseWorkspace(planned, want);
+    return createSession(projectDir, id, workspace);
+}
+// ---------------------------------------------------------------------------
+// Workspace
+// ---------------------------------------------------------------------------
+/**
+ * The workspace is what the agent can read and write, so pointing it outside
+ * the session is the useful case and the dangerous one. It is confirmed once,
+ * explicitly, naming the path — and a script has to say `--yes` to skip that.
+ * An agent with file tools rooted at `$HOME` should take more than one
+ * keystroke to arrange.
+ */
+export async function chooseWorkspace(session, want) {
+    const own = resolve(session.workspace);
+    if (want.workspace) {
+        const at = resolve(want.cwd, want.workspace);
+        await approve(at, session, want);
+        return at;
+    }
+    if (!isInteractive()) {
+        return own;
+    }
+    const chosen = await choose('Workspace — what the agent can read and write', [
+        { label: 'A fresh, empty directory', detail: own, value: own },
+        { label: 'The directory you started in', detail: want.cwd, value: want.cwd },
+    ]);
+    await approve(chosen, session, want);
+    return chosen;
+}
+async function approve(at, session, want) {
+    if (contains(session.dir, at)) {
+        return;
+    }
+    warn(`the agent will be able to read and write ${at}`);
+    if (want.yes) {
+        return;
+    }
+    if (!isInteractive()) {
+        throw usageError('refusing a workspace outside the session without confirmation', 'pass --yes if that is what you meant');
+    }
+    if (!(await confirm('Continue?'))) {
+        throw usageError('cancelled');
+    }
+}
+function contains(parent, child) {
+    const from = resolve(parent);
+    const to = resolve(child);
+    return from === to || !relative(from, to).startsWith(`..${sep}`);
+}
+//# sourceMappingURL=resolve.js.map

package/dist/sandbox.d.ts

@@ -0,0 +1,36 @@
+import { SandboxPool, type AgentProject, type ProjectConfig, type SandboxSpec } from '@zenera/neo';
+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;
+    /** host side of the container's `$HOME`, created only if it is ever needed */
+    home: string;
+}
+export interface SandboxInputs {
+    config: ProjectConfig;
+    session: SessionPaths;
+    workspace: string;
+    readOnly?: boolean;
+    /** `--image` */
+    image?: string;
+}
+export declare function buildSandbox(opts: SandboxInputs): SandboxSetup;
+/**
+ * Whether anything in this project can reach a shell.
+ *
+ * Read off the *resolved* tool lists rather than off the config's selectors,
+ * because `sandbox:*`, `*` and a bare name all mean the same thing by the time
+ * the loader is done, and only one of those three is greppable.
+ */
+export declare function usesSandbox(project: AgentProject): boolean;
+/**
+ * Asked before the first turn rather than at the first tool call, so a missing
+ * container engine costs nothing instead of costing a round trip and half a
+ * plan. A project that never shells out never gets here at all.
+ */
+export declare function preflight(setup: SandboxSetup, yes?: boolean): Promise<void>;
+/** Best-effort teardown: losing a container must never lose a run. */
+export declare function teardown(pool: SandboxPool): Promise<void>;
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/sandbox.js

@@ -0,0 +1,104 @@
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { DEFAULT_SANDBOX_IMAGE, SANDBOX_GROUP, SandboxPool, } from '@zenera/neo';
+import { ensurePodmanReady } from "./podman.js";
+import { warn } from "./term.js";
+// ---------------------------------------------------------------------------
+// The sandbox, as this CLI wires it
+//
+// The library takes resolved values; the config states names and numbers. This
+// is the layer between the two, and it owns the two decisions the library has
+// no business making: which host variables are worth forwarding, and where the
+// container's home directory lives.
+//
+// It lives in the session directory, which is the whole point. A session is
+// already a self-contained thing — copy the directory and its conversation,
+// memory and blobs travel with it — and a `pip install --user` that vanished
+// on close would be the only part of a session that did not. So `$HOME` is a
+// bind mount into `.data/sandbox/home`, and what the agent installs for itself
+// is still there when the session is opened again. Everything *outside* the
+// mounts is throwaway, which is what keeps a stale container from becoming a
+// second, invisible configuration.
+// ---------------------------------------------------------------------------
+/** 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 } : {}) };
+    const home = join(opts.session.data, 'sandbox', 'home');
+    const mounts = [{ host: home, at: HOME }];
+    const spec = toSpec(base, { HOME });
+    const agents = {};
+    for (const agent of opts.config.agents) {
+        if (agent.sandbox) {
+            agents[agent.name] = toSpec({ ...base, ...agent.sandbox }, { HOME });
+        }
+    }
+    const pool = new SandboxPool({
+        ...spec,
+        agents,
+        root: opts.workspace,
+        key: opts.session.id,
+        readOnly: opts.readOnly,
+        mounts,
+    });
+    return { pool, spec, image: spec.image ?? DEFAULT_SANDBOX_IMAGE, home };
+}
+/**
+ * Config names a variable; this reads it. A name that is not set on this host
+ * is simply not forwarded — an empty string in the container is a different
+ * thing from an absent one, and tools test for absence.
+ */
+function toSpec(config, extra) {
+    const env = { ...extra };
+    for (const name of config.env ?? []) {
+        const value = process.env[name];
+        if (value !== undefined && value !== '') {
+            env[name] = value;
+        }
+    }
+    return {
+        image: config.image,
+        cpus: config.cpus,
+        memory: config.memory,
+        network: config.network,
+        workdir: config.workdir,
+        timeout: config.timeout,
+        user: config.user,
+        persist: config.persist,
+        env,
+    };
+}
+/**
+ * Whether anything in this project can reach a shell.
+ *
+ * Read off the *resolved* tool lists rather than off the config's selectors,
+ * because `sandbox:*`, `*` and a bare name all mean the same thing by the time
+ * the loader is done, and only one of those three is greppable.
+ */
+export function usesSandbox(project) {
+    return project.agents.some((a) => a.tools.some((t) => t.group === SANDBOX_GROUP));
+}
+/**
+ * Asked before the first turn rather than at the first tool call, so a missing
+ * container engine costs nothing instead of costing a round trip and half a
+ * plan. A project that never shells out never gets here at all.
+ */
+export async function preflight(setup, yes) {
+    mkdirSync(setup.home, { recursive: true });
+    await ensurePodmanReady({
+        image: setup.image,
+        cpus: setup.spec.cpus,
+        memory: setup.spec.memory,
+        yes,
+    });
+}
+/** Best-effort teardown: losing a container must never lose a run. */
+export async function teardown(pool) {
+    try {
+        await pool.dispose();
+    }
+    catch (err) {
+        warn(`could not clean up the sandbox: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+//# sourceMappingURL=sandbox.js.map

package/dist/scaffold.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Writes `.vscode/settings.json` under `dir`, replacing what is there. The file
+ * is ours: it says how the editor is to treat a directory the agents write
+ * into, and a stale copy of that answer is worse than none. Returns the
+ * relative path.
+ */
+export declare function editorSettings(dir: string): string;
+/**
+ * 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
+ * one is the only one worth having. Returns the relative paths written.
+ */
+export declare function copilotInstructions(dir: string): string[];
+export interface ScaffoldOptions {
+    /** the project directory */
+    dir: string;
+    model: string;
+    /** extra lines for the model's configuration; their presence picks the object form */
+    modelOptions?: string;
+    /** give the default agent `exa:*` — set when a key for it is on hand */
+    web?: boolean;
+}
+/**
+ * Writes a project. Never overwrites the project's own files: the caller
+ * decides whether it may. The editor files are the exception — they are ours,
+ * and are replaced.
+ */
+export declare function scaffold(opts: ScaffoldOptions): string[];
+//# sourceMappingURL=scaffold.d.ts.map

package/dist/scaffold.js

@@ -0,0 +1,220 @@
+import { mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// ---------------------------------------------------------------------------
+// Scaffolding
+//
+// What `zen init` writes. Deliberately close to empty: a template full of
+// commented-out options is a template nobody reads and everybody deletes. The
+// one agent here works as written, and every other knob is in `docs/`.
+// ---------------------------------------------------------------------------
+const INSTRUCTIONS_MD = `# House rules
+
+Everything in this file is prepended to every agent's prompt, so it is the
+place for the things that are true regardless of who is answering: tone,
+constraints, what to do when the answer is not knowable.
+
+Replace this with yours.
+`;
+/**
+ * The `model:` section, which is one line until it has to say more.
+ *
+ * A shorthand cannot carry options, and the object form cannot carry a
+ * shorthand — its `model:` is the bare id the API is sent — so asking for
+ * reasoning means splitting the ref back into the two fields and giving the
+ * configuration a name to be referred to by.
+ */
+const MODEL_SECTION = (ref, options) => {
+    const colon = ref.indexOf(':');
+    if (!options || colon < 0) {
+        return ('# The model an agent uses when it does not pin its own. Change it here and the\n' +
+            '# whole project moves. The prefix is the *provider* name, not the vendor — drop\n' +
+            '# it and the id goes to the default provider, whatever the id looks like.\n' +
+            `model: ${ref}`);
+    }
+    const indented = options
+        .trimEnd()
+        .split('\n')
+        .map((line) => (line ? `        ${line}` : ''))
+        .join('\n');
+    return ('# The model an agent uses when it does not pin its own. Change it here and the\n' +
+        '# whole project moves. A named configuration is what gives the knobs below\n' +
+        '# somewhere to live; a bare `model: <provider>:<id>` works when there are none.\n' +
+        'models:\n' +
+        '    main:\n' +
+        `        provider: ${ref.slice(0, colon)}\n` +
+        `        model: ${ref.slice(colon + 1)}\n` +
+        `${indented}\n` +
+        '\n' +
+        'model: main');
+};
+/**
+ * Added above the tool list when the project is scaffolded with web access.
+ * The group is registered whether or not a key exists, so this only ever
+ * changes what the agent is allowed to reach for.
+ */
+const EXA_NOTE = `
+      #
+      # exa:* is web search and page reading, here because this machine has an
+      # Exa key. The key is read from the environment when a tool is called,
+      # so a clone of this project without one still loads and only the call
+      # fails.`;
+const AGENTS_YAML = (model, options, web) => `# Who exists, and what they may reach for.
+#
+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
+# 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:
+    persist: true
+
+agents:
+    - name: default
+      description: The entry point.
+      # Instructions live in agents/prompts/<name>.md and are picked up by
+      # convention — no need to name the file here.
+      #
+      # workspace:* is every file tool at once, sandbox:* is the shell. Name
+      # them one by one to be narrower, or subtract: [workspace:*, -delete_file]
+      #
+      # sandbox:* runs commands in a container, not on this machine, so it
+      # needs podman — \`zen run\` installs and starts what it can on its own,
+      # and \`zen sandbox status\` says where that got to. Drop the line if you
+      # would rather this agent never reached a shell.${web ? EXA_NOTE : ''}
+      tools:
+          - workspace:*
+          - sandbox:*${web ? '\n          - exa:*' : ''}
+`;
+const PROMPT = `You are a helpful assistant working inside a project workspace.
+
+You have tools to read, search and edit files. The workspace is the only
+place you can see; paths are relative to its root.
+
+You can also run shell commands. They run in a container over the same
+workspace, not on the user's machine, so a command that fails there has cost
+them nothing — but it is still their work in the directory, so read before you
+overwrite and say what you ran.
+
+Read a file before you change it: \`apply_patch\` matches the surrounding text
+exactly, so a patch written from memory will not apply. Use \`apply_patch\` to
+change part of a file and \`write_file\` only for a new one.
+
+Say what you changed.
+`;
+const GITIGNORE = `# Sessions hold run state, memory, blobs and whatever the agent wrote.
+# None of it is source.
+sessions/
+`;
+// ---------------------------------------------------------------------------
+// Telling the editor which instructions are not for it
+//
+// The project's house rules are `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.
+//
+// `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.
+// ---------------------------------------------------------------------------
+const VSCODE_SETTINGS = `{
+    "chat.useNestedAgentsMdFiles": false,
+    "chat.tools.terminal.autoApprove": {
+        "zen": true
+    }
+}
+`;
+/**
+ * Writes `.vscode/settings.json` under `dir`, replacing what is there. The file
+ * is ours: it says how the editor is to treat a directory the agents write
+ * into, and a stale copy of that answer is worse than none. Returns the
+ * relative path.
+ */
+export function editorSettings(dir) {
+    const rel = join('.vscode', 'settings.json');
+    mkdirSync(join(dir, '.vscode'), { recursive: true });
+    writeFileSync(join(dir, rel), VSCODE_SETTINGS);
+    return rel;
+}
+// ---------------------------------------------------------------------------
+// The other half of the editor story
+//
+// `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 a whole `.github/` tree — the
+// standing brief, plus the prompt files and skills the editor picks up from
+// the same place — kept as files rather than template literals in here: they
+// are full of backticks and `${...}` examples, which a TS template literal
+// cannot hold without escaping every one of them into illegibility.
+//
+// `templates/.github/` mirrors what lands in the project one for one, so
+// 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));
+/**
+ * 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
+ * one is the only one worth having. Returns the relative paths written.
+ */
+export function copilotInstructions(dir) {
+    return copyTree(GITHUB_TEMPLATE, dir, '.github');
+}
+/**
+ * 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) {
+    const written = [];
+    mkdirSync(join(dir, rel), { recursive: true });
+    const entries = readdirSync(from, { withFileTypes: true });
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+        const child = join(rel, entry.name);
+        if (entry.isDirectory()) {
+            written.push(...copyTree(join(from, entry.name), dir, child));
+        }
+        else {
+            writeFileSync(join(dir, child), readFileSync(join(from, entry.name)));
+            written.push(child);
+        }
+    }
+    return written;
+}
+/**
+ * Writes a project. Never overwrites the project's own files: the caller
+ * decides whether it may. The editor files are the exception — they are ours,
+ * and are replaced.
+ */
+export function scaffold(opts) {
+    const written = [];
+    const put = (rel, body) => {
+        const path = join(opts.dir, rel);
+        mkdirSync(join(path, '..'), { recursive: true });
+        writeFileSync(path, body, { flag: 'wx' });
+        written.push(rel);
+    };
+    mkdirSync(join(opts.dir, 'agents', 'prompts'), { recursive: true });
+    mkdirSync(join(opts.dir, 'agents', 'skills'), { recursive: true });
+    mkdirSync(join(opts.dir, 'sessions'), { recursive: true });
+    put('INSTRUCTIONS.md', INSTRUCTIONS_MD);
+    put('agents.yaml', AGENTS_YAML(opts.model, opts.modelOptions, opts.web));
+    put(join('agents', 'prompts', 'default.md'), PROMPT);
+    put('.gitignore', GITIGNORE);
+    // 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));
+    return written;
+}
+//# sourceMappingURL=scaffold.js.map

package/dist/session.d.ts

@@ -0,0 +1,77 @@
+export interface SessionPaths {
+    id: string;
+    dir: string;
+    /** what the agent can see and write */
+    workspace: string;
+    data: string;
+    /** the live, resumable state — rewritten after every run */
+    state: string;
+    memory: string;
+    blobs: string;
+    runs: string;
+    lock: string;
+    meta: string;
+}
+export declare function sessionPaths(projectDir: string, id: string): SessionPaths;
+export interface SessionMeta {
+    version: 1;
+    id: string;
+    createdAt: string;
+    /**
+     * Absolute path the agent's file tools are rooted at. Recorded so resuming
+     * never re-asks and never silently moves — a session that quietly changed
+     * what "the workspace" meant between turns would be unexplainable.
+     */
+    workspace: string;
+    lastRunAt?: string;
+    title?: string;
+}
+export declare function createSession(projectDir: string, id: string, workspace: string): SessionPaths;
+export declare function readSessionMeta(p: SessionPaths): Promise<SessionMeta>;
+export declare function writeSessionMeta(p: SessionPaths, meta: SessionMeta): void;
+export interface SessionSummary {
+    id: string;
+    createdAt?: string;
+    runs: number;
+    lastRunAt?: string;
+    busy: boolean;
+    title?: string;
+}
+/** Newest first — the order a picker wants. */
+export declare function listSessions(projectDir: string): Promise<SessionSummary[]>;
+export declare function newestSession(projectDir: string): string | undefined;
+export declare function requireSession(projectDir: string, id: string): SessionPaths;
+export interface Held {
+    release(): void;
+}
+export declare function acquire(p: SessionPaths): Held;
+export interface RunPaths {
+    id: string;
+    dir: string;
+    input: string;
+    output: string;
+    state: string;
+    report: string;
+    meta: string;
+}
+export declare function runPaths(session: SessionPaths, id: string): RunPaths;
+export declare function createRun(session: SessionPaths): RunPaths;
+export interface RunMeta {
+    version: 1;
+    id: string;
+    session: string;
+    startedAt: string;
+    finishedAt: string;
+    durationMs: number;
+    agent: string;
+    stopReason: string;
+    turns: number;
+    usage: unknown;
+    workspace: string;
+    error?: string;
+}
+export declare function writeRunMeta(p: RunPaths, meta: RunMeta): void;
+export declare function newestRun(session: SessionPaths): string | undefined;
+/** A path to show a human: relative when that is shorter, absolute otherwise. */
+export declare function display(path: string, from?: string): string;
+//# sourceMappingURL=session.d.ts.map