@mearl/client 2.20.5 → 2.21.0

package/dist/pluginDiagnostics.d.ts

@@ -0,0 +1,26 @@
+import type { PluginModelDiagnostic } from './generated-plugin-models.js';
+import type { PluginDiagnosticFailure, PluginDiagnosticOptions, PluginDiagnosticPage, PluginDiagnosticPageBinding, PluginDiagnosticReport } from './generated-plugin-diagnostics.js';
+import type { PluginTaskRecord } from './pluginTaskStore.js';
+import type { PluginTaskScope } from './pluginTaskProtocol.js';
+import type { PluginExecutionHost } from './generated-plugin-execution.js';
+export declare const MAX_PLUGIN_DIAGNOSTIC_BYTES: number;
+export declare function normalizeDiagnosticOptions(value: unknown): PluginDiagnosticOptions;
+export declare function diagnosticFailure(value: {
+    code?: string;
+    message?: string;
+} | undefined, options: PluginDiagnosticOptions): PluginDiagnosticFailure | undefined;
+/** A worker can publish only this small operational vocabulary. */
+export declare function normalizeModelDiagnostic(value: unknown, previous?: PluginModelDiagnostic): PluginModelDiagnostic;
+export declare function diagnosticBinding(value: {
+    instanceId: string;
+    target: {
+        browserSessionId: string;
+        tabId: number;
+        frameId: string | number;
+        documentId: string;
+    };
+}): PluginDiagnosticPageBinding;
+export declare function buildDiagnosticReport(host: PluginExecutionHost, scope: PluginTaskScope, options: PluginDiagnosticOptions, scan: {
+    records: PluginTaskRecord[];
+    limited: boolean;
+}, snapshots: PluginDiagnosticPage[]): PluginDiagnosticReport;

package/dist/pluginDiagnostics.js

@@ -0,0 +1,309 @@
+import { isProcessOwnerAlive } from '@mearl/daemon-core';
+import { basename } from 'node:path';
+import { isPluginTaskId, PLUGIN_TASK_PROTOCOL_VERSION } from './generated-plugin-tasks.js';
+import { isPluginPageInstanceId } from './generated-plugin-pages.js';
+export const MAX_PLUGIN_DIAGNOSTIC_BYTES = 256 * 1024;
+function text(value, maximum = 256) {
+    if (typeof value !== 'string')
+        return;
+    const bytes = Buffer.from(value);
+    return bytes.length <= maximum
+        ? value
+        : bytes
+            .subarray(0, maximum)
+            .toString('utf8')
+            .replace(/\uFFFD$/, '');
+}
+export function normalizeDiagnosticOptions(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Invalid diagnostic options');
+    const input = value;
+    if (Object.keys(input).some(key => !['taskId', 'plugin', 'instanceId', 'includeErrorMessages', 'includeLocalPaths'].includes(key)))
+        throw new Error('Unknown diagnostic option');
+    if (input.taskId !== undefined && !isPluginTaskId(input.taskId))
+        throw new Error('Invalid diagnostic task ID');
+    if (input.instanceId !== undefined && !isPluginPageInstanceId(input.instanceId))
+        throw new Error('Invalid diagnostic instance ID');
+    if (input.plugin !== undefined &&
+        (typeof input.plugin !== 'string' ||
+            !/^[a-z][a-z0-9-]*$/.test(input.plugin) ||
+            input.plugin.length > 128))
+        throw new Error('Invalid diagnostic plugin');
+    for (const key of ['includeErrorMessages', 'includeLocalPaths'])
+        if (input[key] !== undefined && typeof input[key] !== 'boolean')
+            throw new Error('Invalid diagnostic content option');
+    return {
+        ...(input.taskId ? { taskId: String(input.taskId) } : {}),
+        ...(input.plugin ? { plugin: String(input.plugin) } : {}),
+        ...(input.instanceId ? { instanceId: String(input.instanceId) } : {}),
+        ...(input.includeErrorMessages !== undefined
+            ? { includeErrorMessages: input.includeErrorMessages }
+            : {}),
+        ...(input.includeLocalPaths !== undefined
+            ? { includeLocalPaths: input.includeLocalPaths }
+            : {}),
+    };
+}
+export function diagnosticFailure(value, options) {
+    if (!value)
+        return;
+    const message = options.includeErrorMessages ? text(value.message, 4096) : undefined;
+    return {
+        code: text(value.code) ?? 'PLUGIN_ERROR_UNCLASSIFIED',
+        ...(message !== undefined
+            ? {
+                message,
+                ...(Buffer.byteLength(value.message ?? '') > 4096 ? { messageTruncated: true } : {}),
+            }
+            : {}),
+    };
+}
+/** A worker can publish only this small operational vocabulary. */
+export function normalizeModelDiagnostic(value, previous = {}) {
+    const result = { ...previous };
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return result;
+    const input = value;
+    for (const key of ['requestedModel', 'selectedModel', 'activeModel'])
+        if (typeof input[key] === 'string')
+            result[key] = text(input[key]);
+    if (['apikey', 'chatgpt', 'chatgptAuthTokens', 'unknown'].includes(input.authentication))
+        result.authentication = input.authentication;
+    for (const key of ['threadRestrictionsAccepted', 'turnRestrictionsAccepted'])
+        if (typeof input[key] === 'boolean')
+            result[key] = input[key];
+    if (Number.isSafeInteger(input.retryCount) && input.retryCount >= 0)
+        result.retryCount = Math.min(input.retryCount, 1000000);
+    const runtime = input.runtime;
+    if (runtime && ['explicit', 'automatic'].includes(runtime.selection))
+        result.runtime = {
+            ...(typeof runtime.executable === 'string'
+                ? { executable: text(runtime.executable, 4096) }
+                : {}),
+            ...(typeof runtime.version === 'string' ? { version: text(runtime.version) } : {}),
+            selection: runtime.selection,
+            ...(typeof runtime.started === 'boolean' ? { started: runtime.started } : {}),
+        };
+    const config = input.configuration;
+    if (config &&
+        ['default', 'environment'].includes(config.source) &&
+        typeof config.filePresent === 'boolean')
+        result.configuration = {
+            source: config.source,
+            filePresent: config.filePresent,
+            ...(typeof config.home === 'string' ? { home: text(config.home, 4096) } : {}),
+            ...(typeof config.baseProvider === 'string'
+                ? { baseProvider: text(config.baseProvider) }
+                : {}),
+            ...(['file', 'keyring', 'auto', 'ephemeral', 'unknown'].includes(config.credentialStore)
+                ? { credentialStore: config.credentialStore }
+                : {}),
+        };
+    return result;
+}
+export function diagnosticBinding(value) {
+    return {
+        instanceId: value.instanceId,
+        browserSessionId: value.target.browserSessionId,
+        tabId: value.target.tabId,
+        frameId: value.target.frameId,
+        documentId: value.target.documentId,
+    };
+}
+function modelProjection(record, options) {
+    if (record.task.kind !== 'model')
+        return;
+    const request = record.task.input.request;
+    const metadata = normalizeModelDiagnostic(record.diagnostics?.model, typeof request?.model === 'string' ? { requestedModel: text(request.model) } : {});
+    if (!options.includeLocalPaths) {
+        if (metadata.runtime?.executable)
+            metadata.runtime = { ...metadata.runtime, executable: basename(metadata.runtime.executable) };
+        if (metadata.configuration) {
+            const { home: _home, ...configuration } = metadata.configuration;
+            metadata.configuration = configuration;
+        }
+    }
+    return metadata;
+}
+function taskProjection(record, options, observedAt) {
+    const { task, diagnostics, execution, executorOwner: owner } = record;
+    const events = record.events.filter(event => event.type !== 'progress');
+    const first = record.events[0]?.sequence ?? task.sequence + 1;
+    const alive = owner && !diagnostics?.executorStoppedAt ? isProcessOwnerAlive(owner) : false;
+    const stopped = diagnostics?.executorStoppedAt;
+    const state = alive
+        ? 'observed-alive'
+        : stopped
+            ? 'stop-confirmed'
+            : diagnostics?.executorAttempted === false
+                ? 'never-started'
+                : 'unknown';
+    const routing = execution?.options;
+    return {
+        taskId: task.taskId,
+        plugin: text(task.plugin),
+        kind: task.kind ?? 'command',
+        command: text(task.command),
+        state: task.state,
+        source: task.source,
+        host: { hostId: task.host.hostId, epoch: task.host.epoch },
+        installationId: task.installationId,
+        revision: task.revision,
+        ...(diagnostics?.invocationId ? { invocationId: diagnostics.invocationId } : {}),
+        createdAt: task.createdAt,
+        updatedAt: task.updatedAt,
+        sequence: task.sequence,
+        ...(diagnostics?.page
+            ? {
+                page: diagnosticBinding({
+                    instanceId: diagnostics.page.instanceId,
+                    target: diagnostics.page,
+                }),
+            }
+            : {}),
+        ...(routing
+            ? {
+                routing: {
+                    ...(routing.browser ? { browser: text(routing.browser, 1024) } : {}),
+                    ...(routing.session ? { session: text(routing.session) } : {}),
+                    ...(routing.connector ? { connector: text(routing.connector) } : {}),
+                    ...(routing.local !== undefined ? { local: routing.local } : {}),
+                    ...(routing.transport ? { transport: routing.transport } : {}),
+                },
+            }
+            : {}),
+        ...(execution?.executionTimeoutMs ? { executionTimeoutMs: execution.executionTimeoutMs } : {}),
+        executor: {
+            state,
+            observedAt,
+            ...(owner ? { pid: owner.pid } : {}),
+            ...(stopped ? { stoppedAt: stopped } : {}),
+        },
+        ...(task.error ? { failure: diagnosticFailure(task.error, options) } : {}),
+        ...(task.checkpoint
+            ? {
+                checkpoint: {
+                    sequence: task.checkpoint.sequence,
+                    version: task.checkpoint.version,
+                    schemaHash: task.checkpoint.schemaHash,
+                    updatedAt: task.checkpoint.updatedAt,
+                },
+            }
+            : {}),
+        ...(task.result
+            ? {
+                result: {
+                    bytes: task.result.bytes,
+                    chunks: task.result.chunks,
+                    sha256: task.result.sha256,
+                },
+            }
+            : {}),
+        ...(task.kind === 'model' ? { model: modelProjection(record, options) } : {}),
+        metadataIncomplete: !diagnostics ||
+            Boolean(diagnostics.updatesDropped) ||
+            (task.kind === 'model' && !diagnostics.model?.runtime),
+        history: {
+            firstRetainedSequence: first,
+            gap: first > 1,
+            omitted: Math.max(0, events.length - 8),
+            events: events.slice(-8).map(event => ({
+                sequence: event.sequence,
+                time: event.time,
+                state: event.state,
+                type: event.type,
+            })),
+        },
+    };
+}
+export function buildDiagnosticReport(host, scope, options, scan, snapshots) {
+    const records = scan.records.filter(record => (!scope.plugin || record.task.plugin === scope.plugin) &&
+        (scope.access !== 'toolbox' || record.access !== 'public') &&
+        (!options.plugin || record.task.plugin === options.plugin) &&
+        (!options.instanceId || record.diagnostics?.page?.instanceId === options.instanceId));
+    const visible = new Map(records.map(record => [record.task.taskId, record]));
+    let selected = records.sort((a, b) => b.task.createdAt - a.task.createdAt || a.task.taskId.localeCompare(b.task.taskId));
+    if (options.taskId) {
+        if (!visible.has(options.taskId))
+            throw Object.assign(new Error('Plugin task was not found'), {
+                code: 'PLUGIN_TASK_NOT_FOUND',
+            });
+        const ids = new Set([options.taskId]), pending = [options.taskId];
+        while (pending.length) {
+            const id = pending.shift(), item = visible.get(id);
+            const candidates = [
+                item.task.parentTaskId,
+                item.task.resumedFrom?.taskId,
+                ...records
+                    .filter(record => record.task.parentTaskId === id || record.task.resumedFrom?.taskId === id)
+                    .map(record => record.task.taskId),
+            ];
+            for (const candidate of candidates)
+                if (candidate && visible.has(candidate) && !ids.has(candidate)) {
+                    ids.add(candidate);
+                    pending.push(candidate);
+                }
+        }
+        selected = [...ids].map(id => visible.get(id));
+    }
+    const generatedAt = Date.now(), chosen = selected.slice(0, 128);
+    const tasks = chosen.map(record => taskProjection(record, options, generatedAt));
+    const pages = snapshots.filter(page => (!scope.plugin || page.plugin === scope.plugin) &&
+        (!options.plugin || page.plugin === options.plugin) &&
+        (!options.instanceId || page.binding.instanceId === options.instanceId) &&
+        (!options.taskId || tasks.some(task => task.page?.instanceId === page.binding.instanceId)));
+    for (const task of tasks)
+        if (task.page && !pages.some(page => page.binding.instanceId === task.page.instanceId))
+            pages.push({
+                plugin: task.plugin,
+                installationId: task.installationId,
+                revision: task.revision,
+                host: task.host,
+                binding: task.page,
+                observation: 'historical-binding',
+            });
+    const report = {
+        version: 1,
+        generatedAt,
+        host: { hostId: host.hostId, epoch: host.epoch },
+        protocolVersion: PLUGIN_TASK_PROTOCOL_VERSION,
+        selection: {
+            ...(options.taskId ? { taskId: options.taskId } : {}),
+            ...(options.plugin ? { plugin: options.plugin } : {}),
+            ...(options.instanceId ? { instanceId: options.instanceId } : {}),
+        },
+        coverage: {
+            scanLimited: scan.limited,
+            tasksOmitted: selected.length - tasks.length,
+            pagesOmitted: Math.max(0, pages.length - 64),
+            byteLimited: false,
+        },
+        tasks,
+        pages: pages.slice(0, 64),
+        links: [],
+    };
+    const links = () => {
+        const retained = new Set(report.tasks.map(task => task.taskId));
+        report.links = report.tasks.flatMap(task => {
+            const record = visible.get(task.taskId);
+            return [
+                ['parent', record.task.parentTaskId],
+                ['resume', record.task.resumedFrom?.taskId],
+            ].flatMap(([kind, from]) => from && retained.has(from) ? [{ from, to: task.taskId, kind }] : []);
+        });
+    };
+    links();
+    while (Buffer.byteLength(JSON.stringify(report)) > MAX_PLUGIN_DIAGNOSTIC_BYTES) {
+        report.coverage.byteLimited = true;
+        if (report.pages.length) {
+            report.pages.pop();
+            report.coverage.pagesOmitted++;
+        }
+        else {
+            report.tasks.pop();
+            report.coverage.tasksOmitted++;
+            links();
+        }
+    }
+    return report;
+}

package/dist/pluginExecution.d.ts

@@ -0,0 +1,21 @@
+import type { PluginExecutionHost, PluginInvocationIdentity, PluginInvocationSource } from './generated-plugin-execution.js';
+import type { PluginApp } from './plugin.js';
+import type { PluginTaskRecoveryContext } from './generated-plugin-recovery.js';
+export type { PluginExecutionHost, PluginInvocationIdentity, PluginInvocationSource };
+export interface PluginCommandContext extends Pick<PluginApp, 'invoke' | 'progress'> {
+    readonly identity: Readonly<PluginInvocationIdentity>;
+    readonly signal: AbortSignal;
+    readonly state: PluginApp['state'];
+    readonly model: PluginApp['model'];
+    readonly recovery?: Readonly<PluginTaskRecoveryContext>;
+    readonly checkpoint: PluginApp['checkpoint'];
+    readonly page?: {
+        send(message: unknown, options?: {
+            timeoutSec?: number;
+        }): Promise<unknown>;
+        get(): Promise<unknown>;
+    };
+}
+/** Exclusive creation gives concurrent browser processes the same environment identity. */
+export declare function localPluginExecutionHost(): PluginExecutionHost;
+export declare function createPluginInvocationIdentity(plugin: string, source: PluginInvocationSource, parent?: PluginInvocationIdentity): PluginInvocationIdentity;

package/dist/pluginExecution.js

@@ -0,0 +1,43 @@
+import { randomUUID } from 'node:crypto';
+import { linkSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { pluginDirectory } from './pluginRegistry.js';
+const epoch = randomUUID();
+const hostIds = new Map();
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+/** Exclusive creation gives concurrent browser processes the same environment identity. */
+export function localPluginExecutionHost() {
+    const directory = pluginDirectory();
+    let hostId = hostIds.get(directory);
+    if (!hostId) {
+        mkdirSync(directory, { recursive: true, mode: 0o700 });
+        const file = join(directory, '.execution-host-id');
+        const proposed = randomUUID();
+        const temporary = `${file}.${proposed}.tmp`;
+        try {
+            writeFileSync(temporary, proposed, { flag: 'wx', mode: 0o600 });
+            linkSync(temporary, file);
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+        }
+        finally {
+            rmSync(temporary, { force: true });
+        }
+        hostId = readFileSync(file, 'utf8').trim();
+        if (!UUID.test(hostId))
+            throw new Error('Invalid plugin execution host identity');
+        hostIds.set(directory, hostId);
+    }
+    return Object.freeze({ hostId, epoch });
+}
+export function createPluginInvocationIdentity(plugin, source, parent) {
+    return Object.freeze({
+        invocationId: randomUUID(),
+        host: parent?.host ?? localPluginExecutionHost(),
+        plugin,
+        source,
+        ...(parent ? { parentInvocationId: parent.invocationId } : {}),
+    });
+}

package/dist/pluginExecutor.d.ts

@@ -0,0 +1,29 @@
+import type { PluginModelDiagnostic, PluginModelRequest } from './generated-plugin-models.js';
+import { type PluginRegistration } from './pluginRegistry.js';
+import type { PluginExecutionContext, PluginInvocation, PluginInvokeOptions } from './plugin.js';
+export interface PluginExecutorDependencies {
+    stopProcessTree?: (pid: number) => Promise<void>;
+    registration?: PluginRegistration;
+}
+export interface PluginExecutorOptions extends PluginInvokeOptions {
+    describe?: boolean;
+    model?: PluginModelRequest;
+    recovery?: boolean;
+    migration?: boolean;
+    expectedRecovery?: string;
+    onDiagnostic?: (metadata: PluginModelDiagnostic) => void;
+    onExecutorStopped?: () => void;
+    onExecutorStarted?: (owner: {
+        pid: number;
+        processIdentity?: string;
+    }) => void;
+    access?: 'public' | 'toolbox' | 'runtime';
+    /** Execution deadline, independent of transport and caller wait timeouts. */
+    executionTimeoutMs?: number;
+    cancellationGraceMs?: number;
+    workerPath?: string;
+    cwd?: string;
+    environment?: NodeJS.ProcessEnv;
+}
+/** Executes registered trusted code in a process whose lifetime belongs to this invocation. */
+export declare function executeRegisteredPlugin(plugin: string, invocation: PluginInvocation, context: PluginExecutionContext, options?: PluginExecutorOptions, dependencies?: PluginExecutorDependencies): Promise<unknown>;

package/dist/pluginExecutor.js

@@ -0,0 +1,223 @@
+import { fork } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { findPluginRegistration, PluginError } from './pluginRegistry.js';
+import { pluginFileVersion } from './pluginSource.js';
+import { createPluginInvocationIdentity } from './pluginExecution.js';
+import { pluginExecutionError, serializePluginExecutionError } from './pluginExecutorProtocol.js';
+import { stopPluginProcessTree } from './pluginProcessTree.js';
+import { processIdentity } from '@mearl/daemon-core';
+/** Executes registered trusted code in a process whose lifetime belongs to this invocation. */
+export async function executeRegisteredPlugin(plugin, invocation, context, options = {}, dependencies = {}) {
+    const { signal, onProgress, source, access = 'public', executionTimeoutMs, cancellationGraceMs = 1000, workerPath, cwd, environment, describe, model, recovery, migration, expectedRecovery, onExecutorStarted, onExecutorStopped, onDiagnostic, ...invokeOptions } = options;
+    for (const [name, value] of [
+        ['executionTimeoutMs', executionTimeoutMs],
+        ['cancellationGraceMs', cancellationGraceMs],
+    ]) {
+        if (value !== undefined && (!Number.isSafeInteger(value) || value < 1 || value > 2_147_483_647))
+            throw new Error(`${name} must be a positive integer within the timer range`);
+    }
+    signal?.throwIfAborted();
+    const registration = dependencies.registration ?? findPluginRegistration(plugin);
+    if (!registration)
+        throw new PluginError('PLUGIN_NOT_REGISTERED', `插件未注册: ${plugin}`);
+    const identity = context.invocation ??
+        createPluginInvocationIdentity(plugin, source ?? context.source ?? 'sdk', context.parentInvocation);
+    const entryVersion = pluginFileVersion(registration.entry);
+    return new Promise((resolve, reject) => {
+        const child = fork(workerPath ?? fileURLToPath(new URL('./plugin-worker.js', import.meta.url)), [], {
+            stdio: ['ignore', 'ignore', 'pipe', 'ipc'],
+            serialization: 'advanced',
+            execArgv: [],
+            detached: process.platform !== 'win32',
+            ...(cwd ? { cwd } : {}),
+            ...(environment ? { env: environment } : {}),
+        });
+        let stderr = '';
+        let outcome;
+        let stopping;
+        let cleanupError;
+        let treeStopRequested = false;
+        let treeCleanup = Promise.resolve();
+        let exited = false;
+        let graceTimer;
+        let deadlineTimer;
+        const pendingActions = new Map();
+        child.stderr?.setEncoding('utf8');
+        child.stderr?.on('data', chunk => {
+            stderr = `${stderr}${chunk}`.slice(-65536);
+        });
+        const send = (message) => {
+            if (!child.connected || exited)
+                return;
+            try {
+                child.send(message, error => {
+                    if (error && !exited)
+                        stop(error);
+                });
+            }
+            catch (error) {
+                stop(error instanceof Error ? error : new Error(String(error)));
+            }
+        };
+        const kill = () => {
+            if (!child.pid || exited || treeStopRequested)
+                return;
+            treeStopRequested = true;
+            const pid = child.pid;
+            treeCleanup = Promise.resolve()
+                .then(() => (dependencies.stopProcessTree ?? stopPluginProcessTree)(pid))
+                .catch(() => {
+                cleanupError = Object.assign(new Error('Unable to confirm plugin process-tree cleanup'), {
+                    code: 'PLUGIN_EXECUTOR_CLEANUP_FAILED',
+                    details: { executionStopped: false },
+                });
+                child.kill('SIGKILL');
+            });
+        };
+        const stop = (error) => {
+            if (stopping || outcome || exited)
+                return;
+            stopping = error;
+            send({ type: 'cancel', error: serializePluginExecutionError(error) });
+            graceTimer = setTimeout(kill, cancellationGraceMs);
+        };
+        const abort = () => stop(Object.assign(new Error('Plugin execution cancelled'), {
+            code: 'PLUGIN_EXECUTION_CANCELLED',
+        }));
+        signal?.addEventListener('abort', abort, { once: true });
+        if (signal?.aborted)
+            abort();
+        if (executionTimeoutMs !== undefined)
+            deadlineTimer = setTimeout(() => stop(Object.assign(new Error('Plugin execution deadline exceeded'), {
+                code: 'PLUGIN_EXECUTION_DEADLINE',
+            })), executionTimeoutMs);
+        child.on('message', (raw) => {
+            if (exited || !raw || typeof raw !== 'object')
+                return;
+            if (raw.type === 'result' || raw.type === 'error') {
+                if (!outcome && !stopping) {
+                    try {
+                        outcome =
+                            raw.type === 'result'
+                                ? { value: JSON.parse(raw.json).value }
+                                : { error: pluginExecutionError(raw.error) };
+                        if (raw.type === 'result' && pendingActions.size)
+                            outcome = {
+                                error: Object.assign(new Error('Plugin returned with pending host calls'), {
+                                    code: 'PLUGIN_PENDING_HOST_CALLS',
+                                    details: { pendingActions: [...pendingActions.values()] },
+                                }),
+                            };
+                    }
+                    catch (error) {
+                        stop(error instanceof Error ? error : new Error(String(error)));
+                    }
+                }
+                kill();
+                return;
+            }
+            if (stopping || outcome)
+                return;
+            if (raw.type === 'diagnostic' && model) {
+                try {
+                    onDiagnostic?.(raw.metadata);
+                }
+                catch (error) {
+                    stop(error instanceof Error ? error : new Error(String(error)));
+                }
+            }
+            else if (raw.type === 'progress') {
+                try {
+                    onProgress?.(raw.progress);
+                }
+                catch (error) {
+                    stop(error instanceof Error ? error : new Error(String(error)));
+                }
+            }
+            else if (raw.type === 'invoke') {
+                pendingActions.set(raw.id, raw.action);
+                void Promise.resolve()
+                    .then(() => {
+                    if (stopping || exited)
+                        throw stopping ?? new Error('Plugin execution ended');
+                    const options = { ...invokeOptions, ...raw.options };
+                    if (!raw.stream)
+                        return context.invoke(raw.action, raw.payload, options);
+                    return context.invoke(raw.action, raw.payload, options, progress => {
+                        if (!stopping && !outcome && pendingActions.has(raw.id))
+                            send({ type: 'invoke-progress', id: raw.id, progress });
+                    });
+                })
+                    .then(result => send({ type: 'response', id: raw.id, result }), error => send({ type: 'response', id: raw.id, error: serializePluginExecutionError(error) }))
+                    .finally(() => pendingActions.delete(raw.id));
+            }
+        });
+        const cleanup = () => {
+            exited = true;
+            signal?.removeEventListener('abort', abort);
+            if (graceTimer)
+                clearTimeout(graceTimer);
+            if (deadlineTimer)
+                clearTimeout(deadlineTimer);
+        };
+        child.once('error', error => {
+            cleanup();
+            reject(error);
+        });
+        child.once('exit', () => {
+            kill();
+            child.stderr?.destroy();
+        });
+        child.once('close', (code, exitSignal) => {
+            cleanup();
+            void treeCleanup.then(() => {
+                if (!cleanupError && treeStopRequested) {
+                    try {
+                        onExecutorStopped?.();
+                    }
+                    catch (error) {
+                        reject(error);
+                        return;
+                    }
+                }
+                if (cleanupError)
+                    reject(cleanupError);
+                else if (stopping) {
+                    Object.assign(stopping, {
+                        details: { pendingActions: [...pendingActions.values()], executionStopped: true },
+                    });
+                    reject(stopping);
+                }
+                else if (outcome?.error)
+                    reject(outcome.error);
+                else if (outcome)
+                    resolve(outcome.value);
+                else
+                    reject(Object.assign(new Error(stderr.trim() || `Plugin executor exited (${code ?? exitSignal})`), { code: 'PLUGIN_EXECUTOR_EXITED' }));
+            });
+        });
+        try {
+            if (child.pid)
+                onExecutorStarted?.({ pid: child.pid, processIdentity: processIdentity(child.pid) });
+            send({
+                type: 'start',
+                plugin,
+                invocation,
+                options: invokeOptions,
+                identity,
+                entry: registration.entry,
+                entryVersion,
+                access,
+                describe,
+                model,
+                recovery,
+                migration,
+                expectedRecovery,
+                ...(dependencies.registration ? { registration } : {}),
+            });
+        }
+        catch (error) {
+            stop(error instanceof Error ? error : new Error(String(error)));
+        }
+    });
+}