@byokit/openclaw 0.1.0

package/dist/kit.js

@@ -0,0 +1,655 @@
+// The OpenClawKit facade: state, complete pass-through (D6), members, sign-in, runs, approvals, config (5.3).
+// Built in O4 (and O5/O6/O8 for the delegated parts); until then every body refuses to run.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { fileURLToPath } from 'node:url';
+import { PROTOCOL_VERSION } from "./constants.js";
+import { Approvals } from "./approvals.js";
+import { Bridge } from "./bridge.js";
+import { Engine } from "./engine.js";
+import { gatewayTransport } from "./transport.js";
+import { createMembers } from "./members.js";
+import { confirmRetainedLogin as confirmLogin, migrateRetainedLogin as migrateLogin } from "./migrate.js";
+import { createRuns } from "./runs.js";
+import { routes as routeTable } from "./routes.js";
+import { providers as engineProviders, signIn as startSignIn, signOut as engineSignOut } from "./signin.js";
+import { reconcileConfig, memoryLimited as configMemoryLimited } from "./config.js";
+const operatorMethods = new Set([
+    'agent',
+    'agent.identity.get',
+    'agent.wait',
+    'agents.create',
+    'agents.delete',
+    'agents.files.get',
+    'agents.files.list',
+    'agents.files.set',
+    'agents.list',
+    'agents.update',
+    'agents.workspace.get',
+    'agents.workspace.list',
+    'approval.get',
+    'approval.history',
+    'approval.resolve',
+    'artifacts.download',
+    'artifacts.get',
+    'artifacts.list',
+    'assistant.media.get',
+    'attach.grant',
+    'attach.revoke',
+    'audit.activity.list',
+    'audit.list',
+    'audit.run.inspect',
+    'board.action',
+    'board.data.read',
+    'board.event',
+    'board.get',
+    'board.prompt.authorize',
+    'board.update',
+    'board.widget.appView',
+    'board.widget.grant',
+    'board.widget.put',
+    'channels.logout',
+    'channels.pairing.approve',
+    'channels.pairing.dismiss',
+    'channels.pairing.list',
+    'channels.start',
+    'channels.status',
+    'channels.stop',
+    'chat.abort',
+    'chat.history',
+    'chat.inject',
+    'chat.message.get',
+    'chat.metadata',
+    'chat.send',
+    'chat.startup',
+    'chat.toolTitles',
+    'commands.list',
+    'config.apply',
+    'config.get',
+    'config.openFile',
+    'config.patch',
+    'config.schema',
+    'config.schema.lookup',
+    'config.set',
+    'connect',
+    'controlUi.githubPreview',
+    'controlUi.sessionPreview',
+    'controlUi.sessionPullRequests.subscribe',
+    'conversations.list',
+    'conversations.send',
+    'conversations.turn',
+    'conversations.turn.cancel',
+    'cron.add',
+    'cron.get',
+    'cron.list',
+    'cron.remove',
+    'cron.run',
+    'cron.runs',
+    'cron.scratch.get',
+    'cron.scratch.set',
+    'cron.status',
+    'cron.update',
+    'desktop.launch',
+    'desktop.observe',
+    'device.pair.approve',
+    'device.pair.list',
+    'device.pair.reject',
+    'device.pair.remove',
+    'device.pair.rename',
+    'device.pair.setupCode',
+    'device.pair.setupStatus',
+    'device.scopes.requestUpgrade',
+    'device.scopes.waitUpgrade',
+    'device.token.revoke',
+    'device.token.rotate',
+    'diagnostics.lanes',
+    'diagnostics.stability',
+    'doctor.memory.backfillDreamDiary',
+    'doctor.memory.dedupeDreamDiary',
+    'doctor.memory.dreamDiary',
+    'doctor.memory.repairDreamingArtifacts',
+    'doctor.memory.resetDreamDiary',
+    'doctor.memory.resetGroundedShortTerm',
+    'doctor.memory.status',
+    'environments.create',
+    'environments.destroy',
+    'environments.list',
+    'environments.status',
+    'exec.approval.get',
+    'exec.approval.grants.list',
+    'exec.approval.grants.revoke',
+    'exec.approval.list',
+    'exec.approval.request',
+    'exec.approval.resolve',
+    'exec.approval.waitDecision',
+    'exec.approvals.get',
+    'exec.approvals.node.get',
+    'exec.approvals.node.set',
+    'exec.approvals.set',
+    'fs.listDir',
+    'gateway.identity.get',
+    'gateway.restart.preflight',
+    'gateway.restart.request',
+    'gateway.suspend.prepare',
+    'gateway.suspend.resume',
+    'gateway.suspend.status',
+    'health',
+    'hooks.status',
+    'last-heartbeat',
+    'logs.tail',
+    'mcp.app.callTool',
+    'mcp.app.listResourceTemplates',
+    'mcp.app.listResources',
+    'mcp.app.listTools',
+    'mcp.app.readResource',
+    'mcp.app.updateModelContext',
+    'mcp.app.view',
+    'memory.search',
+    'message.action',
+    'migrations.memory.apply',
+    'migrations.memory.plan',
+    'models.authLogout',
+    'models.authStatus',
+    'models.list',
+    'models.probe',
+    'nativeHook.invoke',
+    'node.describe',
+    'node.invoke',
+    'node.list',
+    'node.pair.approve',
+    'node.pair.list',
+    'node.pair.reject',
+    'node.pair.remove',
+    'node.pending.enqueue',
+    'node.rename',
+    'openclaw.approval.list',
+    'openclaw.changes.list',
+    'openclaw.chat',
+    'openclaw.chat.history',
+    'openclaw.setup.activate',
+    'openclaw.setup.auth.start',
+    'openclaw.setup.detect',
+    'openclaw.setup.prepare.start',
+    'openclaw.setup.verify',
+    'plugin.approval.list',
+    'plugin.approval.request',
+    'plugin.approval.resolve',
+    'plugin.approval.waitDecision',
+    'plugin.surface.refresh',
+    'plugins.inspect',
+    'plugins.install',
+    'plugins.list',
+    'plugins.refresh',
+    'plugins.search',
+    'plugins.sessionAction',
+    'plugins.setEnabled',
+    'plugins.uiDescriptors',
+    'plugins.uninstall',
+    'poll',
+    'portal.close',
+    'portal.list',
+    'portal.open',
+    'progressCard.get',
+    'progressCard.put',
+    'projects.add',
+    'projects.list',
+    'projects.register',
+    'projects.remove',
+    'projects.searchRemote',
+    'push.test',
+    'push.web.preferences.get',
+    'push.web.preferences.set',
+    'push.web.subscribe',
+    'push.web.test',
+    'push.web.unsubscribe',
+    'push.web.vapidPublicKey',
+    'question.get',
+    'question.list',
+    'question.request',
+    'question.resolve',
+    'question.waitAnswer',
+    'secrets.reload',
+    'secrets.resolve',
+    'secrets.store.delete',
+    'secrets.store.list',
+    'secrets.store.set',
+    'send',
+    'session.discussion.info',
+    'session.discussion.open',
+    'session.members.add',
+    'session.members.list',
+    'session.members.listEvidence',
+    'session.members.remove',
+    'session.suggestions.add',
+    'session.suggestions.list',
+    'session.suggestions.resolve',
+    'session.typing',
+    'session.visibility.set',
+    'sessions.abort',
+    'sessions.assignOwner',
+    'sessions.branches.list',
+    'sessions.branches.switch',
+    'sessions.catalog.archive',
+    'sessions.catalog.continue',
+    'sessions.catalog.list',
+    'sessions.catalog.read',
+    'sessions.catalog.startTerminal',
+    'sessions.cleanup',
+    'sessions.compact',
+    'sessions.compaction.branch',
+    'sessions.compaction.list',
+    'sessions.compaction.restore',
+    'sessions.companion.ask',
+    'sessions.companion.reset',
+    'sessions.companion.state',
+    'sessions.create',
+    'sessions.delete',
+    'sessions.describe',
+    'sessions.diff',
+    'sessions.dispatch',
+    'sessions.files.get',
+    'sessions.files.list',
+    'sessions.files.reveal',
+    'sessions.files.set',
+    'sessions.fork',
+    'sessions.get',
+    'sessions.github.publish',
+    'sessions.goal.clear',
+    'sessions.goal.update',
+    'sessions.groups.defaults',
+    'sessions.groups.delete',
+    'sessions.groups.list',
+    'sessions.groups.put',
+    'sessions.groups.rename',
+    'sessions.groups.update',
+    'sessions.list',
+    'sessions.messages.subscribe',
+    'sessions.messages.unsubscribe',
+    'sessions.move',
+    'sessions.observer.visibility',
+    'sessions.patch',
+    'sessions.patchMany',
+    'sessions.pluginPatch',
+    'sessions.preview',
+    'sessions.reclaim',
+    'sessions.recover',
+    'sessions.reset',
+    'sessions.resolve',
+    'sessions.rewind',
+    'sessions.search',
+    'sessions.send',
+    'sessions.steer',
+    'sessions.subscribe',
+    'sessions.usage',
+    'sessions.usage.logs',
+    'sessions.usage.timeseries',
+    'sessions.viewers.set',
+    'set-heartbeats',
+    'skills.curator.pin',
+    'skills.curator.restore',
+    'skills.curator.status',
+    'skills.curator.unpin',
+    'skills.detail',
+    'skills.install',
+    'skills.proposals.apply',
+    'skills.proposals.create',
+    'skills.proposals.evaluate',
+    'skills.proposals.events.list',
+    'skills.proposals.historyScan',
+    'skills.proposals.historyStatus',
+    'skills.proposals.inspect',
+    'skills.proposals.list',
+    'skills.proposals.quarantine',
+    'skills.proposals.reject',
+    'skills.proposals.requestRevision',
+    'skills.proposals.revise',
+    'skills.proposals.update',
+    'skills.search',
+    'skills.securityVerdicts',
+    'skills.skillCard',
+    'skills.status',
+    'skills.update',
+    'skills.upload.begin',
+    'skills.upload.chunk',
+    'skills.upload.commit',
+    'status',
+    'system-event',
+    'system-presence',
+    'system.info',
+    'talk.catalog',
+    'talk.client.close',
+    'talk.client.create',
+    'talk.client.steer',
+    'talk.client.toolCall',
+    'talk.client.transcript',
+    'talk.config',
+    'talk.mode',
+    'talk.session.acknowledgeMark',
+    'talk.session.appendAudio',
+    'talk.session.cancelOutput',
+    'talk.session.close',
+    'talk.session.create',
+    'talk.session.steer',
+    'talk.session.submitToolResult',
+    'talk.speak',
+    'taskSuggestions.accept',
+    'taskSuggestions.create',
+    'taskSuggestions.dismiss',
+    'taskSuggestions.list',
+    'tasks.cancel',
+    'tasks.dismiss',
+    'tasks.get',
+    'tasks.list',
+    'tasks.retry',
+    'terminal.attach',
+    'terminal.close',
+    'terminal.input',
+    'terminal.list',
+    'terminal.open',
+    'terminal.resize',
+    'terminal.upload',
+    'tools.catalog',
+    'tools.effective',
+    'tools.github.authorize.cancel',
+    'tools.github.authorize.poll',
+    'tools.github.authorize.start',
+    'tools.github.configure',
+    'tools.github.status',
+    'tools.invoke',
+    'tts.convert',
+    'tts.disable',
+    'tts.enable',
+    'tts.personas',
+    'tts.providers',
+    'tts.setPersona',
+    'tts.setProvider',
+    'tts.speak',
+    'tts.status',
+    'ui.command',
+    'update.hold',
+    'update.run',
+    'update.status',
+    'usage.cost',
+    'usage.status',
+    'users.linkEmail',
+    'users.list',
+    'users.prefs.get',
+    'users.prefs.set',
+    'users.self',
+    'users.setAvatar',
+    'users.setDisplayName',
+    'users.setRole',
+    'voicewake.get',
+    'voicewake.routing.get',
+    'voicewake.set',
+    'wake',
+    'web.login.start',
+    'web.login.wait',
+    'wizard.cancel',
+    'wizard.next',
+    'wizard.start',
+    'wizard.status',
+    'worker.desktop.launch',
+    'worker.desktop.observe',
+    'worktrees.branches',
+    'worktrees.create',
+    'worktrees.gc',
+    'worktrees.list',
+    'worktrees.remove',
+    'worktrees.restore',
+]);
+const nodeMethods = new Set([
+    'node.event',
+    'node.invoke.progress',
+    'node.invoke.result',
+    'node.pending.ack',
+    'node.pending.drain',
+    'node.pending.pull',
+    'node.pluginSurface.refresh',
+    'node.pluginTools.update',
+    'node.runnerInventory.update',
+    'node.skills.update',
+    'skills.bins',
+]);
+export class OpenClawKit {
+    engine;
+    o;
+    current = { phase: 'stopped' };
+    transport;
+    greeting;
+    members;
+    // One bridge and one approval surface per kit: listeners and run registrations survive reconnects (B3).
+    // Only the socket itself is per-connection. Approvals always reaches the live transport through this.request().
+    bridge;
+    approvalsCtl;
+    listeners = new Set();
+    off = [];
+    starting;
+    stopping = false;
+    failures = 0;
+    constructor(o) {
+        if (o.tools?.length && !o.host)
+            throw new Error('host required when tools are registered');
+        // The engine lowercases and alias-maps a tool name before the gate hook sees it (bash -> exec, cron ->
+        // automations); a name it would rewrite reaches the gate as a builtin, so refuse it here.
+        for (const t of o.tools ?? []) {
+            if (!/^[a-z][a-z0-9_]*$/.test(t.name) || t.name === 'bash' || t.name === 'cron')
+                throw new Error(`invalid tool name: ${t.name}`);
+        }
+        this.o = o;
+        this.engine = new Engine({ ...o, pluginId: o.plugin?.id ?? 'byokit', tools: o.tools ?? [],
+            gateBuiltins: o.gateBuiltins !== false, spawnEngine: o.spawnEngine !== false,
+            onState: (s) => this.setState(s), onExit: () => this.closed('engine exited') });
+        const slot = {};
+        this.approvalsCtl = new Approvals({
+            request: (method, params, co) => this.request()(method, params, co),
+            bridge: { resolveAsk: (id, d) => slot.bridge?.resolveAsk(id, d) ?? false },
+        });
+        this.bridge = new Bridge({ path: this.engine.bridgeSock, host: o.host, tools: new Set((o.tools ?? []).map((t) => t.name)),
+            permitted: o.permitted ?? (() => true), approvalTimeoutMs: o.approvalTimeoutMs ?? 180_000,
+            onAsk: (a) => this.approvalsCtl.add(a), onAskGone: (id) => this.approvalsCtl.remove(id) });
+        slot.bridge = this.bridge;
+    }
+    setState(s) { this.current = s; this.o.onState?.(s); }
+    get state() { return this.current; }
+    prepare() { return this.engine.prepare(); }
+    start() {
+        if (this.current.phase === 'ready')
+            return Promise.resolve();
+        if (this.starting)
+            return this.starting;
+        this.stopping = false;
+        const task = this.connect();
+        this.starting = task;
+        void task.finally(() => { if (this.starting === task)
+            this.starting = undefined; }).catch(() => { });
+        return task;
+    }
+    async connect() {
+        let transport;
+        try {
+            const ctx = await this.engine.start();
+            if (this.stopping)
+                return;
+            this.setState({ phase: 'starting' });
+            transport = (this.o.transport ?? gatewayTransport)({ ...ctx, bridgeSock: this.engine.bridgeSock });
+            this.transport = transport;
+            this.off = [transport.onEvent((e) => { for (const fn of this.listeners)
+                    fn(e); }), transport.onClose((why) => this.closed(why))];
+            const hello = await Promise.race([transport.start(), delay(90_000, undefined, { ref: false }).then(() => { throw new Error('gateway handshake timed out'); })]);
+            if (this.stopping || this.transport !== transport)
+                return;
+            if (hello.protocol !== PROTOCOL_VERSION) {
+                this.setState({ phase: 'needs-update', why: 'version' });
+                throw new Error(`gateway protocol ${hello.protocol} != ${PROTOCOL_VERSION}`);
+            }
+            this.greeting = hello;
+            for (const name of operatorMethods)
+                if (!hello.methods.includes(name))
+                    this.o.log?.(`gateway missing generated method: ${name}`);
+            for (const name of hello.methods)
+                if (!operatorMethods.has(name) && !nodeMethods.has(name))
+                    this.o.log?.(`gateway has unknown method: ${name}`);
+            this.members = createMembers({ request: transport.request.bind(transport), root: this.engine.root });
+            // The fail-closed tool bridge feeds the kit's single Approval surface (5.9, O5).
+            await this.bridge.start();
+            this.off.push(transport.onEvent((e) => this.approvalsCtl.handleEvent(e)));
+            this.failures = 0;
+            this.setState({ phase: 'ready' });
+            // Replays the engine's native approval lists over the now-live transport (N9).
+            await this.approvalsCtl.resync();
+        }
+        catch (error) {
+            if (transport && this.transport === transport)
+                await this.disconnect();
+            if (this.current.phase !== 'needs-update' && !this.stopping)
+                this.setState({ phase: 'failed', why: 'handshake' });
+            throw error;
+        }
+    }
+    async disconnect() {
+        this.off.splice(0).forEach((fn) => fn());
+        const transport = this.transport;
+        this.transport = undefined;
+        this.greeting = undefined;
+        this.members = undefined;
+        this.bridge.stop();
+        await transport?.stop();
+    }
+    closed(_why) {
+        if (this.stopping || this.current.phase !== 'ready')
+            return;
+        void this.disconnect();
+        if (this.o.spawnEngine === false) {
+            this.setState({ phase: 'failed', why: 'handshake' });
+            return;
+        }
+        const retryAt = Date.now() + Math.min(30_000, 1000 * 2 ** this.failures++);
+        this.setState({ phase: 'restarting', retryAt });
+        void delay(retryAt - Date.now()).then(() => { if (!this.stopping && this.current.phase === 'restarting')
+            void this.start().catch(() => { }); });
+    }
+    async stop() {
+        this.stopping = true;
+        await this.disconnect();
+        await this.engine.stop();
+    }
+    request() {
+        if (!this.transport || this.current.phase !== 'ready')
+            throw new Error('gateway not ready');
+        return this.transport.request.bind(this.transport);
+    }
+    call(method, params, o) {
+        try {
+            return this.request()(method, params, o);
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+    }
+    callDynamic(method, params, o) {
+        if (operatorMethods.has(method) || nodeMethods.has(method))
+            return Promise.reject(new Error(`use typed call for generated method: ${method}`));
+        try {
+            return this.request()(method, params, o);
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+    }
+    get hello() { return this.greeting; }
+    onEvent(event, fn) {
+        const listener = (e) => {
+            if (event === '*' || e.event === event)
+                fn(e.payload, e.event);
+        };
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    ensureMember(member) {
+        if (!this.members)
+            return Promise.reject(new Error('gateway not ready'));
+        return this.members.ensure(member);
+    }
+    // sign-in (5.7): every body here is the module's, with this kit's transport, members and ports.
+    signInCtx() {
+        return { request: (method, params, o) => this.request()(method, params, o),
+            ensure: (member) => this.ensureMember(member), callbackPort: this.o.callbackPort ?? 1455 };
+    }
+    routes() {
+        return routeTable();
+    }
+    providers(member) {
+        return engineProviders(this.signInCtx(), member);
+    }
+    signedIn(member, provider) {
+        return engineProviders(this.signInCtx(), member).then((names) => names.includes(provider)).catch(() => false);
+    }
+    signIn(member, o, on) {
+        return startSignIn(this.signInCtx(), member, o, on);
+    }
+    signOut(member, provider) {
+        return engineSignOut(this.signInCtx(), member, provider);
+    }
+    migrateRetainedLogin(member, source) {
+        return migrateLogin({ root: this.engine.root, prepare: () => this.prepare(), doctor: () => this.engine.doctor(120_000) }, member, source);
+    }
+    confirmRetainedLogin(member, source) {
+        return confirmLogin(this.signInCtx(), member, source);
+    }
+    // runs (5.8): the facade owns no run state; every call delegates to the O8 module
+    // with this kit's live transport, member table and bridge (firstmate clearance, O9).
+    runs() {
+        return createRuns({
+            request: (method, params, o) => this.request()(method, params, o),
+            onEvent: (fn) => {
+                this.listeners.add(fn);
+                return () => {
+                    this.listeners.delete(fn);
+                };
+            },
+            ensure: (member) => this.ensureMember(member),
+            bridge: this.bridge,
+        });
+    }
+    run(spec, on) {
+        return this.runs().run(spec, on);
+    }
+    steer(sessionKey, text) {
+        return this.runs().steer(sessionKey, text);
+    }
+    abort(sessionKey) {
+        return this.runs().abort(sessionKey);
+    }
+    // approvals (5.9)
+    approvals(member) {
+        return this.approvalsCtl.list(member);
+    }
+    onApproval(fn) {
+        return this.approvalsCtl.on(fn);
+    }
+    decide(id, d) {
+        return this.approvalsCtl.decide(id, d);
+    }
+    allowOnce(rule, ms) {
+        this.bridge.allowOnce(rule, ms);
+    }
+    disallowOnce() {
+        this.bridge.disallowOnce();
+    }
+    // config
+    async patchConfig(patch, o) {
+        const response = await this.request()('config.get');
+        const safe = reconcileConfig(response.config, { root: this.engine.root, stateDir: this.o.stateDir,
+            port: Number(readFileSync(join(this.engine.root, 'port'), 'utf8')), pluginId: this.o.plugin?.id ?? 'byokit',
+            pluginDir: join(this.engine.root, 'plugin'), policyPath: fileURLToPath(new URL('../policy/policy.mjs', import.meta.url)), app: patch,
+            installPolicy: this.o.installPolicy });
+        await this.request()('config.patch', { raw: JSON.stringify(safe), baseHash: response.hash, ...(o?.agentId ? { agentId: o.agentId } : {}) });
+    }
+    memoryLimited(member) {
+        const config = JSON.parse(readFileSync(join(this.engine.root, 'openclaw.json'), 'utf8'));
+        return configMemoryLimited(config, member);
+    }
+    doctorContext() { return this.engine.doctorContext(); }
+}

package/dist/link.d.ts

@@ -0,0 +1,24 @@
+import { type IncomingMessage, type ServerResponse } from 'node:http';
+import { type Grant, type Host, type HostOptions } from '@byokit/link';
+import { type ServeIngress, type Via } from '@byokit/reach';
+import type { PushAction, RelayClient } from '@byokit/relay';
+import type { OpenClawKit } from './kit.ts';
+import type { Member } from './types.ts';
+export declare function openclawLink(kit: OpenClawKit, o: {
+    memberOf: (grant: Grant) => Member | undefined;
+    passThrough?: (method: string, grant: Grant) => boolean;
+    relay?: RelayClient;
+}): Pick<HostOptions, 'handle' | 'stream' | 'allow'> & {
+    onAction(a: PushAction): Promise<unknown>;
+};
+export declare function serve(o: {
+    host: Host;
+    port: number;
+    via?: Via;
+    previous?: ServeIngress;
+    http?: (req: IncomingMessage, res: ServerResponse) => void;
+}): Promise<{
+    urls: string[];
+    ingress?: ServeIngress;
+    close(): Promise<void>;
+}>;