@byokit/openclaw 0.3.6 → 0.5.0

package/dist/runs.js

@@ -2,6 +2,8 @@
 import { randomUUID } from 'node:crypto';
 import { setTimeout as delay } from 'node:timers/promises';
 import { authStatus } from "./auth-status.js";
+import { outputSchema } from "./output.js";
+import { words } from "./words.js";
 import { classify } from "./classify.js";
 // The gateway gives up on a silent run after an hour; we wait ten minutes longer for the reply frame itself.
 const WAIT_MS = 3_600_000;
@@ -78,17 +80,20 @@ export function createRuns(ctx) {
             return undefined;
         }
     };
-    const run = async (spec, on) => {
+    const run = async (spec, on, keyAgent, preparedOutput) => {
         // Member boundary first: a member never speaks in another member's session, refused before any request.
         if (!spec.sessionKey.startsWith(`agent:${spec.member}:`))
             throw new Error(`refused: "${spec.sessionKey}" is not a session of member "${spec.member}"`);
+        const output = preparedOutput ?? (spec.schema === undefined ? undefined : outputSchema(spec.schema));
+        const system = [spec.system, output?.prompt].filter(Boolean).join('\n\n');
         const picked = spec.model === undefined ? undefined : account(spec.model);
         for (const tool of spec.tools ?? [])
             if (!ctx.tools.has(tool))
                 throw new Error(`refused: "${tool}" is not one of this kit's tools`);
-        const { agentId } = await ctx.ensure(spec.member);
-        const release = spec.register !== false ? ctx.bridge.register({ sessionKey: spec.sessionKey, member: spec.member }, spec.tools) : undefined;
-        let last = '';
+        const agentId = keyAgent ?? (await ctx.ensure(spec.member)).agentId;
+        const sessionKey = keyAgent ? `agent:${keyAgent}:${spec.sessionKey.slice(`agent:${spec.member}:`.length)}` : spec.sessionKey;
+        const release = spec.register !== false ? ctx.bridge.register({ sessionKey, member: spec.member }, spec.tools) : undefined;
+        let last;
         let runId = ''; // gateway events for other runs carry a real runId and never match the empty one
         let ended = false;
         // The engine flags an aborted run on its lifecycle end event; the wait receipt itself only says
@@ -148,11 +153,11 @@ export function createRuns(ctx) {
             };
             const final = ctx.request('agent', {
                 agentId,
-                sessionKey: spec.sessionKey,
+                sessionKey,
                 message: spec.message,
                 idempotencyKey: randomUUID(),
                 ...(picked ?? {}),
-                ...(spec.system ? { extraSystemPrompt: spec.system } : {}),
+                ...(system ? { extraSystemPrompt: system } : {}),
                 ...(spec.images ? { attachments: spec.images.map((image) => ({ mimeType: image.mimeType, content: image.data })) } : {}),
                 ...(spec.thinking ? { thinking: spec.thinking } : {}),
             }, { expectFinal: true, timeoutMs: WAIT_CLIENT_MS, onAccepted });
@@ -161,15 +166,28 @@ export function createRuns(ctx) {
             runId = started.runId;
             const result = await ctx.request('agent.wait', { runId, timeoutMs: WAIT_MS }, { timeoutMs: WAIT_CLIENT_MS });
             if (result.status === 'ok') {
-                const text = typeof result.terminalReply?.text === 'string' ? result.terminalReply.text : last;
-                on?.({ type: 'text', text }); // the final cumulative text
                 const done = await Promise.race([final.catch(() => undefined), delay(FINAL_GRACE_MS, undefined, { ref: false })]);
-                const meta = isRecord(done) && isRecord(done.result) && isRecord(done.result.meta) ? done.result.meta : {};
+                ended = true; // no later stream event may supersede the final callback
+                const frame = isRecord(done) && isRecord(done.result) ? done.result : {};
+                const payloadText = Array.isArray(frame.payloads)
+                    ? frame.payloads.filter((p) => isRecord(p) && typeof p.text === 'string')
+                        .map((p) => p.text) : [];
+                // The pin's terminal snapshot is capped display evidence, not the complete generated answer.
+                // Its silent/empty disposition still controls visibility, even after transient streamed text.
+                const terminal = result.terminalReply;
+                const text = terminal?.disposition === 'silent' || terminal?.disposition === 'empty' ? ''
+                    : payloadText.length ? payloadText.join('\n\n')
+                        : last ?? (typeof terminal?.text === 'string' ? terminal.text : '');
+                on?.({ type: 'text', text }); // the final cumulative text (unvalidated)
+                const parsed = output?.parse(text);
+                if (output && !parsed)
+                    return { ok: false, kind: 'output', message: words('member.output') };
+                const meta = isRecord(frame.meta) ? frame.meta : {};
                 const agentMeta = isRecord(meta.agentMeta) ? meta.agentMeta : {};
                 const usage = usageOf(agentMeta);
                 const planWindow = typeof agentMeta.provider === 'string'
                     ? await planWindowOf(agentId, agentMeta.provider.toLowerCase()) : undefined;
-                return { ok: true, text, ...(usage ? { usage } : {}), ...(planWindow ? { planWindow } : {}) };
+                return { ok: true, text, ...(parsed ? { data: parsed.data } : {}), ...(usage ? { usage } : {}), ...(planWindow ? { planWindow } : {}) };
             }
             if (result.stopReason === 'aborted' || (abortedByEngine && result.status !== 'ok'))
                 return { ok: false, aborted: true };

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

@@ -1,3 +1,5 @@
+import type { OutputSchema } from './output.ts';
+export type { OutputSchema, SchemaOutput } from './output.ts';
 export type Member = string;
 export interface ToolSpec {
     name: string;
@@ -25,8 +27,9 @@ export interface ToolHost {
     }): Promise<GateResult>;
     call(run: RunRef, tool: string, input: Record<string, unknown>, signal: AbortSignal): Promise<string>;
 }
-export interface RunSpec extends RunRef {
+export interface RunSpec<S extends OutputSchema | undefined = OutputSchema | undefined> extends RunRef {
     message: string;
+    schema?: S;
     system?: string;
     images?: {
         data: string;
@@ -34,6 +37,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;
 }
@@ -69,9 +74,10 @@ export type PlanWindow = {
         resetAt?: number;
     }[];
 };
-export type RunEnd = {
+export type RunEnd<T = unknown> = {
     ok: true;
     text: string;
+    data?: T;
     usage?: RunUsage;
     planWindow?: PlanWindow;
 } | {
@@ -79,7 +85,7 @@ export type RunEnd = {
     aborted: true;
 } | {
     ok: false;
-    kind: 'signed-out' | 'resting' | 'plan' | 'network' | 'other';
+    kind: 'signed-out' | 'resting' | 'plan' | 'network' | 'other' | 'output';
     until?: number;
     message: string;
 };
@@ -139,6 +145,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/types.js

@@ -1,2 +1 @@
-// Public types for the OpenClaw runtime kit (docs/runtime-kits.md 5.2). Types only; behavior lives in the modules.
 export {};

package/dist/words.json

@@ -11,6 +11,7 @@
     "member.signedOut": "Sign in with {name} to start.",
     "member.resting": "{name} needs a break until {time}.",
     "member.plan": "Your {name} plan doesn't include this.",
+    "member.output": "The answer did not match the requested format.",
     "member.network": "Can't reach {name} right now. This keeps trying by itself.",
     "signin.returned": "Thanks. Finishing the sign-in — you can go back to the app now.",
     "signin.busy": "Another sign-in is already in progress. Finish or cancel it, then try again.",
@@ -19,5 +20,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.6",
+  "version": "0.5.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",
@@ -53,8 +53,8 @@
   },
   "dependencies": {
     "@byokit/link": "0.7.0",
-    "@byokit/relay": "0.5.0",
-    "@byokit/reach": "0.5.0",
+    "@byokit/relay": "0.5.1",
+    "@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.5.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' });
+}