@mearl/client 2.21.0 → 2.22.0

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

@@ -1,7 +1,7 @@
-import { pluginRecoverySignature } from './pluginRecoveryDefinition.js';
+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。

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';