@columenlabs/lumen-ai 0.1.185 → 0.1.187

package/README.md

@@ -220,11 +220,12 @@ ctx.waitUntil(meaningStep({ def: notesFind, sql: d1Sql(env.DB), embed, index: en
 | `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 |
+| `planFallback(primary, fallback, onSwitch)` | A plan's model that hands the call, and the rest of the turn, to `fallback` when the plan reaches its usage limit (a 429 or a usage code, before any output) |
 | `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.
+A ChatGPT plan sign-in is free to the app (`priced` with `free`). When the plan is used up for now, a turn with `fallback` (`agentTurn` sets the app's first Claude on the same payer's Anthropic key) answers on Claude instead of ending in the limit's error, its use its own part. 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.
 

package/dist/agent/agent.d.ts

@@ -61,6 +61,15 @@ export interface AgentTurnPlan {
         maxUses: number;
         maxTokens: number;
     };
+    /**
+     * Who answers when the ChatGPT plan `key` signs in with reaches its usage limit: a Claude model
+     * on the payer's own key, for the rest of the turn. Its use is its own part (`label`).
+     */
+    fallback?: {
+        model: ModelDef;
+        key: ModelKey;
+        label: string;
+    };
     /** Dollars the payer has left; at or past it the model gets no more tools. */
     left?: number;
     /** Most model calls in one answer; 8. */

package/dist/agent/agent.js

@@ -16,7 +16,7 @@ import { Think, } from '@cloudflare/think';
 import { createCompactFunction } from 'agents/sessions';
 import { generateText } from 'ai';
 import { CONNECTOR_GROUP, checkConnectorUrl, connectorGroup, connectorId, connectorSource, } from './connectors.js';
-import { aiModel, turnSettings } from './models.js';
+import { aiModel, planFallback, turnSettings } from './models.js';
 import { LAZY_AT, TOOL_SEARCH, lazyTools } from './search.js';
 import { chunkEvents, itemsOf } from './stream.js';
 import { openAiTools, } from './tools.js';
@@ -348,12 +348,15 @@ export class LumenAgent extends Think {
         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);
+        let 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,
+            model: this.#model(plan, () => {
+                const fb = plan.fallback;
+                if (!fb)
+                    return;
+                meter = new UsageMeter(fb.model, `${fb.label} · compact`, false);
+                this.#owed.push(meter);
             }),
             prompt,
             ...turnSettings(plan.model, { effort: 'default', out: 4000, plan: !!plan.key.plan }),
@@ -361,6 +364,14 @@ export class LumenAgent extends Think {
         meter.add(r.usage);
         return r.text;
     }
+    /** The turn's model; on a ChatGPT plan with a fallback, Claude once the plan's limit is reached. */
+    #model(plan, onSwitch) {
+        const o = { ...(plan.fetch ? { fetch: plan.fetch } : {}), name: this.constructor.name };
+        const model = aiModel(plan.model, plan.key, o);
+        if (!plan.key.plan || !plan.fallback)
+            return model;
+        return planFallback(model, aiModel(plan.fallback.model, plan.fallback.key, o), onSwitch);
+    }
     /** Never read: `beforeTurn` gives every turn its own model. */
     getModel() {
         return '@cf/none';
@@ -442,10 +453,15 @@ export class LumenAgent extends Think {
             this.#turn.system = system;
             this.#turn.lazy = lazy;
         }
+        const turn = this.#turn;
         return {
-            model: aiModel(plan.model, plan.key, {
-                ...(plan.fetch ? { fetch: plan.fetch } : {}),
-                name: this.constructor.name,
+            model: this.#model(plan, () => {
+                const fb = plan.fallback;
+                if (!fb)
+                    return;
+                // Claude answers the rest of the turn on the payer's key: its use is its own part.
+                turn.main = new UsageMeter(fb.model, fb.label, false);
+                turn.meters.push(turn.main);
             }),
             instructions: system,
             messages: withLead(ctx.messages, `${this.#news()}${plan.lead ?? ''}`),

package/dist/agent/models.d.ts

@@ -15,8 +15,11 @@ export interface AiModelOptions {
 /**
  * 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.
+ * limitations). It also keeps nothing (`store: false`, so earlier reasoning rides along encrypted)
+ * and takes the system prompt as `instructions`, as the assistant's own OpenAI loop sends it (the
+ * AI SDK's request without these came back 400 Bad Request on a plan, 2026-11-04). 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. */
@@ -30,3 +33,12 @@ export declare function turnSettings(model: ModelDef, o: {
     maxOutputTokens?: number;
     providerOptions?: Record<string, Record<string, JSONValue>>;
 };
+/** A ChatGPT plan used up for now: a 429 or a usage code, thrown or sent before any output. */
+export declare function planLimited(err: unknown): boolean;
+/**
+ * `primary` until its ChatGPT plan reaches its usage limit, then `fallback` for that call and
+ * every later one on this model (the rest of the turn). The limit shows either as a thrown error
+ * or as an error part before any output; once output has started nothing is swapped. `onSwitch`
+ * runs once, at the swap.
+ */
+export declare function planFallback(primary: LanguageModel, fallback: LanguageModel, onSwitch: () => void): LanguageModel;

package/dist/agent/models.js

@@ -8,8 +8,11 @@ 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.
+ * limitations). It also keeps nothing (`store: false`, so earlier reasoning rides along encrypted)
+ * and takes the system prompt as `instructions`, as the assistant's own OpenAI loop sends it (the
+ * AI SDK's request without these came back 400 Bad Request on a plan, 2026-11-04). 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) => {
@@ -17,22 +20,66 @@ export function planFetch(base = fetch, name = 'Assistant') {
         if (!url.endsWith('/responses') || typeof init?.body !== 'string')
             return base(input, init);
         const { max_output_tokens: _cap, ...body } = JSON.parse(init.body);
+        body.store = false;
+        const include = Array.isArray(body.include) ? body.include : [];
+        if (!include.includes('reasoning.encrypted_content'))
+            body.include = [...include, 'reasoning.encrypted_content'];
+        // System and developer messages become the request's instructions.
+        const items = Array.isArray(body.input) ? body.input : [];
+        const lead = items.filter((m) => m.role === 'system' || m.role === 'developer');
+        if (lead.length) {
+            const said = lead.map((m) => textOf(m.content)).filter(Boolean);
+            if (typeof body.instructions === 'string' && body.instructions)
+                said.unshift(body.instructions);
+            body.instructions = said.join('\n\n');
+            body.input = items.filter((m) => !lead.includes(m));
+        }
         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);
+        // Each function as the assistant's own loop sends it: no `strict`, no JSON Schema dialect tag.
+        const fns = tools
+            .filter((t) => t.type === 'function')
+            .map(({ strict: _, ...t }) => {
+            const p = t.parameters;
+            if (!p || !('$schema' in p))
+                return t;
+            const { $schema: _s, ...parameters } = p;
+            return { ...t, parameters };
+        });
         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) });
+        const res = await base(input, { ...init, body: JSON.stringify(body) });
+        // A refusal is logged with OpenAI's own reason; the person sees a plain sentence.
+        if (!res.ok)
+            console.error(JSON.stringify({
+                event: 'assistant_plan_refused',
+                status: res.status,
+                body: (await res.clone().text()).slice(0, 500),
+            }));
+        return res;
     };
 }
+/** A message's text, whether a string or a list of text parts. */
+function textOf(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    return content
+        .map((p) => p && typeof p === 'object' && typeof p.text === 'string'
+        ? p.text
+        : '')
+        .filter(Boolean)
+        .join('\n');
+}
 /** 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')
@@ -43,9 +90,112 @@ export function aiModel(model, key, o = {}) {
 /** 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 } } };
+    // A plan keeps nothing, so earlier turns go back as items, not references to stored ones.
+    const openai = o.plan ? { store: false } : {};
+    if (o.effort !== 'default') {
+        if (model.provider === 'anthropic')
+            return { ...out, providerOptions: { anthropic: { effort: o.effort } } };
+        openai.reasoningEffort = o.effort;
+    }
+    return model.provider === 'openai' && Object.keys(openai).length
+        ? { ...out, providerOptions: { openai } }
+        : out;
+}
+/** A ChatGPT plan used up for now: a 429 or a usage code, thrown or sent before any output. */
+export function planLimited(err) {
+    const e = err;
+    if (!e)
+        return false;
+    if (e.statusCode === 429 || e.status === 429)
+        return true;
+    const text = `${e.code ?? ''} ${e.message ?? ''} ${e.responseBody ?? ''} ${typeof err === 'string' ? err : ''}`;
+    return /usage_limit|usage limit|usage_unavailable|insufficient_quota/i.test(text);
+}
+/** Parts that come before an answer starts; an error among them means nothing was said yet. */
+const PREAMBLE = new Set(['stream-start', 'response-metadata']);
+/**
+ * `primary` until its ChatGPT plan reaches its usage limit, then `fallback` for that call and
+ * every later one on this model (the rest of the turn). The limit shows either as a thrown error
+ * or as an error part before any output; once output has started nothing is swapped. `onSwitch`
+ * runs once, at the swap.
+ */
+export function planFallback(primary, fallback, onSwitch) {
+    const p = primary;
+    const f = fallback;
+    let on = p;
+    const swap = () => {
+        if (on === f)
+            return;
+        on = f;
+        onSwitch();
+    };
+    const model = {
+        specificationVersion: p.specificationVersion,
+        provider: p.provider,
+        modelId: p.modelId,
+        get supportedUrls() {
+            return on.supportedUrls;
+        },
+        async doGenerate(o) {
+            if (on === f)
+                return f.doGenerate(o);
+            try {
+                return await p.doGenerate(o);
+            }
+            catch (err) {
+                if (!planLimited(err))
+                    throw err;
+                swap();
+                return f.doGenerate(o);
+            }
+        },
+        async doStream(o) {
+            if (on === f)
+                return f.doStream(o);
+            let r;
+            try {
+                r = await p.doStream(o);
+            }
+            catch (err) {
+                if (!planLimited(err))
+                    throw err;
+                swap();
+                return f.doStream(o);
+            }
+            // Hold the preamble until the first real part shows whether the plan answered.
+            const reader = r.stream.getReader();
+            const held = [];
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                if (value.type === 'error' && planLimited(value.error)) {
+                    await reader.cancel().catch(() => undefined);
+                    swap();
+                    return f.doStream(o);
+                }
+                held.push(value);
+                if (!PREAMBLE.has(value.type))
+                    break;
+            }
+            const stream = new ReadableStream({
+                start(c) {
+                    for (const v of held)
+                        c.enqueue(v);
+                },
+                async pull(c) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        c.close();
+                    else
+                        c.enqueue(value);
+                },
+                cancel(reason) {
+                    return reader.cancel(reason);
+                },
+            });
+            return { ...r, stream };
+        },
+    };
+    return model;
 }

package/dist/assistant/engine.js

@@ -388,6 +388,13 @@ export class Assistant {
             return apiKey ? { apiKey, ...(paying.plans[provider] ? { plan: true } : {}) } : null;
         };
         const key = keyOf(main.model.provider) ?? { apiKey: paying.apiKey };
+        // A ChatGPT plan used up for now: the app's first Claude (its smallest) answers instead, on
+        // the same payer's Anthropic key, rather than the turn ending in the limit's error.
+        const claude = key.plan ? this.models.find((m) => m.provider === 'anthropic') : undefined;
+        const claudeKey = claude ? keyOf('anthropic') : null;
+        const fallback = claude && claudeKey
+            ? { model: claude, key: claudeKey, label: `${main.tier.label} · ${claude.label}` }
+            : undefined;
         const p = await this.state.person(caller.id);
         const policy = p.hand_off ?? 'next';
         const advisor = await this.advisorFor(caller, p.advice, main);
@@ -423,6 +430,7 @@ export class Assistant {
                 ? `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),
+            ...(fallback ? { fallback } : {}),
             left: paying.left,
             maxSteps: MAX_ROUNDS,
             ...(this.o.fetch ? { fetch: this.o.fetch } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@columenlabs/lumen-ai",
-  "version": "0.1.185",
+  "version": "0.1.187",
   "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.185",
-    "@columenlabs/lumen-ui-types": "0.1.185",
+    "@columenlabs/lumen-ops": "0.1.187",
+    "@columenlabs/lumen-ui-types": "0.1.187",
     "agents": "0.32.0",
     "ai": "7.0.162",
     "just-bash": "3.6.0",