@zenera/engine 1.1.59 → 1.2.0

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.59",
+    "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.59"
+        "@zenera/neo": "^1.2.0"
     }
 }