@mearl/client 2.21.0 → 2.22.1

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

@@ -1,7 +1,7 @@
-import { pluginStateSignature } from './pluginStateDefinition.js';
+import { pluginStateSignature } from '../sdk/pluginStateDefinition.js';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { findPluginRegistration } from './pluginRegistry.js';
+import { findPluginRegistration } from '../pluginRegistry.js';
 import { pluginHostPaths } from './pluginHostPaths.js';
 import { capturePluginRevision } from './pluginRevision.js';
 import { PluginStateStore } from './pluginStateStore.js';

package/dist/{pluginStateStore.d.ts → plugins/runtime/pluginStateStore.d.ts}

@@ -1,4 +1,4 @@
-import type { PluginStateCollection, PluginStateEntry, PluginStateTransaction } from './generated-plugin-state.js';
+import type { PluginStateCollection, PluginStateEntry, PluginStateTransaction } from '../../generated/plugin-state.js';
 export interface PluginStateNamespace {
     installationId: string;
     collection: string;

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

@@ -3,7 +3,6 @@ import { existsSync, readFileSync, readdirSync, statSync, rmSync } from 'node:fs
 import { join, sep } from 'node:path';
 import { pluginHostPaths } from './pluginHostPaths.js';
 import { writePluginHostFile } from './pluginHostFiles.js';
-import { compilePluginStateSchema } from './pluginStateDefinition.js';
 function fail(code, message) {
     throw Object.assign(new Error(message), { code });
 }
@@ -316,7 +315,6 @@ export class PluginStateStore {
                 else
                     delete entry.expiresAt;
             }
-        const validate = compilePluginStateSchema(definition.schema);
         for (const operation of input.operations) {
             key(operation.key);
             if (names.has(operation.key) ||
@@ -328,9 +326,9 @@ export class PluginStateStore {
                 delete entries[operation.key];
                 continue;
             }
-            if (!validate(operation.value) ||
-                Buffer.byteLength(JSON.stringify(operation.value)) > 256 * 1024)
-                fail('PLUGIN_STATE_SCHEMA_INVALID', 'State value does not match the declared schema or exceeds 256 KiB');
+            const json = JSON.stringify(operation.value);
+            if (json === undefined || Buffer.byteLength(json) > 256 * 1024)
+                fail('PLUGIN_STATE_INVALID', 'State value must be JSON within 256 KiB');
             const ttl = operation.ttlMs ?? definition.ttlMs ?? 86400000;
             if (definition.storage === 'persistent' && operation.ttlMs !== undefined)
                 fail('PLUGIN_STATE_INVALID', 'Persistent state does not accept TTL');
@@ -342,9 +340,6 @@ export class PluginStateStore {
                 ...(definition.storage !== 'persistent' ? { expiresAt: now + ttl } : {}),
             };
         }
-        for (const entry of Object.values(entries))
-            if (!validate(entry.value))
-                fail('PLUGIN_STATE_SCHEMA_INVALID', 'Migration leaves entries incompatible with the target schema');
         const commit = {
             revision,
             schemaVersion: definition.schemaVersion,

package/dist/{pluginTaskManager.d.ts → plugins/runtime/pluginTaskManager.d.ts}

@@ -1,19 +1,19 @@
 import type { PluginModelCatalog } from './pluginModelCatalog.js';
 import type { PluginStateManager } from './pluginStateManager.js';
 import type { PluginPageManager } from './pluginPageManager.js';
-import type { PluginStateDeclaration } from './generated-plugin-state.js';
-import type { PluginTaskCheckpoint, PluginTaskRecoveryContext, PluginTaskRecoveryDeclaration } from './generated-plugin-recovery.js';
+import type { PluginStateDeclaration } from '../../generated/plugin-state.js';
+import type { PluginTaskCheckpoint, PluginTaskRecoveryContext, PluginTaskRecoveryDeclaration } from '../../generated/plugin-recovery.js';
 import { executeRegisteredPlugin } from './pluginExecutor.js';
 import { capturePluginRevision } from './pluginRevision.js';
 import type { PluginRevision } from './pluginRevision.js';
 import { PluginTaskStore } from './pluginTaskStore.js';
-import type { PluginTask, PluginTaskStartResult, PluginTaskListResult } from './generated-plugin-tasks.js';
-import type { PluginTaskScope, PluginTaskStartRequest, PluginTaskResumeRequest } from './pluginTaskProtocol.js';
-import type { PluginInvocationIdentity } from './generated-plugin-execution.js';
-import type { PluginPageTarget } from './generated-plugin-pages.js';
-import type { PluginOptions } from './plugin.js';
-import type { PluginPageBinding } from './generated-plugin-pages.js';
-import type { PluginPageRuntime } from './generated-plugin-pages.js';
+import type { PluginTask, PluginTaskStartResult, PluginTaskListResult } from '../../generated/plugin-tasks.js';
+import type { PluginTaskScope, PluginTaskStartRequest, PluginTaskResumeRequest } from '../pluginTaskProtocol.js';
+import type { PluginInvocationIdentity } from '../../generated/plugin-execution.js';
+import type { PluginPageTarget } from '../../generated/plugin-pages.js';
+import type { PluginOptions } from '../sdk/plugin.js';
+import type { PluginPageBinding } from '../../generated/plugin-pages.js';
+import type { PluginPageRuntime } from '../../generated/plugin-pages.js';
 export interface PluginTaskBridge {
     id: string;
     scope: PluginTaskScope;
@@ -37,7 +37,7 @@ export interface PluginTaskServices {
 export declare class PluginTaskManager {
     private readonly configuration;
     private readonly services?;
-    readonly host: import("./generated-plugin-execution.js").PluginExecutionHost;
+    readonly host: import("./pluginExecution.js").PluginExecutionHost;
     readonly store: PluginTaskStore;
     private readonly changes;
     private readonly queue;
@@ -78,8 +78,8 @@ export declare class PluginTaskManager {
     private resumeAttempt;
     private assertExecutionTreeStopped;
     cancel(taskId: string, scope: PluginTaskScope): PluginTask;
-    events(taskId: string, scope: PluginTaskScope, cursor: number, waitMs?: number, signal?: AbortSignal): Promise<import("./generated-plugin-tasks.js").PluginTaskEvents>;
-    resultChunk(taskId: string, scope: PluginTaskScope, index: number): import("./generated-plugin-tasks.js").PluginTaskResultChunk;
+    events(taskId: string, scope: PluginTaskScope, cursor: number, waitMs?: number, signal?: AbortSignal): Promise<import("../../generated/plugin-tasks.js").PluginTaskEvents>;
+    resultChunk(taskId: string, scope: PluginTaskScope, index: number): import("../../generated/plugin-tasks.js").PluginTaskResultChunk;
     private update;
     private drain;
     private execute;

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

@@ -1,7 +1,6 @@
 import { normalizeModelDiagnostic, diagnosticBinding } from './pluginDiagnostics.js';
-import { pluginModelCapabilities, normalizePluginModel, validatePluginModelResult, } from './pluginModelDefinition.js';
-import { pluginRecoverySignature } from './pluginRecoveryDefinition.js';
-import { compilePluginStateSchema } from './pluginStateDefinition.js';
+import { pluginModelCapabilities, normalizePluginModel, validatePluginModelResult, } from '../sdk/pluginModelDefinition.js';
+import { pluginRecoverySignature } from '../sdk/pluginRecoveryDefinition.js';
 import { createHash, randomUUID } from 'node:crypto';
 import { EventEmitter } from 'node:events';
 import { isAbsolute, join, relative, sep } from 'node:path';
@@ -12,9 +11,9 @@ import { serializePluginExecutionError, pluginExecutionError } from './pluginExe
 import { capturePluginRevision, prunePluginRevisions, restorePluginRevision, } from './pluginRevision.js';
 import { pluginHostPaths } from './pluginHostPaths.js';
 import { PluginTaskStore, pluginTaskExecutionUnconfirmed } from './pluginTaskStore.js';
-import { isPluginTaskActive } from './generated-plugin-tasks.js';
-import { UnifiedClient, decodeBrowserTarget } from './unified.js';
-import { COMMAND_MAP } from './commands.js';
+import { isPluginTaskActive } from '../../generated/plugin-tasks.js';
+import { UnifiedClient, decodeBrowserTarget } from '../../unified.js';
+import { COMMAND_MAP } from '../../commands.js';
 function error(code, message) {
     return Object.assign(new Error(message), { code });
 }
@@ -482,8 +481,7 @@ export class PluginTaskManager {
             signal.throwIfAborted();
             if (!sourceDefinition ||
                 sourceDefinition.checkpointVersion !== record.checkpoint.version ||
-                digest(sourceDefinition.schema) !== record.checkpoint.schemaHash ||
-                !compilePluginStateSchema(sourceDefinition.schema)(record.checkpoint.data))
+                digest(sourceDefinition.schema) !== record.checkpoint.schemaHash)
                 throw error('PLUGIN_TASK_RECOVERY_UNAVAILABLE', 'Checkpoint does not match the retained recovery declaration');
             let checkpoint = structuredClone(record.checkpoint);
             let declarationHash = pluginRecoverySignature(sourceDefinition);
@@ -542,8 +540,6 @@ export class PluginTaskManager {
                         data: JSON.parse(json),
                     };
                 }
-                if (!compilePluginStateSchema(target.schema)(checkpoint.data))
-                    throw error('PLUGIN_TASK_CHECKPOINT_INVALID', 'Migrated checkpoint does not match the target schema');
             }
             signal.throwIfAborted();
             // Admission is synchronous after both immutable snapshots and execution ownership are verified.
@@ -809,8 +805,8 @@ export class PluginTaskManager {
                         if (declaration &&
                             payload.expectedDeclaration !== pluginRecoverySignature(declaration))
                             throw error('PLUGIN_RECOVERY_DECLARATION_CHANGED', 'Checkpoint declaration differs from the executing command');
-                        if (!declaration || !compilePluginStateSchema(declaration.schema)(data))
-                            throw error('PLUGIN_TASK_CHECKPOINT_INVALID', 'Checkpoint is undeclared or does not match its schema');
+                        if (!declaration)
+                            throw error('PLUGIN_TASK_CHECKPOINT_INVALID', 'Checkpoint is undeclared');
                         const current = this.store.read(taskId);
                         if (current.task.state !== 'running' ||
                             payload.expectedSequence !== (current.checkpoint?.sequence ?? 0))

package/dist/{pluginTaskStore.d.ts → plugins/runtime/pluginTaskStore.d.ts}

@@ -1,7 +1,7 @@
-import type { PluginTaskDiagnosticMetadata } from './generated-plugin-diagnostics.js';
-import type { PluginTask, PluginTaskEvent, PluginTaskEvents, PluginTaskResultChunk } from './generated-plugin-tasks.js';
-import type { PluginTaskCheckpoint } from './generated-plugin-recovery.js';
-import type { PluginOptions } from './plugin.js';
+import type { PluginTaskDiagnosticMetadata } from '../../generated/plugin-diagnostics.js';
+import type { PluginTask, PluginTaskEvent, PluginTaskEvents, PluginTaskResultChunk } from '../../generated/plugin-tasks.js';
+import type { PluginTaskCheckpoint } from '../../generated/plugin-recovery.js';
+import type { PluginOptions } from '../sdk/plugin.js';
 export declare const PLUGIN_TASK_RESULT_CHUNK_BYTES: number;
 export interface PluginTaskRecord {
     task: PluginTask;

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

@@ -1,7 +1,7 @@
 import { createHash } from 'node:crypto';
 import { closeSync, openSync, opendirSync, readFileSync, readSync, readdirSync, rmSync, statSync, } from 'node:fs';
 import { join } from 'node:path';
-import { isPluginTaskActive, isPluginTaskId } from './generated-plugin-tasks.js';
+import { isPluginTaskActive, isPluginTaskId } from '../../generated/plugin-tasks.js';
 import { writePluginHostFile } from './pluginHostFiles.js';
 import { pluginHostPaths } from './pluginHostPaths.js';
 import { isProcessGroupAlive, isProcessOwnerAlive } from '@mearl/daemon-core';

package/dist/{pythonPlugin.d.ts → plugins/runtime/pythonPlugin.d.ts}

@@ -1,4 +1,4 @@
-import type { PluginOptions, PluginApp } from './plugin.js';
+import type { PluginOptions, PluginApp } from '../sdk/plugin.js';
 import type { PluginCommandContext } from './pluginExecution.js';
 export interface PythonPluginCommand {
     description: string;
@@ -28,4 +28,4 @@ export interface PythonPluginApp {
     progress(message: string): void;
 }
 export declare function describePythonPlugin(entry: string, options: Readonly<PluginOptions>): Promise<PythonPluginDescriptor>;
-export declare function runPythonPluginCommand(entry: string, command: string, input: Record<string, any> | import('./generated-plugin-recovery.js').PluginCheckpointMigrationInput, app: PythonPluginApp, context: PluginCommandContext, recovery?: boolean | 'migration', expectedDescriptor?: PythonPluginDescriptor, runtimeOnly?: boolean): Promise<unknown>;
+export declare function runPythonPluginCommand(entry: string, command: string, input: Record<string, any> | import('../../generated/plugin-recovery.js').PluginCheckpointMigrationInput, app: PythonPluginApp, context: PluginCommandContext, recovery?: boolean | 'migration', expectedDescriptor?: PythonPluginDescriptor, runtimeOnly?: boolean): Promise<unknown>;

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