@byokit/openclaw 0.1.0

package/dist/transport.js

@@ -0,0 +1,94 @@
+import { createHash, createPrivateKey, createPublicKey, sign } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { GatewayClient } from '@openclaw/gateway-client';
+import { OPERATOR_SCOPES, PROTOCOL_VERSION } from "./constants.js";
+/**
+ * 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 const GATEWAY_CAPS = ['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 function loadDeviceKeys(identityPath) {
+    const raw = JSON.parse(readFileSync(identityPath, 'utf8'));
+    const privateKeyPem = typeof raw.privateKey === 'string' ? raw.privateKey
+        : typeof raw.privateKeyPem === 'string' ? raw.privateKeyPem
+            : undefined;
+    const publicKeyPem = typeof raw.publicKey === 'string' ? raw.publicKey
+        : typeof raw.publicKeyPem === 'string' ? raw.publicKeyPem
+            : undefined;
+    if (privateKeyPem === undefined || publicKeyPem === undefined) {
+        throw new Error(`The device identity file at ${identityPath} is not usable: it holds no device key pair.`);
+    }
+    // A paired file names its own deviceId (O11 fan-out): it wins so the paired identity survives re-derivation.
+    const deviceId = typeof raw.deviceId === 'string' && raw.deviceId ? raw.deviceId : undefined;
+    return { privateKeyPem, publicKeyPem, ...(deviceId ? { deviceId } : {}) };
+}
+export function gatewayTransport(ctx) {
+    const pem = loadDeviceKeys(ctx.identityPath);
+    const publicKey = createPublicKey(pem.publicKeyPem).export({ format: 'der', type: 'spki' }).subarray(-32);
+    const events = new Set();
+    const closes = new Set();
+    let ready;
+    let pending;
+    let stopped = false;
+    // The last transient connect failure, kept for the terminal error. The client retries boot-time
+    // ECONNREFUSED itself with backoff (O11: the first kit.start() lands while the gateway still binds),
+    // so connect errors never settle the handshake; only a paused reconnect (terminal: auth, protocol)
+    // or the kit's own deadline does.
+    let lastConnectError;
+    const client = new GatewayClient({
+        url: `ws://127.0.0.1:${ctx.port}`, token: ctx.token, role: 'operator', scopes: [...OPERATOR_SCOPES],
+        clientName: 'cli', caps: [...GATEWAY_CAPS], minProtocol: PROTOCOL_VERSION, maxProtocol: PROTOCOL_VERSION,
+        deviceIdentity: { deviceId: pem.deviceId ?? createHash('sha256').update(publicKey).digest('hex'),
+            privateKeyPem: pem.privateKeyPem, publicKeyPem: pem.publicKeyPem },
+        hostDeps: {
+            signDevicePayload: (key, payload) => sign(null, Buffer.from(payload), createPrivateKey(key)).toString('base64url'),
+            publicKeyRawBase64UrlFromPem: (key) => createPublicKey(key).export({ format: 'der', type: 'spki' }).subarray(-32).toString('base64url'),
+            loadDeviceAuthToken: () => null, storeDeviceAuthToken: () => { }, clearDeviceAuthToken: () => { },
+        },
+        onHelloOk: (h) => {
+            if (stopped)
+                return;
+            ready = { protocol: h.protocol, server: { version: h.server.version }, methods: h.features.methods, events: h.features.events };
+            pending?.resolve(ready);
+            pending = undefined;
+        },
+        onEvent: (e) => { for (const fn of events)
+            fn({ event: e.event, payload: e.payload }); },
+        onConnectError: (e) => { lastConnectError = e; },
+        onReconnectPaused: (info) => {
+            const terminal = new Error(`gateway connect paused: ${info.code} ${info.reason ?? ''}${lastConnectError ? ` (last: ${lastConnectError.message})` : ''}`);
+            pending?.reject(terminal);
+            pending = undefined;
+        },
+        onClose: (code, reason) => {
+            ready = undefined;
+            // A pre-hello close while the client still retries is transient (backoff continues inside the
+            // client); only a stopped transport settles the handshake here. Terminal give-ups arrive paused.
+            if (pending && stopped) {
+                pending.reject(new Error(`gateway closed: ${code} ${reason}`));
+                pending = undefined;
+            }
+            else if (!pending && !stopped)
+                for (const fn of closes)
+                    fn(reason || String(code));
+        },
+    });
+    return {
+        start: () => {
+            if (ready)
+                return Promise.resolve(ready);
+            if (pending)
+                return Promise.reject(new Error('gateway handshake already pending'));
+            return new Promise((resolve, reject) => { pending = { resolve, reject }; stopped = false; client.start(); });
+        },
+        request: (method, params, o) => client.request(method, params, o),
+        onEvent: (fn) => { events.add(fn); return () => { events.delete(fn); }; },
+        onClose: (fn) => { closes.add(fn); return () => { closes.delete(fn); }; },
+        stop: async () => { stopped = true; pending?.reject(new Error('gateway stopped')); pending = undefined; ready = undefined; await client.stopAndWait(); },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,125 @@
+export type Member = string;
+export interface ToolSpec {
+    name: string;
+    description: string;
+    parameters: object;
+}
+export interface RunRef {
+    sessionKey: string;
+    member: Member;
+    meta?: unknown;
+}
+export type GateResult = {
+    allow: true;
+} | {
+    allow: false;
+    reason: string;
+} | {
+    ask: {
+        summary: string;
+    };
+};
+export interface ToolHost {
+    gate(run: RunRef, tool: string, input: Record<string, unknown>, info: {
+        builtin: boolean;
+    }): Promise<GateResult>;
+    call(run: RunRef, tool: string, input: Record<string, unknown>, signal: AbortSignal): Promise<string>;
+}
+export interface RunSpec extends RunRef {
+    message: string;
+    system?: string;
+    images?: {
+        data: string;
+        mimeType: string;
+    }[];
+    thinking?: 'off' | 'low' | 'medium' | 'high';
+    model?: string;
+    register?: boolean;
+}
+export type RunEvent = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'tool';
+    name: string;
+    phase: 'start' | 'end';
+};
+export type RunEnd = {
+    ok: true;
+    text: string;
+} | {
+    ok: false;
+    aborted: true;
+} | {
+    ok: false;
+    kind: 'signed-out' | 'resting' | 'plan' | 'network' | 'other';
+    until?: number;
+    message: string;
+};
+export type SignInView = {
+    state: 'waiting' | 'done' | 'failed';
+    via: 'browser' | 'code';
+    url?: string;
+    code?: string;
+    error?: string;
+    why?: 'busy' | 'declined' | 'expired' | 'failed';
+};
+export type Approval = {
+    id: string;
+    source: 'gate' | 'exec' | 'plugin' | 'question';
+    member: Member;
+    sessionKey?: string;
+    tool?: string;
+    summary: string;
+    input?: unknown;
+    at: number;
+    expires: number;
+};
+export type Decision = {
+    allow: boolean;
+    reason?: string;
+    answer?: unknown;
+};
+export type KitState = {
+    phase: 'stopped' | 'installing' | 'starting' | 'repairing' | 'ready' | 'restarting' | 'failed' | 'needs-update';
+    why?: 'install' | 'handshake' | 'exited' | 'port' | 'version';
+    retryAt?: number;
+};
+export type Hello = {
+    protocol: number;
+    server: {
+        version: string;
+    };
+    methods: string[];
+    events: string[];
+};
+export type Route = {
+    choice: string;
+    provider: string;
+    plugin: string;
+    billing: 'subscription' | 'api' | 'local';
+    via: 'browser' | 'code';
+    prerequisite: string | null;
+    offer: boolean;
+    reason: string;
+    source: string;
+};
+export interface GatewayTransport {
+    start(): Promise<Hello>;
+    request(method: string, params?: unknown, o?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+    onEvent(fn: (e: {
+        event: string;
+        payload?: unknown;
+    }) => void): () => void;
+    onClose(fn: (why: string) => void): () => void;
+    stop(): Promise<void>;
+}
+export type CallOptions = {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+};
+export type { GatewayMethod, GatewayParams, GatewayResult } from './generated/methods.ts';
+export type { GatewayEventName, GatewayEventPayload } from './generated/events.ts';

package/dist/types.js

@@ -0,0 +1,2 @@
+// Public types for the OpenClaw runtime kit (docs/runtime-kits.md 5.2). Types only; behavior lives in the modules.
+export {};

package/dist/words.d.ts

@@ -0,0 +1,12 @@
+import wordsJson from './words.json' with { type: 'json' };
+import type { KitState, SignInView } from './types.ts';
+/** ui-core's AccountView shape, declared locally so this module stays dependency-free (5.14). */
+export type AccountView = {
+    ready?: boolean;
+    work?: string | boolean;
+    signIn?: SignInView | null;
+};
+export type WordKey = Extract<keyof typeof wordsJson, string>;
+export declare function words(key: WordKey, vars?: Record<string, string>): string;
+export declare function stateWords(s: KitState): string;
+export declare function toAccountView(view: SignInView | null, ready: boolean): AccountView;

package/dist/words.js

@@ -0,0 +1,26 @@
+// Every sentence a person can see, in one file other languages can read too (5.14). Plain words only (4.3).
+import wordsJson from './words.json' with { type: 'json' };
+export function words(key, vars) {
+    let sentence = wordsJson[key];
+    if (vars)
+        for (const [name, value] of Object.entries(vars))
+            sentence = sentence.replaceAll(`{${name}}`, value);
+    return sentence;
+}
+const PHASE_WORDS = {
+    installing: 'engine.installing',
+    starting: 'engine.starting',
+    repairing: 'engine.repairing',
+    ready: 'engine.ready',
+    restarting: 'engine.restarting',
+    failed: 'engine.failed',
+    'needs-update': 'engine.needsUpdate',
+};
+export function stateWords(s) {
+    // 'stopped' is never on screen (4.3 covers what a person can see), so 5.14 has no row for it.
+    return s.phase === 'stopped' ? '' : words(PHASE_WORDS[s.phase]);
+}
+export function toAccountView(view, ready) {
+    // `why` maps 1:1; ui-core's phaseOf reads busy/declined/expired itself (5.14).
+    return { ready, signIn: view };
+}

package/dist/words.json

@@ -0,0 +1,20 @@
+{
+    "engine.installing": "Getting things ready on this computer. The first time takes a few minutes.",
+    "engine.starting": "Starting up…",
+    "engine.repairing": "Fixing a small problem with the setup. This takes a moment.",
+    "engine.ready": "Ready.",
+    "engine.restarting": "Something stopped. Starting it again by itself.",
+    "engine.failed": "This computer couldn't start the helper. Restart the app to try again.",
+    "engine.needsUpdate": "This app needs an update to keep working.",
+    "member.signedOut": "Sign in with {name} to start.",
+    "member.resting": "{name} needs a break until {time}.",
+    "member.plan": "Your {name} plan doesn't include this.",
+    "member.network": "Can't reach {name} right now. This keeps trying by itself.",
+    "signin.returned": "Thanks. Finishing the sign-in — you can go back to the app now.",
+    "signin.busy": "Another sign-in is already in progress. Finish or cancel it, then try again.",
+    "signin.expired": "The sign-in took too long. Start it again.",
+    "approval.ask": "{helper} wants to {summary}. Allow it?",
+    "approval.expired": "Nobody answered in time, so this wasn't allowed.",
+    "approval.notice": "Something is waiting for your yes.",
+    "link.notAllowed": "This device can't do that. Ask the person at the computer."
+}