@zenera/neo 1.1.24 → 1.1.25

package/dist/index.d.ts

@@ -9,6 +9,9 @@ export * from './frontmatter.ts';
 export * from './ids.ts';
 export * from './inspect/index.ts';
 export * as Kernel from './kernel.ts';
+export * from './lock.ts';
+export * from './match.ts';
+export * from './memory/diff.ts';
 export * from './memory/files.ts';
 export * from './memory/graph.ts';
 export * from './memory/grep.ts';

package/dist/index.js

@@ -9,6 +9,9 @@ export * from "./frontmatter.js";
 export * from "./ids.js";
 export * from "./inspect/index.js";
 export * as Kernel from "./kernel.js";
+export * from "./lock.js";
+export * from "./match.js";
+export * from "./memory/diff.js";
 export * from "./memory/files.js";
 export * from "./memory/graph.js";
 export * from "./memory/grep.js";

package/dist/lock.d.ts

@@ -0,0 +1,27 @@
+export interface Lock {
+    pid: number;
+    host: string;
+    startedAt: string;
+}
+/** A lock body for this process, with whatever else the holder wants to say. */
+export declare function ownLock<T extends object>(extra?: T): Lock & T;
+/**
+ * `kill(pid, 0)` sends no signal and only asks whether the process exists.
+ * EPERM means it exists and belongs to someone else, which still counts.
+ */
+export declare function pidAlive(pid: number): boolean;
+/** The lock file as written, or undefined when absent or unreadable. */
+export declare function readLock<T extends Lock = Lock>(path: string): T | undefined;
+/**
+ * Who holds a lock right now, if anyone. Read-only: it never claims the lock
+ * and never clears a stale one. A lock from another host cannot be verified
+ * here, so it is not reported as held.
+ */
+export declare function liveHolder<T extends Lock = Lock>(path: string): T | undefined;
+/**
+ * Writes `lock` to `path`, or calls `refuse` with the live holder and throws
+ * what it returns. `wx` makes the create and the check one operation, so two
+ * processes racing for the same directory cannot both win.
+ */
+export declare function claimLock<T extends Lock>(path: string, lock: T, refuse: (held: T) => Error, indent?: number): void;
+//# sourceMappingURL=lock.d.ts.map

package/dist/lock.js

@@ -0,0 +1,66 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { hostname } from 'node:os';
+/** A lock body for this process, with whatever else the holder wants to say. */
+export function ownLock(extra) {
+    return {
+        pid: process.pid,
+        host: hostname(),
+        startedAt: new Date().toISOString(),
+        ...extra,
+    };
+}
+/**
+ * `kill(pid, 0)` sends no signal and only asks whether the process exists.
+ * EPERM means it exists and belongs to someone else, which still counts.
+ */
+export function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+/** The lock file as written, or undefined when absent or unreadable. */
+export function readLock(path) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Who holds a lock right now, if anyone. Read-only: it never claims the lock
+ * and never clears a stale one. A lock from another host cannot be verified
+ * here, so it is not reported as held.
+ */
+export function liveHolder(path) {
+    const held = readLock(path);
+    return held && held.host === hostname() && pidAlive(held.pid) ? held : undefined;
+}
+/**
+ * Writes `lock` to `path`, or calls `refuse` with the live holder and throws
+ * what it returns. `wx` makes the create and the check one operation, so two
+ * processes racing for the same directory cannot both win.
+ */
+export function claimLock(path, lock, refuse, indent = 4) {
+    const body = `${JSON.stringify(lock, null, indent)}\n`;
+    try {
+        writeFileSync(path, body, { flag: 'wx' });
+        return;
+    }
+    catch (err) {
+        if (err.code !== 'EEXIST') {
+            throw err;
+        }
+    }
+    const held = liveHolder(path);
+    if (held) {
+        throw refuse(held);
+    }
+    // Stale, or from another machine's run that cannot be verified here.
+    writeFileSync(path, body);
+}
+//# sourceMappingURL=lock.js.map

package/dist/match.d.ts

@@ -0,0 +1,44 @@
+/** Long enough for any honest pattern, short enough to bound a bad one. */
+export declare const MAX_PATTERN = 200;
+export declare class PatternError extends Error {
+}
+export interface MatchOptions {
+    /** read the pattern as a regular expression rather than as a literal */
+    regex?: boolean;
+    caseSensitive?: boolean;
+}
+export type Matcher = (text: string) => boolean;
+/** The offset of the first match in `text`, or -1. */
+export type Finder = (text: string) => number;
+/**
+ * Where a pattern first occurs. Literal by default: someone typing `user.id`
+ * means those seven characters, and a dot that quietly matched anything would
+ * be a worse answer than no answer.
+ */
+export declare function finder(pattern: string, options?: MatchOptions): Finder;
+/** Whether a pattern occurs at all, read the same way `finder` reads it. */
+export declare function matcher(pattern: string, options?: MatchOptions): Matcher;
+/**
+ * A glob, matched against the whole string. Globs rather than regexes because
+ * these are for naming things — a path, a schema — and a star is what everyone
+ * reaches for first.
+ */
+export declare function wildcard(pattern: string, options?: {
+    caseSensitive?: boolean;
+}): Matcher;
+/** Whether a pattern is asking to be read as a glob at all. */
+export declare const isGlob: (pattern: string) => boolean;
+/**
+ * What someone means when they type a name into a filter. With a star in it,
+ * a glob; without one, a substring — because `password` typed into `--name` is
+ * a search for the word, and a whole-string match would answer nothing and
+ * look like the field does not exist.
+ *
+ * `regex` settles it outright, and has to: a star is punctuation in both
+ * languages, so `^/(users|teams)/.*` read as a glob would match nothing and
+ * never say why.
+ */
+export declare function loose(pattern: string, options?: MatchOptions): Matcher;
+/** True when any of the patterns matches; no patterns means no opinion. */
+export declare function anyOf(matchers: readonly Matcher[]): Matcher | undefined;
+//# sourceMappingURL=match.d.ts.map

package/dist/match.js

@@ -0,0 +1,100 @@
+// ---------------------------------------------------------------------------
+// Matching, with nothing learned in between
+//
+// Everything here is exact. A glob matches the characters it names and a
+// substring is a substring, which is the whole point of the surfaces built on
+// it: a vector index answers "what is near this", and near is a ranking, so it
+// can only ever return the top of a list. When the question is "does the word
+// `password` appear anywhere at all", a ranking is the wrong instrument and no
+// amount of tuning makes it the right one.
+//
+// Memory grep and @zenera/rag's lookups both stand on this. A `finder` says
+// *where*, for grep, which reports the line; a `matcher` says *whether*.
+//
+// A pattern may arrive from a model, so a regex is a bounded promise: the
+// length is capped here and the scan that uses it keeps a deadline.
+// ---------------------------------------------------------------------------
+/** Long enough for any honest pattern, short enough to bound a bad one. */
+export const MAX_PATTERN = 200;
+export class PatternError extends Error {
+}
+/**
+ * Where a pattern first occurs. Literal by default: someone typing `user.id`
+ * means those seven characters, and a dot that quietly matched anything would
+ * be a worse answer than no answer.
+ */
+export function finder(pattern, options = {}) {
+    guard(pattern);
+    if (!options.regex) {
+        if (options.caseSensitive) {
+            return (text) => text.indexOf(pattern);
+        }
+        const needle = pattern.toLowerCase();
+        return (text) => text.toLowerCase().indexOf(needle);
+    }
+    const expression = compile(pattern, options.caseSensitive ? '' : 'i');
+    // `lastIndex` is not carried between calls: the flags never include `g`.
+    return (text) => text.search(expression);
+}
+/** Whether a pattern occurs at all, read the same way `finder` reads it. */
+export function matcher(pattern, options = {}) {
+    const find = finder(pattern, options);
+    return (text) => find(text) >= 0;
+}
+/**
+ * A glob, matched against the whole string. Globs rather than regexes because
+ * these are for naming things — a path, a schema — and a star is what everyone
+ * reaches for first.
+ */
+export function wildcard(pattern, options = {}) {
+    guard(pattern);
+    const source = [...pattern]
+        .map((char) => (char === '*' ? '.*' : char === '?' ? '.' : escape(char)))
+        .join('');
+    const expression = compile(`^${source}$`, options.caseSensitive ? '' : 'i');
+    return (text) => expression.test(text);
+}
+/** Whether a pattern is asking to be read as a glob at all. */
+export const isGlob = (pattern) => /[*?]/.test(pattern);
+/**
+ * What someone means when they type a name into a filter. With a star in it,
+ * a glob; without one, a substring — because `password` typed into `--name` is
+ * a search for the word, and a whole-string match would answer nothing and
+ * look like the field does not exist.
+ *
+ * `regex` settles it outright, and has to: a star is punctuation in both
+ * languages, so `^/(users|teams)/.*` read as a glob would match nothing and
+ * never say why.
+ */
+export function loose(pattern, options = {}) {
+    if (options.regex) {
+        return matcher(pattern, options);
+    }
+    return isGlob(pattern) ? wildcard(pattern, options) : matcher(pattern, options);
+}
+/** True when any of the patterns matches; no patterns means no opinion. */
+export function anyOf(matchers) {
+    if (matchers.length === 0) {
+        return undefined;
+    }
+    return (text) => matchers.some((match) => match(text));
+}
+// ---------------------------------------------------------------------------
+function guard(pattern) {
+    if (pattern.length === 0) {
+        throw new PatternError('the pattern is empty');
+    }
+    if (pattern.length > MAX_PATTERN) {
+        throw new PatternError(`the pattern is longer than ${MAX_PATTERN} characters`);
+    }
+}
+function compile(source, flags) {
+    try {
+        return new RegExp(source, flags);
+    }
+    catch (err) {
+        throw new PatternError(`invalid pattern: ${err.message}`);
+    }
+}
+const escape = (char) => char.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+//# sourceMappingURL=match.js.map

package/dist/memory/diff.d.ts

@@ -0,0 +1,39 @@
+import type { MemoryStore } from './store.ts';
+import type { MemoryNode } from './types.ts';
+export interface MemoryNearest {
+    id: string;
+    score: number;
+    text: string;
+}
+export interface MemoryDiffAdded {
+    node: MemoryNode;
+    /** the closest comparable node the base held, if any */
+    nearest?: MemoryNearest;
+    /** `merge` would fold it onto `nearest`: the base already said this */
+    twin: boolean;
+}
+export interface MemoryDiff {
+    base: string;
+    other: string;
+    /** how `nearest` was scored: cosine when both sides hold vectors, else term overlap */
+    by: 'vector' | 'text';
+    added: MemoryDiffAdded[];
+    revised: {
+        before: MemoryNode;
+        after: MemoryNode;
+    }[];
+    /** base nodes `memory_load` returned since — what the run actually read */
+    used: {
+        node: MemoryNode;
+        loads: number;
+    }[];
+    removed: MemoryNode[];
+    /** edges `other` has that `base` did not */
+    edges: number;
+    supersedes: {
+        source: string;
+        target: string;
+    }[];
+}
+export declare function diffMemories(base: MemoryStore, other: MemoryStore): MemoryDiff;
+//# sourceMappingURL=diff.d.ts.map

package/dist/memory/diff.js

@@ -0,0 +1,95 @@
+import { DUPLICATE_SCORE } from "./index.js";
+import { comparable, sameContent, twinKey } from "./twin.js";
+import { overlap, tokenize } from "./vectors.js";
+export function diffMemories(base, other) {
+    const stale = base.graph.superseded();
+    const block = base.vectors;
+    const theirs = other.vectors;
+    const byVector = !!block?.rows && !!theirs && theirs.dims === block.dims;
+    const held = base.graph.nodes();
+    const lexical = new Map(held.filter((n) => !stale.has(n.id)).map((n) => [twinKey(n), n.id]));
+    const nearestOf = (node) => {
+        if (node.file) {
+            return { twin: false };
+        }
+        const allow = (id) => {
+            const n = base.graph.get(id);
+            return !stale.has(id) && !!n && comparable(n, node);
+        };
+        const exact = lexical.get(twinKey(node));
+        const vector = byVector ? theirs.get(node.id) : undefined;
+        if (vector) {
+            const hit = block.topK(vector, 1, allow)[0];
+            if (hit) {
+                const text = base.graph.get(hit.id).text;
+                return {
+                    nearest: { id: hit.id, score: hit.score, text },
+                    twin: hit.score >= DUPLICATE_SCORE,
+                };
+            }
+        }
+        if (exact) {
+            return {
+                nearest: { id: exact, score: 1, text: base.graph.get(exact).text },
+                twin: true,
+            };
+        }
+        const words = tokenize(node.text);
+        let best;
+        for (const n of held) {
+            if (!allow(n.id)) {
+                continue;
+            }
+            const score = overlap(words, tokenize(n.text));
+            if (score > 0 && (!best || score > best.score)) {
+                best = { id: n.id, score, text: n.text };
+            }
+        }
+        return { nearest: best, twin: false };
+    };
+    const diff = {
+        base: base.dir,
+        other: other.dir,
+        by: byVector ? 'vector' : 'text',
+        added: [],
+        revised: [],
+        used: [],
+        removed: [],
+        edges: 0,
+        supersedes: [],
+    };
+    for (const after of other.graph.nodes()) {
+        const before = base.graph.get(after.id);
+        if (!before) {
+            diff.added.push({ node: after, ...nearestOf(after) });
+            continue;
+        }
+        if (before.revision !== after.revision || !sameContent(before, after)) {
+            diff.revised.push({ before, after });
+        }
+        if (after.useCount > before.useCount) {
+            diff.used.push({ node: after, loads: after.useCount - before.useCount });
+        }
+    }
+    for (const node of held) {
+        if (!other.graph.has(node.id)) {
+            diff.removed.push(node);
+        }
+    }
+    const key = (source, target, relation) => `${source}\u0000${target}\u0000${relation}`;
+    const had = new Set(base.graph.links().map((l) => key(l.source, l.target, l.attrs.relation)));
+    for (const link of other.graph.links()) {
+        if (had.has(key(link.source, link.target, link.attrs.relation))) {
+            continue;
+        }
+        diff.edges++;
+        if (link.attrs.relation === 'SUPERSEDES') {
+            diff.supersedes.push({ source: link.source, target: link.target });
+        }
+    }
+    const newest = (a, b) => b.node.createdAt.localeCompare(a.node.createdAt);
+    diff.added.sort(newest);
+    diff.used.sort((a, b) => b.loads - a.loads);
+    return diff;
+}
+//# sourceMappingURL=diff.js.map

package/dist/memory/files.d.ts

@@ -20,7 +20,7 @@ export interface RememberOptions {
  */
 export declare function rememberFile(dir: string, source: string, id: string, opts?: RememberOptions): Promise<MemoryFile>;
 /** The host path of a remembered file, for reading it back or deleting it. */
-export declare function hostPath(dir: string, file: MemoryFile): string;
+export declare function hostPath(dir: string, file: Pick<MemoryFile, 'path'>): string;
 /** Drop the bytes of a forgotten node. Missing is success — the goal is absence. */
 export declare function forgetFile(dir: string, file: MemoryFile): Promise<void>;
 //# sourceMappingURL=files.d.ts.map

package/dist/memory/grep.d.ts

@@ -1,4 +1,4 @@
-import { type MatchOptions } from './match.ts';
+import { type MatchOptions } from '../match.ts';
 import type { Omitted } from './report.ts';
 import type { MemoryStore } from './store.ts';
 import { type MemoryNode } from './types.ts';

package/dist/memory/grep.js

@@ -1,6 +1,6 @@
 import { readFile, stat } from 'node:fs/promises';
+import { PatternError, finder } from "../match.js";
 import { hostPath } from "./files.js";
-import { PatternError, matcher } from "./match.js";
 import { MemoryError } from "./types.js";
 // ---------------------------------------------------------------------------
 // The memory, read exhaustively
@@ -106,7 +106,7 @@ export async function grepMemory(store, pattern, filter = {}) {
  */
 function compile(pattern, options) {
     try {
-        return matcher(pattern, options);
+        return finder(pattern, options);
     }
     catch (err) {
         if (err instanceof PatternError) {

package/dist/memory/merge.js

@@ -4,6 +4,7 @@ import { join, resolve } from 'node:path';
 import { hostPath } from "./files.js";
 import { DUPLICATE_SCORE, flatten } from "./index.js";
 import { MANIFEST_FILE, MemoryStore, lockHolder } from "./store.js";
+import { comparable, sameContent, twinKey } from "./twin.js";
 import { MemoryError } from "./types.js";
 // ---------------------------------------------------------------------------
 // Folding several memories into one
@@ -251,15 +252,6 @@ function twinOf(target, src, node, lexical, stale) {
     const id = lexical.get(twinKey(node));
     return id && !stale.has(id) ? id : undefined;
 }
-function comparable(a, b) {
-    return a.id !== b.id && a.kind === b.kind && !a.file && audienceKey(a) === audienceKey(b);
-}
-function twinKey(node) {
-    return [node.kind, audienceKey(node), flatten(node.text)].join('\u0000');
-}
-function audienceKey(node) {
-    return [...node.audience].sort().join('|');
-}
 function carryVector(from, to, id) {
     const vector = from.vectors?.get(id);
     const block = to.vectors;
@@ -284,28 +276,6 @@ function reconcile(keep, other) {
 function newer(a, b) {
     return a.revision === b.revision ? a.updatedAt > b.updatedAt : a.revision > b.revision;
 }
-function sameContent(a, b) {
-    return (a.kind === b.kind &&
-        a.text === b.text &&
-        audienceKey(a) === audienceKey(b) &&
-        a.file?.sha256 === b.file?.sha256 &&
-        deep(a.metadata, b.metadata));
-}
-function deep(a, b) {
-    if (a === b) {
-        return true;
-    }
-    if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) {
-        return false;
-    }
-    if (Array.isArray(a) !== Array.isArray(b)) {
-        return false;
-    }
-    const left = a;
-    const right = b;
-    const keys = Object.keys(left);
-    return keys.length === Object.keys(right).length && keys.every((k) => deep(left[k], right[k]));
-}
 /** Stat every file the merge would copy before it copies any of them. */
 async function checkFiles(plan) {
     for (const planned of plan.values()) {

package/dist/memory/store.d.ts

@@ -1,3 +1,4 @@
+import { type Lock } from '../lock.ts';
 import { MemoryGraph } from './graph.ts';
 import { VectorBlock } from './vectors.ts';
 export declare const MEMORY_VERSION = 1;
@@ -19,11 +20,6 @@ export interface MemoryManifest {
     edges: number;
     updatedAt: string;
 }
-export interface Lock {
-    pid: number;
-    host: string;
-    startedAt: string;
-}
 export interface OpenOptions {
     /** the embedder the caller intends to use; a mismatch with the manifest is fatal */
     embedding?: MemoryEmbedding;

package/dist/memory/store.js

@@ -1,7 +1,7 @@
-import { readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { unlinkSync } from 'node:fs';
 import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
-import { hostname } from 'node:os';
 import { join } from 'node:path';
+import { claimLock, liveHolder, ownLock } from "../lock.js";
 import { MemoryGraph } from "./graph.js";
 import { MemoryError } from "./types.js";
 import { VectorBlock } from "./vectors.js";
@@ -143,33 +143,8 @@ export class MemoryStore {
             // Already gone, or taken over as stale: neither is worth failing a run for.
         }
     }
-    /**
-     * `wx` makes the create and the check one operation, so two runs racing for
-     * the same project cannot both win.
-     */
     #claim() {
-        const path = join(this.dir, LOCK_FILE);
-        const lock = {
-            pid: process.pid,
-            host: hostname(),
-            startedAt: new Date().toISOString(),
-        };
-        const body = `${JSON.stringify(lock, null, 4)}\n`;
-        try {
-            writeFileSync(path, body, { flag: 'wx' });
-            this.#locked = true;
-            return;
-        }
-        catch (err) {
-            if (err.code !== 'EEXIST') {
-                throw err;
-            }
-        }
-        const held = readLock(path);
-        if (held && held.host === hostname() && alive(held.pid)) {
-            throw new MemoryError(`this memory is in use (pid ${held.pid}, since ${held.startedAt})`, 'wait for that run to finish, or remove .lock if it crashed');
-        }
-        writeFileSync(path, body);
+        claimLock(join(this.dir, LOCK_FILE), ownLock(), (held) => new MemoryError(`this memory is in use (pid ${held.pid}, since ${held.startedAt})`, 'wait for that run to finish, or remove .lock if it crashed'));
         this.#locked = true;
     }
 }
@@ -226,28 +201,6 @@ async function atomic(path, body) {
  * directory this process has no intention of opening for writing.
  */
 export function lockHolder(dir) {
-    const held = readLock(join(dir, LOCK_FILE));
-    return held && held.host === hostname() && alive(held.pid) ? held : undefined;
-}
-function readLock(path) {
-    try {
-        return JSON.parse(readFileSync(path, 'utf8'));
-    }
-    catch {
-        return undefined;
-    }
-}
-/**
- * `kill(pid, 0)` sends no signal and only asks whether the process exists.
- * EPERM means it exists and belongs to someone else, which still counts.
- */
-function alive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (err) {
-        return err.code === 'EPERM';
-    }
+    return liveHolder(join(dir, LOCK_FILE));
 }
 //# sourceMappingURL=store.js.map

package/dist/memory/twin.d.ts

@@ -0,0 +1,6 @@
+import type { MemoryNode } from './types.ts';
+export declare function comparable(a: MemoryNode, b: MemoryNode): boolean;
+export declare function twinKey(node: MemoryNode): string;
+export declare function audienceKey(node: MemoryNode): string;
+export declare function sameContent(a: MemoryNode, b: MemoryNode): boolean;
+//# sourceMappingURL=twin.d.ts.map

package/dist/memory/twin.js

@@ -0,0 +1,40 @@
+import { flatten } from "./index.js";
+// ---------------------------------------------------------------------------
+// When two memories are the same memory
+//
+// Shared by `merge`, which folds a twin onto the node already held, and `diff`,
+// which reports it. One rule, so what diff calls a re-commit is exactly what
+// merge would have folded.
+// ---------------------------------------------------------------------------
+export function comparable(a, b) {
+    return a.id !== b.id && a.kind === b.kind && !a.file && audienceKey(a) === audienceKey(b);
+}
+export function twinKey(node) {
+    return [node.kind, audienceKey(node), flatten(node.text)].join('\u0000');
+}
+export function audienceKey(node) {
+    return [...node.audience].sort().join('|');
+}
+export function sameContent(a, b) {
+    return (a.kind === b.kind &&
+        a.text === b.text &&
+        audienceKey(a) === audienceKey(b) &&
+        a.file?.sha256 === b.file?.sha256 &&
+        deep(a.metadata, b.metadata));
+}
+function deep(a, b) {
+    if (a === b) {
+        return true;
+    }
+    if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) {
+        return false;
+    }
+    if (Array.isArray(a) !== Array.isArray(b)) {
+        return false;
+    }
+    const left = a;
+    const right = b;
+    const keys = Object.keys(left);
+    return keys.length === Object.keys(right).length && keys.every((k) => deep(left[k], right[k]));
+}
+//# sourceMappingURL=twin.js.map

package/dist/models/factory.d.ts

@@ -150,6 +150,15 @@ export interface ModelRequirement {
 }
 export declare const providerKinds: ProviderKind[];
 export declare function isProviderKind(name: string): name is ProviderKind;
+/**
+ * Vertex serves three request formats behind one account, and the model id
+ * says which: Google's own models through the GenAI API, Claude through
+ * Anthropic's Messages format at `rawPredict`, and every other publisher's
+ * (`xai/grok-4.1-fast-reasoning`, `qwen/qwen3-…-maas`) through the
+ * OpenAI-compatible endpoint, which names its models `publisher/model`.
+ */
+export type VertexRoute = 'gemini' | 'anthropic' | 'openai';
+export declare function vertexRoute(model: string): VertexRoute;
 /**
  * Which knobs each adapter actually reads.
  *
@@ -240,6 +249,21 @@ export declare class ModelRegistry {
     /** A declared kind wins; otherwise a built-in name is its own kind. */
     kindOf(name: string): ProviderKind;
 }
+export interface VertexEndpoint {
+    project: string;
+    location: string;
+    /** `https://…/v1/projects/<project>/locations/<location>` */
+    base: string;
+    /** a fresh access token from Application Default Credentials, or `spec.token` */
+    token: () => Promise<string>;
+}
+/**
+ * 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 declare function vertexEndpoint(spec?: ProviderSpec, name?: string): VertexEndpoint;
 /**
  * The registry behind the bare `createModel`. An application that never
  * declares a provider still gets shared clients through it, because the

package/dist/models/factory.js

@@ -114,6 +114,20 @@ 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
 // ---------------------------------------------------------------------------
@@ -214,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;
     }
@@ -247,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
@@ -275,14 +304,16 @@ export class ModelRegistry {
      */
     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);
+        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 api = spec.api ?? defaults.apis[0];
-        return api && defaults.apis.includes(api) ? unreadKnobs(spec, `openai/${api}`) : [];
+        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) {
@@ -290,7 +321,7 @@ export class ModelRegistry {
         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);
@@ -302,30 +333,35 @@ export class ModelRegistry {
         // 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)
@@ -658,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';

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/sandbox.js

@@ -243,7 +243,10 @@ export class Sandbox {
             this.#created = true;
             return;
         }
-        await this.#must(this.#createArgs(), `could not create container ${this.name}`);
+        const made = await this.#podman(this.#createArgs());
+        if (made.code !== 0) {
+            throw new SandboxError(`could not create container ${this.name}: ${message(made)}`, LOCKS.test(made.stderr) ? locksHint(this.spec.engine) : undefined);
+        }
         this.#created = true;
     }
     #createArgs() {
@@ -320,7 +323,13 @@ export class Sandbox {
         const cwd = this.inside(opts.cwd);
         const timeoutMs = this.#timeout(opts.timeout);
         const startedAt = Date.now();
-        const res = await this.#run(this.spec.engine, ['exec', '--interactive', '--workdir', cwd, this.name, '/bin/sh', '-s'], { input: command, timeoutMs, signal: opts.signal });
+        const once = () => this.#run(this.spec.engine, ['exec', '--interactive', '--workdir', cwd, this.name, '/bin/sh', '-s'], { input: command, timeoutMs, signal: opts.signal });
+        let res = await once();
+        if (gone(res)) {
+            // podman refused before running anything, so the retry cannot run the command twice.
+            await this.#revive(res);
+            res = await once();
+        }
         return {
             exit_code: res.code,
             stdout: res.stdout,
@@ -527,6 +536,18 @@ export class Sandbox {
     #podman(args) {
         return this.#run(this.spec.engine, args, { timeoutMs: 120_000 });
     }
+    /** The container stopped or vanished under us (machine slept, restarted, or someone removed it). */
+    async #revive(res) {
+        this.#ready = undefined;
+        try {
+            await this.start();
+        }
+        catch (err) {
+            throw new SandboxError(`the sandbox container ${this.name} stopped (${message(res)}) and could not be restarted: ` +
+                (err instanceof Error ? err.message : String(err)), `the ${this.spec.engine} machine may have stopped or restarted — check \`${this.spec.engine} machine list\`, ` +
+                `start it with \`${this.spec.engine} machine start\`, then retry`);
+        }
+    }
     async #must(args, what) {
         const res = await this.#podman(args);
         if (res.code !== 0) {
@@ -541,6 +562,23 @@ function mount(m) {
 function message(res) {
     return (res.stderr.trim() || res.stdout.trim() || `exit ${res.code}`).split('\n')[0];
 }
+/** podman's words for "every lock is taken": `allocating lock … exceeded num_locks (2048)`. */
+const LOCKS = /exceeded num_locks|allocating lock/i;
+/**
+ * A stopped container holds a lock as surely as a running one, and a
+ * persisted sandbox is stopped, never removed — so they pile up one per
+ * session until the engine can create nothing at all, for anyone.
+ */
+function locksHint(engine) {
+    return (`the ${engine} engine has no locks left: every container it holds, stopped ones ` +
+        `included, takes one. Remove the stopped sandbox containers with ` +
+        `\`${engine} container prune --force --filter label=zenera=1\`, then retry`);
+}
+/** podman's own exit code for "could not exec at all", with the two reasons that mean the container is not there to exec in. */
+function gone(res) {
+    return (res.code === 125 &&
+        /can only create exec sessions on running containers|container state improper|no such container/i.test(res.stderr));
+}
 /** Only ever applied to paths this module derived, never to a model's text. */
 function quote(s) {
     return `'${s.replaceAll("'", `'\\''`)}'`;

package/package.json

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

package/dist/memory/match.d.ts

@@ -1,18 +0,0 @@
-/** Long enough for any honest pattern, short enough to bound a bad one. */
-export declare const MAX_PATTERN = 200;
-export declare class PatternError extends Error {
-}
-export interface MatchOptions {
-    /** read the pattern as a regular expression rather than as a literal */
-    regex?: boolean;
-    caseSensitive?: boolean;
-}
-/** The offset of the first match in `text`, or -1. */
-export type Matcher = (text: string) => number;
-/**
- * A finder over a string. Literal by default: someone typing `user.id` means
- * those seven characters, and a dot that quietly matched anything would be a
- * worse answer than no answer.
- */
-export declare function matcher(pattern: string, options?: MatchOptions): Matcher;
-//# sourceMappingURL=match.d.ts.map

package/dist/memory/match.js

@@ -1,61 +0,0 @@
-// ---------------------------------------------------------------------------
-// Matching, with nothing learned in between
-//
-// Everything here is exact. A substring is a substring, which is the whole
-// point of the surface built on it: the vector index answers "what is near
-// this", and near is a ranking, so it can only ever return the top of a list.
-// When the question is "does the word `password` appear anywhere at all", a
-// ranking is the wrong instrument and no amount of tuning makes it the right
-// one.
-//
-// This is a copy of `common/match.ts` in @zenera/rag, and has to be: the
-// dependency runs rag → cli → neo, so neo importing rag would close a cycle.
-// Two differences earn their place rather than being drift. A matcher returns
-// the offset it matched at, because grep reports *where*, not merely whether;
-// and there are no globs, because the haystack here is prose and a glob is
-// anchored to the whole string, so `error*` would match a line only when the
-// line began with the word.
-//
-// A pattern may arrive from a model, so a regex is a bounded promise: the
-// length is capped here and the scan that uses it keeps a deadline.
-// ---------------------------------------------------------------------------
-/** Long enough for any honest pattern, short enough to bound a bad one. */
-export const MAX_PATTERN = 200;
-export class PatternError extends Error {
-}
-/**
- * A finder over a string. Literal by default: someone typing `user.id` means
- * those seven characters, and a dot that quietly matched anything would be a
- * worse answer than no answer.
- */
-export function matcher(pattern, options = {}) {
-    guard(pattern);
-    if (!options.regex) {
-        if (options.caseSensitive) {
-            return (text) => text.indexOf(pattern);
-        }
-        const needle = pattern.toLowerCase();
-        return (text) => text.toLowerCase().indexOf(needle);
-    }
-    const expression = compile(pattern, options.caseSensitive ? '' : 'i');
-    // `lastIndex` is not carried between calls: the flags never include `g`.
-    return (text) => text.search(expression);
-}
-// ---------------------------------------------------------------------------
-function guard(pattern) {
-    if (pattern.length === 0) {
-        throw new PatternError('the pattern is empty');
-    }
-    if (pattern.length > MAX_PATTERN) {
-        throw new PatternError(`the pattern is longer than ${MAX_PATTERN} characters`);
-    }
-}
-function compile(source, flags) {
-    try {
-        return new RegExp(source, flags);
-    }
-    catch (err) {
-        throw new PatternError(`invalid pattern: ${err.message}`);
-    }
-}
-//# sourceMappingURL=match.js.map