@columenlabs/lumen-ai 0.1.252 → 0.1.254

package/README.md

@@ -254,7 +254,7 @@ 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.
+**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. **Step lines say what a call did** (`stepLine(c)`): override it to word each call as a verb and what it acted on, from the call's own arguments and answer (`c.input`, `c.output`): present tense while it runs (`state: 'running'`, sent again once the arguments are in), past tense with a short result when it answered (`'done'`), and "Couldn't …" when it failed (`'failed'`, which then shows no `didn't work`). Return `undefined` to keep the tool's title. The kit words its own web lookup (Looking up / Looked up the question). A finished line is kept with the chat, so a chat read back reads the same. In a plain chat the tool search that turns more tools on shows no line.
 
 **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).
 

package/dist/agent/agent.d.ts

@@ -17,6 +17,7 @@ import { type ModelMessage, type ToolSet } from 'ai';
 import type { ModelDef } from '../assistant/models.js';
 import { type AgentConnector, type ConnectorAt } from './connectors.js';
 import { type ModelKey } from './models.js';
+import { type StepCall } from './stream.js';
 import { type AiToolsOptions, type OpenedTools, type SourceAt } from './tools.js';
 import { UsageMeter } from './usage.js';
 /** What a plan's extra tools get: the open tools, a meter of their own and the cap. */
@@ -197,6 +198,16 @@ export declare abstract class LumenAgent<Env = unknown> extends Think<Env> {
      * (`false`) unless the app overrides it; the app logs the details from `onStep`.
      */
     protected plainSteps(): boolean;
+    /**
+     * A tool call's line in the person's words: a verb and what it acted on, from the call's own
+     * arguments and answer. `running` is present tense ("Editing Lid"), `done` past tense with a short
+     * result when it helps ("Edited Lid: wall 2 → 3 mm"), `failed` says it did not ("Couldn't edit
+     * Lid"). Return `undefined` to keep the tool's title. A plain chat's line names no tool id, model,
+     * engine or code. The kit words its own web lookup; the app words its tools by overriding this
+     * (and may call `super.stepLine(c)` for the kit's). A finished line is kept with the chat, so a
+     * chat read back shows the same words.
+     */
+    protected stepLine(c: StepCall): string | undefined;
     /**
      * 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.

package/dist/agent/agent.js

@@ -201,12 +201,45 @@ export class LumenAgent extends Think {
     plainSteps() {
         return false;
     }
+    /**
+     * A tool call's line in the person's words: a verb and what it acted on, from the call's own
+     * arguments and answer. `running` is present tense ("Editing Lid"), `done` past tense with a short
+     * result when it helps ("Edited Lid: wall 2 → 3 mm"), `failed` says it did not ("Couldn't edit
+     * Lid"). Return `undefined` to keep the tool's title. A plain chat's line names no tool id, model,
+     * engine or code. The kit words its own web lookup; the app words its tools by overriding this
+     * (and may call `super.stepLine(c)` for the kit's). A finished line is kept with the chat, so a
+     * chat read back shows the same words.
+     */
+    stepLine(c) {
+        if (c.tool !== 'web__lookup')
+            return undefined;
+        const q = c.input?.question;
+        const question = typeof q === 'string' ? q.trim() : '';
+        if (!question)
+            return undefined;
+        return c.state === 'running'
+            ? `Looking up ${question}`
+            : c.state === 'failed'
+                ? `Couldn't look up ${question}`
+                : `Looked up ${question}`;
+    }
     /** 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],
+            lineOf: (c) => {
+                if (c.state === 'running')
+                    return this.stepLine(c);
+                const kept = this.#get(`line:${c.id}`);
+                if (kept)
+                    return kept;
+                const line = this.stepLine(c);
+                if (line)
+                    this.#put(`line:${c.id}`, line.slice(0, 200));
+                return line;
+            },
         };
     }
     /**

package/dist/agent/stream.d.ts

@@ -17,7 +17,28 @@ export interface StepNames {
     plain?: boolean;
     /** The tool's own title, when it has one. */
     titleOf?: (name: string) => string | undefined;
+    /**
+     * A line that says what this call did and to what (`LumenAgent.stepLine`): present tense while it
+     * runs, past tense with a short result when it answered, "Couldn't …" when it failed. Left out
+     * (or `undefined`), the line reads the tool's title.
+     */
+    lineOf?: (c: StepCall) => string | undefined;
 }
+/** One tool call as its line is worded: its name, arguments, answer and where it stands. */
+export interface StepCall {
+    id: string;
+    /** The tool's name as the model called it (`group__tool`). */
+    tool: string;
+    input?: unknown;
+    /** Its answer, once it answered. */
+    output?: unknown;
+    state: 'running' | 'done' | 'failed';
+}
+/**
+ * Whether a call shows no line at all: in a plain chat, the tool search that turns more tools on is
+ * the assistant finding its own tools, not something it did for the person.
+ */
+export declare function hiddenStep(name: string, names?: StepNames): boolean;
 /** 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. */

package/dist/agent/stream.js

@@ -1,10 +1,32 @@
 import { rowCount } from '../assistant/tools.js';
 import { webStep } from '../assistant/web.js';
+import { TOOL_SEARCH } from './search.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, ' ');
 }
+/** A line's text kept to one short line. */
+const oneLine = (t) => {
+    const s = (t ?? '').replace(/\s+/g, ' ').trim();
+    return s ? s.slice(0, 120) : undefined;
+};
+/** The line the app gave for this call, when it gave one; never throws. */
+function lineFor(names, c) {
+    try {
+        return oneLine(names.lineOf?.(c));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Whether a call shows no line at all: in a plain chat, the tool search that turns more tools on is
+ * the assistant finding its own tools, not something it did for the person.
+ */
+export function hiddenStep(name, names = {}) {
+    return !!names.plain && name === TOOL_SEARCH;
+}
 /** 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. */
@@ -88,15 +110,27 @@ function settledCall(id, c, out, ms, cards, screens = new Map(), names = {}) {
     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');
+    // The app's own line says what the call did; a failed one already says it did not ("Couldn't …").
+    const line = lineFor(names, {
+        id,
+        tool: c.name,
+        input: c.input,
+        ...(error
+            ? {}
+            : { output: o && 'result' in o && o.change !== undefined ? o.result : out.output }),
+        state: error ? 'failed' : 'done',
+    });
     const step = {
         kind: 'step',
         id,
         tool: c.name,
-        title: shownTitle(c.name, names, wrote ? 'write' : 'read'),
+        title: line ?? shownTitle(c.name, names, wrote ? 'write' : 'read'),
         ok: !error,
         ms,
         ...(rows !== undefined && !error && !names.plain ? { rows } : {}),
-        ...(error ? { error: names.plain ? PLAIN_FAILED : error.slice(0, 300) } : {}),
+        ...(error && !(line && names.plain)
+            ? { error: names.plain ? PLAIN_FAILED : error.slice(0, 300) }
+            : {}),
         ...(wrote
             ? { write: { undo: true, status: card?.status === 'undone' ? 'undone' : 'done' } }
             : {}),
@@ -129,7 +163,10 @@ export function chunkEvents(o = {}) {
                     advising = true;
                     return [{ event: 'advice', data: { tier: 'advisor', label: o.advisor ?? 'Advice' } }];
                 }
-                if (name === 'escalate' || name === 'screen' || o.kindOf?.(name) === 'draft')
+                if (name === 'escalate' ||
+                    name === 'screen' ||
+                    o.kindOf?.(name) === 'draft' ||
+                    hiddenStep(name, names))
                     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.
@@ -150,7 +187,23 @@ export function chunkEvents(o = {}) {
             case 'tool-input-available': {
                 const c = calls.get(id) ?? { name: String(chunk.toolName ?? ''), t0: Date.now() };
                 calls.set(id, { ...c, input: chunk.input });
-                return [];
+                // Its arguments are in: the running line can say what it is doing and to what.
+                if (c.name === 'advisor' ||
+                    c.name === 'escalate' ||
+                    c.name === 'screen' ||
+                    o.kindOf?.(c.name) === 'draft' ||
+                    hiddenStep(c.name, names))
+                    return [];
+                const line = lineFor(names, { id, tool: c.name, input: chunk.input, state: 'running' });
+                if (!line)
+                    return [];
+                const write = o.kindOf?.(c.name) === 'write';
+                return [
+                    {
+                        event: 'step_start',
+                        data: { id, tool: c.name, title: line, ...(write ? { write } : {}) },
+                    },
+                ];
             }
             case 'tool-output-available':
             case 'tool-output-error': {
@@ -164,6 +217,8 @@ export function chunkEvents(o = {}) {
                     return [{ event: 'advice_done', data: error ? { error } : {} }];
                 }
                 const ms = Date.now() - c.t0;
+                if (hiddenStep(c.name, names))
+                    return [];
                 const out = obj(chunk.output);
                 const said = error ?? (out && typeof out.error === 'string' ? out.error : undefined);
                 if (said !== undefined) {
@@ -256,6 +311,8 @@ export function itemsOf(messages, cards, screens = new Map(), steers = {}, names
                 items.push({ kind: 'advice', tier: 'advisor', label: 'Advice' });
                 continue;
             }
+            if (hiddenStep(tool, names))
+                continue;
             const ended = p.state === 'output-available'
                 ? { output: p.output }
                 : p.state === 'output-error'

package/dist/assistant/engine.js

@@ -16,7 +16,7 @@ import { webLookupTools } from '../subagents/web.js';
 import { bearings } from './bearings.js';
 import { CHATGPT_REDIRECT, SigninError, finishChatgpt, startChatgpt, testChatgpt, } from './chatgpt.js';
 import { ALL_MODELS, DEFAULT_OUT, Meter, PROVIDERS, XAI_BASE_URL, effortParams, } from './models.js';
-import { DEFAULT_CAP, State, keyDocName, keyState, ownKeyUsd, ownPlanCalls, planDocName, waitText, withProvider, } from './state.js';
+import { DEFAULT_CAP, State, keyDocName, keyState, ownKeyUsd, ownPlanCalls, ownPlanUsd, planDocName, waitText, withProvider, } from './state.js';
 import { Docs } from './store.js';
 import { toolName, withDeadline } from './tools.js';
 import { scrapeqlTools, webFetchTools } from './web.js';
@@ -410,6 +410,7 @@ export class Assistant {
                     title: message.split('\n')[0] || 'Chat',
                     own_usd: ownKeyUsd(paying, onPayer),
                     own_plan_calls: ownPlanCalls(paying, onPayer),
+                    own_plan_usd: ownPlanUsd(paying, onPayer),
                 }, end.parts)
                     .catch(() => undefined);
             const total = end.parts.reduce((a, m) => ({
@@ -1096,6 +1097,7 @@ export class Assistant {
                 title: o.run?.title ?? task?.label ?? o.task,
                 own_usd: ownKeyUsd(paying, [part]),
                 own_plan_calls: ownPlanCalls(paying, [part]),
+                own_plan_usd: ownPlanUsd(paying, [part]),
             }, [part])
                 .catch(() => undefined);
         }
@@ -1185,6 +1187,7 @@ export class Assistant {
                 title: o.run?.title ?? task?.label ?? o.task,
                 own_usd: ownKeyUsd(paying, [part]),
                 own_plan_calls: ownPlanCalls(paying, [part]),
+                own_plan_usd: ownPlanUsd(paying, [part]),
             }, [part])
                 .catch(() => undefined);
         }

package/dist/assistant/state.d.ts

@@ -104,8 +104,19 @@ export type SpendRow = UsagePart & {
 };
 /** The provider a part ran on: by its model id, else by the model's name at the end of its label. */
 export declare function providerOfPart(p: UsagePart): AssistantProvider | undefined;
-/** Spend rows with the provider each ran on, so a page can tell a removed key's spend apart. */
-export declare function withProvider<R extends UsagePart>(rows: R[]): R[];
+/**
+ * What a part's tokens cost at its model's API rates: the estimate shown for a plan sign-in's calls,
+ * which cost the person nothing. Cache writes count as plain input. Undefined for an unknown model.
+ */
+export declare function listUsd(p: UsagePart): number | undefined;
+/**
+ * Spend rows with the provider each ran on, so a page can tell a removed key's spend apart, and
+ * a $0 row (a plan's calls) with what it would cost at API rates (`list_usd`).
+ */
+export declare function withProvider<R extends UsagePart>(rows: R[]): (R & {
+    provider?: "anthropic" | "openai" | "xai" | undefined;
+    list_usd?: number | undefined;
+})[];
 /** USD of `parts` the person's own API keys paid: a provider signed in with a plan costs $0. */
 export declare function ownKeyUsd(paying: {
     payer: AssistantPayer;
@@ -116,6 +127,11 @@ export declare function ownPlanCalls(paying: {
     payer: AssistantPayer;
     plans: Paying['plans'];
 }, parts: UsagePart[]): number;
+/** Those plan calls at the models' API rates: an estimate of what the plan saved the person. */
+export declare function ownPlanUsd(paying: {
+    payer: AssistantPayer;
+    plans: Paying['plans'];
+}, parts: UsagePart[]): number;
 /**
  * What counts toward the person's own cap: own rows paid by an API key (a plan sign-in costs
  * nothing per call), on a provider they can still pay with. A row from before ways were recorded
@@ -282,7 +298,8 @@ export declare class State {
      * Adds one answer's use to a chat or run in this month's history (`usage:YYYY-MM`): one entry a
      * chat or run, its parts merged, the newest `USAGE_KEPT` kept. `title` names a new entry only;
      * `own_usd` is what of this answer the person's own key or plan paid, added to the entry's;
-     * `own_plan_calls` the calls their plan sign-in answered (free to them, so counted, not priced).
+     * `own_plan_calls` the calls their plan sign-in answered (free to them, so counted, not priced),
+     * `own_plan_usd` those calls at API rates (an estimate).
      */
     addUsage(id: string, e: {
         id: string;
@@ -291,6 +308,7 @@ export declare class State {
         title: string;
         own_usd?: number;
         own_plan_calls?: number;
+        own_plan_usd?: number;
     }, parts: UsagePart[]): Promise<void>;
     /** One month's history (this month by default) beside its spend, and the months that have one. */
     usage(id: string, month?: string): Promise<UsageHistory>;

package/dist/assistant/state.js

@@ -14,11 +14,30 @@ export function providerOfPart(p) {
         KNOWN_MODELS.find((x) => p.label === x.label || p.label.endsWith(` · ${x.label}`));
     return m?.provider;
 }
-/** Spend rows with the provider each ran on, so a page can tell a removed key's spend apart. */
+/**
+ * What a part's tokens cost at its model's API rates: the estimate shown for a plan sign-in's calls,
+ * which cost the person nothing. Cache writes count as plain input. Undefined for an unknown model.
+ */
+export function listUsd(p) {
+    const m = KNOWN_MODELS.find((x) => x.id === p.model) ??
+        KNOWN_MODELS.find((x) => p.label === x.label || p.label.endsWith(` · ${x.label}`));
+    if (!m)
+        return undefined;
+    return (Math.max(0, p.in - p.read) * m.in + p.read * m.read + p.out * m.out) / 1e6;
+}
+/**
+ * Spend rows with the provider each ran on, so a page can tell a removed key's spend apart, and
+ * a $0 row (a plan's calls) with what it would cost at API rates (`list_usd`).
+ */
 export function withProvider(rows) {
     return rows.map((r) => {
         const provider = providerOfPart(r);
-        return provider ? { ...r, provider } : r;
+        const list = r.calls && r.usd < 0.0005 ? listUsd(r) : undefined;
+        return {
+            ...r,
+            ...(provider ? { provider } : {}),
+            ...(list !== undefined ? { list_usd: list } : {}),
+        };
     });
 }
 /** USD of `parts` the person's own API keys paid: a provider signed in with a plan costs $0. */
@@ -43,6 +62,17 @@ export function ownPlanCalls(paying, parts) {
     })
         .reduce((a, p) => a + p.calls, 0);
 }
+/** Those plan calls at the models' API rates: an estimate of what the plan saved the person. */
+export function ownPlanUsd(paying, parts) {
+    if (paying.payer !== 'own')
+        return 0;
+    return parts
+        .filter((p) => {
+        const prov = providerOfPart(p);
+        return !!(prov && paying.plans[prov]);
+    })
+        .reduce((a, p) => a + (listUsd(p) ?? 0), 0);
+}
 /**
  * What counts toward the person's own cap: own rows paid by an API key (a plan sign-in costs
  * nothing per call), on a provider they can still pay with. A row from before ways were recorded
@@ -364,7 +394,8 @@ export class State {
      * Adds one answer's use to a chat or run in this month's history (`usage:YYYY-MM`): one entry a
      * chat or run, its parts merged, the newest `USAGE_KEPT` kept. `title` names a new entry only;
      * `own_usd` is what of this answer the person's own key or plan paid, added to the entry's;
-     * `own_plan_calls` the calls their plan sign-in answered (free to them, so counted, not priced).
+     * `own_plan_calls` the calls their plan sign-in answered (free to them, so counted, not priced),
+     * `own_plan_usd` those calls at API rates (an estimate).
      */
     async addUsage(id, e, parts) {
         if (!parts.some((p) => p.calls))
@@ -378,6 +409,7 @@ export class State {
             const sum = (k) => merged.reduce((a, p) => a + p[k], 0);
             const own = (prev?.own_usd ?? 0) + (e.own_usd ?? 0);
             const plan = (prev?.own_plan_calls ?? 0) + (e.own_plan_calls ?? 0);
+            const planUsd = (prev?.own_plan_usd ?? 0) + (e.own_plan_usd ?? 0);
             entries.unshift({
                 id: e.id,
                 kind: e.kind,
@@ -392,6 +424,7 @@ export class State {
                 usd: sum('usd'),
                 ...(own > 0 ? { own_usd: own } : {}),
                 ...(plan > 0 ? { own_plan_calls: plan } : {}),
+                ...(planUsd > 0 ? { own_plan_usd: planUsd } : {}),
                 parts: merged,
             });
             return { entries: entries.slice(0, USAGE_KEPT) };

package/package.json

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