@byokit/openclaw 0.5.1 → 0.6.2

package/dist/kit.js

@@ -3,6 +3,7 @@ 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 { atomic } from "./engine-patches.js";
 import { Approvals } from "./approvals.js";
 import { Bridge } from "./bridge.js";
 import { Engine } from "./engine.js";
@@ -15,7 +16,10 @@ import { outputSchema } from "./output.js";
 import { createKeys } from "./keys.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";
+import { reconcileConfig, browserToolPolicySafe, browserProfileAcknowledged, browserSessionMayRun, memoryLimited as configMemoryLimited, configKeyPath, readConfigKey, writeConfigKey } from "./config.js";
+import { createBrowserHost } from "./browser/host.js";
+import { fileSignInStore } from "./browser/store.js";
+import { launchBroker } from "./browser/broker.js";
 const operatorMethods = new Set([
     'agent',
     'agent.identity.get',
@@ -431,17 +435,213 @@ export class OpenClawKit {
     starting;
     stopping = false;
     failures = 0;
+    browser;
+    browserHost;
+    brokers = new Map();
+    browserSafe = false;
+    browserAttaching = new Map();
+    browserPolicySessions = new Set();
+    browserProfiles = {};
+    browserCapabilities = new Set();
+    browserConfig() { return { profiles: this.browserProfiles, tools: this.toolNames() }; }
+    async launchBrowser(member) {
+        let owned;
+        const broker = await launchBroker({ executablePath: this.o.browser.executablePath,
+            profileDir: join(this.o.stateDir, 'browser', member, 'profile'), member,
+            onExit: () => {
+                if (!this.stopping && owned && this.browserHost?.brokerBinding(member)?.broker === owned)
+                    void this.browserHost.browserGone(member, owned).catch(() => { });
+            } });
+        owned = broker;
+        try {
+            const endpoint = broker.endpoint().cdpUrl, url = new URL(endpoint);
+            this.browserCapabilities.add(endpoint);
+            const token = url.searchParams.get('token');
+            if (!token)
+                throw new Error('browser capability unavailable');
+            this.browserCapabilities.add(token);
+            const id = url.pathname.split('/').at(-1);
+            if (id && /^[a-f0-9]{32}$/i.test(id))
+                this.browserCapabilities.add(id);
+            await broker.fence(true);
+            return broker;
+        }
+        catch (error) {
+            await broker.close();
+            throw error;
+        }
+    }
+    async prepareBrowsers() {
+        if (!this.o.browser || this.browserHost)
+            return;
+        await this.engine.prepare();
+        const c = JSON.parse(readFileSync(join(this.engine.root, 'openclaw.json'), 'utf8'));
+        if (browserToolPolicySafe(c, this.toolNames())) {
+            const members = this.o.browser.members === 'all' ? Object.keys(c.agents?.entries ?? { main: {} }) : this.o.browser.members;
+            for (const member of members)
+                if (this.browserMember(member) && !this.brokers.has(member)) {
+                    const broker = await this.launchBrowser(member);
+                    this.brokers.set(member, broker);
+                    this.browserProfiles[`byokit-${member}`] = { ...broker.endpoint(), attachOnly: true };
+                }
+        }
+        this.browserHost = await createBrowserHost({ brokers: this.brokers, store: fileSignInStore(this.o.stateDir),
+            options: this.o.browser, authorize: (grant, member) => !!grant && this.browserMember(member),
+            park: async (_member, key) => this.abort(key), resume: async () => 'unknown',
+            // Production cannot raise while unprotected. Never substitute a guessed registrable site.
+            siteOf: () => { throw new Error('browser sign-in handoff unavailable'); },
+            ping: (member, kind) => {
+                for (const fn of this.listeners)
+                    fn({ event: 'byokit.browser', payload: { member, kind } });
+                if (kind === 'state' && this.browserHost)
+                    void this.publishBrowserProfile(member).catch(() => { });
+            },
+            // Host recovery owns the registry transition. Never recursively attach or publish a still-unowned endpoint.
+            restart: member => this.launchBrowser(member),
+        });
+        const controller = this.browserHost;
+        this.browser = {
+            state: member => this.browserState(member), signIns: controller.signIns.bind(controller),
+            takeover: controller.takeover.bind(controller), confirmOrigin: controller.confirmOrigin.bind(controller),
+            done: controller.done.bind(controller), notNow: controller.notNow.bind(controller),
+            reopen: controller.reopen.bind(controller), retry: controller.retry.bind(controller),
+            cancel: controller.cancel.bind(controller),
+            thumbnail: (source, by) => this.browserSafe ? controller.thumbnail(source, by) : Promise.resolve({ state: 'off' }),
+            live: (source, options, on) => {
+                if (!this.browserSafe)
+                    throw new Error('browser tool policy refused');
+                return controller.live(source, options, on);
+            }, forget: controller.forget.bind(controller),
+            ...{ revokeGrant: controller.revokeGrant.bind(controller) },
+        };
+    }
+    async publishBrowserProfile(member) {
+        const binding = this.browserHost?.brokerBinding(member);
+        if (!binding)
+            return;
+        const { broker, generation, endpoint } = binding;
+        const name = `byokit-${member}`;
+        if (this.browserProfiles[name]?.cdpUrl === endpoint.cdpUrl)
+            return;
+        this.brokers.set(member, broker);
+        await broker.fence(true);
+        this.browserProfiles[name] = { ...endpoint, attachOnly: true };
+        try {
+            await this.patchConfig({});
+            const current = this.browserHost?.brokerBinding(member);
+            if (current?.broker !== broker || current.generation !== generation)
+                throw new Error('browser binding changed');
+            await this.checkBrowserTools(); // acknowledges the exact profile and rechecks policy/no-open request before unfencing
+        }
+        catch {
+            this.browserSafe = false;
+            await broker.fence(true);
+            throw new Error('browser endpoint unavailable');
+        }
+    }
+    browserMember(member) {
+        return MEMBER_ID.test(member) && !member.startsWith(KEY_PREFIX) && !!this.o.browser
+            && (this.o.browser.members === 'all' || this.o.browser.members.includes(member));
+    }
+    browserState(member) {
+        if (!this.browserSafe)
+            return { member, phase: 'blocked', why: 'unsafe-tools' };
+        return this.browserHost?.state(member) ?? { member, phase: 'off', why: 'no-browser' };
+    }
+    async checkBrowserTools() {
+        if (!this.o.browser)
+            return true;
+        this.browserSafe = false;
+        try {
+            const configPath = join(this.engine.root, 'openclaw.json');
+            const disk = readFileSync(configPath, 'utf8');
+            const snapshot = await this.request()('config.get');
+            const c = snapshot.config;
+            const owned = JSON.parse(disk);
+            if (!browserToolPolicySafe(c, this.toolNames()))
+                return false;
+            const roster = await this.request()('agents.list');
+            if (!Array.isArray(roster.agents) || !roster.agents.length)
+                return false;
+            const safe = new Set(['browser', 'request_sign_in', ...this.toolNames()]);
+            for (const { id } of roster.agents) {
+                if (!MEMBER_ID.test(id))
+                    return false;
+                const sessionKey = `agent:${id}:byokit-browser-policy`;
+                if (!this.browserPolicySessions.has(sessionKey)) {
+                    // The published tools.effective route requires an existing session. No message/task or model submission.
+                    await this.request()('sessions.create', { agentId: id, key: sessionKey, label: 'Browser tool policy' });
+                    this.browserPolicySessions.add(sessionKey);
+                }
+                const policy = await this.request()('tools.effective', { agentId: id, sessionKey });
+                if (policy.agentId !== id || !Array.isArray(policy.groups)
+                    || policy.groups.some(group => !Array.isArray(group.tools) || group.tools.some(tool => !safe.has(tool.id))))
+                    return false;
+            }
+            const stable = disk === readFileSync(configPath, 'utf8');
+            for (const [member, broker] of this.brokers) {
+                const binding = this.browserHost?.brokerBinding(member);
+                const profile = c.browser?.profiles?.[`byokit-${member}`];
+                if (!binding || binding.broker !== broker || !browserProfileAcknowledged(profile, owned.browser?.profiles?.[`byokit-${member}`], binding.endpoint.cdpUrl, snapshot, stable))
+                    return false;
+                if (!this.browserHost?.signIns(member).some(r => ['waiting', 'held', 'checking'].includes(r.state))) {
+                    await broker.fence(false);
+                    const current = this.browserHost?.brokerBinding(member);
+                    if (current?.broker !== broker || current.generation !== binding.generation)
+                        return false;
+                }
+            }
+            this.browserSafe = true;
+            return true;
+        }
+        catch {
+            return false;
+        }
+        finally {
+            if (!this.browserSafe)
+                for (const broker of this.brokers.values())
+                    await broker.fence(true);
+        }
+    }
+    async browserGate(run, tool) {
+        if (!this.o.browser)
+            return undefined;
+        const safe = await this.checkBrowserTools();
+        const allowed = new Set(['browser', 'request_sign_in', ...this.toolNames()]);
+        if (!safe || !allowed.has(tool))
+            return 'browser tool policy refused';
+        if ((tool === 'browser' || tool === 'request_sign_in') && !this.browserMember(run.member))
+            return 'browser member unavailable';
+        if ((tool === 'browser' || tool === 'request_sign_in') && this.browserHost?.signIns(run.member)
+            .some(r => ['waiting', 'held', 'checking'].includes(r.state)))
+            return 'Waiting for the person to sign in';
+        if (tool === 'request_sign_in')
+            return 'browser sign-in handoff unavailable';
+        return undefined;
+    }
     constructor(o) {
         if (o.tools?.length && !o.host)
             throw new Error('host required when tools are registered');
+        if (o.browser && o.gateBuiltins === false)
+            throw new Error('gate-off');
+        if (o.browser && (!o.browser.executablePath.startsWith('/') || (o.browser.members !== 'all'
+            && (!Array.isArray(o.browser.members) || o.browser.members.some(m => !MEMBER_ID.test(m) || m.startsWith(KEY_PREFIX))))))
+            throw new Error('invalid browser options');
         // 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')
+            if (!/^[a-z][a-z0-9_]*$/.test(t.name) || t.name === 'bash' || t.name === 'cron'
+                || (o.browser && ['browser', 'request_sign_in', 'exec', 'process', 'code_execution', 'terminal', 'read', 'write', 'edit', 'apply_patch', 'gateway'].includes(t.name)))
                 throw new Error(`invalid tool name: ${t.name}`);
         }
         this.o = o;
-        this.engine = new Engine({ ...o, pluginId: o.plugin?.id ?? 'byokit', tools: o.tools ?? [],
+        this.engine = new Engine({ ...o, pluginId: o.plugin?.id ?? 'byokit', tools: [...o.tools ?? [], ...(o.browser ? [{
+                        name: 'request_sign_in', description: 'Ask the person to sign in to the current browser site.',
+                        parameters: { type: 'object', additionalProperties: false, properties: {
+                                note: { type: 'string', maxLength: 140 }, targetId: { type: 'string' }
+                            } },
+                    }] : [])],
+            ...(o.browser ? { browserConfig: () => this.browserConfig() } : {}),
             gateBuiltins: o.gateBuiltins !== false, spawnEngine: o.spawnEngine !== false,
             onState: (s) => this.setState(s), onExit: () => this.closed('engine exited') });
         this.keys = createKeys({ root: this.engine.root,
@@ -453,14 +653,46 @@ export class OpenClawKit {
             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)),
+        const host = o.browser ? {
+            gate: async (run, tool, input, info) => {
+                const refusal = await this.browserGate(run, tool);
+                if (refusal)
+                    return { allow: false, reason: refusal };
+                const result = await o.host?.gate(run, tool, input, info) ?? { allow: false, reason: 'tool host unavailable' };
+                const changed = await this.browserGate(run, tool);
+                return changed ? { allow: false, reason: changed } : result;
+            },
+            call: async (run, tool, input, signal) => {
+                const refusal = await this.browserGate(run, tool);
+                if (refusal)
+                    throw new Error(refusal);
+                if (!o.host)
+                    throw new Error('tool host unavailable');
+                return o.host.call(run, tool, input, signal);
+            },
+        } : o.host;
+        this.bridge = new Bridge({ path: this.engine.bridgeSock, host, tools: new Set([...this.toolNames(), ...(o.browser ? ['request_sign_in'] : [])]),
+            ...(o.browser ? { browserCapabilities: () => [...this.browserCapabilities],
+                beforeAgentRun: async (key, runId) => {
+                    // No action-id submission proof or redispatch claim. Open and unproven resumes are always refused.
+                    if (!await this.checkBrowserTools() || !this.browserHost)
+                        return false;
+                    return browserSessionMayRun(this.browserHost.signIns(), key, this.bridge.isRegisteredRun(key, runId));
+                } } : {}),
             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); }
+    setState(s) {
+        this.current = { ...s, ...(this.engine.patchSet !== undefined ? { patchSet: this.engine.patchSet } : {}) };
+        this.o.onState?.(this.current);
+    }
     get state() { return this.current; }
-    prepare() { return this.engine.prepare(); }
+    async prepare() {
+        await this.engine.prepare();
+        if (this.engine.patchSet !== undefined)
+            this.setState(this.current);
+    }
     start() {
         if (this.current.phase === 'ready')
             return Promise.resolve();
@@ -476,6 +708,7 @@ export class OpenClawKit {
     async connect() {
         let transport;
         try {
+            await this.prepareBrowsers();
             const ctx = await this.engine.start();
             if (!ctx || this.stopping)
                 return;
@@ -504,18 +737,26 @@ export class OpenClawKit {
             this.off.push(transport.onEvent((e) => this.approvalsCtl.handleEvent(e)));
             this.failures = 0;
             this.setState({ phase: 'ready' });
+            if (this.o.browser)
+                await this.checkBrowserTools();
             // Replays the engine's native approval lists over the now-live transport (N9).
             await this.approvalsCtl.resync();
         }
         catch (error) {
             const needsUpdate = this.current.phase === 'needs-update';
+            const patchFailure = this.current.why === 'engine-patch';
             if (transport && this.transport === transport)
                 await this.disconnect();
             await this.engine.stop();
+            await this.closeBrowsers();
             if (error instanceof Error && 'code' in error && error.code === 'engine-already-running') {
                 this.setState({ phase: 'failed', why: 'engine-already-running' });
                 throw error;
             }
+            if (patchFailure) {
+                this.setState({ phase: 'failed', why: 'engine-patch' });
+                throw error;
+            }
             if (needsUpdate)
                 this.setState({ phase: 'needs-update', why: 'version' });
             if (!needsUpdate && !this.stopping)
@@ -529,6 +770,7 @@ export class OpenClawKit {
         this.transport = undefined;
         this.greeting = undefined;
         this.members = undefined;
+        this.browserPolicySessions.clear();
         this.bridge.stop();
         await transport?.stop();
     }
@@ -552,6 +794,20 @@ export class OpenClawKit {
         this.stopping = true;
         await this.disconnect();
         await this.engine.stop();
+        await this.closeBrowsers();
+    }
+    async closeBrowsers() {
+        if (this.browserHost)
+            await this.browserHost.close();
+        else
+            for (const broker of this.brokers.values())
+                await broker.close();
+        this.browserHost = undefined;
+        this.browser = undefined;
+        this.browserSafe = false;
+        this.brokers.clear();
+        for (const profile of Object.keys(this.browserProfiles))
+            delete this.browserProfiles[profile];
     }
     request() {
         if (!this.transport || this.current.phase !== 'ready')
@@ -559,6 +815,8 @@ export class OpenClawKit {
         return this.transport.request.bind(this.transport);
     }
     call(method, params, o) {
+        if (this.o.browser && /^(config\.(apply|patch|set)|agents\.(create|update|delete)|plugins\.(install|uninstall|setEnabled|refresh))$/.test(method))
+            return Promise.reject(new Error('browser policy changes require guarded patchConfig'));
         try {
             return this.request()(method, params, o);
         }
@@ -585,10 +843,28 @@ export class OpenClawKit {
         this.listeners.add(listener);
         return () => { this.listeners.delete(listener); };
     }
-    ensureMember(member) {
+    async ensureMember(member) {
         if (!this.members)
-            return Promise.reject(new Error('gateway not ready'));
-        return this.members.ensure(member);
+            throw new Error('gateway not ready');
+        const result = await this.members.ensure(member);
+        if (!this.o.browser || !this.browserMember(member) || this.brokers.has(member) || !this.browserHost)
+            return result;
+        let attaching = this.browserAttaching.get(member);
+        if (!attaching) {
+            attaching = (async () => {
+                if (!await this.checkBrowserTools())
+                    return;
+                const broker = await this.launchBrowser(member);
+                await this.browserHost.attachBroker(member, broker);
+                this.brokers.set(member, broker);
+                await broker.fence(true);
+                await this.publishBrowserProfile(member);
+            })();
+            this.browserAttaching.set(member, attaching);
+            void attaching.finally(() => { this.browserAttaching.delete(member); }).catch(() => { });
+        }
+        await attaching;
+        return result;
     }
     // sign-in (5.7): every body here is the module's, with this kit's transport, members and ports.
     signInCtx() {
@@ -634,7 +910,7 @@ export class OpenClawKit {
                 };
             },
             ensure: (member) => this.ensureMember(member),
-            bridge: this.bridge,
+            bridge: { register: (run, tools, runId) => this.bridge.register(run, tools && this.o.browser ? [...tools, 'request_sign_in'] : tools, runId) },
             tools: new Set(this.toolNames()),
         });
     }
@@ -642,7 +918,13 @@ export class OpenClawKit {
     toolNames() {
         return (this.o.tools ?? []).map((t) => t.name);
     }
-    run(spec, on) {
+    async run(spec, on) {
+        if (this.o.browser) {
+            if (!await this.checkBrowserTools())
+                return { ok: false, kind: 'other', message: 'browser tool policy refused' };
+            if (!await this.browserHost?.beforeRun(spec.member, this.runKey(spec.sessionKey, spec)))
+                return { ok: false, kind: 'other', message: 'Waiting for the person to sign in' };
+        }
         if (spec.auth !== undefined && spec.auth !== 'apiKey')
             return Promise.reject(new Error('Choose a supported account option.'));
         // Snapshot before account readiness awaits; invalid schemas never reach the Gateway.
@@ -703,12 +985,37 @@ export class OpenClawKit {
         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 });
+            installPolicy: this.o.installPolicy, ...(this.o.browser ? { browser: this.browserConfig() } : {}) });
+        if (this.o.browser && !browserToolPolicySafe(safe, this.toolNames()))
+            throw new Error('browser tool policy refused');
+        if (this.o.browser) {
+            this.browserSafe = false;
+            for (const broker of this.brokers.values())
+                await broker.fence(true);
+        }
         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);
     }
+    // One key, not the whole config: stock config.get redacts token-bearing values and needs a gateway round
+    // trip, so it can never hand back a value the app may write unchanged. These read and write that one
+    // dotted key in the file prepare() owns; the engine applies it at its next boot.
+    getConfigKey(key) {
+        const config = JSON.parse(readFileSync(join(this.engine.root, 'openclaw.json'), 'utf8'));
+        return readConfigKey(config, configKeyPath(key));
+    }
+    setConfigKey(key, value) {
+        const path = join(this.engine.root, 'openclaw.json');
+        const text = readFileSync(path, 'utf8');
+        const config = JSON.parse(text);
+        const previous = writeConfigKey(config, configKeyPath(key), value);
+        // prepare() writes exactly this shape, so an unchanged value leaves the file byte for byte alone.
+        const next = JSON.stringify(config, null, 2) + '\n';
+        if (next !== text)
+            atomic(path, next);
+        return previous;
+    }
     doctorContext() { return this.engine.doctorContext(); }
 }

package/dist/link.d.ts

@@ -1,24 +1,35 @@
+import type { BrowserHost } from './browser.ts';
 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: {
+/** `openclawLink`'s options: which member a grant acts for, the D8 pass-through predicate, sealed relay push. */
+export type OpenClawLinkOptions = {
     memberOf: (grant: Grant) => Member | undefined;
     passThrough?: (method: string, grant: Grant) => boolean;
     relay?: RelayClient;
-}): Pick<HostOptions, 'handle' | 'stream' | 'allow'> & {
+};
+/** What `openclawLink` hands the link host: its request/stream handlers plus the kit's push entry point. */
+export type OpenClawLinkHost = Pick<HostOptions, 'handle' | 'stream' | 'allow' | 'onGrantRemoved'> & {
     onAction(a: PushAction): Promise<unknown>;
 };
-export declare function serve(o: {
+export declare function openclawLink(kit: OpenClawKit & {
+    browser?: BrowserHost;
+}, o: OpenClawLinkOptions): OpenClawLinkHost;
+/** `serve`'s options: the link host to accept on, and the ingress to publish or replace. */
+export type OpenClawServeOptions = {
     host: Host;
     port: number;
     via?: Via;
     previous?: ServeIngress;
     http?: (req: IncomingMessage, res: ServerResponse) => void;
-}): Promise<{
+};
+/** The running ingress: its urls, the entry that reaches the engine, and an orderly close. */
+export type OpenClawServeHandle = {
     urls: string[];
     ingress?: ServeIngress;
     close(): Promise<void>;
-}>;
+};
+export declare function serve(o: OpenClawServeOptions): Promise<OpenClawServeHandle>;