@mearl/client 2.20.6 → 2.21.0

package/dist/pluginPages.d.ts

@@ -0,0 +1,21 @@
+import type { PluginHostConnection } from './pluginHostConnection.js';
+import type { UnifiedClientOptions, UnifiedInvokeOptions } from './unified.js';
+import type { PluginPageInstance, PluginPageEvents, PluginPageOperation } from './generated-plugin-pages.js';
+export type { PluginPageInstance, PluginPageEvents, PluginPageRuntime, PluginPageActivation, PluginPageTarget, PluginPageOperation, } from './generated-plugin-pages.js';
+export declare class PluginPageClient {
+    private readonly connection?;
+    private readonly client?;
+    constructor(configuration?: UnifiedClientOptions, connection?: PluginHostConnection | undefined);
+    call(plugin: string, operation: PluginPageOperation, input?: Record<string, unknown>, options?: UnifiedInvokeOptions): Promise<any>;
+    attach(plugin: string, input: Record<string, unknown>, options?: UnifiedInvokeOptions): Promise<PluginPageInstance>;
+    get(plugin: string, instanceId: string): Promise<PluginPageInstance>;
+    list(plugin: string): Promise<{
+        instances: PluginPageInstance[];
+    }>;
+    send(plugin: string, instanceId: string, message: unknown, options?: {
+        timeoutSec?: number;
+    }): Promise<unknown>;
+    detach(plugin: string, instanceId: string): Promise<PluginPageInstance>;
+    events(plugin: string, instanceId: string, cursor?: number, waitMs?: number): Promise<PluginPageEvents>;
+    disconnect(): void;
+}

package/dist/pluginPages.js

@@ -0,0 +1,46 @@
+import { UnifiedClient } from './unified.js';
+export class PluginPageClient {
+    connection;
+    client;
+    constructor(configuration = {}, connection) {
+        this.connection = connection;
+        if (!connection)
+            this.client = new UnifiedClient(configuration);
+    }
+    call(plugin, operation, input = {}, options = {}) {
+        if (this.connection)
+            return this.connection.request('page.call', {
+                plugin,
+                input: { ...input, operation },
+                options,
+                execution: {
+                    cwd: process.cwd(),
+                    environment: Object.fromEntries(Object.entries(process.env).filter(entry => entry[1] !== undefined)),
+                },
+            }, Math.max(120000, typeof input.timeoutSec === 'number' && Number.isFinite(input.timeoutSec)
+                ? (Math.min(300, input.timeoutSec) + 5) * 1000
+                : 0));
+        return this.client.invoke('plugin_page', { ...input, plugin, operation }, options);
+    }
+    attach(plugin, input, options = {}) {
+        return this.call(plugin, 'attach', input, options);
+    }
+    get(plugin, instanceId) {
+        return this.call(plugin, 'get', { instanceId });
+    }
+    list(plugin) {
+        return this.call(plugin, 'list');
+    }
+    send(plugin, instanceId, message, options = {}) {
+        return this.call(plugin, 'send', { instanceId, message, ...options }, options);
+    }
+    detach(plugin, instanceId) {
+        return this.call(plugin, 'detach', { instanceId });
+    }
+    events(plugin, instanceId, cursor = 0, waitMs = 0) {
+        return this.call(plugin, 'events', { instanceId, cursor, waitMs });
+    }
+    disconnect() {
+        this.client?.disconnect();
+    }
+}

package/dist/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/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/pluginRecoveryDefinition.d.ts

@@ -0,0 +1,3 @@
+import type { PluginTaskRecoveryDeclaration } from './generated-plugin-recovery.js';
+export declare function normalizePluginTaskRecovery(value: unknown): PluginTaskRecoveryDeclaration | undefined;
+export declare function pluginRecoverySignature(value: unknown): string;

package/dist/pluginRecoveryDefinition.js

@@ -0,0 +1,56 @@
+import { createHash } from 'node:crypto';
+import { compilePluginStateSchema } from './pluginStateDefinition.js';
+export function normalizePluginTaskRecovery(value) {
+    if (value === undefined)
+        return;
+    const declaration = JSON.parse(JSON.stringify(value));
+    if (!declaration ||
+        declaration.version !== 1 ||
+        !declaration.commands ||
+        typeof declaration.commands !== 'object' ||
+        Array.isArray(declaration.commands) ||
+        Object.keys(declaration.commands).length > 32 ||
+        Buffer.byteLength(JSON.stringify(declaration)) > 128 * 1024)
+        throw new Error('Invalid taskRecovery declaration');
+    for (const [command, definition] of Object.entries(declaration.commands)) {
+        if (!/^[a-z][a-z0-9-]*$/.test(command) ||
+            !definition ||
+            !Number.isSafeInteger(definition.checkpointVersion) ||
+            definition.checkpointVersion < 1 ||
+            !definition.schema ||
+            typeof definition.schema !== 'object' ||
+            Array.isArray(definition.schema) ||
+            definition.schema.$async)
+            throw new Error('Invalid task checkpoint definition');
+        compilePluginStateSchema(definition.schema);
+        if (definition.migrateFrom !== undefined) {
+            if (!Array.isArray(definition.migrateFrom) ||
+                definition.migrateFrom.length < 1 ||
+                definition.migrateFrom.length > 16)
+                throw new Error('Invalid checkpoint migration sources');
+            const versions = new Set();
+            for (const source of definition.migrateFrom) {
+                if (!source ||
+                    !Number.isSafeInteger(source.version) ||
+                    source.version < 1 ||
+                    source.version >= definition.checkpointVersion ||
+                    versions.has(source.version) ||
+                    !source.schema ||
+                    typeof source.schema !== 'object' ||
+                    Array.isArray(source.schema) ||
+                    source.schema.$async)
+                    throw new Error('Checkpoint migrations require distinct older versions and schemas');
+                compilePluginStateSchema(source.schema);
+                versions.add(source.version);
+            }
+        }
+    }
+    return declaration;
+}
+export function pluginRecoverySignature(value) {
+    return createHash('sha256')
+        .update(JSON.stringify(value, (_key, item) => item && typeof item === 'object' && !Array.isArray(item)
+        ? Object.fromEntries(Object.entries(item).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
+        : item))
+        .digest('hex');
+}

package/dist/pluginRegistry.d.ts

@@ -8,9 +8,6 @@ export interface PluginToolboxSandboxPage {
     runtime?: 'preact';
     entry: string;
     commands: string[];
-    lifecycle?: {
-        onNavigation: string;
-    };
 }
 export interface PluginToolboxLocale {
     title?: string;
@@ -38,6 +35,7 @@ export interface PluginPageBundleRegistration {
 }
 export interface PluginRegistration {
     entry: string;
+    hasPublicCommands?: boolean;
     description?: string;
     managedBy?: string;
     toolbox?: PluginToolboxContribution;
@@ -52,6 +50,7 @@ export interface PluginRegistration {
 }
 export declare function pluginRegistrationNeedsRefresh(registration: PluginRegistration, includePage?: boolean): boolean;
 export interface PluginRegistrationOptions {
+    hasPublicCommands?: boolean;
     managedBy?: string;
     toolbox?: PluginToolboxContribution;
     appProfiles?: AppProfileContribution;

package/dist/pluginRegistry.js

@@ -1,5 +1,6 @@
 import { validateAppProfileContribution, } from './generated-app-profile-definition.js';
 import { randomUUID } from 'node:crypto';
+import { parseToolboxIcon } from './generated-toolbox-icon.js';
 import { closeSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
 import { homedir } from 'node:os';
 import { isAbsolute, join, resolve } from 'node:path';
@@ -134,8 +135,8 @@ export function normalizePluginToolboxContribution(value) {
     if (description && description.length > 240) {
         throw new Error('toolbox.description 不能超过 240 个字符');
     }
-    if (icon && (!/^[a-z][a-z0-9-]*$/.test(icon) || icon.length > 40)) {
-        throw new Error('toolbox.icon 必须是短横线命名的图标名称');
+    if (icon && !parseToolboxIcon(icon)) {
+        throw new Error('toolbox.icon 必须是图标名称、SVG、图片 Data URL 或 HTTP(S) 图片地址，最多 32768 个字符');
     }
     let locales;
     if (candidate.locales !== undefined) {
@@ -209,17 +210,8 @@ export function normalizePluginToolboxContribution(value) {
         entry: pageEntry,
         commands,
     };
-    if (pageCandidate.lifecycle !== undefined) {
-        const lifecycle = pageCandidate.lifecycle;
-        if (!lifecycle ||
-            typeof lifecycle !== 'object' ||
-            Array.isArray(lifecycle) ||
-            typeof lifecycle.onNavigation !== 'string' ||
-            !commands.includes(lifecycle.onNavigation)) {
-            throw new Error('toolbox.page.lifecycle.onNavigation 必须是 page.commands 中的命令名称');
-        }
-        page.lifecycle = { onNavigation: lifecycle.onNavigation };
-    }
+    if ('lifecycle' in pageCandidate)
+        throw new Error('toolbox.page.lifecycle is unsupported; declare pageRuntime and activation rules');
     let agent;
     if (candidate.agent !== undefined) {
         if (!candidate.agent || typeof candidate.agent !== 'object' || Array.isArray(candidate.agent)) {
@@ -309,6 +301,9 @@ export function registerPlugin(name, target, description, options = {}) {
     }
     const record = {
         entry,
+        ...(options.hasPublicCommands !== undefined
+            ? { hasPublicCommands: options.hasPublicCommands }
+            : {}),
         source: {
             entry: entryVersion,
             ...(options.profileSources ? { profiles: options.profileSources } : {}),
@@ -339,6 +334,7 @@ export function unregisterPlugin(name) {
     const file = join(pluginDirectory(), `${name}.json`);
     try {
         rmSync(file);
+        rmSync(join(pluginDirectory(), '.host', 'installations', `${name}.json`), { force: true });
         removePluginPageBundles(name);
         return true;
     }
@@ -365,6 +361,8 @@ export function findPluginRegistration(name) {
         const record = JSON.parse(content);
         if (typeof record?.entry !== 'string' || !isAbsolute(record.entry))
             throw new Error('invalid entry');
+        if (record.hasPublicCommands !== undefined && typeof record.hasPublicCommands !== 'boolean')
+            throw new Error('invalid public commands');
         const description = typeof record.description === 'string' && record.description.trim()
             ? record.description.trim()
             : undefined;
@@ -396,6 +394,9 @@ export function findPluginRegistration(name) {
         }
         return {
             entry: record.entry,
+            ...(record.hasPublicCommands !== undefined
+                ? { hasPublicCommands: record.hasPublicCommands }
+                : {}),
             ...(description ? { description } : {}),
             ...(managedBy ? { managedBy } : {}),
             ...(toolbox ? { toolbox } : {}),

package/dist/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/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/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/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 './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/pluginState.d.ts

@@ -0,0 +1,26 @@
+import { PluginHostConnection } from './pluginHostConnection.js';
+import type { PluginHostClientOptions } from './pluginHostConnection.js';
+import type { PluginOptions } from './plugin.js';
+import type { PluginStateOperation, PluginStateSnapshot, PluginStateList, PluginStateTransaction } from './generated-plugin-state.js';
+export type * from './generated-plugin-state.js';
+export declare class PluginStateClient {
+    private readonly options;
+    readonly connection: PluginHostConnection;
+    constructor(options?: PluginHostClientOptions);
+    call(plugin: string, collection: string, operation: PluginStateOperation, input?: Record<string, unknown>, options?: PluginOptions): Promise<any>;
+    get(plugin: string, collection: string, key: string, input?: {
+        instanceId?: string;
+    }): Promise<PluginStateSnapshot>;
+    getMany(plugin: string, collection: string, keys: string[], input?: {
+        instanceId?: string;
+    }): Promise<PluginStateList>;
+    list(plugin: string, collection: string, input?: Record<string, unknown>): Promise<PluginStateList>;
+    transact(plugin: string, collection: string, transaction: PluginStateTransaction, input?: {
+        instanceId?: string;
+    }): Promise<{
+        revision: number;
+        schemaVersion: number;
+        reused?: boolean;
+    }>;
+    disconnect(): void;
+}

package/dist/pluginState.js

@@ -0,0 +1,28 @@
+import { PluginHostConnection } from './pluginHostConnection.js';
+export class PluginStateClient {
+    options;
+    connection;
+    constructor(options = {}) {
+        this.options = options;
+        this.connection = options.connection ?? new PluginHostConnection(options);
+    }
+    call(plugin, collection, operation, input = {}, options = {}) {
+        return this.connection.request('state.call', { plugin, input: { ...input, collection, operation }, options }, 30000);
+    }
+    get(plugin, collection, key, input = {}) {
+        return this.call(plugin, collection, 'get', { ...input, key });
+    }
+    getMany(plugin, collection, keys, input = {}) {
+        return this.call(plugin, collection, 'get-many', { ...input, keys });
+    }
+    list(plugin, collection, input = {}) {
+        return this.call(plugin, collection, 'list', input);
+    }
+    transact(plugin, collection, transaction, input = {}) {
+        return this.call(plugin, collection, 'transact', { ...input, transaction });
+    }
+    disconnect() {
+        if (!this.options.connection)
+            this.connection.disconnect();
+    }
+}

package/dist/pluginStateDefinition.d.ts

@@ -0,0 +1,4 @@
+import type { PluginStateDeclaration } from './generated-plugin-state.js';
+export declare function compilePluginStateSchema(schema: Record<string, unknown>): import("ajv/dist/core.js").AnyValidateFunction<unknown>;
+export declare function normalizePluginState(value: unknown): PluginStateDeclaration | undefined;
+export declare function pluginStateSignature(collection: import('./generated-plugin-state.js').PluginStateCollection): string;