@zenera/neo 1.1.22 → 1.1.24

package/dist/memory/vectors.js

@@ -39,6 +39,13 @@ export class VectorBlock {
     has(id) {
         return this.#index.has(id);
     }
+    /** A copy, not a view: the row it came from moves the next time something is deleted. */
+    get(id) {
+        const row = this.#index.get(id);
+        return row === undefined
+            ? undefined
+            : this.#data.slice(row * this.#dims, (row + 1) * this.#dims);
+    }
     set(id, vector) {
         if (vector.length !== this.#dims) {
             throw new Error(`expected a ${this.#dims}-dimension vector, got ${vector.length}`);

package/dist/models/factory.d.ts

@@ -83,8 +83,9 @@ export interface ProviderSpec extends Credentials {
 }
 /**
  * What to ask for, and of whom. Vendor differences live in the *provider*, so
- * there is nothing here to discriminate on: the option interfaces are unioned
- * and the knobs that do not apply to the chosen vendor are ignored.
+ * there is nothing here to discriminate on: the option interfaces are unioned,
+ * which makes every vendor's knobs type-legal on every model. `model()` rejects
+ * the ones the resolved adapter would not read — see `KNOBS`.
  *
  * `Credentials` are still accepted inline, for a one-off model that does not
  * warrant a declared provider. Using them opts out of the shared client.
@@ -149,6 +150,39 @@ export interface ModelRequirement {
 }
 export declare const providerKinds: ProviderKind[];
 export declare function isProviderKind(name: string): name is ProviderKind;
+/**
+ * Which knobs each adapter actually reads.
+ *
+ * `ModelSpec` unions every vendor's option interface, so `reasoningEffort` on a
+ * Gemini model is type-legal and the yaml schema accepts it too — and until
+ * this table it was dropped in silence, which is the worst outcome available:
+ * the config claims a setting is in force, the request never carries it, and
+ * the run looks healthy. No static type could have caught it either, because
+ * `provider` is a free name and its kind is not known until resolution.
+ *
+ * Translating instead was the alternative, and it is worse. The vendors do not
+ * mean the same thing by the same word: effort is a coarse level on OpenAI, a
+ * token budget on Anthropic, and *both* on Google depending on the model
+ * generation. A silent remap would make one line mean four things and bury the
+ * 2.5/3 split that `gemini.ts` deliberately refuses to paper over.
+ */
+declare const KNOBS: {
+    readonly 'openai/chat': readonly ["reasoningEffort"];
+    readonly 'openai/responses': readonly ["reasoningEffort", "reasoningSummary", "store"];
+    readonly anthropic: readonly ["maxTokens", "thinkingBudgetTokens"];
+    readonly gemini: readonly ["maxTokens", "thinkingBudget", "thinkingLevel", "includeThoughts"];
+    readonly openrouter: readonly ["maxTokens", "reasoningEffort", "reasoningSummary", "routing", "fallbacks", "plugins", "serviceTier"];
+};
+/** An adapter, in the terms `KNOBS` is keyed by: a protocol, split by api where there are two. */
+export type KnobTarget = keyof typeof KNOBS;
+/** A knob a spec carries that the adapter it resolves to will never read. */
+export interface KnobIssue {
+    knob: string;
+    /** the adapter that would have had to read it */
+    target: KnobTarget;
+    /** what that adapter does read */
+    supported: readonly string[];
+}
 /**
  * Substitutes `${VAR}` references. An unset variable with no fallback is an
  * error naming both the variable and where it was written, because the
@@ -176,6 +210,12 @@ export declare class ModelRegistry {
     names(): string[];
     /** The shared client for a provider, built on first use. */
     client(name: string): ProviderClient;
+    /**
+     * Knobs a ref carries that its adapter will never read — the same check
+     * `model()` refuses on, minus the client, so a report can name them before
+     * a credential is resolved or anything is contacted.
+     */
+    knobs(ref: ModelRef): KnobIssue[];
     /** Turns a shorthand or a spec into a `Model`. */
     model(ref: ModelRef): Model;
     /**
@@ -215,4 +255,5 @@ export declare const defaultModels: ModelRegistry;
 export declare function createModel(ref: ModelRef, registry?: ModelRegistry): Model;
 /** `createModel`'s counterpart for vectors, over the same registry and clients. */
 export declare function createEmbedder(ref: EmbeddingRef, registry?: ModelRegistry): Embedder;
+export {};
 //# sourceMappingURL=factory.d.ts.map

package/dist/models/factory.js

@@ -4,6 +4,7 @@ import { GeminiEmbedder } from "../embeddings/gemini.js";
 import { DEFAULT_START, RateLimiter } from "../embeddings/limiter.js";
 import { OpenAIEmbedder } from "../embeddings/openai.js";
 import { OpenRouterEmbedder } from "../embeddings/openrouter.js";
+import { unfundedSymbol } from "../embeddings/rate-limit.js";
 import { AnthropicModel } from "./anthropic.js";
 import { GeminiModel } from "./gemini.js";
 import { OpenAIModel } from "./openai-chat.js";
@@ -114,6 +115,48 @@ export function isProviderKind(name) {
     return Object.hasOwn(KINDS, name);
 }
 // ---------------------------------------------------------------------------
+// Tuning knobs
+// ---------------------------------------------------------------------------
+/**
+ * Which knobs each adapter actually reads.
+ *
+ * `ModelSpec` unions every vendor's option interface, so `reasoningEffort` on a
+ * Gemini model is type-legal and the yaml schema accepts it too — and until
+ * this table it was dropped in silence, which is the worst outcome available:
+ * the config claims a setting is in force, the request never carries it, and
+ * the run looks healthy. No static type could have caught it either, because
+ * `provider` is a free name and its kind is not known until resolution.
+ *
+ * Translating instead was the alternative, and it is worse. The vendors do not
+ * mean the same thing by the same word: effort is a coarse level on OpenAI, a
+ * token budget on Anthropic, and *both* on Google depending on the model
+ * generation. A silent remap would make one line mean four things and bury the
+ * 2.5/3 split that `gemini.ts` deliberately refuses to paper over.
+ */
+const KNOBS = {
+    'openai/chat': ['reasoningEffort'],
+    'openai/responses': ['reasoningEffort', 'reasoningSummary', 'store'],
+    anthropic: ['maxTokens', 'thinkingBudgetTokens'],
+    gemini: ['maxTokens', 'thinkingBudget', 'thinkingLevel', 'includeThoughts'],
+    openrouter: [
+        'maxTokens',
+        'reasoningEffort',
+        'reasoningSummary',
+        'routing',
+        'fallbacks',
+        'plugins',
+        'serviceTier',
+    ],
+};
+/** Every knob some adapter reads. A key outside it is a connection field, not tuning. */
+const TUNING = new Set(Object.values(KNOBS).flat());
+function unreadKnobs(spec, target) {
+    const supported = KNOBS[target];
+    return Object.entries(spec)
+        .filter(([k, v]) => v !== undefined && TUNING.has(k) && !supported.includes(k))
+        .map(([knob]) => ({ knob, target, supported }));
+}
+// ---------------------------------------------------------------------------
 // Environment references
 // ---------------------------------------------------------------------------
 // `${VAR}` and `${VAR:-fallback}`. Chosen over a bare `env.VAR` token because a
@@ -225,6 +268,22 @@ export class ModelRegistry {
         this.#limiters.set(name, built);
         return built;
     }
+    /**
+     * Knobs a ref carries that its adapter will never read — the same check
+     * `model()` refuses on, minus the client, so a report can name them before
+     * a credential is resolved or anything is contacted.
+     */
+    knobs(ref) {
+        const spec = typeof ref === 'string' ? this.parse(ref) : ref;
+        const defaults = KINDS[this.kindOf(spec.provider ?? this.#default)];
+        if (defaults.protocol !== 'openai') {
+            return unreadKnobs(spec, defaults.protocol);
+        }
+        // An api this vendor does not speak already has an error of its own;
+        // answering about its knobs would only bury it.
+        const api = spec.api ?? defaults.apis[0];
+        return api && defaults.apis.includes(api) ? unreadKnobs(spec, `openai/${api}`) : [];
+    }
     /** Turns a shorthand or a spec into a `Model`. */
     model(ref) {
         const spec = typeof ref === 'string' ? this.parse(ref) : ref;
@@ -232,6 +291,13 @@ export class ModelRegistry {
         const provider = this.#spec(name);
         const kind = this.kindOf(name);
         const defaults = KINDS[kind];
+        // Before the client, so a knob for the wrong vendor is reported as the
+        // config mistake it is rather than behind a missing credential.
+        const [stray] = this.knobs(spec);
+        if (stray) {
+            throw new TypeError(`provider "${name}" (${kind}) does not read "${stray.knob}" — a ` +
+                `${stray.target} model takes: ${stray.supported.join(', ')}`);
+        }
         // Inline credentials opt out of the shared client: they describe a
         // different connection, and handing back the memoized one would
         // silently ignore them.
@@ -457,7 +523,7 @@ function buildClient(name, kind, creds, opts) {
         defaultHeaders: headers,
         timeout: opts.timeoutMs,
         maxRetries: retriesOf(opts),
-        ...(opts.token ? { fetch: bearerFetch(opts.token) } : {}),
+        fetch: funded(opts.token ? bearerFetch(opts.token) : fetch),
     };
     if (defaults.protocol === 'anthropic') {
         const { Anthropic } = sdk('@anthropic-ai/sdk', kind);
@@ -608,6 +674,47 @@ function bearerFetch(token) {
         return fetch(input, { ...init, headers });
     };
 }
+/**
+ * Tells the client not to wait out a 429 that no wait will clear.
+ *
+ * Both SDKs retry every 429, because a 429 is normally this minute's rate
+ * limit — but an exhausted balance answers with the same status, and the whole
+ * backoff schedule is then spent on a call that cannot succeed. The account is
+ * named in the body rather than the status, so the body is what decides, and
+ * `x-should-retry` is the SDKs' own override for exactly this.
+ */
+function funded(inner) {
+    return async (input, init) => {
+        const res = await inner(input, init);
+        if (res.status !== 429) {
+            return res;
+        }
+        // A 429 body is a sentence long, and the client is about to read it
+        // anyway to build the error it throws.
+        const body = await res.text();
+        const headers = new Headers(res.headers);
+        // The transfer is already undone by the time a body is text.
+        headers.delete('content-encoding');
+        headers.delete('content-length');
+        if (unfunded(body)) {
+            headers.set('x-should-retry', 'false');
+        }
+        return new Response(body, { status: res.status, statusText: res.statusText, headers });
+    };
+}
+/** Whether a refusal body names the account rather than the rate. */
+function unfunded(body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return false;
+    }
+    const root = parsed;
+    const said = (root?.error ?? root);
+    return Boolean(said) && (unfundedSymbol(said?.code) || unfundedSymbol(said?.type));
+}
 function expandHeaders(headers, where) {
     if (!headers) {
         return undefined;

package/dist/project/config.js

@@ -193,7 +193,7 @@ const memoryBinding = z
      * lets it decide when to look.
      */
     autoRecall: z
-        .union([z.boolean(), z.object({ limit: z.int().positive().default(5) }).strict()])
+        .union([z.boolean(), z.object({ limit: z.int().positive().default(10) }).strict()])
         .optional(),
 })
     .strict();

package/dist/project/load.d.ts

@@ -63,6 +63,13 @@ export interface ProjectOptions<TCtx = unknown> {
      * and writes to another.
      */
     memoryDir?: string;
+    /**
+     * Recall only: the graph is opened read-only and every agent's `access` is
+     * clamped to `read`, so the writing tools are never offered and the house
+     * rules never claim they are. It is what lets several runs share one
+     * warmed memory at once, which the directory lock otherwise forbids.
+     */
+    memoryReadOnly?: boolean;
     /** turns an agent-visible path into a host path, so files can be remembered */
     resolveFile?: (path: string) => string;
     payloads?: PayloadStore;

package/dist/project/load.js

@@ -4,6 +4,7 @@ import { Agent, AgentRegistry } from "../agent.js";
 import { RunStream } from "../events.js";
 import { frontmatter, toList } from "../frontmatter.js";
 import { MemoryIndex } from "../memory/index.js";
+import { DEFAULT_SEEDS } from "../memory/recall.js";
 import { MemoryStore } from "../memory/store.js";
 import { ModelRegistry, } from "../models/factory.js";
 import { promptFile } from "../prompt.js";
@@ -42,7 +43,10 @@ export function readProjectConfig(dir) {
  * error nobody can act on.
  */
 export async function loadProject(dir, opts = {}) {
-    const { root, source, config } = readProjectConfig(dir);
+    const { root, source, config: declared } = readProjectConfig(dir);
+    // Clamped here rather than at each use, so the tools, the house rules and
+    // the report all read the same access and cannot disagree about it.
+    const config = opts.memoryReadOnly ? recallOnly(declared) : declared;
     // Read once and share the objects: every agent's prompt then reports the
     // same paths and the same content hashes, so the report says "one document,
     // five prompts" instead of showing five identical blobs.
@@ -73,7 +77,8 @@ export async function loadProject(dir, opts = {}) {
     // The default is resolved here rather than on first use, so a broken
     // `embedding:` fails at load like a broken `model:` does.
     embedders(config.embedding, 'embedding');
-    const memory = opts.memory ?? (await openMemory(root, config, embedders, opts.memoryDir));
+    const memory = opts.memory ??
+        (await openMemory(root, config, embedders, opts.memoryDir, opts.memoryReadOnly));
     return new AgentProject({
         root,
         source,
@@ -240,10 +245,17 @@ const FILE_TOOLS = [
     'find_files',
     'write_file',
     'apply_patch',
+    'copy_file',
     'move_file',
     'delete_file',
 ];
-const FILE_WRITE_TOOLS = new Set(['write_file', 'apply_patch', 'move_file', 'delete_file']);
+const FILE_WRITE_TOOLS = new Set([
+    'write_file',
+    'apply_patch',
+    'copy_file',
+    'move_file',
+    'delete_file',
+]);
 function activeFileTools(selectors) {
     const active = new Set();
     if (!selectors?.length) {
@@ -503,7 +515,7 @@ function memoryFor(spec) {
         sees: b.sees,
         writes: b.writes,
         autoRecall: auto
-            ? { query: 'last_user_input', limit: auto === true ? 5 : auto.limit }
+            ? { query: 'last_user_input', limit: auto === true ? DEFAULT_SEEDS : auto.limit }
             : undefined,
     };
 }
@@ -527,13 +539,24 @@ export function memoryDir(root, config, override) {
     }
     return join(root, config.memory?.dir ?? 'memory');
 }
+/**
+ * The same project with every memory binding demoted to `read`. A read-only
+ * graph refuses a commit, so an agent offered `memory_commit` would only find
+ * that out by having one fail mid-run.
+ */
+function recallOnly(config) {
+    return {
+        ...config,
+        agents: config.agents.map((spec) => spec.memory ? { ...spec, memory: { ...spec.memory, access: 'read' } } : spec),
+    };
+}
 /**
  * Opened only when something will use it, so an ordinary project neither
  * creates a directory nor takes a lock. A `memory:` block with no agent bound
  * to it still counts: it is how a project declares the graph `zen memory`
  * inspects between runs.
  */
-async function openMemory(root, config, embedders, override) {
+async function openMemory(root, config, embedders, override, readOnly) {
     const dir = memoryDir(root, config, override);
     if (!dir) {
         return undefined;
@@ -541,7 +564,7 @@ async function openMemory(root, config, embedders, override) {
     const declared = config.memory;
     const embedder = embedders(declared?.embedding ?? config.embedding, 'memory.embedding');
     return new MemoryIndex({
-        store: await MemoryStore.open(dir),
+        store: await MemoryStore.open(dir, { readOnly }),
         embedder,
         kinds: declared?.kinds,
         relations: declared?.relations,

package/dist/tools/exa.js

@@ -41,7 +41,7 @@ const MAX_TIMEOUT_MS = 120_000;
 /**
  * A failure the model should read rather than one the run should die of.
  * Module-private: it never escapes a tool, which turns it into `{error, hint}`
- * the same way the workspace tools turn a bad patch into one.
+ * the same way the file tools turn a bad patch into one.
  */
 class ExaError extends Error {
     hint;

package/dist/tools/files.d.ts

@@ -0,0 +1,81 @@
+import { type AnyTool } from '../types.ts';
+/** Where a project's `assets/` directory appears in the agent's namespace. */
+export declare const ASSETS_MOUNT = "/assets";
+/** ...and where its skill catalog does, so a skill's scripts can be run. */
+export declare const SKILLS_MOUNT = "/skills";
+/**
+ * A second tree the agent can reach, under a name of its own. Structurally the
+ * same as a `SandboxMount` on purpose: one directory is one mount, and the host
+ * hands the identical array to the file tools and to the container so that both
+ * call it by the same name.
+ */
+export interface WorkspaceMount {
+    /** absolute host path; must already exist */
+    host: string;
+    /** absolute path the agent names it by, e.g. `/assets` */
+    at: string;
+    /** defaults to true — an extra tree is reference material unless said otherwise */
+    readOnly?: boolean;
+}
+export interface WorkspaceOptions {
+    root: string;
+    /** refuse every mutating tool; `zen run --read-only` */
+    readOnly?: boolean;
+    /**
+     * An absolute path the root is *also* known by, because something else has
+     * mounted it there — the sandbox bind-mounts the workspace at `/workspace`,
+     * so `run_command` returns compiler errors, stack traces and `pwd` output
+     * naming files under a prefix the file tools would otherwise refuse. Set
+     * it and both spellings reach the same file.
+     */
+    mount?: string;
+    /** further trees, each under its own name; read-only unless one says otherwise */
+    mounts?: readonly WorkspaceMount[];
+}
+export declare class Workspace {
+    #private;
+    readonly root: string;
+    readonly readOnly: boolean;
+    readonly mount: string | undefined;
+    /** the extra trees, resolved — the primary root is not among them */
+    readonly mounts: readonly Required<WorkspaceMount>[];
+    constructor(opts: WorkspaceOptions);
+    /**
+     * The one gate. Returns an absolute path inside one of the roots, or throws.
+     *
+     * A path that does not exist yet cannot be realpath'd, so the nearest
+     * existing ancestor is resolved instead and the remainder appended — which
+     * is exactly what a create needs and closes the same hole a create opens.
+     */
+    within(input: string, opts?: {
+        write?: boolean;
+    }): string;
+    /** Where a path sits under its own root, in posix form. `.` is that root. */
+    rel(path: string): string;
+    /**
+     * How a path is written back to the model, and the reason `mount` is not
+     * only about what comes in. A shell in the sandbox prints the mounted name
+     * — `find` returns /workspace/src/a.ts — so if the file tools answered with
+     * `src/a.ts` the model would be holding two vocabularies for one tree and
+     * would have to translate between them to feed one tool's output to the
+     * other. With a mount configured every path in and every path out is the
+     * mounted one, and copying a path from a command's output into read_file
+     * is exact. Without one, everything stays relative as before.
+     */
+    show(path: string): string;
+    /** Whether a resolved path *is* one of the roots. Nothing may move or delete one. */
+    isRoot(path: string): boolean;
+    mutable(): void;
+}
+export type FileFormat = 'text' | 'binary' | 'image' | 'audio' | 'video' | 'pdf' | 'archive';
+export interface FileInfo {
+    name: string;
+    kind: 'file' | 'dir' | 'link' | 'other';
+    format?: FileFormat;
+    bytes?: number;
+    lines?: number;
+}
+export declare function fileTools<TCtx = unknown>(opts: WorkspaceOptions): AnyTool<TCtx>[];
+/** @deprecated The group has been `files` for a while; this is the old spelling. */
+export declare const workspaceTools: typeof fileTools;
+//# sourceMappingURL=files.d.ts.map