@columenlabs/lumen-ai 0.1.72 → 0.1.74

package/dist/assistant/engine.js

@@ -0,0 +1,1064 @@
+/**
+ * The assistant: one turn loop for any app, ported from a production assistant.
+ *
+ * A turn streams the model's words and runs its tool calls until it answers (at most `MAX_ROUNDS`
+ * rounds). A write tool only drafts: a card the person saves or dismisses. Stop aborts the model
+ * and any running tool at once and keeps what was said. Past `COMPACT_AT` tokens (or on
+ * `/compact`) the history sent to the model becomes a short summary; the screen keeps every message.
+ *
+ * Hand off: an `escalate` tool hands one task to a higher tier with the same tools, in its own
+ * section of the chat, and its memo goes back. Advice: Anthropic's advisor tool lets a higher tier
+ * read the chat and send a plan (it runs nothing), at most `ADVICE_MAX` an answer.
+ *
+ * Spend: every call is priced at list price as it runs; past what its payer has left this month the
+ * model must answer from what it has.
+ */
+import Anthropic from '@anthropic-ai/sdk';
+import { HAND_OFF_WHYS } from '@columenlabs/lumen-ui-types/assistant';
+import { CLAUDE_MODELS, DEFAULT_OUT, Meter, effortParams, } from './models.js';
+import { DEFAULT_CAP, State, WAIT_TEXT, keyState } from './state.js';
+import { Docs } from './store.js';
+import { ToolError, rowCount, toolName, withDeadline, } from './tools.js';
+import { scrapeqlTools, webFetchTools } from './web.js';
+/** A turn's failure the person can act on. */
+export class AssistantError extends Error {
+    code;
+    status;
+    constructor(message, code, status = 400) {
+        super(message);
+        this.code = code;
+        this.status = status;
+    }
+}
+const MAX_ROUNDS = 8;
+const COMPACT_AT = 150_000;
+/** A tool result handed to the model is cut past this (about 4,000 tokens). */
+const RESULT_CHARS = 16_000;
+const MEMO_CHARS = 8000;
+const ADVICE_MAX = 2;
+const ADVICE_TOKENS = 2048;
+const ADVISOR_BETA = 'advisor-tool-2026-03-01';
+/** What later turns remember of a turn's tool results. */
+const RAN_CHARS = 1500;
+const RAN_TOTAL = 6000;
+const CHATS_LISTED = 200;
+const WHY_TEXT = {
+    asked: 'you asked',
+    judgement: 'judgement',
+    stuck: 'stuck',
+    check_failed: 'check failed',
+};
+const NO_USAGE = { calls: 0, in: 0, read: 0, out: 0, usd: 0, parts: [] };
+function addUsage(u, parts) {
+    const out = { ...u, parts: u.parts.map((p) => ({ ...p })) };
+    for (const p of parts) {
+        if (!p.calls)
+            continue;
+        out.calls += p.calls;
+        out.in += p.in;
+        out.read += p.read;
+        out.out += p.out;
+        out.usd += p.usd;
+        const prev = out.parts.find((x) => x.label === p.label);
+        if (prev) {
+            prev.calls += p.calls;
+            prev.in += p.in;
+            prev.read += p.read;
+            prev.out += p.out;
+            prev.usd += p.usd;
+        }
+        else
+            out.parts.push({ ...p });
+    }
+    return out;
+}
+function withCacheMark(m) {
+    const blocks = typeof m.content === 'string' ? [{ type: 'text', text: m.content }] : [...m.content];
+    const last = blocks[blocks.length - 1];
+    if (!last || last.type === 'thinking' || last.type === 'redacted_thinking')
+        return m;
+    blocks[blocks.length - 1] = { ...last, cache_control: { type: 'ephemeral' } };
+    return { ...m, content: blocks };
+}
+/** A tool's result, or Stop's abort as soon as it comes. */
+function untilStopped(work, signal) {
+    if (!signal)
+        return work;
+    signal.throwIfAborted();
+    return new Promise((done, fail) => {
+        const stop = () => fail(signal.reason);
+        signal.addEventListener('abort', stop, { once: true });
+        work.then(done, fail).finally(() => signal.removeEventListener('abort', stop));
+    });
+}
+const newId = (prefix) => `${prefix}_${crypto.randomUUID().replaceAll('-', '').slice(0, 20)}`;
+/** Every draft in a chat, those in hand-off sections included. */
+function draftsOf(items) {
+    return items.flatMap((i) => i.kind === 'draft' ? [i] : i.kind === 'handoff' ? draftsOf(i.items) : []);
+}
+/** A short line of what an error was, never an upstream body. */
+function shownError(err) {
+    if (err instanceof AssistantError)
+        return { message: err.message, code: err.code };
+    if (err instanceof Anthropic.APIError) {
+        if (err.status === 401)
+            return { message: 'The Claude key was refused.', code: 'key_refused' };
+        if (err.status === 429)
+            return {
+                message: 'Claude is busy or the key hit its rate limit. Try again shortly.',
+                code: 'rate_limited',
+            };
+        if (err.status === 529 || (err.status ?? 0) >= 500)
+            return { message: 'Claude is overloaded. Try again shortly.', code: 'overloaded' };
+        return {
+            message: `Claude refused the request (${err.status ?? 'error'}).`,
+            code: 'model_error',
+        };
+    }
+    return { message: 'Something went wrong while answering.', code: 'internal' };
+}
+export class Assistant {
+    o;
+    name;
+    tiers;
+    tasks;
+    models;
+    state;
+    groups;
+    constructor(o) {
+        this.o = o;
+        if (!o.tiers.length)
+            throw new Error('An assistant needs at least one tier');
+        this.name = o.name;
+        this.tiers = o.tiers;
+        this.models = o.models ?? CLAUDE_MODELS;
+        this.tasks = o.tasks ?? [
+            { id: 'chat', label: 'Chat', about: 'The side panel', tier: o.tiers[0].id },
+        ];
+        this.groups = o.groups ?? [];
+        this.state = new State(new Docs(o.store, o.sealer), {
+            timeZone: o.timeZone ?? 'UTC',
+            defaultCap: o.defaultCap ?? DEFAULT_CAP,
+            ...(o.appKey ? { appKey: o.appKey } : {}),
+        });
+    }
+    client(apiKey) {
+        const f = this.o.fetch;
+        return new Anthropic({ apiKey, maxRetries: 1, ...(f ? { fetch: f } : {}) });
+    }
+    tierById(id) {
+        return this.tiers.find((t) => t.id === id);
+    }
+    above(main) {
+        return this.tiers.slice(this.tiers.indexOf(main) + 1);
+    }
+    modelById(id) {
+        return this.models.find((m) => m.id === id);
+    }
+    /** The person's model and effort for a tier, or the tier's own when unset or gone. */
+    async pick(caller, tier) {
+        const saved = (await this.state.person(caller.id)).tiers?.[tier.id];
+        const model = this.modelById(saved?.model) ?? this.modelById(tier.model) ?? this.models[0];
+        return { model, effort: saved?.effort ?? 'default' };
+    }
+    async session(caller, tier, label) {
+        const { model, effort } = await this.pick(caller, tier);
+        return {
+            tier,
+            model,
+            effort,
+            meter: new Meter(model, label ?? `${tier.label} · ${model.label}`),
+        };
+    }
+    /** The tier the person's chat runs on: their pick, else the chat task's start tier. */
+    async mainTier(caller, task = 'chat') {
+        const p = await this.state.person(caller.id);
+        const startId = p.tasks?.[task] ?? this.tasks.find((t) => t.id === task)?.tier;
+        return (this.tierById(task === 'chat' ? (p.tier ?? startId) : startId) ?? this.tiers[0]);
+    }
+    access(p, g) {
+        return p.access?.[g.id] ?? g.access ?? 'read';
+    }
+    // ---------------------------------------------------------------- status and settings
+    async status(caller) {
+        const [p, appDoc, appKey, own, scrapeql, spend, appCap, { paying, wait }, main] = await Promise.all([
+            this.state.person(caller.id),
+            this.state.appKey(),
+            this.state.appApiKey(),
+            this.state.ownKey(caller.id),
+            this.o.web?.scrapeql ? this.state.scrapeql() : Promise.resolve(null),
+            this.state.spend(caller.id),
+            this.state.appCap(),
+            this.state.paying(caller.id),
+            this.mainTier(caller),
+        ]);
+        const tiers = await Promise.all(this.tiers.map(async (t) => {
+            const { model, effort } = await this.pick(caller, t);
+            return {
+                id: t.id,
+                label: t.label,
+                about: t.about,
+                model: model.id,
+                model_label: model.label,
+                effort,
+            };
+        }));
+        const appState = caller.admin
+            ? keyState(appDoc, (d) => d.api_key)
+            : { set: !!appKey };
+        return {
+            name: this.name,
+            wait,
+            admin: caller.admin,
+            tier: main.id,
+            tiers,
+            models: this.models.map((m) => ({ id: m.id, label: m.label, group: m.group })),
+            tasks: this.tasks.map((t) => ({
+                id: t.id,
+                label: t.label,
+                about: t.about,
+                tier: this.tierById(p.tasks?.[t.id])?.id ?? t.tier,
+            })),
+            groups: this.groups.map((g) => ({
+                id: g.id,
+                label: g.label,
+                about: g.about,
+                access: this.access(p, g),
+                drafts: true,
+            })),
+            hand_off: p.hand_off ?? 'next',
+            advice: p.advice && (p.advice === 'off' || this.tierById(p.advice)) ? p.advice : 'off',
+            web: {
+                fetch: p.web ?? true,
+                scrapeql: this.o.web?.scrapeql
+                    ? caller.admin
+                        ? keyState(scrapeql, (d) => d.client_id)
+                        : { set: !!scrapeql }
+                    : null,
+            },
+            keys: {
+                app: { ...appState, cap: appCap, ...(appKey?.fromEnv ? { from_env: true } : {}) },
+                own: {
+                    ...keyState(own, (d) => d.api_key),
+                    cap: own?.cap_usd ?? this.o.defaultCap ?? DEFAULT_CAP,
+                },
+            },
+            pay: p.pay ?? 'app',
+            spend: {
+                month: this.state.month(),
+                usd: spend.rows.reduce((a, r) => a + r.usd, 0),
+                cap: paying?.cap ?? null,
+                payer: paying?.payer ?? null,
+                rows: spend.rows,
+            },
+        };
+    }
+    // ---------------------------------------------------------------- chats
+    async listChats(caller) {
+        const rows = await this.state.docs.list(caller.id, 'chat:', CHATS_LISTED);
+        return rows.map((r) => ({ id: r.key.slice(5), title: r.meta ?? '', at: r.at }));
+    }
+    async readChat(caller, id) {
+        const d = await this.state.docs.read(caller.id, `chat:${id}`);
+        if (!d)
+            return null;
+        return {
+            id,
+            title: d.title,
+            at: d.at ?? Date.now(),
+            items: d.items,
+            ...(d.usage ? { usage: d.usage } : {}),
+        };
+    }
+    removeChat(caller, id) {
+        return this.state.docs.remove(caller.id, `chat:${id}`);
+    }
+    /** Deletes chats past `keepDays` since their last message; run it once a day. */
+    purge() {
+        return this.o.store.purge('chat:', Date.now() - (this.o.keepDays ?? 30) * 86_400_000);
+    }
+    writeChat(caller, id, doc) {
+        return this.state.docs.write(caller.id, `chat:${id}`, { ...doc, at: Date.now() }, doc.title);
+    }
+    // ---------------------------------------------------------------- tools
+    /** Opens the tools the person allows: each group's, then the web's. */
+    async openTools(caller, p) {
+        const opened = [];
+        const sources = [];
+        for (const g of this.groups) {
+            const access = this.access(p, g);
+            if (access === 'off')
+                continue;
+            const s = g.tools(caller);
+            for (const source of Array.isArray(s) ? s : [s])
+                sources.push({ group: g.id, access, source });
+        }
+        if (p.web ?? true) {
+            if (this.o.web?.fetch !== false)
+                sources.push({
+                    group: 'web',
+                    access: 'read',
+                    source: webFetchTools(this.o.web?.fetch || {}),
+                });
+            const sq = this.o.web?.scrapeql ? await this.state.scrapeql() : null;
+            if (sq && this.o.web?.scrapeql)
+                sources.push({
+                    group: 'web',
+                    access: 'read',
+                    source: scrapeqlTools(this.o.web.scrapeql.url, sq, this.o.fetch),
+                });
+        }
+        const results = await Promise.allSettled(sources.map((s) => s.source()));
+        results.forEach((r, i) => {
+            const s = sources[i];
+            if (r.status === 'fulfilled' && s)
+                opened.push({ group: s.group, access: s.access, open: r.value });
+        });
+        const fns = new Map();
+        for (const o of opened)
+            for (const def of o.open.tools) {
+                if (!def.read && o.access !== 'draft')
+                    continue;
+                fns.set(toolName(o.group, def.name), {
+                    group: o.group,
+                    def,
+                    draft: !def.read,
+                    open: o.open,
+                });
+            }
+        return {
+            fns,
+            failed: results.filter((r) => r.status === 'rejected').length,
+            close: () => Promise.all(opened.map((o) => o.open.close().catch(() => undefined))),
+        };
+    }
+    toolsFor(fns) {
+        return [...fns.entries()].map(([name, f]) => ({
+            name,
+            description: `${f.draft ? "DRAFT ONLY: this call changes nothing. It puts a card on the person's screen that they Save or Dismiss. " : ''}${f.def.title ? `${f.def.title}. ` : ''}${f.def.description ?? ''}`.slice(0, 4000),
+            input_schema: { type: 'object', ...f.def.inputSchema },
+        }));
+    }
+    // ---------------------------------------------------------------- the turn
+    /** One answer as server-sent events. Abort `signal` to stop it. */
+    turnStream(caller, req, signal) {
+        const enc = new TextEncoder();
+        let ctl;
+        let closed = false;
+        const stream = new ReadableStream({
+            start: (c) => {
+                ctl = c;
+            },
+            cancel: () => {
+                closed = true;
+            },
+        });
+        const emit = (event, data) => {
+            if (closed)
+                return;
+            try {
+                ctl.enqueue(enc.encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`));
+            }
+            catch {
+                closed = true;
+            }
+        };
+        void this.turn(caller, req, emit, signal).finally(() => {
+            if (closed)
+                return;
+            closed = true;
+            try {
+                ctl.close();
+            }
+            catch { }
+        });
+        return stream;
+    }
+    async turn(caller, req, emit, signal) {
+        const t0 = performance.now();
+        const message = req.message.trim();
+        const chatId = req.chat_id ?? newId('ac');
+        const prev = req.chat_id
+            ? await this.state.docs.read(caller.id, `chat:${req.chat_id}`)
+            : null;
+        if (req.chat_id && !prev) {
+            emit('error', { message: 'That chat is gone.', code: 'not_found' });
+            return;
+        }
+        const doc = prev ?? {
+            title: message.replace(/\s+/g, ' ').slice(0, 60),
+            items: [],
+            history: [],
+        };
+        const compactOnly = message === '/compact';
+        if (!compactOnly)
+            doc.items.push({
+                kind: 'user',
+                text: message,
+                at: Date.now(),
+                ...(req.context?.label ? { context: req.context.label } : {}),
+                ...(req.refs?.length ? { refs: req.refs } : {}),
+                ...(req.tier ? { tier: req.tier } : {}),
+            });
+        const start = doc.items.length;
+        emit('chat', { id: chatId, title: doc.title });
+        const { paying, wait } = await this.state.paying(caller.id);
+        if (!paying) {
+            const text = WAIT_TEXT[wait ?? 'not_connected'];
+            doc.items.push({ kind: 'error', text, code: wait ?? 'not_connected' });
+            await this.writeChat(caller, chatId, doc);
+            emit('error', { message: text, code: wait });
+            emit('done', { id: chatId, usage: doc.usage ?? NO_USAGE });
+            return;
+        }
+        const p = await this.state.person(caller.id);
+        const main = await this.session(caller, await this.mainTier(caller));
+        const policy = p.hand_off ?? 'next';
+        const advisor = await this.advisorFor(caller, p.advice, main);
+        const client = this.client(paying.apiKey);
+        const live = [main.meter, ...(advisor ? [advisor.session.meter] : [])];
+        const before = doc.usage ?? NO_USAGE;
+        let context = before.context;
+        const spent = () => ({
+            ...addUsage(before, live.map((m) => m.part())),
+            ...(context ? { context } : {}),
+        });
+        let limited = false;
+        const over = () => {
+            if (live.reduce((a, m) => a + m.usd, 0) < paying.left)
+                return null;
+            limited = true;
+            return '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.';
+        };
+        const handTo = req.tier ? this.above(main.tier).find((t) => t.id === req.tier) : undefined;
+        const tools = await this.openTools(caller, p);
+        const runs = [];
+        const counts = { steps: 0, handoffs: 0, advice: 0, end: main.tier };
+        let outcome = 'ok';
+        try {
+            const appSystem = typeof this.o.system === 'string' ? this.o.system : await this.o.system(caller);
+            const kitRules = this.rules(main, policy, advisor, tools.fns, tools.failed);
+            const system = [
+                { type: 'text', text: appSystem },
+                { type: 'text', text: kitRules, cache_control: { type: 'ephemeral' } },
+            ];
+            const subSystem = [
+                { type: 'text', text: appSystem },
+                {
+                    type: 'text',
+                    text: this.rules(null, policy, null, tools.fns, tools.failed),
+                    cache_control: { type: 'ephemeral' },
+                },
+            ];
+            if (compactOnly || (before.context ?? 0) > COMPACT_AT) {
+                const did = await this.compact(client, main, doc, emit);
+                if (did)
+                    context = undefined;
+                if (compactOnly) {
+                    if (!did) {
+                        const text = 'Nothing to compact yet.';
+                        doc.items.push({ kind: 'text', text });
+                        emit('text', { delta: text });
+                        emit('text_end', {});
+                    }
+                    doc.usage = spent();
+                    await this.writeChat(caller, chatId, doc);
+                    await this.state.addSpend(caller.id, paying.payer, live.map((m) => m.part()));
+                    emit('done', { id: chatId, usage: doc.usage });
+                    return;
+                }
+            }
+            const page = this.cardNews(doc) +
+                (req.refs?.length
+                    ? `The person points at: ${JSON.stringify(req.refs).slice(0, 2000)}\n\n`
+                    : '') +
+                (req.context
+                    ? `Page: ${req.context.label}${req.context.note === undefined ? '' : `\n${JSON.stringify(req.context.note).slice(0, 4000)}`}\n\n`
+                    : '');
+            const lead = handTo
+                ? `The person handed this message to ${handTo.label}: call escalate {tier: "${handTo.id}", why: "asked"} now, its task the message with every fact from this chat it needs, then answer from its memo.\n\n`
+                : '';
+            const messages = [
+                ...doc.history.map((t) => ({ role: t.role, content: t.content })),
+                { role: 'user', content: `${page}${lead}${message}` },
+            ];
+            const escalateTool = this.escalateTool(main.tier);
+            let answer = await this.loop({
+                client,
+                session: main,
+                system,
+                tools: [...this.toolsFor(tools.fns), ...(escalateTool ? [escalateTool] : [])],
+                messages,
+                sink: doc.items,
+                emit,
+                signal,
+                over,
+                ...(handTo && escalateTool ? { first: { type: 'tool', name: 'escalate' } } : {}),
+                ...(advisor ? { advisor } : {}),
+                context: (n) => {
+                    context = n;
+                },
+                called: () => emit('usage', spent()),
+                tool: (use) => use.name === 'escalate'
+                    ? this.handOff(use, {
+                        caller,
+                        client,
+                        message,
+                        handTo,
+                        page,
+                        policy,
+                        main,
+                        live,
+                        sink: doc.items,
+                        emit,
+                        spent,
+                        system: subSystem,
+                        tools: tools.fns,
+                        runs,
+                        counts,
+                        signal,
+                        over,
+                    })
+                    : this.runTool(use, tools.fns, doc.items, emit, runs, counts, main, false, signal),
+            });
+            if (limited) {
+                doc.items.push({ kind: 'stopped', reason: 'cap' });
+                emit('stopped', { reason: 'cap' });
+            }
+            if (!answer) {
+                answer = 'I could not finish that. Try a narrower question.';
+                doc.items.push({ kind: 'text', text: answer });
+                emit('text', { delta: answer });
+                emit('text_end', {});
+            }
+            doc.history.push({ role: 'user', content: `${page}${message}` });
+            doc.history.push({ role: 'assistant', content: this.remember(answer, runs) });
+        }
+        catch (err) {
+            if (signal?.aborted) {
+                outcome = 'stopped';
+                doc.items.push({ kind: 'stopped' });
+                const said = doc.items
+                    .slice(start)
+                    .filter((i) => i.kind === 'text')
+                    .map((i) => i.text)
+                    .join('\n\n');
+                if (!compactOnly) {
+                    doc.history.push({ role: 'user', content: message });
+                    doc.history.push({ role: 'assistant', content: said || '(stopped before answering)' });
+                }
+            }
+            else {
+                outcome = 'error';
+                const shown = shownError(err);
+                if (!(err instanceof AssistantError) && !(err instanceof Anthropic.APIError))
+                    console.error(JSON.stringify({
+                        event: 'assistant_error',
+                        error: String(err?.stack ?? err).slice(0, 2000),
+                    }));
+                doc.items.push({ kind: 'error', text: shown.message, code: shown.code });
+                emit('error', shown);
+            }
+        }
+        finally {
+            await tools.close();
+        }
+        doc.usage = spent();
+        await this.writeChat(caller, chatId, doc).catch(() => undefined);
+        await this.state
+            .addSpend(caller.id, paying.payer, live.map((m) => m.part()))
+            .catch(() => undefined);
+        if (outcome !== 'stopped')
+            emit('done', { id: chatId, usage: doc.usage });
+        const total = live.reduce((a, m) => ({
+            calls: a.calls + m.calls,
+            in: a.in + m.in,
+            out: a.out + m.out,
+            usd: a.usd + m.usd,
+        }), { calls: 0, in: 0, out: 0, usd: 0 });
+        await Promise.resolve(this.o.onStep?.({
+            kind: 'turn',
+            outcome,
+            ms: Math.round(performance.now() - t0),
+            tier: main.tier.id,
+            end_tier: counts.end.id,
+            handoffs: counts.handoffs,
+            advice: counts.advice,
+            steps: counts.steps,
+            ...total,
+        })).catch(() => undefined);
+    }
+    /** What the kit adds to the app's instructions: tools, drafts, hand off, advice, limits. */
+    rules(main, policy, advisor, fns, failed) {
+        const lines = [
+            `You are ${this.name}. Today is ${new Date().toISOString().slice(0, 10)}.`,
+            'Answer in short plain sentences. Use the tools for facts; never guess a number a tool can give you. Call several tools at once when they do not depend on each other.',
+            'A tool marked DRAFT ONLY makes a card the person saves or dismisses; it changes nothing by itself. Say what the card will do; never claim it is done. The next message tells you how each card ended.',
+        ];
+        if (!fns.size)
+            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.values()].some((f) => f.group === '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.');
+        if (main) {
+            const reach = this.above(main.tier);
+            if (reach.length) {
+                const own = policy === 'any' ? reach : policy === 'next' ? reach.slice(0, 1) : [];
+                lines.push(`Tiers: you run on ${main.tier.label}. The escalate tool hands one task to a higher tier (${reach.map((t) => t.label).join(' or ')}) with the same tools; it works in its own section of the chat and returns a memo. It costs more than answering yourself.`, `Call it when the person names a tier or says "go deeper"${own.length ? `, and on your own (${own.map((t) => t.label).join(' or ')}) when the question needs judgement across many results (why "judgement"), after two of your tool calls failed (why "stuck"), or when a fix of a check still fails (why "check_failed")` : ''}. Lookups you answer yourself.`, 'Its task must carry every fact from this chat it needs: it does not see the chat. Then answer from its memo in your own short words.');
+            }
+            if (advisor)
+                lines.push(`Advisor: the advisor tool (no input) asks ${advisor.session.tier.label} to read this chat and send you a plan; it runs no tools. Call it before a question that needs judgement or after a tool failed, then do the work yourself. At most ${ADVICE_MAX} times an answer. Ask the advisor before you escalate.`);
+        }
+        return lines.join('\n\n');
+    }
+    /** The advisor for this answer, or null when off. Never weaker than the model it advises. */
+    async advisorFor(caller, setting, main) {
+        const tier = setting && setting !== 'off' ? this.tierById(setting) : undefined;
+        if (!tier)
+            return null;
+        const rank = (m) => this.models.indexOf(m);
+        let session = await this.session(caller, tier);
+        if (rank(session.model) < rank(main.model))
+            session = { ...main, meter: new Meter(main.model, '') };
+        session.meter = new Meter(session.model, `${session.tier.label} · advice`);
+        return { session, asked: 0 };
+    }
+    escalateTool(main) {
+        const reach = this.above(main);
+        if (!reach.length)
+            return null;
+        return {
+            name: 'escalate',
+            description: 'Hands one task to a higher tier with the same tools. It works in its own section and returns a memo of at most 200 words.',
+            input_schema: {
+                type: 'object',
+                properties: {
+                    tier: { type: 'string', enum: reach.map((t) => t.id) },
+                    why: { type: 'string', enum: [...HAND_OFF_WHYS] },
+                    task: {
+                        type: 'string',
+                        description: 'The task, with every fact from the chat it needs.',
+                    },
+                },
+                required: ['tier', 'why', 'task'],
+            },
+        };
+    }
+    /** The tiers the person's message asks for by name ("go deeper" is the next one up). */
+    askedFor(message, main) {
+        const reach = this.above(main);
+        const asked = new Set();
+        for (const t of reach)
+            if (new RegExp(`\\b(${t.id}|${t.label.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')})\\b`, 'i').test(message))
+                asked.add(t.id);
+        if (/\b(deeper|escalate)\b/i.test(message) && reach[0])
+            asked.add(reach[0].id);
+        return asked;
+    }
+    async handOff(use, c) {
+        const reply = (content, is_error = false) => ({
+            type: 'tool_result',
+            tool_use_id: use.id,
+            content,
+            is_error,
+        });
+        const input = (use.input ?? {});
+        const reach = this.above(c.main.tier);
+        const tier = reach.find((t) => t.id === input.tier);
+        const why = HAND_OFF_WHYS.find((w) => w === input.why);
+        const task = typeof input.task === 'string' ? input.task.trim() : '';
+        if (!tier || !why || !task)
+            return reply(`Give {tier: ${reach.map((t) => `"${t.id}"`).join(' | ')}, why: ${HAND_OFF_WHYS.map((w) => `"${w}"`).join(' | ')}, task}.`, true);
+        const asked = this.askedFor(c.message, c.main.tier);
+        if (c.handTo)
+            asked.add(c.handTo.id);
+        const own = c.policy === 'any' ? reach : c.policy === 'next' ? reach.slice(0, 1) : [];
+        const may = new Set([...own.map((t) => t.id), ...asked]);
+        if (!may.has(tier.id))
+            return reply(may.size
+                ? `Not ${tier.id} now: you may call ${[...may].join(' or ')}.`
+                : 'The person has not asked for a higher tier: answer yourself.', true);
+        if (c.over())
+            return reply('No money left for a higher tier this answer: answer yourself.', true);
+        const sub = await this.session(c.caller, tier);
+        c.live.push(sub.meter);
+        c.counts.handoffs += 1;
+        if (this.tiers.indexOf(tier) > this.tiers.indexOf(c.counts.end))
+            c.counts.end = tier;
+        const item = {
+            kind: 'handoff',
+            tier: tier.id,
+            label: sub.meter.label,
+            task: task.replace(/\s+/g, ' ').slice(0, 200),
+            why: asked.has(tier.id) ? 'asked' : why,
+            items: [],
+        };
+        c.sink.push(item);
+        c.emit('handoff', {
+            kind: 'handoff',
+            tier: item.tier,
+            label: item.label,
+            task: item.task,
+            why: item.why,
+        });
+        const inside = (event, data) => c.emit(event, { ...data, handoff: true });
+        let memo = '';
+        let failed;
+        try {
+            memo = await this.loop({
+                client: c.client,
+                session: sub,
+                system: c.system,
+                tools: this.toolsFor(c.tools),
+                messages: [
+                    {
+                        role: 'user',
+                        content: `${c.page}The person asked: ${c.message}\n\n${this.name} handed you this task (${WHY_TEXT[item.why]}): ${task}\n\nWork it out with the tools, then end with a memo for ${this.name} of at most 200 words: the answer and the facts it rests on. ${this.name} answers the person.`,
+                    },
+                ],
+                sink: item.items,
+                emit: inside,
+                signal: c.signal,
+                over: c.over,
+                called: () => c.emit('usage', c.spent()),
+                tool: (u) => this.runTool(u, c.tools, item.items, inside, c.runs, c.counts, sub, true, c.signal),
+            });
+        }
+        catch (err) {
+            if (c.signal?.aborted)
+                throw err;
+            const shown = shownError(err);
+            failed = shown.message;
+            item.items.push({ kind: 'error', text: failed, code: shown.code });
+            inside('error', shown);
+        }
+        finally {
+            item.usage = sub.meter.part();
+            c.emit('handoff_done', { usage: item.usage });
+        }
+        return failed
+            ? reply(`${item.label} failed: ${failed}`, true)
+            : reply(`Memo from ${item.label}:\n${memo.slice(0, MEMO_CHARS)}`);
+    }
+    /** One tool call: a draft card for a write, else the call itself, timed. */
+    async runTool(use, fns, sink, emit, runs, counts, session, handoff, signal) {
+        const reply = (content, is_error = false) => ({
+            type: 'tool_result',
+            tool_use_id: use.id,
+            content,
+            is_error,
+        });
+        const f = fns.get(use.name);
+        if (!f)
+            return reply(`No tool ${use.name}.`, true);
+        const title = f.def.title ?? f.def.name;
+        if (f.draft) {
+            const item = {
+                kind: 'draft',
+                id: newId('d'),
+                tool: use.name,
+                title,
+                args: use.input,
+                status: 'open',
+            };
+            sink.push(item);
+            emit('draft', item);
+            await Promise.resolve(this.o.onStep?.({ kind: 'draft', tool: use.name, tier: session.tier.id, handoff })).catch(() => undefined);
+            return reply(`Drafted: a "${title}" card is on the person's screen. Nothing changed until they press Save.`);
+        }
+        const id = newId('s');
+        emit('step_start', { id, tool: use.name, title });
+        const t0 = performance.now();
+        let out;
+        let ok = true;
+        let error;
+        let rows;
+        try {
+            const result = await untilStopped(withDeadline(title, 60_000, f.open.call(f.def.name, use.input)), signal);
+            rows = rowCount(result);
+            out = typeof result === 'string' ? result : JSON.stringify(result);
+        }
+        catch (err) {
+            if (signal?.aborted)
+                throw err;
+            ok = false;
+            error =
+                err instanceof ToolError || err instanceof Error ? err.message.slice(0, 300) : 'failed';
+            out = error;
+        }
+        const ms = Math.round(performance.now() - t0);
+        const item = {
+            kind: 'step',
+            id,
+            tool: use.name,
+            title,
+            ok,
+            ms,
+            ...(rows !== undefined ? { rows } : {}),
+            ...(error ? { error } : {}),
+        };
+        sink.push(item);
+        emit('step', item);
+        counts.steps += 1;
+        runs.push({ tool: use.name, result: out.slice(0, RAN_CHARS) });
+        await Promise.resolve(this.o.onStep?.({
+            kind: 'tool',
+            tool: use.name,
+            ok,
+            ms,
+            ...(rows !== undefined ? { rows } : {}),
+            ...(error ? { error } : {}),
+            tier: session.tier.id,
+            handoff,
+        })).catch(() => undefined);
+        const cut = out.length > RESULT_CHARS ? `${out.slice(0, RESULT_CHARS)} …(cut: ask for less)` : out;
+        return reply(cut, !ok);
+    }
+    /** Model calls and tool rounds until the model answers; returns its words. */
+    async loop(o) {
+        const { client, session, system, tools, messages, sink, emit, signal } = o;
+        let answer = '';
+        let force = o.first;
+        for (let round = 0; round < MAX_ROUNDS; round++) {
+            signal?.throwIfAborted();
+            // The system prompt and tools are one cached prefix; the chat so far a second breakpoint.
+            const sent = messages.map((m, i) => (i === messages.length - 1 ? withCacheMark(m) : m));
+            const params = {
+                model: session.model.id,
+                max_tokens: session.tier.out ?? DEFAULT_OUT,
+                ...effortParams(session.effort),
+                system,
+                tools,
+                messages: sent,
+                ...(force ? { tool_choice: force } : {}),
+            };
+            const adv = o.advisor;
+            // A forced tool choice may not come with the advisor; the beta header stays while it is on.
+            const advise = adv && adv.asked < ADVICE_MAX && force?.type !== 'tool' && force?.type !== 'any';
+            const stream = adv
+                ? client.beta.messages.stream({
+                    ...params,
+                    tools: [
+                        ...tools,
+                        ...(advise
+                            ? [
+                                {
+                                    type: 'advisor_20260301',
+                                    name: 'advisor',
+                                    model: adv.session.model.id,
+                                    max_tokens: ADVICE_TOKENS,
+                                    caching: { type: 'ephemeral', ttl: '5m' },
+                                },
+                            ]
+                            : []),
+                    ],
+                    betas: [ADVISOR_BETA],
+                }, { signal })
+                : client.messages.stream(params, signal ? { signal } : {});
+            let partial = '';
+            stream.on('text', (delta) => {
+                partial += delta;
+                emit('text', { delta });
+            });
+            if (adv)
+                stream.on('streamEvent', (e) => {
+                    if (e.type !== 'content_block_start')
+                        return;
+                    const b = e.content_block;
+                    const label = adv.session.meter.label;
+                    if (b.type === 'server_tool_use' && b.name === 'advisor') {
+                        adv.asked += 1;
+                        emit('advice', { tier: adv.session.tier.id, label });
+                    }
+                    else if (b.type === 'advisor_tool_result') {
+                        const error = b.content?.type === 'advisor_tool_result_error'
+                            ? (b.content.error_code ?? 'error')
+                            : undefined;
+                        sink.push({
+                            kind: 'advice',
+                            tier: adv.session.tier.id,
+                            label,
+                            ...(error ? { error } : {}),
+                        });
+                        emit('advice_done', error ? { error } : {});
+                    }
+                });
+            const msg = await stream.finalMessage().catch((err) => {
+                if (signal?.aborted && partial)
+                    sink.push({ kind: 'text', text: partial });
+                throw err;
+            });
+            session.meter.add(msg.usage);
+            if (adv)
+                for (const it of msg.usage.iterations ?? [])
+                    if (it.type === 'advisor_message')
+                        adv.session.meter.add(it);
+            o.context?.(msg.usage.input_tokens +
+                (msg.usage.cache_read_input_tokens ?? 0) +
+                (msg.usage.cache_creation_input_tokens ?? 0) +
+                msg.usage.output_tokens);
+            o.called();
+            const cut = msg.stop_reason === 'max_tokens' ? ' …(cut)' : '';
+            if (cut)
+                emit('text', { delta: cut });
+            const text = msg.content
+                .filter((b) => b.type === 'text')
+                .map((b) => b.text)
+                .join('') + cut;
+            if (text) {
+                answer += (answer ? '\n\n' : '') + text;
+                sink.push({ kind: 'text', text });
+                emit('text_end', {});
+            }
+            messages.push({ role: 'assistant', content: msg.content });
+            if (msg.stop_reason === 'pause_turn')
+                continue;
+            const uses = msg.content.filter((b) => b.type === 'tool_use');
+            if (msg.stop_reason !== 'tool_use' || uses.length === 0)
+                break;
+            const results = await Promise.all(uses.map((use) => untilStopped(o.tool(use), signal)));
+            if (force === o.first)
+                force = undefined;
+            const limit = o.over();
+            if (limit) {
+                results.push({ type: 'text', text: limit });
+                force = { type: 'none' };
+            }
+            else if (round === MAX_ROUNDS - 2) {
+                results.push({ type: 'text', text: 'No more tool calls: answer now from what you have.' });
+                force = { type: 'none' };
+            }
+            messages.push({ role: 'user', content: results });
+        }
+        return answer;
+    }
+    /** Swaps the history for a short summary. False with nothing to compact. */
+    async compact(client, s, doc, emit) {
+        if (doc.history.length < 2)
+            return false;
+        const msg = await client.messages.create({
+            model: s.model.id,
+            max_tokens: 1500,
+            system: `Summarise this chat between a person and ${this.name}, their assistant, so ${this.name} can carry on from the summary alone. Keep what the person wants, the facts and numbers found, decisions made and cards drafted or saved, and anything still open. Plain bullets, at most 400 words. No preamble.`,
+            messages: [
+                {
+                    role: 'user',
+                    content: doc.history
+                        .map((t) => `${t.role === 'user' ? 'Person' : this.name}: ${t.content}`)
+                        .join('\n\n'),
+                },
+            ],
+        });
+        s.meter.add(msg.usage);
+        const summary = msg.content
+            .filter((b) => b.type === 'text')
+            .map((b) => b.text)
+            .join('');
+        doc.history = [
+            { role: 'user', content: `Summary of our chat so far (compacted):\n${summary}` },
+            { role: 'assistant', content: 'Noted. I carry on from this summary.' },
+        ];
+        doc.items.push({ kind: 'compacted' });
+        emit('compacted', {});
+        return true;
+    }
+    /** How the person's cards ended since the last answer, once each. */
+    cardNews(doc) {
+        const told = new Set(doc.told ?? []);
+        const news = draftsOf(doc.items).filter((d) => d.status !== 'open' && !told.has(d.id));
+        if (!news.length)
+            return '';
+        doc.told = [...told, ...news.map((d) => d.id)];
+        return `Cards since your last answer:\n${news
+            .map((d) => `- ${d.title} ${JSON.stringify(d.args).slice(0, 300)}: ${d.status}${d.error ? ` (${d.error})` : ''}${d.result !== undefined ? ` → ${JSON.stringify(d.result).slice(0, 300)}` : ''}`)
+            .join('\n')}\n\n`;
+    }
+    /** The answer as later turns remember it: with what its tools returned, cut. */
+    remember(answer, runs) {
+        if (!runs.length)
+            return answer;
+        let left = RAN_TOTAL;
+        const lines = [];
+        for (const r of runs) {
+            if (left <= 0)
+                break;
+            const line = `- ${r.tool} → ${r.result.slice(0, Math.min(RAN_CHARS, left))}`;
+            left -= line.length;
+            lines.push(line);
+        }
+        return `${answer}\n\n[Tools I used and what they returned]\n${lines.join('\n')}`;
+    }
+    // ---------------------------------------------------------------- keys
+    /** One free call (reading a model) that says whether Claude takes the key. */
+    async testKey(apiKey) {
+        const at = Date.now();
+        const model = this.modelById(this.tiers[0].model) ?? this.models[0];
+        try {
+            await this.client(apiKey).models.retrieve(model.id);
+            return { ok: true, detail: 'Claude took the key.', at };
+        }
+        catch (err) {
+            return { ok: false, detail: shownError(err).message, at };
+        }
+    }
+    /** Lists ScrapeQL's tools with the token: works or why not. */
+    async testScrapeql(token) {
+        const at = Date.now();
+        const url = this.o.web?.scrapeql?.url;
+        if (!url)
+            return { ok: false, detail: 'ScrapeQL is not set up in this app.', at };
+        try {
+            const open = await scrapeqlTools(url, token, this.o.fetch)();
+            const n = open.tools.length;
+            await open.close();
+            return { ok: true, detail: `ScrapeQL answered with ${n} tool${n === 1 ? '' : 's'}.`, at };
+        }
+        catch {
+            return { ok: false, detail: 'ScrapeQL refused the token or could not be reached.', at };
+        }
+    }
+    // ---------------------------------------------------------------- drafts
+    /** Saves (runs, as the person) or dismisses a drafted card. Access is checked again first. */
+    async settleDraft(caller, chatId, draftId, action) {
+        const doc = await this.state.docs.read(caller.id, `chat:${chatId}`);
+        if (!doc)
+            throw new AssistantError('That chat is gone.', 'not_found', 404);
+        const d = draftsOf(doc.items).find((x) => x.id === draftId);
+        if (!d)
+            throw new AssistantError('That card is gone.', 'not_found', 404);
+        if (d.status !== 'open')
+            throw new AssistantError(`That card is already ${d.status}.`, 'settled', 409);
+        if (action === 'dismiss')
+            d.status = 'dismissed';
+        else {
+            const p = await this.state.person(caller.id);
+            const tools = await this.openTools(caller, p);
+            try {
+                const f = tools.fns.get(d.tool);
+                if (!f?.draft) {
+                    d.status = 'failed';
+                    d.error = 'Its tools are no longer on Read + draft in Settings ▸ Tools.';
+                }
+                else {
+                    try {
+                        d.result = await withDeadline(d.title, 60_000, f.open.call(f.def.name, d.args));
+                        d.status = 'saved';
+                    }
+                    catch (err) {
+                        d.status = 'failed';
+                        d.error = err instanceof Error ? err.message.slice(0, 300) : 'failed';
+                    }
+                }
+            }
+            finally {
+                await tools.close();
+            }
+        }
+        await this.writeChat(caller, chatId, doc);
+        return d;
+    }
+}
+export function createAssistant(o) {
+    return new Assistant(o);
+}