@columenlabs/lumen-ai 0.1.276 → 0.1.278

package/dist/agent/agent.d.ts

@@ -177,6 +177,8 @@ export interface AskInput {
     outcomes?: AssistantScreenOutcome[];
     /** The person kept this message in this chat after a fresh chat was offered (`offerFresh`). */
     stay?: boolean;
+    /** How many images went with the message (set by the agent: the images go in its parts). */
+    image_count?: number;
 }
 /** 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;

package/dist/agent/agent.js

@@ -18,7 +18,7 @@ import { ASSISTANT_IMAGES_MAX, ASSISTANT_IMAGE_CHARS, ASSISTANT_IMAGE_TYPES, ASS
 import { createCompactFunction } from 'agents/sessions';
 import { generateText } from 'ai';
 import { CONNECTOR_GROUP, checkConnectorUrl, connectorGroup, connectorId, connectorSource, } from './connectors.js';
-import { aiModel, cachedTurn, planFallback, turnSettings } from './models.js';
+import { aiModel, cachedTurn, planFallback, prefixCacheKey, turnSettings, } from './models.js';
 import { screenMapOf, screenNews, screenOutcomesOf, screenRules, screenTool, } from './screen.js';
 import { LAZY_AT, TOOL_SEARCH, lazyTools, usedTools } from './search.js';
 import { chunkEvents, itemsOf, shownTitle, } from './stream.js';
@@ -413,7 +413,12 @@ export class LumenAgent extends Think {
         this.#steered = [];
         // The images go in the message's parts; the turn's plan reads the rest.
         const { images: _images, ...asked } = input;
-        this.#input = { ...asked, ...(map ? { screen: map } : {}) };
+        const pictures = imageParts(input.images);
+        this.#input = {
+            ...asked,
+            ...(map ? { screen: map } : {}),
+            ...(pictures.length ? { image_count: pictures.length } : {}),
+        };
         if (!map)
             delete this.#input.screen;
         let failed = false;
@@ -424,7 +429,7 @@ export class LumenAgent extends Think {
                 parts: [
                     ...(quote ? [{ type: 'text', text: quoteLead(quote) }] : []),
                     { type: 'text', text: input.message },
-                    ...imageParts(input.images),
+                    ...pictures,
                 ],
                 metadata: meta,
             }, {
@@ -854,7 +859,10 @@ export class LumenAgent extends Think {
                 effort: plan.effort ?? 'default',
                 ...(plan.out ? { out: plan.out } : {}),
                 plan: free,
-                cacheKey: this.name,
+                // Named for how the prompt starts, so a new chat reads its instructions and tools from the cache.
+                cacheKey: prefixCacheKey(plan.model.id, system, Object.keys(tools)
+                    .filter((n) => !lazy || lazy.active().includes(n))
+                    .join(',')),
             }),
         };
     }

package/dist/agent/models.d.ts

@@ -35,14 +35,21 @@ export declare function cachedTurn(instructions: string, messages: ModelMessage[
     messages: ModelMessage[];
 };
 /**
- * OpenAI's prompt cache key for one chat or run: calls with the same key go to the same cache, so
- * a long prompt's start is read from it instead of paid again. A ChatGPT plan sign-in caches
- * nothing without one. At most 64 characters.
+ * OpenAI's prompt cache key: calls with the same key go to the same cache, so a long prompt's start
+ * is read from it instead of paid again. A ChatGPT plan sign-in caches nothing without one. At most
+ * 64 characters.
  */
 export declare const promptCacheKey: (key: string) => string;
+/**
+ * A cache key named for what a prompt starts with (its model, instructions and tools), not for
+ * one chat or run: a new chat or run that starts the same way reads that start from the cache
+ * (a key per chat read 0 of a new chat's 5.9k-token start; one key for the start read 99.7%, our
+ * key, 2026-11-14). The key only routes; what is read is still only the exact same start.
+ */
+export declare function prefixCacheKey(...parts: (string | undefined)[]): string;
 /**
  * A tier's effort and output cap as a turn's settings, with the prompt cache on: Claude's
- * breakpoint, and OpenAI's cache key when `cacheKey` names the chat.
+ * breakpoint, and OpenAI's cache key (`prefixCacheKey`) when `cacheKey` is given.
  */
 export declare function turnSettings(model: ModelDef, o: {
     effort: AssistantEffort;

package/dist/agent/models.js

@@ -71,9 +71,51 @@ export function planFetch(base = fetch, name = 'Assistant') {
                 status: res.status,
                 body: (await res.clone().text()).slice(0, 500),
             }));
-        return res.ok && !streamed ? whole(res, init?.signal) : res;
+        if (!res.ok || !res.body)
+            return res;
+        // The plan's own usage numbers, as it sent them (cache reads included), one line a call.
+        const [mine, theirs] = res.body.tee();
+        void logPlanUsage(theirs, String(body.model ?? ''), typeof body.prompt_cache_key === 'string');
+        const seen = new Response(mine, {
+            status: res.status,
+            statusText: res.statusText,
+            headers: res.headers,
+        });
+        return streamed ? seen : whole(seen, init?.signal);
     };
 }
+/**
+ * Reads a plan's streamed answer for its final usage and logs it as sent (`assistant_plan_usage`):
+ * whether a plan reads its prompt from the cache shows in its own numbers. Never throws.
+ */
+async function logPlanUsage(stream, model, keyed) {
+    try {
+        const reader = stream.getReader();
+        const text = new TextDecoder();
+        let buf = '';
+        let usage;
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buf += text.decode(value, { stream: true });
+            const lines = buf.split('\n');
+            buf = lines.pop() ?? '';
+            for (const line of lines) {
+                if (!line.startsWith('data:') || !line.includes('"usage"'))
+                    continue;
+                const e = JSON.parse(line.slice(5));
+                if (e.type === 'response.completed' || e.type === 'response.incomplete')
+                    usage = e.response?.usage;
+            }
+        }
+        if (usage)
+            console.log(JSON.stringify({ event: 'assistant_plan_usage', model, keyed, usage }));
+    }
+    catch {
+        // A log line is never worth a failed answer.
+    }
+}
 /**
  * A streamed Responses answer as the one JSON response a request that was not streamed expects:
  * the final `response.completed` (or `response.incomplete`), with the items from each
@@ -178,14 +220,30 @@ export function cachedTurn(instructions, messages) {
     };
 }
 /**
- * OpenAI's prompt cache key for one chat or run: calls with the same key go to the same cache, so
- * a long prompt's start is read from it instead of paid again. A ChatGPT plan sign-in caches
- * nothing without one. At most 64 characters.
+ * OpenAI's prompt cache key: calls with the same key go to the same cache, so a long prompt's start
+ * is read from it instead of paid again. A ChatGPT plan sign-in caches nothing without one. At most
+ * 64 characters.
  */
 export const promptCacheKey = (key) => key.slice(0, 64);
+/**
+ * A cache key named for what a prompt starts with (its model, instructions and tools), not for
+ * one chat or run: a new chat or run that starts the same way reads that start from the cache
+ * (a key per chat read 0 of a new chat's 5.9k-token start; one key for the start read 99.7%, our
+ * key, 2026-11-14). The key only routes; what is read is still only the exact same start.
+ */
+export function prefixCacheKey(...parts) {
+    const of = parts.filter(Boolean).join('\u0000');
+    let h = 0x811c9dc5;
+    let g = 0x01000193;
+    for (let i = 0; i < of.length; i++) {
+        h = Math.imul(h ^ of.charCodeAt(i), 0x01000193);
+        g = Math.imul(g ^ of.charCodeAt(i), 0x85ebca6b);
+    }
+    return `lumen-${(h >>> 0).toString(36)}${(g >>> 0).toString(36)}`;
+}
 /**
  * A tier's effort and output cap as a turn's settings, with the prompt cache on: Claude's
- * breakpoint, and OpenAI's cache key when `cacheKey` names the chat.
+ * breakpoint, and OpenAI's cache key (`prefixCacheKey`) when `cacheKey` is given.
  */
 export function turnSettings(model, o) {
     const out = o.plan || !o.out ? {} : { maxOutputTokens: o.out };

package/dist/assistant/engine.d.ts

@@ -278,6 +278,8 @@ export interface AgentTurnInput {
     tier?: string;
     /** The browser's IANA zone, for the bearings. */
     time_zone?: string;
+    /** How many images went with the message, counted in the chat's usage (`UsageEntry.images`). */
+    image_count?: number;
     /** When the chat's last message was, for "since you last asked". */
     last_at?: number;
     /**

package/dist/assistant/engine.js

@@ -66,7 +66,7 @@ function claudeHistory(history) {
         };
     });
 }
-/** OpenAI's prompt cache key for one person's task or run: a short, stable hash of `of`. */
+/** OpenAI's prompt cache key: a short, stable hash of `of` (how the prompt starts). */
 function cacheKey(of) {
     let h = 0x811c9dc5;
     let g = 0x01000193;
@@ -549,6 +549,9 @@ export class Assistant {
                     id: `chat:${input.chat}`,
                     kind: 'chat',
                     title: message.split('\n')[0] || 'Chat',
+                    turns: 1,
+                    images: input.image_count ?? 0,
+                    refs: input.refs?.length ?? 0,
                     own_usd: ownKeyUsd(paying, onPayer),
                     own_plan_calls: ownPlanCalls(paying, onPayer),
                     own_plan_usd: ownPlanUsd(paying, onPayer),
@@ -1276,7 +1279,10 @@ 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 ?? ''}`), o.history));
+                ({ text, cut } = await this.openaiOnce(clients, s, o.system, parts, max, o.signal, o.images, o.effort, 
+                // Named for how the prompt starts (the person, task and instructions), not the run, so
+                // the next run of the same task reads that start from the cache.
+                cacheKey(`${caller.id}:${o.task}:${s.model.id}:${o.system ?? ''}`), o.history));
             }
             else if (clients.anthropic) {
                 // Streamed and read whole: a long answer (minutes at a high cap) keeps its connection alive,

package/dist/assistant/state.d.ts

@@ -316,6 +316,11 @@ export declare class State {
         kind: UsageEntry['kind'];
         task?: string;
         title: string;
+        /** Messages the person sent with this use (1 a chat turn; a run's calls send none). */
+        turns?: number;
+        /** Images and picks (refs) that went with those messages. */
+        images?: number;
+        refs?: number;
         own_usd?: number;
         own_plan_calls?: number;
         own_plan_usd?: number;

package/dist/assistant/state.js

@@ -429,6 +429,9 @@ export class State {
             const own = (prev?.own_usd ?? 0) + (e.own_usd ?? 0);
             const plan = (prev?.own_plan_calls ?? 0) + (e.own_plan_calls ?? 0);
             const planUsd = (prev?.own_plan_usd ?? 0) + (e.own_plan_usd ?? 0);
+            const turns = (prev?.turns ?? 0) + (e.turns ?? 0);
+            const images = (prev?.images ?? 0) + (e.images ?? 0);
+            const refs = (prev?.refs ?? 0) + (e.refs ?? 0);
             entries.unshift({
                 id: e.id,
                 kind: e.kind,
@@ -444,6 +447,9 @@ export class State {
                 ...(own > 0 ? { own_usd: own } : {}),
                 ...(plan > 0 ? { own_plan_calls: plan } : {}),
                 ...(planUsd > 0 ? { own_plan_usd: planUsd } : {}),
+                ...(turns > 0 ? { turns } : {}),
+                ...(images > 0 ? { images } : {}),
+                ...(refs > 0 ? { refs } : {}),
                 parts: merged,
             });
             return { entries: entries.slice(0, USAGE_KEPT) };

package/package.json

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