@byokit/openclaw 0.1.0

package/dist/testing/fake-gateway.js

@@ -0,0 +1,378 @@
+// The fake Gateway (5.11): an in-memory transport double driven by default handlers and scripts. Use it as
+// `new OpenClawKit({ transport: fake.factory, spawnEngine: false, ... })` or drive `fake.transport.request`
+// directly. No engine, no network, no account.
+import { connect } from 'node:net';
+import { randomUUID } from 'node:crypto';
+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";
+// 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',
+    deviceCode: { code: 'CREW-2026', expiresInMinutes: 15 }, externalUrl: 'https://auth.openai.com/codex/device',
+};
+const PROGRESS_STEP = { id: 'step-wait', type: 'progress', message: 'Waiting for authorization', executor: 'gateway' };
+const EVENTS = [
+    'agent',
+    'exec.approval.requested', 'exec.approval.resolved',
+    'plugin.approval.requested', 'plugin.approval.resolved',
+    'question.requested', 'question.resolved',
+];
+/** Window between a run's last event and its completion, so an abort issued on the text event still lands. */
+const ABORT_WINDOW_MS = 25;
+const BRIDGE_TIMEOUT_MS = 30_000;
+const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+function mergeInto(target, patch) {
+    for (const [key, value] of Object.entries(patch)) {
+        const current = target[key];
+        if (isPlainObject(current) && isPlainObject(value))
+            mergeInto(current, value);
+        else
+            target[key] = value;
+    }
+}
+/** The one config invariant the engine itself keeps at runtime (5.6): memory search never leaves the free path. */
+function enforceMemoryInvariants(config) {
+    const agents = (config.agents ?? {});
+    // A node is whatever holds `.memory.search`: the config itself, an agent default, or one agent entry.
+    const nodes = [config, agents.defaults, ...Object.values(agents.entries ?? {})];
+    for (const node of nodes) {
+        const search = node?.memory?.search;
+        if (!isPlainObject(search))
+            continue;
+        if ('provider' in search)
+            search.provider = 'none';
+        if ('fallback' in search)
+            search.fallback = 'none';
+    }
+}
+/**
+ * The plugin's tool table, read from beside the kit's socket the way the plugin reads it. Absent (a bare socket with
+ * no kit): every tool counts as the app's.
+ */
+function pluginTable(sock) {
+    try {
+        return JSON.parse(readFileSync(join(dirname(sock), 'plugin', 'tools.json'), 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** One newline-framed request over the bridge socket, exactly what the plugin does (5.9). */
+function bridgeRequest(path, message) {
+    return new Promise((resolve, reject) => {
+        const socket = connect(path);
+        let buffer = '';
+        let timer;
+        const fail = (error) => {
+            clearTimeout(timer);
+            socket.destroy();
+            reject(error);
+        };
+        socket.once('error', fail);
+        socket.on('data', (chunk) => {
+            buffer += String(chunk);
+            if (buffer.length > 1_000_000)
+                return fail(new Error('bridge reply too large'));
+            const end = buffer.indexOf('\n');
+            if (end < 0)
+                return;
+            clearTimeout(timer);
+            socket.end();
+            try {
+                resolve(JSON.parse(buffer.slice(0, end)));
+            }
+            catch (error) {
+                fail(error);
+            }
+        });
+        socket.once('connect', () => {
+            timer = setTimeout(() => fail(new Error('bridge timed out')), BRIDGE_TIMEOUT_MS);
+            socket.write(JSON.stringify(message) + '\n');
+        });
+    });
+}
+export function fakeGateway(script) {
+    const calls = [];
+    const failures = new Map();
+    const handlers = new Map();
+    const agents = new Map();
+    const wizards = new Map();
+    const runs = new Map();
+    const configBox = { hash: 'hash-1', config: {} };
+    let hashSeq = 1;
+    const ensureAgent = (id, workspace) => {
+        let agent = agents.get(id);
+        if (!agent) {
+            agent = { id, workspace, providers: [] };
+            agents.set(id, agent);
+        }
+        else if (workspace)
+            agent.workspace = workspace;
+        return agent;
+    };
+    const signInAgent = (id, provider) => {
+        const agent = ensureAgent(id);
+        if (!agent.providers.includes(provider))
+            agent.providers.push(provider);
+    };
+    // Every transport the factory made; events fan out to all of them, drop() closes all of them.
+    const live = new Set();
+    let droppedWhy = '';
+    const emit = (event, payload) => {
+        for (const transport of live)
+            for (const fn of transport.events)
+                fn({ event, payload });
+    };
+    const failNext = (method, message) => {
+        const queue = failures.get(method);
+        if (queue)
+            queue.push(message);
+        else
+            failures.set(method, [message]);
+    };
+    const finish = (run, result) => {
+        if (run.result)
+            return;
+        run.result = result;
+        for (const waiter of run.waiters.splice(0))
+            waiter(result);
+    };
+    const emitRun = (run, stream, data) => emit('agent', { runId: run.runId, seq: run.seq++, stream, ts: Date.now(), data });
+    /** The `agent` handler: the run's scripted turn, its `[tool NAME {json}]` calls through the real bridge. */
+    const startRun = (params, bridgeSock) => {
+        if (params.agentId != null && !agents.has(String(params.agentId)))
+            throw new Error(`unknown agent: ${params.agentId}`);
+        const run = { runId: randomUUID(), sessionKey: String(params.sessionKey ?? ''), seq: 0, waiters: [] };
+        runs.set(run.runId, run);
+        const message = String(params.message ?? '');
+        const text = `fake: ${message}`;
+        setTimeout(() => {
+            void (async () => {
+                const table = bridgeSock ? pluginTable(bridgeSock) : undefined;
+                for (const call of toolCalls(message)) {
+                    emitRun(run, 'tool', { name: call.name, phase: 'start' });
+                    // As the plugin: an engine builtin is gated unless the app opted out, and an allowed one never calls back.
+                    const builtin = !!table && !table.tools.some((t) => t.name === call.name);
+                    if (bridgeSock && !(builtin && table?.gateBuiltins === false)) {
+                        try {
+                            const gate = await bridgeRequest(bridgeSock, { kind: 'gate', key: run.sessionKey, tool: call.name, input: call.input });
+                            if (gate.allow && !builtin)
+                                await bridgeRequest(bridgeSock, { kind: 'call', key: run.sessionKey, permit: gate.permit, tool: call.name, input: call.input });
+                        }
+                        catch { /* no bridge or refused: the tool pair still plays, nothing is called */ }
+                    }
+                    // Completion rides `phase: 'result'` like the real engine (O11), not `'end'`.
+                    emitRun(run, 'tool', { name: call.name, phase: 'result' });
+                }
+                emitRun(run, 'assistant', { text });
+                setTimeout(() => finish(run, { status: 'ok', terminalReply: { text } }), ABORT_WINDOW_MS);
+            })();
+        }, 0);
+        return { runId: run.runId };
+    };
+    const defaults = {
+        health: () => ({ ok: true, plugins: { loaded: [] } }),
+        'agents.list': () => ({
+            defaultId: 'main', mainKey: 'main', scope: 'global',
+            agents: [...agents.values()].map((agent) => ({ id: agent.id })),
+        }),
+        'agents.create': (p) => {
+            ensureAgent(String(p.name), p.workspace ? String(p.workspace) : undefined);
+            return { id: String(p.name) };
+        },
+        'models.authStatus': (p) => ({
+            providers: (agents.get(String(p?.agentId ?? 'main'))?.providers ?? []).map((provider) => ({ provider })),
+        }),
+        'models.authLogout': (p) => {
+            const agent = agents.get(String(p?.agentId ?? 'main'));
+            if (agent)
+                agent.providers = agent.providers.filter((provider) => provider !== p.provider);
+            return {};
+        },
+        'openclaw.setup.auth.start': (p) => {
+            const sessionId = String(p.sessionId ?? `fake-${randomUUID()}`);
+            wizards.set(sessionId, { agentId: String(p.agentId ?? 'main'), answered: false, pulls: 0 });
+            return { sessionId, done: false, status: 'running' };
+        },
+        'wizard.next': (p) => {
+            const session = wizards.get(String(p.sessionId));
+            if (!session)
+                throw new Error(`unknown wizard session: ${p.sessionId}`);
+            if (p.answer) {
+                session.answered = true;
+                return { done: false, step: PROGRESS_STEP };
+            }
+            if (!session.answered)
+                return { done: false, step: DEVICE_STEP };
+            if (session.pulls++ === 0)
+                return { done: false, step: PROGRESS_STEP };
+            wizards.delete(String(p.sessionId));
+            signInAgent(session.agentId, 'openai');
+            return { done: true, status: 'done', modelActivation: { modelRef: 'openai/gpt-5.1' } };
+        },
+        'wizard.cancel': (p) => {
+            wizards.delete(String(p.sessionId));
+            return { status: 'cancelled' };
+        },
+        agent: (p, bridgeSock) => startRun(p, bridgeSock),
+        'agent.wait': (p) => new Promise((resolve, reject) => {
+            const run = runs.get(String(p.runId));
+            if (!run)
+                return reject(new Error(`unknown run: ${p.runId}`));
+            if (run.result)
+                resolve(run.result);
+            else
+                run.waiters.push(resolve);
+        }),
+        'sessions.steer': () => ({}),
+        'chat.abort': (p) => {
+            for (const run of runs.values()) {
+                if (run.result || run.sessionKey !== String(p.sessionKey ?? ''))
+                    continue;
+                if (p.runId && run.runId !== String(p.runId))
+                    continue;
+                // Engine-shaped abort (O11): the receipt only says rpc-error; the run's lifecycle end carries aborted.
+                emitRun(run, 'lifecycle', { phase: 'end', status: 'cancelled', aborted: true, stopReason: 'rpc' });
+                finish(run, { status: 'error', stopReason: 'rpc' });
+            }
+            return {};
+        },
+        'config.get': () => ({ hash: configBox.hash, config: configBox.config }),
+        'config.patch': (p) => {
+            if (typeof p.raw !== 'string')
+                throw new Error('config.patch requires raw');
+            if (p.baseHash !== undefined && p.baseHash !== configBox.hash)
+                throw new Error('stale config: baseHash does not match');
+            const next = JSON.parse(p.raw);
+            // Like the real engine (O11) the merged config is validated, so entries added onto an already
+            // explicit roster stay valid: a multi-agent roster without explicit ownership is invalid.
+            const merged = JSON.parse(JSON.stringify(configBox.config));
+            mergeInto(merged, next);
+            const agents = merged.agents;
+            const roster = Object.keys(agents?.entries ?? {});
+            if ((roster.length > 1 || (roster.length === 1 && roster[0] !== 'main')) && agents?.ownership !== 'explicit')
+                throw new Error('invalid config: agents.ownership: multi-agent rosters require agents.ownership="explicit"');
+            mergeInto(configBox.config, next);
+            enforceMemoryInvariants(configBox.config);
+            configBox.hash = `hash-${++hashSeq}`;
+            return { hash: configBox.hash };
+        },
+        // Real-shaped requested events: details nest under `request` (B1); question events stay flat upstream.
+        'exec.approval.request': (p) => {
+            const id = String(p.id ?? `exec-${randomUUID()}`);
+            const now = Date.now();
+            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,
+                },
+            });
+            return { id };
+        },
+        'plugin.approval.request': (p) => {
+            // Like the real engine: title and description are required, the engine mints the id.
+            if (typeof p.title !== 'string' || typeof p.description !== 'string')
+                throw new Error('plugin.approval.request requires title and description');
+            const id = `plugin-${randomUUID()}`;
+            const now = Date.now();
+            emit('plugin.approval.requested', {
+                approvalKind: 'plugin', id, createdAtMs: now, expiresAtMs: now + 180_000,
+                request: { title: p.title, description: p.description, agentId: p.agentId, sessionKey: p.sessionKey },
+            });
+            return { id };
+        },
+        'exec.approval.resolve': (p) => {
+            emit('exec.approval.resolved', { id: p.id, decision: p.decision });
+            return {};
+        },
+        'exec.approval.list': () => ({ approvals: [] }),
+        'plugin.approval.list': () => ({ approvals: [] }),
+        'plugin.approval.resolve': (p) => {
+            emit('plugin.approval.resolved', { id: p.id, decision: p.decision });
+            return {};
+        },
+        'question.resolve': (p) => {
+            emit('question.resolved', { id: p.id, answers: p.answers });
+            return {};
+        },
+    };
+    for (const [method, handler] of Object.entries(defaults))
+        handlers.set(method, handler);
+    for (const [method, handler] of Object.entries(script ?? {}))
+        handlers.set(method, handler);
+    const dispatch = async (method, params, bridgeSock) => {
+        calls.push({ method, params });
+        const queue = failures.get(method);
+        if (queue?.length)
+            throw new Error(queue.shift());
+        const handler = handlers.get(method);
+        if (!handler)
+            throw new Error(`unknown method: ${method}`);
+        return await handler(params ?? {}, bridgeSock);
+    };
+    const hello = () => ({
+        protocol: PROTOCOL_VERSION,
+        server: { version: ENGINE_VERSION },
+        // The methods the fake serves. The generated tables are type-only until O2 ships runtime names; O11's
+        // generated.test.ts cross-checks the real engine's hello against the committed tables.
+        methods: [...handlers.keys()].sort(),
+        events: [...EVENTS],
+    });
+    const closedWhy = () => (droppedWhy ? `transport closed: ${droppedWhy}` : 'transport closed');
+    const factory = (ctx) => {
+        const sock = ctx.bridgeSock;
+        const entry = {
+            open: true,
+            events: new Set(),
+            closes: new Set(),
+        };
+        live.add(entry);
+        const transport = {
+            start: async () => {
+                if (!entry.open)
+                    throw new Error(closedWhy());
+                return hello();
+            },
+            request: async (method, params) => {
+                if (!entry.open)
+                    throw new Error(closedWhy());
+                return dispatch(method, params, sock);
+            },
+            onEvent: (fn) => (entry.events.add(fn), () => entry.events.delete(fn)),
+            onClose: (fn) => (entry.closes.add(fn), () => entry.closes.delete(fn)),
+            stop: async () => {
+                entry.open = false;
+                entry.events.clear();
+                entry.closes.clear();
+                live.delete(entry);
+            },
+        };
+        return transport;
+    };
+    const drop = (why) => {
+        droppedWhy = why;
+        for (const entry of [...live]) {
+            entry.open = false;
+            const closes = [...entry.closes];
+            entry.closes.clear();
+            for (const fn of closes)
+                fn(why);
+            live.delete(entry);
+        }
+    };
+    return {
+        factory,
+        calls,
+        emit,
+        failNext,
+        drop,
+        handle: (method, fn) => { handlers.set(method, fn); },
+        transport: factory({ port: 0, token: 'test', identityPath: '', bridgeSock: '' }),
+    };
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,3 @@
+export { fakeGateway, type FakeScript } from './fake-gateway.ts';
+export { openclawContract, type ContractFixture } from './contract.ts';
+export { startModelStub, useModelStub, releaseStub, stubHolding, toolCalls, type ModelStub, type ModelStubOptions, type StubCall } from './model-stub.ts';

package/dist/testing/index.js

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

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

@@ -0,0 +1,29 @@
+import type { OpenClawKit } from '../kit.ts';
+export type StubCall = {
+    authorization: string;
+    path: string;
+    body: any;
+};
+export type ModelStub = {
+    port: number;
+    url: string;
+    calls: StubCall[];
+    close(): Promise<void>;
+};
+/** The tool calls in the script, each with its arguments. Braces are balanced, so a script may nest. */
+export declare function toolCalls(text: string): {
+    name: string;
+    input: Record<string, unknown>;
+}[];
+export declare const releaseStub: (key?: string, reply?: string) => void;
+export declare const stubHolding: (key?: string) => boolean;
+/**
+ * One loopback HTTP server that speaks the script. `script` queues plain replies consumed one per completion
+ * request before the message-embedded grammar applies.
+ */
+export type ModelStubOptions = {
+    idPattern?: RegExp;
+    routingMarker?: string;
+};
+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

@@ -0,0 +1,182 @@
+// The scripted OpenAI-compatible model the contract and engine tests run against (5.11): ported from Crewhouse's
+// test/openclaw-stub.ts with its script grammar unchanged. One loopback HTTP server; sessions, tools, the gate and
+// the run events stay the engine's own code path. No network, no account, no quota, no sign-ins anywhere.
+// Script (read from the latest user message):
+//   [tool NAME {json}]   call that tool once, then reply with what it returned; several are called in turn, the reply
+//                        saying what the last one returned (the json may nest: braces are matched, not guessed)
+//   hit the limit        answer with the account's own usage-limit error (rests it)
+//   no helpers in plan   answer as a plan without helpers does
+//   sign me out          answer as an account whose sign-in stopped working does
+//   ask permission       hold the turn (after its tool calls) until `releaseStub` lets it finish
+//   [route ID]           asked who should take a request: ID, fairly sure; [route ?]: torn evenly; neither: Chief, sure
+//   anything else        reply `stub <bot>: done with "<the last line of the message>"`
+// The bot id (`idPattern`, default /Your id is ([a-z0-9-]+)\./) is read from the system prompt, and routing
+// requests start with `routingMarker` (default '[routing]'); pass both explicitly to mirror another app's grammar.
+import { createServer } from 'node:http';
+import { randomUUID } from 'node:crypto';
+/** The tool calls in the script, each with its arguments. Braces are balanced, so a script may nest. */
+export function toolCalls(text) {
+    const out = [];
+    for (const m of text.matchAll(/\[tool (\w+) \{/g)) {
+        const from = m.index + m[0].length - 1;
+        let depth = 0, i = from, quote = false, esc = false;
+        for (; i < text.length; i++) {
+            const c = text[i];
+            if (esc) {
+                esc = false;
+                continue;
+            }
+            if (c === '\\') {
+                esc = true;
+                continue;
+            }
+            if (c === '"') {
+                quote = !quote;
+                continue;
+            }
+            if (quote)
+                continue;
+            if (c === '{')
+                depth++;
+            else if (c === '}' && !--depth)
+                break;
+        }
+        out.push({ name: m[1], input: JSON.parse(text.slice(from, i + 1)) });
+    }
+    return out;
+}
+// A turn whose message says `ask permission` holds until released; the key is the request's Authorization header.
+const holds = new Map();
+export const releaseStub = (key, reply = '') => {
+    for (const [k, release] of holds)
+        if (!key || k === key) {
+            release(reply);
+            holds.delete(k);
+        }
+};
+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('') : '';
+export function startModelStub(script = [], o = {}) {
+    const calls = [];
+    const queue = [...script];
+    const idPattern = o.idPattern ?? /Your id is ([a-z0-9-]+)\./;
+    const routingMarker = o.routingMarker ?? '[routing]';
+    const server = createServer(async (req, res) => {
+        const chunks = [];
+        for await (const chunk of req)
+            chunks.push(chunk);
+        let body;
+        try {
+            body = JSON.parse(Buffer.concat(chunks).toString());
+        }
+        catch {
+            res.writeHead(400).end();
+            return;
+        }
+        calls.push({ authorization: String(req.headers.authorization ?? ''), path: req.url ?? '', body });
+        if (req.url === '/api/embed' || req.url === '/api/embeddings') {
+            res.writeHead(200, { 'content-type': 'application/json' });
+            return res.end(JSON.stringify({
+                embeddings: (Array.isArray(body.input) ? body.input : [body.input]).map(() => [0.1, 0.2, 0.3]),
+            }));
+        }
+        const messages = body.messages ?? [];
+        const system = messages.filter((m) => m.role === 'system').map((m) => words(m)).join('\n');
+        const bot = idPattern.exec(system)?.[1] ?? 'bot';
+        // The engine appends runtime-context user messages after the person's own (O11): the script lives in the
+        // last user message that carries a script marker, falling back to the last user message for plain replies.
+        // Tool results count from that same message, or the first scripted call replays forever: each follow-up
+        // request carries a fresh trailing runtime-context user message with zero tool results after it.
+        const users = messages.filter((m) => m.role === 'user');
+        const structural = (text) => /\[tool \w+ \{|\[route [\w?-]+\]/.test(text) || text.startsWith(routingMarker);
+        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);
+        const said = words(lastUser);
+        const anchor = messages.lastIndexOf(lastUser);
+        const results = anchor < 0 ? [] : messages.slice(anchor + 1).filter((m) => m.role === 'tool');
+        const scripted = toolCalls(said);
+        const lastResult = results.at(-1);
+        const done = () => {
+            if (results.length && lastResult)
+                return `stub ${bot}: ${lastResult.name ?? 'tool'} said ${words(lastResult).slice(0, 300)}`;
+            const asked = said.split('\n').map((l) => l.trim()).filter((l) => l && !l.startsWith(routingMarker) && !/^\[route /.test(l)).pop() ?? '';
+            return `stub ${bot}: done with "${asked.slice(0, 60)}"`;
+        };
+        // Routing asks who takes a request; the script answers in the kit's own shape.
+        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)]))));
+        }
+        if (/sign me out/i.test(said)) {
+            res.writeHead(401, { 'content-type': 'application/json' });
+            return res.end(JSON.stringify({ error: { message: '401 Unauthorized: your sign-in has expired' } }));
+        }
+        if (/hit the limit/i.test(said)) {
+            res.writeHead(429, { 'content-type': 'application/json' });
+            return res.end(JSON.stringify({ error: { message: 'You have hit your ChatGPT usage limit (plus plan). Try again in ~30 min.' } }));
+        }
+        if (/no helpers in plan/i.test(said)) {
+            res.writeHead(403, { 'content-type': 'application/json' });
+            return res.end(JSON.stringify({ error: { message: "Your plan doesn't include this model." } }));
+        }
+        const next = scripted[results.length];
+        const id = randomUUID();
+        res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache' });
+        const send = (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`);
+        if (next) {
+            send({ role: 'assistant', tool_calls: [{ index: 0, id: `call_${id}`, type: 'function', function: { name: next.name, arguments: JSON.stringify(next.input) } }] });
+            send({}, 'tool_calls');
+            return void res.end('data: [DONE]\n\n');
+        }
+        let text = queue.length ? queue.shift() : done();
+        if (/ask permission/i.test(said)) {
+            const key = String(req.headers.authorization ?? 'hold');
+            text = await new Promise((resolve) => {
+                holds.set(key, (reply) => resolve(reply || text));
+                res.once('close', () => holds.delete(key));
+            });
+        }
+        send({ role: 'assistant', content: text });
+        send({}, 'stop');
+        res.end('data: [DONE]\n\n');
+    });
+    return new Promise((resolve) => {
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            const port = address && typeof address !== 'string' ? address.port : 0;
+            resolve({
+                port,
+                url: `http://127.0.0.1:${port}/v1`,
+                calls,
+                close: () => new Promise((yes) => server.close(() => yes())),
+            });
+        });
+    });
+}
+const plain = (res, body, 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`);
+    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({
+            models: { providers: { 'byokit-stub': {
+                        baseUrl: stub.url, apiKey: 'byokit-stub', api: 'openai-completions',
+                        models: [{ id: 'test', name: 'Test', reasoning: true, input: ['text'],
+                                cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 32000, maxTokens: 2048,
+                                compat: { supportsReasoningEffort: true, supportedReasoningEfforts: ['off', 'low', 'medium', 'high'] } }],
+                    } } },
+            agents: { defaults: { model: { primary: 'byokit-stub/test' } } },
+        }) });
+}

package/dist/transport.d.ts

@@ -0,0 +1,22 @@
+import type { GatewayTransport } from './types.ts';
+/**
+ * Client caps for the operator connection. `approvals` makes this connection an approval client, so the
+ * engine delivers exec/plugin.approval.requested to it (B7); without it the broadcast set is empty.
+ */
+export declare const GATEWAY_CAPS: readonly ["tool-events", "approvals"];
+/**
+ * Read the device key pair from `device.json`. The kit writes `{ privateKey, publicKey }` (PEM strings);
+ * existing Crewhouse state carries `{ deviceId, publicKeyPem, privateKeyPem }` instead. Both shapes are
+ * accepted and the file is only ever read, never rewritten, so an existing device identity keeps its keys.
+ */
+export declare function loadDeviceKeys(identityPath: string): {
+    privateKeyPem: string;
+    publicKeyPem: string;
+    deviceId?: string;
+};
+export declare function gatewayTransport(ctx: {
+    port: number;
+    token: string;
+    identityPath: string;
+    bridgeSock: string;
+}): GatewayTransport;