@zenera/engine 1.1.58 → 1.2.0

package/dist/engine.js

@@ -97,12 +97,15 @@ export async function openEngine(opts) {
             provider: opts.newSandbox ? 'the host' : chosen?.provider.describe,
             ...(opts.disposable ? { persist: false } : {}),
         });
-        const workspaceOptions = setup.sandbox.files({
-            root: workspace,
-            readOnly: opts.readOnly,
+        // The sandbox's own files, by the names its commands use: what
+        // `run_command` prints a path as, `read_file` accepts.
+        const workspaceOptions = {
+            fs: setup.sandbox.fs,
+            root: setup.workdir,
             mount: setup.workdir,
-            mounts,
-        });
+            mounts: mounts.map(({ at, readOnly, source }) => ({ at, readOnly, source })),
+            readOnly: opts.readOnly,
+        };
         // 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);
@@ -362,10 +365,11 @@ async function record(engine, input, result, startedAt, durationMs) {
             title: `${engine.name} · ${run.id}`,
             architecture: await engine.runner.describe(),
             memory: engine.runner.services.memory?.store,
-            mounts: [
-                { at: engine.workspaceMount, href: pathToFileURL(engine.files.root).href },
-                ...engine.files.mounts.map((m) => ({ at: m.at, href: pathToFileURL(m.host).href })),
-            ],
+            // Links to the trees on this machine — the ones the tools reach.
+            mounts: mounts(engine)
+                .filter((m) => m.at === engine.workspaceMount ||
+                engine.files.mounts.some((f) => f.at === m.at))
+                .map((m) => ({ at: m.at, href: pathToFileURL(m.host).href })),
         });
         await writeFile(run.report, renderReportHtml(built), 'utf8');
         report = run.report;

package/dist/keys.d.ts

@@ -27,6 +27,8 @@ export declare const MODES: readonly KeyMode[];
 /** Anything the keyring can hold a credential for. */
 export declare const OWNERS: readonly ["openai", "anthropic", "google", "vertex", "openrouter", "exa", "bifrost"];
 export type KeyOwner = Provider | Service | GatewayOwner;
+/** Non-secret provider settings that accompany credentials into a runtime or sandbox. */
+export declare const MODEL_CONTEXT_ENV: readonly ["GOOGLE_CLOUD_PROJECT", "GOOGLE_CLOUD_LOCATION", "GOOGLE_CLOUD_QUOTA_PROJECT", "BIFROST_BASE_URL"];
 /**
  * One way a credential can arrive.
  *

package/dist/keys.js

@@ -1,3 +1,9 @@
+/**
+ * Host keyring and ambient credential discovery used by the engine and CLI.
+ * KeyStore materializes active entries, credentials lists supplied secrets/files,
+ * and gcloudAdc locates SDK-default credentials. MODEL_CONTEXT_ENV defines the
+ * non-secret provider settings shared by command sandboxes and agent containers.
+ */
 import { EXA_API_KEY_ENV, GATEWAY_KEY_ENV, GATEWAY_URL_ENV } from '@zenera/neo';
 import { chmodSync, copyFileSync, existsSync, readFileSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
@@ -40,6 +46,13 @@ export const GATEWAYS = ['bifrost'];
 export const MODES = ['direct', ...GATEWAYS];
 /** Anything the keyring can hold a credential for. */
 export const OWNERS = [...PROVIDERS, ...SERVICES, ...GATEWAYS];
+/** Non-secret provider settings that accompany credentials into a runtime or sandbox. */
+export const MODEL_CONTEXT_ENV = [
+    'GOOGLE_CLOUD_PROJECT',
+    'GOOGLE_CLOUD_LOCATION',
+    'GOOGLE_CLOUD_QUOTA_PROJECT',
+    GATEWAY_URL_ENV,
+];
 /**
  * Vertex is the odd one, and it is odd twice.
  *

package/dist/sandbox.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Engine sandbox setup and credential forwarding used by zen run and server turns.
+ * forwarded collects credential mounts, secret names and MODEL_CONTEXT_ENV settings;
+ * the setup helpers build the sandbox specification and map per-run environment.
+ * File credentials reach commands only when the project's keys policy allows them.
+ */
 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';
@@ -75,22 +81,24 @@ export declare function usesSandbox(project: AgentProject): boolean;
  * attached to it, so the host supplies this; the engine only calls it.
  */
 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. 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.
- */
+/** Where the container's `$HOME` lives must exist before podman mounts it. */
 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`.
+ * for an image build that puts them in the image.
  */
 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";
+/** Where the libraries are, inside every sandbox. */
+export declare const RUNTIME_DIR = "/opt/zenera/runtime";
+export declare const RUNTIME_PYTHON = "/opt/zenera/runtime/python";
+export declare const RUNTIME_NODE = "/opt/zenera/runtime/node";
+/** Lays the libraries out as a sandbox sees them: `python/zenera/`, `node/zenera/`. */
+export declare function writeRuntime(dir: string): void;
+/**
+ * This machine's copy of the libraries: the agent image's own when it is one, else one in the
+ * zen home per content — written once, by whichever process gets there first.
+ */
+export declare function runtimeDir(): string;
 /**
  * Best-effort teardown: losing a container must never lose a run. Closing is
  * also where a sandbox that keeps its files elsewhere persists them.

package/dist/sandbox.js

@@ -1,10 +1,18 @@
-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';
+/**
+ * Engine sandbox setup and credential forwarding used by zen run and server turns.
+ * forwarded collects credential mounts, secret names and MODEL_CONTEXT_ENV settings;
+ * the setup helpers build the sandbox specification and map per-run environment.
+ * File credentials reach commands only when the project's keys policy allows them.
+ */
+import { DEFAULT_SANDBOX_IMAGE, SANDBOX_GROUP, WORKSPACE_MOUNT, identityEnv, podmanSandbox, isHostOnlyEnv, } from '@zenera/neo';
+import { createHash } from 'node:crypto';
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, } from 'node:fs';
+import { basename, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { stderrLogger } from "./errors.js";
+import { home as zenHome } from "./home.js";
 import { resolveBuild } from "./image.js";
-import { credentials } from "./keys.js";
+import { credentials, MODEL_CONTEXT_ENV } from "./keys.js";
 // ---------------------------------------------------------------------------
 // The sandbox, as zen wires it
 //
@@ -62,7 +70,7 @@ function forwarded() {
     // Not secrets, and useless without one: a service account says which
     // project it belongs to but never which region to call, and a gateway key
     // says nothing of where the gateway is.
-    for (const name of ['GOOGLE_CLOUD_PROJECT', 'GOOGLE_CLOUD_LOCATION', GATEWAY_URL_ENV]) {
+    for (const name of MODEL_CONTEXT_ENV) {
         const value = process.env[name];
         if (value) {
             env[name] = value;
@@ -82,6 +90,7 @@ export function buildSandbox(opts) {
     const home = join(opts.session.data, 'sandbox', 'home');
     const mounts = [
         { host: home, at: HOME, source: { kind: 'home' } },
+        { host: runtimeDir(), at: RUNTIME_DIR, readOnly: true, source: { kind: 'runtime' } },
         ...(opts.mounts ?? []),
     ];
     const keys = base.keys === false ? undefined : forwarded();
@@ -176,16 +185,9 @@ function toSpec(config, extra, secrets) {
 export function usesSandbox(project) {
     return project.agents.some((a) => a.tools.some((t) => t.group === SANDBOX_GROUP));
 }
-/**
- * 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. 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.
- */
+/** Where the container's `$HOME` lives must exist before podman mounts it. */
 export function prepareHome(setup) {
     mkdirSync(setup.home, { recursive: true });
-    installRuntime(setup.home);
 }
 // ---------------------------------------------------------------------------
 // The `zenera` libraries
@@ -193,33 +195,70 @@ export function prepareHome(setup) {
 // What generated code calls to ask who it is running for. Python and Node,
 // because those are what agents write; anything else reads `ZEN_USER_*`.
 //
-// They live in the home the container already mounts, not in a mount of their
-// own: a new mount would rename every container that already exists, and a
-// persisted one would lose what it had installed. Each language is put where
-// its interpreter looks without being told — `require` searches
-// `$HOME/.node_modules` on its own — except Python, which has no such place
-// 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.
+// One read-only copy for every session, at the same path in every sandbox:
+// /opt/zenera/runtime/{python,node}/zenera. podman binds this machine's copy
+// there (written once per content, in the zen home); the agent image has it
+// there already. Every command gets both directories in front of PYTHONPATH and
+// NODE_PATH, ahead of whatever the image set, so `import zenera` and
+// `require('zenera')` work as they are (an ES `import` ignores NODE_PATH).
 // ---------------------------------------------------------------------------
 /**
  * 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`.
+ * for an image build that puts them in the image.
  */
 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`;
-const RUNTIME_PATHS = { PYTHONPATH: [RUNTIME_PYTHON] };
-function installRuntime(home) {
-    const inside = (path) => join(home, relative(HOME, path));
-    for (const [from, to] of [
-        ['python', RUNTIME_PYTHON],
-        ['node', RUNTIME_NODE],
-    ]) {
-        const target = inside(to);
-        rmSync(target, { recursive: true, force: true });
-        cpSync(join(RUNTIME_SOURCE, from), target, { recursive: true });
+/** Where the libraries are, inside every sandbox. */
+export const RUNTIME_DIR = '/opt/zenera/runtime';
+export const RUNTIME_PYTHON = `${RUNTIME_DIR}/python`;
+export const RUNTIME_NODE = `${RUNTIME_DIR}/node`;
+const RUNTIME_PATHS = { PYTHONPATH: [RUNTIME_PYTHON], NODE_PATH: [RUNTIME_NODE] };
+/** Lays the libraries out as a sandbox sees them: `python/zenera/`, `node/zenera/`. */
+export function writeRuntime(dir) {
+    mkdirSync(join(dir, 'node'), { recursive: true });
+    cpSync(join(RUNTIME_SOURCE, 'python'), join(dir, 'python'), { recursive: true });
+    cpSync(join(RUNTIME_SOURCE, 'node'), join(dir, 'node', 'zenera'), { recursive: true });
+}
+/**
+ * This machine's copy of the libraries: the agent image's own when it is one, else one in the
+ * zen home per content — written once, by whichever process gets there first.
+ */
+export function runtimeDir() {
+    if (existsSync(join(RUNTIME_PYTHON, 'zenera', '__init__.py'))) {
+        return RUNTIME_DIR;
     }
+    const dir = join(zenHome(), 'runtime', runtimeHash());
+    if (!existsSync(dir)) {
+        const tmp = `${dir}.tmp-${process.pid}-${Date.now()}`;
+        writeRuntime(tmp);
+        try {
+            renameSync(tmp, dir);
+        }
+        catch {
+            // Another process wrote the same content first.
+            rmSync(tmp, { recursive: true, force: true });
+        }
+    }
+    return dir;
+}
+let hashed;
+function runtimeHash() {
+    if (hashed)
+        return hashed;
+    const hash = createHash('sha256');
+    const walk = (rel) => {
+        for (const entry of readdirSync(join(RUNTIME_SOURCE, rel), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            const path = join(rel, entry.name);
+            if (entry.isDirectory()) {
+                walk(path);
+            }
+            else {
+                hash.update(`\0${path}\0`).update(readFileSync(join(RUNTIME_SOURCE, path)));
+            }
+        }
+    };
+    walk('');
+    hashed = hash.digest('hex').slice(0, 12);
+    return hashed;
 }
 /**
  * Best-effort teardown: losing a container must never lose a run. Closing is

package/package.json

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