@columenlabs/lumen-ai 0.1.139 → 0.1.141

package/README.md

@@ -156,3 +156,35 @@ createAssistant({
 ```
 
 An app with its own assistant loop builds the same block with `bearings({ timeZone, lastAt, app, extras })` and puts it before the message.
+
+### Find: one question, one query
+
+The standard way to search an app's records (Columen's canonical setup, 2026-10-28): every app that shows the assistant a collection gives it a find tool, never a list plus one-record reads. One call turns the question into one query that runs where the rows live (D1 or a Durable Object's SQLite). The model gets back only the matching rows and the fields it asked for, and makes the final call itself.
+
+- **Filters** (tags, number and date ranges) are exact SQL.
+- **Words** are matched by an FTS5 index (`porter unicode61`, so "egg" finds "eggs"): `any`, `all`, `none` (leave out: "no milk"), and `in` to say which fields to look in.
+- **Meaning** comes from Vectorize: candidates for a loose ask, trimmed by the same filters and words. It is the next step on this part; until it lands, the model does the fuzzy part over what words and filters return.
+
+```ts
+import { d1Sql, defineFind, findSql, findTool } from '@columenlabs/lumen-ai/assistant';
+
+export const notesFind = defineFind({
+  name: 'notes', label: 'note', table: 'notes', key: 'id',
+  where: 'deleted = 0',          // the app's own SQL, always applied
+  order: 'updated_at DESC',      // with no words to rank by
+  fields: {
+    title: { kind: 'text' },
+    body: { kind: 'text', show: false },     // searchable, returned only when asked
+    tags: { kind: 'text', json: true },      // a JSON column, returned parsed
+    folder: { kind: 'tag' },                 // exact filter; its values are listed to the model
+    updated_at: { kind: 'date' },            // updated_at_from, updated_at_to
+  },
+});
+
+// In a group's tool source, per answer (a Durable Object passes doSql(ctx.storage.sql)):
+plainTools([await findTool(notesFind, d1Sql(env.DB))]);
+```
+
+- `findTool` makes `<name>_find` with a flat input schema (every provider takes it) and reads each tag field's values once to list them. The assistant tells the model to put a whole question in one find call.
+- `runFind(def, sql, query)` is the same query without the tool: bound parameters only, never model-written SQL. It gives up after 3 s.
+- `findSql(def)` gives the index's SQL. `create` is an external-content FTS5 table plus triggers that keep it in step on every insert, update and delete, whoever writes. `fill` indexes the rows already there, and `drop` takes it all out. Put `create` and `fill` in a migration (D1) or a budgeted background step (a Durable Object), never on a request. Until the index exists, words fall back to a plain text match and the result says so, so code can ship before its migration.

package/dist/assistant/engine.d.ts

@@ -214,6 +214,8 @@ export declare class Assistant {
     /** Opens the tools the person allows: each group's, then the web's. */
     private openTools;
     private toolsFor;
+    /** `batch`: any of the reads, up to BATCH_MAX at once, as one step. Null with no reads. */
+    private batchTool;
     /** One answer as server-sent events. Abort `signal` to stop it. */
     turnStream(caller: Caller, req: AssistantMessage, signal?: AbortSignal): ReadableStream<Uint8Array>;
     turn(caller: Caller, req: AssistantMessage, emit: Emit, signal?: AbortSignal): Promise<void>;
@@ -229,6 +231,8 @@ export declare class Assistant {
     private handOff;
     /** One tool call: a draft card for a write, else the call itself, timed. */
     private runTool;
+    /** A batch of reads: each runs as its own call (the same read twice runs once), in parallel, shown as one step. */
+    private runBatch;
     /** Model calls and tool rounds until the model answers; returns its words. */
     private loop;
     /** The loop on OpenAI's Responses API: the same tools, Stop, caps and rounds as Claude's. */

package/dist/assistant/engine.js

@@ -45,6 +45,11 @@ const COMPACT_AT = 150_000;
 /** A tool result handed to the model is cut past this (about 4,000 tokens). */
 const RESULT_CHARS = 16_000;
 const MEMO_CHARS = 8000;
+/** The built-in tool that runs several reads at once, as one step. */
+const BATCH = 'batch';
+const BATCH_MAX = 25;
+/** What one batch returns at most, all its results together. */
+const BATCH_CHARS = 48_000;
 const ADVICE_MAX = 2;
 const ADVICE_TOKENS = 2048;
 const ADVISOR_BETA = 'advisor-tool-2026-03-01';
@@ -631,14 +636,49 @@ export class Assistant {
         };
     }
     toolsFor(fns) {
-        return [...fns.entries()].map(([name, f]) => ({
-            name,
-            description: `${f.draft ? "DRAFT ONLY: this call changes nothing. It puts a card on the person's screen that they Save or Dismiss. " : f.write ? 'WRITES AT ONCE: this call makes the change now; the person can undo it. ' : ''}${f.def.title ? `${f.def.title}. ` : ''}${f.def.description ?? ''}`.slice(0, 4000),
+        const batch = this.batchTool(fns);
+        return [
+            ...[...fns.entries()].map(([name, f]) => ({
+                name,
+                description: `${f.draft ? "DRAFT ONLY: this call changes nothing. It puts a card on the person's screen that they Save or Dismiss. " : f.write ? 'WRITES AT ONCE: this call makes the change now; the person can undo it. ' : ''}${f.def.title ? `${f.def.title}. ` : ''}${f.def.description ?? ''}`.slice(0, 4000),
+                input_schema: {
+                    type: 'object',
+                    ...withoutMeta(f.def.inputSchema),
+                },
+            })),
+            ...(batch ? [batch] : []),
+        ];
+    }
+    /** `batch`: any of the reads, up to BATCH_MAX at once, as one step. Null with no reads. */
+    batchTool(fns) {
+        if (fns.has(BATCH))
+            return null;
+        const reads = [...fns.entries()].filter(([, f]) => !f.draft && !f.write).map(([n]) => n);
+        if (!reads.length)
+            return null;
+        return {
+            name: BATCH,
+            description: `Runs up to ${BATCH_MAX} read calls at once and returns each result, numbered in order. Use it to read several records (one tool with several inputs) or several tools that do not depend on each other, in one step instead of one call at a time. Reads only.`,
             input_schema: {
                 type: 'object',
-                ...withoutMeta(f.def.inputSchema),
+                properties: {
+                    calls: {
+                        type: 'array',
+                        minItems: 1,
+                        maxItems: BATCH_MAX,
+                        items: {
+                            type: 'object',
+                            properties: {
+                                tool: { type: 'string', enum: reads },
+                                input: { type: 'object', description: "The tool's own input." },
+                            },
+                            required: ['tool', 'input'],
+                        },
+                    },
+                },
+                required: ['calls'],
             },
-        }));
+        };
     }
     // ---------------------------------------------------------------- the turn
     /** One answer as server-sent events. Abort `signal` to stop it. */
@@ -918,6 +958,16 @@ export class Assistant {
         const lines = [
             `You are ${this.name}. Each message starts with <bearings>: the time now in the person's zone and where they are. Take today, now and how long ago from it; never guess the date. It is for you only: never quote it or start an answer with it.`,
             'Answer in short plain sentences. Use the tools for facts; never guess a number a tool can give you. Call several tools at once when they do not depend on each other.',
+            ...([...fns.values()].some((f) => f.def.find)
+                ? [
+                    "Questions about an app's records go through its find tool (the tool named <app>_find): put every condition of the question in one call (filters, words to include or leave out, which fields to look in), ask only for the fields the answer needs, then judge the rest yourself from what it returns. Never list or open records one by one to filter them. Rows a find already returned in this chat you use again without asking for them again.",
+                ]
+                : []),
+            ...([...fns.values()].some((f) => !f.draft && !f.write) && !fns.has(BATCH)
+                ? [
+                    `To read several records, or one tool with several inputs, put the reads in one ${BATCH} call: one step for all of them, never one call at a time. Results you already have from earlier in the chat you use, without reading them again.`,
+                ]
+                : []),
             'A tool marked DRAFT ONLY makes a card the person saves or dismisses; it changes nothing by itself. Say what the card will do; never claim it is done. The next message tells you how each card ended.',
             'A tool marked WRITES AT ONCE makes its change when you call it; the person can undo it from the chat. Change only what they asked for, and say what you changed.',
         ];
@@ -933,7 +983,7 @@ export class Assistant {
             const reach = this.above(main.tier);
             if (reach.length) {
                 const own = policy === 'any' ? reach : policy === 'next' ? reach.slice(0, 1) : [];
-                lines.push(`Tiers: you run on ${main.tier.label}. The escalate tool hands one task to a higher tier (${reach.map((t) => t.label).join(' or ')}) with the same tools; it works in its own section of the chat and returns a memo. It costs more than answering yourself.`, `Call it when the person names a tier or says "go deeper"${own.length ? `, and on your own (${own.map((t) => t.label).join(' or ')}) when the question needs judgement across many results (why "judgement"), after two of your tool calls failed (why "stuck"), or when a fix of a check still fails (why "check_failed")` : ''}. Lookups you answer yourself.`, 'Its task must carry every fact from this chat it needs: it does not see the chat. Then answer from its memo in your own short words.');
+                lines.push(`Tiers: you run on ${main.tier.label}. The escalate tool hands one task to a higher tier (${reach.map((t) => t.label).join(' or ')}) with the same tools; it works in its own section of the chat and returns a memo. It costs more than answering yourself.`, `Call it when the person names a tier or says "go deeper"${own.length ? `, and on your own (${own.map((t) => t.label).join(' or ')}) when the question needs judgement a lookup cannot settle (why "judgement"), after two of your tool calls failed (why "stuck"), or when a fix of a check still fails (why "check_failed")` : ''}. Lookups you answer yourself: reading or checking many records against a plain rule (an ingredient, a date, a number, a name) is a lookup, done with a find call or ${BATCH}, never escalated.`, 'Its task must carry every fact from this chat it needs: it does not see the chat. Then answer from its memo in your own short words.');
             }
             if (advisor)
                 lines.push(`Advisor: the advisor tool (no input) asks ${advisor.session.tier.label} to read this chat and send you a plan; it runs no tools. Call it before a question that needs judgement or after a tool failed, then do the work yourself. At most ${ADVICE_MAX} times an answer. Ask the advisor before you escalate.`);
@@ -1086,13 +1136,17 @@ export class Assistant {
             : reply(`Memo from ${item.label}:\n${memo.slice(0, MEMO_CHARS)}`);
     }
     /** One tool call: a draft card for a write, else the call itself, timed. */
-    async runTool(use, fns, sink, emit, runs, counts, session, handoff, signal) {
+    async runTool(use, fns, sink, emit, runs, counts, session, handoff, signal, 
+    /** Part of a batch: runs and is remembered, but draws no step of its own. */
+    quiet = false) {
         const reply = (content, is_error = false) => ({
             type: 'tool_result',
             tool_use_id: use.id,
             content,
             is_error,
         });
+        if (use.name === BATCH && !fns.has(BATCH) && !quiet)
+            return this.runBatch(use, fns, sink, emit, runs, counts, session, handoff, signal);
         const f = fns.get(use.name);
         if (!f)
             return reply(`No tool ${use.name}.`, true);
@@ -1123,7 +1177,8 @@ export class Assistant {
                 settle = done;
             }));
         const id = newId('s');
-        emit('step_start', { id, tool: use.name, title });
+        if (!quiet)
+            emit('step_start', { id, tool: use.name, title });
         const t0 = performance.now();
         let out;
         let ok = true;
@@ -1160,9 +1215,11 @@ export class Assistant {
                 ? { write: { undo: !!this.groupById(f.group)?.undo, status: 'done' } }
                 : {}),
         };
-        sink.push(item);
-        emit('step', item);
-        counts.steps += 1;
+        if (!quiet) {
+            sink.push(item);
+            emit('step', item);
+            counts.steps += 1;
+        }
         // A change made at once can make an earlier read stale: reads after it run again.
         if (f.write)
             counts.seen.clear();
@@ -1187,6 +1244,68 @@ export class Assistant {
         }
         return reply(cut, !ok);
     }
+    /** A batch of reads: each runs as its own call (the same read twice runs once), in parallel, shown as one step. */
+    async runBatch(use, fns, sink, emit, runs, counts, session, handoff, signal) {
+        const reply = (content, is_error = false) => ({
+            type: 'tool_result',
+            tool_use_id: use.id,
+            content,
+            is_error,
+        });
+        const raw = use.input?.calls;
+        const calls = (Array.isArray(raw) ? raw : []).map((c) => {
+            const o = (c && typeof c === 'object' ? c : {});
+            return {
+                tool: typeof o.tool === 'string' ? o.tool : '',
+                input: o.input && typeof o.input === 'object' ? o.input : {},
+            };
+        });
+        if (!calls.length)
+            return reply(`Give {calls: [{tool, input}]}: 1 to ${BATCH_MAX} reads.`, true);
+        if (calls.length > BATCH_MAX)
+            return reply(`At most ${BATCH_MAX} calls a batch: split them into batches.`, true);
+        const titles = [...new Set(calls.map((c) => fns.get(c.tool)?.def.title ?? c.tool))];
+        const title = titles.length === 1 ? `${titles[0]} ×${calls.length}` : `${calls.length} reads`;
+        const id = newId('s');
+        emit('step_start', { id, tool: BATCH, title });
+        const t0 = performance.now();
+        const done = await Promise.all(calls.map(async (c, i) => {
+            const f = fns.get(c.tool);
+            if (!f)
+                return { ...c, ok: false, text: `No tool ${c.tool}.` };
+            if (f.draft || f.write)
+                return { ...c, ok: false, text: 'Only reads go in a batch: call this tool on its own.' };
+            const r = await this.runTool({
+                type: 'tool_use',
+                id: `${use.id}_${i}`,
+                name: c.tool,
+                input: c.input,
+            }, fns, sink, emit, runs, counts, session, handoff, signal, true);
+            return { ...c, ok: !r.is_error, text: typeof r.content === 'string' ? r.content : '' };
+        }));
+        const failed = done.filter((d) => !d.ok).length;
+        const item = {
+            kind: 'step',
+            id,
+            tool: BATCH,
+            title,
+            ok: failed < done.length,
+            ms: Math.round(performance.now() - t0),
+            ...(failed ? { error: `${failed} of ${done.length} failed` } : {}),
+        };
+        sink.push(item);
+        emit('step', item);
+        counts.steps += 1;
+        let left = BATCH_CHARS;
+        const parts = done.map((d, i) => {
+            const fits = d.text.length <= left;
+            left -= fits ? d.text.length : 0;
+            return `[${i + 1}] ${d.tool} ${stableJson(d.input)}${d.ok ? '' : ' (failed)'}\n${fits
+                ? d.text
+                : '(left out: the batch passed its size; read this one again in a smaller batch)'}`;
+        });
+        return reply(parts.join('\n\n'), failed === done.length);
+    }
     /** Model calls and tool rounds until the model answers; returns its words. */
     loop(o) {
         const { provider } = o.session.model;

package/dist/assistant/find.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Find tools: one call turns a question into one query that runs where the rows live (D1 or a
+ * Durable Object's SQLite), so the assistant never lists or opens records one by one to filter them.
+ *
+ * An app declares its table's fields once (`defineFind`). The kit gives the tool (`findTool`: a flat
+ * input of tag filters, words to include or leave out, which fields to look in and which to return),
+ * the query (`runFind`: bound parameters only, never model-written SQL) and the SQL that sets up the
+ * word index (`findSql`: an FTS5 table kept in step with the table by triggers, whoever writes).
+ *
+ *   const recipesFind = defineFind({ name: 'recipes', label: 'recipe', table: 'recipes', key: 'id',
+ *     where: 'is_deleted = 0', fields: { title: { kind: 'text' }, category: { kind: 'tag' } } });
+ *   const tool = await findTool(recipesFind, d1Sql(env.RECIPES_DB));
+ *
+ * Words are matched by the FTS5 index (stems: "egg" finds "eggs"). Until that index exists, words
+ * fall back to a plain text match, so a build that lands before its index still answers.
+ */
+import type { SqlRunner } from './store.js';
+import { type PlainTool } from './tools.js';
+/** text: searchable words. tag: an exact value to filter on (listed to the model). number, date: ranges. */
+export type FindKind = 'text' | 'tag' | 'number' | 'date';
+export interface FindField {
+    kind: FindKind;
+    /** The table's column, when it is named differently. */
+    column?: string;
+    /** Returned unless the call names its fields. False keeps it searchable but out of the default. */
+    show?: boolean;
+    /** The column holds JSON (a list of ingredients): returned parsed. */
+    json?: boolean;
+    /** A few words for the model. */
+    about?: string;
+}
+export interface FindDef {
+    /** The tool is `<name>_find`. */
+    name: string;
+    /** What one row is, for the model: "recipe". */
+    label: string;
+    /** One line on what the rows are. */
+    about?: string;
+    table: string;
+    /** The table's integer primary key (the FTS rowid). */
+    key: string;
+    /** Always applied: rows the person never sees (deleted ones). The app's own SQL, never the model's. */
+    where?: string;
+    fields: Record<string, FindField>;
+    /** The FTS5 table: `<table>_fts` by default. */
+    fts?: string;
+    /** The order with no words to rank by: `category, title`. Column names. */
+    order?: string;
+    /** Rows a call returns by default (25) and at most (200). */
+    limit?: number;
+    max?: number;
+}
+/** What the model sends: flat, so every provider takes the schema. Tag fields are their own keys. */
+export interface FindQuery {
+    any?: string[];
+    all?: string[];
+    none?: string[];
+    in?: string[];
+    ids?: number[];
+    fields?: string[];
+    sort?: string;
+    desc?: boolean;
+    limit?: number;
+    [tagOrRange: string]: unknown;
+}
+export interface FindResult {
+    /** Rows that match, all of them, before `limit`. */
+    count: number;
+    rows: Record<string, unknown>[];
+    /** Set when words were matched without the word index (it is not set up yet). */
+    note?: string;
+}
+/** Checks a definition once, where the app declares it. */
+export declare function defineFind(def: FindDef): FindDef;
+/**
+ * The SQL that sets up the word index: an external-content FTS5 table over the text columns, the
+ * triggers that keep it in step on every insert, update and delete, and (`fill`) the one statement
+ * that indexes the rows already there. Each `create` statement is safe to run again. Run `fill` once,
+ * in a migration or a budgeted background step, never on a request.
+ */
+export declare function findSql(def: FindDef): {
+    create: string[];
+    fill: string;
+    drop: string[];
+};
+/** Runs one find: one query, the rows' asked fields (JSON parsed) and how many match in all. */
+export declare function runFind(def: FindDef, sql: SqlRunner, q: FindQuery): Promise<FindResult>;
+/**
+ * The find tool for one table, opened for one answer: its tag values are read once (one small query)
+ * so the model picks real ones. A read; `find` marks it so the assistant puts a whole question in it.
+ */
+export declare function findTool(def: FindDef, sql: SqlRunner): Promise<PlainTool>;

package/dist/assistant/find.js

@@ -0,0 +1,321 @@
+import { ToolError, withDeadline } from './tools.js';
+const RESERVED = new Set(['any', 'all', 'none', 'in', 'ids', 'fields', 'sort', 'desc', 'limit']);
+const FIND_MS = 3_000;
+const TAG_VALUES = 60;
+const WORDS = 20;
+/** Checks a definition once, where the app declares it. */
+export function defineFind(def) {
+    const ident = /^[A-Za-z_][A-Za-z0-9_]*$/;
+    for (const n of [def.name, def.table, def.key, def.fts ?? 'x'])
+        if (!ident.test(n))
+            throw new Error(`find ${def.name}: "${n}" is not a plain name`);
+    for (const [n, f] of Object.entries(def.fields)) {
+        if (!ident.test(n) || !ident.test(f.column ?? n))
+            throw new Error(`find ${def.name}: field "${n}" is not a plain name`);
+        if (RESERVED.has(n))
+            throw new Error(`find ${def.name}: field "${n}" is a reserved word`);
+    }
+    if (!Object.values(def.fields).some((f) => f.kind === 'text'))
+        throw new Error(`find ${def.name}: give at least one text field`);
+    return def;
+}
+const col = (def, f) => def.fields[f]?.column ?? f;
+const ftsName = (def) => def.fts ?? `${def.table}_fts`;
+const textFields = (def) => Object.entries(def.fields)
+    .filter(([, f]) => f.kind === 'text')
+    .map(([n]) => n);
+/**
+ * The SQL that sets up the word index: an external-content FTS5 table over the text columns, the
+ * triggers that keep it in step on every insert, update and delete, and (`fill`) the one statement
+ * that indexes the rows already there. Each `create` statement is safe to run again. Run `fill` once,
+ * in a migration or a budgeted background step, never on a request.
+ */
+export function findSql(def) {
+    const fts = ftsName(def);
+    const cols = textFields(def).map((f) => col(def, f));
+    const list = cols.join(', ');
+    const nu = cols.map((c) => `new.${c}`).join(', ');
+    const ol = cols.map((c) => `old.${c}`).join(', ');
+    return {
+        create: [
+            `CREATE VIRTUAL TABLE IF NOT EXISTS ${fts} USING fts5(${list}, content='${def.table}', content_rowid='${def.key}', tokenize='porter unicode61')`,
+            `CREATE TRIGGER IF NOT EXISTS ${fts}_ai AFTER INSERT ON ${def.table} BEGIN INSERT INTO ${fts}(rowid, ${list}) VALUES (new.${def.key}, ${nu}); END`,
+            `CREATE TRIGGER IF NOT EXISTS ${fts}_ad AFTER DELETE ON ${def.table} BEGIN INSERT INTO ${fts}(${fts}, rowid, ${list}) VALUES ('delete', old.${def.key}, ${ol}); END`,
+            `CREATE TRIGGER IF NOT EXISTS ${fts}_au AFTER UPDATE ON ${def.table} BEGIN INSERT INTO ${fts}(${fts}, rowid, ${list}) VALUES ('delete', old.${def.key}, ${ol}); INSERT INTO ${fts}(rowid, ${list}) VALUES (new.${def.key}, ${nu}); END`,
+        ],
+        fill: `INSERT INTO ${fts}(${fts}) VALUES ('rebuild')`,
+        drop: [
+            `DROP TRIGGER IF EXISTS ${fts}_ai`,
+            `DROP TRIGGER IF EXISTS ${fts}_ad`,
+            `DROP TRIGGER IF EXISTS ${fts}_au`,
+            `DROP TABLE IF EXISTS ${fts}`,
+        ],
+    };
+}
+/** Words as the model sent them (a list, or one string as a list of one): trimmed, deduped, at most `WORDS`. */
+function words(v) {
+    const list = Array.isArray(v) ? v : typeof v === 'string' ? [v] : [];
+    const out = new Set();
+    for (const w of list) {
+        if (typeof w !== 'string')
+            continue;
+        const t = w.replace(/\s+/g, ' ').trim().slice(0, 80);
+        if (t)
+            out.add(t);
+    }
+    return [...out].slice(0, WORDS);
+}
+/** One FTS5 term: a quoted phrase, so the model's words are never read as FTS syntax. */
+const phrase = (w) => `"${w.replace(/"/g, '""')}"`;
+function strings(v) {
+    const a = Array.isArray(v) ? v : v === undefined || v === null ? [] : [v];
+    return a.filter((x) => typeof x === 'string' || typeof x === 'number').map((x) => String(x));
+}
+/** The query, checked: what is not a field of this table is an error the model can fix. */
+function checked(def, q) {
+    const names = Object.keys(def.fields);
+    const unknown = (list, what) => {
+        const bad = list.filter((f) => !def.fields[f]);
+        if (bad.length)
+            throw new ToolError(`${what}: no field ${bad.join(', ')}. Fields: ${names.join(', ')}.`);
+    };
+    const inFields = strings(q.in);
+    unknown(inFields, 'in');
+    const notText = inFields.filter((f) => def.fields[f]?.kind !== 'text');
+    if (notText.length)
+        throw new ToolError(`in: ${notText.join(', ')} are not text fields.`);
+    const fields = strings(q.fields);
+    unknown(fields, 'fields');
+    if (q.sort !== undefined)
+        unknown(strings(q.sort), 'sort');
+    for (const k of Object.keys(q)) {
+        if (RESERVED.has(k))
+            continue;
+        const base = k.replace(/_(min|max|from|to)$/, '');
+        if (!def.fields[base] || def.fields[base]?.kind === 'text')
+            throw new ToolError(`${k}: not a filter. Filters: ${filterKeys(def).join(', ')}.`);
+    }
+    const max = def.max ?? 200;
+    const limit = Math.max(1, Math.min(max, Math.trunc(Number(q.limit ?? def.limit ?? 25)) || 25));
+    return {
+        any: words(q.any),
+        all: words(q.all),
+        none: words(q.none),
+        in: inFields.length ? inFields : textFields(def),
+        ids: (Array.isArray(q.ids) ? q.ids : []).map(Number).filter(Number.isInteger).slice(0, max),
+        fields: fields.length ? fields : names.filter((n) => def.fields[n]?.show !== false),
+        sort: typeof q.sort === 'string' ? q.sort : undefined,
+        desc: q.desc === true,
+        limit,
+    };
+}
+function filterKeys(def) {
+    return Object.entries(def.fields).flatMap(([n, f]) => f.kind === 'tag'
+        ? [n]
+        : f.kind === 'number'
+            ? [`${n}_min`, `${n}_max`]
+            : f.kind === 'date'
+                ? [`${n}_from`, `${n}_to`]
+                : []);
+}
+/** One find as SQL and its bound values. `fts` false matches words with LIKE (no index yet). */
+function compile(def, q, fts) {
+    const c = checked(def, q);
+    const t = 't';
+    const where = [];
+    const args = [];
+    if (def.where)
+        where.push(`(${def.where})`);
+    for (const [n, f] of Object.entries(def.fields)) {
+        const column = `${t}.${col(def, n)}`;
+        if (f.kind === 'tag') {
+            const vals = strings(q[n]).slice(0, 50);
+            if (vals.length) {
+                where.push(`${column} COLLATE NOCASE IN (${vals.map(() => '?').join(', ')})`);
+                args.push(...vals);
+            }
+        }
+        else if (f.kind === 'number' || f.kind === 'date') {
+            const [lo, hi] = f.kind === 'number' ? ['_min', '_max'] : ['_from', '_to'];
+            for (const [suffix, op] of [
+                [lo, '>='],
+                [hi, '<='],
+            ]) {
+                const v = q[`${n}${suffix}`];
+                if (v === undefined || v === null || v === '')
+                    continue;
+                where.push(`${column} ${op} ?`);
+                args.push(f.kind === 'number' ? Number(v) : String(v));
+            }
+        }
+    }
+    if (c.ids.length) {
+        where.push(`${t}.${def.key} IN (${c.ids.map(() => '?').join(', ')})`);
+        args.push(...c.ids);
+    }
+    const fname = ftsName(def);
+    const cols = c.in.map((f) => col(def, f));
+    const scope = `{${cols.join(' ')}} : `;
+    const positive = [
+        ...(c.any.length ? [`(${c.any.map(phrase).join(' OR ')})`] : []),
+        ...c.all.map(phrase),
+    ];
+    let join = '';
+    let rank = '';
+    if (fts) {
+        if (positive.length) {
+            join = ` JOIN ${fname} ON ${fname}.rowid = ${t}.${def.key}`;
+            where.push(`${fname} MATCH ?`);
+            args.push(`${scope}(${positive.join(' AND ')})`);
+            rank = `${fname}.rank`;
+        }
+        if (c.none.length) {
+            where.push(`${t}.${def.key} NOT IN (SELECT rowid FROM ${fname} WHERE ${fname} MATCH ?)`);
+            args.push(`${scope}(${c.none.map(phrase).join(' OR ')})`);
+        }
+    }
+    else {
+        const like = (w) => {
+            args.push(...cols.map(() => `%${w}%`));
+            return `(${cols.map((x) => `${t}.${x} LIKE ?`).join(' OR ')})`;
+        };
+        if (c.any.length)
+            where.push(`(${c.any.map(like).join(' OR ')})`);
+        for (const w of c.all)
+            where.push(like(w));
+        for (const w of c.none)
+            where.push(`NOT ${like(w)}`);
+    }
+    const order = c.sort
+        ? `${t}.${col(def, c.sort)} ${c.desc ? 'DESC' : 'ASC'}`
+        : rank ||
+            (def.order
+                ? def.order
+                    .split(',')
+                    .map((o) => `${t}.${o.trim()}`)
+                    .join(', ')
+                : `${t}.${def.key}`);
+    const select = [...new Set([def.key, ...c.fields])]
+        .map((f) => (f === def.key ? `${t}.${def.key} AS ${def.key}` : `${t}.${col(def, f)} AS ${f}`))
+        .join(', ');
+    const sql = `SELECT ${select}, COUNT(*) OVER () AS _count FROM ${def.table} ${t}${join}${where.length ? ` WHERE ${where.join(' AND ')}` : ''} ORDER BY ${order} LIMIT ${c.limit}`;
+    return { sql, args, fields: c.fields, words: c.any.length + c.all.length + c.none.length > 0 };
+}
+const missingIndex = (e) => e instanceof Error && /no such table|no such module|fts5/i.test(e.message);
+/** Runs one find: one query, the rows' asked fields (JSON parsed) and how many match in all. */
+export async function runFind(def, sql, q) {
+    let built = compile(def, q, true);
+    let note;
+    let rows;
+    try {
+        rows = await withDeadline(`${def.name} find`, FIND_MS, sql.all(built.sql, ...built.args));
+    }
+    catch (e) {
+        if (!built.words || !missingIndex(e))
+            throw e;
+        built = compile(def, q, false);
+        note = 'Words were matched as plain text: the word index is not set up yet.';
+        rows = await withDeadline(`${def.name} find`, FIND_MS, sql.all(built.sql, ...built.args));
+    }
+    const count = Number(rows[0]?._count ?? 0);
+    return {
+        count,
+        rows: rows.map((r) => {
+            const out = { [def.key]: r[def.key] };
+            for (const f of built.fields) {
+                const v = r[f];
+                if (def.fields[f]?.json && typeof v === 'string') {
+                    try {
+                        out[f] = JSON.parse(v);
+                    }
+                    catch {
+                        out[f] = v;
+                    }
+                }
+                else
+                    out[f] = v;
+            }
+            return out;
+        }),
+        ...(note ? { note } : {}),
+    };
+}
+/** The values a tag field holds, to list in the tool's description. */
+async function tagValues(def, sql, field) {
+    const c = col(def, field);
+    const rows = await sql.all(`SELECT DISTINCT ${c} AS v FROM ${def.table}${def.where ? ` WHERE ${def.where}` : ''} ORDER BY ${c} LIMIT ${TAG_VALUES + 1}`);
+    return rows.map((r) => String(r.v ?? '')).filter(Boolean);
+}
+/** The tool's flat JSON Schema, from the fields. */
+function schemaOf(def, tags) {
+    const names = Object.keys(def.fields);
+    const text = textFields(def);
+    const list = (description, items = { type: 'string' }) => ({
+        type: 'array',
+        items,
+        description,
+    });
+    const props = {
+        any: list('Rows with at least one of these words or phrases.'),
+        all: list('Rows with every one of these words or phrases.'),
+        none: list('Leave out rows with any of these words or phrases (an ingredient to avoid).'),
+        in: list('Which fields the words must be in; all text fields when left out.', {
+            type: 'string',
+            enum: text,
+        }),
+        ids: list(`Only these ${def.label}s, by ${def.key}.`, { type: 'integer' }),
+        fields: list(`What to return for each ${def.label}; ${names.filter((n) => def.fields[n]?.show !== false).join(', ')} when left out. Ask only for what the answer needs.`, { type: 'string', enum: names }),
+        sort: {
+            type: 'string',
+            enum: names,
+            description: 'Order by this field; by best word match, else the default order, when left out.',
+        },
+        desc: { type: 'boolean', description: 'Highest first.' },
+        limit: {
+            type: 'integer',
+            minimum: 1,
+            maximum: def.max ?? 200,
+            description: `Rows to return (${def.limit ?? 25} by default). The result says how many match in all.`,
+        },
+    };
+    for (const [n, f] of Object.entries(def.fields)) {
+        if (f.kind === 'tag') {
+            const vals = tags[n] ?? [];
+            props[n] = list(`Only these ${n} values${vals.length && vals.length <= TAG_VALUES ? `: ${vals.join(', ')}` : ''}.`, vals.length && vals.length <= TAG_VALUES
+                ? { type: 'string', enum: vals }
+                : { type: 'string' });
+        }
+        else if (f.kind === 'number') {
+            props[`${n}_min`] = { type: 'number', description: `${n} at least this.` };
+            props[`${n}_max`] = { type: 'number', description: `${n} at most this.` };
+        }
+        else if (f.kind === 'date') {
+            props[`${n}_from`] = { type: 'string', description: `${n} on or after this (YYYY-MM-DD).` };
+            props[`${n}_to`] = { type: 'string', description: `${n} on or before this (YYYY-MM-DD).` };
+        }
+    }
+    return { type: 'object', properties: props, additionalProperties: false };
+}
+/**
+ * The find tool for one table, opened for one answer: its tag values are read once (one small query)
+ * so the model picks real ones. A read; `find` marks it so the assistant puts a whole question in it.
+ */
+export async function findTool(def, sql) {
+    const tags = {};
+    await Promise.all(Object.entries(def.fields)
+        .filter(([, f]) => f.kind === 'tag')
+        .map(async ([n]) => {
+        tags[n] = await withDeadline(`${def.name} values`, FIND_MS, tagValues(def, sql, n)).catch(() => []);
+    }));
+    const fields = Object.entries(def.fields)
+        .map(([n, f]) => `${n} (${f.kind}${f.about ? `: ${f.about}` : ''})`)
+        .join(', ');
+    return {
+        name: `${def.name}_find`,
+        description: `Finds ${def.label}s in one query${def.about ? ` (${def.about})` : ''}: put every condition of the question in one call (filters, words to include or leave out, which fields to look in) and ask only for the fields the answer needs. Fields: ${fields}. Returns the matching ${def.label}s and how many match in all.`,
+        inputSchema: schemaOf(def, tags),
+        read: true,
+        find: true,
+        run: (args) => runFind(def, sql, (args ?? {})),
+    };
+}

package/dist/assistant/index.d.ts

@@ -15,6 +15,7 @@
 export * from './bearings.js';
 export * from './chatgpt.js';
 export * from './engine.js';
+export * from './find.js';
 export * from './models.js';
 export * from './routes.js';
 export { DEFAULT_CAP, type KeyDoc, keyDocName, type KeyTest, monthIn, type Paying, type PersonDoc, type SpendDoc, State, type TokenDoc, waitText, } from './state.js';

package/dist/assistant/index.js

@@ -15,6 +15,7 @@
 export * from './bearings.js';
 export * from './chatgpt.js';
 export * from './engine.js';
+export * from './find.js';
 export * from './models.js';
 export * from './routes.js';
 export { DEFAULT_CAP, keyDocName, monthIn, State, waitText, } from './state.js';

package/dist/assistant/tools.d.ts

@@ -7,6 +7,8 @@ export interface ToolDef {
     /** JSON Schema of its input (an object). */
     inputSchema: Record<string, unknown>;
     read: boolean;
+    /** A find tool (`findTool`): one query per question, so the assistant puts every condition in it. */
+    find?: boolean;
 }
 /** Tools opened for one answer: what they are, how to call one, and how to let them go. */
 export interface OpenTools {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@columenlabs/lumen-ai",
-  "version": "0.1.139",
+  "version": "0.1.141",
   "description": "Lumen's assistant and agent parts: a chat assistant's server (Claude tiers, tools over MCP, the web, hand off, spend caps), serving an MCP server from a Worker, read-only tool sets and metered tool calls.",
   "license": "MIT",
   "type": "module",
@@ -41,8 +41,8 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "0.133.0",
-    "@columenlabs/lumen-ops": "0.1.139",
-    "@columenlabs/lumen-ui-types": "0.1.139",
+    "@columenlabs/lumen-ops": "0.1.141",
+    "@columenlabs/lumen-ui-types": "0.1.141",
     "openai": "7.32.0",
     "zod": "^4.3.6"
   },