@byokit/openclaw 0.1.0

package/dist/signin.js

@@ -0,0 +1,251 @@
+// Sign-in: the kit drives OpenClaw's own setup wizard loop and holds the ChatGPT callback port during a browser
+// sign-in; credentials never pass through kit or app (D11, 5.7).
+import { randomUUID } from 'node:crypto';
+import { createServer } from 'node:http';
+import { words } from "./words.js";
+// The pin's wizard contract (2026.8.1): steps arrive only from `wizard.next` (wizard.status answers {status, error}
+// and never carries a step), and one session at a time holds the gateway's single setup admission.
+const BUSY = /setup is already in progress|SETUP_ADMISSION_BUSY/i;
+const START_MS = 60_000;
+const PULL_MS = 120_000;
+const STATUS_MS = 20_000;
+const CANCEL_MS = 10_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
+ * 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 wantsCallback = via === 'browser' && o.authChoice === 'openai';
+    let server;
+    let sessionId = '';
+    let starting;
+    let releasing;
+    let settleStart;
+    const startingSettled = new Promise((resolve) => { settleStart = resolve; });
+    let over = false;
+    let settle;
+    let pasteIn;
+    let returned;
+    const done = new Promise((resolve) => { settle = resolve; });
+    const say = (v) => on({ state: 'waiting', via, ...v });
+    const closeCallback = async () => {
+        const held = server;
+        server = undefined;
+        if (held)
+            await new Promise((closed) => held.close(() => closed()));
+    };
+    const finish = async (view) => {
+        if (over)
+            return;
+        over = true;
+        owner.abort();
+        await closeCallback();
+        on(view);
+        settle(view);
+    };
+    const release = () => {
+        releasing ??= (async () => {
+            // A cancel never goes out early: the pinned engine holds one setup admission per gateway and registers the
+            // session only as `openclaw.setup.auth.start` settles, so a cancel sent sooner is answered `wizard not found`
+            // 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(() => { });
+        })();
+        return releasing;
+    };
+    const paste = (text) => {
+        if (pasteIn)
+            pasteIn(text);
+        else
+            returned = text; // the browser came back before the wizard asked; held for the text step
+    };
+    const cancel = () => {
+        // Stop the drive now; the start itself is never aborted, and release waits for it to settle before cancelling,
+        // so the gateway's one setup admission is freed by a cancel that the engine can actually find.
+        owner.abort();
+        void (async () => { await release(); await finish({ state: 'failed', via, why: 'declined' }); })();
+    };
+    /** Hold 127.0.0.1:<callbackPort> for the sign-in's life; a taken port is why the sign-in cannot start. */
+    const holdCallback = () => {
+        let took = false;
+        const held = createServer((req, res) => {
+            const host = req.headers.host ?? `localhost:${ctx.callbackPort}`;
+            const address = `http://${host}${req.url ?? ''}`;
+            let url;
+            try {
+                url = new URL(address);
+            }
+            catch {
+                url = new URL(`http://${host}/`);
+            }
+            // Only the provider's own callback is pasted: a favicon or any other local page is not a redirect back.
+            if (took || req.method !== 'GET' || url.pathname !== '/auth/callback' || !url.searchParams.has('code')) {
+                res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' });
+                res.end('Not found');
+                return;
+            }
+            took = true;
+            res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' });
+            res.end('<!doctype html><meta charset="utf-8"><meta name="viewport" content="width=device-width">' +
+                `<title>Sign-in</title><body style="font:18px system-ui;margin:3em auto;max-width:26em;padding:0 1em;text-align:center">${words('signin.returned')}</body>`);
+            paste(address);
+        });
+        return new Promise((open, refuse) => {
+            held.once('error', refuse);
+            held.listen(ctx.callbackPort, '127.0.0.1', () => { held.off('error', refuse); held.on('error', () => { }); open(held); });
+        });
+    };
+    const drive = async () => {
+        if (wantsCallback) {
+            server = await holdCallback().catch(() => undefined);
+            if (!server)
+                return { state: 'failed', via, why: 'busy' };
+        }
+        const { agentId } = await ctx.ensure(member);
+        // The session id is the client's to choose (5.7), and the start request carries no abort signal: the engine
+        // registers the session as it settles, so a cancel waits for it (release) rather than racing it.
+        sessionId = `byokit-${randomUUID()}`;
+        let started;
+        try {
+            starting = ctx.request('openclaw.setup.auth.start', { sessionId, agentId, authChoice: o.authChoice }, { timeoutMs: START_MS });
+            started = await starting;
+        }
+        finally {
+            settleStart();
+        }
+        if (started.done)
+            return { state: 'done', via };
+        // wizard.next, never wizard.status: the status method answers {status, error} and carries no step.
+        const pull = () => ctx.request('wizard.next', { sessionId }, pullOptions(signal));
+        const answer = (step, value) => ctx.request('wizard.next', { sessionId, answer: { stepId: step.id, ...(value === undefined ? {} : { value }) } }, pullOptions(signal));
+        const waitForPaste = () => new Promise((resolve) => {
+            if (returned !== undefined) {
+                const text = returned;
+                returned = undefined;
+                resolve(text);
+                return;
+            }
+            let timer;
+            let settled = false;
+            const stop = (text) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timer)
+                    clearTimeout(timer);
+                signal.removeEventListener('abort', onAbort);
+                pasteIn = undefined;
+                resolve(text);
+            };
+            const onAbort = () => stop(undefined);
+            timer = setTimeout(() => stop(undefined), PASTE_MS);
+            pasteIn = (text) => stop(text);
+            signal.addEventListener('abort', onAbort, { once: true });
+        });
+        let step;
+        let terminal;
+        for (let turns = 0; turns < TURNS && !signal.aborted; turns++) {
+            if (!step) {
+                const next = await pull();
+                if (next.done) {
+                    terminal = next;
+                    break;
+                }
+                step = next.step;
+                continue;
+            }
+            const current = step;
+            step = undefined;
+            if (current.deviceCode) {
+                // The code is on the card; acknowledging it lets the engine poll the provider itself.
+                say({ ...(current.deviceCode.code ? { code: current.deviceCode.code } : {}), ...(current.externalUrl ? { url: current.externalUrl } : {}) });
+                const next = await answer(current);
+                if (next.done) {
+                    terminal = next;
+                    break;
+                }
+                step = next.step;
+                continue;
+            }
+            if (current.type === 'text' && !current.sensitive) {
+                const value = await waitForPaste();
+                if (value === undefined)
+                    return { state: 'failed', via, why: signal.aborted ? 'declined' : 'expired' };
+                const next = await answer(current, value);
+                if (next.done) {
+                    terminal = next;
+                    break;
+                }
+                step = next.step;
+                if (next.error)
+                    say({ error: cut(next.error) });
+                continue;
+            }
+            if (current.type === 'note' || current.type === 'confirm' || current.type === 'select' || current.type === 'action') {
+                if (current.externalUrl)
+                    say({ url: current.externalUrl });
+                const next = await answer(current);
+                if (next.done) {
+                    terminal = next;
+                    break;
+                }
+                step = next.step;
+                if (next.error)
+                    say({ error: cut(next.error) });
+                continue;
+            }
+            // progress and anything gateway-driven: it advances by itself
+            const next = await pull();
+            if (next.done) {
+                terminal = next;
+                break;
+            }
+            step = next.step;
+        }
+        if (signal.aborted)
+            return { state: 'failed', via, why: 'declined' };
+        if (!terminal)
+            return { state: 'failed', via, why: 'expired' };
+        const error = String(terminal.error ?? (terminal.status === 'error' ? 'Sign-in failed' : ''));
+        return error ? { state: 'failed', via, why: 'failed', error: cut(error) } : { state: 'done', via };
+    };
+    void (async () => {
+        let view;
+        try {
+            view = await drive();
+        }
+        catch (error) {
+            if (signal.aborted)
+                view = { state: 'failed', via, why: 'declined' };
+            else if (BUSY.test(cut(error)))
+                view = { state: 'failed', via, why: 'busy' };
+            else
+                view = { state: 'failed', via, why: 'failed', error: cut(error) };
+        }
+        settleStart();
+        if (view.state !== 'done')
+            await release();
+        await finish(view);
+    })();
+    return { paste, cancel, done };
+}
+/** The providers this member's engine reports as signed in, from `models.authStatus` (a string or `{ provider }`). */
+export async function providers(ctx, member, refresh) {
+    const { agentId } = await ctx.ensure(member);
+    const status = await ctx.request('models.authStatus', { agentId, ...(refresh ? { refresh: true } : {}) }, { timeoutMs: STATUS_MS });
+    const names = (status?.providers ?? []).map((entry) => (typeof entry === 'string' ? entry : entry?.provider));
+    return [...new Set(names.filter((name) => typeof name === 'string' && name !== ''))];
+}
+export async function signOut(ctx, member, provider) {
+    const { agentId } = await ctx.ensure(member);
+    await ctx.request('models.authLogout', { provider, agentId }, { timeoutMs: STATUS_MS });
+}

package/dist/testing/contract.d.ts

@@ -0,0 +1,12 @@
+import type { OpenClawKit } from '../kit.ts';
+import { type ModelStub } from './model-stub.ts';
+export type ContractFixture = {
+    kit: OpenClawKit;
+    model?: ModelStub;
+    peer?: {
+        request(method: string, params?: unknown): Promise<unknown>;
+    };
+};
+export declare function openclawContract(make: () => Promise<ContractFixture>, o?: {
+    skipDeviceCode?: string;
+}): void;

package/dist/testing/contract.js

@@ -0,0 +1,250 @@
+// The contract suite (4.5, 5.11): the same assertions run against the fake in npm test and against the real pinned
+// engine in the engine job. Every case drives only the kit's public surface, so a pass on the fake and a pass on the
+// engine mean the same thing. O11 wires the calls; the cases are not run before then.
+//
+// `make` must return a started kit with the tool `note` registered and a host whose gate, for every tool (engine
+// builtins included), asks for `{ mode: 'ask', ... }` input, denies `{ mode: 'deny', ... }` input and allows the rest,
+// and whose calls answer `note: <input.text>`. An optional model is a started model stub the kit was pointed at with `useModelStub`.
+import { test } from 'node:test';
+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.
+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',
+    'exec.approval.request', 'exec.approval.resolve', 'health', 'models.authStatus', 'openclaw.setup.auth.start',
+    'plugin.approval.resolve', 'question.resolve', 'wizard.cancel', 'wizard.next',
+];
+// Driven by the kit but not advertised in hello (O11 probe, e.g. sessions.steer): routable, just not listed.
+// The engine job's generated.test.ts audits the full generated table against hello instead of asserting it here.
+const REQUIRED_EVENTS = [
+    'agent',
+    'exec.approval.requested', 'exec.approval.resolved',
+    'plugin.approval.requested', 'plugin.approval.resolved',
+    'question.requested', 'question.resolved',
+];
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function until(there, ms = 5_000) {
+    for (let waited = 0; waited < ms; waited += 50) {
+        if (there())
+            return;
+        await wait(50);
+    }
+    throw new Error('the expected state never arrived');
+}
+export function openclawContract(make, o) {
+    test('contract: hello carries the protocol and every method and event the kit drives', async () => {
+        const { kit } = await make();
+        try {
+            const hello = kit.hello;
+            assert.ok(hello, 'the kit has no hello');
+            assert.equal(hello.protocol, PROTOCOL_VERSION);
+            // The connection must be an approval client or native approvals never arrive (B7).
+            assert.ok(GATEWAY_CAPS.includes('approvals'), 'operator caps lack approvals');
+            for (const method of REQUIRED_METHODS)
+                assert.ok(hello.methods.includes(method), `hello is missing ${method}`);
+            for (const event of REQUIRED_EVENTS)
+                assert.ok(hello.events.includes(event), `hello is missing ${event}`);
+        }
+        finally {
+            await kit.stop();
+        }
+    });
+    test('contract: members are created, cached and validated', async () => {
+        const { kit } = await make();
+        try {
+            const first = await kit.ensureMember('m1');
+            assert.equal(first.agentId, 'm1');
+            const again = await kit.ensureMember('m1');
+            assert.equal(again.agentId, 'm1');
+            await assert.rejects(kit.ensureMember('M1'));
+        }
+        finally {
+            await kit.stop();
+        }
+    });
+    test('contract: a member cannot run in another member\'s session', async () => {
+        const { kit } = await make();
+        try {
+            await kit.ensureMember('m1');
+            await assert.rejects(kit.run({ member: 'm1', sessionKey: 'agent:m2:other:1', message: 'hello' }));
+        }
+        finally {
+            await kit.stop();
+        }
+    });
+    // The device-code happy path needs a person at the device URL (the fake auto-completes it, 5.11).
+    // Unattended runs (the engine job) skip it with the reason and prove sign-in live instead (O11 lab).
+    const deviceCodeName = `contract: device-code sign-in shows a code and finishes signed in${o?.skipDeviceCode ? ` (skipped: ${o.skipDeviceCode})` : ''}`;
+    test(deviceCodeName, { ...(o?.skipDeviceCode ? { skip: true } : {}) }, async () => {
+        const { kit } = await make();
+        try {
+            await kit.ensureMember('m1');
+            const views = [];
+            const signIn = kit.signIn('m1', { authChoice: 'openai-device-code', via: 'code' }, (v) => views.push(v));
+            const done = await signIn.done;
+            assert.equal(done.state, 'done');
+            assert.ok(views.some((v) => v.state === 'waiting' && v.code), 'no device code was shown');
+            assert.equal(await kit.signedIn('m1', 'openai'), true);
+        }
+        finally {
+            await kit.stop();
+        }
+    });
+    test('contract: a person-cancelled sign-in fails cleanly', async () => {
+        const { kit } = await make();
+        try {
+            await kit.ensureMember('m1');
+            const signIn = kit.signIn('m1', { authChoice: 'openai-device-code', via: 'code' }, () => { });
+            signIn.cancel();
+            const done = await signIn.done;
+            assert.equal(done.state, 'failed');
+        }
+        finally {
+            await kit.stop();
+        }
+    });
+    test('contract: a run streams text and ends ok', async () => {
+        const { kit } = await make();
+        try {
+            await kit.ensureMember('m1');
+            const events = [];
+            const end = await kit.run({ member: 'm1', sessionKey: 'agent:m1:contract:1', message: 'hello contract' }, (e) => events.push(e));
+            assert.ok(end.ok, JSON.stringify(end));
+            if (end.ok)
+                assert.ok(end.text.length > 0, 'the run ended without text');
+            assert.ok(events.some((e) => e.type === 'text'), 'no text event arrived');
+        }
+        finally {
+            await kit.stop();
+        }
+    });
+    test('contract: a gated tool ask parks, approves and runs', async () => {
+        const { kit } = await make();
+        try {
+            await kit.ensureMember('m1');
+            const events = [];
+            const pending = kit.run({ member: 'm1', sessionKey: 'agent:m1:contract:2', message: '[tool note {"mode":"ask","text":"hi"}]' }, (e) => events.push(e));
+            // A real turn reaches the gate only after a model round trip; the fake answers at once.
+            await until(() => kit.approvals('m1').length > 0, 120_000);
+            const approval = kit.approvals('m1')[0];
+            assert.equal(approval.source, 'gate');
+            assert.equal(approval.tool, 'note');
+            await kit.decide(approval.id, { allow: true });
+            const end = await pending;
+            assert.ok(end.ok, JSON.stringify(end));
+            assert.ok(events.some((e) => e.type === 'tool' && e.name === 'note' && e.phase === 'start'));
+            assert.ok(events.some((e) => e.type === 'tool' && e.name === 'note' && e.phase === 'end'));
+        }
+        finally {
+            releaseStub();
+            await kit.stop();
+        }
+    });
+    test('contract: a denied tool is blocked without an approval', async () => {
+        const { kit } = await make();
+        try {
+            await kit.ensureMember('m1');
+            const end = await kit.run({ member: 'm1', sessionKey: 'agent:m1:contract:3', message: '[tool note {"mode":"deny","text":"x"}]' });
+            assert.ok(end.ok, JSON.stringify(end));
+            assert.equal(kit.approvals().length, 0);
+        }
+        finally {
+            await kit.stop();
+        }
+    });
+    test('contract: an engine builtin reaches the app gate and a denial blocks it', async () => {
+        const { kit } = await make();
+        try {
+            await kit.ensureMember('m1');
+            const pending = kit.run({ member: 'm1', sessionKey: 'agent:m1:contract:5',
+                message: '[tool web_fetch {"mode":"ask","url":"https://example.invalid/"}]' });
+            await until(() => kit.approvals('m1').length > 0);
+            const approval = kit.approvals('m1')[0];
+            assert.equal(approval.source, 'gate');
+            assert.equal(approval.tool, 'web_fetch');
+            await kit.decide(approval.id, { allow: false, reason: 'no fetching' });
+            const end = await pending;
+            assert.ok(end.ok, JSON.stringify(end));
+            assert.equal(kit.approvals().length, 0);
+        }
+        finally {
+            releaseStub();
+            await kit.stop();
+        }
+    });
+    test('contract: abort ends a run aborted', async () => {
+        const { kit, model } = await make();
+        try {
+            await kit.ensureMember('m1');
+            const key = 'agent:m1:contract:4';
+            if (model) {
+                // With the model stub the turn holds (`ask permission`), so the abort cannot race the run's end.
+                const pending = kit.run({ member: 'm1', sessionKey: key, message: 'ask permission to continue' });
+                await until(() => stubHolding(), 120_000);
+                const aborted = kit.abort(key).finally(() => releaseStub());
+                assert.deepEqual(await pending, { ok: false, aborted: true });
+                await aborted;
+            }
+            else {
+                const pending = kit.run({ member: 'm1', sessionKey: key, message: 'hello' }, (e) => {
+                    if (e.type === 'text')
+                        void kit.abort(key);
+                });
+                assert.deepEqual(await pending, { ok: false, aborted: true });
+            }
+        }
+        finally {
+            releaseStub();
+            await kit.stop();
+        }
+    });
+    test('contract: a native exec approval round-trips', async () => {
+        const { kit, peer } = await make();
+        try {
+            // Raised by another party (a second connection): the engine broadcasts requested events to the
+            // kit's approval-capable connection, never back to the requester (O11). On the fake both hear it.
+            const raise = peer ? peer.request.bind(peer) : call.bind(null, kit);
+            // The real engine holds the request open until the approval resolves, so it stays in flight.
+            const pending = raise('exec.approval.request', { id: 'contract-exec-1', command: 'echo contract',
+                ask: 'contract approval', agentId: 'm1', sessionKey: 'agent:m1:contract:9' });
+            await until(() => kit.approvals().some((a) => a.id === 'contract-exec-1'), 120_000);
+            assert.equal(kit.approvals()[0].source, 'exec');
+            assert.equal(kit.approvals('m1')[0].id, 'contract-exec-1');
+            await kit.decide('contract-exec-1', { allow: true });
+            assert.equal((await pending).id, 'contract-exec-1');
+            await until(() => kit.approvals().length === 0);
+        }
+        finally {
+            await kit.stop();
+        }
+    });
+    test('contract: call passes health through', async () => {
+        const { kit } = await make();
+        try {
+            const health = await call(kit, 'health');
+            assert.ok(health && typeof health === 'object', 'health did not answer');
+        }
+        finally {
+            await kit.stop();
+        }
+    });
+    test('contract: patchConfig keeps the memory invariants', async () => {
+        const { kit } = await make();
+        try {
+            await kit.patchConfig({ memory: { search: { provider: 'openai', fallback: 'openai' } } });
+            const config = await call(kit, 'config.get');
+            assert.equal(config.config.memory.search.provider, 'none');
+            assert.equal(config.config.memory.search.fallback, 'none');
+            await kit.patchConfig({ agents: { entries: { m1: { memory: { search: { provider: 'openai' } } } } } });
+            const after = await call(kit, 'config.get');
+            assert.equal(after.config.agents.entries.m1.memory.search.provider, 'none');
+        }
+        finally {
+            await kit.stop();
+        }
+    });
+}

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

@@ -0,0 +1,19 @@
+import type { 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): {
+    factory: NonNullable<KitOptions['transport']>;
+    calls: {
+        method: string;
+        params: unknown;
+    }[];
+    emit(event: string, payload?: unknown): void;
+    failNext(method: string, message: string): void;
+    drop(why: string): void;
+    handle(method: string, fn: Handler): void;
+} & {
+    transport: GatewayTransport;
+};
+export {};