@byokit/openclaw 0.5.0 → 0.6.1

package/dist/engine-patches.d.ts

@@ -0,0 +1,36 @@
+export type PatchFile = {
+    path: string;
+    before: string;
+    after: string;
+    edits: {
+        find: string;
+        replace: string;
+    }[];
+};
+export type PatchSet = {
+    v: 1;
+    id: string;
+    upstream: {
+        name: string;
+        version: string;
+        integrity: string;
+        commit: string;
+        license: string;
+    };
+    files: PatchFile[];
+};
+export declare class EnginePatchError extends Error {
+    readonly code = "engine-patch";
+    readonly cause: 'spec' | 'drift' | 'drift-after-build' | 'write';
+    readonly file?: string;
+    constructor(cause: EnginePatchError['cause'], file?: string);
+}
+export declare const sha256: (text: string | Buffer) => string;
+export declare const patchId: (files: PatchFile[]) => string;
+export declare function readPatchSet(path: string, version: string, integrity: string): PatchSet;
+export declare function editText(text: string, file: PatchFile): string;
+export declare function atomic(path: string, text: string): void;
+export declare function processStartTime(pid: number): string;
+export declare function verifyEngineSet(dir: string, set: PatchSet, installMatches: (dir: string) => boolean): void;
+export declare function engineSetName(set: PatchSet): string;
+export declare function prepareEngineSet(engineDir: string, set: PatchSet, install: (dir: string) => void | Promise<void>, installMatches: (dir: string) => boolean): Promise<string>;

package/dist/engine-patches.js

@@ -0,0 +1,320 @@
+// Internal artifact seam. Published patch semantics live only in engine/patches.json.
+import { createHash, randomUUID } from 'node:crypto';
+import { closeSync, constants, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { chmod, cp, open, readdir, rm } from 'node:fs/promises';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+export class EnginePatchError extends Error {
+    code = 'engine-patch';
+    cause;
+    file;
+    constructor(cause, file) {
+        super(`engine-patch: ${cause}${file ? ` (${file})` : ''}`);
+        this.name = 'EnginePatchError';
+        this.cause = cause;
+        this.file = file;
+    }
+}
+export const sha256 = (text) => createHash('sha256').update(text).digest('hex');
+function canonical(value) {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (value && typeof value === 'object')
+        return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, item]) => [key, canonical(item)]));
+    return value;
+}
+export const patchId = (files) => sha256(JSON.stringify(canonical(files))).slice(0, 16);
+const object = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const keys = (v, expected) => Object.keys(v).sort().join(',') === expected.sort().join(',');
+function validateFiles(id, files) {
+    if (typeof id !== 'string' || !Array.isArray(files))
+        throw new EnginePatchError('spec');
+    const paths = new Set();
+    for (const f of files) {
+        if (!object(f) || !keys(f, ['path', 'before', 'after', 'edits']) || typeof f.path !== 'string' ||
+            !/^dist\/(?:[A-Za-z0-9_-]+\/)*[A-Za-z0-9_.-]+\.m?js$/.test(f.path) || f.path.split('/').some(p => p === '.' || p === '..') || paths.has(f.path) ||
+            typeof f.before !== 'string' || !/^[a-f0-9]{64}$/.test(f.before) || typeof f.after !== 'string' || !/^[a-f0-9]{64}$/.test(f.after) || f.before === f.after ||
+            !Array.isArray(f.edits) || !f.edits.length)
+            throw new EnginePatchError('spec');
+        paths.add(f.path);
+        for (const e of f.edits)
+            if (!object(e) || !keys(e, ['find', 'replace']) || typeof e.find !== 'string' || !e.find || typeof e.replace !== 'string' || !e.replace || e.find === e.replace)
+                throw new EnginePatchError('spec');
+    }
+    if (id !== patchId(files))
+        throw new EnginePatchError('spec');
+}
+export function readPatchSet(path, version, integrity) {
+    try {
+        const value = JSON.parse(readFileSync(path, 'utf8'));
+        if (!object(value) || !keys(value, ['v', 'id', 'upstream', 'files']) || value.v !== 1 || !object(value.upstream) ||
+            !keys(value.upstream, ['name', 'version', 'integrity', 'commit', 'license']) || value.upstream.name !== 'openclaw' || value.upstream.version !== version ||
+            value.upstream.integrity !== integrity || value.upstream.license !== 'MIT' || typeof value.upstream.commit !== 'string' || !/^[a-f0-9]{40}$/.test(value.upstream.commit))
+            throw new Error();
+        validateFiles(value.id, value.files);
+        return value;
+    }
+    catch {
+        throw new EnginePatchError('spec', path);
+    }
+}
+export function editText(text, file) {
+    for (const edit of file.edits) {
+        const at = text.indexOf(edit.find);
+        if (at < 0 || text.indexOf(edit.find, at + 1) >= 0)
+            throw new EnginePatchError('spec', file.path);
+        text = text.slice(0, at) + edit.replace + text.slice(at + edit.find.length);
+    }
+    return text;
+}
+export function atomic(path, text) {
+    const temp = `${path}.${randomUUID()}.tmp`;
+    let fd;
+    try {
+        fd = openSync(temp, 'wx', 0o600);
+        writeFileSync(fd, text);
+        fsyncSync(fd);
+        closeSync(fd);
+        fd = undefined;
+        renameSync(temp, path);
+        syncDir(dirname(path));
+    }
+    catch {
+        throw new EnginePatchError('write', path);
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+        rmSync(temp, { force: true });
+    }
+}
+const syncDir = (path) => { const fd = openSync(path, 'r'); try {
+    fsyncSync(fd);
+}
+finally {
+    closeSync(fd);
+} };
+export function processStartTime(pid) {
+    const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+    const startTime = stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19];
+    if (!startTime || !/^\d+$/.test(startTime))
+        throw new EnginePatchError('write');
+    return startTime;
+}
+const noLink = (path) => { if (lstatSync(path, { throwIfNoEntry: false })?.isSymbolicLink())
+    throw new EnginePatchError('spec', path); };
+const inside = (root, path) => { const rel = relative(root, path); return rel !== '..' && !rel.startsWith(`..${sep}`) && !rel.startsWith(sep); };
+function tree(dir) {
+    const result = [];
+    const root = realpathSync(dir);
+    const walk = (path, rel) => {
+        const info = lstatSync(path);
+        if (info.isSymbolicLink()) {
+            const link = readlinkSync(path);
+            if (resolve(link) === link || !inside(root, realpathSync(path)))
+                throw new EnginePatchError('spec', rel);
+            result.push({ path: rel, kind: 'link', mode: info.mode & 0o777, size: info.size, hash: sha256(link) });
+            return;
+        }
+        if (info.isDirectory()) {
+            for (const name of readdirSync(path).sort()) {
+                if (!rel && ['.byokit-tree', '.byokit-patches'].includes(name))
+                    continue;
+                walk(join(path, name), rel ? `${rel}/${name}` : name);
+            }
+            result.push({ path: rel, kind: 'dir', mode: info.mode & 0o777, size: 0, hash: '' });
+            return;
+        }
+        if (!info.isFile())
+            throw new EnginePatchError('spec', rel);
+        const hash = sha256(readFileSync(path));
+        result.push({ path: rel, kind: 'file', mode: info.mode & 0o777, size: info.size, hash });
+    };
+    walk(dir, '');
+    return result.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+}
+function metadata(dir, set) {
+    const root = join(dir, 'node_modules/openclaw');
+    const build = JSON.parse(readFileSync(join(root, 'dist/build-info.json'), 'utf8'));
+    if (build.version !== set.upstream.version || build.commit !== set.upstream.commit || JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).version !== set.upstream.version)
+        throw new EnginePatchError('drift', 'dist/build-info.json');
+    for (const file of set.files) {
+        const path = join(root, file.path);
+        if (!inside(realpathSync(root), realpathSync(path)) || lstatSync(path).isSymbolicLink() || sha256(readFileSync(path)) !== file.after)
+            throw new EnginePatchError('drift', file.path);
+    }
+}
+// Full verification on EVERY prepare/adoption, not just listed patched files or the directory mode.
+export function verifyEngineSet(dir, set, installMatches) {
+    noLink(dir);
+    try {
+        for (const name of ['.byokit-tree', '.byokit-patches']) {
+            const info = lstatSync(join(dir, name));
+            if (!info.isFile() || (info.mode & 0o777) !== 0o444)
+                throw new Error();
+        }
+        const bytes = readFileSync(join(dir, '.byokit-tree'), 'utf8');
+        const marker = JSON.parse(readFileSync(join(dir, '.byokit-patches'), 'utf8'));
+        if (!object(marker) || !keys(marker, ['id', 'files', 'tree']) || marker.id !== set.id || JSON.stringify(marker.files) !== JSON.stringify(set.files) || marker.tree !== sha256(bytes))
+            throw new Error();
+        metadata(dir, set);
+        if (!installMatches(dir) || bytes !== JSON.stringify(tree(dir)))
+            throw new Error();
+    }
+    catch (error) {
+        if (error instanceof EnginePatchError && error.cause === 'spec')
+            throw error;
+        throw new EnginePatchError('drift', dir);
+    }
+}
+// chmod/remove only this invocation's unlaunched private temp, never a final set or the base install.
+async function removeTemp(dir) {
+    if (!existsSync(dir))
+        return;
+    const walk = async (path) => {
+        if (!lstatSync(path).isDirectory())
+            return;
+        await chmod(path, 0o700);
+        for (const name of await readdir(path))
+            await walk(join(path, name));
+    };
+    await walk(dir);
+    await rm(dir, { recursive: true, force: true });
+}
+async function freeze(dir) {
+    const entries = tree(dir);
+    // Bound descriptors/I/O while yielding the host event loop. Every regular file and directory is fsynced.
+    const paths = [...entries.filter(e => e.kind === 'file'), ...entries.filter(e => e.kind === 'dir').reverse()];
+    for (let i = 0; i < paths.length; i += 16)
+        await Promise.all(paths.slice(i, i + 16).map(async (entry) => {
+            const path = join(dir, entry.path);
+            await chmod(path, entry.kind === 'dir' ? 0o555 : 0o444);
+            const fd = await open(path, 'r');
+            try {
+                await fd.sync();
+            }
+            finally {
+                await fd.close();
+            }
+        }));
+}
+export function engineSetName(set) { return `${sha256(set.upstream.integrity).slice(0, 16)}-${set.id}`; }
+export async function prepareEngineSet(engineDir, set, install, installMatches) {
+    validateFiles(set.id, set.files);
+    const sets = `${engineDir}.sets`;
+    noLink(sets);
+    mkdirSync(sets, { recursive: true, mode: 0o700 });
+    const name = engineSetName(set);
+    for (const candidate of readdirSync(sets).filter(n => n === name || n.startsWith(`${name}.`)).sort()) {
+        const dir = join(sets, candidate);
+        try {
+            verifyEngineSet(dir, set, installMatches);
+            return dir;
+        }
+        catch (error) {
+            if (!(error instanceof EnginePatchError) || error.cause !== 'drift')
+                throw error;
+        }
+    }
+    const stock = { ...set, id: patchId([]), files: [] };
+    const stockDir = set.files.length ? await prepareEngineSet(engineDir, stock, install, installMatches) : undefined;
+    const tmp = join(sets, `.tmp-${process.pid}-${process.platform === 'linux' ? processStartTime(process.pid) : 'unknown'}-${randomUUID()}`);
+    const final = join(sets, existsSync(join(sets, name)) ? `${name}.${randomUUID()}` : name);
+    try {
+        if (stockDir) {
+            // ponytail: reflink or plain copy, never hardlinks; no GC without per-launch leases (~889 MB/set).
+            await cp(stockDir, tmp, { recursive: true, verbatimSymlinks: true, mode: constants.COPYFILE_FICLONE });
+            // The copy is private and unlaunched. Make only it writable, and drop inherited provenance.
+            const writable = async (path) => {
+                const info = lstatSync(path);
+                if (info.isSymbolicLink())
+                    return;
+                await chmod(path, info.isDirectory() ? 0o700 : 0o600);
+                if (info.isDirectory())
+                    for (const name of await readdir(path))
+                        await writable(join(path, name));
+            };
+            await writable(tmp);
+            rmSync(join(tmp, '.byokit-tree'));
+            rmSync(join(tmp, '.byokit-patches'));
+        }
+        else {
+            mkdirSync(tmp, { mode: 0o700 });
+            await install(tmp);
+        }
+        if (!installMatches(tmp))
+            throw new EnginePatchError('drift-after-build', tmp);
+        const root = join(tmp, 'node_modules/openclaw');
+        for (const file of set.files) {
+            const path = join(root, file.path);
+            if (!inside(realpathSync(root), realpathSync(path)) || lstatSync(path).isSymbolicLink())
+                throw new EnginePatchError('spec', file.path);
+            const before = readFileSync(path, 'utf8');
+            if (sha256(before) !== file.before)
+                throw new EnginePatchError('drift-after-build', file.path);
+            const after = editText(before, file);
+            if (sha256(after) !== file.after)
+                throw new EnginePatchError('spec', file.path);
+            atomic(path, after);
+        }
+        metadata(tmp, set);
+        await freeze(tmp);
+        const bytes = JSON.stringify(tree(tmp));
+        // Root alone is writable while publishing metadata, then made read-only too.
+        await chmod(tmp, 0o700);
+        atomic(join(tmp, '.byokit-tree'), bytes);
+        atomic(join(tmp, '.byokit-patches'), JSON.stringify({ id: set.id, files: set.files, tree: sha256(bytes) }));
+        for (const file of ['.byokit-tree', '.byokit-patches']) {
+            const path = join(tmp, file);
+            await chmod(path, 0o444);
+            const fd = await open(path, 'r');
+            try {
+                await fd.sync();
+            }
+            finally {
+                await fd.close();
+            }
+        }
+        await chmod(tmp, 0o555);
+        const directory = await open(tmp, 'r');
+        try {
+            await directory.sync();
+        }
+        finally {
+            await directory.close();
+        }
+        try {
+            verifyEngineSet(tmp, set, installMatches);
+        }
+        catch (error) {
+            if (error instanceof EnginePatchError && error.cause === 'drift')
+                throw new EnginePatchError('drift-after-build', error.file);
+            throw error;
+        }
+        try {
+            renameSync(tmp, final);
+            syncDir(sets);
+        }
+        catch (error) {
+            if (!['ENOTEMPTY', 'EEXIST', 'EPERM'].includes(error.code ?? ''))
+                throw error;
+            try {
+                verifyEngineSet(final, set, installMatches);
+            }
+            catch {
+                throw new EnginePatchError('drift-after-build', final);
+            }
+        }
+        return final;
+    }
+    catch (error) {
+        if (error instanceof EnginePatchError) {
+            if (error.cause === 'drift')
+                throw new EnginePatchError('drift-after-build', error.file);
+            throw error;
+        }
+        throw new EnginePatchError('write', tmp);
+    }
+    finally {
+        await removeTemp(tmp);
+    }
+}

package/dist/engine-status.d.ts

@@ -1,3 +1,16 @@
+import type { ChildProcess } from 'node:child_process';
+/** Every process the kit itself spawned, held for shutdown by pid. */
+export declare class StartedProcesses {
+    private readonly started;
+    /** Record a spawn. Its pid is the kit's to signal; nothing else about it is. */
+    add(child: ChildProcess): void;
+    forget(child: ChildProcess | undefined): void;
+    /** SIGTERM each recorded pid, wait, SIGKILL the ones still running, wait. Never signals a process group. */
+    terminate(wait: (ms: number) => Promise<void>, graceMs?: number): Promise<void>;
+    private live;
+    private signal;
+    private settle;
+}
 /** A live or unverifiable writer still owns the isolated engine state. Retry after it stops. */
 export declare class EngineAlreadyRunningError extends Error {
     readonly code = "engine-already-running";

package/dist/engine-status.js

@@ -1,4 +1,35 @@
 import { readFileSync } from 'node:fs';
+/** Every process the kit itself spawned, held for shutdown by pid. */
+export class StartedProcesses {
+    started = new Set();
+    /** Record a spawn. Its pid is the kit's to signal; nothing else about it is. */
+    add(child) { this.started.add(child); }
+    forget(child) { if (child)
+        this.started.delete(child); }
+    /** SIGTERM each recorded pid, wait, SIGKILL the ones still running, wait. Never signals a process group. */
+    async terminate(wait, graceMs = 3000) {
+        for (const child of this.live())
+            this.signal(child, 'SIGTERM');
+        await this.settle(wait, graceMs);
+        for (const child of this.live())
+            this.signal(child, 'SIGKILL');
+        await this.settle(wait, graceMs);
+    }
+    live() { return [...this.started].filter(child => child.exitCode === null && child.signalCode === null); }
+    signal(child, sig) {
+        const { pid } = child;
+        if (pid === undefined)
+            return;
+        try {
+            process.kill(pid, sig);
+        }
+        catch { /* already gone */ }
+    }
+    async settle(wait, graceMs) {
+        for (let waited = 200; waited <= graceMs && this.live().length; waited += 200)
+            await wait(200);
+    }
+}
 /** A live or unverifiable writer still owns the isolated engine state. Retry after it stops. */
 export class EngineAlreadyRunningError extends Error {
     code = 'engine-already-running';

package/dist/engine.d.ts

@@ -1,10 +1,17 @@
 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' | 'authSeal'> & {
+export type EngineOptions = Pick<KitOptions, 'stateDir' | 'engineDir' | 'npmPath' | 'enginePath' | 'config' | 'appOwnedSessions' | 'installPolicy' | 'log' | 'bridge' | 'authSeal'> & {
     pluginId: string;
     tools: ToolSpec[];
     gateBuiltins?: boolean;
     spawnEngine: boolean;
+    browserConfig?: () => {
+        profiles: Record<string, {
+            cdpUrl: string;
+            attachOnly: true;
+        }>;
+        tools: string[];
+    };
     onState(s: KitState): void;
     onExit(code: number | null): void;
 };
@@ -12,17 +19,22 @@ export declare class Engine {
     readonly root: string;
     readonly bridgeSock: string;
     private readonly dir;
+    private setDir?;
+    private wantedSet?;
     private child?;
+    private readonly started;
     private starting?;
     private readonly authStore;
     private stopping;
     private credentialsLocked;
     private repaired;
     private prepared?;
+    patchSet?: string | null;
     private port;
     private token;
     private readonly o;
     private readonly paramPrefix;
+    private readonly appOwnedSessionPrefixes;
     constructor(o: EngineOptions);
     private state;
     private get entry();