@columenlabs/lumen-ai 0.1.209 → 0.1.210

package/README.md

@@ -103,7 +103,8 @@ app.all('/api/assistant/*', (c) => routes(c.req.raw));
 - **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.
 - **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.
+- **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` and `usage` (tokens in, cache reads, out, per model). `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.
+- **Usage history.** Each chat (`agentTurn` with `chat`) and each run of background work is one line of the person's month (`usage:YYYY-MM`, the newest 300): its title, first and last use, tokens, cost and its parts per tier and model. `GET /usage?month=YYYY-MM` returns it beside that month's spend and the months that have any; `LumenAssistant`'s footer shows this month's total and opens it (`UsageHistoryView`).
 
 ### Commands, `@` and `#`
 
@@ -243,7 +244,8 @@ class Chat extends LumenAgent<Env> {
   #settle?: (end: AgentTurnEnd) => Promise<void>;
   async plan(turn: TurnContext) {
     // this.input: what the person sent (message, page, refs, tier, time zone).
-    const { plan, settle } = await assistant.agentTurn(caller, this.input ?? { message: '' });
+    // chat: this chat's id, so its use is one line of the person's usage history.
+    const { plan, settle } = await assistant.agentTurn(caller, { ...(this.input ?? { message: '' }), chat: this.name });
     this.#settle = settle;
     return plan;
   }

package/dist/assistant/engine.d.ts

@@ -1,4 +1,4 @@
-import type { AllowanceRequest, AllowanceState, AllowanceUnit, AssistantAccess, AssistantChat, AssistantChatRow, AssistantMessage, AssistantOwnWay, AssistantProvider, AssistantStatus } from '@columenlabs/lumen-ui-types/assistant';
+import type { AllowanceRequest, AllowanceState, AllowanceUnit, AssistantAccess, AssistantChat, AssistantChatRow, AssistantMessage, AssistantOwnWay, AssistantProvider, AssistantStatus, UsagePart } from '@columenlabs/lumen-ui-types/assistant';
 import type { AgentTurnEnd, AgentTurnPlan } from '../agent/agent.js';
 import { type BearingsExtra, type BearingsNow } from './bearings.js';
 import { type ModelDef, type TaskDef, type TierDef } from './models.js';
@@ -186,6 +186,11 @@ export interface AgentTurnInput {
     time_zone?: string;
     /** When the chat's last message was, for "since you last asked". */
     last_at?: number;
+    /**
+     * The chat this turn is in (the agent's name), so its use shows as one line of the person's
+     * usage history (`GET /usage`). Left out, the turn counts toward spend only.
+     */
+    chat?: string;
 }
 export declare class Assistant {
     private readonly o;
@@ -297,11 +302,21 @@ export declare class Assistant {
         /** The answer's token cap, thinking included (default 1,000, at most COMPLETE_MAX_TOKENS). */
         maxTokens?: number;
         signal?: AbortSignal;
+        /**
+         * The run this call belongs to, as one line of the person's usage history (`GET /usage`):
+         * calls with the same `id` add up (every round of one rebuild). Left out, the task's calls
+         * that day share one line named after the task.
+         */
+        run?: {
+            id: string;
+            title: string;
+        };
     }): Promise<{
         text: string;
         usd: number;
         model: string;
         cut: boolean;
+        usage: UsagePart;
     }>;
     /** Starts a person's ChatGPT plan sign-in: the address to open in a new tab. */
     startSignin(caller: Caller, provider: AssistantProvider): Promise<{

package/dist/assistant/engine.js

@@ -332,6 +332,10 @@ export class Assistant {
         };
         const settle = async (end) => {
             await this.state.addSpend(caller.id, paying.payer, end.parts).catch(() => undefined);
+            if (input.chat)
+                await this.state
+                    .addUsage(caller.id, { id: `chat:${input.chat}`, kind: 'chat', title: message.split('\n')[0] || 'Chat' }, end.parts)
+                    .catch(() => undefined);
             const total = end.parts.reduce((a, m) => ({
                 calls: a.calls + m.calls,
                 in: a.in + m.in,
@@ -963,9 +967,19 @@ export class Assistant {
             throw new AssistantError(`${s.model.label} did not answer: ${String(e?.message ?? e).slice(0, 200)}`, 'upstream', 502);
         }
         finally {
-            await this.state.addSpend(caller.id, paying.payer, [s.meter.part()]);
+            const part = s.meter.part();
+            await this.state.addSpend(caller.id, paying.payer, [part]);
+            const task = this.tasks.find((t) => t.id === o.task);
+            await this.state
+                .addUsage(caller.id, {
+                id: `task:${o.task}:${o.run?.id ?? new Date().toISOString().slice(0, 10)}`,
+                kind: 'task',
+                task: o.task,
+                title: o.run?.title ?? task?.label ?? o.task,
+            }, [part])
+                .catch(() => undefined);
         }
-        return { text, usd: s.meter.usd, model: s.model.id, cut };
+        return { text, usd: s.meter.usd, model: s.model.id, cut, usage: s.meter.part() };
     }
     // ---------------------------------------------------------------- keys
     /** Starts a person's ChatGPT plan sign-in: the address to open in a new tab. */

package/dist/assistant/models.js

@@ -126,7 +126,7 @@ export class Meter {
     }
     part() {
         const { label, calls, read, out, usd } = this;
-        return { label, calls, in: this.in, read, out, usd };
+        return { label, calls, in: this.in, read, out, usd, model: this.model.id };
     }
 }
 /** The request's effort setting: nothing at the model's own default. */

package/dist/assistant/routes.js

@@ -20,6 +20,7 @@
  *   PUT    /web/scrapeql {client_id, client_secret}, DELETE /web/scrapeql, POST /web/test   admin
  *   POST   /chat                    one answer as server-sent events; closing the request stops it
  *   GET    /chats, GET|DELETE /chats/:id
+ *   GET    /usage?month=YYYY-MM    the person's use that month: total, per tier and model, each chat and run
  *   POST   /chats/:id/drafts/:draft {action: save | dismiss}
  *   POST   /chats/:id/writes/:step/undo
  *   POST   /allowance/request {amount, why}   asks for more allowance (one open at a time)
@@ -321,6 +322,13 @@ export function assistantRoutes(app, o) {
                     return fail('Chats run on the agent now. Start a new chat.', 410, 'moved');
                 case 'GET /chats':
                     return json(await a.listChats(caller));
+                // The person's own use: one month's total, per tier and model, and each chat and run.
+                case 'GET /usage': {
+                    const month = url.searchParams.get('month') ?? undefined;
+                    if (month !== undefined && !/^\d{4}-\d{2}$/.test(month))
+                        return fail('month is YYYY-MM.');
+                    return json(await a.state.usage(caller.id, month));
+                }
                 case 'POST /allowance/request': {
                     const b = await body(req);
                     const amount = typeof b.amount === 'number' && Number.isFinite(b.amount) ? b.amount : 0;

package/dist/assistant/state.d.ts

@@ -19,7 +19,7 @@
  * tier runs on and money left this month, else the other; with neither the assistant waits and says
  * why. A cap covers every provider of its payer.
  */
-import type { AllowanceRequest, AssistantAccess, AssistantEffort, AssistantOwnWay, AssistantPayer, AssistantProvider, AssistantScreenSetting, AssistantWait, HandOffPolicy, UsagePart } from '@columenlabs/lumen-ui-types/assistant';
+import type { AllowanceRequest, AssistantAccess, AssistantEffort, AssistantOwnWay, AssistantPayer, AssistantProvider, AssistantScreenSetting, AssistantWait, HandOffPolicy, UsageEntry, UsageHistory, UsagePart } from '@columenlabs/lumen-ui-types/assistant';
 import { type ChatgptTokens } from './chatgpt.js';
 import { type Docs } from './store.js';
 export interface KeyTest {
@@ -98,6 +98,22 @@ export type SpendRow = UsagePart & {
 export interface SpendDoc {
     rows: SpendRow[];
 }
+/** Chats and runs kept in one month's usage history: the newest this many. */
+export declare const USAGE_KEPT = 300;
+export interface UsageDoc {
+    entries: UsageEntry[];
+}
+/** Adds `more` to `parts`, merged by label (the model kept from the first). */
+export declare function mergeParts(parts: UsagePart[], more: UsagePart[]): {
+    label: string;
+    calls: number;
+    in: number;
+    read: number;
+    out: number;
+    usd: number;
+    runs?: number;
+    model?: string;
+}[];
 /** USD a month when nobody set a cap. */
 export declare const DEFAULT_CAP = 10;
 /** `2026-10` in the app's time zone. */
@@ -191,6 +207,18 @@ export declare class State {
     spend(id: string, month?: string): Promise<SpendDoc>;
     /** Adds an answer's use to this month's spend, by label and payer. */
     addSpend(id: string, payer: AssistantPayer, parts: UsagePart[]): 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.
+     */
+    addUsage(id: string, e: {
+        id: string;
+        kind: UsageEntry['kind'];
+        task?: string;
+        title: string;
+    }, 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>;
     /** The payer's key of each provider, those set, and which are plan sign-ins. */
     keysOf(id: string, payer: AssistantPayer): Promise<{
         keys: Partial<Record<"anthropic" | "openai" | "xai", string>>;

package/dist/assistant/state.js

@@ -7,6 +7,33 @@ 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;
+/** 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). */
+const USAGE_MONTHS = 24;
+/** Adds `more` to `parts`, merged by label (the model kept from the first). */
+export function mergeParts(parts, more) {
+    const out = parts.map((p) => ({ ...p }));
+    for (const p of more) {
+        if (!p.calls)
+            continue;
+        const prev = out.find((r) => r.label === p.label);
+        if (!prev)
+            out.push({ ...p });
+        else {
+            prev.calls += p.calls;
+            prev.in += p.in;
+            prev.read += p.read;
+            prev.out += p.out;
+            prev.usd += p.usd;
+            if (p.runs)
+                prev.runs = (prev.runs ?? 0) + p.runs;
+            if (!prev.model && p.model)
+                prev.model = p.model;
+        }
+    }
+    return out;
+}
 /** USD a month when nobody set a cap. */
 export const DEFAULT_CAP = 10;
 /** `2026-10` in the app's time zone. */
@@ -227,6 +254,53 @@ export class State {
                 await this.setAllowance(id, (d) => ({ ...d, spent_usd: (d.spent_usd ?? 0) + usd }));
         }
     }
+    /**
+     * 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.
+     */
+    async addUsage(id, e, parts) {
+        if (!parts.some((p) => p.calls))
+            return;
+        const now = Date.now();
+        await this.docs.update(id, `usage:${this.month()}`, (d) => {
+            const entries = [...(d?.entries ?? [])];
+            const i = entries.findIndex((x) => x.id === e.id);
+            const prev = i >= 0 ? entries.splice(i, 1)[0] : undefined;
+            const merged = mergeParts(prev?.parts ?? [], parts);
+            const sum = (k) => merged.reduce((a, p) => a + p[k], 0);
+            entries.unshift({
+                id: e.id,
+                kind: e.kind,
+                ...(e.task ? { task: e.task } : {}),
+                title: prev?.title || e.title.slice(0, 120),
+                first: prev?.first ?? now,
+                at: now,
+                calls: sum('calls'),
+                in: sum('in'),
+                read: sum('read'),
+                out: sum('out'),
+                usd: sum('usd'),
+                parts: merged,
+            });
+            return { entries: entries.slice(0, USAGE_KEPT) };
+        });
+    }
+    /** One month's history (this month by default) beside its spend, and the months that have one. */
+    async usage(id, month = this.month()) {
+        const [doc, spend, listed] = await Promise.all([
+            this.docs.read(id, `usage:${month}`),
+            this.spend(id, month),
+            this.docs.list(id, 'usage:', USAGE_MONTHS),
+        ]);
+        const months = [...new Set([this.month(), ...listed.map((r) => r.key.slice(6))])].sort((a, b) => b.localeCompare(a));
+        return {
+            month,
+            months,
+            usd: spend.rows.reduce((a, r) => a + r.usd, 0),
+            rows: spend.rows,
+            entries: doc?.entries ?? [],
+        };
+    }
     /** The payer's key of each provider, those set, and which are plan sign-ins. */
     async keysOf(id, payer) {
         const ids = Object.keys(PROVIDERS);

package/package.json

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