@byokit/openclaw 0.11.1 → 0.13.0

package/dist/keys.d.ts

@@ -1,20 +1,34 @@
-import type { GatewayTransport, Member } from './types.ts';
-export type AddKeyResult = 'ok' | 'invalid' | 'not_included';
-export declare function createKeys(ctx: {
+import { type ActivationCtx } from './activation.ts';
+import type { Member, ModelInfo } from './types.ts';
+export type KeyFailureReason = 'auth' | 'billing' | 'empty' | 'model' | 'network' | 'engine' | 'inference' | 'busy';
+export type AddKeyResult = {
+    status: 'ok';
+} | {
+    status: 'invalid' | 'not_included' | 'retry';
+    reason: KeyFailureReason;
+};
+export declare function createKeys(ctx: ActivationCtx & {
     root: string;
-    request: GatewayTransport['request'];
     ensure(member: Member): Promise<{
         agentId: string;
     }>;
     restarting?(): boolean;
+    prepareOwner(agentId: string): Promise<void>;
 }): {
+    models: (member: Member, o: {
+        authChoice: string;
+    }) => Promise<ModelInfo[]>;
     exclusive: <T>(member: Member, work: () => Promise<T>) => Promise<T>;
     add(member: Member, o: {
         authChoice: string;
         apiKey: string;
+        model?: string;
     }): Promise<AddKeyResult>;
-    ready(member: Member): Promise<{
+    ready(member: Member, o?: {
+        once?: boolean;
+    }): Promise<{
         agentId: string;
         model: string;
     } | undefined>;
+    sweep(): Promise<boolean>;
 };

package/dist/keys.js

@@ -1,6 +1,9 @@
 import { join } from 'node:path';
-import { keyAgentId, MEMBER_ID, KEY_PREFIX } from "./members.js";
+import { activate } from "./activation.js";
+import { keyAgentId, MEMBER_ID, KEY_PREFIX, untilListed } from "./members.js";
 import { routes } from "./routes.js";
+import { modelsOf } from "./accounts.js";
+import { LIVE_CATALOGS } from "./constants.js";
 export function createKeys(ctx) {
     // Serialize key replacement and key runs, so an in-flight run never sees a half-installed replacement.
     const tails = new Map();
@@ -17,39 +20,117 @@ export function createKeys(ctx) {
         }
     };
     const check = (member) => MEMBER_ID.test(member) && !member.startsWith(KEY_PREFIX);
-    const control = (member, action, provider) => ctx.request('byokit.keys', { member, action, ...(provider ? { provider } : {}) });
+    // Config writes may drain/restart the gateway: a restart, or a retryable refusal, means the call may simply run again.
+    const transient = (error) => {
+        const refusal = error;
+        return Boolean(ctx.restarting?.() || (refusal?.code === 'UNAVAILABLE' && refusal.retryable === true));
+    };
+    const control = (member, action, provider, model) => ctx.request('byokit.keys', { member, action, ...(provider ? { provider } : {}), ...(model ? { model } : {}) });
+    const failure = (status, reason) => ({ status, reason });
+    // Only a provider refusal is `invalid`; an unavailable route or model is `not_included`; everything else may be retried.
+    const probeResult = (status) => {
+        switch (status) {
+            case 'auth': return failure('invalid', 'auth');
+            case 'billing': return failure('invalid', 'billing');
+            case 'unavailable':
+            case 'no_model': return failure('not_included', 'model');
+            case 'timeout':
+            case 'network': return failure('retry', 'network');
+            case 'rate_limit':
+            case 'busy': return failure('retry', 'busy');
+            case 'format':
+            case 'unknown': return failure('retry', 'inference');
+            default: return failure('retry', 'engine');
+        }
+    };
+    const registered = async (provider, model) => {
+        const { config } = await ctx.request('config.get');
+        return Boolean(config?.models?.providers?.[provider]?.models?.some((m) => `${provider}/${m.id}` === model));
+    };
+    const errorReason = (error, sent) => {
+        if (transient(error))
+            return 'busy';
+        const e = error;
+        if (sent && e?.code === 'INVALID_REQUEST')
+            return 'inference';
+        return ['ECONNRESET', 'ECONNREFUSED', 'ENOTFOUND', 'EAI_AGAIN', 'ETIMEDOUT', 'CLIENT_TIMEOUT', 'NETWORK_ERROR'].includes(e?.code ?? '')
+            || e?.name === 'TimeoutError' ? 'network' : 'engine';
+    };
+    const models = async (member, o) => {
+        if (!check(member))
+            throw new Error('Choose your own member.');
+        const route = routes().find((r) => r.choice === o.authChoice && r.keyEntry && r.readiness === 'ready');
+        if (!route || !LIVE_CATALOGS.includes(route.provider))
+            return [];
+        await ctx.ensure(member);
+        const catalog = await ctx.request('byokit.catalog', { provider: route.provider });
+        if (catalog.ok)
+            return modelsOf(route.provider, { models: catalog.models?.map((m) => ({ ...m, provider: route.provider })) });
+        if (catalog.reason !== 'no-key')
+            throw new Error('Model catalog is unavailable.');
+        return [];
+    };
     return {
+        models,
         exclusive,
         async add(member, o) {
-            if (!check(member) || !o.apiKey.trim())
-                return 'invalid';
-            const route = routes().find((r) => r.choice === o.authChoice && r.keyEntry);
-            if (!route)
-                return 'not_included';
+            if (!check(member))
+                throw new Error('Choose your own member.');
+            if (!o.apiKey.trim())
+                return failure('invalid', 'empty');
+            const route = routes().find((r) => r.choice === o.authChoice && r.keyEntry && r.readiness === 'ready');
+            if (!route || (o.model !== undefined && !LIVE_CATALOGS.includes(route.provider)))
+                return failure('not_included', 'model');
             return exclusive(member, async () => {
+                let sent = false;
+                // A key the engine may have taken but not sealed is cleared (prepare already emptied the agent); if the clear
+                // does not reach the engine, the key stays unsealed and unusable until the next key add or kit start, so runs
+                // fail closed.
+                const abandon = async (result) => {
+                    await control(member, 'clear').catch(() => undefined);
+                    return result;
+                };
                 try {
                     await ctx.ensure(member);
                     const agentId = keyAgentId(member);
                     const list = await ctx.request('agents.list');
                     if (!list.agents.some((a) => a.id === agentId))
                         await ctx.request('agents.create', { name: agentId, workspace: join(ctx.root, 'key-workspaces', member) });
+                    // Creation answers before the runtime roster/owners publish, just as for ordinary members.
+                    await untilListed(ctx.request, agentId);
                     if (!(await control(member, 'prepare', route.provider)).ok)
-                        return 'invalid';
+                        return failure('retry', 'engine');
                     // The public pin's typed API-key path, never a CLI-login import. Discard the engine's lines/errors.
-                    const params = {
-                        kind: 'api-key', agentId, authChoice: o.authChoice, apiKey: o.apiKey,
-                    };
-                    const result = (await ctx.request('openclaw.setup.activate', params, { timeoutMs: 180_000 }));
-                    if (!result.ok)
-                        return result.status === 'unavailable' ? 'not_included' : 'invalid';
-                    return (await control(member, 'seal')).ok ? 'ok' : 'invalid';
+                    sent = true;
+                    const result = await activate(ctx, { kind: 'api-key', agentId, authChoice: o.authChoice, apiKey: o.apiKey }, { timeoutMs: 180_000 });
+                    if (!result.ok && !result.late)
+                        return abandon(probeResult(result.status));
+                    if (result.late)
+                        return abandon(failure('retry', 'busy'));
+                    if (o.model !== undefined && !(await models(member, o)).some((m) => m.id === o.model && m.available))
+                        return abandon(failure('not_included', 'model'));
+                    // Prepare before publishing the ready marker: failed preparation remains unusable even if clear fails.
+                    try {
+                        await ctx.prepareOwner(agentId);
+                    }
+                    catch {
+                        return abandon(failure('retry', 'engine'));
+                    }
+                    if (o.model !== undefined && LIVE_CATALOGS.includes(route.provider) && !(await registered(route.provider, o.model)))
+                        return abandon(failure('retry', 'model'));
+                    if ((await control(member, 'seal', undefined, o.model)).ok)
+                        return { status: 'ok' };
+                    return abandon(failure('retry', 'engine'));
                 }
-                catch {
-                    return 'invalid';
+                catch (error) {
+                    const reason = errorReason(error, sent);
+                    if (sent)
+                        return abandon(failure('retry', reason));
+                    return failure('retry', reason);
                 }
             });
         },
-        async ready(member) {
+        async ready(member, o = {}) {
             if (!check(member))
                 return undefined;
             const deadline = Date.now() + 60_000;
@@ -59,15 +140,46 @@ export function createKeys(ctx) {
                     return ready.ok && ready.model ? { agentId: keyAgentId(member), model: ready.model } : undefined;
                 }
                 catch (error) {
-                    // Config writes may drain/restart the gateway after activation. This read is safe to retry;
-                    // an absent profile or a terminal refusal still fails closed immediately.
-                    const refusal = error;
-                    const transient = ctx.restarting?.() || (refusal?.code === 'UNAVAILABLE' && refusal.retryable === true);
-                    if (!transient || Date.now() >= deadline)
+                    // This read is safe to retry; an absent profile or a terminal refusal still fails closed immediately.
+                    if (o.once || !transient(error) || Date.now() >= deadline)
                         return undefined;
                     await new Promise((resolve) => setTimeout(resolve, 250));
                 }
             }
         },
+        // Kit start calls this once the gateway is ready: a failed add whose abandon clear never reached the engine
+        // leaves an unsealed key with no ready marker, so drop it. A single ready read per key agent, no retries; an add
+        // in flight for that member is waited for. Only an absent marker is cleared; a refused read or clear (the gateway
+        // left ready) makes the sweep incomplete. Resolves true once every key agent was read.
+        async sweep() {
+            let agents;
+            try {
+                agents = (await ctx.request('agents.list')).agents;
+            }
+            catch {
+                return false;
+            }
+            let complete = true;
+            for (const agent of agents) {
+                if (!agent.id.startsWith(KEY_PREFIX))
+                    continue;
+                const member = agent.id.slice(KEY_PREFIX.length);
+                if (!check(member))
+                    continue;
+                await exclusive(member, async () => {
+                    const ready = await control(member, 'ready').catch(() => undefined);
+                    if (ready?.ok === true)
+                        return;
+                    if (ready?.absent !== true) {
+                        complete = false;
+                        return;
+                    }
+                    const cleared = await control(member, 'clear').catch(() => undefined);
+                    if (cleared?.ok !== true)
+                        complete = false;
+                });
+            }
+            return complete;
+        },
     };
 }

package/dist/kit.d.ts

@@ -2,7 +2,7 @@ import type { SealingAdapter } from '@byokit/secrets';
 import { type AddKeyResult } from './keys.ts';
 import { type RouteView } from './routes.ts';
 import type { BrowserHost, BrowserOptions } from './browser.ts';
-import type { Account, AccountId, Approval, CallOptions, Decision, Defaults, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, Hello, KitState, KitEventName, KitEventPayload, LearningCapture, LearningMode, Member, ModelInfo, Room, RunEnd, RunEvent, RunSpec, OutputSchema, SchemaOutput, SignInOptions, SignInView, ToolHost, ToolSpec } from './types.ts';
+import type { Account, AccountId, AccountPick, Approval, CallOptions, Decision, Defaults, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, Hello, KitState, KitEventName, KitEventPayload, LearningCapture, LearningMode, Member, ModelInfo, MoveResult, Room, RunEnd, RunEvent, RunRef, RunSelection, RunSpec, OutputSchema, SchemaOutput, SignInOptions, SignInView, ToolHost, ToolSpec } from './types.ts';
 export type KitOptions = {
     stateDir: string;
     authSeal?: SealingAdapter;
@@ -64,9 +64,12 @@ export declare class OpenClawKit {
     private listeners;
     private off;
     private signInDisconnects;
+    private readonly phaseListeners;
     private starting?;
     private stopping;
     private failures;
+    private swept;
+    private catalogs;
     browser?: BrowserHost;
     private browserHost?;
     private readonly brokers;
@@ -90,6 +93,9 @@ export declare class OpenClawKit {
     start(): Promise<void>;
     private connect;
     private disconnect;
+    private engineRestarting;
+    private authSnapshot;
+    private restarted;
     private closed;
     stop(): Promise<void>;
     private closeBrowsers;
@@ -106,6 +112,7 @@ export declare class OpenClawKit {
     routes(): RouteView[];
     providerStatus(member: Member): Promise<string[] | undefined>;
     providers(member: Member): Promise<string[]>;
+    /** A member sign-in to `provider`, or a ready key (5.8) whose saved model is that provider's. */
     signedIn(member: Member, provider: string): Promise<boolean>;
     signIn(member: Member, o: SignInOptions, on: (v: SignInView) => void): {
         paste(text: string): void;
@@ -113,9 +120,18 @@ export declare class OpenClawKit {
         done: Promise<SignInView>;
     };
     signOut(member: Member, provider: string): Promise<void>;
+    memberOf(ref: string): Member | undefined;
     accounts(member: Member): Promise<Account[]>;
-    models(member: Member, id: AccountId): Promise<ModelInfo[]>;
+    models(member: Member, id: AccountId | {
+        authChoice: string;
+    }): Promise<ModelInfo[]>;
     room(member: Member, id: AccountId, demand?: string[]): Promise<Room>;
+    /** What `run` would decide now with this selection and key, refusals included; decides nothing and runs nothing. */
+    pick(member: Member, sel: RunSelection, o?: {
+        sessionKey?: string;
+    }): Promise<AccountPick>;
+    /** Carry a conversation to another account: its whole transcript forks onto that account, then the old session goes. */
+    move(ref: RunRef, to: AccountId): Promise<MoveResult>;
     /** Sign in one more account: on the member agent while it holds none of the provider, else on a new sealed agent. */
     addAccount(member: Member, o: {
         authChoice: string;
@@ -132,13 +148,19 @@ export declare class OpenClawKit {
         }>;
     }>;
     renameAccount(member: Member, id: AccountId, name: string): Promise<Account>;
+    /** Remove one account: a member-agent account through `authLogout` with its profileIds, an account agent through
+     * `clear`, an empty `list`, `agents.delete` with `deleteFiles: false`, removal of its state dir, then the entry. */
+    removeAccount(member: Member, id: AccountId): Promise<void>;
     defaults(member: Member): Promise<Defaults>;
     setDefaults(member: Member, d: Defaults): Promise<void>;
     /** Save an explicitly supplied API key (billed per use) in this member's separate key agent. */
     addKey(agentId: Member, o: {
         authChoice: string;
         apiKey: string;
+        model?: string;
     }): Promise<AddKeyResult>;
+    private prepareKeyOwner;
+    private syncCatalogs;
     migrateRetainedLogin(member: Member, source: RetainedLogin): Promise<'staged' | 'nothing' | 'failed'>;
     confirmRetainedLogin(member: Member, source: RetainedLogin): Promise<boolean>;
     private runs;

package/dist/kit.js

@@ -1,8 +1,9 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
+import { isDeepStrictEqual } from 'node:util';
 import { fileURLToPath } from 'node:url';
-import { PROTOCOL_VERSION } from "./constants.js";
+import { PROTOCOL_VERSION, LIVE_CATALOGS } from "./constants.js";
 import { atomic } from "./engine-patches.js";
 import { Approvals } from "./approvals.js";
 import { Bridge } from "./bridge.js";
@@ -10,15 +11,16 @@ import { Engine, refusedOnly } from "./engine.js";
 import { AuthStoreSealSizeError } from "./auth-store.js";
 import { gatewayTransport } from "./transport.js";
 import { createMembers } from "./members.js";
-import { createAccounts } from "./accounts.js";
+import { createAccounts, memberOfAccount } from "./accounts.js";
 import { createLocks } from "./locks.js";
 import { keyAgentId, KEY_PREFIX, MEMBER_ID } from "./members.js";
 import { confirmRetainedLogin as confirmLogin, migrateRetainedLogin as migrateLogin } from "./migrate.js";
 import { createRuns, signedInProviders } from "./runs.js";
-import { createAuthStatus } from "./auth-status.js";
+import { authStatus, createAuthStatus } from "./auth-status.js";
 import { outputSchema } from "./output.js";
 import { createKeys } from "./keys.js";
 import { routes as routeTable } from "./routes.js";
+import { providerOf } from "./pick.js";
 import { signIn as startSignIn, signOut as engineSignOut } from "./signin.js";
 import { reconcileConfig, browserToolPolicySafe, browserProfileAcknowledged, browserSessionMayRun, memoryLimited as configMemoryLimited, configKeyPath, readConfigKey, writeConfigKey } from "./config.js";
 import { createBrowserHost } from "./browser/host.js";
@@ -26,6 +28,7 @@ import { fileSignInStore } from "./browser/store.js";
 import { launchBroker } from "./browser/broker.js";
 /** The engine's learning-mode config key (5.6 "Engine learning state"). */
 const LEARNING_KEY = 'skills.workshop.autonomous.mode';
+const RESTART_MS = 60_000;
 const operatorMethods = new Set([
     'agent',
     'agent.identity.get',
@@ -443,9 +446,12 @@ export class OpenClawKit {
     listeners = new Set();
     off = [];
     signInDisconnects = new Set();
+    phaseListeners = new Set();
     starting;
     stopping = false;
     failures = 0;
+    swept = false;
+    catalogs = Promise.resolve();
     browser;
     browserHost;
     brokers = new Map();
@@ -657,13 +663,17 @@ export class OpenClawKit {
             onState: (s) => this.setState(s), onExit: () => this.closed('engine exited') });
         this.admission = createAuthStatus(this.engine.root, (method, params, options) => this.request()(method, params, options));
         this.keys = createKeys({ root: this.engine.root,
-            restarting: () => this.current.phase === 'restarting' || this.current.phase === 'starting',
+            prepareOwner: (agentId) => this.prepareKeyOwner(agentId),
+            restarting: () => this.engineRestarting(),
             request: (method, params, options) => this.request()(method, params, options),
-            ensure: (member) => this.ensureMember(member) });
+            ensure: (member) => this.ensureMember(member),
+            authConfig: () => this.authSnapshot(),
+            restarted: (authBefore, signal) => this.restarted(authBefore, signal) });
         const slot = {};
         this.approvalsCtl = new Approvals({
             request: (method, params, co) => this.request()(method, params, co),
             bridge: { resolveAsk: (id, d) => slot.bridge?.resolveAsk(id, d) ?? false },
+            memberOf: (ref) => this.memberOf(ref),
         });
         const host = o.browser ? {
             gate: async (run, tool, input, info) => {
@@ -692,6 +702,7 @@ export class OpenClawKit {
                     return browserSessionMayRun(this.browserHost.signIns(), key, this.bridge.isRegisteredRun(key, runId));
                 } } : {}),
             permitted: o.permitted ?? (() => true), approvalTimeoutMs: o.approvalTimeoutMs ?? 180_000,
+            memberOf: (ref) => this.memberOf(ref),
             onAsk: (a) => this.approvalsCtl.add(a), onAskGone: (id) => this.approvalsCtl.remove(id) });
         slot.bridge = this.bridge;
     }
@@ -700,6 +711,8 @@ export class OpenClawKit {
             this.admission?.invalidate();
         this.current = { ...s, ...(this.engine.patchSet !== undefined ? { patchSet: this.engine.patchSet } : {}) };
         this.o.onState?.(this.current);
+        for (const fn of this.phaseListeners)
+            fn();
     }
     get state() { return this.current; }
     async prepare() {
@@ -746,15 +759,22 @@ export class OpenClawKit {
                 if (!operatorMethods.has(name) && !nodeMethods.has(name))
                     this.o.log?.(`gateway has unknown method: ${name}`);
             this.members = createMembers({ request: transport.request.bind(transport), root: this.engine.root });
-            this.accountsCtl = createAccounts({ request: transport.request.bind(transport), root: this.engine.root,
+            // An add outlives a restart (activation restarts the gateway before it settles): requests use the kit's current transport.
+            this.accountsCtl = createAccounts({ request: (method, params, o) => this.request()(method, params, o), root: this.engine.root,
                 ensure: (member) => this.ensureMember(member), locks: this.locks,
                 signIn: (agentId, o, on, fresh) => startSignIn({ ...this.signInCtx(), ensure: async () => ({ agentId }), fresh }, agentId, o, on),
-                log: this.o.log });
+                routes: this.routeMap, log: this.o.log, reseal: () => this.engine.authStore.reseal() });
             // The fail-closed tool bridge feeds the kit's single Approval surface (5.9, O5).
             await this.bridge.start();
             this.off.push(transport.onEvent((e) => this.approvalsCtl.handleEvent(e)));
             this.failures = 0;
             this.setState({ phase: 'ready' });
+            this.syncCatalogs();
+            // A failed key add whose abandon clear never reached the engine leaves an unsealed key with no ready marker;
+            // runs stay closed, so drop it now that the gateway is ready. Ready keys keep their marker and survive.
+            if (!this.swept)
+                void this.keys.sweep().then((done) => { if (done)
+                    this.swept = true; }).catch(() => undefined);
             if (this.o.browser)
                 await this.checkBrowserTools();
             // Replays the engine's native approval lists over the now-live transport (N9).
@@ -803,6 +823,39 @@ export class OpenClawKit {
         this.bridge.stop();
         await transport?.stop();
     }
+    engineRestarting() {
+        return this.current.phase === 'restarting' || this.current.phase === 'starting';
+    }
+    authSnapshot() {
+        return JSON.stringify(this.getConfigKey('auth')) ?? '';
+    }
+    // An activation that changed config `auth` makes the pin restart the gateway; then this resolves true once that
+    // restart has begun and the kit is ready again, false if it fails, is aborted or runs past RESTART_MS. No change: true.
+    restarted(authBefore, signal) {
+        if (this.o.spawnEngine === false || this.authSnapshot() === authBefore)
+            return Promise.resolve(true);
+        if (signal?.aborted)
+            return Promise.resolve(false);
+        return new Promise((resolve) => {
+            let began = this.engineRestarting();
+            const end = (ok) => {
+                clearTimeout(timer);
+                this.phaseListeners.delete(check);
+                signal?.removeEventListener('abort', abort);
+                resolve(ok);
+            };
+            const abort = () => end(false);
+            const check = () => {
+                if (this.engineRestarting())
+                    began = true;
+                else if (began)
+                    end(this.current.phase === 'ready');
+            };
+            const timer = setTimeout(() => end(false), RESTART_MS);
+            this.phaseListeners.add(check);
+            signal?.addEventListener('abort', abort, { once: true });
+        });
+    }
     closed(_why) {
         const engineFailed = _why === 'engine exited' && this.current.phase === 'failed' && this.current.why === 'exited';
         if (this.stopping || (this.current.phase !== 'ready' && !engineFailed))
@@ -839,9 +892,9 @@ export class OpenClawKit {
             delete this.browserProfiles[profile];
     }
     request() {
-        if (!this.transport || this.current.phase !== 'ready')
-            throw new Error('gateway not ready');
         const transport = this.transport;
+        if (!transport || this.current.phase !== 'ready')
+            return () => Promise.reject(new Error('gateway not ready'));
         return (method, params, options) => {
             const changesAuth = /^(models\.authLogout|openclaw\.setup\.(auth\.start|activate)|wizard\.(next|cancel)|config\.(apply|patch|set)|agents\.(create|update|delete)|secrets\.(reload|store\.(set|delete))|byokit\.keys)$/.test(method);
             if (!changesAuth || (method === 'byokit.keys' && params?.action === 'ready'))
@@ -853,22 +906,12 @@ export class OpenClawKit {
     call(method, params, o) {
         if (this.o.browser && /^(config\.(apply|patch|set)|agents\.(create|update|delete)|plugins\.(install|uninstall|setEnabled|refresh))$/.test(method))
             return Promise.reject(new Error('browser policy changes require guarded patchConfig'));
-        try {
-            return this.request()(method, params, o);
-        }
-        catch (error) {
-            return Promise.reject(error);
-        }
+        return this.request()(method, params, o);
     }
     callDynamic(method, params, o) {
         if (operatorMethods.has(method) || nodeMethods.has(method))
             return Promise.reject(new Error(`use typed call for generated method: ${method}`));
-        try {
-            return this.request()(method, params, o);
-        }
-        catch (error) {
-            return Promise.reject(error);
-        }
+        return this.request()(method, params, o);
     }
     get hello() { return this.greeting; }
     onEvent(event, fn) {
@@ -908,7 +951,9 @@ export class OpenClawKit {
             // Public readiness/sign-in reads stay live; their fresh result can prepare the next run's admission.
             authStatus: (agentId, refresh, native) => this.admission.read(agentId, refresh, native, false),
             ensure: (member) => this.ensureMember(member), callbackPort: this.o.callbackPort ?? 1455,
-            onDisconnect: (fn) => { this.signInDisconnects.add(fn); return () => { this.signInDisconnects.delete(fn); }; } };
+            onDisconnect: (fn) => { this.signInDisconnects.add(fn); return () => { this.signInDisconnects.delete(fn); }; },
+            authConfig: () => this.authSnapshot(),
+            restarted: (authBefore, signal) => this.restarted(authBefore, signal) };
     }
     routes() {
         return routeTable();
@@ -920,8 +965,10 @@ export class OpenClawKit {
     providers(member) {
         return this.providerStatus(member).then((names) => names ?? []);
     }
+    /** A member sign-in to `provider`, or a ready key (5.8) whose saved model is that provider's. */
     signedIn(member, provider) {
-        return this.providers(member).then((names) => names.includes(provider)).catch(() => false);
+        return this.providers(member).then(async (names) => names.includes(provider)
+            || providerOf((await this.keys.ready(member, { once: true }))?.model ?? '') === provider).catch(() => false);
     }
     signIn(member, o, on) {
         return startSignIn(this.signInCtx(), member, o, on);
@@ -929,14 +976,22 @@ export class OpenClawKit {
     signOut(member, provider) {
         return engineSignOut(this.signInCtx(), member, provider);
     }
-    // accounts (5.15, O14 steps S5, S6, S9 and S10): the per-member index with listing, adding, defaults, rename, models
-    // and room; `run({ account })` picks among them. Removing, `pick` and move arrive in later steps.
+    // The member an agent id or session key belongs to, through the account index (5.15, O14m). Reads the index file, so it
+    // needs no live gateway.
+    memberOf(ref) {
+        return memberOfAccount(this.engine.root, ref);
+    }
+    // accounts (5.15, O14 steps S5, S6 and S8-S12): the per-member index with listing, adding, defaults, rename, models
+    // and room; `run({ account })` and `pick` choose among them, held to the account a session is bound to, `move`
+    // carries a conversation to another account, and `removeAccount` deletes one.
     accounts(member) {
         if (!this.accountsCtl)
             return Promise.reject(new Error('gateway not ready'));
         return this.accountsCtl.list(member);
     }
     models(member, id) {
+        if (typeof id !== 'string')
+            return this.keys.models(member, id);
         if (!this.accountsCtl)
             return Promise.reject(new Error('gateway not ready'));
         return this.accountsCtl.models(member, id);
@@ -946,17 +1001,40 @@ export class OpenClawKit {
             return Promise.reject(new Error('gateway not ready'));
         return this.accountsCtl.room(member, id, demand);
     }
+    /** What `run` would decide now with this selection and key, refusals included; decides nothing and runs nothing. */
+    async pick(member, sel, o) {
+        const accounts = this.accountsCtl;
+        if (!accounts)
+            throw new Error('gateway not ready');
+        const binding = o?.sessionKey === undefined ? undefined : await accounts.bind(member, o.sessionKey);
+        return (await accounts.pick(member, sel, [], binding)).pick;
+    }
+    /** Carry a conversation to another account: its whole transcript forks onto that account, then the old session goes. */
+    move(ref, to) {
+        if (!this.accountsCtl)
+            return Promise.reject(new Error('gateway not ready'));
+        return this.accountsCtl.move(ref.member, ref.sessionKey, to);
+    }
     /** Sign in one more account: on the member agent while it holds none of the provider, else on a new sealed agent. */
     addAccount(member, o, on) {
         if (!this.accountsCtl)
             return Promise.reject(new Error('gateway not ready'));
-        return this.accountsCtl.add(member, o, on);
+        return this.accountsCtl.add(member, o, on).then((added) => ({ ...added,
+            done: added.done.then((r) => { if (r.view.state === 'done')
+                this.syncCatalogs(); return r; }) }));
     }
     renameAccount(member, id, name) {
         if (!this.accountsCtl)
             return Promise.reject(new Error('gateway not ready'));
         return this.accountsCtl.rename(member, id, name);
     }
+    /** Remove one account: a member-agent account through `authLogout` with its profileIds, an account agent through
+     * `clear`, an empty `list`, `agents.delete` with `deleteFiles: false`, removal of its state dir, then the entry. */
+    removeAccount(member, id) {
+        if (!this.accountsCtl)
+            return Promise.reject(new Error('gateway not ready'));
+        return this.accountsCtl.remove(member, id);
+    }
     defaults(member) {
         if (!this.accountsCtl)
             return Promise.reject(new Error('gateway not ready'));
@@ -971,6 +1049,37 @@ export class OpenClawKit {
     addKey(agentId, o) {
         return this.keys.add(agentId, o);
     }
+    async prepareKeyOwner(agentId) {
+        this.syncCatalogs();
+        await this.catalogs;
+        if ((await authStatus(this.request(), agentId, true)).unavailable)
+            throw new Error('Key owner unavailable.');
+    }
+    // Live provider catalogs (5.6): registers each live model with its api from the provider's catalog data, so
+    // embedded runs resolve it. Serialized and in the background; a failure is logged and keeps the registered list.
+    syncCatalogs() {
+        for (const provider of LIVE_CATALOGS) {
+            if (this.o.config?.models?.providers?.[provider]?.models !== undefined)
+                continue;
+            this.catalogs = this.catalogs.then(async () => {
+                const answer = await this.request()('byokit.catalog', { provider });
+                if (!answer.ok) {
+                    if (answer.reason !== 'no-key')
+                        this.o.log?.(`catalog sync ${provider}: ${answer.reason ?? 'failed'}`);
+                    return;
+                }
+                const { config } = await this.request()('config.get');
+                const registered = config?.models?.providers?.[provider]?.models ?? [];
+                const byId = new Map(registered.map((m) => [m.id, m]));
+                for (const m of answer.models ?? [])
+                    byId.set(m.id, m);
+                const models = [...byId.values()];
+                if (!isDeepStrictEqual(models, registered))
+                    await this.patchConfig({ models: { providers: { [provider]: { models } } } });
+            }).catch(() => { if (this.current.phase === 'ready')
+                this.o.log?.(`catalog sync ${provider}: failed`); });
+        }
+    }
     migrateRetainedLogin(member, source) {
         return migrateLogin({ root: this.engine.root, prepare: () => this.prepare(), doctor: () => this.engine.doctor(120_000),
             seal: this.o.authSeal, log: this.o.log, withStore: (task) => this.engine.withAuthStore(task) }, member, source);
@@ -1027,10 +1136,11 @@ export class OpenClawKit {
                 const selected = await this.keys.ready(spec.member);
                 if (!selected)
                     return { ok: false, kind: 'signed-out', message: 'Add an API key to use this option.' };
-                if (spec.model !== undefined && spec.model !== selected.model)
-                    return { ok: false, kind: 'plan', message: 'Choose the model saved with this key.' };
+                // A key pays for its provider's models (5.8); the engine refuses one its catalog does not list.
+                if (spec.model !== undefined && providerOf(spec.model) !== providerOf(selected.model))
+                    return { ok: false, kind: 'plan', message: 'Choose a model of the provider saved with this key.' };
                 // RunRef.member stays the person for app gates; the engine receives the isolated agent and history.
-                return this.runs().run({ ...spec, model: selected.model }, on, selected.agentId, output);
+                return this.runs().run({ ...spec, model: spec.model ?? selected.model }, on, selected.agentId, output);
             });
         return this.runs().run(spec, on, undefined, output);
     }