@zenera/neo 1.1.23 → 1.1.25

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,21 +20,23 @@ 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;
     /** take the directory lock; off for read-only inspection (`zen memory ls`) */
     lock?: boolean;
+    /**
+     * Recall, and nothing else. Writing is refused rather than dropped, the
+     * directory is never created, and no lock is taken — so any number of runs
+     * may share one graph at once, which is the whole point of it.
+     */
+    readOnly?: boolean;
 }
 export declare class MemoryStore {
     #private;
     readonly dir: string;
     readonly graph: MemoryGraph;
+    readonly readOnly: boolean;
     private constructor();
     static open(dir: string, opts?: OpenOptions): Promise<MemoryStore>;
     get embedding(): MemoryEmbedding | undefined;

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";
@@ -34,18 +34,29 @@ export const LOCK_FILE = '.lock';
 export class MemoryStore {
     dir;
     graph;
+    readOnly;
     #embedding;
     #vectors;
     #locked = false;
-    constructor(dir, graph, vectors, embedding) {
+    constructor(dir, graph, vectors, embedding, readOnly) {
         this.dir = dir;
         this.graph = graph;
         this.#vectors = vectors;
         this.#embedding = embedding;
+        this.readOnly = readOnly;
     }
     static async open(dir, opts = {}) {
-        await mkdir(join(dir, FILES_DIR), { recursive: true });
+        const readOnly = opts.readOnly === true;
+        if (!readOnly) {
+            await mkdir(join(dir, FILES_DIR), { recursive: true });
+        }
         const manifest = await readManifest(dir);
+        // Opening for writing brings a memory into existence; opening one to
+        // read from has to find it, or a mistyped path is an empty graph that
+        // answers every question with silence and reports no error.
+        if (readOnly && !manifest) {
+            throw new MemoryError(`${dir} is not a memory`, `no ${MANIFEST_FILE} in it, and a read-only open cannot create one`);
+        }
         if (manifest?.embedding && opts.embedding) {
             const a = manifest.embedding;
             const b = opts.embedding;
@@ -59,8 +70,10 @@ export class MemoryStore {
             : new MemoryGraph();
         const embedding = opts.embedding ?? manifest?.embedding;
         const vectors = manifest && embedding ? await readVectors(dir, embedding) : undefined;
-        const store = new MemoryStore(dir, graph, vectors, embedding);
-        if (opts.lock !== false) {
+        const store = new MemoryStore(dir, graph, vectors, embedding, readOnly);
+        // A reader that claimed the lock would only be refusing itself, and the
+        // readers of one graph are meant to be able to refuse each other least.
+        if (!readOnly && opts.lock !== false) {
             store.#claim();
         }
         return store;
@@ -97,6 +110,11 @@ export class MemoryStore {
     }
     /** Manifest last: a torn commit reads as no memory, never as a partial one. */
     async commit() {
+        // Loudly, not quietly. A write that is silently dropped is a run that
+        // believes it remembered something and did not.
+        if (this.readOnly) {
+            throw new MemoryError('this memory is open read-only', 'nothing this run learns can be kept — point it at a memory of its own');
+        }
         await atomic(join(this.dir, GRAPH_FILE), JSON.stringify(this.graph.export()));
         const vectors = this.#vectors;
         if (vectors) {
@@ -125,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;
     }
 }
@@ -208,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/tools.js

@@ -1,25 +1,30 @@
 /**
- * The four tools an agent gets. Deliberately four and not seven: `search` and
- * `load` are split because finding is not reading — search returns stitched
- * context the model never asked for, and counting that as use would poison
- * recency. `commit` is one transaction because a remembered thing is a
- * subgraph, and building it with three calls leaves the graph half-formed if
- * the model stops early. `forget` is separate because deleting rarely happens
- * in the same breath as creating, and a `forget` buried inside a truncated
- * commit preview would be both irreversible and invisible.
+ * The five tools an agent gets. `search` and `load` are split because finding
+ * is not reading — search returns stitched context the model never asked for,
+ * and counting that as use would poison recency. `grep` is separate from
+ * `search` because exactness is not a tuning of nearness: a ranking returns the
+ * top of a list, so it can say what is closest but never that nothing is there.
+ * `commit` is one transaction because a remembered thing is a subgraph, and
+ * building it with three calls leaves the graph half-formed if the model stops
+ * early. `forget` is separate because deleting rarely happens in the same
+ * breath as creating, and a `forget` buried inside a truncated commit preview
+ * would be both irreversible and invisible.
  *
  * `audience` reaches the schema only when the binding grants more than one
  * label, and `sees` never does: an agent that could name its own audience
  * could read another agent's slice just by asking for it.
  */
 import { hash } from "../payload.js";
-import { MEMORY_COMMIT_TOOL, MEMORY_FORGET_TOOL, MEMORY_LOAD_TOOL, MEMORY_SEARCH_TOOL, tool, withEffects, } from "../types.js";
+import { MEMORY_COMMIT_TOOL, MEMORY_FORGET_TOOL, MEMORY_GREP_TOOL, MEMORY_LOAD_TOOL, MEMORY_SEARCH_TOOL, tool, withEffects, } from "../types.js";
+import { GREP_FIELDS, grepMemory } from "./grep.js";
 import { renderRecollection } from "./render.js";
 import { canForget, canWrite, KIND_HELP, MemoryError, RELATION_HELP, } from "./types.js";
 /** Deterministic, so a replayed call is the same op and not a second one. */
 export function memoryOpId(runId, callId) {
     return hash(`${runId}\u0000${callId}`);
 }
+/** Enough nodes to settle a question, few enough not to be a context dump. */
+const GREPPED = 20;
 export function memoryTools(opts) {
     const { index, binding } = opts;
     const kinds = [...index.kinds];
@@ -131,6 +136,97 @@ export function memoryTools(opts) {
                 })), { kind: 'memory_op', spec });
             },
         }),
+        tool({
+            name: MEMORY_GREP_TOOL,
+            description: 'Find an exact string in memory, the way grep does: every node whose text, ' +
+                'metadata or remembered file contains it, with the matching lines. Use this ' +
+                `instead of ${MEMORY_SEARCH_TOOL} when the answer has to be complete rather ` +
+                'than close — whether something was already recorded, or where a name, path, ' +
+                'id or command appears. This is the only correct way to search the memory ' +
+                'directly; never run a shell grep over /memory. Read a whole node with ' +
+                `${MEMORY_LOAD_TOOL}.`,
+            parameters: {
+                type: 'object',
+                properties: {
+                    pattern: {
+                        type: 'string',
+                        description: 'the exact text to look for; matched case-insensitively',
+                    },
+                    regex: {
+                        type: 'boolean',
+                        description: 'read the pattern as a regular expression, matched per line',
+                    },
+                    case_sensitive: { type: 'boolean', description: 'match case exactly' },
+                    kinds: {
+                        type: 'array',
+                        items: { type: 'string', enum: kinds },
+                        description: 'restrict to these kinds',
+                    },
+                    in: {
+                        type: 'array',
+                        items: { type: 'string', enum: [...GREP_FIELDS] },
+                        description: 'which parts to look in; all of them by default',
+                    },
+                    include_superseded: {
+                        type: 'boolean',
+                        description: 'also search nodes that have been corrected by a newer one; they come back marked stale',
+                    },
+                    limit: { type: 'integer', description: `nodes to return; default ${GREPPED}` },
+                },
+                required: ['pattern'],
+                additionalProperties: false,
+            },
+            execute: async (args, tc) => {
+                const opId = memoryOpId(tc.state.runId, tc.callId);
+                let res;
+                try {
+                    res = await grepMemory(index.store, args.pattern, {
+                        sees: binding.sees,
+                        regex: args.regex,
+                        caseSensitive: args.case_sensitive,
+                        kinds: args.kinds,
+                        in: args.in,
+                        stale: args.include_superseded ? 'include' : 'exclude',
+                        limit: args.limit ?? GREPPED,
+                    });
+                }
+                catch (err) {
+                    return refusal(err);
+                }
+                // A complete answer, so nothing found is information rather than
+                // a failed lookup — that is the whole reason this tool exists.
+                if (!res.found && !res.skipped.length) {
+                    return `nothing in memory contains ${JSON.stringify(args.pattern)}`;
+                }
+                const spec = {
+                    kind: 'op',
+                    op: 'grep',
+                    opId,
+                    nodes: res.matches.map((m) => ({
+                        id: m.node.id,
+                        kind: m.node.kind,
+                        revision: m.node.revision,
+                    })),
+                    edges: [],
+                    files: 0,
+                };
+                return withEffects({
+                    found: res.found,
+                    truncated: res.truncated || undefined,
+                    matches: res.matches.map((m) => ({
+                        id: m.node.id,
+                        kind: m.node.kind,
+                        stale: m.stale || undefined,
+                        file: m.node.file?.path,
+                        hits: m.hits.map((h) => ({ in: h.where, line: h.line, text: h.text })),
+                        more: m.more || undefined,
+                    })),
+                    // Named, because a file that was not read means a hit in
+                    // it would not have been reported either.
+                    unsearched: res.skipped.length ? res.skipped : undefined,
+                }, { kind: 'memory_op', spec });
+            },
+        }),
     ];
     if (!canWrite(binding)) {
         return tools;

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/memory/types.d.ts

@@ -169,8 +169,13 @@ export interface MemoryRecallSpec {
 }
 export interface MemoryOpSpec {
     kind: 'op';
-    /** `load` is here rather than under recall: it hands the model whole bodies, and it writes. */
-    op: 'commit' | 'forget' | 'load';
+    /**
+     * `load` is here rather than under recall: it hands the model whole bodies,
+     * and it writes. `grep` is here because it is not a recall either — there is
+     * no query vector, no subgraph and no ranking to record, only the nodes a
+     * pattern happened to hit.
+     */
+    op: 'commit' | 'forget' | 'load' | 'grep';
     /** sha256(runId, callId) — deterministic, so a replay is deduplicated */
     opId: string;
     /** nodes this op created, changed, removed or read in full */

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,48 @@ 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.
+ *
+ * `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 +219,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;
     /**
@@ -200,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
@@ -215,4 +279,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