@columenlabs/lumen-ai 0.1.238 → 0.1.240

package/README.md

@@ -92,6 +92,7 @@ const assistant = createAssistant({
   // turn when a ChatGPT plan runs out ('shared': the same model on the app's key, shared spend).
   // ownWays: async (caller) => ({ openai: ['key', 'plan'] }),
   // ownFallback: async (caller) => true,
+  // credits: (tier) => tier !== 'reviewer', // false: that tier runs on the app's key, never counted against allowance
   // planFallback: 'shared',
 });
 // A check the app always runs on its own key, whoever pays the person's answers:

package/dist/assistant/engine.d.ts

@@ -205,6 +205,12 @@ export interface AssistantOptions {
      * its cap or their plan is used up. True by default.
      */
     ownFallback?: (caller: Caller) => boolean | Promise<boolean>;
+    /**
+     * Whether a tier's work counts against the person's allowance (Admin ▸ Models' Credits switch).
+     * False: it runs on the app's key whatever the person pays with or has left, and its spend is
+     * kept as free (shown, never counted). Left out, every tier counts.
+     */
+    credits?: (tier: string) => boolean | Promise<boolean>;
     /**
      * Who answers when a ChatGPT plan reaches its usage limit mid-turn. 'claude' (default): the
      * app's smallest Claude on the same payer's Anthropic key. 'shared': the same model on the app's
@@ -273,6 +279,10 @@ export declare class Assistant {
     mayOwn(caller: Caller, provider: AssistantProvider, way: AssistantOwnWay): Promise<boolean>;
     /** The app's rules for who pays this person's answers (own ways, fallback). */
     private payingRules;
+    /** True when this tier's work is the app's own (`credits` answers false): the app's key, not counted. */
+    private freeTier;
+    /** The paying rules for a tier: its own rules, or the app's key uncounted for a free tier. */
+    private rulesFor;
     /**
      * One turn as a Think agent's plan (`LumenAgent` in `@columenlabs/lumen-ai/agent`): the person's
      * tier and its model on whoever pays, the tool groups at their access, the kit's rules, the

package/dist/assistant/engine.js

@@ -246,6 +246,18 @@ export class Assistant {
         ]);
         return { ...(ways ? { ways } : {}), fallback, ...(only ? { only } : {}) };
     }
+    /** True when this tier's work is the app's own (`credits` answers false): the app's key, not counted. */
+    async freeTier(tier) {
+        if (!this.o.credits)
+            return false;
+        return (await Promise.resolve(this.o.credits(tier)).catch(() => true)) === false;
+    }
+    /** The paying rules for a tier: its own rules, or the app's key uncounted for a free tier. */
+    async rulesFor(caller, tier, only) {
+        const free = await this.freeTier(tier);
+        const rules = await this.payingRules(caller, free ? 'app' : only);
+        return { rules: free ? { ...rules, free: true } : rules, free };
+    }
     // ---------------------------------------------------------------- a turn on Think
     /**
      * One turn as a Think agent's plan (`LumenAgent` in `@columenlabs/lumen-ai/agent`): the person's
@@ -263,7 +275,7 @@ export class Assistant {
             ? this.tierById(input.tier)
             : undefined;
         const main = await this.session(caller, lower ?? picked);
-        const rules = await this.payingRules(caller);
+        const { rules, free } = await this.rulesFor(caller, main.tier.id);
         const { paying, wait } = await this.state.paying(caller.id, main.model.provider, rules);
         if (!paying) {
             const code = wait ?? 'not_connected';
@@ -376,7 +388,7 @@ export class Assistant {
             const onShared = sharedLabel ? end.parts.filter((x) => x.label === sharedLabel) : [];
             const onPayer = onShared.length ? end.parts.filter((x) => !onShared.includes(x)) : end.parts;
             await this.state
-                .addSpend(caller.id, paying.payer, onPayer, { task: 'chat', ms: end.ms })
+                .addSpend(caller.id, paying.payer, onPayer, { task: 'chat', ms: end.ms }, free)
                 .catch(() => undefined);
             if (onShared.length)
                 await this.state
@@ -571,7 +583,7 @@ export class Assistant {
             this.state.spend(caller.id),
             this.state.appCap(),
             this.state.ownCap(caller.id),
-            this.payingRules(caller).then((r) => this.state.paying(caller.id, mainModel.provider, r)),
+            this.rulesFor(caller, main.id).then(({ rules }) => this.state.paying(caller.id, mainModel.provider, rules)),
         ]);
         const link = await linkTest;
         const tiers = await Promise.all(this.tiers.map(async (t) => {
@@ -970,7 +982,8 @@ export class Assistant {
     async complete(caller, o) {
         const began = Date.now();
         const s = await this.session(caller, await this.mainTier(caller, o.task));
-        const { paying, wait } = await this.state.paying(caller.id, s.model.provider, await this.payingRules(caller, o.payer));
+        const { rules, free } = await this.rulesFor(caller, s.tier.id, o.payer);
+        const { paying, wait } = await this.state.paying(caller.id, s.model.provider, rules);
         if (!paying) {
             const code = wait ?? 'not_connected';
             throw new AssistantError(waitText(code, s.model.provider, !!this.o.allowance), code, 402);
@@ -1031,10 +1044,7 @@ export class Assistant {
         }
         finally {
             const part = s.meter.part();
-            await this.state.addSpend(caller.id, paying.payer, [part], {
-                task: o.tag ?? o.task,
-                ms: Date.now() - began,
-            });
+            await this.state.addSpend(caller.id, paying.payer, [part], { task: o.tag ?? o.task, ms: Date.now() - began }, free);
             const task = this.tasks.find((t) => t.id === o.task);
             await this.state
                 .addUsage(caller.id, {

package/dist/assistant/state.d.ts

@@ -94,8 +94,11 @@ export interface AllowanceDoc {
 export interface RequestsDoc {
     rows: AllowanceRequest[];
 }
+/** `free`: run on the app's key for a job the app does not count against the person's allowance
+ *  (`AssistantOptions.credits`). Kept apart so the admin still sees what it cost. */
 export type SpendRow = UsagePart & {
     payer: AssistantPayer;
+    free?: true;
 };
 /** The ways of their own a person may pay with, per provider; a provider left out has none. */
 export type OwnWays = Partial<Record<AssistantProvider, AssistantOwnWay[]>>;
@@ -107,6 +110,8 @@ export interface PayingRules {
     fallback?: boolean;
     /** Only this payer: an app's own check always runs on the shared key (`complete({ payer })`). */
     only?: AssistantPayer;
+    /** The app's key, not counted against the person's allowance and never stopped by it. */
+    free?: boolean;
 }
 /**
  * One task's use of one model this month: what a kind of work cost (a chat answer, a background
@@ -250,7 +255,7 @@ export declare class State {
     addSpend(id: string, payer: AssistantPayer, parts: UsagePart[], at?: {
         task: string;
         ms?: number;
-    }): Promise<void>;
+    }, free?: boolean): Promise<void>;
     /**
      * Adds one answer's use to a chat or run in this month's history (`usage:YYYY-MM`): one entry a
      * chat or run, its parts merged, the newest `USAGE_KEPT` kept. `title` names a new entry only;

package/dist/assistant/state.js

@@ -92,7 +92,9 @@ export class State {
     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);
+            (await this.spend(id)).rows
+                .filter((r) => r.payer === 'app' && !r.free)
+                .reduce((a, r) => a + r.usd, 0);
         if (!al)
             return { total: await this.appCap(), used };
         const d = await this.allowance(id);
@@ -239,7 +241,7 @@ export class State {
      * Adds an answer's use to this month's spend, by label and payer. `at` names the task the answer
      * was for and how long it took, so the month also adds up per task and model (`tasks`).
      */
-    async addSpend(id, payer, parts, at) {
+    async addSpend(id, payer, parts, at, free = false) {
         if (!parts.some((p) => p.calls))
             return;
         await this.docs.update(id, `spend:${this.month()}`, (d) => {
@@ -275,7 +277,7 @@ export class State {
             for (const p of parts) {
                 if (!p.calls)
                     continue;
-                const i = rows.findIndex((r) => r.label === p.label && r.payer === payer);
+                const i = rows.findIndex((r) => r.label === p.label && r.payer === payer && !!r.free === free);
                 const prev = i >= 0 ? rows[i] : undefined;
                 const row = prev
                     ? {
@@ -286,7 +288,7 @@ export class State {
                         out: prev.out + p.out,
                         usd: prev.usd + p.usd,
                     }
-                    : { ...p, payer };
+                    : { ...p, payer, ...(free ? { free: true } : {}) };
                 if (i >= 0)
                     rows[i] = row;
                 else
@@ -294,7 +296,7 @@ export class State {
             }
             return tasks.length ? { rows, tasks } : { rows };
         });
-        if (payer === 'app' && this.o.allowance?.period === 'once') {
+        if (payer === 'app' && !free && 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 }));
@@ -376,7 +378,7 @@ export class State {
             this.spend(id),
             this.ownCap(id),
         ]);
-        const spent = (p) => spend.rows.filter((r) => r.payer === p).reduce((a, r) => a + r.usd, 0);
+        const spent = (p) => spend.rows.filter((r) => r.payer === p && !r.free).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];
@@ -387,7 +389,8 @@ export class State {
                     apiKey: app,
                     ...appKeys,
                     cap: budget.total,
-                    left: budget.total - budget.used,
+                    // A free job runs on the app's key whatever the person's allowance holds.
+                    left: rules.free ? Number.POSITIVE_INFINITY : budget.total - budget.used,
                 }
                 : null,
             own: own

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@columenlabs/lumen-ai",
-  "version": "0.1.238",
+  "version": "0.1.240",
   "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",
@@ -52,8 +52,8 @@
     "@ai-sdk/openai": "4.0.108",
     "@anthropic-ai/sdk": "0.133.0",
     "@cloudflare/think": "0.23.0",
-    "@columenlabs/lumen-ops": "0.1.238",
-    "@columenlabs/lumen-ui-types": "0.1.238",
+    "@columenlabs/lumen-ops": "0.1.240",
+    "@columenlabs/lumen-ui-types": "0.1.240",
     "agents": "0.32.0",
     "ai": "7.0.162",
     "just-bash": "3.6.0",