@columenlabs/lumen-ai 0.1.177 → 0.1.179

package/README.md

@@ -225,3 +225,21 @@ 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 and writes are cards in the chat's own storage (`lumen_cards` in the agent's SQLite). A write the person's access only drafts makes an open card and changes nothing. `saveCard(id)` runs it through the app's `applyDraft`, and `dismissCard(id)` drops it. A write made at once is kept for `undoCard(id)` through the app's `undoWrite`. `cards()` lists the cards. The next answer is told how each card ended and what was undone. With an `Assistant`, `applyDraft` is `assistant.runDraft(caller, card)` and `undoWrite` is `assistant.undoChange(caller, card)`. Think compacts the chat past `COMPACT_AT` (150k tokens) on the last answer's model and key, and that spend is added to the next answer.
+
+```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(); }
+  protected applyDraft(card: AgentCard) { return assistant.runDraft(caller, card); }
+  protected undoWrite(card: AgentCard) { return assistant.undoChange(caller, card); }
+}
+```

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 Session, 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, type 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,60 @@ 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.";
+/** A card in the chat: a draft the person saves or dismisses, or a write made at once (Undo). */
+export interface AgentCard {
+    id: string;
+    kind: 'draft' | 'write';
+    group: string;
+    /** The tool's own name, not the `group__tool` the model calls. */
+    tool: string;
+    args: unknown;
+    result?: unknown;
+    status: 'open' | 'saved' | 'dismissed' | 'failed' | 'done' | 'undone';
+    error?: string;
+    at: number;
+}
+/** Past this many tokens in the chat Think summarizes its older part. */
+export declare const COMPACT_AT = 150000;
+/** What the model is told of cards settled and changes undone since its last answer. */
+export declare function cardNews(cards: AgentCard[]): string;
+/** 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>;
+    /** Saves a draft: runs its write as the person. The result is shown and told to the model. */
+    protected applyDraft(_card: AgentCard): Promise<unknown>;
+    /** Takes back a write made at once (Undo). */
+    protected undoWrite(_card: AgentCard): Promise<void>;
+    /** The chat's cards, newest last: drafts and writes made at once (at most 200). */
+    cards(): AgentCard[];
+    /** The person saved a draft: its write runs now. */
+    saveCard(id: string): Promise<AgentCard>;
+    /** The person dismissed a draft: nothing changes. */
+    dismissCard(id: string): AgentCard;
+    /** The person undid a write made at once. */
+    undoCard(id: string): Promise<AgentCard>;
+    /** Think compacts the chat past `COMPACT_AT` tokens, on the last turn's model and key. */
+    configureSession(session: Session): Session;
     /** 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,10 +1,183 @@
+/**
+ * `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 { createCompactFunction } from 'agents/sessions';
+import { generateText } from 'ai';
 import { aiModel, turnSettings } from './models.js';
-import { openAiTools } from './tools.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.';
+/** Past this many tokens in the chat Think summarizes its older part. */
+export const COMPACT_AT = 150_000;
+const CARD_NOTE = "A card is on the person's screen; nothing has changed yet. Say what it will do when they save it. The next message tells you how it ended.";
+/** What the model is told of cards settled and changes undone since its last answer. */
+export function cardNews(cards) {
+    const undone = cards.filter((c) => c.kind === 'write' && c.status === 'undone');
+    const ended = cards.filter((c) => c.kind === 'draft' && c.status !== 'open');
+    const line = (c) => `${c.group}/${c.tool} ${JSON.stringify(c.args ?? {}).slice(0, 300)}`;
+    const back = undone.length
+        ? `The person undid these changes you made: ${undone.map(line).join('; ')}. Do not make them again unless asked.\n\n`
+        : '';
+    if (!ended.length)
+        return back;
+    return `${back}Cards since your last answer:\n${ended
+        .map((c) => `- ${line(c)}: ${c.status}${c.error ? ` (${c.error})` : ''}${c.result !== undefined ? ` → ${JSON.stringify(c.result).slice(0, 300)}` : ''}`)
+        .join('\n')}\n\n`;
+}
+const cardOf = (r) => ({
+    id: r.id,
+    kind: r.kind,
+    group: r.grp,
+    tool: r.tool,
+    args: JSON.parse(r.args),
+    ...(r.result === null ? {} : { result: JSON.parse(r.result) }),
+    status: r.status,
+    ...(r.error ? { error: r.error } : {}),
+    at: r.at,
+});
+/** 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 {
+    /** Saves a draft: runs its write as the person. The result is shown and told to the model. */
+    applyDraft(_card) {
+        return Promise.reject(new Error('Saving a card is not set up here.'));
+    }
+    /** Takes back a write made at once (Undo). */
+    undoWrite(_card) {
+        return Promise.reject(new Error('This change cannot be undone here.'));
+    }
     #turn = null;
+    /** The last turn's model and key, for compaction between turns. */
+    #last = null;
+    /** Usage spent between turns (compaction), settled with the next turn. */
+    #owed = [];
+    #tabled = false;
+    #cards() {
+        if (!this.#tabled) {
+            this
+                .sql `CREATE TABLE IF NOT EXISTS lumen_cards (id TEXT PRIMARY KEY, kind TEXT NOT NULL, grp TEXT NOT NULL, tool TEXT NOT NULL, args TEXT NOT NULL, result TEXT, status TEXT NOT NULL, error TEXT, told INTEGER NOT NULL DEFAULT 0, at INTEGER NOT NULL)`;
+            this.#tabled = true;
+        }
+    }
+    #addCard(kind, d, result) {
+        this.#cards();
+        const id = `card_${crypto.randomUUID().replaceAll('-', '').slice(0, 16)}`;
+        this
+            .sql `INSERT INTO lumen_cards (id, kind, grp, tool, args, result, status, at) VALUES (${id}, ${kind}, ${d.group}, ${d.tool}, ${JSON.stringify(d.args ?? null)}, ${result === undefined ? null : JSON.stringify(result).slice(0, 20_000)}, ${kind === 'draft' ? 'open' : 'done'}, ${Date.now()})`;
+        return id;
+    }
+    #card(id) {
+        this.#cards();
+        const [r] = this.sql `SELECT * FROM lumen_cards WHERE id = ${id} LIMIT 1`;
+        return r ? cardOf(r) : null;
+    }
+    #setCard(id, status, o = {}) {
+        this
+            .sql `UPDATE lumen_cards SET status = ${status}, result = COALESCE(${o.result === undefined ? null : JSON.stringify(o.result).slice(0, 20_000)}, result), error = ${o.error ?? null}, told = 0 WHERE id = ${id}`;
+    }
+    /** The chat's cards, newest last: drafts and writes made at once (at most 200). */
+    cards() {
+        this.#cards();
+        return this.sql `SELECT * FROM lumen_cards ORDER BY at DESC LIMIT 200`
+            .map(cardOf)
+            .reverse();
+    }
+    /** The person saved a draft: its write runs now. */
+    async saveCard(id) {
+        const c = this.#card(id);
+        if (!c || c.kind !== 'draft')
+            throw new Error('That card is gone.');
+        if (c.status !== 'open')
+            throw new Error(`That card is already ${c.status}.`);
+        try {
+            this.#setCard(id, 'saved', { result: await this.applyDraft(c) });
+        }
+        catch (err) {
+            this.#setCard(id, 'failed', { error: String(err?.message ?? err).slice(0, 300) });
+        }
+        return this.#card(id);
+    }
+    /** The person dismissed a draft: nothing changes. */
+    dismissCard(id) {
+        const c = this.#card(id);
+        if (!c || c.kind !== 'draft')
+            throw new Error('That card is gone.');
+        if (c.status !== 'open')
+            throw new Error(`That card is already ${c.status}.`);
+        this.#setCard(id, 'dismissed');
+        return this.#card(id);
+    }
+    /** The person undid a write made at once. */
+    async undoCard(id) {
+        const c = this.#card(id);
+        if (!c || c.kind !== 'write')
+            throw new Error('That change is gone.');
+        if (c.status === 'undone')
+            throw new Error('That change is already undone.');
+        await this.undoWrite(c);
+        this.#setCard(id, 'undone');
+        return this.#card(id);
+    }
+    /** Cards settled since the model last heard, as its note; marks them told. */
+    #news() {
+        this.#cards();
+        const rows = this
+            .sql `SELECT * FROM lumen_cards WHERE told = 0 AND status IN ('saved', 'dismissed', 'failed', 'undone') ORDER BY at LIMIT 50`;
+        if (!rows.length)
+            return '';
+        for (const r of rows)
+            this.sql `UPDATE lumen_cards SET told = 1 WHERE id = ${r.id}`;
+        return cardNews(rows.map(cardOf));
+    }
+    /** Think compacts the chat past `COMPACT_AT` tokens, on the last turn's model and key. */
+    configureSession(session) {
+        return session
+            .onCompaction(createCompactFunction({ summarize: (prompt) => this.#summarize(prompt) }))
+            .compactAfter(COMPACT_AT);
+    }
+    async #summarize(prompt) {
+        const last = this.#last;
+        if (!last)
+            throw new Error('No model to compact with until the next answer.');
+        const { plan } = last;
+        const meter = new UsageMeter(plan.model, `${plan.label} · compact`, !!plan.key.plan);
+        this.#owed.push(meter);
+        const r = await generateText({
+            model: aiModel(plan.model, plan.key, {
+                ...(plan.fetch ? { fetch: plan.fetch } : {}),
+                name: this.constructor.name,
+            }),
+            prompt,
+            ...turnSettings(plan.model, { effort: 'default', out: 4000, plan: !!plan.key.plan }),
+        });
+        meter.add(r.usage);
+        return r.text;
+    }
     /** Never read: `beforeTurn` gives every turn its own model. */
     getModel() {
         return '@cf/none';
@@ -12,22 +185,58 @@ 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 ?? {});
+        this.#last = { plan };
+        const opened = await openAiTools(plan.sources, {
+            draft: async (d) => ({ card: this.#addCard('draft', d), note: CARD_NOTE }),
+            wrote: async (w) => this.#addCard('write', w, w.result),
+            ...plan.tools,
+        });
         const free = !!plan.key.plan;
+        const main = new UsageMeter(plan.model, plan.label, free);
+        const meters = [main, ...this.#owed];
+        this.#owed = [];
+        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, `${this.#news()}${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 +245,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 +285,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 +297,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

@@ -23,6 +23,10 @@ export interface DraftCall {
 export interface AiToolsOptions {
     /** A draft's card was made: return what the model is told (its id, "a card is on screen"). */
     draft?: (d: DraftCall) => Promise<unknown>;
+    /** A write ran at once: what it did, for Undo. Its answer is added to the model's result. */
+    wrote?: (w: DraftCall & {
+        result: unknown;
+    }) => Promise<unknown>;
     /** Every call's outcome, for the app's meter: shapes only. */
     called?: (c: {
         group: string;
@@ -33,11 +37,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)),
@@ -47,7 +49,13 @@ export async function openAiTools(sources, o = {}) {
                         const out = await open.call(def.name, args);
                         o.called?.({ group: s.group, tool: def.name, ok: true, ms: Date.now() - t0 });
                         const text = typeof out === 'string' ? out : JSON.stringify(out);
-                        return text.length > max ? `${text.slice(0, max)} …(cut)` : out;
+                        const shown = text.length > max ? `${text.slice(0, max)} …(cut)` : out;
+                        if (kind === 'write' && o.wrote) {
+                            const change = await o.wrote({ group: s.group, tool: def.name, args, result: out });
+                            if (change !== undefined)
+                                return { result: shown, change };
+                        }
+                        return shown;
                     }
                     catch (err) {
                         o.called?.({ group: s.group, tool: def.name, ok: false, ms: Date.now() - t0 });
@@ -59,6 +67,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,35 @@ 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>;
+    }>;
+    /**
+     * Saves a Think chat's draft card (`LumenAgent.applyDraft`): its group's write runs as the person,
+     * while that group is still on Read + draft or Read + write.
+     */
+    runDraft(caller: Caller, card: {
+        group: string;
+        tool: string;
+        args: unknown;
+    }): Promise<unknown>;
+    /** Takes back a Think chat's write made at once (`LumenAgent.undoWrite`) through its group's `undo`. */
+    undoChange(caller: Caller, card: {
+        group: string;
+        tool: string;
+        args: unknown;
+        result?: unknown;
+    }): 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 +264,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,245 @@ 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 };
+    }
+    /**
+     * Saves a Think chat's draft card (`LumenAgent.applyDraft`): its group's write runs as the person,
+     * while that group is still on Read + draft or Read + write.
+     */
+    async runDraft(caller, card) {
+        const g = this.groupById(card.group);
+        const p = await this.state.person(caller.id);
+        const access = g ? this.access(p, g) : 'off';
+        if (access !== 'draft' && access !== 'write')
+            throw new AssistantError('Its tools are no longer on Read + draft or Read + write in Settings ▸ Tools.', 'off', 409);
+        const sources = (await this.sourcesOf(caller, p)).filter((x) => x.group === card.group);
+        for (const x of sources) {
+            const open = await x.source();
+            try {
+                const def = open.tools.find((d) => d.name === card.tool);
+                if (!def)
+                    continue;
+                if (def.read)
+                    throw new AssistantError('That card is not a change.', 'not_write', 400);
+                return await withDeadline(card.tool, 60_000, open.call(card.tool, card.args));
+            }
+            finally {
+                await open.close().catch(() => undefined);
+            }
+        }
+        throw new AssistantError('That tool is gone.', 'not_found', 404);
+    }
+    /** Takes back a Think chat's write made at once (`LumenAgent.undoWrite`) through its group's `undo`. */
+    async undoChange(caller, card) {
+        const g = this.groupById(card.group);
+        if (!g?.undo)
+            throw new AssistantError('That change cannot be undone here.', 'no_undo', 400);
+        await withDeadline(`Undo ${card.tool}`, 60_000, g.undo(caller, { tool: card.tool, args: card.args, result: card.result }));
+    }
+    /** 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 +847,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 +856,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 +874,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 +1065,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 +1074,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 +1229,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 +1248,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.179",
   "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.179",
+    "@columenlabs/lumen-ui-types": "0.1.179",
     "agents": "0.32.0",
     "ai": "7.0.162",
     "just-bash": "3.6.0",