@columenlabs/lumen-ai 0.1.177 → 0.1.178

package/README.md

@@ -225,3 +225,17 @@ ctx.waitUntil(meaningStep({ def: notesFind, sql: d1Sql(env.DB), embed, index: en
 | `UsageMeter`, `tokenUsage(u)` | Prices each step's tokens (cache reads and writes, reasoning) into one usage part |
 
 A ChatGPT plan sign-in is free to the app (`priced` with `free`). Nothing here holds a key or a token: the app passes them per turn.
+
+An app with an `Assistant` gets the whole plan from it: `assistant.agentTurn(caller, { message, tier?, context?, refs?, time_zone? })` returns `{ plan, settle }` with the person's tier and model on whoever pays, the tool groups at their access, the kit's rules, the bearings and the page before the message, `escalate` to a higher tier (its own usage part, inside the same cap) and Claude's advisor. `settle` adds the spend to the payer's month and reports the turn through `onStep`. It throws `AssistantError` when nobody can pay. Drafts, Undo and compaction still run only in `turn`.
+
+```ts
+class Chat extends LumenAgent<Env> {
+  #settle?: (end: AgentTurnEnd) => Promise<void>;
+  async plan(turn: TurnContext) {
+    const { plan, settle } = await assistant.agentTurn(caller, { message: lastText(turn), ...turn.body });
+    this.#settle = settle;
+    return plan;
+  }
+  settle(end: AgentTurnEnd) { return this.#settle?.(end) ?? Promise.resolve(); }
+}
+```

package/dist/agent/agent.d.ts

@@ -1,4 +1,3 @@
-import { type ChatResponseResult, type PrepareStepContext, type StepConfig, type StepContext, Think, type ThinkModel, type TurnConfig, type TurnContext } from '@cloudflare/think';
 /**
  * `LumenAgent`: one chat as a Cloudflare Think agent, run on the app's tiers, keys and tool groups.
  * Think keeps the loop, the messages, streaming, resume and compaction; the app answers `plan` for
@@ -9,11 +8,24 @@ import { type ChatResponseResult, type PrepareStepContext, type StepConfig, type
  *     plan(turn) { return sagePlan(this.env, this.name, turn); }
  *     settle(s) { return recordSpend(this.env, this.name, s); }
  *   }
+ *
+ * An `Assistant` gives both: `assistant.agentTurn(caller, input)` returns a plan and its settle.
  */
+import { type ChatResponseResult, type PrepareStepContext, type StepConfig, type StepContext, Think, type ThinkModel, type TurnConfig, type TurnContext } from '@cloudflare/think';
 import type { AssistantEffort, UsagePart } from '@columenlabs/lumen-ui-types/assistant';
+import type { ModelMessage, ToolSet } from 'ai';
 import type { ModelDef } from '../assistant/models.js';
 import { type ModelKey } from './models.js';
-import { type AiToolsOptions, type SourceAt } from './tools.js';
+import { type AiToolsOptions, type OpenedTools, type SourceAt } from './tools.js';
+import { UsageMeter } from './usage.js';
+/** What a plan's extra tools get: the open tools, a meter of their own and the cap. */
+export interface TurnTools {
+    opened: OpenedTools;
+    /** A new part of this answer's usage (a hand off), counted against the cap. */
+    meter(model: ModelDef, label: string, free?: boolean): UsageMeter;
+    /** Spent this answer reached what the payer has left. */
+    over(): boolean;
+}
 /** What one turn runs on, as the app decides it. */
 export interface AgentTurnPlan {
     /** The tier's model, and the key or sign-in it runs on. */
@@ -24,10 +36,23 @@ export interface AgentTurnPlan {
     out?: number;
     /** The usage part's label: `Tier · Model`. */
     label: string;
-    /** The app's instructions and the kit's rules, joined. */
-    system: string;
+    /** The app's instructions and the kit's rules, joined; a function sees the tools opened. */
+    system: string | ((t: OpenedTools) => string);
+    /** Put before the person's newest message for the model only (bearings, the page). */
+    lead?: string;
     /** The tool groups at the person's access. */
     sources: SourceAt[];
+    /** Tools beside the groups' (hand off), made once those are open. */
+    more?: (t: TurnTools) => ToolSet;
+    /** Call this tool first (a message handed to a higher tier). */
+    first?: string;
+    /** Claude's advisor: a bigger Claude reads the chat and sends a plan. */
+    advisor?: {
+        model: ModelDef;
+        label: string;
+        maxUses: number;
+        maxTokens: number;
+    };
     /** Dollars the payer has left; at or past it the model gets no more tools. */
     left?: number;
     /** Most model calls in one answer; 8. */
@@ -39,23 +64,29 @@ export interface AgentTurnPlan {
 /** How a turn ended, with its usage, for the app to record. */
 export interface AgentTurnEnd {
     outcome: 'ok' | 'stopped' | 'error';
+    /** The main model's part first, then advice and hand offs; parts with no calls left out. */
     parts: UsagePart[];
     /** Tokens in the main model's last call: how full its context is. */
     context?: number;
+    /** Model calls of the main tier. */
+    steps: number;
     ms: number;
     /** The spend cap stopped tool use in this answer. */
     capped: boolean;
 }
+export declare const CAP_NOTE = "The spend cap for this month is reached: answer now from what you have, in a sentence or two. You can call no more tools.";
+/** The messages with `lead` put before the newest message the person wrote. */
+export declare function withLead(messages: ModelMessage[], lead: string | undefined): ModelMessage[];
 export declare abstract class LumenAgent<Env = unknown> extends Think<Env> {
     #private;
-    /** The turn the app runs now, or null between turns. */
+    /** The turn the app runs now. Throw to refuse it (no key, no money); the error is shown. */
     abstract plan(turn: TurnContext): Promise<AgentTurnPlan>;
     /** A turn ended: record its spend and how it went. Errors here are logged, never shown. */
     abstract settle(end: AgentTurnEnd): Promise<void>;
     /** Never read: `beforeTurn` gives every turn its own model. */
     getModel(): ThinkModel;
     beforeTurn(ctx: TurnContext): Promise<TurnConfig>;
-    beforeStep(_ctx: PrepareStepContext): StepConfig | undefined;
+    beforeStep(ctx: PrepareStepContext): StepConfig | undefined;
     onStepFinish(ctx: StepContext): void;
     onChatResponse(result: ChatResponseResult): Promise<void>;
     onChatError(error: unknown): unknown;

package/dist/agent/agent.js

@@ -1,8 +1,37 @@
+/**
+ * `LumenAgent`: one chat as a Cloudflare Think agent, run on the app's tiers, keys and tool groups.
+ * Think keeps the loop, the messages, streaming, resume and compaction; the app answers `plan` for
+ * each turn (which model on whose key, the instructions, the tools at the person's access, what is
+ * left to spend) and hears `settle` when the turn ends, to record the spend.
+ *
+ *   export class SageChat extends LumenAgent<Env> {
+ *     plan(turn) { return sagePlan(this.env, this.name, turn); }
+ *     settle(s) { return recordSpend(this.env, this.name, s); }
+ *   }
+ *
+ * An `Assistant` gives both: `assistant.agentTurn(caller, input)` returns a plan and its settle.
+ */
+import { anthropic } from '@ai-sdk/anthropic';
 import { Think, } from '@cloudflare/think';
 import { aiModel, turnSettings } from './models.js';
 import { openAiTools } from './tools.js';
 import { UsageMeter } from './usage.js';
-const CAP_NOTE = 'The spend cap for this month is reached: answer now from what you have, in a sentence or two. You can call no more tools.';
+export const CAP_NOTE = 'The spend cap for this month is reached: answer now from what you have, in a sentence or two. You can call no more tools.';
+/** The messages with `lead` put before the newest message the person wrote. */
+export function withLead(messages, lead) {
+    if (!lead)
+        return messages;
+    let i = messages.length - 1;
+    while (i >= 0 && messages[i]?.role !== 'user')
+        i -= 1;
+    const m = messages[i];
+    if (!m || m.role !== 'user')
+        return messages;
+    const content = typeof m.content === 'string'
+        ? `${lead}${m.content}`
+        : [{ type: 'text', text: lead }, ...m.content];
+    return [...messages.slice(0, i), { ...m, content }, ...messages.slice(i + 1)];
+}
 export class LumenAgent extends Think {
     #turn = null;
     /** Never read: `beforeTurn` gives every turn its own model. */
@@ -12,22 +41,52 @@ export class LumenAgent extends Think {
     async beforeTurn(ctx) {
         await this.#close();
         const plan = await this.plan(ctx);
-        const tools = await openAiTools(plan.sources, plan.tools ?? {});
+        const opened = await openAiTools(plan.sources, plan.tools ?? {});
         const free = !!plan.key.plan;
+        const main = new UsageMeter(plan.model, plan.label, free);
+        const meters = [main];
+        const advice = plan.advisor
+            ? new UsageMeter(plan.advisor.model, plan.advisor.label, free)
+            : undefined;
+        if (advice)
+            meters.push(advice);
+        const system = typeof plan.system === 'string' ? plan.system : plan.system(opened);
         this.#turn = {
             plan,
-            tools,
-            meter: new UsageMeter(plan.model, plan.label, free),
+            system,
+            tools: opened,
+            main,
+            ...(advice ? { advice } : {}),
+            meters,
+            steps: 0,
             capped: false,
             t0: Date.now(),
         };
+        const more = plan.more?.({
+            opened,
+            over: () => plan.left !== undefined && this.#spent() >= plan.left,
+            meter: (model, label, f = free) => {
+                const m = new UsageMeter(model, label, f);
+                meters.push(m);
+                return m;
+            },
+        });
+        const advisor = {};
+        if (plan.advisor)
+            advisor.advisor = anthropic.tools.advisor_20260301({
+                model: plan.advisor.model.id,
+                maxUses: plan.advisor.maxUses,
+                maxTokens: plan.advisor.maxTokens,
+            });
         return {
             model: aiModel(plan.model, plan.key, {
                 ...(plan.fetch ? { fetch: plan.fetch } : {}),
                 name: this.constructor.name,
             }),
-            instructions: plan.system,
-            tools: tools.tools,
+            instructions: system,
+            messages: withLead(ctx.messages, plan.lead),
+            tools: { ...opened.tools, ...more, ...advisor },
+            ...(plan.first ? { toolChoice: { type: 'tool', toolName: plan.first } } : {}),
             maxSteps: plan.maxSteps ?? 8,
             ...turnSettings(plan.model, {
                 effort: plan.effort ?? 'default',
@@ -36,22 +95,38 @@ export class LumenAgent extends Think {
             }),
         };
     }
-    beforeStep(_ctx) {
+    beforeStep(ctx) {
         const t = this.#turn;
-        if (!t || t.plan.left === undefined)
-            return undefined;
-        if (t.meter.part().usd < t.plan.left)
+        if (!t)
             return undefined;
-        t.capped = true;
-        // The SDK's step result is a union that Omit narrows to shared keys; these two exist on it.
-        return { activeTools: [], instructions: `${t.plan.system}\n\n${CAP_NOTE}` };
+        // The SDK's step result is a union that Omit narrows to shared keys; these exist on it.
+        if (t.plan.left !== undefined && this.#spent() >= t.plan.left) {
+            t.capped = true;
+            return { activeTools: [], instructions: `${t.system}\n\n${CAP_NOTE}` };
+        }
+        // A forced first call is for the first step only.
+        if (t.plan.first && ctx.stepNumber > 0)
+            return { toolChoice: 'auto' };
+        return undefined;
     }
     onStepFinish(ctx) {
         const t = this.#turn;
         if (!t)
             return;
-        const p = t.meter.add(ctx.usage);
+        t.steps += 1;
+        const p = t.main.add(ctx.usage);
         t.context = p.in + p.out;
+        // Claude's advisor bills apart from the step's own usage: its calls are listed one by one.
+        const meta = ctx
+            .providerMetadata;
+        for (const it of meta?.anthropic?.iterations ?? [])
+            if (it.type === 'advisor_message' && t.advice)
+                t.advice.addTokens({
+                    input_tokens: it.inputTokens ?? 0,
+                    output_tokens: it.outputTokens ?? 0,
+                    cache_read_input_tokens: it.cacheReadInputTokens ?? 0,
+                    cache_creation_input_tokens: it.cacheCreationInputTokens ?? 0,
+                });
     }
     async onChatResponse(result) {
         await this.#end(result.status === 'completed' ? 'ok' : result.status === 'aborted' ? 'stopped' : 'error');
@@ -60,6 +135,9 @@ export class LumenAgent extends Think {
         void this.#end('error');
         return error;
     }
+    #spent() {
+        return (this.#turn?.meters ?? []).reduce((a, m) => a + m.part().usd, 0);
+    }
     async #end(outcome) {
         const t = this.#turn;
         if (!t)
@@ -69,8 +147,9 @@ export class LumenAgent extends Think {
         try {
             await this.settle({
                 outcome,
-                parts: [t.meter.part()],
+                parts: t.meters.map((m) => m.part()).filter((p) => p.calls),
                 ...(t.context ? { context: t.context } : {}),
+                steps: t.steps,
                 ms: Date.now() - t.t0,
                 capped: t.capped,
             });

package/dist/agent/models.d.ts

@@ -1,5 +1,5 @@
 import type { AssistantEffort } from '@columenlabs/lumen-ui-types/assistant';
-import type { LanguageModel } from 'ai';
+import type { JSONValue, LanguageModel } from 'ai';
 import type { ModelDef } from '../assistant/models.js';
 /** The key a model runs on. `plan`: an OpenAI access token from a ChatGPT plan sign-in. */
 export interface ModelKey {
@@ -28,5 +28,5 @@ export declare function turnSettings(model: ModelDef, o: {
     plan?: boolean;
 }): {
     maxOutputTokens?: number;
-    providerOptions?: Record<string, Record<string, unknown>>;
+    providerOptions?: Record<string, Record<string, JSONValue>>;
 };

package/dist/agent/tools.d.ts

@@ -33,11 +33,20 @@ export interface AiToolsOptions {
     /** A result handed to the model is cut past this many characters. */
     maxChars?: number;
 }
+/** One tool offered this answer, as the instructions describe the set. */
+export interface ToolInfo {
+    name: string;
+    group: string;
+    kind: 'read' | 'draft' | 'write';
+    find: boolean;
+}
 /** Tools open for one answer, as the AI SDK's set, and how to let them go. */
 export interface OpenedTools {
     tools: ToolSet;
     /** Names of the reads, for a lazy loader's catalog or `activeTools`. */
     reads: string[];
+    /** Each tool offered: its name, group, kind and whether it is an app's find. */
+    info: ToolInfo[];
     failed: number;
     close(): Promise<void>;
 }

package/dist/agent/tools.js

@@ -25,6 +25,7 @@ export async function openAiTools(sources, o = {}) {
     const max = o.maxChars ?? 16_000;
     const tools = {};
     const reads = [];
+    const info = [];
     for (const { s, open } of opened)
         for (const def of open.tools) {
             const canWrite = s.access === 'draft' || s.access === 'write';
@@ -36,6 +37,7 @@ export async function openAiTools(sources, o = {}) {
             const name = toolName(s.group, def.name);
             if (kind === 'read')
                 reads.push(name);
+            info.push({ name, group: s.group, kind, find: !!def.find });
             tools[name] = tool({
                 description: describe(def, kind),
                 inputSchema: jsonSchema(withoutMeta(def.inputSchema)),
@@ -59,6 +61,7 @@ export async function openAiTools(sources, o = {}) {
     return {
         tools,
         reads,
+        info,
         failed: results.filter((r) => r.status === 'rejected').length,
         close: async () => {
             await Promise.all(opened.map((x) => x.open.close().catch(() => undefined)));

package/dist/agent/usage.d.ts

@@ -1,7 +1,7 @@
 /** An AI SDK step's usage as the kit's tokens and list-price cost. */
 import type { UsagePart } from '@columenlabs/lumen-ui-types/assistant';
 import type { LanguageModelUsage } from 'ai';
-import { type ModelDef } from '../assistant/models.js';
+import { type ModelDef, type TokenUsage } from '../assistant/models.js';
 /**
  * One call's usage in the kit's terms. Input splits into plain, cache writes and cache reads where
  * the provider says (Claude reports all three; OpenAI reports reads, its writes cost nothing extra).
@@ -25,5 +25,12 @@ export declare class UsageMeter {
         read: number;
         usd: number;
     };
+    /** Tokens a provider reports apart from the step's usage (Claude's advisor calls). */
+    addTokens(u: TokenUsage): {
+        in: number;
+        out: number;
+        read: number;
+        usd: number;
+    };
     part(): UsagePart;
 }

package/dist/agent/usage.js

@@ -27,7 +27,11 @@ export class UsageMeter {
         this.p = { label, calls: 0, in: 0, read: 0, out: 0, usd: 0 };
     }
     add(u) {
-        const t = priced(this.model, tokenUsage(u));
+        return this.addTokens(tokenUsage(u));
+    }
+    /** Tokens a provider reports apart from the step's usage (Claude's advisor calls). */
+    addTokens(u) {
+        const t = priced(this.model, u);
         this.p.calls += 1;
         this.p.in += t.in;
         this.p.read += t.read;

package/dist/assistant/engine.d.ts

@@ -1,4 +1,5 @@
 import type { AllowanceRequest, AllowanceState, AllowanceUnit, AssistantAccess, AssistantChat, AssistantChatRow, AssistantMessage, AssistantOwnWay, AssistantProvider, AssistantStatus, DraftItem, StepItem } from '@columenlabs/lumen-ui-types/assistant';
+import type { AgentTurnEnd, AgentTurnPlan } from '../agent/agent.js';
 import { type BearingsExtra, type BearingsNow } from './bearings.js';
 import { type ModelDef, type TaskDef, type TierDef } from './models.js';
 import { State } from './state.js';
@@ -173,6 +174,18 @@ export declare class AssistantError extends Error {
     constructor(message: string, code: string, status?: number);
 }
 type Emit = (event: string, data: unknown) => void;
+/** What a Think turn calls this turn: what one turn asks besides the message itself. */
+export interface AgentTurnInput {
+    message: string;
+    context?: AssistantMessage['context'];
+    refs?: AssistantMessage['refs'];
+    /** The tier the person picked for this message (`@`). */
+    tier?: string;
+    /** The browser's IANA zone, for the bearings. */
+    time_zone?: string;
+    /** When the chat's last message was, for "since you last asked". */
+    last_at?: number;
+}
 export declare class Assistant {
     private readonly o;
     readonly name: string;
@@ -203,6 +216,19 @@ export declare class Assistant {
     private mainTier;
     private access;
     private groupById;
+    /**
+     * One turn as a Think agent's plan (`LumenAgent` in `@columenlabs/lumen-ai/agent`): the person's
+     * tier and its model on whoever pays, the tool groups at their access, the kit's rules, the
+     * bearings and the page, hand off to a higher tier and Claude's advisor. `settle` records the
+     * spend and the turn. Throws `AssistantError` when nobody can pay (its text says what to do).
+     * Drafts, Undo and compaction stay with `turn` for now.
+     */
+    agentTurn(caller: Caller, input: AgentTurnInput): Promise<{
+        plan: AgentTurnPlan;
+        settle: (end: AgentTurnEnd) => Promise<void>;
+    }>;
+    /** The escalate tool of a Think turn: one task to a higher tier, its memo back. */
+    private agentEscalate;
     status(caller: Caller): Promise<AssistantStatus>;
     private get unit();
     private approver;
@@ -222,6 +248,8 @@ export declare class Assistant {
     purge(): Promise<number>;
     private writeChat;
     /** Opens the tools the person allows: each group's, then the web's. */
+    /** The tool groups (and the web) at the person's access, not opened yet. */
+    private sourcesOf;
     private openTools;
     private toolsFor;
     /** `batch`: any of the reads, up to BATCH_MAX at once, as one step. Null with no reads. */

package/dist/assistant/engine.js

@@ -18,7 +18,9 @@
  */
 import Anthropic from '@anthropic-ai/sdk';
 import { HAND_OFF_WHYS } from '@columenlabs/lumen-ui-types/assistant';
+import { generateText, jsonSchema, stepCountIs, tool } from 'ai';
 import OpenAI from 'openai';
+import { aiModel, turnSettings } from '../agent/models.js';
 import { bearings } from './bearings.js';
 import { CHATGPT_REDIRECT, SigninError, finishChatgpt, startChatgpt, testChatgpt, } from './chatgpt.js';
 import { ALL_MODELS, DEFAULT_OUT, Meter, PROVIDERS, effortParams, } from './models.js';
@@ -229,6 +231,29 @@ const withoutMeta = (schema) => {
 const shows = (output) => output.some((b) => b.type === 'function_call' ||
     (b.type === 'message' && b.content.some((c) => c.type === 'output_text' && c.text)));
 const isApiError = (err) => err instanceof Anthropic.APIError || err instanceof OpenAI.APIError;
+/**
+ * The tools of a Think turn as the rules describe them. Think calls several tools in one step on
+ * its own, so the kit's batch tool is not offered and its line is left out (`batch`).
+ */
+function openedSummary(t) {
+    return {
+        size: t.info.length,
+        find: t.info.some((i) => i.find),
+        reads: t.reads.length > 0,
+        batch: true,
+        web: t.info.some((i) => i.group === 'web'),
+    };
+}
+function summarize(fns) {
+    const all = [...fns.values()];
+    return {
+        size: fns.size,
+        find: all.some((f) => f.def.find),
+        reads: all.some((f) => !f.draft && !f.write),
+        batch: fns.has(BATCH),
+        web: all.some((f) => f.group === 'web'),
+    };
+}
 export class Assistant {
     o;
     name;
@@ -338,6 +363,211 @@ export class Assistant {
     groupById(id) {
         return this.groups.find((g) => g.id === id);
     }
+    // ---------------------------------------------------------------- a turn on Think
+    /**
+     * One turn as a Think agent's plan (`LumenAgent` in `@columenlabs/lumen-ai/agent`): the person's
+     * tier and its model on whoever pays, the tool groups at their access, the kit's rules, the
+     * bearings and the page, hand off to a higher tier and Claude's advisor. `settle` records the
+     * spend and the turn. Throws `AssistantError` when nobody can pay (its text says what to do).
+     * Drafts, Undo and compaction stay with `turn` for now.
+     */
+    async agentTurn(caller, input) {
+        const message = input.message.trim();
+        const picked = await this.mainTier(caller);
+        const lower = input.tier && !this.above(picked).some((t) => t.id === input.tier)
+            ? this.tierById(input.tier)
+            : undefined;
+        const main = await this.session(caller, lower ?? picked);
+        const { paying, wait } = await this.state.paying(caller.id, main.model.provider);
+        if (!paying) {
+            const code = wait ?? 'not_connected';
+            throw new AssistantError(waitText(code, main.model.provider, !!this.o.allowance), code, 402);
+        }
+        const keyOf = (provider) => {
+            const apiKey = paying.keys[provider];
+            return apiKey ? { apiKey, ...(paying.plans[provider] ? { plan: true } : {}) } : null;
+        };
+        const key = keyOf(main.model.provider) ?? { apiKey: paying.apiKey };
+        const p = await this.state.person(caller.id);
+        const policy = p.hand_off ?? 'next';
+        const advisor = await this.advisorFor(caller, p.advice, main);
+        const handTo = input.tier ? this.above(main.tier).find((t) => t.id === input.tier) : undefined;
+        const appSystem = typeof this.o.system === 'string' ? this.o.system : await this.o.system(caller);
+        const asked = await this.expand(caller, message);
+        const told = await bearings({
+            timeZone: input.time_zone,
+            fallbackZone: this.o.timeZone,
+            lastAt: input.last_at,
+            app: this.o.app,
+            ...(this.o.bearings ? { extras: (b) => this.o.bearings?.(b, caller) } : {}),
+        });
+        const page = told +
+            (input.refs?.length
+                ? `The person points at these parts: they are what "this" means, and when the person asks for a change they are the only parts to change. Read anything else you need (the rest of the page, other records, your tools) for context, but leave it as it is unless they ask.\n${JSON.stringify(input.refs).slice(0, 16000)}\n\n`
+                : '') +
+            (input.context
+                ? `Page: ${input.context.label}${input.context.note === undefined ? '' : `\n${JSON.stringify(input.context.note).slice(0, 4000)}`}\n\n`
+                : '');
+        const command = asked === message ? '' : `The person typed ${message.split(/\s/)[0]}: ${asked}\n\n`;
+        const reach = this.above(main.tier);
+        const counts = { handoffs: 0, end: main.tier };
+        const rulesFor = (s, t) => `${appSystem}\n\n${this.rules(s, policy, s ? advisor : null, openedSummary(t), t.failed)}`;
+        const plan = {
+            model: main.model,
+            key,
+            effort: main.effort,
+            out: main.tier.out ?? DEFAULT_OUT,
+            label: main.meter.label,
+            system: (t) => rulesFor(main, t),
+            lead: `${page}${handTo && reach.length
+                ? `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`
+                : ''}${command}`,
+            sources: await this.sourcesOf(caller, p),
+            left: paying.left,
+            maxSteps: MAX_ROUNDS,
+            ...(this.o.fetch ? { fetch: this.o.fetch } : {}),
+            ...(handTo && reach.length ? { first: 'escalate' } : {}),
+            ...(advisor
+                ? {
+                    advisor: {
+                        model: advisor.session.model,
+                        label: advisor.session.meter.label,
+                        maxUses: ADVICE_MAX,
+                        maxTokens: ADVICE_TOKENS,
+                    },
+                }
+                : {}),
+            tools: {
+                called: (c) => void Promise.resolve(this.o.onStep?.({
+                    kind: 'tool',
+                    tool: toolName(c.group, c.tool),
+                    ok: c.ok,
+                    ms: c.ms,
+                    tier: main.tier.id,
+                    handoff: false,
+                })).catch(() => undefined),
+            },
+            more: (tt) => reach.length
+                ? {
+                    escalate: this.agentEscalate(tt, {
+                        caller,
+                        message: `${page}${asked}`,
+                        asked: this.askedFor(message, main.tier),
+                        handTo,
+                        policy,
+                        main,
+                        keyOf,
+                        counts,
+                        system: (t) => rulesFor(null, t),
+                    }),
+                }
+                : {},
+        };
+        const settle = async (end) => {
+            await this.state.addSpend(caller.id, paying.payer, end.parts).catch(() => undefined);
+            const total = end.parts.reduce((a, m) => ({
+                calls: a.calls + m.calls,
+                in: a.in + m.in,
+                out: a.out + m.out,
+                usd: a.usd + m.usd,
+            }), { calls: 0, in: 0, out: 0, usd: 0 });
+            await Promise.resolve(this.o.onStep?.({
+                kind: 'turn',
+                outcome: end.outcome,
+                ms: end.ms,
+                tier: main.tier.id,
+                end_tier: counts.end.id,
+                handoffs: counts.handoffs,
+                advice: advisor
+                    ? (end.parts.find((x) => x.label === advisor.session.meter.label)?.calls ?? 0)
+                    : 0,
+                steps: end.steps,
+                ...total,
+            })).catch(() => undefined);
+        };
+        return { plan, settle };
+    }
+    /** The escalate tool of a Think turn: one task to a higher tier, its memo back. */
+    agentEscalate(tt, c) {
+        const reach = this.above(c.main.tier);
+        return tool({
+            description: 'Hands one task to a higher tier with the same tools. It works on its own and returns a memo of at most 200 words.',
+            inputSchema: jsonSchema({
+                type: 'object',
+                properties: {
+                    tier: { type: 'string', enum: reach.map((t) => t.id) },
+                    why: { type: 'string', enum: [...HAND_OFF_WHYS] },
+                    task: {
+                        type: 'string',
+                        description: 'The task, with every fact from the chat it needs.',
+                    },
+                },
+                required: ['tier', 'why', 'task'],
+            }),
+            execute: async (input, { abortSignal }) => {
+                const tier = reach.find((t) => t.id === input.tier);
+                const why = HAND_OFF_WHYS.find((w) => w === input.why);
+                const task = typeof input.task === 'string' ? input.task.trim() : '';
+                if (!tier || !why || !task)
+                    return {
+                        error: `Give {tier: ${reach.map((t) => `"${t.id}"`).join(' | ')}, why: ${HAND_OFF_WHYS.map((w) => `"${w}"`).join(' | ')}, task}.`,
+                    };
+                const asked = new Set(c.asked);
+                if (c.handTo)
+                    asked.add(c.handTo.id);
+                const own = c.policy === 'any' ? reach : c.policy === 'next' ? reach.slice(0, 1) : [];
+                const may = new Set([...own.map((t) => t.id), ...asked]);
+                if (!may.has(tier.id))
+                    return {
+                        error: may.size
+                            ? `Not ${tier.id} now: you may call ${[...may].join(' or ')}.`
+                            : 'The person has not asked for a higher tier: answer yourself.',
+                    };
+                if (tt.over())
+                    return { error: 'No money left for a higher tier this answer: answer yourself.' };
+                const sub = await this.session(c.caller, tier);
+                const key = c.keyOf(sub.model.provider);
+                const provider = PROVIDERS[sub.model.provider].label;
+                if (!key)
+                    return {
+                        error: `${tier.label} runs on ${provider} and no ${provider} key is set for whoever pays this answer: answer yourself.`,
+                    };
+                const meter = tt.meter(sub.model, sub.meter.label, !!key.plan);
+                c.counts.handoffs += 1;
+                if (this.tiers.indexOf(tier) > this.tiers.indexOf(c.counts.end))
+                    c.counts.end = tier;
+                const shown = asked.has(tier.id) ? 'asked' : why;
+                try {
+                    const r = await generateText({
+                        model: aiModel(sub.model, key, {
+                            ...(this.o.fetch ? { fetch: this.o.fetch } : {}),
+                            name: this.name,
+                        }),
+                        instructions: c.system(tt.opened),
+                        prompt: `${c.message}\n\n${this.name} handed you this task (${WHY_TEXT[shown]}): ${task}\n\nWork it out with the tools, then end with a memo for ${this.name} of at most 200 words: the answer and the facts it rests on. ${this.name} answers the person.`,
+                        tools: tt.opened.tools,
+                        stopWhen: stepCountIs(MAX_ROUNDS),
+                        prepareStep: () => (tt.over() ? { activeTools: [] } : undefined),
+                        onStepFinish: (s) => {
+                            meter.add(s.usage);
+                        },
+                        ...(abortSignal ? { abortSignal } : {}),
+                        ...turnSettings(sub.model, {
+                            effort: sub.effort,
+                            out: tier.out ?? DEFAULT_OUT,
+                            plan: !!key.plan,
+                        }),
+                    });
+                    return { memo: `Memo from ${sub.meter.label}:\n${r.text.slice(0, MEMO_CHARS)}` };
+                }
+                catch (err) {
+                    if (abortSignal?.aborted)
+                        throw err;
+                    return { error: `${sub.meter.label} failed: ${shownError(err).message}` };
+                }
+            },
+        });
+    }
     // ---------------------------------------------------------------- status and settings
     async status(caller) {
         const main = await this.mainTier(caller);
@@ -583,8 +813,8 @@ export class Assistant {
     }
     // ---------------------------------------------------------------- tools
     /** Opens the tools the person allows: each group's, then the web's. */
-    async openTools(caller, p) {
-        const opened = [];
+    /** The tool groups (and the web) at the person's access, not opened yet. */
+    async sourcesOf(caller, p) {
         const sources = [];
         for (const g of this.groups) {
             const access = this.access(p, g);
@@ -592,7 +822,7 @@ export class Assistant {
                 continue;
             const s = g.tools(caller);
             for (const source of Array.isArray(s) ? s : [s])
-                sources.push({ group: g.id, access, source });
+                sources.push({ group: g.id, access, source, ...(g.writes ? { writes: true } : {}) });
         }
         if (p.web ?? true) {
             if (this.o.web?.fetch !== false)
@@ -610,6 +840,11 @@ export class Assistant {
                     source: scrapeqlTools(sq.url, token, sq.fetch ?? this.o.fetch),
                 });
         }
+        return sources;
+    }
+    async openTools(caller, p) {
+        const opened = [];
+        const sources = await this.sourcesOf(caller, p);
         const results = await Promise.allSettled(sources.map((s) => s.source()));
         results.forEach((r, i) => {
             const s = sources[i];
@@ -796,7 +1031,7 @@ export class Assistant {
         let outcome = 'ok';
         try {
             const appSystem = typeof this.o.system === 'string' ? this.o.system : await this.o.system(caller);
-            const kitRules = this.rules(main, policy, advisor, tools.fns, tools.failed);
+            const kitRules = this.rules(main, policy, advisor, summarize(tools.fns), tools.failed);
             const system = [
                 { type: 'text', text: appSystem },
                 { type: 'text', text: kitRules, cache_control: { type: 'ephemeral' } },
@@ -805,7 +1040,7 @@ export class Assistant {
                 { type: 'text', text: appSystem },
                 {
                     type: 'text',
-                    text: this.rules(null, policy, null, tools.fns, tools.failed),
+                    text: this.rules(null, policy, null, summarize(tools.fns), tools.failed),
                     cache_control: { type: 'ephemeral' },
                 },
             ];
@@ -960,12 +1195,12 @@ 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)
+            ...(fns.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 (a like search has no count, only the nearest rows: never give a number of matches for it), 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)
+            ...(fns.reads && !fns.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.`,
                 ]
@@ -979,7 +1214,7 @@ export class Assistant {
             lines.push('No tools are on now: the person can turn them on in Settings ▸ Tools.');
         if (failed)
             lines.push(`${failed} tool source${failed === 1 ? '' : 's'} could not be reached this turn.`);
-        if ([...fns.values()].some((f) => f.group === 'web'))
+        if (fns.web)
             lines.push('Web: use web__fetch first for APIs and plain pages; the browser tools only for pages that need JavaScript or after a fetch fails.');
         if (main) {
             const reach = this.above(main.tier);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@columenlabs/lumen-ai",
-  "version": "0.1.177",
+  "version": "0.1.178",
   "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",
@@ -48,8 +48,8 @@
     "@ai-sdk/openai": "4.0.108",
     "@anthropic-ai/sdk": "0.133.0",
     "@cloudflare/think": "0.23.0",
-    "@columenlabs/lumen-ops": "0.1.177",
-    "@columenlabs/lumen-ui-types": "0.1.177",
+    "@columenlabs/lumen-ops": "0.1.178",
+    "@columenlabs/lumen-ui-types": "0.1.178",
     "agents": "0.32.0",
     "ai": "7.0.162",
     "just-bash": "3.6.0",