@columenlabs/lumen-ai 0.1.275 → 0.1.277

package/README.md

@@ -164,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

@@ -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';
@@ -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];
@@ -766,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;
@@ -790,7 +854,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.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;
@@ -1276,7 +1276,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/package.json

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