@columenlabs/lumen-ai 0.1.77 → 0.1.79

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,9 +94,50 @@ 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.
-- **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`.
+- **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, Read + draft or Read + write per person. A tool is a read when its MCP `readOnlyHint` is set. On Read + draft a write only drafts a card, and runs as the person when they press Save, after access is checked again. Read + write is offered only for a group with `writes: true`: its writes run at once, and with `undo` set each one's line in the chat has Undo, which calls `undo(caller, { tool, args, result })` (`POST /chats/:id/writes/:step/undo`); the model is told what was undone. Cards drafted one after another show as one stack with Save all. 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.
 - **Chats** stream as server-sent events (`POST /chat`); closing the request stops the answer and keeps what was said. Past 150k tokens, or on `/compact`, the history sent to the model becomes a summary. Run `assistant.purge()` once a day to drop chats 30 days after their last message.
+
+### Commands, `@` and `#`
+
+The panel's composer lists what can follow three keys as they are typed. The kit's own entries are on for every app; an app only adds its own.
+
+- **`/` commands.** Built in: `/compact` (summarise the chat), `/clear` (a new chat), `/model <tier>` (answer on another tier from now on) and `/escalate <task>` (hand one task to the next tier up). An app adds its own on the server with `commands`: the chat shows what the person typed and the model gets `prompt`, with `{args}` replaced by the words after the name (or what the function returns). An app's command wins a built-in's name.
+
+  ```ts
+  createAssistant({
+    // ...
+    commands: [
+      { name: 'story', about: 'Find stories for a question', args: '<question>',
+        prompt: 'Search my stories for: {args}. List the best three with why each fits.' },
+      { name: 'prep', about: 'Prep for an interview', args: '<company>',
+        prompt: async (company, caller) => prepPrompt(caller.id, company) },
+    ],
+  });
+  ```
+
+  A command that acts in the browser (opens a page, sets a filter) goes on the panel instead: `LumenAssistant` (or `useLumenAssistantDock`) takes `commands`, each `{ name, about, args?, options?, run }`; `run` returns text to send, or nothing when it acted itself, and `options` lists choices for its words as they are typed.
+- **`@` a tier.** `@` lists the app's tiers; the pick is a chip and goes with that message only (`tier`). A higher tier takes it as a task in its own section of the chat; the same or a lower one answers it.
+- **`#` a thing.** `#` lists what the person can point at, a group per source; each pick is a chip and goes with the message as a ref (`kind`, `label` and whatever finds it), which the model reads before the message. Standing sources go on the panel (`sources`); a page adds its own while it is shown:
+
+  ```tsx
+  import { useAssistantSource } from '@columenlabs/lumen-ui/assistant';
+
+  useAssistantSource({
+    id: 'page',
+    label: 'On this page',
+    items: (q) =>
+      rows
+        .filter((r) => r.title.toLowerCase().includes(q.toLowerCase()))
+        .map((r) => ({ id: r.id, label: r.title, target: `card:${r.id}`, ref: { kind: 'story', label: r.title, id: r.id } })),
+  });
+  ```
+
+  `target` lights the thing on screen while its row is hovered. A page's source replaces a standing one with the same `id`.
+
+  Text the person highlights on the page is offered first under `#` (Selected text), with where it sits from the nearest `data-assistant-where` attribute. To hand a highlight over from the page, an Ask button calls `composeAssistant({ refs: [selectionRef({ text, where })], text: '' })` (or any refs and text): the panel opens with the chips in the composer, focused for the person to finish.

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,21 +1,47 @@
-import type { AssistantAccess, AssistantChat, AssistantChatRow, AssistantMessage, AssistantStatus, DraftItem } from '@columenlabs/lumen-ui-types/assistant';
+import type { 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';
 import { type ToolSource } from './tools.js';
 import { type AccessToken, type WebFetchOptions } from './web.js';
+/** An app's slash command (`/story <words>`). */
+export interface AssistantCommandDef {
+    /** Typed after the slash, letters, digits and `-`: `story`. */
+    name: string;
+    /** One line in the list. */
+    about: string;
+    /** What follows the name, shown in the list (`<words>`). Without it, picking it sends it. */
+    args?: string;
+    /** What the model is asked: `{args}` is the words after the name. */
+    prompt: string | ((args: string, caller: Caller) => string | Promise<string>);
+}
 /** Who is asking: their id (the store's scope for their things) and whether they are an admin. */
 export interface Caller {
     id: string;
     admin: boolean;
 }
-/** A group of the app's tools the person sets Off, Read or Read + draft. */
+/** A change a write tool made at once, as `undo` gets it. */
+export interface AssistantWrite {
+    /** The tool's own name (not the `group__tool` the model calls). */
+    tool: string;
+    args: unknown;
+    /** What the tool returned. */
+    result: unknown;
+}
+/** A group of the app's tools the person sets Off, Read, Read + draft or Read + write. */
 export interface ToolGroup {
     id: string;
     label: string;
     about: string;
     /** Where a person starts: `read` by default. */
     access?: AssistantAccess;
+    /**
+     * Offers Read + write: its write tools then run at once, without a card, each with Undo in the
+     * chat when `undo` is set. Off by default, so a group only drafts.
+     */
+    writes?: boolean;
+    /** Takes back one change a write made at once (Undo on its line in the chat). */
+    undo?: (caller: Caller, write: AssistantWrite) => Promise<void>;
     tools: (caller: Caller) => ToolSource | ToolSource[];
 }
 /** What one step or answer was, for the app's meter: shapes only, never content. */
@@ -52,11 +78,17 @@ export interface AssistantOptions {
     name: string;
     /** The app's instructions: what it is, what its tools are for. */
     system: string | ((caller: Caller) => string | Promise<string>);
+    /**
+     * The app's slash commands, listed in the composer when the person types `/`. A message
+     * `/name words` is sent to the model as `prompt` with `{args}` replaced by the words (or what the
+     * function returns); the chat shows what the person typed.
+     */
+    commands?: AssistantCommandDef[];
     /** The app's tiers, smallest first. */
     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 +101,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 +129,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;
@@ -107,6 +143,7 @@ export declare class Assistant {
     /** The tier the person's chat runs on: their pick, else the chat task's start tier. */
     private mainTier;
     private access;
+    private groupById;
     status(caller: Caller): Promise<AssistantStatus>;
     listChats(caller: Caller): Promise<AssistantChatRow[]>;
     readChat(caller: Caller, id: string): Promise<AssistantChat | null>;
@@ -125,6 +162,8 @@ export declare class Assistant {
     /** The advisor for this answer, or null when off. Never weaker than the model it advises. */
     private advisorFor;
     private escalateTool;
+    /** What the model is asked: an app command's prompt, else the message as typed. */
+    private expand;
     /** The tiers the person's message asks for by name ("go deeper" is the next one up). */
     private askedFor;
     private handOff;
@@ -132,14 +171,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;
@@ -152,6 +204,8 @@ export declare class Assistant {
     }>;
     /** Saves (runs, as the person) or dismisses a drafted card. Access is checked again first. */
     settleDraft(caller: Caller, chatId: string, draftId: string, action: 'save' | 'dismiss'): Promise<DraftItem>;
+    /** Takes back one change a write made at once, through its group's `undo`. */
+    undoWrite(caller: Caller, chatId: string, stepId: string): Promise<StepItem>;
 }
 export declare function createAssistant(o: AssistantOptions): Assistant;
 export {};