@byokit/openclaw 0.3.5 → 0.4.0

package/dist/testing/fake-gateway.js

@@ -7,6 +7,7 @@ import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { ENGINE_VERSION, PROTOCOL_VERSION } from "../constants.js";
 import { toolCalls } from "./model-stub.js";
+import { routes } from "../routes.js";
 // The device-code script from Crewhouse's openclaw-wizard.test.ts, ported: the step, then progress, then done.
 const DEVICE_STEP = {
     id: 'step-device', type: 'note', executor: 'client',
@@ -98,6 +99,7 @@ export function fakeGateway(script) {
     const failures = new Map();
     const handlers = new Map();
     const agents = new Map();
+    const keys = new Map();
     const wizards = new Map();
     const runs = new Map();
     const configBox = { hash: 'hash-1', config: {} };
@@ -220,8 +222,37 @@ export function fakeGateway(script) {
             const agent = agents.get(String(p?.agentId ?? 'main'));
             if (agent)
                 agent.providers = agent.providers.filter((provider) => provider !== p.provider);
+            if (keys.get(String(p.agentId))?.provider === p.provider)
+                keys.delete(String(p.agentId));
             return {};
         },
+        'byokit.keys': (p) => {
+            const id = `byokit-key-${p.member}`;
+            if (p.action === 'prepare') {
+                keys.delete(id);
+                ensureAgent(id).providers = [];
+                return { ok: true };
+            }
+            const key = keys.get(id);
+            if (!key)
+                return { ok: false };
+            if (p.action === 'seal') {
+                key.sealed = true;
+                return { ok: true };
+            }
+            return { ok: key.sealed, ...(key.sealed ? { model: key.model } : {}) };
+        },
+        'openclaw.setup.activate': (p) => {
+            if (p.kind !== 'api-key')
+                throw new Error('only the API-key setup path is simulated');
+            const route = routes().find((r) => r.choice === p.authChoice && r.keyEntry);
+            if (!route)
+                return { ok: false, status: 'unavailable' };
+            const model = `${route.provider}/fake-key-model`;
+            keys.set(p.agentId, { provider: route.provider, key: p.apiKey, model, sealed: false });
+            signInAgent(p.agentId, route.provider);
+            return { ok: true, status: 'ok', modelRef: model };
+        },
         'openclaw.setup.auth.start': (p) => {
             const sessionId = String(p.sessionId ?? `fake-${randomUUID()}`);
             wizards.set(sessionId, { agentId: String(p.agentId ?? 'main'), answered: false, pulls: 0 });
@@ -338,7 +369,8 @@ export function fakeGateway(script) {
     for (const [method, handler] of Object.entries(script ?? {}))
         handlers.set(method, handler);
     const dispatch = async (method, params, bridgeSock) => {
-        calls.push({ method, params });
+        calls.push({ method, params: method === 'openclaw.setup.activate' && isPlainObject(params)
+                ? { ...params, ...(params.apiKey === undefined ? {} : { apiKey: '[redacted]' }) } : params });
         const queue = failures.get(method);
         if (queue?.length)
             throw new Error(queue.shift());

package/dist/types.d.ts

@@ -34,6 +34,8 @@ export interface RunSpec extends RunRef {
     }[];
     thinking?: 'off' | 'low' | 'medium' | 'high';
     model?: string;
+    /** Explicit paid key choice. Uses a separate member-owned agent and separate session history. */
+    auth?: 'apiKey';
     tools?: string[];
     register?: boolean;
 }
@@ -139,6 +141,14 @@ export type Route = {
     offer: boolean;
     reason: string;
     source: string;
+    revision: string;
+    checked: string;
+    label: string;
+    keyEntry: boolean;
+    keyErrors: {
+        invalid: 'key.invalid';
+        not_included: 'key.notIncluded';
+    } | null;
 };
 export interface GatewayTransport {
     start(): Promise<Hello>;

package/dist/words.json

@@ -19,5 +19,12 @@
     "approval.ask": "{helper} wants to {summary}. Allow it?",
     "approval.expired": "Nobody answered in time, so this wasn't allowed.",
     "approval.notice": "Something is waiting for your yes.",
-    "link.notAllowed": "This device can't do that. Ask the person at the computer."
+    "link.notAllowed": "This device can't do that. Ask the person at the computer.",
+    "key.label": "API key (billed per use)",
+    "key.entry": "Paste your API key. You pay the provider for each use.",
+    "key.checking": "Checking your key…",
+    "key.ok": "Your key is ready. Use it only when you choose this option.",
+    "key.invalid": "This key could not be saved. Check it and try again.",
+    "key.notIncluded": "This option is not available here.",
+    "key.missing": "Add an API key to use this option."
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/openclaw",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "description": "The OpenClaw runtime kit: the pinned engine's full operator surface with plain-words helpers for members, sign-in, runs and approvals.",
   "license": "Apache-2.0",
   "type": "module",
@@ -52,9 +52,9 @@
     "prepack": "tsc -b && node ../../scripts/fix-words-dts.cjs"
   },
   "dependencies": {
-    "@byokit/link": "0.6.0",
-    "@byokit/relay": "0.4.2",
-    "@byokit/reach": "0.4.0",
+    "@byokit/link": "0.7.0",
+    "@byokit/relay": "0.5.0",
+    "@byokit/reach": "0.6.0",
     "@byokit/seal": "0.2.0",
     "@byokit/secrets": "0.5.0",
     "@openclaw/gateway-client": "2026.8.1",
@@ -62,7 +62,7 @@
     "ws": "8.21.3"
   },
   "devDependencies": {
-    "@byokit/ui-core": "0.4.0"
+    "@byokit/ui-core": "0.6.0"
   },
   "publishConfig": {
     "access": "public"

package/plugin/index.js

@@ -3,6 +3,7 @@
 // schemas and descriptions stay app data. No imports beyond node builtins: nothing here needs resolving in-gateway.
 import { connect } from 'node:net';
 import { readFileSync } from 'node:fs';
+import { registerKeys } from './keys.js';
 
 /** TypeBox's Kind is a global symbol, so these schemas are valid TypeBox without importing typebox. */
 const Kind = Symbol.for('TypeBox.Kind');
@@ -114,6 +115,7 @@ export default {
     jsonSchema: { type: 'object', additionalProperties: false, properties: {} },
   },
   register(api) {
+    if (api.registerGatewayMethod) registerKeys(api);
     for (const spec of table.tools) {
       api.registerTool({
         name: spec.name,

package/plugin/keys.js

@@ -0,0 +1,101 @@
+// Agent-local key isolation. The engine owns the SQLite transaction and publishes the changed runtime snapshot.
+// No key value crosses this method. Only the typed setup.activate request ever carries a secret.
+export function registerKeys(api) {
+  api.registerGatewayMethod('byokit.keys', async ({ params, respond }) => {
+    const member = params?.member;
+    if (typeof member !== 'string' || !/^[a-z][a-z0-9-]{0,31}$/.test(member) || member.startsWith('byokit-key-')
+      || !['prepare', 'seal', 'ready'].includes(params.action)) {
+      respond(true, { ok: false });
+      return;
+    }
+    const diagnostics = params.action === 'ready' && params.diagnostics === true ? { stage: 'imports' } : undefined;
+    const reply = (value) => respond(true, { ...value, ...(diagnostics ? { diagnostics } : {}) });
+    try {
+      const { readFile, writeFile, rm } = await import('node:fs/promises');
+      const { join } = await import('node:path');
+      const { resolveAgentDir } = await import('openclaw/plugin-sdk/agent-runtime');
+      const { updateAuthProfileStoreWithLock } = await import('openclaw/plugin-sdk/provider-auth');
+      // Read the current config: activation changes the roster and selection during the same gateway lifetime.
+      if (diagnostics) diagnostics.stage = 'config';
+      const config = JSON.parse(await readFile(process.env.OPENCLAW_CONFIG_PATH, 'utf8'));
+      const keyId = `byokit-key-${member}`;
+      if (!config.agents?.entries?.[member] || !config.agents?.entries?.[keyId]) {
+        reply({ ok: false });
+        return;
+      }
+      const keyDir = resolveAgentDir(config, keyId);
+      const marker = join(keyDir, 'byokit-key-ready.json');
+      if (params.action === 'ready') {
+        if (diagnostics) diagnostics.stage = 'marker';
+        const selected = JSON.parse(await readFile(marker, 'utf8'));
+        let ready = false;
+        if (diagnostics) diagnostics.stage = 'store';
+        await updateAuthProfileStoreWithLock({ agentDir: keyDir, updater(store) {
+          if (diagnostics) {
+            diagnostics.profiles = Object.entries(store.profiles).map(([id, p]) => ({ id, apiKey: p.type === 'api_key', local: p.copyToAgents === false }));
+            diagnostics.order = store.order;
+            diagnostics.selected = selected.profileId;
+            diagnostics.stage = 'checked';
+          }
+          const profile = store.profiles[selected.profileId];
+          ready = profile?.type === 'api_key' && profile.copyToAgents === false
+            && store.order?.[profile.provider]?.length === 1 && store.order[profile.provider][0] === selected.profileId;
+          return false;
+        } });
+        reply({ ok: ready, ...(ready ? { model: selected.model } : {}) });
+        return;
+      }
+      await rm(marker, { force: true });
+      if (params.action === 'prepare') {
+        // Only local profiles are loaded by this transaction: no shared-store read-through or CLI sync.
+        const normal = await updateAuthProfileStoreWithLock({
+          agentDir: resolveAgentDir(config, member),
+          saveOptions: { filterExternalAuthProfiles: false, syncExternalCli: false },
+          updater(store) {
+            if (Object.values(store.profiles).some((p) => p.type === 'api_key'))
+              throw new Error('The normal agent already has a key.');
+            const providers = new Set([params.provider, ...Object.values(store.profiles).map((p) => p.provider)].filter((p) => typeof p === 'string'));
+            store.order ??= {};
+            for (const provider of providers) store.order[provider] = Object.entries(store.profiles)
+              .filter(([, p]) => p.provider === provider && p.type === 'oauth').map(([id]) => id);
+            return true;
+          },
+        });
+        if (!normal) { respond(true, { ok: false }); return; }
+        // A replacement starts empty. During activation this agent is unavailable to kit.run.
+        const cleared = await updateAuthProfileStoreWithLock({ agentDir: keyDir,
+          saveOptions: { filterExternalAuthProfiles: false, syncExternalCli: false },
+          updater(store) { store.profiles = {}; store.order = {}; return true; } });
+        respond(true, { ok: Boolean(cleared) });
+        return;
+      }
+      const ref = config.agents.entries[keyId].model;
+      const primary = typeof ref === 'string' ? ref : ref?.primary;
+      const at = typeof primary === 'string' ? primary.lastIndexOf('@') : -1;
+      if (at < 1) { respond(true, { ok: false }); return; }
+      const profileId = primary.slice(at + 1);
+      const model = primary.slice(0, at);
+      let found = false;
+      const sealed = await updateAuthProfileStoreWithLock({ agentDir: keyDir,
+        saveOptions: { filterExternalAuthProfiles: false, syncExternalCli: false },
+        updater(store) {
+          const profile = store.profiles[profileId];
+          if (profile?.type !== 'api_key') return false;
+          found = true;
+          profile.copyToAgents = false;
+          store.profiles = { [profileId]: profile };
+          // A stored agent-local order wins over global config and contains exactly this key, never a sign-in.
+          store.order = { [profile.provider]: [profileId] };
+          store.lastGood = {};
+          return true;
+        },
+      });
+      if (!sealed || !found) { respond(true, { ok: false }); return; }
+      await writeFile(marker, JSON.stringify({ profileId, model }), { mode: 0o600 });
+      respond(true, { ok: true });
+    } catch {
+      // Neither engine errors nor store contents (which contain secrets) ever leave this method.
+      reply({ ok: false });
+    }
+  }, { scope: 'operator.admin' });
+}