@columenlabs/lumen-ai 0.1.71 → 0.1.73

package/README.md

@@ -1,6 +1,6 @@
 # @columenlabs/lumen-ai
 
-Assistant and agent parts for apps on Cloudflare Workers. Today: serving an MCP server from a Worker, keeping only the read tools for a read-only caller, and metering every tool call. A product-neutral assistant joins later.
+Assistant and agent parts for apps on Cloudflare Workers. Serving an MCP server from a Worker, keeping only the read tools for a read-only caller, metering every tool call, and the server side of a chat assistant (`@columenlabs/lumen-ai/assistant`).
 
 ## Install
 
@@ -54,3 +54,48 @@ app.all('/mcp', async (c) => {
 ## Versions
 
 Every merge to `main` publishes the next patch of every Lumen package at once.
+
+## A chat assistant
+
+`@columenlabs/lumen-ai/assistant` is the server behind a chat side panel: Claude on the app's own tiers, the app's tools from any MCP server, the web, drafts the person saves, hand off to a higher tier, advice, and a monthly spend cap per person. The panel and Settings sections are `@columenlabs/lumen-ui`'s; the shared types are `@columenlabs/lumen-ui-types/assistant`.
+
+```ts
+import {
+  assistantRoutes,
+  createAssistant,
+  doSql,
+  mcpServerTools,
+  sqlAssistantStore,
+} from '@columenlabs/lumen-ai/assistant';
+
+const assistant = createAssistant({
+  name: 'Helper',
+  system: 'You help people with their notes. Use the notes tools for facts.',
+  // Smallest first. The app names them; a person picks each tier's model and effort.
+  tiers: [
+    { id: 'fast', label: 'Fast', about: 'Quick lookups', model: 'claude-haiku-5-5' },
+    { id: 'steady', label: 'Steady', about: 'Most work', model: 'claude-sonnet-5-5' },
+    { id: 'deep', label: 'Deep', about: 'Hard judgement', model: 'claude-opus-5-5' },
+  ],
+  groups: [
+    { id: 'notes', label: 'Notes', about: 'Read and edit notes', tools: (caller) => mcpServerTools(() => notesServer(caller.id)) },
+  ],
+  web: { fetch: { blockHosts: ['app.example.com'] }, scrapeql: { url: 'https://scrapeql.example.com/mcp' } },
+  store: sqlAssistantStore(doSql(ctx.storage.sql)), // or d1Sql(env.DB)
+  sealer, // the app's own sealing: keys and chats are stored sealed
+  appKey: async () => env.ANTHROPIC_API_KEY, // when no key is set in Settings
+});
+
+const routes = assistantRoutes(assistant, {
+  base: '/api/assistant',
+  caller: (req) => ({ id: personId(req), admin: isAdmin(req) }),
+});
+app.all('/api/assistant/*', (c) => routes(c.req.raw));
+```
+
+- **Keys.** An admin pastes the app's Claude key (`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 its own monthly cap.
+- **Who pays.** The person's pick (the app's key by default) while it has money left this month under its cap (an admin sets the app key's 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`.
+- **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.

package/dist/assistant/engine.d.ts

@@ -0,0 +1,157 @@
+import type { AssistantAccess, AssistantChat, AssistantChatRow, AssistantMessage, AssistantStatus, DraftItem } 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';
+/** 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. */
+export interface ToolGroup {
+    id: string;
+    label: string;
+    about: string;
+    /** Where a person starts: `read` by default. */
+    access?: AssistantAccess;
+    tools: (caller: Caller) => ToolSource | ToolSource[];
+}
+/** What one step or answer was, for the app's meter: shapes only, never content. */
+export type StepRecord = {
+    kind: 'tool';
+    tool: string;
+    ok: boolean;
+    ms: number;
+    rows?: number;
+    error?: string;
+    tier: string;
+    handoff: boolean;
+} | {
+    kind: 'draft';
+    tool: string;
+    tier: string;
+    handoff: boolean;
+} | {
+    kind: 'turn';
+    outcome: 'ok' | 'stopped' | 'error';
+    ms: number;
+    tier: string;
+    end_tier: string;
+    handoffs: number;
+    advice: number;
+    steps: number;
+    calls: number;
+    in: number;
+    out: number;
+    usd: number;
+};
+export interface AssistantOptions {
+    /** What people call it ("Sage"): the panel, Settings and the model's own name. */
+    name: string;
+    /** The app's instructions: what it is, what its tools are for. */
+    system: string | ((caller: Caller) => string | Promise<string>);
+    /** The app's tiers, smallest first. */
+    tiers: TierDef[];
+    /** Tasks a person picks a starting tier for; the chat on the smallest tier by default. */
+    tasks?: TaskDef[];
+    /** Models a tier may run; Claude's by default. */
+    models?: ModelDef[];
+    groups?: ToolGroup[];
+    web?: {
+        /** `fetch` options, or false for no fetch. */
+        fetch?: WebFetchOptions | false;
+        /** ScrapeQL's MCP address; its tools join once an admin adds the Access token. */
+        scrapeql?: {
+            url: string;
+        };
+    };
+    store: AssistantStore;
+    sealer?: Sealer;
+    /** The app's key when none is stored in Settings (a Worker secret). */
+    appKey?: () => Promise<string | null | undefined>;
+    /** USD a person may spend a month when nobody set a cap; 10. */
+    defaultCap?: number;
+    /** Months and dates in this zone; UTC by default. */
+    timeZone?: string;
+    /** Chats are deleted this many days after their last message (`purge`); 30. */
+    keepDays?: number;
+    /** The fetch Anthropic and ScrapeQL calls go through. */
+    fetch?: typeof fetch;
+    onStep?: (s: StepRecord) => void | Promise<void>;
+}
+/** A turn's failure the person can act on. */
+export declare class AssistantError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(message: string, code: string, status?: number);
+}
+type Emit = (event: string, data: unknown) => void;
+export declare class Assistant {
+    private readonly o;
+    readonly name: string;
+    readonly tiers: TierDef[];
+    readonly tasks: TaskDef[];
+    readonly models: ModelDef[];
+    readonly state: State;
+    private readonly groups;
+    constructor(o: AssistantOptions);
+    private client;
+    private tierById;
+    private above;
+    private modelById;
+    /** The person's model and effort for a tier, or the tier's own when unset or gone. */
+    private pick;
+    private session;
+    /** The tier the person's chat runs on: their pick, else the chat task's start tier. */
+    private mainTier;
+    private access;
+    status(caller: Caller): Promise<AssistantStatus>;
+    listChats(caller: Caller): Promise<AssistantChatRow[]>;
+    readChat(caller: Caller, id: string): Promise<AssistantChat | null>;
+    removeChat(caller: Caller, id: string): Promise<void>;
+    /** Deletes chats past `keepDays` since their last message; run it once a day. */
+    purge(): Promise<number>;
+    private writeChat;
+    /** Opens the tools the person allows: each group's, then the web's. */
+    private openTools;
+    private toolsFor;
+    /** One answer as server-sent events. Abort `signal` to stop it. */
+    turnStream(caller: Caller, req: AssistantMessage, signal?: AbortSignal): ReadableStream<Uint8Array>;
+    turn(caller: Caller, req: AssistantMessage, emit: Emit, signal?: AbortSignal): Promise<void>;
+    /** What the kit adds to the app's instructions: tools, drafts, hand off, advice, limits. */
+    private rules;
+    /** The advisor for this answer, or null when off. Never weaker than the model it advises. */
+    private advisorFor;
+    private escalateTool;
+    /** The tiers the person's message asks for by name ("go deeper" is the next one up). */
+    private askedFor;
+    private handOff;
+    /** One tool call: a draft card for a write, else the call itself, timed. */
+    private runTool;
+    /** Model calls and tool rounds until the model answers; returns its words. */
+    private loop;
+    /** Swaps the history for a short summary. False with nothing to compact. */
+    private compact;
+    /** How the person's cards ended since the last answer, once each. */
+    private cardNews;
+    /** The answer as later turns remember it: with what its tools returned, cut. */
+    private remember;
+    /** One free call (reading a model) that says whether Claude takes the key. */
+    testKey(apiKey: string): Promise<{
+        ok: boolean;
+        detail: string;
+        at: number;
+    }>;
+    /** Lists ScrapeQL's tools with the token: works or why not. */
+    testScrapeql(token: AccessToken): Promise<{
+        ok: boolean;
+        detail: string;
+        at: number;
+    }>;
+    /** 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>;
+}
+export declare function createAssistant(o: AssistantOptions): Assistant;
+export {};