@columenlabs/lumen-ai 0.1.247 → 0.1.248

package/README.md

@@ -253,6 +253,8 @@ Drafts and writes are cards in the chat's own storage (`lumen_cards` in the agen
 
 **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.
 
+**Tool lines.** Each tool call shows as a line with the tool's own `title` (an MCP tool's `title`, a plain tool's `title`), kept in the chat's storage so a chat read back words its lines the same; a tool with no title shows its name. An app that keeps its insides off the screen overrides `plainSteps()` to return `true`: every line reads its tool's title, else a word for what it did (Look something up, Make a change, Draft a change), with no tool id, row count or error text (a failed line says `didn't work`), and a hand-off section reads Take a closer look with no tier or task. The details go to the app's log instead: `stepFailed({ tool, error, ms })` hears each failed call with its whole error (override it to log it with the chat's ids), and `onStep` carries `error` and `caller` on a failed tool or hand-off. `stepTitleOf(name, kind)` gives a line's title for an app's own card answers.
+
 **A write in progress.** A tool line starts (`step_start`) as soon as the model starts the call, while it is still writing the arguments. For a Read + write tool it carries `write: true`, and `useAssistantChat` marks that running step `writing` until its result lands or the answer ends, so an app can show what the tool changes as being changed now (a pending edit is not ready to accept while the model rewrites it).
 
 **Steps.** One answer makes at most `plan.maxSteps` model calls (`MAX_STEPS`, 8). The last one runs with no tools and `LAST_STEP_NOTE`, so an answer always ends in words: what it found, and what is left when the task did not fit.

package/dist/agent/agent.d.ts

@@ -191,6 +191,23 @@ export declare abstract class LumenAgent<Env = unknown> extends Think<Env> {
      * `stay`. Off (`false`) unless the app overrides it; a throw counts as `false`.
      */
     protected offerFresh(_input: AskInput): Promise<boolean>;
+    /**
+     * Whether the chat's tool lines keep inner names off the screen: each reads its tool's title
+     * (or a word for what it did), with no tool id, tier, model, row count or error text. Off
+     * (`false`) unless the app overrides it; the app logs the details from `onStep`.
+     */
+    protected plainSteps(): boolean;
+    /**
+     * A tool call this answer failed: its name and whole error (a plain line shows neither). Does
+     * nothing unless the app overrides it, e.g. to log it with the chat's ids.
+     */
+    protected stepFailed(_f: {
+        tool: string;
+        error: string;
+        ms: number;
+    }): void;
+    /** A tool line's title as this chat words it (`plainSteps`), for an app's own card answers. */
+    protected stepTitleOf(name: string, kind?: 'read' | 'draft' | 'write'): string;
     /** 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. */

package/dist/agent/agent.js

@@ -20,7 +20,7 @@ import { CONNECTOR_GROUP, checkConnectorUrl, connectorGroup, connectorId, connec
 import { aiModel, cachedTurn, planFallback, 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 } from './stream.js';
+import { chunkEvents, itemsOf, shownTitle, } 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.';
@@ -193,6 +193,43 @@ export class LumenAgent extends Think {
     async offerFresh(_input) {
         return false;
     }
+    /**
+     * Whether the chat's tool lines keep inner names off the screen: each reads its tool's title
+     * (or a word for what it did), with no tool id, tier, model, row count or error text. Off
+     * (`false`) unless the app overrides it; the app logs the details from `onStep`.
+     */
+    plainSteps() {
+        return false;
+    }
+    /** How this chat words its tool lines: plain or not, with the titles of every tool it offered. */
+    #names() {
+        return {
+            plain: this.plainSteps(),
+            titleOf: (n) => this.#turn?.tools.info.find((i) => i.name === n)?.title ??
+                this.#get('titles')?.[n],
+        };
+    }
+    /**
+     * A tool call this answer failed: its name and whole error (a plain line shows neither). Does
+     * nothing unless the app overrides it, e.g. to log it with the chat's ids.
+     */
+    stepFailed(_f) { }
+    /** A tool line's title as this chat words it (`plainSteps`), for an app's own card answers. */
+    stepTitleOf(name, kind) {
+        return shownTitle(name, this.#names(), kind);
+    }
+    /** Keeps the titles of a turn's tools, so a chat read back words its lines the same. */
+    #keepTitles(info) {
+        const titles = this.#get('titles') ?? {};
+        let changed = false;
+        for (const i of info)
+            if (i.title && titles[i.name] !== i.title) {
+                titles[i.name] = i.title.slice(0, 80);
+                changed = true;
+            }
+        if (changed)
+            this.#put('titles', titles);
+    }
     /** The chat's running use: every answer's parts added up, and the last context size. */
     usage() {
         return this.#get('usage') ?? chatUsage([]);
@@ -203,7 +240,7 @@ export class LumenAgent extends Think {
             id,
             title: this.#get('title') ?? '',
             at: this.#get('at') ?? 0,
-            items: itemsOf(await this.getMessages(), this.cards(), this.#screens(), this.#get('steers') ?? {}),
+            items: itemsOf(await this.getMessages(), this.cards(), this.#screens(), this.#get('steers') ?? {}, this.#names()),
             usage: this.usage(),
         };
     }
@@ -258,6 +295,8 @@ export class LumenAgent extends Think {
             cards: () => new Map(this.cards().map((c) => [c.id, c])),
             screens: () => this.#screens(),
             kindOf: (n) => this.#turn?.tools.info.find((i) => i.name === n)?.kind,
+            names: this.#names(),
+            failed: (f) => this.stepFailed(f),
         });
         const map = screenMapOf(input.screen);
         const userId = `u_${crypto.randomUUID().replaceAll('-', '').slice(0, 16)}`;
@@ -575,6 +614,7 @@ export class LumenAgent extends Think {
         if (advice)
             meters.push(advice);
         let system = typeof plan.system === 'string' ? plan.system : plan.system(opened);
+        this.#keepTitles(opened.info);
         this.#turn = {
             plan,
             system,

package/dist/agent/stream.d.ts

@@ -8,6 +8,22 @@ import type { AgentCard } from './agent.js';
 import type { ScreenCall } from './screen.js';
 /** A tool's name as a line's title: `notes__find_notes` → `find notes`. */
 export declare function stepTitle(name: string): string;
+/**
+ * How a chat's tool lines are worded. `plain` keeps every inner name off the screen: no tool ids,
+ * no tier or model, no row counts and no error text (the app logs those; see `StepRecord.error`).
+ * A line reads the tool's own `title` (`titleOf`), else a word for what it did.
+ */
+export interface StepNames {
+    plain?: boolean;
+    /** The tool's own title, when it has one. */
+    titleOf?: (name: string) => string | undefined;
+}
+/** What a plain line says when a call failed: the assistant reads the error and goes on. */
+export declare const PLAIN_FAILED = "didn't work";
+/** A plain hand-off's heading: a closer look, never the tier it went to. */
+export declare const PLAIN_HANDOFF = "Take a closer look";
+/** The line's title: the tool's own title, else its name (or, plain, a word for what it did). */
+export declare function shownTitle(name: string, names?: StepNames, kind?: 'read' | 'draft' | 'write'): 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.
@@ -19,6 +35,14 @@ export declare function chunkEvents(o?: {
     screens?: () => Map<string, ScreenCall>;
     /** 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;
+    /** How the lines are worded. */
+    names?: StepNames;
+    /** A tool call failed: its name and whole error, before a plain line hides them (for logs). */
+    failed?: (f: {
+        tool: string;
+        error: string;
+        ms: number;
+    }) => void;
 }): (chunk: {
     type: string;
     [k: string]: unknown;
@@ -51,5 +75,5 @@ export interface SteerNote {
     text: string;
     at: number;
 }
-export declare function itemsOf(messages: StoredMessage[], cards: AgentCard[], screens?: Map<string, ScreenCall>, steers?: Record<string, SteerNote[]>): ChatItem[];
+export declare function itemsOf(messages: StoredMessage[], cards: AgentCard[], screens?: Map<string, ScreenCall>, steers?: Record<string, SteerNote[]>, names?: StepNames): ChatItem[];
 export {};

package/dist/agent/stream.js

@@ -5,6 +5,25 @@ export function stepTitle(name) {
     const own = name.includes('__') ? name.slice(name.indexOf('__') + 2) : name;
     return own.replace(/_/g, ' ');
 }
+/** What a plain line says when a call failed: the assistant reads the error and goes on. */
+export const PLAIN_FAILED = "didn't work";
+/** A plain hand-off's heading: a closer look, never the tier it went to. */
+export const PLAIN_HANDOFF = 'Take a closer look';
+/** The line's title: the tool's own title, else its name (or, plain, a word for what it did). */
+export function shownTitle(name, names = {}, kind) {
+    const own = names.titleOf?.(name);
+    if (own)
+        return own;
+    if (!names.plain)
+        return stepTitle(name);
+    if (name === 'escalate')
+        return PLAIN_HANDOFF;
+    return kind === 'write'
+        ? 'Make a change'
+        : kind === 'draft'
+            ? 'Draft a change'
+            : 'Look something up';
+}
 const obj = (v) => v && typeof v === 'object' && !Array.isArray(v) ? v : null;
 /** A tool's `image` output as the panel's card: a same-site path or an https address only. */
 function stepImage(v) {
@@ -19,7 +38,7 @@ function stepImage(v) {
     };
 }
 /** What one finished tool call shows as: a line, a card, a hand-off section or nothing. */
-function settledCall(id, c, out, ms, cards, screens = new Map()) {
+function settledCall(id, c, out, ms, cards, screens = new Map(), names = {}) {
     const o = obj(out.output);
     if (c.name === 'screen') {
         // A call the page map refused goes back to the model only; the person sees the one that ran.
@@ -43,7 +62,7 @@ function settledCall(id, c, out, ms, cards, screens = new Map()) {
             kind: 'draft',
             id,
             tool: c.name,
-            title: stepTitle(c.name),
+            title: shownTitle(c.name, names, 'draft'),
             args: card?.args ?? c.input ?? null,
             status: card && card.status !== 'done' && card.status !== 'undone' ? card.status : 'open',
             ...(card?.result !== undefined ? { result: card.result } : {}),
@@ -53,11 +72,13 @@ function settledCall(id, c, out, ms, cards, screens = new Map()) {
     }
     const h = obj(o?.handoff);
     if (h && typeof h.tier === 'string' && typeof o?.memo === 'string') {
-        const task = String(obj(c.input)?.task ?? '');
+        // Plain: the tier and the task the model wrote for it stay off the screen.
+        const task = names.plain ? '' : String(obj(c.input)?.task ?? '');
+        const label = names.plain ? PLAIN_HANDOFF : h.label;
         return [
             {
                 event: 'handoff',
-                data: { kind: 'handoff', tier: h.tier, label: h.label, task, why: h.why },
+                data: { kind: 'handoff', tier: h.tier, label, task, why: h.why },
             },
             { event: 'handoff_done', data: { usage: h.usage } },
         ];
@@ -66,16 +87,17 @@ function settledCall(id, c, out, ms, cards, screens = new Map()) {
     const rows = rowCount(o && 'result' in o ? o.result : out.output);
     const image = stepImage(o?.image);
     const web = webStep(c.name, c.input, out.output, !!error || obj(out.output)?.ok === false);
+    const wrote = card?.kind === 'write' || (o && typeof o.change === 'string');
     const step = {
         kind: 'step',
         id,
         tool: c.name,
-        title: stepTitle(c.name),
+        title: shownTitle(c.name, names, wrote ? 'write' : 'read'),
         ok: !error,
         ms,
-        ...(rows !== undefined && !error ? { rows } : {}),
-        ...(error ? { error: error.slice(0, 300) } : {}),
-        ...(card?.kind === 'write' || (o && typeof o.change === 'string')
+        ...(rows !== undefined && !error && !names.plain ? { rows } : {}),
+        ...(error ? { error: names.plain ? PLAIN_FAILED : error.slice(0, 300) } : {}),
+        ...(wrote
             ? { write: { undo: true, status: card?.status === 'undone' ? 'undone' : 'done' } }
             : {}),
         ...(web ? { web } : {}),
@@ -88,6 +110,7 @@ function settledCall(id, c, out, ms, cards, screens = new Map()) {
  * or write ended (a card's id is its tool call's). `advisor` names the advice part.
  */
 export function chunkEvents(o = {}) {
+    const names = o.names ?? {};
     const calls = new Map();
     let advising = false;
     return (chunk) => {
@@ -110,11 +133,17 @@ export function chunkEvents(o = {}) {
                     return [];
                 // A tool that makes a change at once says so as it starts, so an app can show that what it
                 // changes is being changed now, before the model has finished writing the call.
-                const write = o.kindOf?.(name) === 'write';
+                const kind = o.kindOf?.(name);
+                const write = kind === 'write';
                 return [
                     {
                         event: 'step_start',
-                        data: { id, tool: name, title: stepTitle(name), ...(write ? { write } : {}) },
+                        data: {
+                            id,
+                            tool: name,
+                            title: shownTitle(name, names, kind),
+                            ...(write ? { write } : {}),
+                        },
                     },
                 ];
             }
@@ -134,7 +163,18 @@ export function chunkEvents(o = {}) {
                     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(), c.name === 'screen' ? (o.screens?.() ?? new Map()) : undefined);
+                const ms = Date.now() - c.t0;
+                const out = obj(chunk.output);
+                const said = error ?? (out && typeof out.error === 'string' ? out.error : undefined);
+                if (said !== undefined) {
+                    try {
+                        o.failed?.({ tool: c.name, error: said.slice(0, 2000), ms });
+                    }
+                    catch {
+                        // a log hook never breaks the answer
+                    }
+                }
+                return settledCall(id, c, error !== undefined ? { error } : { output: chunk.output }, ms, o.cards?.() ?? new Map(), c.name === 'screen' ? (o.screens?.() ?? new Map()) : undefined, names);
             }
             case 'error':
                 return [
@@ -152,7 +192,7 @@ export function chunkEvents(o = {}) {
         }
     };
 }
-export function itemsOf(messages, cards, screens = new Map(), steers = {}) {
+export function itemsOf(messages, cards, screens = new Map(), steers = {}, names = {}) {
     const byId = new Map(cards.map((c) => [c.id, c]));
     const items = [];
     let asked;
@@ -223,7 +263,7 @@ export function itemsOf(messages, cards, screens = new Map(), steers = {}) {
                     : null;
             if (!ended)
                 continue;
-            for (const e of settledCall(p.toolCallId, { name: tool, input: p.input, t0: 0 }, ended, 0, byId, screens)) {
+            for (const e of settledCall(p.toolCallId, { name: tool, input: p.input, t0: 0 }, ended, 0, byId, screens, names)) {
                 if (e.event === 'handoff')
                     items.push({ ...e.data, items: [] });
                 else if (e.event === 'handoff_done') {

package/dist/agent/tools.d.ts

@@ -35,6 +35,7 @@ export interface AiToolsOptions {
         tool: string;
         ok: boolean;
         ms: number;
+        error?: string;
     }) => void;
     /** A result handed to the model is cut past this many characters. */
     maxChars?: number;
@@ -45,6 +46,8 @@ export interface ToolInfo {
     group: string;
     kind: 'read' | 'draft' | 'write';
     find: boolean;
+    /** The tool's own title, in words a person reads ("Read the design guide"). */
+    title?: string;
 }
 /** Tools open for one answer, as the AI SDK's set, and how to let them go. */
 export interface OpenedTools {

package/dist/agent/tools.js

@@ -37,7 +37,13 @@ export async function openAiTools(sources, o = {}) {
             const name = toolName(s.group, def.name);
             if (kind === 'read')
                 reads.push(name);
-            info.push({ name, group: s.group, kind, find: !!def.find });
+            info.push({
+                name,
+                group: s.group,
+                kind,
+                find: !!def.find,
+                ...(def.title ? { title: def.title } : {}),
+            });
             tools[name] = tool({
                 description: describe(def, kind),
                 inputSchema: jsonSchema(withoutMeta(def.inputSchema)),
@@ -65,8 +71,9 @@ export async function openAiTools(sources, o = {}) {
                         return shown;
                     }
                     catch (err) {
-                        o.called?.({ group: s.group, tool: def.name, ok: false, ms: Date.now() - t0 });
-                        return { error: String(err?.message ?? err).slice(0, 500) };
+                        const error = String(err?.message ?? err).slice(0, 500);
+                        o.called?.({ group: s.group, tool: def.name, ok: false, ms: Date.now() - t0, error });
+                        return { error };
                     }
                 },
             });

package/dist/assistant/engine.d.ts

@@ -111,6 +111,8 @@ export type StepRecord = {
     ms: number;
     rows?: number;
     error?: string;
+    /** The person the answer was for (their id), so a log line links to them. */
+    caller?: string;
     tier: string;
     handoff: boolean;
 } | {

package/dist/assistant/engine.js

@@ -363,6 +363,8 @@ export class Assistant {
                     tool: toolName(c.group, c.tool),
                     ok: c.ok,
                     ms: c.ms,
+                    ...(c.error ? { error: c.error } : {}),
+                    caller: caller.id,
                     tier: main.tier.id,
                     handoff: false,
                 })).catch(() => undefined),
@@ -509,6 +511,7 @@ export class Assistant {
                 if (this.tiers.indexOf(tier) > this.tiers.indexOf(c.counts.end))
                     c.counts.end = tier;
                 const shown = asked.has(tier.id) ? 'asked' : why;
+                const t0 = Date.now();
                 try {
                     const r = await generateText({
                         model: aiModel(sub.model, key, {
@@ -539,6 +542,17 @@ export class Assistant {
                 catch (err) {
                     if (abortSignal?.aborted)
                         throw err;
+                    // The whole error goes to the app's log; the chat line may show none of it (plain steps).
+                    await Promise.resolve(this.o.onStep?.({
+                        kind: 'tool',
+                        tool: 'escalate',
+                        ok: false,
+                        ms: Date.now() - t0,
+                        error: `${sub.meter.label}: ${String(err?.message ?? err).slice(0, 500)}`,
+                        caller: c.caller.id,
+                        tier: tier.id,
+                        handoff: true,
+                    })).catch(() => undefined);
                     return { error: `${sub.meter.label} failed: ${shownError(err).message}` };
                 }
             },

package/package.json

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