@byokit/openclaw 0.14.0 → 0.14.4

package/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 ## Unreleased
 
+## 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.
+- Dependency update: pins @byokit/accounts 0.24.1.
+
+- FIX: `addKey` takes `orgId` for the Go live-catalog route and writes it into the engine's provider config (`models.providers['opencode-go'].headers['x-opencode-org-id']`) before the activation, so a multi-workspace login token is accepted — the engine's own probe and every run carry the header, and the first chat runs. The slot is provider-wide (shared by every member's key on one engine): a replacement key with no `orgId` keeps the standing workspace, `removeKey` drops it, and naming an `orgId` on a route with no workspace is refused `not_included`/`model` instead of silently dropped. Keys and workspace ids never reach logs, errors or views.
+
+## 0.14.1 (2026-10-16)
+
+- Dependency update: pins @byokit/ui 0.8.0.
+- Dependency update: pins @byokit/discover 0.8.2.
+- Dependency update: pins @byokit/relay 0.7.0.
+- Dependency update: pins @byokit/pair 0.10.1.
+- Dependency update: pins @byokit/accounts 0.24.0.
+
+- FIX: when the engine answers a sign-in's cancel `cancelled`, `done` now also waits (up to 10 s) for it to free its setup admission, so a sign-in started right after is admitted instead of ending `why: 'busy'`.
+- FIX: The kit now resolves `stateDir` to one absolute path through no symlink before it uses it. A native Claude CLI sign-in (`claude-cli`, browser or phone) with a relative `stateDir`, or one under a symlinked folder such as macOS `/tmp` or `os.tmpdir()`, failed with "The app supplied invalid account options." Engine paths the kit reports (for example the bridge socket and `identityPath`) now use that resolved path.
+- FIX: `removeKey` (and `signOut`, which calls it for that provider) also drops the lane's `<provider>.key` index entry, so `accounts()` no longer lists a removed key; a scoped removal keeps another provider's entry.
+- FIX: `pick` builds its live room/models reads from the filtered pick rows, so an Auto pick for a member whose only other account is the unnamed key lane makes no `models.list`/`models.authStatus` calls for the lane it never consults.
+- FIX: the key-lane docs now scope the "no `<member>--<hex6>` per later key" claim to the `addKey` path; a plan key added with `addAccount` when the member agent already holds that provider still mints one `<member>--<hex6>` agent per key. The Choosing spec names the kit-only lane filter.
+- The README states platform support: Linux and macOS x64/arm64 supported, Windows unsupported. CI runs the offline suite on macOS.
+
 ## 0.14.0 (2026-10-15)
 
 - Dependency update: pins @byokit/accounts 0.23.0.

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
 
@@ -568,7 +575,8 @@ for await (const e of oc.run('Say hello.')) console.log(e);
 
 ## Isolation and billing
 
-The kit writes only under the `stateDir` the app passes. It spawns the engine with an explicit isolated environment
+The kit writes only under the `stateDir` the app passes, resolved to one absolute path through no symlink (so a
+relative path or macOS `os.tmpdir()` works, and paths the kit reports use the resolved form). It spawns the engine with an explicit isolated environment
 (never `process.env`), reads no environment variables except `PATH` to find `npm`, and never bills an API behind the
 person's back (memory search is never a paid provider).
 
@@ -685,6 +693,8 @@ retained-login cleanup and sealed approval limits.
 
 ## Status
 
+Linux and macOS x64/arm64 are supported; Windows is unsupported.
+
 Pinned to OpenClaw `2026.8.35` (protocol 4); `ENGINE_VERSION` and `PROTOCOL_VERSION` carry the pin. Signatures are
 frozen (docs/runtime-kits.md §5).
 

package/dist/accounts.js

@@ -10,11 +10,11 @@ import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync
 import { randomBytes, randomUUID } from 'node:crypto';
 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 { routes, routeFor } from "./routes.js";
-import { words } from "./words.js";
+import { providerOf, resolveSelection } from './pick.js';
+import { agentOf, memberOf as baseMemberOf } from './attribution.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);
 // `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.
@@ -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/approvals.js

@@ -1,6 +1,6 @@
 // Native approvals: exec.approval.*, plugin.approval.* and question.* surfaced through the same Approval shape (5.9, O5).
 import { randomBytes } from 'node:crypto';
-import { MEMBER_ID } from "./members.js";
+import { MEMBER_ID } from './members.js';
 const strip = (a) => {
     const { native, ...approval } = a;
     void native;

package/dist/auth-status.js

@@ -1,6 +1,6 @@
 import { statSync } from 'node:fs';
 import { join } from 'node:path';
-import { signedInProviders, USABLE } from "./runs.js";
+import { signedInProviders, USABLE } from './runs.js';
 /** Native Claude login stays in Claude Code. The pin's profile status does not include this synthetic auth;
  * setup detection asks the CLI itself, without handing credentials to the kit. */
 export async function authStatus(request, agentId, refresh = false, native = false) {

package/dist/auth-store.js

@@ -7,8 +7,8 @@
 import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, rmdirSync, writeFileSync, closeSync, fsyncSync, openSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
-import { EngineAlreadyRunningError, pidAlive as live } from "./engine-status.js";
-import { damagedAccountMembers, heldBackAgent, removedAccountAgents, sweepOrphans } from "./accounts.js";
+import { EngineAlreadyRunningError, pidAlive as live } from './engine-status.js';
+import { damagedAccountMembers, heldBackAgent, removedAccountAgents, sweepOrphans } from './accounts.js';
 const agentDirOf = (path) => path.startsWith('state/agents/') ? path.split('/')[2] : undefined;
 const encoder = new TextEncoder();
 const archive = (name) => !name.endsWith('.sealed') && (/^(auth-profiles|auth-state|auth|oauth)\.json\.(migrated-.+|sqlite-import\..+\.bak)$/.test(name)

package/dist/bridge.js

@@ -3,7 +3,7 @@ import { randomBytes } from 'node:crypto';
 import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { createServer } from 'node:net';
 import { rm } from 'node:fs/promises';
-import { words } from "./words.js";
+import { words } from './words.js';
 /** Newline-framed JSON, one request per connection; anything larger is not a gate request. */
 const FRAME_CAP = 1_000_000;
 /**

package/dist/browser/host.js

@@ -1,8 +1,8 @@
 // Internal host runtime (5.17). Production handoff is deliberately unprotected until W7/O17 qualification.
 import { randomBytes } from 'node:crypto';
-import { BrowserStoreError, checkUrl, validOrigin } from "./store.js";
-import { validateVerifiers, verifySignIn } from "./verify.js";
-import { dispatchResume, newResume, recoverResume } from "./resume.js";
+import { BrowserStoreError, checkUrl, validOrigin } from './store.js';
+import { validateVerifiers, verifySignIn } from './verify.js';
+import { dispatchResume, newResume, recoverResume } from './resume.js';
 export class SignInRefused extends Error {
     why;
     constructor(why) { super(`sign-in refused: ${why}`); this.why = why; }

package/dist/browser/verify.js

@@ -1,4 +1,4 @@
-import { checkUrl, validOrigin } from "./store.js";
+import { checkUrl, validOrigin } from './store.js';
 export function validateVerifiers(verifiers) {
     for (const v of verifiers) {
         validOrigin(v.origin);

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,6 +1,7 @@
 import { dirname, join } from 'node:path';
-import { routes } from "./routes.js";
-import { MEMBER_ID, KEY_PREFIX, BASE_AGENT, keyAgentId } from "./members.js";
+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) => {
     for (const [k, v] of Object.entries(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/constants.d.ts

@@ -1,4 +1,4 @@
 export declare const ENGINE_VERSION = "2026.8.35";
 export declare const PROTOCOL_VERSION = 4;
 export declare const LIVE_CATALOGS: string[];
-export declare const OPERATOR_SCOPES: readonly ["operator.read", "operator.write", "operator.admin", "operator.approvals", "operator.questions", "operator.pairing", "operator.talk"];
+export declare const OPERATOR_SCOPES: readonly ['operator.read', 'operator.write', 'operator.admin', 'operator.approvals', 'operator.questions', 'operator.pairing', 'operator.talk'];

package/dist/day-usage.js

@@ -1,5 +1,5 @@
 // Portable additive day reader. No host files, pricing guesses or side totals for persisted turns.
-import { agentUsageOf } from "./usage.js";
+import { agentUsageOf } from './usage.js';
 const object = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
 const count = (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0;
 const text = (v) => typeof v === 'string' && v.length > 0 && v.length <= 512;

package/dist/device.js

@@ -1,7 +1,7 @@
 import { openBoxFromSeed, boxKeyPairFromSeed } from '@byokit/seal';
-import { memberOf } from "./attribution.js";
-import { toAccountView } from "./words.js";
-import { b64urlDecode, b64urlEncode, openNotice } from "./notices.js";
+import { memberOf } from './attribution.js';
+import { toAccountView } from './words.js';
+import { b64urlDecode, b64urlEncode, openNotice } from './notices.js';
 /**
  * The host ended a stream with its own words (e.g. a refusal). Portable twin of link's PublicLinkError:
  * same shape ({ code: 'failed', sealed: true }) so a screen can show .message the same way. A device-side
@@ -418,8 +418,8 @@ export function openclawDevice(link) {
     };
 }
 // Portable, re-exported by ./device (7.3).
-export { openNotice } from "./notices.js";
-export { readAgentUsage, agentUsageOf } from "./usage.js";
-export { readAgentDayUsage } from "./day-usage.js";
+export { openNotice } from './notices.js';
+export { readAgentUsage, agentUsageOf } from './usage.js';
+export { readAgentDayUsage } from './day-usage.js';
 // The kit's sentences, so a phone or browser shows the same words the computer does (5.14).
-export { stateWords, toAccountView, words } from "./words.js";
+export { stateWords, toAccountView, words } from './words.js';

package/dist/engine.d.ts

@@ -2,6 +2,9 @@ import { remoteCliHost } from '@byokit/accounts/cli';
 import { AuthStore, AuthStoreSealSizeError } from './auth-store.ts';
 import type { KitOptions } from './kit.ts';
 import type { KitState, ToolSpec } from './types.ts';
+/** 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 declare function canonicalStateDir(dir: string): string;
 export type EngineOptions = Pick<KitOptions, 'stateDir' | 'engineDir' | 'npmPath' | 'enginePath' | 'config' | 'offered' | 'appOwnedSessions' | 'installPolicy' | 'log' | 'bridge' | 'authSeal'> & {
     pluginId: string;
     tools: ToolSpec[];
@@ -50,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

@@ -2,18 +2,31 @@ import { spawn, spawnSync } from 'node:child_process';
 import { randomBytes, generateKeyPairSync, randomUUID } from 'node:crypto';
 import { accessSync, constants, closeSync, existsSync, mkdirSync, openSync, readFileSync, writeFileSync, copyFileSync, rmSync, realpathSync, statSync } from 'node:fs';
 import { createServer } from 'node:net';
-import { basename, join, dirname } from 'node:path';
+import { basename, join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { setTimeout as delay } from 'node:timers/promises';
 import { cliAccounts, remoteCliHost } from '@byokit/accounts/cli';
-import { AuthStore, AuthStoreUnreadableError, AuthStoreSealSizeError } from "./auth-store.js";
-import { EngineAlreadyRunningError, pidAlive, StartedProcesses } from "./engine-status.js";
-import { EnginePatchError, atomic, prepareEngineSet, processStartTime, readPatchSet, sha256, verifyEngineSet } from "./engine-patches.js";
-import { ENGINE_VERSION } from "./constants.js";
-import { appendUsageBoot } from "./usage-boots.js";
-import { reconcileConfig, appRecoveryPrefixes } from "./config.js";
-import { writePlugin, resolveBridge } from "./bridge.js";
-import { sweepOrphans } from "./accounts.js";
+import { AuthStore, AuthStoreUnreadableError, AuthStoreSealSizeError } from './auth-store.js';
+import { EngineAlreadyRunningError, pidAlive, StartedProcesses } from './engine-status.js';
+import { EnginePatchError, atomic, prepareEngineSet, processStartTime, readPatchSet, sha256, verifyEngineSet } from './engine-patches.js';
+import { ENGINE_VERSION } from './constants.js';
+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) {
+    const path = resolve(dir);
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        const parent = dirname(path);
+        return parent === path ? path : join(canonicalStateDir(parent), basename(path));
+    }
+}
 const kitDir = dirname(dirname(fileURLToPath(import.meta.url)));
 const putOnce = (path, data) => { if (!existsSync(path))
     writeFileSync(path, data, { mode: 0o600, flag: 'wx' }); };
@@ -95,6 +108,7 @@ export class Engine {
     appOwnedSessionPrefixes;
     constructor(o) {
         this.appOwnedSessionPrefixes = appRecoveryPrefixes(o.appOwnedSessions);
+        o = { ...o, stateDir: canonicalStateDir(o.stateDir) };
         this.o = o;
         const bridge = resolveBridge(o.bridge);
         this.root = join(o.stateDir, 'openclaw');
@@ -277,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

@@ -1,10 +1,11 @@
 // @byokit/openclaw — the OpenClaw runtime kit, host side (docs/runtime-kits.md 5.3). Entries: `.` (this),
 // `./device` (portable), `./link` (Node host-side adapter), `./testing` (fakes and contract suite).
-export { ENGINE_VERSION, OPERATOR_SCOPES, PROTOCOL_VERSION } from "./constants.js";
-export { OpenClawKit } from "./kit.js";
-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 { readAgentDayUsage } from "./day-usage.js";
-export { readAgentUsage, agentUsageOf } from "./usage.js";
+export { ENGINE_VERSION, OPERATOR_SCOPES, PROTOCOL_VERSION } from './constants.js';
+export { OpenClawKit } from './kit.js';
+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;
     }>;
@@ -22,6 +31,9 @@ export declare function createKeys(ctx: ActivationCtx & {
     indexLane(member: Member, route: RouteView): Promise<void>;
     dropLane(member: Member, provider?: string): Promise<void>;
     backfillLane(member: Member, model: string | undefined): Promise<void>;
+    /** The provider config headers a live-catalog key's calls and probes must carry (`null` clears them),
+     *  written through the kit's own config patch. The Go workspace header is the one user. */
+    setProviderHeaders(provider: string, headers: Record<string, string> | null): Promise<void>;
 }): {
     models: (member: Member, o: {
         authChoice: string;
@@ -31,6 +43,7 @@ export declare function createKeys(ctx: ActivationCtx & {
         authChoice: string;
         apiKey: string;
         model?: string;
+        orgId?: string;
     }): AddKeyHandle;
     ready(member: Member, o?: {
         once?: boolean;

package/dist/keys.js

@@ -1,10 +1,10 @@
 import { join } from 'node:path';
-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";
+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 { modelsOf } from './accounts.js';
+import { LIVE_CATALOGS } from './constants.js';
 export function createKeys(ctx) {
     // Serialize key replacement and key runs, so an in-flight run never sees a half-installed replacement.
     const tails = new Map();
@@ -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,9 +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).
+                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 () => {
@@ -93,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');
@@ -112,6 +144,18 @@ export function createKeys(ctx) {
                             return cancelled();
                         if (!(await control(member, 'prepare', route.provider)).ok)
                             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 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)
@@ -187,9 +231,13 @@ export function createKeys(ctx) {
                     else if (ready.ok !== true || providerOf(ready.model ?? '') !== o.provider)
                         return;
                 }
+                // The lane's own provider, when the removal can name it: the header clear below is scoped like the removal.
                 const cleared = await control(member, 'clear').catch(() => undefined);
                 if (cleared?.ok !== true && cleared?.absent !== true)
                     refused();
+                // A workspace header the removed key named must not outlive it; the next add names its own (or none).
+                if (o.provider !== undefined && LIVE_CATALOGS.includes(o.provider))
+                    await ctx.setProviderHeaders(o.provider, null).catch(() => { throw new Error('The key could not be removed.'); });
                 await ctx.dropLane(member, o.provider);
             });
         },

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. */
@@ -153,11 +163,15 @@ export declare class OpenClawKit {
     removeAccount(member: Member, id: AccountId): Promise<void>;
     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. */
+    /** 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; 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;
         model?: string;
+        orgId?: string;
     }): AddKeyHandle;
     private indexKeyLane;
     /** Remove this member's saved key (the `byokit-key-<member>` lane: its credential store and ready marker), so