@byokit/openclaw 0.1.0

package/dist/device.js

@@ -0,0 +1,192 @@
+// The device side (7.2): portable — browsers, React Native, Node; no node:* or Node-only imports may reach here
+// (test/portable.test.ts guards it). Only type imports from @byokit/link; the seal crypto bundles cleanly.
+import { boxKeyPairFromSeed } from '@byokit/seal';
+import { toAccountView } from "./words.js";
+import { b64urlEncode, openNotice } from "./notices.js";
+/**
+ * The host ended a stream with its own words (e.g. a refusal). Portable twin of link's PublicLinkError:
+ * same shape ({ code: 'failed', sealed: true }) so a screen can show .message the same way. A device-side
+ * import of link's class would drag node:* into this portable entry (test/portable.test.ts).
+ */
+export class LinkRefused extends Error {
+    code = 'failed';
+    sealed = true;
+    constructor(message) {
+        super(message);
+        this.name = 'LinkRefused';
+    }
+}
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * Newline-delimited JSON frames off a link stream, in order. A host end with an error becomes a
+ * LinkRefused with the host's words (a refusal arrives after the stream opens, so it cannot ride
+ * the open itself).
+ *
+ * Plain manual iterables, deliberately not async generators: on this runtime a generator parked at
+ * an await never settles a return() call, which would wedge teardown of an infinite stream. A plain
+ * return() method always runs, ends the stream and wakes any parked next().
+ */
+function liveStream(open) {
+    let s;
+    let opening;
+    let failed;
+    let hasFailed = false;
+    let ended = false;
+    let endError;
+    let closed = false;
+    let text = '';
+    const pending = [];
+    const decoder = new TextDecoder();
+    const waiters = new Set();
+    const wake = () => {
+        for (const waiter of waiters)
+            waiter();
+        waiters.clear();
+    };
+    const ensure = () => {
+        opening ??= open().then((stream) => {
+            if (closed) {
+                stream.end();
+                return;
+            }
+            s = stream;
+            stream.onData = (chunk) => {
+                text += decoder.decode(chunk, { stream: true });
+                let at = text.indexOf('\n');
+                while (at >= 0) {
+                    pending.push(text.slice(0, at));
+                    text = text.slice(at + 1);
+                    at = text.indexOf('\n');
+                }
+                wake();
+            };
+            stream.onEnd = (error) => {
+                ended = true;
+                endError = error;
+                wake();
+            };
+        }, (error) => {
+            failed = error;
+            hasFailed = true;
+            wake();
+        });
+        return opening;
+    };
+    return {
+        [Symbol.asyncIterator]() {
+            return {
+                async next() {
+                    for (;;) {
+                        if (closed)
+                            return { value: undefined, done: true };
+                        while (pending.length) {
+                            const line = pending.shift();
+                            if (line)
+                                return { value: JSON.parse(line), done: false };
+                        }
+                        if (hasFailed)
+                            throw failed;
+                        if (ended) {
+                            if (endError !== undefined)
+                                throw new LinkRefused(endError);
+                            return { value: undefined, done: true };
+                        }
+                        // Opening phase races the open against abandonment; once open, park only on the
+                        // waiters (re-racing a settled open would spin microtasks and starve the loop).
+                        if (s === undefined) {
+                            await Promise.race([ensure(), new Promise((resolve) => {
+                                    waiters.add(resolve);
+                                })]);
+                        }
+                        else {
+                            await new Promise((resolve) => {
+                                waiters.add(resolve);
+                            });
+                        }
+                    }
+                },
+                async return() {
+                    closed = true;
+                    s?.end();
+                    wake();
+                    return { value: undefined, done: true };
+                },
+            };
+        },
+    };
+}
+export function openclawDevice(link) {
+    return {
+        state: () => link.request('oc.state'),
+        routes: () => link.request('oc.routes'),
+        signIn: {
+            start: (p, via) => link.request('oc.signin.start', { provider: p, via }),
+            view: async (p) => {
+                const { ready, view } = (await link.request('oc.signin.view', { provider: p }));
+                return toAccountView(view, ready);
+            },
+            paste: async (p, t) => {
+                await link.request('oc.signin.paste', { provider: p, text: t });
+            },
+            cancel: async (p) => {
+                await link.request('oc.signin.cancel', { provider: p });
+            },
+        },
+        signOut: async (p) => {
+            await link.request('oc.signout', { provider: p });
+        },
+        sessions: () => link.request('oc.sessions'),
+        run: (message, o) => {
+            const inner = liveStream(() => link.stream('oc.run', { message, ...(o?.sessionKey ? { sessionKey: o.sessionKey } : {}),
+                ...(o?.model !== undefined ? { model: o.model } : {}) }));
+            let finished = false;
+            return {
+                [Symbol.asyncIterator]() {
+                    const it = inner[Symbol.asyncIterator]();
+                    return {
+                        next: async () => {
+                            if (finished)
+                                return { value: undefined, done: true };
+                            const frame = await it.next();
+                            if (frame.done)
+                                return { value: undefined, done: true };
+                            if (isRecord(frame.value) && frame.value.type === 'end') {
+                                finished = true;
+                                await it.return?.();
+                                return { value: frame.value, done: false };
+                            }
+                            return { value: frame.value, done: false };
+                        },
+                        return: async () => {
+                            finished = true;
+                            await it.return?.();
+                            return { value: undefined, done: true };
+                        },
+                    };
+                },
+            };
+        },
+        steer: async (k, t) => {
+            await link.request('oc.steer', { sessionKey: k, text: t });
+        },
+        abort: async (k) => {
+            await link.request('oc.abort', { sessionKey: k });
+        },
+        approvals: () => link.request('oc.approvals'),
+        decide: async (id, d) => {
+            await link.request('oc.decide', { id, ...d });
+        },
+        events: () => liveStream(() => link.stream('oc.events', {})),
+        registerNotices: async (seed) => {
+            if (!ArrayBuffer.isView(seed) || !(seed instanceof Uint8Array) || seed.length !== 32)
+                throw new Error('registerNotices needs a 32-byte seed');
+            await link.request('oc.notices.register', { boxPublicKey: b64urlEncode(boxKeyPairFromSeed(seed).publicKey) });
+        },
+        openNotice,
+        call: (method, params) => link.request('oc.call', { method, params }),
+    };
+}
+// Portable, re-exported by ./device (7.3).
+export { openNotice } from "./notices.js";
+// The kit's sentences, so a phone or browser shows the same words the computer does (5.14).
+export { stateWords, toAccountView, words } from "./words.js";

package/dist/engine.d.ts

@@ -0,0 +1,43 @@
+import type { KitOptions } from './kit.ts';
+import type { KitState, ToolSpec } from './types.ts';
+export type EngineOptions = Pick<KitOptions, 'stateDir' | 'engineDir' | 'npmPath' | 'enginePath' | 'config' | 'installPolicy' | 'log' | 'bridge'> & {
+    pluginId: string;
+    tools: ToolSpec[];
+    gateBuiltins?: boolean;
+    spawnEngine: boolean;
+    onState(s: KitState): void;
+    onExit(code: number | null): void;
+};
+export declare class Engine {
+    readonly root: string;
+    readonly bridgeSock: string;
+    private readonly dir;
+    private child?;
+    private stopping;
+    private repaired;
+    private prepared?;
+    private port;
+    private token;
+    private readonly o;
+    private readonly paramPrefix;
+    constructor(o: EngineOptions);
+    private state;
+    private get entry();
+    private freePort;
+    prepare(): Promise<void>;
+    private prepareOnce;
+    doctorContext(): {
+        entry: string;
+        env: Record<string, string>;
+    };
+    doctor(timeoutMs: number): {
+        status: number | null;
+    };
+    private stalePid;
+    start(): Promise<{
+        port: number;
+        token: string;
+        identityPath: string;
+    }>;
+    stop(): Promise<void>;
+}

package/dist/engine.js

@@ -0,0 +1,212 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { randomBytes, generateKeyPairSync } from 'node:crypto';
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, writeFileSync, copyFileSync, rmSync } from 'node:fs';
+import { createServer } from 'node:net';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { setTimeout as delay } from 'node:timers/promises';
+import { ENGINE_VERSION } from "./constants.js";
+import { reconcileConfig } from "./config.js";
+import { writePlugin, resolveBridge } from "./bridge.js";
+const kitDir = dirname(dirname(fileURLToPath(import.meta.url)));
+const putOnce = (path, data) => { if (!existsSync(path))
+    writeFileSync(path, data, { mode: 0o600, flag: 'wx' }); };
+const putChanged = (path, data) => {
+    if (!existsSync(path) || readFileSync(path, 'utf8') !== data)
+        writeFileSync(path, data, { mode: 0o600 });
+};
+export class Engine {
+    root;
+    bridgeSock;
+    dir;
+    child;
+    stopping = false;
+    repaired = false;
+    prepared;
+    port = 0;
+    token = '';
+    o;
+    paramPrefix;
+    constructor(o) {
+        this.o = o;
+        const bridge = resolveBridge(o.bridge);
+        this.root = join(o.stateDir, 'openclaw');
+        this.dir = o.engineDir ?? join(this.root, 'engine');
+        this.bridgeSock = join(this.root, bridge.socketName);
+        this.paramPrefix = bridge.paramPrefix;
+    }
+    state(phase, why, retryAt) { this.o.onState({ phase, ...(why ? { why } : {}), ...(retryAt ? { retryAt } : {}) }); }
+    get entry() { return join(this.dir, 'node_modules', 'openclaw', 'openclaw.mjs'); }
+    async freePort() {
+        const server = createServer();
+        return new Promise((resolve, reject) => {
+            server.once('error', reject);
+            server.listen(0, '127.0.0.1', () => {
+                const a = server.address();
+                const port = a && typeof a !== 'string' ? a.port : 0;
+                server.close(() => resolve(port));
+            });
+        });
+    }
+    prepare() {
+        if (this.prepared)
+            return this.prepared;
+        const pending = this.prepareOnce();
+        this.prepared = pending;
+        void pending.finally(() => { if (this.prepared === pending)
+            this.prepared = undefined; }).catch(() => { });
+        return pending;
+    }
+    async prepareOnce() {
+        for (const d of [this.root, join(this.root, 'home'), join(this.root, 'state'), join(this.root, 'tmp'), join(this.root, 'install-home'), join(this.root, 'npm-cache'), join(this.o.stateDir, 'logs'), this.dir])
+            mkdirSync(d, { recursive: true, mode: 0o700 });
+        if (this.o.spawnEngine) {
+            const versionPath = join(this.dir, 'node_modules', 'openclaw', 'package.json');
+            const version = existsSync(versionPath) ? JSON.parse(readFileSync(versionPath, 'utf8')).version : undefined;
+            if (!existsSync(this.entry) || version !== ENGINE_VERSION) {
+                this.state('installing');
+                rmSync(join(this.dir, 'node_modules'), { recursive: true, force: true });
+                for (const f of ['package.json', 'package-lock.json'])
+                    copyFileSync(join(kitDir, 'engine', f), join(this.dir, f));
+                const result = spawnSync(this.o.npmPath ?? 'npm', ['ci', '--ignore-scripts', '--no-audit', '--no-fund', '--prefix', this.dir], {
+                    env: { PATH: process.env.PATH ?? '/usr/bin:/bin', HOME: join(this.root, 'install-home'), npm_config_cache: join(this.root, 'npm-cache'), OPENCLAW_DISABLE_BUNDLED_PLUGIN_POSTINSTALL: '1' },
+                    timeout: 300_000, stdio: 'pipe', encoding: 'utf8', maxBuffer: 1024 * 1024,
+                });
+                if (result.status !== 0) {
+                    this.state('failed', 'install');
+                    throw new Error(`engine install: ${result.error ?? result.stderr?.slice(-500)}`);
+                }
+            }
+            if (!existsSync(this.entry) || JSON.parse(readFileSync(versionPath, 'utf8')).version !== ENGINE_VERSION) {
+                this.state('needs-update', 'version');
+                throw new Error('engine version mismatch');
+            }
+        }
+        const tokenFile = join(this.root, 'token');
+        putOnce(tokenFile, randomBytes(32).toString('hex'));
+        this.token = readFileSync(tokenFile, 'utf8').trim();
+        const portFile = join(this.root, 'port');
+        putOnce(portFile, String(await this.freePort()));
+        this.port = Number(readFileSync(portFile, 'utf8'));
+        if (!Number.isInteger(this.port) || this.port < 1 || this.port > 65535 || this.port === 18789) {
+            this.state('failed', 'port');
+            throw new Error('invalid engine port');
+        }
+        const pluginDir = join(this.root, 'plugin');
+        mkdirSync(pluginDir, { recursive: true, mode: 0o700 });
+        // The shipped plugin follows the kit on every prepare too: a state dir from an older kit must not keep its gate.
+        for (const f of ['package.json', 'index.js']) {
+            const source = join(kitDir, 'plugin', f);
+            putChanged(join(pluginDir, f), readFileSync(source, 'utf8'));
+        }
+        // The bridge manifest and tool table follow the app's tools on every prepare (O5).
+        writePlugin(pluginDir, { id: this.o.pluginId, tools: this.o.tools, paramPrefix: this.paramPrefix,
+            gateBuiltins: this.o.gateBuiltins !== false });
+        const path = join(this.root, 'openclaw.json');
+        const saved = existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : undefined;
+        const config = reconcileConfig(saved, { root: this.root, stateDir: this.o.stateDir, port: this.port, pluginId: this.o.pluginId,
+            pluginDir, policyPath: join(kitDir, 'policy', 'policy.mjs'), app: this.o.config, installPolicy: this.o.installPolicy });
+        putChanged(path, JSON.stringify(config, null, 2) + '\n');
+    }
+    doctorContext() {
+        const home = join(this.root, 'home');
+        return { entry: this.entry, env: {
+                PATH: ['/usr/bin', '/bin', ...this.o.enginePath ?? []].join(':'), LANG: 'C.UTF-8', HOME: home, OPENCLAW_HOME: home,
+                OPENCLAW_STATE_DIR: join(this.root, 'state'), OPENCLAW_CONFIG_PATH: join(this.root, 'openclaw.json'),
+                XDG_CONFIG_HOME: join(home, '.config'), XDG_CACHE_HOME: join(home, '.cache'), XDG_DATA_HOME: join(home, '.local/share'),
+                XDG_STATE_HOME: join(home, '.local/state'), CODEX_HOME: join(home, '.codex'), CLAUDE_CONFIG_DIR: join(home, '.claude'),
+                TMPDIR: join(this.root, 'tmp'), OPENCLAW_NO_RESPAWN: '1', OPENCLAW_SKIP_CHANNELS: '1', OPENCLAW_DISABLE_BONJOUR: '1',
+                OPENCLAW_EXEC_SHELL_SNAPSHOT: '0', OPENCLAW_LOAD_SHELL_ENV: '0', OPENCLAW_GATEWAY_TOKEN: this.token,
+                BYOKIT_BRIDGE_SOCK: this.bridgeSock,
+            } };
+    }
+    doctor(timeoutMs) {
+        const { entry, env } = this.doctorContext();
+        const result = spawnSync(process.execPath, [entry, 'doctor', '--fix', '--yes', '--non-interactive'], { cwd: env.HOME, env, timeout: timeoutMs, stdio: 'pipe' });
+        return { status: result.status };
+    }
+    stalePid() {
+        const path = join(this.root, 'gateway.pid');
+        if (!existsSync(path))
+            return;
+        const pid = Number(readFileSync(path, 'utf8'));
+        if (!Number.isSafeInteger(pid) || pid < 1)
+            return;
+        try {
+            const cmd = readFileSync(`/proc/${pid}/cmdline`, 'utf8');
+            if (cmd.includes(this.entry) && cmd.includes('gateway'))
+                process.kill(-pid, 'SIGTERM');
+        }
+        catch { /* pid is gone or not ours */ }
+    }
+    async start() {
+        await this.prepare();
+        const identityPath = join(this.root, 'device.json');
+        if (!existsSync(identityPath)) {
+            const { privateKey, publicKey } = generateKeyPairSync('ed25519');
+            putOnce(identityPath, JSON.stringify({ privateKey: privateKey.export({ format: 'pem', type: 'pkcs8' }), publicKey: publicKey.export({ format: 'pem', type: 'spki' }) }));
+        }
+        if (!this.o.spawnEngine)
+            return { port: this.port, token: this.token, identityPath };
+        if (this.child && this.child.exitCode === null)
+            return { port: this.port, token: this.token, identityPath };
+        this.stopping = false;
+        this.stalePid();
+        this.state('starting');
+        const { entry, env } = this.doctorContext();
+        const fd = openSync(join(this.o.stateDir, 'logs', 'openclaw.log'), 'a', 0o600);
+        try {
+            this.child = spawn(process.execPath, [entry, 'gateway', '--port', String(this.port)], { cwd: env.HOME, env, detached: true, stdio: ['ignore', fd, fd] });
+        }
+        finally {
+            closeSync(fd);
+        }
+        const child = this.child;
+        if (!child.pid) {
+            this.state('failed', 'exited');
+            throw new Error('engine spawn failed');
+        }
+        writeFileSync(join(this.root, 'gateway.pid'), String(child.pid), { mode: 0o600 });
+        child.once('exit', (code) => {
+            if (this.child !== child || this.stopping)
+                return;
+            this.child = undefined;
+            this.o.onExit(code);
+            if (code === 78 && !this.repaired) {
+                this.repaired = true;
+                this.state('repairing');
+                const result = this.doctor(60_000);
+                if (result.status === 0) {
+                    void this.start().catch(() => this.state('failed', 'exited'));
+                    return;
+                }
+            }
+            this.state('failed', 'exited');
+        });
+        return { port: this.port, token: this.token, identityPath };
+    }
+    async stop() {
+        this.stopping = true;
+        const child = this.child;
+        this.child = undefined;
+        if (child?.pid && child.exitCode === null) {
+            try {
+                process.kill(-child.pid, 'SIGTERM');
+            }
+            catch { /* already gone */ }
+            for (let i = 0; i < 15 && child.exitCode === null; i++)
+                await delay(200);
+            if (child.exitCode === null) {
+                try {
+                    process.kill(-child.pid, 'SIGKILL');
+                }
+                catch { /* already gone */ }
+            }
+            for (let i = 0; i < 15 && child.exitCode === null; i++)
+                await delay(200);
+        }
+        rmSync(join(this.root, 'gateway.pid'), { force: true });
+        rmSync(this.bridgeSock, { force: true });
+        this.state('stopped');
+    }
+}

package/dist/generated/events.d.ts

@@ -0,0 +1,61 @@
+import type { AgentEvent, DevicePairSetupCompletedEvent, DevicePairSetupDeliveryUncertainEvent, NodeInvokeInputEvent, PortalChangedEvent, ProgressCardChangedEvent, QuestionRequestedEvent, SessionOperationEvent, SessionSharingEvent, SessionSharingEvidenceEvent, SessionSuggestionEvent, SessionTypingEvent, ShutdownEvent, TerminalDataEvent, TerminalExitEvent, TickEvent, UsersPrefsChangedEvent } from '@openclaw/gateway-protocol';
+import type { ChatEvent, QuestionResolvedEvent, SessionApprovalEvent, TaskSuggestionEvent } from './params.ts';
+export interface GatewayEvents {
+    'agent': AgentEvent;
+    'chat': ChatEvent;
+    'chat.metadata.changed': unknown;
+    'connect.challenge': unknown;
+    'controlUi.sessionPullRequests.changed': unknown;
+    'cron': unknown;
+    'device.pair.changed': unknown;
+    'device.pair.requested': unknown;
+    'device.pair.resolved': unknown;
+    'device.pair.setup.completed': DevicePairSetupCompletedEvent;
+    'device.pair.setup.deliveryUncertain': DevicePairSetupDeliveryUncertainEvent;
+    'exec.approval.requested': unknown;
+    'exec.approval.resolved': unknown;
+    'health': unknown;
+    'heartbeat': unknown;
+    'node.invoke.cancel': unknown;
+    'node.invoke.input': NodeInvokeInputEvent;
+    'node.invoke.request': unknown;
+    'node.pair.requested': unknown;
+    'node.pair.resolved': unknown;
+    'node.presence': unknown;
+    'node.runnerInventory.changed': unknown;
+    'openclaw.approval.requested': unknown;
+    'openclaw.approval.resolved': unknown;
+    'plugin.approval.requested': unknown;
+    'plugin.approval.resolved': unknown;
+    'portal.changed': PortalChangedEvent;
+    'presence': unknown;
+    'progressCard.changed': ProgressCardChangedEvent;
+    'question.requested': QuestionRequestedEvent;
+    'question.resolved': QuestionResolvedEvent;
+    'session.approval': SessionApprovalEvent;
+    'session.message': unknown;
+    'session.observer': unknown;
+    'session.operation': SessionOperationEvent;
+    'session.sharing': SessionSharingEvent;
+    'session.sharing.evidence': SessionSharingEvidenceEvent;
+    'session.suggestion': SessionSuggestionEvent;
+    'session.tool': unknown;
+    'session.typing': SessionTypingEvent;
+    'sessions.changed': unknown;
+    'shutdown': ShutdownEvent;
+    'skills.changed': unknown;
+    'talk.event': unknown;
+    'talk.mode': unknown;
+    'task': unknown;
+    'task.suggestion': TaskSuggestionEvent;
+    'terminal.data': TerminalDataEvent;
+    'terminal.exit': TerminalExitEvent;
+    'tick': TickEvent;
+    'ui.command': unknown;
+    'update.available': unknown;
+    'users.prefs.changed': UsersPrefsChangedEvent;
+    'voicewake.changed': unknown;
+    'voicewake.routing.changed': unknown;
+}
+export type GatewayEventName = keyof GatewayEvents;
+export type GatewayEventPayload<E extends GatewayEventName> = GatewayEvents[E];

package/dist/generated/events.js

@@ -0,0 +1 @@
+export {};