@zenera/engine 1.1.47 → 1.1.49

package/README.md

@@ -13,6 +13,10 @@ behind (`state.json`, `report.html`, run metadata).
 It never prints and never prompts. Warnings go to the `Logger` you pass, errors are `EngineError`s
 with a code, and installing a container engine is a `preflight` the host supplies.
 
+Pass `user` to say who the run is acting for. The agent gets it from the `current_user` tool, and code in
+the sandbox gets it from `ZEN_USER_*` or the `zenera` library. See
+[docs/identity.md](../../docs/identity.md).
+
 ## Use
 
 ```ts
@@ -26,6 +30,7 @@ const engine = await openEngine({
     project: { dir: '/project', name: 'acme' },
     session,
     memoryDir: '/data/users/u1/memory',
+    user: { id: 'u1', email: 'ann@acme.com', role: 'editor', source: 'host' },
     logger: { warn: (m) => console.warn(m) },
 });
 try {

package/dist/engine.d.ts

@@ -1,9 +1,11 @@
-import { AgentRunner, Workspace, type AgentEvent, type AgentProject, type AgentState, type Input, type MemoryIndex, type RunResult } from '@zenera/neo';
+import { AgentRunner, Workspace, type AgentEvent, type AgentProject, type AgentState, type Input, type MemoryIndex, type RunIdentity, type RunResult } from '@zenera/neo';
 import { type ModelIssue } from './audit.ts';
 import { type Logger } from './errors.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. */
+export type { RunIdentity } from '@zenera/neo';
 /** A run drawn for a model to read, written beside it as `graph.mmd`. */
 export type GraphRenderer = (state: AgentState, run: {
     runId: string;
@@ -53,6 +55,18 @@ export interface EngineOptions {
     preflight?: Preflight;
     /** draws each finished run as `graph.mmd`; no graph when unset */
     graph?: GraphRenderer;
+    /**
+     * Who the run is acting for — the person the host authenticated, not the
+     * project's author and not the owner of the keys. `current_user` answers with it and
+     * every sandbox command sees it as `ZEN_USER_*`.
+     *
+     * Unset, the engine takes `ZEN_USER_*` from its own environment, marked
+     * `local`: that is how a `zen run` inside a sandbox keeps acting for the
+     * same person, and how `zen run --as` works. `null` means nobody, and reads
+     * nothing — a server that knows its runs have no user says so, rather than
+     * letting whatever its own environment holds speak for one.
+     */
+    user?: RunIdentity | null;
 }
 export interface Engine {
     project: AgentProject;
@@ -74,6 +88,8 @@ export interface Engine {
     sandbox: SandboxSetup;
     lock: Held;
     graph?: GraphRenderer;
+    /** who the run is acting for, when anyone */
+    user?: RunIdentity;
     close(): Promise<void>;
 }
 /**
@@ -82,6 +98,13 @@ export interface Engine {
  * and the whole conversation, its memory and its blobs travel with it.
  */
 export declare function openEngine(opts: EngineOptions): Promise<Engine>;
+/**
+ * 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
+ * here because it is about to become variables and a container's argv: a
+ * newline in an id is not an id.
+ */
+export declare function resolveUser(given: RunIdentity | null | undefined): RunIdentity | undefined;
 export interface Mount {
     /** the directory on this machine */
     host: string;

package/dist/engine.js

@@ -1,11 +1,11 @@
-import { AgentRunner, FilePayloadStore, SANDBOX_MOUNT, SKILLS_MOUNT, Workspace, assertState, buildRunReport, exaTools, fileTools, lastText, loadProject, memoryDir, readProjectConfig, renderReportHtml, sandboxTools, turns, } from '@zenera/neo';
+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 { existsSync } from 'node:fs';
 import { writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { auditModels, describeIssue } from "./audit.js";
 import { loadProjectEnv } from "./env.js";
-import { EXIT, EngineError, invalidError, stderrLogger } from "./errors.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";
@@ -19,10 +19,15 @@ import { acquire, createRun, readSessionMeta, writeRunMeta, writeSessionMeta, }
 export async function openEngine(opts) {
     const logger = opts.logger ?? stderrLogger;
     const onIssue = opts.onIssue ?? ((issue) => logger.warn(describeIssue(issue)));
+    const user = resolveUser(opts.user);
     // Before the keyring, so the project's own file wins over the machine's
     // keys, and before the load, so `${VAR}` in agents.yaml can name anything
     // in it. The real environment still beats both.
     const env = loadProjectEnv(opts.project.dir);
+    if (env?.refused.length && !opts.quiet) {
+        logger.warn(`${env.path} sets ${env.refused.join(', ')} — ignored: who a run acts for ` +
+            'is the host’s to say (zen run --as <user> to try one)');
+    }
     const keys = await KeyStore.open();
     keys.materialize();
     assertUsable(keys);
@@ -66,6 +71,7 @@ export async function openEngine(opts) {
             keys: opts.keys,
             env: env?.names,
             mounts,
+            identity: user,
             ...(opts.disposable ? { persist: false } : {}),
         });
         const workspaceOptions = {
@@ -90,6 +96,9 @@ export async function openEngine(opts) {
                 // turn that tried.
                 ...exaTools(),
             ],
+            // Every agent can ask who it is acting for without the project
+            // having to know the tool exists; `-current_user` still takes it away.
+            alwaysTools: identityTools(user),
             skillsAt: SKILLS_MOUNT,
             memory: opts.memory,
             memoryDir: opts.memoryDir,
@@ -135,6 +144,7 @@ export async function openEngine(opts) {
         sandbox,
         lock,
         graph: opts.graph,
+        user,
         close: async () => {
             await teardown(sandbox.pool, logger);
             // A host-supplied graph is the host's to release.
@@ -145,6 +155,30 @@ export async function openEngine(opts) {
         },
     };
 }
+/**
+ * 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
+ * here because it is about to become variables and a container's argv: a
+ * newline in an id is not an id.
+ */
+export function resolveUser(given) {
+    if (given === null) {
+        return undefined;
+    }
+    const user = given ? compactIdentity(given) : identityFromEnv(process.env);
+    if (!user) {
+        return undefined;
+    }
+    if (!user.id.trim()) {
+        throw usageError('the run’s user has an empty id');
+    }
+    for (const [key, value] of Object.entries(user)) {
+        if (typeof value === 'string' && /[\0\r\n]/.test(value)) {
+            throw usageError(`the run’s user ${key} has a control character in it`);
+        }
+    }
+    return user;
+}
 async function loadState(session) {
     if (!existsSync(session.state)) {
         return undefined;
@@ -188,6 +222,7 @@ export function envelope(engine, outcome) {
             ...(outcome.graph ? { graph: outcome.graph } : {}),
         },
         mounts: mounts(engine),
+        ...(engine.user ? { user: engine.user } : {}),
         agent: outcome.result.agent,
         stopReason: outcome.result.stopReason,
         durationMs: outcome.durationMs,
@@ -285,6 +320,7 @@ async function record(engine, input, result, startedAt, durationMs) {
         usage: result.usage,
         workspace: engine.workspace,
         memory: engine.memory,
+        ...(engine.user ? { user: engine.user } : {}),
         error: result.state.error,
     });
     return { run, result, text, durationMs, report, graph };

package/dist/env.d.ts

@@ -13,6 +13,12 @@ export interface ProjectEnv {
     names: string[];
     /** what the file says, credential paths made absolute */
     values: Record<string, string>;
+    /**
+     * 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.
+     */
+    refused: string[];
 }
 /** The env file a project in `dir` reads: `$ZEN_ENV_FILE` when set, `.env` otherwise. */
 export declare function projectEnvPath(dir: string): string;

package/dist/env.js

@@ -1,3 +1,4 @@
+import { isIdentityEnv } from '@zenera/neo';
 import { existsSync, readFileSync } from 'node:fs';
 import { isAbsolute, resolve } from 'node:path';
 import { parseEnv } from 'node:util';
@@ -43,12 +44,16 @@ export function readProjectEnv(dir) {
         return undefined;
     }
     const values = {};
+    const refused = [];
     for (const [name, value] of Object.entries(parseEnv(readFileSync(path, 'utf8')))) {
-        if (value !== undefined) {
+        if (isIdentityEnv(name)) {
+            refused.push(name);
+        }
+        else if (value !== undefined) {
             values[name] = located(dir, name, value);
         }
     }
-    return { path, names: Object.keys(values), values };
+    return { path, names: Object.keys(values), values, refused };
 }
 /**
  * Reads the project's env file (`.env`, or `$ZEN_ENV_FILE`) into

package/dist/sandbox.d.ts

@@ -1,4 +1,4 @@
-import { SandboxPool, type AgentProject, type ProjectConfig, type SandboxMount, type SandboxSpec } from '@zenera/neo';
+import { SandboxPool, type AgentProject, type ProjectConfig, type RunIdentity, type SandboxMount, type SandboxSpec } from '@zenera/neo';
 import { type Logger } from './errors.ts';
 import { type ResolvedBuild } from './image.ts';
 import type { SessionPaths } from './session.ts';
@@ -42,6 +42,11 @@ export interface SandboxInputs {
     env?: readonly string[];
     /** `false` overrides every `persist:` in the config, the agents' included */
     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;
 }
 export declare function buildSandbox(opts: SandboxInputs): SandboxSetup;
 /**
@@ -59,8 +64,15 @@ 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. */
+/**
+ * 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.
+ */
 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>;
 //# sourceMappingURL=sandbox.d.ts.map

package/dist/sandbox.js

@@ -1,6 +1,7 @@
-import { DEFAULT_SANDBOX_IMAGE, GATEWAY_URL_ENV, SANDBOX_GROUP, SandboxPool, } from '@zenera/neo';
-import { mkdirSync } from 'node:fs';
-import { basename, join } from 'node:path';
+import { DEFAULT_SANDBOX_IMAGE, GATEWAY_URL_ENV, SANDBOX_GROUP, SandboxPool, identityEnv, isIdentityEnv, } from '@zenera/neo';
+import { cpSync, mkdirSync, rmSync } from 'node:fs';
+import { basename, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { stderrLogger } from "./errors.js";
 import { resolveBuild } from "./image.js";
 import { credentials } from "./keys.js";
@@ -107,6 +108,8 @@ export function buildSandbox(opts) {
         key: opts.session.id,
         readOnly: opts.readOnly,
         mounts,
+        execEnv: identityEnv(opts.identity),
+        execPaths: RUNTIME_PATHS,
     });
     return { pool, spec, image: spec.image ?? DEFAULT_SANDBOX_IMAGE, build, home, mounts };
 }
@@ -137,7 +140,7 @@ function secretsOf(secrets, env) {
     if (!secrets) {
         return undefined;
     }
-    return [...new Set([...secrets, ...(env ?? [])])];
+    return [...new Set([...secrets, ...(env ?? [])])].filter((name) => !isIdentityEnv(name));
 }
 /**
  * Config names a variable; this reads it. A name that is not set on this host
@@ -155,7 +158,7 @@ function toSpec(config, extra, secrets) {
     const env = { ...extra };
     for (const name of config.env ?? []) {
         const value = process.env[name];
-        if (value !== undefined && value !== '') {
+        if (value !== undefined && value !== '' && !isIdentityEnv(name)) {
             env[name] = value;
         }
     }
@@ -183,9 +186,45 @@ 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. */
+/**
+ * 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.
+ */
 export function prepareHome(setup) {
     mkdirSync(setup.home, { recursive: true });
+    installRuntime(setup.home);
+}
+// ---------------------------------------------------------------------------
+// The `zenera` libraries
+//
+// 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.
+// ---------------------------------------------------------------------------
+/** The packaged sources, beside `src/` and `dist/` alike. */
+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 });
+    }
 }
 /** Best-effort teardown: losing a container must never lose a run. */
 export async function teardown(pool, logger = stderrLogger) {

package/dist/session.d.ts

@@ -1,3 +1,4 @@
+import { type RunIdentity } from '@zenera/neo';
 export interface SessionPaths {
     id: string;
     dir: string;
@@ -94,6 +95,8 @@ export interface RunMeta {
     usage: unknown;
     workspace: string;
     memory?: string;
+    /** who the run acted for, when anyone */
+    user?: RunIdentity;
     error?: string;
 }
 export declare function writeRunMeta(p: RunPaths, meta: RunMeta): void;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/engine",
-    "version": "1.1.47",
+    "version": "1.1.49",
     "description": "Runs a @zenera/neo project on this machine: keyring, sandbox, sessions and the record each turn leaves behind.",
     "keywords": [
         "agents",
@@ -33,7 +33,8 @@
     },
     "files": [
         "dist",
-        "!dist/**/*.map"
+        "!dist/**/*.map",
+        "runtime"
     ],
     "engines": {
         "node": ">=24"
@@ -44,6 +45,6 @@
         "prepack": "tsc -b"
     },
     "dependencies": {
-        "@zenera/neo": "^1.1.47"
+        "@zenera/neo": "^1.1.49"
     }
 }

package/runtime/node/index.cjs

@@ -0,0 +1,46 @@
+'use strict';
+
+// Who this Zenera run is acting for. The host puts the signed-in user into every
+// command's environment as ZEN_USER_*; this reads them.
+//
+//     const { identity, requireIdentity } = require('zenera');
+//     const me = identity(); // null when no one is signed in
+
+function get(name) {
+    const value = (process.env[name] || '').trim();
+    return value || undefined;
+}
+
+function identity() {
+    const id = get('ZEN_USER_ID');
+    if (!id) {
+        return null;
+    }
+    return {
+        id,
+        email: get('ZEN_USER_EMAIL'),
+        name: get('ZEN_USER_NAME'),
+        role: get('ZEN_USER_ROLE'),
+        source: get('ZEN_USER_SOURCE') || 'local',
+    };
+}
+
+class NoIdentityError extends Error {
+    constructor() {
+        super(
+            'this run has no signed-in user (ZEN_USER_ID is not set); ' +
+                'outside the Zenera app, start it with: zen run --as <user>',
+        );
+        this.name = 'NoIdentityError';
+    }
+}
+
+function requireIdentity() {
+    const me = identity();
+    if (!me) {
+        throw new NoIdentityError();
+    }
+    return me;
+}
+
+module.exports = { identity, requireIdentity, NoIdentityError };

package/runtime/node/index.d.ts

@@ -0,0 +1,17 @@
+/** The signed-in user a Zenera run is acting for. */
+export interface Identity {
+    id: string;
+    email?: string;
+    name?: string;
+    role?: string;
+    /** `host`: the application authenticated them; `local`: only stated on this machine */
+    source: 'host' | 'local' | string;
+}
+
+/** The user this run acts for, or `null` when there is none. */
+export function identity(): Identity | null;
+
+/** The user this run acts for; throws `NoIdentityError` when there is none. */
+export function requireIdentity(): Identity;
+
+export class NoIdentityError extends Error {}

package/runtime/node/index.mjs

@@ -0,0 +1,15 @@
+// The ES-module face of index.cjs, so there is one implementation.
+//
+// `import 'zenera'` only resolves from a directory with this package in a
+// node_modules above it — ES modules do not search $HOME/.node_modules the way
+// `require` does. Anywhere else, import it by path:
+//
+//     import { identity } from '/home/agent/.node_modules/zenera/index.mjs';
+import { createRequire } from 'node:module';
+
+const lib = createRequire(import.meta.url)('./index.cjs');
+
+export const identity = lib.identity;
+export const requireIdentity = lib.requireIdentity;
+export const NoIdentityError = lib.NoIdentityError;
+export default lib;

package/runtime/node/package.json

@@ -0,0 +1,15 @@
+{
+    "name": "zenera",
+    "version": "1.0.0",
+    "description": "Who this Zenera run is acting for. Installed into the sandbox by the engine.",
+    "license": "MIT",
+    "main": "./index.cjs",
+    "types": "./index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./index.d.ts",
+            "import": "./index.mjs",
+            "require": "./index.cjs"
+        }
+    }
+}

package/runtime/python/zenera/__init__.py

@@ -0,0 +1,65 @@
+"""Who this Zenera run is acting for.
+
+The host that started the run - Zenera's app, or ``zen run --as`` - puts the
+signed-in user into every command's environment as ``ZEN_USER_*``. This module
+reads them, so code an agent writes can depend on who is asking::
+
+    import zenera
+
+    me = zenera.identity()          # None when no one is signed in
+    if me:
+        print(me.id, me.email, me.role)
+
+    me = zenera.require_identity()  # raises when no one is signed in
+
+``source`` is ``"host"`` when the application authenticated the user and
+``"local"`` when it was only stated on the machine running the project.
+Standard library only, so it works in any image with a Python 3.
+"""
+
+import os
+from typing import NamedTuple, Optional
+
+__all__ = ["Identity", "NoIdentityError", "identity", "require_identity"]
+
+
+class Identity(NamedTuple):
+    id: str
+    email: Optional[str] = None
+    name: Optional[str] = None
+    role: Optional[str] = None
+    source: str = "local"
+
+
+class NoIdentityError(RuntimeError):
+    """Raised by require_identity() when the run has no signed-in user."""
+
+
+def _get(name: str) -> Optional[str]:
+    value = os.environ.get(name, "").strip()
+    return value or None
+
+
+def identity() -> Optional[Identity]:
+    """The signed-in user this run acts for, or None when there is none."""
+    user_id = _get("ZEN_USER_ID")
+    if not user_id:
+        return None
+    return Identity(
+        id=user_id,
+        email=_get("ZEN_USER_EMAIL"),
+        name=_get("ZEN_USER_NAME"),
+        role=_get("ZEN_USER_ROLE"),
+        source=_get("ZEN_USER_SOURCE") or "local",
+    )
+
+
+def require_identity() -> Identity:
+    """The signed-in user this run acts for; raises NoIdentityError when there is none."""
+    me = identity()
+    if me is None:
+        raise NoIdentityError(
+            "this run has no signed-in user (ZEN_USER_ID is not set); "
+            "outside the Zenera app, start it with: zen run --as <user>"
+        )
+    return me