@mearl/client 2.20.6 → 2.22.0

package/dist/plugins/runtime/pluginProcessTree.d.ts

@@ -0,0 +1,2 @@
+/** Resolves after the owned process group can no longer execute. */
+export declare function stopPluginProcessTree(pid: number): Promise<void>;

package/dist/plugins/runtime/pluginProcessTree.js

@@ -0,0 +1,31 @@
+import { execFile } from 'node:child_process';
+import { isProcessGroupAlive } from '@mearl/daemon-core';
+/** Resolves after the owned process group can no longer execute. */
+export async function stopPluginProcessTree(pid) {
+    if (!Number.isSafeInteger(pid) || pid < 1)
+        throw new Error('Invalid plugin process group');
+    if (process.platform === 'win32') {
+        return new Promise((resolve, reject) => {
+            execFile('taskkill', ['/PID', String(pid), '/T', '/F'], { windowsHide: true, timeout: 5000 }, error => {
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            });
+        });
+    }
+    try {
+        process.kill(-pid, 'SIGKILL');
+    }
+    catch (error) {
+        if (error.code === 'ESRCH')
+            return;
+        throw error;
+    }
+    const deadline = Date.now() + 5000;
+    while (isProcessGroupAlive(pid)) {
+        if (Date.now() >= deadline)
+            throw new Error('Unable to confirm plugin process group stopped');
+        await new Promise(resolve => setTimeout(resolve, 20));
+    }
+}

package/dist/plugins/runtime/pluginRevision.d.ts

@@ -0,0 +1,14 @@
+import type { PluginRegistration } from '../pluginRegistry.js';
+export interface PluginRevision {
+    plugin: string;
+    installationId: string;
+    revision: string;
+    originalRoot: string;
+    entry: string;
+    registration: PluginRegistration;
+}
+/** Captures relative source and resources before a task is accepted; execution never reads the live entry. */
+export declare function capturePluginRevision(plugin: string): PluginRevision;
+export declare function prunePluginRevisions(references: Set<string>): void;
+/** Recovery uses the retained snapshot after checking its identity and every source byte. */
+export declare function restorePluginRevision(plugin: string, installationId: string, revision: string, entry: string): PluginRevision;

package/dist/plugins/runtime/pluginRevision.js

@@ -0,0 +1,227 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { claimRecord, readRecord, writeRecord } from '@mearl/daemon-core';
+import { isBuiltin } from 'node:module';
+import { parse } from 'acorn';
+import { pluginHostPaths } from './pluginHostPaths.js';
+import { findPluginRegistration, PluginError } from '../pluginRegistry.js';
+const MAX_REVISION_BYTES = 64 * 1024 * 1024;
+const validatedSources = new Set();
+function within(root, file) {
+    const path = relative(root, file);
+    return path === '' || (!path.startsWith(`..${sep}`) && path !== '..' && !isAbsolute(path));
+}
+function sourceRoot(entry) {
+    let candidate = dirname(entry);
+    for (let depth = 0; depth < 6; depth++) {
+        if (existsSync(join(candidate, 'SKILL.md')))
+            return candidate;
+        const parent = dirname(candidate);
+        if (parent === candidate)
+            break;
+        candidate = parent;
+    }
+    return basename(dirname(entry)) === 'scripts' ? dirname(dirname(entry)) : dirname(entry);
+}
+function readSources(root) {
+    const files = [];
+    const registry = realpathSync(pluginHostPaths().registry);
+    let bytes = 0;
+    const visit = (directory, ancestors) => {
+        const real = realpathSync(directory);
+        if (!within(root, real) || ancestors.has(real))
+            throw new Error('Plugin snapshot has an external or cyclic directory link');
+        const next = new Set([...ancestors, real]);
+        for (const item of readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) {
+            if (['.git', '__pycache__', 'node_modules', '.DS_Store'].includes(item.name))
+                continue;
+            const file = join(directory, item.name);
+            if (within(root, registry) && within(registry, file))
+                continue;
+            const target = realpathSync(file);
+            if (!within(root, target))
+                throw new Error(`Plugin snapshot resource leaves the Skill directory: ${file}`);
+            const stat = statSync(file);
+            if (stat.isDirectory()) {
+                visit(file, next);
+                continue;
+            }
+            if (!stat.isFile())
+                throw new Error(`Unsupported plugin resource: ${file}`);
+            bytes += stat.size;
+            if (bytes > MAX_REVISION_BYTES || files.length >= 10000)
+                throw new Error('Plugin source snapshot exceeds 64 MiB or 10000 files');
+            const content = readFileSync(file);
+            bytes += content.length - stat.size;
+            if (bytes > MAX_REVISION_BYTES)
+                throw new Error('Plugin source snapshot exceeds 64 MiB');
+            files.push({
+                path: relative(root, file).split(sep).join('/'),
+                hash: createHash('sha256').update(content).digest('hex'),
+                bytes: content,
+                executable: (stat.mode & 0o111) !== 0,
+            });
+        }
+    };
+    visit(root, new Set());
+    return files;
+}
+function validateDependencies(files) {
+    const paths = new Set(files.map(file => file.path));
+    for (const file of files) {
+        if (!/\.[cm]?js$/.test(file.path))
+            continue;
+        const tree = parse(file.bytes.toString('utf8'), {
+            ecmaVersion: 'latest',
+            sourceType: 'module',
+            allowReturnOutsideFunction: true,
+        });
+        const check = (specifier) => {
+            if (typeof specifier !== 'string' || isBuiltin(specifier))
+                return;
+            if (!specifier.startsWith('./') && !specifier.startsWith('../'))
+                throw new PluginError('PLUGIN_SOURCE_NOT_SELF_CONTAINED', `后台任务需要自包含 Skill，请先打包依赖: ${file.path}: ${specifier}`);
+            const local = resolve('/source', dirname(file.path), specifier);
+            const normalized = relative('/source', local).split(sep).join('/');
+            if (!within('/source', local) ||
+                ![normalized, `${normalized}.js`, `${normalized}.json`, `${normalized}/index.js`].some(path => paths.has(path)))
+                throw new PluginError('PLUGIN_SOURCE_NOT_SELF_CONTAINED', `依赖不在 Skill 快照中: ${file.path}: ${specifier}`);
+        };
+        const visit = (node) => {
+            if (!node || typeof node !== 'object')
+                return;
+            if (['ImportDeclaration', 'ExportNamedDeclaration', 'ExportAllDeclaration'].includes(node.type))
+                check(node.source?.value);
+            if (node.type === 'ImportExpression')
+                check(node.source?.value);
+            if (node.type === 'CallExpression' &&
+                node.callee?.type === 'Identifier' &&
+                node.callee.name === 'require')
+                check(node.arguments[0]?.value);
+            for (const value of Object.values(node)) {
+                if (Array.isArray(value))
+                    value.forEach(visit);
+                else if (value && typeof value === 'object')
+                    visit(value);
+            }
+        };
+        visit(tree);
+    }
+}
+function fingerprint(files, entry) {
+    return createHash('sha256')
+        .update(JSON.stringify({ entry, files: files.map(file => [file.path, file.hash, file.executable]) }))
+        .digest('hex');
+}
+/** Captures relative source and resources before a task is accepted; execution never reads the live entry. */
+export function capturePluginRevision(plugin) {
+    const registration = findPluginRegistration(plugin);
+    if (!registration)
+        throw new PluginError('PLUGIN_NOT_REGISTERED', `插件未注册: ${plugin}`);
+    const entry = realpathSync(registration.entry);
+    const root = realpathSync(sourceRoot(entry));
+    const paths = pluginHostPaths();
+    mkdirSync(paths.installations, { recursive: true, mode: 0o700 });
+    const identityFile = join(paths.installations, `${plugin}.json`);
+    let installation = readRecord(identityFile);
+    if (!installation || installation.root !== root) {
+        const proposed = { pid: process.pid, root, installationId: randomUUID() };
+        if (installation)
+            writeRecord(identityFile, proposed);
+        else
+            claimRecord(identityFile, proposed);
+        installation = readRecord(identityFile);
+    }
+    if (!installation || installation.root !== root)
+        throw new Error('Plugin installation changed during capture');
+    const relativeEntry = relative(root, entry).split(sep).join('/');
+    const files = readSources(root);
+    const revision = fingerprint(files, relativeEntry);
+    if (!validatedSources.has(revision)) {
+        validateDependencies(files);
+        if (validatedSources.size >= 64)
+            validatedSources.delete(validatedSources.values().next().value);
+        validatedSources.add(revision);
+    }
+    const revisionRoot = join(paths.revisions, installation.installationId, revision);
+    if (!existsSync(revisionRoot)) {
+        const temporary = `${revisionRoot}.${randomUUID()}.tmp`;
+        try {
+            mkdirSync(temporary, { recursive: true, mode: 0o700 });
+            for (const file of files) {
+                const destination = resolve(temporary, file.path);
+                mkdirSync(dirname(destination), { recursive: true, mode: 0o700 });
+                writeFileSync(destination, file.bytes, {
+                    flag: 'wx',
+                    mode: file.executable ? 0o555 : 0o444,
+                });
+            }
+            if (fingerprint(readSources(root), relativeEntry) !== revision)
+                throw new PluginError('PLUGIN_SOURCE_CHANGED', '插件源码在创建快照时发生变化');
+            mkdirSync(dirname(revisionRoot), { recursive: true, mode: 0o700 });
+            renameSync(temporary, revisionRoot);
+        }
+        finally {
+            rmSync(temporary, { recursive: true, force: true });
+        }
+    }
+    return {
+        plugin,
+        installationId: installation.installationId,
+        revision,
+        originalRoot: root,
+        entry: join(revisionRoot, relativeEntry),
+        registration: { ...registration, entry: join(revisionRoot, relativeEntry), source: undefined },
+    };
+}
+export function prunePluginRevisions(references) {
+    const directory = pluginHostPaths().revisions;
+    if (!existsSync(directory))
+        return;
+    for (const installation of readdirSync(directory, { withFileTypes: true })) {
+        if (!installation.isDirectory())
+            continue;
+        const root = join(directory, installation.name);
+        for (const revision of readdirSync(root, { withFileTypes: true })) {
+            if (revision.isDirectory() && !references.has(`${installation.name}/${revision.name}`))
+                rmSync(join(root, revision.name), { recursive: true, force: true });
+        }
+        if (!readdirSync(root).length)
+            rmSync(root, { recursive: true, force: true });
+    }
+}
+/** Recovery uses the retained snapshot after checking its identity and every source byte. */
+export function restorePluginRevision(plugin, installationId, revision, entry) {
+    if (!/^[a-f0-9-]{36}$/.test(installationId) || !/^[a-f0-9]{64}$/.test(revision))
+        throw new Error('Invalid recovery revision');
+    const paths = pluginHostPaths();
+    const registration = findPluginRegistration(plugin);
+    const installation = readRecord(join(paths.installations, `${plugin}.json`));
+    if (!registration ||
+        !installation ||
+        installation.installationId !== installationId ||
+        sourceRoot(realpathSync(registration.entry)) !== installation.root)
+        throw new PluginError('PLUGIN_TASK_INSTALLATION_CHANGED', 'Task installation was removed or replaced');
+    try {
+        const root = realpathSync(join(paths.revisions, installationId, revision));
+        const restoredEntry = resolve(root, entry);
+        if (!entry ||
+            isAbsolute(entry) ||
+            !within(root, restoredEntry) ||
+            !within(root, realpathSync(restoredEntry)) ||
+            fingerprint(readSources(root), entry) !== revision)
+            throw new Error('Snapshot identity changed');
+        return {
+            plugin,
+            installationId,
+            revision,
+            originalRoot: installation.root,
+            entry: restoredEntry,
+            registration: { ...registration, entry: restoredEntry, source: undefined },
+        };
+    }
+    catch {
+        throw new PluginError('PLUGIN_TASK_REVISION_UNAVAILABLE', 'Task source snapshot is missing or has changed');
+    }
+}

package/dist/plugins/runtime/pluginRuntimeCleanup.d.ts

@@ -0,0 +1,2 @@
+/** Complete uninstall discards execution caches after every plugin has been removed. */
+export declare function cleanupPluginRuntime(): Promise<void>;

package/dist/plugins/runtime/pluginRuntimeCleanup.js

@@ -0,0 +1,55 @@
+import { rmSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { claimRecord, isProcessOwnerAlive, processIdentity, readRecord, removeInvalidRecord, removeRecordIfPid, } from '@mearl/daemon-core';
+import { pluginHostPaths } from './pluginHostPaths.js';
+import { listPluginNames } from '../pluginRegistry.js';
+import { PluginTaskClient } from '../clients/pluginTasks.js';
+import { PluginTaskStore, pluginTaskExecutionUnconfirmed } from './pluginTaskStore.js';
+/** Complete uninstall discards execution caches after every plugin has been removed. */
+export async function cleanupPluginRuntime() {
+    const paths = pluginHostPaths();
+    if (listPluginNames().length)
+        throw new Error('Registered plugins still use the execution service');
+    // The service launcher uses this same claim before creating a replacement host.
+    const lock = `${paths.lease}.start`;
+    const starter = readRecord(lock);
+    if (starter && !isProcessOwnerAlive(starter))
+        removeRecordIfPid(lock, starter.pid);
+    else if (!starter)
+        removeInvalidRecord(lock);
+    if (!claimRecord(lock, { pid: process.pid, processIdentity: processIdentity(process.pid) }))
+        throw new Error('Plugin execution service is starting; caches were retained');
+    try {
+        const lease = readRecord(paths.lease);
+        if (lease && isProcessOwnerAlive(lease)) {
+            const client = new PluginTaskClient({ autoStart: false });
+            try {
+                await client.stopHost();
+            }
+            finally {
+                client.disconnect();
+            }
+        }
+        const current = readRecord(paths.lease);
+        if ((current && isProcessOwnerAlive(current)) || listPluginNames().length)
+            throw new Error('Plugin execution service restarted during cleanup; caches were retained');
+        const store = new PluginTaskStore();
+        if (store.list().some(pluginTaskExecutionUnconfirmed))
+            throw new Error('Plugin execution is not confirmed stopped; task records were retained');
+        store.recover(randomUUID());
+        if (store.list().some(pluginTaskExecutionUnconfirmed))
+            throw new Error('Plugin execution is not confirmed stopped; task records were retained');
+        const replacement = readRecord(paths.lease);
+        if ((replacement && isProcessOwnerAlive(replacement)) || listPluginNames().length)
+            throw new Error('Plugin execution service restarted during cleanup; caches were retained');
+        for (const file of [paths.tasks, paths.revisions, paths.log, `${paths.log}.1`])
+            rmSync(file, { recursive: true, force: true });
+        if (current)
+            removeRecordIfPid(paths.lease, current.pid);
+        if (process.platform !== 'win32')
+            rmSync(paths.socket, { force: true });
+    }
+    finally {
+        removeRecordIfPid(lock, process.pid);
+    }
+}

package/dist/plugins/runtime/pluginStateManager.d.ts

@@ -0,0 +1,24 @@
+import type { PluginRevision } from './pluginRevision.js';
+import { PluginStateStore } from './pluginStateStore.js';
+import type { PluginTaskManager, PluginTaskBridge } from './pluginTaskManager.js';
+import type { PluginOptions } from '../sdk/plugin.js';
+import type { PluginPageTarget } from '../../generated/plugin-pages.js';
+export declare class PluginStateManager {
+    private readonly tasks;
+    readonly store: PluginStateStore;
+    private readonly descriptions;
+    private readonly pending;
+    private readonly controller;
+    resolveTarget?: (plugin: string, instanceId: unknown, bridge: PluginTaskBridge, options: PluginOptions) => Promise<{
+        target: PluginPageTarget;
+        assertActive(): void;
+    }>;
+    private readonly maintenance;
+    constructor(tasks: PluginTaskManager);
+    call(plugin: string, input: Record<string, unknown>, bridge: PluginTaskBridge, options?: PluginOptions, binding?: {
+        revision: PluginRevision;
+        signal?: AbortSignal;
+        expectedTarget?: PluginPageTarget;
+    }): Promise<unknown>;
+    close(): Promise<void>;
+}

package/dist/plugins/runtime/pluginStateManager.js

@@ -0,0 +1,132 @@
+import { pluginStateSignature } from '../sdk/pluginStateDefinition.js';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { findPluginRegistration } from '../pluginRegistry.js';
+import { pluginHostPaths } from './pluginHostPaths.js';
+import { capturePluginRevision } from './pluginRevision.js';
+import { PluginStateStore } from './pluginStateStore.js';
+export class PluginStateManager {
+    tasks;
+    store = new PluginStateStore();
+    descriptions = new Map();
+    pending = new Set();
+    controller = new AbortController();
+    resolveTarget;
+    maintenance;
+    constructor(tasks) {
+        this.tasks = tasks;
+        this.store.prune();
+        this.maintenance = setInterval(() => {
+            try {
+                this.store.prune();
+            }
+            catch (error) {
+                console.error('Plugin cache maintenance failed:', error);
+            }
+        }, 60000);
+        this.maintenance.unref();
+    }
+    async call(plugin, input, bridge, options = {}, binding) {
+        this.controller.signal.throwIfAborted();
+        binding?.signal?.throwIfAborted();
+        if (!/^[a-z][a-z0-9-]*$/.test(plugin) ||
+            (bridge.scope.plugin && bridge.scope.plugin !== plugin) ||
+            !input ||
+            typeof input !== 'object' ||
+            Array.isArray(input))
+            throw new Error('Invalid plugin state scope');
+        const revision = binding?.revision ?? capturePluginRevision(plugin);
+        const id = `${revision.installationId}/${revision.revision}`;
+        let description = this.descriptions.get(id);
+        if (!description) {
+            if (this.descriptions.size >= 64)
+                this.descriptions.delete(this.descriptions.keys().next().value);
+            const release = this.tasks.pinRevision(revision);
+            description = this.tasks
+                .describeRevision(revision, this.controller.signal, { cache: true })
+                .finally(release);
+            this.descriptions.set(id, description);
+            this.pending.add(description);
+            void description.finally(() => this.pending.delete(description)).catch(() => { });
+            void description.catch(() => {
+                if (this.descriptions.get(id) === description)
+                    this.descriptions.delete(id);
+            });
+        }
+        const declaration = (await description).stateStorage;
+        this.controller.signal.throwIfAborted();
+        binding?.signal?.throwIfAborted();
+        const name = String(input.collection ?? '');
+        const definition = declaration && Object.hasOwn(declaration.collections, name)
+            ? declaration.collections[name]
+            : undefined;
+        if (!definition || !/^[a-z][a-z0-9-]{0,63}$/.test(name))
+            throw Object.assign(new Error('Plugin state collection is not declared'), {
+                code: 'PLUGIN_STATE_NOT_DECLARED',
+            });
+        if (input.expectedDeclaration !== undefined &&
+            input.expectedDeclaration !== pluginStateSignature(definition))
+            throw Object.assign(new Error('Plugin state declaration changed during command execution'), {
+                code: 'PLUGIN_STATE_REVISION_CHANGED',
+            });
+        let scope = definition.scope;
+        let assertScope = () => { };
+        if (definition.scope === 'host')
+            scope += `:${this.tasks.host.hostId}`;
+        if (definition.scope === 'instance' || definition.scope === 'browser-session') {
+            if (!this.resolveTarget)
+                throw new Error('Page state scope is unavailable');
+            const resolved = await this.resolveTarget(plugin, input.instanceId, bridge, options);
+            const target = resolved.target;
+            const expected = binding?.expectedTarget;
+            if (expected &&
+                (target.browserSessionId !== expected.browserSessionId ||
+                    target.tabId !== expected.tabId ||
+                    target.frameId !== expected.frameId ||
+                    target.documentId !== expected.documentId))
+                throw Object.assign(new Error('State access cannot change the inherited document'), {
+                    code: 'PLUGIN_PAGE_TARGET_CHANGED',
+                });
+            assertScope = resolved.assertActive;
+            scope +=
+                definition.scope === 'instance'
+                    ? `:${String(input.instanceId)}`
+                    : `:${target.browserSessionId}`;
+        }
+        // No await occurs between the final target check and the atomic store operation.
+        this.controller.signal.throwIfAborted();
+        binding?.signal?.throwIfAborted();
+        let installation;
+        try {
+            installation = JSON.parse(readFileSync(join(pluginHostPaths().installations, `${plugin}.json`), 'utf8'));
+        }
+        catch {
+            /* Removed installations have no writable state scope. */
+        }
+        if (!findPluginRegistration(plugin) || installation?.installationId !== revision.installationId)
+            throw Object.assign(new Error('Plugin state installation was removed or replaced'), {
+                code: 'PLUGIN_STATE_SCOPE_ENDED',
+            });
+        assertScope();
+        const namespace = { installationId: revision.installationId, collection: name, scope };
+        switch (input.operation) {
+            case 'get':
+                return this.store.get(namespace, definition, input.key);
+            case 'get-many':
+                return this.store.getMany(namespace, definition, input.keys);
+            case 'list':
+                return this.store.list(namespace, definition, input);
+            case 'transact':
+                return this.store.transact(namespace, definition, input.transaction);
+            default:
+                throw new Error('Invalid state operation');
+        }
+    }
+    async close() {
+        clearInterval(this.maintenance);
+        this.controller.abort();
+        this.descriptions.clear();
+        this.store.clearMemory();
+        await Promise.allSettled([...this.pending]);
+    }
+}

package/dist/plugins/runtime/pluginStateStore.d.ts

@@ -0,0 +1,57 @@
+import type { PluginStateCollection, PluginStateEntry, PluginStateTransaction } from '../../generated/plugin-state.js';
+export interface PluginStateNamespace {
+    installationId: string;
+    collection: string;
+    scope: string;
+}
+/** A collection namespace is one atomic record, including CAS and commit receipts. */
+export declare class PluginStateStore {
+    readonly directory: string;
+    private readonly now;
+    private readonly memory;
+    private memoryBytes;
+    private memoryRevisionFloor;
+    clearMemory(): void;
+    private readonly valueBytes;
+    private memorySize;
+    private saveMemory;
+    constructor(directory?: string, now?: () => number);
+    private path;
+    private read;
+    private entry;
+    discardScope(installationId: string, scope: string): void;
+    prune(skipFile?: string): void;
+    get(namespace: PluginStateNamespace, definition: PluginStateCollection, name: string): {
+        revision: number;
+        schemaVersion: number;
+        key: string;
+        exists: boolean;
+        version: string;
+        value?: unknown;
+        expiresAt?: number;
+    };
+    getMany(namespace: PluginStateNamespace, definition: PluginStateCollection, names: unknown): {
+        entries: PluginStateEntry[];
+        revision: number;
+        schemaVersion: number;
+    };
+    list(namespace: PluginStateNamespace, definition: PluginStateCollection, input?: {
+        cursor?: string;
+        limit?: number;
+        expectedRevision?: number;
+    }): {
+        nextCursor?: string | undefined;
+        entries: PluginStateEntry[];
+        revision: number;
+        schemaVersion: number;
+    };
+    transact(namespace: PluginStateNamespace, definition: PluginStateCollection, input: PluginStateTransaction): {
+        revision: number;
+        schemaVersion: number;
+        reused: boolean;
+    } | {
+        revision: number;
+        schemaVersion: number;
+        reused?: undefined;
+    };
+}