@columenlabs/lumen-ai 0.1.250 → 0.1.252

package/README.md

@@ -111,6 +111,7 @@ app.all('/api/assistant/*', (c) => routes(c.req.raw));
 - **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`.
 - **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`). A Worker on ScrapeQL's own Cloudflare account passes its service binding instead, `scrapeql: { url: 'https://scrapeql/mcp', fetch: env.SCRAPEQL.fetch.bind(env.SCRAPEQL) }`: no token is stored, the tools are always on and Settings shows the link with a Test. Each web step carries `web` (`StepWeb`: a search's `query` and `results`, or the page it `read`), so the panel folds a search's results under its line and numbers each page read under the answer as Sources chips; the model marks facts with those numbers ([1]).
+- **Web lookup (a subagent).** `web: { scrapeql, lookup: true }` swaps fetch and ScrapeQL's own tools for one tool, `web__lookup` (`webLookupTools` from `@columenlabs/lumen-ai/subagents`): given a question (and `urls` when the pages are known), it searches with ScrapeQL, has ScrapeQL's `ask` read the best pages (3 by default, `pages` up to 5) and answer in a few sentences each (`answerTokens`, default 300), and returns `{question, sources: [{url, title, answer}], failed}`: about a thousand tokens, never whole pages, so the assistant's context stays small. No model runs in the kit for it; ScrapeQL picks its own cheapest model. Its step carries `web.lookup` and `web.reads`, which the panel folds under a Looked up line and numbers as Sources chips. `fetch.blockHosts` still applies.
 - **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. A hand-off gives up after `HAND_OFF_MS` (4 minutes) and the turn goes on without it.
 - **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.

package/dist/assistant/engine.d.ts

@@ -1,5 +1,6 @@
 import type { AllowanceRequest, AllowanceState, AllowanceUnit, AssistantAccess, AssistantChat, AssistantChatRow, AssistantEffort, AssistantMessage, AssistantOwnWay, AssistantPayer, AssistantProvider, AssistantStatus, UsagePart } from '@columenlabs/lumen-ui-types/assistant';
 import type { AgentTurnEnd, AgentTurnPlan } from '../agent/agent.js';
+import { type WebLookupOptions } from '../subagents/web.js';
 import { type BearingsExtra, type BearingsNow } from './bearings.js';
 import { type ModelDef, type TaskDef, type TierDef } from './models.js';
 import { type OwnWays, State } from './state.js';
@@ -174,6 +175,12 @@ export interface AssistantOptions {
             url: string;
             fetch?: typeof fetch;
         };
+        /**
+         * One `web__lookup` tool in place of fetch and ScrapeQL's own tools: it searches, has ScrapeQL
+         * read the best pages and answer the question, and returns a short answer per page, so whole
+         * pages never reach the model. Needs `scrapeql`; without it the web is off.
+         */
+        lookup?: boolean | WebLookupOptions;
     };
     store: AssistantStore;
     sealer?: Sealer;

package/dist/assistant/engine.js

@@ -12,10 +12,11 @@ import { HAND_OFF_WHYS } from '@columenlabs/lumen-ui-types/assistant';
 import { generateText, jsonSchema, stepCountIs, tool } from 'ai';
 import OpenAI, { toFile } from 'openai';
 import { aiModel, turnSettings } from '../agent/models.js';
+import { webLookupTools } from '../subagents/web.js';
 import { bearings } from './bearings.js';
 import { CHATGPT_REDIRECT, SigninError, finishChatgpt, startChatgpt, testChatgpt, } from './chatgpt.js';
 import { ALL_MODELS, DEFAULT_OUT, Meter, PROVIDERS, XAI_BASE_URL, effortParams, } from './models.js';
-import { DEFAULT_CAP, State, keyDocName, keyState, ownKeyUsd, planDocName, waitText, withProvider, } from './state.js';
+import { DEFAULT_CAP, State, keyDocName, keyState, ownKeyUsd, ownPlanCalls, planDocName, waitText, withProvider, } from './state.js';
 import { Docs } from './store.js';
 import { toolName, withDeadline } from './tools.js';
 import { scrapeqlTools, webFetchTools } from './web.js';
@@ -408,6 +409,7 @@ export class Assistant {
                     kind: 'chat',
                     title: message.split('\n')[0] || 'Chat',
                     own_usd: ownKeyUsd(paying, onPayer),
+                    own_plan_calls: ownPlanCalls(paying, onPayer),
                 }, end.parts)
                     .catch(() => undefined);
             const total = end.parts.reduce((a, m) => ({
@@ -824,7 +826,22 @@ export class Assistant {
             for (const source of Array.isArray(s) ? s : [s])
                 sources.push({ group: g.id, access, source, ...(g.writes ? { writes: true } : {}) });
         }
-        if (p.web ?? true) {
+        const lookup = this.o.web?.lookup;
+        const blockHosts = this.o.web?.fetch ? this.o.web.fetch.blockHosts : undefined;
+        if ((p.web ?? true) && lookup) {
+            const sq = this.o.web?.scrapeql;
+            const token = sq && !sq.fetch ? await this.state.scrapeql() : null;
+            if (sq && (sq.fetch || token))
+                sources.push({
+                    group: 'web',
+                    access: 'read',
+                    source: webLookupTools(scrapeqlTools(sq.url, token, sq.fetch ?? this.o.fetch), {
+                        ...(blockHosts ? { blockHosts } : {}),
+                        ...(typeof lookup === 'object' ? lookup : {}),
+                    }),
+                });
+        }
+        else if (p.web ?? true) {
             if (this.o.web?.fetch !== false)
                 sources.push({
                     group: 'web',
@@ -869,7 +886,9 @@ export class Assistant {
             lines.push('No tools are on now: the person can turn them on in Settings ▸ Tools.');
         if (failed)
             lines.push(`${failed} tool source${failed === 1 ? '' : 's'} could not be reached this turn.`);
-        if (fns.web)
+        if (fns.web && this.o.web?.lookup)
+            lines.push("Web: web__lookup answers one question from the web: give the full question (and urls when you already know the pages); it returns a short answer from each page it read. Look up again with a sharper question rather than asking for whole pages. The person sees each page a lookup read numbered under your answer, in the order returned (the first lookup's sources first, a later lookup's after them): mark a fact with its number, like [1], and never cite a page that is not among the sources.");
+        else if (fns.web)
             lines.push('Web: use web__fetch first for APIs and plain pages; the browser tools only for pages that need JavaScript or after a fetch fails. To find pages, search, then read the one to three that answer the question. The person sees each page you read numbered under your answer, in the order you read them (1 for the first page read in this answer): mark a fact you took from a page with its number, like [1], and never cite a page you did not read.');
         if (main) {
             const reach = this.above(main.tier);
@@ -1076,6 +1095,7 @@ export class Assistant {
                 task: o.task,
                 title: o.run?.title ?? task?.label ?? o.task,
                 own_usd: ownKeyUsd(paying, [part]),
+                own_plan_calls: ownPlanCalls(paying, [part]),
             }, [part])
                 .catch(() => undefined);
         }
@@ -1164,6 +1184,7 @@ export class Assistant {
                 task: o.task,
                 title: o.run?.title ?? task?.label ?? o.task,
                 own_usd: ownKeyUsd(paying, [part]),
+                own_plan_calls: ownPlanCalls(paying, [part]),
             }, [part])
                 .catch(() => undefined);
         }

package/dist/assistant/state.d.ts

@@ -111,6 +111,11 @@ export declare function ownKeyUsd(paying: {
     payer: AssistantPayer;
     plans: Paying['plans'];
 }, parts: UsagePart[]): number;
+/** Calls in `parts` a plan sign-in of the person's answered (their own payer, a plan provider). */
+export declare function ownPlanCalls(paying: {
+    payer: AssistantPayer;
+    plans: Paying['plans'];
+}, parts: UsagePart[]): number;
 /**
  * What counts toward the person's own cap: own rows paid by an API key (a plan sign-in costs
  * nothing per call), on a provider they can still pay with. A row from before ways were recorded
@@ -276,7 +281,8 @@ export declare class State {
     /**
      * Adds one answer's use to a chat or run in this month's history (`usage:YYYY-MM`): one entry a
      * chat or run, its parts merged, the newest `USAGE_KEPT` kept. `title` names a new entry only;
-     * `own_usd` is what of this answer the person's own key or plan paid, added to the entry's.
+     * `own_usd` is what of this answer the person's own key or plan paid, added to the entry's;
+     * `own_plan_calls` the calls their plan sign-in answered (free to them, so counted, not priced).
      */
     addUsage(id: string, e: {
         id: string;
@@ -284,6 +290,7 @@ export declare class State {
         task?: string;
         title: string;
         own_usd?: number;
+        own_plan_calls?: number;
     }, parts: UsagePart[]): Promise<void>;
     /** One month's history (this month by default) beside its spend, and the months that have one. */
     usage(id: string, month?: string): Promise<UsageHistory>;

package/dist/assistant/state.js

@@ -32,6 +32,17 @@ export function ownKeyUsd(paying, parts) {
     })
         .reduce((a, p) => a + p.usd, 0);
 }
+/** Calls in `parts` a plan sign-in of the person's answered (their own payer, a plan provider). */
+export function ownPlanCalls(paying, parts) {
+    if (paying.payer !== 'own')
+        return 0;
+    return parts
+        .filter((p) => {
+        const prov = providerOfPart(p);
+        return !!(prov && paying.plans[prov]);
+    })
+        .reduce((a, p) => a + p.calls, 0);
+}
 /**
  * What counts toward the person's own cap: own rows paid by an API key (a plan sign-in costs
  * nothing per call), on a provider they can still pay with. A row from before ways were recorded
@@ -352,7 +363,8 @@ export class State {
     /**
      * Adds one answer's use to a chat or run in this month's history (`usage:YYYY-MM`): one entry a
      * chat or run, its parts merged, the newest `USAGE_KEPT` kept. `title` names a new entry only;
-     * `own_usd` is what of this answer the person's own key or plan paid, added to the entry's.
+     * `own_usd` is what of this answer the person's own key or plan paid, added to the entry's;
+     * `own_plan_calls` the calls their plan sign-in answered (free to them, so counted, not priced).
      */
     async addUsage(id, e, parts) {
         if (!parts.some((p) => p.calls))
@@ -365,6 +377,7 @@ export class State {
             const merged = mergeParts(prev?.parts ?? [], parts);
             const sum = (k) => merged.reduce((a, p) => a + p[k], 0);
             const own = (prev?.own_usd ?? 0) + (e.own_usd ?? 0);
+            const plan = (prev?.own_plan_calls ?? 0) + (e.own_plan_calls ?? 0);
             entries.unshift({
                 id: e.id,
                 kind: e.kind,
@@ -378,6 +391,7 @@ export class State {
                 out: sum('out'),
                 usd: sum('usd'),
                 ...(own > 0 ? { own_usd: own } : {}),
+                ...(plan > 0 ? { own_plan_calls: plan } : {}),
                 parts: merged,
             });
             return { entries: entries.slice(0, USAGE_KEPT) };

package/dist/assistant/web.d.ts

@@ -12,6 +12,8 @@ export interface WebFetchOptions {
     userAgent?: string;
     fetch?: typeof fetch;
 }
+/** Why a URL is refused, or null. */
+export declare function refused(url: URL, block: string[]): string | null;
 /** One GET, never thrown: what it got, or why not. */
 export declare function webFetch(raw: string, headers?: Record<string, string>, o?: WebFetchOptions): Promise<{
     ok: boolean;

package/dist/assistant/web.js

@@ -6,7 +6,7 @@ const TIMEOUT_MS = 10_000;
 const MAX_BYTES = 2_000_000;
 const DESCRIPTION = `Plain HTTP GET of one URL from the server, no browser: fast and cheap, so use it first for APIs, JSON, CSV, RSS and plain HTML. Returns {ok, status, url (after redirects), content_type, json (when the body is JSON) or text, truncated}; a failed fetch (refused, timed out, not 2xx) returns ok false with status and error. Bodies over ${MAX_BYTES / 1_000_000} MB are cut; ${TIMEOUT_MS / 1000} s per fetch. Use the browser tools (scrape, extract, ask) only for pages built by JavaScript, bot walls, or after fetch fails.`;
 /** Why a URL is refused, or null. */
-function refused(url, block) {
+export function refused(url, block) {
     if (url.protocol !== 'https:' && url.protocol !== 'http:')
         return 'only http and https';
     const host = url.hostname.toLowerCase();
@@ -212,6 +212,31 @@ export function webStep(name, input, output, failed) {
         }
         return { ...(query ? { query } : {}), results };
     }
+    if (tool === 'lookup') {
+        if (failed)
+            return undefined;
+        let o = output;
+        if (typeof o === 'string') {
+            try {
+                o = JSON.parse(o);
+            }
+            catch {
+                o = {};
+            }
+        }
+        const r = (o && typeof o === 'object' ? o : {});
+        const reads = [];
+        for (const x of Array.isArray(r.sources) ? r.sources : []) {
+            const u = (x ?? {});
+            if (typeof u.url !== 'string' || !/^https?:\/\//.test(u.url))
+                continue;
+            if (reads.some((p) => p.url === u.url))
+                continue;
+            reads.push(typeof u.title === 'string' && u.title ? { url: u.url, title: u.title } : { url: u.url });
+        }
+        const q = typeof args.question === 'string' ? args.question : r.question;
+        return { lookup: true, ...(typeof q === 'string' ? { query: q.slice(0, 300) } : {}), reads };
+    }
     if (failed) {
         const url = typeof args.url === 'string' ? args.url : '';
         return /^https?:\/\//.test(url) ? { tried: { url } } : undefined;

package/dist/subagents/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Subagents: tools that do a small job on a cheap path and hand the assistant a short result, so
+ * the assistant's own context stays small. The first is web lookup.
+ */
+export * from './web.js';

package/dist/subagents/index.js

@@ -0,0 +1,5 @@
+/**
+ * Subagents: tools that do a small job on a cheap path and hand the assistant a short result, so
+ * the assistant's own context stays small. The first is web lookup.
+ */
+export * from './web.js';

package/dist/subagents/web.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Web lookup: one tool that answers a question from the web without putting whole pages in the
+ * assistant's context. It searches (ScrapeQL `search`, no model), then has ScrapeQL `ask` read each
+ * of the best pages and answer the question in a few sentences (ScrapeQL runs that on its cheapest
+ * model). The assistant gets back a short answer per page and its address, about a thousand tokens
+ * in all, instead of the pages themselves.
+ */
+import { type ToolSource } from '../assistant/tools.js';
+export interface WebLookupOptions {
+    /** Pages read for one question; default 3, at most 5. */
+    pages?: number;
+    /** Tokens each page's answer may use; default 300 (ScrapeQL's floor is 200). */
+    answerTokens?: number;
+    /** Hosts never read (the app's own, behind sign-in), each with its subdomains. */
+    blockHosts?: string[];
+}
+/** One page a lookup read: its address, its title when the search gave one, and its answer. */
+export interface LookupSource {
+    url: string;
+    title?: string;
+    answer: string;
+}
+/** What `web__lookup` returns. */
+export interface LookupResult {
+    question: string;
+    /** The search words, when it searched. */
+    query?: string;
+    sources: LookupSource[];
+    /** Pages it could not read, and why. */
+    failed?: {
+        url: string;
+        error: string;
+    }[];
+}
+/**
+ * The `lookup` tool (in the `web` group, `web__lookup`) over ScrapeQL's tools (`scrapeqlTools`).
+ * ScrapeQL is opened on the first lookup of an answer and closed with it.
+ */
+export declare function webLookupTools(scrapeql: ToolSource, o?: WebLookupOptions): ToolSource;

package/dist/subagents/web.js

@@ -0,0 +1,133 @@
+/**
+ * Web lookup: one tool that answers a question from the web without putting whole pages in the
+ * assistant's context. It searches (ScrapeQL `search`, no model), then has ScrapeQL `ask` read each
+ * of the best pages and answer the question in a few sentences (ScrapeQL runs that on its cheapest
+ * model). The assistant gets back a short answer per page and its address, about a thousand tokens
+ * in all, instead of the pages themselves.
+ */
+import { ToolError, plainTools } from '../assistant/tools.js';
+import { refused } from '../assistant/web.js';
+const LINK = /\[([^\]\n]{0,300})\]\((https?:\/\/[^)\s]{1,2000})\)/g;
+/** ScrapeQL notes after an answer (`\n\n---\n_…_`): for an agent, not for this one. */
+const FOOTER = /\n\n---\n_[\s\S]*$/;
+const ANSWER_MAX = 2000;
+const DESCRIPTION = 'Answer a question from the web. It searches, reads the best pages and returns a short answer from each with its address: about a thousand tokens, never whole pages. Ask one specific question (a part number, a standard, a size); pass urls to read pages you already know instead of searching. Returns {question, sources: [{url, title, answer}], failed}.';
+const clamp = (n, lo, hi, d) => Math.min(hi, Math.max(lo, Math.round(n ?? d)));
+/** Text of a tool's answer: a string, or JSON of anything else. */
+const textOf = (v) => (typeof v === 'string' ? v : JSON.stringify(v ?? ''));
+/** True when `raw` is an http(s) address this lookup may read. */
+function readable(raw, block) {
+    try {
+        return refused(new URL(raw), block) === null;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The `lookup` tool (in the `web` group, `web__lookup`) over ScrapeQL's tools (`scrapeqlTools`).
+ * ScrapeQL is opened on the first lookup of an answer and closed with it.
+ */
+export function webLookupTools(scrapeql, o = {}) {
+    const pages = clamp(o.pages, 1, 5, 3);
+    const answerTokens = clamp(o.answerTokens, 200, 2000, 300);
+    const block = (o.blockHosts ?? []).map((h) => h.toLowerCase());
+    return async () => {
+        let open;
+        const sq = () => {
+            open ??= scrapeql();
+            return open;
+        };
+        const tools = await plainTools([
+            {
+                name: 'lookup',
+                title: 'Look it up on the web',
+                description: DESCRIPTION,
+                read: true,
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        question: {
+                            type: 'string',
+                            maxLength: 500,
+                            description: 'The question each page should answer, in full.',
+                        },
+                        search: {
+                            type: 'string',
+                            maxLength: 300,
+                            description: 'Search words, when they differ from the question.',
+                        },
+                        urls: {
+                            type: 'array',
+                            items: { type: 'string', maxLength: 2000 },
+                            maxItems: pages,
+                            description: 'Pages to read instead of searching.',
+                        },
+                    },
+                    required: ['question'],
+                },
+                async run(args) {
+                    const a = (args ?? {});
+                    const question = String(a.question ?? '')
+                        .trim()
+                        .slice(0, 500);
+                    if (!question)
+                        throw new ToolError('Give the question to look up.');
+                    const given = Array.isArray(a.urls) ? a.urls.map(String) : [];
+                    const t = await sq();
+                    let query;
+                    let picks;
+                    if (given.length) {
+                        picks = given.filter((u) => readable(u, block)).map((url) => ({ url }));
+                        if (!picks.length)
+                            throw new ToolError('None of those addresses can be read.');
+                    }
+                    else {
+                        query =
+                            String(a.search ?? '')
+                                .trim()
+                                .slice(0, 300) || question;
+                        const found = textOf(await t.call('search', { query, limit: pages + 3 }));
+                        picks = [];
+                        for (const m of found.matchAll(LINK)) {
+                            const url = m[2];
+                            if (!readable(url, block) || picks.some((p) => p.url === url))
+                                continue;
+                            const title = m[1].trim();
+                            picks.push(title && title !== url ? { url, title } : { url });
+                        }
+                    }
+                    picks = picks.slice(0, pages);
+                    const out = { question, ...(query ? { query } : {}), sources: [] };
+                    if (!picks.length)
+                        return out;
+                    const read = await Promise.all(picks.map(async (p) => {
+                        try {
+                            const r = textOf(await t.call('ask', { url: p.url, question, budgetTokens: answerTokens }));
+                            return { ...p, answer: r.replace(FOOTER, '').trim().slice(0, ANSWER_MAX) };
+                        }
+                        catch (err) {
+                            return { url: p.url, error: String(err?.message ?? err).slice(0, 200) };
+                        }
+                    }));
+                    const failed = [];
+                    for (const r of read)
+                        if ('answer' in r) {
+                            if (r.answer)
+                                out.sources.push(r);
+                        }
+                        else
+                            failed.push(r);
+                    return failed.length ? { ...out, failed } : out;
+                },
+            },
+        ])();
+        return {
+            ...tools,
+            async close() {
+                if (open)
+                    await (await open.catch(() => null))?.close();
+            },
+        };
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@columenlabs/lumen-ai",
-  "version": "0.1.250",
+  "version": "0.1.252",
   "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",
@@ -26,6 +26,10 @@
     "./workspaces": {
       "types": "./dist/workspaces/index.d.ts",
       "default": "./dist/workspaces/index.js"
+    },
+    "./subagents": {
+      "types": "./dist/subagents/index.d.ts",
+      "default": "./dist/subagents/index.js"
     }
   },
   "files": [
@@ -52,8 +56,8 @@
     "@ai-sdk/openai": "4.0.108",
     "@anthropic-ai/sdk": "0.133.0",
     "@cloudflare/think": "0.23.0",
-    "@columenlabs/lumen-ops": "0.1.250",
-    "@columenlabs/lumen-ui-types": "0.1.250",
+    "@columenlabs/lumen-ops": "0.1.252",
+    "@columenlabs/lumen-ui-types": "0.1.252",
     "agents": "0.32.0",
     "ai": "7.0.162",
     "just-bash": "3.6.0",