@columenlabs/lumen-ai 0.1.78 → 0.1.79

package/README.md

@@ -98,7 +98,46 @@ app.all('/api/assistant/*', (c) => routes(c.req.raw));
 - **Keys.** Each provider has its own keys (`?provider=anthropic|openai` on the key routes). An admin pastes the shared key everyone uses (`PUT /key`); it is tested with one free call before it is kept, then sealed, and no route returns it. A person may add their own (`PUT /my-key`), with one monthly cap on their own keys (`PUT /my-key/cap`).
 - **ChatGPT sign-in.** In place of their own OpenAI key a person may sign in with their ChatGPT plan (`POST /my-signin`, then `POST /my-signin/finish {url}`): the sign-in opens in a new tab and ends on `http://127.0.0.1:1455/auth/callback`, a page that does not load, whose address the person pastes back. The tokens are sealed as their own key and refreshed before they run out; answers on the plan count tokens and no dollars.
 - **Who pays.** The person's pick (the shared keys by default) while it has a key for the tier's provider and money left this month under its cap (an admin sets the shared keys' cap per person, `PUT /app`), else the other; with neither the panel says why.
-- **Tools.** Each group is Off, Read or Read + draft per person. A tool is a read when its MCP `readOnlyHint` is set; a write only drafts a card, and runs as the person when they press Save, after access is checked again. Use `mcpServerTools` (an SDK `McpServer`), `mcpFetchTools` (a server served as a fetch handler, any SDK), `remoteMcpTools` or `plainTools`.
+- **Tools.** Each group is Off, Read, Read + draft or Read + write per person. A tool is a read when its MCP `readOnlyHint` is set. On Read + draft a write only drafts a card, and runs as the person when they press Save, after access is checked again. Read + write is offered only for a group with `writes: true`: its writes run at once, and with `undo` set each one's line in the chat has Undo, which calls `undo(caller, { tool, args, result })` (`POST /chats/:id/writes/:step/undo`); the model is told what was undone. Cards drafted one after another show as one stack with Save all. Use `mcpServerTools` (an SDK `McpServer`), `mcpFetchTools` (a server served as a fetch handler, any SDK), `remoteMcpTools` or `plainTools`.
 - **Web.** `fetch` is a plain GET from the Worker (10 s, 2 MB, never the app's own hosts or private addresses). ScrapeQL's own tools join over its MCP API once an admin pastes a Cloudflare Access service token (`PUT /web/scrapeql`).
 - **Hand off and advice.** The `escalate` tool hands one task to a higher tier (the person sets next, any or only when asked); Anthropic's advisor tool lets a higher tier send a plan, at most two an answer.
 - **Chats** stream as server-sent events (`POST /chat`); closing the request stops the answer and keeps what was said. Past 150k tokens, or on `/compact`, the history sent to the model becomes a summary. Run `assistant.purge()` once a day to drop chats 30 days after their last message.
+
+### Commands, `@` and `#`
+
+The panel's composer lists what can follow three keys as they are typed. The kit's own entries are on for every app; an app only adds its own.
+
+- **`/` commands.** Built in: `/compact` (summarise the chat), `/clear` (a new chat), `/model <tier>` (answer on another tier from now on) and `/escalate <task>` (hand one task to the next tier up). An app adds its own on the server with `commands`: the chat shows what the person typed and the model gets `prompt`, with `{args}` replaced by the words after the name (or what the function returns). An app's command wins a built-in's name.
+
+  ```ts
+  createAssistant({
+    // ...
+    commands: [
+      { name: 'story', about: 'Find stories for a question', args: '<question>',
+        prompt: 'Search my stories for: {args}. List the best three with why each fits.' },
+      { name: 'prep', about: 'Prep for an interview', args: '<company>',
+        prompt: async (company, caller) => prepPrompt(caller.id, company) },
+    ],
+  });
+  ```
+
+  A command that acts in the browser (opens a page, sets a filter) goes on the panel instead: `LumenAssistant` (or `useLumenAssistantDock`) takes `commands`, each `{ name, about, args?, options?, run }`; `run` returns text to send, or nothing when it acted itself, and `options` lists choices for its words as they are typed.
+- **`@` a tier.** `@` lists the app's tiers; the pick is a chip and goes with that message only (`tier`). A higher tier takes it as a task in its own section of the chat; the same or a lower one answers it.
+- **`#` a thing.** `#` lists what the person can point at, a group per source; each pick is a chip and goes with the message as a ref (`kind`, `label` and whatever finds it), which the model reads before the message. Standing sources go on the panel (`sources`); a page adds its own while it is shown:
+
+  ```tsx
+  import { useAssistantSource } from '@columenlabs/lumen-ui/assistant';
+
+  useAssistantSource({
+    id: 'page',
+    label: 'On this page',
+    items: (q) =>
+      rows
+        .filter((r) => r.title.toLowerCase().includes(q.toLowerCase()))
+        .map((r) => ({ id: r.id, label: r.title, target: `card:${r.id}`, ref: { kind: 'story', label: r.title, id: r.id } })),
+  });
+  ```
+
+  `target` lights the thing on screen while its row is hovered. A page's source replaces a standing one with the same `id`.
+
+  Text the person highlights on the page is offered first under `#` (Selected text), with where it sits from the nearest `data-assistant-where` attribute. To hand a highlight over from the page, an Ask button calls `composeAssistant({ refs: [selectionRef({ text, where })], text: '' })` (or any refs and text): the panel opens with the chips in the composer, focused for the person to finish.

package/dist/assistant/engine.d.ts

@@ -1,21 +1,47 @@
-import type { AssistantAccess, AssistantChat, AssistantChatRow, AssistantMessage, AssistantProvider, AssistantStatus, DraftItem } from '@columenlabs/lumen-ui-types/assistant';
+import type { AssistantAccess, AssistantChat, AssistantChatRow, AssistantMessage, AssistantProvider, AssistantStatus, DraftItem, StepItem } from '@columenlabs/lumen-ui-types/assistant';
 import { type ModelDef, type TaskDef, type TierDef } from './models.js';
 import { State } from './state.js';
 import { type AssistantStore, type Sealer } from './store.js';
 import { type ToolSource } from './tools.js';
 import { type AccessToken, type WebFetchOptions } from './web.js';
+/** An app's slash command (`/story <words>`). */
+export interface AssistantCommandDef {
+    /** Typed after the slash, letters, digits and `-`: `story`. */
+    name: string;
+    /** One line in the list. */
+    about: string;
+    /** What follows the name, shown in the list (`<words>`). Without it, picking it sends it. */
+    args?: string;
+    /** What the model is asked: `{args}` is the words after the name. */
+    prompt: string | ((args: string, caller: Caller) => string | Promise<string>);
+}
 /** Who is asking: their id (the store's scope for their things) and whether they are an admin. */
 export interface Caller {
     id: string;
     admin: boolean;
 }
-/** A group of the app's tools the person sets Off, Read or Read + draft. */
+/** A change a write tool made at once, as `undo` gets it. */
+export interface AssistantWrite {
+    /** The tool's own name (not the `group__tool` the model calls). */
+    tool: string;
+    args: unknown;
+    /** What the tool returned. */
+    result: unknown;
+}
+/** A group of the app's tools the person sets Off, Read, Read + draft or Read + write. */
 export interface ToolGroup {
     id: string;
     label: string;
     about: string;
     /** Where a person starts: `read` by default. */
     access?: AssistantAccess;
+    /**
+     * Offers Read + write: its write tools then run at once, without a card, each with Undo in the
+     * chat when `undo` is set. Off by default, so a group only drafts.
+     */
+    writes?: boolean;
+    /** Takes back one change a write made at once (Undo on its line in the chat). */
+    undo?: (caller: Caller, write: AssistantWrite) => Promise<void>;
     tools: (caller: Caller) => ToolSource | ToolSource[];
 }
 /** What one step or answer was, for the app's meter: shapes only, never content. */
@@ -52,6 +78,12 @@ export interface AssistantOptions {
     name: string;
     /** The app's instructions: what it is, what its tools are for. */
     system: string | ((caller: Caller) => string | Promise<string>);
+    /**
+     * The app's slash commands, listed in the composer when the person types `/`. A message
+     * `/name words` is sent to the model as `prompt` with `{args}` replaced by the words (or what the
+     * function returns); the chat shows what the person typed.
+     */
+    commands?: AssistantCommandDef[];
     /** The app's tiers, smallest first. */
     tiers: TierDef[];
     /** Tasks a person picks a starting tier for; the chat on the smallest tier by default. */
@@ -111,6 +143,7 @@ export declare class Assistant {
     /** The tier the person's chat runs on: their pick, else the chat task's start tier. */
     private mainTier;
     private access;
+    private groupById;
     status(caller: Caller): Promise<AssistantStatus>;
     listChats(caller: Caller): Promise<AssistantChatRow[]>;
     readChat(caller: Caller, id: string): Promise<AssistantChat | null>;
@@ -129,6 +162,8 @@ export declare class Assistant {
     /** The advisor for this answer, or null when off. Never weaker than the model it advises. */
     private advisorFor;
     private escalateTool;
+    /** What the model is asked: an app command's prompt, else the message as typed. */
+    private expand;
     /** The tiers the person's message asks for by name ("go deeper" is the next one up). */
     private askedFor;
     private handOff;
@@ -169,6 +204,8 @@ export declare class Assistant {
     }>;
     /** Saves (runs, as the person) or dismisses a drafted card. Access is checked again first. */
     settleDraft(caller: Caller, chatId: string, draftId: string, action: 'save' | 'dismiss'): Promise<DraftItem>;
+    /** Takes back one change a write made at once, through its group's `undo`. */
+    undoWrite(caller: Caller, chatId: string, stepId: string): Promise<StepItem>;
 }
 export declare function createAssistant(o: AssistantOptions): Assistant;
 export {};

package/dist/assistant/engine.js

@@ -97,6 +97,10 @@ function untilStopped(work, signal) {
     });
 }
 const newId = (prefix) => `${prefix}_${crypto.randomUUID().replaceAll('-', '').slice(0, 20)}`;
+/** Every tool line in a chat, those in hand-off sections included. */
+function stepsOf(items) {
+    return items.flatMap((i) => i.kind === 'step' ? [i] : i.kind === 'handoff' ? stepsOf(i.items) : []);
+}
 /** Every draft in a chat, those in hand-off sections included. */
 function draftsOf(items) {
     return items.flatMap((i) => i.kind === 'draft' ? [i] : i.kind === 'handoff' ? draftsOf(i.items) : []);
@@ -205,7 +209,11 @@ export class Assistant {
         return (this.tierById(task === 'chat' ? (p.tier ?? startId) : startId) ?? this.tiers[0]);
     }
     access(p, g) {
-        return p.access?.[g.id] ?? g.access ?? 'read';
+        const a = p.access?.[g.id] ?? g.access ?? 'read';
+        return a === 'write' && !g.writes ? 'draft' : a;
+    }
+    groupById(id) {
+        return this.groups.find((g) => g.id === id);
     }
     // ---------------------------------------------------------------- status and settings
     async status(caller) {
@@ -252,6 +260,11 @@ export class Assistant {
         }));
         return {
             name: this.name,
+            commands: (this.o.commands ?? []).map((c) => ({
+                name: c.name,
+                about: c.about,
+                ...(c.args ? { args: c.args } : {}),
+            })),
             wait,
             ...(wait ? { wait_provider: mainModel.provider } : {}),
             admin: caller.admin,
@@ -275,6 +288,7 @@ export class Assistant {
                 about: g.about,
                 access: this.access(p, g),
                 drafts: true,
+                writes: !!g.writes,
             })),
             hand_off: p.hand_off ?? 'next',
             advice: p.advice && (p.advice === 'off' || this.tierById(p.advice)) ? p.advice : 'off',
@@ -362,12 +376,15 @@ export class Assistant {
         const fns = new Map();
         for (const o of opened)
             for (const def of o.open.tools) {
-                if (!def.read && o.access !== 'draft')
+                if (!def.read && o.access !== 'draft' && o.access !== 'write')
                     continue;
+                // Read + write on a group that offers no writes drafts.
+                const write = !def.read && o.access === 'write' && !!this.groupById(o.group)?.writes;
                 fns.set(toolName(o.group, def.name), {
                     group: o.group,
                     def,
-                    draft: !def.read,
+                    draft: !def.read && !write,
+                    write,
                     open: o.open,
                 });
             }
@@ -380,7 +397,7 @@ export class Assistant {
     toolsFor(fns) {
         return [...fns.entries()].map(([name, f]) => ({
             name,
-            description: `${f.draft ? "DRAFT ONLY: this call changes nothing. It puts a card on the person's screen that they Save or Dismiss. " : ''}${f.def.title ? `${f.def.title}. ` : ''}${f.def.description ?? ''}`.slice(0, 4000),
+            description: `${f.draft ? "DRAFT ONLY: this call changes nothing. It puts a card on the person's screen that they Save or Dismiss. " : f.write ? 'WRITES AT ONCE: this call makes the change now; the person can undo it. ' : ''}${f.def.title ? `${f.def.title}. ` : ''}${f.def.description ?? ''}`.slice(0, 4000),
             input_schema: { type: 'object', ...f.def.inputSchema },
         }));
     }
@@ -436,6 +453,7 @@ export class Assistant {
             history: [],
         };
         const compactOnly = message === '/compact';
+        const asked = await this.expand(caller, message);
         if (!compactOnly)
             doc.items.push({
                 kind: 'user',
@@ -447,7 +465,13 @@ export class Assistant {
             });
         const start = doc.items.length;
         emit('chat', { id: chatId, title: doc.title });
-        const main = await this.session(caller, await this.mainTier(caller));
+        // `tier` on a message: a higher one takes it as a task in its own section (handTo below); the
+        // same or a lower one answers it as the main tier, for this message only.
+        const picked = await this.mainTier(caller);
+        const lower = req.tier && !this.above(picked).some((t) => t.id === req.tier)
+            ? this.tierById(req.tier)
+            : undefined;
+        const main = await this.session(caller, lower ?? picked);
         const { paying, wait } = await this.state.paying(caller.id, main.model.provider);
         if (!paying) {
             const code = wait ?? 'not_connected';
@@ -479,7 +503,8 @@ export class Assistant {
         const handTo = req.tier ? this.above(main.tier).find((t) => t.id === req.tier) : undefined;
         const tools = await this.openTools(caller, p);
         const runs = [];
-        const counts = { steps: 0, handoffs: 0, advice: 0, end: main.tier };
+        doc.writes ??= {};
+        const counts = { steps: 0, handoffs: 0, advice: 0, end: main.tier, writes: doc.writes };
         let outcome = 'ok';
         try {
             const appSystem = typeof this.o.system === 'string' ? this.o.system : await this.o.system(caller);
@@ -516,7 +541,7 @@ export class Assistant {
             }
             const page = this.cardNews(doc) +
                 (req.refs?.length
-                    ? `The person points at: ${JSON.stringify(req.refs).slice(0, 2000)}\n\n`
+                    ? `The person points at: ${JSON.stringify(req.refs).slice(0, 8000)}\n\n`
                     : '') +
                 (req.context
                     ? `Page: ${req.context.label}${req.context.note === undefined ? '' : `\n${JSON.stringify(req.context.note).slice(0, 4000)}`}\n\n`
@@ -526,7 +551,7 @@ export class Assistant {
                 : '';
             const messages = [
                 ...doc.history.map((t) => ({ role: t.role, content: t.content })),
-                { role: 'user', content: `${page}${lead}${message}` },
+                { role: 'user', content: `${page}${lead}${asked}` },
             ];
             const escalateTool = this.escalateTool(main.tier);
             let answer = await this.loop({
@@ -549,7 +574,7 @@ export class Assistant {
                     ? this.handOff(use, {
                         caller,
                         clients,
-                        message,
+                        message: asked,
                         handTo,
                         page,
                         policy,
@@ -577,7 +602,7 @@ export class Assistant {
                 emit('text', { delta: answer });
                 emit('text_end', {});
             }
-            doc.history.push({ role: 'user', content: `${page}${message}` });
+            doc.history.push({ role: 'user', content: `${page}${asked}` });
             doc.history.push({ role: 'assistant', content: this.remember(answer, runs) });
         }
         catch (err) {
@@ -590,7 +615,7 @@ export class Assistant {
                     .map((i) => i.text)
                     .join('\n\n');
                 if (!compactOnly) {
-                    doc.history.push({ role: 'user', content: message });
+                    doc.history.push({ role: 'user', content: asked });
                     doc.history.push({ role: 'assistant', content: said || '(stopped before answering)' });
                 }
             }
@@ -640,6 +665,7 @@ export class Assistant {
             `You are ${this.name}. Today is ${new Date().toISOString().slice(0, 10)}.`,
             'Answer in short plain sentences. Use the tools for facts; never guess a number a tool can give you. Call several tools at once when they do not depend on each other.',
             'A tool marked DRAFT ONLY makes a card the person saves or dismisses; it changes nothing by itself. Say what the card will do; never claim it is done. The next message tells you how each card ended.',
+            'A tool marked WRITES AT ONCE makes its change when you call it; the person can undo it from the chat. Change only what they asked for, and say what you changed.',
         ];
         if (!fns.size)
             lines.push('No tools are on now: the person can turn them on in Settings ▸ Tools.');
@@ -694,6 +720,17 @@ export class Assistant {
             },
         };
     }
+    /** What the model is asked: an app command's prompt, else the message as typed. */
+    async expand(caller, message) {
+        const m = /^\/([\w-]+)(?:\s+([\s\S]*))?$/.exec(message);
+        const c = m && this.o.commands?.find((x) => x.name === m[1]);
+        if (!c)
+            return message;
+        const args = (m?.[2] ?? '').trim();
+        return typeof c.prompt === 'function'
+            ? c.prompt(args, caller)
+            : c.prompt.replaceAll('{args}', args);
+    }
     /** The tiers the person's message asks for by name ("go deeper" is the next one up). */
     askedFor(message, main) {
         const reach = this.above(main);
@@ -827,6 +864,8 @@ export class Assistant {
         let rows;
         try {
             const result = await untilStopped(withDeadline(title, 60_000, f.open.call(f.def.name, use.input)), signal);
+            if (f.write && counts.writes)
+                counts.writes[id] = { group: f.group, tool: f.def.name, args: use.input, result };
             rows = rowCount(result);
             out = typeof result === 'string' ? result : JSON.stringify(result);
         }
@@ -848,6 +887,9 @@ export class Assistant {
             ms,
             ...(rows !== undefined ? { rows } : {}),
             ...(error ? { error } : {}),
+            ...(f.write && ok
+                ? { write: { undo: !!this.groupById(f.group)?.undo, status: 'done' } }
+                : {}),
         };
         sink.push(item);
         emit('step', item);
@@ -1186,10 +1228,16 @@ export class Assistant {
     cardNews(doc) {
         const told = new Set(doc.told ?? []);
         const news = draftsOf(doc.items).filter((d) => d.status !== 'open' && !told.has(d.id));
-        if (!news.length)
+        const undone = stepsOf(doc.items).filter((x) => x.write?.status === 'undone' && !told.has(x.id));
+        if (!news.length && !undone.length)
             return '';
-        doc.told = [...told, ...news.map((d) => d.id)];
-        return `Cards since your last answer:\n${news
+        doc.told = [...told, ...news.map((d) => d.id), ...undone.map((x) => x.id)];
+        const back = undone.length
+            ? `The person undid these changes you made: ${undone.map((x) => `${x.title} ${JSON.stringify(doc.writes?.[x.id]?.args ?? {}).slice(0, 300)}`).join('; ')}. Do not make them again unless asked.\n\n`
+            : '';
+        if (!news.length)
+            return back;
+        return `${back}Cards since your last answer:\n${news
             .map((d) => `- ${d.title} ${JSON.stringify(d.args).slice(0, 300)}: ${d.status}${d.error ? ` (${d.error})` : ''}${d.result !== undefined ? ` → ${JSON.stringify(d.result).slice(0, 300)}` : ''}`)
             .join('\n')}\n\n`;
     }
@@ -1303,9 +1351,9 @@ export class Assistant {
             const tools = await this.openTools(caller, p);
             try {
                 const f = tools.fns.get(d.tool);
-                if (!f?.draft) {
+                if (!f || f.def.read) {
                     d.status = 'failed';
-                    d.error = 'Its tools are no longer on Read + draft in Settings ▸ Tools.';
+                    d.error = 'Its tools are no longer on Read + draft or Read + write in Settings ▸ Tools.';
                 }
                 else {
                     try {
@@ -1325,6 +1373,30 @@ export class Assistant {
         await this.writeChat(caller, chatId, doc);
         return d;
     }
+    /** Takes back one change a write made at once, through its group's `undo`. */
+    async undoWrite(caller, chatId, stepId) {
+        const doc = await this.state.docs.read(caller.id, `chat:${chatId}`);
+        if (!doc)
+            throw new AssistantError('That chat is gone.', 'not_found', 404);
+        const step = stepsOf(doc.items).find((x) => x.id === stepId);
+        const w = doc.writes?.[stepId];
+        if (!step?.write || !w)
+            throw new AssistantError('That change is gone.', 'not_found', 404);
+        if (step.write.status === 'undone')
+            throw new AssistantError('That change is already undone.', 'settled', 409);
+        const g = this.groupById(w.group);
+        if (!g?.undo)
+            throw new AssistantError('That change cannot be undone here.', 'no_undo', 400);
+        try {
+            await withDeadline(`Undo ${step.title}`, 60_000, g.undo(caller, w));
+            step.write = { ...step.write, status: 'undone' };
+        }
+        catch (err) {
+            throw new AssistantError(err instanceof Error ? err.message.slice(0, 300) : 'Undo failed.', 'undo_failed', 502);
+        }
+        await this.writeChat(caller, chatId, doc);
+        return step;
+    }
 }
 export function createAssistant(o) {
     return new Assistant(o);

package/dist/assistant/routes.js

@@ -18,6 +18,7 @@
  *   POST   /chat                    one answer as server-sent events; closing the request stops it
  *   GET    /chats, GET|DELETE /chats/:id
  *   POST   /chats/:id/drafts/:draft {action: save | dismiss}
+ *   POST   /chats/:id/writes/:step/undo
  *
  * Writes must be same-origin JSON: a signed-in browser session is a cookie, so a foreign page's
  * form or fetch is refused before it reaches a rule. Keys and tokens are write-only: no route
@@ -316,6 +317,8 @@ export function assistantRoutes(a, o) {
                         return fail('action is save or dismiss.');
                     return json(await a.settleDraft(caller, id, parts[3], action));
                 }
+                if (parts.length === 5 && parts[2] === 'writes' && parts[4] === 'undo' && m === 'POST')
+                    return json(await a.undoWrite(caller, id, parts[3]));
             }
             return fail('Not found.', 404);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@columenlabs/lumen-ai",
-  "version": "0.1.78",
+  "version": "0.1.79",
   "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",
@@ -41,8 +41,8 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "0.133.0",
-    "@columenlabs/lumen-ops": "0.1.78",
-    "@columenlabs/lumen-ui-types": "0.1.78",
+    "@columenlabs/lumen-ops": "0.1.79",
+    "@columenlabs/lumen-ui-types": "0.1.79",
     "openai": "7.32.0",
     "zod": "^4.3.6"
   },