@byokit/openclaw 0.5.0 → 0.6.1

package/dist/engine.js

@@ -1,14 +1,16 @@
 import { spawn, spawnSync } from 'node:child_process';
-import { randomBytes, generateKeyPairSync } from 'node:crypto';
+import { randomBytes, generateKeyPairSync, randomUUID } from 'node:crypto';
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, writeFileSync, copyFileSync, rmSync, realpathSync, statSync } 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 { AuthStore } from "./auth-store.js";
-import { EngineAlreadyRunningError, pidAlive } from "./engine-status.js";
+import { EngineAlreadyRunningError, pidAlive, StartedProcesses } from "./engine-status.js";
+import { EnginePatchError, atomic, prepareEngineSet, processStartTime, readPatchSet, verifyEngineSet } from "./engine-patches.js";
 import { ENGINE_VERSION } from "./constants.js";
-import { reconcileConfig } from "./config.js";
+import { appendUsageBoot } from "./usage-boots.js";
+import { reconcileConfig, appRecoveryPrefixes } from "./config.js";
 import { writePlugin, resolveBridge } from "./bridge.js";
 const kitDir = dirname(dirname(fileURLToPath(import.meta.url)));
 const putOnce = (path, data) => { if (!existsSync(path))
@@ -17,14 +19,6 @@ const putChanged = (path, data) => {
     if (!existsSync(path) || readFileSync(path, 'utf8') !== data)
         writeFileSync(path, data, { mode: 0o600 });
 };
-function processStartTime(pid) {
-    const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
-    // comm can contain spaces and parentheses; field 22 is index 19 after its final ')'.
-    const startTime = stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19];
-    if (!startTime || !/^\d+$/.test(startTime))
-        throw new Error('unverifiable engine start time');
-    return startTime;
-}
 const supports = (list, value) => !list ||
     (!list.includes(`!${value}`) && (list.includes('any') || list.every(item => item.startsWith('!')) || list.includes(value)));
 function installMatches(dir) {
@@ -57,18 +51,24 @@ export class Engine {
     root;
     bridgeSock;
     dir;
+    setDir;
+    wantedSet;
     child;
+    started = new StartedProcesses();
     starting;
     authStore;
     stopping = false;
     credentialsLocked = false;
     repaired = false;
     prepared;
+    patchSet;
     port = 0;
     token = '';
     o;
     paramPrefix;
+    appOwnedSessionPrefixes;
     constructor(o) {
+        this.appOwnedSessionPrefixes = appRecoveryPrefixes(o.appOwnedSessions);
         this.o = o;
         const bridge = resolveBridge(o.bridge);
         this.root = join(o.stateDir, 'openclaw');
@@ -77,8 +77,12 @@ export class Engine {
         this.paramPrefix = bridge.paramPrefix;
         this.authStore = new AuthStore({ root: this.root, stateDir: o.stateDir, engineDir: this.dir, seal: o.authSeal, log: o.log });
     }
-    state(phase, why, retryAt) { this.o.onState({ phase, ...(why ? { why } : {}), ...(retryAt ? { retryAt } : {}) }); }
-    get entry() { return join(this.dir, 'node_modules', 'openclaw', 'openclaw.mjs'); }
+    state(phase, why, retryAt) { this.o.onState({ phase, ...(why ? { why } : {}), ...(retryAt ? { retryAt } : {}), ...(this.patchSet !== undefined ? { patchSet: this.patchSet } : {}) }); }
+    get entry() {
+        if (this.o.spawnEngine && !this.setDir)
+            throw new EnginePatchError('spec', 'engine-set');
+        return join(this.setDir ?? this.dir, 'node_modules', 'openclaw', 'openclaw.mjs');
+    }
     async freePort() {
         const server = createServer();
         return new Promise((resolve, reject) => {
@@ -93,7 +97,13 @@ export class Engine {
     prepare() {
         if (this.prepared)
             return this.prepared;
-        const pending = this.prepareOnce();
+        const pending = this.prepareOnce().catch(error => {
+            if (error instanceof EnginePatchError) {
+                this.patchSet = null;
+                this.state('failed', 'engine-patch');
+            }
+            throw error;
+        });
         this.prepared = pending;
         void pending.finally(() => { if (this.prepared === pending)
             this.prepared = undefined; }).catch(() => { });
@@ -103,7 +113,7 @@ export class Engine {
         if (!this.o.authSeal && existsSync(join(this.root, 'auth-store.sealed')))
             throw new Error('authSeal required for sealed credential store');
         await this.recoverOrphan();
-        for (const d of [this.root, ...(!this.o.authSeal ? [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])
+        for (const d of [this.root, ...(!this.o.authSeal ? [join(this.root, 'home'), join(this.root, 'state')] : []), join(this.root, 'tmp'), join(this.root, 'usage'), join(this.root, 'install-home'), join(this.root, 'npm-cache'), join(this.o.stateDir, 'logs')])
             mkdirSync(d, { recursive: true, mode: 0o700 });
         try {
             await this.authStore.prepare();
@@ -115,25 +125,38 @@ export class Engine {
             throw error;
         }
         if (this.o.spawnEngine) {
-            const versionPath = join(this.dir, 'node_modules', 'openclaw', 'package.json');
-            if (!existsSync(this.entry) || !installMatches(this.dir)) {
+            const lock = JSON.parse(readFileSync(join(kitDir, 'engine/package-lock.json'), 'utf8'));
+            const patches = readPatchSet(join(kitDir, 'engine/patches.json'), ENGINE_VERSION, lock.packages['node_modules/openclaw'].integrity);
+            const install = async (dir) => {
                 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,
+                    copyFileSync(join(kitDir, 'engine', f), join(dir, f));
+                await new Promise((resolve, reject) => {
+                    const child = spawn(this.o.npmPath ?? 'npm', ['ci', '--ignore-scripts', '--no-audit', '--no-fund', '--prefix', 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' },
+                        stdio: ['ignore', 'ignore', 'pipe'],
+                    });
+                    let stderr = '', expired = false;
+                    this.started.add(child);
+                    child.stderr.on('data', chunk => { stderr = (stderr + chunk).slice(-500); });
+                    const timer = setTimeout(() => { expired = true; child.kill('SIGKILL'); }, 300_000);
+                    child.once('error', error => { clearTimeout(timer); this.started.forget(child); reject(error); });
+                    child.once('exit', code => {
+                        clearTimeout(timer);
+                        this.started.forget(child);
+                        if (code === 0 && !expired)
+                            resolve();
+                        else {
+                            this.state('failed', 'install');
+                            reject(new Error(`engine install: ${expired ? 'timeout' : stderr}`));
+                        }
+                    });
                 });
-                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');
-            }
+            };
+            this.setDir = await prepareEngineSet(this.dir, patches, install, installMatches);
+            this.wantedSet = patches;
+            atomic(join(this.root, 'engine-set'), this.setDir);
+            this.patchSet = patches.id;
         }
         const tokenFile = join(this.root, 'token');
         putOnce(tokenFile, randomBytes(32).toString('hex'));
@@ -148,17 +171,18 @@ export class Engine {
         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', 'keys.js']) {
+        for (const f of ['package.json', 'index.js', 'keys.js', 'usage.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 });
+            gateBuiltins: this.o.gateBuiltins !== false, browser: !!this.o.browserConfig });
         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 });
+            pluginDir, policyPath: join(kitDir, 'policy', 'policy.mjs'), app: this.o.config, installPolicy: this.o.installPolicy,
+            browser: this.o.browserConfig?.() });
         putChanged(path, JSON.stringify(config, null, 2) + '\n');
     }
     doctorContext() {
@@ -171,11 +195,16 @@ export class Engine {
                 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,
+                BYOKIT_APP_OWNED_SESSION_PREFIXES: JSON.stringify(this.appOwnedSessionPrefixes),
             } };
     }
     doctor(timeoutMs) {
         const { entry, env } = this.doctorContext();
+        if (this.o.spawnEngine)
+            verifyEngineSet(this.setDir, this.wantedSet, installMatches);
         const result = spawnSync(process.execPath, [entry, 'doctor', '--fix', '--yes', '--non-interactive'], { cwd: env.HOME, env, timeout: timeoutMs, stdio: 'pipe' });
+        if (this.o.spawnEngine)
+            verifyEngineSet(this.setDir, this.wantedSet, installMatches);
         return { status: result.status };
     }
     verifiedOrphan(pid) {
@@ -286,17 +315,49 @@ export class Engine {
             return { port: this.port, token: this.token, identityPath };
         if (this.child && this.child.exitCode === null)
             return { port: this.port, token: this.token, identityPath };
+        try {
+            verifyEngineSet(this.setDir, this.wantedSet, installMatches);
+        }
+        catch (error) {
+            this.patchSet = null;
+            this.state('failed', 'engine-patch');
+            throw error;
+        }
         this.state('starting');
         const { entry, env } = this.doctorContext();
         const fd = openSync(join(this.o.stateDir, 'logs', 'openclaw.log'), 'a', 0o600);
+        const usageDir = join(this.root, 'usage'), bootId = randomUUID();
         try {
-            this.child = spawn(process.execPath, [entry, 'gateway', '--port', String(this.port)], { cwd: env.HOME, env, detached: true, stdio: ['ignore', fd, fd] });
+            const accounted = this.wantedSet.files.some(file => file.path === 'dist/experience-review-default-6DPIIJds.js');
+            if (accounted) {
+                appendUsageBoot(usageDir, { bootId, startedAt: Date.now() });
+                env.BYOKIT_ENGINE_USAGE_LEDGER = usageDir;
+                env.BYOKIT_ENGINE_BOOT = bootId;
+            }
+            // Detached keeps the engine out of the host's session; stop() still signals its pid alone, never its group.
+            try {
+                this.child = spawn(process.execPath, [entry, 'gateway', '--port', String(this.port)], { cwd: env.HOME, env, detached: true, stdio: ['ignore', fd, fd] });
+            }
+            catch (error) {
+                if (env.BYOKIT_ENGINE_BOOT)
+                    appendUsageBoot(usageDir, { bootId, failedAt: Date.now(), spawned: false });
+                throw error;
+            }
         }
         finally {
             closeSync(fd);
         }
         const child = this.child;
+        this.started.add(child);
         child.on('error', () => {
+            this.started.forget(child);
+            // Only absence of a pid proves no engine could have attempted a ledger write.
+            if (!child.pid && env.BYOKIT_ENGINE_BOOT) {
+                try {
+                    appendUsageBoot(usageDir, { bootId, failedAt: Date.now(), spawned: false });
+                }
+                catch { /* unclosed boot remains incomplete */ }
+            }
             if (this.child !== child || this.stopping)
                 return;
             this.child = undefined;
@@ -307,10 +368,11 @@ export class Engine {
             throw new Error('engine spawn failed');
         }
         if (process.platform === 'linux') {
-            writeFileSync(join(this.root, 'gateway.identity'), JSON.stringify({ pid: child.pid, startTime: processStartTime(child.pid) }), { mode: 0o600 });
+            writeFileSync(join(this.root, 'gateway.identity'), JSON.stringify({ pid: child.pid, startTime: processStartTime(child.pid), ...(env.BYOKIT_ENGINE_BOOT ? { bootId } : {}) }), { mode: 0o600 });
         }
         writeFileSync(join(this.root, 'gateway.pid'), String(child.pid), { mode: 0o600 });
         child.once('exit', (code) => {
+            this.started.forget(child);
             if (this.child !== child || this.stopping)
                 return;
             this.child = undefined;
@@ -346,22 +408,7 @@ export class Engine {
         this.stopping = true;
         await this.starting?.catch(() => { });
         const child = this.child;
-        if (child?.pid && child.exitCode === null) {
-            try {
-                process.kill(-child.pid, 'SIGTERM');
-            }
-            catch { /* already gone */ }
-            for (let i = 0; i < 15 && child.exitCode === null && child.signalCode === null; i++)
-                await delay(200);
-            if (child.exitCode === null && child.signalCode === null) {
-                try {
-                    process.kill(-child.pid, 'SIGKILL');
-                }
-                catch { /* already gone */ }
-            }
-            for (let i = 0; i < 15 && child.exitCode === null && child.signalCode === null; i++)
-                await delay(200);
-        }
+        await this.started.terminate(delay);
         if (child && child.exitCode === null && child.signalCode === null)
             throw new Error('engine did not stop; credential store still in use');
         this.child = undefined;

package/dist/index.d.ts

@@ -1,6 +1,11 @@
 export { ENGINE_VERSION, OPERATOR_SCOPES, PROTOCOL_VERSION } from './constants.ts';
-export type { Approval, CallOptions, Decision, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, GateResult, Hello, KitState, Member, PlanWindow, Route, RunEnd, RunEvent, RunRef, RunSpec, OutputSchema, SchemaOutput, RunUsage, SignInOptions, SignInView, ToolHost, ToolSpec, } from './types.ts';
+export type { Approval, CallOptions, Decision, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, GateResult, Hello, KitState, KitEventName, KitEventPayload, BrowserPing, Member, PlanWindow, Route, RunEnd, RunEvent, RunRef, RunSpec, OutputSchema, SchemaOutput, RunUsage, SignInOptions, SignInView, ToolHost, ToolSpec, } from './types.ts';
 export { OpenClawKit, type KitOptions, type RetainedLogin } from './kit.ts';
 export type { AddKeyResult } from './keys.ts';
 export { stateWords, toAccountView, words, type AccountView, type WordKey } from './words.ts';
 export { EngineAlreadyRunningError } from './engine-status.ts';
+export { readAgentDayUsage } from './day-usage.ts';
+export type { AgentDayUsage, EngineStartedCharge, EngineStartedKind } from './day-usage.ts';
+export { readAgentUsage, agentUsageOf } from './usage.ts';
+export type { AgentUsageReading, LedgerUsageTotals, UsageCache, UsageWindow } from './usage.ts';
+export type { LiveSource, BrowserState, SignInMethodHint, SignInReason, SignInChoice, SettledState, SettledReason, ResumeState, NeedSignIn, TakeoverLease, LiveViewState, LiveFrame, LiveInput, ThumbnailResult, SignInRefusedWhy, BrowserOptions, SiteVerifier, BrowserHost, BrowserDevice } from './browser.ts';

package/dist/index.js

@@ -4,3 +4,5 @@ export { ENGINE_VERSION, OPERATOR_SCOPES, PROTOCOL_VERSION } from "./constants.j
 export { OpenClawKit } from "./kit.js";
 export { stateWords, toAccountView, words } from "./words.js";
 export { EngineAlreadyRunningError } from "./engine-status.js";
+export { readAgentDayUsage } from "./day-usage.js";
+export { readAgentUsage, agentUsageOf } from "./usage.js";

package/dist/kit.d.ts

@@ -1,6 +1,8 @@
 import type { SealingAdapter } from '@byokit/secrets';
 import { type AddKeyResult } from './keys.ts';
-import type { Approval, CallOptions, Decision, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, Hello, KitState, Member, Route, RunEnd, RunEvent, RunSpec, OutputSchema, SchemaOutput, SignInOptions, SignInView, ToolHost, ToolSpec } from './types.ts';
+import { type RouteView } from './routes.ts';
+import type { BrowserHost, BrowserOptions } from './browser.ts';
+import type { Approval, CallOptions, Decision, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, Hello, KitState, KitEventName, KitEventPayload, Member, RunEnd, RunEvent, RunSpec, OutputSchema, SchemaOutput, SignInOptions, SignInView, ToolHost, ToolSpec } from './types.ts';
 export type KitOptions = {
     stateDir: string;
     authSeal?: SealingAdapter;
@@ -19,6 +21,10 @@ export type KitOptions = {
     permitted?: (tool: string) => boolean;
     gateBuiltins?: boolean;
     config?: object;
+    appOwnedSessions?: {
+        keyPrefixes: string[];
+    };
+    browser?: BrowserOptions;
     installPolicy?: {
         trustedSkills: string;
         ownRoots: string[];
@@ -52,9 +58,26 @@ export declare class OpenClawKit {
     private readonly approvalsCtl;
     private listeners;
     private off;
+    private signInDisconnects;
     private starting?;
     private stopping;
     private failures;
+    browser?: BrowserHost;
+    private browserHost?;
+    private readonly brokers;
+    private browserSafe;
+    private readonly browserAttaching;
+    private readonly browserPolicySessions;
+    private readonly browserProfiles;
+    private readonly browserCapabilities;
+    private browserConfig;
+    private launchBrowser;
+    private prepareBrowsers;
+    private publishBrowserProfile;
+    private browserMember;
+    private browserState;
+    private checkBrowserTools;
+    private browserGate;
     constructor(o: KitOptions);
     private setState;
     get state(): KitState;
@@ -64,17 +87,18 @@ export declare class OpenClawKit {
     private disconnect;
     private closed;
     stop(): Promise<void>;
+    private closeBrowsers;
     private request;
     call<M extends GatewayMethod>(method: M, params: GatewayParams<M>, o?: CallOptions): Promise<GatewayResult<M>>;
     callDynamic(method: string, params?: unknown, o?: CallOptions): Promise<unknown>;
     get hello(): Hello | undefined;
-    onEvent<E extends GatewayEventName>(event: E | '*', fn: (payload: GatewayEventPayload<E>, event: E) => void): () => void;
+    onEvent<E extends KitEventName>(event: E | '*', fn: (payload: KitEventPayload<E>, event: E) => void): () => void;
     ensureMember(member: Member): Promise<{
         agentId: string;
         workspace: string;
     }>;
     private signInCtx;
-    routes(): Route[];
+    routes(): RouteView[];
     providers(member: Member): Promise<string[]>;
     signedIn(member: Member, provider: string): Promise<boolean>;
     signIn(member: Member, o: SignInOptions, on: (v: SignInView) => void): {
@@ -114,6 +138,8 @@ export declare class OpenClawKit {
         agentId?: string;
     }): Promise<void>;
     memoryLimited(member: Member): boolean;
+    getConfigKey(key: string): unknown;
+    setConfigKey(key: string, value: unknown): unknown;
     doctorContext(): {
         entry: string;
         env: Record<string, string>;