@byokit/openclaw 0.5.0 → 0.6.1

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

@@ -5,10 +5,11 @@ export type SignInCtx = {
         agentId: string;
     }>;
     callbackPort: number;
+    onDisconnect?(fn: () => void): () => void;
 };
 /**
  * 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

@@ -12,19 +12,21 @@ const START_MS = 60_000;
 const PULL_MS = 120_000;
 const STATUS_MS = 20_000;
 const CANCEL_MS = 10_000;
+const RECONFIRM_MS = 60_000;
 const TURNS = 200;
 const PASTE_MS = 15 * 60_000;
 const cut = (value) => (value instanceof Error ? value.message : String(value)).slice(0, 200);
 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) {
     const via = o.via ?? 'browser';
     const owner = new AbortController();
     const { signal } = owner;
+    const driveOwner = new AbortController();
     const wantsCallback = via === 'browser' && o.authChoice === 'openai';
     let server;
     let sessionId = '';
@@ -33,6 +35,24 @@ export function signIn(ctx, member, o, on) {
     let settleStart;
     const startingSettled = new Promise((resolve) => { settleStart = resolve; });
     let over = false;
+    let recovering = false;
+    let offDisconnect;
+    let agentId;
+    let before;
+    // Only ChatGPT's OAuth routes are qualified for auth-reload recovery. No API-key fallback.
+    const reconfirm = o.authChoice === 'openai' || o.authChoice === 'openai-device-code';
+    // Pin models-auth-status: profiles carry {profileId, type, status, expiry: {at, remainingMs, label}}.
+    // Older summaries are not credential proof; a refreshed pre-existing id cannot stand in for this login.
+    const profiles = (status, usable = true) => {
+        const auth = status;
+        if (auth?.unavailable || !Array.isArray(auth?.providers) || auth.providers.some((row) => !row || typeof row !== 'object' || typeof row.provider !== 'string' || !Array.isArray(row.profiles)
+            || row.profiles.some((p) => !p || typeof p.profileId !== 'string' || typeof p.type !== 'string')))
+            return undefined;
+        return new Set(auth.providers.filter((row) => row.provider === 'openai').flatMap((row) => (row.profiles ?? []).filter((p) => p.type === 'oauth' && typeof p.profileId === 'string'
+            && (!usable || ((p.status === 'ok' || p.status === 'expiring') && Number.isFinite(p.expiry?.at)
+                && p.expiry.at > Date.now())))
+            .map((p) => p.profileId)));
+    };
     let approval = false;
     let sawDeviceCode = false;
     let codeExpired = false;
@@ -48,8 +68,16 @@ 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) => on({ state: 'waiting', via, ...v });
+    const say = (v) => {
+        if (!over && !recovering && !signal.aborted)
+            on({ state: 'waiting', via, ...(sensitive
+                    ? { ...(v.prompt ? { prompt: v.prompt } : {}), ...(v.error ? { error: secretFailure() } : {}) }
+                    : v) });
+    };
     const closeCallback = async () => {
         const held = server;
         server = undefined;
@@ -61,11 +89,14 @@ export function signIn(ctx, member, o, on) {
             return;
         over = true;
         stopApproval();
+        offDisconnect?.();
         o.signal?.removeEventListener('abort', cancel);
         owner.abort();
         returned = undefined;
         pasteIn = undefined;
         await closeCallback();
+        if (sensitive && view.state === 'failed' && view.why === 'failed')
+            view = { ...view, error: secretFailure() };
         on(view);
         settle(view);
     };
@@ -76,7 +107,7 @@ export function signIn(ctx, member, o, on) {
             // and leaves the person locked out of signing in. Waiting for that settlement is what frees the admission.
             await startingSettled;
             if (sessionId)
-                await ctx.request('wizard.cancel', { sessionId }, { timeoutMs: CANCEL_MS }).catch(() => { });
+                await Promise.resolve().then(() => ctx.request('wizard.cancel', { sessionId }, { timeoutMs: CANCEL_MS })).catch(() => { });
         })();
         return releasing;
     };
@@ -130,12 +161,18 @@ export function signIn(ctx, member, o, on) {
         });
     };
     const drive = async () => {
+        const signal = AbortSignal.any([owner.signal, driveOwner.signal]);
         if (wantsCallback) {
             server = await holdCallback().catch(() => undefined);
             if (!server)
                 return { state: 'failed', via, why: 'busy' };
         }
-        const { agentId } = await ctx.ensure(member);
+        ({ agentId } = await ctx.ensure(member));
+        if (reconfirm && ctx.onDisconnect) {
+            before = profiles(await authStatus(ctx.request, agentId).catch(() => undefined), false);
+            if (signal.aborted)
+                return cancelled();
+        }
         // Native login is completed by the person in unmodified Claude Code. The pin does not expose this
         // choice via auth.start; activation verifies the CLI route and persists it only after a live test succeeds.
         if (o.authChoice === 'anthropic-cli' || o.authChoice === 'apiKey') {
@@ -188,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;
@@ -225,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;
@@ -248,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();
@@ -292,10 +337,61 @@ export function signIn(ctx, member, o, on) {
             return expired();
         return error ? { state: 'failed', via, why: 'failed', error: cut(error) } : { state: 'done', via };
     };
+    const disconnected = new Promise((resolve) => {
+        if (reconfirm)
+            offDisconnect = ctx.onDisconnect?.(() => {
+                recovering = true;
+                resolve(undefined); // win the race before the old request's abort/close rejection propagates
+                driveOwner.abort();
+            });
+    });
+    const recover = async () => {
+        const failed = { state: 'failed', via, why: 'failed', error: 'Sign-in could not be confirmed after the gateway restarted. Try again.' };
+        if (!agentId || !before)
+            return failed;
+        const recovery = new AbortController();
+        const recoverySignal = AbortSignal.any([signal, recovery.signal]);
+        let timer;
+        let abort;
+        const end = new Promise((resolve) => {
+            abort = () => resolve(codeExpired ? expired() : cancelled());
+            signal.addEventListener('abort', abort, { once: true });
+            timer = setTimeout(() => resolve(failed), RECONFIRM_MS);
+            if (signal.aborted)
+                abort();
+        });
+        const readback = async () => {
+            while (!recoverySignal.aborted && !over) {
+                const status = await Promise.resolve().then(() => ctx.request('models.authStatus', { agentId, refresh: true }, { timeoutMs: STATUS_MS, signal: recoverySignal })).catch(() => undefined);
+                const after = profiles(status);
+                if (!recoverySignal.aborted && after && [...after].some((p) => !before.has(p)))
+                    return { state: 'done', via };
+                await new Promise((resolve) => {
+                    const stop = () => { clearTimeout(wait); recoverySignal.removeEventListener('abort', stop); resolve(); };
+                    const wait = setTimeout(stop, 1_000);
+                    recoverySignal.addEventListener('abort', stop, { once: true });
+                    if (recoverySignal.aborted)
+                        stop();
+                });
+            }
+            return codeExpired ? expired() : cancelled();
+        };
+        try {
+            return await Promise.race([readback(), end]);
+        }
+        finally {
+            recovery.abort();
+            clearTimeout(timer);
+            signal.removeEventListener('abort', abort);
+        }
+    };
     void (async () => {
         let view;
         try {
-            view = await drive();
+            const driven = await Promise.race([drive(), disconnected]);
+            view = driven ?? await recover();
+            if (signal.aborted)
+                view = codeExpired ? expired() : cancelled();
         }
         catch (error) {
             if (signal.aborted)

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/index.d.ts

@@ -1,3 +1,4 @@
 export { fakeGateway, 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';

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

@@ -30,6 +30,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

@@ -76,7 +76,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({

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;

package/dist/usage-boots.js

@@ -0,0 +1,26 @@
+// Internal lifecycle records. Accounting UUIDs never participate in process ownership or liveness.
+import { closeSync, fsyncSync, openSync, writeSync } from 'node:fs';
+import { join } from 'node:path';
+export function appendUsageBoot(dir, record) {
+    let fd;
+    try {
+        fd = openSync(join(dir, 'boots.jsonl'), 'a', 0o600);
+        const line = Buffer.from(JSON.stringify(record) + '\n');
+        if (writeSync(fd, line) !== line.length)
+            throw new Error();
+        fsyncSync(fd);
+    }
+    catch {
+        throw new Error('Usage boot record could not be made durable');
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                throw new Error('Usage boot record could not be made durable');
+            }
+        }
+    }
+}