@columenlabs/lumen-ai 0.1.224 → 0.1.226

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). `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.
+- **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/agent/agent.d.ts

@@ -12,7 +12,7 @@
  * An `Assistant` gives both: `assistant.agentTurn(caller, input)` returns a plan and its settle.
  */
 import { type ChatResponseResult, type PrepareStepContext, type Session, type StepConfig, type StepContext, Think, type ThinkModel, type TurnConfig, type TurnContext } from '@cloudflare/think';
-import { type AssistantChat, type AssistantEffort, type AssistantEvent, type AssistantImage, type AssistantRefNote, type AssistantScreenMap, type AssistantScreenOutcome, type ChatUsage, type UsagePart } from '@columenlabs/lumen-ui-types/assistant';
+import { type AssistantChat, type AssistantEffort, type AssistantEvent, type AssistantImage, type AssistantQuote, type AssistantRefNote, type AssistantScreenMap, type AssistantScreenOutcome, type ChatUsage, type UsagePart } from '@columenlabs/lumen-ui-types/assistant';
 import { type ModelMessage, type ToolSet } from 'ai';
 import type { ModelDef } from '../assistant/models.js';
 import { type AgentConnector, type ConnectorAt } from './connectors.js';
@@ -134,6 +134,8 @@ export interface AskInput {
         note?: unknown;
     };
     refs?: AssistantRefNote[];
+    /** The piece of the chat this message replies to (Reply on selected text). */
+    quote?: AssistantQuote;
     tier?: string;
     time_zone?: string;
     /** What the browser can show (Screen on): the `screen` tool and its rules join the turn. */
@@ -141,6 +143,14 @@ export interface AskInput {
     /** How earlier screen calls ended in the browser. */
     outcomes?: AssistantScreenOutcome[];
 }
+/** A quote as sent, checked: its text cut to `ASSISTANT_QUOTE_MAX`, and whose message it came from. */
+export declare function quoteOf(q: unknown): AssistantQuote | undefined;
+/**
+ * The words the model reads before a message that replies to a quote: which message it came from
+ * and the quote itself. It is the message's first text part; the panel shows the quote from the
+ * message's metadata instead, so `itemsOf` leaves this part out.
+ */
+export declare function quoteLead(q: AssistantQuote): string;
 /**
  * The images a message may carry, as file parts: allowed types only, at most `ASSISTANT_IMAGES_MAX`,
  * and no more than `ASSISTANT_IMAGE_CHARS` of base64 together; the rest are left out.

package/dist/agent/agent.js

@@ -13,7 +13,7 @@
  */
 import { anthropic } from '@ai-sdk/anthropic';
 import { Think, } from '@cloudflare/think';
-import { ASSISTANT_IMAGES_MAX, ASSISTANT_IMAGE_CHARS, ASSISTANT_IMAGE_TYPES, } from '@columenlabs/lumen-ui-types/assistant';
+import { ASSISTANT_IMAGES_MAX, ASSISTANT_IMAGE_CHARS, ASSISTANT_IMAGE_TYPES, ASSISTANT_QUOTE_MAX, } from '@columenlabs/lumen-ui-types/assistant';
 import { createCompactFunction } from 'agents/sessions';
 import { generateText } from 'ai';
 import { CONNECTOR_GROUP, checkConnectorUrl, connectorGroup, connectorId, connectorSource, } from './connectors.js';
@@ -73,6 +73,27 @@ export function withLead(messages, lead) {
         : [{ type: 'text', text: lead }, ...m.content];
     return [...messages.slice(0, i), { ...m, content }, ...messages.slice(i + 1)];
 }
+/** A quote as sent, checked: its text cut to `ASSISTANT_QUOTE_MAX`, and whose message it came from. */
+export function quoteOf(q) {
+    const o = q;
+    const text = typeof o?.text === 'string' ? o.text.trim().slice(0, ASSISTANT_QUOTE_MAX) : '';
+    if (!text)
+        return undefined;
+    return { text, from: o?.from === 'user' ? 'user' : 'assistant' };
+}
+/**
+ * The words the model reads before a message that replies to a quote: which message it came from
+ * and the quote itself. It is the message's first text part; the panel shows the quote from the
+ * message's metadata instead, so `itemsOf` leaves this part out.
+ */
+export function quoteLead(q) {
+    const whose = q.from === 'user' ? 'their own earlier message' : 'your earlier answer';
+    const lines = q.text
+        .split('\n')
+        .map((l) => `> ${l}`)
+        .join('\n');
+    return `The person replies to this part of ${whose}:\n${lines}\n\n`;
+}
 /**
  * The images a message may carry, as file parts: allowed types only, at most `ASSISTANT_IMAGES_MAX`,
  * and no more than `ASSISTANT_IMAGE_CHARS` of base64 together; the rest are left out.
@@ -209,10 +230,12 @@ export class LumenAgent extends Think {
         this.#put('at', at);
         await sink.event({ event: 'chat', data: { id: this.name, title } });
         this.#outcomes(screenOutcomesOf(input.outcomes));
+        const quote = quoteOf(input.quote);
         const meta = {
             at,
             ...(input.context ? { context: { label: input.context.label } } : {}),
             ...(input.refs?.length ? { refs: input.refs } : {}),
+            ...(quote ? { quote } : {}),
             ...(input.tier ? { tier: input.tier } : {}),
         };
         const toEvents = chunkEvents({
@@ -237,7 +260,11 @@ export class LumenAgent extends Think {
             await this.chat({
                 id: userId,
                 role: 'user',
-                parts: [{ type: 'text', text: input.message }, ...imageParts(input.images)],
+                parts: [
+                    ...(quote ? [{ type: 'text', text: quoteLead(quote) }] : []),
+                    { type: 'text', text: input.message },
+                    ...imageParts(input.images),
+                ],
                 metadata: meta,
             }, {
                 onStart: () => undefined,

package/dist/agent/stream.d.ts

@@ -3,7 +3,7 @@
  * panel's `AssistantEvent`s, and a stored chat's messages and cards as its `ChatItem`s. The panel
  * (`@columenlabs/lumen-ui`'s `LumenAssistant`) reads a Think chat the same way as before.
  */
-import type { AssistantEvent, AssistantRefNote, ChatItem } from '@columenlabs/lumen-ui-types/assistant';
+import type { AssistantEvent, AssistantQuote, AssistantRefNote, ChatItem } from '@columenlabs/lumen-ui-types/assistant';
 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`. */
@@ -40,6 +40,8 @@ export interface AskMeta {
         label: string;
     };
     refs?: AssistantRefNote[];
+    /** The piece of the chat the message replies to; its words to the model are the first text part. */
+    quote?: AssistantQuote;
     tier?: string;
 }
 /** A stored chat as the panel's items: the messages in order, each tool call as it ended. */

package/dist/agent/stream.js

@@ -137,11 +137,12 @@ export function itemsOf(messages, cards, screens = new Map(), steers = {}) {
     for (const m of messages) {
         if (m.role === 'user') {
             asked = m.id;
+            const meta = (obj(m.metadata) ?? {});
             const text = m.parts
                 .filter((p) => p.type === 'text')
+                .slice(meta.quote ? 1 : 0)
                 .map((p) => String(p.text ?? ''))
                 .join('');
-            const meta = (obj(m.metadata) ?? {});
             const images = m.parts
                 .filter((p) => p.type === 'file' && typeof p.url === 'string' && p.url.startsWith('data:image/'))
                 .map((p) => p.url);
@@ -152,6 +153,7 @@ export function itemsOf(messages, cards, screens = new Map(), steers = {}) {
                 ...(images.length ? { images } : {}),
                 ...(meta.context?.label ? { context: meta.context.label } : {}),
                 ...(meta.refs?.length ? { refs: meta.refs } : {}),
+                ...(meta.quote ? { quote: meta.quote } : {}),
                 ...(meta.tier ? { tier: meta.tier } : {}),
             });
             continue;

package/dist/assistant/engine.d.ts

@@ -322,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)
@@ -909,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) {
@@ -971,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.224",
+  "version": "0.1.226",
   "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.224",
-    "@columenlabs/lumen-ui-types": "0.1.224",
+    "@columenlabs/lumen-ops": "0.1.226",
+    "@columenlabs/lumen-ui-types": "0.1.226",
     "agents": "0.32.0",
     "ai": "7.0.162",
     "just-bash": "3.6.0",