@columenlabs/lumen-ai 0.1.72 → 0.1.73

package/dist/assistant/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * An assistant for any app: a chat side panel's server. Claude on the app's tiers (named by the
+ * app), the app's tools from any MCP server, the web (a plain fetch and ScrapeQL over its API),
+ * hand off to a higher tier, advice, drafts the person saves, and a monthly spend cap per person.
+ *
+ *   const assistant = createAssistant({ name, system, tiers, groups, store, sealer, appKey });
+ *   const routes = assistantRoutes(assistant, { base: '/api/assistant', caller });
+ *
+ * The panel and the Settings sections are `@columenlabs/lumen-ui`'s; the types they share are
+ * `@columenlabs/lumen-ui-types/assistant`.
+ */
+export * from './engine.js';
+export * from './models.js';
+export * from './routes.js';
+export { DEFAULT_CAP, type KeyDoc, type KeyTest, monthIn, type Paying, type PersonDoc, type SpendDoc, State, type TokenDoc, } from './state.js';
+export * from './store.js';
+export * from './tools.js';
+export * from './web.js';

package/dist/assistant/index.js

@@ -0,0 +1,18 @@
+/**
+ * An assistant for any app: a chat side panel's server. Claude on the app's tiers (named by the
+ * app), the app's tools from any MCP server, the web (a plain fetch and ScrapeQL over its API),
+ * hand off to a higher tier, advice, drafts the person saves, and a monthly spend cap per person.
+ *
+ *   const assistant = createAssistant({ name, system, tiers, groups, store, sealer, appKey });
+ *   const routes = assistantRoutes(assistant, { base: '/api/assistant', caller });
+ *
+ * The panel and the Settings sections are `@columenlabs/lumen-ui`'s; the types they share are
+ * `@columenlabs/lumen-ui-types/assistant`.
+ */
+export * from './engine.js';
+export * from './models.js';
+export * from './routes.js';
+export { DEFAULT_CAP, monthIn, State, } from './state.js';
+export * from './store.js';
+export * from './tools.js';
+export * from './web.js';

package/dist/assistant/models.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Models and tiers. The app names its tiers (smallest first) and the model each runs by default; a
+ * person may pick another model and effort per tier. Prices are the providers' list prices per
+ * million tokens, so every answer's cost is known as it runs.
+ */
+import type { AssistantEffort, UsagePart } from '@columenlabs/lumen-ui-types/assistant';
+/** A model a tier can run, with its list price per million tokens (input, output, cache reads). */
+export interface ModelDef {
+    id: string;
+    label: string;
+    /** The heading pickers list it under (its provider). */
+    group: string;
+    in: number;
+    out: number;
+    read: number;
+}
+/** Claude models, smallest first (an advisor is never weaker than the model it advises). */
+export declare const CLAUDE_MODELS: ModelDef[];
+/** A tier as the app defines it. `out` caps each model call's output tokens. */
+export interface TierDef {
+    id: string;
+    label: string;
+    about: string;
+    model: string;
+    out?: number;
+}
+/** A task a person picks a starting tier for (the chat panel, a drafting job, a schedule). */
+export interface TaskDef {
+    id: string;
+    label: string;
+    about: string;
+    tier: string;
+}
+/** Output tokens per model call when a tier sets none. */
+export declare const DEFAULT_OUT = 16000;
+/** Token use of one reply, as the provider reports it. */
+export interface TokenUsage {
+    input_tokens: number;
+    output_tokens: number;
+    cache_creation_input_tokens?: number | null;
+    cache_read_input_tokens?: number | null;
+}
+/** Tokens in (cache reads and writes included) and out of one reply, and its cost at list price. */
+export declare function priced(model: ModelDef, usage: TokenUsage): {
+    in: number;
+    out: number;
+    read: number;
+    usd: number;
+};
+/** The running use of one tier in one answer. */
+export declare class Meter {
+    readonly model: ModelDef;
+    readonly label: string;
+    calls: number;
+    in: number;
+    read: number;
+    out: number;
+    usd: number;
+    constructor(model: ModelDef, label: string);
+    add(usage: TokenUsage): void;
+    part(): UsagePart;
+}
+/** The request's effort setting: nothing at the model's own default. */
+export declare function effortParams(effort: AssistantEffort): {
+    output_config?: undefined;
+} | {
+    output_config: {
+        effort: "high" | "low" | "max" | "medium";
+    };
+};
+/** `sk-ant-api03-…7Qx2`: never more of a key than its start and last four. */
+export declare const keyHint: (key: string) => string;

package/dist/assistant/models.js

@@ -0,0 +1,69 @@
+/** Claude models, smallest first (an advisor is never weaker than the model it advises). */
+export const CLAUDE_MODELS = [
+    {
+        id: 'claude-haiku-5-5',
+        label: 'Claude Haiku 5.5',
+        group: 'Claude',
+        in: 0.1,
+        out: 0.5,
+        read: 0.01,
+    },
+    {
+        id: 'claude-sonnet-5-5',
+        label: 'Claude Sonnet 5.5',
+        group: 'Claude',
+        in: 2,
+        out: 10,
+        read: 0.2,
+    },
+    { id: 'claude-opus-5-5', label: 'Claude Opus 5.5', group: 'Claude', in: 4, out: 20, read: 0.2 },
+];
+/** Output tokens per model call when a tier sets none. */
+export const DEFAULT_OUT = 16_000;
+/** Tokens in (cache reads and writes included) and out of one reply, and its cost at list price. */
+export function priced(model, usage) {
+    const written = usage.cache_creation_input_tokens ?? 0;
+    const read = usage.cache_read_input_tokens ?? 0;
+    return {
+        in: usage.input_tokens + written + read,
+        out: usage.output_tokens,
+        read,
+        usd: (usage.input_tokens * model.in +
+            written * model.in * 1.25 +
+            read * model.read +
+            usage.output_tokens * model.out) /
+            1e6,
+    };
+}
+/** The running use of one tier in one answer. */
+export class Meter {
+    model;
+    label;
+    calls = 0;
+    in = 0;
+    read = 0;
+    out = 0;
+    usd = 0;
+    constructor(model, label) {
+        this.model = model;
+        this.label = label;
+    }
+    add(usage) {
+        const p = priced(this.model, usage);
+        this.calls += 1;
+        this.in += p.in;
+        this.read += p.read;
+        this.out += p.out;
+        this.usd += p.usd;
+    }
+    part() {
+        const { label, calls, read, out, usd } = this;
+        return { label, calls, in: this.in, read, out, usd };
+    }
+}
+/** The request's effort setting: nothing at the model's own default. */
+export function effortParams(effort) {
+    return effort === 'default' ? {} : { output_config: { effort } };
+}
+/** `sk-ant-api03-…7Qx2`: never more of a key than its start and last four. */
+export const keyHint = (key) => `${key.slice(0, 7)}…${key.slice(-4)}`;

package/dist/assistant/routes.d.ts

@@ -0,0 +1,10 @@
+import { type Assistant, type Caller } from './engine.js';
+type Awaitable<T> = T | Promise<T>;
+export interface AssistantRoutesOptions {
+    /** Where the routes are mounted (`/api/assistant`). */
+    base: string;
+    /** The verified caller, or null (403). The app decides who is an admin. */
+    caller: (req: Request) => Awaitable<Caller | null>;
+}
+export declare function assistantRoutes(a: Assistant, o: AssistantRoutesOptions): (req: Request) => Promise<Response>;
+export {};

package/dist/assistant/routes.js

@@ -0,0 +1,319 @@
+/**
+ * The HTTP routes the assistant's panel and Settings call, as one fetch handler on Web
+ * `Request`/`Response`, so it mounts in any router:
+ *
+ *   app.all('/api/assistant/*', (c) => assistant(c.req.raw));   // Hono
+ *
+ *   GET    /status                  what the panel and Settings show
+ *   PUT    /settings                the person's tiers, tasks, hand off, advice, tool access, web, payer
+ *   PUT    /app {cap_usd}           admin: what each person may spend a month on the app's key
+ *   PUT    /key {api_key}           admin: the app's Claude key, tested before it is kept
+ *   DELETE /key, POST /key/test     admin
+ *   PUT    /my-key {api_key, cap_usd?}, PUT /my-key/cap {cap_usd}, DELETE /my-key, POST /my-key/test
+ *   PUT    /web/scrapeql {client_id, client_secret}, DELETE /web/scrapeql, POST /web/test   admin
+ *   POST   /chat                    one answer as server-sent events; closing the request stops it
+ *   GET    /chats, GET|DELETE /chats/:id
+ *   POST   /chats/:id/drafts/:draft {action: save | dismiss}
+ *
+ * Writes must be same-origin JSON: a signed-in browser session is a cookie, so a foreign page's
+ * form or fetch is refused before it reaches a rule. Keys and tokens are write-only: no route
+ * returns one, only a hint (`sk-ant-…abcd`).
+ */
+import { ASSISTANT_ACCESS, ASSISTANT_EFFORTS, ASSISTANT_PAYERS, HAND_OFF_POLICIES, } from '@columenlabs/lumen-ui-types/assistant';
+import { AssistantError } from './engine.js';
+import { APP_SCOPE } from './store.js';
+const MUTATING = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+const MAX_MESSAGE = 20_000;
+const MAX_CAP = 10_000;
+const json = (body, status = 200) => new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json', 'cache-control': 'no-store' },
+});
+const fail = (error, status = 400, code) => json({ error, ...(code ? { code } : {}) }, status);
+async function body(req) {
+    try {
+        const b = await req.json();
+        return b && typeof b === 'object' && !Array.isArray(b) ? b : {};
+    }
+    catch {
+        return {};
+    }
+}
+const str = (v, max = 500) => typeof v === 'string' && v.trim() && v.length <= max ? v.trim() : null;
+const cap = (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0 && v <= MAX_CAP
+    ? Math.round(v * 100) / 100
+    : null;
+const oneOf = (list, v) => list.find((x) => x === v);
+/** Checks a settings change against the app's tiers, tasks, models and tool groups. */
+function settingsChange(a, groups, b) {
+    const p = b;
+    const tierIds = new Set(a.tiers.map((t) => t.id));
+    const modelIds = new Set(a.models.map((m) => m.id));
+    if (p.tier !== undefined && !tierIds.has(p.tier))
+        return 'No such tier.';
+    if (p.tiers !== undefined) {
+        if (!p.tiers || typeof p.tiers !== 'object')
+            return 'tiers is {tier: {model, effort}}.';
+        for (const [id, t] of Object.entries(p.tiers)) {
+            if (!tierIds.has(id))
+                return `No tier ${id}.`;
+            if (t.model !== undefined && !modelIds.has(t.model))
+                return `No model ${t.model}.`;
+            if (t.effort !== undefined && !oneOf(ASSISTANT_EFFORTS, t.effort))
+                return `No effort ${t.effort}.`;
+        }
+    }
+    if (p.tasks !== undefined) {
+        if (!p.tasks || typeof p.tasks !== 'object')
+            return 'tasks is {task: tier}.';
+        for (const [id, tier] of Object.entries(p.tasks)) {
+            if (!a.tasks.some((t) => t.id === id))
+                return `No task ${id}.`;
+            if (!tierIds.has(tier))
+                return `No tier ${tier}.`;
+        }
+    }
+    if (p.hand_off !== undefined && !oneOf(HAND_OFF_POLICIES, p.hand_off))
+        return 'No such hand off.';
+    if (p.advice !== undefined && p.advice !== 'off' && !tierIds.has(p.advice))
+        return 'Advice is off or a tier.';
+    if (p.access !== undefined) {
+        if (!p.access || typeof p.access !== 'object')
+            return 'access is {group: off | read | draft}.';
+        for (const [g, v] of Object.entries(p.access)) {
+            if (!groups.includes(g))
+                return `No tool group ${g}.`;
+            if (!oneOf(ASSISTANT_ACCESS, v))
+                return `No access ${v}.`;
+        }
+    }
+    if (p.web !== undefined && (typeof p.web !== 'object' || typeof p.web?.fetch !== 'boolean'))
+        return 'web is {fetch: true | false}.';
+    if (p.pay !== undefined && !oneOf(ASSISTANT_PAYERS, p.pay))
+        return 'pay is app or own.';
+    return (d) => {
+        const tiers = { ...(d.tiers ?? {}) };
+        for (const [id, t] of Object.entries(p.tiers ?? {})) {
+            const tier = a.tiers.find((x) => x.id === id);
+            const prev = tiers[id] ?? { model: tier?.model ?? '', effort: 'default' };
+            tiers[id] = { model: t.model ?? prev.model, effort: t.effort ?? prev.effort };
+        }
+        return {
+            ...d,
+            ...(p.tier !== undefined ? { tier: p.tier } : {}),
+            ...(p.tiers !== undefined ? { tiers } : {}),
+            ...(p.tasks !== undefined ? { tasks: { ...(d.tasks ?? {}), ...p.tasks } } : {}),
+            ...(p.hand_off !== undefined ? { hand_off: p.hand_off } : {}),
+            ...(p.advice !== undefined ? { advice: p.advice } : {}),
+            ...(p.access !== undefined ? { access: { ...(d.access ?? {}), ...p.access } } : {}),
+            ...(p.web !== undefined ? { web: p.web.fetch } : {}),
+            ...(p.pay !== undefined ? { pay: p.pay } : {}),
+        };
+    };
+}
+export function assistantRoutes(a, o) {
+    const base = o.base.replace(/\/+$/, '');
+    const docs = a.state.docs;
+    return async (req) => {
+        const url = new URL(req.url);
+        if (!url.pathname.startsWith(base))
+            return fail('Not found.', 404);
+        const parts = url.pathname
+            .slice(base.length)
+            .split('/')
+            .filter(Boolean)
+            .map(decodeURIComponent);
+        const m = req.method;
+        const route = `${m} /${parts.join('/')}`;
+        if (MUTATING.has(m)) {
+            const origin = req.headers.get('origin');
+            if (origin && origin !== url.origin)
+                return fail('Not from this site.', 403, 'forbidden_origin');
+            if (!(req.headers.get('content-type') ?? '').toLowerCase().startsWith('application/json'))
+                return fail('Use Content-Type: application/json.', 415);
+        }
+        const caller = await o.caller(req);
+        if (!caller)
+            return fail('Sign in first.', 403, 'forbidden');
+        const admin = () => (caller.admin ? null : fail('Admins only.', 403, 'forbidden'));
+        const status = async () => json(await a.status(caller));
+        try {
+            switch (route) {
+                case 'GET /status':
+                    return status();
+                case 'PUT /settings': {
+                    const groups = (await a.status(caller)).groups.map((g) => g.id);
+                    const change = settingsChange(a, groups, await body(req));
+                    if (typeof change === 'string')
+                        return fail(change);
+                    await a.state.setPerson(caller.id, change);
+                    return status();
+                }
+                case 'PUT /app': {
+                    const no = admin();
+                    if (no)
+                        return no;
+                    const c = cap((await body(req)).cap_usd);
+                    if (c === null)
+                        return fail(`cap_usd is a number of dollars, 0 to ${MAX_CAP}.`);
+                    await a.state.setApp((d) => ({ ...d, cap_usd: c }));
+                    return status();
+                }
+                case 'PUT /key':
+                case 'PUT /my-key': {
+                    const mine = route === 'PUT /my-key';
+                    if (!mine) {
+                        const no = admin();
+                        if (no)
+                            return no;
+                    }
+                    const b = await body(req);
+                    const key = str(b.api_key, 400);
+                    if (!key)
+                        return fail('Paste the key (sk-ant-…).');
+                    const c = b.cap_usd === undefined ? undefined : cap(b.cap_usd);
+                    if (c === null)
+                        return fail(`cap_usd is a number of dollars, 0 to ${MAX_CAP}.`);
+                    const test = await a.testKey(key);
+                    if (!test.ok)
+                        return fail(test.detail, 400, 'key_refused');
+                    const scope = mine ? caller.id : APP_SCOPE;
+                    await docs.update(scope, 'key', (d) => ({
+                        api_key: key,
+                        saved_at: Date.now(),
+                        test,
+                        ...(mine ? { cap_usd: c ?? d?.cap_usd ?? a.state.defaultCap } : {}),
+                    }));
+                    return status();
+                }
+                case 'PUT /my-key/cap': {
+                    const c = cap((await body(req)).cap_usd);
+                    if (c === null)
+                        return fail(`cap_usd is a number of dollars, 0 to ${MAX_CAP}.`);
+                    const d = await a.state.ownKey(caller.id);
+                    if (!d)
+                        return fail('Add your key first.', 404);
+                    await docs.write(caller.id, 'key', { ...d, cap_usd: c });
+                    return status();
+                }
+                case 'DELETE /key':
+                case 'DELETE /my-key': {
+                    const mine = route === 'DELETE /my-key';
+                    if (!mine) {
+                        const no = admin();
+                        if (no)
+                            return no;
+                    }
+                    await docs.remove(mine ? caller.id : APP_SCOPE, 'key');
+                    return status();
+                }
+                case 'POST /key/test':
+                case 'POST /my-key/test': {
+                    const mine = route === 'POST /my-key/test';
+                    if (!mine) {
+                        const no = admin();
+                        if (no)
+                            return no;
+                    }
+                    const scope = mine ? caller.id : APP_SCOPE;
+                    const d = await docs.read(scope, 'key');
+                    const key = d?.api_key ?? (mine ? null : (await a.state.appApiKey())?.key);
+                    if (!key)
+                        return fail('No key is set.', 404);
+                    const test = await a.testKey(key);
+                    if (d)
+                        await docs.write(scope, 'key', { ...d, test });
+                    return json(test);
+                }
+                case 'PUT /web/scrapeql': {
+                    const no = admin();
+                    if (no)
+                        return no;
+                    const b = await body(req);
+                    const client_id = str(b.client_id, 200);
+                    const client_secret = str(b.client_secret, 400);
+                    if (!client_id || !client_secret)
+                        return fail('Paste the Client ID and Client Secret.');
+                    const test = await a.testScrapeql({ client_id, client_secret });
+                    if (!test.ok)
+                        return fail(test.detail, 400, 'token_refused');
+                    await docs.write(APP_SCOPE, 'scrapeql', {
+                        client_id,
+                        client_secret,
+                        saved_at: Date.now(),
+                        test,
+                    });
+                    return status();
+                }
+                case 'DELETE /web/scrapeql': {
+                    const no = admin();
+                    if (no)
+                        return no;
+                    await docs.remove(APP_SCOPE, 'scrapeql');
+                    return status();
+                }
+                case 'POST /web/test': {
+                    const no = admin();
+                    if (no)
+                        return no;
+                    const d = await a.state.scrapeql();
+                    if (!d)
+                        return fail('No ScrapeQL token is set.', 404);
+                    const test = await a.testScrapeql(d);
+                    await docs.write(APP_SCOPE, 'scrapeql', { ...d, test });
+                    return json(test);
+                }
+                case 'POST /chat': {
+                    const b = (await body(req));
+                    const message = typeof b.message === 'string' ? b.message.trim() : '';
+                    if (!message || message.length > MAX_MESSAGE)
+                        return fail(`Write a message of up to ${MAX_MESSAGE} characters.`);
+                    const msg = {
+                        message,
+                        ...(typeof b.chat_id === 'string' ? { chat_id: b.chat_id } : {}),
+                        ...(b.context && typeof b.context === 'object' ? { context: b.context } : {}),
+                        ...(Array.isArray(b.refs) ? { refs: b.refs.slice(0, 20) } : {}),
+                        ...(typeof b.tier === 'string' ? { tier: b.tier } : {}),
+                    };
+                    return new Response(a.turnStream(caller, msg, req.signal), {
+                        headers: {
+                            'content-type': 'text/event-stream',
+                            'cache-control': 'no-store',
+                            'x-accel-buffering': 'no',
+                        },
+                    });
+                }
+                case 'GET /chats':
+                    return json(await a.listChats(caller));
+            }
+            if (parts[0] === 'chats' && parts[1]) {
+                const id = parts[1];
+                if (parts.length === 2 && m === 'GET') {
+                    const chat = await a.readChat(caller, id);
+                    return chat ? json(chat) : fail('That chat is gone.', 404, 'not_found');
+                }
+                if (parts.length === 2 && m === 'DELETE') {
+                    await a.removeChat(caller, id);
+                    return json({ ok: true });
+                }
+                if (parts.length === 4 && parts[2] === 'drafts' && m === 'POST') {
+                    const action = (await body(req)).action;
+                    if (action !== 'save' && action !== 'dismiss')
+                        return fail('action is save or dismiss.');
+                    return json(await a.settleDraft(caller, id, parts[3], action));
+                }
+            }
+            return fail('Not found.', 404);
+        }
+        catch (err) {
+            if (err instanceof AssistantError)
+                return fail(err.message, err.status, err.code);
+            console.error(JSON.stringify({
+                event: 'assistant_route_error',
+                route,
+                error: String(err?.stack ?? err).slice(0, 2000),
+            }));
+            return fail('Something went wrong.', 500);
+        }
+    };
+}

package/dist/assistant/state.d.ts

@@ -0,0 +1,109 @@
+/**
+ * The assistant's settings, keys and spend, as stored documents.
+ *
+ *   app      (the app's scope)   the cap per person on the app's key
+ *   key      (the app's scope)   the app's Anthropic key, tested before it is kept, sealed
+ *   scrapeql (the app's scope)   ScrapeQL's Access service token, tested before it is kept, sealed
+ *   settings (a person's scope)  their tiers, start tiers, hand off, advice, tool access, web, payer
+ *   key      (a person's scope)  their own Anthropic key and its monthly cap, sealed
+ *   spend:YYYY-MM                what each tier cost them this month, by payer
+ *
+ * Who pays: the person's pick (the app's key by default) while it has money left this month, else
+ * the other; with neither the assistant waits and says why.
+ */
+import type { AssistantAccess, AssistantEffort, AssistantPayer, AssistantWait, HandOffPolicy, UsagePart } from '@columenlabs/lumen-ui-types/assistant';
+import { type Docs } from './store.js';
+export interface KeyTest {
+    at: number;
+    ok: boolean;
+    detail: string;
+}
+export interface KeyDoc {
+    api_key: string;
+    saved_at: number;
+    test: KeyTest | null;
+    /** USD a month: the person's own key only. */
+    cap_usd?: number;
+}
+export interface TokenDoc {
+    client_id: string;
+    client_secret: string;
+    saved_at: number;
+    test: KeyTest | null;
+}
+export interface AppDoc {
+    /** USD each person may spend a month on the app's key. */
+    cap_usd?: number;
+}
+export interface PersonDoc {
+    tier?: string;
+    tiers?: Record<string, {
+        model: string;
+        effort: AssistantEffort;
+    }>;
+    tasks?: Record<string, string>;
+    hand_off?: HandOffPolicy;
+    advice?: string;
+    access?: Record<string, AssistantAccess>;
+    web?: boolean;
+    pay?: AssistantPayer;
+}
+export type SpendRow = UsagePart & {
+    payer: AssistantPayer;
+};
+export interface SpendDoc {
+    rows: SpendRow[];
+}
+/** USD a month when nobody set a cap. */
+export declare const DEFAULT_CAP = 10;
+/** `2026-10` in the app's time zone. */
+export declare function monthIn(timeZone: string, at?: Date): string;
+export declare function keyState(d: KeyDoc | TokenDoc | null, secret: (d: KeyDoc | TokenDoc) => string): {
+    set: false;
+} | {
+    set: true;
+    hint: string;
+    saved_at: number;
+    test?: KeyTest | undefined;
+};
+export interface Paying {
+    payer: AssistantPayer;
+    apiKey: string;
+    /** USD left this month under the payer's cap. */
+    left: number;
+    cap: number;
+}
+export declare class State {
+    readonly docs: Docs;
+    private readonly o;
+    constructor(docs: Docs, o: {
+        timeZone: string;
+        defaultCap: number;
+        appKey?: () => Promise<string | null | undefined>;
+    });
+    /** USD a month when nobody set a cap. */
+    get defaultCap(): number;
+    month(): string;
+    person(id: string): Promise<PersonDoc>;
+    setPerson(id: string, change: (d: PersonDoc) => PersonDoc): Promise<PersonDoc | null>;
+    app(): Promise<AppDoc>;
+    setApp(change: (d: AppDoc) => AppDoc): Promise<AppDoc | null>;
+    appKey(): Promise<KeyDoc | null>;
+    /** The app's key: the stored one, else the app's fallback (a Worker secret). */
+    appApiKey(): Promise<{
+        key: string;
+        fromEnv: boolean;
+    } | null>;
+    ownKey(id: string): Promise<KeyDoc | null>;
+    scrapeql(): Promise<TokenDoc | null>;
+    appCap(): Promise<number>;
+    spend(id: string, month?: string): Promise<SpendDoc>;
+    /** Adds an answer's use to this month's spend, by label and payer. */
+    addSpend(id: string, payer: AssistantPayer, parts: UsagePart[]): Promise<void>;
+    /** Who pays the person's next answer, or why nobody can. */
+    paying(id: string): Promise<{
+        paying: Paying | null;
+        wait: AssistantWait | null;
+    }>;
+}
+export declare const WAIT_TEXT: Record<AssistantWait, string>;