@zenera/engine 1.1.55 → 1.1.57

package/README.md

@@ -41,10 +41,31 @@ const lookup: ZenPlugin = {
 const engine = await openEngine({ project, session, user, plugins: [lookup] });
 ```
 
+A plugin can also say where the sandbox runs: `sandbox(ctx)` returns a `SandboxProvider`
+(`describe`, `newSandbox`, and optionally `status` and `clean` for `zen sandbox`), or nothing.
+The engine asks before it builds the sandbox, with the project, session, user and the project's
+`sandbox:` block. At most one plugin may answer; podman on this machine is used when none does.
+`newSandbox` passed to `openEngine` beats any plugin, and `sandboxPlugins: false` (`zen run
+--podman`) ignores them. A plugin may provide only a sandbox, with no `tools`:
+
+```ts
+const service: ZenPlugin = {
+    name: 'zenera-sandbox',
+    sandbox: ({ session }) => ({
+        describe: 'zenera-sandbox (https://sandbox.example)',
+        newSandbox: (opts) => new RemoteSandbox(opts, session),
+    }),
+};
+```
+
+The engine's `preflight` still runs; a host that wants the image ready before the first turn calls
+`setup.sandbox.prepare()` there (`allowBuild: false` when images are built elsewhere).
+
 A `zen` nobody embeds (the CLI, `zen check`, a job) loads the plugins the machine names instead:
 `ZEN_PLUGINS` is a comma-separated list of absolute paths to ES modules whose default export is a
 `ZenPlugin`. It is read from the real environment when the engine is first imported; a project's
-`.env` cannot set it. An embedding host gets them too, unless it passes a plugin of the same name or
+`.env` cannot set it, nor `ZEN_SANDBOX_*`, which a sandbox plugin reads its service and credential
+from. An embedding host gets them too, unless it passes a plugin of the same name or
 `envPlugins: false`.
 
 ## Use

package/dist/engine.d.ts

@@ -1,4 +1,4 @@
-import { AgentRunner, Workspace, type AgentEvent, type AgentProject, type AgentState, type Input, type ResumeAnswer, 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 ZenPlugin } from './plugins.ts';
@@ -30,7 +30,6 @@ export interface EngineOptions {
      * 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.
-     * Name its directory in `memoryDir` too: that is what is mounted at `/memory`.
      */
     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;
     /**
@@ -78,6 +84,11 @@ export interface EngineOptions {
     plugins?: ZenPlugin[];
     /** false: ignore `ZEN_PLUGINS` and use only `plugins` */
     envPlugins?: boolean;
+    /**
+     * false: a plugin that provides the sandbox is not asked, and podman on
+     * this machine is used — `zen run --podman`. Its tools still load.
+     */
+    sandboxPlugins?: boolean;
 }
 export interface Engine {
     project: AgentProject;

package/dist/engine.js

@@ -1,4 +1,4 @@
-import { AgentRunner, FilePayloadStore, MemoryError, 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,7 +8,7 @@ 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 { envPlugins, loadPlugins, mergePlugins, } from "./plugins.js";
+import { envPlugins, loadPlugins, mergePlugins, resolveSandboxProvider, } 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";
@@ -32,7 +32,9 @@ export async function openEngine(opts) {
         logger.warn(`${env.path} sets ${env.refused.join(', ')} — ignored: who a run acts for, and ` +
             'which plugins load, are the host’s to say (zen run --as <user> to try one)');
     }
-    const hostPlugins = mergePlugins(opts.plugins ?? [], machinePlugins);
+    // Closed at most once each: a provider is asked before the tools are, and
+    // an open that fails in between must not close it twice.
+    const hostPlugins = mergePlugins(opts.plugins ?? [], machinePlugins).map(closingOnce);
     const keys = await KeyStore.open();
     keys.materialize();
     assertUsable(keys);
@@ -52,13 +54,26 @@ 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;
     let plugins;
+    let providedBy;
     try {
         const { root, config } = readProjectConfig(opts.project.dir);
+        // Where the sandbox runs is settled before anything is built on it:
+        // the host's own factory, else a plugin's, else podman here.
+        const chosen = opts.newSandbox || opts.sandboxPlugins === false
+            ? undefined
+            : await resolveSandboxProvider(hostPlugins, {
+                project: opts.project,
+                session: opts.session,
+                user,
+                config: config.sandbox,
+                logger,
+            });
+        providedBy = chosen?.plugin;
         // Naming a directory declares the graph, but it cannot bind anyone to
         // it — so say when the run is pointed at a memory no agent will touch.
         if (opts.memoryDir && !opts.quiet && !config.agents.some((a) => a.memory)) {
@@ -66,8 +81,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 +93,16 @@ export async function openEngine(opts) {
             env: env?.names,
             mounts,
             identity: user,
+            newSandbox: opts.newSandbox ?? chosen?.provider.newSandbox,
+            provider: opts.newSandbox ? 'the host' : chosen?.provider.describe,
             ...(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 +111,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,11 +130,11 @@ export async function openEngine(opts) {
             memoryDir: opts.memoryDir,
             memoryReadOnly: opts.memoryReadOnly,
             payloads,
-            resolveFile: (path) => files.within(path),
+            files,
         });
     }
     catch (err) {
-        await plugins?.close();
+        await (plugins ? plugins.close() : closeQuietly(providedBy, logger));
         throw invalidError(err instanceof Error ? err.message : String(err), err instanceof MemoryError && err.hint ? err.hint : `while loading ${opts.project.dir}`);
     }
     const loaded = plugins;
@@ -129,8 +146,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 +172,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();
@@ -176,6 +193,24 @@ export async function openEngine(opts) {
         },
     };
 }
+/** A plugin whose `close` runs once, however many paths reach it. */
+function closingOnce(plugin) {
+    let closing;
+    return {
+        name: plugin.name,
+        ...(plugin.tools ? { tools: (ctx) => plugin.tools(ctx) } : {}),
+        ...(plugin.sandbox ? { sandbox: (ctx) => plugin.sandbox(ctx) } : {}),
+        close: () => (closing ??= Promise.resolve(plugin.close?.())),
+    };
+}
+async function closeQuietly(plugin, logger) {
+    try {
+        await plugin?.close?.();
+    }
+    catch (err) {
+        logger.warn(`plugin ${plugin?.name}: close failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
 /**
  * The identity a run acts for: what the host said, or — when it said nothing —
  * what the environment carries, which is never more than `local`. Validated

package/dist/env.d.ts

@@ -17,7 +17,8 @@ export interface ProjectEnv {
      * Names the file declared and was not allowed to: `ZEN_USER_*` says who a
      * run is acting for, and only the host gets to say that. A project that
      * could set it in a committed file could be anyone it liked. `ZEN_PLUGINS`
-     * names code to run inside the engine's process, with its credentials.
+     * names code to run inside the engine's process, with its credentials, and
+     * `ZEN_SANDBOX_*` the service a sandbox — and the user's work — goes to.
      */
     refused: string[];
 }

package/dist/env.js

@@ -1,4 +1,4 @@
-import { isIdentityEnv } from '@zenera/neo';
+import { isHostOnlyEnv } from '@zenera/neo';
 import { existsSync, readFileSync } from 'node:fs';
 import { isAbsolute, resolve } from 'node:path';
 import { parseEnv } from 'node:util';
@@ -47,7 +47,7 @@ export function readProjectEnv(dir) {
     const values = {};
     const refused = [];
     for (const [name, value] of Object.entries(parseEnv(readFileSync(path, 'utf8')))) {
-        if (isIdentityEnv(name) || name === PLUGINS_ENV) {
+        if (isHostOnlyEnv(name) || name === PLUGINS_ENV) {
             refused.push(name);
         }
         else if (value !== undefined) {

package/dist/image.d.ts

@@ -1,16 +1,12 @@
-import { type SandboxConfig } from '@zenera/neo';
-export interface ResolvedBuild {
-    /** the image reference to run, and to build under */
+import { type BuildIdentity, type BuildSpec, type SandboxConfig } from '@zenera/neo';
+export interface ResolvedBuild extends BuildSpec, BuildIdentity {
+    /** the tag it runs under on this machine */
     tag: string;
-    /** absolute path to the Dockerfile */
-    dockerfile: string;
-    /** absolute path to the build context */
-    context: string;
 }
 /**
  * What the config's `build:` block means on this machine, or nothing if it has
  * none. Both paths are resolved against the project root and refused if they
- * escape it — a project is data someone else may have written.
+ * escape it.
  */
 export declare function resolveBuild(root: string, config?: SandboxConfig): ResolvedBuild | undefined;
 //# sourceMappingURL=image.d.ts.map

package/dist/image.js

@@ -1,34 +1,9 @@
-import { projectDir, projectFile } from '@zenera/neo';
-import { createHash } from 'node:crypto';
-import { readFileSync, readdirSync } from 'node:fs';
-import { dirname, join, relative, sep } from 'node:path';
-// ---------------------------------------------------------------------------
-// Building the sandbox image
-//
-// `image:` names something to pull; `build:` names a Dockerfile to build. The
-// library never learns the difference — it is handed a resolved reference and
-// runs it — because building is a host concern with a container engine
-// attached to it, and that is the line this CLI exists on the other side of.
-//
-// The tag is a function of what goes into the image, and it has to be: the
-// container's name in @zenera/neo hashes `spec.image`, so a tag that stayed put
-// while the Dockerfile changed would leave a `persist: true` container running
-// last week's filesystem, with nothing anywhere saying so. Hashing the context
-// as well as the Dockerfile means an edit to either yields a new tag, a new
-// container name, and a build — which is the only honest answer.
-// ---------------------------------------------------------------------------
-/** Not scoped: a `/` or an `@` is not a legal image tag. */
-const TAG = 'localhost/zenera-sandbox';
-/**
- * A build context is meant to be small — a Dockerfile and whatever it copies.
- * Hashing a directory someone pointed at their whole home folder would hang
- * before it was wrong, so it stops and says which key to narrow.
- */
-const MAX_CONTEXT_FILES = 2_000;
+import { buildIdentity, localImageTag, projectDir, projectFile, } from '@zenera/neo';
+import { dirname } from 'node:path';
 /**
  * What the config's `build:` block means on this machine, or nothing if it has
  * none. Both paths are resolved against the project root and refused if they
- * escape it — a project is data someone else may have written.
+ * escape it.
  */
 export function resolveBuild(root, config) {
     if (!config?.build) {
@@ -38,48 +13,8 @@ export function resolveBuild(root, config) {
     const context = config.build.context
         ? projectDir(root, config.build.context, 'sandbox.build.context')
         : dirname(dockerfile);
-    return { tag: `${TAG}:${digest(dockerfile, context)}`, dockerfile, context };
-}
-/**
- * The content address of a build: the Dockerfile, then every file the build can
- * see, by path and by content.
- *
- * `.dockerignore` is not read. The engine honours it and we do not, so an
- * ignored file that changes yields a new tag and a build that produces the same
- * image — wasteful, never wrong, and the alternative is reimplementing a match
- * syntax whose disagreements would be silent.
- */
-function digest(dockerfile, context) {
-    const hash = createHash('sha256');
-    hash.update(readFileSync(dockerfile));
-    for (const rel of walk(context)) {
-        // The separator is hashed as posix so the same tree tags the same on
-        // any host.
-        hash.update(`\0${rel.split(sep).join('/')}\0`);
-        hash.update(readFileSync(join(context, rel)));
-    }
-    return hash.digest('hex').slice(0, 12);
-}
-/** Every file under `dir`, relative and sorted, so the digest is stable. */
-function walk(dir) {
-    const found = [];
-    const pending = [dir];
-    while (pending.length > 0) {
-        const at = pending.pop();
-        for (const entry of readdirSync(at, { withFileTypes: true })) {
-            const path = join(at, entry.name);
-            if (entry.isDirectory()) {
-                pending.push(path);
-            }
-            else if (entry.isFile()) {
-                found.push(relative(dir, path));
-            }
-        }
-        if (found.length > MAX_CONTEXT_FILES) {
-            throw new Error(`sandbox.build.context: ${dir} holds more than ${MAX_CONTEXT_FILES} files — ` +
-                'point `context:` at the directory the build actually copies from');
-        }
-    }
-    return found.sort();
+    const spec = { dockerfile, context };
+    const id = buildIdentity(spec);
+    return { ...spec, ...id, tag: localImageTag(id) };
 }
 //# sourceMappingURL=image.js.map

package/dist/plugins.d.ts

@@ -1,4 +1,4 @@
-import type { AnyTool, RunIdentity } from '@zenera/neo';
+import type { AnyTool, RunIdentity, SandboxConfig, SandboxFactory } from '@zenera/neo';
 import type { Logger } from './errors.ts';
 import type { SessionPaths } from './session.ts';
 /** What a plugin needs to write a tool — re-exported so a host needs only this package. */
@@ -19,10 +19,57 @@ export interface ZenPlugin {
     /** for error messages: which plugin a tool or a failure came from */
     name: string;
     /** Called once when the engine opens. May return nothing, which adds nothing. */
-    tools(ctx: PluginContext): AnyTool[] | Promise<AnyTool[]>;
+    tools?(ctx: PluginContext): AnyTool[] | Promise<AnyTool[]>;
+    /**
+     * Where this run's sandbox lives, when not in podman on this machine.
+     * Asked once when the engine opens, before anything else; nothing means
+     * "not mine to say". At most one plugin may answer.
+     */
+    sandbox?(ctx: SandboxContext): SandboxProvider | undefined | Promise<SandboxProvider | undefined>;
     /** Called when the engine closes, or when it fails to open after the plugin was asked. */
     close?(): void | Promise<void>;
 }
+/** What a plugin is told when it is asked where the sandbox runs. */
+export interface SandboxContext {
+    project: {
+        dir: string;
+        name: string;
+    };
+    /** the session the sandbox is for; absent when a project is only checked */
+    session?: SessionPaths;
+    /** who the run acts for, when anyone */
+    user?: RunIdentity;
+    /** the project's `sandbox:` block, as written */
+    config: SandboxConfig | undefined;
+    logger: Logger;
+}
+/** A plugin's answer: where sandboxes are opened, and how to report on them. */
+export interface SandboxProvider {
+    /** for people: `zenera-sandbox (http://localhost:7080)` */
+    describe: string;
+    newSandbox: SandboxFactory;
+    /** what `zen sandbox status` prints for it */
+    status?(): Promise<SandboxStatusReport>;
+    /** what `zen sandbox clean` does for it; returns what it removed */
+    clean?(opts: {
+        all?: boolean;
+    }): Promise<string[]>;
+}
+export interface SandboxStatusReport {
+    /** whether a sandbox could be opened right now */
+    ready: boolean;
+    /** one line each, for a person */
+    lines: string[];
+}
+/**
+ * The provider among `plugins`, if any. Two answers is an error rather than a
+ * choice: which one wins would be an accident of the order the machine listed
+ * them in, and the loser's users would never know their sandbox moved.
+ */
+export declare function resolveSandboxProvider(plugins: readonly ZenPlugin[], ctx: SandboxContext): Promise<{
+    provider: SandboxProvider;
+    plugin: ZenPlugin;
+} | undefined>;
 export interface LoadedPlugins {
     tools: AnyTool[];
     /** Closes every plugin that was asked for tools, latest first. Never throws: failures are warnings. */
@@ -55,4 +102,17 @@ export declare function machinePluginTools(project: {
     dir: string;
     name: string;
 }, builtins: readonly AnyTool[], logger: Logger): Promise<AnyTool[]>;
+/**
+ * The sandbox provider the machine's plugins name, for checking a project
+ * rather than running it: asked with no user and no session. The caller closes
+ * the plugin once it is done with the provider. A plugin that fails is a
+ * warning, and podman is used.
+ */
+export declare function machineSandboxProvider(project: {
+    dir: string;
+    name: string;
+}, config: SandboxConfig | undefined, logger: Logger): Promise<{
+    provider: SandboxProvider;
+    plugin: ZenPlugin;
+} | undefined>;
 //# sourceMappingURL=plugins.d.ts.map

package/dist/plugins.js

@@ -10,6 +10,38 @@ import { isAbsolute } from 'node:path';
 import { pathToFileURL } from 'node:url';
 /** What a plugin needs to write a tool — re-exported so a host needs only this package. */
 export { tool } from '@zenera/neo';
+/**
+ * The provider among `plugins`, if any. Two answers is an error rather than a
+ * choice: which one wins would be an accident of the order the machine listed
+ * them in, and the loser's users would never know their sandbox moved.
+ */
+export async function resolveSandboxProvider(plugins, ctx) {
+    let found;
+    for (const plugin of plugins) {
+        if (!plugin.sandbox) {
+            continue;
+        }
+        let provider;
+        try {
+            provider = await plugin.sandbox(ctx);
+        }
+        catch (err) {
+            throw new Error(`plugin ${plugin.name}: ${message(err)}`);
+        }
+        if (!provider) {
+            continue;
+        }
+        if (typeof provider.newSandbox !== 'function') {
+            throw new Error(`plugin ${plugin.name}: its sandbox provider has no newSandbox`);
+        }
+        if (found) {
+            throw new Error(`plugins ${found.plugin.name} and ${plugin.name} both provide the sandbox — ` +
+                'remove one of them from ZEN_PLUGINS');
+        }
+        found = { provider, plugin };
+    }
+    return found;
+}
 /**
  * Asks each plugin for its tools and checks them against the built-ins and each
  * other. When a plugin fails or a check does, the plugins already asked are
@@ -44,7 +76,7 @@ export async function loadPlugins(plugins, ctx, builtins) {
             asked.push(plugin);
             let given;
             try {
-                given = (await plugin.tools(ctx)) ?? [];
+                given = (await plugin.tools?.(ctx)) ?? [];
             }
             catch (err) {
                 throw new Error(`plugin ${name}: ${message(err)}`);
@@ -120,8 +152,11 @@ export async function importPlugins(list, logger) {
         try {
             const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(path).href)));
             const plugin = mod.default;
-            if (!plugin || typeof plugin.name !== 'string' || typeof plugin.tools !== 'function') {
-                logger.warn(`${PLUGINS_ENV}: ${path} has no default export with a name and tools() — ignored`);
+            const usable = plugin &&
+                typeof plugin.name === 'string' &&
+                (typeof plugin.tools === 'function' || typeof plugin.sandbox === 'function');
+            if (!usable || !plugin) {
+                logger.warn(`${PLUGINS_ENV}: ${path} has no default export with a name and tools() or sandbox() — ignored`);
                 continue;
             }
             plugins.push(plugin);
@@ -159,4 +194,19 @@ export async function machinePluginTools(project, builtins, logger) {
     }
     return tools;
 }
+/**
+ * The sandbox provider the machine's plugins name, for checking a project
+ * rather than running it: asked with no user and no session. The caller closes
+ * the plugin once it is done with the provider. A plugin that fails is a
+ * warning, and podman is used.
+ */
+export async function machineSandboxProvider(project, config, logger) {
+    try {
+        return await resolveSandboxProvider(await envPlugins(logger), { project, config, logger });
+    }
+    catch (err) {
+        logger.warn(`${PLUGINS_ENV}: ${message(err)} — the sandbox is checked in podman`);
+        return undefined;
+    }
+}
 //# sourceMappingURL=plugins.js.map

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,23 @@
-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[];
+    /** where it runs, for people: `podman (this machine)`, or what a plugin calls itself */
+    provider: string;
 }
 export interface SandboxInputs {
     config: ProjectConfig;
@@ -26,7 +31,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,15 +45,21 @@ 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;
+    /** what to call whatever `newSandbox` opens */
+    provider?: string;
 }
 export declare function buildSandbox(opts: SandboxInputs): SandboxSetup;
+/** How the default sandbox is described. */
+export declare const PODMAN_PROVIDER = "podman (this machine)";
 /**
  * Whether anything in this project can reach a shell.
  *
@@ -67,12 +78,22 @@ 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;
+/**
+ * The packaged sources, beside `src/` and `dist/` alike — also `@zenera/engine/runtime/*`,
+ * for a sandbox that puts them in its image rather than in a bound `$HOME`.
+ */
+export declare const RUNTIME_SOURCE: string;
 /** 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, isHostOnlyEnv, } 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;
         }
@@ -70,12 +75,15 @@ export function buildSandbox(opts) {
     const build = opts.image ? undefined : resolveBuild(opts.root, opts.config.sandbox);
     const base = {
         ...(opts.config.sandbox ?? {}),
-        ...((opts.image ?? build?.tag) ? { image: opts.image ?? build?.tag } : {}),
+        ...(opts.image ? { image: opts.image } : {}),
         ...(opts.keys === false ? { keys: false } : {}),
         ...(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,11 @@ 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));
-        }
+    if (build) {
+        spec.build = { dockerfile: build.dockerfile, context: build.context };
     }
-    const pool = new SandboxPool({
+    const sandbox = (opts.newSandbox ?? podmanSandbox)({
         ...spec,
-        agents,
         root: opts.workspace,
         key: opts.session.id,
         readOnly: opts.readOnly,
@@ -111,24 +106,19 @@ 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: build?.tag ?? spec.image ?? DEFAULT_SANDBOX_IMAGE,
+        build,
+        home,
+        mounts,
+        provider: opts.newSandbox ? (opts.provider ?? 'the host') : PODMAN_PROVIDER,
+    };
 }
+/** How the default sandbox is described. */
+export const PODMAN_PROVIDER = 'podman (this machine)';
 /**
  * The two sources of forwarded names, as one list: the credentials the keyring
  * selected, and whatever the project's `.env` declares. Deduped, because the
@@ -140,7 +130,7 @@ function secretsOf(secrets, env) {
     if (!secrets) {
         return undefined;
     }
-    return [...new Set([...secrets, ...(env ?? [])])].filter((name) => !isIdentityEnv(name));
+    return [...new Set([...secrets, ...(env ?? [])])].filter((name) => !isHostOnlyEnv(name));
 }
 /**
  * Config names a variable; this reads it. A name that is not set on this host
@@ -158,7 +148,7 @@ function toSpec(config, extra, secrets) {
     const env = { ...extra };
     for (const name of config.env ?? []) {
         const value = process.env[name];
-        if (value !== undefined && value !== '' && !isIdentityEnv(name)) {
+        if (value !== undefined && value !== '' && !isHostOnlyEnv(name)) {
             env[name] = value;
         }
     }
@@ -189,7 +179,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 });
@@ -209,8 +201,11 @@ export function prepareHome(setup) {
 // that does not depend on the version, so its directory is put in front of
 // `PYTHONPATH` on every command, ahead of whatever the image set.
 // ---------------------------------------------------------------------------
-/** The packaged sources, beside `src/` and `dist/` alike. */
-const RUNTIME_SOURCE = fileURLToPath(new URL('../runtime/', import.meta.url));
+/**
+ * The packaged sources, beside `src/` and `dist/` alike — also `@zenera/engine/runtime/*`,
+ * for a sandbox that puts them in its image rather than in a bound `$HOME`.
+ */
+export const RUNTIME_SOURCE = fileURLToPath(new URL('../runtime/', import.meta.url));
 /** Where each one lands, inside the container. */
 export const RUNTIME_PYTHON = `${HOME}/.zenera/python`;
 export const RUNTIME_NODE = `${HOME}/.node_modules/zenera`;
@@ -226,10 +221,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.55",
+    "version": "1.1.57",
     "description": "Runs a @zenera/neo project on this machine: keyring, sandbox, sessions and the record each turn leaves behind.",
     "keywords": [
         "agents",
@@ -29,6 +29,7 @@
             "types": "./dist/index.d.ts",
             "default": "./dist/index.js"
         },
+        "./runtime/*": "./runtime/*",
         "./package.json": "./package.json"
     },
     "files": [
@@ -45,6 +46,6 @@
         "prepack": "tsc -b"
     },
     "dependencies": {
-        "@zenera/neo": "^1.1.55"
+        "@zenera/neo": "^1.1.57"
     }
 }