@byokit/openclaw 0.14.2 → 0.14.5

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## Unreleased
 
+## 0.14.5 (2026-10-17)
+
+- FIX: adding a Go plan key that names no workspace (a bound service key the console refuses to list) now clears the standing workspace header before its probe, instead of carrying the previous workspace on its calls. A failed add's cleanup now drops the workspace header with the key, instead of leaving it behind for the next key.
+- FEAT: `kit.installPlugin(pluginId)` installs the external provider plugin a route needs (`readiness: 'needs_plugin'`, such as Z.AI's GLM Coding Plan routes) into the kit's own engine, at exactly the engine's version and with the pinned npm integrity (`engine/plugins.json`). The plugin joins `plugins.allow` across restarts and `routes()` then reports its routes ready, so `addKey` reaches the engine's key test. A version or integrity mismatch rejects with `PluginInstallError` (`code: 'version' | 'integrity'`) and installs nothing; discovery never installs. The GLM Coding Plan sign-ins are subscription; the plain Z.AI key rows stay API key (billed per use), explicit opt-in.
+- FIX: the install policy no longer blocks every `@openclaw/` npm plugin at its dependency-tree check; plugin installs are allowed only at a pinned spec and integrity.
+- FIX: `removeAccount` and a cancelled/failed `addAccount` no longer resolve while the removed agent is still on the roster. The engine answers `agents.delete` before its roster hot-reload applies (the same lag as after `agents.create`), so an immediate `agents.list` could still show the gone agent and a cancelled ChatGPT add flaked as "the cancelled agent is deleted". Both delete paths now wait until the roster drops the agent (`untilUnlisted`, the `untilListed` mirror: 25 ms poll, ~5 s bound, plain error naming the agent on timeout). The fake gateway's `rosterApplyMs` now lags the delete roster the same way for engine parity.
+- FIX: a Go plan key pasted over the link signs in with its workspace. The wizard sign-in listed no workspaces, so a key acting for several was refused on the activation probe and every run (403 Workspace selection is required). The sign-in now lists the key's workspaces the way `addKey` does (one used unasked; several asked through the same hidden paste; refused or unreadable listing fails before anything changes) and writes the pick as the provider header before activation.
+
+## 0.14.4 (2026-10-17)
+
+- Dependency update: pins @byokit/relay 0.8.0.
+- Dependency update: pins @byokit/pair 0.10.2.
+- Dependency update: pins @byokit/accounts 0.24.3.
+
+- FIX: `routes()` now describes the engine the kit actually pins. The generated table was still built from the 2026.8.1 pin while `ENGINE_VERSION` is 2026.8.35, so every row said `source: "... (2026.8.1)"` and `revision: "2026.8.1"`. `scripts/gen-routes.ts` pins 2026.8.35 (upstream commit from `engine/patches.json`), reads manifest directories only (the 2026.8.35 source tree keeps an `extensions/.npmignore` file), and a new public-API journey test fails whenever the table names anything but `ENGINE_VERSION`. All 96 rows re-verified against the 2026.8.35 manifests: the choice set is identical (nothing added or removed); every row now carries `(2026.8.35)`.
+
+## 0.14.3 (2026-10-17)
+
+- Dependency update: pins @byokit/ui 0.9.0.
+- Dependency update: pins @byokit/discover 0.8.3.
+- Dependency update: pins @byokit/accounts 0.24.2.
+
+- FIX: `addKey` for an OpenCode Go plan key with no `orgId` no longer saves a key whose every call is refused with `403 Workspace selection is required`. The add lists the key's workspaces first (`openCodeWorkspaces` from `@byokit/accounts/opencode-go`): one is used as the `x-opencode-org-id` header; several resolve the new `AddKeyResult` `{ status: 'needs_workspace', workspaces: [{ id, name }] }` for the app's pick (add again with `orgId`); a key the console refuses adds with no header. A listing that could not be read resolves `{ status: 'retry', reason: 'network' }` and changes nothing. An explicit `orgId` is used as before.
+
 ## 0.14.2 (2026-10-16)
 
 - Dependency update: pins @byokit/relay 0.7.1.

package/README.md

@@ -157,6 +157,13 @@ register (`retry`). `network` is a timeout or transport failure; `inference` is
 probe failure, or a typed request-validation refusal; `engine` is a control or preparation failure; `busy` is a rate limit or a
 restarting engine. `not_included` covers an unsupported route, an unknown chosen model and a probe reporting the route unavailable;
 every other failure is `retry`. Migrate from the old string result with `result.status === 'ok'`, not `result === 'ok'`.
+An OpenCode Go plan login can act for several workspaces, and the Go gateway refuses its every call until one is named
+(`403 Workspace selection is required`). Pass the workspace as `orgId` when you have it; it rides the probe and every run as
+`x-opencode-org-id`. Without `orgId` the add lists the key's workspaces first (the console listing `@byokit/accounts` uses):
+one is used unasked; several resolve `{ status: 'needs_workspace', workspaces: [{ id, name }] }` with nothing saved, so show
+the pick (the names) and add again with `orgId: '<picked id>'`; a key the console refuses (a workspace-bound service key) adds
+with no workspace. A listing that could not be read (offline, a server error) resolves `{ status: 'retry', reason: 'network' }`
+and changes nothing. Workspace ids are row ids, never secrets. Another route refuses an `orgId` with `not_included`/`model`.
 A member that is not your own throws. `retry` means the engine may have taken the key but it was not kept
 sealed (for example a gateway restart ran late); no usable key was kept, so add it again. Failures never contain keys, key fragments, headers or raw engine diagnostics. Label the option **API key (billed per use)**. Select only `routes()` rows with
 `keyEntry: true`; API rows remain `offer: false`. Each route also carries its engine `revision`, `checked` date,
@@ -381,7 +388,7 @@ streams, [`examples/openclaw-kit`](../../examples/openclaw-kit) for a whole app,
 Subscription sign-ins are offered by default. API-billed routes remain in `kit.routes()` with `offer: false`;
 apps can offer them when the app or person opts in, labelled API key (billed per use). Each `Route` carries `billing` (`subscription`, `api` or
 `local`) so the app can label what is billed. Proxy routes, compatibility aliases, local runtimes stay off. Native Claude Code sign-in is offered by default. A plan key (OpenCode Go: `kit.addAccount(member, { authChoice: 'opencode-go' }, on)`) asks for `Plan key`; `paste` it and the engine live-tests it before `done`. A paired device starts the same sign-in with either `via` and pastes the key over the sealed link, which keeps it on the host. A run reaches the pinned engine's static Go models (default `opencode-go/deepseek-v4-pro`); the kit keeps OpenCode Go's `x-opencode-session` header on every request, the setup probe included. A live-only Go model such as Muse needs no app config: the kit registers the plan's live catalog with each model's API, so `run({ model: 'opencode-go/muse-spark-1.3-contributor' })` runs on the account (or with `auth: 'apiKey'` on a Go key); an app that sets `config.models.providers['opencode-go'].models` keeps its own list. A choice the pinned Gateway cannot set up has readiness `no_upstream_flow` and is never offered. Pass the accounts the app offers in `KitOptions.offered` (the provider, auth choice or alias each route carries, e.g. `'openrouter'`); the kit allow-lists the plugin of every route those name, so an opted-in sign-in is not blocked. An app can still name a plugin directly in `config.plugins.allow`, and pass the route's `choice` explicitly to `kit.signIn()`.
-Offered provider plugins are allowed by default alongside the app's plugin ids.
+Offered provider plugins are allowed by default alongside the app's plugin ids. A route whose provider plugin ships outside the engine (Z.AI's GLM Coding Plan, for one) has readiness `needs_plugin` until the app calls `await kit.installPlugin(route.needs.plugin)`: it installs that plugin into the kit's own engine at exactly the engine's version and pinned npm integrity, keeps it allowed across restarts, and rejects `PluginInstallError` (`code` `version` or `integrity`) with nothing installed on a mismatch. Discovery never installs.
 
 ## API at a glance
 

package/dist/accounts.js

@@ -12,7 +12,7 @@ import { join } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
 import { providerOf, resolveSelection } from './pick.js';
 import { agentOf, memberOf as baseMemberOf } from './attribution.js';
-import { KEY_PREFIX, MEMBER_ID, NEW_MEMBER_ID, keyAgentId, untilListed } from './members.js';
+import { KEY_PREFIX, MEMBER_ID, NEW_MEMBER_ID, keyAgentId, untilListed, untilUnlisted } from './members.js';
 import { routes, routeFor } from './routes.js';
 import { words } from './words.js';
 const record = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
@@ -1007,6 +1007,9 @@ export function createAccounts(ctx) {
                 if (listed.profiles.length)
                     throw new Error('removeAccount: the account is still signing in');
                 await ctx.request('agents.delete', { agentId: agent, deleteFiles: false });
+                // The roster hot-reload applies a beat after the delete answer: wait until the agent is gone, so a
+                // roster read right after the removal no longer sees it.
+                await untilUnlisted(ctx.request, agent);
             }
             rmSync(agentDir(agent), { recursive: true, force: true });
             // Already holding the index lock: write directly instead of `edit`, which would wait on itself.
@@ -1027,6 +1030,9 @@ export function createAccounts(ctx) {
         if (created) {
             await ctx.request('byokit.accounts', { action: 'clear', agentId: agent });
             await ctx.request('agents.delete', { agentId: agent, deleteFiles: false });
+            // The roster hot-reload applies a beat after the delete answer: `done` resolves only once the agent is
+            // gone, so a roster read right after a cancelled sign-in no longer sees it.
+            await untilUnlisted(ctx.request, agent);
         }
         rmSync(agentDir(agent), { recursive: true, force: true });
         await edit(member, (file) => { delete file.accounts[id]; });

package/dist/config.d.ts

@@ -12,6 +12,7 @@ export declare function reconcileConfig(saved: object | undefined, o: {
     app?: object;
     installPolicy?: KitOptions['installPolicy'];
     offered?: readonly string[];
+    plugins?: readonly string[];
     browser?: {
         profiles: Record<string, {
             cdpUrl: string;

package/dist/config.js

@@ -1,5 +1,6 @@
 import { dirname, join } from 'node:path';
 import { routes } from './routes.js';
+import { pluginPins } from './plugins.js';
 import { MEMBER_ID, KEY_PREFIX, BASE_AGENT, keyAgentId } from './members.js';
 const object = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
 const merge = (a, b) => {
@@ -84,7 +85,9 @@ export function reconcileConfig(saved, o) {
             ...routes().filter(route => route.offerPolicy === 'default' && !route.needs?.plugin && route.plugin)
                 .map(route => route.plugin),
             // Plus every explicitly offered route the app names, so an opted-in sign-in (OpenRouter) is not blocked.
-            ...offeredPlugins(o.offered)])];
+            ...offeredPlugins(o.offered),
+            // Plus every external plugin the kit installed (B7): an app's own allow list must not disable it at the next boot.
+            ...o.plugins ?? []])];
     c.plugins.entries ??= {};
     c.plugins.entries[o.pluginId] = merge(c.plugins.entries[o.pluginId] ?? {}, { hooks: { timeouts: { before_tool_call: 200_000 } } });
     if (o.browser) {
@@ -112,6 +115,7 @@ export function reconcileConfig(saved, o) {
             passEnv: ['OPENCLAW_STATE_DIR'], env: {
                 BYOKIT_TRUSTED_SKILLS: o.installPolicy?.trustedSkills ?? '',
                 BYOKIT_OWN_ROOTS: JSON.stringify(o.installPolicy?.ownRoots ?? []),
+                BYOKIT_PLUGIN_PINS: JSON.stringify(Object.values(pluginPins())),
             },
         } };
     return c;

package/dist/engine.d.ts

@@ -53,6 +53,13 @@ export declare class Engine {
     private freePort;
     prepare(): Promise<void>;
     private prepareOnce;
+    /** B7: the engine's own installer for one pinned external plugin, in the isolated engine env with the kit's npm
+     * first on PATH (the installer runs `npm`). The explicit kit call is the consent; the install policy holds the pin and
+     * its integrity. Resolves the installer's exit code and output tail; the kit then restarts the gateway to load it. */
+    installPlugin(spec: string): Promise<{
+        code: number | null;
+        output: string;
+    }>;
     doctorContext(): {
         entry: string;
         env: Record<string, string>;

package/dist/engine.js

@@ -14,6 +14,7 @@ import { appendUsageBoot } from './usage-boots.js';
 import { reconcileConfig, appRecoveryPrefixes } from './config.js';
 import { writePlugin, resolveBridge } from './bridge.js';
 import { sweepOrphans } from './accounts.js';
+import { installedPlugins } from './plugins.js';
 /** The app's stateDir as an absolute path with no symlinked ancestor (macOS /tmp and /var are symlinks):
  * the native Claude login's accounts store refuses any other, so a relative or symlinked stateDir failed it. */
 export function canonicalStateDir(dir) {
@@ -290,9 +291,30 @@ export class Engine {
         const saved = existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : undefined;
         const config = reconcileConfig(saved, { root: this.root, stateDir: this.o.stateDir, port: this.port, pluginId: this.o.pluginId,
             pluginDir, policyPath: join(kitDir, 'policy', 'policy.mjs'), app: this.o.config, offered: this.o.offered,
-            installPolicy: this.o.installPolicy, browser: this.o.browserConfig?.() });
+            installPolicy: this.o.installPolicy, browser: this.o.browserConfig?.(), plugins: installedPlugins(this.root) });
         putChanged(path, JSON.stringify(config, null, 2) + '\n');
     }
+    /** B7: the engine's own installer for one pinned external plugin, in the isolated engine env with the kit's npm
+     * first on PATH (the installer runs `npm`). The explicit kit call is the consent; the install policy holds the pin and
+     * its integrity. Resolves the installer's exit code and output tail; the kit then restarts the gateway to load it. */
+    installPlugin(spec) {
+        const { entry, env } = this.doctorContext();
+        const npm = this.o.npmPath && this.o.npmPath.includes('/') ? [dirname(this.o.npmPath)] : (process.env.PATH ?? '').split(':');
+        return new Promise((resolve, reject) => {
+            const child = spawn(process.execPath, [entry, 'plugins', 'install', spec, '--force', '--accept-capabilities'], {
+                cwd: env.HOME, env: { ...env, PATH: [...npm, env.PATH].join(':'), npm_config_cache: join(this.root, 'npm-cache') },
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+            let output = '';
+            this.started.add(child);
+            const keep = (chunk) => { output = (output + chunk).slice(-2000); };
+            child.stdout.on('data', keep);
+            child.stderr.on('data', keep);
+            const timer = setTimeout(() => child.kill('SIGKILL'), 300_000);
+            child.once('error', error => { clearTimeout(timer); this.started.forget(child); reject(error); });
+            child.once('close', code => { clearTimeout(timer); this.started.forget(child); resolve({ code, output }); });
+        });
+    }
     doctorContext() {
         const home = join(this.root, 'home');
         return { entry: this.entry, env: {

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export { stateWords, toAccountView, words, type AccountView, type WordKey } from
 export { chooseAccount, consider, resolveSelection, type RoomOf } from './pick.ts';
 export { AuthStoreUnreadableError, AuthStoreSealSizeError } from './auth-store.ts';
 export { EngineAlreadyRunningError } from './engine-status.ts';
+export { PluginInstallError, type PluginInstallFailure } from './plugins.ts';
 export { readAgentDayUsage } from './day-usage.ts';
 export type { AgentDayUsage, DayUsageClient, EngineStartedCharge, EngineStartedKind } from './day-usage.ts';
 export { readAgentUsage, agentUsageOf } from './usage.ts';

package/dist/index.js

@@ -6,5 +6,6 @@ export { stateWords, toAccountView, words } from './words.js';
 export { chooseAccount, consider, resolveSelection } from './pick.js';
 export { AuthStoreUnreadableError, AuthStoreSealSizeError } from './auth-store.js';
 export { EngineAlreadyRunningError } from './engine-status.js';
+export { PluginInstallError } from './plugins.js';
 export { readAgentDayUsage } from './day-usage.js';
 export { readAgentUsage, agentUsageOf } from './usage.js';

package/dist/keys.d.ts

@@ -1,12 +1,20 @@
 import { type ActivationCtx } from './activation.ts';
-import { type RouteView } from './routes.ts';
+import type { RouteView } from './routes.ts';
 import type { Member, ModelInfo } from './types.ts';
 export type KeyFailureReason = 'auth' | 'billing' | 'empty' | 'model' | 'network' | 'engine' | 'inference' | 'busy';
+/** `needs_workspace`: the Go plan login acts for several workspaces (console orgs); show the pick and add again with
+ *  its `orgId`. Nothing was saved or sent to the engine. Ids are row ids, never secrets. */
 export type AddKeyResult = {
     status: 'ok';
 } | {
     status: 'invalid' | 'not_included' | 'retry';
     reason: KeyFailureReason;
+} | {
+    status: 'needs_workspace';
+    workspaces: {
+        id: string;
+        name: string;
+    }[];
 };
 /** The add resolves like a Promise; `cancel()` stops a pending add and clears any partial key (retry/busy). */
 export type AddKeyHandle = Promise<AddKeyResult> & {
@@ -14,6 +22,7 @@ export type AddKeyHandle = Promise<AddKeyResult> & {
 };
 export declare function createKeys(ctx: ActivationCtx & {
     root: string;
+    routes(): RouteView[];
     ensure(member: Member): Promise<{
         agentId: string;
     }>;

package/dist/keys.js

@@ -1,8 +1,8 @@
 import { join } from 'node:path';
+import { openCodeWorkspaces } from '@byokit/accounts/opencode-go';
 import { activate } from './activation.js';
 import { keyAgentId, MEMBER_ID, KEY_PREFIX, untilListed } from './members.js';
 import { providerOf } from './pick.js';
-import { routes } from './routes.js';
 import { modelsOf } from './accounts.js';
 import { LIVE_CATALOGS } from './constants.js';
 export function createKeys(ctx) {
@@ -60,7 +60,7 @@ export function createKeys(ctx) {
     const models = async (member, o) => {
         if (!check(member))
             throw new Error('Choose your own member.');
-        const route = routes().find((r) => r.choice === o.authChoice && r.keyEntry && r.readiness === 'ready');
+        const route = ctx.routes().find((r) => r.choice === o.authChoice && r.keyEntry && r.readiness === 'ready');
         if (!route || !LIVE_CATALOGS.includes(route.provider))
             return [];
         await ctx.ensure(member);
@@ -83,18 +83,36 @@ export function createKeys(ctx) {
                     throw new Error('Choose your own member.');
                 if (!o.apiKey.trim())
                     return failure('invalid', 'empty');
-                const route = routes().find((r) => r.choice === o.authChoice && r.keyEntry && r.readiness === 'ready');
+                const route = ctx.routes().find((r) => r.choice === o.authChoice && r.keyEntry && r.readiness === 'ready');
                 if (!route || (o.model !== undefined && !LIVE_CATALOGS.includes(route.provider)))
                     return failure('not_included', 'model');
                 // A workspace names a live-catalog login's own workspace only; another route takes no header, and a
                 // refusal here leaves the member's lanes untouched (it lands before any prepare or activation).
-                const orgId = typeof o.orgId === 'string' ? o.orgId.trim() : '';
+                let orgId = typeof o.orgId === 'string' ? o.orgId.trim() : '';
                 if (orgId) {
                     if (orgId.length > 256)
                         return failure('invalid', 'auth');
                     if (!LIVE_CATALOGS.includes(route.provider))
                         return failure('not_included', 'model');
                 }
+                else if (route.provider === 'opencode-go') {
+                    // The Go gateway refuses a login acting for several workspaces until one is named (403 Workspace selection
+                    // is required), so an add without `orgId` lists the key's own (the console listing `@byokit/accounts` uses):
+                    // one is used, several come back for the app's pick, and a key the console refuses (a workspace-bound
+                    // service key) needs none. A listing that could not be read fails the add before anything changes.
+                    let workspaces;
+                    try {
+                        workspaces = await openCodeWorkspaces(o.apiKey, (input, init) => fetch(input, { ...init, signal: init?.signal ? AbortSignal.any([init.signal, ac.signal]) : ac.signal }));
+                    }
+                    catch { // `workspaces_unread`: offline, timeout, a server error or a body that is no list
+                        return ac.signal.aborted ? failure('retry', 'busy') : failure('retry', 'network');
+                    }
+                    if (ac.signal.aborted)
+                        return failure('retry', 'busy');
+                    if (workspaces.length > 1)
+                        return { status: 'needs_workspace', workspaces };
+                    orgId = workspaces[0]?.id ?? '';
+                }
                 if (ac.signal.aborted)
                     return failure('retry', 'busy');
                 return exclusive(member, async () => {
@@ -102,8 +120,13 @@ export function createKeys(ctx) {
                     // A key the engine may have taken but not sealed is cleared (prepare already emptied the agent); if the clear
                     // does not reach the engine, the key stays unsealed and unusable until the next key add or kit start, so runs
                     // fail closed.
+                    let wroteHeader = false;
                     const abandon = async (result) => {
                         await control(member, 'clear').catch(() => undefined);
+                        // A header this add wrote must not outlive its abandoned key; a clear that fails never throws past
+                        // the abandon, like the key clear itself.
+                        if (wroteHeader)
+                            await ctx.setProviderHeaders(route.provider, null).catch(() => undefined);
                         return result;
                     };
                     const cancelled = () => failure('retry', 'busy');
@@ -123,9 +146,16 @@ export function createKeys(ctx) {
                             return failure('retry', 'engine');
                         // The workspace rides the provider's probe and every run from its config; it is written before the
                         // activation, so the probe itself carries it. The slot is provider-wide (shared by every member's
-                        // key on this engine), so a replacement with no `orgId` keeps the standing one and `removeKey` drops it.
-                        if (orgId)
+                        // key on this engine), so a workspace-scoped add that names none clears the standing one before the
+                        // probe: a bound service key never carries another workspace, and `removeKey` drops it.
+                        if (orgId) {
                             await ctx.setProviderHeaders(route.provider, { 'x-opencode-org-id': orgId });
+                            wroteHeader = true;
+                        }
+                        else if (LIVE_CATALOGS.includes(route.provider)) {
+                            await ctx.setProviderHeaders(route.provider, null);
+                            wroteHeader = true;
+                        }
                         // The public pin's typed API-key path, never a CLI-login import. Discard the engine's lines/errors.
                         sent = true;
                         if (ac.signal.aborted)

package/dist/kit.d.ts

@@ -41,6 +41,10 @@ export type KitOptions = {
     spawnEngine?: boolean;
     onState?: (s: KitState) => void;
     log?: (line: string) => void;
+    listWorkspaces?: (key: string, signal: AbortSignal) => Promise<{
+        id: string;
+        name: string;
+    }[]>;
 };
 export type RetainedLogin = {
     path: string;
@@ -56,6 +60,7 @@ export declare class OpenClawKit {
     private members?;
     private readonly locks;
     private readonly routeMap;
+    private installs;
     private accountsCtl?;
     private readonly bridge;
     private readonly keys;
@@ -110,6 +115,11 @@ export declare class OpenClawKit {
     }>;
     private signInCtx;
     routes(): RouteView[];
+    /** B7 (5.7): install one external provider plugin a `needs_plugin` route names into this kit's own engine, at its
+     * pin; resolves once the restarted gateway lists it enabled at that version. Discovery never installs. Serialized:
+     * concurrent installs would race the allow-list update and double-spawn the installer into one engine tree. */
+    installPlugin(pluginId: string): Promise<void>;
+    private runInstall;
     providerStatus(member: Member): Promise<string[] | undefined>;
     providers(member: Member): Promise<string[]>;
     /** A member sign-in to `provider`, or a ready key (5.8) whose saved model is that provider's. */
@@ -154,8 +164,9 @@ export declare class OpenClawKit {
     defaults(member: Member): Promise<Defaults>;
     setDefaults(member: Member, d: Defaults): Promise<void>;
     /** Save an explicitly supplied API key (billed per use) in this member's separate key agent.
-     * `orgId` names the workspace a Go plan login acts for (the pick the app captured at connect);
-     * it rides every probe and run as `x-opencode-org-id`, and replacing the key rewrites it. */
+     * `orgId` names the workspace a Go plan login acts for; it rides every probe and run as `x-opencode-org-id`,
+     * and replacing the key rewrites it. Without it a Go key's workspaces are listed: one is used, several resolve
+     * `needs_workspace` with the rows for the app's pick (add again with `orgId`). */
     addKey(agentId: Member, o: {
         authChoice: string;
         apiKey: string;

package/dist/kit.js

@@ -1,3 +1,4 @@
+import { openCodeWorkspaces } from '@byokit/accounts/opencode-go';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
@@ -20,6 +21,7 @@ import { authStatus, createAuthStatus } from './auth-status.js';
 import { outputSchema } from './output.js';
 import { createKeys } from './keys.js';
 import { routes as routeTable } from './routes.js';
+import { installedPlugins, pinnedSpec, recordPlugin, PluginInstallError } from './plugins.js';
 import { providerOf } from './pick.js';
 import { signIn as startSignIn, signOut as engineSignOut } from './signin.js';
 import { reconcileConfig, browserToolPolicySafe, browserProfileAcknowledged, browserSessionMayRun, memoryLimited as configMemoryLimited, configKeyPath, readConfigKey, writeConfigKey } from './config.js';
@@ -436,6 +438,7 @@ export class OpenClawKit {
     members;
     locks = createLocks();
     routeMap = new Map();
+    installs = Promise.resolve();
     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().
@@ -668,6 +671,7 @@ export class OpenClawKit {
             dropLane: (member, provider) => this.dropKeyLane(member, provider),
             backfillLane: (member, model) => this.backfillKeyLane(member, model),
             restarting: () => this.engineRestarting(),
+            routes: () => this.routes(),
             request: (method, params, options) => this.request()(method, params, options),
             ensure: (member) => this.ensureMember(member),
             authConfig: () => this.authSnapshot(),
@@ -961,10 +965,69 @@ export class OpenClawKit {
             onDisconnect: (fn) => { this.signInDisconnects.add(fn); return () => { this.signInDisconnects.delete(fn); }; },
             stopSignal: this.engine.stopSignal,
             authConfig: () => this.authSnapshot(),
-            restarted: (authBefore, signal) => this.restarted(authBefore, signal) };
+            restarted: (authBefore, signal) => this.restarted(authBefore, signal),
+            setProviderHeaders: (provider, headers) => this.patchConfig({ models: { providers: { [provider]: { headers: headers ?? null } } } }),
+            listWorkspaces: (key, signal) => this.o.listWorkspaces
+                ? this.o.listWorkspaces(key, signal)
+                : openCodeWorkspaces(key, (input, init) => fetch(input, { ...init, signal: init?.signal ? AbortSignal.any([init.signal, signal]) : signal })) };
     }
     routes() {
-        return routeTable();
+        return routeTable({ plugins: installedPlugins(this.engine.root) });
+    }
+    /** B7 (5.7): install one external provider plugin a `needs_plugin` route names into this kit's own engine, at its
+     * pin; resolves once the restarted gateway lists it enabled at that version. Discovery never installs. Serialized:
+     * concurrent installs would race the allow-list update and double-spawn the installer into one engine tree. */
+    installPlugin(pluginId) {
+        const run = this.installs.then(() => this.runInstall(pluginId));
+        this.installs = run.catch(() => { });
+        return run;
+    }
+    async runInstall(pluginId) {
+        const pin = pinnedSpec(pluginId);
+        const version = pin.spec.slice(pin.spec.lastIndexOf('@') + 1);
+        const loaded = async () => {
+            const { plugins } = await this.request()('plugins.list', {});
+            return plugins.some((p) => p.id === pluginId && p.enabled && p.version === version);
+        };
+        if (!(await loaded())) {
+            // The installer enables a plugin only when the (restrictive once non-empty) allow list already names it.
+            const allow = (this.getConfigKey('plugins.allow') ?? []);
+            const added = !allow.includes(pluginId);
+            if (added)
+                this.setConfigKey('plugins.allow', [...allow, pluginId]);
+            let code;
+            let output;
+            try {
+                ({ code, output } = await this.engine.installPlugin(pin.spec));
+            }
+            catch (error) {
+                if (added)
+                    this.setConfigKey('plugins.allow', allow);
+                throw error;
+            }
+            if (code !== 0) {
+                if (added)
+                    this.setConfigKey('plugins.allow', allow);
+                if (output.includes('pinned plugin integrity mismatch'))
+                    throw new PluginInstallError('integrity', `${pin.spec} does not match its pinned integrity; nothing was installed.`);
+                if (output.includes('not a pinned plugin version'))
+                    throw new PluginInstallError('version', `The registry does not serve ${pin.spec} as pinned; nothing was installed.`);
+                const reason = output.trim().split('\n').filter((line) => line.trim()).slice(-3).join(' ');
+                throw new PluginInstallError('install', `${pin.spec} did not install: ${reason || `the installer exited ${code}`}`);
+            }
+        }
+        // The running gateway hot-reloads the installer's config write without loading the plugin (verified live on
+        // 2026.8.35); a safe restart (after in-flight requests) loads it, and the kit reconnects. Reads fail while it is down.
+        if (!(await loaded()))
+            await this.request()('gateway.restart.request', { reason: `byokit installed plugin ${pluginId}` });
+        const deadline = Date.now() + RESTART_MS;
+        while (!(await loaded().catch(() => false))) {
+            if (Date.now() >= deadline)
+                throw new PluginInstallError('install', `${pin.spec} installed, but the engine did not load it.`);
+            await delay(500);
+        }
+        // Readiness (routes(), the keys gates) tracks this record, so it names the plugin only once the engine lists it loaded.
+        recordPlugin(this.engine.root, pluginId);
     }
     async providerStatus(member) {
         const { agentId } = await this.ensureMember(member);
@@ -1070,8 +1133,9 @@ export class OpenClawKit {
         return this.accountsCtl.setDefaults(member, d);
     }
     /** Save an explicitly supplied API key (billed per use) in this member's separate key agent.
-     * `orgId` names the workspace a Go plan login acts for (the pick the app captured at connect);
-     * it rides every probe and run as `x-opencode-org-id`, and replacing the key rewrites it. */
+     * `orgId` names the workspace a Go plan login acts for; it rides every probe and run as `x-opencode-org-id`,
+     * and replacing the key rewrites it. Without it a Go key's workspaces are listed: one is used, several resolve
+     * `needs_workspace` with the rows for the app's pick (add again with `orgId`). */
     addKey(agentId, o) {
         return this.keys.add(agentId, o);
     }
@@ -1098,7 +1162,7 @@ export class OpenClawKit {
         await this.accountsCtl.unkey(member, provider).catch((error) => this.o.log?.(`removeKey: the key lane entry is not dropped yet: ${error instanceof Error ? error.message : String(error)}`));
     }
     async backfillKeyLane(member, model) {
-        const found = model === undefined ? [] : routeTable().filter((r) => r.keyEntry && r.readiness === 'ready' && r.provider === providerOf(model));
+        const found = model === undefined ? [] : this.routes().filter((r) => r.keyEntry && r.readiness === 'ready' && r.provider === providerOf(model));
         await this.accountsCtl?.backfill(member, found).catch((error) => this.o.log?.(`key lane ${member}: not indexed yet: ${error instanceof Error ? error.message : String(error)}`));
     }
     async prepareKeyOwner(agentId) {
@@ -1140,7 +1204,7 @@ export class OpenClawKit {
         return confirmLogin({ ...this.signInCtx(), seal: this.o.authSeal, log: this.o.log }, member, source);
     }
     // runs (5.8): the facade owns no run state; every call delegates to the O8 module
-    // with this kit's live transport, member table and bridge (firstmate clearance, O9).
+    // with this kit's live transport, member table and bridge (spec item O9).
     runs() {
         return createRuns({
             request: (method, params, o) => this.request()(method, params, o),
@@ -1233,7 +1297,8 @@ export class OpenClawKit {
         const safe = reconcileConfig(response.config, { root: this.engine.root, stateDir: this.o.stateDir,
             port: Number(readFileSync(join(this.engine.root, 'port'), 'utf8')), pluginId: this.o.plugin?.id ?? 'byokit',
             pluginDir: join(this.engine.root, 'plugin'), policyPath: fileURLToPath(new URL('../policy/policy.mjs', import.meta.url)), app: patch,
-            offered: this.o.offered, installPolicy: this.o.installPolicy, ...(this.o.browser ? { browser: this.browserConfig() } : {}) });
+            offered: this.o.offered, installPolicy: this.o.installPolicy, plugins: installedPlugins(this.engine.root),
+            ...(this.o.browser ? { browser: this.browserConfig() } : {}) });
         if (this.o.browser && !browserToolPolicySafe(safe, this.toolNames()))
             throw new Error('browser tool policy refused');
         if (this.o.browser) {

package/dist/members.d.ts

@@ -6,6 +6,9 @@ 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>;
+/** Resolves once agents.list no longer shows `id`, which agents.delete answers before: the engine's roster
+ * hot-reload applies a beat after the delete answer, the same lag as after agents.create. */
+export declare function untilUnlisted(request: GatewayTransport['request'], id: string): Promise<void>;
 export declare function createMembers(ctx: {
     request: GatewayTransport['request'];
     root: string;

package/dist/members.js

@@ -23,6 +23,16 @@ export async function untilListed(request, id) {
         await new Promise((resolve) => setTimeout(resolve, VISIBLE_POLL_MS));
     }
 }
+/** Resolves once agents.list no longer shows `id`, which agents.delete answers before: the engine's roster
+ * hot-reload applies a beat after the delete answer, the same lag as after agents.create. */
+export async function untilUnlisted(request, id) {
+    const deadline = Date.now() + VISIBLE_TIMEOUT_MS;
+    while (await listed(request, id)) {
+        if (Date.now() >= deadline)
+            throw new Error(`agent ${id} is still listed by agents.list after agents.delete`);
+        await new Promise((resolve) => setTimeout(resolve, VISIBLE_POLL_MS));
+    }
+}
 export function createMembers(ctx) {
     const cache = new Map();
     return { ensure(member) {

package/dist/plugins.d.ts

@@ -0,0 +1,17 @@
+export type PluginInstallFailure = 'unknown_plugin' | 'version' | 'integrity' | 'install';
+export declare class PluginInstallError extends Error {
+    readonly code: PluginInstallFailure;
+    constructor(code: PluginInstallFailure, message: string);
+}
+type Pin = {
+    spec: string;
+    integrity: string;
+};
+/** engine/plugins.json: `{ "<plugin id>": { spec: '<package>@<engine version>', integrity } }`. */
+export declare const pluginPins: () => Record<string, Pin>;
+/** The exact spec to install for a plugin a route needs: its `install.npmSpec` at the engine pin, and pinned so. */
+export declare function pinnedSpec(pluginId: string): Pin;
+/** The external plugins this kit installed into its own engine. */
+export declare function installedPlugins(root: string): string[];
+export declare function recordPlugin(root: string, pluginId: string): void;
+export {};

package/dist/plugins.js

@@ -0,0 +1,40 @@
+// External provider plugins (5.7, B7): the pins the kit installs at, and the ids it installed. Installing is the
+// kit's explicit call; discovery only reads the record.
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { atomic } from './engine-patches.js';
+import { ENGINE_VERSION } from './constants.js';
+import { routes } from './routes.js';
+export class PluginInstallError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'PluginInstallError';
+        this.code = code;
+    }
+}
+const kitDir = dirname(dirname(fileURLToPath(import.meta.url)));
+/** engine/plugins.json: `{ "<plugin id>": { spec: '<package>@<engine version>', integrity } }`. */
+export const pluginPins = () => JSON.parse(readFileSync(join(kitDir, 'engine', 'plugins.json'), 'utf8'));
+/** The exact spec to install for a plugin a route needs: its `install.npmSpec` at the engine pin, and pinned so. */
+export function pinnedSpec(pluginId) {
+    const npmSpec = routes().find(route => route.needs?.plugin === pluginId && route.install?.npmSpec)?.install?.npmSpec;
+    if (!npmSpec)
+        throw new PluginInstallError('unknown_plugin', `No route needs a plugin named ${pluginId}.`);
+    const pin = pluginPins()[pluginId];
+    if (pin?.spec !== `${npmSpec}@${ENGINE_VERSION}`)
+        throw new PluginInstallError('version', `${pluginId} has no pin for engine ${ENGINE_VERSION}.`);
+    return pin;
+}
+const recordOf = (root) => join(root, 'installed-plugins.json');
+/** The external plugins this kit installed into its own engine. */
+export function installedPlugins(root) {
+    const path = recordOf(root);
+    return existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : [];
+}
+export function recordPlugin(root, pluginId) {
+    const installed = installedPlugins(root);
+    if (!installed.includes(pluginId))
+        atomic(recordOf(root), JSON.stringify([...installed, pluginId]) + '\n');
+}