@columenlabs/lumen-ai 0.1.180 → 0.1.181

package/README.md

@@ -230,6 +230,10 @@ An app with an `Assistant` gets the whole plan from it: `assistant.agentTurn(cal
 
 Drafts and writes are cards in the chat's own storage (`lumen_cards` in the agent's SQLite). A write the person's access only drafts makes an open card and changes nothing. `saveCard(id)` runs it through the app's `applyDraft`, and `dismissCard(id)` drops it. A write made at once is kept for `undoCard(id)` through the app's `undoWrite`. `cards()` lists the cards. The next answer is told how each card ended and what was undone. With an `Assistant`, `applyDraft` is `assistant.runDraft(caller, card)` and `undoWrite` is `assistant.undoChange(caller, card)`. Think compacts the chat past `COMPACT_AT` (150k tokens) on the last answer's model and key, and that spend is added to the next answer.
 
+**Connectors.** A person adds an MCP server to their chat with `addConnector(name, url)`. The address must be https. The server signs in with its own OAuth through Think's MCP client, and the answer carries `authUrl` while it asks. `connectors()` lists them and `removeConnector(id)` drops one. Think never merges their tools on its own (`includeMcpTools` is false). A turn opens the ones `plan.connectors` lists, at the access the app gives each, as group `mcp_<id>`. Read keeps the tools the server marks read-only. Read + draft makes the rest cards, which `saveCard` runs on the server itself. Read + write runs them at once with no Undo. A connector's text is untrusted data.
+
+**Lazy tools.** Past `LAZY_AT` (30) tools, a turn sends the model its core tools and `tool_search`, with one catalog line per group in the instructions. By default the core tools are the apps' finds, the hand off and the advisor. `plan.lazy` sets `{ at, core }`. A search matches the words in a tool's name and description and turns on up to 8 tools from the next step on.
+
 ```ts
 class Chat extends LumenAgent<Env> {
   #settle?: (end: AgentTurnEnd) => Promise<void>;

package/dist/agent/agent.d.ts

@@ -15,6 +15,7 @@ import { type ChatResponseResult, type PrepareStepContext, type Session, type St
 import type { AssistantEffort, UsagePart } from '@columenlabs/lumen-ui-types/assistant';
 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 AiToolsOptions, type OpenedTools, type SourceAt } from './tools.js';
 import { UsageMeter } from './usage.js';
@@ -46,6 +47,13 @@ export interface AgentTurnPlan {
     more?: (t: TurnTools) => ToolSet;
     /** Call this tool first (a message handed to a higher tier). */
     first?: string;
+    /** The person's connectors to open, at the access they gave each. */
+    connectors?: ConnectorAt[];
+    /** Past `at` tools (`LAZY_AT`) the model starts with `core` and `tool_search` only. */
+    lazy?: {
+        at?: number;
+        core?: string[];
+    };
     /** Claude's advisor: a bigger Claude reads the chat and sends a plan. */
     advisor?: {
         model: ModelDef;
@@ -104,6 +112,17 @@ export declare abstract class LumenAgent<Env = unknown> extends Think<Env> {
     protected applyDraft(_card: AgentCard): Promise<unknown>;
     /** Takes back a write made at once (Undo). */
     protected undoWrite(_card: AgentCard): Promise<void>;
+    /** Connectors' tools join a turn through `plan.connectors`, at the person's access. */
+    includeMcpTools: boolean;
+    /** The person's connectors, with their state and tool counts. */
+    connectors(): AgentConnector[];
+    /** Adds a connector by its https address; the answer says where to sign in when it asks. */
+    addConnector(name: string, url: string, o?: {
+        callbackHost?: string;
+        callbackPath?: string;
+    }): Promise<AgentConnector>;
+    /** Removes a connector and its sign-in. */
+    removeConnector(id: string): Promise<void>;
     /** The chat's cards, newest last: drafts and writes made at once (at most 200). */
     cards(): AgentCard[];
     /** The person saved a draft: its write runs now. */

package/dist/agent/agent.js

@@ -15,7 +15,9 @@ import { anthropic } from '@ai-sdk/anthropic';
 import { Think, } from '@cloudflare/think';
 import { createCompactFunction } from 'agents/sessions';
 import { generateText } from 'ai';
+import { CONNECTOR_GROUP, checkConnectorUrl, connectorGroup, connectorId, connectorSource, } from './connectors.js';
 import { aiModel, turnSettings } from './models.js';
+import { LAZY_AT, TOOL_SEARCH, lazyTools } from './search.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.';
@@ -71,6 +73,8 @@ export class LumenAgent extends Think {
     undoWrite(_card) {
         return Promise.reject(new Error('This change cannot be undone here.'));
     }
+    /** Connectors' tools join a turn through `plan.connectors`, at the person's access. */
+    includeMcpTools = false;
     #turn = null;
     /** The last turn's model and key, for compaction between turns. */
     #last = null;
@@ -100,6 +104,43 @@ export class LumenAgent extends Think {
         this
             .sql `UPDATE lumen_cards SET status = ${status}, result = COALESCE(${o.result === undefined ? null : JSON.stringify(o.result).slice(0, 20_000)}, result), error = ${o.error ?? null}, told = 0 WHERE id = ${id}`;
     }
+    #connectorClient() {
+        return {
+            listTools: () => this.getMcpServers().tools,
+            callTool: (p) => this.mcp.callTool(p),
+        };
+    }
+    /** The person's connectors, with their state and tool counts. */
+    connectors() {
+        const { servers, tools } = this.getMcpServers();
+        return Object.entries(servers).map(([id, s]) => {
+            const own = tools.filter((t) => t.serverId === id);
+            return {
+                id,
+                name: s.name,
+                url: s.server_url,
+                state: s.state,
+                ...(s.auth_url ? { authUrl: s.auth_url } : {}),
+                ...(s.error ? { error: s.error.slice(0, 300) } : {}),
+                tools: own.length,
+                reads: own.filter((t) => t.annotations?.readOnlyHint === true).length,
+            };
+        });
+    }
+    /** Adds a connector by its https address; the answer says where to sign in when it asks. */
+    async addConnector(name, url, o = {}) {
+        const u = checkConnectorUrl(url);
+        const id = connectorId(name);
+        await this.addMcpServer(name.slice(0, 60), u.href, { id, ...o });
+        const c = this.connectors().find((x) => x.id === id);
+        if (!c)
+            throw new Error('The connector did not stay.');
+        return c;
+    }
+    /** Removes a connector and its sign-in. */
+    async removeConnector(id) {
+        await this.removeMcpServer(id);
+    }
     /** The chat's cards, newest last: drafts and writes made at once (at most 200). */
     cards() {
         this.#cards();
@@ -115,7 +156,13 @@ export class LumenAgent extends Think {
         if (c.status !== 'open')
             throw new Error(`That card is already ${c.status}.`);
         try {
-            this.#setCard(id, 'saved', { result: await this.applyDraft(c) });
+            const server = c.group.startsWith(CONNECTOR_GROUP)
+                ? c.group.slice(CONNECTOR_GROUP.length)
+                : null;
+            const result = server
+                ? await (await connectorSource(this.#connectorClient(), server)()).call(c.tool, c.args)
+                : await this.applyDraft(c);
+            this.#setCard(id, 'saved', { result });
         }
         catch (err) {
             this.#setCard(id, 'failed', { error: String(err?.message ?? err).slice(0, 300) });
@@ -186,9 +233,23 @@ export class LumenAgent extends Think {
         await this.#close();
         const plan = await this.plan(ctx);
         this.#last = { plan };
-        const opened = await openAiTools(plan.sources, {
+        const linked = (plan.connectors ?? []).filter((c) => c.access !== 'off');
+        if (linked.length)
+            await this.mcp.waitForConnections({ timeout: 1500 }).catch(() => undefined);
+        const client = this.#connectorClient();
+        const sources = [
+            ...plan.sources,
+            ...linked.map((c) => ({
+                group: connectorGroup(c.id),
+                access: c.access,
+                source: connectorSource(client, c.id),
+                writes: true,
+            })),
+        ];
+        const opened = await openAiTools(sources, {
             draft: async (d) => ({ card: this.#addCard('draft', d), note: CARD_NOTE }),
-            wrote: async (w) => this.#addCard('write', w, w.result),
+            // A connector's change cannot be taken back, so it gets no Undo card.
+            wrote: async (w) => w.group.startsWith(CONNECTOR_GROUP) ? undefined : this.#addCard('write', w, w.result),
             ...plan.tools,
         });
         const free = !!plan.key.plan;
@@ -200,7 +261,7 @@ export class LumenAgent extends Think {
             : undefined;
         if (advice)
             meters.push(advice);
-        const system = typeof plan.system === 'string' ? plan.system : plan.system(opened);
+        let system = typeof plan.system === 'string' ? plan.system : plan.system(opened);
         this.#turn = {
             plan,
             system,
@@ -228,6 +289,23 @@ export class LumenAgent extends Think {
                 maxUses: plan.advisor.maxUses,
                 maxTokens: plan.advisor.maxTokens,
             });
+        const tools = { ...opened.tools, ...more, ...advisor };
+        let lazy;
+        if (Object.keys(tools).length > (plan.lazy?.at ?? LAZY_AT)) {
+            const groups = new Map(opened.info.map((i) => [i.name, i.group]));
+            const core = plan.lazy?.core ?? [
+                ...opened.info.filter((i) => i.find).map((i) => i.name),
+                ...Object.keys(more ?? {}),
+                ...Object.keys(advisor),
+            ];
+            if (plan.first && !core.includes(plan.first))
+                core.push(plan.first);
+            lazy = lazyTools(tools, core, (n) => groups.get(n) ?? 'other');
+            tools[TOOL_SEARCH] = lazy.search;
+            system = `${system}\n\n${lazy.catalog}`;
+            this.#turn.system = system;
+            this.#turn.lazy = lazy;
+        }
         return {
             model: aiModel(plan.model, plan.key, {
                 ...(plan.fetch ? { fetch: plan.fetch } : {}),
@@ -235,7 +313,8 @@ export class LumenAgent extends Think {
             }),
             instructions: system,
             messages: withLead(ctx.messages, `${this.#news()}${plan.lead ?? ''}`),
-            tools: { ...opened.tools, ...more, ...advisor },
+            tools,
+            ...(lazy ? { activeTools: lazy.active() } : {}),
             ...(plan.first ? { toolChoice: { type: 'tool', toolName: plan.first } } : {}),
             maxSteps: plan.maxSteps ?? 8,
             ...turnSettings(plan.model, {
@@ -254,10 +333,14 @@ export class LumenAgent extends Think {
             t.capped = true;
             return { activeTools: [], instructions: `${t.system}\n\n${CAP_NOTE}` };
         }
-        // A forced first call is for the first step only.
-        if (t.plan.first && ctx.stepNumber > 0)
-            return { toolChoice: 'auto' };
-        return undefined;
+        // 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)
+            return undefined;
+        return {
+            ...(auto ? { toolChoice: 'auto' } : {}),
+            ...(t.lazy ? { activeTools: t.lazy.active() } : {}),
+        };
     }
     onStepFinish(ctx) {
         const t = this.#turn;

package/dist/agent/connectors.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Connectors: MCP servers a person adds to their chat (a URL, signed in with the server's own
+ * OAuth through Think's MCP client). Each is a tool group like the app's own, at the access the
+ * app gives it: Read keeps the tools the server marks read-only, Read + draft turns the rest into
+ * cards, Read + write runs them at once. A server's text is untrusted data, never instructions.
+ */
+import type { AssistantAccess } from '@columenlabs/lumen-ui-types/assistant';
+import { type ToolSource } from '../assistant/tools.js';
+/** A connector's tool group: `mcp_` and its id. */
+export declare const CONNECTOR_GROUP = "mcp_";
+export declare const connectorGroup: (id: string) => string;
+/** One connector the app opens for a turn, at the access the person gave it. */
+export interface ConnectorAt {
+    id: string;
+    access: AssistantAccess;
+}
+/** A connector as the app's settings list it. */
+export interface AgentConnector {
+    id: string;
+    name: string;
+    url: string;
+    state: string;
+    /** Where the person signs in, while the server asks for it. */
+    authUrl?: string;
+    error?: string;
+    /** Its tools, and how many are marked read-only. */
+    tools: number;
+    reads: number;
+}
+interface McpTool {
+    name: string;
+    serverId: string;
+    title?: string;
+    description?: string;
+    inputSchema: unknown;
+    annotations?: {
+        readOnlyHint?: boolean;
+        title?: string;
+    };
+}
+/** The part of Think's MCP client a connector needs. */
+export interface ConnectorClient {
+    listTools(): McpTool[];
+    callTool(p: {
+        serverId: string;
+        name: string;
+        arguments: Record<string, unknown>;
+    }): Promise<{
+        content?: unknown;
+        isError?: boolean;
+    }>;
+}
+/** What a connector's call answered: its text as JSON when it parses, else the text. */
+export declare function connectorResult(r: {
+    content?: unknown;
+    isError?: boolean;
+}, name: string): unknown;
+/** One connector's tools as a source: listed from the client's catalog, called through it. */
+export declare function connectorSource(mcp: ConnectorClient, serverId: string): ToolSource;
+/** A connector's id from its name: a letter first, then letters, digits and `_`, at most 24. */
+export declare function connectorId(name: string): string;
+/** A connector's address must be https (localhost only while developing). */
+export declare function checkConnectorUrl(url: string): URL;
+export {};

package/dist/agent/connectors.js

@@ -0,0 +1,71 @@
+import { ToolError, withDeadline } from '../assistant/tools.js';
+/** A connector's tool group: `mcp_` and its id. */
+export const CONNECTOR_GROUP = 'mcp_';
+export const connectorGroup = (id) => `${CONNECTOR_GROUP}${id}`;
+/** What a connector's call answered: its text as JSON when it parses, else the text. */
+export function connectorResult(r, name) {
+    const parts = r.content ?? [];
+    const text = parts
+        .filter((c) => c.type === 'text' && c.text)
+        .map((c) => c.text)
+        .join('\n');
+    if (r.isError)
+        throw new ToolError(text.slice(0, 500) || `${name} failed`);
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+/** One connector's tools as a source: listed from the client's catalog, called through it. */
+export function connectorSource(mcp, serverId) {
+    return async () => ({
+        tools: mcp
+            .listTools()
+            .filter((t) => t.serverId === serverId)
+            .map((t) => {
+            const title = t.title ?? t.annotations?.title;
+            return {
+                name: t.name,
+                ...(title ? { title } : {}),
+                ...(t.description ? { description: t.description } : {}),
+                inputSchema: (t.inputSchema ?? { type: 'object' }),
+                read: t.annotations?.readOnlyHint === true,
+            };
+        }),
+        call: async (name, args) => connectorResult(await withDeadline(`${name}`, 60_000, mcp.callTool({
+            serverId,
+            name,
+            arguments: (args ?? {}),
+        })), name),
+        close: async () => undefined,
+    });
+}
+/** A connector's id from its name: a letter first, then letters, digits and `_`, at most 24. */
+export function connectorId(name) {
+    const id = name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .slice(0, 24);
+    if (!id)
+        throw new Error('Give the connector a name.');
+    return /^[a-z]/.test(id) ? id : `c_${id}`.slice(0, 24);
+}
+/** A connector's address must be https (localhost only while developing). */
+export function checkConnectorUrl(url) {
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        throw new Error('That is not a web address.');
+    }
+    const local = u.hostname === 'localhost' || u.hostname === '127.0.0.1';
+    if (u.protocol !== 'https:' && !(local && u.protocol === 'http:'))
+        throw new Error('A connector needs an https address.');
+    if (u.username || u.password)
+        throw new Error('Leave sign-in details out of the address.');
+    return u;
+}

package/dist/agent/index.d.ts

@@ -4,6 +4,8 @@
  * payer rules; Think keeps the loop, the messages, streaming, resume and compaction.
  */
 export * from './agent.js';
+export * from './connectors.js';
 export * from './models.js';
+export * from './search.js';
 export * from './tools.js';
 export * from './usage.js';

package/dist/agent/index.js

@@ -4,6 +4,8 @@
  * payer rules; Think keeps the loop, the messages, streaming, resume and compaction.
  */
 export * from './agent.js';
+export * from './connectors.js';
 export * from './models.js';
+export * from './search.js';
 export * from './tools.js';
 export * from './usage.js';

package/dist/agent/search.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Lazy tools: past `LAZY_AT` tools a turn sends the model only its core tools and `tool_search`,
+ * with one catalog line per group in the instructions. A search finds tools by their name and
+ * description and turns them on from the next step, so a big set (many connectors) costs a short
+ * prompt instead of every schema on every call.
+ */
+import { type Tool, type ToolSet } from 'ai';
+/** Past this many tools a turn starts with `tool_search` and its core tools only. */
+export declare const LAZY_AT = 30;
+export declare const TOOL_SEARCH = "tool_search";
+export interface LazyTools {
+    /** The search tool, to add to the turn's tools. */
+    search: Tool;
+    /** One line per group, for the instructions. */
+    catalog: string;
+    /** The names to keep active now: the core tools, the search and what it found. */
+    active(): string[];
+}
+/** How well a tool's name and description match the query's words. */
+export declare function toolScore(query: string, name: string, description?: string): number;
+/**
+ * A search over `tools` whose finds stay on for the rest of the turn. `core` names are always on;
+ * `groupOf` names each tool's group for the catalog.
+ */
+export declare function lazyTools(tools: ToolSet, core: string[], groupOf: (name: string) => string): LazyTools;

package/dist/agent/search.js

@@ -0,0 +1,93 @@
+/**
+ * Lazy tools: past `LAZY_AT` tools a turn sends the model only its core tools and `tool_search`,
+ * with one catalog line per group in the instructions. A search finds tools by their name and
+ * description and turns them on from the next step, so a big set (many connectors) costs a short
+ * prompt instead of every schema on every call.
+ */
+import { jsonSchema, tool } from 'ai';
+/** Past this many tools a turn starts with `tool_search` and its core tools only. */
+export const LAZY_AT = 30;
+export const TOOL_SEARCH = 'tool_search';
+/** Most tools one search turns on. */
+const FOUND_MAX = 8;
+const words = (s) => s
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((w) => w.length > 1);
+/** How well a tool's name and description match the query's words. */
+export function toolScore(query, name, description = '') {
+    const q = words(query);
+    if (!q.length)
+        return 0;
+    const n = new Set(words(name));
+    const d = new Set(words(description));
+    let score = 0;
+    for (const w of q) {
+        if (n.has(w))
+            score += 3;
+        else if ([...n].some((x) => x.startsWith(w) || w.startsWith(x)))
+            score += 2;
+        if (d.has(w))
+            score += 1;
+    }
+    return score;
+}
+/**
+ * A search over `tools` whose finds stay on for the rest of the turn. `core` names are always on;
+ * `groupOf` names each tool's group for the catalog.
+ */
+export function lazyTools(tools, core, groupOf) {
+    const found = new Set();
+    const about = (n) => {
+        const d = tools[n]?.description;
+        return typeof d === 'string' ? d : '';
+    };
+    const names = Object.keys(tools);
+    const groups = new Map();
+    for (const n of names) {
+        if (core.includes(n))
+            continue;
+        const g = groupOf(n);
+        groups.set(g, (groups.get(g) ?? 0) + 1);
+    }
+    const catalog = `More tools are off until you find them: call ${TOOL_SEARCH} with a few words of what you need, then call what it finds. Groups: ${[
+        ...groups,
+    ]
+        .map(([g, n]) => `${g} (${n})`)
+        .join(', ')}.`;
+    const search = tool({
+        description: 'Finds tools by what they do and turns them on for your next call. Give a few words (e.g. "create calendar event"), and a group to look in only it.',
+        inputSchema: jsonSchema({
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'A few words of what the tool does.' },
+                group: { type: 'string', description: 'Look in this group only.' },
+            },
+            required: ['query'],
+        }),
+        execute: async ({ query, group }) => {
+            const hits = names
+                .filter((n) => !core.includes(n) && (!group || groupOf(n) === group))
+                .map((n) => ({ n, s: toolScore(query, n, about(n)) }))
+                .filter((h) => h.s > 0)
+                .sort((a, b) => b.s - a.s)
+                .slice(0, FOUND_MAX);
+            for (const h of hits)
+                found.add(h.n);
+            if (!hits.length)
+                return { found: [], note: 'Nothing matched. Try other words or a group.' };
+            return {
+                found: hits.map((h) => ({
+                    name: h.n,
+                    description: about(h.n).slice(0, 300),
+                })),
+                note: 'These are on from your next call.',
+            };
+        },
+    });
+    return {
+        search,
+        catalog,
+        active: () => [...core, TOOL_SEARCH, ...found],
+    };
+}

package/package.json

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