@columenlabs/lumen-ai 0.1.175 → 0.1.177

package/README.md

@@ -210,3 +210,18 @@ 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.

package/dist/agent/agent.d.ts

@@ -0,0 +1,62 @@
+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
+ * 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); }
+ *   }
+ */
+import type { AssistantEffort, UsagePart } from '@columenlabs/lumen-ui-types/assistant';
+import type { ModelDef } from '../assistant/models.js';
+import { type ModelKey } from './models.js';
+import { type AiToolsOptions, type SourceAt } from './tools.js';
+/** 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. */
+    system: string;
+    /** The tool groups at the person's access. */
+    sources: SourceAt[];
+    /** 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';
+    parts: UsagePart[];
+    /** Tokens in the main model's last call: how full its context is. */
+    context?: number;
+    ms: number;
+    /** The spend cap stopped tool use in this answer. */
+    capped: boolean;
+}
+export declare abstract class LumenAgent<Env = unknown> extends Think<Env> {
+    #private;
+    /** The turn the app runs now, or null between turns. */
+    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,87 @@
+import { Think, } from '@cloudflare/think';
+import { aiModel, turnSettings } from './models.js';
+import { openAiTools } from './tools.js';
+import { UsageMeter } from './usage.js';
+const CAP_NOTE = 'The spend cap for this month is reached: answer now from what you have, in a sentence or two. You can call no more tools.';
+export 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 tools = await openAiTools(plan.sources, plan.tools ?? {});
+        const free = !!plan.key.plan;
+        this.#turn = {
+            plan,
+            tools,
+            meter: new UsageMeter(plan.model, plan.label, free),
+            capped: false,
+            t0: Date.now(),
+        };
+        return {
+            model: aiModel(plan.model, plan.key, {
+                ...(plan.fetch ? { fetch: plan.fetch } : {}),
+                name: this.constructor.name,
+            }),
+            instructions: plan.system,
+            tools: tools.tools,
+            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 || t.plan.left === undefined)
+            return undefined;
+        if (t.meter.part().usd < t.plan.left)
+            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}` };
+    }
+    onStepFinish(ctx) {
+        const t = this.#turn;
+        if (!t)
+            return;
+        const p = t.meter.add(ctx.usage);
+        t.context = p.in + p.out;
+    }
+    async onChatResponse(result) {
+        await this.#end(result.status === 'completed' ? 'ok' : result.status === 'aborted' ? 'stopped' : 'error');
+    }
+    onChatError(error) {
+        void this.#end('error');
+        return error;
+    }
+    async #end(outcome) {
+        const t = this.#turn;
+        if (!t)
+            return;
+        this.#turn = null;
+        await t.tools.close();
+        try {
+            await this.settle({
+                outcome,
+                parts: [t.meter.part()],
+                ...(t.context ? { context: t.context } : {}),
+                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 { 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, unknown>>;
+};

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,45 @@
+/**
+ * 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;
+}
+/** 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[];
+    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,67 @@
+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 = [];
+    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);
+            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,
+        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,29 @@
+/** 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';
+/**
+ * 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;
+    };
+    part(): UsagePart;
+}

package/dist/agent/usage.js

@@ -0,0 +1,42 @@
+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) {
+        const t = priced(this.model, tokenUsage(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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@columenlabs/lumen-ai",
-  "version": "0.1.175",
+  "version": "0.1.177",
   "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.175",
-    "@columenlabs/lumen-ui-types": "0.1.175",
+    "@cloudflare/think": "0.23.0",
+    "@columenlabs/lumen-ops": "0.1.177",
+    "@columenlabs/lumen-ui-types": "0.1.177",
+    "agents": "0.32.0",
+    "ai": "7.0.162",
+    "just-bash": "3.6.0",
     "openai": "7.32.0",
     "zod": "^4.3.6"
   },