@zenera/neo 1.1.22 → 1.1.24

package/dist/tools/index.d.ts

@@ -1,4 +1,4 @@
 export * from './exa.ts';
+export * from './files.ts';
 export * from './sandbox.ts';
-export * from './workspace.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/tools/index.js

@@ -1,6 +1,6 @@
 // Tools a host may hand to a project. Nothing here is wired in by default:
 // what an agent can reach is a deployment decision, so it is opted into.
 export * from "./exa.js";
+export * from "./files.js";
 export * from "./sandbox.js";
-export * from "./workspace.js";
 //# sourceMappingURL=index.js.map

package/dist/tools/sandbox.d.ts

@@ -120,6 +120,15 @@ export interface ProcResult {
 }
 export type Runner = (bin: string, args: readonly string[], opts?: ProcOptions) => Promise<ProcResult>;
 export declare const runProcess: Runner;
+/**
+ * `run`, retried while the engine could not be reached at all.
+ *
+ * Empty stdout is the guard that keeps this from retrying real work: a command
+ * that produced output ran, whatever its stderr says afterwards. The wait is
+ * jittered because the burst being backed off from is N clients arriving
+ * together, and a fixed delay would only reassemble it.
+ */
+export declare function resilient(run: Runner, attempts?: number): Runner;
 interface Resolved extends Required<Omit<SandboxSpec, 'user'>> {
     user?: string;
     root: string;
@@ -143,12 +152,30 @@ export interface ExecResult {
     truncated?: boolean;
     timed_out?: boolean;
     duration_ms: number;
+    out_of_memory?: OutOfMemory;
+}
+/**
+ * Why a command was killed for memory, which is a different question from
+ * whether it was. A container that overran its own `--memory` will do it again
+ * however long anyone waits; one the kernel sacrificed for a neighbour may
+ * simply succeed later. Exit code 137 is all either of them says.
+ */
+export interface OutOfMemory {
+    /** what this container was allowed */
+    limit_mib: number;
+    /** high-water mark for the container's whole life, not for this command */
+    peak_mib?: number;
+    /** false when the limit itself is the problem, so an unchanged rerun ends the same way */
+    retryable: boolean;
+    hint: string;
 }
 interface Job {
     id: string;
     command: string;
     cwd: string;
     startedAt: number;
+    /** worked out once, because a log is read many times and the evidence is consumed */
+    oom?: OutOfMemory;
 }
 /**
  * The container, started when it is first needed and not before. A project
@@ -195,6 +222,23 @@ export declare class Sandbox {
      */
     inside(path?: string): string;
 }
+export interface SandboxLimits {
+    /** MiB */
+    memory: number;
+    /** fractional cores */
+    cpus: number;
+    hardening: SandboxHardening;
+    /** whether the numbers above were written down, or are this profile's defaults */
+    declared: boolean;
+}
+/**
+ * What a spec's ceilings come to, for a report that has no container to ask.
+ *
+ * It exists so `zen sandbox status` cannot disagree with what a run actually
+ * applies: the defaults are stated once, here and in `resolveSpec`, and
+ * nothing outside this module repeats them.
+ */
+export declare function sandboxLimits(spec?: Pick<SandboxSpec, 'cpus' | 'memory' | 'hardening'>): SandboxLimits;
 export declare class SandboxPool {
     #private;
     constructor(opts: SandboxPoolOptions);

package/dist/tools/sandbox.js

@@ -39,6 +39,8 @@ const MAX_TIMEOUT_MS = 3_600_000;
 const DEFAULT_PIDS = 1024;
 /** How long a container gets to stop itself before it is killed. */
 const STOP_GRACE_S = 2;
+/** SIGKILL, which is how the kernel's out-of-memory killer arrives. */
+const KILLED = 137;
 // Standard mode's resource ceilings. Even without the strict profile, an
 // unbounded container can exhaust host cores or memory during runaway builds.
 const DEFAULT_CPUS = 4;
@@ -138,6 +140,57 @@ export const runProcess = (bin, args, opts = {}) => new Promise((settle, fail) =
         child.stdin.end();
     }
 });
+// ---------------------------------------------------------------------------
+// Reaching the engine at all
+//
+// On macOS and Windows the client is remote: unless it has been pointed at the
+// machine's forwarded endpoint, every invocation opens its own ssh connection
+// into the virtual machine, and sshd refuses new ones past `MaxStartups` — ten
+// by default, with a random drop above that. A wide batch therefore loses
+// calls for a reason that has nothing to do with the command, on a different
+// task each time.
+//
+// A refused connection is the one failure that can be retried without asking
+// what the command was: it happened before authentication, so nothing ran.
+// ---------------------------------------------------------------------------
+const TRANSPORT = /kex_exchange_identification|ssh: handshake failed|ssh: unexpected packet|connection closed by remote host|connection reset by peer|connection refused/i;
+const ATTEMPTS = 4;
+/**
+ * `run`, retried while the engine could not be reached at all.
+ *
+ * Empty stdout is the guard that keeps this from retrying real work: a command
+ * that produced output ran, whatever its stderr says afterwards. The wait is
+ * jittered because the burst being backed off from is N clients arriving
+ * together, and a fixed delay would only reassemble it.
+ */
+export function resilient(run, attempts = ATTEMPTS) {
+    return async (bin, args, opts = {}) => {
+        for (let n = 1;; n++) {
+            const res = await run(bin, args, opts);
+            if (n >= attempts ||
+                res.code === 0 ||
+                res.stdout !== '' ||
+                opts.signal?.aborted ||
+                !TRANSPORT.test(res.stderr)) {
+                return res;
+            }
+            await new Promise((go) => setTimeout(go, 2 ** n * 50 + Math.random() * 100));
+        }
+    };
+}
+/**
+ * Asked of the container after a kill. Builtins only: a slim image may have no
+ * `awk`, and strict hardening leaves nowhere writable to install one. `oom_kill`
+ * counts kills in this container's cgroup and no other, which is what separates
+ * the two cases. Unreadable values print empty, and the caller reads that as
+ * "could not tell".
+ */
+const CGROUP = [
+    `peak=; kills=`,
+    `read peak < /sys/fs/cgroup/memory.peak 2>/dev/null`,
+    `while read -r k v; do [ "$k" = oom_kill ] && kills=$v; done < /sys/fs/cgroup/memory.events 2>/dev/null`,
+    `echo "peak=$peak kills=$kills"`,
+].join('\n');
 /**
  * The container, started when it is first needed and not before. A project
  * whose agents never shell out never pays for an image pull, and a session
@@ -150,9 +203,11 @@ export class Sandbox {
     #jobs = new Map();
     #ready;
     #created = false;
+    /** kills counted in this container's cgroup as of the last probe */
+    #kills;
     constructor(opts) {
         this.spec = resolveSpec(opts);
-        this.#run = opts.exec ?? runProcess;
+        this.#run = resilient(opts.exec ?? runProcess);
         this.name = containerName(this.spec);
     }
     /** Whether anything was actually started — `dispose` is free when not. */
@@ -273,6 +328,7 @@ export class Sandbox {
             truncated: res.truncated || undefined,
             timed_out: res.timedOut || undefined,
             duration_ms: Date.now() - startedAt,
+            out_of_memory: await this.#oom(res.code, res.timedOut, opts.signal),
         };
     }
     /**
@@ -353,17 +409,24 @@ export class Sandbox {
         const output = rest.join('\n---\n');
         const lines = Number(meta.lines ?? 0);
         const shown = output ? output.replace(/\n$/, '').split('\n').length : 0;
+        const exit = meta.exit === undefined ? undefined : Number(meta.exit);
+        // Kept on the job: a second read would find the kill counter unchanged
+        // and report this container's own overrun as the machine's doing.
+        if (exit === KILLED && !job.oom) {
+            job.oom = await this.#oom(exit, false);
+        }
         return {
             job_id: id,
             command: job.command,
             running: meta.exit === undefined,
-            exit_code: meta.exit === undefined ? undefined : Number(meta.exit),
+            exit_code: exit,
             duration_ms: Date.now() - job.startedAt,
             start_line: first,
             end_line: first + shown - 1,
             lines,
             truncated: first + shown - 1 < lines || undefined,
             output,
+            out_of_memory: job.oom,
         };
     }
     /** Signals a job's whole process group, so its children go too. */
@@ -422,6 +485,45 @@ export class Sandbox {
         const wanted = seconds && seconds > 0 ? seconds * 1000 : this.spec.timeout * 1000;
         return Math.min(wanted || DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS);
     }
+    /**
+     * Turns a bare 137 into a reason, by asking the container which cgroup did
+     * the killing. Only a kill counted against *this* container is the caller's
+     * to fix; the rest is the machine being busy, and telling someone to shrink
+     * a command that already fit would send them off after the wrong thing.
+     */
+    async #oom(code, timedOut, signal) {
+        // A timeout or a cancel kills podman on this side, not the container,
+        // and an uncapped container has no limit it could have exceeded.
+        if (code !== KILLED || timedOut || signal?.aborted || this.spec.memory <= 0) {
+            return undefined;
+        }
+        const res = await this.#run(this.spec.engine, ['exec', '--interactive', this.name, '/bin/sh', '-s'], { input: CGROUP, timeoutMs: 15_000 }).catch(() => undefined);
+        const out = res?.stdout ?? '';
+        const peak = Number(/peak=(\d+)/.exec(out)?.[1]);
+        const kills = Number(/kills=(\d+)/.exec(out)?.[1]);
+        const counted = Number.isFinite(kills);
+        // Nothing readable is read as our own doing: that costs one wasted
+        // retry, where the other guess costs an agent retrying forever a
+        // command that was never going to fit.
+        const own = !counted || kills > (this.#kills ?? 0);
+        if (counted) {
+            this.#kills = kills;
+        }
+        const limit = this.spec.memory;
+        return {
+            limit_mib: limit,
+            peak_mib: Number.isFinite(peak) ? Math.round(peak / (1024 * 1024)) : undefined,
+            retryable: !own,
+            hint: own
+                ? `this container is limited to ${limit} MiB and the command wanted more. ` +
+                    `Running it again unchanged will end the same way: give the sandbox more ` +
+                    `memory in the project configuration, or do the work in smaller pieces.`
+                : `the machine ran out of memory while this container was inside its ` +
+                    `${limit} MiB limit, so it was killed for something another container did. ` +
+                    `The command itself does not need to change, and may work once the machine ` +
+                    `is less busy.`,
+        };
+    }
     #podman(args) {
         return this.#run(this.spec.engine, args, { timeoutMs: 120_000 });
     }
@@ -474,6 +576,23 @@ function resolveSpec(opts) {
         engine: opts.engine ?? 'podman',
     };
 }
+/**
+ * What a spec's ceilings come to, for a report that has no container to ask.
+ *
+ * It exists so `zen sandbox status` cannot disagree with what a run actually
+ * applies: the defaults are stated once, here and in `resolveSpec`, and
+ * nothing outside this module repeats them.
+ */
+export function sandboxLimits(spec = {}) {
+    const hardening = spec.hardening ?? 'standard';
+    const strict = hardening === 'strict';
+    return {
+        memory: spec.memory ?? (strict ? STRICT_MEMORY : DEFAULT_MEMORY),
+        cpus: spec.cpus ?? (strict ? STRICT_CPUS : DEFAULT_CPUS),
+        hardening,
+        declared: spec.memory !== undefined || spec.cpus !== undefined,
+    };
+}
 /**
  * The container's name is a function of its configuration. Change the image
  * and a new container appears rather than an old one quietly persisting with
@@ -585,7 +704,7 @@ export function sandboxTools(opts) {
         group: SANDBOX_GROUP,
         description: 'Runs a shell command in a Linux container and waits for it to finish. The ' +
             `workspace is mounted at ${SANDBOX_MOUNT} and is the working directory, so files you ` +
-            'read and write here are the same files the workspace tools see. Everything ' +
+            'read and write here are the same files the file tools see. Everything ' +
             'else is throwaway. Use this for builds, tests, and package installs; use ' +
             'run_command_background for anything that does not end on its own, such as a ' +
             'server or a watcher.',

package/dist/tools/workspace.js

@@ -1,5 +1,5 @@
 import { realpathSync, statSync } from 'node:fs';
-import { mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { cp, mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { dirname, extname, join, relative, resolve, sep } from 'node:path';
 import { tool } from "../types.js";
 // ---------------------------------------------------------------------------
@@ -684,7 +684,7 @@ function patchLines(lines, chunks, file) {
             const at = findHeading(out, heading, cursor);
             if (at < 0) {
                 // A heading only narrows the search. Models invent them —
-                // `@@ class DfwRiskScanner` for a file of plain functions — and
+                // `@@ class RiskScanner` for a file of plain functions — and
                 // when the context occurs once the heading was never needed, so
                 // refusing spends a turn to learn nothing.
                 if (countMatches(out, chunk.before, cursor) === 1) {
@@ -1064,6 +1064,75 @@ export function workspaceTools(opts) {
             return { from: ws.show(source), to: ws.show(target), moved: true };
         },
     });
+    // The one mutating tool whose source may sit in a read-only tree, and the
+    // reason it earns its place: reaching a mounted file otherwise means
+    // reading it into the context and writing it back out, which costs a turn,
+    // truncates past the read cap and cannot carry a binary at all.
+    const copyPath = tool({
+        name: 'copy_file',
+        group: GROUP,
+        description: 'Copies a file, making the destination parent directories as needed. The source ' +
+            'may be in a read-only tree, so this is how something mounted for reference is ' +
+            'brought into the workspace; the destination must be writable. The bytes are ' +
+            'copied directly and are not read into the conversation, so size is no object ' +
+            'and a binary copies as faithfully as text. Refuses to clobber an existing ' +
+            'destination unless overwrite is set, and only copies a directory, with ' +
+            'everything in it, when recursive is set.',
+        parameters: {
+            type: 'object',
+            properties: {
+                from: { type: 'string', description: `What to copy. ${inside}` },
+                to: { type: 'string', description: `Where the copy should land. ${inside}` },
+                overwrite: {
+                    type: 'boolean',
+                    description: 'Replace the destination if it exists.',
+                },
+                recursive: {
+                    type: 'boolean',
+                    description: 'Required to copy a directory and its contents.',
+                },
+            },
+            required: ['from', 'to'],
+            additionalProperties: false,
+        },
+        execute: async ({ from, to, overwrite, recursive }) => {
+            ws.mutable();
+            const source = ws.within(from);
+            const target = ws.within(to, { write: true });
+            if (ws.isRoot(target)) {
+                return { error: 'refusing to overwrite the workspace root' };
+            }
+            if (source === target) {
+                return { error: 'the source and the destination are the same path' };
+            }
+            const info = await stat(source); // ENOENT here is the honest error
+            if (info.isDirectory()) {
+                if (!recursive) {
+                    return {
+                        error: `${ws.show(source)} is a directory`,
+                        hint: 'pass recursive to copy it and everything in it',
+                    };
+                }
+                if (target.startsWith(source + sep)) {
+                    return { error: `cannot copy ${ws.show(source)} into itself` };
+                }
+            }
+            if (await statOrNull(target)) {
+                if (!overwrite) {
+                    return {
+                        error: `${ws.show(target)} already exists`,
+                        hint: 'pass overwrite to replace it',
+                    };
+                }
+                // cp() will not replace a directory with a file, or the reverse.
+                await rm(target, { recursive: true, force: true });
+            }
+            await mkdir(dirname(target), { recursive: true });
+            await cp(source, target, { recursive: recursive === true });
+            const out = { from: ws.show(source), to: ws.show(target), copied: true };
+            return info.isDirectory() ? { ...out, directory: true } : { ...out, bytes: info.size };
+        },
+    });
     const deleteFile = tool({
         name: 'delete_file',
         group: GROUP,
@@ -1154,7 +1223,16 @@ export function workspaceTools(opts) {
     });
     return named(ws, opts.readOnly
         ? [readFileTool, listDir, findFiles]
-        : [readFileTool, listDir, findFiles, writeFileTool, applyPatch, movePath, deleteFile]);
+        : [
+            readFileTool,
+            listDir,
+            findFiles,
+            writeFileTool,
+            applyPatch,
+            copyPath,
+            movePath,
+            deleteFile,
+        ]);
 }
 /** What each errno means, said the way the rest of these tools say things. */
 const ERRNO = {

package/dist/trajectory.d.ts

@@ -67,7 +67,7 @@ export interface MemoryRecallNode extends NodeBase {
 }
 export interface MemoryOpNode extends NodeBase {
     type: 'memory_op';
-    op: 'commit' | 'forget' | 'load';
+    op: 'commit' | 'forget' | 'load' | 'grep';
     /** sha256(runId, callId) — deterministic, so a replay is deduplicated */
     opId: string;
     nodes: {
@@ -202,6 +202,24 @@ export declare function projected(nodes: TrajectoryNode[]): TrajectoryNode[];
  * added, since counting it too would double every branch.
  */
 export declare function totalUsage(trajectory: TrajectoryNode[]): TokenUsage;
+export interface ModelUsage {
+    /** the exact model id the call was served by, as recorded on the node */
+    model: string;
+    calls: number;
+    usage: TokenUsage;
+}
+/** A summarizer's tokens are real spend, but no node records which model burned them. */
+export declare const COMPACTION_MODEL = "(compaction)";
+/**
+ * `totalUsage`, split by the model that spent it. The same walk and the same
+ * recursion into branches, so the rows always add back up to the total — which
+ * is the point: a run that used three models must not report one number that
+ * belongs to none of them. Heaviest first, since that is the one being asked
+ * about.
+ */
+export declare function usageByModel(trajectory: TrajectoryNode[]): ModelUsage[];
+/** Folds splits together: many turns of one run, or many items of a batch. */
+export declare function mergeModelUsage(...lists: readonly (readonly ModelUsage[])[]): ModelUsage[];
 export declare function lastOfType<T extends TrajectoryNode['type']>(trajectory: TrajectoryNode[], type: T): Extract<TrajectoryNode, {
     type: T;
 }> | undefined;

package/dist/trajectory.js

@@ -47,6 +47,59 @@ export function totalUsage(trajectory) {
         return acc;
     }, zeroUsage());
 }
+/** A summarizer's tokens are real spend, but no node records which model burned them. */
+export const COMPACTION_MODEL = '(compaction)';
+/**
+ * `totalUsage`, split by the model that spent it. The same walk and the same
+ * recursion into branches, so the rows always add back up to the total — which
+ * is the point: a run that used three models must not report one number that
+ * belongs to none of them. Heaviest first, since that is the one being asked
+ * about.
+ */
+export function usageByModel(trajectory) {
+    const into = new Map();
+    collect(trajectory, into);
+    return sorted(into);
+}
+/** Folds splits together: many turns of one run, or many items of a batch. */
+export function mergeModelUsage(...lists) {
+    const into = new Map();
+    for (const list of lists) {
+        for (const one of list) {
+            fold(into, one);
+        }
+    }
+    return sorted(into);
+}
+function collect(trajectory, into) {
+    for (const n of trajectory) {
+        if (n.type === 'llm_call') {
+            fold(into, { model: n.model, calls: 1, usage: n.usage });
+        }
+        else if (n.type === 'compaction') {
+            fold(into, { model: COMPACTION_MODEL, calls: 1, usage: n.usage });
+        }
+        else if (n.type === 'join') {
+            for (const branch of n.branches) {
+                collect(branch.nodes, into);
+            }
+        }
+    }
+}
+function fold(into, one) {
+    const had = into.get(one.model);
+    into.set(one.model, had
+        ? {
+            model: had.model,
+            calls: had.calls + one.calls,
+            usage: addUsage(had.usage, one.usage),
+        }
+        : { model: one.model, calls: one.calls, usage: one.usage });
+}
+function sorted(into) {
+    const spent = (m) => m.usage.inputTokens + m.usage.outputTokens;
+    return [...into.values()].sort((a, b) => spent(b) - spent(a) || a.model.localeCompare(b.model));
+}
 export function lastOfType(trajectory, type) {
     for (let i = trajectory.length - 1; i >= 0; i--) {
         if (trajectory[i].type === type) {

package/dist/types.d.ts

@@ -184,6 +184,7 @@ export declare const HANDOFF_PREFIX = "transfer_to_";
 export declare const FORK_TOOL = "fork";
 export declare const FINAL_OUTPUT_TOOL = "final_output";
 export declare const MEMORY_SEARCH_TOOL = "memory_search";
+export declare const MEMORY_GREP_TOOL = "memory_grep";
 export declare const MEMORY_LOAD_TOOL = "memory_load";
 export declare const MEMORY_COMMIT_TOOL = "memory_commit";
 export declare const MEMORY_FORGET_TOOL = "memory_forget";

package/dist/types.js

@@ -144,6 +144,7 @@ export const HANDOFF_PREFIX = 'transfer_to_';
 export const FORK_TOOL = 'fork';
 export const FINAL_OUTPUT_TOOL = 'final_output';
 export const MEMORY_SEARCH_TOOL = 'memory_search';
+export const MEMORY_GREP_TOOL = 'memory_grep';
 export const MEMORY_LOAD_TOOL = 'memory_load';
 export const MEMORY_COMMIT_TOOL = 'memory_commit';
 export const MEMORY_FORGET_TOOL = 'memory_forget';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/neo",
-    "version": "1.1.22",
+    "version": "1.1.24",
     "description": "A multi-agent runtime for Node.js: agents, models, tools, skills, memory and an append-only trajectory.",
     "keywords": [
         "agents",