@byokit/openclaw 0.11.1 → 0.12.0

package/dist/activation.d.ts

@@ -0,0 +1,17 @@
+import type { GatewayParams, GatewayTransport } from './types.ts';
+export type ActivationCtx = {
+    request: GatewayTransport['request'];
+    authConfig(): string;
+    restarted(authBefore: string | undefined, signal?: AbortSignal): Promise<boolean>;
+};
+export declare const LATE_RESTART = "The engine took too long to restart after this sign-in. Nothing was kept; try again.";
+export type Activation = {
+    ok: boolean;
+    late?: boolean;
+    status?: string;
+    error?: string;
+};
+export declare function activate(ctx: ActivationCtx, params: GatewayParams<'openclaw.setup.activate'>, o: {
+    timeoutMs: number;
+    signal?: AbortSignal;
+}): Promise<Activation>;

package/dist/activation.js

@@ -0,0 +1,9 @@
+export const LATE_RESTART = 'The engine took too long to restart after this sign-in. Nothing was kept; try again.';
+export async function activate(ctx, params, o) {
+    const authBefore = ctx.authConfig();
+    // The request is never aborted by a cancel: its answer decides whether the engine kept the key, so cleanup waits for it.
+    const result = await ctx.request('openclaw.setup.activate', params, { timeoutMs: o.timeoutMs });
+    if (!result.ok)
+        return { ok: false, status: result.status, error: result.error };
+    return await ctx.restarted(authBefore, o.signal) ? { ok: true } : { ok: false, late: true };
+}

package/dist/approvals.d.ts

@@ -3,11 +3,13 @@ import type { Approval, Decision, GatewayTransport, Member } from './types.ts';
 export declare class Approvals {
     private readonly request;
     private readonly bridge;
+    private readonly memberOf;
     private readonly approvals;
     private readonly listeners;
     constructor(o: {
         request: GatewayTransport['request'];
         bridge: Pick<Bridge, 'resolveAsk'>;
+        memberOf: (ref: string) => Member | undefined;
     });
     handleEvent(e: {
         event: string;

package/dist/approvals.js

@@ -14,21 +14,19 @@ const REQUESTED = {
 const RESOLVED = new Set(['exec.approval.resolved', 'plugin.approval.resolved', 'question.resolved']);
 const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
 const asString = (v) => (typeof v === 'string' && v.length > 0 ? v : undefined);
-const memberOfKey = (key) => {
-    const m = /^agent:([a-z][a-z0-9-]{0,31}):/.exec(key);
-    return m?.[1];
-};
 /**
- * Member attribution: the request detail's agent first, else the `agent:<member>:` session key (5.9). The real
+ * Member attribution: the request detail's agent first, else the `agent:<member>:` session key (5.9). An
+ * indexed `<member>--<hex6>` account agent attributes to `<member>` (5.15). The real
  * engine nests exec/plugin details under `request` (question events stay flat); unattributed approvals carry ''
  * so they can never match a member id (B2).
  */
-function attribute(payload) {
+function attribute(payload, memberOf) {
     const detail = isRecord(payload.request) ? payload.request : payload;
     const agent = asString(detail.agentId);
     const key = asString(detail.sessionKey);
-    const fromKey = key ? memberOfKey(key) : undefined;
-    const member = agent ?? fromKey ?? asString(detail.member) ?? '';
+    const fromAgent = agent ? memberOf(agent) : undefined;
+    const fromKey = key ? memberOf(key) : undefined;
+    const member = fromAgent ?? fromKey ?? asString(detail.member) ?? '';
     return { member, ...(key ? { sessionKey: key } : {}) };
 }
 /** Exec policy modes (`off|on-miss|always`) ride in `request.ask`; they are not something a person said (B8). */
@@ -58,11 +56,13 @@ function expiresOf(payload, fallbackMs) {
 export class Approvals {
     request;
     bridge;
+    memberOf;
     approvals = new Map();
     listeners = new Set();
     constructor(o) {
         this.request = o.request;
         this.bridge = o.bridge;
+        this.memberOf = o.memberOf;
     }
     handleEvent(e) {
         const payload = isRecord(e.payload) ? e.payload : {};
@@ -71,7 +71,7 @@ export class Approvals {
             const id = asString(payload.id) ?? randomBytes(12).toString('base64url');
             if (this.approvals.has(id))
                 return;
-            const { member, sessionKey } = attribute(payload);
+            const { member, sessionKey } = attribute(payload, this.memberOf);
             const detail = isRecord(payload.request) ? payload.request : payload;
             const now = Date.now();
             const approval = {

package/dist/attribution.d.ts

@@ -0,0 +1,3 @@
+import type { Member } from './types.ts';
+export declare function agentOf(ref: string): string | undefined;
+export declare function memberOf(ref: string): Member | undefined;

package/dist/attribution.js

@@ -0,0 +1,25 @@
+const MEMBER = /^[a-z][a-z0-9-]{0,31}$/;
+const HEX6 = /^[0-9a-f]{6}$/;
+const KEY_PREFIX = 'byokit-key-';
+export function agentOf(ref) {
+    if (!ref.startsWith('agent:'))
+        return ref;
+    return /^agent:([^:]+):/.exec(ref)?.[1];
+}
+export function memberOf(ref) {
+    const agent = agentOf(ref);
+    if (agent === undefined)
+        return undefined;
+    if (agent.startsWith(KEY_PREFIX)) {
+        const inner = agent.slice(KEY_PREFIX.length);
+        return MEMBER.test(inner) ? inner : undefined;
+    }
+    const dash = agent.lastIndexOf('--');
+    if (dash >= 0) {
+        const head = agent.slice(0, dash);
+        const tail = agent.slice(dash + 2);
+        if (MEMBER.test(head) && HEX6.test(tail))
+            return head;
+    }
+    return MEMBER.test(agent) ? agent : undefined;
+}

package/dist/bridge.d.ts

@@ -1,4 +1,4 @@
-import type { Approval, Decision, RunRef, ToolHost, ToolSpec } from './types.ts';
+import type { Approval, Decision, Member, RunRef, ToolHost, ToolSpec } from './types.ts';
 /**
  * Asks must expire before the plugin's 195 s gate timeout, or the run gets a generic block while the approval
  * lingers (N3). The kit passes its `approvalTimeoutMs` through; anything above is clamped to this.
@@ -32,6 +32,7 @@ export declare class Bridge {
     private readonly tools;
     private readonly permitted;
     private readonly approvalTimeoutMs;
+    private readonly memberOf;
     private readonly onAsk;
     private readonly onAskGone;
     private readonly beforeAgentRun?;
@@ -52,6 +53,7 @@ export declare class Bridge {
         tools: ReadonlySet<string>;
         permitted: (tool: string) => boolean;
         approvalTimeoutMs: number;
+        memberOf(ref: string): Member | undefined;
         onAsk(a: Approval): void;
         onAskGone(id: string): void;
         beforeAgentRun?: (key: string, runId?: string) => Promise<boolean>;

package/dist/bridge.js

@@ -12,10 +12,6 @@ const FRAME_CAP = 1_000_000;
  */
 export const MAX_APPROVAL_TIMEOUT_MS = 190_000;
 const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
-const memberOfKey = (key) => {
-    const m = /^agent:([a-z][a-z0-9-]{0,31}):/.exec(key);
-    return m?.[1];
-};
 export const DEFAULT_SOCKET_NAME = 'bridge.sock';
 export const DEFAULT_PARAM_PREFIX = '__byokit';
 /** Resolve the bridge naming options, validating explicit values; defaults keep prior behavior. */
@@ -66,6 +62,7 @@ export class Bridge {
     tools;
     permitted;
     approvalTimeoutMs;
+    memberOf;
     onAsk;
     onAskGone;
     beforeAgentRun;
@@ -88,6 +85,7 @@ export class Bridge {
         this.tools = o.tools;
         this.permitted = o.permitted;
         this.approvalTimeoutMs = Math.min(o.approvalTimeoutMs, MAX_APPROVAL_TIMEOUT_MS);
+        this.memberOf = o.memberOf;
         this.onAsk = o.onAsk;
         this.onAskGone = o.onAskGone;
         this.beforeAgentRun = o.beforeAgentRun;
@@ -293,7 +291,7 @@ export class Bridge {
             (!armed.input || armed.input(input))) {
             this.armed = undefined;
             // '' when unattributable: never a member id (B2).
-            const member = memberOfKey(key) ?? '';
+            const member = this.memberOf(key) ?? '';
             const runRef = { sessionKey: key, member };
             return void this.gateRun(socket, runRef, tool, input);
         }
@@ -389,7 +387,7 @@ export class Bridge {
         }
         if (!this.host)
             return this.reply(socket, { ok: false, reason: "can't run this action right now" });
-        const run = this.runs.get(key) ?? { sessionKey: key, member: memberOfKey(key) ?? '' };
+        const run = this.runs.get(key) ?? { sessionKey: key, member: this.memberOf(key) ?? '' };
         // The plugin destroys its socket when the run aborts (run abort, hook timeout); without this the host's
         // sandboxed command keeps running after the tool is gone.
         const controller = new AbortController();

package/dist/config.js

@@ -52,6 +52,16 @@ export function reconcileConfig(saved, o) {
     c.agents.defaults.authInheritance = { agentId: BASE_AGENT };
     c.agents.defaults.models ??= {};
     c.agents.defaults.models['openai/*'] = { ...c.agents.defaults.models['openai/*'], agentRuntime: { id: 'openclaw' } };
+    // With no policy record the pin reads the `models` keys above as a legacy allowlist and materializes
+    // `modelPolicy.allow: ['openai/*']` on boot, so a member's OpenCode Go (any non-OpenAI) model fell back to
+    // openai. An empty record restricts nothing; the exact list that migration wrote is dropped unless the app sets one.
+    if (!o.app?.agents?.defaults?.modelPolicy) {
+        const policy = c.agents.defaults.modelPolicy;
+        if (!object(policy))
+            c.agents.defaults.modelPolicy = {};
+        else if (Array.isArray(policy.allow) && policy.allow.length === 1 && policy.allow[0] === 'openai/*')
+            delete policy.allow;
+    }
     const allow = c.agents.defaults.modelPolicy?.allow;
     if (Array.isArray(allow) && allow.length && !allow.includes('openai/*'))
         allow.push('openai/*');

package/dist/constants.d.ts

@@ -1,3 +1,4 @@
 export declare const ENGINE_VERSION = "2026.8.35";
 export declare const PROTOCOL_VERSION = 4;
+export declare const LIVE_CATALOGS: string[];
 export declare const OPERATOR_SCOPES: readonly ["operator.read", "operator.write", "operator.admin", "operator.approvals", "operator.questions", "operator.pairing", "operator.talk"];

package/dist/constants.js

@@ -2,6 +2,8 @@
 // `needs-update`, never silently run.
 export const ENGINE_VERSION = '2026.8.35';
 export const PROTOCOL_VERSION = 4;
+// Providers whose live catalog the kit registers (5.6); key choice uses the same catalog hook.
+export const LIVE_CATALOGS = ['opencode-go'];
 export const OPERATOR_SCOPES = [
     'operator.read',
     'operator.write',

package/dist/device.d.ts

@@ -2,7 +2,7 @@ import type { BrowserDevice, SignInRefusedWhy } from './browser.ts';
 import type { DeviceLink } from '@byokit/pair';
 import type { RouteView } from './routes.ts';
 import { type AccountView } from './words.ts';
-import type { Approval, Decision, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, KitState, RunEnd, OutputSchema, SchemaOutput, RunEvent, SignInView } from './types.ts';
+import type { Approval, Decision, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, KitState, RunEnd, OutputSchema, SchemaOutput, RunEvent, SignInView, AccountRef } from './types.ts';
 export type { GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult } from './types.ts';
 export type { Approval, Decision, KitState, PlanWindow, Route, RunEnd, RunEvent, RunUsage, SignInView, OutputSchema, SchemaOutput } from './types.ts';
 /** One `oc.events` frame: a member's Gateway event, typed by name, or an approval add/resolve (7.2). */
@@ -36,6 +36,8 @@ export type DeviceEndFrame<T = unknown> = {
 export type DeviceRunOptions<S extends OutputSchema | undefined = OutputSchema | undefined> = {
     schema?: S;
     sessionKey?: string;
+    account?: AccountRef | 'default' | 'auto';
+    needs?: string[];
     model?: string;
     auth?: 'apiKey';
     system?: string;
@@ -79,9 +81,7 @@ export type SignInNotice = {
 export declare function openSignInNotice(data: Record<string, unknown>, seed: Uint8Array): SignInNotice | null;
 /** Transient streams bypass link's durable request/answer cache: no lease nonce or frame is persisted. */
 export declare function browserDevice(link: DeviceLink): BrowserDevice;
-type DeviceRunEvent = Exclude<RunEvent, {
-    type: 'account';
-}>;
+type DeviceRunEvent = RunEvent;
 /** `openclawDevice`'s device surface: every `oc.*` op the computer answers, typed. */
 export type OpenClawDevice = {
     browser: BrowserDevice;

package/dist/device.js

@@ -1,4 +1,5 @@
 import { openBoxFromSeed, boxKeyPairFromSeed } from '@byokit/seal';
+import { memberOf } from "./attribution.js";
 import { toAccountView } from "./words.js";
 import { b64urlDecode, b64urlEncode, openNotice } from "./notices.js";
 /**
@@ -19,6 +20,13 @@ export class BrowserRefused extends LinkRefused {
     constructor(why) { super(`Sign-in refused: ${why}`); this.why = why; }
 }
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+// A session key this device sends must be shaped like one: `agent:<member>:` or an
+// `<member>--<hex6>` account agent's key (5.15). Anything else is refused before it reaches the computer.
+const checkKey = (sessionKey) => {
+    if (typeof sessionKey !== 'string' || !sessionKey.startsWith('agent:') || memberOf(sessionKey) === undefined)
+        throw new LinkRefused('Invalid session key');
+    return sessionKey;
+};
 /**
  * Newline-delimited JSON frames off a link stream, in order. A host end with an error becomes a
  * LinkRefused with the host's words (a refusal arrives after the stream opens, so it cannot ride
@@ -354,7 +362,9 @@ export function openclawDevice(link) {
         },
         sessions: () => link.request('oc.sessions'),
         run: (message, o) => {
-            const inner = liveStream(() => link.stream('oc.run', { message, ...(o?.sessionKey ? { sessionKey: o.sessionKey } : {}),
+            const inner = liveStream(() => link.stream('oc.run', { message, ...(o?.sessionKey ? { sessionKey: checkKey(o.sessionKey) } : {}),
+                ...(o?.account !== undefined ? { account: o.account } : {}),
+                ...(o?.needs !== undefined ? { needs: o.needs } : {}),
                 ...(o?.model !== undefined ? { model: o.model } : {}), ...(o?.system !== undefined ? { system: o.system } : {}),
                 ...(o?.auth !== undefined ? { auth: o.auth } : {}),
                 ...(o?.images !== undefined ? { images: o.images } : {}), ...(o?.thinking !== undefined ? { thinking: o.thinking } : {}),

package/dist/engine.js

@@ -256,7 +256,7 @@ export class Engine {
         const pluginDir = join(this.root, 'plugin');
         mkdirSync(pluginDir, { recursive: true, mode: 0o700 });
         // The shipped plugin follows the kit on every prepare too: a state dir from an older kit must not keep its gate.
-        for (const f of ['package.json', 'index.js', 'keys.js', 'usage.js', 'accounts.js']) {
+        for (const f of ['package.json', 'index.js', 'keys.js', 'usage.js', 'accounts.js', 'catalog.js']) {
             const source = join(kitDir, 'plugin', f);
             putChanged(join(pluginDir, f), readFileSync(source, 'utf8'));
         }

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export type { GatewayMethods } from './generated/methods.ts';
 export type { JsonValue } from './output.ts';
 export type { RouteFacts, RouteView } from './routes.ts';
 export { OpenClawKit, type KitOptions, type RetainedLogin } from './kit.ts';
-export type { AddKeyResult } from './keys.ts';
+export type { AddKeyResult, KeyFailureReason } from './keys.ts';
 export { stateWords, toAccountView, words, type AccountView, type WordKey } from './words.ts';
 export { chooseAccount, consider, resolveSelection, type RoomOf } from './pick.ts';
 export { AuthStoreUnreadableError, AuthStoreSealSizeError } from './auth-store.ts';

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;
@@ -138,7 +154,10 @@ export declare class OpenClawKit {
     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;