@columenlabs/lumen-ai 0.1.140 → 0.1.142

package/README.md

@@ -156,3 +156,56 @@ 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, opt in per app: `like` ("something light for a hot day") asks the index for the nearest rows, and the same filters and words trim them.
+- **Worked-out fields**: a number, date or tag field may be the app's own SQL over the row (`sql: 'json_array_length(t.steps)'`) instead of a column.
+- **Counts**: the result carries `count` (all matches), `returned` and `same_name` (different rows that share a name), so the model says the right number.
+
+```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.
+
+Meaning, for the apps whose people ask loosely (a recipe book, a career log; not for exact records like card benefits):
+
+```ts
+import { meaningStep, vectorMeaning, workersEmbed } from '@columenlabs/lumen-ai/assistant';
+
+// On the definition: what a row means, and the column every write moves.
+meaning: { fields: ['title', 'body', 'tags'], changed: 'updated_at' },
+
+const embed = workersEmbed(env.AI);              // bge-base-en-v1.5: a 768-dimension cosine index
+await findTool(notesFind, d1Sql(env.DB), { meaning: vectorMeaning({ embed, index: env.NOTES_INDEX }) });
+
+// Off the request path (waitUntil after a write and when the tool opens, an alarm, a queue):
+ctx.waitUntil(meaningStep({ def: notesFind, sql: d1Sql(env.DB), embed, index: env.NOTES_INDEX, mark }));
+```
+
+- `meaningStep` embeds only the rows whose `changed` column moved past its bookmark (`mark`: get and put, kept by the app), at most 50 a step in one embedding call and one upsert, and takes rows the find hides (its `where`) out of the index. It resumes where it stopped and runs safely twice at once; `done` is false while rows are left.
+- A person's own rows get a `namespace` each (`vectorMeaning` and `meaningStep` take one), so one index serves one app.
+- When the index cannot answer in 3 s, `like` is left out, the rest of the find runs and the result says so.

package/dist/assistant/engine.js

@@ -958,6 +958,11 @@ 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. A loose ask (a mood, an occasion, "something light", "good for a party") goes in its like field when the tool has one; then pick from what it returns yourself. How many match is the result\'s count: say that number, and name each row in same_name, which are different records that share a name. Rows a find already returned you use again only when they answer the whole new question; a new condition (another ingredient, a kind of dish, how quick) is a new find call.',
+                ]
+                : []),
             ...([...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.`,
@@ -978,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 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 ${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.');
+                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. Suggesting a few of an app's records for a loose ask (a dish for a hot day, something for a party) is a lookup too: one find call, then your own pick, 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.`);

package/dist/assistant/find.d.ts

@@ -0,0 +1,128 @@
+/**
+ * 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.
+ *
+ * Meaning (opt in, `meaning` on the definition plus a `FindMeaning` given to `findTool`): `like`
+ * asks a vector index for the rows nearest a loose ask ("something light for a hot day") and the
+ * same SQL trims them, so filters and words still hold. `meaning.ts` gives the Vectorize index and
+ * the budgeted background step that keeps it in step.
+ */
+import type { FindMeaning } from './meaning.js';
+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;
+    /**
+     * Not a column but the app's own SQL over the row, its columns as `t.<column>`
+     * (`json_array_length(t.steps)`): a number, date or tag worked out per row. Never text.
+     */
+    sql?: 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;
+    /** The field that names a row (the first text field by default): rows that share one are flagged. */
+    title?: string;
+    /**
+     * Search by meaning: which fields make up what a row means (embedded in the background) and
+     * the column that changes on every write, so the index step picks up only what changed.
+     */
+    meaning?: {
+        fields: string[];
+        changed: string;
+    };
+}
+/** What the model sends: flat, so every provider takes the schema. Tag fields are their own keys. */
+export interface FindQuery {
+    like?: string;
+    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`. Say this number when asked how many. */
+    count: number;
+    /** Rows in this answer (at most `limit`). */
+    returned: number;
+    rows: Record<string, unknown>[];
+    /** Different rows that share a name: each is its own row, so say both. */
+    same_name?: {
+        name: string;
+        ids: unknown[];
+    }[];
+    /** Set when a part of the query could not run as asked (no word index yet, meaning down). */
+    note?: string;
+}
+/** Checks a definition once, where the app declares it. */
+export declare function defineFind(def: FindDef): FindDef;
+/** A field as SQL over the row aliased `t`: its column, or its own expression. */
+export declare const findRef: (def: FindDef, f: string) => string;
+/**
+ * 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. With
+ * `like` and a `meaning`, the index's nearest rows come first and the same SQL trims them.
+ */
+export declare function runFind(def: FindDef, sql: SqlRunner, q: FindQuery, meaning?: FindMeaning): 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, opts?: {
+    meaning?: FindMeaning;
+}): Promise<PlainTool>;

package/dist/assistant/find.js

@@ -0,0 +1,416 @@
+import { ToolError, withDeadline } from './tools.js';
+const RESERVED = new Set([
+    'like',
+    'any',
+    'all',
+    'none',
+    'in',
+    'ids',
+    'fields',
+    'sort',
+    'desc',
+    'limit',
+]);
+const FIND_MS = 3_000;
+const TAG_VALUES = 60;
+const WORDS = 20;
+/** Rows nearest in meaning that `like` asks the index for, before the SQL trims them. */
+const NEAR_MIN = 20;
+const NEAR_MAX = 50;
+/** 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 (f.sql && f.kind === 'text')
+            throw new Error(`find ${def.name}: field "${n}" is text, which needs a column, not sql`);
+    }
+    if (!Object.values(def.fields).some((f) => f.kind === 'text'))
+        throw new Error(`find ${def.name}: give at least one text field`);
+    if (def.title && def.fields[def.title]?.kind !== 'text')
+        throw new Error(`find ${def.name}: title "${def.title}" is not a text field`);
+    if (def.meaning) {
+        if (!ident.test(def.meaning.changed))
+            throw new Error(`find ${def.name}: meaning.changed "${def.meaning.changed}" is not a plain name`);
+        const bad = def.meaning.fields.filter((f) => !def.fields[f]);
+        if (bad.length || !def.meaning.fields.length)
+            throw new Error(`find ${def.name}: meaning.fields ${bad.join(', ') || '(none)'} are not fields`);
+    }
+    return def;
+}
+const col = (def, f) => def.fields[f]?.column ?? f;
+/** A field as SQL over the row aliased `t`: its column, or its own expression. */
+export const findRef = (def, f) => def.fields[f]?.sql ?? `t.${col(def, 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 {
+        like: typeof q.like === 'string' ? q.like.replace(/\s+/g, ' ').trim().slice(0, 300) : '',
+        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). `near`
+ * is the rows nearest in meaning, nearest first: only they can match, in that order.
+ */
+function compile(def, q, fts, near) {
+    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 = findRef(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);
+    }
+    let nearOrder = '';
+    if (near?.length) {
+        where.push(`${t}.${def.key} IN (${near.map(() => '?').join(', ')})`);
+        args.push(...near);
+        // Literal integers, not bound: the ORDER BY comes after the WHERE's bound values.
+        nearOrder = `CASE ${t}.${def.key} ${near.map((id, i) => `WHEN ${Math.trunc(id)} THEN ${i}`).join(' ')} END`;
+    }
+    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
+        ? `${findRef(def, c.sort)} ${c.desc ? 'DESC' : 'ASC'}`
+        : nearOrder ||
+            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}` : `${findRef(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,
+        like: c.like,
+        limit: c.limit,
+        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. With
+ * `like` and a `meaning`, the index's nearest rows come first and the same SQL trims them.
+ */
+export async function runFind(def, sql, q, meaning) {
+    let built = compile(def, q, true);
+    const notes = [];
+    let near;
+    if (built.like) {
+        if (!meaning || !def.meaning)
+            throw new ToolError('like: this find has no search by meaning; use words instead.');
+        const k = Math.min(NEAR_MAX, Math.max(NEAR_MIN, built.limit * 2));
+        try {
+            near = await withDeadline(`${def.name} meaning`, FIND_MS, meaning.near(built.like, k));
+        }
+        catch {
+            near = undefined;
+        }
+        if (near?.length)
+            built = compile(def, q, true, near);
+        else
+            notes.push('Search by meaning is not available now: like was left out, the rest applied.');
+    }
+    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, near);
+        notes.push('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);
+    const out = rows.map((r) => {
+        const row = { [def.key]: r[def.key] };
+        for (const f of built.fields) {
+            const v = r[f];
+            if (def.fields[f]?.json && typeof v === 'string') {
+                try {
+                    row[f] = JSON.parse(v);
+                }
+                catch {
+                    row[f] = v;
+                }
+            }
+            else
+                row[f] = v;
+        }
+        return row;
+    });
+    const same = sameNames(def, out, built.fields);
+    return {
+        count,
+        returned: out.length,
+        rows: out,
+        ...(same.length ? { same_name: same } : {}),
+        ...(notes.length ? { note: notes.join(' ') } : {}),
+    };
+}
+/** Rows in the answer that share a name, so the model counts and lists each of them. */
+function sameNames(def, rows, fields) {
+    const title = def.title ?? textFields(def)[0];
+    if (!title || !fields.includes(title))
+        return [];
+    const by = new Map();
+    for (const r of rows) {
+        const name = String(r[title] ?? '').trim();
+        if (!name)
+            continue;
+        const k = name.toLowerCase();
+        const g = by.get(k) ?? { name, ids: [] };
+        g.ids.push(r[def.key]);
+        by.set(k, g);
+    }
+    return [...by.values()].filter((g) => g.ids.length > 1);
+}
+/** The values a tag field holds, to list in the tool's description. */
+async function tagValues(def, sql, field) {
+    const c = findRef(def, field);
+    const rows = await sql.all(`SELECT DISTINCT ${c} AS v FROM ${def.table} t${def.where ? ` WHERE ${def.where}` : ''} ORDER BY v 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, meaning) {
+    const names = Object.keys(def.fields);
+    const text = textFields(def);
+    const list = (description, items = { type: 'string' }) => ({
+        type: 'array',
+        items,
+        description,
+    });
+    const props = {
+        ...(meaning
+            ? {
+                like: {
+                    type: 'string',
+                    description: `A loose ask in plain words ("something light for a hot day", "good for a party"): the ${def.label}s nearest in meaning come first, and every other condition still applies. Use it for a mood, an occasion or a kind of thing, not for one exact word.`,
+                },
+            }
+            : {}),
+        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, opts = {}) {
+    const meaning = def.meaning ? opts.meaning : undefined;
+    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${meaning ? ', and like for a loose ask' : ''}) and ask only for the fields the answer needs. Fields: ${fields}. Returns the matching ${def.label}s, how many match in all (count) and any that share a name (same_name).`,
+        inputSchema: schemaOf(def, tags, Boolean(meaning)),
+        read: true,
+        find: true,
+        run: (args) => runFind(def, sql, (args ?? {}), meaning),
+    };
+}

package/dist/assistant/index.d.ts

@@ -15,6 +15,8 @@
 export * from './bearings.js';
 export * from './chatgpt.js';
 export * from './engine.js';
+export * from './find.js';
+export * from './meaning.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,8 @@
 export * from './bearings.js';
 export * from './chatgpt.js';
 export * from './engine.js';
+export * from './find.js';
+export * from './meaning.js';
 export * from './models.js';
 export * from './routes.js';
 export { DEFAULT_CAP, keyDocName, monthIn, State, waitText, } from './state.js';

package/dist/assistant/meaning.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Search by meaning for a find tool: a vector index of what each row means, asked for the rows
+ * nearest a loose ask, which the find's own SQL then trims (filters, words, rows the person never
+ * sees). Opt in per app: `meaning` on the definition, then
+ *
+ *   const meaning = vectorMeaning({ embed: workersEmbed(env.AI), index: env.NOTES_INDEX });
+ *   await findTool(notesFind, d1Sql(env.DB), { meaning });
+ *
+ * The index is kept in step by `meaningStep`, a small budgeted background step (`waitUntil`, an
+ * alarm or a queue) that embeds only the rows whose `changed` column moved past its bookmark, so
+ * it never runs on the request path and resumes wherever it stopped, whoever wrote the rows.
+ */
+import { type FindDef } from './find.js';
+import type { SqlRunner } from './store.js';
+/** The rows nearest in meaning to a loose ask, by key, nearest first. */
+export interface FindMeaning {
+    near(text: string, k: number): Promise<number[]>;
+}
+/** Texts to vectors, in order. */
+export type Embed = (texts: string[], as: 'query' | 'passage') => Promise<number[][]>;
+/** What a vector index needs (Cloudflare Vectorize has it). */
+export interface VectorIndex {
+    query(vector: number[], options: {
+        topK: number;
+        namespace?: string;
+    }): Promise<{
+        matches: {
+            id: string;
+            score: number;
+        }[];
+    }>;
+    upsert(vectors: {
+        id: string;
+        values: number[];
+        namespace?: string;
+    }[]): Promise<unknown>;
+    deleteByIds(ids: string[]): Promise<unknown>;
+}
+/** Workers AI's text embeddings (`AI.run`). */
+export interface EmbedAi {
+    run(model: string, input: {
+        text: string[];
+    }): Promise<unknown>;
+}
+export declare const EMBED_MODEL = "@cf/baai/bge-base-en-v1.5";
+/** Embeddings from Workers AI: bge-base-en-v1.5 (768 dimensions, cosine) unless `model` says. */
+export declare function workersEmbed(ai: EmbedAi, model?: string): Embed;
+/** Search by meaning over a vector index: one embedding, one query. */
+export declare function vectorMeaning(o: {
+    embed: Embed;
+    index: VectorIndex;
+    /** One per person when rows are a person's own. */
+    namespace?: string;
+}): FindMeaning;
+/** Where the step stopped: the last row's `changed` value and key. */
+export interface MeaningMark {
+    at: string | number;
+    key: number;
+}
+export interface MeaningStepOptions {
+    def: FindDef;
+    sql: SqlRunner;
+    embed: Embed;
+    index: VectorIndex;
+    namespace?: string;
+    /** The bookmark, kept by the app (a settings row, its object's storage). */
+    mark: {
+        get(): Promise<MeaningMark | null>;
+        put(m: MeaningMark): Promise<void>;
+    };
+    /** Rows one step reads at most (50). */
+    rows?: number;
+}
+/** What a row means, as text: its meaning fields with their names, JSON lists flattened. */
+export declare function meaningText(def: FindDef, row: Record<string, unknown>): string;
+/**
+ * One budgeted step of keeping the index in step: the next rows (at most `rows`) whose `changed`
+ * column moved past the bookmark, embedded in one call and written in one upsert; rows the find
+ * never shows (its `where`) leave the index. Safe to run twice at once (writes are idempotent).
+ * `done` is false while rows are left: run it again (another `waitUntil`, the next alarm).
+ * A row deleted outright keeps its vector, which the find's SQL never matches.
+ */
+export declare function meaningStep(o: MeaningStepOptions): Promise<{
+    indexed: number;
+    removed: number;
+    done: boolean;
+}>;

package/dist/assistant/meaning.js

@@ -0,0 +1,115 @@
+/**
+ * Search by meaning for a find tool: a vector index of what each row means, asked for the rows
+ * nearest a loose ask, which the find's own SQL then trims (filters, words, rows the person never
+ * sees). Opt in per app: `meaning` on the definition, then
+ *
+ *   const meaning = vectorMeaning({ embed: workersEmbed(env.AI), index: env.NOTES_INDEX });
+ *   await findTool(notesFind, d1Sql(env.DB), { meaning });
+ *
+ * The index is kept in step by `meaningStep`, a small budgeted background step (`waitUntil`, an
+ * alarm or a queue) that embeds only the rows whose `changed` column moved past its bookmark, so
+ * it never runs on the request path and resumes wherever it stopped, whoever wrote the rows.
+ */
+import { findRef } from './find.js';
+import { withDeadline } from './tools.js';
+export const EMBED_MODEL = '@cf/baai/bge-base-en-v1.5';
+/** bge models are asymmetric: a query (not a passage) needs this, or scores bunch together. */
+const BGE_QUERY = 'Represent this sentence for searching relevant passages: ';
+/** Texts one embedding call takes. */
+const EMBED_BATCH = 100;
+/** Embeddings from Workers AI: bge-base-en-v1.5 (768 dimensions, cosine) unless `model` says. */
+export function workersEmbed(ai, model = EMBED_MODEL) {
+    const prefix = /\/bge-/.test(model) ? BGE_QUERY : '';
+    return async (texts, as) => {
+        const out = [];
+        for (let i = 0; i < texts.length; i += EMBED_BATCH) {
+            const batch = texts.slice(i, i + EMBED_BATCH).map((t) => (as === 'query' ? prefix + t : t));
+            const res = (await ai.run(model, { text: batch }));
+            if (!res.data || res.data.length !== batch.length)
+                throw new Error('embedding failed');
+            out.push(...res.data);
+        }
+        return out;
+    };
+}
+/**
+ * A vector id: the row's key, after the namespace when there is one, so ids stay unique across
+ * people in one index (a Durable Object app gives each person a namespace).
+ */
+const vectorId = (key, namespace) => namespace ? `${namespace}:${key}` : `${key}`;
+const keyOf = (id) => Number(id.slice(id.lastIndexOf(':') + 1));
+/** Search by meaning over a vector index: one embedding, one query. */
+export function vectorMeaning(o) {
+    return {
+        async near(text, k) {
+            const [vector] = await o.embed([text], 'query');
+            if (!vector)
+                return [];
+            const res = await o.index.query(vector, {
+                topK: k,
+                ...(o.namespace ? { namespace: o.namespace } : {}),
+            });
+            return res.matches.map((m) => keyOf(m.id)).filter(Number.isInteger);
+        },
+    };
+}
+/** What a row means, as text: its meaning fields with their names, JSON lists flattened. */
+export function meaningText(def, row) {
+    const parts = [];
+    for (const f of def.meaning?.fields ?? []) {
+        let v = row[f];
+        if (def.fields[f]?.json && typeof v === 'string') {
+            try {
+                v = JSON.parse(v);
+            }
+            catch { }
+        }
+        const flat = (x) => Array.isArray(x)
+            ? x.map(flat).filter(Boolean).join('; ')
+            : x && typeof x === 'object'
+                ? Object.values(x).map(flat).filter(Boolean).join(': ')
+                : x === null || x === undefined
+                    ? ''
+                    : String(x);
+        const text = flat(v).replace(/\s+/g, ' ').trim();
+        if (text)
+            parts.push(`${f}: ${text}`);
+    }
+    return parts.join('\n').slice(0, 2_000);
+}
+const STEP_MS = 20_000;
+/**
+ * One budgeted step of keeping the index in step: the next rows (at most `rows`) whose `changed`
+ * column moved past the bookmark, embedded in one call and written in one upsert; rows the find
+ * never shows (its `where`) leave the index. Safe to run twice at once (writes are idempotent).
+ * `done` is false while rows are left: run it again (another `waitUntil`, the next alarm).
+ * A row deleted outright keeps its vector, which the find's SQL never matches.
+ */
+export async function meaningStep(o) {
+    const { def } = o;
+    if (!def.meaning)
+        return { indexed: 0, removed: 0, done: true };
+    const n = Math.max(1, Math.min(EMBED_BATCH, o.rows ?? 50));
+    const changed = `t.${def.meaning.changed}`;
+    const mark = await o.mark.get();
+    const cols = [...new Set(def.meaning.fields)].map((f) => `${findRef(def, f)} AS ${f}`).join(', ');
+    const live = def.where ? `CASE WHEN (${def.where}) THEN 1 ELSE 0 END` : '1';
+    const rows = await withDeadline(`${def.name} meaning`, STEP_MS, o.sql.all(`SELECT t.${def.key} AS _key, ${changed} AS _at, ${live} AS _live, ${cols} FROM ${def.table} t${mark ? ` WHERE (${changed} > ? OR (${changed} = ? AND t.${def.key} > ?))` : ''} ORDER BY ${changed}, t.${def.key} LIMIT ${n}`, ...(mark ? [mark.at, mark.at, mark.key] : [])));
+    if (!rows.length)
+        return { indexed: 0, removed: 0, done: true };
+    const keep = rows.filter((r) => Number(r._live) === 1);
+    const gone = rows.filter((r) => Number(r._live) !== 1);
+    if (keep.length) {
+        const vectors = await withDeadline(`${def.name} embed`, STEP_MS, o.embed(keep.map((r) => meaningText(def, r)), 'passage'));
+        await o.index.upsert(keep.map((r, i) => ({
+            id: vectorId(Number(r._key), o.namespace),
+            values: vectors[i] ?? [],
+            ...(o.namespace ? { namespace: o.namespace } : {}),
+        })));
+    }
+    if (gone.length)
+        await o.index.deleteByIds(gone.map((r) => vectorId(Number(r._key), o.namespace)));
+    const last = rows[rows.length - 1];
+    await o.mark.put({ at: last._at, key: Number(last._key) });
+    return { indexed: keep.length, removed: gone.length, done: rows.length < n };
+}

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.140",
+  "version": "0.1.142",
   "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.140",
-    "@columenlabs/lumen-ui-types": "0.1.140",
+    "@columenlabs/lumen-ops": "0.1.142",
+    "@columenlabs/lumen-ui-types": "0.1.142",
     "openai": "7.32.0",
     "zod": "^4.3.6"
   },