@zenera/neo 1.1.23 → 1.1.24

package/dist/memory/grep.js

@@ -0,0 +1,182 @@
+import { readFile, stat } from 'node:fs/promises';
+import { hostPath } from "./files.js";
+import { PatternError, matcher } from "./match.js";
+import { MemoryError } from "./types.js";
+// ---------------------------------------------------------------------------
+// The memory, read exhaustively
+//
+// `search` ranks and `grep` decides. They answer different questions and
+// neither can be made to answer the other's: a ranking hands back the top of a
+// list, so "nothing came back" and "nothing is there" are the same result, and
+// the one question memory keeps raising — *did we already write this down* —
+// needs them to be different results. So this is one pass, no embedder, no
+// credential, and `found` is the true total even when the list was cut.
+//
+// Three fields, because a memory is not only its summary. `text` is what the
+// ranker sees; `metadata` is where an agent puts the identifiers nobody would
+// ever phrase as a sentence — a commit sha, an endpoint, a container name; and
+// the bytes of a remembered file are the thing itself. An exact match belongs
+// against all three.
+//
+// Two rules keep this honest against raw `grep` over /memory, which is what it
+// exists to replace. Superseded nodes are excluded unless asked for, and come
+// back flagged when they are — serving a withdrawn correction as current is
+// the failure mode the mount is warned about. And reading here is not use:
+// recency decay is meant to track what an agent actually opened, and a finder
+// that bumped it would make every scan look like a read.
+// ---------------------------------------------------------------------------
+/** The three places a pattern is looked for. */
+export const GREP_FIELDS = ['text', 'metadata', 'file'];
+/** A scan is bounded, because a pattern may have come from a model. */
+const DEADLINE_MS = 2000;
+const DEADLINE_EVERY = 100;
+/** Past this a remembered file is reported as unsearched rather than read. */
+export const MAX_GREP_FILE_BYTES = 256 * 1024;
+/** And past this, so does the rest of the scan: one memory can hold hundreds. */
+export const MAX_GREP_BYTES = 8 * 1024 * 1024;
+/** Enough to see why a node matched without one file crowding out every other. */
+const HITS_PER_NODE = 5;
+/** A matched line, as much of it as is worth carrying. */
+const EXCERPT = 240;
+export async function grepMemory(store, pattern, filter = {}) {
+    const match = compile(pattern, filter);
+    const fields = new Set(filter.in?.length ? filter.in : GREP_FIELDS);
+    const kinds = filter.kinds?.length ? new Set(filter.kinds) : undefined;
+    const cap = filter.hitsPerNode ?? HITS_PER_NODE;
+    const want = filter.stale ?? 'exclude';
+    const superseded = store.graph.superseded(filter.sees);
+    const matches = [];
+    const skipped = [];
+    const until = Date.now() + DEADLINE_MS;
+    let budget = MAX_GREP_BYTES;
+    let seen = 0;
+    for (const node of store.graph.nodes(filter.sees)) {
+        if (++seen % DEADLINE_EVERY === 0 && Date.now() > until) {
+            throw new MemoryError(`the pattern is still running after ${DEADLINE_MS / 1000}s — it is too expensive to be useful`, 'anchor the pattern, or narrow the scan with `kinds` or `in`');
+        }
+        const stale = superseded.has(node.id);
+        if (want === 'exclude' ? stale : want === 'only' && !stale) {
+            continue;
+        }
+        if (kinds && !kinds.has(node.kind)) {
+            continue;
+        }
+        if (filter.audience && !node.audience.includes(filter.audience)) {
+            continue;
+        }
+        if (filter.files && !node.file) {
+            continue;
+        }
+        const hits = [];
+        let total = 0;
+        if (fields.has('text')) {
+            total += scan(hits, 'text', node.text, match, cap);
+        }
+        // Indented rather than compact, so a line number names a key someone
+        // can search for: one-line JSON would make every hit "line 1".
+        if (fields.has('metadata') && node.metadata) {
+            total += scan(hits, 'metadata', JSON.stringify(node.metadata, null, 4), match, cap);
+        }
+        if (fields.has('file') && node.file) {
+            const body = await read(store.dir, node.file, budget);
+            if (body.omitted) {
+                skipped.push({ id: node.id, path: node.file.path, reason: body.omitted });
+            }
+            else {
+                budget -= body.bytes;
+                total += scan(hits, 'file', body.text, match, cap);
+            }
+        }
+        if (hits.length) {
+            matches.push({ node, hits, more: total - hits.length, stale });
+        }
+    }
+    // Newest first, as `zen memory ls` lists them: when a pattern matches an
+    // old node and the node that corrected it, the correction should read first.
+    matches.sort((a, b) => b.node.createdAt.localeCompare(a.node.createdAt) || a.node.id.localeCompare(b.node.id));
+    const found = matches.length;
+    const limit = filter.limit;
+    const truncated = limit !== undefined && limit >= 0 && limit < found;
+    return { found, matches: truncated ? matches.slice(0, limit) : matches, truncated, skipped };
+}
+// ---------------------------------------------------------------------------
+/**
+ * A bad pattern is the model's mistake to fix, and `MemoryError` is the one
+ * shape both surfaces already know how to hand back rather than throw.
+ */
+function compile(pattern, options) {
+    try {
+        return matcher(pattern, options);
+    }
+    catch (err) {
+        if (err instanceof PatternError) {
+            throw new MemoryError(err.message, options.regex
+                ? 'fix the expression, or drop `regex` to search for the literal text'
+                : 'pass a shorter, non-empty pattern');
+        }
+        throw err;
+    }
+}
+/** Every matching line, of which the first `cap` are kept; the count is of all of them. */
+function scan(out, where, body, match, cap) {
+    const lines = body.split('\n');
+    let total = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const at = match(lines[i]);
+        if (at < 0) {
+            continue;
+        }
+        total++;
+        if (out.length < cap) {
+            out.push({ where, line: i + 1, text: excerpt(lines[i], at) });
+        }
+    }
+    return total;
+}
+/**
+ * The line, windowed onto the match. Clipping from the front would be right for
+ * prose and useless for the one case that most needs it — a minified file or a
+ * long serialized value, where the hit is thousands of characters in.
+ */
+function excerpt(line, at) {
+    const text = line.replace(/\t/g, '    ').trimEnd();
+    if (text.length <= EXCERPT) {
+        return text;
+    }
+    const start = Math.max(0, Math.min(at - Math.floor(EXCERPT / 3), text.length - EXCERPT));
+    const end = start + EXCERPT;
+    return (start > 0 ? '…' : '') + text.slice(start, end) + (end < text.length ? '…' : '');
+}
+/**
+ * A remembered file's bytes, or why they were not read. The recorded size is
+ * not trusted for the decision — what is on disk is what would have to be
+ * scanned — and a skip is reported rather than swallowed, because a grep that
+ * silently did not look is worse than one that refused to.
+ */
+async function read(dir, file, budget) {
+    const path = hostPath(dir, file);
+    let size;
+    try {
+        size = (await stat(path)).size;
+    }
+    catch {
+        return { omitted: 'missing' };
+    }
+    if (size > Math.min(MAX_GREP_FILE_BYTES, budget)) {
+        return { omitted: 'too-big' };
+    }
+    let buf;
+    try {
+        buf = await readFile(path);
+    }
+    catch {
+        return { omitted: 'unreadable' };
+    }
+    // A NUL byte in the first few KiB is the cheap, boring test for "this is
+    // not text", and it is right about every format anyone remembers on purpose.
+    if (buf.subarray(0, 8192).includes(0)) {
+        return { omitted: 'binary' };
+    }
+    return { text: buf.toString('utf8'), bytes: buf.byteLength };
+}
+//# sourceMappingURL=grep.js.map

package/dist/memory/index.d.ts

@@ -73,8 +73,16 @@ export declare class MemoryIndex {
     get graph(): MemoryGraph;
     get kinds(): readonly string[];
     get relations(): readonly string[];
-    /** Read-only: a search returns nodes the model has not read, so nothing is touched. */
-    search(query: MemoryQuery, sees: readonly string[]): Promise<Recollection>;
+    /**
+     * Read-only: a search returns nodes the model has not read, so nothing is
+     * touched. `stale` is the audit view — it puts back the superseded nodes
+     * recall drops, which is the only way to see the correction and the thing
+     * it corrected at once. No tool passes it; it is for `zen memory search`,
+     * where the question is why a run recalled what it did.
+     */
+    search(query: MemoryQuery, sees: readonly string[], opts?: {
+        stale?: boolean;
+    }): Promise<Recollection>;
     /**
      * Listed rather than ranked, and deliberately not routed through `recall`:
      * ranking decays by `lastUsedAt`, only `memory_load` bumps that, and a

package/dist/memory/index.js

@@ -13,7 +13,7 @@ import { ALL_AGENTS, MEMORY_KINDS, MEMORY_RELATIONS, MemoryError, PREFERENCE_KIN
 // `ref` — it cannot know an id that has not been minted — and edges join refs
 // and existing ids indiscriminately, so a whole subgraph arrives in one call.
 // Everything is validated, and every source file stat-ed, before the first
-// mutation, on the same principle as `runPatch` in tools/workspace.ts: a
+// mutation, on the same principle as `runPatch` in tools/files.ts: a
 // commit that fails must leave no half-built graph behind.
 // ---------------------------------------------------------------------------
 /** Past this a `load` returns the path and lets the agent open it itself. */
@@ -44,8 +44,14 @@ export class MemoryIndex {
     get relations() {
         return [...this.#relations];
     }
-    /** Read-only: a search returns nodes the model has not read, so nothing is touched. */
-    async search(query, sees) {
+    /**
+     * Read-only: a search returns nodes the model has not read, so nothing is
+     * touched. `stale` is the audit view — it puts back the superseded nodes
+     * recall drops, which is the only way to see the correction and the thing
+     * it corrected at once. No tool passes it; it is for `zen memory search`,
+     * where the question is why a run recalled what it did.
+     */
+    async search(query, sees, opts = {}) {
         const vector = query.text ? await this.#embed([query.text], 'query') : undefined;
         return recall({
             graph: this.graph,
@@ -53,6 +59,7 @@ export class MemoryIndex {
             sees,
             vector: vector?.[0],
             vectors: this.store.vectors,
+            stale: opts.stale,
         });
     }
     /**
@@ -92,7 +99,11 @@ export class MemoryIndex {
                     : undefined,
             });
         }
-        await this.store.commit();
+        // The bump is bookkeeping, and persisting it is what would make a
+        // read-only recall rewrite the graph every other run is reading.
+        if (!this.store.readOnly) {
+            await this.store.commit();
+        }
         return out;
     }
     async commit(tx, opts) {

package/dist/memory/match.d.ts

@@ -0,0 +1,18 @@
+/** 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

@@ -0,0 +1,61 @@
+// ---------------------------------------------------------------------------
+// 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

package/dist/memory/recall.d.ts

@@ -1,7 +1,7 @@
 import type { MemoryGraph } from './graph.ts';
 import { type MemoryQuery, type Recollection, type ScoredNode } from './types.ts';
 import { type VectorBlock } from './vectors.ts';
-export declare const DEFAULT_SEEDS = 5;
+export declare const DEFAULT_SEEDS = 10;
 export declare const DEFAULT_MAX_HOPS = 2;
 /** Past roughly this many nodes a rendered graph reads as soup, not structure. */
 export declare const DEFAULT_MAX_NODES = 25;

package/dist/memory/recall.js

@@ -17,7 +17,7 @@ import { overlap, recencyDecay, tokenize } from "./vectors.js";
 // it replaced from every recall, while the history stays on disk for anyone
 // asking how the correction came about.
 // ---------------------------------------------------------------------------
-export const DEFAULT_SEEDS = 5;
+export const DEFAULT_SEEDS = 10;
 export const DEFAULT_MAX_HOPS = 2;
 /** Past roughly this many nodes a rendered graph reads as soup, not structure. */
 export const DEFAULT_MAX_NODES = 25;

package/dist/memory/store.d.ts

@@ -29,11 +29,18 @@ export interface OpenOptions {
     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

@@ -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) {

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