@zenera/neo 1.1.23 → 1.1.25

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";
@@ -113,6 +114,62 @@ export const providerKinds = Object.keys(KINDS);
 export function isProviderKind(name) {
     return Object.hasOwn(KINDS, name);
 }
+export function vertexRoute(model) {
+    if (/^(anthropic\/)?claude-/.test(model)) {
+        return 'anthropic';
+    }
+    return model.includes('/') ? 'openai' : 'gemini';
+}
+/** The protocol one model on one kind is spoken in. Only Vertex has more than one. */
+function protocolOf(kind, model) {
+    return kind === 'vertex' ? vertexRoute(model) : KINDS[kind].protocol;
+}
+/** The OpenAI-compatible endpoint on Vertex has chat completions and nothing else. */
+function apisOf(kind, protocol) {
+    return kind === 'vertex' && protocol === 'openai' ? ['chat'] : KINDS[kind].apis;
+}
+// ---------------------------------------------------------------------------
+// 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
 // ---------------------------------------------------------------------------
@@ -171,7 +228,11 @@ export class ModelRegistry {
         this.#providers.set(name, spec);
         // Re-declaring after a client was handed out would otherwise leave the
         // old credentials in service for the rest of the process.
-        this.#clients.delete(name);
+        for (const key of this.#clients.keys()) {
+            if (key === name || key.startsWith(`${name}\0`)) {
+                this.#clients.delete(key);
+            }
+        }
         this.#limiters.delete(name);
         return this;
     }
@@ -204,6 +265,17 @@ export class ModelRegistry {
         this.#clients.set(name, built);
         return built;
     }
+    /** A Vertex provider's Claude or partner client: built once, beside its GenAI one. */
+    #partner(name, protocol, spec) {
+        const key = `${name}\0${protocol}`;
+        const existing = this.#clients.get(key);
+        if (existing) {
+            return existing;
+        }
+        const built = buildVertexPartner(name, protocol, spec);
+        this.#clients.set(key, built);
+        return built;
+    }
     /**
      * The pacing shared by every embedder on a provider, so that what one of
      * them learns from a 429 the others do not have to learn again — and so
@@ -225,41 +297,71 @@ 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 kind = this.kindOf(spec.provider ?? this.#default);
+        const protocol = protocolOf(kind, spec.model);
+        if (protocol !== 'openai') {
+            return unreadKnobs(spec, protocol);
+        }
+        // An api this vendor does not speak already has an error of its own;
+        // answering about its knobs would only bury it.
+        const apis = apisOf(kind, protocol);
+        const api = spec.api ?? apis[0];
+        return api && 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;
         const name = spec.provider ?? this.#default;
         const provider = this.#spec(name);
         const kind = this.kindOf(name);
-        const defaults = KINDS[kind];
+        const protocol = protocolOf(kind, spec.model);
+        // 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.
         const client = spec.client ??
-            (hasCredentials(spec) ? buildClient(name, kind, spec, provider) : this.client(name));
+            (protocol !== KINDS[kind].protocol
+                ? this.#partner(name, protocol, provider)
+                : hasCredentials(spec)
+                    ? buildClient(name, kind, spec, provider)
+                    : this.client(name));
         // The *resolved* name, not `spec.provider`: a bare ref carries none,
         // and a failure that cannot say which connection refused it is the
         // thing this is here to prevent.
         const options = { ...spec, provider: name };
         // Every protocol but OpenAI's has exactly one API, so naming one is a
         // mistake worth reporting rather than a field to ignore.
-        if (defaults.protocol !== 'openai') {
+        if (protocol !== 'openai') {
             if (spec.api) {
                 throw new TypeError(`provider "${name}" (${kind}) has one api, so "${spec.api}" means nothing here`);
             }
-            switch (defaults.protocol) {
+            switch (protocol) {
                 case 'anthropic':
-                    return new AnthropicModel(spec.model, client, options);
+                    return new AnthropicModel(spec.model.replace(/^anthropic\//, ''), client, options);
                 case 'gemini':
                     return new GeminiModel(spec.model, client, options);
                 case 'openrouter':
                     return new OpenRouterModel(spec.model, client, options);
             }
         }
-        const api = spec.api ?? defaults.apis[0];
-        if (!defaults.apis.includes(api)) {
+        const apis = apisOf(kind, protocol);
+        const api = spec.api ?? apis[0];
+        if (!apis.includes(api)) {
             throw new TypeError(`provider "${name}" (${kind}) does not speak the "${api}" api ` +
-                `(supported: ${defaults.apis.join(', ')})`);
+                `(supported: ${apis.join(', ')})`);
         }
         return api === 'responses'
             ? new OpenAIResponsesModel(spec.model, client, options)
@@ -457,7 +559,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);
@@ -592,6 +694,109 @@ function projectFromKeyFile() {
         return undefined;
     }
 }
+// ---------------------------------------------------------------------------
+// Vertex partner models
+// ---------------------------------------------------------------------------
+/** Gemini has these; the partner endpoints do not, and answer them with a bare 404. */
+const MULTI_REGIONS = new Set(['us', 'eu']);
+/**
+ * Where a Vertex provider's partner models are served, and how to authenticate
+ * there. The GenAI SDK does both for Gemini; nothing does them for Claude or
+ * the OpenAI-compatible endpoint, so they are resolved here the same way:
+ * `project`, then GOOGLE_CLOUD_PROJECT, then the service-account file.
+ */
+export function vertexEndpoint(spec = {}, name = 'vertex') {
+    const where = `provider "${name}"`;
+    const project = expand(spec.project, `${where}: project`) ??
+        fromEnv('GOOGLE_CLOUD_PROJECT') ??
+        projectFromKeyFile();
+    if (!project) {
+        throw new Error(`${where}: Claude and partner models on vertex need \`project\`, or ` +
+            `GOOGLE_CLOUD_PROJECT, and a service account — an express-mode key reaches Gemini only`);
+    }
+    const named = expand(spec.location, `${where}: location`) ?? fromEnv('GOOGLE_CLOUD_LOCATION') ?? 'global';
+    const location = MULTI_REGIONS.has(named) ? 'global' : named;
+    const host = location === 'global'
+        ? 'https://aiplatform.googleapis.com'
+        : `https://${location}-aiplatform.googleapis.com`;
+    const token = spec.token;
+    return {
+        project,
+        location,
+        base: `${host}/v1/projects/${project}/locations/${location}`,
+        token: token ? async () => token() : adcToken(),
+    };
+}
+/** Mints and refreshes tokens the way the GenAI SDK does for Gemini. */
+function adcToken() {
+    let auth;
+    return async () => {
+        if (!auth) {
+            // `@google/genai`'s own dependency, so it is resolved from there rather than declared twice.
+            const genai = sdkPath('@google/genai', 'vertex');
+            const { GoogleAuth } = createRequire(genai)('google-auth-library');
+            auth = new GoogleAuth({ scopes: ['https://www.googleapis.com/auth/cloud-platform'] });
+        }
+        const token = await auth.getAccessToken();
+        if (!token) {
+            throw new Error('vertex: Application Default Credentials gave no access token');
+        }
+        return token;
+    };
+}
+function sdkPath(pkg, kind) {
+    try {
+        return requirePeer.resolve(pkg);
+    }
+    catch (cause) {
+        throw new Error(`provider kind "${kind}" needs ${pkg}, which is not installed — run: npm i ${pkg}`, { cause });
+    }
+}
+function buildVertexPartner(name, protocol, opts) {
+    const at = vertexEndpoint(opts, name);
+    const common = {
+        apiKey: OAUTH_PLACEHOLDER,
+        defaultHeaders: expandHeaders(opts.headers, `provider "${name}"`),
+        timeout: opts.timeoutMs,
+        maxRetries: retriesOf(opts),
+    };
+    if (protocol === 'anthropic') {
+        const { Anthropic } = sdk('@anthropic-ai/sdk', 'vertex');
+        return new Anthropic({
+            ...common,
+            baseURL: at.base,
+            fetch: funded(rawPredictFetch(at.base, at.token)),
+        });
+    }
+    const { OpenAI } = sdk('openai', 'vertex');
+    return new OpenAI({
+        ...common,
+        baseURL: `${at.base}/endpoints/openapi`,
+        fetch: funded(bearerFetch(at.token)),
+    });
+}
+/**
+ * Anthropic's client posts to `/v1/messages`; Vertex wants the model in the
+ * path and its own `anthropic_version` in the body instead.
+ */
+function rawPredictFetch(base, token) {
+    const authed = bearerFetch(token);
+    return async (input, init) => {
+        const url = input instanceof Request ? input.url : String(input);
+        if (!new URL(url).pathname.endsWith('/v1/messages') || typeof init?.body !== 'string') {
+            return authed(input, init);
+        }
+        const { model, ...body } = JSON.parse(init.body);
+        const headers = new Headers(init.headers);
+        headers.delete('x-api-key');
+        const verb = body.stream ? 'streamRawPredict' : 'rawPredict';
+        return authed(`${base}/publishers/anthropic/models/${model}:${verb}`, {
+            ...init,
+            headers,
+            body: JSON.stringify({ ...body, anthropic_version: 'vertex-2023-10-16' }),
+        });
+    };
+}
 // Both SDKs refuse to construct without a key. When a token callback owns the
 // Authorization header this value is never sent, so it only has to be non-empty.
 const OAUTH_PLACEHOLDER = 'oauth';
@@ -608,6 +813,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/runner.js

@@ -449,6 +449,13 @@ export class AgentRunner {
         catch (e) {
             return fail(`error: arguments are not valid JSON: ${String(e)}`);
         }
+        if (typeof args !== 'object' || args === null || Array.isArray(args)) {
+            return fail(`error: arguments to ${def.name} must be a JSON object`);
+        }
+        const missing = (def.parameters.required ?? []).filter((k) => args[k] == null);
+        if (missing.length) {
+            return fail(`error: ${def.name} is missing required arguments: ${missing.join(', ')}`);
+        }
         try {
             const out = await def.execute(args, {
                 ctx: state.context,

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