@columenlabs/lumen-ai 0.1.139 → 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. */

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,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.',
         ];
@@ -933,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.`);
@@ -1086,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);
@@ -1123,7 +1172,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 +1210,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 +1239,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/package.json

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