@columenlabs/lumen-ai 0.1.82 → 0.1.84

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 });

package/dist/assistant/index.d.ts

@@ -8,7 +8,11 @@
  *
  * The panel and the Settings sections are `@columenlabs/lumen-ui`'s; the types they share are
  * `@columenlabs/lumen-ui-types/assistant`.
+ *
+ * The ChatGPT plan sign-in's parts are exported on their own too, for an app that keeps the tokens and
+ * calls OpenAI itself (`LumenChatgptSignin` is the panel's part for it).
  */
+export * from './chatgpt.js';
 export * from './engine.js';
 export * from './models.js';
 export * from './routes.js';

package/dist/assistant/index.js

@@ -8,7 +8,11 @@
  *
  * The panel and the Settings sections are `@columenlabs/lumen-ui`'s; the types they share are
  * `@columenlabs/lumen-ui-types/assistant`.
+ *
+ * The ChatGPT plan sign-in's parts are exported on their own too, for an app that keeps the tokens and
+ * calls OpenAI itself (`LumenChatgptSignin` is the panel's part for it).
  */
+export * from './chatgpt.js';
 export * from './engine.js';
 export * from './models.js';
 export * from './routes.js';

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.82",
+  "version": "0.1.84",
   "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.82",
-    "@columenlabs/lumen-ui-types": "0.1.82",
+    "@columenlabs/lumen-ops": "0.1.84",
+    "@columenlabs/lumen-ui-types": "0.1.84",
     "openai": "7.32.0",
     "zod": "^4.3.6"
   },