@columenlabs/lumen-ai 0.1.181 → 0.1.183

package/README.md

@@ -234,11 +234,14 @@ Drafts and writes are cards in the chat's own storage (`lumen_cards` in the agen
 
 **Lazy tools.** Past `LAZY_AT` (30) tools, a turn sends the model its core tools and `tool_search`, with one catalog line per group in the instructions. By default the core tools are the apps' finds, the hand off and the advisor. `plan.lazy` sets `{ at, core }`. A search matches the words in a tool's name and description and turns on up to 8 tools from the next step on.
 
+**The panel.** `LumenAssistant` reads a Think chat with no change. `ask(input, sink)` runs one answer and sends the panel's own events (`AssistantEvent`: the chat, the text, each tool line, cards, hand-off sections, advice, the use) to `sink`. The app's `POST /chat` returns `askResponse((sink) => chat.ask(input, sink), { signal, stop: () => chat.stop() })`, the same server-sent events `assistantRoutes` sends. `view()` gives a stored chat as the panel's items, and `usage()` gives the chat's use so far. A card's id is its tool call's, so the panel's Save, Dismiss and Undo go to `saveCard`, `dismissCard` and `undoCard`. The app keeps the list of chats, and each chat is its own agent, such as a facet of the person's store. `chunkEvents` and `itemsOf` are the mapping, for an app that streams some other way.
+
 ```ts
 class Chat extends LumenAgent<Env> {
   #settle?: (end: AgentTurnEnd) => Promise<void>;
   async plan(turn: TurnContext) {
-    const { plan, settle } = await assistant.agentTurn(caller, { message: lastText(turn), ...turn.body });
+    // this.input: what the person sent (message, page, refs, tier, time zone).
+    const { plan, settle } = await assistant.agentTurn(caller, this.input ?? { message: '' });
     this.#settle = settle;
     return plan;
   }

package/dist/agent/agent.d.ts

@@ -12,7 +12,7 @@
  * An `Assistant` gives both: `assistant.agentTurn(caller, input)` returns a plan and its settle.
  */
 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 { AssistantChat, AssistantEffort, AssistantEvent, AssistantRefNote, ChatUsage, UsagePart } from '@columenlabs/lumen-ui-types/assistant';
 import { type ModelMessage, type ToolSet } from 'ai';
 import type { ModelDef } from '../assistant/models.js';
 import { type AgentConnector, type ConnectorAt } from './connectors.js';
@@ -102,6 +102,23 @@ export declare const COMPACT_AT = 150000;
 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[];
+/** One message the person sent, with the page, refs and tier the composer added. */
+export interface AskInput {
+    message: string;
+    context?: {
+        label: string;
+        note?: unknown;
+    };
+    refs?: AssistantRefNote[];
+    tier?: string;
+    time_zone?: string;
+}
+/** Where an answer's events go: the app's route, over RPC. */
+export interface AskSink {
+    event(e: AssistantEvent): void | Promise<void>;
+}
+/** Usage parts added up: same label, one part. */
+export declare function chatUsage(parts: UsagePart[], context?: number): ChatUsage;
 export declare abstract class LumenAgent<Env = unknown> extends Think<Env> {
     #private;
     /** The turn the app runs now. Throw to refuse it (no key, no money); the error is shown. */
@@ -114,6 +131,19 @@ export declare abstract class LumenAgent<Env = unknown> extends Think<Env> {
     protected undoWrite(_card: AgentCard): Promise<void>;
     /** Connectors' tools join a turn through `plan.connectors`, at the person's access. */
     includeMcpTools: boolean;
+    /** What the person sent with the message this turn answers (page, refs, tier, zone). */
+    protected get input(): AskInput | null;
+    /** The chat's running use: every answer's parts added up, and the last context size. */
+    usage(): ChatUsage;
+    /** The chat as the panel reads it: title, last message, items and use. */
+    view(id?: string): Promise<AssistantChat>;
+    /** Stops the answer running now; what was said so far is kept. */
+    stop(): void;
+    /**
+     * One answer to `input`, its events sent to `sink` in the panel's words: the chat's title, the
+     * text, each tool line and card, then its use. The app's route calls it over RPC.
+     */
+    ask(input: AskInput, sink: AskSink): Promise<void>;
     /** The person's connectors, with their state and tool counts. */
     connectors(): AgentConnector[];
     /** Adds a connector by its https address; the answer says where to sign in when it asks. */

package/dist/agent/agent.js

@@ -18,6 +18,7 @@ import { generateText } from 'ai';
 import { CONNECTOR_GROUP, checkConnectorUrl, connectorGroup, connectorId, connectorSource, } from './connectors.js';
 import { aiModel, turnSettings } from './models.js';
 import { LAZY_AT, TOOL_SEARCH, lazyTools } from './search.js';
+import { chunkEvents, itemsOf } from './stream.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.';
@@ -64,6 +65,34 @@ export function withLead(messages, lead) {
         : [{ type: 'text', text: lead }, ...m.content];
     return [...messages.slice(0, i), { ...m, content }, ...messages.slice(i + 1)];
 }
+/** Usage parts added up: same label, one part. */
+export function chatUsage(parts, context) {
+    const by = new Map();
+    for (const p of parts) {
+        const was = by.get(p.label);
+        by.set(p.label, was
+            ? {
+                label: p.label,
+                calls: was.calls + p.calls,
+                in: was.in + p.in,
+                read: was.read + p.read,
+                out: was.out + p.out,
+                usd: was.usd + p.usd,
+            }
+            : { ...p });
+    }
+    const all = [...by.values()];
+    const sum = (k) => all.reduce((a, p) => a + p[k], 0);
+    return {
+        calls: sum('calls'),
+        in: sum('in'),
+        read: sum('read'),
+        out: sum('out'),
+        usd: sum('usd'),
+        parts: all,
+        ...(context ? { context } : {}),
+    };
+}
 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) {
@@ -76,6 +105,113 @@ export class LumenAgent extends Think {
     /** Connectors' tools join a turn through `plan.connectors`, at the person's access. */
     includeMcpTools = false;
     #turn = null;
+    #input = null;
+    #metaTabled = false;
+    /** What the person sent with the message this turn answers (page, refs, tier, zone). */
+    get input() {
+        return this.#input;
+    }
+    #meta() {
+        if (!this.#metaTabled) {
+            this.sql `CREATE TABLE IF NOT EXISTS lumen_chat (k TEXT PRIMARY KEY, v TEXT NOT NULL)`;
+            this.#metaTabled = true;
+        }
+    }
+    #get(k) {
+        this.#meta();
+        const [r] = this.sql `SELECT v FROM lumen_chat WHERE k = ${k} LIMIT 1`;
+        return r ? JSON.parse(r.v) : null;
+    }
+    #put(k, v) {
+        this.#meta();
+        this.sql `INSERT OR REPLACE INTO lumen_chat (k, v) VALUES (${k}, ${JSON.stringify(v)})`;
+    }
+    /** The chat's running use: every answer's parts added up, and the last context size. */
+    usage() {
+        return this.#get('usage') ?? chatUsage([]);
+    }
+    /** The chat as the panel reads it: title, last message, items and use. */
+    async view(id = this.name) {
+        return {
+            id,
+            title: this.#get('title') ?? '',
+            at: this.#get('at') ?? 0,
+            items: itemsOf(await this.getMessages(), this.cards()),
+            usage: this.usage(),
+        };
+    }
+    /** Stops the answer running now; what was said so far is kept. */
+    stop() {
+        this.cancelAllChats();
+    }
+    /**
+     * One answer to `input`, its events sent to `sink` in the panel's words: the chat's title, the
+     * text, each tool line and card, then its use. The app's route calls it over RPC.
+     */
+    async ask(input, sink) {
+        const at = Date.now();
+        this.#capped = false;
+        let title = this.#get('title');
+        if (!title) {
+            title = input.message.replace(/\s+/g, ' ').trim().slice(0, 60);
+            this.#put('title', title);
+        }
+        this.#put('at', at);
+        await sink.event({ event: 'chat', data: { id: this.name, title } });
+        const meta = {
+            at,
+            ...(input.context ? { context: { label: input.context.label } } : {}),
+            ...(input.refs?.length ? { refs: input.refs } : {}),
+            ...(input.tier ? { tier: input.tier } : {}),
+        };
+        const map = chunkEvents({
+            ...(this.#last?.plan.advisor ? { advisor: this.#last.plan.advisor.label } : {}),
+            cards: () => new Map(this.cards().map((c) => [c.id, c])),
+            kindOf: (n) => this.#turn?.tools.info.find((i) => i.name === n)?.kind,
+        });
+        this.#input = input;
+        let failed = false;
+        try {
+            await this.chat({
+                id: `u_${crypto.randomUUID().replaceAll('-', '').slice(0, 16)}`,
+                role: 'user',
+                parts: [{ type: 'text', text: input.message }],
+                metadata: meta,
+            }, {
+                onStart: () => undefined,
+                onEvent: async (json) => {
+                    let chunk;
+                    try {
+                        chunk = JSON.parse(json);
+                    }
+                    catch {
+                        return;
+                    }
+                    for (const e of map(chunk))
+                        await sink.event(e);
+                },
+                onDone: () => undefined,
+                onError: async (message) => {
+                    failed = true;
+                    await sink.event({ event: 'error', data: { message: message.slice(0, 500) } });
+                },
+            });
+        }
+        catch (err) {
+            if (!failed)
+                await sink.event({
+                    event: 'error',
+                    data: { message: String(err?.message ?? err).slice(0, 500) },
+                });
+        }
+        finally {
+            this.#input = null;
+        }
+        if (this.#capped)
+            await sink.event({ event: 'stopped', data: { reason: 'cap' } });
+        await sink.event({ event: 'done', data: { id: this.name, usage: this.usage() } });
+    }
+    #capped = false;
     /** The last turn's model and key, for compaction between turns. */
     #last = null;
     /** Usage spent between turns (compaction), settled with the next turn. */
@@ -90,9 +226,9 @@ export class LumenAgent extends Think {
     }
     #addCard(kind, d, result) {
         this.#cards();
-        const id = `card_${crypto.randomUUID().replaceAll('-', '').slice(0, 16)}`;
+        const id = d.call ?? `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()})`;
+            .sql `INSERT OR REPLACE 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) {
@@ -377,10 +513,13 @@ export class LumenAgent extends Think {
             return;
         this.#turn = null;
         await t.tools.close();
+        const parts = t.meters.map((m) => m.part()).filter((p) => p.calls);
+        this.#capped = t.capped;
+        this.#put('usage', chatUsage([...this.usage().parts, ...parts], t.context));
         try {
             await this.settle({
                 outcome,
-                parts: t.meters.map((m) => m.part()).filter((p) => p.calls),
+                parts,
                 ...(t.context ? { context: t.context } : {}),
                 steps: t.steps,
                 ms: Date.now() - t.t0,

package/dist/agent/index.d.ts

@@ -6,6 +6,8 @@
 export * from './agent.js';
 export * from './connectors.js';
 export * from './models.js';
+export * from './respond.js';
 export * from './search.js';
+export * from './stream.js';
 export * from './tools.js';
 export * from './usage.js';

package/dist/agent/index.js

@@ -6,6 +6,8 @@
 export * from './agent.js';
 export * from './connectors.js';
 export * from './models.js';
+export * from './respond.js';
 export * from './search.js';
+export * from './stream.js';
 export * from './tools.js';
 export * from './usage.js';

package/dist/agent/respond.d.ts

@@ -0,0 +1,10 @@
+import type { AskSink } from './agent.js';
+export interface AskResponseOptions {
+    /** The request's signal: when the person stops or leaves, `stop` ends the answer. */
+    signal?: AbortSignal;
+    stop?: () => unknown;
+    /** Keeps the answer running past the response (a Worker's `ctx.waitUntil`). */
+    waitUntil?: (p: Promise<unknown>) => void;
+}
+/** Streams `run`'s events as `event:` / `data:` blocks; a failure ends in an `error` event. */
+export declare function askResponse(run: (sink: AskSink) => Promise<void>, o?: AskResponseOptions): Response;

package/dist/agent/respond.js

@@ -0,0 +1,44 @@
+/** Streams `run`'s events as `event:` / `data:` blocks; a failure ends in an `error` event. */
+export function askResponse(run, o = {}) {
+    const { readable, writable } = new TransformStream();
+    const writer = writable.getWriter();
+    const enc = new TextEncoder();
+    let open = true;
+    const write = async (e) => {
+        if (!open)
+            return;
+        try {
+            await writer.write(enc.encode(`event: ${e.event}\ndata: ${JSON.stringify(e.data)}\n\n`));
+        }
+        catch {
+            open = false;
+        }
+    };
+    o.signal?.addEventListener('abort', () => {
+        open = false;
+        void Promise.resolve(o.stop?.()).catch(() => undefined);
+    });
+    const work = (async () => {
+        try {
+            await run({ event: write });
+        }
+        catch (err) {
+            await write({
+                event: 'error',
+                data: { message: String(err?.message ?? err).slice(0, 500) },
+            });
+        }
+        finally {
+            open = false;
+            await writer.close().catch(() => undefined);
+        }
+    })();
+    o.waitUntil?.(work);
+    return new Response(readable, {
+        headers: {
+            'content-type': 'text/event-stream; charset=utf-8',
+            'cache-control': 'no-store',
+            'x-accel-buffering': 'no',
+        },
+    });
+}

package/dist/agent/stream.d.ts

@@ -0,0 +1,43 @@
+/**
+ * A Think chat in the panel's words: the AI SDK's UI message stream (what `chat()` sends) as the
+ * panel's `AssistantEvent`s, and a stored chat's messages and cards as its `ChatItem`s. The panel
+ * (`@columenlabs/lumen-ui`'s `LumenAssistant`) reads a Think chat the same way as before.
+ */
+import type { AssistantEvent, AssistantRefNote, ChatItem } from '@columenlabs/lumen-ui-types/assistant';
+import type { AgentCard } from './agent.js';
+/** A tool's name as a line's title: `notes__find_notes` → `find notes`. */
+export declare function stepTitle(name: string): string;
+/**
+ * Turns UI message chunks into the panel's events, one chunk at a time. `cards` says how a draft
+ * or write ended (a card's id is its tool call's). `advisor` names the advice part.
+ */
+export declare function chunkEvents(o?: {
+    advisor?: string;
+    cards?: () => Map<string, AgentCard>;
+    /** A tool's kind this turn: a draft shows as its card only, with no line before it. */
+    kindOf?: (name: string) => 'read' | 'draft' | 'write' | undefined;
+}): (chunk: {
+    type: string;
+    [k: string]: unknown;
+}) => AssistantEvent[];
+/** A stored UI message, as much of it as a chat's items need. */
+interface StoredMessage {
+    role: string;
+    parts: {
+        type: string;
+        [k: string]: unknown;
+    }[];
+    metadata?: unknown;
+}
+/** A user message's extras, kept in its metadata by `LumenAgent.ask`. */
+export interface AskMeta {
+    at?: number;
+    context?: {
+        label: string;
+    };
+    refs?: AssistantRefNote[];
+    tier?: string;
+}
+/** A stored chat as the panel's items: the messages in order, each tool call as it ended. */
+export declare function itemsOf(messages: StoredMessage[], cards: AgentCard[]): ChatItem[];
+export {};

package/dist/agent/stream.js

@@ -0,0 +1,180 @@
+import { rowCount } from '../assistant/tools.js';
+/** A tool's name as a line's title: `notes__find_notes` → `find notes`. */
+export function stepTitle(name) {
+    const own = name.includes('__') ? name.slice(name.indexOf('__') + 2) : name;
+    return own.replace(/_/g, ' ');
+}
+const obj = (v) => v && typeof v === 'object' && !Array.isArray(v) ? v : null;
+/** What one finished tool call shows as: a line, a card, a hand-off section or nothing. */
+function settledCall(id, c, out, ms, cards) {
+    const o = obj(out.output);
+    const card = cards.get(id);
+    if (card?.kind === 'draft' || (o && typeof o.card === 'string')) {
+        const draft = {
+            kind: 'draft',
+            id,
+            tool: c.name,
+            title: stepTitle(c.name),
+            args: card?.args ?? c.input ?? null,
+            status: card && card.status !== 'done' && card.status !== 'undone' ? card.status : 'open',
+            ...(card?.result !== undefined ? { result: card.result } : {}),
+            ...(card?.error ? { error: card.error } : {}),
+        };
+        return [{ event: 'draft', data: draft }];
+    }
+    const h = obj(o?.handoff);
+    if (h && typeof h.tier === 'string' && typeof o?.memo === 'string') {
+        const task = String(obj(c.input)?.task ?? '');
+        return [
+            {
+                event: 'handoff',
+                data: { kind: 'handoff', tier: h.tier, label: h.label, task, why: h.why },
+            },
+            { event: 'handoff_done', data: { usage: h.usage } },
+        ];
+    }
+    const error = out.error ?? (o && typeof o.error === 'string' ? o.error : undefined);
+    const rows = rowCount(o && 'result' in o ? o.result : out.output);
+    const step = {
+        kind: 'step',
+        id,
+        tool: c.name,
+        title: stepTitle(c.name),
+        ok: !error,
+        ms,
+        ...(rows !== undefined && !error ? { rows } : {}),
+        ...(error ? { error: error.slice(0, 300) } : {}),
+        ...(card?.kind === 'write' || (o && typeof o.change === 'string')
+            ? { write: { undo: true, status: card?.status === 'undone' ? 'undone' : 'done' } }
+            : {}),
+    };
+    return [{ event: 'step', data: step }];
+}
+/**
+ * Turns UI message chunks into the panel's events, one chunk at a time. `cards` says how a draft
+ * or write ended (a card's id is its tool call's). `advisor` names the advice part.
+ */
+export function chunkEvents(o = {}) {
+    const calls = new Map();
+    let advising = false;
+    return (chunk) => {
+        const id = typeof chunk.toolCallId === 'string' ? chunk.toolCallId : '';
+        switch (chunk.type) {
+            case 'text-delta':
+                return typeof chunk.delta === 'string' && chunk.delta
+                    ? [{ event: 'text', data: { delta: chunk.delta } }]
+                    : [];
+            case 'text-end':
+                return [{ event: 'text_end', data: {} }];
+            case 'tool-input-start': {
+                const name = String(chunk.toolName ?? '');
+                calls.set(id, { name, t0: Date.now() });
+                if (name === 'advisor') {
+                    advising = true;
+                    return [{ event: 'advice', data: { tier: 'advisor', label: o.advisor ?? 'Advice' } }];
+                }
+                if (name === 'escalate' || o.kindOf?.(name) === 'draft')
+                    return [];
+                return [{ event: 'step_start', data: { id, tool: name, title: stepTitle(name) } }];
+            }
+            case 'tool-input-available': {
+                const c = calls.get(id) ?? { name: String(chunk.toolName ?? ''), t0: Date.now() };
+                calls.set(id, { ...c, input: chunk.input });
+                return [];
+            }
+            case 'tool-output-available':
+            case 'tool-output-error': {
+                const c = calls.get(id);
+                if (!c)
+                    return [];
+                calls.delete(id);
+                const error = chunk.type === 'tool-output-error' ? String(chunk.errorText ?? '') : undefined;
+                if (c.name === 'advisor') {
+                    advising = false;
+                    return [{ event: 'advice_done', data: error ? { error } : {} }];
+                }
+                return settledCall(id, c, error !== undefined ? { error } : { output: chunk.output }, Date.now() - c.t0, o.cards?.() ?? new Map());
+            }
+            case 'error':
+                return [
+                    { event: 'error', data: { message: String(chunk.errorText ?? 'The answer failed.') } },
+                ];
+            case 'abort':
+                return advising
+                    ? [
+                        { event: 'advice_done', data: {} },
+                        { event: 'stopped', data: {} },
+                    ]
+                    : [{ event: 'stopped', data: {} }];
+            default:
+                return [];
+        }
+    };
+}
+/** A stored chat as the panel's items: the messages in order, each tool call as it ended. */
+export function itemsOf(messages, cards) {
+    const byId = new Map(cards.map((c) => [c.id, c]));
+    const items = [];
+    for (const m of messages) {
+        if (m.role === 'user') {
+            const text = m.parts
+                .filter((p) => p.type === 'text')
+                .map((p) => String(p.text ?? ''))
+                .join('');
+            const meta = (obj(m.metadata) ?? {});
+            items.push({
+                kind: 'user',
+                text,
+                at: meta.at ?? 0,
+                ...(meta.context?.label ? { context: meta.context.label } : {}),
+                ...(meta.refs?.length ? { refs: meta.refs } : {}),
+                ...(meta.tier ? { tier: meta.tier } : {}),
+            });
+            continue;
+        }
+        if (m.role !== 'assistant')
+            continue;
+        for (const p of m.parts) {
+            if (p.type === 'text' && typeof p.text === 'string' && p.text) {
+                const last = items[items.length - 1];
+                if (last?.kind === 'text')
+                    last.text += p.text;
+                else
+                    items.push({ kind: 'text', text: p.text });
+                continue;
+            }
+            const tool = p.type === 'dynamic-tool'
+                ? String(p.toolName ?? '')
+                : p.type.startsWith('tool-')
+                    ? p.type.slice(5)
+                    : '';
+            if (!tool || typeof p.toolCallId !== 'string')
+                continue;
+            if (tool === 'advisor') {
+                items.push({ kind: 'advice', tier: 'advisor', label: 'Advice' });
+                continue;
+            }
+            const ended = p.state === 'output-available'
+                ? { output: p.output }
+                : p.state === 'output-error'
+                    ? { error: String(p.errorText ?? 'failed') }
+                    : null;
+            if (!ended)
+                continue;
+            for (const e of settledCall(p.toolCallId, { name: tool, input: p.input, t0: 0 }, ended, 0, byId)) {
+                if (e.event === 'handoff')
+                    items.push({ ...e.data, items: [] });
+                else if (e.event === 'handoff_done') {
+                    const h = items[items.length - 1];
+                    if (h?.kind === 'handoff')
+                        h.usage = e.data.usage;
+                }
+                else if (e.event === 'step' || e.event === 'draft') {
+                    const { handoff: _h, ...item } = e.data;
+                    items.push(item);
+                }
+            }
+        }
+    }
+    return items;
+}

package/dist/agent/tools.d.ts

@@ -16,6 +16,8 @@ export interface SourceAt {
 }
 /** A write the model asked for while its group drafts: the card's content. */
 export interface DraftCall {
+    /** The model's tool call id: a card keeps it as its own. */
+    call?: string;
     group: string;
     tool: string;
     args: unknown;

package/dist/agent/tools.js

@@ -41,9 +41,10 @@ export async function openAiTools(sources, o = {}) {
             tools[name] = tool({
                 description: describe(def, kind),
                 inputSchema: jsonSchema(withoutMeta(def.inputSchema)),
-                execute: async (args) => {
+                execute: async (args, { toolCallId }) => {
+                    const call = toolCallId;
                     if (kind === 'draft')
-                        return o.draft?.({ group: s.group, tool: def.name, args });
+                        return o.draft?.({ call, group: s.group, tool: def.name, args });
                     const t0 = Date.now();
                     try {
                         const out = await open.call(def.name, args);
@@ -51,7 +52,13 @@ export async function openAiTools(sources, o = {}) {
                         const text = typeof out === 'string' ? out : JSON.stringify(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 });
+                            const change = await o.wrote({
+                                call,
+                                group: s.group,
+                                tool: def.name,
+                                args,
+                                result: out,
+                            });
                             if (change !== undefined)
                                 return { result: shown, change };
                         }

package/dist/assistant/engine.js

@@ -592,7 +592,11 @@ export class Assistant {
                             plan: !!key.plan,
                         }),
                     });
-                    return { memo: `Memo from ${sub.meter.label}:\n${r.text.slice(0, MEMO_CHARS)}` };
+                    return {
+                        memo: `Memo from ${sub.meter.label}:\n${r.text.slice(0, MEMO_CHARS)}`,
+                        // For the chat's hand-off section; the model reads the memo.
+                        handoff: { tier: tier.id, label: sub.meter.label, why: shown, usage: meter.part() },
+                    };
                 }
                 catch (err) {
                     if (abortSignal?.aborted)

package/package.json

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