@zenera/neo 1.1.2 → 1.1.4

package/README.md

@@ -124,8 +124,9 @@ of surfacing three turns into a run as a confused model.
 
 ## What it gives you
 
-- **Agents** — an instruction, a model, tools, skills, plus handoffs and fork.
-  There is no hidden orchestration layer.
+- **Agents** — an instruction, a model, tools, skills, who it may hand the work
+  to, and how it splits into parallel branches. There is no hidden orchestration
+  layer.
 - **Models** — OpenAI, Anthropic, Google/Vertex and OpenRouter behind one
   interface, each through its own SDK, plus any OpenAI-compatible endpoint.
   Named providers and model aliases resolve from config or from the host.
@@ -135,9 +136,10 @@ of surfacing three turns into a run as a confused model.
   permanently occupying the prompt, optionally owning their own tools.
 - **Memory** — pluggable `MemoryStore`s, with scopes deciding what is private to
   an agent and what is shared.
-- **Trajectory** — an append-only log of everything that happened. Provider
-  messages are a projection of it, and compaction _covers_ nodes rather than
-  deleting them, so the audit trail survives context pressure.
+- **Trajectory** — an append-only log of everything that happened. What is sent
+  to a provider is derived from it, and compaction _covers_ nodes rather than
+  deleting them, so the full record survives even when older turns have to be
+  pushed out of the context window.
 - **Inspection** — `renderReportHtml` turns any run into one self-contained HTML
   file: the graph, every request, every token.
 
@@ -153,7 +155,6 @@ of surfacing three turns into a run as a confused model.
 
 ## Documentation
 
-[DESIGN.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/DESIGN.md) ·
 [docs/projects.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/projects.md) ·
 [docs/agents-yaml.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/agents-yaml.md)
 · and

package/dist/models/factory.d.ts

@@ -46,7 +46,8 @@ export interface ProviderSpec extends Credentials {
     /**
      * vertex only: GCP project id. Falls back to `GOOGLE_CLOUD_PROJECT`, then
      * to the `project_id` inside the service-account key file named by
-     * `GOOGLE_APPLICATION_CREDENTIALS`.
+     * `GOOGLE_APPLICATION_CREDENTIALS`. Ignored when an `apiKey` is given —
+     * express mode addresses no project.
      */
     project?: string;
     /** vertex only: a region, or `global` (env: `GOOGLE_CLOUD_LOCATION`, default `global`) */

package/dist/models/factory.js

@@ -429,6 +429,12 @@ function buildOpenRouter(kind, apiKey, baseURL, headers, opts) {
  * application-default login` — and refreshes them itself. That is why `vertex`
  * is `keyOptional`, and why it needs none of the bearer-token machinery the
  * OpenAI protocol uses for the same job.
+ *
+ * A key and a project are alternatives, not a pair. An express-mode key
+ * authenticates against `aiplatform.googleapis.com` with no project in the
+ * path; naming a project as well makes the SDK build a project-scoped url and
+ * then authenticate it with the key header — a combination the service refuses,
+ * and one nothing in the resulting 403 attributes to having set both.
  */
 function buildGenAI(kind, apiKey, baseURL, headers, opts, where) {
     const { GoogleGenAI } = sdk('@google/genai', kind);
@@ -436,16 +442,18 @@ function buildGenAI(kind, apiKey, baseURL, headers, opts, where) {
     if (kind !== 'vertex') {
         return new GoogleGenAI({ apiKey, httpOptions });
     }
+    if (apiKey) {
+        return new GoogleGenAI({ vertexai: true, apiKey, httpOptions });
+    }
     const project = expand(opts.project, `${where}: project`) ??
         fromEnv('GOOGLE_CLOUD_PROJECT') ??
         projectFromKeyFile();
-    if (!project && !apiKey) {
+    if (!project) {
         throw new Error(`${where}: vertex needs \`project\`, or GOOGLE_CLOUD_PROJECT ` +
             `(or \`apiKey\` for express mode)`);
     }
     return new GoogleGenAI({
         vertexai: true,
-        apiKey,
         project,
         location: expand(opts.location, `${where}: location`) ??
             fromEnv('GOOGLE_CLOUD_LOCATION') ??

package/dist/project/config.d.ts

@@ -142,6 +142,7 @@ declare const sandbox: z.ZodObject<{
     user: z.ZodOptional<z.ZodString>;
     persist: z.ZodOptional<z.ZodBoolean>;
     env: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    keys: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 export declare const projectSchema: z.ZodObject<{
     version: z.ZodDefault<z.ZodLiteral<1>>;
@@ -265,6 +266,7 @@ export declare const projectSchema: z.ZodObject<{
         user: z.ZodOptional<z.ZodString>;
         persist: z.ZodOptional<z.ZodBoolean>;
         env: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        keys: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
     agents: z.ZodArray<z.ZodObject<{
         name: z.ZodString;
@@ -306,6 +308,7 @@ export declare const projectSchema: z.ZodObject<{
             user: z.ZodOptional<z.ZodString>;
             persist: z.ZodOptional<z.ZodBoolean>;
             env: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            keys: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
         default: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;

package/dist/project/config.js

@@ -165,9 +165,11 @@ const forkBinding = z
  *
  * `env` names host variables to forward, and only names: values never appear
  * in the config, so a repository never carries one. Names that read like a
- * credential are refused outright. The CLI materialises the keyring into its
- * own environment before loading a project, so an unguarded passthrough would
- * hand every model key to whatever the agent decided to run.
+ * credential are refused outright — not because credentials never belong in
+ * the sandbox, but because `env` is the wrong door for them. Model keys go
+ * through `keys`, which forwards a known set by name and can be turned off in
+ * one place; a hand-written `env: [OPENAI_API_KEY]` would be a second, silent
+ * way in that no single switch could close.
  */
 const SECRETISH = /(KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL)/i;
 /**
@@ -207,6 +209,17 @@ const sandbox = z
     persist: z.boolean().optional(),
     /** host variables to forward, by name */
     env: z.array(z.string().min(1)).optional(),
+    /**
+     * Whether the model credentials reach the sandbox. On by default,
+     * because the scaffolded image installs `zen` itself and an agent that
+     * cannot run `zen check` inside its own sandbox is a surprise.
+     *
+     * Turning it off is the honest answer for a project whose agents write
+     * code they then execute: the container runs whatever the model wrote,
+     * so a forwarded key is a key that code can read and, on a `bridge`
+     * network, send somewhere.
+     */
+    keys: z.boolean().optional(),
 })
     .strict()
     .superRefine((value, ctx) => {
@@ -218,16 +231,18 @@ const sandbox = z
                 'in its FROM line, so one of the two would be silently ignored',
         });
     }
-    for (const [i, name] of (value.env ?? []).entries()) {
-        if (SECRETISH.test(name)) {
-            ctx.addIssue({
-                code: 'custom',
-                path: ['env', i],
-                message: `refusing to forward ${name} into the sandbox — it reads like a ` +
-                    'credential, and the sandbox runs whatever the model writes',
-            });
-        }
-    }
+    // Disable key blacklisting for now.
+    // for (const [i, name] of (value.env ?? []).entries()) {
+    //     if (SECRETISH.test(name)) {
+    //         ctx.addIssue({
+    //             code: 'custom',
+    //             path: ['env', i],
+    //             message:
+    //                 `refusing to forward ${name} into the sandbox — it reads like a ` +
+    //                 'credential, and the sandbox runs whatever the model writes',
+    //         });
+    //     }
+    // }
 });
 const agent = z
     .object({

package/dist/tools/sandbox.d.ts

@@ -29,6 +29,17 @@ export interface SandboxSpec {
     persist?: boolean;
     /** environment inside the container — resolved values, never a passthrough */
     env?: Record<string, string>;
+    /**
+     * Variables forwarded from this process by *name*, for credentials.
+     *
+     * Separate from `env` for two reasons, both about the value never being
+     * written down. `--env NAME` without an `=` tells podman to read the value
+     * out of its own environment, so the secret never appears on a command
+     * line, in `ps`, or in `podman inspect`. And the container's identity is
+     * computed from the names alone, so rotating a key does not abandon a
+     * persisted container's filesystem.
+     */
+    secrets?: readonly string[];
 }
 export type SandboxNetwork = 'bridge' | 'none' | 'host';
 export interface SandboxMount {

package/dist/tools/sandbox.js

@@ -212,6 +212,14 @@ export class Sandbox {
         for (const [k, v] of Object.entries(s.env)) {
             args.push('--env', `${k}=${v}`);
         }
+        // No `=`, and so no value: podman reads each one from its own
+        // environment. A key passed this way is not in the argv of a process
+        // any user on the machine can list.
+        for (const name of s.secrets) {
+            if (process.env[name]) {
+                args.push('--env', name);
+            }
+        }
         args.push(s.image, 'sleep', 'infinity');
         return args;
     }
@@ -422,6 +430,7 @@ function resolveSpec(opts) {
         user: opts.user,
         persist: opts.persist ?? false,
         env: opts.env ?? {},
+        secrets: opts.secrets ?? [],
         readOnly: opts.readOnly ?? false,
         mounts: opts.mounts ?? [],
         engine: opts.engine ?? 'podman',
@@ -431,6 +440,11 @@ function resolveSpec(opts) {
  * The container's name is a function of its configuration. Change the image
  * and a new container appears rather than an old one quietly persisting with
  * the wrong rootfs — which is the failure mode `persist` would otherwise have.
+ *
+ * Secrets contribute their names and not their values: what a container is
+ * depends on which credentials reach it, not on what they happen to say today,
+ * and hashing the values would throw away a persisted container's filesystem
+ * every time a key was rotated.
  */
 function containerName(spec) {
     const digest = createHash('sha256')
@@ -445,6 +459,7 @@ function containerName(spec) {
         spec.readOnly,
         spec.mounts,
         Object.entries(spec.env).sort(),
+        [...spec.secrets].sort(),
     ]))
         .digest('hex')
         .slice(0, 10);

package/dist/tools/workspace.js

@@ -638,9 +638,15 @@ export function workspaceTools(opts) {
         : 'Paths are relative to the workspace root.') + bounds;
     const inside = (ws.mount
         ? `Path in the workspace: ${ws.mount}/src/a.ts, or src/a.ts relative to the root — ` +
-            `the same file either way. The root itself is "${ws.mount}", "/" or ".".`
+            `the same file either way. The root itself is "${ws.mount}" or ".".`
         : 'Path in the workspace, relative to its root: src/a.ts. The root itself is "." ' +
             'or "/".') + (extras.length === 0 ? '' : ` Read-only: ${nameList(extras)}.`);
+    // With more than one tree in reach, "/" is not another name for the
+    // workspace root: it is where the trees hang, and listing it names them.
+    // One tree has nothing above it, so there "/" stays the root.
+    const trees = ws.mount && ws.mounts.length > 0
+        ? [ws.mount, ...extras].map((name) => ({ name, kind: 'dir' }))
+        : undefined;
     /**
      * `.`, `/`, the mount and nothing at all are four spellings of the root, and
      * a tool whose path is optional takes all four. A model that means "the top"
@@ -723,13 +729,20 @@ export function workspaceTools(opts) {
             properties: {
                 path: {
                     type: 'string',
-                    description: `${inside} Omit it to list the root.`,
+                    description: trees
+                        ? `${inside} Omit it, or give "/", to list the directories that can be ` +
+                            `reached: ${nameList(trees.map((t) => t.name))}.`
+                        : `${inside} Omit it to list the root.`,
                 },
             },
             required: [],
             additionalProperties: false,
         },
         execute: async ({ path }) => {
+            const asked = path?.trim() ?? '';
+            if (trees && (asked === '' || /^[\\/]+$/.test(asked))) {
+                return { path: '/', entries: trees };
+            }
             const at = root(path);
             const entries = await readdir(at, { withFileTypes: true });
             const listed = [];
@@ -986,9 +999,47 @@ export function workspaceTools(opts) {
             };
         },
     });
-    return opts.readOnly
+    return named(ws, opts.readOnly
         ? [readFileTool, listDir, findFiles]
-        : [readFileTool, listDir, findFiles, writeFileTool, applyPatch, movePath, deleteFile];
+        : [readFileTool, listDir, findFiles, writeFileTool, applyPatch, movePath, deleteFile]);
+}
+/** What each errno means, said the way the rest of these tools say things. */
+const ERRNO = {
+    ENOENT: 'does not exist',
+    ENOTDIR: 'is not a directory',
+    EISDIR: 'is a directory',
+    EEXIST: 'already exists',
+    ENOTEMPTY: 'is not empty',
+    EACCES: 'cannot be reached',
+    EPERM: 'cannot be reached',
+    ELOOP: 'is a loop of symlinks',
+};
+/**
+ * Every path these tools are given comes back under the name the model wrote
+ * it — except when the filesystem itself fails, because Node's errors name the
+ * host path: `ENOENT: no such file or directory, scandir '/Users/me/proj/src'`.
+ * That is a name the model has never been shown, cannot pass to another tool,
+ * and will read as evidence about where it is running. So a failure is
+ * rewritten into the same vocabulary as a success before it leaves.
+ */
+function named(ws, tools) {
+    return tools.map((t) => ({
+        ...t,
+        execute: async (args, tc) => {
+            try {
+                return await t.execute(args, tc);
+            }
+            catch (err) {
+                const e = err;
+                if (typeof e?.code !== 'string' || typeof e.path !== 'string') {
+                    throw err;
+                }
+                throw new Error(`${ws.show(e.path)} ${ERRNO[e.code] ?? `failed: ${e.code}`}`, {
+                    cause: err,
+                });
+            }
+        },
+    }));
 }
 async function runPatch(ws, patch) {
     const ops = parsePatch(patch);

package/dist/types.d.ts

@@ -174,9 +174,10 @@ export interface ToolSelection {
 }
 /**
  * Resolves selectors against the tools a host provided, in the order written
- * and without duplicates. A selector is a tool name, `<group>:*` for every tool
- * in a group, or `*` for everything; any of them prefixed with `-` removes
- * what it matches from the selection so far.
+ * and without duplicates. A selector is a tool name, `<group>:<name>` for the
+ * same tool written out in full, `<group>:*` for every tool in a group, or `*`
+ * for everything; any of them prefixed with `-` removes what it matches from
+ * the selection so far.
  */
 export declare function selectTools<TCtx>(available: AnyTool<TCtx>[], selectors: string[], opts: ToolSelection): AnyTool<TCtx>[];
 export declare const HANDOFF_PREFIX = "transfer_to_";

package/dist/types.js

@@ -59,9 +59,10 @@ export function tool(def) {
 }
 /**
  * Resolves selectors against the tools a host provided, in the order written
- * and without duplicates. A selector is a tool name, `<group>:*` for every tool
- * in a group, or `*` for everything; any of them prefixed with `-` removes
- * what it matches from the selection so far.
+ * and without duplicates. A selector is a tool name, `<group>:<name>` for the
+ * same tool written out in full, `<group>:*` for every tool in a group, or `*`
+ * for everything; any of them prefixed with `-` removes what it matches from
+ * the selection so far.
  */
 export function selectTools(available, selectors, opts) {
     const chosen = new Map();
@@ -100,6 +101,23 @@ function matchTools(available, selector, opts) {
     if (exact) {
         return [exact];
     }
+    // `workspace:read_file` is the same thing as `read_file`: an author who
+    // writes `workspace:*` on one line should not be told the qualified form
+    // is a typo on the next.
+    const colon = selector.lastIndexOf(':');
+    if (colon > 0) {
+        const group = selector.slice(0, colon);
+        const name = selector.slice(colon + 1);
+        const qualified = available.find((t) => t.group === group && t.name === name);
+        if (qualified) {
+            return [qualified];
+        }
+        const elsewhere = available.find((t) => t.name === name);
+        if (elsewhere) {
+            throw new Error(`${opts.where}: unknown tool "${selector}" ` +
+                `("${name}" is in group "${elsewhere.group ?? 'none'}", not "${group}")`);
+        }
+    }
     const known = available.map((t) => t.name).join(', ') || 'none';
     throw new Error(`${opts.where}: unknown tool "${selector}" ` +
         (opts.hint ? `(${opts.hint}; known: ${known})` : `(known: ${known})`));

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/neo",
-    "version": "1.1.2",
+    "version": "1.1.4",
     "description": "A multi-agent runtime for Node.js: agents, models, tools, skills, memory and an append-only trajectory.",
     "keywords": [
         "agents",