@columenlabs/lumen-ai 0.1.249 → 0.1.251

package/README.md

@@ -111,7 +111,7 @@ app.all('/api/assistant/*', (c) => routes(c.req.raw));
 - **Who pays.** The person's pick (the shared keys by default) while it has a key for the tier's provider and money left this month under its cap (an admin sets the shared keys' cap per person, `PUT /app`), else the other; with neither the panel says why.
 - **Tools.** Each group is Off, Read, Read + draft or Read + write per person. A tool is a read when its MCP `readOnlyHint` is set. On Read + draft a write only drafts a card, and runs as the person when they press Save, after access is checked again. A group with `readOnly: true` (read tools only) is offered Off or Read alone. Read + write is offered only for a group with `writes: true`: its writes run at once, and with `undo` set each one's line in the chat has Undo, which calls `undo(caller, { tool, args, result })`; the model is told what was undone. Cards drafted one after another show as one stack with Save all. Use `mcpServerTools` (an SDK `McpServer`), `mcpFetchTools` (a server served as a fetch handler, any SDK), `remoteMcpTools` or `plainTools`.
 - **Web.** `fetch` is a plain GET from the Worker (10 s, 2 MB, never the app's own hosts or private addresses). ScrapeQL's own tools join over its MCP API once an admin pastes a Cloudflare Access service token (`PUT /web/scrapeql`). A Worker on ScrapeQL's own Cloudflare account passes its service binding instead, `scrapeql: { url: 'https://scrapeql/mcp', fetch: env.SCRAPEQL.fetch.bind(env.SCRAPEQL) }`: no token is stored, the tools are always on and Settings shows the link with a Test. Each web step carries `web` (`StepWeb`: a search's `query` and `results`, or the page it `read`), so the panel folds a search's results under its line and numbers each page read under the answer as Sources chips; the model marks facts with those numbers ([1]).
-- **Hand off and advice.** The `escalate` tool hands one task to a higher tier (the person sets next, any or only when asked); Anthropic's advisor tool lets a higher tier send a plan, at most two an answer.
+- **Hand off and advice.** The `escalate` tool hands one task to a higher tier (the person sets next, any or only when asked); Anthropic's advisor tool lets a higher tier send a plan, at most two an answer. A hand-off gives up after `HAND_OFF_MS` (4 minutes) and the turn goes on without it.
 - **Chats** run on the agent (`./agent`, `LumenAgent`, below): the app routes `POST /chat` and each chat's reads, cards and Undo to its own agent, and `assistantRoutes` answers `POST /chat` with 410 `moved`. Chats saved by the old turn loop stay readable (`GET /chats`, `GET|DELETE /chats/:id`) until `assistant.purge()` drops them 30 days after their last message.
 - **Screen moves**: while the person's Settings ▸ Screen is Move (the default), the panel sends its page map (`AssistantMessage.screen`: routes, nav pages, Settings sections, cards on screen, rows to open) and `LumenAgent` gives the model a `screen` tool (`./agent` `screen.ts`). Each call's moves (go, settings, chart, open, point) are checked against the map, kept in the chat and streamed as a `screen` event; the panel runs them through `AssistantScreenProvider` (mounted by `LumenShell`) with an Undo chip, and their outcomes go back with the next message (`outcomes`). Nothing is saved by a move.
 - **Background work** an app runs for a person (a score, a summary) is `assistant.complete(caller, { task, system, prompt, images?, maxTokens })`: one answer on the task's tier (`tasks`, so the person picks its model in Settings ▸ Models), no chat and no tools (`images`, base64 with their media type, are read with the prompt: a scanned page, a screenshot), billed to their payer and counted in their spend and allowance like a chat turn. `maxTokens` (default 1,000) goes up to `COMPLETE_MAX_TOKENS` (32,000, thinking included); the answer is streamed, so a long one keeps its connection, and `cut: true` says it stopped at the cap before it ended (the app can ask again, shorter, or continue). It throws `AssistantError` `not_connected`, `app_cap` or `own_cap` when nobody can pay, so the caller waits and tries later. It returns the answer's `usd`, `model`, `usage` (tokens in, cache reads, out, per model) and `payer` (`app` or `own`: who paid, so the app can show a cost on the person's own key as money and the rest as credits). `effort` sets how hard the model thinks on that one call (`low` to `max`; on an OpenAI or xAI model it is the request's reasoning effort), over what the person saved for the tier. `run: { id, title }` makes the calls that share an `id` one line of the person's usage history (every round of one rebuild); without it a task's calls that day share a line. The month's spend also adds up per task and model (`spend:YYYY-MM` `tasks`: answers, calls, tokens, cost and time, a chat answer as `chat`), so an app's admin page can show what each kind of work costs; `tag` counts one call under another name when a task does more than one kind of work (a first try, a repair).
@@ -233,7 +233,7 @@ 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 |
+| `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, every call streamed (a call that is not streamed, such as a hand-off or a compaction, gets back the one response it asked for) |
 | `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 |

package/dist/agent/models.d.ts

@@ -17,9 +17,11 @@ export interface AiModelOptions {
  * forced call is the one tool offered with any call required (developers.openai.com/siwc, Preview
  * 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.
+ * AI SDK's request without these came back 400 Bad Request on a plan, 2026-11-04). A plan also
+ * answers only streamed requests ("Stream must be set to true", 400): a call that is not streamed
+ * (`generateText`: a hand-off, a compaction) is sent streamed and its events are put back together
+ * into the one response it asked for. 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. */

package/dist/agent/models.js

@@ -5,15 +5,18 @@
  */
 import { createAnthropic } from '@ai-sdk/anthropic';
 import { createOpenAI } from '@ai-sdk/openai';
+import { Stream } from 'openai/core/streaming';
 import { XAI_BASE_URL } from '../assistant/models.js';
 /**
  * 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). 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.
+ * AI SDK's request without these came back 400 Bad Request on a plan, 2026-11-04). A plan also
+ * answers only streamed requests ("Stream must be set to true", 400): a call that is not streamed
+ * (`generateText`: a hand-off, a compaction) is sent streamed and its events are put back together
+ * into the one response it asked for. 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) => {
@@ -57,6 +60,8 @@ export function planFetch(base = fetch, name = 'Assistant') {
                 ...rest,
                 { type: 'namespace', name: 'app', description: `${name}'s tools`, tools: fns },
             ];
+        const streamed = body.stream === true;
+        body.stream = true;
         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)
@@ -65,9 +70,54 @@ export function planFetch(base = fetch, name = 'Assistant') {
                 status: res.status,
                 body: (await res.clone().text()).slice(0, 500),
             }));
-        return res;
+        return res.ok && !streamed ? whole(res, init?.signal) : res;
     };
 }
+/**
+ * A streamed Responses answer as the one JSON response a request that was not streamed expects:
+ * the final `response.completed` (or `response.incomplete`), with the items from each
+ * `response.output_item.done` when the final event leaves its output empty. A failed answer comes
+ * back as an error response with OpenAI's own error, so the caller fails as it would have.
+ */
+async function whole(res, signal) {
+    const controller = new AbortController();
+    if (signal) {
+        if (signal.aborted)
+            controller.abort(signal.reason);
+        else
+            signal.addEventListener('abort', () => controller.abort(signal.reason), { once: true });
+    }
+    const failed = (error) => new Response(JSON.stringify({ error: error ?? { message: 'The answer failed.' } }), {
+        status: 500,
+        headers: { 'content-type': 'application/json' },
+    });
+    const items = [];
+    let done;
+    try {
+        const events = Stream.fromSSEResponse(res, controller);
+        for await (const e of events) {
+            if (e.type === 'response.output_item.done' && e.item)
+                items.push(e.item);
+            else if (e.type === 'response.completed' || e.type === 'response.incomplete')
+                done = e.response;
+            else if (e.type === 'response.failed')
+                return failed(e.response?.error);
+        }
+    }
+    catch (err) {
+        if (signal?.aborted)
+            throw err;
+        const e = err;
+        return failed(e.error ?? { message: e.message ?? String(err) });
+    }
+    if (!done)
+        return failed({ message: 'The answer ended before it was complete.' });
+    const output = Array.isArray(done.output) && done.output.length ? done.output : items;
+    return new Response(JSON.stringify({ ...done, output }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+    });
+}
 /** A message's text, whether a string or a list of text parts. */
 function textOf(content) {
     if (typeof content === 'string')

package/dist/assistant/engine.d.ts

@@ -227,6 +227,11 @@ export declare class AssistantError extends Error {
     readonly status: number;
     constructor(message: string, code: string, status?: number);
 }
+/**
+ * The most a hand-off may take. A chat turn waits for it with no stream of its own, so an app that
+ * times out a silent turn (Think's `chatStreamStallTimeoutMs`) sets that above this.
+ */
+export declare const HAND_OFF_MS = 240000;
 /** What a Think turn calls this turn: what one turn asks besides the message itself. */
 export interface AgentTurnInput {
     message: string;

package/dist/assistant/engine.js

@@ -15,7 +15,7 @@ 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, XAI_BASE_URL, effortParams, } from './models.js';
-import { DEFAULT_CAP, State, keyDocName, keyState, ownKeyUsd, planDocName, waitText, withProvider, } from './state.js';
+import { DEFAULT_CAP, State, keyDocName, keyState, ownKeyUsd, ownPlanCalls, planDocName, waitText, withProvider, } from './state.js';
 import { Docs } from './store.js';
 import { toolName, withDeadline } from './tools.js';
 import { scrapeqlTools, webFetchTools } from './web.js';
@@ -44,6 +44,11 @@ export class AssistantError extends Error {
 }
 const MAX_ROUNDS = 8;
 const MEMO_CHARS = 8000;
+/**
+ * The most a hand-off may take. A chat turn waits for it with no stream of its own, so an app that
+ * times out a silent turn (Think's `chatStreamStallTimeoutMs`) sets that above this.
+ */
+export const HAND_OFF_MS = 240_000;
 /** The built-in tool that runs several reads at once, as one step. */
 const BATCH = 'batch';
 const ADVICE_MAX = 2;
@@ -403,6 +408,7 @@ export class Assistant {
                     kind: 'chat',
                     title: message.split('\n')[0] || 'Chat',
                     own_usd: ownKeyUsd(paying, onPayer),
+                    own_plan_calls: ownPlanCalls(paying, onPayer),
                 }, end.parts)
                     .catch(() => undefined);
             const total = end.parts.reduce((a, m) => ({
@@ -526,7 +532,9 @@ export class Assistant {
                         onStepFinish: (s) => {
                             meter.add(s.usage);
                         },
-                        ...(abortSignal ? { abortSignal } : {}),
+                        abortSignal: abortSignal
+                            ? AbortSignal.any([abortSignal, AbortSignal.timeout(HAND_OFF_MS)])
+                            : AbortSignal.timeout(HAND_OFF_MS),
                         ...turnSettings(sub.model, {
                             effort: sub.effort,
                             out: tier.out ?? DEFAULT_OUT,
@@ -1069,6 +1077,7 @@ export class Assistant {
                 task: o.task,
                 title: o.run?.title ?? task?.label ?? o.task,
                 own_usd: ownKeyUsd(paying, [part]),
+                own_plan_calls: ownPlanCalls(paying, [part]),
             }, [part])
                 .catch(() => undefined);
         }
@@ -1157,6 +1166,7 @@ export class Assistant {
                 task: o.task,
                 title: o.run?.title ?? task?.label ?? o.task,
                 own_usd: ownKeyUsd(paying, [part]),
+                own_plan_calls: ownPlanCalls(paying, [part]),
             }, [part])
                 .catch(() => undefined);
         }

package/dist/assistant/state.d.ts

@@ -111,6 +111,11 @@ export declare function ownKeyUsd(paying: {
     payer: AssistantPayer;
     plans: Paying['plans'];
 }, parts: UsagePart[]): number;
+/** Calls in `parts` a plan sign-in of the person's answered (their own payer, a plan provider). */
+export declare function ownPlanCalls(paying: {
+    payer: AssistantPayer;
+    plans: Paying['plans'];
+}, parts: UsagePart[]): number;
 /**
  * What counts toward the person's own cap: own rows paid by an API key (a plan sign-in costs
  * nothing per call), on a provider they can still pay with. A row from before ways were recorded
@@ -276,7 +281,8 @@ export declare class State {
     /**
      * Adds one answer's use to a chat or run in this month's history (`usage:YYYY-MM`): one entry a
      * chat or run, its parts merged, the newest `USAGE_KEPT` kept. `title` names a new entry only;
-     * `own_usd` is what of this answer the person's own key or plan paid, added to the entry's.
+     * `own_usd` is what of this answer the person's own key or plan paid, added to the entry's;
+     * `own_plan_calls` the calls their plan sign-in answered (free to them, so counted, not priced).
      */
     addUsage(id: string, e: {
         id: string;
@@ -284,6 +290,7 @@ export declare class State {
         task?: string;
         title: string;
         own_usd?: number;
+        own_plan_calls?: number;
     }, parts: UsagePart[]): Promise<void>;
     /** One month's history (this month by default) beside its spend, and the months that have one. */
     usage(id: string, month?: string): Promise<UsageHistory>;

package/dist/assistant/state.js

@@ -32,6 +32,17 @@ export function ownKeyUsd(paying, parts) {
     })
         .reduce((a, p) => a + p.usd, 0);
 }
+/** Calls in `parts` a plan sign-in of the person's answered (their own payer, a plan provider). */
+export function ownPlanCalls(paying, parts) {
+    if (paying.payer !== 'own')
+        return 0;
+    return parts
+        .filter((p) => {
+        const prov = providerOfPart(p);
+        return !!(prov && paying.plans[prov]);
+    })
+        .reduce((a, p) => a + p.calls, 0);
+}
 /**
  * What counts toward the person's own cap: own rows paid by an API key (a plan sign-in costs
  * nothing per call), on a provider they can still pay with. A row from before ways were recorded
@@ -352,7 +363,8 @@ export class State {
     /**
      * Adds one answer's use to a chat or run in this month's history (`usage:YYYY-MM`): one entry a
      * chat or run, its parts merged, the newest `USAGE_KEPT` kept. `title` names a new entry only;
-     * `own_usd` is what of this answer the person's own key or plan paid, added to the entry's.
+     * `own_usd` is what of this answer the person's own key or plan paid, added to the entry's;
+     * `own_plan_calls` the calls their plan sign-in answered (free to them, so counted, not priced).
      */
     async addUsage(id, e, parts) {
         if (!parts.some((p) => p.calls))
@@ -365,6 +377,7 @@ export class State {
             const merged = mergeParts(prev?.parts ?? [], parts);
             const sum = (k) => merged.reduce((a, p) => a + p[k], 0);
             const own = (prev?.own_usd ?? 0) + (e.own_usd ?? 0);
+            const plan = (prev?.own_plan_calls ?? 0) + (e.own_plan_calls ?? 0);
             entries.unshift({
                 id: e.id,
                 kind: e.kind,
@@ -378,6 +391,7 @@ export class State {
                 out: sum('out'),
                 usd: sum('usd'),
                 ...(own > 0 ? { own_usd: own } : {}),
+                ...(plan > 0 ? { own_plan_calls: plan } : {}),
                 parts: merged,
             });
             return { entries: entries.slice(0, USAGE_KEPT) };

package/package.json

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