@zenera/engine 1.1.54 → 1.1.56

package/dist/engine.d.ts

@@ -1,8 +1,8 @@
-import { AgentRunner, Workspace, type AgentEvent, type AgentProject, type AgentState, type Input, type MemoryIndex, type RunIdentity, type RunResult } from '@zenera/neo';
+import { AgentRunner, Workspace, type AgentEvent, type AgentProject, type AgentState, type Input, type ResumeAnswer, type MemoryIndex, type RunIdentity, type RunResult, type SandboxFactory } from '@zenera/neo';
 import { type ModelIssue } from './audit.ts';
 import { type Logger } from './errors.ts';
-import { type Project } from './projects.ts';
 import { type ZenPlugin } from './plugins.ts';
+import { type Project } from './projects.ts';
 import { type Preflight, type SandboxSetup } from './sandbox.ts';
 import { type Held, type RunPaths, type SessionPaths } from './session.ts';
 /** Who a run acts for — re-exported so a host needs only this package. */
@@ -27,10 +27,9 @@ export interface EngineOptions {
     /** recall only: nothing is written and several runs may share one graph */
     memoryReadOnly?: boolean;
     /**
-     * An already-open graph to remember into instead of opening `memoryDir`. A
-     * memory directory is locked by whoever opens it, so a host running several
-     * sessions over one graph opens it once and hands the same index to each.
-     * Name its directory in `memoryDir` too: that is what is mounted at `/memory`.
+     * An already-open graph to remember into instead of opening `memoryDir`.
+     * Sessions may each open the same directory; handing them one index saves
+     * every session loading the graph again.
      */
     memory?: MemoryIndex;
     /** whether credentials reach the sandbox — `--no-keys` sets this false */
@@ -54,6 +53,13 @@ export interface EngineOptions {
     onIssue?: (issue: ModelIssue) => void;
     /** readies the container engine when the project can shell out; nothing when unset */
     preflight?: Preflight;
+    /**
+     * Opens the session's sandbox — where its commands run and its files
+     * live. Podman on this machine when unset, which is what `zen run` is; a
+     * host with a sandbox service passes its own, and the file tools then read
+     * the files where that sandbox keeps them.
+     */
+    newSandbox?: SandboxFactory;
     /** draws each finished run as `graph.mmd`; no graph when unset */
     graph?: GraphRenderer;
     /**
@@ -148,4 +154,11 @@ export declare function envelope(engine: Engine, outcome: RunOutcome): Record<st
  * command.
  */
 export declare function runEngine(engine: Engine, input: Input, onEvent?: (event: AgentEvent) => void, signal?: AbortSignal): Promise<RunOutcome>;
+/**
+ * Continues a session whose last run stopped `suspended`: `answers` answer its
+ * suspended calls (re-run, a result, or cancelled - see `ResumeAnswer`). The
+ * run is recorded like any other turn; its input reads as the answers given.
+ * Calls left unanswered keep it suspended.
+ */
+export declare function resumeEngine(engine: Engine, answers: Record<string, ResumeAnswer>, onEvent?: (event: AgentEvent) => void, signal?: AbortSignal): Promise<RunOutcome>;
 //# sourceMappingURL=engine.d.ts.map

package/dist/engine.js

@@ -1,4 +1,4 @@
-import { AgentRunner, FilePayloadStore, SANDBOX_MOUNT, SKILLS_MOUNT, Workspace, assertState, buildRunReport, compactIdentity, exaTools, fileTools, identityFromEnv, identityTools, lastText, loadProject, memoryDir, readProjectConfig, renderReportHtml, sandboxTools, turns, } from '@zenera/neo';
+import { AgentRunner, FilePayloadStore, MemoryError, SKILLS_MOUNT, Workspace, assertState, buildRunReport, compactIdentity, exaTools, fileTools, identityFromEnv, identityTools, 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,8 @@ import { loadProjectEnv } from "./env.js";
 import { EXIT, EngineError, invalidError, stderrLogger, usageError, } from "./errors.js";
 import { readJson, writeJson } from "./home.js";
 import { KeyStore, assertUsable } from "./keys.js";
-import { projectMounts } from "./projects.js";
 import { envPlugins, loadPlugins, mergePlugins, } from "./plugins.js";
+import { projectMounts } from "./projects.js";
 import { buildSandbox, prepareHome, teardown, usesSandbox, } from "./sandbox.js";
 import { acquire, createRun, readSessionMeta, writeRunMeta, writeSessionMeta, } from "./session.js";
 /**
@@ -52,7 +52,7 @@ export async function openEngine(opts) {
     // 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 setup;
     let project;
     let files;
     let memory;
@@ -66,8 +66,8 @@ export async function openEngine(opts) {
         }
         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({
+        const mounts = projectMounts(root, config);
+        setup = buildSandbox({
             config,
             root,
             session: opts.session,
@@ -78,14 +78,15 @@ export async function openEngine(opts) {
             env: env?.names,
             mounts,
             identity: user,
+            newSandbox: opts.newSandbox,
             ...(opts.disposable ? { persist: false } : {}),
         });
-        const workspaceOptions = {
+        const workspaceOptions = setup.sandbox.files({
             root: workspace,
             readOnly: opts.readOnly,
-            mount: sandbox.spec.workdir ?? SANDBOX_MOUNT,
+            mount: setup.workdir,
             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);
@@ -94,7 +95,7 @@ export async function openEngine(opts) {
             // one name for it: whatever `run_command` prints a path as,
             // `read_file` accepts.
             ...fileTools(workspaceOptions),
-            ...sandboxTools(sandbox.pool),
+            ...sandboxTools(setup.sandbox),
             // 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
@@ -113,12 +114,12 @@ export async function openEngine(opts) {
             memoryDir: opts.memoryDir,
             memoryReadOnly: opts.memoryReadOnly,
             payloads,
-            resolveFile: (path) => files.within(path),
+            files,
         });
     }
     catch (err) {
         await plugins?.close();
-        throw invalidError(err instanceof Error ? err.message : String(err), `while loading ${opts.project.dir}`);
+        throw invalidError(err instanceof Error ? err.message : String(err), err instanceof MemoryError && err.hint ? err.hint : `while loading ${opts.project.dir}`);
     }
     const loaded = plugins;
     let state;
@@ -129,8 +130,8 @@ export async function openEngine(opts) {
         // 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);
+            prepareHome(setup);
+            await opts.preflight?.(setup, 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
@@ -155,18 +156,18 @@ export async function openEngine(opts) {
         runner,
         name: opts.project.name,
         workspace,
-        workspaceMount: sandbox.spec.workdir ?? SANDBOX_MOUNT,
+        workspaceMount: setup.workdir,
         files,
         readOnly: Boolean(opts.readOnly),
         session: opts.session,
         memory,
         state,
-        sandbox,
+        sandbox: setup,
         lock,
         graph: opts.graph,
         user,
         close: async () => {
-            await teardown(sandbox.pool, logger);
+            await teardown(setup, logger);
             // A host-supplied graph is the host's to release.
             if (!opts.memory) {
                 project.close();
@@ -275,6 +276,35 @@ export async function runEngine(engine, input, onEvent, signal) {
     }
     return outcome;
 }
+/**
+ * Continues a session whose last run stopped `suspended`: `answers` answer its
+ * suspended calls (re-run, a result, or cancelled - see `ResumeAnswer`). The
+ * run is recorded like any other turn; its input reads as the answers given.
+ * Calls left unanswered keep it suspended.
+ */
+export async function resumeEngine(engine, answers, onEvent, signal) {
+    if (!engine.state?.suspended?.length) {
+        throw usageError('this session is not waiting on anything to resume');
+    }
+    const startedAt = new Date();
+    const stream = engine.runner.resume(engine.state, { answers, 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 input = `(resumed: ${Object.entries(answers)
+        .map(([id, a]) => `${id} ${a.status}`)
+        .join(', ')})`;
+    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

package/dist/projects.d.ts

@@ -1,4 +1,4 @@
-import { type ProjectConfig, type SandboxMount } from '@zenera/neo';
+import { type ProjectConfig, type Mount } from '@zenera/neo';
 /** Whether a directory is a project: whether the loader has something to read. */
 export declare function isProjectDir(dir: string): boolean;
 /** A project resolved on disk. */
@@ -16,7 +16,7 @@ export interface Project {
  * and does not edit — and the paths are resolved, because the podman machine on
  * macOS shares the real path or nothing.
  */
-export declare function projectMounts(root: string, config: ProjectConfig, memoryAt?: string): SandboxMount[];
+export declare function projectMounts(root: string, config: ProjectConfig): Mount[];
 /** Walks up from `start` looking for a project configuration. */
 export declare function findUp(start: string): Promise<Project | undefined>;
 export declare function openDir(dir: string): Promise<Project>;

package/dist/projects.js

@@ -1,5 +1,5 @@
-import { ASSETS_MOUNT, assetsDir, FILES_DIR, MEMORY_MOUNT, memoryDir, pidAlive, skillDirs, skillMounts, SKILLS_MOUNT, } from '@zenera/neo';
-import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
+import { ASSETS_MOUNT, assetsDir, pidAlive, skillDirs, skillMounts, SKILLS_MOUNT, } from '@zenera/neo';
+import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
 import { invalidError, usageError } from "./errors.js";
 import { paths, readJson, writeJson } from "./home.js";
@@ -35,25 +35,27 @@ export function isProjectDir(dir) {
  * and does not edit — and the paths are resolved, because the podman machine on
  * macOS shares the real path or nothing.
  */
-export function projectMounts(root, config, memoryAt) {
+export function projectMounts(root, config) {
     const mounts = [];
     const assets = assetsDir(root, config);
     if (assets) {
-        mounts.push({ host: realpathSync(assets), at: ASSETS_MOUNT, readOnly: true });
+        mounts.push({
+            host: realpathSync(assets),
+            at: ASSETS_MOUNT,
+            readOnly: true,
+            source: { kind: 'assets' },
+        });
     }
     // The catalog goes in whole, at fixed names, before anything is loaded: a
     // container's mounts are decided when it is created, so a skill folder
     // cannot be added at the moment `skill_load` asks for it.
     for (const dir of skillMounts(skillDirs(root, config), SKILLS_MOUNT)) {
-        mounts.push({ host: realpathSync(dir.path), at: dir.at, readOnly: true });
-    }
-    const memory = memoryDir(root, config, memoryAt);
-    if (memory) {
-        // Created here because the mount is decided before the project is
-        // loaded, and podman would refuse a source that does not exist yet.
-        const files = join(memory, FILES_DIR);
-        mkdirSync(files, { recursive: true });
-        mounts.push({ host: realpathSync(files), at: MEMORY_MOUNT, readOnly: true });
+        mounts.push({
+            host: realpathSync(dir.path),
+            at: dir.at,
+            readOnly: true,
+            source: { kind: 'skills' },
+        });
     }
     return mounts;
 }

package/dist/sandbox.d.ts

@@ -1,18 +1,21 @@
-import { SandboxPool, type AgentProject, type ProjectConfig, type RunIdentity, type SandboxMount, type SandboxSpec } from '@zenera/neo';
+import { type AgentProject, type ProjectConfig, type RunIdentity, type Sandbox, type SandboxFactory, type Mount, type SandboxSpec } from '@zenera/neo';
 import { type Logger } from './errors.ts';
 import { type ResolvedBuild } from './image.ts';
 import type { SessionPaths } from './session.ts';
 export interface SandboxSetup {
-    pool: SandboxPool;
+    /** where the session's commands run, and the files they see; podman for `zen run` */
+    sandbox: Sandbox;
     /** the resolved base spec, for `zn sandbox status` and the image pre-warm */
     spec: SandboxSpec;
+    /** where the workspace is in the sandbox, and so the name the file tools answer with */
+    workdir: string;
     image: string;
     /** the Dockerfile behind `image`, when it came from one */
     build?: ResolvedBuild;
     /** host side of the container's `$HOME`, created only if it is ever needed */
     home: string;
     /** every tree bound into the container besides the workspace itself */
-    mounts: readonly SandboxMount[];
+    mounts: readonly Mount[];
 }
 export interface SandboxInputs {
     config: ProjectConfig;
@@ -26,7 +29,7 @@ export interface SandboxInputs {
      * and its skill catalog. The same array goes to the file tools, so a path
      * a command prints is a path `read_file` accepts.
      */
-    mounts?: readonly SandboxMount[];
+    mounts?: readonly Mount[];
     /** `--image` */
     image?: string;
     /** `--no-keys`: refuse to forward credentials, whatever the config says */
@@ -40,13 +43,15 @@ export interface SandboxInputs {
      * promise it does not keep.
      */
     env?: readonly string[];
-    /** `false` overrides every `persist:` in the config, the agents' included */
+    /** `false` overrides the config's `persist:` */
     persist?: boolean;
     /**
      * Who the run is acting for. Set on every command as `ZEN_USER_*`, never
      * on the container — see `execEnv` in the library for why.
      */
     identity?: RunIdentity;
+    /** opens the sandbox; podman on this machine when unset */
+    newSandbox?: SandboxFactory;
 }
 export declare function buildSandbox(opts: SandboxInputs): SandboxSetup;
 /**
@@ -67,12 +72,17 @@ export type Preflight = (setup: SandboxSetup, yes?: boolean) => Promise<void>;
 /**
  * Where the container's `$HOME` lives must exist before podman mounts it — and
  * the `zenera` libraries go into it, written fresh on every open so they match
- * the engine that set the variables they read.
+ * the engine that set the variables they read. Done for every sandbox: it is a
+ * small copy into the session folder, and a sandbox that does not bind it
+ * supplies its own `$HOME` (`source: home`) with the same libraries.
  */
 export declare function prepareHome(setup: SandboxSetup): void;
 /** Where each one lands, inside the container. */
 export declare const RUNTIME_PYTHON = "/home/agent/.zenera/python";
 export declare const RUNTIME_NODE = "/home/agent/.node_modules/zenera";
-/** Best-effort teardown: losing a container must never lose a run. */
-export declare function teardown(pool: SandboxPool, logger?: Logger): Promise<void>;
+/**
+ * Best-effort teardown: losing a container must never lose a run. Closing is
+ * also where a sandbox that keeps its files elsewhere persists them.
+ */
+export declare function teardown(setup: SandboxSetup, logger?: Logger): Promise<void>;
 //# sourceMappingURL=sandbox.d.ts.map

package/dist/sandbox.js

@@ -1,4 +1,4 @@
-import { DEFAULT_SANDBOX_IMAGE, GATEWAY_URL_ENV, SANDBOX_GROUP, SandboxPool, identityEnv, isIdentityEnv, } from '@zenera/neo';
+import { DEFAULT_SANDBOX_IMAGE, GATEWAY_URL_ENV, SANDBOX_GROUP, WORKSPACE_MOUNT, identityEnv, podmanSandbox, isIdentityEnv, } from '@zenera/neo';
 import { cpSync, mkdirSync, rmSync } from 'node:fs';
 import { basename, join, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -48,7 +48,12 @@ function forwarded() {
     for (const cred of credentials()) {
         if (cred.holds === 'file') {
             const at = `${KEY_MOUNT}/${basename(cred.value)}`;
-            mounts.push({ host: cred.value, at, readOnly: true });
+            mounts.push({
+                host: cred.value,
+                at,
+                readOnly: true,
+                source: { kind: 'credential', name: cred.env },
+            });
             env[cred.env] = at;
             continue;
         }
@@ -75,7 +80,10 @@ export function buildSandbox(opts) {
         ...(opts.persist === false ? { persist: false } : {}),
     };
     const home = join(opts.session.data, 'sandbox', 'home');
-    const mounts = [{ host: home, at: HOME }, ...(opts.mounts ?? [])];
+    const mounts = [
+        { host: home, at: HOME, source: { kind: 'home' } },
+        ...(opts.mounts ?? []),
+    ];
     const keys = base.keys === false ? undefined : forwarded();
     if (keys) {
         mounts.push(...keys.mounts);
@@ -86,24 +94,8 @@ export function buildSandbox(opts) {
     // `ZENERA_AGENT` tells a `zen` run by `run_command` that no person is there.
     const extra = { HOME, PYTHONDONTWRITEBYTECODE: '1', ZENERA_AGENT: '1', ...(keys?.env ?? {}) };
     const spec = toSpec(base, extra, secretsOf(keys?.secrets, opts.env));
-    const agents = {};
-    for (const agent of opts.config.agents) {
-        if (agent.sandbox) {
-            const merged = merge(base, agent.sandbox);
-            if (opts.persist === false) {
-                merged.persist = false;
-            }
-            // An agent that opts out gets neither the variables nor the mount,
-            // but the mount is on the pool and cannot be taken back per agent —
-            // so the variable is what actually decides, and without it the file
-            // sitting there is not a credential anything will look for.
-            const own = merged.keys === false ? undefined : keys;
-            agents[agent.name] = toSpec(merged, { HOME, PYTHONDONTWRITEBYTECODE: '1', ZENERA_AGENT: '1', ...(own?.env ?? {}) }, own && secretsOf(own.secrets, opts.env));
-        }
-    }
-    const pool = new SandboxPool({
+    const sandbox = (opts.newSandbox ?? podmanSandbox)({
         ...spec,
-        agents,
         root: opts.workspace,
         key: opts.session.id,
         readOnly: opts.readOnly,
@@ -111,23 +103,15 @@ export function buildSandbox(opts) {
         execEnv: identityEnv(opts.identity),
         execPaths: RUNTIME_PATHS,
     });
-    return { pool, spec, image: spec.image ?? DEFAULT_SANDBOX_IMAGE, build, home, mounts };
-}
-/**
- * An agent's overrides on the project's block. `image` and `build` answer the
- * same question, so naming either one drops the other: a plain spread would
- * leave an agent's `image` sitting next to the project's `build`, and the
- * schema forbids exactly that combination when it is written down.
- */
-function merge(base, agent) {
-    const merged = { ...base, ...agent };
-    if (agent.image !== undefined) {
-        delete merged.build;
-    }
-    if (agent.build !== undefined) {
-        delete merged.image;
-    }
-    return merged;
+    return {
+        sandbox,
+        spec,
+        workdir: spec.workdir ?? WORKSPACE_MOUNT,
+        image: spec.image ?? DEFAULT_SANDBOX_IMAGE,
+        build,
+        home,
+        mounts,
+    };
 }
 /**
  * The two sources of forwarded names, as one list: the credentials the keyring
@@ -189,7 +173,9 @@ export function usesSandbox(project) {
 /**
  * Where the container's `$HOME` lives must exist before podman mounts it — and
  * the `zenera` libraries go into it, written fresh on every open so they match
- * the engine that set the variables they read.
+ * the engine that set the variables they read. Done for every sandbox: it is a
+ * small copy into the session folder, and a sandbox that does not bind it
+ * supplies its own `$HOME` (`source: home`) with the same libraries.
  */
 export function prepareHome(setup) {
     mkdirSync(setup.home, { recursive: true });
@@ -226,10 +212,13 @@ function installRuntime(home) {
         cpSync(join(RUNTIME_SOURCE, from), target, { recursive: true });
     }
 }
-/** Best-effort teardown: losing a container must never lose a run. */
-export async function teardown(pool, logger = stderrLogger) {
+/**
+ * Best-effort teardown: losing a container must never lose a run. Closing is
+ * also where a sandbox that keeps its files elsewhere persists them.
+ */
+export async function teardown(setup, logger = stderrLogger) {
     try {
-        await pool.dispose();
+        await setup.sandbox.close();
     }
     catch (err) {
         logger.warn(`could not clean up the sandbox: ${err instanceof Error ? err.message : String(err)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/engine",
-    "version": "1.1.54",
+    "version": "1.1.56",
     "description": "Runs a @zenera/neo project on this machine: keyring, sandbox, sessions and the record each turn leaves behind.",
     "keywords": [
         "agents",
@@ -45,6 +45,6 @@
         "prepack": "tsc -b"
     },
     "dependencies": {
-        "@zenera/neo": "^1.1.54"
+        "@zenera/neo": "^1.1.56"
     }
 }