@columenlabs/lumen-ai 0.1.246 → 0.1.248

package/README.md

@@ -106,7 +106,7 @@ app.all('/api/assistant/*', (c) => routes(c.req.raw));
 ```
 
 - **Providers.** A tier runs any model in `models` (Claude's and OpenAI's by default, `CLAUDE_MODELS`, `OPENAI_MODELS`): Claude through Anthropic's Messages API, OpenAI through the Responses API, with the same tools, drafts, Stop and caps. xAI's Grok models (`XAI_MODELS`) are opt in: an app that lists them gets an xAI row in Model providers (an API key, `xai-…`); they run on the same Responses client at `XAI_BASE_URL` (`https://api.x.ai/v1`). xAI has no public sign-in for other apps, so Grok takes a key only. A hand-off may cross providers. The advisor and prompt caching marks are Claude's only.
-- **Keys.** Each provider has its own keys (`?provider=anthropic|openai|xai` on the key routes). An admin pastes the shared key everyone uses (`PUT /key`); it is tested with one free call before it is kept, then sealed, and no route returns it. A person may add their own (`PUT /my-key`), with one monthly cap on their own keys (`PUT /my-key/cap`).
+- **Keys.** Each provider has its own keys (`?provider=anthropic|openai|xai` on the key routes). An admin pastes the shared key everyone uses (`PUT /key`); it is tested with one free call before it is kept, then sealed, and no route returns it. A person may add their own (`PUT /my-key`), with one monthly cap on their own keys (`PUT /my-key/cap`). The cap counts what their own API keys spent this month on providers they can still pay with; a plan sign-in (ChatGPT) costs them nothing per call, so its calls count $0 (each own spend row records its `way`). Status gives that count as `spend.own_used`.
 - **ChatGPT sign-in.** In place of their own OpenAI key a person may sign in with their ChatGPT plan (`POST /my-signin`, then `POST /my-signin/finish {url}`): the sign-in opens in a new tab and ends on `http://127.0.0.1:1455/auth/callback`, a page that does not load, whose address the person pastes back. The tokens are sealed as their own key and refreshed before they run out; answers on the plan count tokens and no dollars.
 - **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`.
@@ -253,6 +253,10 @@ Drafts and writes are cards in the chat's own storage (`lumen_cards` in the agen
 
 **The panel.** `LumenAssistant` reads a Think chat with no change. `ask(input, sink)` runs one answer and sends the panel's own events (`AssistantEvent`: the chat, the text, each tool line, cards, hand-off sections, advice, the use) to `sink`. The app's `POST /chat` returns `askResponse((sink) => chat.ask(input, sink), { signal, stop: () => chat.stop() })`, the same server-sent events `assistantRoutes` sends. `view()` gives a stored chat as the panel's items, and `usage()` gives the chat's use so far. A card's id is its tool call's, so the panel's Save, Dismiss and Undo go to `saveCard`, `dismissCard` and `undoCard`. The app keeps the list of chats, and each chat is its own agent, such as a facet of the person's store. `chunkEvents` and `itemsOf` are the mapping, for an app that streams some other way.
 
+**Tool lines.** Each tool call shows as a line with the tool's own `title` (an MCP tool's `title`, a plain tool's `title`), kept in the chat's storage so a chat read back words its lines the same; a tool with no title shows its name. An app that keeps its insides off the screen overrides `plainSteps()` to return `true`: every line reads its tool's title, else a word for what it did (Look something up, Make a change, Draft a change), with no tool id, row count or error text (a failed line says `didn't work`), and a hand-off section reads Take a closer look with no tier or task. The details go to the app's log instead: `stepFailed({ tool, error, ms })` hears each failed call with its whole error (override it to log it with the chat's ids), and `onStep` carries `error` and `caller` on a failed tool or hand-off. `stepTitleOf(name, kind)` gives a line's title for an app's own card answers.
+
+**A write in progress.** A tool line starts (`step_start`) as soon as the model starts the call, while it is still writing the arguments. For a Read + write tool it carries `write: true`, and `useAssistantChat` marks that running step `writing` until its result lands or the answer ends, so an app can show what the tool changes as being changed now (a pending edit is not ready to accept while the model rewrites it).
+
 **Steps.** One answer makes at most `plan.maxSteps` model calls (`MAX_STEPS`, 8). The last one runs with no tools and `LAST_STEP_NOTE`, so an answer always ends in words: what it found, and what is left when the task did not fit.
 
 **Steer and queue.** While an answer runs, the panel's box stays open: Enter steers the message into the answer (`steer(message)` on the agent; the app routes `POST /chats/:id/steer` `{ message }` to it and answers `{ steered }`), Alt+Enter queues it for after. A steer joins at the answer's next step, after the tool it is on, with `STEER_NOTE` before it for the model; the panel shows it there marked Steered (event `steered`), and `view()` keeps it in place (`SteerNote`, under the message the answer is to). A steer the answer ends before reading comes back as `unsteered` and goes first in the queue. `plan.steer: false` turns it off for a model; an app without the route (404) shows Queue only. Queued messages each go as their own message when the answer before them ends; each has Steer now, Edit and Remove.

package/dist/agent/agent.d.ts

@@ -191,6 +191,23 @@ export declare abstract class LumenAgent<Env = unknown> extends Think<Env> {
      * `stay`. Off (`false`) unless the app overrides it; a throw counts as `false`.
      */
     protected offerFresh(_input: AskInput): Promise<boolean>;
+    /**
+     * Whether the chat's tool lines keep inner names off the screen: each reads its tool's title
+     * (or a word for what it did), with no tool id, tier, model, row count or error text. Off
+     * (`false`) unless the app overrides it; the app logs the details from `onStep`.
+     */
+    protected plainSteps(): boolean;
+    /**
+     * A tool call this answer failed: its name and whole error (a plain line shows neither). Does
+     * nothing unless the app overrides it, e.g. to log it with the chat's ids.
+     */
+    protected stepFailed(_f: {
+        tool: string;
+        error: string;
+        ms: number;
+    }): void;
+    /** A tool line's title as this chat words it (`plainSteps`), for an app's own card answers. */
+    protected stepTitleOf(name: string, kind?: 'read' | 'draft' | 'write'): string;
     /** The chat's running use: every answer's parts added up, and the last context size. */
     usage(): ChatUsage;
     /** The chat as the panel reads it: title, last message, items and use. */

package/dist/agent/agent.js

@@ -20,7 +20,7 @@ import { CONNECTOR_GROUP, checkConnectorUrl, connectorGroup, connectorId, connec
 import { aiModel, cachedTurn, planFallback, turnSettings } from './models.js';
 import { screenMapOf, screenNews, screenOutcomesOf, screenRules, screenTool, } from './screen.js';
 import { LAZY_AT, TOOL_SEARCH, lazyTools, usedTools } from './search.js';
-import { chunkEvents, itemsOf } from './stream.js';
+import { chunkEvents, itemsOf, shownTitle, } from './stream.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.';
@@ -193,6 +193,43 @@ export class LumenAgent extends Think {
     async offerFresh(_input) {
         return false;
     }
+    /**
+     * Whether the chat's tool lines keep inner names off the screen: each reads its tool's title
+     * (or a word for what it did), with no tool id, tier, model, row count or error text. Off
+     * (`false`) unless the app overrides it; the app logs the details from `onStep`.
+     */
+    plainSteps() {
+        return false;
+    }
+    /** How this chat words its tool lines: plain or not, with the titles of every tool it offered. */
+    #names() {
+        return {
+            plain: this.plainSteps(),
+            titleOf: (n) => this.#turn?.tools.info.find((i) => i.name === n)?.title ??
+                this.#get('titles')?.[n],
+        };
+    }
+    /**
+     * A tool call this answer failed: its name and whole error (a plain line shows neither). Does
+     * nothing unless the app overrides it, e.g. to log it with the chat's ids.
+     */
+    stepFailed(_f) { }
+    /** A tool line's title as this chat words it (`plainSteps`), for an app's own card answers. */
+    stepTitleOf(name, kind) {
+        return shownTitle(name, this.#names(), kind);
+    }
+    /** Keeps the titles of a turn's tools, so a chat read back words its lines the same. */
+    #keepTitles(info) {
+        const titles = this.#get('titles') ?? {};
+        let changed = false;
+        for (const i of info)
+            if (i.title && titles[i.name] !== i.title) {
+                titles[i.name] = i.title.slice(0, 80);
+                changed = true;
+            }
+        if (changed)
+            this.#put('titles', titles);
+    }
     /** The chat's running use: every answer's parts added up, and the last context size. */
     usage() {
         return this.#get('usage') ?? chatUsage([]);
@@ -203,7 +240,7 @@ export class LumenAgent extends Think {
             id,
             title: this.#get('title') ?? '',
             at: this.#get('at') ?? 0,
-            items: itemsOf(await this.getMessages(), this.cards(), this.#screens(), this.#get('steers') ?? {}),
+            items: itemsOf(await this.getMessages(), this.cards(), this.#screens(), this.#get('steers') ?? {}, this.#names()),
             usage: this.usage(),
         };
     }
@@ -258,6 +295,8 @@ export class LumenAgent extends Think {
             cards: () => new Map(this.cards().map((c) => [c.id, c])),
             screens: () => this.#screens(),
             kindOf: (n) => this.#turn?.tools.info.find((i) => i.name === n)?.kind,
+            names: this.#names(),
+            failed: (f) => this.stepFailed(f),
         });
         const map = screenMapOf(input.screen);
         const userId = `u_${crypto.randomUUID().replaceAll('-', '').slice(0, 16)}`;
@@ -575,6 +614,7 @@ export class LumenAgent extends Think {
         if (advice)
             meters.push(advice);
         let system = typeof plan.system === 'string' ? plan.system : plan.system(opened);
+        this.#keepTitles(opened.info);
         this.#turn = {
             plan,
             system,

package/dist/agent/stream.d.ts

@@ -8,6 +8,22 @@ import type { AgentCard } from './agent.js';
 import type { ScreenCall } from './screen.js';
 /** A tool's name as a line's title: `notes__find_notes` → `find notes`. */
 export declare function stepTitle(name: string): string;
+/**
+ * How a chat's tool lines are worded. `plain` keeps every inner name off the screen: no tool ids,
+ * no tier or model, no row counts and no error text (the app logs those; see `StepRecord.error`).
+ * A line reads the tool's own `title` (`titleOf`), else a word for what it did.
+ */
+export interface StepNames {
+    plain?: boolean;
+    /** The tool's own title, when it has one. */
+    titleOf?: (name: string) => string | undefined;
+}
+/** What a plain line says when a call failed: the assistant reads the error and goes on. */
+export declare const PLAIN_FAILED = "didn't work";
+/** A plain hand-off's heading: a closer look, never the tier it went to. */
+export declare const PLAIN_HANDOFF = "Take a closer look";
+/** The line's title: the tool's own title, else its name (or, plain, a word for what it did). */
+export declare function shownTitle(name: string, names?: StepNames, kind?: 'read' | 'draft' | 'write'): string;
 /**
  * Turns UI message chunks into the panel's events, one chunk at a time. `cards` says how a draft
  * or write ended (a card's id is its tool call's). `advisor` names the advice part.
@@ -19,6 +35,14 @@ export declare function chunkEvents(o?: {
     screens?: () => Map<string, ScreenCall>;
     /** A tool's kind this turn: a draft shows as its card only, with no line before it. */
     kindOf?: (name: string) => 'read' | 'draft' | 'write' | undefined;
+    /** How the lines are worded. */
+    names?: StepNames;
+    /** A tool call failed: its name and whole error, before a plain line hides them (for logs). */
+    failed?: (f: {
+        tool: string;
+        error: string;
+        ms: number;
+    }) => void;
 }): (chunk: {
     type: string;
     [k: string]: unknown;
@@ -51,5 +75,5 @@ export interface SteerNote {
     text: string;
     at: number;
 }
-export declare function itemsOf(messages: StoredMessage[], cards: AgentCard[], screens?: Map<string, ScreenCall>, steers?: Record<string, SteerNote[]>): ChatItem[];
+export declare function itemsOf(messages: StoredMessage[], cards: AgentCard[], screens?: Map<string, ScreenCall>, steers?: Record<string, SteerNote[]>, names?: StepNames): ChatItem[];
 export {};

package/dist/agent/stream.js

@@ -5,6 +5,25 @@ export function stepTitle(name) {
     const own = name.includes('__') ? name.slice(name.indexOf('__') + 2) : name;
     return own.replace(/_/g, ' ');
 }
+/** What a plain line says when a call failed: the assistant reads the error and goes on. */
+export const PLAIN_FAILED = "didn't work";
+/** A plain hand-off's heading: a closer look, never the tier it went to. */
+export const PLAIN_HANDOFF = 'Take a closer look';
+/** The line's title: the tool's own title, else its name (or, plain, a word for what it did). */
+export function shownTitle(name, names = {}, kind) {
+    const own = names.titleOf?.(name);
+    if (own)
+        return own;
+    if (!names.plain)
+        return stepTitle(name);
+    if (name === 'escalate')
+        return PLAIN_HANDOFF;
+    return kind === 'write'
+        ? 'Make a change'
+        : kind === 'draft'
+            ? 'Draft a change'
+            : 'Look something up';
+}
 const obj = (v) => v && typeof v === 'object' && !Array.isArray(v) ? v : null;
 /** A tool's `image` output as the panel's card: a same-site path or an https address only. */
 function stepImage(v) {
@@ -19,7 +38,7 @@ function stepImage(v) {
     };
 }
 /** What one finished tool call shows as: a line, a card, a hand-off section or nothing. */
-function settledCall(id, c, out, ms, cards, screens = new Map()) {
+function settledCall(id, c, out, ms, cards, screens = new Map(), names = {}) {
     const o = obj(out.output);
     if (c.name === 'screen') {
         // A call the page map refused goes back to the model only; the person sees the one that ran.
@@ -43,7 +62,7 @@ function settledCall(id, c, out, ms, cards, screens = new Map()) {
             kind: 'draft',
             id,
             tool: c.name,
-            title: stepTitle(c.name),
+            title: shownTitle(c.name, names, 'draft'),
             args: card?.args ?? c.input ?? null,
             status: card && card.status !== 'done' && card.status !== 'undone' ? card.status : 'open',
             ...(card?.result !== undefined ? { result: card.result } : {}),
@@ -53,11 +72,13 @@ function settledCall(id, c, out, ms, cards, screens = new Map()) {
     }
     const h = obj(o?.handoff);
     if (h && typeof h.tier === 'string' && typeof o?.memo === 'string') {
-        const task = String(obj(c.input)?.task ?? '');
+        // Plain: the tier and the task the model wrote for it stay off the screen.
+        const task = names.plain ? '' : String(obj(c.input)?.task ?? '');
+        const label = names.plain ? PLAIN_HANDOFF : h.label;
         return [
             {
                 event: 'handoff',
-                data: { kind: 'handoff', tier: h.tier, label: h.label, task, why: h.why },
+                data: { kind: 'handoff', tier: h.tier, label, task, why: h.why },
             },
             { event: 'handoff_done', data: { usage: h.usage } },
         ];
@@ -66,16 +87,17 @@ function settledCall(id, c, out, ms, cards, screens = new Map()) {
     const rows = rowCount(o && 'result' in o ? o.result : out.output);
     const image = stepImage(o?.image);
     const web = webStep(c.name, c.input, out.output, !!error || obj(out.output)?.ok === false);
+    const wrote = card?.kind === 'write' || (o && typeof o.change === 'string');
     const step = {
         kind: 'step',
         id,
         tool: c.name,
-        title: stepTitle(c.name),
+        title: shownTitle(c.name, names, wrote ? 'write' : 'read'),
         ok: !error,
         ms,
-        ...(rows !== undefined && !error ? { rows } : {}),
-        ...(error ? { error: error.slice(0, 300) } : {}),
-        ...(card?.kind === 'write' || (o && typeof o.change === 'string')
+        ...(rows !== undefined && !error && !names.plain ? { rows } : {}),
+        ...(error ? { error: names.plain ? PLAIN_FAILED : error.slice(0, 300) } : {}),
+        ...(wrote
             ? { write: { undo: true, status: card?.status === 'undone' ? 'undone' : 'done' } }
             : {}),
         ...(web ? { web } : {}),
@@ -88,6 +110,7 @@ function settledCall(id, c, out, ms, cards, screens = new Map()) {
  * or write ended (a card's id is its tool call's). `advisor` names the advice part.
  */
 export function chunkEvents(o = {}) {
+    const names = o.names ?? {};
     const calls = new Map();
     let advising = false;
     return (chunk) => {
@@ -108,7 +131,21 @@ export function chunkEvents(o = {}) {
                 }
                 if (name === 'escalate' || name === 'screen' || o.kindOf?.(name) === 'draft')
                     return [];
-                return [{ event: 'step_start', data: { id, tool: name, title: stepTitle(name) } }];
+                // A tool that makes a change at once says so as it starts, so an app can show that what it
+                // changes is being changed now, before the model has finished writing the call.
+                const kind = o.kindOf?.(name);
+                const write = kind === 'write';
+                return [
+                    {
+                        event: 'step_start',
+                        data: {
+                            id,
+                            tool: name,
+                            title: shownTitle(name, names, kind),
+                            ...(write ? { write } : {}),
+                        },
+                    },
+                ];
             }
             case 'tool-input-available': {
                 const c = calls.get(id) ?? { name: String(chunk.toolName ?? ''), t0: Date.now() };
@@ -126,7 +163,18 @@ export function chunkEvents(o = {}) {
                     advising = false;
                     return [{ event: 'advice_done', data: error ? { error } : {} }];
                 }
-                return settledCall(id, c, error !== undefined ? { error } : { output: chunk.output }, Date.now() - c.t0, o.cards?.() ?? new Map(), c.name === 'screen' ? (o.screens?.() ?? new Map()) : undefined);
+                const ms = Date.now() - c.t0;
+                const out = obj(chunk.output);
+                const said = error ?? (out && typeof out.error === 'string' ? out.error : undefined);
+                if (said !== undefined) {
+                    try {
+                        o.failed?.({ tool: c.name, error: said.slice(0, 2000), ms });
+                    }
+                    catch {
+                        // a log hook never breaks the answer
+                    }
+                }
+                return settledCall(id, c, error !== undefined ? { error } : { output: chunk.output }, ms, o.cards?.() ?? new Map(), c.name === 'screen' ? (o.screens?.() ?? new Map()) : undefined, names);
             }
             case 'error':
                 return [
@@ -144,7 +192,7 @@ export function chunkEvents(o = {}) {
         }
     };
 }
-export function itemsOf(messages, cards, screens = new Map(), steers = {}) {
+export function itemsOf(messages, cards, screens = new Map(), steers = {}, names = {}) {
     const byId = new Map(cards.map((c) => [c.id, c]));
     const items = [];
     let asked;
@@ -215,7 +263,7 @@ export function itemsOf(messages, cards, screens = new Map(), steers = {}) {
                     : null;
             if (!ended)
                 continue;
-            for (const e of settledCall(p.toolCallId, { name: tool, input: p.input, t0: 0 }, ended, 0, byId, screens)) {
+            for (const e of settledCall(p.toolCallId, { name: tool, input: p.input, t0: 0 }, ended, 0, byId, screens, names)) {
                 if (e.event === 'handoff')
                     items.push({ ...e.data, items: [] });
                 else if (e.event === 'handoff_done') {

package/dist/agent/tools.d.ts

@@ -35,6 +35,7 @@ export interface AiToolsOptions {
         tool: string;
         ok: boolean;
         ms: number;
+        error?: string;
     }) => void;
     /** A result handed to the model is cut past this many characters. */
     maxChars?: number;
@@ -45,6 +46,8 @@ export interface ToolInfo {
     group: string;
     kind: 'read' | 'draft' | 'write';
     find: boolean;
+    /** The tool's own title, in words a person reads ("Read the design guide"). */
+    title?: string;
 }
 /** Tools open for one answer, as the AI SDK's set, and how to let them go. */
 export interface OpenedTools {

package/dist/agent/tools.js

@@ -37,7 +37,13 @@ export async function openAiTools(sources, o = {}) {
             const name = toolName(s.group, def.name);
             if (kind === 'read')
                 reads.push(name);
-            info.push({ name, group: s.group, kind, find: !!def.find });
+            info.push({
+                name,
+                group: s.group,
+                kind,
+                find: !!def.find,
+                ...(def.title ? { title: def.title } : {}),
+            });
             tools[name] = tool({
                 description: describe(def, kind),
                 inputSchema: jsonSchema(withoutMeta(def.inputSchema)),
@@ -65,8 +71,9 @@ export async function openAiTools(sources, o = {}) {
                         return shown;
                     }
                     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) };
+                        const error = String(err?.message ?? err).slice(0, 500);
+                        o.called?.({ group: s.group, tool: def.name, ok: false, ms: Date.now() - t0, error });
+                        return { error };
                     }
                 },
             });

package/dist/assistant/engine.d.ts

@@ -111,6 +111,8 @@ export type StepRecord = {
     ms: number;
     rows?: number;
     error?: string;
+    /** The person the answer was for (their id), so a log line links to them. */
+    caller?: string;
     tier: string;
     handoff: boolean;
 } | {

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, planDocName, waitText, } from './state.js';
+import { DEFAULT_CAP, State, keyDocName, keyState, ownKeyUsd, planDocName, waitText, withProvider, } from './state.js';
 import { Docs } from './store.js';
 import { toolName, withDeadline } from './tools.js';
 import { scrapeqlTools, webFetchTools } from './web.js';
@@ -363,6 +363,8 @@ export class Assistant {
                     tool: toolName(c.group, c.tool),
                     ok: c.ok,
                     ms: c.ms,
+                    ...(c.error ? { error: c.error } : {}),
+                    caller: caller.id,
                     tier: main.tier.id,
                     handoff: false,
                 })).catch(() => undefined),
@@ -388,7 +390,7 @@ export class Assistant {
             const onShared = sharedLabel ? end.parts.filter((x) => x.label === sharedLabel) : [];
             const onPayer = onShared.length ? end.parts.filter((x) => !onShared.includes(x)) : end.parts;
             await this.state
-                .addSpend(caller.id, paying.payer, onPayer, { task: 'chat', ms: end.ms }, free)
+                .addSpend(caller.id, paying.payer, onPayer, { task: 'chat', ms: end.ms }, free, paying.plans)
                 .catch(() => undefined);
             if (onShared.length)
                 await this.state
@@ -400,7 +402,7 @@ export class Assistant {
                     id: `chat:${input.chat}`,
                     kind: 'chat',
                     title: message.split('\n')[0] || 'Chat',
-                    own_usd: paying.payer === 'own' ? onPayer.reduce((a, x) => a + x.usd, 0) : 0,
+                    own_usd: ownKeyUsd(paying, onPayer),
                 }, end.parts)
                     .catch(() => undefined);
             const total = end.parts.reduce((a, m) => ({
@@ -509,6 +511,7 @@ export class Assistant {
                 if (this.tiers.indexOf(tier) > this.tiers.indexOf(c.counts.end))
                     c.counts.end = tier;
                 const shown = asked.has(tier.id) ? 'asked' : why;
+                const t0 = Date.now();
                 try {
                     const r = await generateText({
                         model: aiModel(sub.model, key, {
@@ -539,6 +542,17 @@ export class Assistant {
                 catch (err) {
                     if (abortSignal?.aborted)
                         throw err;
+                    // The whole error goes to the app's log; the chat line may show none of it (plain steps).
+                    await Promise.resolve(this.o.onStep?.({
+                        kind: 'tool',
+                        tool: 'escalate',
+                        ok: false,
+                        ms: Date.now() - t0,
+                        error: `${sub.meter.label}: ${String(err?.message ?? err).slice(0, 500)}`,
+                        caller: c.caller.id,
+                        tier: tier.id,
+                        handoff: true,
+                    })).catch(() => undefined);
                     return { error: `${sub.meter.label} failed: ${shownError(err).message}` };
                 }
             },
@@ -551,7 +565,7 @@ export class Assistant {
         // The binding's last test has no token doc to sit in; it is read beside the rest.
         const linkTest = this.o.web?.scrapeql?.fetch ? this.state.scrapeqlLink() : null;
         const ownWays = await this.ownWaysOf(caller);
-        const [p, providers, scrapeql, spend, appCap, ownCap, { paying, wait }] = await Promise.all([
+        const [p, providers, scrapeql, spend, appCap, ownCap, { paying, wait }, ownUsed] = await Promise.all([
             this.state.person(caller.id),
             Promise.all(this.providers.map(async (id) => {
                 const [doc, key, own, plan, use] = await Promise.all([
@@ -584,6 +598,7 @@ export class Assistant {
             this.state.appCap(),
             this.state.ownCap(caller.id),
             this.rulesFor(caller, main.id).then(({ rules }) => this.state.paying(caller.id, mainModel.provider, rules)),
+            this.state.ownUsed(caller.id, ownWays),
         ]);
         const link = await linkTest;
         const tiers = await Promise.all(this.tiers.map(async (t) => {
@@ -656,7 +671,8 @@ export class Assistant {
                 usd: spend.rows.reduce((a, r) => a + r.usd, 0),
                 cap: paying?.cap ?? null,
                 payer: paying?.payer ?? null,
-                rows: spend.rows,
+                rows: withProvider(spend.rows),
+                own_used: ownUsed,
             },
             ...(this.o.allowance ? { allowance: await this.allowanceState(caller) } : {}),
         };
@@ -1044,7 +1060,7 @@ export class Assistant {
         }
         finally {
             const part = s.meter.part();
-            await this.state.addSpend(caller.id, paying.payer, [part], { task: o.tag ?? o.task, ms: Date.now() - began }, free);
+            await this.state.addSpend(caller.id, paying.payer, [part], { task: o.tag ?? o.task, ms: Date.now() - began }, free, paying.plans);
             const task = this.tasks.find((t) => t.id === o.task);
             await this.state
                 .addUsage(caller.id, {
@@ -1052,7 +1068,7 @@ export class Assistant {
                 kind: 'task',
                 task: o.task,
                 title: o.run?.title ?? task?.label ?? o.task,
-                own_usd: paying.payer === 'own' ? part.usd : 0,
+                own_usd: ownKeyUsd(paying, [part]),
             }, [part])
                 .catch(() => undefined);
         }
@@ -1132,10 +1148,7 @@ export class Assistant {
                 usd,
                 model: m.id,
             };
-            await this.state.addSpend(caller.id, paying.payer, [part], {
-                task: o.task,
-                ms: Date.now() - began,
-            });
+            await this.state.addSpend(caller.id, paying.payer, [part], { task: o.task, ms: Date.now() - began }, false, paying.plans);
             const task = this.tasks.find((t) => t.id === o.task);
             await this.state
                 .addUsage(caller.id, {
@@ -1143,7 +1156,7 @@ export class Assistant {
                 kind: 'task',
                 task: o.task,
                 title: o.run?.title ?? task?.label ?? o.task,
-                own_usd: paying.payer === 'own' ? part.usd : 0,
+                own_usd: ownKeyUsd(paying, [part]),
             }, [part])
                 .catch(() => undefined);
         }

package/dist/assistant/state.d.ts

@@ -99,7 +99,24 @@ export interface RequestsDoc {
 export type SpendRow = UsagePart & {
     payer: AssistantPayer;
     free?: true;
+    /** Of an own row: paid by the person's API key or their plan sign-in (a plan costs them $0). */
+    way?: AssistantOwnWay;
 };
+/** The provider a part ran on: by its model id, else by the model's name at the end of its label. */
+export declare function providerOfPart(p: UsagePart): AssistantProvider | undefined;
+/** Spend rows with the provider each ran on, so a page can tell a removed key's spend apart. */
+export declare function withProvider<R extends UsagePart>(rows: R[]): R[];
+/** USD of `parts` the person's own API keys paid: a provider signed in with a plan costs $0. */
+export declare function ownKeyUsd(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
+ * counts unless its provider has no own way left (an old key since removed).
+ */
+export declare function ownCapUsed(rows: SpendRow[], usable: Partial<Record<AssistantProvider, unknown>>): number;
 /** The ways of their own a person may pay with, per provider; a provider left out has none. */
 export type OwnWays = Partial<Record<AssistantProvider, AssistantOwnWay[]>>;
 /** How `paying` may choose: the app's limits on a person's own keys, and one payer only. */
@@ -255,7 +272,7 @@ export declare class State {
     addSpend(id: string, payer: AssistantPayer, parts: UsagePart[], at?: {
         task: string;
         ms?: number;
-    }, free?: boolean): Promise<void>;
+    }, free?: boolean, plans?: Partial<Record<AssistantProvider, boolean>>): Promise<void>;
     /**
      * 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;
@@ -275,6 +292,8 @@ export declare class State {
         keys: Partial<Record<"anthropic" | "openai" | "xai", string>>;
         plans: Partial<Record<"anthropic" | "openai" | "xai", boolean>>;
     }>;
+    /** USD of this month's own spend that counts toward the person's own cap (`ownCapUsed`). */
+    ownUsed(id: string, ways?: OwnWays): Promise<number>;
     /** Who pays the person's next answer on `provider`'s model, or why nobody can. */
     paying(id: string, provider: AssistantProvider, rules?: PayingRules): Promise<{
         paying: Paying | null;

package/dist/assistant/state.js

@@ -1,5 +1,5 @@
 import { refreshChatgpt, staleChatgpt } from './chatgpt.js';
-import { PROVIDERS, keyHint } from './models.js';
+import { ALL_MODELS, PROVIDERS, XAI_MODELS, keyHint } from './models.js';
 import { APP_SCOPE } from './store.js';
 /** Where a provider's key is kept: `key` for Anthropic, `key:<provider>` for the rest. */
 export const keyDocName = (provider) => provider === 'anthropic' ? 'key' : `key:${provider}`;
@@ -7,6 +7,45 @@ export const keyDocName = (provider) => provider === 'anthropic' ? 'key' : `key:
 export const planDocName = (provider) => `plan:${provider}`;
 /** Requests kept for approvers: the newest this many. */
 const REQUESTS_KEPT = 300;
+const KNOWN_MODELS = [...ALL_MODELS, ...XAI_MODELS];
+/** The provider a part ran on: by its model id, else by the model's name at the end of its label. */
+export function providerOfPart(p) {
+    const m = KNOWN_MODELS.find((x) => x.id === p.model) ??
+        KNOWN_MODELS.find((x) => p.label === x.label || p.label.endsWith(` · ${x.label}`));
+    return m?.provider;
+}
+/** Spend rows with the provider each ran on, so a page can tell a removed key's spend apart. */
+export function withProvider(rows) {
+    return rows.map((r) => {
+        const provider = providerOfPart(r);
+        return provider ? { ...r, provider } : r;
+    });
+}
+/** USD of `parts` the person's own API keys paid: a provider signed in with a plan costs $0. */
+export function ownKeyUsd(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.usd, 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
+ * counts unless its provider has no own way left (an old key since removed).
+ */
+export function ownCapUsed(rows, usable) {
+    return rows
+        .filter((r) => r.payer === 'own' && !r.free && r.way !== 'plan')
+        .filter((r) => {
+        const prov = providerOfPart(r);
+        return !prov || !!usable[prov];
+    })
+        .reduce((a, r) => a + r.usd, 0);
+}
 /** Chats and runs kept in one month's usage history: the newest this many. */
 export const USAGE_KEPT = 300;
 /** Months of usage history offered (`usage:YYYY-MM` documents are listed this far back). */
@@ -241,9 +280,16 @@ export class State {
      * Adds an answer's use to this month's spend, by label and payer. `at` names the task the answer
      * was for and how long it took, so the month also adds up per task and model (`tasks`).
      */
-    async addSpend(id, payer, parts, at, free = false) {
+    async addSpend(id, payer, parts, at, free = false, plans) {
         if (!parts.some((p) => p.calls))
             return;
+        // Which own way paid each part: a plan sign-in or a key, by the part's provider.
+        const wayOf = (p) => {
+            if (payer !== 'own' || !plans)
+                return undefined;
+            const prov = providerOfPart(p);
+            return prov && plans[prov] ? 'plan' : 'key';
+        };
         await this.docs.update(id, `spend:${this.month()}`, (d) => {
             const rows = [...(d?.rows ?? [])];
             const tasks = [...(d?.tasks ?? [])];
@@ -277,7 +323,8 @@ export class State {
             for (const p of parts) {
                 if (!p.calls)
                     continue;
-                const i = rows.findIndex((r) => r.label === p.label && r.payer === payer && !!r.free === free);
+                const way = wayOf(p);
+                const i = rows.findIndex((r) => r.label === p.label && r.payer === payer && !!r.free === free && r.way === way);
                 const prev = i >= 0 ? rows[i] : undefined;
                 const row = prev
                     ? {
@@ -288,7 +335,7 @@ export class State {
                         out: prev.out + p.out,
                         usd: prev.usd + p.usd,
                     }
-                    : { ...p, payer, ...(free ? { free: true } : {}) };
+                    : { ...p, payer, ...(free ? { free: true } : {}), ...(way ? { way } : {}) };
                 if (i >= 0)
                     rows[i] = row;
                 else
@@ -348,7 +395,7 @@ export class State {
             month,
             months,
             usd: spend.rows.reduce((a, r) => a + r.usd, 0),
-            rows: spend.rows,
+            rows: withProvider(spend.rows),
             entries: doc?.entries ?? [],
         };
     }
@@ -369,6 +416,11 @@ export class State {
         });
         return { keys, plans };
     }
+    /** USD of this month's own spend that counts toward the person's own cap (`ownCapUsed`). */
+    async ownUsed(id, ways) {
+        const [{ keys }, spend] = await Promise.all([this.keysOf(id, 'own', ways), this.spend(id)]);
+        return ownCapUsed(spend.rows, keys);
+    }
     /** Who pays the person's next answer on `provider`'s model, or why nobody can. */
     async paying(id, provider, rules = {}) {
         const [person, appKeys, ownKeys, spend, ownCap] = await Promise.all([
@@ -399,7 +451,7 @@ export class State {
                     apiKey: own,
                     ...ownKeys,
                     cap: ownCap,
-                    left: ownCap - spent('own'),
+                    left: ownCap - ownCapUsed(spend.rows, ownKeys.keys),
                 }
                 : null,
         };

package/package.json

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