@columenlabs/lumen-ai 0.1.274 → 0.1.276

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`).
 
@@ -162,7 +164,7 @@ The panel's composer lists what can follow three keys as they are typed. The kit
 
 ### Bearings
 
-Each message the model gets starts with a few lines of bearings: the time now in the person's zone (the panel sends the browser's), UTC, how long since the chat's last message and the app's name. They go in the message, not the system prompt, so the prompt cache holds. A turn's lead (bearings, `plan.lead`, news) goes before the newest message only, so the chat never grows by it; a chat's OpenAI calls carry the chat's id as their cache key. `/compact` in the panel summarizes the chat's older part at once (as past `compactAt()`), without asking the model. An app adds its own lines with `bearings`; each call gets 300 ms, and when it is late or throws its lines are left out.
+Each message the model gets starts with a few lines of bearings: the time now in the person's zone (the panel sends the browser's), UTC, how long since the chat's last message and the app's name. They go in the message, not the system prompt, so the prompt cache holds. A turn's lead (bearings, `plan.lead`, news) stays on the message it went with, so every earlier message is sent exactly as before and read from the prompt cache (a lead taken off the last message changed it, and that message and its tool steps were paid again: 0% read before, 97 to 99% after, on OpenAI). The newest lead says only what changed since the last (`stickyLeads`, `leadDelta`): one line when nothing did, the new and gone lines when some did, and the whole lead the first time, after compaction, or when the change is most of it. A chat's OpenAI calls carry the chat's id as their cache key. `/compact` in the panel summarizes the chat's older part at once (as past `compactAt()`), without asking the model. An app adds its own lines with `bearings`; each call gets 300 ms, and when it is late or throws its lines are left out.
 
 ```ts
 createAssistant({

package/dist/agent/agent.d.ts

@@ -132,6 +132,29 @@ export declare function cardNews(cards: AgentCard[]): string;
 export declare const COMPACT_COMMAND = "/compact";
 /** The messages with `lead` put before the newest message the person wrote. */
 export declare function withLead(messages: ModelMessage[], lead: string | undefined): ModelMessage[];
+/** The leads a chat has sent, kept so each earlier message is sent again exactly as it was. */
+export interface SentLeads {
+    /** Each person's message (`leadKey`) and the lead it went with. */
+    sent: Record<string, string>;
+    /** The last whole lead, which the next one is told against. */
+    last?: string;
+}
+/**
+ * The lead for the newest message, told against the last one: the whole lead the first time, a line
+ * when nothing changed, else only the lines that are new and the lines that went (the whole lead
+ * when that is not much shorter).
+ */
+export declare function leadDelta(last: string | undefined, next: string): string;
+/**
+ * The chat's messages with every lead where it was first sent, and the newest message's lead told
+ * against the last. A provider's prompt cache reuses only earlier messages sent exactly as before:
+ * a lead moved off the last message changed it, and that message and every step after it were
+ * paid again on the next turn. Unchanged context costs one line, changed context only what changed.
+ */
+export declare function stickyLeads(messages: ModelMessage[], kept: SentLeads, lead: string): {
+    messages: ModelMessage[];
+    kept: SentLeads;
+};
 /** One message the person sent, with the page, refs and tier the composer added. */
 export interface AskInput {
     message: string;

package/dist/agent/agent.js

@@ -70,6 +70,68 @@ export function withLead(messages, lead) {
         i -= 1;
     return i < 0 ? messages : leadAt(messages, i, lead);
 }
+/** Leads kept per chat; the oldest go first (a compacted chat no longer has their messages). */
+const LEADS_KEPT = 60;
+const LEAD_SAME = 'Context: as in my last message.\n\n';
+const LEAD_CHANGED = 'Context: what changed since my last message (the rest is as it was).';
+/** A person's message's place among theirs and a hash of its words: the same message turn after turn. */
+function leadKey(n, m) {
+    const text = typeof m.content === 'string'
+        ? m.content
+        : m.content.map((p) => (p.type === 'text' ? p.text : p.type)).join('\n');
+    let h = 0x811c9dc5;
+    for (let i = 0; i < text.length; i++)
+        h = Math.imul(h ^ text.charCodeAt(i), 0x01000193);
+    return `${n}:${(h >>> 0).toString(36)}`;
+}
+/**
+ * The lead for the newest message, told against the last one: the whole lead the first time, a line
+ * when nothing changed, else only the lines that are new and the lines that went (the whole lead
+ * when that is not much shorter).
+ */
+export function leadDelta(last, next) {
+    if (!next || last === undefined)
+        return next;
+    if (last === next)
+        return LEAD_SAME;
+    const was = new Set(last.split('\n'));
+    const is = new Set(next.split('\n'));
+    const added = next.split('\n').filter((l) => l.trim() && !was.has(l));
+    const gone = last.split('\n').filter((l) => l.trim() && !is.has(l));
+    const delta = `${LEAD_CHANGED}\n${added.length ? `Now:\n${added.join('\n')}\n` : ''}${gone.length ? `No longer:\n${gone.join('\n')}\n` : ''}\n`;
+    return delta.length < next.length * 0.6 ? delta : next;
+}
+/**
+ * The chat's messages with every lead where it was first sent, and the newest message's lead told
+ * against the last. A provider's prompt cache reuses only earlier messages sent exactly as before:
+ * a lead moved off the last message changed it, and that message and every step after it were
+ * paid again on the next turn. Unchanged context costs one line, changed context only what changed.
+ */
+export function stickyLeads(messages, kept, lead) {
+    const users = messages.flatMap((m, i) => (m.role === 'user' ? [i] : []));
+    const newest = users.at(-1);
+    const sent = { ...kept.sent };
+    // Told against the last lead only when an earlier message still carries one (not after compaction).
+    let last = users.some((i, n) => i !== newest && sent[leadKey(n, messages[i])])
+        ? kept.last
+        : undefined;
+    let out = messages;
+    users.forEach((i, n) => {
+        const m = messages[i];
+        const key = leadKey(n, m);
+        if (i === newest && sent[key] === undefined && lead) {
+            sent[key] = leadDelta(last, lead);
+            last = lead;
+        }
+        const l = sent[key];
+        if (l)
+            out = leadAt(out, i, l);
+    });
+    const keys = Object.keys(sent);
+    for (const k of keys.slice(0, Math.max(0, keys.length - LEADS_KEPT)))
+        delete sent[k];
+    return { messages: out, kept: { sent, ...(last !== undefined && { last }) } };
+}
 /** The message at `i` (one the person wrote) with `lead` put before what it says. */
 function leadAt(messages, i, lead) {
     const m = messages[i];
@@ -632,6 +694,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 +703,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 +748,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 +779,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;
             },
@@ -759,9 +828,11 @@ export class LumenAgent extends Think {
             this.#turn.lazy = lazy;
         }
         const turn = this.#turn;
-        // The lead goes before the newest message only. Kept on every earlier message it grew the chat
-        // by a whole lead (an app's page, often thousands of tokens) each turn.
-        const cached = cachedTurn(system, withLead(ctx.messages, `${this.#news()}${this.#screenNews()}${plan.lead ?? ''}`));
+        // Each lead stays on the message it went with, so earlier messages are sent as before and read
+        // from the prompt cache; the newest says only what changed since the last (`stickyLeads`).
+        const led = stickyLeads(ctx.messages, this.#get('leads') ?? { sent: {} }, `${this.#news()}${this.#screenNews()}${plan.lead ?? ''}`);
+        this.#put('leads', led.kept);
+        const cached = cachedTurn(system, led.messages);
         return {
             model: this.#model(plan, () => {
                 const fb = plan.fallback;
@@ -769,6 +840,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.276",
   "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.276",
+    "@columenlabs/lumen-ui-types": "0.1.276",
     "agents": "0.32.0",
     "ai": "7.0.162",
     "just-bash": "3.6.0",