@columenlabs/lumen-ai 0.1.275 → 0.1.276

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

@@ -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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@columenlabs/lumen-ai",
-  "version": "0.1.275",
+  "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.275",
-    "@columenlabs/lumen-ui-types": "0.1.275",
+    "@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",