@byokit/openclaw 0.11.0 → 0.11.1

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## 0.11.1 (2026-10-12)
+
+- Dependency update: pins @byokit/discover 0.8.1.
+- FIX: (from @byokit/discover 0.8.1) `browse()` and `scan()` accept resolved services whose `fullName` carries the service type without a trailing dot (`host._type._tcp`, as Android's react-native-zeroconf delivers) or with a trailing `.local` domain suffix, case-insensitive, instead of only the `host.local._type._tcp.` shape. Android phones now discover computers over mDNS instead of always scanning empty.
+
+- FIX: restoring an engine home no longer rewrites a live file whose bytes already match the sealed object. `restore()` compares each decrypted object against the live file at the restore mode (0600) — size first, then bytes — and skips the temp write, file fsync, atomic rename and directory fsync when they match, so a start over an untouched tree pays no per-object writes. A missing, changed, different-mode or unreadable file restores exactly as before, and a skipped file changes nothing on disk, so the crash-durability contract is unchanged; nothing new is written to disk.
+- FEAT: OpenClaw kit S5 account spine: per-member `accounts/<member>.json` index (0600, atomic, no email/token/engine line) behind `kit.accounts`, `renameAccount` and `defaults`/`setDefaults`; a pre-O14 sign-in synthesizes an `addedAt: 0` entry, a default naming a removed account drops on read, and an unindexed `<member>--<hex6>` agent is never listed. `src/locks.ts` adds the per-agent shared/exclusive/live locks later steps use for runs, removal, moves and sealing.
+- FEAT: OpenClaw kit S6 `kit.addAccount(member, { authChoice, via?, name?, again? }, on)`: a member's first sign-in of a provider stays on its own agent, and each further one (or `again`) gets a new sealed agent `<member>--<hex6>` (drawn again on a collision) with account id `<provider>.<hex6>`, its index entry written before the agent and IDENTITY.md kept byte-identical. The ChatGPT authorize URL carries `prompt=login` so a second account can be chosen; the row reads `signing` until the sign-in ends; `done` comes only after the agent is sealed to that one sign-in and its `who` hash is indexed; a sign-in that fails, ends busy or is cancelled removes the new agent and its entry. `authChoice: 'openai-codex'` (the engine's id for ChatGPT) signs in on the `openai` route.
+- FEAT: OpenClaw kit S9 Auto input: `kit.models(member, id)` maps the account provider's `models.list { agentId, view: 'default' }` rows to `provider/model` (`missing-auth`/`auth-failed` → `why: 'signed_out'`, `cooldown` → `why: 'resting'` with `until = unavailableUntil`), and `kit.room(member, id, demand?)` reads the `models.authStatus { agentId }` row for the provider's tightest applying usage window (`left`, `span`, `resetsAt`; no `at`, no kit cache, unknown for API-key accounts and unanswered reads). Both hold the account agent's shared lock for the read. The fake gateway serves `models.list { agentId }` per agent and a cold per-provider usage cache (`setUsage`; no `usage` on the first answer carrying the provider).
+- FEAT: OpenClaw kit S10 account runs: `kit.run({ member, sessionKey, account: 'auto' | 'default' | id, model?, needs? })` picks one account once, before any request (Choosing, 5.15), checks its own sealed sign-in with `byokit.accounts ready` and runs on its agent; an unbound key that picks an account agent runs as `agent:<account agent>:<tail>`. The first event is `{ type: 'account', account, model, sessionKey, how, why, considered }`, an ok end carries `account` and `model`, a chosen account that fails its ready check ends `signed-out` after its account event, with no agent request (Auto skips such an account for the next one), an empty pick ends `signed-out`, a missing model ends `plan`, and a resting end writes `until` (now + 5 min when the message names none) so the next Auto skips the account. `needs` alone resolves as `account: 'default'`; with `account` absent and `needs` absent or empty a run is unchanged. Account runs hold the agent's shared lock to their end, and index edits now take their own per-member lock, so a live run never blocks a rename or a listing. A model the engine reports unavailable only because its account is signed out or resting still counts as that account's plan. Session binding arrives in the next step.
+
 ## 0.11.0 (2026-10-12)
 
 - Dependency update: pins @byokit/ui 0.7.0.

package/README.md

@@ -124,12 +124,18 @@ engine text that could echo the token. It is sent only as this member's wizard a
 results or kit logs. Ordinary browser paste and typed `kit.call('wizard.next', …)` pass-through are unchanged.
 API key (billed per use) entry still requires explicit selection; there is no subscription-to-key fallback.
 
-To choose which of a member's accounts a run uses, pass `model: 'provider/model'` in the run spec (for example
+To choose the model for a run, pass `model: 'provider/model'` in the run spec (for example
 `'openai/gpt-5.1'`, where `provider` is an id `kit.providers(member)` lists). That provider is the one called and billed for this run only, with no fallback to another
 provider or model. If the member isn't signed in to it, the run ends `{ ok: false, kind: 'signed-out' }` and the
 engine is never called. Leave `model` out to keep the engine's own choice. A specific sign-in (`@profile`) can't be
 picked per run: the pinned engine may still switch to another sign-in for the same provider.
 
+To let the kit choose among a member's accounts, pass `account: 'auto'` (the account with the most room left, decided
+once at run start), `'default'` (the saved default) or an id from `kit.accounts(member)`, with `needs: ['provider/model', …]`
+for other models the run may call. The first event is `{ type: 'account', account, model, sessionKey, how, why, considered }`,
+and an ok end carries `account` and `model`. A chosen account that isn't signed in ends `signed-out` with no agent request;
+when every account is resting, the end is `resting` with `until`, and Auto skips a resting account until then.
+
 
 For an owner who explicitly offers keys, `kit.addKey('ana', { authChoice: 'openai-api-key', apiKey })` returns
 `ok`, `invalid` or `not_included`. Label the option **API key (billed per use)**. Select only `routes()` rows with

package/dist/accounts.d.ts

@@ -1,5 +1,25 @@
 import { createLocks } from './locks.ts';
-import type { Account, AccountId, Defaults, GatewayTransport, Member } from './types.ts';
+import type { Account, AccountId, AccountPick, Defaults, GatewayTransport, Member, ModelInfo, Room, RunSelection, SignInOptions, SignInView } from './types.ts';
+type AddOptions = {
+    authChoice: string;
+    via?: 'browser' | 'code';
+    name?: string;
+    again?: AccountId;
+};
+type AccountSignIn = {
+    id: AccountId;
+    paste(text: string): void;
+    cancel(): void;
+    done: Promise<{
+        view: SignInView;
+        id: AccountId;
+    }>;
+};
+type StartSignIn = (agentId: string, o: SignInOptions, on: (v: SignInView) => void, fresh: boolean) => {
+    paste(text: string): void;
+    cancel(): void;
+    done: Promise<SignInView>;
+};
 export declare function createAccounts(ctx: {
     request: GatewayTransport['request'];
     root: string;
@@ -8,9 +28,20 @@ export declare function createAccounts(ctx: {
         workspace: string;
     }>;
     locks: ReturnType<typeof createLocks>;
+    signIn: StartSignIn;
+    log?: (line: string) => void;
 }): {
     list(member: Member): Promise<Account[]>;
+    add(member: Member, o: AddOptions, on: (v: SignInView) => void): Promise<AccountSignIn>;
     rename(member: Member, id: AccountId, name: string): Promise<Account>;
     defaults(member: Member): Promise<Defaults>;
     setDefaults(member: Member, d: Defaults): Promise<void>;
+    models(member: Member, id: AccountId): Promise<ModelInfo[]>;
+    room(member: Member, id: AccountId, demand?: string[]): Promise<Room>;
+    pick(member: Member, sel: RunSelection, skip?: readonly AccountId[]): Promise<{
+        pick: AccountPick;
+        agent?: string;
+    }>;
+    rest(member: Member, id: AccountId, until: number): Promise<void>;
 };
+export {};

package/dist/accounts.js

@@ -1,14 +1,23 @@
 // The per-member account index (5.15, O14 step S5): `<root>/accounts/<member>.json` (0600, whole-file temp
 // plus rename) is the only kit state: `{ v: 1, accounts: { [id]: { agent, name, route, addedAt, until?, model?,
-// who? } }, defaults }`. No credential, token, email or engine line. Listing, rename and defaults live here;
-// add, remove, models, room, pick and move arrive in later steps.
+// who? } }, defaults }`. No credential, token, email or engine line. Listing, rename, defaults, models, room,
+// adding (O14 step S6) and the start-of-run pick (S10) live here; remove and move arrive in later steps.
 import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
-import { randomUUID } from 'node:crypto';
+import { randomBytes, randomUUID } from 'node:crypto';
 import { join } from 'node:path';
-import { KEY_PREFIX, MEMBER_ID } from "./members.js";
+import { providerOf, resolveSelection } from "./pick.js";
+import { KEY_PREFIX, MEMBER_ID, NEW_MEMBER_ID, untilListed } from "./members.js";
 import { routes, routeFor } from "./routes.js";
+import { words } from "./words.js";
 const ACCOUNT_AGENT = /^[a-z][a-z0-9-]{0,31}--[0-9a-f]{6}$/;
 const usable = (status) => status === 'ok' || status === 'expiring' || status === 'static';
+const IDENTITY = 'IDENTITY.md';
+const named = (name, op) => {
+    const trimmed = typeof name === 'string' ? name.trim() : '';
+    if (!trimmed || trimmed.length > 100 || /[\u0000-\u001f\u007f]/.test(trimmed))
+        throw new Error(`${op}: name is empty`);
+    return trimmed;
+};
 const empty = () => ({ v: 1, accounts: {}, defaults: {} });
 const validEntry = (v) => !!v && typeof v === 'object'
     && typeof v.agent === 'string' && typeof v.name === 'string'
@@ -18,6 +27,10 @@ const validEntry = (v) => !!v && typeof v === 'object'
     && (v.who === undefined || typeof v.who === 'string');
 export function createAccounts(ctx) {
     const path = (member) => join(ctx.root, 'accounts', `${member}.json`);
+    // Accounts whose sign-in is running, as `<member>\n<id>`, counted per add: listed `signing` until the last one ends.
+    const signing = new Map();
+    // The index file's own lock, apart from any agent's: a run's shared hold on the member agent never blocks an edit.
+    const indexLock = (member) => `${member}#index`;
     const check = (member) => {
         if (!MEMBER_ID.test(member) || member.startsWith(KEY_PREFIX))
             throw new Error(`invalid member id: ${member}`);
@@ -141,6 +154,9 @@ export function createAccounts(ctx) {
         memberRows.sort((a, b) => a.addedAt - b.addedAt || (a.id < b.id ? -1 : 1));
         agentRows.sort((a, b) => a.addedAt - b.addedAt);
         const rows = [...memberRows, ...agentRows];
+        for (const row of rows)
+            if (signing.has(`${member}\n${row.id}`))
+                row.state = 'signing';
         if (file.defaults.account !== undefined && !rows.some((r) => r.id === file.defaults.account)) {
             delete file.defaults.account;
             dirty = true;
@@ -153,15 +169,101 @@ export function createAccounts(ctx) {
         const [roster, profiles] = await gather(agentId);
         return { ...(await build(member, agentId, file, roster, profiles)), file };
     };
+    // The account's index entry, only when `list` names it: an unindexed agent is never reachable, whatever the
+    // file holds.
+    const entryOf = async (member, id) => {
+        const row = (await list(member)).find((r) => r.id === id);
+        const entry = read(member).accounts[id];
+        if (!row || !entry)
+            throw new Error(`unknown account: ${id}`);
+        return { row, entry };
+    };
+    const record = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+    // `models.list { agentId, view: 'default' }` rows of the account's provider, mapped to `provider/model`. The pin
+    // reports no per-plan availability, so `why: 'plan'` only comes from a run ending `plan`, never from here.
+    const modelsOf = (provider, answer) => {
+        const rows = record(answer) && Array.isArray(answer.models) ? answer.models : [];
+        const out = [];
+        for (const candidate of rows) {
+            if (!record(candidate) || typeof candidate.provider !== 'string'
+                || candidate.provider.toLowerCase() !== provider.toLowerCase())
+                continue;
+            if (typeof candidate.id !== 'string' || !candidate.id || typeof candidate.name !== 'string')
+                continue;
+            const id = candidate.id.includes('/') ? candidate.id : `${candidate.provider}/${candidate.id}`;
+            if (providerOf(id) !== provider.toLowerCase())
+                continue;
+            const available = candidate.available === undefined
+                ? candidate.unavailableReason === undefined : candidate.available === true;
+            const info = { id, name: candidate.name, available };
+            if ((candidate.tier === 'strong' || candidate.tier === 'fast'))
+                info.tier = candidate.tier;
+            if (!available) {
+                if (candidate.unavailableReason === 'missing-auth' || candidate.unavailableReason === 'auth-failed')
+                    info.why = 'signed_out';
+                else if (candidate.unavailableReason === 'cooldown') {
+                    info.why = 'resting';
+                    if (typeof candidate.unavailableUntil === 'number' && Number.isFinite(candidate.unavailableUntil))
+                        info.until = candidate.unavailableUntil;
+                }
+            }
+            out.push(info);
+        }
+        return out;
+    };
+    const spanOf = (label) => {
+        const lower = label.toLowerCase();
+        if (lower === 'session')
+            return 'session';
+        if (lower === 'weekly')
+            return 'week';
+        if (lower === 'monthly')
+            return 'month';
+        return 'tightest';
+    };
+    // The `models.authStatus { agentId }` row for the account's provider: of its `usage.windows` entries the one
+    // with the highest numeric `usedPercent` gives `left`, `resetsAt` and `span`. A window applies to every model
+    // unless the engine scopes it to models; the pin's rows carry no scope, so the demand never narrows them today
+    // (the tightest known). A window without a numeric `usedPercent` is skipped, never read as unused. `at` is left
+    // out: the pin exposes no reading age, so the kit never stamps receipt time as reading time. The kit adds no
+    // cache: every call reads live.
+    const roomOf = (provider, answer) => {
+        const unknown = { left: 'unknown' };
+        const rows = record(answer) && Array.isArray(answer.providers) ? answer.providers : undefined;
+        if (!rows)
+            return unknown;
+        const row = rows.find((r) => record(r) && typeof r.provider === 'string'
+            && r.provider.toLowerCase() === provider.toLowerCase());
+        if (!row || !record(row))
+            return unknown;
+        const windows = record(row.usage) && Array.isArray(row.usage.windows) ? row.usage.windows : undefined;
+        if (!windows)
+            return unknown;
+        let best;
+        for (const candidate of windows) {
+            if (!record(candidate))
+                continue;
+            if (typeof candidate.usedPercent !== 'number' || !Number.isFinite(candidate.usedPercent))
+                continue;
+            const span = spanOf(typeof candidate.label === 'string' ? candidate.label : '');
+            const resetAt = typeof candidate.resetAt === 'number' && Number.isFinite(candidate.resetAt)
+                ? candidate.resetAt : undefined;
+            if (!best || candidate.usedPercent > best.used)
+                best = { used: candidate.usedPercent, ...(resetAt !== undefined ? { resetAt } : {}), span };
+        }
+        if (!best)
+            return unknown;
+        return { left: 100 - best.used, span: best.span, ...(best.resetAt !== undefined ? { resetsAt: best.resetAt } : {}) };
+    };
     async function list(member) {
         check(member);
         const { agentId } = await ctx.ensure(member);
-        const first = await ctx.locks.shared(agentId, () => buildRows(member, agentId));
+        const first = await ctx.locks.shared(indexLock(member), () => buildRows(member, agentId));
         if (!first.dirty)
             return first.rows;
         // A write is needed (synthesized entry, `who` backfill or dropped default): redo it under the
         // exclusive lock so two first-lists cannot interleave their read-modify-write.
-        return ctx.locks.exclusive([agentId], async () => {
+        return ctx.locks.exclusive([indexLock(member)], async () => {
             const { rows, dirty, file } = await buildRows(member, agentId);
             if (dirty)
                 write(member, file);
@@ -170,15 +272,10 @@ export function createAccounts(ctx) {
     }
     async function rename(member, id, name) {
         check(member);
-        if (typeof name !== 'string')
-            throw new Error('renameAccount: name is empty');
-        const trimmed = name.trim();
-        if (!trimmed || trimmed.length > 100 || /[\u0000-\u001f\u007f]/.test(trimmed))
-            throw new Error('renameAccount: name is empty');
-        const { agentId } = await ctx.ensure(member);
+        const trimmed = named(name, 'renameAccount');
         if (!(await list(member)).some((r) => r.id === id))
             throw new Error(`unknown account: ${id}`);
-        await ctx.locks.exclusive([agentId], async () => {
+        await ctx.locks.exclusive([indexLock(member)], async () => {
             const file = read(member);
             const entry = file.accounts[id];
             if (!entry)
@@ -205,8 +302,8 @@ export function createAccounts(ctx) {
             throw new Error('setDefaults: defaults are invalid');
         if (d.auto !== undefined && typeof d.auto !== 'boolean')
             throw new Error('setDefaults: defaults are invalid');
-        const { agentId } = await ctx.ensure(member);
-        return ctx.locks.exclusive([agentId], async () => {
+        await ctx.ensure(member);
+        return ctx.locks.exclusive([indexLock(member)], async () => {
             const file = read(member);
             const next = {};
             if (d.account !== undefined)
@@ -218,5 +315,185 @@ export function createAccounts(ctx) {
             write(member, { ...file, defaults: next });
         });
     }
-    return { list, rename, defaults, setDefaults };
+    async function models(member, id) {
+        check(member);
+        await ctx.ensure(member);
+        const { row, entry } = await entryOf(member, id);
+        return readModels(row, entry);
+    }
+    // The shared hold covers the read, so no kit read of the agent is in flight while it is removed.
+    const readModels = (row, entry) => ctx.locks.shared(entry.agent, async () => modelsOf(row.provider, await ctx.request('models.list', { agentId: entry.agent, view: 'default' })));
+    async function room(member, id, demand) {
+        check(member);
+        await ctx.ensure(member);
+        const { row, entry } = await entryOf(member, id);
+        return readRoom(row, entry);
+    }
+    // An API-key account is used only when chosen, never by Auto: its room is always unknown, with no read. A demand
+    // never narrows the windows (see `roomOf`), so the read takes none.
+    const readRoom = (row, entry) => row.billing === 'api'
+        ? Promise.resolve({ left: 'unknown' })
+        : ctx.locks.shared(entry.agent, async () => {
+            let answer;
+            try {
+                answer = await ctx.request('models.authStatus', { agentId: entry.agent }, { timeoutMs: 20_000 });
+            }
+            catch {
+                return { left: 'unknown' };
+            }
+            return roomOf(row.provider, answer);
+        });
+    // Choosing (5.15) for an unbound key: every listed account's room and models are read live once, then the pure
+    // `resolveSelection` decides. `agent` is the picked account's engine agent. A model unavailable only because the
+    // account is signed out or resting is still in its plan: the account's state and the run's ready check judge that.
+    // The pinned engine may hold no prepared model catalog for an agent added since it started, and refuses its models; that
+    // row's models are then unknown (`undefined`), and `resolveSelection` host-validates its membership by provider.
+    async function pick(member, sel, skip = []) {
+        const rows = (await list(member)).filter((r) => !skip.includes(r.id));
+        const file = read(member);
+        const reads = new Map(await Promise.all(rows.map(async (row) => {
+            const entry = file.accounts[row.id];
+            const models = await readModels(row, entry).then((ms) => ms.map((m) => (m.why ? { ...m, available: true } : m)), () => undefined);
+            return [row.id, { room: await readRoom(row, entry), models }];
+        })));
+        const chosen = resolveSelection(rows, file.defaults, sel, (a) => reads.get(a.id).room, Date.now(), (a) => reads.get(a.id).models);
+        return { pick: chosen, ...(chosen.ok ? { agent: file.accounts[chosen.account.id].agent } : {}) };
+    }
+    // A run on the account ended resting: Auto skips it until `until` (its state reads `resting` until then).
+    const rest = (member, id, until) => edit(member, (file) => { const entry = file.accounts[id]; if (entry)
+        entry.until = until; });
+    // Index edits take the index lock, as listing's own write does.
+    const edit = (member, fn) => ctx.locks.exclusive([indexLock(member)], async () => { const file = read(member); fn(file); write(member, file); });
+    const identityOf = async (agentId) => {
+        const { file } = await ctx.request('agents.files.get', { agentId, name: IDENTITY });
+        return file.missing ? undefined : file.content;
+    };
+    const restoreIdentity = async (memberAgent, before) => {
+        if (before !== undefined && await identityOf(memberAgent) !== before)
+            await ctx.request('agents.files.set', { agentId: memberAgent, name: IDENTITY, content: before });
+    };
+    const onGateway = (agent) => untilListed(ctx.request, agent)
+        .then(() => true, () => ctx.request('agents.list')
+        .then((r) => r.agents.some((a) => a.id === agent)));
+    // A new agent whose sign-in did not finish goes with its entry (5.15); the shared workspace stays. The entry is
+    // dropped only once the agent's directory is gone, so a later removal can finish what this one could not.
+    const discard = (member, id, agent, created) => (async () => {
+        if (created) {
+            await ctx.request('byokit.accounts', { action: 'clear', agentId: agent });
+            await ctx.request('agents.delete', { agentId: agent, deleteFiles: false });
+        }
+        rmSync(join(ctx.root, 'state', 'agents', agent), { recursive: true, force: true });
+        await edit(member, (file) => { delete file.accounts[id]; });
+    })().catch((error) => ctx.log?.(`addAccount: ${agent} is not removed yet: ${error instanceof Error ? error.message : String(error)}`));
+    async function add(member, o, on) {
+        check(member);
+        if (!NEW_MEMBER_ID.test(member))
+            throw new Error(words('account.legacyMember'));
+        const choice = o?.authChoice === 'openai-codex' ? 'openai' : o?.authChoice;
+        const route = routes().find((r) => r.choice === choice && r.billing === 'subscription');
+        if (!route)
+            throw new Error(`addAccount: ${String(o?.authChoice)} is not a subscription sign-in`);
+        const name = o.name === undefined ? undefined : named(o.name, 'addAccount');
+        const provider = route.provider;
+        const { agentId: memberAgent, workspace } = await ctx.ensure(member);
+        if (o.again !== undefined && (!read(member).accounts[o.again] || o.again.split('.')[0] !== provider))
+            throw new Error(`unknown account: ${o.again}`);
+        // The member agent is the target only while it holds no local profile of the provider (5.15).
+        const own = await ctx.request('byokit.accounts', { action: 'list', agentId: memberAgent });
+        if (!own.ok || !Array.isArray(own.profiles))
+            throw new Error('addAccount: the member\'s sign-ins could not be read');
+        const fresh = o.again !== undefined || own.profiles.some((p) => p.provider === provider);
+        const entryOf = (file, agent) => ({ agent, route: route.choice, addedAt: Date.now(),
+            name: name ?? `${route.label} ${Object.values(file.accounts).filter((e) => e.route === route.choice).length + 1}` });
+        let id = provider;
+        let agent = memberAgent;
+        let added = false;
+        if (!fresh) {
+            await edit(member, (file) => { if (!file.accounts[id]) {
+                file.accounts[id] = entryOf(file, agent);
+                added = true;
+            } });
+        }
+        else {
+            // `<member>--<hex6>`, drawn again while that agent exists; its entry is written before the agent.
+            const roster = new Set((await ctx.request('agents.list')).agents.map((a) => a.id));
+            await edit(member, (file) => {
+                const taken = new Set([...roster, ...Object.values(file.accounts).map((e) => e.agent)]);
+                do {
+                    const hex = randomBytes(3).toString('hex');
+                    id = `${provider}.${hex}`;
+                    agent = `${member}--${hex}`;
+                } while (taken.has(agent) || file.accounts[id]);
+                file.accounts[id] = entryOf(file, agent);
+            });
+            added = true;
+            let created = false;
+            // The pin rewrites the shared workspace's IDENTITY.md Name line on create, so the create window is one lock per member.
+            await ctx.locks.exclusive([`${member}#identity`], async () => {
+                let before;
+                try {
+                    before = await identityOf(memberAgent);
+                    const made = await ctx.request('agents.create', { name: agent, workspace });
+                    created = true;
+                    if (made.agentId !== agent)
+                        throw new Error(`addAccount: agents.create answered ${String(made.agentId)}, not ${agent}`);
+                    await untilListed(ctx.request, agent);
+                    await restoreIdentity(memberAgent, before);
+                }
+                catch (error) {
+                    await restoreIdentity(memberAgent, before)
+                        .catch((restoreError) => ctx.log?.(`addAccount: IDENTITY.md is not restored: ${restoreError instanceof Error ? restoreError.message : String(restoreError)}`));
+                    const exists = created || await onGateway(agent).catch((listError) => {
+                        ctx.log?.(`addAccount: ${agent} is not removed yet: ${listError instanceof Error ? listError.message : String(listError)}`);
+                        return undefined;
+                    });
+                    if (exists !== undefined)
+                        await discard(member, id, agent, exists);
+                    throw error;
+                }
+            });
+        }
+        const key = `${member}\n${id}`;
+        signing.set(key, (signing.get(key) ?? 0) + 1);
+        const handle = ctx.signIn(agent, { authChoice: route.choice, ...(o.via ? { via: o.via } : {}) }, (v) => { if (v.state === 'waiting')
+            on(v); }, fresh);
+        // Sealed before the person sees done: the agent keeps only this sign-in, and its `who` goes to the index.
+        const settle = async (view) => {
+            if (view.state === 'done') {
+                const sealed = await ctx.locks.exclusive([memberAgent, agent, indexLock(member)], async () => {
+                    const answer = await ctx.request('byokit.accounts', { action: 'seal', agentId: agent, provider });
+                    if (!answer.ok)
+                        return 'Sign-in could not be saved. Try again.';
+                    const file = read(member);
+                    const entry = file.accounts[id];
+                    if (entry && answer.who) {
+                        entry.who = answer.who;
+                        write(member, file);
+                    }
+                    return true;
+                }).catch((error) => (error instanceof Error ? error.message : String(error)).slice(0, 200));
+                if (sealed === true)
+                    return view;
+                view = { state: 'failed', via: view.via, why: 'failed', error: sealed };
+            }
+            if (agent !== memberAgent)
+                await discard(member, id, agent, true);
+            else if (added)
+                await edit(member, (file) => { delete file.accounts[id]; })
+                    .catch((error) => ctx.log?.(`addAccount: ${id} entry is kept: ${error instanceof Error ? error.message : String(error)}`));
+            return view;
+        };
+        const done = handle.done.then(settle).finally(() => {
+            const left = signing.get(key) - 1;
+            if (left)
+                signing.set(key, left);
+            else
+                signing.delete(key);
+        }).then((view) => {
+            on(view);
+            return { view, id };
+        });
+        return { id, paste: handle.paste, cancel: handle.cancel, done };
+    }
+    return { list, add, rename, defaults, setDefaults, models, room, pick, rest };
 }

package/dist/device.d.ts

@@ -79,6 +79,9 @@ 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';
+}>;
 /** `openclawDevice`'s device surface: every `oc.*` op the computer answers, typed. */
 export type OpenClawDevice = {
     browser: BrowserDevice;
@@ -92,7 +95,7 @@ export type OpenClawDevice = {
     };
     signOut(p: string): Promise<void>;
     sessions(): Promise<SessionRow[]>;
-    run<const S extends OutputSchema | undefined = undefined>(message: string, o?: DeviceRunOptions<S>): AsyncIterable<RunEvent | DeviceEndFrame<SchemaOutput<S>>>;
+    run<const S extends OutputSchema | undefined = undefined>(message: string, o?: DeviceRunOptions<S>): AsyncIterable<DeviceRunEvent | DeviceEndFrame<SchemaOutput<S>>>;
     steer(k: string, t: string, o?: {
         auth?: 'apiKey';
     }): Promise<void>;

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, 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;
@@ -55,6 +55,7 @@ export declare class OpenClawKit {
     private greeting?;
     private members?;
     private readonly locks;
+    private readonly routeMap;
     private accountsCtl?;
     private readonly bridge;
     private readonly keys;
@@ -113,6 +114,23 @@ export declare class OpenClawKit {
     };
     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>;

package/dist/kit.js

@@ -432,6 +432,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().
@@ -746,7 +747,9 @@ export class OpenClawKit {
                     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 });
+                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)));
@@ -926,13 +929,29 @@ 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.
+    // 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'));
@@ -975,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/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/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;
 };

package/dist/testing/fake-gateway.js

@@ -14,6 +14,13 @@ const DEVICE_STEP = {
     deviceCode: { code: 'CREW-2026', expiresInMinutes: 15 }, externalUrl: 'https://auth.openai.com/codex/device',
 };
 const PROGRESS_STEP = { id: 'step-wait', type: 'progress', message: 'Waiting for authorization', executor: 'gateway' };
+// ChatGPT's browser route: the pin hands its unsigned authorize URL to the next step as `externalUrl`.
+const BROWSER_STEP = {
+    id: 'step-browser', type: 'note', executor: 'client', message: 'Open this URL in your LOCAL browser.',
+    externalUrl: 'https://auth.openai.com/oauth/authorize?response_type=code&client_id=fake-client&redirect_uri=http%3A%2F%2Flocalhost%3A1455%2Fauth%2Fcallback&state=fake-state',
+};
+// The pin's agents.create into an existing workspace rewrites IDENTITY.md's Name line (mergeIdentityMarkdownContent).
+const IDENTITY_NAME = /^- \*\*Name:\*\*.*$/m;
 const EVENTS = [
     'agent',
     'exec.approval.requested', 'exec.approval.resolved',
@@ -110,7 +117,32 @@ export function fakeGateway(script, o) {
     const orders = new Map();
     const models = new Map();
     const wizards = new Map();
+    // Each workspace's files by name, as `agents.files.get/set` and the create-time IDENTITY.md rewrite see them.
+    const workspaces = new Map();
+    const filesOf = (agentId) => {
+        const agent = agents.get(agentId);
+        if (!agent)
+            throw new Error(`unknown agent id "${agentId}"`);
+        const workspace = agent.workspace ?? `workspace-${agentId}`;
+        let files = workspaces.get(workspace);
+        if (!files) {
+            files = new Map();
+            workspaces.set(workspace, files);
+        }
+        return { workspace, files };
+    };
+    const fileAnswer = (agentId, name) => {
+        const { workspace, files } = filesOf(agentId);
+        const content = files.get(name);
+        return { agentId, workspace, file: { name, path: join(workspace, name), missing: content === undefined,
+                ...(content === undefined ? {} : { size: Buffer.byteLength(content), content }) } };
+    };
     const runs = new Map();
+    // The engine's own cached read of each provider's usage endpoint (O14): cold until a `models.authStatus`
+    // answer has carried the provider once (no `usage` on that first answer), then whatever `setUsage` stored.
+    // A pre-sign-in read names no provider, so it warms nothing: the journey's first room read stays cold.
+    const usage = new Map();
+    const warmed = new Set();
     const configBox = { hash: 'hash-1', config: {} };
     let hashSeq = 1;
     const ensureAgent = (id, workspace) => {
@@ -304,16 +336,41 @@ export function fakeGateway(script, o) {
         }),
         'agents.create': (p) => {
             const id = String(p.name);
+            if (agents.has(id))
+                throw new Error(`agent "${id}" already exists`);
             const workspace = p.workspace ? String(p.workspace) : undefined;
+            if (workspace) {
+                const files = workspaces.get(workspace) ?? new Map();
+                workspaces.set(workspace, files);
+                const identity = files.get('IDENTITY.md') ?? '# IDENTITY.md - Agent Identity\n\n';
+                files.set('IDENTITY.md', IDENTITY_NAME.test(identity) ? identity.replace(IDENTITY_NAME, `- **Name:** ${id}`) : `${identity}- **Name:** ${id}\n`);
+            }
             // With rosterApplyMs the fake mirrors the pinned engine: create answers before the roster hot-reload
             // makes the agent visible to agents.list (Crewhouse saw ~113 ms).
             if (o?.rosterApplyMs)
                 setTimeout(() => ensureAgent(id, workspace), o.rosterApplyMs);
             else
                 ensureAgent(id, workspace);
-            return { id };
+            return { ok: true, agentId: id, name: id, workspace: workspace ?? `workspace-${id}` };
+        },
+        // deleteFiles: false keeps the workspace, as the kit always asks; the agent's own store and model go.
+        'agents.delete': (p) => {
+            const id = String(p.agentId);
+            if (!agents.delete(id))
+                throw new Error(`agent "${id}" not found`);
+            profiles.delete(id);
+            orders.delete(id);
+            models.delete(id);
+            return { ok: true, agentId: id, removedBindings: 0 };
+        },
+        'agents.files.get': (p) => fileAnswer(String(p.agentId), String(p.name)),
+        'agents.files.set': (p) => {
+            filesOf(String(p.agentId)).files.set(String(p.name), String(p.content));
+            return { ok: true, ...fileAnswer(String(p.agentId), String(p.name)) };
         },
         // One profile per signed-in provider, `<provider>:default`, as the pin lists an agent's own profiles.
+        // Plus its cached usage once warm: cold on the first answer carrying the provider (no `usage`), then the
+        // stored windows.
         'models.authStatus': (p) => {
             const id = String(p?.agentId ?? 'main');
             const store = storeOf(id);
@@ -322,12 +379,26 @@ export function fakeGateway(script, o) {
                 providers: (agents.get(id)?.providers ?? []).map((provider) => {
                     const profileId = `${provider}:default`;
                     const credential = store[profileId];
+                    const key = `${id}\n${provider}`;
+                    const cold = !warmed.has(key);
+                    warmed.add(key);
+                    const windows = cold ? undefined : usage.get(id)?.get(provider);
                     return { provider,
                         profiles: [{ profileId, type: credential?.type ?? 'oauth',
-                                status: credential ? statusOf(credential, now) : 'ok' }] };
+                                status: credential ? statusOf(credential, now) : 'ok' }],
+                        ...(windows !== undefined ? { usage: { windows } } : {}) };
                 }),
             };
         },
+        // The runtime-allowed catalog for the agent's signed-in providers (O14): one available row each. A test
+        // scripting exact availability scripts this method with `handle`.
+        'models.list': (p) => {
+            const id = String(p?.agentId ?? 'main');
+            return {
+                models: (agents.get(id)?.providers ?? []).map((provider) => ({ id: `${provider}/default`,
+                    name: 'Default', provider, available: true })),
+            };
+        },
         'models.authLogout': (p) => {
             const agent = agents.get(String(p?.agentId ?? 'main'));
             // The pin refuses a profileIds list naming a profile the agent does not hold.
@@ -475,8 +546,11 @@ export function fakeGateway(script, o) {
             return { ok: true, status: 'ok', modelRef: model };
         },
         'openclaw.setup.auth.start': (p) => {
+            // The pin's single setup admission: a second start while a session runs is refused.
+            if (wizards.size)
+                throw new Error('setup is already in progress');
             const sessionId = String(p.sessionId ?? `fake-${randomUUID()}`);
-            wizards.set(sessionId, { agentId: String(p.agentId ?? 'main'), answered: false, pulls: 0 });
+            wizards.set(sessionId, { agentId: String(p.agentId ?? 'main'), authChoice: String(p.authChoice ?? ''), answered: false, pulls: 0 });
             return { sessionId, done: false, status: 'running' };
         },
         'wizard.next': (p) => {
@@ -488,7 +562,7 @@ export function fakeGateway(script, o) {
                 return { done: false, step: PROGRESS_STEP };
             }
             if (!session.answered)
-                return { done: false, step: DEVICE_STEP };
+                return { done: false, step: session.authChoice === 'openai' ? BROWSER_STEP : DEVICE_STEP };
             if (session.pulls++ === 0)
                 return { done: false, step: PROGRESS_STEP };
             wizards.delete(String(p.sessionId));
@@ -664,6 +738,14 @@ export function fakeGateway(script, o) {
         failNext,
         drop,
         handle: (method, fn) => { handlers.set(method, fn); },
+        setUsage: (agentId, provider, windows) => {
+            let perAgent = usage.get(agentId);
+            if (!perAgent) {
+                perAgent = new Map();
+                usage.set(agentId, perAgent);
+            }
+            perAgent.set(provider, windows);
+        },
         transport: factory({ port: 0, token: 'test', identityPath: '', bridgeSock: '' }),
     };
 }

package/dist/types.d.ts

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

package/package.json

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