@byokit/openclaw 0.11.0 → 0.12.0

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',
@@ -432,6 +435,7 @@ export class OpenClawKit {
     greeting;
     members;
     locks = createLocks();
+    routeMap = new Map();
     accountsCtl;
     // One bridge and one approval surface per kit: listeners and run registrations survive reconnects (B3).
     // Only the socket itself is per-connection. Approvals always reaches the live transport through this.request().
@@ -442,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();
@@ -656,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) => {
@@ -691,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;
     }
@@ -699,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() {
@@ -745,13 +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,
-                ensure: (member) => this.ensureMember(member), locks: this.locks });
+            // 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),
+                routes: this.routeMap, log: this.o.log });
             // 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).
@@ -800,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))
@@ -836,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'))
@@ -850,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) {
@@ -905,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();
@@ -917,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);
@@ -926,13 +976,53 @@ export class OpenClawKit {
     signOut(member, provider) {
         return engineSignOut(this.signInCtx(), member, provider);
     }
-    // accounts (5.15, O14 step S5): the per-member index with listing, defaults and rename. Adding,
-    // removing, models, room, 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 S9-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, and `move`
+    // carries a conversation to another account. Removing arrives in a later step.
     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);
+    }
+    room(member, id, demand) {
+        if (!this.accountsCtl)
+            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).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'));
@@ -952,6 +1042,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);
@@ -975,6 +1096,9 @@ export class OpenClawKit {
             ensure: (member) => this.ensureMember(member),
             bridge: { register: (run, tools, runId) => this.bridge.register(run, tools && this.o.browser ? [...tools, 'request_sign_in'] : tools, runId) },
             tools: new Set(this.toolNames()),
+            ...(this.accountsCtl ? { accounts: this.accountsCtl } : {}),
+            locks: this.locks,
+            routes: this.routeMap,
         });
     }
     /** The app tool names (`KitOptions.tools`): the only names `RunSpec.tools` may carry. */
@@ -1005,10 +1129,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);
     }

package/dist/link.js

@@ -24,29 +24,32 @@ const isRecord = (value) => typeof value === 'object' && value !== null && !Arra
 const browserTag = (event) => event === 'byokit.browser';
 const browserEvent = (event, payload) => event === 'byokit.browser' && isRecord(payload) && typeof payload.member === 'string'
     && (payload.kind === 'state' || payload.kind === 'signin');
-const memberKey = (member, sessionKey) => sessionKey.startsWith(`agent:${member}:`);
-function memberSessions(result, member) {
+function memberSessions(result, owns) {
     const rows = Array.isArray(result) ? result : isRecord(result) && Array.isArray(result.sessions) ? result.sessions : [];
-    return rows.filter((row) => isRecord(row) && typeof row.sessionKey === 'string' && memberKey(member, row.sessionKey));
+    return rows.filter((row) => isRecord(row) && typeof row.sessionKey === 'string' && owns(row.sessionKey));
 }
 /** `oc.run`'s run options, type-checked; the kit's own checks (account, tool names) still apply. */
 function runOptions(args) {
-    const { message, model, auth, system, images, thinking, tools, schema } = args;
+    const { message, model, account, needs, auth, system, images, thinking, tools, schema } = args;
     const ok = typeof message === 'string'
         && (model === undefined || typeof model === 'string')
+        && (account === undefined || typeof account === 'string')
+        && (needs === undefined || (Array.isArray(needs) && needs.every((n) => typeof n === 'string')))
         && (auth === undefined || auth === 'apiKey')
         && (system === undefined || typeof system === 'string')
         && (images === undefined || (Array.isArray(images) && images.every((i) => isRecord(i) && typeof i.data === 'string' && typeof i.mimeType === 'string')))
         && (thinking === undefined || (typeof thinking === 'string' && THINKING.has(thinking)))
         && (tools === undefined || (Array.isArray(tools) && tools.every((t) => typeof t === 'string')));
     if (!ok)
-        throw new Error('oc.run needs { message, sessionKey?, model?, auth?, system?, images?, thinking?, tools?, schema? }');
+        throw new Error('oc.run needs { message, sessionKey?, model?, account?, needs?, auth?, system?, images?, thinking?, tools?, schema? }');
     if (schema !== undefined)
         outputSchema(schema);
     return {
         message: message,
         ...(schema === undefined ? {} : { schema: schema }),
         ...(model === undefined ? {} : { model: model }),
+        ...(account === undefined ? {} : { account: account }),
+        ...(needs === undefined ? {} : { needs: [...needs] }),
         ...(auth === undefined ? {} : { auth: 'apiKey' }),
         ...(system === undefined ? {} : { system: system }),
         ...(images === undefined ? {} : { images: images
@@ -74,6 +77,7 @@ function browserInput(value) {
 }
 export function openclawLink(kit, o) {
     const passThrough = o.passThrough ?? (() => false);
+    const memberKey = (member, sessionKey) => kit.memberOf(sessionKey) === member;
     // The host lifecycle extension is supplied by the browser host. Without it control fails closed.
     const browser = () => {
         if (!kit.browser)
@@ -120,10 +124,14 @@ export function openclawLink(kit, o) {
         if (grant.expires !== undefined) {
             const timer = setTimeout(() => {
                 const current = seen.get(grant.id);
-                if (current?.expires !== undefined && current.expires > Date.now())
-                    memberOf(current);
-                else
-                    void revoke(grant.id).catch(() => { });
+                if (current?.expires !== undefined && current.expires > Date.now()) {
+                    try {
+                        memberOf(current);
+                        return;
+                    }
+                    catch { /* refused at the boundary: revoke below, never throw from a timer */ }
+                }
+                void revoke(grant.id).catch(() => { });
             }, Math.min(grant.expires - Date.now(), 2 ** 31 - 1));
             timer.unref();
             expiry.set(grant.id, timer);
@@ -355,7 +363,7 @@ export function openclawLink(kit, o) {
             }
             case 'oc.sessions': {
                 const result = await kit.call('sessions.list', {});
-                return memberSessions(result, member);
+                return memberSessions(result, (key) => memberKey(member, key));
             }
             case 'oc.steer': {
                 if (typeof args.sessionKey !== 'string' || typeof args.text !== 'string' || (args.auth !== undefined && args.auth !== 'apiKey'))
@@ -584,9 +592,11 @@ export function openclawLink(kit, o) {
                         void s.write(`${JSON.stringify({ event: 'byokit.browser', payload: { member, kind: record.kind } })}\n`).catch(() => { });
                     return;
                 }
+                // Attribution (5.15): an `<member>--<hex6>` account agent's events are the member's.
                 const agent = record?.agentId;
                 const key = record?.sessionKey;
-                if (agent !== member && !(typeof key === 'string' && memberKey(member, key)))
+                if (!(typeof agent === 'string' && kit.memberOf(agent) === member)
+                    && !(typeof key === 'string' && memberKey(member, key)))
                     return;
                 void s.write(`${JSON.stringify({ event, payload })}\n`).catch(() => { });
             });

package/dist/members.d.ts

@@ -1,8 +1,11 @@
 import type { GatewayTransport, Member } from './types.ts';
 export declare const MEMBER_ID: RegExp;
+export declare const NEW_MEMBER_ID: RegExp;
 export declare const KEY_PREFIX = "byokit-key-";
 export declare const BASE_AGENT = "byokit-base";
 export declare const keyAgentId: (member: Member) => string;
+/** Resolves once agents.list shows `id`, which agents.create answers before. */
+export declare function untilListed(request: GatewayTransport['request'], id: string): Promise<void>;
 export declare function createMembers(ctx: {
     request: GatewayTransport['request'];
     root: string;

package/dist/members.js

@@ -2,7 +2,7 @@ import { join } from 'node:path';
 // Any member that may run: D9's older rule, which a member created before O14 still matches (D17).
 export const MEMBER_ID = /^[a-z][a-z0-9-]{0,31}$/;
 // D9 for a member the kit creates: no `--` (account agents are `<member>--<6 hex>`) and at most 24 characters.
-const NEW_MEMBER_ID = /^[a-z](?!.*--)[a-z0-9-]{0,23}$/;
+export const NEW_MEMBER_ID = /^[a-z](?!.*--)[a-z0-9-]{0,23}$/;
 export const KEY_PREFIX = 'byokit-key-';
 // The inherited auth base every agent reads through (5.15): the kit never creates, signs in to or runs it.
 export const BASE_AGENT = 'byokit-base';
@@ -13,9 +13,18 @@ export const keyAgentId = (member) => `${KEY_PREFIX}${member}`;
 // at once fails as 'unknown agent id'. ensure resolves only once agents.list shows the member.
 const VISIBLE_TIMEOUT_MS = 5_000;
 const VISIBLE_POLL_MS = 25;
+const listed = (request, id) => request('agents.list').then((list) => list.agents.some((agent) => agent.id === id));
+/** Resolves once agents.list shows `id`, which agents.create answers before. */
+export async function untilListed(request, id) {
+    const deadline = Date.now() + VISIBLE_TIMEOUT_MS;
+    while (!await listed(request, id)) {
+        if (Date.now() >= deadline)
+            throw new Error(`agent ${id} is not listed by agents.list after agents.create`);
+        await new Promise((resolve) => setTimeout(resolve, VISIBLE_POLL_MS));
+    }
+}
 export function createMembers(ctx) {
     const cache = new Map();
-    const listed = (member) => ctx.request('agents.list').then((list) => list.agents.some((agent) => agent.id === member));
     return { ensure(member) {
             const invalid = () => new Error(`invalid member id: ${member}`);
             if (!MEMBER_ID.test(member) || member.startsWith(KEY_PREFIX) || RESERVED.has(member))
@@ -25,16 +34,11 @@ export function createMembers(ctx) {
                 return existing;
             const workspace = join(ctx.root, 'workspaces', member);
             const result = (async () => {
-                if (!await listed(member)) {
+                if (!await listed(ctx.request, member)) {
                     if (!NEW_MEMBER_ID.test(member) || member.startsWith('byokit-'))
                         throw invalid();
                     await ctx.request('agents.create', { name: member, workspace });
-                    const deadline = Date.now() + VISIBLE_TIMEOUT_MS;
-                    while (!await listed(member)) {
-                        if (Date.now() >= deadline)
-                            throw new Error(`agent ${member} is not listed by agents.list after agents.create`);
-                        await new Promise((resolve) => setTimeout(resolve, VISIBLE_POLL_MS));
-                    }
+                    await untilListed(ctx.request, member);
                 }
                 return { agentId: member, workspace };
             })();

package/dist/pick.d.ts

@@ -1,11 +1,15 @@
 import type { Account, AccountId, AccountPick, Considered, Defaults, ModelInfo, PickWhy, Room, RunSelection } from './types.ts';
 export type RoomOf = (a: Account, demand: readonly string[]) => Room;
+/** The lowercased provider of a well-formed `provider/model` reference; undefined when the reference is malformed. */
+export declare function providerOf(model: string): string | undefined;
 /** Every account's `Considered` row, in list order, with the kit-only `bound` applied. */
-export declare function consider(accounts: readonly Account[], defaults: Defaults, sel: RunSelection, room: RoomOf, nowMs: number, models?: (a: Account) => readonly ModelInfo[], bound?: readonly AccountId[]): Considered[];
+export declare function consider(accounts: readonly Account[], defaults: Defaults, sel: RunSelection, room: RoomOf, nowMs: number, models?: (a: Account) => readonly ModelInfo[] | undefined, bound?: readonly AccountId[]): Considered[];
 /** Auto's winner only; `candidates` are the eligible accounts. Pure and portable; no timers, reads or mid-run switching. */
 export declare function chooseAccount(candidates: readonly Account[], room: (a: Account) => Room, nowMs: number): {
     account: Account;
     why: PickWhy;
 } | undefined;
-/** Resolve once before starting. Without `models`, membership is host-validated and a missing model is ''. */
-export declare function resolveSelection(accounts: readonly Account[], defaults: Defaults, sel: RunSelection, room: RoomOf, nowMs: number, models?: (a: Account) => readonly ModelInfo[], bound?: readonly AccountId[]): AccountPick;
+/** Resolve once before starting. Without `models`, membership is host-validated and a missing model is ''. A row whose
+ * models are unknown (`undefined`) host-validates membership by provider; with no model asked for it runs the saved
+ * default, else model '' (no override: the engine's own default). */
+export declare function resolveSelection(accounts: readonly Account[], defaults: Defaults, sel: RunSelection, room: RoomOf, nowMs: number, models?: (a: Account) => readonly ModelInfo[] | undefined, bound?: readonly AccountId[]): AccountPick;

package/dist/pick.js

@@ -1,6 +1,11 @@
 import { words } from "./words.js";
 const DAY_MS = 24 * 60 * 60 * 1000;
 const finite = (n) => typeof n === 'number' && Number.isFinite(n);
+/** The lowercased provider of a well-formed `provider/model` reference; undefined when the reference is malformed. */
+export function providerOf(model) {
+    const at = model.indexOf('/');
+    return at <= 0 || at === model.length - 1 || /[\s@]/.test(model) ? undefined : model.slice(0, at).toLowerCase();
+}
 const reset = (r) => r.resetsAt ?? Infinity;
 const roomWords = (left, span) => words(`room.${span}`, { left: `${Math.round(left)}%` });
 // "3:40pm", or "Fri 3:40pm" when it isn't today (matches @byokit/accounts' clock).
@@ -35,8 +40,18 @@ function considerRows(accounts, room, nowMs, demand = [], models, provider, name
             else if (account.billing !== 'subscription')
                 row.out = 'billing';
         }
+        if (!row.out && models) {
+            const listed = models(account) ?? [];
+            if (listed.length && listed.every((m) => m.why === 'resting')) {
+                row.out = 'resting';
+                const untils = listed.map((m) => m.until).filter(finite);
+                if (untils.length)
+                    row.until = Math.min(...untils);
+            }
+        }
         if (!row.out && demand.length && models) {
-            const available = models(account);
+            const available = models(account) ?? demand.filter((id) => id.split('/')[0].toLowerCase() === account.provider.toLowerCase())
+                .map((id) => ({ id, name: id, available: true }));
             const missing = demand.find((id) => !available.some((m) => m.id === id && m.available));
             if (missing !== undefined) {
                 row.out = 'model';
@@ -105,7 +120,9 @@ function nameOf(accounts, defaults, sel, bound) {
         (bound === undefined || bound.includes(defaultAccount.id));
     return sel.account === 'default' ? (usable ? defaultAccount.id : undefined) : sel.account === 'auto' ? undefined : sel.account;
 }
-/** Resolve once before starting. Without `models`, membership is host-validated and a missing model is ''. */
+/** Resolve once before starting. Without `models`, membership is host-validated and a missing model is ''. A row whose
+ * models are unknown (`undefined`) host-validates membership by provider; with no model asked for it runs the saved
+ * default, else model '' (no override: the engine's own default). */
 export function resolveSelection(accounts, defaults, sel, room, nowMs, models, bound) {
     const demand = [...new Set([...(sel.model ? [sel.model] : []), ...(sel.needs ?? [])])];
     const defaultAccount = accounts.find((a) => a.id === defaults.account);
@@ -114,10 +131,14 @@ export function resolveSelection(accounts, defaults, sel, room, nowMs, models, b
     const rows = considerRows(accounts, (a) => room(a, demand), nowMs, demand, models, provider, named, bound);
     const considered = rows.map((c) => c.row);
     const auto = rank(rows); // also fills explanations for every eligible row, even on explicit selection
+    const restingPick = (c) => ({ ok: false, code: 'resting', account: c.account.id, until: c.row.until,
+        reason: words('pick.out.resting', { time: finite(c.row.until) ? clock(c.row.until) : '' }), considered });
     if (named !== undefined) {
         const chosen = rows.find((c) => c.account.id === named);
         if (!chosen)
             return { ok: false, code: 'unknown_account', reason: words('auto.none', { provider: provider ?? '' }), considered };
+        if (chosen.row.out === 'resting')
+            return restingPick(chosen);
         if (chosen.row.out)
             return { ok: false, code: 'not_included', reason: words(`pick.out.${chosen.row.out}`, { model: chosen.row.missing ?? '' }), considered };
         return finish(chosen.account, chosen.row, sel.account === 'default' ? 'default' : 'chosen', sel.account === 'default' ? 'default' : 'chosen');
@@ -129,11 +150,19 @@ export function resolveSelection(accounts, defaults, sel, room, nowMs, models, b
     }
     else if (auto)
         return finish(auto.account, auto.row, 'auto', auto.why);
+    const eligible = rows.filter((c) => !c.row.out || c.row.out === 'resting');
+    const rests = eligible.filter((c) => c.row.out === 'resting');
+    if (rests.length)
+        return restingPick(rests.reduce((a, b) => ((b.row.until ?? Infinity) < (a.row.until ?? Infinity) ? b : a)));
     return { ok: false, code: 'none', reason: words('auto.none', { provider: provider ?? '' }), considered };
     function finish(account, row, how, why) {
-        const available = models?.(account).filter((m) => m.available);
-        const model = sel.model ?? (defaults.model && (!available || available.some((m) => m.id === defaults.model)) ? defaults.model : available?.[0]?.id) ?? '';
-        if (models && !model)
+        const listed = models?.(account);
+        const ready = listed?.filter((m) => m.available && !m.why);
+        const usable = ready?.length ? ready : listed?.filter((m) => m.available && m.why === 'signed_out');
+        const saved = defaults.model && (usable ? usable.some((m) => m.id === defaults.model)
+            : providerOf(defaults.model) === account.provider.toLowerCase()) ? defaults.model : undefined;
+        const model = sel.model ?? saved ?? usable?.[0]?.id ?? '';
+        if (listed && !model)
             return { ok: false, code: 'not_included', reason: words('pick.out.model', { model: sel.model ?? '' }), considered };
         row.reason = why;
         const slots = { name: account.name, provider: account.provider };

package/dist/routes.d.ts

@@ -17,5 +17,6 @@ export type RouteView = Route & {
 export declare function routes(facts?: RouteFacts): RouteView[];
 /** Retain explicit legacy selectors alongside corrected discovery metadata. A native CLI selector still
  * reaches engine detection (which checks its own login); it does not make an unavailable route default.
+ * An offered plan key is served whichever way was asked: it is always the pasted key.
  * API billing is never picked as a fallback. */
 export declare function routeFor(provider: string, via: 'browser' | 'code'): Route | undefined;

package/dist/routes.js

@@ -41,9 +41,11 @@ export function routes(facts = {}) {
 }
 /** Retain explicit legacy selectors alongside corrected discovery metadata. A native CLI selector still
  * reaches engine detection (which checks its own login); it does not make an unavailable route default.
+ * An offered plan key is served whichever way was asked: it is always the pasted key.
  * API billing is never picked as a fallback. */
 export function routeFor(provider, via) {
-    return table.find(route => route.billing === 'subscription' && route.offerPolicy === 'default'
-        && ((route.offer && route.provider === provider && route.via === via)
-            || (route.legacy?.provider === provider && route.legacy.via === via)));
+    const served = table.filter(route => route.billing === 'subscription' && route.offerPolicy === 'default');
+    return served.find(route => (route.offer && route.provider === provider && route.via === via)
+        || (route.legacy?.provider === provider && route.legacy.via === via))
+        ?? served.find(route => route.offer && route.provider === provider && route.keyEntry);
 }