@byokit/openclaw 0.11.0 → 0.12.0

package/dist/testing/fake-gateway.d.ts

@@ -20,6 +20,24 @@ export type FakeGateway = {
     failNext(method: string, message: string): void;
     drop(why: string): void;
     handle(method: string, fn: FakeHandler): void;
+    /** Usage windows a later `models.authStatus` read reports for the agent's provider (O14: the Auto input). */
+    setUsage(agentId: string, provider: string, windows: {
+        label: string;
+        usedPercent?: number;
+        resetAt?: number;
+    }[]): void;
+    /** Profile fields every later wizard sign-in stores (O14 identity): `accountId: undefined` signs in with no account
+     * id, so no `who`. With no call, or `signInAs()`, the account id is `fake-<agentId>`. */
+    signInAs(fields?: {
+        accountId?: string;
+        email?: string;
+        expires?: number;
+    }): void;
+    /** A sealed profile already in an agent's store, as a sign-in of another provider leaves it; the agent's model points at it. */
+    seedProfile(agentId: string, profileId: string, profile: {
+        provider: string;
+        type: string;
+    } & Record<string, unknown>): void;
 } & {
     transport: GatewayTransport;
 };

package/dist/testing/fake-gateway.js

@@ -14,6 +14,13 @@ const DEVICE_STEP = {
     deviceCode: { code: 'CREW-2026', expiresInMinutes: 15 }, externalUrl: 'https://auth.openai.com/codex/device',
 };
 const PROGRESS_STEP = { id: 'step-wait', type: 'progress', message: 'Waiting for authorization', executor: 'gateway' };
+// ChatGPT's browser route: the pin hands its unsigned authorize URL to the next step as `externalUrl`.
+const BROWSER_STEP = {
+    id: 'step-browser', type: 'note', executor: 'client', message: 'Open this URL in your LOCAL browser.',
+    externalUrl: 'https://auth.openai.com/oauth/authorize?response_type=code&client_id=fake-client&redirect_uri=http%3A%2F%2Flocalhost%3A1455%2Fauth%2Fcallback&state=fake-state',
+};
+// The pin's agents.create into an existing workspace rewrites IDENTITY.md's Name line (mergeIdentityMarkdownContent).
+const IDENTITY_NAME = /^- \*\*Name:\*\*.*$/m;
 const EVENTS = [
     'agent',
     'exec.approval.requested', 'exec.approval.resolved',
@@ -110,7 +117,47 @@ export function fakeGateway(script, o) {
     const orders = new Map();
     const models = new Map();
     const wizards = new Map();
+    let signInFields;
+    // Each workspace's files by name, as `agents.files.get/set` and the create-time IDENTITY.md rewrite see them.
+    const workspaces = new Map();
+    const filesOf = (agentId) => {
+        const agent = agents.get(agentId);
+        if (!agent)
+            throw new Error(`unknown agent id "${agentId}"`);
+        const workspace = agent.workspace ?? `workspace-${agentId}`;
+        let files = workspaces.get(workspace);
+        if (!files) {
+            files = new Map();
+            workspaces.set(workspace, files);
+        }
+        return { workspace, files };
+    };
+    const fileAnswer = (agentId, name) => {
+        const { workspace, files } = filesOf(agentId);
+        const content = files.get(name);
+        return { agentId, workspace, file: { name, path: join(workspace, name), missing: content === undefined,
+                ...(content === undefined ? {} : { size: Buffer.byteLength(content), content }) } };
+    };
     const runs = new Map();
+    const sessions = new Map();
+    const sessionOf = (agentId, key) => {
+        let session = sessions.get(`${agentId}\n${key}`);
+        if (!session) {
+            session = { sessionId: randomUUID(), updatedAt: 0, rows: [] };
+            sessions.set(`${agentId}\n${key}`, session);
+        }
+        return session;
+    };
+    const append = (session, row) => {
+        session.rows.push(row);
+        session.updatedAt = Math.max(Date.now(), session.updatedAt + 1);
+    };
+    const activeOn = (agentId, key) => [...runs.values()].some((run) => !run.result && run.agentId === agentId && run.sessionKey === key);
+    // The engine's own cached read of each provider's usage endpoint (O14): cold until a `models.authStatus`
+    // answer has carried the provider once (no `usage` on that first answer), then whatever `setUsage` stored.
+    // A pre-sign-in read names no provider, so it warms nothing: the journey's first room read stays cold.
+    const usage = new Map();
+    const warmed = new Set();
     const configBox = { hash: 'hash-1', config: {} };
     let hashSeq = 1;
     const ensureAgent = (id, workspace) => {
@@ -238,10 +285,14 @@ export function fakeGateway(script, o) {
         if (params.agentId != null && !agents.has(String(params.agentId)))
             throw new Error(`unknown agent: ${params.agentId}`);
         // Like the engine: the provider/model the run is called on, its own override or the member's (here openai).
-        const run = { runId: randomUUID(), sessionKey: String(params.sessionKey ?? ''), seq: 0,
+        const run = { runId: randomUUID(), agentId: String(params.agentId ?? 'main'), sessionKey: String(params.sessionKey ?? ''), seq: 0,
             provider: String(params.provider ?? 'openai'), model: String(params.model ?? 'gpt-5.1'), waiters: [] };
         runs.set(run.runId, run);
+        const session = sessionOf(run.agentId, run.sessionKey);
+        session.provider = run.provider;
+        session.model = run.model;
         const message = String(params.message ?? '');
+        append(session, { role: 'user', content: [{ type: 'text', text: message }] });
         const text = `fake: ${message}`;
         setTimeout(() => {
             void (async () => {
@@ -272,8 +323,11 @@ export function fakeGateway(script, o) {
                     // Completion rides `phase: 'result'` like the real engine (O11), not `'end'`, with its result.
                     emitRun(run, 'tool', { phase: 'result', name: call.name, toolCallId, isError,
                         result: { content: [{ type: 'text', text: output }] } });
+                    append(session, { role: 'assistant', content: [{ type: 'toolCall', id: toolCallId, name: call.name, arguments: call.input }] });
+                    append(session, { role: 'toolResult', toolCallId, toolName: call.name, isError, content: [{ type: 'text', text: output }] });
                 }
                 emitRun(run, 'assistant', { text });
+                append(session, { role: 'assistant', content: [{ type: 'text', text }] });
                 // The engine sums the run's usage (zero buckets omitted); the fake counts characters.
                 run.usage = { input: message.length, output: text.length, total: message.length + text.length };
                 setTimeout(() => finish(run, { status: 'ok', terminalReply: { text } }), ABORT_WINDOW_MS);
@@ -304,16 +358,41 @@ export function fakeGateway(script, o) {
         }),
         'agents.create': (p) => {
             const id = String(p.name);
+            if (agents.has(id))
+                throw new Error(`agent "${id}" already exists`);
             const workspace = p.workspace ? String(p.workspace) : undefined;
+            if (workspace) {
+                const files = workspaces.get(workspace) ?? new Map();
+                workspaces.set(workspace, files);
+                const identity = files.get('IDENTITY.md') ?? '# IDENTITY.md - Agent Identity\n\n';
+                files.set('IDENTITY.md', IDENTITY_NAME.test(identity) ? identity.replace(IDENTITY_NAME, `- **Name:** ${id}`) : `${identity}- **Name:** ${id}\n`);
+            }
             // With rosterApplyMs the fake mirrors the pinned engine: create answers before the roster hot-reload
             // makes the agent visible to agents.list (Crewhouse saw ~113 ms).
             if (o?.rosterApplyMs)
                 setTimeout(() => ensureAgent(id, workspace), o.rosterApplyMs);
             else
                 ensureAgent(id, workspace);
-            return { id };
+            return { ok: true, agentId: id, name: id, workspace: workspace ?? `workspace-${id}` };
+        },
+        // deleteFiles: false keeps the workspace, as the kit always asks; the agent's own store and model go.
+        'agents.delete': (p) => {
+            const id = String(p.agentId);
+            if (!agents.delete(id))
+                throw new Error(`agent "${id}" not found`);
+            profiles.delete(id);
+            orders.delete(id);
+            models.delete(id);
+            return { ok: true, agentId: id, removedBindings: 0 };
+        },
+        'agents.files.get': (p) => fileAnswer(String(p.agentId), String(p.name)),
+        'agents.files.set': (p) => {
+            filesOf(String(p.agentId)).files.set(String(p.name), String(p.content));
+            return { ok: true, ...fileAnswer(String(p.agentId), String(p.name)) };
         },
         // One profile per signed-in provider, `<provider>:default`, as the pin lists an agent's own profiles.
+        // Plus its cached usage once warm: cold on the first answer carrying the provider (no `usage`), then the
+        // stored windows.
         'models.authStatus': (p) => {
             const id = String(p?.agentId ?? 'main');
             const store = storeOf(id);
@@ -322,12 +401,26 @@ export function fakeGateway(script, o) {
                 providers: (agents.get(id)?.providers ?? []).map((provider) => {
                     const profileId = `${provider}:default`;
                     const credential = store[profileId];
+                    const key = `${id}\n${provider}`;
+                    const cold = !warmed.has(key);
+                    warmed.add(key);
+                    const windows = cold ? undefined : usage.get(id)?.get(provider);
                     return { provider,
                         profiles: [{ profileId, type: credential?.type ?? 'oauth',
-                                status: credential ? statusOf(credential, now) : 'ok' }] };
+                                status: credential ? statusOf(credential, now) : 'ok' }],
+                        ...(windows !== undefined ? { usage: { windows } } : {}) };
                 }),
             };
         },
+        // The runtime-allowed catalog for the agent's signed-in providers (O14): one available row each. A test
+        // scripting exact availability scripts this method with `handle`.
+        'models.list': (p) => {
+            const id = String(p?.agentId ?? 'main');
+            return {
+                models: (agents.get(id)?.providers ?? []).map((provider) => ({ id: `${provider}/default`,
+                    name: 'Default', provider, available: true })),
+            };
+        },
         'models.authLogout': (p) => {
             const agent = agents.get(String(p?.agentId ?? 'main'));
             // The pin refuses a profileIds list naming a profile the agent does not hold.
@@ -353,20 +446,27 @@ export function fakeGateway(script, o) {
         },
         'byokit.keys': (p) => {
             const id = `byokit-key-${p.member}`;
-            if (p.action === 'prepare') {
+            if (p.action === 'prepare' || p.action === 'clear') {
                 keys.delete(id);
                 ensureAgent(id).providers = [];
                 return { ok: true };
             }
             const key = keys.get(id);
             if (!key)
-                return { ok: false };
+                return { ok: false, absent: true };
             if (p.action === 'seal') {
                 key.sealed = true;
+                if (typeof p.model === 'string')
+                    key.model = p.model;
                 return { ok: true };
             }
-            return { ok: key.sealed, ...(key.sealed ? { model: key.model } : {}) };
+            return key.sealed ? { ok: true, model: key.model } : { ok: false, absent: true };
         },
+        // The provider's live catalog hook (5.6): every live model with its own api, once an agent holds the provider's key.
+        'byokit.catalog': (p) => ([...keys.values()].some((key) => key.provider === p.provider) ? { ok: true, models: [
+                { id: 'fake-key-model', name: 'Fake Key Model', api: 'openai-completions' },
+                { id: 'fake-live-model', name: 'Fake Live Model', api: 'openai-responses' }
+            ] } : { ok: false, reason: 'no-key' }),
         // Account sealing (5.15): the same five actions, branches and refusals the shipped plugin method serves.
         'byokit.accounts': (p) => {
             const action = String(p.action ?? '');
@@ -414,11 +514,21 @@ export function fakeGateway(script, o) {
                 return { ok: true, profiles: Object.entries(store).map(([profileId, credential]) => ({ provider: credential.provider,
                         profileId, type: credential.type, status: statusOf(credential, Date.now()), ...(whoOf(credential) ? { who: whoOf(credential) } : {}) })) };
             if (action === 'clear') {
-                profiles.set(id, {});
-                orders.set(id, {});
+                // Mirrors the plugin: a provider scope drops only that provider's profiles, order and lastGood.
+                const scope = typeof p.provider === 'string' && p.provider ? String(p.provider) : undefined;
+                if (!scope) {
+                    profiles.set(id, {});
+                    orders.set(id, {});
+                }
+                else {
+                    for (const [profileId, credential] of Object.entries(store))
+                        if (credential.provider === scope)
+                            delete store[profileId];
+                    delete order[scope];
+                }
                 const cleared = agents.get(id);
                 if (cleared)
-                    cleared.providers = [];
+                    cleared.providers = scope ? cleared.providers.filter((x) => x !== scope) : [];
                 return { ok: true };
             }
             if (action === 'ready') {
@@ -441,7 +551,8 @@ export function fakeGateway(script, o) {
                 const profileId = primary.slice(at + 1);
                 const credential = store[profileId];
                 const account = ACCOUNT_AGENT.test(id);
-                if (!credential || credential.provider !== p.provider || (!account && credential.type === 'api_key'))
+                if (!credential || credential.provider !== p.provider
+                    || (!account && credential.type === 'api_key' && p.planKey !== true))
                     return { ok: false };
                 for (const [otherId, other] of Object.entries(store))
                     if (account ? otherId !== profileId : other.provider === p.provider && otherId !== profileId)
@@ -466,17 +577,26 @@ export function fakeGateway(script, o) {
         'openclaw.setup.activate': (p) => {
             if (p.kind !== 'api-key')
                 throw new Error('only the API-key setup path is simulated');
+            // The pin takes a pasted key only for a choice whose manifest allows one (`appGuidedSecret`).
             const route = routes().find((r) => r.choice === String(p.authChoice) && r.keyEntry);
-            if (!route)
-                return { ok: false, status: 'unavailable' };
+            if (!route || route.upstream?.flow === 'absent')
+                return { ok: false, status: 'unavailable', error: 'That key-based provider is not available on this Gateway.' };
             const model = `${route.provider}/fake-key-model`;
             keys.set(String(p.agentId), { provider: route.provider, key: String(p.apiKey), model, sealed: false });
-            signInAgent(String(p.agentId), route.provider);
+            signInAgent(String(p.agentId), route.provider, { type: 'api_key', key: String(p.apiKey) });
+            setPrimaryOfId(String(p.agentId), `${model}@${route.provider}:default`);
             return { ok: true, status: 'ok', modelRef: model };
         },
         'openclaw.setup.auth.start': (p) => {
+            // The pin starts only an app-guided login; a key-entry choice is set up from its pasted key instead.
+            const route = routes().find((r) => r.choice === String(p.authChoice ?? ''));
+            if (!route || route.keyEntry || route.via === 'cli' || route.upstream?.flow === 'absent')
+                throw new Error('That provider setup is not available on this Gateway.');
+            // The pin's single setup admission: a second start while a session runs is refused.
+            if (wizards.size)
+                throw new Error('setup is already in progress');
             const sessionId = String(p.sessionId ?? `fake-${randomUUID()}`);
-            wizards.set(sessionId, { agentId: String(p.agentId ?? 'main'), answered: false, pulls: 0 });
+            wizards.set(sessionId, { agentId: String(p.agentId ?? 'main'), authChoice: String(p.authChoice ?? ''), answered: false, pulls: 0 });
             return { sessionId, done: false, status: 'running' };
         },
         'wizard.next': (p) => {
@@ -488,11 +608,11 @@ export function fakeGateway(script, o) {
                 return { done: false, step: PROGRESS_STEP };
             }
             if (!session.answered)
-                return { done: false, step: DEVICE_STEP };
+                return { done: false, step: session.authChoice === 'openai' ? BROWSER_STEP : DEVICE_STEP };
             if (session.pulls++ === 0)
                 return { done: false, step: PROGRESS_STEP };
             wizards.delete(String(p.sessionId));
-            signInAgent(session.agentId, 'openai');
+            signInAgent(session.agentId, 'openai', signInFields);
             return { done: true, status: 'done', modelActivation: { modelRef: 'openai/gpt-5.1' } };
         },
         'wizard.cancel': (p) => {
@@ -510,6 +630,66 @@ export function fakeGateway(script, o) {
                 run.waiters.push(resolve);
         }),
         'sessions.steer': () => ({}),
+        // The pin: a key the agent holds answers its canonical key; a missing one errors unless `allowMissing`, which answers `{ ok: false }`.
+        'sessions.resolve': (p) => {
+            const key = String(p.key ?? ''), agentId = String(p.agentId ?? 'main');
+            if (sessions.has(`${agentId}\n${key}`))
+                return { ok: true, key, agentId };
+            if (p.allowMissing === true)
+                return { ok: false };
+            throw new Error(`No session found: ${key}`);
+        },
+        // The pin's rows for one agent (`search` matches a key substring), `hasActiveRun` while a run on it is live.
+        'sessions.list': (p) => {
+            const agentId = String(p.agentId ?? 'main'), search = String(p.search ?? '').toLowerCase();
+            const rows = [...sessions].filter(([id]) => id.startsWith(`${agentId}\n`)).map(([id, s]) => ({ key: id.slice(agentId.length + 1), s }))
+                .filter(({ key }) => key.toLowerCase().includes(search))
+                .map(({ key, s }) => ({ key, sessionId: s.sessionId, updatedAt: s.updatedAt, hasActiveRun: activeOn(agentId, key),
+                ...(s.provider ? { modelProvider: s.provider } : {}), ...(s.model ? { model: s.model } : {}) }));
+            return { count: rows.length, sessions: rows };
+        },
+        // `fork` copies the parent's whole transcript, from any agent, into a new session id; refused while the parent runs.
+        'sessions.create': (p) => {
+            const agentId = String(p.agentId ?? 'main'), key = String(p.key ?? '');
+            if (!agents.has(agentId))
+                throw new Error(`unknown agent id "${agentId}"`);
+            const rows = [];
+            let model = {};
+            if (p.fork === true) {
+                const parentKey = String(p.parentSessionKey ?? '');
+                const parentAgent = /^agent:([^:]+):/.exec(parentKey)?.[1] ?? 'main';
+                const parent = sessions.get(`${parentAgent}\n${parentKey}`);
+                if (!parent)
+                    throw new Error(`No session found: ${parentKey}`);
+                if (activeOn(parentAgent, parentKey))
+                    throw new Error(`Parent session ${parentKey} is still active; try again in a moment.`);
+                rows.push(...structuredClone(parent.rows));
+                model = { provider: parent.provider, model: parent.model };
+            }
+            const ref = typeof p.model === 'string' ? p.model : undefined;
+            if (ref)
+                model = ref.includes('/') ? { provider: ref.slice(0, ref.indexOf('/')), model: ref.slice(ref.indexOf('/') + 1) } : { ...model, model: ref };
+            const session = { sessionId: randomUUID(), updatedAt: Date.now(), rows, ...model };
+            sessions.set(`${agentId}\n${key}`, session);
+            return { ok: true, key, sessionId: session.sessionId, runStarted: false };
+        },
+        // A changed session (id or `updatedAt` other than expected) is refused before anything goes, as the pin does.
+        'sessions.delete': (p) => {
+            const agentId = String(p.agentId ?? 'main'), key = String(p.key ?? '');
+            const session = sessions.get(`${agentId}\n${key}`);
+            if ((p.expectedSessionId !== undefined && session?.sessionId !== p.expectedSessionId)
+                || (p.expectedSessionUpdatedAt !== undefined && session?.updatedAt !== p.expectedSessionUpdatedAt))
+                throw new Error(`Session ${key} changed before deletion. Retry.`);
+            if (session && activeOn(agentId, key))
+                throw new Error(`Session ${key} is still active; try again.`);
+            return { ok: true, key, deleted: sessions.delete(`${agentId}\n${key}`), archived: [] };
+        },
+        'chat.history': (p) => {
+            const key = String(p.sessionKey ?? '');
+            const agentId = String(p.agentId ?? /^agent:([^:]+):/.exec(key)?.[1] ?? 'main');
+            const session = sessions.get(`${agentId}\n${key}`);
+            return { sessionKey: key, ...(session ? { sessionId: session.sessionId } : {}), messages: structuredClone(session?.rows ?? []) };
+        },
         'chat.abort': (p) => {
             for (const run of runs.values()) {
                 if (run.result || run.sessionKey !== String(p.sessionKey ?? ''))
@@ -664,6 +844,20 @@ export function fakeGateway(script, o) {
         failNext,
         drop,
         handle: (method, fn) => { handlers.set(method, fn); },
+        setUsage: (agentId, provider, windows) => {
+            let perAgent = usage.get(agentId);
+            if (!perAgent) {
+                perAgent = new Map();
+                usage.set(agentId, perAgent);
+            }
+            perAgent.set(provider, windows);
+        },
+        signInAs: (fields) => { signInFields = fields && { ...fields }; },
+        seedProfile: (agentId, profileId, profile) => {
+            ensureAgent(agentId);
+            storeOf(agentId)[profileId] = profile;
+            setPrimaryOfId(agentId, `${profile.provider}/default@${profileId}`);
+        },
         transport: factory({ port: 0, token: 'test', identityPath: '', bridgeSock: '' }),
     };
 }

package/dist/testing/model-stub.d.ts

@@ -16,6 +16,7 @@ export type StubCall = {
     authorization: string;
     path: string;
     body: StubRequest;
+    session?: string;
 };
 /** The token usage every stub reply reports when asked (`stream_options.include_usage`), per model call. */
 export declare const STUB_USAGE: {

package/dist/testing/model-stub.js

@@ -77,7 +77,8 @@ export function startModelStub(script = [], o = {}) {
             res.writeHead(400).end();
             return;
         }
-        const call = { authorization: String(req.headers.authorization ?? ''), path: req.url ?? '', body };
+        const call = { authorization: String(req.headers.authorization ?? ''), path: req.url ?? '', body,
+            ...(req.headers['x-opencode-session'] ? { session: String(req.headers['x-opencode-session']) } : {}) };
         calls.push(call);
         o.onCall?.(call); // Fixture evidence is persisted before any response/hold awaits.
         if (req.url === '/api/embed' || req.url === '/api/embeddings') {

package/dist/types.d.ts

@@ -50,6 +50,8 @@ export interface RunSpec<S extends OutputSchema | undefined = OutputSchema | und
     }[];
     thinking?: 'off' | 'low' | 'medium' | 'high';
     model?: string;
+    account?: AccountRef | 'default' | 'auto';
+    needs?: string[];
     /** Explicit paid key choice. Uses a separate member-owned agent and separate session history. */
     auth?: 'apiKey';
     tools?: string[];
@@ -60,6 +62,14 @@ export type RunEvent = {
 } | {
     type: 'thinking';
     tokens: number;
+} | {
+    type: 'account';
+    account: AccountId;
+    model: string;
+    sessionKey: string;
+    how: 'chosen' | 'default' | 'auto';
+    why: PickWhy;
+    considered: Considered[];
 } | {
     type: 'text';
     text: string;
@@ -98,6 +108,8 @@ export type RunEnd<T = unknown> = {
     data?: T;
     usage?: RunUsage;
     planWindow?: PlanWindow;
+    account?: AccountId;
+    model?: string;
 } | {
     ok: false;
     aborted: true;
@@ -319,6 +331,13 @@ export type AccountPick = {
     code: 'none' | 'not_included' | 'unknown_account' | 'bound' | 'paid';
     reason: string;
     considered: Considered[];
+} | {
+    ok: false;
+    code: 'resting';
+    account: AccountId;
+    until?: number;
+    reason: string;
+    considered: Considered[];
 };
 export type MoveResult = {
     ok: true;

package/dist/words.json

@@ -107,6 +107,13 @@
     "ago.hours": "{n} h",
     "account.bound": "This conversation uses {name}. Move it to switch accounts.",
     "account.paid": "This conversation uses {name}, which is billed per use. Choose {name} to keep going.",
+    "account.another": "another account",
     "account.signOutFirst": "To add a different {provider} account, sign out of {provider} in your browser first.",
-    "account.legacyMember": "This person needs a new profile before adding more accounts."
+    "account.legacyMember": "This person needs a new profile before adding more accounts.",
+    "move.unsupported": "This conversation has not started yet, so there is nothing to move.",
+    "move.busy": "Wait for this conversation to finish before moving it.",
+    "move.notReady": "Sign in to {name} first.",
+    "move.closeFailed": "This conversation now continues on {name}, but its earlier copy could not be removed.",
+    "move.taken": "{name} already holds a conversation under this name, so nothing was moved.",
+    "run.moved": "This conversation just moved to another account. Send it again to continue there."
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/openclaw",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "The OpenClaw runtime kit: the pinned engine's full operator surface with plain-words helpers for members, sign-in, runs and approvals.",
   "license": "Apache-2.0",
   "type": "module",
@@ -62,7 +62,7 @@
   "dependencies": {
     "@byokit/pair": "0.10.0",
     "@byokit/relay": "0.6.1",
-    "@byokit/discover": "0.8.0",
+    "@byokit/discover": "0.8.1",
     "@byokit/seal": "0.3.0",
     "@byokit/secrets": "0.5.1",
     "@openclaw/gateway-client": "2026.8.35",

package/plugin/accounts.js

@@ -124,8 +124,10 @@ async function handle(params) {
     let sealed = false;
     const store = await updateAuthProfileStoreWithLock({ agentDir, saveOptions: LOCAL, updater(s) {
       const credential = s.profiles?.[profileId];
-      // No such profile, or the named profile belongs to another provider; on a member agent an api_key is refused.
-      if (!credential || credential.provider !== provider || (!account && credential.type === 'api_key')) return false;
+      // No such profile, or the named profile belongs to another provider; on a member agent an api_key is refused
+      // unless it is a plan key (subscription billing, never billed per use).
+      if (!credential || credential.provider !== provider
+        || (!account && credential.type === 'api_key' && params.planKey !== true)) return false;
       who = whoOf(credential);
       s.profiles = sealProfiles(s.profiles, provider, profileId, account);
       s.order = account ? { [provider]: [profileId] } : { ...(s.order ?? {}), [provider]: [profileId] };
@@ -137,8 +139,15 @@ async function handle(params) {
   }
 
   if (params.action === 'clear') {
+    // With a provider only that provider's profiles go: a member agent keeps its other providers' sign-ins.
+    const provider = params.provider;
+    const scoped = typeof provider === 'string' && provider.length > 0;
     const cleared = await updateAuthProfileStoreWithLock({ agentDir, saveOptions: LOCAL, updater(s) {
-      s.profiles = {}; s.order = {}; delete s.lastGood; return true;
+      if (!scoped) { s.profiles = {}; s.order = {}; delete s.lastGood; return true; }
+      s.profiles = Object.fromEntries(Object.entries(s.profiles ?? {}).filter(([, p]) => p.provider !== provider));
+      if (s.order) delete s.order[provider];
+      if (object(s.lastGood)) delete s.lastGood[provider];
+      return true;
     } });
     return cleared ? { ok: true } : { ok: false };
   }

package/plugin/catalog.js

@@ -0,0 +1,48 @@
+// byokit.catalog (5.6 live provider catalogs): the provider plugin's own live model list, with each model's api and
+// baseUrl from its catalog data, so the kit can register models embedded runs cannot resolve otherwise. The engine's
+// catalog loader stops at a registered list; the provider's catalog hook does not.
+export function registerCatalog(api) {
+  api.registerGatewayMethod('byokit.catalog', async ({ params, respond }) => {
+    try {
+      const provider = String(params?.provider ?? '');
+      const { resolveAgentDir } = await import('openclaw/plugin-sdk/agent-runtime');
+      const { getRuntimeConfig } = await import('openclaw/plugin-sdk/config-runtime');
+      const { resolvePluginProviders } = await import('openclaw/plugin-sdk/provider-catalog-runtime');
+      const { resolveApiKeyForProvider } = await import('openclaw/plugin-sdk/provider-auth-runtime');
+      const config = getRuntimeConfig();
+      const hook = resolvePluginProviders({ config, env: process.env }).find((p) => p.id === provider)?.catalog;
+      if (!provider || typeof hook?.run !== 'function') return respond(true, { ok: false, reason: 'failed' });
+      // The first agent holding the provider's key; every account of one provider sees the same catalog.
+      let unreadable = false;
+      for (const agentId of new Set([...Object.keys(config.agents?.entries ?? {}), 'main'])) {
+        const agentDir = resolveAgentDir(config, agentId);
+        const apiKey = await resolveApiKeyForProvider({ provider, cfg: config, agentDir })
+          .then((a) => a?.apiKey, () => { unreadable = true; return undefined; });
+        if (!apiKey) continue;
+        const run = async (discoveryApiKey) => (await hook.run({ config, agentDir, env: process.env, providerIds: [provider],
+          resolveProviderApiKey: () => ({ apiKey, discoveryApiKey }),
+          resolveProviderAuth: () => ({ apiKey, discoveryApiKey, mode: 'api_key', source: 'profile' }) }))?.provider;
+        const live = await run(apiKey);
+        // Each api's endpoint comes from the pinned catalog (no discovery key): upstream now names endpoints the
+        // pinned engine does not recognize, and it sends Go's routing header only to ones it does.
+        // ponytail: drop when the engine pin recognizes the live endpoints.
+        const pinned = await run(undefined);
+        const endpoint = new Map();
+        for (const m of pinned?.models ?? []) {
+          const api = m.api ?? pinned.api;
+          if (!endpoint.has(api) && (m.baseUrl ?? pinned.baseUrl)) endpoint.set(api, m.baseUrl ?? pinned.baseUrl);
+        }
+        if (!live?.models?.length) return respond(true, { ok: false, reason: 'failed' });
+        // A pinned model the live list omits stays in the catalog; live wins by id.
+        const liveIds = new Set(live.models.map((m) => m.id));
+        const models = [...live.models, ...(pinned?.models ?? []).filter((m) => !liveIds.has(m.id))]
+          .map(({ provider: _p, apiKey: _k, headers: _h, ...model }) =>
+            (endpoint.has(model.api) ? { ...model, baseUrl: endpoint.get(model.api) } : model));
+        return respond(true, { ok: true, models });
+      }
+      respond(true, { ok: false, reason: unreadable ? 'failed' : 'no-key' });
+    } catch {
+      respond(true, { ok: false, reason: 'failed' }); // never engine text: a hook error could carry the key
+    }
+  }, { scope: 'operator.admin' });
+}

package/plugin/index.js

@@ -6,6 +6,7 @@ import { readFileSync } from 'node:fs';
 import { registerKeys } from './keys.js';
 import { registerUsage } from './usage.js';
 import { registerAccounts } from './accounts.js';
+import { registerCatalog } from './catalog.js';
 
 /** TypeBox's Kind is a global symbol, so these schemas are valid TypeBox without importing typebox. */
 const Kind = Symbol.for('TypeBox.Kind');
@@ -147,7 +148,7 @@ export default {
     jsonSchema: { type: 'object', additionalProperties: false, properties: {} },
   },
   register(api) {
-    if (api.registerGatewayMethod) { registerKeys(api); registerUsage(api); registerAccounts(api); }
+    if (api.registerGatewayMethod) { registerKeys(api); registerUsage(api); registerAccounts(api); registerCatalog(api); }
     if (BROWSER) {
       if (typeof api.registerAgentToolResultMiddleware !== 'function') throw new Error('browser result protection unavailable');
       api.registerAgentToolResultMiddleware(async (event, ctx) => {

package/plugin/keys.js

@@ -4,7 +4,7 @@ export function registerKeys(api) {
   api.registerGatewayMethod('byokit.keys', async ({ params, respond }) => {
     const member = params?.member;
     if (typeof member !== 'string' || !/^[a-z][a-z0-9-]{0,31}$/.test(member) || member.startsWith('byokit-key-')
-      || !['prepare', 'seal', 'ready'].includes(params.action)) {
+      || !['prepare', 'seal', 'ready', 'clear'].includes(params.action)) {
       respond(true, { ok: false });
       return;
     }
@@ -27,7 +27,10 @@ export function registerKeys(api) {
       const marker = join(keyDir, 'byokit-key-ready.json');
       if (params.action === 'ready') {
         if (diagnostics) diagnostics.stage = 'marker';
-        const selected = JSON.parse(await readFile(marker, 'utf8'));
+        let text;
+        try { text = await readFile(marker, 'utf8'); }
+        catch (error) { if (error?.code !== 'ENOENT') throw error; reply({ ok: false, absent: true }); return; }
+        const selected = JSON.parse(text);
         let ready = false;
         if (diagnostics) diagnostics.stage = 'store';
         await updateAuthProfileStoreWithLock({ agentDir: keyDir, updater(store) {
@@ -45,7 +48,6 @@ export function registerKeys(api) {
         reply({ ok: ready, ...(ready ? { model: selected.model } : {}) });
         return;
       }
-      await rm(marker, { force: true });
       if (params.action === 'prepare') {
         // Only local profiles are loaded by this transaction: no shared-store read-through or CLI sync.
         const normal = await updateAuthProfileStoreWithLock({
@@ -66,6 +68,18 @@ export function registerKeys(api) {
         const cleared = await updateAuthProfileStoreWithLock({ agentDir: keyDir,
           saveOptions: { filterExternalAuthProfiles: false, syncExternalCli: false },
           updater(store) { store.profiles = {}; store.order = {}; return true; } });
+        // The marker goes only once the replacement passes its own checks: a refused prepare keeps it.
+        if (cleared) await rm(marker, { force: true });
+        respond(true, { ok: Boolean(cleared) });
+        return;
+      }
+      if (params.action === 'clear') {
+        // A failed add drops the key it activated; if this clear never reaches the engine, the unsealed key stays but is
+        // unusable until the next add's prepare or the next kit start's sweep.
+        const cleared = await updateAuthProfileStoreWithLock({ agentDir: keyDir,
+          saveOptions: { filterExternalAuthProfiles: false, syncExternalCli: false },
+          updater(store) { store.profiles = {}; store.order = {}; delete store.lastGood; return true; } });
+        if (cleared) await rm(marker, { force: true });
         respond(true, { ok: Boolean(cleared) });
         return;
       }
@@ -74,7 +88,11 @@ export function registerKeys(api) {
       const at = typeof primary === 'string' ? primary.lastIndexOf('@') : -1;
       if (at < 1) { respond(true, { ok: false }); return; }
       const profileId = primary.slice(at + 1);
-      const model = primary.slice(0, at);
+      const model = params.model ?? primary.slice(0, at);
+      // The kit checks the route catalog before seal; a direct call still cannot cross the activated provider.
+      if (typeof model !== 'string' || !model || model.split('/')[0] !== primary.split('/')[0]) {
+        respond(true, { ok: false }); return;
+      }
       let found = false;
       const sealed = await updateAuthProfileStoreWithLock({ agentDir: keyDir,
         saveOptions: { filterExternalAuthProfiles: false, syncExternalCli: false },