@columenlabs/lumen-ai 0.1.207 → 0.1.209

package/README.md

@@ -94,8 +94,8 @@ const routes = assistantRoutes(assistant, {
 app.all('/api/assistant/*', (c) => routes(c.req.raw));
 ```
 
-- **Providers.** A tier runs any model in `models` (Claude's and OpenAI's by default, `CLAUDE_MODELS`, `OPENAI_MODELS`): Claude through Anthropic's Messages API, OpenAI through the Responses API, with the same tools, drafts, Stop and caps. A hand-off may cross providers. The advisor and prompt caching marks are Claude's only.
-- **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`).
+- **Providers.** A tier runs any model in `models` (Claude's and OpenAI's by default, `CLAUDE_MODELS`, `OPENAI_MODELS`): Claude through Anthropic's Messages API, OpenAI through the Responses API, with the same tools, drafts, Stop and caps. xAI's Grok models (`XAI_MODELS`) are opt in: an app that lists them gets an xAI row in Model providers (an API key, `xai-…`); they run on the same Responses client at `XAI_BASE_URL` (`https://api.x.ai/v1`). xAI has no public sign-in for other apps, so Grok takes a key only. A hand-off may cross providers. The advisor and prompt caching marks are Claude's only.
+- **Keys.** Each provider has its own keys (`?provider=anthropic|openai|xai` 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, 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. A group with `readOnly: true` (read tools only) is offered Off or Read alone. 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 })`; 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`.
@@ -103,7 +103,7 @@ app.all('/api/assistant/*', (c) => routes(c.req.raw));
 - **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** run on the agent (`./agent`, `LumenAgent`, below): the app routes `POST /chat` and each chat's reads, cards and Undo to its own agent, and `assistantRoutes` answers `POST /chat` with 410 `moved`. Chats saved by the old turn loop stay readable (`GET /chats`, `GET|DELETE /chats/:id`) until `assistant.purge()` drops them 30 days after their last message.
 - **Screen moves**: while the person's Settings ▸ Screen is Move (the default), the panel sends its page map (`AssistantMessage.screen`: routes, nav pages, Settings sections, cards on screen, rows to open) and `LumenAgent` gives the model a `screen` tool (`./agent` `screen.ts`). Each call's moves (go, settings, chart, open, point) are checked against the map, kept in the chat and streamed as a `screen` event; the panel runs them through `AssistantScreenProvider` (mounted by `LumenShell`) with an Undo chip, and their outcomes go back with the next message (`outcomes`). Nothing is saved by a move.
-- **Background work** an app runs for a person (a score, a summary) is `assistant.complete(caller, { task, system, prompt, images?, maxTokens })`: one answer on the task's tier (`tasks`, so the person picks its model in Settings ▸ Models), no chat and no tools (`images`, base64 with their media type, are read with the prompt: a scanned page, a screenshot), billed to their payer and counted in their spend and allowance like a chat turn. It throws `AssistantError` `not_connected`, `app_cap` or `own_cap` when nobody can pay, so the caller waits and tries later.
+- **Background work** an app runs for a person (a score, a summary) is `assistant.complete(caller, { task, system, prompt, images?, maxTokens })`: one answer on the task's tier (`tasks`, so the person picks its model in Settings ▸ Models), no chat and no tools (`images`, base64 with their media type, are read with the prompt: a scanned page, a screenshot), billed to their payer and counted in their spend and allowance like a chat turn. `maxTokens` (default 1,000) goes up to `COMPLETE_MAX_TOKENS` (32,000, thinking included); the answer is streamed, so a long one keeps its connection, and `cut: true` says it stopped at the cap before it ended (the app can ask again, shorter, or continue). It throws `AssistantError` `not_connected`, `app_cap` or `own_cap` when nobody can pay, so the caller waits and tries later.
 
 ### Commands, `@` and `#`
 

package/dist/agent/models.d.ts

@@ -1,6 +1,6 @@
 import type { AssistantEffort } from '@columenlabs/lumen-ui-types/assistant';
 import type { JSONValue, LanguageModel, ModelMessage, SystemModelMessage } from 'ai';
-import type { ModelDef } from '../assistant/models.js';
+import { type ModelDef } from '../assistant/models.js';
 /** The key a model runs on. `plan`: an OpenAI access token from a ChatGPT plan sign-in. */
 export interface ModelKey {
     apiKey: string;

package/dist/agent/models.js

@@ -5,6 +5,7 @@
  */
 import { createAnthropic } from '@ai-sdk/anthropic';
 import { createOpenAI } from '@ai-sdk/openai';
+import { XAI_BASE_URL } from '../assistant/models.js';
 /**
  * A ChatGPT plan sign-in takes function tools only inside one namespace and no output cap, and a
  * forced call is the one tool offered with any call required (developers.openai.com/siwc, Preview
@@ -84,6 +85,12 @@ function textOf(content) {
 export function aiModel(model, key, o = {}) {
     if (model.provider === 'anthropic')
         return createAnthropic({ apiKey: key.apiKey, ...(o.fetch ? { fetch: o.fetch } : {}) })(model.id);
+    if (model.provider === 'xai')
+        return createOpenAI({
+            apiKey: key.apiKey,
+            baseURL: XAI_BASE_URL,
+            ...(o.fetch ? { fetch: o.fetch } : {}),
+        }).responses(model.id);
     const f = key.plan ? planFetch(o.fetch, o.name) : o.fetch;
     return createOpenAI({ apiKey: key.apiKey, ...(f ? { fetch: f } : {}) }).responses(model.id);
 }

package/dist/assistant/engine.d.ts

@@ -56,6 +56,8 @@ export interface AllowanceNotice {
     request: AllowanceRequest;
     unit: AllowanceUnit;
 }
+/** The largest answer `complete` asks for, tokens (thinking included). Streamed, so minutes are fine. */
+export declare const COMPLETE_MAX_TOKENS = 32000;
 /** 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). */
@@ -202,6 +204,7 @@ export declare class Assistant {
     forRequest(): Assistant;
     private anthropic;
     private openai;
+    private xai;
     private clients;
     /** The providers the app's models run on, in the order the models list them. */
     get providers(): AssistantProvider[];
@@ -274,7 +277,7 @@ export declare class Assistant {
     private askedFor;
     /** Swaps the history for a short summary. False with nothing to compact. */
     /**
-     * One plain answer from OpenAI, metered on `s`: no tools, no chat. Streamed and read from the raw
+     * One plain answer from OpenAI (or xAI, on the same API), metered on `s`: no tools, no chat. Streamed and read from the raw
      * events like the chat loop, because a ChatGPT plan sign-in answers only streamed calls, takes no
      * output cap and may send its words only as deltas.
      */
@@ -291,12 +294,14 @@ export declare class Assistant {
         prompt: string;
         /** Photos read with the prompt (a scanned page, a screenshot). */
         images?: CompleteImage[];
+        /** The answer's token cap, thinking included (default 1,000, at most COMPLETE_MAX_TOKENS). */
         maxTokens?: number;
         signal?: AbortSignal;
     }): Promise<{
         text: string;
         usd: number;
         model: string;
+        cut: boolean;
     }>;
     /** Starts a person's ChatGPT plan sign-in: the address to open in a new tab. */
     startSignin(caller: Caller, provider: AssistantProvider): Promise<{

package/dist/assistant/engine.js

@@ -14,7 +14,7 @@ import OpenAI from 'openai';
 import { aiModel, turnSettings } from '../agent/models.js';
 import { bearings } from './bearings.js';
 import { CHATGPT_REDIRECT, SigninError, finishChatgpt, startChatgpt, testChatgpt, } from './chatgpt.js';
-import { ALL_MODELS, DEFAULT_OUT, Meter, PROVIDERS, effortParams, } from './models.js';
+import { ALL_MODELS, DEFAULT_OUT, Meter, PROVIDERS, XAI_BASE_URL, effortParams, } from './models.js';
 import { DEFAULT_CAP, State, keyDocName, keyState, planDocName, waitText, } from './state.js';
 import { Docs } from './store.js';
 import { toolName, withDeadline } from './tools.js';
@@ -23,6 +23,8 @@ const DOLLARS = { one: 'dollar', many: 'dollars', usd: 1 };
 const round2 = (n) => Math.round(n * 100) / 100;
 /** A request may ask for at most this many times the starter or monthly cap. */
 const REQUEST_MAX_TIMES = 100;
+/** The largest answer `complete` asks for, tokens (thinking included). Streamed, so minutes are fine. */
+export const COMPLETE_MAX_TOKENS = 32_000;
 /** A turn's failure the person can act on. */
 export class AssistantError extends Error {
     code;
@@ -162,6 +164,10 @@ export class Assistant {
         // A plan sign-in's calls are not retried: a usage limit is final for now.
         return new OpenAI({ apiKey, maxRetries: plan ? 0 : 1, ...(f ? { fetch: f } : {}) });
     }
+    xai(apiKey) {
+        const f = this.o.fetch;
+        return new OpenAI({ apiKey, baseURL: XAI_BASE_URL, maxRetries: 1, ...(f ? { fetch: f } : {}) });
+    }
     clients(paying) {
         const { keys, plans } = paying;
         return {
@@ -169,6 +175,7 @@ export class Assistant {
             ...(keys.openai
                 ? { openai: this.openai(keys.openai, !!plans.openai), openaiPlan: !!plans.openai }
                 : {}),
+            ...(keys.xai ? { xai: this.xai(keys.xai) } : {}),
         };
     }
     /** The providers the app's models run on, in the order the models list them. */
@@ -815,13 +822,15 @@ export class Assistant {
     }
     /** Swaps the history for a short summary. False with nothing to compact. */
     /**
-     * One plain answer from OpenAI, metered on `s`: no tools, no chat. Streamed and read from the raw
+     * One plain answer from OpenAI (or xAI, on the same API), metered on `s`: no tools, no chat. Streamed and read from the raw
      * events like the chat loop, because a ChatGPT plan sign-in answers only streamed calls, takes no
      * output cap and may send its words only as deltas.
      */
     async openaiOnce(clients, s, instructions, input, max, signal, images) {
-        const client = clients.openai;
-        const plan = !!clients.openaiPlan;
+        // xAI's API is OpenAI's Responses API at another address.
+        const xai = s.model.provider === 'xai';
+        const client = (xai ? clients.xai : clients.openai);
+        const plan = !xai && !!clients.openaiPlan;
         let text = '';
         let done;
         try {
@@ -880,7 +889,10 @@ export class Assistant {
                 cache_read_input_tokens: read,
             }, plan);
         }
-        return text || done?.output_text || '';
+        return {
+            text: text || done?.output_text || '',
+            cut: done?.status === 'incomplete' && done.incomplete_details?.reason === 'max_output_tokens',
+        };
     }
     // ---------------------------------------------------------------- one-shot work
     /**
@@ -897,14 +909,20 @@ export class Assistant {
             throw new AssistantError(waitText(code, s.model.provider, !!this.o.allowance), code, 402);
         }
         const clients = this.clients(paying);
-        const max = Math.min(o.maxTokens ?? 1000, 8000);
+        const max = Math.min(o.maxTokens ?? 1000, COMPLETE_MAX_TOKENS);
         let text = '';
+        // The answer stopped at `max` before it ended (its thinking counts toward the cap too).
+        let cut = false;
         try {
-            if (s.model.provider === 'openai' && clients.openai) {
-                text = await this.openaiOnce(clients, s, o.system, o.prompt, max, o.signal, o.images);
+            if ((s.model.provider === 'openai' && clients.openai) ||
+                (s.model.provider === 'xai' && clients.xai)) {
+                ({ text, cut } = await this.openaiOnce(clients, s, o.system, o.prompt, max, o.signal, o.images));
             }
             else if (clients.anthropic) {
-                const msg = await clients.anthropic.messages.create({
+                // Streamed and read whole: a long answer (minutes at a high cap) keeps its connection alive,
+                // and the SDK refuses a long answer as one unstreamed request.
+                const msg = await clients.anthropic.messages
+                    .stream({
                     model: s.model.id,
                     max_tokens: max,
                     system: o.system,
@@ -927,8 +945,10 @@ export class Assistant {
                         },
                     ],
                     ...effortParams(s.effort),
-                }, o.signal ? { signal: o.signal } : undefined);
+                }, o.signal ? { signal: o.signal } : undefined)
+                    .finalMessage();
                 s.meter.add(msg.usage);
+                cut = msg.stop_reason === 'max_tokens';
                 text = msg.content
                     .filter((b) => b.type === 'text')
                     .map((b) => b.text)
@@ -945,7 +965,7 @@ export class Assistant {
         finally {
             await this.state.addSpend(caller.id, paying.payer, [s.meter.part()]);
         }
-        return { text, usd: s.meter.usd, model: s.model.id };
+        return { text, usd: s.meter.usd, model: s.model.id, cut };
     }
     // ---------------------------------------------------------------- keys
     /** Starts a person's ChatGPT plan sign-in: the address to open in a new tab. */
@@ -1025,6 +1045,8 @@ export class Assistant {
         try {
             if (provider === 'openai')
                 await this.openai(apiKey).models.retrieve(model.id);
+            else if (provider === 'xai')
+                await this.xai(apiKey).models.retrieve(model.id);
             else
                 await this.anthropic(apiKey).models.retrieve(model.id);
             return { ok: true, detail: `${label} took the key.`, at };

package/dist/assistant/models.d.ts

@@ -20,6 +20,14 @@ export interface ModelDef {
 export declare const CLAUDE_MODELS: ModelDef[];
 /** OpenAI models, smallest first (list prices from OpenAI's pricing page, October 2026). */
 export declare const OPENAI_MODELS: ModelDef[];
+/**
+ * xAI's Grok models, smallest first (list prices from docs.x.ai/developers/pricing, October 2026,
+ * under 200k tokens of context). xAI's API is OpenAI-compatible (`XAI_BASE_URL`), so they run on the
+ * same Responses client as OpenAI's. Not in `ALL_MODELS`: an app opts in by listing them.
+ */
+export declare const XAI_MODELS: ModelDef[];
+/** xAI's OpenAI-compatible API. */
+export declare const XAI_BASE_URL = "https://api.x.ai/v1";
 /** Every model the kit knows: what a tier may run unless the app lists its own. */
 export declare const ALL_MODELS: ModelDef[];
 /** How Settings names each provider, how its keys start and where a person makes one. */

package/dist/assistant/models.js

@@ -43,6 +43,26 @@ export const OPENAI_MODELS = [
     out: o,
     read: r,
 }));
+/**
+ * xAI's Grok models, smallest first (list prices from docs.x.ai/developers/pricing, October 2026,
+ * under 200k tokens of context). xAI's API is OpenAI-compatible (`XAI_BASE_URL`), so they run on the
+ * same Responses client as OpenAI's. Not in `ALL_MODELS`: an app opts in by listing them.
+ */
+export const XAI_MODELS = [
+    ['grok-4.3', 'Grok 4.3', 1.25, 2.5, 0.2],
+    ['grok-4.6', 'Grok 4.6', 2, 6, 0.5],
+    ['grok-4.7', 'Grok 4.7', 2, 6, 0.5],
+].map(([id, label, i, o, r]) => ({
+    id: id,
+    label: label,
+    provider: 'xai',
+    group: 'xAI',
+    in: i,
+    out: o,
+    read: r,
+}));
+/** xAI's OpenAI-compatible API. */
+export const XAI_BASE_URL = 'https://api.x.ai/v1';
 /** Every model the kit knows: what a tier may run unless the app lists its own. */
 export const ALL_MODELS = [...CLAUDE_MODELS, ...OPENAI_MODELS];
 /** How Settings names each provider, how its keys start and where a person makes one. */
@@ -58,6 +78,11 @@ export const PROVIDERS = {
         keysUrl: 'https://platform.openai.com/api-keys',
         signin: 'chatgpt',
     },
+    xai: {
+        label: 'xAI',
+        prefix: 'xai-',
+        keysUrl: 'https://console.x.ai/team/default/api-keys',
+    },
 };
 /** Output tokens per model call when a tier sets none. */
 export const DEFAULT_OUT = 16_000;

package/dist/assistant/state.d.ts

@@ -193,8 +193,8 @@ export declare class State {
     addSpend(id: string, payer: AssistantPayer, parts: UsagePart[]): Promise<void>;
     /** The payer's key of each provider, those set, and which are plan sign-ins. */
     keysOf(id: string, payer: AssistantPayer): Promise<{
-        keys: Partial<Record<"anthropic" | "openai", string>>;
-        plans: Partial<Record<"anthropic" | "openai", boolean>>;
+        keys: Partial<Record<"anthropic" | "openai" | "xai", string>>;
+        plans: Partial<Record<"anthropic" | "openai" | "xai", boolean>>;
     }>;
     /** Who pays the person's next answer on `provider`'s model, or why nobody can. */
     paying(id: string, provider: AssistantProvider): Promise<{

package/package.json

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