@columenlabs/lumen-ai 0.1.176 → 0.1.178

package/README.md

@@ -210,3 +210,32 @@ ctx.waitUntil(meaningStep({ def: notesFind, sql: d1Sql(env.DB), embed, index: en
 - `meaningStep` embeds only the rows whose `changed` column moved past its bookmark (`mark`: get and put, kept by the app), at most 50 a step in one embedding call and one upsert, and takes rows the find hides (its `where`) out of the index. It resumes where it stopped and runs safely twice at once; `done` is false while rows are left.
 - A person's own rows get a `namespace` each (`vectorMeaning` and `meaningStep` take one), so one index serves one app.
 - When the index cannot answer in 3 s, `like` is left out, the rest of the find runs and the result says so.
+
+## An agent on Cloudflare Think
+
+`@columenlabs/lumen-ai/agent` runs one chat as a Cloudflare Think agent (`@cloudflare/think`, experimental) on the app's tiers, keys and tool groups. Think keeps the loop, the messages, streaming, resume and compaction; the kit adds the model on the payer's key, the tools at the person's access, the spend cap and the usage. It will replace `./assistant`'s own loop.
+
+| Export | What it does |
+|---|---|
+| `LumenAgent` | An abstract Think agent. The app answers `plan(turn)` (model, key, effort, instructions, tool sources, money left) and hears `settle(end)` (outcome, usage parts, context size, time) when the turn ends |
+| `aiModel(model, key, opts?)` | The AI SDK model for a tier on an API key, or on a ChatGPT plan sign-in (`key.plan`, through `planFetch`) |
+| `planFetch(fetch?, name?)` | Rewrites Responses calls to a plan sign-in's rules: tools in one namespace, no output cap, a forced call as the only tool |
+| `turnSettings(model, opts)` | Output cap and effort as the provider takes them |
+| `openAiTools(sources, opts)` | The app's tool groups as AI SDK tools: reads always, drafts and writes by access, results cut at 16k characters |
+| `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

@@ -0,0 +1,93 @@
+/**
+ * `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 { 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 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. */
+    model: ModelDef;
+    key: ModelKey;
+    effort?: AssistantEffort;
+    /** Output tokens per call; left out on a plan sign-in, which takes no cap. */
+    out?: number;
+    /** The usage part's label: `Tier · Model`. */
+    label: 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. */
+    maxSteps?: number;
+    /** Fetch for provider calls (a metered one). */
+    fetch?: typeof fetch;
+    tools?: Omit<AiToolsOptions, 'maxChars'>;
+}
+/** 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. 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;
+    onStepFinish(ctx: StepContext): void;
+    onChatResponse(result: ChatResponseResult): Promise<void>;
+    onChatError(error: unknown): unknown;
+}

package/dist/agent/agent.js

@@ -0,0 +1,166 @@
+/**
+ * `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';
+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. */
+    getModel() {
+        return '@cf/none';
+    }
+    async beforeTurn(ctx) {
+        await this.#close();
+        const plan = await this.plan(ctx);
+        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,
+            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: 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',
+                ...(plan.out ? { out: plan.out } : {}),
+                plan: free,
+            }),
+        };
+    }
+    beforeStep(ctx) {
+        const t = this.#turn;
+        if (!t)
+            return undefined;
+        // 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;
+        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');
+    }
+    onChatError(error) {
+        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)
+            return;
+        this.#turn = null;
+        await t.tools.close();
+        try {
+            await this.settle({
+                outcome,
+                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,
+            });
+        }
+        catch (err) {
+            console.error(JSON.stringify({ event: 'agent_settle_error', error: String(err).slice(0, 500) }));
+        }
+    }
+    async #close() {
+        const t = this.#turn;
+        this.#turn = null;
+        await t?.tools.close();
+    }
+}

package/dist/agent/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The assistant on Cloudflare Think: the kit's models, keys, tool groups and usage as AI SDK parts,
+ * and `LumenAgent`, a Think agent that runs one chat on them. The app keeps its tiers, tools and
+ * payer rules; Think keeps the loop, the messages, streaming, resume and compaction.
+ */
+export * from './agent.js';
+export * from './models.js';
+export * from './tools.js';
+export * from './usage.js';

package/dist/agent/index.js

@@ -0,0 +1,9 @@
+/**
+ * The assistant on Cloudflare Think: the kit's models, keys, tool groups and usage as AI SDK parts,
+ * and `LumenAgent`, a Think agent that runs one chat on them. The app keeps its tiers, tools and
+ * payer rules; Think keeps the loop, the messages, streaming, resume and compaction.
+ */
+export * from './agent.js';
+export * from './models.js';
+export * from './tools.js';
+export * from './usage.js';

package/dist/agent/models.d.ts

@@ -0,0 +1,32 @@
+import type { AssistantEffort } from '@columenlabs/lumen-ui-types/assistant';
+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 {
+    apiKey: string;
+    plan?: boolean;
+}
+export interface AiModelOptions {
+    /** The fetch provider calls go through (a Worker's own, a metered one). */
+    fetch?: typeof fetch;
+    /** What a plan sign-in's tool namespace is described as (the assistant's name). */
+    name?: string;
+}
+/**
+ * A ChatGPT plan sign-in takes function tools only inside one namespace and no output cap, and a
+ * forced call is the one tool offered with any call required (developers.openai.com/siwc, Preview
+ * limitations). This fetch rewrites each Responses request to those rules, so the AI SDK's OpenAI
+ * provider runs on a plan unchanged.
+ */
+export declare function planFetch(base?: typeof fetch, name?: string): typeof fetch;
+/** The AI SDK model a tier runs: its provider's client on the payer's key. */
+export declare function aiModel(model: ModelDef, key: ModelKey, o?: AiModelOptions): LanguageModel;
+/** A tier's effort and output cap as a turn's settings; nothing at the model's own default. */
+export declare function turnSettings(model: ModelDef, o: {
+    effort: AssistantEffort;
+    out?: number;
+    plan?: boolean;
+}): {
+    maxOutputTokens?: number;
+    providerOptions?: Record<string, Record<string, JSONValue>>;
+};

package/dist/agent/models.js

@@ -0,0 +1,51 @@
+/**
+ * The kit's models as AI SDK language models, so a Think agent (or any `streamText` call) runs on
+ * the same tiers, keys and sign-ins as the assistant: Claude on an API key, OpenAI on an API key or
+ * a person's ChatGPT plan sign-in.
+ */
+import { createAnthropic } from '@ai-sdk/anthropic';
+import { createOpenAI } from '@ai-sdk/openai';
+/**
+ * A ChatGPT plan sign-in takes function tools only inside one namespace and no output cap, and a
+ * forced call is the one tool offered with any call required (developers.openai.com/siwc, Preview
+ * limitations). This fetch rewrites each Responses request to those rules, so the AI SDK's OpenAI
+ * provider runs on a plan unchanged.
+ */
+export function planFetch(base = fetch, name = 'Assistant') {
+    return async (input, init) => {
+        const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+        if (!url.endsWith('/responses') || typeof init?.body !== 'string')
+            return base(input, init);
+        const { max_output_tokens: _cap, ...body } = JSON.parse(init.body);
+        let tools = body.tools ?? [];
+        const choice = body.tool_choice;
+        if (choice && typeof choice === 'object' && choice.type === 'function' && choice.name) {
+            tools = tools.filter((t) => t.name === choice.name);
+            body.tool_choice = 'required';
+        }
+        const fns = tools.filter((t) => t.type === 'function').map(({ strict: _, ...t }) => t);
+        const rest = tools.filter((t) => t.type !== 'function');
+        if (fns.length)
+            body.tools = [
+                ...rest,
+                { type: 'namespace', name: 'app', description: `${name}'s tools`, tools: fns },
+            ];
+        return base(input, { ...init, body: JSON.stringify(body) });
+    };
+}
+/** The AI SDK model a tier runs: its provider's client on the payer's key. */
+export function aiModel(model, key, o = {}) {
+    if (model.provider === 'anthropic')
+        return createAnthropic({ apiKey: key.apiKey, ...(o.fetch ? { fetch: o.fetch } : {}) })(model.id);
+    const f = key.plan ? planFetch(o.fetch, o.name) : o.fetch;
+    return createOpenAI({ apiKey: key.apiKey, ...(f ? { fetch: f } : {}) }).responses(model.id);
+}
+/** A tier's effort and output cap as a turn's settings; nothing at the model's own default. */
+export function turnSettings(model, o) {
+    const out = o.plan || !o.out ? {} : { maxOutputTokens: o.out };
+    if (o.effort === 'default')
+        return out;
+    return model.provider === 'anthropic'
+        ? { ...out, providerOptions: { anthropic: { effort: o.effort } } }
+        : { ...out, providerOptions: { openai: { reasoningEffort: o.effort } } };
+}

package/dist/agent/tools.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The kit's tool sources (MCP servers, plain functions) as an AI SDK tool set, with the person's
+ * access applied: Off leaves a group out, Read keeps its reads, Read + draft adds its writes as
+ * drafts (a card the person saves; nothing changes), Read + write runs writes at once.
+ */
+import type { AssistantAccess } from '@columenlabs/lumen-ui-types/assistant';
+import { type ToolSet } from 'ai';
+import { type ToolSource } from '../assistant/tools.js';
+/** A group's tools to open for one answer, at the person's access. */
+export interface SourceAt {
+    group: string;
+    access: AssistantAccess;
+    source: ToolSource;
+    /** The group runs writes at once on Read + write; else a write drafts. */
+    writes?: boolean;
+}
+/** A write the model asked for while its group drafts: the card's content. */
+export interface DraftCall {
+    group: string;
+    tool: string;
+    args: unknown;
+}
+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>;
+    /** Every call's outcome, for the app's meter: shapes only. */
+    called?: (c: {
+        group: string;
+        tool: string;
+        ok: boolean;
+        ms: number;
+    }) => void;
+    /** 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>;
+}
+/** Opens every source at once; one that fails is counted and left out. */
+export declare function openAiTools(sources: SourceAt[], o?: AiToolsOptions): Promise<OpenedTools>;

package/dist/agent/tools.js

@@ -0,0 +1,70 @@
+import { jsonSchema, tool } from 'ai';
+import { toolName } from '../assistant/tools.js';
+const withoutMeta = (schema) => {
+    const { $schema: _, ...rest } = schema;
+    return { type: 'object', ...rest };
+};
+function describe(def, kind) {
+    const lead = kind === 'draft'
+        ? "DRAFT ONLY: this call changes nothing. It puts a card on the person's screen that they Save or Dismiss. "
+        : kind === 'write'
+            ? 'WRITES AT ONCE: this call makes the change now; the person can undo it. '
+            : '';
+    return `${lead}${def.title ? `${def.title}. ` : ''}${def.description ?? ''}`.slice(0, 4000);
+}
+/** Opens every source at once; one that fails is counted and left out. */
+export async function openAiTools(sources, o = {}) {
+    const live = sources.filter((s) => s.access !== 'off');
+    const results = await Promise.allSettled(live.map((s) => s.source()));
+    const opened = [];
+    results.forEach((r, i) => {
+        const s = live[i];
+        if (r.status === 'fulfilled' && s)
+            opened.push({ s, open: r.value });
+    });
+    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';
+            if (!def.read && !canWrite)
+                continue;
+            const kind = def.read ? 'read' : s.access === 'write' && s.writes ? 'write' : 'draft';
+            if (kind === 'draft' && !o.draft)
+                continue;
+            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)),
+                execute: async (args) => {
+                    if (kind === 'draft')
+                        return o.draft?.({ group: s.group, tool: def.name, args });
+                    const t0 = Date.now();
+                    try {
+                        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;
+                    }
+                    catch (err) {
+                        o.called?.({ group: s.group, tool: def.name, ok: false, ms: Date.now() - t0 });
+                        return { error: String(err?.message ?? err).slice(0, 500) };
+                    }
+                },
+            });
+        }
+    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

@@ -0,0 +1,36 @@
+/** 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, 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).
+ * A field a provider leaves out counts as 0.
+ */
+export declare function tokenUsage(u: LanguageModelUsage): {
+    input_tokens: number;
+    output_tokens: number;
+    cache_creation_input_tokens: number;
+    cache_read_input_tokens: number;
+};
+/** A running part of an answer (a tier, its advice): calls, tokens and dollars. `free` on a plan. */
+export declare class UsageMeter {
+    readonly model: ModelDef;
+    private readonly free;
+    private p;
+    constructor(model: ModelDef, label: string, free?: boolean);
+    add(u: LanguageModelUsage): {
+        in: number;
+        out: number;
+        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

@@ -0,0 +1,46 @@
+import { priced } 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).
+ * A field a provider leaves out counts as 0.
+ */
+export function tokenUsage(u) {
+    const d = u.inputTokenDetails;
+    const read = d?.cacheReadTokens ?? 0;
+    const written = d?.cacheWriteTokens ?? 0;
+    const plain = d?.noCacheTokens ?? Math.max(0, (u.inputTokens ?? 0) - read - written);
+    return {
+        input_tokens: plain,
+        output_tokens: u.outputTokens ?? 0,
+        cache_creation_input_tokens: written,
+        cache_read_input_tokens: read,
+    };
+}
+/** A running part of an answer (a tier, its advice): calls, tokens and dollars. `free` on a plan. */
+export class UsageMeter {
+    model;
+    free;
+    p;
+    constructor(model, label, free = false) {
+        this.model = model;
+        this.free = free;
+        this.p = { label, calls: 0, in: 0, read: 0, out: 0, usd: 0 };
+    }
+    add(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;
+        this.p.out += t.out;
+        if (!this.free)
+            this.p.usd += t.usd;
+        return t;
+    }
+    part() {
+        return { ...this.p };
+    }
+}

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.176",
+  "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",
@@ -18,6 +18,10 @@
     "./assistant": {
       "types": "./dist/assistant/index.d.ts",
       "default": "./dist/assistant/index.js"
+    },
+    "./agent": {
+      "types": "./dist/agent/index.d.ts",
+      "default": "./dist/agent/index.js"
     }
   },
   "files": [
@@ -40,9 +44,15 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
+    "@ai-sdk/anthropic": "4.0.96",
+    "@ai-sdk/openai": "4.0.108",
     "@anthropic-ai/sdk": "0.133.0",
-    "@columenlabs/lumen-ops": "0.1.176",
-    "@columenlabs/lumen-ui-types": "0.1.176",
+    "@cloudflare/think": "0.23.0",
+    "@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",
     "openai": "7.32.0",
     "zod": "^4.3.6"
   },