@zenera/cli 1.1.23 → 1.1.25

package/dist/commands/sandbox.js

@@ -1,14 +1,18 @@
-import { readProjectConfig } from '@zenera/neo';
+import { readProjectConfig, sandboxLimits, } from '@zenera/neo';
 import { parse } from "../args.js";
 import { resolveBuild } from "../image.js";
-import { engineDisk, ensurePodmanReady, ownedContainers, podmanStatus, removeContainers, } from "../podman.js";
+import { engineDisk, ensurePodmanReady, idleContainers, ownedContainers, podmanStatus, removeContainers, sessionOwners, } from "../podman.js";
 import { current as currentProject, dirSize, isProjectDir, open as openProject, Registry, sessionIds, } from "../projects.js";
-import { ago, bold, bytes, dim, green, json, note, red, table, usageError, write, writeAll, yellow, } from "../term.js";
+import { ago, bold, bytes, count, dim, green, json, note, red, table, usageError, write, writeAll, yellow, } from "../term.js";
 const USAGE = 'zen sandbox [status|up|pull|clean|disk] [options]';
 /** Enough to see the pattern; the rest are a number. */
 const LISTED = 6;
 /** Under the labels, which is where the eye already is. */
 const INDENT = ' '.repeat(11);
+/** `agents.yaml` states memory in MiB; `bytes` prints bytes. */
+const MIB = 1024 * 1024;
+/** Below this many free locks, `status` says so: a batch can spend that in minutes. */
+const FEW_LOCKS = 256;
 // ---------------------------------------------------------------------------
 // The container engine, on its own
 //
@@ -31,6 +35,8 @@ export const sandbox = {
         '',
         '  --project <name|dir>   Which project the image and containers belong to.',
         '  --image <ref>          Use this image instead of the project\u2019s.',
+        '  --idle                 With clean: only what no live run is using — stopped ones,',
+        '                         and running ones whose run was killed before it cleaned up.',
         '',
         'Without --project this is the project you are standing in, and standing',
         'nowhere is an answer: `status` then reports the engine and every container',
@@ -43,6 +49,8 @@ export const sandbox = {
         const { values, positionals } = parse(ctx.args, {
             project: { type: 'string' },
             image: { type: 'string' },
+            stopped: { type: 'boolean' },
+            idle: { type: 'boolean' },
         }, USAGE);
         const what = positionals[0] ?? 'status';
         if (!['status', 'up', 'pull', 'clean', 'disk'].includes(what)) {
@@ -68,7 +76,7 @@ export const sandbox = {
                 }
                 return up(image, build, true, ctx.json, true);
             case 'clean':
-                return clean(ctx.json);
+                return clean(ctx.json, Boolean(values.idle || values.stopped));
             case 'disk':
                 return disk(ctx.json);
         }
@@ -97,6 +105,7 @@ async function projectSandbox(cwd, values) {
             name: found.name,
             image: build?.tag ?? config.sandbox?.image,
             build,
+            limits: widest(config),
         };
     }
     catch {
@@ -113,12 +122,16 @@ async function status(project, image, asJson) {
     // a report about one project must not list another's — or the faker's,
     // which wears the same label and belongs to no project at all.
     const containers = project ? ofProject(project.dir, all) : all;
+    const idle = all.length > 0 ? idleContainers(all, await sessionOwners()) : [];
     if (asJson) {
         json({
             ...found,
             project: project?.name ?? null,
             dockerfile: build?.dockerfile ?? null,
+            limits: project?.limits ?? null,
+            fits: fits(found.capacity?.memory, project?.limits?.memory) ?? null,
             containers,
+            idle: idle.map((c) => c.name),
         });
         return;
     }
@@ -128,7 +141,17 @@ async function status(project, image, asJson) {
         const state = found.machine.starting ? yellow('starting') : mark(found.machine.running);
         write(`${bold('machine')}    ${found.machine.name} ${state}`);
     }
+    if (found.connection) {
+        // A concurrency limit wearing a connection string: `ssh://` opens one
+        // connection per call and sshd refuses them past ten, which stays
+        // invisible until a batch is wide enough to lose tasks at random.
+        const how = found.connection.shared
+            ? dim('· one shared connection, no limit on parallel calls')
+            : yellow('· a new ssh connection per call — about 10 at a time');
+        write(`${bold('connection')} ${dim(found.connection.uri)} ${how}`);
+    }
     write(`${bold('responds')}   ${mark(found.ready)}`);
+    writeAll(limitLines(found, project?.limits));
     if (project) {
         write(`${bold('project')}    ${project.name} ${dim(project.dir)}`);
     }
@@ -138,12 +161,69 @@ async function status(project, image, asJson) {
     if (build) {
         write(`${bold('dockerfile')} ${dim(build.dockerfile)}`);
     }
-    writeAll(containerLines(containers, project?.name));
+    writeAll(lockLines(found.freeLocks, idle.length));
+    writeAll(containerLines(containers, idle, project?.name, all.length));
     if (!found.installed || !found.ready) {
         note('');
         note(dim('run `zen sandbox up` to fix what can be fixed.'));
     }
 }
+/**
+ * The hungriest container this project can start. An agent may override the
+ * project's `sandbox:` block, and it is the largest of them that decides
+ * whether a batch fits — reporting the project's own figure would understate
+ * the machine by however much an agent asked for on top.
+ *
+ * The overrides are merged onto the project's block rather than read alone,
+ * because that is what `SandboxPool.for` does when it builds the container: an
+ * agent that names only `memory:` still runs with the project's `cpus:`.
+ */
+function widest(config) {
+    const base = config.sandbox ?? {};
+    return config.agents
+        .map((a) => sandboxLimits(a.sandbox ? { ...base, ...a.sandbox } : base))
+        .reduce((most, one) => (one.memory > most.memory ? one : most), sandboxLimits(base));
+}
+/**
+ * How many containers of this size the engine could hold at once.
+ *
+ * Nothing enforces it — `--memory` caps one container and the kernel kills
+ * whatever overruns the sum, so this is what the machine can honour, not a
+ * gate anything checks. It is worth printing because neither figure gives it
+ * alone: off Linux the memory is the *machine's*, which has nothing to do with
+ * the host, so a few containers at the 4096 MiB default can be past it while
+ * the laptop sits nearly empty.
+ */
+function fits(capacity, container) {
+    if (!capacity || !container) {
+        return undefined;
+    }
+    return Math.max(0, Math.floor(capacity / container));
+}
+/**
+ * Two ceilings, in the order they bite: what the engine has, and what one
+ * container is permitted to take of it.
+ */
+function limitLines(found, limits) {
+    const lines = [];
+    const where = found.machine ? 'machine' : 'host';
+    if (found.capacity) {
+        const { memory, swap, cpus } = found.capacity;
+        const swapped = swap > 0 ? `${bytes(swap * MIB)} swap` : 'no swap';
+        lines.push(`${bold('capacity')}   ${bytes(memory * MIB)} ${dim(`· ${swapped} · ${cpus} cpus · the ${where}'s, not the host's`)}`);
+    }
+    if (limits) {
+        const room = fits(found.capacity?.memory, limits.memory);
+        const how = limits.declared ? limits.hardening : `${limits.hardening} defaults`;
+        const tail = room === undefined
+            ? how
+            : room > 0
+                ? `· ${how} · the ${where} has room for ${room}`
+                : `· ${how} · more than the ${where} has`;
+        lines.push(`${bold('container')}  ${bytes(limits.memory * MIB)} ${dim(`· ${limits.cpus} cpus ${tail}`)}`);
+    }
+    return lines;
+}
 /**
  * The containers this project's sessions made. A container carries the session
  * id that made it in a label, and a session id is a directory name under the
@@ -154,6 +234,22 @@ function ofProject(dir, containers) {
     const sessions = new Set(sessionIds(dir));
     return containers.filter((c) => c.key !== undefined && sessions.has(c.key));
 }
+/**
+ * Every container the engine holds takes one of its locks, stopped or not, and
+ * at zero nothing can be created — for any project. Said only when it is close.
+ */
+function lockLines(free, idle) {
+    if (free === undefined || free >= FEW_LOCKS) {
+        return [];
+    }
+    const left = free === 0 ? red('none free') : yellow(`${free} free`);
+    return [
+        `${bold('locks')}      ${left} ${dim('· one per container, stopped ones included')}`,
+        ...(idle > 0
+            ? [`${INDENT}${dim(`${idle} no live run is using — zen sandbox clean --idle`)}`]
+            : []),
+    ];
+}
 /**
  * One per line rather than one long line, because there is normally more than
  * one and the interesting part — how old, and whether anything is still up —
@@ -164,21 +260,31 @@ function ofProject(dir, containers) {
  * stopped ones behind. `scope` names the project these belong to, and saying
  * so is half the answer — the other half is that there are more elsewhere.
  */
-function containerLines(containers, scope) {
+function containerLines(containers, idle, scope, total = containers.length) {
     const tail = scope
         ? `one per session in ${scope}, kept by \`persist: true\` — all of them: zen sandbox disk`
         : 'one per session, kept by `persist: true` — see: zen sandbox disk';
+    const elsewhere = total > containers.length ? ` · ${total} on the machine` : '';
     if (containers.length === 0) {
-        return [`${bold('containers')} ${dim(scope ? `none in ${scope}` : 'none')}`];
+        return [`${bold('containers')} ${dim(scope ? `none in ${scope}${elsewhere}` : 'none')}`];
     }
+    // Running, but the run that started it is gone: nothing will ever stop it.
+    const orphans = new Set(idle.filter((c) => c.state === 'running').map((c) => c.name));
     const running = containers.filter((c) => c.state === 'running').length;
-    const head = `${bold('containers')} ${containers.length} ${dim(running ? `· ${running} running` : '· none running')}`;
+    const lost = containers.filter((c) => orphans.has(c.name)).length;
+    const head = `${bold('containers')} ${containers.length} ${dim((running ? `· ${running} running` : '· none running') +
+        (lost ? `, ${lost} of them orphaned` : '') +
+        elsewhere)}`;
     const rows = containers
         .slice(0, LISTED)
         .map((c) => [
         INDENT.slice(2),
         c.name,
-        c.state === 'running' ? green('running') : dim(c.state),
+        orphans.has(c.name)
+            ? yellow('orphaned')
+            : c.state === 'running'
+                ? green('running')
+                : dim(c.state),
         dim(ago(c.createdAt)),
     ]);
     const rest = containers.length - LISTED;
@@ -187,6 +293,9 @@ function containerLines(containers, scope) {
         ...table(rows),
         ...(rest > 0 ? [`${INDENT}${dim(`+${rest} more`)}`] : []),
         `${INDENT}${dim(tail)}`,
+        ...(lost
+            ? [`${INDENT}${dim('orphaned: its run was killed — zen sandbox clean --idle')}`]
+            : []),
     ];
 }
 async function up(image, build, yes, asJson, rebuild = false) {
@@ -197,8 +306,9 @@ async function up(image, build, yes, asJson, rebuild = false) {
     }
     write(`${green('ready')}${image ? ` ${dim(image)}` : ''}`);
 }
-async function clean(asJson) {
-    const containers = await ownedContainers(undefined, undefined, { sizes: true });
+async function clean(asJson, idle) {
+    const owned = await ownedContainers(undefined, undefined, { sizes: true });
+    const containers = idle ? idleContainers(owned, await sessionOwners()) : owned;
     const names = containers.map((c) => c.name);
     const freed = containers.reduce((n, c) => n + (c.size ?? 0), 0);
     await removeContainers(names);
@@ -236,10 +346,30 @@ async function disk(asJson) {
         write('');
     }
     writeAll(projectRows(projects, loose));
-    if (usage && usage.images.reclaimable > 0) {
+    const idle = idleContainers(containers, await sessionOwners());
+    const live = containers.length - idle.length;
+    const sessions = projects.reduce((n, p) => n + p.files, 0);
+    const hints = [
+        ...(idle.length > 0
+            ? [`zen sandbox clean --idle  ${count(idle.length, 'container')} no live run is using`]
+            : []),
+        ...(live > 0
+            ? [`zen sandbox clean         also the ${live} in use, cutting off whatever runs there`]
+            : []),
+        ...(usage && usage.images.reclaimable > 0
+            ? [`podman image prune -a     ${bytes(usage.images.reclaimable)} of unused images`]
+            : []),
+        // The ON DISK column is the bulk of the report and no command above touches it.
+        ...(sessions > 0
+            ? [
+                `${bytes(sessions)} ON DISK is project directories on this host, not the engine: ` +
+                    'removing containers frees none of it',
+            ]
+            : []),
+    ];
+    if (hints.length > 0) {
         write('');
-        write(dim(`zen sandbox clean       every container above`));
-        write(dim(`podman image prune -a   ${bytes(usage.images.reclaimable)} of unused images`));
+        writeAll(hints.map((h) => dim(h)));
     }
 }
 function engineRows(usage) {
@@ -311,13 +441,16 @@ function projectRows(projects, loose) {
         // Containers whose session directory is gone, and faker's, which are
         // labelled the same way and belong to no project at all.
         const size = loose.reduce((n, c) => n + (c.size ?? 0), 0);
+        const fakers = loose.filter((c) => c.key?.startsWith('faker-')).length;
         rows.push([
             dim('(unclaimed)'),
             dim('—'),
             dim('—'),
             dim(String(loose.length)),
             dim(bytes(size)),
-            dim('no session owns these'),
+            dim(fakers === loose.length
+                ? `zen faker ${fakers === 1 ? 'server' : 'servers'}, no project`
+                : 'no session owns these'),
         ]);
     }
     const total = (pick) => projects.reduce((n, p) => n + pick(p), 0);

package/dist/engine.d.ts

@@ -12,10 +12,23 @@ export interface EngineOptions {
     image?: string;
     /** another directory to remember into — `--memory` */
     memoryDir?: string;
+    /** recall only: nothing is written and several runs may share one graph */
+    memoryReadOnly?: boolean;
     /** whether credentials reach the sandbox — `--no-keys` sets this false */
     keys?: boolean;
     /** answer the sandbox's install question without asking — `--yes` */
     yes?: boolean;
+    /**
+     * Hold back the warnings about the project rather than the run. A batch
+     * opens one project a hundred times, and a hundred copies of the same
+     * complaint is a worse report than one.
+     */
+    quiet?: boolean;
+    /**
+     * The session will never be resumed, so its containers are removed on close
+     * whatever `persist:` says. A stopped one would only hold an engine lock.
+     */
+    disposable?: boolean;
 }
 export interface Engine {
     project: AgentProject;
@@ -27,6 +40,8 @@ export interface Engine {
     /** whether the agent was denied every writing tool */
     readOnly: boolean;
     session: SessionPaths;
+    /** the graph this session remembers into, when any agent has one */
+    memory?: string;
     /** the session's accumulated state, when it has one */
     state?: AgentState;
     /** the containers this session may start; present whether or not it does */
@@ -56,7 +71,16 @@ export interface RunOutcome {
     durationMs: number;
     /** where the report landed, when one could be rendered */
     report?: string;
+    /** where the Mermaid graph landed, when one could be emitted */
+    graph?: string;
 }
+/**
+ * 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 declare function envelope(engine: Engine, outcome: RunOutcome): Record<string, unknown>;
 /**
  * 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

package/dist/engine.js

@@ -1,4 +1,4 @@
-import { AgentRunner, FilePayloadStore, SANDBOX_MOUNT, SKILLS_MOUNT, Workspace, assertState, buildRunReport, exaTools, lastText, loadProject, readProjectConfig, renderReportHtml, sandboxTools, turns, workspaceTools, } from '@zenera/neo';
+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';
@@ -8,8 +8,9 @@ import { readJson, writeJson } from "./home.js";
 import { KeyStore, assertUsable } from "./keys.js";
 import { projectMounts } from "./projects.js";
 import { buildSandbox, preflight, teardown, usesSandbox } from "./sandbox.js";
-import { acquire, createRun, readSessionMeta, writeSessionMeta, } from "./session.js";
+import { acquire, createRun, readSessionMeta, writeRunMeta, writeSessionMeta, } from "./session.js";
 import { CliError, EXIT, invalidError, warn } from "./term.js";
+import { traceMermaid } from "./trace.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
@@ -27,7 +28,9 @@ export async function open(opts) {
     // 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)) {
-        warn(describeIssue(issue));
+        if (!opts.quiet) {
+            warn(describeIssue(issue));
+        }
     }
     const meta = await readSessionMeta(opts.session);
     const workspace = resolve(meta.workspace);
@@ -40,13 +43,15 @@ export async function open(opts) {
     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 && !config.agents.some((a) => a.memory)) {
+        if (opts.memoryDir && !opts.quiet && !config.agents.some((a) => a.memory)) {
             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({
@@ -59,6 +64,7 @@ export async function open(opts) {
             keys: opts.keys,
             env: env?.names,
             mounts,
+            ...(opts.disposable ? { persist: false } : {}),
         });
         const workspaceOptions = {
             root: workspace,
@@ -74,7 +80,7 @@ export async function open(opts) {
                 // 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(workspaceOptions),
+                ...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:*`
@@ -84,6 +90,7 @@ export async function open(opts) {
             ],
             skillsAt: SKILLS_MOUNT,
             memoryDir: opts.memoryDir,
+            memoryReadOnly: opts.memoryReadOnly,
             payloads,
             resolveFile: (path) => files.within(path),
         });
@@ -118,6 +125,7 @@ export async function open(opts) {
         workspaceMount: sandbox.spec.workdir ?? SANDBOX_MOUNT,
         readOnly: Boolean(opts.readOnly),
         session: opts.session,
+        memory,
         state,
         sandbox,
         lock,
@@ -151,6 +159,33 @@ export function mounts(engine) {
         })),
     ];
 }
+/**
+ * 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
@@ -205,7 +240,24 @@ async function record(engine, input, result, startedAt, durationMs) {
     catch {
         // A report is a convenience. Losing it must not lose the run.
     }
-    writeJson(run.meta, {
+    // 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 {
+        await writeFile(run.graph, traceMermaid(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,
@@ -217,9 +269,10 @@ async function record(engine, input, result, startedAt, durationMs) {
         turns: turns(result.state),
         usage: result.usage,
         workspace: engine.workspace,
+        memory: engine.memory,
         error: result.state.error,
-    }, 0o644);
-    return { run, result, text, durationMs, report };
+    });
+    return { run, result, text, durationMs, report, graph };
 }
 function asText(input) {
     if (typeof input === 'string') {

package/dist/eventlog.d.ts

@@ -0,0 +1,59 @@
+import { type AgentEvent } from '@zenera/neo';
+export type EventBody = {
+    type: 'llm';
+    model: string;
+    in: number;
+    cached: number;
+    out: number;
+    reasoning: number;
+    ms?: number;
+} | {
+    type: 'tool';
+    phase: 'start';
+    id: string;
+    name: string;
+    subject: string;
+} | {
+    type: 'tool';
+    phase: 'end';
+    id: string;
+    name: string;
+    ok: boolean;
+    ms?: number;
+} | {
+    type: 'say';
+    text: string;
+};
+export type EventLine = EventBody & {
+    t: string;
+};
+/** A line that cannot be written is dropped: watching a run must not break it. */
+export declare function eventLog(path: string): (body: EventBody) => void;
+/** For `zen run`: the runtime's own events, folded to the shared lines. */
+export declare function agentEventLog(path: string): (event: AgentEvent) => void;
+/** One line of copilot's JSONL, as much of it as is read here. */
+export interface CopilotEvent {
+    type: string;
+    data?: Record<string, unknown>;
+}
+/** A model call read off copilot's span file - see `meta/tokens.ts`. */
+export interface CopilotCall {
+    model: string;
+    usage: {
+        inputTokens: number;
+        cachedInputTokens: number;
+        outputTokens: number;
+        reasoningTokens: number;
+    };
+    durationMs: number;
+}
+/**
+ * For `zen meta run`: copilot's events and spans, folded to the same lines.
+ * Its JSONL has no token counts, so `llm` lines come from the spans instead,
+ * about a second after each call.
+ */
+export declare function copilotEventLog(path: string): {
+    event: (event: CopilotEvent) => void;
+    call: (call: CopilotCall) => void;
+};
+//# sourceMappingURL=eventlog.d.ts.map