@columenlabs/lumen-ai 0.1.83 → 0.1.85

package/dist/assistant/engine.d.ts

@@ -1,4 +1,4 @@
-import type { AssistantAccess, AssistantChat, AssistantChatRow, AssistantMessage, AssistantProvider, AssistantStatus, DraftItem, StepItem } from '@columenlabs/lumen-ui-types/assistant';
+import type { AllowanceRequest, AllowanceState, AllowanceUnit, AssistantAccess, AssistantChat, AssistantChatRow, AssistantMessage, AssistantProvider, AssistantStatus, DraftItem, StepItem } from '@columenlabs/lumen-ui-types/assistant';
 import { type ModelDef, type TaskDef, type TierDef } from './models.js';
 import { State } from './state.js';
 import { type AssistantStore, type Sealer } from './store.js';
@@ -19,6 +19,35 @@ export interface AssistantCommandDef {
 export interface Caller {
     id: string;
     admin: boolean;
+    /** What approvers see a request from them as: their email or name. */
+    label?: string;
+}
+/**
+ * How an app counts allowance on its shared keys, and how a person asks for more. The kit holds
+ * the ledger and the forms; the app picks the unit, the size, who approves and how they hear.
+ */
+export interface AllowanceOptions {
+    /** What it is counted in; dollars by default. */
+    unit?: AllowanceUnit;
+    /** `month` (default): the admin's monthly cap plus grants made that month; `once`: one balance. */
+    period?: 'month' | 'once';
+    /**
+     * Units: each person's balance to start (once), or the monthly cap before an admin sets one
+     * (month).
+     */
+    starter?: number;
+    /** Amounts the Request more form offers. */
+    amounts?: number[];
+    /** Who may grant or decline requests; admins by default. */
+    approver?: (caller: Caller) => boolean;
+    /** Hears each request and each decision: tell the approvers, then the person. */
+    notify?: (n: AllowanceNotice) => void | Promise<void>;
+}
+/** A request made, or decided. */
+export interface AllowanceNotice {
+    kind: 'requested' | 'granted' | 'declined';
+    request: AllowanceRequest;
+    unit: AllowanceUnit;
 }
 /** A change a write tool made at once, as `undo` gets it. */
 export interface AssistantWrite {
@@ -103,8 +132,10 @@ export interface AssistantOptions {
     sealer?: Sealer;
     /** The app's key of a provider when none is stored in Settings (a Worker secret). */
     appKey?: (provider: AssistantProvider) => Promise<string | null | undefined>;
-    /** USD a person may spend a month when nobody set a cap; 10. */
+    /** USD a person may spend a month when nobody set a cap; 10 (or `allowance.starter`). */
     defaultCap?: number;
+    /** An allowance on the shared keys a person can ask to raise (Request more). */
+    allowance?: AllowanceOptions;
     /** Months and dates in this zone; UTC by default. */
     timeZone?: string;
     /** Chats are deleted this many days after their last message (`purge`); 30. */
@@ -145,6 +176,17 @@ export declare class Assistant {
     private access;
     private groupById;
     status(caller: Caller): Promise<AssistantStatus>;
+    private get unit();
+    private approver;
+    /** The person's allowance in the app's unit, and their newest request. */
+    allowanceState(caller: Caller): Promise<AllowanceState>;
+    private notify;
+    /** Asks the approvers for more; one open request at a time. */
+    requestMore(caller: Caller, amount: number, why: string): Promise<AllowanceRequest>;
+    /** Approvers: every request, newest first. */
+    allowanceRequests(caller: Caller): Promise<AllowanceRequest[]>;
+    /** Approvers: grants (any amount, the asked one by default) or declines an open request. */
+    decideRequest(caller: Caller, id: string, action: 'grant' | 'decline', amount?: number): Promise<AllowanceRequest>;
     listChats(caller: Caller): Promise<AssistantChatRow[]>;
     readChat(caller: Caller, id: string): Promise<AssistantChat | null>;
     removeChat(caller: Caller, id: string): Promise<void>;

package/dist/assistant/engine.js

@@ -25,6 +25,10 @@ import { DEFAULT_CAP, State, keyDocName, keyState, waitText, } from './state.js'
 import { Docs } from './store.js';
 import { ToolError, rowCount, toolName, withDeadline, } from './tools.js';
 import { scrapeqlTools, webFetchTools } from './web.js';
+const DOLLARS = { one: 'dollar', many: 'dollars', usd: 1 };
+const round2 = (n) => Math.round(n * 100) / 100;
+/** A request may ask for at most this many times the starter or monthly cap. */
+const REQUEST_MAX_TIMES = 100;
 /** A turn's failure the person can act on. */
 export class AssistantError extends Error {
     code;
@@ -149,11 +153,23 @@ export class Assistant {
             { id: 'chat', label: 'Chat', about: 'The side panel', tier: o.tiers[0].id },
         ];
         this.groups = o.groups ?? [];
+        const al = o.allowance;
+        const unit = al?.unit ?? DOLLARS;
         this.state = new State(new Docs(o.store, o.sealer), {
             timeZone: o.timeZone ?? 'UTC',
-            defaultCap: o.defaultCap ?? DEFAULT_CAP,
+            defaultCap: o.defaultCap ??
+                (al?.starter !== undefined && al.period !== 'once' ? al.starter * unit.usd : DEFAULT_CAP),
             ...(o.appKey ? { appKey: o.appKey } : {}),
             ...(o.fetch ? { fetch: o.fetch } : {}),
+            ...(al
+                ? {
+                    allowance: {
+                        usd: unit.usd,
+                        period: al.period ?? 'month',
+                        starter: al.starter ?? DEFAULT_CAP / unit.usd,
+                    },
+                }
+                : {}),
         });
     }
     anthropic(apiKey) {
@@ -310,7 +326,111 @@ export class Assistant {
                 payer: paying?.payer ?? null,
                 rows: spend.rows,
             },
+            ...(this.o.allowance ? { allowance: await this.allowanceState(caller) } : {}),
+        };
+    }
+    // ---------------------------------------------------------------- allowance
+    get unit() {
+        return this.o.allowance?.unit ?? DOLLARS;
+    }
+    approver(caller) {
+        return this.o.allowance?.approver ? this.o.allowance.approver(caller) : caller.admin;
+    }
+    /** The person's allowance in the app's unit, and their newest request. */
+    async allowanceState(caller) {
+        const al = this.o.allowance ?? {};
+        const u = this.unit;
+        const [budget, doc, approver] = await Promise.all([
+            this.state.appBudget(caller.id),
+            this.state.allowance(caller.id),
+            this.approver(caller),
+        ]);
+        const total = round2(budget.total / u.usd);
+        const used = round2(budget.used / u.usd);
+        const base = this.state.allowanceConfig?.period === 'once'
+            ? (this.state.allowanceConfig?.starter ?? total)
+            : (await this.state.appCap()) / u.usd;
+        const waiting = approver
+            ? (await this.state.requests()).rows.filter((r) => r.status === 'open').length
+            : undefined;
+        return {
+            unit: u,
+            period: al.period ?? 'month',
+            total,
+            used,
+            left: round2(Math.max(0, total - used)),
+            request: doc.request ?? null,
+            amounts: al.amounts ?? [...new Set([base, base * 3].map((n) => Math.max(1, Math.round(n))))],
+            approver,
+            ...(waiting !== undefined ? { waiting } : {}),
+        };
+    }
+    notify(kind, request) {
+        const n = this.o.allowance?.notify;
+        if (!n)
+            return;
+        // A notice that fails is logged; the request or decision stands.
+        return Promise.resolve(n({ kind, request, unit: this.unit })).catch((err) => console.error(JSON.stringify({ event: 'assistant_allowance_notify_failed', kind, error: String(err) })));
+    }
+    /** Asks the approvers for more; one open request at a time. */
+    async requestMore(caller, amount, why) {
+        if (!this.o.allowance)
+            throw new AssistantError('This app has no allowance to raise.', 'not_found', 404);
+        const s = await this.allowanceState(caller);
+        if (s.request?.status === 'open')
+            throw new AssistantError('Your last request is still waiting.', 'open_request', 409);
+        const max = Math.max(...s.amounts, 1) * REQUEST_MAX_TIMES;
+        if (!(amount > 0) || amount > max)
+            throw new AssistantError(`Ask for 1 to ${max} ${this.unit.many}.`, 'bad_amount');
+        const request = {
+            id: `ar_${crypto.randomUUID().replace(/-/g, '').slice(0, 16)}`,
+            person: caller.id,
+            who: caller.label ?? caller.id,
+            amount: round2(amount),
+            why: why.slice(0, 500),
+            at: Date.now(),
+            status: 'open',
         };
+        await this.state.setAllowance(caller.id, (d) => ({ ...d, request }));
+        await this.state.putRequest(request);
+        await this.notify('requested', request);
+        return request;
+    }
+    /** Approvers: every request, newest first. */
+    async allowanceRequests(caller) {
+        if (!(await this.approver(caller)))
+            throw new AssistantError('Only an approver can see requests.', 'forbidden', 403);
+        return (await this.state.requests()).rows;
+    }
+    /** Approvers: grants (any amount, the asked one by default) or declines an open request. */
+    async decideRequest(caller, id, action, amount) {
+        if (!(await this.approver(caller)))
+            throw new AssistantError('Only an approver can decide requests.', 'forbidden', 403);
+        const r = (await this.state.requests()).rows.find((x) => x.id === id);
+        if (!r)
+            throw new AssistantError('That request is gone.', 'not_found', 404);
+        if (r.status !== 'open')
+            throw new AssistantError('That request was already decided.', 'decided', 409);
+        const granted = action === 'grant' ? round2(amount ?? r.amount) : undefined;
+        if (granted !== undefined && !(granted > 0))
+            throw new AssistantError(`Grant more than 0 ${this.unit.many}.`, 'bad_amount');
+        const done = {
+            ...r,
+            status: action === 'grant' ? 'granted' : 'declined',
+            ...(granted !== undefined ? { granted } : {}),
+            decided_at: Date.now(),
+            decided_by: caller.label ?? caller.id,
+        };
+        await this.state.setAllowance(r.person, (d) => ({
+            ...d,
+            grants: granted !== undefined
+                ? [...d.grants, { at: Date.now(), amount: granted, by: caller.id, request: r.id }]
+                : d.grants,
+            ...(d.request?.id === r.id ? { request: done } : {}),
+        }));
+        await this.state.putRequest(done);
+        await this.notify(action === 'grant' ? 'granted' : 'declined', done);
+        return done;
     }
     // ---------------------------------------------------------------- chats
     async listChats(caller) {
@@ -475,7 +595,7 @@ export class Assistant {
         const { paying, wait } = await this.state.paying(caller.id, main.model.provider);
         if (!paying) {
             const code = wait ?? 'not_connected';
-            const text = waitText(code, main.model.provider);
+            const text = waitText(code, main.model.provider, !!this.o.allowance);
             doc.items.push({ kind: 'error', text, code });
             await this.writeChat(caller, chatId, doc);
             emit('error', { message: text, code });
@@ -541,7 +661,7 @@ export class Assistant {
             }
             const page = this.cardNews(doc) +
                 (req.refs?.length
-                    ? `The person points at: ${JSON.stringify(req.refs).slice(0, 16000)}\n\n`
+                    ? `The person points at these parts: they are what "this" means, and when the person asks for a change they are the only parts to change. Read anything else you need (the rest of the page, other records, your tools) for context, but leave it as it is unless they ask.\n${JSON.stringify(req.refs).slice(0, 16000)}\n\n`
                     : '') +
                 (req.context
                     ? `Page: ${req.context.label}${req.context.note === undefined ? '' : `\n${JSON.stringify(req.context.note).slice(0, 4000)}`}\n\n`
@@ -667,6 +787,8 @@ export class Assistant {
             '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.',
             'A tool marked WRITES AT ONCE makes its change when you call it; the person can undo it from the chat. Change only what they asked for, and say what you changed.',
         ];
+        if (main)
+            lines.push(`You run on the ${main.tier.label} tier: ${main.model.label}, from ${PROVIDERS[main.model.provider].label}. Say so when asked which tier or model you are.`);
         if (!fns.size)
             lines.push('No tools are on now: the person can turn them on in Settings ▸ Tools.');
         if (failed)

package/dist/assistant/routes.js

@@ -19,6 +19,9 @@
  *   GET    /chats, GET|DELETE /chats/:id
  *   POST   /chats/:id/drafts/:draft {action: save | dismiss}
  *   POST   /chats/:id/writes/:step/undo
+ *   POST   /allowance/request {amount, why}   asks for more allowance (one open at a time)
+ *   GET    /allowance/requests                approvers: every request
+ *   POST   /allowance/requests/:id {action: grant | decline, amount?}   approvers
  *
  * 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
@@ -300,6 +303,23 @@ export function assistantRoutes(a, o) {
                 }
                 case 'GET /chats':
                     return json(await a.listChats(caller));
+                case 'POST /allowance/request': {
+                    const b = await body(req);
+                    const amount = typeof b.amount === 'number' && Number.isFinite(b.amount) ? b.amount : 0;
+                    const why = typeof b.why === 'string' ? b.why.trim() : '';
+                    await a.requestMore(caller, amount, why);
+                    return status();
+                }
+                case 'GET /allowance/requests':
+                    return json(await a.allowanceRequests(caller));
+            }
+            if (parts[0] === 'allowance' && parts[1] === 'requests' && parts[2] && m === 'POST') {
+                const b = await body(req);
+                const action = b.action;
+                if (action !== 'grant' && action !== 'decline')
+                    return fail('action is grant or decline.');
+                const amount = typeof b.amount === 'number' && Number.isFinite(b.amount) ? b.amount : undefined;
+                return json(await a.decideRequest(caller, parts[2], action, amount));
             }
             if (parts[0] === 'chats' && parts[1]) {
                 const id = parts[1];

package/dist/assistant/state.d.ts

@@ -11,12 +11,15 @@
  *                                plan sign-in, refreshed before it runs out
  *   signin:<p>   (a person's)    the app's sign-in registration for them, kept across sign-outs
  *   spend:YYYY-MM                what each tier cost them this month, by payer
+ *   allowance    (a person's)    grants of more allowance, their newest request, and (when it is
+ *                                once for good) what they spent on the app's keys in all
+ *   allowance_requests (the app's)  every request, newest first, for approvers
  *
  * Who pays: the person's pick (the app's keys by default) while it has a key for the provider the
  * tier runs on and money left this month, else the other; with neither the assistant waits and says
  * why. A cap covers every provider of its payer.
  */
-import type { AssistantAccess, AssistantEffort, AssistantPayer, AssistantProvider, AssistantWait, HandOffPolicy, UsagePart } from '@columenlabs/lumen-ui-types/assistant';
+import type { AllowanceRequest, AssistantAccess, AssistantEffort, AssistantPayer, AssistantProvider, AssistantWait, HandOffPolicy, UsagePart } from '@columenlabs/lumen-ui-types/assistant';
 import { type ChatgptTokens } from './chatgpt.js';
 import { type Docs } from './store.js';
 export interface KeyTest {
@@ -60,6 +63,29 @@ export interface PersonDoc {
     /** USD a month on their own keys. */
     own_cap?: number;
 }
+/** How the app counts allowance on its shared keys (`createAssistant` `allowance`). */
+export interface AllowanceConfig {
+    /** USD one unit buys. */
+    usd: number;
+    /** `month`: the cap resets each month, grants count in their month; `once`: one balance for good. */
+    period: 'month' | 'once';
+    /** Units each person starts with (once); a month's cap is the admin's cap in Settings. */
+    starter: number;
+}
+export interface AllowanceDoc {
+    grants: {
+        at: number;
+        amount: number;
+        by: string;
+        request?: string;
+    }[];
+    /** USD spent on the app's keys in all (counted only when the allowance is once for good). */
+    spent_usd?: number;
+    request?: AllowanceRequest;
+}
+export interface RequestsDoc {
+    rows: AllowanceRequest[];
+}
 export type SpendRow = UsagePart & {
     payer: AssistantPayer;
 };
@@ -99,7 +125,22 @@ export declare class State {
         defaultCap: number;
         appKey?: (provider: AssistantProvider) => Promise<string | null | undefined>;
         fetch?: typeof fetch;
+        allowance?: AllowanceConfig;
     });
+    get allowanceConfig(): AllowanceConfig | undefined;
+    allowance(id: string): Promise<AllowanceDoc>;
+    setAllowance(id: string, change: (d: AllowanceDoc) => AllowanceDoc): Promise<AllowanceDoc | null>;
+    requests(): Promise<RequestsDoc>;
+    /** Adds or replaces one request in the approvers' list. */
+    putRequest(r: AllowanceRequest): Promise<RequestsDoc | null>;
+    /**
+     * USD the person has on the app's keys for the period and USD used: the admin's monthly cap plus
+     * this month's grants, or (once for good) the starter and every grant against all spend.
+     */
+    appBudget(id: string, spentThisMonth?: number): Promise<{
+        total: number;
+        used: number;
+    }>;
     /** USD a month when nobody set a cap. */
     get defaultCap(): number;
     month(): string;
@@ -137,4 +178,4 @@ export declare class State {
         wait: AssistantWait | null;
     }>;
 }
-export declare function waitText(wait: AssistantWait, provider: AssistantProvider): string;
+export declare function waitText(wait: AssistantWait, provider: AssistantProvider, canRequest?: boolean): string;

package/dist/assistant/state.js

@@ -3,6 +3,8 @@ import { PROVIDERS, keyHint } from './models.js';
 import { APP_SCOPE } from './store.js';
 /** Where a provider's key is kept: `key` for Anthropic, `key:<provider>` for the rest. */
 export const keyDocName = (provider) => provider === 'anthropic' ? 'key' : `key:${provider}`;
+/** Requests kept for approvers: the newest this many. */
+const REQUESTS_KEPT = 300;
 /** USD a month when nobody set a cap. */
 export const DEFAULT_CAP = 10;
 /** `2026-10` in the app's time zone. */
@@ -30,6 +32,47 @@ export class State {
         this.docs = docs;
         this.o = o;
     }
+    get allowanceConfig() {
+        return this.o.allowance;
+    }
+    allowance(id) {
+        return this.docs.read(id, 'allowance').then((d) => d ?? { grants: [] });
+    }
+    setAllowance(id, change) {
+        return this.docs.update(id, 'allowance', (d) => change(d ?? { grants: [] }));
+    }
+    requests() {
+        return this.docs
+            .read(APP_SCOPE, 'allowance_requests')
+            .then((d) => d ?? { rows: [] });
+    }
+    /** Adds or replaces one request in the approvers' list. */
+    putRequest(r) {
+        return this.docs.update(APP_SCOPE, 'allowance_requests', (d) => ({
+            rows: [r, ...(d?.rows ?? []).filter((x) => x.id !== r.id)].slice(0, REQUESTS_KEPT),
+        }));
+    }
+    /**
+     * USD the person has on the app's keys for the period and USD used: the admin's monthly cap plus
+     * this month's grants, or (once for good) the starter and every grant against all spend.
+     */
+    async appBudget(id, spentThisMonth) {
+        const al = this.o.allowance;
+        const used = spentThisMonth ??
+            (await this.spend(id)).rows.filter((r) => r.payer === 'app').reduce((a, r) => a + r.usd, 0);
+        if (!al)
+            return { total: await this.appCap(), used };
+        const d = await this.allowance(id);
+        if (al.period === 'once') {
+            const units = al.starter + d.grants.reduce((a, g) => a + g.amount, 0);
+            return { total: units * al.usd, used: d.spent_usd ?? 0 };
+        }
+        const month = this.month();
+        const granted = d.grants
+            .filter((g) => monthIn(this.o.timeZone, new Date(g.at)) === month)
+            .reduce((a, g) => a + g.amount, 0);
+        return { total: (await this.appCap()) + granted * al.usd, used };
+    }
     /** USD a month when nobody set a cap. */
     get defaultCap() {
         return this.o.defaultCap;
@@ -133,6 +176,11 @@ export class State {
             }
             return { rows };
         });
+        if (payer === 'app' && this.o.allowance?.period === 'once') {
+            const usd = parts.reduce((a, p) => a + p.usd, 0);
+            if (usd > 0)
+                await this.setAllowance(id, (d) => ({ ...d, spent_usd: (d.spent_usd ?? 0) + usd }));
+        }
     }
     /** The payer's key of each provider, those set, and which are plan sign-ins. */
     async keysOf(id, payer) {
@@ -153,15 +201,15 @@ export class State {
     }
     /** Who pays the person's next answer on `provider`'s model, or why nobody can. */
     async paying(id, provider) {
-        const [person, appKeys, ownKeys, spend, appCap, ownCap] = await Promise.all([
+        const [person, appKeys, ownKeys, spend, ownCap] = await Promise.all([
             this.person(id),
             this.keysOf(id, 'app'),
             this.keysOf(id, 'own'),
             this.spend(id),
-            this.appCap(),
             this.ownCap(id),
         ]);
         const spent = (p) => spend.rows.filter((r) => r.payer === p).reduce((a, r) => a + r.usd, 0);
+        const budget = await this.appBudget(id, spent('app'));
         const app = appKeys.keys[provider];
         const own = ownKeys.keys[provider];
         const sources = {
@@ -170,8 +218,8 @@ export class State {
                     payer: 'app',
                     apiKey: app,
                     ...appKeys,
-                    cap: appCap,
-                    left: appCap - spent('app'),
+                    cap: budget.total,
+                    left: budget.total - budget.used,
                 }
                 : null,
             own: own
@@ -198,11 +246,13 @@ export class State {
         return { paying: null, wait: capped === 'own' ? 'own_cap' : 'app_cap' };
     }
 }
-export function waitText(wait, provider) {
+export function waitText(wait, provider, canRequest = false) {
     const label = PROVIDERS[provider].label;
     if (wait === 'not_connected')
         return `No ${label} key is set: add one in Settings ▸ Model providers, or pick another model in Settings ▸ Models.`;
     if (wait === 'app_cap')
-        return "You reached this month's cap on the shared keys. Add your own key, or wait for next month.";
+        return canRequest
+            ? 'You used your allowance on the shared keys. Request more in Settings, or add your own key.'
+            : "You reached this month's cap on the shared keys. Add your own key, or wait for next month.";
     return 'Your own keys reached their monthly cap: raise it in Settings ▸ Model providers.';
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@columenlabs/lumen-ai",
-  "version": "0.1.83",
+  "version": "0.1.85",
   "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",
@@ -41,8 +41,8 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "0.133.0",
-    "@columenlabs/lumen-ops": "0.1.83",
-    "@columenlabs/lumen-ui-types": "0.1.83",
+    "@columenlabs/lumen-ops": "0.1.85",
+    "@columenlabs/lumen-ui-types": "0.1.85",
     "openai": "7.32.0",
     "zod": "^4.3.6"
   },