@columenlabs/lumen-ai 0.1.215 → 0.1.216

package/README.md

@@ -241,6 +241,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.
 
+**Steer and queue.** While an answer runs, the panel's box stays open: Enter steers the message into the answer (`steer(message)` on the agent; the app routes `POST /chats/:id/steer` `{ message }` to it and answers `{ steered }`), Alt+Enter queues it for after. A steer joins at the answer's next step, after the tool it is on, with `STEER_NOTE` before it for the model; the panel shows it there marked Steered (event `steered`), and `view()` keeps it in place (`SteerNote`, under the message the answer is to). A steer the answer ends before reading comes back as `unsteered` and goes first in the queue. `plan.steer: false` turns it off for a model; an app without the route (404) shows Queue only. Queued messages each go as their own message when the answer before them ends; each has Steer now, Edit and Remove.
+
 ```ts
 class Chat extends LumenAgent<Env> {
   #settle?: (end: AgentTurnEnd) => Promise<void>;

package/dist/agent/agent.d.ts

@@ -76,6 +76,11 @@ export interface AgentTurnPlan {
     screen?: boolean;
     /** Most model calls in one answer; 8. */
     maxSteps?: number;
+    /**
+     * A message sent while the answer runs joins it at its next step (Steer); on unless `false`,
+     * for a model that should not read a new message between its calls. Refused steers are queued.
+     */
+    steer?: boolean;
     /** Fetch for provider calls (a metered one). */
     fetch?: typeof fetch;
     tools?: Omit<AiToolsOptions, 'maxChars'>;
@@ -94,6 +99,8 @@ export interface AgentTurnEnd {
     capped: boolean;
 }
 export declare const CAP_NOTE = "The spend cap for this month is reached: answer now from what you have, in a sentence or two. You can call no more tools.";
+/** Put before a message the person steered into a running answer, for the model only. */
+export declare const STEER_NOTE = "The person sent this while you were working. Take it into account from here on; it does not cancel what you were asked before unless it says so.";
 /** A card in the chat: a draft the person saves or dismisses, or a write made at once (Undo). */
 export interface AgentCard {
     id: string;
@@ -165,6 +172,14 @@ export declare abstract class LumenAgent<Env = unknown> extends Think<Env> {
     view(id?: string): Promise<AssistantChat>;
     /** Stops the answer running now; what was said so far is kept. */
     stop(): void;
+    /**
+     * A message for the answer running now: it joins at the answer's next step (after the tool it
+     * is on), shown there as steered. `steered: false` when no answer runs or its plan turned steer
+     * off: the panel queues it. One the answer ends without reading comes back as `unsteered`.
+     */
+    steer(message: string): {
+        steered: boolean;
+    };
     /**
      * 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.

package/dist/agent/agent.js

@@ -24,6 +24,8 @@ 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.';
+/** Put before a message the person steered into a running answer, for the model only. */
+export const STEER_NOTE = 'The person sent this while you were working. Take it into account from here on; it does not cancel what you were asked before unless it says so.';
 /** Past this many tokens in the chat Think summarizes its older part. */
 export const COMPACT_AT = 150_000;
 const CARD_NOTE = "A card is on the person's screen; nothing has changed yet. Say what it will do when they save it. The next message tells you how it ended.";
@@ -129,6 +131,14 @@ export class LumenAgent extends Think {
     includeMcpTools = false;
     #turn = null;
     #input = null;
+    /** The answer's events go here while it runs; a steer's line goes here too. */
+    #sink = null;
+    /** The person's message this answer is to, by id: where its steers are kept. */
+    #asked = null;
+    /** Steered messages waiting for the next step. */
+    #steers = [];
+    /** Steered messages read this answer: where they sit in the step's messages, and their words. */
+    #steered = [];
     #metaTabled = false;
     /** What the person sent with the message this turn answers (page, refs, tier, zone). */
     get input() {
@@ -159,7 +169,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()),
+            items: itemsOf(await this.getMessages(), this.cards(), this.#screens(), this.#get('steers') ?? {}),
             usage: this.usage(),
         };
     }
@@ -167,6 +177,19 @@ export class LumenAgent extends Think {
     stop() {
         this.cancelAllChats();
     }
+    /**
+     * A message for the answer running now: it joins at the answer's next step (after the tool it
+     * is on), shown there as steered. `steered: false` when no answer runs or its plan turned steer
+     * off: the panel queues it. One the answer ends without reading comes back as `unsteered`.
+     */
+    steer(message) {
+        const text = message.trim();
+        const t = this.#turn;
+        if (!text || !t || !this.#sink || t.plan.steer === false)
+            return { steered: false };
+        this.#steers.push({ text: text.slice(0, 20_000), at: Date.now() });
+        return { steered: true };
+    }
     /**
      * 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.
@@ -195,6 +218,11 @@ export class LumenAgent extends Think {
             kindOf: (n) => this.#turn?.tools.info.find((i) => i.name === n)?.kind,
         });
         const map = screenMapOf(input.screen);
+        const userId = `u_${crypto.randomUUID().replaceAll('-', '').slice(0, 16)}`;
+        this.#sink = sink;
+        this.#asked = userId;
+        this.#steers = [];
+        this.#steered = [];
         // The images go in the message's parts; the turn's plan reads the rest.
         const { images: _images, ...asked } = input;
         this.#input = { ...asked, ...(map ? { screen: map } : {}) };
@@ -203,7 +231,7 @@ export class LumenAgent extends Think {
         let failed = false;
         try {
             await this.chat({
-                id: `u_${crypto.randomUUID().replaceAll('-', '').slice(0, 16)}`,
+                id: userId,
                 role: 'user',
                 parts: [{ type: 'text', text: input.message }, ...imageParts(input.images)],
                 metadata: meta,
@@ -236,7 +264,14 @@ export class LumenAgent extends Think {
         }
         finally {
             this.#input = null;
+            this.#sink = null;
+            this.#asked = null;
+            this.#steered = [];
         }
+        // Steers the answer ended before reading go back to the panel, first in its queue.
+        const unread = this.#steers.splice(0).map((s) => s.text);
+        if (unread.length)
+            await sink.event({ event: 'unsteered', data: { texts: unread } });
         if (this.#capped)
             await sink.event({ event: 'stopped', data: { reason: 'cap' } });
         await sink.event({ event: 'done', data: { id: this.name, usage: this.usage() } });
@@ -573,20 +608,58 @@ export class LumenAgent extends Think {
         const t = this.#turn;
         if (!t)
             return undefined;
+        const steered = this.#steerInto(ctx);
+        const messages = steered ? { messages: steered } : {};
         // The SDK's step result is a union that Omit narrows to shared keys; these exist on it.
         if (t.plan.left !== undefined && this.#spent() >= t.plan.left) {
             t.capped = true;
-            return { activeTools: [], instructions: `${t.system}\n\n${CAP_NOTE}` };
+            const capped = {
+                ...messages,
+                activeTools: [],
+                instructions: `${t.system}\n\n${CAP_NOTE}`,
+            };
+            return capped;
         }
         // A forced first call is for the first step only; tools a search found join each step.
         const auto = t.plan.first && ctx.stepNumber > 0;
-        if (!auto && !t.lazy)
+        if (!auto && !t.lazy && !steered)
             return undefined;
         return {
             ...(auto ? { toolChoice: 'auto' } : {}),
             ...(t.lazy ? { activeTools: t.lazy.active() } : {}),
+            ...messages,
         };
     }
+    /**
+     * The step's messages with every steer read so far in its place: waiting ones join at the end
+     * now (told to the panel and kept for the chat's history), earlier ones where they joined.
+     */
+    #steerInto(ctx) {
+        const sink = this.#sink;
+        const asked = this.#asked;
+        if (this.#steers.length && sink && asked) {
+            const now = this.#steers.splice(0);
+            const kept = this.#get('steers') ?? {};
+            kept[asked] = [
+                ...(kept[asked] ?? []),
+                ...now.map((s) => ({ step: ctx.stepNumber, text: s.text, at: s.at })),
+            ];
+            this.#put('steers', kept);
+            for (const s of now) {
+                this.#steered.push({ index: ctx.messages.length, text: s.text });
+                void Promise.resolve(sink.event({ event: 'steered', data: s })).catch(() => undefined);
+            }
+        }
+        if (!this.#steered.length)
+            return null;
+        const out = [...ctx.messages];
+        for (const s of [...this.#steered].reverse())
+            out.splice(s.index, 0, {
+                role: 'user',
+                content: [{ type: 'text', text: `${STEER_NOTE}\n\n${s.text}` }],
+            });
+        return out;
+    }
     onStepFinish(ctx) {
         const t = this.#turn;
         if (!t)

package/dist/agent/stream.d.ts

@@ -25,6 +25,7 @@ export declare function chunkEvents(o?: {
 }) => AssistantEvent[];
 /** A stored UI message, as much of it as a chat's items need. */
 interface StoredMessage {
+    id?: string;
     role: string;
     parts: {
         type: string;
@@ -42,5 +43,11 @@ export interface AskMeta {
     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[], screens?: Map<string, ScreenCall>): ChatItem[];
+/** A message steered into an answer: the step it was read at, under the message the answer is to. */
+export interface SteerNote {
+    step: number;
+    text: string;
+    at: number;
+}
+export declare function itemsOf(messages: StoredMessage[], cards: AgentCard[], screens?: Map<string, ScreenCall>, steers?: Record<string, SteerNote[]>): ChatItem[];
 export {};

package/dist/agent/stream.js

@@ -127,12 +127,13 @@ export function chunkEvents(o = {}) {
         }
     };
 }
-/** A stored chat as the panel's items: the messages in order, each tool call as it ended. */
-export function itemsOf(messages, cards, screens = new Map()) {
+export function itemsOf(messages, cards, screens = new Map(), steers = {}) {
     const byId = new Map(cards.map((c) => [c.id, c]));
     const items = [];
+    let asked;
     for (const m of messages) {
         if (m.role === 'user') {
+            asked = m.id;
             const text = m.parts
                 .filter((p) => p.type === 'text')
                 .map((p) => String(p.text ?? ''))
@@ -154,7 +155,21 @@ export function itemsOf(messages, cards, screens = new Map()) {
         }
         if (m.role !== 'assistant')
             continue;
+        // Steered messages show where the answer read them: before the step they joined.
+        const steered = [...((asked && steers[asked]) || [])].sort((x, y) => x.step - y.step);
+        const steerTo = (step) => {
+            while (steered.length && steered[0].step <= step) {
+                const n = steered.shift();
+                items.push({ kind: 'user', text: n.text, at: n.at, steered: true });
+            }
+        };
+        let step = -1;
         for (const p of m.parts) {
+            if (p.type === 'step-start') {
+                step += 1;
+                steerTo(step);
+                continue;
+            }
             if (p.type === 'text' && typeof p.text === 'string' && p.text) {
                 const last = items[items.length - 1];
                 if (last?.kind === 'text')
@@ -195,6 +210,7 @@ export function itemsOf(messages, cards, screens = new Map()) {
                 }
             }
         }
+        steerTo(Number.POSITIVE_INFINITY);
     }
     return items;
 }

package/package.json

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