@byokit/openclaw 0.10.0 → 0.11.1

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 { Approval, CallOptions, Decision, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, Hello, KitState, KitEventName, KitEventPayload, LearningCapture, LearningMode, Member, RunEnd, RunEvent, RunSpec, OutputSchema, SchemaOutput, SignInOptions, SignInView, ToolHost, ToolSpec } from './types.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';
 export type KitOptions = {
     stateDir: string;
     authSeal?: SealingAdapter;
@@ -54,6 +54,9 @@ export declare class OpenClawKit {
     private transport?;
     private greeting?;
     private members?;
+    private readonly locks;
+    private readonly routeMap;
+    private accountsCtl?;
     private readonly bridge;
     private readonly keys;
     private readonly admission;
@@ -110,6 +113,27 @@ export declare class OpenClawKit {
         done: Promise<SignInView>;
     };
     signOut(member: Member, provider: string): Promise<void>;
+    accounts(member: Member): Promise<Account[]>;
+    models(member: Member, id: AccountId): Promise<ModelInfo[]>;
+    room(member: Member, id: AccountId, demand?: string[]): Promise<Room>;
+    /** 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;
+        via?: 'browser' | 'code';
+        name?: string;
+        again?: AccountId;
+    }, on: (v: SignInView) => void): Promise<{
+        id: AccountId;
+        paste(text: string): void;
+        cancel(): void;
+        done: Promise<{
+            view: SignInView;
+            id: AccountId;
+        }>;
+    }>;
+    renameAccount(member: Member, id: AccountId, name: string): Promise<Account>;
+    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;

package/dist/kit.js

@@ -10,6 +10,8 @@ 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 { 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";
@@ -429,6 +431,9 @@ export class OpenClawKit {
     transport;
     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().
     bridge;
@@ -741,6 +746,10 @@ 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,
+                signIn: (agentId, o, on, fresh) => startSignIn({ ...this.signInCtx(), ensure: async () => ({ agentId }), fresh }, agentId, o, on),
+                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)));
@@ -789,6 +798,7 @@ export class OpenClawKit {
         this.transport = undefined;
         this.greeting = undefined;
         this.members = undefined;
+        this.accountsCtl = undefined;
         this.browserPolicySessions.clear();
         this.bridge.stop();
         await transport?.stop();
@@ -919,6 +929,44 @@ 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.
+    accounts(member) {
+        if (!this.accountsCtl)
+            return Promise.reject(new Error('gateway not ready'));
+        return this.accountsCtl.list(member);
+    }
+    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);
+    }
+    /** 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);
+    }
+    renameAccount(member, id, name) {
+        if (!this.accountsCtl)
+            return Promise.reject(new Error('gateway not ready'));
+        return this.accountsCtl.rename(member, id, name);
+    }
+    defaults(member) {
+        if (!this.accountsCtl)
+            return Promise.reject(new Error('gateway not ready'));
+        return this.accountsCtl.defaults(member);
+    }
+    setDefaults(member, d) {
+        if (!this.accountsCtl)
+            return Promise.reject(new Error('gateway not ready'));
+        return this.accountsCtl.setDefaults(member, d);
+    }
     /** Save an explicitly supplied API key (billed per use) in this member's separate key agent. */
     addKey(agentId, o) {
         return this.keys.add(agentId, o);
@@ -946,6 +994,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. */

package/dist/locks.d.ts

@@ -0,0 +1,5 @@
+export declare function createLocks(): {
+    shared<T>(agentId: string, work: () => Promise<T>): Promise<T>;
+    exclusive<T>(agentIds: string[], work: () => Promise<T>): Promise<T>;
+    live(agentId: string): boolean;
+};

package/dist/locks.js

@@ -0,0 +1,85 @@
+export function createLocks() {
+    const slots = new Map();
+    const slot = (id) => {
+        let s = slots.get(id);
+        if (!s) {
+            s = { readers: 0, writer: false, queue: [] };
+            slots.set(id, s);
+        }
+        return s;
+    };
+    // FIFO: an exclusive waiter blocks later shared waiters until the readers ahead of it drain.
+    const pump = (s) => {
+        if (s.writer)
+            return;
+        const head = s.queue[0];
+        if (!head)
+            return;
+        if (head.mode === 'exclusive') {
+            if (s.readers === 0) {
+                s.queue.shift();
+                s.writer = true;
+                head.grant();
+            }
+            return;
+        }
+        while (s.queue[0]?.mode === 'shared') {
+            const w = s.queue.shift();
+            s.readers++;
+            w.grant();
+        }
+    };
+    const acquire = (id, mode) => {
+        const s = slot(id);
+        if (mode === 'shared' && !s.writer && s.queue.every((w) => w.mode === 'shared')) {
+            s.readers++;
+            return Promise.resolve();
+        }
+        if (mode === 'exclusive' && !s.writer && s.readers === 0 && s.queue.length === 0) {
+            s.writer = true;
+            return Promise.resolve();
+        }
+        return new Promise((grant) => {
+            s.queue.push(mode === 'exclusive' ? { mode, grant: () => { s.writer = true; grant(); } } : { mode, grant });
+            pump(s);
+        });
+    };
+    const release = (id, mode) => {
+        const s = slot(id);
+        if (mode === 'shared')
+            s.readers = Math.max(0, s.readers - 1);
+        else
+            s.writer = false;
+        pump(s);
+        if (s.readers === 0 && !s.writer && s.queue.length === 0)
+            slots.delete(id);
+    };
+    return {
+        async shared(agentId, work) {
+            await acquire(agentId, 'shared');
+            try {
+                return await work();
+            }
+            finally {
+                release(agentId, 'shared');
+            }
+        },
+        async exclusive(agentIds, work) {
+            // Sorted so two exclusive takes over overlapping sets cannot deadlock each other.
+            const ids = [...new Set(agentIds)].sort();
+            for (const id of ids)
+                await acquire(id, 'exclusive');
+            try {
+                return await work();
+            }
+            finally {
+                for (const id of [...ids].reverse())
+                    release(id, 'exclusive');
+            }
+        },
+        live(agentId) {
+            const s = slots.get(agentId);
+            return !!s && (s.readers > 0 || s.writer);
+        },
+    };
+}

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/runs.d.ts

@@ -1,4 +1,6 @@
 import type { Bridge } from './bridge.ts';
+import type { createAccounts } from './accounts.ts';
+import type { createLocks } from './locks.ts';
 import { authStatus } from './auth-status.ts';
 import { outputSchema, type OutputSchema, type SchemaOutput } from './output.ts';
 import type { GatewayTransport, Member, RunEnd, RunEvent, RunSpec } from './types.ts';
@@ -18,6 +20,11 @@ export declare function createRuns(ctx: {
     }>;
     bridge: Pick<Bridge, 'register'>;
     tools: ReadonlySet<string>;
+    accounts?: Pick<ReturnType<typeof createAccounts>, 'pick' | 'rest'>;
+    locks?: ReturnType<typeof createLocks>;
+    routes: Map<string, {
+        session: string;
+    }>;
 }): {
     run<const S extends OutputSchema | undefined = undefined>(spec: RunSpec<S>, on?: (e: RunEvent) => void, keyAgent?: string, preparedOutput?: ReturnType<typeof outputSchema>): Promise<RunEnd<SchemaOutput<S>>>;
     steer(k: string, t: string): Promise<void>;

package/dist/runs.js

@@ -5,12 +5,15 @@ import { authStatus } from "./auth-status.js";
 import { outputSchema } from "./output.js";
 import { words } from "./words.js";
 import { classify } from "./classify.js";
+import { providerOf } from "./pick.js";
 // The gateway gives up on a silent run after an hour; we wait ten minutes longer for the reply frame itself.
 const WAIT_MS = 3_600_000;
 const WAIT_CLIENT_MS = 3_610_000;
 // The `agent` request's final frame lands with the run's end; a run already over waits no longer than this for it.
 const FINAL_GRACE_MS = 5_000;
 const STATUS_MS = 5_000;
+// A resting end whose message names no time rests the account this long (5.15 Runs step 7).
+const REST_MS = 300_000;
 export const USABLE = new Set(['ok', 'expiring', 'static']);
 const usable = (row) => typeof row === 'string'
     || (Array.isArray(row.profiles) && row.profiles.length > 0 ? row.profiles.some((p) => USABLE.has(String(p?.status)))
@@ -62,10 +65,10 @@ function planOf(provider, row) {
  * a session preference it may rotate away from (docs/runtime-kits.md 5.8), so the kit never sends one.
  */
 function account(model) {
-    const at = model.indexOf('/');
-    if (at <= 0 || at === model.length - 1 || /[\s@]/.test(model))
+    const provider = providerOf(model);
+    if (provider === undefined)
         throw new Error(`refused: "${model}" is not a provider/model reference`);
-    return { provider: model.slice(0, at).toLowerCase(), model: model.slice(at + 1) }; // the engine lowercases ids
+    return { provider, model: model.slice(model.indexOf('/') + 1) }; // the engine lowercases ids
 }
 export function createRuns(ctx) {
     // The plan window the engine last read for the run's provider: `models.authStatus` answers from its cache without
@@ -97,11 +100,83 @@ export function createRuns(ctx) {
         const output = preparedOutput ?? (spec.schema === undefined ? undefined : outputSchema(spec.schema));
         const system = [spec.system, output?.prompt].filter(Boolean).join('\n\n');
         const picked = spec.model === undefined ? undefined : account(spec.model);
+        for (const need of spec.needs ?? [])
+            account(need);
         for (const tool of spec.tools ?? [])
             if (!ctx.tools.has(tool))
                 throw new Error(`refused: "${tool}" is not one of this kit's tools`);
-        const agentId = keyAgent ?? (await ctx.ensure(spec.member)).agentId;
-        const sessionKey = keyAgent ? `agent:${keyAgent}:${spec.sessionKey.slice(`agent:${spec.member}:`.length)}` : spec.sessionKey;
+        const tail = spec.sessionKey.slice(`agent:${spec.member}:`.length);
+        // Runs step 3 (5.15): with `account` and `needs` both absent, exactly the run on the member agent it always was.
+        if (spec.account === undefined && !spec.needs?.length) {
+            const agentId = keyAgent ?? (await ctx.ensure(spec.member)).agentId;
+            return start(spec, on, { agentId, sessionKey: keyAgent ? `agent:${keyAgent}:${tail}` : spec.sessionKey, idempotencyKey, system, picked, output });
+        }
+        if (keyAgent)
+            throw new Error('refused: an API-key run uses its own account');
+        if (!ctx.accounts || !ctx.locks)
+            throw new Error('gateway not ready');
+        const accounts = ctx.accounts;
+        const locks = ctx.locks;
+        const restAccount = async (id, until) => {
+            const at = until ?? Date.now() + REST_MS;
+            await accounts.rest(spec.member, id, at);
+            return at;
+        };
+        const signedIn = async (agentId, provider) => !!(await ctx.request('byokit.accounts', { action: 'ready', agentId, provider })).ok;
+        const skipped = [];
+        for (;;) {
+            // Step 4: the selection is resolved once per attempt, before any request; `needs` alone resolves as 'default'.
+            const { pick, agent } = await accounts.pick(spec.member, { account: spec.account ?? 'default',
+                ...(spec.model !== undefined ? { model: spec.model } : {}), ...(spec.needs ? { needs: spec.needs } : {}) }, skipped);
+            if (!pick.ok) {
+                if (pick.code === 'unknown_account')
+                    throw new Error(`unknown account: ${spec.account}`); // a caller bug
+                if (pick.code === 'resting')
+                    return { ok: false, kind: 'resting', until: await restAccount(pick.account, pick.until), message: pick.reason };
+                return { ok: false, kind: pick.code === 'none' ? 'signed-out' : pick.code === 'not_included' ? 'plan' : 'other', message: pick.reason };
+            }
+            const sessionKey = `agent:${agent}:${tail}`;
+            const automatic = pick.how === 'auto' || pick.why === 'first_ready';
+            // An unbound key runs on the picked account's agent, under the app key's tail. The run holds the agent's shared
+            // lock from its ready check to its end. An automatic pick not signed in is skipped before any event; an explicit
+            // one announces itself, then ends signed-out.
+            const end = await locks.shared(agent, async () => {
+                let ready;
+                try {
+                    ready = await signedIn(agent, pick.account.provider);
+                }
+                catch (error) {
+                    return failure(error instanceof Error ? error.message : String(error));
+                }
+                if (!ready && automatic)
+                    return undefined;
+                const route = { session: sessionKey };
+                ctx.routes.set(spec.sessionKey, route);
+                try {
+                    on?.({ type: 'account', account: pick.account.id, model: pick.model, sessionKey, how: pick.how, why: pick.why, considered: pick.considered });
+                    if (!ready)
+                        return { ok: false, kind: 'signed-out', message: `${pick.account.name} is not signed in` };
+                    return await start(spec, on, { agentId: agent, sessionKey, idempotencyKey, system,
+                        picked: pick.model ? account(pick.model) : undefined, output, chosen: pick }); // '' = no override
+                }
+                finally {
+                    if (ctx.routes.get(spec.sessionKey) === route)
+                        ctx.routes.delete(spec.sessionKey);
+                }
+            });
+            if (end === undefined) {
+                skipped.push(pick.account.id);
+                continue;
+            }
+            // Step 7: a resting end rests the account, so the next Auto skips it until then.
+            if (end.ok || !('kind' in end) || end.kind !== 'resting')
+                return end;
+            const until = await restAccount(pick.account.id, end.until);
+            return { ...end, until };
+        }
+    };
+    const start = async (spec, on, t) => {
+        const { agentId, sessionKey, idempotencyKey, system, picked, output, chosen } = t;
         const release = spec.register !== false ? ctx.bridge.register({ sessionKey, member: spec.member }, spec.tools, idempotencyKey) : undefined;
         let last;
         let runId = ''; // gateway events for other runs carry a real runId and never match the empty one
@@ -140,7 +215,7 @@ export function createRuns(ctx) {
             }
         });
         try {
-            if (picked) {
+            if (picked && !chosen) {
                 // The picked account must be the one called: check it is signed in for this member before the run, since
                 // the engine would otherwise fail the run only after admitting it. An explicit provider/model is strict on
                 // the pinned engine (never another provider or model), so this check plus the override is the guarantee.
@@ -207,7 +282,10 @@ export function createRuns(ctx) {
                 const usage = usageOf(agentMeta);
                 const planWindow = typeof agentMeta.provider === 'string'
                     ? await planWindowOf(agentId, agentMeta.provider.toLowerCase()) : undefined;
-                return { ok: true, text, ...(parsed ? { data: parsed.data } : {}), ...(usage ? { usage } : {}), ...(planWindow ? { planWindow } : {}) };
+                const reported = typeof agentMeta.provider === 'string' && typeof agentMeta.model === 'string'
+                    ? `${agentMeta.provider}/${agentMeta.model}`.toLowerCase() : '';
+                return { ok: true, text, ...(parsed ? { data: parsed.data } : {}), ...(usage ? { usage } : {}), ...(planWindow ? { planWindow } : {}),
+                    ...(chosen ? { account: chosen.account.id, model: chosen.model || reported } : {}) };
             }
             if (result.stopReason === 'aborted' || (abortedByEngine && result.status !== 'ok'))
                 return { ok: false, aborted: true };
@@ -227,7 +305,7 @@ export function createRuns(ctx) {
     };
     return {
         run,
-        steer: (k, t) => ctx.request('sessions.steer', { sessionKey: k, message: t }),
-        abort: async (k) => { await ctx.request('chat.abort', { sessionKey: k }); },
+        steer: (k, t) => ctx.request('sessions.steer', { sessionKey: ctx.routes.get(k)?.session ?? k, message: t }),
+        abort: async (k) => { await ctx.request('chat.abort', { sessionKey: ctx.routes.get(k)?.session ?? k }); },
     };
 }

package/dist/signin.d.ts

@@ -8,6 +8,7 @@ export type SignInCtx = {
     }>;
     callbackPort: number;
     onDisconnect?(fn: () => void): () => void;
+    fresh?: boolean;
 };
 /**
  * Drive the engine's provider-owned login. `on` sees every view the person watches; `done` resolves once, and

package/dist/signin.js

@@ -41,6 +41,16 @@ export function signIn(ctx, member, o, on) {
     const { signal } = owner;
     const driveOwner = new AbortController();
     const wantsCallback = via === 'browser' && o.authChoice === 'openai';
+    // The pin builds ChatGPT's authorize URL unsigned, so a fresh sign-in can ask for the login screen itself.
+    const shown = (url) => {
+        if (!ctx.fresh || !wantsCallback)
+            return url;
+        const parsed = URL.canParse(url) ? new URL(url) : undefined;
+        if (parsed?.origin !== 'https://auth.openai.com' || parsed.pathname !== '/oauth/authorize')
+            return url;
+        parsed.searchParams.set('prompt', 'login');
+        return parsed.toString();
+    };
     let server;
     let sessionId = '';
     let starting;
@@ -295,7 +305,7 @@ export function signIn(ctx, member, o, on) {
                     codeTimer = setTimeout(() => { codeExpired = true; owner.abort(); }, duration);
                 const message = deviceCode.message ?? current.message;
                 // The code is on the card; acknowledging it lets the engine poll the provider itself.
-                say({ ...(deviceCode.code ? { code: deviceCode.code } : {}), ...(current.externalUrl ? { url: current.externalUrl } : {}),
+                say({ ...(deviceCode.code ? { code: deviceCode.code } : {}), ...(current.externalUrl ? { url: shown(current.externalUrl) } : {}),
                     ...(timed ? { expiresAt: Date.now() + duration } : {}), ...(message ? { message } : {}) });
                 const next = await answer(current);
                 if (next.done) {
@@ -326,7 +336,7 @@ export function signIn(ctx, member, o, on) {
             }
             if (current.type === 'note' || current.type === 'confirm' || current.type === 'select' || current.type === 'action') {
                 if (current.externalUrl)
-                    say({ url: current.externalUrl });
+                    say({ url: shown(current.externalUrl) });
                 const next = await answer(current);
                 if (next.done) {
                     terminal = next;

package/dist/testing/contract.js

@@ -18,7 +18,6 @@ const REQUIRED_METHODS = [
     'plugin.approval.resolve', 'question.resolve', 'wizard.cancel', 'wizard.next',
 ];
 // Driven by the kit but not advertised in hello (O11 probe, e.g. sessions.steer): routable, just not listed.
-// The engine job's generated.test.ts audits the full generated table against hello instead of asserting it here.
 const REQUIRED_EVENTS = [
     'agent',
     'exec.approval.requested', 'exec.approval.resolved',

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

@@ -20,6 +20,12 @@ export type FakeGateway = {
     failNext(method: string, message: string): void;
     drop(why: string): void;
     handle(method: string, fn: FakeHandler): void;
+    /** Usage windows a later `models.authStatus` read reports for the agent's provider (O14: the Auto input). */
+    setUsage(agentId: string, provider: string, windows: {
+        label: string;
+        usedPercent?: number;
+        resetAt?: number;
+    }[]): void;
 } & {
     transport: GatewayTransport;
 };