@mearl/client 2.20.6 → 2.22.0

package/dist/{pythonPlugin.js → plugins/runtime/pythonPlugin.js}

@@ -1,6 +1,8 @@
+import { pluginRecoverySignature } from '../sdk/pluginRecoveryDefinition.js';
 import { spawn } from 'node:child_process';
 import { createInterface } from 'node:readline';
-import { PluginError } from './pluginRegistry.js';
+import { PluginError } from '../pluginRegistry.js';
+import { pluginExecutionError, serializePluginExecutionError } from './pluginExecutorProtocol.js';
 const STDERR_LIMIT = 64 * 1024;
 // Bootstrap 随 Node client 分发，Python 插件无需额外安装宿主 SDK。
 const PYTHON_BOOTSTRAP = String.raw `
@@ -9,6 +11,7 @@ import importlib.util
 import inspect
 import json
 import os
+import signal
 import sys
 from types import MappingProxyType
 
@@ -20,6 +23,9 @@ def _send(message):
     encoded = json.dumps(message, ensure_ascii=False, allow_nan=False, separators=(",", ":"))
     _protocol_output.write(encoded + "\n")
     _protocol_output.flush()
+    if message.get("type") in ("result", "error"):
+        if _receive().get("type") != "terminal_ack":
+            raise RuntimeError("Mearl 宿主未确认执行终态")
 
 
 def _receive():
@@ -38,10 +44,54 @@ def _resolve(value):
     return value
 
 
+class _Signal:
+    def __init__(self):
+        self.aborted = False
+
+    def throw_if_aborted(self):
+        if self.aborted:
+            raise RuntimeError("插件命令已取消")
+
+
+class _CommandContext:
+    def __init__(self, app, identity):
+        self.identity = MappingProxyType({**identity, "host": MappingProxyType(identity["host"])})
+        self.signal = _Signal()
+        self.invoke = app.invoke
+        self.progress = app.progress
+        self.state = lambda collection, operation, payload=None: app.state(collection, operation, {**({"instanceId": identity["page"]["instanceId"]} if identity.get("page") else {}), **(payload or {})})
+        self.model = app.model
+        self.checkpoint = app.checkpoint
+        self.recovery = identity.get("recovery")
+        self.page = _BoundPage(app, identity["page"]["instanceId"]) if identity.get("page") else None
+        app.identity = identity
+
+    def cancel(self, *_):
+        self.signal.aborted = True
+        self.signal.throw_if_aborted()
+
+
+class _BoundPage:
+    def __init__(self, app, instance_id):
+        self._app = app
+        self._instance_id = instance_id
+
+    def send(self, message, options=None):
+        return self._app.page("send", {"instanceId": self._instance_id, "message": message, **({"timeoutSec": options["timeoutSec"]} if options and "timeoutSec" in options else {})})
+
+    def get(self):
+        return self._app.page("get", {"instanceId": self._instance_id})
+
+
 class _InvocationError(RuntimeError):
-    def __init__(self, message, code=None):
+    def __init__(self, message, code=None, details=None, metadata=None):
         super().__init__(message)
         self.code = code
+        self.details = details
+        self.metadata = metadata
+        for key, value in (metadata or {}).items():
+            if not key.startswith("_") and key not in ("code", "details", "metadata"):
+                setattr(self, key, value)
 
 
 class _App:
@@ -51,6 +101,8 @@ class _App:
         self.registering = True
         self.executing = False
         self.request_id = 0
+        self.responses = {}
+        self.observers = {}
 
     def command(self, signature, handler=None, description=""):
         return self._register_command(signature, handler, description, False)
@@ -58,7 +110,16 @@ class _App:
     def toolboxCommand(self, signature, handler=None, description=""):
         return self._register_command(signature, handler, description, True)
 
-    def _register_command(self, signature, handler, description, toolbox_only):
+    def runtimeCommand(self, signature, handler=None, description=""):
+        return self._register_command(signature, handler, description, False, runtime_only=True)
+
+    def recoveryCommand(self, command, handler=None):
+        return self._register_command(command, handler, "", False, True)
+
+    def checkpointMigration(self, command, handler=None):
+        return self._register_command(command, handler, "", False, False, True)
+
+    def _register_command(self, signature, handler, description, toolbox_only, recovery_only=False, migration_only=False, runtime_only=False):
         if not self.registering:
             raise RuntimeError("命令只能在入口注册阶段声明")
         if not isinstance(signature, str):
@@ -74,6 +135,9 @@ class _App:
                 "description": description,
                 "handler": candidate,
                 "toolboxOnly": toolbox_only,
+                "runtimeOnly": runtime_only,
+                "recoveryOnly": recovery_only,
+                "migrationOnly": migration_only,
             })
             return candidate
 
@@ -82,7 +146,7 @@ class _App:
         add(handler)
         return None
 
-    def invoke(self, action, payload=None, options=None):
+    def invoke(self, action, payload=None, options=None, on_progress=None):
         if not self.executing:
             raise RuntimeError("app.invoke 只能在命令执行期间调用")
         if not isinstance(action, str) or not action:
@@ -95,21 +159,53 @@ class _App:
             raise TypeError("app.invoke payload 和 options 必须为字典")
         self.request_id += 1
         request_id = self.request_id
+        if on_progress is not None:
+            if not callable(on_progress):
+                raise TypeError("on_progress 必须为可调用对象")
+            self.observers[request_id] = on_progress
         _send({
             "type": "invoke",
             "id": request_id,
             "action": action,
             "payload": payload,
             "options": options,
+            "stream": on_progress is not None,
         })
-        response = _receive()
-        if response.get("type") != "response" or response.get("id") != request_id:
-            raise RuntimeError("Mearl 宿主返回了无效的 invoke 响应")
+        try:
+            while request_id not in self.responses:
+                message = _receive()
+                if message.get("type") == "invoke-progress":
+                    observer = self.observers.get(message.get("id"))
+                    if observer:
+                        _resolve(observer(message.get("progress")))
+                elif message.get("type") == "response" and isinstance(message.get("id"), int):
+                    self.responses[message["id"]] = message
+                else:
+                    raise RuntimeError("Mearl 宿主返回了无效的 invoke 响应")
+            response = self.responses.pop(request_id)
+        finally:
+            self.observers.pop(request_id, None)
         error = response.get("error")
         if isinstance(error, dict):
-            raise _InvocationError(str(error.get("message", "调用失败")), error.get("code"))
+            raise _InvocationError(str(error.get("message", "调用失败")), error.get("code"), error.get("details"), error.get("metadata"))
         return response.get("result")
 
+    def state(self, collection, operation, payload=None):
+        return self.invoke("plugin_state", {**(payload or {}), "plugin": self.identity["plugin"], "collection": collection, "operation": operation})
+
+    def checkpoint(self, data, expectedSequence):
+        return self.invoke("plugin_task_checkpoint", {"plugin": self.identity["plugin"], "data":data,"expectedSequence":expectedSequence})
+
+    def model(self, request, on_progress=None):
+        return self.invoke("plugin_model", {"plugin": self.identity["plugin"], "operation": "run", "request": request}, on_progress=on_progress)
+
+    def page(self, operation, payload=None):
+        if payload is None:
+            payload = {}
+        if not isinstance(operation, str) or not operation or not isinstance(payload, dict):
+            raise TypeError("app.page 需要非空 operation 和字典 payload")
+        return self.invoke("plugin_page", {**payload, "plugin": self.identity["plugin"], "operation": operation})
+
     def progress(self, message):
         if not self.executing:
             raise RuntimeError("app.progress 只能在命令执行期间调用")
@@ -172,7 +268,7 @@ try:
     descriptor = {
         "type": "ready",
         "commands": [
-            {"signature": item["signature"], "description": item["description"], "toolboxOnly": item["toolboxOnly"]}
+            {"signature": item["signature"], "description": item["description"], "toolboxOnly": item["toolboxOnly"], "runtimeOnly": item["runtimeOnly"], "recoveryOnly": item["recoveryOnly"], "migrationOnly": item["migrationOnly"]}
             for item in app.commands
         ],
     }
@@ -182,28 +278,42 @@ try:
         descriptor["description"] = plugin_description
     if plugin_toolbox is not None:
         descriptor["toolbox"] = plugin_toolbox
+    if getattr(module, "pageRuntime", None) is not None:
+        descriptor["pageRuntime"] = module.pageRuntime
+    if getattr(module, "stateStorage", None) is not None:
+        descriptor["stateStorage"] = module.stateStorage
+    if getattr(module, "taskRecovery", None) is not None:
+        descriptor["taskRecovery"] = module.taskRecovery
     if plugin_app_profiles is not None:
         descriptor["appProfiles"] = plugin_app_profiles
     _send(descriptor)
 
+    acknowledgement = _receive()
+    if acknowledgement.get("type") != "ready_ack":
+        raise RuntimeError("Mearl 宿主未确认插件注册信息")
     if mode == "run":
-        acknowledgement = _receive()
-        if acknowledgement.get("type") != "ready_ack":
-            raise RuntimeError("Mearl 宿主未确认插件注册信息")
         command_name = initial.get("command")
         command_input = initial.get("input")
         if not isinstance(command_name, str) or not isinstance(command_input, dict):
             raise RuntimeError("Mearl 宿主发送了无效的命令")
         selected = next(
-            (item for item in app.commands if item["signature"].strip().split()[0] == command_name),
+            (item for item in app.commands if item["signature"].strip().split()[0] == command_name and item["runtimeOnly"] == (initial.get("runtime") is True) and item["recoveryOnly"] == (initial.get("recovery") is True) and item["migrationOnly"] == (initial.get("recovery") == "migration")),
             None,
         )
         if selected is None:
             raise RuntimeError("未知子命令: " + command_name)
         phase = "run"
+        command_context = _CommandContext(app, initial["identity"])
+        signal.signal(signal.SIGTERM, command_context.cancel)
         app.executing = True
         try:
-            result = _resolve(selected["handler"](command_input))
+            handler = selected["handler"]
+            try:
+                inspect.signature(handler).bind(command_input, command_context)
+                takes_context = True
+            except TypeError:
+                takes_context = False
+            result = _resolve(handler(command_input, command_context) if takes_context else handler(command_input))
         finally:
             app.executing = False
         _send({"type": "result", "result": result})
@@ -212,6 +322,10 @@ except BaseException as error:
     code = getattr(error, "code", None)
     if isinstance(code, str):
         response["code"] = code
+    for field in ("details", "metadata"):
+        value = getattr(error, field, None)
+        if isinstance(value, dict):
+            response[field] = value
     try:
         _send(response)
     except BaseException as serialization_error:
@@ -235,13 +349,17 @@ function parseDescriptor(message) {
         if (!isObject(value) ||
             typeof value.signature !== 'string' ||
             typeof value.description !== 'string' ||
-            typeof value.toolboxOnly !== 'boolean') {
+            typeof value.toolboxOnly !== 'boolean' ||
+            typeof value.runtimeOnly !== 'boolean') {
             throw new Error('Python 插件返回了无效的命令描述');
         }
         return {
             signature: value.signature,
             description: value.description,
             toolboxOnly: value.toolboxOnly,
+            runtimeOnly: value.runtimeOnly,
+            recoveryOnly: value.recoveryOnly === true,
+            migrationOnly: value.migrationOnly === true,
         };
     });
     if (message.name !== undefined && typeof message.name !== 'string') {
@@ -255,29 +373,40 @@ function parseDescriptor(message) {
         ...(typeof message.name === 'string' ? { name: message.name } : {}),
         ...(typeof message.description === 'string' ? { description: message.description } : {}),
         ...(message.toolbox !== undefined ? { toolbox: message.toolbox } : {}),
+        ...(message.pageRuntime !== undefined ? { pageRuntime: message.pageRuntime } : {}),
+        ...(message.stateStorage !== undefined ? { stateStorage: message.stateStorage } : {}),
+        ...(message.taskRecovery !== undefined ? { taskRecovery: message.taskRecovery } : {}),
         ...(message.appProfiles !== undefined ? { appProfiles: message.appProfiles } : {}),
     };
 }
 function bridgedError(message) {
     const detail = typeof message.message === 'string' ? message.message : 'Python 插件执行失败';
+    const restored = pluginExecutionError({
+        message: detail,
+        ...(typeof message.code === 'string' ? { code: message.code } : {}),
+        ...(isObject(message.details) ? { details: message.details } : {}),
+        ...(isObject(message.metadata) ? { metadata: message.metadata } : {}),
+    });
     if (typeof message.code === 'string' && /^PLUGIN_[A-Z0-9_]+$/.test(message.code)) {
-        return new PluginError(message.code, detail);
+        return Object.assign(new PluginError(message.code, detail), restored);
     }
-    return new Error(detail);
+    return restored;
 }
 function errorResponse(error) {
+    const serialized = serializePluginExecutionError(error);
     if (error instanceof PluginError) {
         const prefix = `${error.code}: `;
         return {
+            ...serialized,
             code: error.code,
             message: error.message.startsWith(prefix)
                 ? error.message.slice(prefix.length)
                 : error.message,
         };
     }
-    return { message: error instanceof Error ? error.message : String(error) };
+    return serialized;
 }
-async function runPythonWorker(entry, initial, app) {
+async function runPythonWorker(entry, initial, app, signal, expectedDescriptor) {
     return new Promise((resolve, reject) => {
         const executable = pythonExecutable();
         const child = spawn(executable, ['-u', '-c', PYTHON_BOOTSTRAP, entry], {
@@ -293,7 +422,7 @@ async function runPythonWorker(entry, initial, app) {
             if (protocolError)
                 return;
             protocolError = error instanceof Error ? error : new Error(String(error));
-            child.kill();
+            cancel();
         };
         const write = (message) => {
             try {
@@ -308,6 +437,27 @@ async function runPythonWorker(entry, initial, app) {
             stderr = `${stderr}${chunk}`.slice(-STDERR_LIMIT);
         });
         child.stdin.on('error', () => undefined);
+        let killTimer;
+        let terminalStopRequested = false;
+        const armKill = () => {
+            if (killTimer)
+                return;
+            killTimer = setTimeout(() => {
+                terminalStopRequested =
+                    !protocolError &&
+                        !signal?.aborted &&
+                        Boolean(outcome || (initial.mode === 'describe' && descriptor));
+                child.kill('SIGKILL');
+            }, 1000);
+            killTimer.unref();
+        };
+        const cancel = () => {
+            child.kill('SIGTERM');
+            armKill();
+        };
+        signal?.addEventListener('abort', cancel, { once: true });
+        if (signal?.aborted)
+            cancel();
         child.once('error', error => {
             if (error.code === 'ENOENT') {
                 reject(new Error(`未找到 ${executable}，Python 插件需要 Python 3.9 或更高版本` +
@@ -318,6 +468,8 @@ async function runPythonWorker(entry, initial, app) {
             }
         });
         lines.on('line', line => {
+            if (protocolError)
+                return;
             let message;
             try {
                 const value = JSON.parse(line);
@@ -335,8 +487,14 @@ async function runPythonWorker(entry, initial, app) {
                     if (descriptor)
                         throw new Error('Python 插件重复发送 ready');
                     descriptor = parseDescriptor(message);
-                    if (initial.mode === 'run')
-                        write({ type: 'ready_ack' });
+                    if (initial.mode === 'run') {
+                        if (expectedDescriptor &&
+                            pluginRecoverySignature(descriptor) !== pluginRecoverySignature(expectedDescriptor))
+                            throw new PluginError('PLUGIN_DECLARATION_CHANGED', 'Python execution declaration differs from its loaded metadata');
+                    }
+                    write({ type: 'ready_ack' });
+                    if (initial.mode === 'describe')
+                        armKill();
                 }
                 catch (error) {
                     failProtocol(error);
@@ -365,8 +523,24 @@ async function runPythonWorker(entry, initial, app) {
                     failProtocol(new Error('Python 插件发送了无效的 invoke 消息'));
                     return;
                 }
-                void app
-                    .invoke(message.action, message.payload, message.options)
+                const { action, payload, options } = message;
+                void Promise.resolve()
+                    .then(() => action === 'plugin_task_checkpoint' && app.checkpoint
+                    ? app.checkpoint(payload.data, payload.expectedSequence)
+                    : action === 'plugin_model' && payload.operation === 'run' && app.model
+                        ? app.model(payload.request, message.stream
+                            ? {
+                                onProgress: progress => {
+                                    if (!signal?.aborted && !outcome)
+                                        write({ type: 'invoke-progress', id: message.id, progress });
+                                },
+                            }
+                            : undefined)
+                        : action === 'plugin_state' && app.state
+                            ? app.state(payload.collection, payload.operation, payload)
+                            : action === 'plugin_page' && app.page
+                                ? app.page(payload.operation, payload)
+                                : app.invoke(action, payload, options))
                     .then(result => {
                     write({
                         type: 'response',
@@ -380,17 +554,37 @@ async function runPythonWorker(entry, initial, app) {
                 return;
             }
             if (message.type === 'result') {
-                outcome = { hasResult: true, result: message.result };
+                if (!outcome)
+                    outcome = { hasResult: true, result: message.result };
+                write({ type: 'terminal_ack' });
+                armKill();
                 return;
             }
             if (message.type === 'error') {
-                outcome = { error: bridgedError(message) };
+                if (!outcome)
+                    outcome = { error: bridgedError(message) };
+                write({ type: 'terminal_ack' });
+                armKill();
                 return;
             }
             failProtocol(new Error(`Python 插件发送了未知消息类型: ${message.type}`));
         });
-        child.once('close', code => {
+        let finished = false;
+        const finish = (code) => {
+            if (finished)
+                return;
+            finished = true;
+            signal?.removeEventListener('abort', cancel);
+            if (killTimer)
+                clearTimeout(killTimer);
             lines.close();
+            child.stdin.destroy();
+            child.stdout.destroy();
+            child.stderr.destroy();
+            if (signal?.aborted) {
+                reject(signal.reason ?? new Error('Plugin command cancelled'));
+                return;
+            }
             if (protocolError) {
                 reject(protocolError);
                 return;
@@ -399,7 +593,7 @@ async function runPythonWorker(entry, initial, app) {
                 reject(outcome.error);
                 return;
             }
-            if (code !== 0) {
+            if (code !== 0 && !terminalStopRequested) {
                 reject(new Error(stderr.trim() || `Python 插件进程异常退出${code === null ? '' : ` (exit ${code})`}`));
                 return;
             }
@@ -412,7 +606,10 @@ async function runPythonWorker(entry, initial, app) {
                 return;
             }
             resolve({ descriptor, ...(outcome?.hasResult ? { result: outcome.result } : {}) });
-        });
+        };
+        // Acknowledged frames precede process exit; inherited pipes cannot delay completion.
+        child.once('exit', finish);
+        child.once('close', finish);
         write(initial);
     });
 }
@@ -420,7 +617,15 @@ export async function describePythonPlugin(entry, options) {
     const { descriptor } = await runPythonWorker(entry, { mode: 'describe', options });
     return descriptor;
 }
-export async function runPythonPluginCommand(entry, command, input, app) {
-    const { result } = await runPythonWorker(entry, { mode: 'run', command, input, options: app.options }, app);
+export async function runPythonPluginCommand(entry, command, input, app, context, recovery = false, expectedDescriptor, runtimeOnly = false) {
+    const { result } = await runPythonWorker(entry, {
+        mode: 'run',
+        command,
+        input,
+        options: app.options,
+        identity: context.identity,
+        recovery,
+        runtime: runtimeOnly,
+    }, app, context.signal, expectedDescriptor);
     return result;
 }

package/dist/plugins/sdk/plugin.d.ts

@@ -0,0 +1,118 @@
+import type { PluginTaskRecoveryDeclaration, PluginTaskCheckpoint, PluginCheckpointMigrationInput } from '../../generated/plugin-recovery.js';
+import type { PluginStateDeclaration } from '../../generated/plugin-state.js';
+import type { PluginModelRequest, PluginModelResult } from '../../generated/plugin-models.js';
+import type { PluginPageRuntime } from '../../generated/plugin-pages.js';
+import type { AppProfileContribution } from '../../generated/app-profile-definition.js';
+export type { AppProfileContribution, AppProfileDefinition, } from '../../generated/app-profile-definition.js';
+export { invokePageEvalWithArgs } from '../../pageEvalArguments.js';
+import { type OfficialPluginInstaller } from '../officialPluginInstaller.js';
+import { type PluginToolboxContribution, type PluginRegistration } from '../pluginRegistry.js';
+import { type PluginCommandContext, type PluginInvocationIdentity, type PluginInvocationSource } from '../runtime/pluginExecution.js';
+import type { UnifiedInvokeOptions } from '../../unified.js';
+export type { PluginCommandContext, PluginExecutionHost, PluginInvocationIdentity, PluginInvocationSource, } from '../runtime/pluginExecution.js';
+export { executeRegisteredPlugin, type PluginExecutorOptions, type PluginExecutorDependencies, } from '../runtime/pluginExecutor.js';
+export { PluginTaskClient } from '../clients/pluginTasks.js';
+export { cleanupPluginRuntime } from '../runtime/pluginRuntimeCleanup.js';
+export { PluginPageClient } from '../clients/pluginPages.js';
+export { assertPluginName, findPluginDirectoryEntry, findPluginEntry, findPluginRegistration, listPluginNames, pluginDirectory, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, readPluginPageBundleChunk, type PluginRegistration, type PluginRegistrationOptions, type PluginToolboxAgentConfig, type PluginPageBundleRegistration, type PluginToolboxContribution, type PluginToolboxLocale, type PluginToolboxSandboxPage, } from '../pluginRegistry.js';
+export { findOfficialPlugin, listOfficialPluginNames, OFFICIAL_PLUGIN_MANAGER, OFFICIAL_PLUGINS, type OfficialPluginDefinition, type OfficialPluginName, } from '../officialPluginCatalog.js';
+export type PluginOptions = UnifiedInvokeOptions;
+export interface StructuredPluginProgress {
+    message: string;
+    data?: Record<string, unknown>;
+}
+export type PluginProgress = string | StructuredPluginProgress;
+export interface PluginInvocation {
+    command: string;
+    input: Record<string, any>;
+}
+export interface PluginInvokeOptions extends UnifiedInvokeOptions {
+    onProgress?: (progress: PluginProgress) => void;
+    signal?: AbortSignal;
+    /** Audit label supplied by the entry point, never an authorization decision. */
+    source?: PluginInvocationSource;
+}
+export interface PluginExecutionContext {
+    runModel?(plugin: string, request: PluginModelRequest, options: Pick<PluginInvokeOptions, 'signal' | 'onProgress'>): Promise<PluginModelResult>;
+    ensurePlugin?: OfficialPluginInstaller;
+    source?: PluginInvocationSource;
+    parentInvocation?: PluginInvocationIdentity;
+    invocation?: PluginInvocationIdentity;
+    resolveRegistration?: (name: string) => PluginRegistration | undefined;
+    invoke(action: string, payload?: Record<string, any>, options?: UnifiedInvokeOptions, onProgress?: PluginInvokeOptions['onProgress']): Promise<any>;
+}
+export interface PluginApp {
+    readonly options: Readonly<PluginOptions>;
+    /** Examples omit the `mearl <plugin>` prefix, which help adds when displayed. */
+    command(signature: string, handler: PluginHandler, description?: string, examples?: string[]): void;
+    /** Registers a page-only command, also declared in toolbox.page.commands. */
+    state(collection: string, operation: string, input?: Record<string, unknown>): Promise<any>;
+    model(request: PluginModelRequest, options?: Pick<PluginInvokeOptions, 'onProgress'>): Promise<PluginModelResult>;
+    runtimeCommand(signature: string, handler: PluginHandler, description?: string, examples?: string[]): void;
+    recoveryCommand(command: string, handler: PluginHandler): void;
+    checkpointMigration(command: string, handler: (input: PluginCheckpointMigrationInput, context: PluginCommandContext) => unknown | Promise<unknown>): void;
+    checkpoint(data: unknown, expectedSequence: number): Promise<PluginTaskCheckpoint>;
+    page(operation: string, input?: Record<string, unknown>): Promise<any>;
+    toolboxCommand(signature: string, handler: PluginHandler, description?: string, examples?: string[]): void;
+    invoke(action: string, payload?: Record<string, any>, options?: UnifiedInvokeOptions): Promise<any>;
+    progress(progress: PluginProgress): void;
+}
+export type PluginHandler = (input: Record<string, any>, context: PluginCommandContext) => unknown | Promise<unknown>;
+/** 工具列表仅检查入口；页面资源只在打开对应工具时检查。 */
+export declare function refreshRegisteredPlugin(name: string, includePage?: boolean): Promise<PluginRegistration | undefined>;
+/** 注册和执行复用同一宿主能力边界；仅 handler 执行期间开放浏览器调用。 */
+export declare function loadPlugin(entry: string, context: Pick<PluginApp, 'options' | 'progress'> & {
+    invoke: PluginExecutionContext['invoke'];
+    source?: PluginInvocationSource;
+    parentInvocation?: PluginInvocationIdentity;
+    invocation?: PluginInvocationIdentity;
+    signal?: AbortSignal;
+    runModel?: PluginExecutionContext['runModel'];
+    onInvocation?: (identity: PluginInvocationIdentity | undefined) => void;
+}, pluginName?: string): Promise<{
+    name: string | undefined;
+    description: string | undefined;
+    toolbox: PluginToolboxContribution | undefined;
+    pageRuntime: PluginPageRuntime | undefined;
+    stateStorage: PluginStateDeclaration | undefined;
+    taskRecovery: PluginTaskRecoveryDeclaration | undefined;
+    appProfiles: AppProfileContribution | undefined;
+    profileSources: Record<string, string> | undefined;
+    version: string | undefined;
+    commandHelp(namespace: string): string;
+    help(namespace: string, name?: string): string;
+    run(positionals: string[], payload?: unknown, namedInput?: Record<string, unknown>): Promise<unknown>;
+    runRuntime(invocation: PluginInvocation): Promise<unknown>;
+    runRecovery(invocation: PluginInvocation): Promise<unknown>;
+    runMigration(invocation: PluginInvocation): Promise<unknown>;
+    runToolbox(invocation: PluginInvocation): Promise<unknown>;
+}>;
+export declare function loadRegisteredPlugin(name: string, context: PluginExecutionContext, options?: PluginInvokeOptions): Promise<{
+    name: string | undefined;
+    description: string | undefined;
+    toolbox: PluginToolboxContribution | undefined;
+    pageRuntime: PluginPageRuntime | undefined;
+    stateStorage: PluginStateDeclaration | undefined;
+    taskRecovery: PluginTaskRecoveryDeclaration | undefined;
+    appProfiles: AppProfileContribution | undefined;
+    profileSources: Record<string, string> | undefined;
+    version: string | undefined;
+    commandHelp(namespace: string): string;
+    help(namespace: string, name?: string): string;
+    run(positionals: string[], payload?: unknown, namedInput?: Record<string, unknown>): Promise<unknown>;
+    runRuntime(invocation: PluginInvocation): Promise<unknown>;
+    runRecovery(invocation: PluginInvocation): Promise<unknown>;
+    runMigration(invocation: PluginInvocation): Promise<unknown>;
+    runToolbox(invocation: PluginInvocation): Promise<unknown>;
+}>;
+export declare function invokeRegisteredPlugin(name: string, invocation: PluginInvocation, context: PluginExecutionContext, options?: PluginInvokeOptions): Promise<unknown>;
+/** Entry point for the native toolbox service; nested plugin calls retain public-command access. */
+export declare function invokeRegisteredToolboxPlugin(name: string, invocation: PluginInvocation, context: PluginExecutionContext, options?: PluginInvokeOptions): Promise<unknown>;
+export declare function invokeRegisteredRuntimePlugin(name: string, invocation: PluginInvocation, context: PluginExecutionContext, options?: PluginInvokeOptions): Promise<unknown>;
+export declare function invokeRegisteredRecoveryPlugin(name: string, invocation: PluginInvocation, context: PluginExecutionContext, options?: PluginInvokeOptions): Promise<unknown>;
+export { PluginStateClient } from '../clients/pluginState.js';
+export { PluginModelClient } from '../clients/pluginModels.js';
+export type * from '../../generated/plugin-state.js';
+export type * from '../../generated/plugin-models.js';
+export type * from '../../generated/plugin-recovery.js';
+export type * from '../../generated/plugin-diagnostics.js';