@mearl/client 2.20.5 → 2.21.0

package/dist/plugin.js

@@ -1,3 +1,6 @@
+import { normalizePluginState, pluginStateSignature } from './pluginStateDefinition.js';
+import { normalizePluginTaskRecovery, pluginRecoverySignature, } from './pluginRecoveryDefinition.js';
+import { normalizePluginPageRuntime } from './pluginPageDefinition.js';
 import { loadPluginAppProfiles } from './pluginAppProfiles.js';
 export { invokePageEvalWithArgs } from './pageEvalArguments.js';
 import { readFileSync } from 'node:fs';
@@ -10,7 +13,12 @@ import { ensureOfficialPluginRegistered, } from './officialPluginInstaller.js';
 import { findPluginRegistration, pluginRegistrationNeedsRefresh, registerPlugin, pluginDirectory, normalizePluginToolboxContribution, PluginError, } from './pluginRegistry.js';
 import { pluginFileVersion } from './pluginSource.js';
 import { describePythonPlugin, runPythonPluginCommand } from './pythonPlugin.js';
-export { assertPluginName, findPluginDirectoryEntry, findPluginEntry, findPluginRegistration, listPluginNames, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, readPluginPageBundleChunk, } from './pluginRegistry.js';
+import { createPluginInvocationIdentity, } from './pluginExecution.js';
+export { executeRegisteredPlugin, } from './pluginExecutor.js';
+export { PluginTaskClient } from './pluginTasks.js';
+export { cleanupPluginRuntime } from './pluginRuntimeCleanup.js';
+export { PluginPageClient } from './pluginPages.js';
+export { assertPluginName, findPluginDirectoryEntry, findPluginEntry, findPluginRegistration, listPluginNames, pluginDirectory, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, readPluginPageBundleChunk, } from './pluginRegistry.js';
 export { findOfficialPlugin, listOfficialPluginNames, OFFICIAL_PLUGIN_MANAGER, OFFICIAL_PLUGINS, } from './officialPluginCatalog.js';
 function readPluginVersion(entry) {
     try {
@@ -107,6 +115,7 @@ export async function refreshRegisteredPlugin(name, includePage = false) {
             throw new PluginError('PLUGIN_SOURCE_CHANGED', `插件更新进行中，请重新打开工具: ${name}`);
         }
         registerPlugin(name, registration.entry, loaded.description, {
+            hasPublicCommands: 'commandHelp' in loaded ? Boolean(loaded.commandHelp(name)) : loaded.hasPublicCommands,
             toolbox: loaded.toolbox,
             appProfiles: loaded.appProfiles,
             profileSources: 'profileSources' in loaded ? loaded.profileSources : loaded.source?.profiles,
@@ -132,14 +141,21 @@ export async function loadPlugin(entry, context, pluginName) {
         throw new PluginError('PLUGIN_ENTRY_MISSING', missingPluginEntryMessage(entry, pluginName));
     }
     const commands = new Map();
+    const recoveries = new Map();
+    const migrations = new Map();
     let executing = false;
+    let checkpointDeclaration;
+    let invocationGeneration = 0;
     let registering = true;
     let name;
     let description;
     let toolbox;
+    let pageRuntime;
+    let stateStorage;
+    let taskRecovery;
     let appProfiles;
     let profileSources;
-    const registerCommand = (signature, handler, description = '', examples = [], toolboxOnly = false) => {
+    const registerCommand = (signature, handler, description = '', examples = [], toolboxOnly = false, runtimeOnly = false) => {
         if (!registering)
             throw new Error('命令只能在入口注册阶段声明');
         const [name, ...args] = signature.trim().split(/\s+/);
@@ -160,15 +176,99 @@ export async function loadPlugin(entry, context, pluginName) {
         const names = command.registeredArguments.map(argument => argument.name());
         if (new Set(names).size !== names.length)
             throw new Error(`参数名称重复: ${signature}`);
-        commands.set(name, { command, signature, handler, examples: [...examples], toolboxOnly });
+        commands.set(name, {
+            command,
+            signature,
+            handler,
+            examples: [...examples],
+            toolboxOnly,
+            runtimeOnly,
+        });
     };
     const app = Object.freeze({
         options: Object.freeze({ ...context.options }),
         command: (signature, handler, description = '', examples = []) => registerCommand(signature, handler, description, examples),
+        runtimeCommand: (signature, handler, description = '', examples = []) => registerCommand(signature, handler, description, examples, false, true),
+        recoveryCommand(command, handler) {
+            if (!registering ||
+                !/^[a-z][a-z0-9-]*$/.test(command) ||
+                typeof handler !== 'function' ||
+                recoveries.has(command))
+                throw new Error('Invalid or duplicate recovery command');
+            recoveries.set(command, handler);
+        },
+        checkpointMigration(command, handler) {
+            if (!registering ||
+                !/^[a-z][a-z0-9-]*$/.test(command) ||
+                typeof handler !== 'function' ||
+                migrations.has(command))
+                throw new Error('Invalid or duplicate checkpoint migration');
+            migrations.set(command, (input, commandContext) => handler(input, commandContext));
+        },
+        checkpoint(data, expectedSequence) {
+            if (!executing || !context.invocation?.taskId)
+                throw new PluginError('PLUGIN_TASK_REQUIRED', 'Checkpoints require a managed task');
+            context.signal?.throwIfAborted();
+            return context.invoke('plugin_task_checkpoint', {
+                plugin: pluginName ?? name,
+                data,
+                expectedSequence,
+                expectedDeclaration: checkpointDeclaration,
+            });
+        },
+        state(collection, operation, input = {}) {
+            if (!executing)
+                throw new Error('app.state is only available during command execution');
+            context.signal?.throwIfAborted();
+            if (!stateStorage || !Object.hasOwn(stateStorage.collections, collection))
+                throw new PluginError('PLUGIN_STATE_NOT_DECLARED', 'Plugin state collection is not declared');
+            return context.invoke('plugin_state', {
+                ...input,
+                plugin: pluginName ?? name,
+                collection,
+                operation,
+                expectedDeclaration: pluginStateSignature(stateStorage.collections[collection]),
+            });
+        },
+        model(request, options = {}) {
+            if (!executing)
+                throw new Error('app.model is only available during command execution');
+            context.signal?.throwIfAborted();
+            const generation = invocationGeneration;
+            const observing = () => executing && generation === invocationGeneration && !context.signal?.aborted;
+            if (context.runModel)
+                return context.runModel(pluginName ?? name, request, {
+                    signal: context.signal,
+                    onProgress: progress => {
+                        if (!observing())
+                            return;
+                        context.progress(progress);
+                        options.onProgress?.(progress);
+                    },
+                });
+            const payload = {
+                plugin: pluginName ?? name,
+                operation: 'run',
+                request,
+            };
+            return (options.onProgress
+                ? context.invoke('plugin_model', payload, {}, progress => {
+                    if (observing())
+                        options.onProgress?.(progress);
+                })
+                : context.invoke('plugin_model', payload));
+        },
+        page(operation, input = {}) {
+            if (!executing)
+                throw new Error('app.page is only available during command execution');
+            context.signal?.throwIfAborted();
+            return context.invoke('plugin_page', { ...input, plugin: pluginName ?? name, operation });
+        },
         toolboxCommand: (signature, handler, description = '', examples = []) => registerCommand(signature, handler, description, examples, true),
         invoke(action, payload = {}, options = {}) {
             if (!executing)
                 throw new Error('app.invoke 只能在命令执行期间调用');
+            context.signal?.throwIfAborted();
             return context.invoke(action, payload, options);
         },
         progress(progress) {
@@ -183,11 +283,26 @@ export async function loadPlugin(entry, context, pluginName) {
             name = descriptor.name;
             description = descriptor.description;
             toolbox = normalizePluginToolboxContribution(descriptor.toolbox);
+            pageRuntime = normalizePluginPageRuntime(descriptor.pageRuntime);
+            stateStorage = normalizePluginState(descriptor.stateStorage);
+            taskRecovery = normalizePluginTaskRecovery(descriptor.taskRecovery);
             ({ appProfiles, profileSources } = loadPluginAppProfiles(entry, descriptor.appProfiles));
             for (const command of descriptor.commands) {
                 const commandName = command.signature.trim().split(/\s+/)[0];
-                const register = command.toolboxOnly ? app.toolboxCommand : app.command;
-                register(command.signature, input => runPythonPluginCommand(entry, commandName, input, app), command.description);
+                if (command.migrationOnly) {
+                    app.checkpointMigration(commandName, (input, commandContext) => runPythonPluginCommand(entry, commandName, input, app, commandContext, 'migration', descriptor));
+                    continue;
+                }
+                if (command.recoveryOnly) {
+                    app.recoveryCommand(commandName, (input, commandContext) => runPythonPluginCommand(entry, commandName, input, app, commandContext, true, descriptor));
+                    continue;
+                }
+                const register = command.runtimeOnly
+                    ? app.runtimeCommand
+                    : command.toolboxOnly
+                        ? app.toolboxCommand
+                        : app.command;
+                register(command.signature, (input, commandContext) => runPythonPluginCommand(entry, commandName, input, app, commandContext, false, descriptor, command.runtimeOnly), command.description);
             }
         }
         else {
@@ -201,6 +316,9 @@ export async function loadPlugin(entry, context, pluginName) {
                 throw new Error('入口的 description 导出必须为字符串');
             description = module.description;
             toolbox = normalizePluginToolboxContribution(module.toolbox);
+            pageRuntime = normalizePluginPageRuntime(module.pageRuntime);
+            stateStorage = normalizePluginState(module.stateStorage);
+            taskRecovery = normalizePluginTaskRecovery(module.taskRecovery);
             ({ appProfiles, profileSources } = loadPluginAppProfiles(entry, module.appProfiles));
             if (module.default !== undefined && typeof module.default !== 'function')
                 throw new Error('入口必须默认导出 register(app) 函数');
@@ -211,6 +329,33 @@ export async function loadPlugin(entry, context, pluginName) {
         }
         if (commands.size === 0 && !appProfiles)
             throw new Error('入口未注册任何命令');
+        for (const command of Object.keys(taskRecovery?.commands ?? {})) {
+            if (!commands.has(command) ||
+                commands.get(command)?.runtimeOnly ||
+                commands.get(command)?.toolboxOnly ||
+                !recoveries.has(command))
+                throw new Error(`Recovery requires a command and recoveryCommand: ${command}`);
+        }
+        for (const command of recoveries.keys())
+            if (!Object.hasOwn(taskRecovery?.commands ?? {}, command))
+                throw new Error(`Undeclared recovery command: ${command}`);
+        for (const [command, definition] of Object.entries(taskRecovery?.commands ?? {})) {
+            if (Boolean(definition.migrateFrom?.length) !== migrations.has(command))
+                throw new Error(`Checkpoint migrations require a declaration and checkpointMigration: ${command}`);
+        }
+        for (const command of migrations.keys())
+            if (!Object.hasOwn(taskRecovery?.commands ?? {}, command))
+                throw new Error(`Undeclared checkpoint migration: ${command}`);
+        const runtimeCommands = new Set(Object.values(pageRuntime?.events ?? {}).map(event => event.command));
+        if (pageRuntime?.initialize)
+            runtimeCommands.add(pageRuntime.initialize);
+        for (const [name, command] of commands) {
+            if (command.runtimeOnly && !runtimeCommands.has(name))
+                throw new Error(`runtimeCommand is not declared in pageRuntime.events: ${name}`);
+        }
+        for (const name of runtimeCommands)
+            if (!commands.has(name) || commands.get(name)?.toolboxOnly)
+                throw new Error(`Invalid page runtime command: ${name}`);
         const toolboxCommands = toolbox?.page.commands ?? [];
         for (const [name, command] of commands) {
             if (command.toolboxOnly && !toolboxCommands.includes(name)) {
@@ -232,7 +377,16 @@ export async function loadPlugin(entry, context, pluginName) {
         const command = commands.get(name);
         if (!command)
             throw new PluginError('PLUGIN_COMMAND_NOT_FOUND', `未知子命令: ${name}`);
-        if (toolboxPage) {
+        if (toolboxPage === 'runtime') {
+            if (!(pageRuntime?.initialize === name ||
+                Object.values(pageRuntime?.events ?? {}).some(event => event.command === name)) ||
+                command.toolboxOnly)
+                throw new PluginError('PLUGIN_COMMAND_NOT_ALLOWED', 'Page runtime command is not declared');
+        }
+        else if (command.runtimeOnly) {
+            throw new PluginError('PLUGIN_COMMAND_RUNTIME_ONLY', `命令仅供页面运行时调用: ${name}`);
+        }
+        else if (toolboxPage) {
             if (!toolbox?.page.commands.includes(name)) {
                 throw new PluginError('PLUGIN_COMMAND_NOT_ALLOWED', `工具页面不允许调用命令: ${name}`);
             }
@@ -242,7 +396,7 @@ export async function loadPlugin(entry, context, pluginName) {
         }
         return command;
     };
-    const publicCommands = () => [...commands.values()].filter(command => !command.toolboxOnly);
+    const publicCommands = () => [...commands.values()].filter(command => !command.toolboxOnly && !command.runtimeOnly);
     const run = async (positionals, payload, namedInput = {}, toolboxPage = false) => {
         if (payload !== undefined && positionals.length > 0) {
             throw new PluginError('PLUGIN_INVALID_INPUT', '位置参数调用与 --payload 调用不能混用');
@@ -255,7 +409,21 @@ export async function loadPlugin(entry, context, pluginName) {
             throw new PluginError('PLUGIN_INVALID_INPUT', '--payload 必须为 {"command":"...","input":{...}}');
         }
         const envelope = payload;
-        const { command, handler } = find(envelope?.command ?? positionals[0] ?? '', toolboxPage);
+        const commandName = envelope?.command ?? positionals[0] ?? '';
+        const hidden = toolboxPage === 'recovery' || toolboxPage === 'migration';
+        const selected = find(commandName, hidden ? false : toolboxPage);
+        const command = selected.command;
+        const handler = toolboxPage === 'recovery'
+            ? recoveries.get(commandName)
+            : toolboxPage === 'migration'
+                ? migrations.get(commandName)
+                : selected.handler;
+        if (!handler || (toolboxPage === 'recovery' && !context.invocation?.recovery))
+            throw new PluginError('PLUGIN_TASK_RECOVERY_UNAVAILABLE', 'Recovery handler requires a managed recovery attempt');
+        if (toolboxPage === 'recovery' &&
+            context.invocation?.recovery?.declarationHash !==
+                pluginRecoverySignature(taskRecovery.commands[commandName]))
+            throw new PluginError('PLUGIN_RECOVERY_DECLARATION_CHANGED', 'Recovery declaration differs from the admitted format');
         const positionalInput = envelope
             ? { ...envelope.input }
             : Object.fromEntries(command.registeredArguments
@@ -275,7 +443,7 @@ export async function loadPlugin(entry, context, pluginName) {
             positionals.length - 1 > command.registeredArguments.length) {
             throw new PluginError('PLUGIN_INVALID_INPUT', '位置参数过多');
         }
-        for (const argument of command.registeredArguments) {
+        for (const argument of hidden ? [] : command.registeredArguments) {
             const value = Object.hasOwn(input, argument.name()) ? input[argument.name()] : undefined;
             if (argument.required &&
                 (value === undefined ||
@@ -288,18 +456,86 @@ export async function loadPlugin(entry, context, pluginName) {
                 throw new PluginError('PLUGIN_INVALID_INPUT', `${argument.name()} 必须为数组`);
             }
         }
+        if (executing)
+            throw new PluginError('PLUGIN_BUSY', '同一命令实例不能并发执行');
+        const signal = context.signal ?? new AbortController().signal;
+        signal.throwIfAborted();
+        const identity = context.invocation ??
+            createPluginInvocationIdentity(pluginName ?? name ?? 'unregistered', context.source ?? 'sdk', context.parentInvocation);
+        const generation = ++invocationGeneration;
+        const assertActive = () => {
+            if (!executing || generation !== invocationGeneration)
+                throw new PluginError('PLUGIN_INVOCATION_ENDED', '命令调用已结束');
+            signal.throwIfAborted();
+        };
+        const commandContext = Object.freeze({
+            identity,
+            signal,
+            ...(identity.recovery ? { recovery: structuredClone(identity.recovery) } : {}),
+            checkpoint: (data, expectedSequence) => {
+                assertActive();
+                return app.checkpoint(data, expectedSequence);
+            },
+            ...(identity.page
+                ? {
+                    page: Object.freeze({
+                        send: (message, options = {}) => {
+                            assertActive();
+                            return app.page('send', {
+                                instanceId: identity.page.instanceId,
+                                message,
+                                ...(options.timeoutSec !== undefined ? { timeoutSec: options.timeoutSec } : {}),
+                            });
+                        },
+                        get: () => {
+                            assertActive();
+                            return app.page('get', { instanceId: identity.page.instanceId });
+                        },
+                    }),
+                }
+                : {}),
+            invoke: (action, payload, options) => {
+                assertActive();
+                return app.invoke(action, payload, options);
+            },
+            state: (collection, operation, input) => {
+                assertActive();
+                return app.state(collection, operation, {
+                    ...(identity.page ? { instanceId: identity.page.instanceId } : {}),
+                    ...input,
+                });
+            },
+            model: (request, options) => {
+                assertActive();
+                return app.model(request, options);
+            },
+            progress: progress => {
+                assertActive();
+                app.progress(progress);
+            },
+        });
+        checkpointDeclaration =
+            taskRecovery && Object.hasOwn(taskRecovery.commands, commandName)
+                ? pluginRecoverySignature(taskRecovery.commands[commandName])
+                : undefined;
         executing = true;
+        context.onInvocation?.(identity);
         try {
-            return await handler(input);
+            return await handler(input, commandContext);
         }
         finally {
             executing = false;
+            checkpointDeclaration = undefined;
+            context.onInvocation?.(undefined);
         }
     };
     return {
         name,
         description,
         toolbox,
+        pageRuntime,
+        stateStorage,
+        taskRecovery,
         appProfiles,
         profileSources,
         version: readPluginVersion(entry),
@@ -310,6 +546,12 @@ export async function loadPlugin(entry, context, pluginName) {
         },
         help(namespace, name) {
             const selected = name ? [find(name)] : publicCommands();
+            if (!selected.length) {
+                const location = toolbox
+                    ? `请在 Mearl ${toolbox.displayMode === 'popup' ? 'Popup' : '工具箱'} 中打开「${toolbox.title}」使用。`
+                    : '此插件未提供公开 CLI 命令。';
+                return `${namespace} 未提供 CLI 命令。\n${location}`;
+            }
             const examples = selected.flatMap(({ examples }) => examples);
             return [
                 '用法：',
@@ -322,6 +564,15 @@ export async function loadPlugin(entry, context, pluginName) {
         run(positionals, payload, namedInput = {}) {
             return run(positionals, payload, namedInput);
         },
+        runRuntime(invocation) {
+            return run([], invocation, {}, 'runtime');
+        },
+        runRecovery(invocation) {
+            return run([], invocation, {}, 'recovery');
+        },
+        runMigration(invocation) {
+            return run([], invocation, {}, 'migration');
+        },
         runToolbox(invocation) {
             return run([], invocation, {}, true);
         },
@@ -331,7 +582,9 @@ async function loadRegisteredPluginWithState(name, context, options = {}, state
     if (state.stack.includes(name)) {
         throw new PluginError('PLUGIN_INVOCATION_CYCLE', `插件调用形成循环: ${[...state.stack, name].join(' -> ')}`);
     }
-    let registration = findPluginRegistration(name);
+    let registration = context.resolveRegistration
+        ? context.resolveRegistration(name)
+        : findPluginRegistration(name);
     if (!registration && findOfficialPlugin(name)) {
         await (context.ensurePlugin ?? ensureOfficialPluginRegistered)(name, options.onProgress ? message => options.onProgress?.(message) : undefined);
         registration = findPluginRegistration(name);
@@ -339,12 +592,21 @@ async function loadRegisteredPluginWithState(name, context, options = {}, state
     if (!registration) {
         throw new PluginError('PLUGIN_NOT_REGISTERED', `插件未注册: ${name}`);
     }
-    const { onProgress, ...invokeOptions } = options;
+    const { onProgress, signal, source, ...invokeOptions } = options;
     const childState = { stack: [...state.stack, name] };
+    let activeInvocation;
     return loadPlugin(registration.entry, {
         options: invokeOptions,
+        source: source ?? context.source,
+        parentInvocation: context.parentInvocation,
+        invocation: context.invocation,
+        signal,
+        runModel: context.runModel,
+        onInvocation: identity => {
+            activeInvocation = identity;
+        },
         progress: onProgress ?? (() => undefined),
-        async invoke(action, payload, overrides) {
+        async invoke(action, payload, overrides, progress) {
             const nestedOptions = {
                 ...invokeOptions,
                 ...overrides,
@@ -361,12 +623,21 @@ async function loadRegisteredPluginWithState(name, context, options = {}, state
                 if (!pluginInvocation) {
                     throw new PluginError('PLUGIN_INVALID_INPUT', `调用插件 ${action} 需要 {"command":"...","input":{...}}`);
                 }
-                return invokeRegisteredPluginWithState(action, payload, context, {
+                if (activeInvocation?.taskId) {
+                    if (!findPluginRegistration(action) && findOfficialPlugin(action))
+                        await (context.ensurePlugin ?? ensureOfficialPluginRegistered)(action);
+                    return context.invoke('plugin_invoke_child', { plugin: action, invocation: payload }, nestedOptions);
+                }
+                return invokeRegisteredPluginWithState(action, payload, { ...context, invocation: undefined, parentInvocation: activeInvocation }, {
                     ...nestedOptions,
                     ...(onProgress ? { onProgress } : {}),
+                    ...(signal ? { signal } : {}),
+                    ...(source ? { source } : {}),
                 }, childState);
             }
-            const result = await context.invoke(action, payload, nestedOptions);
+            const result = await (progress
+                ? context.invoke(action, payload, nestedOptions, progress)
+                : context.invoke(action, payload, nestedOptions));
             if (result?.action?.success === false) {
                 throw new Error(result.action.error || `${action} failed`);
             }
@@ -389,3 +660,13 @@ export async function invokeRegisteredToolboxPlugin(name, invocation, context, o
     const plugin = await loadRegisteredPluginWithState(name, context, options);
     return plugin.runToolbox(invocation);
 }
+export async function invokeRegisteredRuntimePlugin(name, invocation, context, options = {}) {
+    const plugin = await loadRegisteredPluginWithState(name, context, options);
+    return plugin.runRuntime(invocation);
+}
+export async function invokeRegisteredRecoveryPlugin(name, invocation, context, options = {}) {
+    const plugin = await loadRegisteredPluginWithState(name, context, options);
+    return plugin.runRecovery(invocation);
+}
+export { PluginStateClient } from './pluginState.js';
+export { PluginModelClient } from './pluginModels.js';

package/dist/pluginCliOutput.d.ts

@@ -0,0 +1,2 @@
+/** CLI host commands share the SDK error code without exporting arbitrary error metadata. */
+export declare function writePluginCliError(error: unknown): void;

package/dist/pluginCliOutput.js

@@ -0,0 +1,7 @@
+/** CLI host commands share the SDK error code without exporting arbitrary error metadata. */
+export function writePluginCliError(error) {
+    const code = error && typeof error === 'object' && 'code' in error && typeof error.code === 'string'
+        ? error.code
+        : 'PLUGIN_HOST_ERROR';
+    process.stderr.write(`${JSON.stringify({ error: { code, message: error instanceof Error ? error.message : String(error) } })}\n`);
+}

package/dist/pluginCommandWorker.d.ts

@@ -0,0 +1,2 @@
+import type { PluginWorkerRequest } from './pluginExecutorProtocol.js';
+export declare function handlePluginWorkerMessage(message: PluginWorkerRequest): void;

package/dist/pluginCommandWorker.js

@@ -0,0 +1,174 @@
+import { pluginRecoverySignature } from './pluginRecoveryDefinition.js';
+import { loadPlugin, findPluginRegistration, invokeRegisteredPlugin, invokeRegisteredToolboxPlugin, invokeRegisteredRuntimePlugin, invokeRegisteredRecoveryPlugin, } from './plugin.js';
+import { pluginFileVersion } from './pluginSource.js';
+import { MAX_PLUGIN_RESULT_BYTES, pluginExecutionError, serializePluginExecutionError, } from './pluginExecutorProtocol.js';
+const controller = new AbortController();
+const pending = new Map();
+let sequence = 0;
+let started = false;
+let completed = false;
+function send(event) {
+    return new Promise((resolve, reject) => {
+        if (!process.connected || !process.send) {
+            reject(new Error('Plugin executor disconnected'));
+            return;
+        }
+        process.send(event, error => (error ? reject(error) : resolve()));
+    });
+}
+async function run(message) {
+    try {
+        const registration = message.registration ?? findPluginRegistration(message.plugin);
+        if (registration?.entry !== message.entry ||
+            pluginFileVersion(message.entry) !== message.entryVersion)
+            throw Object.assign(new Error('Plugin source changed before execution'), {
+                code: 'PLUGIN_SOURCE_CHANGED',
+            });
+        const invokePlugin = message.recovery
+            ? invokeRegisteredRecoveryPlugin
+            : message.access === 'runtime'
+                ? invokeRegisteredRuntimePlugin
+                : message.access === 'toolbox'
+                    ? invokeRegisteredToolboxPlugin
+                    : invokeRegisteredPlugin;
+        const declaration = message.describe
+            ? await loadPlugin(message.entry, {
+                options: {},
+                progress: () => { },
+                invoke: async () => {
+                    throw new Error('Host actions are unavailable during runtime declaration');
+                },
+            }, message.plugin)
+            : undefined;
+        const migration = message.migration
+            ? await loadPlugin(message.entry, {
+                options: {},
+                signal: controller.signal,
+                progress: () => { },
+                invoke: async () => {
+                    throw Object.assign(new Error('Checkpoint migration cannot invoke host actions or plugins'), { code: 'PLUGIN_CHECKPOINT_MIGRATION_HOST_CALL' });
+                },
+            }, message.plugin)
+            : undefined;
+        if (migration) {
+            const definitions = migration.taskRecovery?.commands;
+            const definition = definitions && Object.hasOwn(definitions, message.invocation.command)
+                ? definitions[message.invocation.command]
+                : undefined;
+            if (!definition ||
+                !message.expectedRecovery ||
+                pluginRecoverySignature(definition) !== message.expectedRecovery)
+                throw Object.assign(new Error('Migration declaration differs from the admitted target format'), { code: 'PLUGIN_RECOVERY_DECLARATION_CHANGED' });
+        }
+        const value = migration
+            ? await migration.runMigration(message.invocation)
+            : declaration
+                ? {
+                    pageRuntime: declaration.pageRuntime,
+                    stateStorage: declaration.stateStorage,
+                    taskRecovery: declaration.taskRecovery,
+                }
+                : message.model
+                    ? await (await import('@mearl/agent-runtime/codex')).runCodexModel(message.model, {
+                        signal: controller.signal,
+                        cwd: process.cwd(),
+                        onDiagnostic: metadata => {
+                            void send({ type: 'diagnostic', metadata }).catch(() => process.exit(1));
+                        },
+                        onDelta: (delta, index, metadata) => {
+                            void send({
+                                type: 'progress',
+                                progress: {
+                                    message: 'model.delta',
+                                    data: { delta, index, ...metadata, partial: true },
+                                },
+                            }).catch(() => process.exit(1));
+                        },
+                    })
+                    : await invokePlugin(message.plugin, message.invocation, {
+                        invocation: Object.freeze({
+                            ...message.identity,
+                            host: Object.freeze(message.identity.host),
+                        }),
+                        ...(message.registration
+                            ? {
+                                resolveRegistration: (name) => name === message.plugin
+                                    ? message.registration
+                                    : findPluginRegistration(name),
+                            }
+                            : {}),
+                        invoke: (action, payload = {}, options = {}, onProgress) => {
+                            controller.signal.throwIfAborted();
+                            const id = ++sequence;
+                            return new Promise((resolve, reject) => {
+                                pending.set(id, { resolve, reject, onProgress });
+                                void send({
+                                    type: 'invoke',
+                                    id,
+                                    action,
+                                    payload,
+                                    options,
+                                    ...(onProgress ? { stream: true } : {}),
+                                }).catch(error => {
+                                    pending.delete(id);
+                                    reject(error);
+                                });
+                            });
+                        },
+                    }, {
+                        ...message.options,
+                        signal: controller.signal,
+                        source: message.identity.source,
+                        onProgress: progress => {
+                            void send({ type: 'progress', progress }).catch(() => process.exit(1));
+                        },
+                    });
+        // Business results use a separate lossless channel; diagnostics never supply the result.
+        const json = JSON.stringify({ value });
+        if (Buffer.byteLength(json) > (message.migration ? 64 * 1024 : MAX_PLUGIN_RESULT_BYTES))
+            throw Object.assign(new Error('Plugin result exceeds the execution result limit'), {
+                code: 'PLUGIN_RESULT_TOO_LARGE',
+            });
+        await send({ type: 'result', json });
+        completed = true;
+    }
+    catch (error) {
+        await send({ type: 'error', error: serializePluginExecutionError(error) }).catch(() => { });
+        completed = true;
+    }
+}
+export function handlePluginWorkerMessage(message) {
+    if (message.type === 'start') {
+        if (started)
+            return;
+        started = true;
+        void run(message);
+    }
+    else if (message.type === 'cancel') {
+        if (completed)
+            return;
+        const error = pluginExecutionError(message.error);
+        controller.abort(error);
+        for (const request of pending.values())
+            request.reject(error);
+        pending.clear();
+    }
+    else if (message.type === 'invoke-progress') {
+        const request = pending.get(message.id);
+        try {
+            request?.onProgress?.(message.progress);
+        }
+        catch (error) {
+            pending.delete(message.id);
+            request?.reject(error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+    else if (message.type === 'response') {
+        const request = pending.get(message.id);
+        pending.delete(message.id);
+        if (message.error)
+            request?.reject(pluginExecutionError(message.error));
+        else
+            request?.resolve(message.result);
+    }
+}