@columenlabs/lumen-ai 0.1.246 → 0.1.247

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,8 @@ 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.
 
+**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/stream.js

@@ -108,7 +108,15 @@ 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 write = o.kindOf?.(name) === 'write';
+                return [
+                    {
+                        event: 'step_start',
+                        data: { id, tool: name, title: stepTitle(name), ...(write ? { write } : {}) },
+                    },
+                ];
             }
             case 'tool-input-available': {
                 const c = calls.get(id) ?? { name: String(chunk.toolName ?? ''), t0: Date.now() };

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';
@@ -388,7 +388,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 +400,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) => ({
@@ -551,7 +551,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 +584,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 +657,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 +1046,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 +1054,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 +1134,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 +1142,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.247",
   "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.247",
+    "@columenlabs/lumen-ui-types": "0.1.247",
     "agents": "0.32.0",
     "ai": "7.0.162",
     "just-bash": "3.6.0",