@columenlabs/lumen-ai 0.1.274 → 0.1.275

package/README.md

@@ -117,7 +117,9 @@ 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. A hand-off gives up after `HAND_OFF_MS` (4 minutes) and the turn goes on without it.
 - **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`, `usage` (tokens in, cache reads, out, per model) and `payer` (`app` or `own`: who paid, so the app can show a cost on the person's own key as money and the rest as credits). `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). **Prompt cache:** `prompt` may be a list of parts; every part but the last is kept in the provider's prompt cache with the instructions and the pictures (sent first), so the next call of a run that starts with the same parts reads them at a tenth of the price. Put what stays the same first. OpenAI calls carry a cache key per person, task and run (a ChatGPT plan sign-in caches nothing without one).
+- **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`, `usage` (tokens in, cache reads, out, per model) and `payer` (`app` or `own`: who paid, so the app can show a cost on the person's own key as money and the rest as credits). `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). **Prompt cache:** a provider's cache reuses whole earlier messages, not text added inside the same message (OpenAI read 0% of a prompt that only gained a part, and 99.7% when the same words came as a new message). So a job of several steps (a study that asks for more pictures, then a build) passes `history`: the conversation so far as `{ role, text, images? }` messages, oldest first, ending with the model's answer, and `prompt` and `images` as the newest message; each call then pays only for what is new. `prompt` may also be a list of parts (Claude marks every part but the last), which helps only an exact repeat on OpenAI. OpenAI calls carry a cache key per person, task and run (a ChatGPT plan sign-in caches nothing without one).
+
+**Call log:** every model call (chat steps, hand-offs, compaction, `complete`) writes one JSON line on the console, `{ event: 'ai.call', model, label, task, run, in, read, written, out, hit, usd, free }`: tokens in (cache included), cache reads and writes, out, the share read from cache (`hit`), the cost at list price, and `free` for a plan sign-in. Workers Logs keeps it, so an app sees each call's cache use with no wiring. `setCallLog(fn)` sends the records elsewhere; `setCallLog(null)` turns it off.
 - **Images** an app makes for a person are `assistant.image(caller, { task, prompt, images?, size?, quality?, run? })`: one image on the payer's OpenAI key (`IMAGE_MODEL`, gpt-image-2; a ChatGPT plan sign-in cannot make one), from `images` when given (a reference, a sketch), billed and capped like `complete` at the model's list price per token. It returns the PNG as base64 with its `usd`. A chat tool that returns `image: { url, alt?, cost? }` shows as an image card in the panel (`StepItem.image`); `LumenAssistant` `imageTool` names that tool (its "Making the image" box while it runs, Make another) and `modes` adds composer toggles (Make an image) whose id goes with the message as `use`.
 - **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`).
 

package/dist/agent/agent.js

@@ -632,6 +632,7 @@ export class LumenAgent extends Think {
             throw new Error('No model to compact with until the next answer.');
         const { plan } = last;
         let meter = new UsageMeter(plan.model, `${plan.label} · compact`, !!plan.key.plan);
+        meter.ctx = { task: 'chat', run: this.name };
         this.#owed.push(meter);
         const r = await generateText({
             maxRetries: 0,
@@ -640,6 +641,7 @@ export class LumenAgent extends Think {
                 if (!fb)
                     return;
                 meter = new UsageMeter(fb.model, `${fb.label} · compact`, false);
+                meter.ctx = { task: 'chat', run: this.name };
                 this.#owed.push(meter);
             }),
             prompt,
@@ -684,14 +686,18 @@ export class LumenAgent extends Think {
             ...plan.tools,
         });
         const free = !!plan.key.plan;
+        const call = { task: 'chat', run: this.name };
         const main = new UsageMeter(plan.model, plan.label, free);
+        main.ctx = call;
         const meters = [main, ...this.#owed];
         this.#owed = [];
         const advice = plan.advisor
             ? new UsageMeter(plan.advisor.model, plan.advisor.label, free)
             : undefined;
-        if (advice)
+        if (advice) {
+            advice.ctx = call;
             meters.push(advice);
+        }
         let system = typeof plan.system === 'string' ? plan.system : plan.system(opened);
         this.#keepTitles(opened.info);
         this.#turn = {
@@ -711,6 +717,7 @@ export class LumenAgent extends Think {
             over: () => plan.left !== undefined && this.#spent() >= plan.left,
             meter: (model, label, f = free) => {
                 const m = new UsageMeter(model, label, f);
+                m.ctx = call;
                 meters.push(m);
                 return m;
             },
@@ -769,6 +776,7 @@ export class LumenAgent extends Think {
                     return;
                 // Claude answers the rest of the turn on the payer's key: its use is its own part.
                 turn.main = new UsageMeter(fb.model, fb.label, false);
+                turn.main.ctx = { task: 'chat', run: this.name };
                 turn.meters.push(turn.main);
             }),
             // Think types instructions as a string; the SDK it hands them to takes a system message too.

package/dist/agent/usage.d.ts

@@ -1,7 +1,7 @@
 /** An AI SDK step's usage as the kit's tokens and list-price cost. */
 import type { UsagePart } from '@columenlabs/lumen-ui-types/assistant';
 import type { LanguageModelUsage } from 'ai';
-import { type ModelDef, type TokenUsage } from '../assistant/models.js';
+import { type CallContext, type ModelDef, type TokenUsage } from '../assistant/models.js';
 /**
  * One call's usage in the kit's terms. Input splits into plain, cache writes and cache reads where
  * the provider says (Claude reports all three; OpenAI reports reads, its writes cost nothing extra).
@@ -18,6 +18,8 @@ export declare class UsageMeter {
     readonly model: ModelDef;
     private readonly free;
     private p;
+    /** What the calls are for, on each call's log line (`logCall`). */
+    ctx?: CallContext;
     constructor(model: ModelDef, label: string, free?: boolean);
     add(u: LanguageModelUsage): {
         in: number;

package/dist/agent/usage.js

@@ -1,4 +1,4 @@
-import { priced } from '../assistant/models.js';
+import { logCall, priced, } from '../assistant/models.js';
 /**
  * One call's usage in the kit's terms. Input splits into plain, cache writes and cache reads where
  * the provider says (Claude reports all three; OpenAI reports reads, its writes cost nothing extra).
@@ -21,6 +21,8 @@ export class UsageMeter {
     model;
     free;
     p;
+    /** What the calls are for, on each call's log line (`logCall`). */
+    ctx;
     constructor(model, label, free = false) {
         this.model = model;
         this.free = free;
@@ -32,6 +34,7 @@ export class UsageMeter {
     /** Tokens a provider reports apart from the step's usage (Claude's advisor calls). */
     addTokens(u) {
         const t = priced(this.model, u);
+        logCall(this.model, this.p.label, u, t, this.free, this.ctx);
         this.p.calls += 1;
         this.p.in += t.in;
         this.p.read += t.read;

package/dist/assistant/engine.d.ts

@@ -36,6 +36,20 @@ export interface CompleteImage {
     mediaType: string;
     data: string;
 }
+/**
+ * One earlier message of a `complete` conversation: what was asked (with its own photos) or what the
+ * model answered. Sent as real messages, in order, before the newest prompt: a provider's prompt
+ * cache reuses whole earlier messages, so a conversation that only grows at its end is read from
+ * the cache at a tenth of the price. Text added inside one message is not (OpenAI, checked
+ * 2026-11-14: 0 of 3,889 tokens read when a part was added to the same message, 9,563 of 9,592
+ * when the same words came as a new message).
+ */
+export interface CompleteTurn {
+    role: 'user' | 'assistant';
+    text: string;
+    /** A user message's photos, sent before its text. */
+    images?: CompleteImage[];
+}
 export interface Caller {
     id: string;
     admin: boolean;
@@ -407,6 +421,13 @@ export declare class Assistant {
         prompt: string | string[];
         /** Photos read with the prompt (a scanned page, a screenshot), sent before it and cached. */
         images?: CompleteImage[];
+        /**
+         * The conversation so far, oldest first, alternating user and assistant and ending with the
+         * model's answer; `prompt` and `images` are the newest message. Each earlier message is read
+         * from the prompt cache on the next call, so a multi-step job (a study that asks for more
+         * pictures, then a build) re-pays only what is new.
+         */
+        history?: CompleteTurn[];
         /** The answer's token cap, thinking included (default 1,000, at most COMPLETE_MAX_TOKENS). */
         maxTokens?: number;
         /**

package/dist/assistant/engine.js

@@ -38,6 +38,34 @@ export const COMPLETE_MAX_TOKENS = 32_000;
 /** A turn's failure the person can act on. */
 /** Claude's prompt cache mark on a block: the prompt up to it is kept for the next call. */
 const CACHE_MARK = { type: 'ephemeral' };
+/**
+ * A `complete` conversation's earlier messages for Claude, the last block marked so the next call
+ * reads the whole conversation so far from the cache.
+ */
+function claudeHistory(history) {
+    return history.map((t, n) => {
+        const last = n === history.length - 1;
+        if (t.role === 'assistant')
+            return {
+                role: 'assistant',
+                content: [{ type: 'text', text: t.text, ...(last ? { cache_control: CACHE_MARK } : {}) }],
+            };
+        return {
+            role: 'user',
+            content: [
+                ...(t.images ?? []).map((i) => ({
+                    type: 'image',
+                    source: {
+                        type: 'base64',
+                        media_type: i.mediaType,
+                        data: i.data,
+                    },
+                })),
+                { type: 'text', text: t.text, ...(last ? { cache_control: CACHE_MARK } : {}) },
+            ],
+        };
+    });
+}
 /** OpenAI's prompt cache key for one person's task or run: a short, stable hash of `of`. */
 function cacheKey(of) {
     let h = 0x811c9dc5;
@@ -1132,7 +1160,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, effort, cacheKey) {
+    async openaiOnce(clients, s, instructions, input, max, signal, images, effort, cacheKey, history = []) {
         // xAI's API is OpenAI's Responses API at another address.
         const xai = s.model.provider === 'xai';
         const client = (xai ? clients.xai : clients.openai);
@@ -1144,8 +1172,24 @@ export class Assistant {
                 model: s.model.id,
                 instructions,
                 // A plan sign-in takes only a list of items, never bare text ("Input must be a list").
-                // Pictures first, then the text in its parts: the cache keeps the longest unchanged start.
+                // The earlier messages as they were, then the newest: pictures first, then its text parts.
                 input: [
+                    ...history.map((t) => t.role === 'assistant'
+                        ? {
+                            role: 'assistant',
+                            content: [{ type: 'output_text', text: t.text }],
+                        }
+                        : {
+                            role: 'user',
+                            content: [
+                                ...(t.images ?? []).map((i) => ({
+                                    type: 'input_image',
+                                    image_url: `data:${i.mediaType};base64,${i.data}`,
+                                    detail: 'auto',
+                                })),
+                                { type: 'input_text', text: t.text },
+                            ],
+                        }),
                     {
                         role: 'user',
                         content: [
@@ -1217,6 +1261,7 @@ export class Assistant {
         const began = Date.now();
         const s = await this.session(caller, await this.mainTier(caller, o.task));
         const { rules, free } = await this.rulesFor(caller, s.tier.id, o.payer);
+        s.meter.ctx = { task: o.task, ...(o.run && { run: o.run.id }) };
         const { paying, wait } = await this.state.paying(caller.id, s.model.provider, rules);
         if (!paying) {
             const code = wait ?? 'not_connected';
@@ -1231,7 +1276,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, parts, max, o.signal, o.images, o.effort, cacheKey(`${caller.id}:${o.task}:${o.run?.id ?? ''}`)));
+                ({ text, cut } = await this.openaiOnce(clients, s, o.system, parts, max, o.signal, o.images, o.effort, cacheKey(`${caller.id}:${o.task}:${o.run?.id ?? ''}`), o.history));
             }
             else if (clients.anthropic) {
                 // Streamed and read whole: a long answer (minutes at a high cap) keeps its connection alive,
@@ -1260,7 +1305,7 @@ export class Assistant {
                     model: s.model.id,
                     max_tokens: max,
                     system: [{ type: 'text', text: o.system, cache_control: CACHE_MARK }],
-                    messages: [{ role: 'user', content }],
+                    messages: [...claudeHistory(o.history ?? []), { role: 'user', content }],
                     ...effortParams(o.effort ?? s.effort),
                 }, o.signal ? { signal: o.signal } : undefined)
                     .finalMessage();

package/dist/assistant/models.d.ts

@@ -73,6 +73,35 @@ export declare function priced(model: ModelDef, usage: TokenUsage): {
     read: number;
     usd: number;
 };
+/** What a model call was for, as far as the code that made it knows: its task and its run (a chat, a rebuild). */
+export interface CallContext {
+    task?: string;
+    run?: string;
+}
+/**
+ * One model call, as every app logs it: the model, the part's label (`Tier · Model`), tokens in (cache
+ * reads and writes included), cache reads, cache writes and tokens out, the share of the input read
+ * from cache (`hit`, 0 to 1), the cost at list price and whether a plan sign-in ran it (`free`).
+ */
+export interface CallRecord extends CallContext {
+    event: 'ai.call';
+    model: string;
+    label: string;
+    in: number;
+    read: number;
+    written: number;
+    out: number;
+    hit: number;
+    usd: number;
+    free: boolean;
+}
+/**
+ * Where each model call's record goes. By default one JSON line on the console (Workers Logs keeps
+ * it), so every app sees each call's tokens and cache reads with no wiring. `null` turns it off.
+ */
+export declare function setCallLog(fn: ((r: CallRecord) => void) | null): void;
+/** Logs one priced call. Never throws: a log that fails never fails the call. */
+export declare function logCall(model: ModelDef, label: string, usage: TokenUsage, p: ReturnType<typeof priced>, free: boolean, ctx?: CallContext): void;
 /** The running use of one tier in one answer. */
 export declare class Meter {
     readonly model: ModelDef;
@@ -82,6 +111,8 @@ export declare class Meter {
     read: number;
     out: number;
     usd: number;
+    /** What the calls are for, on each call's log line. */
+    ctx?: CallContext;
     constructor(model: ModelDef, label: string);
     /** `free`: the call ran on a plan sign-in, so it counts tokens and no dollars. */
     add(usage: TokenUsage, free?: boolean): void;

package/dist/assistant/models.js

@@ -101,6 +101,36 @@ export function priced(model, usage) {
             1e6,
     };
 }
+let callLog = (r) => console.log(JSON.stringify(r));
+/**
+ * Where each model call's record goes. By default one JSON line on the console (Workers Logs keeps
+ * it), so every app sees each call's tokens and cache reads with no wiring. `null` turns it off.
+ */
+export function setCallLog(fn) {
+    callLog = fn;
+}
+/** Logs one priced call. Never throws: a log that fails never fails the call. */
+export function logCall(model, label, usage, p, free, ctx) {
+    try {
+        callLog?.({
+            event: 'ai.call',
+            model: model.id,
+            label,
+            ...(ctx?.task && { task: ctx.task }),
+            ...(ctx?.run && { run: ctx.run }),
+            in: p.in,
+            read: p.read,
+            written: usage.cache_creation_input_tokens ?? 0,
+            out: p.out,
+            hit: p.in ? Math.round((p.read / p.in) * 1000) / 1000 : 0,
+            usd: free ? 0 : Math.round(p.usd * 1e6) / 1e6,
+            free,
+        });
+    }
+    catch {
+        // A log is never worth a failed call.
+    }
+}
 /** The running use of one tier in one answer. */
 export class Meter {
     model;
@@ -110,6 +140,8 @@ export class Meter {
     read = 0;
     out = 0;
     usd = 0;
+    /** What the calls are for, on each call's log line. */
+    ctx;
     constructor(model, label) {
         this.model = model;
         this.label = label;
@@ -117,6 +149,7 @@ export class Meter {
     /** `free`: the call ran on a plan sign-in, so it counts tokens and no dollars. */
     add(usage, free = false) {
         const p = priced(this.model, usage);
+        logCall(this.model, this.label, usage, p, free, this.ctx);
         this.calls += 1;
         this.in += p.in;
         this.read += p.read;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@columenlabs/lumen-ai",
-  "version": "0.1.274",
+  "version": "0.1.275",
   "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",
@@ -57,8 +57,8 @@
     "@anthropic-ai/sdk": "0.133.0",
     "@cloudflare/computer": "0.8.0",
     "@cloudflare/think": "0.23.0",
-    "@columenlabs/lumen-ops": "0.1.274",
-    "@columenlabs/lumen-ui-types": "0.1.274",
+    "@columenlabs/lumen-ops": "0.1.275",
+    "@columenlabs/lumen-ui-types": "0.1.275",
     "agents": "0.32.0",
     "ai": "7.0.162",
     "just-bash": "3.6.0",