@columenlabs/lumen-ai 0.1.76 → 0.1.78

package/README.md

@@ -57,7 +57,7 @@ Every merge to `main` publishes the next patch of every Lumen package at once.
 
 ## A chat assistant
 
-`@columenlabs/lumen-ai/assistant` is the server behind a chat side panel: Claude on the app's own tiers, the app's tools from any MCP server, the web, drafts the person saves, hand off to a higher tier, advice, and a monthly spend cap per person. The panel and Settings sections are `@columenlabs/lumen-ui`'s; the shared types are `@columenlabs/lumen-ui-types/assistant`.
+`@columenlabs/lumen-ai/assistant` is the server behind a chat side panel: Claude or OpenAI models on the app's own tiers, the app's tools from any MCP server, the web, drafts the person saves, hand off to a higher tier, advice, and a monthly spend cap per person. The panel and Settings sections are `@columenlabs/lumen-ui`'s; the shared types are `@columenlabs/lumen-ui-types/assistant`.
 
 ```ts
 import {
@@ -83,7 +83,8 @@ const assistant = createAssistant({
   web: { fetch: { blockHosts: ['app.example.com'] }, scrapeql: { url: 'https://scrapeql.example.com/mcp' } },
   store: sqlAssistantStore(doSql(ctx.storage.sql)), // or d1Sql(env.DB)
   sealer, // the app's own sealing: keys and chats are stored sealed
-  appKey: async () => env.ANTHROPIC_API_KEY, // when no key is set in Settings
+  // A provider's key when none is set in Settings.
+  appKey: async (provider) => (provider === 'openai' ? env.OPENAI_API_KEY : env.ANTHROPIC_API_KEY),
 });
 
 const routes = assistantRoutes(assistant, {
@@ -93,8 +94,10 @@ const routes = assistantRoutes(assistant, {
 app.all('/api/assistant/*', (c) => routes(c.req.raw));
 ```
 
-- **Keys.** An admin pastes the app's Claude key (`PUT /key`); it is tested with one free call before it is kept, then sealed, and no route returns it. A person may add their own (`PUT /my-key`) with its own monthly cap.
-- **Who pays.** The person's pick (the app's key by default) while it has money left this month under its cap (an admin sets the app key's cap per person, `PUT /app`), else the other; with neither the panel says why.
+- **Providers.** A tier runs any model in `models` (Claude's and OpenAI's by default, `CLAUDE_MODELS`, `OPENAI_MODELS`): Claude through Anthropic's Messages API, OpenAI through the Responses API, with the same tools, drafts, Stop and caps. A hand-off may cross providers. The advisor and prompt caching marks are Claude's only.
+- **Keys.** Each provider has its own keys (`?provider=anthropic|openai` on the key routes). An admin pastes the shared key everyone uses (`PUT /key`); it is tested with one free call before it is kept, then sealed, and no route returns it. A person may add their own (`PUT /my-key`), with one monthly cap on their own keys (`PUT /my-key/cap`).
+- **ChatGPT sign-in.** In place of their own OpenAI key a person may sign in with their ChatGPT plan (`POST /my-signin`, then `POST /my-signin/finish {url}`): the sign-in opens in a new tab and ends on `http://127.0.0.1:1455/auth/callback`, a page that does not load, whose address the person pastes back. The tokens are sealed as their own key and refreshed before they run out; answers on the plan count tokens and no dollars.
+- **Who pays.** The person's pick (the shared keys by default) while it has a key for the tier's provider and money left this month under its cap (an admin sets the shared keys' cap per person, `PUT /app`), else the other; with neither the panel says why.
 - **Tools.** Each group is Off, Read or Read + draft per person. A tool is a read when its MCP `readOnlyHint` is set; a write only drafts a card, and runs as the person when they press Save, after access is checked again. Use `mcpServerTools` (an SDK `McpServer`), `mcpFetchTools` (a server served as a fetch handler, any SDK), `remoteMcpTools` or `plainTools`.
 - **Web.** `fetch` is a plain GET from the Worker (10 s, 2 MB, never the app's own hosts or private addresses). ScrapeQL's own tools join over its MCP API once an admin pastes a Cloudflare Access service token (`PUT /web/scrapeql`).
 - **Hand off and advice.** The `escalate` tool hands one task to a higher tier (the person sets next, any or only when asked); Anthropic's advisor tool lets a higher tier send a plan, at most two an answer.

package/dist/assistant/chatgpt.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Sign in with ChatGPT: a person runs OpenAI models on their own ChatGPT plan instead of an API key
+ * (OpenAI's "token sharing" flow, developers.openai.com/siwc). The sign-in opens in a new tab and
+ * ends on a 127.0.0.1 address that loads nothing, since the app is not on the person's machine; the
+ * person pastes that address back and the server finishes it. PKCE, a fresh state and nonce each
+ * time, no client secret. The first sign-in registers the app (`dynamic_agent_client`) and OpenAI
+ * issues a client id kept for later sign-ins.
+ */
+export declare const CHATGPT_RESOURCE = "https://api.openai.com/v1";
+/** Only the port may change between sign-ins; `localhost` is refused. */
+export declare const CHATGPT_REDIRECT = "http://127.0.0.1:1455/auth/callback";
+/** The app's registration with OpenAI for one person, kept across sign-outs. */
+export interface ChatgptRegistration {
+    /** An opaque id of this app for this person, the same on every sign-in. */
+    host_id: string;
+    /** The client id OpenAI issued on the first sign-in. */
+    client_id?: string;
+    /** A sign-in started and not yet finished. */
+    pending?: {
+        state: string;
+        nonce: string;
+        verifier: string;
+        at: number;
+    };
+}
+/** A finished sign-in: kept sealed as the person's own OpenAI key. */
+export interface ChatgptTokens {
+    client_id: string;
+    access_token: string;
+    refresh_token: string;
+    /** ms */
+    expires_at: number;
+    scope: string;
+    email?: string;
+}
+export declare class SigninError extends Error {
+}
+/** The sign-in address to open, and the registration with its new pending sign-in. */
+export declare function startChatgpt(reg: ChatgptRegistration | null, appName: string): Promise<{
+    url: string;
+    reg: ChatgptRegistration;
+}>;
+/**
+ * Finishes a sign-in from the address it ended on: checks the state, trades the code for tokens and
+ * checks they may run models on the plan. The ID token comes straight from OpenAI's token endpoint
+ * over TLS, so its nonce and audience are checked and its signature is not (OIDC Core 3.1.3.7).
+ */
+export declare function finishChatgpt(reg: ChatgptRegistration | null, pasted: string, fetchFn: typeof fetch): Promise<{
+    tokens: ChatgptTokens;
+    reg: ChatgptRegistration;
+}>;
+/** Whether the access token needs a refresh before the next call. */
+export declare const staleChatgpt: (t: ChatgptTokens) => boolean;
+/** A new access token and the rotated refresh token that replaces the old one. */
+export declare function refreshChatgpt(t: ChatgptTokens, fetchFn: typeof fetch): Promise<ChatgptTokens>;
+/** One free read (the account's models) that says whether the plan sign-in still works. */
+export declare function testChatgpt(t: ChatgptTokens, fetchFn: typeof fetch): Promise<{
+    ok: boolean;
+    detail: string;
+    at: number;
+}>;

package/dist/assistant/chatgpt.js

@@ -0,0 +1,165 @@
+/**
+ * Sign in with ChatGPT: a person runs OpenAI models on their own ChatGPT plan instead of an API key
+ * (OpenAI's "token sharing" flow, developers.openai.com/siwc). The sign-in opens in a new tab and
+ * ends on a 127.0.0.1 address that loads nothing, since the app is not on the person's machine; the
+ * person pastes that address back and the server finishes it. PKCE, a fresh state and nonce each
+ * time, no client secret. The first sign-in registers the app (`dynamic_agent_client`) and OpenAI
+ * issues a client id kept for later sign-ins.
+ */
+const AUTH = 'https://auth.openai.com/api/accounts';
+export const CHATGPT_RESOURCE = 'https://api.openai.com/v1';
+/** Only the port may change between sign-ins; `localhost` is refused. */
+export const CHATGPT_REDIRECT = 'http://127.0.0.1:1455/auth/callback';
+const SCOPE = 'openid profile email offline_access resource.invoke chatgpt.tokens.use.direct';
+/** The scope that lets the tokens run models on the plan. */
+const PLAN_SCOPE = 'chatgpt.tokens.use.direct';
+/** Refresh this long before the access token runs out. */
+const EARLY_MS = 5 * 60_000;
+/** A started sign-in is finished within this. */
+const PENDING_MS = 15 * 60_000;
+const b64url = (bytes) => btoa(String.fromCharCode(...new Uint8Array(bytes)))
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+const random = (n = 32) => b64url(crypto.getRandomValues(new Uint8Array(n)));
+export class SigninError extends Error {
+}
+/** The sign-in address to open, and the registration with its new pending sign-in. */
+export async function startChatgpt(reg, appName) {
+    const pending = { state: random(), nonce: random(), verifier: random(48), at: Date.now() };
+    const challenge = b64url(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(pending.verifier)));
+    const next = { host_id: reg?.host_id ?? random(18), ...reg, pending };
+    const q = new URLSearchParams({
+        client_id: next.client_id ?? 'dynamic_agent_client',
+        ...(next.client_id ? {} : { agent_name_hint: appName }),
+        ext_agent_host_id: next.host_id,
+        response_type: 'code',
+        redirect_uri: CHATGPT_REDIRECT,
+        scope: SCOPE,
+        resource: CHATGPT_RESOURCE,
+        state: pending.state,
+        nonce: pending.nonce,
+        code_challenge_method: 'S256',
+        code_challenge: challenge,
+    });
+    return { url: `${AUTH}/authorize?${q}`, reg: next };
+}
+function claims(idToken) {
+    try {
+        const part = idToken.split('.')[1] ?? '';
+        const pad = part.replace(/-/g, '+').replace(/_/g, '/');
+        return JSON.parse(atob(pad + '='.repeat((4 - (pad.length % 4)) % 4)));
+    }
+    catch {
+        return {};
+    }
+}
+async function token(fetchFn, form) {
+    const res = await fetchFn(`${AUTH}/oauth/token`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams(form),
+    });
+    const b = (await res.json().catch(() => ({})));
+    if (!res.ok || typeof b.access_token !== 'string' || typeof b.refresh_token !== 'string') {
+        const code = typeof b.error === 'string' ? b.error : `HTTP ${res.status}`;
+        throw new SigninError(code === 'invalid_grant'
+            ? 'That sign-in has expired or was used already: sign in again.'
+            : `OpenAI refused the sign-in (${code}).`);
+    }
+    return {
+        access_token: b.access_token,
+        refresh_token: b.refresh_token,
+        expires_at: Date.now() + (typeof b.expires_in === 'number' ? b.expires_in : 3600) * 1000,
+        scope: typeof b.scope === 'string' ? b.scope : '',
+        id_token: typeof b.id_token === 'string' ? b.id_token : '',
+    };
+}
+/**
+ * Finishes a sign-in from the address it ended on: checks the state, trades the code for tokens and
+ * checks they may run models on the plan. The ID token comes straight from OpenAI's token endpoint
+ * over TLS, so its nonce and audience are checked and its signature is not (OIDC Core 3.1.3.7).
+ */
+export async function finishChatgpt(reg, pasted, fetchFn) {
+    const pending = reg?.pending;
+    if (!reg || !pending || Date.now() - pending.at > PENDING_MS)
+        throw new SigninError('Start the sign-in again: this one is too old.');
+    let q;
+    try {
+        q = new URL(pasted.trim()).searchParams;
+    }
+    catch {
+        throw new SigninError('Paste the whole address from the tab the sign-in ended on.');
+    }
+    if (q.get('state') !== pending.state)
+        throw new SigninError('That address is from another sign-in: start again.');
+    if (q.get('error') === 'access_denied')
+        throw new SigninError('ChatGPT said no: plan use may be off for this account.');
+    if (q.get('error'))
+        throw new SigninError(`ChatGPT stopped the sign-in (${q.get('error')}).`);
+    const code = q.get('code');
+    if (!code)
+        throw new SigninError('That address has no sign-in code.');
+    const returned = q.get('client_id');
+    if (reg.client_id && returned && returned !== reg.client_id)
+        throw new SigninError('That sign-in belongs to another registration: start again.');
+    const clientId = reg.client_id ?? returned;
+    if (!clientId)
+        throw new SigninError('OpenAI sent no client id: start again.');
+    const t = await token(fetchFn, {
+        grant_type: 'authorization_code',
+        client_id: clientId,
+        code,
+        code_verifier: pending.verifier,
+        redirect_uri: CHATGPT_REDIRECT,
+        resource: CHATGPT_RESOURCE,
+    });
+    const c = claims(t.id_token);
+    const aud = Array.isArray(c.aud) ? c.aud : [c.aud];
+    if (c.nonce !== pending.nonce || !aud.includes(clientId))
+        throw new SigninError('The sign-in did not match: start again.');
+    if (!t.scope.split(' ').includes(PLAN_SCOPE))
+        throw new SigninError('This ChatGPT account may not run models on its plan.');
+    const { pending: _, ...kept } = reg;
+    return {
+        reg: { ...kept, client_id: clientId },
+        tokens: {
+            client_id: clientId,
+            access_token: t.access_token,
+            refresh_token: t.refresh_token,
+            expires_at: t.expires_at,
+            scope: t.scope,
+            ...(typeof c.email === 'string' ? { email: c.email } : {}),
+        },
+    };
+}
+/** Whether the access token needs a refresh before the next call. */
+export const staleChatgpt = (t) => t.expires_at - EARLY_MS < Date.now();
+/** A new access token and the rotated refresh token that replaces the old one. */
+export async function refreshChatgpt(t, fetchFn) {
+    const n = await token(fetchFn, {
+        grant_type: 'refresh_token',
+        client_id: t.client_id,
+        refresh_token: t.refresh_token,
+        resource: CHATGPT_RESOURCE,
+    });
+    return {
+        ...t,
+        access_token: n.access_token,
+        refresh_token: n.refresh_token,
+        expires_at: n.expires_at,
+        ...(n.scope ? { scope: n.scope } : {}),
+    };
+}
+/** One free read (the account's models) that says whether the plan sign-in still works. */
+export async function testChatgpt(t, fetchFn) {
+    const at = Date.now();
+    const res = await fetchFn(`${CHATGPT_RESOURCE}/models`, {
+        headers: { authorization: `Bearer ${t.access_token}` },
+    }).catch(() => null);
+    if (!res)
+        return { ok: false, detail: 'OpenAI could not be reached.', at };
+    if (!res.ok)
+        return { ok: false, detail: `OpenAI refused the sign-in (HTTP ${res.status}).`, at };
+    return { ok: true, detail: 'ChatGPT plan sign-in works.', at };
+}

package/dist/assistant/engine.d.ts

@@ -1,4 +1,4 @@
-import type { AssistantAccess, AssistantChat, AssistantChatRow, AssistantMessage, AssistantStatus, DraftItem } from '@columenlabs/lumen-ui-types/assistant';
+import type { AssistantAccess, AssistantChat, AssistantChatRow, AssistantMessage, AssistantProvider, AssistantStatus, DraftItem } 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';
@@ -56,7 +56,7 @@ export interface AssistantOptions {
     tiers: TierDef[];
     /** Tasks a person picks a starting tier for; the chat on the smallest tier by default. */
     tasks?: TaskDef[];
-    /** Models a tier may run; Claude's by default. */
+    /** Models a tier may run; every model the kit knows (Claude's and OpenAI's) by default. */
     models?: ModelDef[];
     groups?: ToolGroup[];
     web?: {
@@ -69,15 +69,15 @@ export interface AssistantOptions {
     };
     store: AssistantStore;
     sealer?: Sealer;
-    /** The app's key when none is stored in Settings (a Worker secret). */
-    appKey?: () => Promise<string | null | undefined>;
+    /** 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. */
     defaultCap?: number;
     /** Months and dates in this zone; UTC by default. */
     timeZone?: string;
     /** Chats are deleted this many days after their last message (`purge`); 30. */
     keepDays?: number;
-    /** The fetch Anthropic and ScrapeQL calls go through. */
+    /** The fetch the model providers and ScrapeQL calls go through. */
     fetch?: typeof fetch;
     onStep?: (s: StepRecord) => void | Promise<void>;
 }
@@ -97,7 +97,11 @@ export declare class Assistant {
     readonly state: State;
     private readonly groups;
     constructor(o: AssistantOptions);
-    private client;
+    private anthropic;
+    private openai;
+    private clients;
+    /** The providers the app's models run on, in the order the models list them. */
+    get providers(): AssistantProvider[];
     private tierById;
     private above;
     private modelById;
@@ -132,14 +136,27 @@ export declare class Assistant {
     private runTool;
     /** Model calls and tool rounds until the model answers; returns its words. */
     private loop;
+    /** The loop on OpenAI's Responses API: the same tools, Stop, caps and rounds as Claude's. */
+    private loopOpenAI;
+    /** The loop on Anthropic's Messages API, with the advisor and prompt caching. */
+    private loopClaude;
     /** Swaps the history for a short summary. False with nothing to compact. */
     private compact;
     /** How the person's cards ended since the last answer, once each. */
     private cardNews;
     /** The answer as later turns remember it: with what its tools returned, cut. */
     private remember;
-    /** One free call (reading a model) that says whether Claude takes the key. */
-    testKey(apiKey: string): Promise<{
+    /** Starts a person's ChatGPT plan sign-in: the address to open in a new tab. */
+    startSignin(caller: Caller, provider: AssistantProvider): Promise<{
+        url: string;
+        redirect: string;
+    }>;
+    /** Finishes it from the address it ended on; the plan then stands in for the person's own key. */
+    finishSignin(caller: Caller, provider: AssistantProvider, pasted: string): Promise<void>;
+    /** Tests a person's own key, refreshing a plan sign-in first. */
+    testOwn(caller: Caller, provider: AssistantProvider): Promise<import("./state.js").KeyTest | null>;
+    /** One free call (reading a model) that says whether the provider takes the key. */
+    testKey(provider: AssistantProvider, apiKey: string): Promise<{
         ok: boolean;
         detail: string;
         at: number;