@columenlabs/lumen-ai 0.1.138 → 0.1.140

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. */
@@ -239,8 +243,6 @@ export declare class Assistant {
     private compact;
     /** How the person's cards ended since the last answer, once each. */
     private cardNews;
-    /** The answer as later turns remember it: with what its tools returned, cut. */
-    private remember;
     /** Starts a person's ChatGPT plan sign-in: the address to open in a new tab. */
     startSignin(caller: Caller, provider: AssistantProvider): Promise<{
         url: string;

package/dist/assistant/engine.js

@@ -45,12 +45,24 @@ 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';
-/** What later turns remember of a turn's tool results. */
-const RAN_CHARS = 1500;
-const RAN_TOTAL = 6000;
+/**
+ * What later turns remember of the tools' results, so a follow-up ("list them all", "which have no
+ * milk") answers from what was read instead of calling the same tools again. Each result is kept
+ * as the model saw it (`RAN_CHARS`), at most `RAN_TURN` a turn as stored, and the whole chat sends
+ * at most `RAN_CHAT`: newest first, a call repeated later kept only in its latest turn, and past
+ * the budget an older result is named but dropped, so a long chat costs no more than a short one.
+ */
+const RAN_CHARS = RESULT_CHARS;
+const RAN_TURN = 40_000;
+const RAN_CHAT = 40_000;
 const CHATS_LISTED = 200;
 const WHY_TEXT = {
     asked: 'you asked',
@@ -58,6 +70,58 @@ const WHY_TEXT = {
     stuck: 'stuck',
     check_failed: 'check failed',
 };
+/** JSON with object keys sorted, so the same input written in another order is the same call. */
+function stableJson(v) {
+    return JSON.stringify(v, (_k, x) => x && typeof x === 'object' && !Array.isArray(x)
+        ? Object.fromEntries(Object.entries(x).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
+        : x);
+}
+/** A turn's tool results as stored: each cut to what the model saw, the turn to `RAN_TURN`. */
+function ranOf(runs) {
+    let left = RAN_TURN;
+    const ran = [];
+    for (const r of runs) {
+        if (left <= 0)
+            break;
+        const result = r.result.slice(0, Math.min(RAN_CHARS, left));
+        left -= result.length;
+        ran.push({ ...r, result: result.length < r.result.length ? `${result} …(cut)` : result });
+    }
+    return ran.length ? { ran } : {};
+}
+/**
+ * The history as sent: each answer followed by what its tools returned, within `RAN_CHAT` for the
+ * whole chat, newest first. A call made again later is kept only there; one past the budget is
+ * named so the model knows to call it again. Chats stored before `ran` carry it in `content`.
+ */
+function toolMemory(history) {
+    let left = RAN_CHAT;
+    const later = new Set();
+    const out = [];
+    for (let i = history.length - 1; i >= 0; i--) {
+        const t = history[i];
+        if (!t.ran?.length) {
+            out.push({ role: t.role, content: t.content });
+            continue;
+        }
+        const lines = t.ran.map((r) => {
+            if (r.key && later.has(r.key))
+                return `- ${r.tool} → (called again later; see there)`;
+            if (r.key)
+                later.add(r.key);
+            if (left < 200)
+                return `- ${r.tool} → (no longer kept; call it again if you need it)`;
+            const kept = r.result.slice(0, left);
+            left -= kept.length;
+            return `- ${r.tool} → ${kept}${kept.length < r.result.length ? ' …(cut)' : ''}`;
+        });
+        out.push({
+            role: t.role,
+            content: `${t.content}\n\n[Tools I used and what they returned]\n${lines.join('\n')}`,
+        });
+    }
+    return out.reverse();
+}
 const NO_USAGE = { calls: 0, in: 0, read: 0, out: 0, usd: 0, parts: [] };
 function addUsage(u, parts) {
     const out = { ...u, parts: u.parts.map((p) => ({ ...p })) };
@@ -572,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. */
@@ -684,7 +783,14 @@ export class Assistant {
         const tools = await this.openTools(caller, p);
         const runs = [];
         doc.writes ??= {};
-        const counts = { steps: 0, handoffs: 0, advice: 0, end: main.tier, writes: doc.writes };
+        const counts = {
+            steps: 0,
+            handoffs: 0,
+            advice: 0,
+            end: main.tier,
+            writes: doc.writes,
+            seen: new Map(),
+        };
         let outcome = 'ok';
         try {
             const appSystem = typeof this.o.system === 'string' ? this.o.system : await this.o.system(caller);
@@ -738,7 +844,7 @@ export class Assistant {
                 ? `The person handed this message to ${handTo.label}: call escalate {tier: "${handTo.id}", why: "asked"} now, its task the message with every fact from this chat it needs, then answer from its memo.\n\n`
                 : '';
             const messages = [
-                ...doc.history.map((t) => ({ role: t.role, content: t.content })),
+                ...toolMemory(doc.history),
                 { role: 'user', content: `${page}${lead}${asked}` },
             ];
             const escalateTool = this.escalateTool(main.tier);
@@ -791,7 +897,7 @@ export class Assistant {
                 emit('text_end', {});
             }
             doc.history.push({ role: 'user', content: `${page}${asked}` });
-            doc.history.push({ role: 'assistant', content: this.remember(answer, runs) });
+            doc.history.push({ role: 'assistant', content: answer, ...ranOf(runs) });
         }
         catch (err) {
             if (signal?.aborted) {
@@ -852,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.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.',
         ];
@@ -867,7 +978,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 ${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.`);
@@ -1020,13 +1131,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);
@@ -1045,8 +1160,20 @@ export class Assistant {
             await Promise.resolve(this.o.onStep?.({ kind: 'draft', tool: use.name, tier: session.tier.id, handoff })).catch(() => undefined);
             return reply(`Drafted: a "${title}" card is on the person's screen. Nothing changed until they press Save.`);
         }
+        // The same read with the same input in one answer gives back what it gave, without running it
+        // again or showing a second step: a model that lost track of a result reads it here, not twice.
+        const key = f.write ? '' : `${use.name}\u0000${stableJson(use.input)}`;
+        const again = key ? counts.seen.get(key) : undefined;
+        if (again)
+            return reply(`(Same call as earlier in this answer; its result again.)\n${await again}`);
+        let settle = () => undefined;
+        if (key)
+            counts.seen.set(key, new Promise((done) => {
+                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;
@@ -1060,8 +1187,10 @@ export class Assistant {
             out = typeof result === 'string' ? result : JSON.stringify(result);
         }
         catch (err) {
-            if (signal?.aborted)
+            if (signal?.aborted) {
+                settle('(stopped)');
                 throw err;
+            }
             ok = false;
             error =
                 err instanceof ToolError || err instanceof Error ? err.message.slice(0, 300) : 'failed';
@@ -1081,10 +1210,15 @@ export class Assistant {
                 ? { write: { undo: !!this.groupById(f.group)?.undo, status: 'done' } }
                 : {}),
         };
-        sink.push(item);
-        emit('step', item);
-        counts.steps += 1;
-        runs.push({ tool: use.name, result: out.slice(0, RAN_CHARS) });
+        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();
+        runs.push({ tool: use.name, key, result: out });
         await Promise.resolve(this.o.onStep?.({
             kind: 'tool',
             tool: use.name,
@@ -1095,9 +1229,78 @@ export class Assistant {
             tier: session.tier.id,
             handoff,
         })).catch(() => undefined);
-        const cut = out.length > RESULT_CHARS ? `${out.slice(0, RESULT_CHARS)} …(cut: ask for less)` : out;
+        const cut = out.length > RESULT_CHARS
+            ? `${out.slice(0, RESULT_CHARS)} …(cut at ${RESULT_CHARS.toLocaleString('en-US')} of ${out.length.toLocaleString('en-US')} characters: the rest was not read; ask again for less)`
+            : out;
+        if (key) {
+            settle(cut);
+            if (!ok)
+                counts.seen.delete(key);
+        }
         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;
@@ -1493,7 +1696,7 @@ export class Assistant {
         if (doc.history.length < 2)
             return false;
         const system = `Summarise this chat between a person and ${this.name}, their assistant, so ${this.name} can carry on from the summary alone. Keep what the person wants, the facts and numbers found, decisions made and cards drafted or saved, and anything still open. Plain bullets, at most 400 words. No preamble.`;
-        const chat = doc.history
+        const chat = toolMemory(doc.history)
             .map((t) => `${t.role === 'user' ? 'Person' : this.name}: ${t.content}`)
             .join('\n\n');
         let summary = '';
@@ -1554,21 +1757,6 @@ export class Assistant {
             .map((d) => `- ${d.title} ${JSON.stringify(d.args).slice(0, 300)}: ${d.status}${d.error ? ` (${d.error})` : ''}${d.result !== undefined ? ` → ${JSON.stringify(d.result).slice(0, 300)}` : ''}`)
             .join('\n')}\n\n`;
     }
-    /** The answer as later turns remember it: with what its tools returned, cut. */
-    remember(answer, runs) {
-        if (!runs.length)
-            return answer;
-        let left = RAN_TOTAL;
-        const lines = [];
-        for (const r of runs) {
-            if (left <= 0)
-                break;
-            const line = `- ${r.tool} → ${r.result.slice(0, Math.min(RAN_CHARS, left))}`;
-            left -= line.length;
-            lines.push(line);
-        }
-        return `${answer}\n\n[Tools I used and what they returned]\n${lines.join('\n')}`;
-    }
     // ---------------------------------------------------------------- keys
     /** Starts a person's ChatGPT plan sign-in: the address to open in a new tab. */
     async startSignin(caller, provider) {

package/dist/assistant/tools.d.ts

@@ -45,5 +45,5 @@ export interface PlainTool extends ToolDef {
 export declare function plainTools(tools: PlainTool[]): ToolSource;
 /** A tool name the model may use: letters, digits, `_` and `-`, at most 64. */
 export declare function toolName(group: string, name: string): string;
-/** Rows in a list result: an array, or the first array field of an object. */
+/** Rows in a list result: an array, an object's `count`, or the one array an object holds. */
 export declare function rowCount(v: unknown): number | undefined;

package/dist/assistant/tools.js

@@ -98,13 +98,17 @@ export function plainTools(tools) {
 export function toolName(group, name) {
     return `${group}__${name}`.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 64);
 }
-/** Rows in a list result: an array, or the first array field of an object. */
+/** Rows in a list result: an array, an object's `count`, or the one array an object holds. */
 export function rowCount(v) {
     if (Array.isArray(v))
         return v.length;
-    if (v && typeof v === 'object')
-        for (const x of Object.values(v))
-            if (Array.isArray(x))
-                return x.length;
-    return undefined;
+    if (!v || typeof v !== 'object')
+        return undefined;
+    // A list with its total says so; else the one list it holds. A record with several lists (a
+    // recipe's ingredients and steps) is one thing, not rows.
+    const o = v;
+    if (typeof o.count === 'number' && Number.isFinite(o.count))
+        return o.count;
+    const lists = Object.values(o).filter(Array.isArray);
+    return lists.length === 1 ? lists[0]?.length : undefined;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@columenlabs/lumen-ai",
-  "version": "0.1.138",
+  "version": "0.1.140",
   "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.138",
-    "@columenlabs/lumen-ui-types": "0.1.138",
+    "@columenlabs/lumen-ops": "0.1.140",
+    "@columenlabs/lumen-ui-types": "0.1.140",
     "openai": "7.32.0",
     "zod": "^4.3.6"
   },