@byokit/openclaw 0.5.1 → 0.6.2

package/dist/runs.js

@@ -84,6 +84,10 @@ export function createRuns(ctx) {
         // 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}"`);
+        // Same validation as the pin's NonEmptyString; preserve the caller's bytes (including whitespace).
+        if (spec.idempotencyKey !== undefined && (typeof spec.idempotencyKey !== 'string' || !spec.idempotencyKey.length))
+            throw new Error('refused: idempotencyKey must be a non-empty string');
+        const idempotencyKey = spec.idempotencyKey ?? randomUUID();
         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);
@@ -92,7 +96,7 @@ export function createRuns(ctx) {
                 throw new Error(`refused: "${tool}" is not one of this kit's tools`);
         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;
+        const release = spec.register !== false ? ctx.bridge.register({ sessionKey, member: spec.member }, spec.tools, idempotencyKey) : undefined;
         let last;
         let runId = ''; // gateway events for other runs carry a real runId and never match the empty one
         let ended = false;
@@ -155,7 +159,7 @@ export function createRuns(ctx) {
                 agentId,
                 sessionKey,
                 message: spec.message,
-                idempotencyKey: randomUUID(),
+                idempotencyKey,
                 ...(picked ?? {}),
                 ...(system ? { extraSystemPrompt: system } : {}),
                 ...(spec.images ? { attachments: spec.images.map((image) => ({ mimeType: image.mimeType, content: image.data })) } : {}),
@@ -166,6 +170,8 @@ 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') {
+                // A cached `in_flight` replay has no final subscription. Keep the existing wait/stream fallback:
+                // re-sending `agent` to fetch its final could dispatch again if the bounded cache was evicted.
                 const done = await Promise.race([final.catch(() => undefined), delay(FINAL_GRACE_MS, undefined, { ref: false })]);
                 ended = true; // no later stream event may supersede the final callback
                 const frame = isRecord(done) && isRecord(done.result) ? done.result : {};

package/dist/signin.d.ts

@@ -9,7 +9,7 @@ export type SignInCtx = {
 };
 /**
  * Drive the engine's provider-owned login. `on` sees every view the person watches; `done` resolves once, and
- * `paste` hands a returned browser address to a waiting wizard text step. Every exit short of done cancels this
+ * `paste` hands a returned browser address or sign-in token to a waiting wizard text step. Every exit short of done cancels this
  * session and its callback listener only.
  */
 export declare function signIn(ctx: SignInCtx, member: Member, o: SignInOptions, on: (v: SignInView) => void): {

package/dist/signin.js

@@ -19,7 +19,7 @@ const cut = (value) => (value instanceof Error ? value.message : String(value)).
 const pullOptions = (signal) => ({ timeoutMs: PULL_MS, signal });
 /**
  * Drive the engine's provider-owned login. `on` sees every view the person watches; `done` resolves once, and
- * `paste` hands a returned browser address to a waiting wizard text step. Every exit short of done cancels this
+ * `paste` hands a returned browser address or sign-in token to a waiting wizard text step. Every exit short of done cancels this
  * session and its callback listener only.
  */
 export function signIn(ctx, member, o, on) {
@@ -68,10 +68,15 @@ export function signIn(ctx, member, o, on) {
     let settle;
     let pasteIn;
     let returned;
+    // Once a secret step is seen, no later gateway prose, link or code is safe to display.
+    let sensitive = o.authChoice === 'setup-token' || o.authChoice === 'apiKey';
+    const secretFailure = () => o.authChoice === 'apiKey' ? 'API key activation failed' : 'Sign-in failed. Try again.';
     const done = new Promise((resolve) => { settle = resolve; });
     const say = (v) => {
         if (!over && !recovering && !signal.aborted)
-            on({ state: 'waiting', via, ...v });
+            on({ state: 'waiting', via, ...(sensitive
+                    ? { ...(v.prompt ? { prompt: v.prompt } : {}), ...(v.error ? { error: secretFailure() } : {}) }
+                    : v) });
     };
     const closeCallback = async () => {
         const held = server;
@@ -90,6 +95,8 @@ export function signIn(ctx, member, o, on) {
         returned = undefined;
         pasteIn = undefined;
         await closeCallback();
+        if (sensitive && view.state === 'failed' && view.why === 'failed')
+            view = { ...view, error: secretFailure() };
         on(view);
         settle(view);
     };
@@ -218,6 +225,10 @@ export function signIn(ctx, member, o, on) {
         const pull = () => ctx.request('wizard.next', { sessionId }, options());
         const answer = (step, value) => ctx.request('wizard.next', { sessionId, answer: { stepId: step.id, ...(value === undefined ? {} : { value }) } }, options());
         const waitForPaste = () => new Promise((resolve) => {
+            if (signal.aborted) {
+                resolve(undefined);
+                return;
+            }
             if (returned !== undefined) {
                 const text = returned;
                 returned = undefined;
@@ -255,7 +266,9 @@ export function signIn(ctx, member, o, on) {
             }
             const current = step;
             step = undefined;
-            if (current.deviceCode) {
+            if (current.type === 'text' && current.sensitive)
+                sensitive = true;
+            if (current.deviceCode && current.type !== 'text') {
                 stopApproval();
                 approval = true;
                 sawDeviceCode = true;
@@ -278,7 +291,9 @@ export function signIn(ctx, member, o, on) {
             }
             if (current.type !== 'progress')
                 stopApproval();
-            if (current.type === 'text' && !current.sensitive) {
+            if (current.type === 'text') {
+                if (current.sensitive)
+                    say({ prompt: 'Sign-in token' });
                 const value = await waitForPaste();
                 if (value === undefined)
                     return signal.aborted ? cancelled() : expired();

package/dist/testing/browser.d.ts

@@ -0,0 +1,50 @@
+import type { BrowserHost, BrowserOptions, LiveFrame, NeedSignIn } from '../browser.ts';
+import { type BrowserHostController, type HostBroker } from '../browser/host.ts';
+import { type SignInStore } from '../browser/store.ts';
+import type { Probe } from '../browser/verify.ts';
+export declare function memorySignInStore(): SignInStore;
+export type BrowserFixture = {
+    /** Set the synthetic address bar; no network call. */
+    navigate(member: string, origin: string): void;
+    authenticated(member: string, value: boolean): void;
+    frame(member: string, frame?: LiveFrame): void;
+    dropStreams(member: string): void;
+    advance(ms: number): Promise<void>;
+    resumeOutcome(value: 'accepted' | 'refused' | 'unknown' | 'throw'): void;
+    closePrivate(member: string, fn: (() => Promise<void>) | undefined): void;
+    probe(member: string, fn: ((p: Probe) => Promise<'ok' | 'fail' | 'timeout'>) | undefined): void;
+    readonly dispatches: {
+        member: string;
+        sessionKey: string;
+        idempotencyKey: string;
+        message: string;
+    }[];
+    readonly parked: {
+        member: string;
+        sessionKey: string;
+    }[];
+    readonly calls: string[];
+    broker(member: string): HostBroker;
+    inputCount(member: string): number;
+    privateOpen(member: string): boolean;
+    fenced(member: string): boolean;
+};
+export type FakeBrowserHost = BrowserHostController & {
+    readonly fixture: BrowserFixture;
+};
+export type FakeBrowserHostOptions = {
+    members?: string[];
+    options?: Partial<BrowserOptions>;
+    store?: SignInStore;
+    authorize?: (grant: string, member: string, control: boolean) => boolean;
+    ping?: (member: string, kind: 'state' | 'signin') => void;
+};
+export declare function fakeBrowserHost(o?: FakeBrowserHostOptions): Promise<FakeBrowserHost>;
+export declare const createBrowserHostFake: typeof fakeBrowserHost;
+/** Reusable public-host contract, fixture controls kept outside BrowserHost. Runs against any host adapter. */
+export declare function browserHostContract(f: {
+    host: BrowserHost;
+    raise(): Promise<NeedSignIn>;
+    signedIn(): void;
+    dispatches(): number;
+}): Promise<void>;

package/dist/testing/browser.js

@@ -0,0 +1,166 @@
+import { fixtureBrowserHost, secureOrigin } from "../browser/host.js";
+import { emptySignIns, validateSignIns } from "../browser/store.js";
+function channel() {
+    let pending;
+    let value;
+    let ended = false;
+    return {
+        push(next) { if (ended)
+            return; if (pending) {
+            const resolve = pending;
+            pending = undefined;
+            resolve({ done: false, value: next });
+        }
+        else
+            value = next; },
+        close() { ended = true; value = undefined; pending?.({ done: true, value: undefined }); pending = undefined; },
+        iterable: { [Symbol.asyncIterator]() {
+                return {
+                    next() {
+                        if (value !== undefined) {
+                            const next = value;
+                            value = undefined;
+                            return Promise.resolve({ done: false, value: next });
+                        }
+                        if (ended)
+                            return Promise.resolve({ done: true, value: undefined });
+                        return new Promise(resolve => { pending = resolve; });
+                    },
+                    return() { ended = true; pending?.({ done: true, value: undefined }); return Promise.resolve({ done: true, value: undefined }); },
+                };
+            } },
+    };
+}
+export function memorySignInStore() {
+    let data = emptySignIns();
+    return { read: () => structuredClone(data), write: next => { data = validateSignIns(next); } };
+}
+export async function fakeBrowserHost(o = {}) {
+    const members = o.members ?? ['ada'];
+    const states = new Map(members.map(member => [member, { origin: 'http://127.0.0.1:2820', privateOrigin: undefined,
+            fenced: false, signedIn: false, binding: undefined,
+            confirmed: new Set(), viewers: new Set(), inputs: 0,
+            closer: undefined, prober: undefined }]));
+    const get = (member) => { const s = states.get(member); if (!s)
+        throw new Error('unknown fixture member'); return s; };
+    const privateState = (member) => {
+        const s = get(member);
+        return s.privateOrigin ? { origin: s.privateOrigin, secure: secureOrigin(s.privateOrigin), offOrigin: !s.binding
+                || !(s.privateOrigin === s.binding.origin || s.binding.knownIdps.includes(s.privateOrigin) || s.confirmed.has(s.privateOrigin)) } : undefined;
+    };
+    const calls = [];
+    const dispatches = [];
+    const parked = [];
+    let now = Date.now();
+    let outcome = 'accepted';
+    let seq = 0;
+    const frame = () => ({ seq: ++seq, at: now, w: 1, h: 1, jpeg: Uint8Array.of(255, 216, 255, 217) });
+    const brokers = new Map(members.map(member => {
+        const s = get(member);
+        return [member, {
+                endpoint: () => ({ cdpUrl: 'ws://127.0.0.1:2820/devtools/browser?token=synthetic' }),
+                async fence(on) { calls.push(`${member}:fence:${on}`); s.fenced = on; },
+                agentTab: () => 'agent',
+                async originOf(target) { return target === 'private' ? s.privateOrigin ?? s.origin : s.origin; },
+                async openPrivate(url) { calls.push(`${member}:open`); s.privateOrigin = new URL(url).origin; return 'private'; },
+                async closePrivate() { calls.push(`${member}:close`); await s.closer?.(); s.privateOrigin = undefined; },
+                async probe(url, verify) {
+                    calls.push(`${member}:probe`);
+                    const p = { url, status: s.signedIn ? 200 : 401, exists: async () => s.signedIn };
+                    return s.prober ? s.prober(p) : await verify(p) ? 'ok' : 'fail';
+                },
+                attachViewer({ lease }) {
+                    const frames = channel();
+                    const liveStates = channel();
+                    const v = { frames, states: liveStates, lease, close: () => { frames.close(); liveStates.close(); s.viewers.delete(v); } };
+                    s.viewers.add(v);
+                    frames.push(frame());
+                    const state = privateState(member);
+                    if (lease && state)
+                        liveStates.push(state);
+                    return { frames: frames.iterable, states: liveStates.iterable,
+                        input(_i) {
+                            // Do not retain, log, event or echo input values, even in this fixture.
+                            const state = privateState(member);
+                            if (lease && s.binding?.epoch === lease.epoch && s.binding.nonce === lease.nonce && state?.secure && !state.offOrigin)
+                                s.inputs++;
+                        }, close: v.close };
+                },
+                async navigateAgent(url) { calls.push(`${member}:navigate`); if (url !== 'reload')
+                    s.origin = new URL(url).origin; },
+                async close() { s.viewers.forEach(v => v.close()); s.privateOrigin = undefined; },
+                bindLease(l) { calls.push(`${member}:bind:${l ? 'on' : 'off'}`); s.binding = l; s.confirmed.clear(); },
+                confirmOrigin(l, origin) {
+                    if (s.binding?.epoch !== l.epoch || s.binding.nonce !== l.nonce || s.privateOrigin !== origin)
+                        return false;
+                    s.confirmed.add(origin);
+                    const state = privateState(member);
+                    if (state)
+                        s.viewers.forEach(v => v.states.push(state));
+                    return true;
+                },
+                privateState: () => privateState(member),
+                async clearSite(origins) { if (s.fenced)
+                    throw new Error('fixture fenced'); calls.push(`${member}:clear:${origins.length}`); s.signedIn = false; },
+            }];
+    }));
+    const defaultVerifier = { origin: 'http://127.0.0.1:2820', url: 'http://127.0.0.1:2820/account', status: 200, selector: '#signed-in' };
+    const host = await fixtureBrowserHost({ brokers, store: o.store ?? memorySignInStore(),
+        options: { executablePath: '/synthetic/chromium', members, verifiers: [defaultVerifier], ...o.options },
+        authorize: o.authorize ?? ((grant, member, control) => members.includes(member) && (grant === 'control' || grant === 'other' || (!control && grant === 'view'))),
+        ping: o.ping,
+        park: async (member, sessionKey) => { parked.push({ member, sessionKey }); },
+        resume: async (input) => { dispatches.push(input); if (outcome === 'throw')
+            throw new Error('synthetic transport drop'); return outcome; },
+        siteOf: origin => new URL(origin).hostname,
+        now: () => now,
+    });
+    const fixture = {
+        navigate(member, origin) {
+            const s = get(member);
+            const exact = new URL(origin).origin;
+            if (s.privateOrigin)
+                s.privateOrigin = exact;
+            else
+                s.origin = exact;
+            const state = privateState(member);
+            if (state)
+                s.viewers.forEach(v => v.states.push(state));
+        },
+        authenticated(member, value) { get(member).signedIn = value; },
+        frame(member, value) { get(member).viewers.forEach(v => v.frames.push(value ?? frame())); },
+        dropStreams(member) { get(member).viewers.forEach(v => v.close()); },
+        async advance(ms) { now += ms; await host.sweep(); },
+        resumeOutcome(value) { outcome = value; },
+        closePrivate(member, fn) { get(member).closer = fn; },
+        probe(member, fn) { get(member).prober = fn; },
+        dispatches, parked, calls,
+        broker: member => { const broker = brokers.get(member); if (!broker)
+            throw new Error('unknown fixture member'); return broker; },
+        inputCount: member => get(member).inputs,
+        privateOpen: member => !!get(member).privateOrigin,
+        fenced: member => get(member).fenced,
+    };
+    return Object.assign(host, { fixture });
+}
+export const createBrowserHostFake = fakeBrowserHost;
+/** Reusable public-host contract, fixture controls kept outside BrowserHost. Runs against any host adapter. */
+export async function browserHostContract(f) {
+    const require = (value) => { if (!value)
+        throw new Error('browser host contract failed'); };
+    const r = await f.raise();
+    require(r.state === 'waiting');
+    require((await f.host.thumbnail({ kind: 'browser', member: r.member }, { grant: 'view' })).state === 'private');
+    const lease = await f.host.takeover(r.id, r.gen, { grant: 'control', confirmSite: r.site });
+    f.signedIn();
+    const settled = await f.host.done(lease);
+    require(settled.state === 'settled' && settled.settled?.state === 'verified' && !!settled.settled.resume?.key);
+    require(f.dispatches() === 1);
+    try {
+        await f.host.done(lease);
+    }
+    catch {
+        return;
+    }
+    throw new Error('browser host contract failed');
+}

package/dist/testing/contract.js

@@ -10,8 +10,7 @@ import assert from 'node:assert/strict';
 import { PROTOCOL_VERSION } from "../constants.js";
 import { GATEWAY_CAPS } from "../transport.js";
 import { releaseStub, stubHolding } from "./model-stub.js";
-// The generated method table arrives with O2; until then kit.call's typed surface accepts no method names, so the
-// suite drives pass-through through this string-typed view of the same runtime path.
+/** The contract drives pass-through by method name, so results arrive untyped and are narrowed per case. */
 const call = (kit, method, params) => kit.call(method, params);
 const REQUIRED_METHODS = [
     'agent', 'agent.wait', 'agents.create', 'agents.list', 'chat.abort', 'config.get', 'config.patch',

package/dist/testing/fake-gateway.d.ts

@@ -1,9 +1,16 @@
-import type { GatewayTransport } from '../types.ts';
+import type { GatewayMethod, GatewayParams, GatewayTransport } from '../types.ts';
 import type { KitOptions } from '../kit.ts';
-type Handler = (params: any, bridgeSock: string) => unknown;
-/** Pre-registered handlers for `fakeGateway(script)`, on top of the defaults (a same-name entry replaces one). */
-export type FakeScript = Record<string, Handler>;
-export declare function fakeGateway(script?: FakeScript): {
+/** A scripted handler's params: the generated type when the pin publishes one, else the raw params object. */
+export type FakeParams<M extends GatewayMethod> = unknown extends GatewayParams<M> ? Record<string, unknown> : GatewayParams<M>;
+/** A scripted handler for one method, with that method's params typed. */
+export type FakeHandler<M extends GatewayMethod = GatewayMethod> = (params: FakeParams<M>, bridgeSock: string) => unknown;
+/** Pre-registered handlers for `fakeGateway(script)`, on top of the defaults (a same-name entry replaces one).
+ * Only methods the pinned engine publishes are scriptable, exactly as `kit.call` and `kit.callDynamic` divide them. */
+export type FakeScript = {
+    [M in GatewayMethod]?: FakeHandler<M>;
+};
+/** The fake's control surface: the transport to hand a kit, the calls it saw, and its triggers. */
+export type FakeGateway = {
     factory: NonNullable<KitOptions['transport']>;
     calls: {
         method: string;
@@ -12,8 +19,8 @@ export declare function fakeGateway(script?: FakeScript): {
     emit(event: string, payload?: unknown): void;
     failNext(method: string, message: string): void;
     drop(why: string): void;
-    handle(method: string, fn: Handler): void;
+    handle(method: string, fn: FakeHandler): void;
 } & {
     transport: GatewayTransport;
 };
-export {};
+export declare function fakeGateway(script?: FakeScript): FakeGateway;

package/dist/testing/fake-gateway.js

@@ -245,12 +245,12 @@ export function fakeGateway(script) {
         '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);
+            const route = routes().find((r) => r.choice === String(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);
+            keys.set(String(p.agentId), { provider: route.provider, key: String(p.apiKey), model, sealed: false });
+            signInAgent(String(p.agentId), route.provider);
             return { ok: true, status: 'ok', modelRef: model };
         },
         'openclaw.setup.auth.start': (p) => {
@@ -325,14 +325,15 @@ export function fakeGateway(script) {
         'exec.approval.request': (p) => {
             const id = String(p.id ?? `exec-${randomUUID()}`);
             const now = Date.now();
+            const plan = isPlainObject(p.systemRunPlan) ? p.systemRunPlan : {};
             emit('exec.approval.requested', {
                 approvalKind: 'exec', id, createdAtMs: now, expiresAtMs: now + 180_000,
                 request: {
                     command: p.command,
                     // Like the real engine, which normalizes the exec policy mode into request.ask (B8).
                     ask: p.ask ?? 'on-miss',
-                    agentId: p.agentId ?? p.systemRunPlan?.agentId,
-                    sessionKey: p.sessionKey ?? p.systemRunPlan?.sessionKey,
+                    agentId: p.agentId ?? plan.agentId,
+                    sessionKey: p.sessionKey ?? plan.sessionKey,
                 },
             });
             return { id };
@@ -366,6 +367,7 @@ export function fakeGateway(script) {
     };
     for (const [method, handler] of Object.entries(defaults))
         handlers.set(method, handler);
+    // A script handler is already per-method typed; the loose internal map only dispatches it.
     for (const [method, handler] of Object.entries(script ?? {}))
         handlers.set(method, handler);
     const dispatch = async (method, params, bridgeSock) => {
@@ -377,7 +379,7 @@ export function fakeGateway(script) {
         const handler = handlers.get(method);
         if (!handler)
             throw new Error(`unknown method: ${method}`);
-        return await handler(params ?? {}, bridgeSock);
+        return await handler(isPlainObject(params) ? params : {}, bridgeSock);
     };
     const hello = () => ({
         protocol: PROTOCOL_VERSION,

package/dist/testing/index.d.ts

@@ -1,3 +1,4 @@
-export { fakeGateway, type FakeScript } from './fake-gateway.ts';
+export { fakeGateway, type FakeGateway, type FakeHandler, type FakeParams, type FakeScript } from './fake-gateway.ts';
+export { fakeBrowserHost, createBrowserHostFake, browserHostContract, memorySignInStore, type FakeBrowserHost, type FakeBrowserHostOptions, type BrowserFixture } from './browser.ts';
 export { openclawContract, type ContractFixture } from './contract.ts';
-export { STUB_USAGE, startModelStub, useModelStub, releaseStub, stubHolding, toolCalls, type ModelStub, type ModelStubOptions, type StubCall } from './model-stub.ts';
+export { STUB_USAGE, startModelStub, useModelStub, releaseStub, stubHolding, toolCalls, type ModelStub, type ModelStubOptions, type StubCall, type StubRequest } from './model-stub.ts';

package/dist/testing/index.js

@@ -1,4 +1,5 @@
 // The kit's fakes, contract suite and scripted model (5.11). Built in O7.
 export { fakeGateway } from "./fake-gateway.js";
+export { fakeBrowserHost, createBrowserHostFake, browserHostContract, memorySignInStore } from "./browser.js";
 export { openclawContract } from "./contract.js";
 export { STUB_USAGE, startModelStub, useModelStub, releaseStub, stubHolding, toolCalls } from "./model-stub.js";

package/dist/testing/model-stub.d.ts

@@ -1,8 +1,21 @@
 import type { OpenClawKit } from '../kit.ts';
+export type StubRequest = {
+    model?: unknown;
+    input?: unknown;
+    messages?: {
+        role?: string;
+        content?: unknown;
+        name?: unknown;
+        tool_call_id?: unknown;
+    }[];
+    stream_options?: {
+        include_usage?: boolean;
+    };
+};
 export type StubCall = {
     authorization: string;
     path: string;
-    body: any;
+    body: StubRequest;
 };
 /** The token usage every stub reply reports when asked (`stream_options.include_usage`), per model call. */
 export declare const STUB_USAGE: {
@@ -30,6 +43,7 @@ export declare const stubHolding: (key?: string) => boolean;
 export type ModelStubOptions = {
     idPattern?: RegExp;
     routingMarker?: string;
+    onCall?: (call: StubCall) => void;
 };
 export declare function startModelStub(script?: string[], o?: ModelStubOptions): Promise<ModelStub>;
 export declare function useModelStub(kit: OpenClawKit, stub: ModelStub): Promise<void>;

package/dist/testing/model-stub.js

@@ -58,7 +58,8 @@ export const releaseStub = (key, reply = '') => {
         }
 };
 export const stubHolding = (key) => (key ? holds.has(key) : holds.size > 0);
-const words = (m) => typeof m?.content === 'string' ? m.content : Array.isArray(m?.content) ? m.content.map((c) => c.text ?? '').join('') : '';
+const words = (m) => typeof m?.content === 'string' ? m.content : Array.isArray(m?.content)
+    ? m.content.map((c) => (typeof c?.text === 'string' ? c.text : '')).join('') : '';
 export function startModelStub(script = [], o = {}) {
     const calls = [];
     const queue = [...script];
@@ -76,7 +77,9 @@ export function startModelStub(script = [], o = {}) {
             res.writeHead(400).end();
             return;
         }
-        calls.push({ authorization: String(req.headers.authorization ?? ''), path: req.url ?? '', body });
+        const call = { authorization: String(req.headers.authorization ?? ''), path: req.url ?? '', body };
+        calls.push(call);
+        o.onCall?.(call); // Fixture evidence is persisted before any response/hold awaits.
         if (req.url === '/api/embed' || req.url === '/api/embeddings') {
             res.writeHead(200, { 'content-type': 'application/json' });
             return res.end(JSON.stringify({
@@ -95,7 +98,7 @@ export function startModelStub(script = [], o = {}) {
         const phrased = (text) => /hit the limit|no helpers in plan|sign me out|ask permission/i.test(text);
         const lastUser = [...users].reverse().find((m) => structural(words(m)))
             ?? [...users].reverse().find((m) => phrased(words(m)))
-            ?? users.at(-1);
+            ?? users.at(-1) ?? {};
         const said = words(lastUser);
         const anchor = messages.lastIndexOf(lastUser);
         const results = anchor < 0 ? [] : messages.slice(anchor + 1).filter((m) => m.role === 'tool');
@@ -111,7 +114,7 @@ export function startModelStub(script = [], o = {}) {
         if (said.startsWith(routingMarker)) {
             const options = [...said.matchAll(/^- ([a-z0-9-]+):/gm)].map((m) => m[1]);
             const pick = /\[route ([a-z0-9-]+|\?)\]/.exec(said)?.[1] ?? 'chief';
-            return plain(res, body, JSON.stringify(Object.fromEntries(options.map((o) => [o, pick === '?' ? 1 / options.length : o === pick ? 0.9 : 0.1 / (options.length - 1)]))));
+            return plain(res, body.model, JSON.stringify(Object.fromEntries(options.map((o) => [o, pick === '?' ? 1 / options.length : o === pick ? 0.9 : 0.1 / (options.length - 1)]))));
         }
         if (/sign me out/i.test(said)) {
             res.writeHead(401, { 'content-type': 'application/json' });
@@ -165,21 +168,18 @@ export function startModelStub(script = [], o = {}) {
         });
     });
 }
-const plain = (res, body, text) => {
+const plain = (res, model, text) => {
     const id = randomUUID();
     res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache' });
-    const chunk = (delta, finish = null) => res.write(`data: ${JSON.stringify({ id, object: 'chat.completion.chunk', created: Math.floor(Date.now() / 1000), model: body.model, choices: [{ index: 0, delta, finish_reason: finish }] })}\n\n`);
+    const chunk = (delta, finish = null) => res.write(`data: ${JSON.stringify({ id, object: 'chat.completion.chunk', created: Math.floor(Date.now() / 1000), model, choices: [{ index: 0, delta, finish_reason: finish }] })}\n\n`);
     chunk({ role: 'assistant', content: text });
     chunk({}, 'stop');
     res.end('data: [DONE]\n\n');
 };
 // provider id 'byokit-stub', model 'test': the stub becomes every agent's primary model.
 export async function useModelStub(kit, stub) {
-    // The generated method table arrives with O2; until then kit.call's typed surface accepts no method names, so
-    // configure through this string-typed view of the same runtime path.
-    const call = kit.call.bind(kit);
-    const current = await call('config.get');
-    await call('config.patch', { baseHash: current.hash, raw: JSON.stringify({
+    const current = await kit.call('config.get', {});
+    await kit.call('config.patch', { baseHash: current.hash, raw: JSON.stringify({
             models: { providers: { 'byokit-stub': {
                         baseUrl: stub.url, apiKey: 'byokit-stub', api: 'openai-completions',
                         models: [{ id: 'test', name: 'Test', reasoning: true, input: ['text'],

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import type { OutputSchema } from './output.ts';
+import type { GatewayEventName, GatewayEventPayload } from './generated/events.ts';
 export type { OutputSchema, SchemaOutput } from './output.ts';
 export type Member = string;
 export interface ToolSpec {
@@ -29,6 +30,9 @@ export interface ToolHost {
 }
 export interface RunSpec<S extends OutputSchema | undefined = OutputSchema | undefined> extends RunRef {
     message: string;
+    /** Stable per-dispatch action key; omit for a fresh UUID. Gateway-wide across agents/sessions for `agent`.
+     * Reuse only for the same input/attempt. In-memory bounded cache, not exactly-once across engine restarts. */
+    idempotencyKey?: string;
     schema?: S;
     system?: string;
     images?: {
@@ -121,8 +125,9 @@ export type Decision = {
 };
 export type KitState = {
     phase: 'stopped' | 'installing' | 'starting' | 'repairing' | 'ready' | 'restarting' | 'failed' | 'needs-update' | 'locked';
-    why?: 'install' | 'handshake' | 'exited' | 'port' | 'version' | 'engine-already-running';
+    why?: 'install' | 'handshake' | 'exited' | 'port' | 'version' | 'engine-already-running' | 'engine-patch';
     retryAt?: number;
+    patchSet?: string | null;
 };
 export type Hello = {
     protocol: number;
@@ -136,13 +141,48 @@ export type Route = {
     choice: string;
     provider: string;
     plugin: string;
-    billing: 'subscription' | 'api' | 'local';
+    billing: 'subscription' | 'api' | 'local' | 'free' | 'unknown';
     auth?: 'cli' | 'api_key' | 'token';
     terms?: 'allowed' | 'grey';
     termsUrl?: string;
-    via: 'browser' | 'code';
+    via: 'browser' | 'code' | 'paste' | 'key' | 'setup_token' | 'cli' | 'plan_key' | 'cloud' | 'local' | 'endpoint';
     prerequisite: string | null;
     offer: boolean;
+    id?: string;
+    name?: string;
+    company?: string;
+    aliases?: string[];
+    offerPolicy?: 'default' | 'explicit';
+    legacy?: {
+        provider: string;
+        via: 'browser' | 'code';
+    };
+    billingFrom?: 'source' | 'host';
+    group?: 'models' | 'services';
+    platforms?: {
+        node: 'yes' | 'host' | 'no';
+        browser: 'yes' | 'host' | 'no';
+        rn: 'yes' | 'host' | 'no';
+    };
+    needs?: {
+        binary?: string;
+        plugin?: string;
+        client?: string;
+    };
+    install?: {
+        npmSpec?: string;
+        clawhubSpec?: string;
+        minHostVersion?: string;
+    };
+    upstream?: {
+        surface: 'openclaw';
+        id: string;
+        method?: string;
+        revision: string;
+        flow: 'present' | 'absent';
+    };
+    readiness?: 'ready' | 'needs_binary' | 'needs_plugin' | 'needs_host' | 'needs_client' | 'unsupported_platform' | 'no_upstream_flow';
+    why?: string;
     reason: string;
     source: string;
     revision: string;
@@ -173,5 +213,12 @@ export type CallOptions = {
     timeoutMs?: number | null;
     signal?: AbortSignal;
 };
+/** Kit-owned invalidation only: no origin, URL, input value or lease secret. */
+export type BrowserPing = {
+    member: Member;
+    kind: 'state' | 'signin';
+};
+export type KitEventName = GatewayEventName | 'byokit.browser';
+export type KitEventPayload<E extends KitEventName> = E extends 'byokit.browser' ? BrowserPing : GatewayEventPayload<Extract<E, GatewayEventName>>;
 export type { GatewayMethod, GatewayParams, GatewayResult } from './generated/methods.ts';
 export type { GatewayEventName, GatewayEventPayload } from './generated/events.ts';

package/dist/usage-boots.d.ts

@@ -0,0 +1,8 @@
+export declare function appendUsageBoot(dir: string, record: {
+    bootId: string;
+} & ({
+    startedAt: number;
+} | {
+    failedAt: number;
+    spawned: false;
+})): void;