@byokit/openclaw 0.14.0 → 0.14.4

package/dist/kit.js

@@ -1,31 +1,33 @@
+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';
 import { isDeepStrictEqual } from 'node:util';
 import { fileURLToPath } from 'node:url';
-import { PROTOCOL_VERSION, LIVE_CATALOGS } from "./constants.js";
-import { atomic } from "./engine-patches.js";
-import { Approvals } from "./approvals.js";
-import { Bridge } from "./bridge.js";
-import { Engine, refusedOnly } from "./engine.js";
-import { AuthStoreSealSizeError } from "./auth-store.js";
-import { gatewayTransport } from "./transport.js";
-import { createMembers } from "./members.js";
-import { createAccounts, memberOfAccount } from "./accounts.js";
-import { createLocks } from "./locks.js";
-import { keyAgentId, KEY_PREFIX, MEMBER_ID } from "./members.js";
-import { confirmRetainedLogin as confirmLogin, migrateRetainedLogin as migrateLogin } from "./migrate.js";
-import { createRuns, signedInProviders } from "./runs.js";
-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 { 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";
-import { createBrowserHost } from "./browser/host.js";
-import { fileSignInStore } from "./browser/store.js";
-import { launchBroker } from "./browser/broker.js";
+import { PROTOCOL_VERSION, LIVE_CATALOGS } from './constants.js';
+import { atomic } from './engine-patches.js';
+import { Approvals } from './approvals.js';
+import { Bridge } from './bridge.js';
+import { Engine, canonicalStateDir, refusedOnly } from './engine.js';
+import { AuthStoreSealSizeError } from './auth-store.js';
+import { gatewayTransport } from './transport.js';
+import { createMembers } from './members.js';
+import { createAccounts, memberOfAccount } from './accounts.js';
+import { createLocks } from './locks.js';
+import { keyAgentId, KEY_PREFIX, MEMBER_ID } from './members.js';
+import { confirmRetainedLogin as confirmLogin, migrateRetainedLogin as migrateLogin } from './migrate.js';
+import { createRuns, signedInProviders } from './runs.js';
+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';
+import { createBrowserHost } from './browser/host.js';
+import { fileSignInStore } from './browser/store.js';
+import { launchBroker } from './browser/broker.js';
 /** The engine's learning-mode config key (5.6 "Engine learning state"). */
 const LEARNING_KEY = 'skills.workshop.autonomous.mode';
 const RESTART_MS = 60_000;
@@ -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().
@@ -651,7 +654,7 @@ export class OpenClawKit {
                 || (o.browser && ['browser', 'request_sign_in', 'exec', 'process', 'code_execution', 'terminal', 'read', 'write', 'edit', 'apply_patch', 'gateway'].includes(t.name)))
                 throw new Error(`invalid tool name: ${t.name}`);
         }
-        this.o = o;
+        this.o = { ...o, stateDir: canonicalStateDir(o.stateDir) };
         this.engine = new Engine({ ...o, pluginId: o.plugin?.id ?? 'byokit', tools: [...o.tools ?? [], ...(o.browser ? [{
                         name: 'request_sign_in', description: 'Ask the person to sign in to the current browser site.',
                         parameters: { type: 'object', additionalProperties: false, properties: {
@@ -668,10 +671,12 @@ 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(),
-            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 } } } }) });
         const slot = {};
         this.approvalsCtl = new Approvals({
             request: (method, params, co) => this.request()(method, params, co),
@@ -960,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);
@@ -1068,7 +1132,10 @@ export class OpenClawKit {
             return Promise.reject(new Error('gateway not ready'));
         return this.accountsCtl.setDefaults(member, d);
     }
-    /** Save an explicitly supplied API key (billed per use) in this member's separate key agent. */
+    /** 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, o) {
         return this.keys.add(agentId, o);
     }
@@ -1095,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) {
@@ -1137,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),
@@ -1230,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/link.js

@@ -7,11 +7,11 @@ import { createServer } from 'node:http';
 import { WebSocketServer } from 'ws';
 import { PublicLinkError, } from '@byokit/pair';
 import { reach } from '@byokit/discover';
-import { ENGINE_VERSION } from "./constants.js";
-import { b64urlDecode, b64urlEncode, sealNotice } from "./notices.js";
-import { routeFor } from "./routes.js";
-import { outputSchema } from "./output.js";
-import { stateWords, words } from "./words.js";
+import { ENGINE_VERSION } from './constants.js';
+import { b64urlDecode, b64urlEncode, sealNotice } from './notices.js';
+import { routeFor } from './routes.js';
+import { outputSchema } from './output.js';
+import { stateWords, words } from './words.js';
 const VIEW_OPS = new Set(['oc.state', 'oc.routes', 'oc.signin.view', 'oc.sessions', 'oc.approvals', 'oc.events',
     'oc.browser.state', 'oc.browser.signins', 'oc.browser.thumb']);
 // This kit's own version, read once from its package.json (beside src/ and dist/ alike).

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/migrate.js

@@ -2,9 +2,9 @@
 // only when the Gateway itself reports every provider signed in.
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { retireArchive } from "./auth-store.js";
-import { MEMBER_ID } from "./members.js";
-import { providers } from "./signin.js";
+import { retireArchive } from './auth-store.js';
+import { MEMBER_ID } from './members.js';
+import { providers } from './signin.js';
 const MOVED = '.moved-to-engine';
 const MARKER = '.canonicalized';
 const TRY_MS = 1_500;

package/dist/pick.js

@@ -1,4 +1,4 @@
-import { words } from "./words.js";
+import { words } from './words.js';
 const DAY_MS = 24 * 60 * 60 * 1000;
 const finite = (n) => typeof n === 'number' && Number.isFinite(n);
 /** The lowercased provider of a well-formed `provider/model` reference; undefined when the reference is malformed. */

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');
+}