@columenlabs/lumen-ai 0.1.178 → 0.1.179

package/README.md

@@ -226,7 +226,9 @@ ctx.waitUntil(meaningStep({ def: notesFind, sql: d1Sql(env.DB), embed, index: en
 
 A ChatGPT plan sign-in is free to the app (`priced` with `free`). Nothing here holds a key or a token: the app passes them per turn.
 
-An app with an `Assistant` gets the whole plan from it: `assistant.agentTurn(caller, { message, tier?, context?, refs?, time_zone? })` returns `{ plan, settle }` with the person's tier and model on whoever pays, the tool groups at their access, the kit's rules, the bearings and the page before the message, `escalate` to a higher tier (its own usage part, inside the same cap) and Claude's advisor. `settle` adds the spend to the payer's month and reports the turn through `onStep`. It throws `AssistantError` when nobody can pay. Drafts, Undo and compaction still run only in `turn`.
+An app with an `Assistant` gets the whole plan from it: `assistant.agentTurn(caller, { message, tier?, context?, refs?, time_zone? })` returns `{ plan, settle }` with the person's tier and model on whoever pays, the tool groups at their access, the kit's rules, the bearings and the page before the message, `escalate` to a higher tier (its own usage part, inside the same cap) and Claude's advisor. `settle` adds the spend to the payer's month and reports the turn through `onStep`. It throws `AssistantError` when nobody can pay.
+
+Drafts and writes are cards in the chat's own storage (`lumen_cards` in the agent's SQLite). A write the person's access only drafts makes an open card and changes nothing. `saveCard(id)` runs it through the app's `applyDraft`, and `dismissCard(id)` drops it. A write made at once is kept for `undoCard(id)` through the app's `undoWrite`. `cards()` lists the cards. The next answer is told how each card ended and what was undone. With an `Assistant`, `applyDraft` is `assistant.runDraft(caller, card)` and `undoWrite` is `assistant.undoChange(caller, card)`. Think compacts the chat past `COMPACT_AT` (150k tokens) on the last answer's model and key, and that spend is added to the next answer.
 
 ```ts
 class Chat extends LumenAgent<Env> {
@@ -237,5 +239,7 @@ class Chat extends LumenAgent<Env> {
     return plan;
   }
   settle(end: AgentTurnEnd) { return this.#settle?.(end) ?? Promise.resolve(); }
+  protected applyDraft(card: AgentCard) { return assistant.runDraft(caller, card); }
+  protected undoWrite(card: AgentCard) { return assistant.undoChange(caller, card); }
 }
 ```

package/dist/agent/agent.d.ts

@@ -11,9 +11,9 @@
  *
  * An `Assistant` gives both: `assistant.agentTurn(caller, input)` returns a plan and its settle.
  */
-import { type ChatResponseResult, type PrepareStepContext, type StepConfig, type StepContext, Think, type ThinkModel, type TurnConfig, type TurnContext } from '@cloudflare/think';
+import { type ChatResponseResult, type PrepareStepContext, type Session, type StepConfig, type StepContext, Think, type ThinkModel, type TurnConfig, type TurnContext } from '@cloudflare/think';
 import type { AssistantEffort, UsagePart } from '@columenlabs/lumen-ui-types/assistant';
-import type { ModelMessage, ToolSet } from 'ai';
+import { type ModelMessage, type ToolSet } from 'ai';
 import type { ModelDef } from '../assistant/models.js';
 import { type ModelKey } from './models.js';
 import { type AiToolsOptions, type OpenedTools, type SourceAt } from './tools.js';
@@ -75,6 +75,23 @@ export interface AgentTurnEnd {
     capped: boolean;
 }
 export declare const CAP_NOTE = "The spend cap for this month is reached: answer now from what you have, in a sentence or two. You can call no more tools.";
+/** A card in the chat: a draft the person saves or dismisses, or a write made at once (Undo). */
+export interface AgentCard {
+    id: string;
+    kind: 'draft' | 'write';
+    group: string;
+    /** The tool's own name, not the `group__tool` the model calls. */
+    tool: string;
+    args: unknown;
+    result?: unknown;
+    status: 'open' | 'saved' | 'dismissed' | 'failed' | 'done' | 'undone';
+    error?: string;
+    at: number;
+}
+/** Past this many tokens in the chat Think summarizes its older part. */
+export declare const COMPACT_AT = 150000;
+/** What the model is told of cards settled and changes undone since its last answer. */
+export declare function cardNews(cards: AgentCard[]): string;
 /** The messages with `lead` put before the newest message the person wrote. */
 export declare function withLead(messages: ModelMessage[], lead: string | undefined): ModelMessage[];
 export declare abstract class LumenAgent<Env = unknown> extends Think<Env> {
@@ -83,6 +100,20 @@ export declare abstract class LumenAgent<Env = unknown> extends Think<Env> {
     abstract plan(turn: TurnContext): Promise<AgentTurnPlan>;
     /** A turn ended: record its spend and how it went. Errors here are logged, never shown. */
     abstract settle(end: AgentTurnEnd): Promise<void>;
+    /** Saves a draft: runs its write as the person. The result is shown and told to the model. */
+    protected applyDraft(_card: AgentCard): Promise<unknown>;
+    /** Takes back a write made at once (Undo). */
+    protected undoWrite(_card: AgentCard): Promise<void>;
+    /** The chat's cards, newest last: drafts and writes made at once (at most 200). */
+    cards(): AgentCard[];
+    /** The person saved a draft: its write runs now. */
+    saveCard(id: string): Promise<AgentCard>;
+    /** The person dismissed a draft: nothing changes. */
+    dismissCard(id: string): AgentCard;
+    /** The person undid a write made at once. */
+    undoCard(id: string): Promise<AgentCard>;
+    /** Think compacts the chat past `COMPACT_AT` tokens, on the last turn's model and key. */
+    configureSession(session: Session): Session;
     /** Never read: `beforeTurn` gives every turn its own model. */
     getModel(): ThinkModel;
     beforeTurn(ctx: TurnContext): Promise<TurnConfig>;

package/dist/agent/agent.js

@@ -13,10 +13,40 @@
  */
 import { anthropic } from '@ai-sdk/anthropic';
 import { Think, } from '@cloudflare/think';
+import { createCompactFunction } from 'agents/sessions';
+import { generateText } from 'ai';
 import { aiModel, turnSettings } from './models.js';
-import { openAiTools } from './tools.js';
+import { openAiTools, } from './tools.js';
 import { UsageMeter } from './usage.js';
 export const CAP_NOTE = 'The spend cap for this month is reached: answer now from what you have, in a sentence or two. You can call no more tools.';
+/** Past this many tokens in the chat Think summarizes its older part. */
+export const COMPACT_AT = 150_000;
+const CARD_NOTE = "A card is on the person's screen; nothing has changed yet. Say what it will do when they save it. The next message tells you how it ended.";
+/** What the model is told of cards settled and changes undone since its last answer. */
+export function cardNews(cards) {
+    const undone = cards.filter((c) => c.kind === 'write' && c.status === 'undone');
+    const ended = cards.filter((c) => c.kind === 'draft' && c.status !== 'open');
+    const line = (c) => `${c.group}/${c.tool} ${JSON.stringify(c.args ?? {}).slice(0, 300)}`;
+    const back = undone.length
+        ? `The person undid these changes you made: ${undone.map(line).join('; ')}. Do not make them again unless asked.\n\n`
+        : '';
+    if (!ended.length)
+        return back;
+    return `${back}Cards since your last answer:\n${ended
+        .map((c) => `- ${line(c)}: ${c.status}${c.error ? ` (${c.error})` : ''}${c.result !== undefined ? ` → ${JSON.stringify(c.result).slice(0, 300)}` : ''}`)
+        .join('\n')}\n\n`;
+}
+const cardOf = (r) => ({
+    id: r.id,
+    kind: r.kind,
+    group: r.grp,
+    tool: r.tool,
+    args: JSON.parse(r.args),
+    ...(r.result === null ? {} : { result: JSON.parse(r.result) }),
+    status: r.status,
+    ...(r.error ? { error: r.error } : {}),
+    at: r.at,
+});
 /** The messages with `lead` put before the newest message the person wrote. */
 export function withLead(messages, lead) {
     if (!lead)
@@ -33,7 +63,121 @@ export function withLead(messages, lead) {
     return [...messages.slice(0, i), { ...m, content }, ...messages.slice(i + 1)];
 }
 export class LumenAgent extends Think {
+    /** Saves a draft: runs its write as the person. The result is shown and told to the model. */
+    applyDraft(_card) {
+        return Promise.reject(new Error('Saving a card is not set up here.'));
+    }
+    /** Takes back a write made at once (Undo). */
+    undoWrite(_card) {
+        return Promise.reject(new Error('This change cannot be undone here.'));
+    }
     #turn = null;
+    /** The last turn's model and key, for compaction between turns. */
+    #last = null;
+    /** Usage spent between turns (compaction), settled with the next turn. */
+    #owed = [];
+    #tabled = false;
+    #cards() {
+        if (!this.#tabled) {
+            this
+                .sql `CREATE TABLE IF NOT EXISTS lumen_cards (id TEXT PRIMARY KEY, kind TEXT NOT NULL, grp TEXT NOT NULL, tool TEXT NOT NULL, args TEXT NOT NULL, result TEXT, status TEXT NOT NULL, error TEXT, told INTEGER NOT NULL DEFAULT 0, at INTEGER NOT NULL)`;
+            this.#tabled = true;
+        }
+    }
+    #addCard(kind, d, result) {
+        this.#cards();
+        const id = `card_${crypto.randomUUID().replaceAll('-', '').slice(0, 16)}`;
+        this
+            .sql `INSERT INTO lumen_cards (id, kind, grp, tool, args, result, status, at) VALUES (${id}, ${kind}, ${d.group}, ${d.tool}, ${JSON.stringify(d.args ?? null)}, ${result === undefined ? null : JSON.stringify(result).slice(0, 20_000)}, ${kind === 'draft' ? 'open' : 'done'}, ${Date.now()})`;
+        return id;
+    }
+    #card(id) {
+        this.#cards();
+        const [r] = this.sql `SELECT * FROM lumen_cards WHERE id = ${id} LIMIT 1`;
+        return r ? cardOf(r) : null;
+    }
+    #setCard(id, status, o = {}) {
+        this
+            .sql `UPDATE lumen_cards SET status = ${status}, result = COALESCE(${o.result === undefined ? null : JSON.stringify(o.result).slice(0, 20_000)}, result), error = ${o.error ?? null}, told = 0 WHERE id = ${id}`;
+    }
+    /** The chat's cards, newest last: drafts and writes made at once (at most 200). */
+    cards() {
+        this.#cards();
+        return this.sql `SELECT * FROM lumen_cards ORDER BY at DESC LIMIT 200`
+            .map(cardOf)
+            .reverse();
+    }
+    /** The person saved a draft: its write runs now. */
+    async saveCard(id) {
+        const c = this.#card(id);
+        if (!c || c.kind !== 'draft')
+            throw new Error('That card is gone.');
+        if (c.status !== 'open')
+            throw new Error(`That card is already ${c.status}.`);
+        try {
+            this.#setCard(id, 'saved', { result: await this.applyDraft(c) });
+        }
+        catch (err) {
+            this.#setCard(id, 'failed', { error: String(err?.message ?? err).slice(0, 300) });
+        }
+        return this.#card(id);
+    }
+    /** The person dismissed a draft: nothing changes. */
+    dismissCard(id) {
+        const c = this.#card(id);
+        if (!c || c.kind !== 'draft')
+            throw new Error('That card is gone.');
+        if (c.status !== 'open')
+            throw new Error(`That card is already ${c.status}.`);
+        this.#setCard(id, 'dismissed');
+        return this.#card(id);
+    }
+    /** The person undid a write made at once. */
+    async undoCard(id) {
+        const c = this.#card(id);
+        if (!c || c.kind !== 'write')
+            throw new Error('That change is gone.');
+        if (c.status === 'undone')
+            throw new Error('That change is already undone.');
+        await this.undoWrite(c);
+        this.#setCard(id, 'undone');
+        return this.#card(id);
+    }
+    /** Cards settled since the model last heard, as its note; marks them told. */
+    #news() {
+        this.#cards();
+        const rows = this
+            .sql `SELECT * FROM lumen_cards WHERE told = 0 AND status IN ('saved', 'dismissed', 'failed', 'undone') ORDER BY at LIMIT 50`;
+        if (!rows.length)
+            return '';
+        for (const r of rows)
+            this.sql `UPDATE lumen_cards SET told = 1 WHERE id = ${r.id}`;
+        return cardNews(rows.map(cardOf));
+    }
+    /** Think compacts the chat past `COMPACT_AT` tokens, on the last turn's model and key. */
+    configureSession(session) {
+        return session
+            .onCompaction(createCompactFunction({ summarize: (prompt) => this.#summarize(prompt) }))
+            .compactAfter(COMPACT_AT);
+    }
+    async #summarize(prompt) {
+        const last = this.#last;
+        if (!last)
+            throw new Error('No model to compact with until the next answer.');
+        const { plan } = last;
+        const meter = new UsageMeter(plan.model, `${plan.label} · compact`, !!plan.key.plan);
+        this.#owed.push(meter);
+        const r = await generateText({
+            model: aiModel(plan.model, plan.key, {
+                ...(plan.fetch ? { fetch: plan.fetch } : {}),
+                name: this.constructor.name,
+            }),
+            prompt,
+            ...turnSettings(plan.model, { effort: 'default', out: 4000, plan: !!plan.key.plan }),
+        });
+        meter.add(r.usage);
+        return r.text;
+    }
     /** Never read: `beforeTurn` gives every turn its own model. */
     getModel() {
         return '@cf/none';
@@ -41,10 +185,16 @@ export class LumenAgent extends Think {
     async beforeTurn(ctx) {
         await this.#close();
         const plan = await this.plan(ctx);
-        const opened = await openAiTools(plan.sources, plan.tools ?? {});
+        this.#last = { plan };
+        const opened = await openAiTools(plan.sources, {
+            draft: async (d) => ({ card: this.#addCard('draft', d), note: CARD_NOTE }),
+            wrote: async (w) => this.#addCard('write', w, w.result),
+            ...plan.tools,
+        });
         const free = !!plan.key.plan;
         const main = new UsageMeter(plan.model, plan.label, free);
-        const meters = [main];
+        const meters = [main, ...this.#owed];
+        this.#owed = [];
         const advice = plan.advisor
             ? new UsageMeter(plan.advisor.model, plan.advisor.label, free)
             : undefined;
@@ -84,7 +234,7 @@ export class LumenAgent extends Think {
                 name: this.constructor.name,
             }),
             instructions: system,
-            messages: withLead(ctx.messages, plan.lead),
+            messages: withLead(ctx.messages, `${this.#news()}${plan.lead ?? ''}`),
             tools: { ...opened.tools, ...more, ...advisor },
             ...(plan.first ? { toolChoice: { type: 'tool', toolName: plan.first } } : {}),
             maxSteps: plan.maxSteps ?? 8,

package/dist/agent/tools.d.ts

@@ -23,6 +23,10 @@ export interface DraftCall {
 export interface AiToolsOptions {
     /** A draft's card was made: return what the model is told (its id, "a card is on screen"). */
     draft?: (d: DraftCall) => Promise<unknown>;
+    /** A write ran at once: what it did, for Undo. Its answer is added to the model's result. */
+    wrote?: (w: DraftCall & {
+        result: unknown;
+    }) => Promise<unknown>;
     /** Every call's outcome, for the app's meter: shapes only. */
     called?: (c: {
         group: string;

package/dist/agent/tools.js

@@ -49,7 +49,13 @@ export async function openAiTools(sources, o = {}) {
                         const out = await open.call(def.name, args);
                         o.called?.({ group: s.group, tool: def.name, ok: true, ms: Date.now() - t0 });
                         const text = typeof out === 'string' ? out : JSON.stringify(out);
-                        return text.length > max ? `${text.slice(0, max)} …(cut)` : out;
+                        const shown = text.length > max ? `${text.slice(0, max)} …(cut)` : out;
+                        if (kind === 'write' && o.wrote) {
+                            const change = await o.wrote({ group: s.group, tool: def.name, args, result: out });
+                            if (change !== undefined)
+                                return { result: shown, change };
+                        }
+                        return shown;
                     }
                     catch (err) {
                         o.called?.({ group: s.group, tool: def.name, ok: false, ms: Date.now() - t0 });

package/dist/assistant/engine.d.ts

@@ -227,6 +227,22 @@ export declare class Assistant {
         plan: AgentTurnPlan;
         settle: (end: AgentTurnEnd) => Promise<void>;
     }>;
+    /**
+     * Saves a Think chat's draft card (`LumenAgent.applyDraft`): its group's write runs as the person,
+     * while that group is still on Read + draft or Read + write.
+     */
+    runDraft(caller: Caller, card: {
+        group: string;
+        tool: string;
+        args: unknown;
+    }): Promise<unknown>;
+    /** Takes back a Think chat's write made at once (`LumenAgent.undoWrite`) through its group's `undo`. */
+    undoChange(caller: Caller, card: {
+        group: string;
+        tool: string;
+        args: unknown;
+        result?: unknown;
+    }): Promise<void>;
     /** The escalate tool of a Think turn: one task to a higher tier, its memo back. */
     private agentEscalate;
     status(caller: Caller): Promise<AssistantStatus>;

package/dist/assistant/engine.js

@@ -487,6 +487,40 @@ export class Assistant {
         };
         return { plan, settle };
     }
+    /**
+     * Saves a Think chat's draft card (`LumenAgent.applyDraft`): its group's write runs as the person,
+     * while that group is still on Read + draft or Read + write.
+     */
+    async runDraft(caller, card) {
+        const g = this.groupById(card.group);
+        const p = await this.state.person(caller.id);
+        const access = g ? this.access(p, g) : 'off';
+        if (access !== 'draft' && access !== 'write')
+            throw new AssistantError('Its tools are no longer on Read + draft or Read + write in Settings ▸ Tools.', 'off', 409);
+        const sources = (await this.sourcesOf(caller, p)).filter((x) => x.group === card.group);
+        for (const x of sources) {
+            const open = await x.source();
+            try {
+                const def = open.tools.find((d) => d.name === card.tool);
+                if (!def)
+                    continue;
+                if (def.read)
+                    throw new AssistantError('That card is not a change.', 'not_write', 400);
+                return await withDeadline(card.tool, 60_000, open.call(card.tool, card.args));
+            }
+            finally {
+                await open.close().catch(() => undefined);
+            }
+        }
+        throw new AssistantError('That tool is gone.', 'not_found', 404);
+    }
+    /** Takes back a Think chat's write made at once (`LumenAgent.undoWrite`) through its group's `undo`. */
+    async undoChange(caller, card) {
+        const g = this.groupById(card.group);
+        if (!g?.undo)
+            throw new AssistantError('That change cannot be undone here.', 'no_undo', 400);
+        await withDeadline(`Undo ${card.tool}`, 60_000, g.undo(caller, { tool: card.tool, args: card.args, result: card.result }));
+    }
     /** The escalate tool of a Think turn: one task to a higher tier, its memo back. */
     agentEscalate(tt, c) {
         const reach = this.above(c.main.tier);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@columenlabs/lumen-ai",
-  "version": "0.1.178",
+  "version": "0.1.179",
   "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",
@@ -48,8 +48,8 @@
     "@ai-sdk/openai": "4.0.108",
     "@anthropic-ai/sdk": "0.133.0",
     "@cloudflare/think": "0.23.0",
-    "@columenlabs/lumen-ops": "0.1.178",
-    "@columenlabs/lumen-ui-types": "0.1.178",
+    "@columenlabs/lumen-ops": "0.1.179",
+    "@columenlabs/lumen-ui-types": "0.1.179",
     "agents": "0.32.0",
     "ai": "7.0.162",
     "just-bash": "3.6.0",