@byokit/openclaw 0.10.0 → 0.11.1

package/dist/testing/fake-gateway.js

@@ -2,7 +2,7 @@
 // `new OpenClawKit({ transport: fake.factory, spawnEngine: false, ... })` or drive `fake.transport.request`
 // directly. No engine, no network, no account.
 import { connect } from 'node:net';
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { ENGINE_VERSION, PROTOCOL_VERSION } from "../constants.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',
@@ -23,6 +30,12 @@ const EVENTS = [
 /** Window between a run's last event and its completion, so an abort issued on the text event still lands. */
 const ABORT_WINDOW_MS = 25;
 const BRIDGE_TIMEOUT_MS = 30_000;
+// The plugin's accounts.js status thresholds: auth selection's refresh margin and auth-health's oauth warn window.
+const EXPIRING_MS = 300_000;
+const OAUTH_WARN_MS = 86_400_000;
+// The plugin's account agent shape (D9) and agent id shape, as plugin/accounts.js tests them.
+const ACCOUNT_AGENT = /--[0-9a-f]{6}$/;
+const AGENT_ID = /^[a-z][a-z0-9-]{0,31}$/;
 const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
 function mergeInto(target, patch) {
     for (const [key, value] of Object.entries(patch)) {
@@ -100,8 +113,36 @@ export function fakeGateway(script, o) {
     const handlers = new Map();
     const agents = new Map();
     const keys = new Map();
+    const profiles = new Map();
+    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) => {
@@ -114,10 +155,92 @@ export function fakeGateway(script, o) {
             agent.workspace = workspace;
         return agent;
     };
-    const signInAgent = (id, provider) => {
+    const storeOf = (id) => {
+        let store = profiles.get(id);
+        if (!store) {
+            store = {};
+            profiles.set(id, store);
+        }
+        return store;
+    };
+    const orderOf = (id) => {
+        let order = orders.get(id);
+        if (!order) {
+            order = {};
+            orders.set(id, order);
+        }
+        return order;
+    };
+    // As the plugin's accounts.js: `who` only exists for an OAuth profile that stores a provider account id.
+    const whoOf = (credential) => credential.type === 'oauth' && typeof credential.accountId === 'string' && credential.accountId.length > 0
+        ? createHash('sha256').update(`${credential.provider}\n${credential.accountId}`).digest('hex').slice(0, 16) : undefined;
+    const hasSecret = (value, ref) => (typeof value === 'string' && value.length > 0) || (!!ref && typeof ref === 'object' && !Array.isArray(ref));
+    // The plugin's token expiry state (credential-state.ts): missing, invalid, expired, or valid.
+    const expiryState = (expires, now) => {
+        if (expires === undefined)
+            return 'missing';
+        if (typeof expires !== 'number' || !Number.isFinite(expires) || expires <= 0 || expires > 8.64e13)
+            return 'invalid';
+        return expires <= now ? 'expired' : 'valid';
+    };
+    // The plugin's profile status (auth-health.ts) from the credential alone: static, ok, expiring, expired or missing.
+    const statusOf = (credential, now) => {
+        if (credential.type === 'api_key')
+            return hasSecret(credential.key, credential.keyRef) ? 'static' : 'missing';
+        if (credential.type === 'token') {
+            if (!hasSecret(credential.token, credential.tokenRef))
+                return 'missing';
+            const state = expiryState(credential.expires, now);
+            if (state === 'invalid')
+                return 'missing';
+            if (state === 'expired')
+                return 'expired';
+            if (credential.expires === undefined)
+                return 'static';
+            return credential.expires - now <= EXPIRING_MS ? 'expiring' : 'ok';
+        }
+        if (!hasSecret(credential.access, undefined) && !hasSecret(credential.refresh, undefined))
+            return 'missing';
+        const expires = credential.expires;
+        const state = expiryState(expires, now);
+        if (state === 'invalid' || state === 'missing')
+            return 'missing';
+        if (state === 'expired')
+            return 'expired';
+        return expires - now <= OAUTH_WARN_MS ? 'expiring' : 'ok';
+    };
+    const entryPrimaryOf = (id) => {
+        const entries = configBox.config.agents?.entries;
+        const entry = entries?.[id];
+        const ref = entry?.model;
+        if (typeof ref === 'string')
+            return ref;
+        if (isPlainObject(ref) && typeof ref.primary === 'string')
+            return ref.primary;
+        return undefined;
+    };
+    const primaryOfId = (id) => entryPrimaryOf(id) ?? models.get(id);
+    const setPrimaryOfId = (id, primary) => {
+        models.set(id, primary);
+        const entries = configBox.config.agents?.entries;
+        const entry = entries?.[id];
+        if (entry && isPlainObject(entry)) {
+            const current = entry.model;
+            if (isPlainObject(current))
+                current.primary = primary;
+            else
+                entry.model = primary;
+        }
+    };
+    const signInAgent = (id, provider, extra) => {
         const agent = ensureAgent(id);
         if (!agent.providers.includes(provider))
             agent.providers.push(provider);
+        // The pin names the first profile of a provider `<provider>:default` and points the agent's model at it.
+        storeOf(id)[`${provider}:default`] = { provider, type: 'oauth', status: 'ok', access: 'fake-access',
+            refresh: 'fake-refresh', expires: Date.now() + 30 * 86_400_000, accountId: `fake-${id}`, ...extra };
+        orderOf(id)[provider] = [`${provider}:default`];
+        setPrimaryOfId(id, `${provider}/default@${provider}:default`);
     };
     // Every transport the factory made; events fan out to all of them, drop() closes all of them.
     const live = new Set();
@@ -213,20 +336,69 @@ 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.
-        'models.authStatus': (p) => ({
-            providers: (agents.get(String(p?.agentId ?? 'main'))?.providers ?? []).map((provider) => ({ provider,
-                profiles: [{ profileId: `${provider}:default`, type: 'oauth', status: 'ok' }] })),
-        }),
+        // 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);
+            const now = Date.now();
+            return {
+                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' }],
+                        ...(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.
@@ -235,6 +407,17 @@ export function fakeGateway(script, o) {
                 throw new Error('profileIds contain unavailable auth profiles');
             if (agent)
                 agent.providers = agent.providers.filter((provider) => provider !== p.provider);
+            const store = profiles.get(String(p.agentId ?? 'main'));
+            if (store)
+                for (const profileId of Object.keys(store))
+                    if (store[profileId].provider === p.provider)
+                        delete store[profileId];
+            const order = orders.get(String(p.agentId ?? 'main'));
+            if (order)
+                delete order[String(p.provider)];
+            const pin = models.get(String(p.agentId ?? 'main'));
+            if (typeof pin === 'string' && pin.includes(`@${String(p.provider)}:`))
+                models.delete(String(p.agentId ?? 'main'));
             if (keys.get(String(p.agentId))?.provider === p.provider)
                 keys.delete(String(p.agentId));
             return {};
@@ -255,6 +438,102 @@ export function fakeGateway(script, o) {
             }
             return { ok: key.sealed, ...(key.sealed ? { model: key.model } : {}) };
         },
+        // Account sealing (5.15): the same five actions, branches and refusals the shipped plugin method serves.
+        'byokit.accounts': (p) => {
+            const action = String(p.action ?? '');
+            const entries = configBox.config.agents?.entries;
+            const known = (id) => Boolean(id) && AGENT_ID.test(id) && ((Boolean(entries) && id in entries) || agents.has(id));
+            if (action === 'adopt') {
+                const from = String(p.from), to = String(p.to), provider = String(p.provider);
+                if (from === to || !known(from) || !known(to))
+                    return { ok: false };
+                if (typeof p.who !== 'string' || !p.who)
+                    return { ok: false };
+                const fromOrder = orderOf(from), named = fromOrder[provider] ?? [];
+                const fromId = named.length === 1 ? named[0] : undefined;
+                const credential = fromId ? storeOf(from)[fromId] : undefined;
+                if (!fromId || !credential || credential.provider !== provider || whoOf(credential) !== p.who)
+                    return { ok: false };
+                const target = primaryOfId(to);
+                if (typeof target !== 'string')
+                    return { ok: false };
+                const toStore = storeOf(to), toOrder = orderOf(to);
+                for (const [otherId, other] of Object.entries(toStore))
+                    if (ACCOUNT_AGENT.test(to) ? otherId !== fromId : other.provider === provider && otherId !== fromId)
+                        delete toStore[otherId];
+                toStore[fromId] = credential;
+                toOrder[provider] = [fromId];
+                if (!ensureAgent(to).providers.includes(provider))
+                    ensureAgent(to).providers.push(provider);
+                delete storeOf(from)[fromId];
+                if (fromOrder[provider]) {
+                    fromOrder[provider] = fromOrder[provider].filter((x) => x !== fromId);
+                    if (!fromOrder[provider].length)
+                        delete fromOrder[provider];
+                }
+                if (!Object.values(storeOf(from)).some((c) => c.provider === provider))
+                    ensureAgent(from).providers = ensureAgent(from).providers.filter((x) => x !== provider);
+                const cut = target.lastIndexOf('@');
+                setPrimaryOfId(to, `${cut > 0 ? target.slice(0, cut) : target}@${fromId}`);
+                return { ok: true };
+            }
+            const id = String(p.agentId ?? '');
+            if (!known(id))
+                return { ok: false };
+            const store = storeOf(id), order = orderOf(id);
+            if (action === 'list')
+                return { ok: true, profiles: Object.entries(store).map(([profileId, credential]) => ({ provider: credential.provider,
+                        profileId, type: credential.type, status: statusOf(credential, Date.now()), ...(whoOf(credential) ? { who: whoOf(credential) } : {}) })) };
+            if (action === 'clear') {
+                profiles.set(id, {});
+                orders.set(id, {});
+                const cleared = agents.get(id);
+                if (cleared)
+                    cleared.providers = [];
+                return { ok: true };
+            }
+            if (action === 'ready') {
+                const provider = String(p.provider ?? '');
+                const named = order[provider] ?? [];
+                const credential = named.length === 1 ? store[named[0]] : undefined;
+                if (!provider || !credential || credential.provider !== provider)
+                    return { ok: false };
+                const status = statusOf(credential, Date.now());
+                if (status === 'missing' || status === 'expired')
+                    return { ok: false };
+                return { ok: true, type: credential.type, ...(typeof credential.expires === 'number' ? { expiresAt: credential.expires } : {}),
+                    ...(whoOf(credential) ? { who: whoOf(credential) } : {}) };
+            }
+            if (action === 'seal') {
+                const primary = primaryOfId(id) ?? '';
+                const at = primary.lastIndexOf('@');
+                if (at < 1)
+                    return { ok: false };
+                const profileId = primary.slice(at + 1);
+                const credential = store[profileId];
+                const account = ACCOUNT_AGENT.test(id);
+                if (!credential || credential.provider !== p.provider || (!account && credential.type === 'api_key'))
+                    return { ok: false };
+                for (const [otherId, other] of Object.entries(store))
+                    if (account ? otherId !== profileId : other.provider === p.provider && otherId !== profileId)
+                        delete store[otherId];
+                // An account agent's whole order is replaced; a member's keeps its other providers, as plugin/accounts.js does.
+                const provider = String(p.provider);
+                if (account)
+                    orders.set(id, { [provider]: [profileId] });
+                else
+                    order[provider] = [profileId];
+                const sealedAgent = agents.get(id);
+                if (sealedAgent) {
+                    if (account)
+                        sealedAgent.providers = [provider];
+                    else if (!sealedAgent.providers.includes(provider))
+                        sealedAgent.providers.push(provider);
+                }
+                return { ok: true, ...(whoOf(credential) ? { who: whoOf(credential) } : {}) };
+            }
+            return { ok: false };
+        },
         'openclaw.setup.activate': (p) => {
             if (p.kind !== 'api-key')
                 throw new Error('only the API-key setup path is simulated');
@@ -267,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) => {
@@ -280,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));
@@ -397,8 +679,7 @@ export function fakeGateway(script, o) {
     const hello = () => ({
         protocol: PROTOCOL_VERSION,
         server: { version: ENGINE_VERSION },
-        // The methods the fake serves. The generated tables are type-only until O2 ships runtime names; O11's
-        // generated.test.ts cross-checks the real engine's hello against the committed tables.
+        // The methods the fake serves. The generated tables are type-only until O2 ships runtime names.
         methods: [...handlers.keys()].sort(),
         events: [...EVENTS],
     });
@@ -457,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.10.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",
@@ -60,17 +60,17 @@
     "prepack": "tsc -b && node ../../scripts/fix-words-dts.cjs"
   },
   "dependencies": {
-    "@byokit/pair": "0.9.0",
-    "@byokit/relay": "0.6.0",
-    "@byokit/discover": "0.7.0",
+    "@byokit/pair": "0.10.0",
+    "@byokit/relay": "0.6.1",
+    "@byokit/discover": "0.8.1",
     "@byokit/seal": "0.3.0",
-    "@byokit/secrets": "0.5.0",
+    "@byokit/secrets": "0.5.1",
     "@openclaw/gateway-client": "2026.8.35",
     "@openclaw/gateway-protocol": "2026.8.35",
     "ws": "8.22.0"
   },
   "devDependencies": {
-    "@byokit/ui": "0.6.0"
+    "@byokit/ui": "0.7.0"
   },
   "publishConfig": {
     "access": "public"