@columenlabs/lumen-ai 0.1.223 → 0.1.225

package/README.md

@@ -103,7 +103,7 @@ 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. 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.
+- **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). `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).
 - **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 `#`

package/dist/assistant/engine.d.ts

@@ -1,4 +1,4 @@
-import type { AllowanceRequest, AllowanceState, AllowanceUnit, AssistantAccess, AssistantChat, AssistantChatRow, AssistantMessage, AssistantOwnWay, AssistantProvider, AssistantStatus, UsagePart } from '@columenlabs/lumen-ui-types/assistant';
+import type { AllowanceRequest, AllowanceState, AllowanceUnit, AssistantAccess, AssistantChat, AssistantChatRow, AssistantEffort, 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';
@@ -306,6 +306,12 @@ export declare class Assistant {
         images?: CompleteImage[];
         /** The answer's token cap, thinking included (default 1,000, at most COMPLETE_MAX_TOKENS). */
         maxTokens?: number;
+        /**
+         * How hard the model thinks on this one call, whatever the person saved for the tier. On an
+         * OpenAI or xAI model it is the request's reasoning effort (`max` asks for `high`); left out,
+         * those models run at their own default.
+         */
+        effort?: AssistantEffort;
         signal?: AbortSignal;
         /**
          * The run this call belongs to, as one line of the person's usage history (`GET /usage`):
@@ -316,6 +322,11 @@ export declare class Assistant {
             id: string;
             title: string;
         };
+        /**
+         * What this call counts as in the month's spend per task (`spend:YYYY-MM` `tasks`), when one
+         * task does more than one kind of work (a first try, a repair). Left out, it is the task.
+         */
+        tag?: string;
     }): Promise<{
         text: string;
         usd: number;

package/dist/assistant/engine.js

@@ -332,7 +332,9 @@ export class Assistant {
                 : {},
         };
         const settle = async (end) => {
-            await this.state.addSpend(caller.id, paying.payer, end.parts).catch(() => undefined);
+            await this.state
+                .addSpend(caller.id, paying.payer, end.parts, { task: 'chat', ms: end.ms })
+                .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)
@@ -831,7 +833,7 @@ export class Assistant {
      * events like the chat loop, because a ChatGPT plan sign-in answers only streamed calls, takes no
      * output cap and may send its words only as deltas.
      */
-    async openaiOnce(clients, s, instructions, input, max, signal, images) {
+    async openaiOnce(clients, s, instructions, input, max, signal, images, effort) {
         // xAI's API is OpenAI's Responses API at another address.
         const xai = s.model.provider === 'xai';
         const client = (xai ? clients.xai : clients.openai);
@@ -861,6 +863,8 @@ export class Assistant {
                 store: false,
                 stream: true,
                 ...(plan ? {} : { max_output_tokens: max }),
+                ...(effort &&
+                    effort !== 'default' && { reasoning: { effort: effort === 'max' ? 'high' : effort } }),
             }, signal ? { signal } : {});
             for await (const e of stream) {
                 if (e.type === 'response.output_text.delta' && typeof e.delta === 'string')
@@ -907,6 +911,7 @@ export class Assistant {
      * `not_connected`, `app_cap` or `own_cap` when nobody can pay, or `upstream` when the model fails.
      */
     async complete(caller, o) {
+        const began = Date.now();
         const s = await this.session(caller, await this.mainTier(caller, o.task));
         const { paying, wait } = await this.state.paying(caller.id, s.model.provider);
         if (!paying) {
@@ -921,7 +926,7 @@ export class Assistant {
         try {
             if ((s.model.provider === 'openai' && clients.openai) ||
                 (s.model.provider === 'xai' && clients.xai)) {
-                ({ text, cut } = await this.openaiOnce(clients, s, o.system, o.prompt, max, o.signal, o.images));
+                ({ text, cut } = await this.openaiOnce(clients, s, o.system, o.prompt, max, o.signal, o.images, o.effort));
             }
             else if (clients.anthropic) {
                 // Streamed and read whole: a long answer (minutes at a high cap) keeps its connection alive,
@@ -949,7 +954,7 @@ export class Assistant {
                                 : o.prompt,
                         },
                     ],
-                    ...effortParams(s.effort),
+                    ...effortParams(o.effort ?? s.effort),
                 }, o.signal ? { signal: o.signal } : undefined)
                     .finalMessage();
                 s.meter.add(msg.usage);
@@ -969,7 +974,10 @@ export class Assistant {
         }
         finally {
             const part = s.meter.part();
-            await this.state.addSpend(caller.id, paying.payer, [part]);
+            await this.state.addSpend(caller.id, paying.payer, [part], {
+                task: o.tag ?? o.task,
+                ms: Date.now() - began,
+            });
             const task = this.tasks.find((t) => t.id === o.task);
             await this.state
                 .addUsage(caller.id, {

package/dist/assistant/index.d.ts

@@ -19,7 +19,7 @@ export * from './find.js';
 export * from './meaning.js';
 export * from './models.js';
 export * from './routes.js';
-export { DEFAULT_CAP, type KeyDoc, keyDocName, type KeyTest, monthIn, type Paying, type PersonDoc, type SpendDoc, State, type TokenDoc, waitText, } from './state.js';
+export { DEFAULT_CAP, type KeyDoc, keyDocName, type KeyTest, monthIn, type Paying, type PersonDoc, type SpendDoc, type TaskSpend, State, type TokenDoc, waitText, } from './state.js';
 export * from './store.js';
 export * from './tools.js';
 export * from './web.js';

package/dist/assistant/state.d.ts

@@ -97,8 +97,30 @@ export interface RequestsDoc {
 export type SpendRow = UsagePart & {
     payer: AssistantPayer;
 };
+/**
+ * One task's use of one model this month: what a kind of work cost (a chat answer, a background
+ * task), beside `rows`, which stay per tier and payer.
+ */
+export interface TaskSpend {
+    /** The task's id (`chat`, or a `complete` call's `tag` or `task`). */
+    task: string;
+    /** The model's id. */
+    model: string;
+    /** Answers: chat turns, or `complete` calls. */
+    runs: number;
+    /** Model calls. */
+    calls: number;
+    in: number;
+    read: number;
+    out: number;
+    usd: number;
+    /** Time the answers took in all, in ms (`ms / runs` is the average). */
+    ms: number;
+}
 export interface SpendDoc {
     rows: SpendRow[];
+    /** Per task and model, counted since the kit began tagging (older spend is only in `rows`). */
+    tasks?: TaskSpend[];
 }
 /** Chats and runs kept in one month's usage history: the newest this many. */
 export declare const USAGE_KEPT = 300;
@@ -210,8 +232,14 @@ export declare class State {
     } | null>;
     appCap(): Promise<number>;
     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 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`).
+     */
+    addSpend(id: string, payer: AssistantPayer, parts: UsagePart[], at?: {
+        task: string;
+        ms?: number;
+    }): 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.

package/dist/assistant/state.js

@@ -227,12 +227,43 @@ export class State {
     spend(id, month = this.month()) {
         return this.docs.read(id, `spend:${month}`).then((d) => d ?? { rows: [] });
     }
-    /** Adds an answer's use to this month's spend, by label and payer. */
-    async addSpend(id, payer, parts) {
+    /**
+     * 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) {
         if (!parts.some((p) => p.calls))
             return;
         await this.docs.update(id, `spend:${this.month()}`, (d) => {
             const rows = [...(d?.rows ?? [])];
+            const tasks = [...(d?.tasks ?? [])];
+            if (at) {
+                // The answer and its time count once, on its first model.
+                let first = true;
+                for (const p of parts) {
+                    if (!p.calls)
+                        continue;
+                    const model = p.model ?? p.label;
+                    const i = tasks.findIndex((t) => t.task === at.task && t.model === model);
+                    const prev = i >= 0 ? tasks[i] : undefined;
+                    const row = {
+                        task: at.task,
+                        model,
+                        runs: (prev?.runs ?? 0) + (first ? 1 : 0),
+                        calls: (prev?.calls ?? 0) + p.calls,
+                        in: (prev?.in ?? 0) + p.in,
+                        read: (prev?.read ?? 0) + p.read,
+                        out: (prev?.out ?? 0) + p.out,
+                        usd: (prev?.usd ?? 0) + p.usd,
+                        ms: (prev?.ms ?? 0) + (first ? (at.ms ?? 0) : 0),
+                    };
+                    first = false;
+                    if (i >= 0)
+                        tasks[i] = row;
+                    else
+                        tasks.push(row);
+                }
+            }
             for (const p of parts) {
                 if (!p.calls)
                     continue;
@@ -253,7 +284,7 @@ export class State {
                 else
                     rows.push(row);
             }
-            return { rows };
+            return tasks.length ? { rows, tasks } : { rows };
         });
         if (payer === 'app' && this.o.allowance?.period === 'once') {
             const usd = parts.reduce((a, p) => a + p.usd, 0);

package/package.json

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