@columenlabs/lumen-ai 0.1.230 → 0.1.231

package/README.md

@@ -87,7 +87,15 @@ const assistant = createAssistant({
   sealer, // the app's own sealing: keys and chats are stored sealed
   // A provider's key when none is set in Settings.
   appKey: async (provider) => (provider === 'openai' ? env.OPENAI_API_KEY : env.ANTHROPIC_API_KEY),
+  // Bring your own AI, per caller (a feature flag, a person's plan): which own ways Settings offers
+  // and the routes accept, whether their own key falls back to the shared one, and who finishes a
+  // 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,
+  // planFallback: 'shared',
 });
+// A check the app always runs on its own key, whoever pays the person's answers:
+// await assistant.complete(caller, { task: 'scope', system, prompt, payer: 'app' });
 
 const routes = assistantRoutes(assistant, {
   base: '/api/assistant',

package/dist/assistant/engine.d.ts

@@ -1,8 +1,8 @@
-import type { AllowanceRequest, AllowanceState, AllowanceUnit, AssistantAccess, AssistantChat, AssistantChatRow, AssistantEffort, AssistantMessage, AssistantOwnWay, AssistantProvider, AssistantStatus, UsagePart } from '@columenlabs/lumen-ui-types/assistant';
+import type { AllowanceRequest, AllowanceState, AllowanceUnit, AssistantAccess, AssistantChat, AssistantChatRow, AssistantEffort, AssistantMessage, AssistantOwnWay, AssistantPayer, AssistantProvider, AssistantStatus, UsagePart } from '@columenlabs/lumen-ui-types/assistant';
 import type { AgentTurnEnd, AgentTurnPlan } from '../agent/agent.js';
 import { type BearingsExtra, type BearingsNow } from './bearings.js';
 import { type ModelDef, type TaskDef, type TierDef } from './models.js';
-import { State } from './state.js';
+import { type OwnWays, State } from './state.js';
 import { type AssistantStore, type Sealer } from './store.js';
 import { type ToolSource } from './tools.js';
 import { type AccessToken, type WebFetchOptions } from './web.js';
@@ -194,6 +194,23 @@ export interface AssistantOptions {
     keepDays?: number;
     /** The fetch the model providers and ScrapeQL calls go through. */
     fetch?: typeof fetch;
+    /**
+     * Which of their own ways (an API key, a plan sign-in) a person may pay with, per provider: a
+     * provider left out has none, and Settings shows only these. Left out, every way of every
+     * provider (feature flags or a person's plan decide it per caller).
+     */
+    ownWays?: (caller: Caller) => OwnWays | Promise<OwnWays>;
+    /**
+     * Whether a person who pays with their own key first moves to the shared key when theirs is at
+     * its cap or their plan is used up. True by default.
+     */
+    ownFallback?: (caller: Caller) => 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
+     * shared key, counted as shared spend (only when `ownFallback` allows it).
+     */
+    planFallback?: 'claude' | 'shared';
     onStep?: (s: StepRecord) => void | Promise<void>;
 }
 /** A turn's failure the person can act on. */
@@ -250,6 +267,12 @@ export declare class Assistant {
     private mainTier;
     private access;
     private groupById;
+    /** The own ways the app lets this person pay with (`ownWays`); undefined is every way. */
+    ownWaysOf(caller: Caller): Promise<OwnWays | undefined>;
+    /** Whether this person may use `way` of their own on `provider`. */
+    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;
     /**
      * 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
@@ -349,6 +372,11 @@ export declare class Assistant {
          * task does more than one kind of work (a first try, a repair). Left out, it is the task.
          */
         tag?: string;
+        /**
+         * Only this payer: 'app' runs the call on the shared key whatever the person pays with (a
+         * check the app always runs on its own key). Left out, whoever pays the person's answers.
+         */
+        payer?: AssistantPayer;
     }): Promise<{
         text: string;
         usd: number;

package/dist/assistant/engine.js

@@ -229,6 +229,23 @@ export class Assistant {
     groupById(id) {
         return this.groups.find((g) => g.id === id);
     }
+    /** The own ways the app lets this person pay with (`ownWays`); undefined is every way. */
+    async ownWaysOf(caller) {
+        return this.o.ownWays ? await this.o.ownWays(caller) : undefined;
+    }
+    /** Whether this person may use `way` of their own on `provider`. */
+    async mayOwn(caller, provider, way) {
+        const ways = await this.ownWaysOf(caller);
+        return !ways || !!ways[provider]?.includes(way);
+    }
+    /** The app's rules for who pays this person's answers (own ways, fallback). */
+    async payingRules(caller, only) {
+        const [ways, fallback] = await Promise.all([
+            this.ownWaysOf(caller),
+            this.o.ownFallback ? this.o.ownFallback(caller) : true,
+        ]);
+        return { ...(ways ? { ways } : {}), fallback, ...(only ? { only } : {}) };
+    }
     // ---------------------------------------------------------------- a turn on Think
     /**
      * One turn as a Think agent's plan (`LumenAgent` in `@columenlabs/lumen-ai/agent`): the person's
@@ -246,7 +263,8 @@ export class Assistant {
             ? this.tierById(input.tier)
             : undefined;
         const main = await this.session(caller, lower ?? picked);
-        const { paying, wait } = await this.state.paying(caller.id, main.model.provider);
+        const rules = await this.payingRules(caller);
+        const { paying, wait } = await this.state.paying(caller.id, main.model.provider, rules);
         if (!paying) {
             const code = wait ?? 'not_connected';
             throw new AssistantError(waitText(code, main.model.provider, !!this.o.allowance), code, 402);
@@ -256,13 +274,26 @@ export class Assistant {
             return apiKey ? { apiKey, ...(paying.plans[provider] ? { plan: true } : {}) } : null;
         };
         const key = keyOf(main.model.provider) ?? { apiKey: paying.apiKey };
-        // A ChatGPT plan used up for now: the app's first Claude (its smallest) answers instead, on
-        // the same payer's Anthropic key, rather than the turn ending in the limit's error.
-        const claude = key.plan ? this.models.find((m) => m.provider === 'anthropic') : undefined;
-        const claudeKey = claude ? keyOf('anthropic') : null;
-        const fallback = claude && claudeKey
-            ? { model: claude, key: claudeKey, label: `${main.tier.label} · ${claude.label}` }
-            : undefined;
+        // A ChatGPT plan used up for now: rather than the turn ending in the limit's error, the same
+        // model on the app's shared key ('shared'), or the app's first Claude (its smallest) on the
+        // same payer's Anthropic key.
+        let fallback;
+        let sharedLabel;
+        if (key.plan && this.o.planFallback === 'shared') {
+            const shared = rules.fallback !== false
+                ? (await this.state.paying(caller.id, main.model.provider, { only: 'app' })).paying
+                : null;
+            if (shared) {
+                sharedLabel = `${main.meter.label} · shared key`;
+                fallback = { model: main.model, key: { apiKey: shared.apiKey }, label: sharedLabel };
+            }
+        }
+        else if (key.plan) {
+            const claude = this.models.find((m) => m.provider === 'anthropic');
+            const claudeKey = claude ? keyOf('anthropic') : null;
+            if (claude && claudeKey)
+                fallback = { model: claude, key: claudeKey, label: `${main.tier.label} · ${claude.label}` };
+        }
         const p = await this.state.person(caller.id);
         const policy = p.hand_off ?? 'next';
         const advisor = await this.advisorFor(caller, p.advice, main);
@@ -341,9 +372,16 @@ export class Assistant {
                 : {},
         };
         const settle = async (end) => {
+            // What the shared key answered after a plan ran out is the app's spend, not the person's.
+            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, end.parts, { task: 'chat', ms: end.ms })
+                .addSpend(caller.id, paying.payer, onPayer, { task: 'chat', ms: end.ms })
                 .catch(() => undefined);
+            if (onShared.length)
+                await this.state
+                    .addSpend(caller.id, 'app', onShared, { task: 'chat' })
+                    .catch(() => undefined);
             if (input.chat)
                 await this.state
                     .addUsage(caller.id, { id: `chat:${input.chat}`, kind: 'chat', title: message.split('\n')[0] || 'Chat' }, end.parts)
@@ -495,6 +533,7 @@ export class Assistant {
         const mainModel = (await this.pick(caller, main)).model;
         // The binding's last test has no token doc to sit in; it is read beside the rest.
         const linkTest = this.o.web?.scrapeql?.fetch ? this.state.scrapeqlLink() : null;
+        const ownWays = await this.ownWaysOf(caller);
         const [p, providers, scrapeql, spend, appCap, ownCap, { paying, wait }] = await Promise.all([
             this.state.person(caller.id),
             Promise.all(this.providers.map(async (id) => {
@@ -520,13 +559,14 @@ export class Assistant {
                         ? { plan: keyState(plan?.doc ?? null, (d) => d.api_key) }
                         : {}),
                     ...(use ? { use } : {}),
+                    ...(ownWays ? { own_ways: ownWays[id] ?? [] } : {}),
                 };
             })),
             this.o.web?.scrapeql ? this.state.scrapeql() : Promise.resolve(null),
             this.state.spend(caller.id),
             this.state.appCap(),
             this.state.ownCap(caller.id),
-            this.state.paying(caller.id, mainModel.provider),
+            this.payingRules(caller).then((r) => this.state.paying(caller.id, mainModel.provider, r)),
         ]);
         const link = await linkTest;
         const tiers = await Promise.all(this.tiers.map(async (t) => {
@@ -925,7 +965,7 @@ 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);
+        const { paying, wait } = await this.state.paying(caller.id, s.model.provider, await this.payingRules(caller, o.payer));
         if (!paying) {
             const code = wait ?? 'not_connected';
             throw new AssistantError(waitText(code, s.model.provider, !!this.o.allowance), code, 402);
@@ -1012,7 +1052,7 @@ export class Assistant {
      */
     async image(caller, o) {
         const began = Date.now();
-        const { paying, wait } = await this.state.paying(caller.id, 'openai');
+        const { paying, wait } = await this.state.paying(caller.id, 'openai', await this.payingRules(caller));
         if (!paying) {
             const code = wait ?? 'not_connected';
             throw new AssistantError(waitText(code, 'openai', !!this.o.allowance), code, 402);

package/dist/assistant/routes.js

@@ -173,6 +173,15 @@ export function assistantRoutes(app, o) {
             return fail(`This app runs no ${asked} models.`, 404);
         const prov = provider ?? 'anthropic';
         const docName = keyDocName(prov);
+        // Adding a way of their own the app does not let this person use (`ownWays`); removing one
+        // always works.
+        const addsOwn = route === 'PUT /my-key'
+            ? 'key'
+            : route === 'POST /my-signin' || route === 'POST /my-signin/finish'
+                ? 'plan'
+                : null;
+        if (addsOwn && !(await a.mayOwn(caller, prov, addsOwn)))
+            return fail("That isn't available on your account.", 403, 'forbidden');
         try {
             switch (route) {
                 case 'GET /status':

package/dist/assistant/state.d.ts

@@ -97,6 +97,17 @@ export interface RequestsDoc {
 export type SpendRow = UsagePart & {
     payer: AssistantPayer;
 };
+/** 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[]>>;
+/** How `paying` may choose: the app's limits on a person's own keys, and one payer only. */
+export interface PayingRules {
+    /** The own ways this person may use (`AssistantOptions.ownWays`); left out, every way. */
+    ways?: OwnWays;
+    /** False: a person who pays with their own key first never moves to the shared key. */
+    fallback?: boolean;
+    /** Only this payer: an app's own check always runs on the shared key (`complete({ payer })`). */
+    only?: AssistantPayer;
+}
 /**
  * One task's use of one model this month: what a kind of work cost (a chat answer, a background
  * task), beside `rows`, which stay per tier and payer.
@@ -219,7 +230,7 @@ export declare class State {
     /** The plan's access token, refreshed first when it is about to run out; null once it fails. */
     planToken(id: string, provider: AssistantProvider): Promise<string | null>;
     /** The person's own key or plan, the one in use first, the other when that one fails. */
-    ownApiKey(id: string, provider: AssistantProvider): Promise<{
+    ownApiKey(id: string, provider: AssistantProvider, ways?: OwnWays): Promise<{
         key: string;
         plan: boolean;
     } | null>;
@@ -253,12 +264,12 @@ export declare class State {
     /** One month's history (this month by default) beside its spend, and the months that have one. */
     usage(id: string, month?: string): Promise<UsageHistory>;
     /** The payer's key of each provider, those set, and which are plan sign-ins. */
-    keysOf(id: string, payer: AssistantPayer): Promise<{
+    keysOf(id: string, payer: AssistantPayer, ways?: OwnWays): Promise<{
         keys: Partial<Record<"anthropic" | "openai" | "xai", string>>;
         plans: Partial<Record<"anthropic" | "openai" | "xai", boolean>>;
     }>;
     /** Who pays the person's next answer on `provider`'s model, or why nobody can. */
-    paying(id: string, provider: AssistantProvider): Promise<{
+    paying(id: string, provider: AssistantProvider, rules?: PayingRules): Promise<{
         paying: Paying | null;
         wait: AssistantWait | null;
     }>;

package/dist/assistant/state.js

@@ -193,7 +193,10 @@ export class State {
         }
     }
     /** The person's own key or plan, the one in use first, the other when that one fails. */
-    async ownApiKey(id, provider) {
+    async ownApiKey(id, provider, ways) {
+        const allowed = ways ? (ways[provider] ?? []) : null;
+        if (allowed && !allowed.length)
+            return null;
         const use = await this.ownUse(id, provider);
         if (!use)
             return null;
@@ -205,7 +208,12 @@ export class State {
             const t = await this.planToken(id, provider);
             return t ? { key: t, plan: true } : null;
         };
-        return use === 'key' ? ((await key()) ?? (await plan())) : ((await plan()) ?? (await key()));
+        const may = (w) => !allowed || allowed.includes(w);
+        const tryKey = async () => (may('key') ? key() : null);
+        const tryPlan = async () => (may('plan') ? plan() : null);
+        return use === 'key'
+            ? ((await tryKey()) ?? (await tryPlan()))
+            : ((await tryPlan()) ?? (await tryKey()));
     }
     /** USD a month on the person's own keys. */
     async ownCap(id) {
@@ -340,11 +348,11 @@ export class State {
         };
     }
     /** The payer's key of each provider, those set, and which are plan sign-ins. */
-    async keysOf(id, payer) {
+    async keysOf(id, payer, ways) {
         const ids = Object.keys(PROVIDERS);
         const found = await Promise.all(ids.map((p) => payer === 'app'
             ? this.appApiKey(p).then((k) => (k ? { key: k.key, plan: false } : null))
-            : this.ownApiKey(id, p)));
+            : this.ownApiKey(id, p, ways)));
         const keys = {};
         const plans = {};
         ids.forEach((p, i) => {
@@ -357,11 +365,11 @@ export class State {
         return { keys, plans };
     }
     /** Who pays the person's next answer on `provider`'s model, or why nobody can. */
-    async paying(id, provider) {
+    async paying(id, provider, rules = {}) {
         const [person, appKeys, ownKeys, spend, ownCap] = await Promise.all([
             this.person(id),
             this.keysOf(id, 'app'),
-            this.keysOf(id, 'own'),
+            this.keysOf(id, 'own', rules.ways),
             this.spend(id),
             this.ownCap(id),
         ]);
@@ -389,8 +397,16 @@ export class State {
                 }
                 : null,
         };
-        const first = person.pay ?? 'app';
-        const order = first === 'own' ? ['own', 'app'] : ['app', 'own'];
+        const first = rules.only ?? person.pay ?? 'app';
+        const order = rules.only
+            ? [rules.only]
+            : first === 'own'
+                ? rules.fallback === false && sources.own
+                    ? ['own']
+                    : ['own', 'app']
+                : ['app', 'own'];
+        if (rules.only)
+            sources[rules.only === 'app' ? 'own' : 'app'] = null;
         for (const p of order) {
             const s = sources[p];
             if (s && s.left > 0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@columenlabs/lumen-ai",
-  "version": "0.1.230",
+  "version": "0.1.231",
   "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.230",
-    "@columenlabs/lumen-ui-types": "0.1.230",
+    "@columenlabs/lumen-ops": "0.1.231",
+    "@columenlabs/lumen-ui-types": "0.1.231",
     "agents": "0.32.0",
     "ai": "7.0.162",
     "just-bash": "3.6.0",