@mearl/client 2.20.5 → 2.21.0

package/dist/generated-plugin-models.d.ts

@@ -0,0 +1,64 @@
+export type PluginModelMode = 'generate' | 'agent';
+export interface PluginModelRequest {
+    provider: string;
+    mode: PluginModelMode;
+    prompt: string;
+    instructions?: string;
+    model?: string;
+    reasoningEffort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+    outputSchema?: Record<string, unknown>;
+    /** Opt-in conversation scoped to the bound document or calling command execution. */
+    conversation?: string;
+    /** Required for an agent task; never inferred from a pure-generation request. */
+    permissions?: 'read-only';
+}
+export interface PluginModelCapability {
+    provider: string;
+    modes: PluginModelMode[];
+    permissions: Array<'read-only'>;
+    structuredOutput: boolean;
+    streaming: boolean;
+    cancellation: boolean;
+}
+export interface PluginModelOption {
+    id: string;
+    displayName: string;
+    description?: string;
+    isDefault?: boolean;
+    reasoningEfforts?: NonNullable<PluginModelRequest['reasoningEffort']>[];
+    defaultReasoningEffort?: PluginModelRequest['reasoningEffort'];
+}
+export interface PluginModelList {
+    provider: string;
+    models: PluginModelOption[];
+}
+export interface PluginModelResult {
+    text: string;
+    output?: unknown;
+    provider: string;
+    mode: PluginModelMode;
+    model?: string;
+}
+/** Execution observations contain no prompts, account identities or credential values. */
+export interface PluginModelDiagnostic {
+    requestedModel?: string;
+    selectedModel?: string;
+    activeModel?: string;
+    runtime?: {
+        executable?: string;
+        version?: string;
+        selection: 'explicit' | 'automatic';
+        started?: boolean;
+    };
+    configuration?: {
+        source: 'default' | 'environment';
+        home?: string;
+        filePresent: boolean;
+        baseProvider?: string;
+        credentialStore?: 'file' | 'keyring' | 'auto' | 'ephemeral' | 'unknown';
+    };
+    authentication?: 'apikey' | 'chatgpt' | 'chatgptAuthTokens' | 'unknown';
+    threadRestrictionsAccepted?: boolean;
+    turnRestrictionsAccepted?: boolean;
+    retryCount?: number;
+}

package/dist/generated-plugin-models.js

@@ -0,0 +1 @@
+export {};

package/dist/generated-plugin-pages.d.ts

@@ -0,0 +1,76 @@
+import type { PluginExecutionError, PluginExecutionHost } from './generated-plugin-execution.js';
+export declare const PLUGIN_PAGE_LEASE_MS = 30000;
+/** Document or access-scope invalidation can cross transports that preserve only a message. */
+export declare function isPluginPageInvalidation(error: unknown): boolean;
+export declare function isPluginPageUnavailable(error: unknown): boolean;
+export declare function pluginPageUnavailable(error: unknown): Error;
+/** main/business selectors, Chrome numeric frame IDs, or CDP opaque frame IDs. */
+export type PluginPageFrame = string | number;
+export type PluginPageOperation = 'attach' | 'get' | 'list' | 'send' | 'detach' | 'events' | 'activation';
+export interface PluginPageEventBinding {
+    command: string;
+    schema: Record<string, unknown>;
+    policy?: 'serial' | 'latest' | 'parallel';
+    concurrency?: number;
+    maxPending?: number;
+}
+export interface PluginPageRuntime {
+    version: 1;
+    matches: string[];
+    /** Self-contained function expression receiving {input, signal, emit, identity}. */
+    code: string;
+    initialize?: string;
+    events?: Record<string, PluginPageEventBinding>;
+}
+export interface PluginPageTarget {
+    browserSessionId: string;
+    tabId: number;
+    frameId: string | number;
+    documentId: string;
+    url: string;
+}
+export interface PluginPageInstance {
+    instanceId: string;
+    plugin: string;
+    installationId: string;
+    revision: string;
+    host: PluginExecutionHost;
+    target: PluginPageTarget;
+    state: 'active' | 'detached' | 'invalidated';
+    sequence: number;
+    createdAt: number;
+    error?: PluginExecutionError;
+}
+export interface PluginPageEvent {
+    sequence: number;
+    time: number;
+    type: 'received' | 'running' | 'success' | 'error' | 'superseded' | 'navigation' | 'invalidated';
+    eventSequence?: number;
+    name?: string;
+    payload?: unknown;
+    taskId?: string;
+    error?: PluginExecutionError;
+}
+export interface PluginPageEvents {
+    instance: PluginPageInstance;
+    events: PluginPageEvent[];
+    nextCursor: number;
+    firstAvailableSequence: number;
+    gap: boolean;
+}
+export interface PluginPageActivation {
+    plugin: string;
+    installationId: string;
+    enabled: boolean;
+    matches: string[];
+    persistence: 'session' | 'persistent';
+    frame: PluginPageFrame;
+    input: Record<string, unknown>;
+}
+export interface PluginPageBinding {
+    instanceId: string;
+    target: PluginPageTarget;
+}
+export declare function isPluginPageMatchPattern(value: unknown): value is string;
+export declare function matchesPluginPageURL(matches: readonly string[], value: string): boolean;
+export declare function isPluginPageInstanceId(value: unknown): value is string;

package/dist/generated-plugin-pages.js

@@ -0,0 +1,59 @@
+export const PLUGIN_PAGE_LEASE_MS = 30000;
+/** Document or access-scope invalidation can cross transports that preserve only a message. */
+export function isPluginPageInvalidation(error) {
+    const value = error;
+    const codes = [
+        'PLUGIN_PAGE_INVALIDATED',
+        'PLUGIN_PAGE_NOT_FOUND',
+        'PLUGIN_PAGE_TARGET_CHANGED',
+        'DOMAIN_PERMISSION_REQUIRED',
+    ];
+    const message = typeof value?.message === 'string' ? value.message : '';
+    return codes.includes(String(value?.code)) || codes.some(code => message.startsWith(`${code}:`));
+}
+export function isPluginPageUnavailable(error) {
+    return error?.code === 'PLUGIN_PAGE_UNAVAILABLE';
+}
+export function pluginPageUnavailable(error) {
+    return Object.assign(new Error('Plugin page host is temporarily unavailable', { cause: error }), {
+        code: 'PLUGIN_PAGE_UNAVAILABLE',
+    });
+}
+const pattern = /^(https?|\*):\/\/(\*|\*\.[a-z0-9.-]+|[a-z0-9.-]+|localhost)(:\d+)?(\/[^#]*)$/i;
+export function isPluginPageMatchPattern(value) {
+    return typeof value === 'string' && value.length <= 2048 && pattern.test(value);
+}
+export function matchesPluginPageURL(matches, value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return false;
+    }
+    if (!['http:', 'https:'].includes(url.protocol))
+        return false;
+    return matches.some(item => {
+        const match = item.match(pattern);
+        if (!match || (match[1] !== '*' && match[1].toLowerCase() + ':' !== url.protocol))
+            return false;
+        const host = match[2].toLowerCase();
+        if (host !== '*' &&
+            host !== url.hostname &&
+            !(host.startsWith('*.') &&
+                (url.hostname === host.slice(2) || url.hostname.endsWith(host.slice(1)))))
+            return false;
+        if (match[3] && match[3].slice(1) !== (url.port || (url.protocol === 'https:' ? '443' : '80')))
+            return false;
+        const expression = '^' +
+            match[4]
+                .split('*')
+                .map(part => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+                .join('.*') +
+            '$';
+        return new RegExp(expression).test(url.pathname + url.search);
+    });
+}
+export function isPluginPageInstanceId(value) {
+    return typeof value === 'string' && /^pi_[0-9a-f-]{36}$/i.test(value);
+}

package/dist/generated-plugin-recovery.d.ts

@@ -0,0 +1,32 @@
+export interface PluginTaskRecoveryDeclaration {
+    version: 1;
+    commands: Record<string, {
+        checkpointVersion: number;
+        schema: Record<string, unknown>;
+        migrateFrom?: Array<{
+            version: number;
+            schema: Record<string, unknown>;
+        }>;
+    }>;
+}
+export interface PluginTaskCheckpointReference {
+    sequence: number;
+    version: number;
+    schemaHash: string;
+    updatedAt: number;
+}
+export interface PluginTaskCheckpoint extends PluginTaskCheckpointReference {
+    data: unknown;
+}
+export interface PluginTaskRecoveryContext {
+    fromTaskId: string;
+    fromRevision: string;
+    declarationHash: string;
+    sourceCheckpoint: PluginTaskCheckpointReference;
+    checkpoint: PluginTaskCheckpoint;
+}
+export interface PluginCheckpointMigrationInput {
+    checkpoint: PluginTaskCheckpoint;
+    fromRevision: string;
+    toRevision: string;
+}

package/dist/generated-plugin-recovery.js

@@ -0,0 +1 @@
+export {};

package/dist/generated-plugin-state.d.ts

@@ -0,0 +1,50 @@
+export type PluginStateScope = 'installation' | 'host' | 'browser-session' | 'instance';
+export interface PluginStateCollection {
+    scope: PluginStateScope;
+    storage: 'persistent' | 'cache' | 'memory';
+    schemaVersion: number;
+    schema: Record<string, unknown>;
+    maxEntries?: number;
+    maxBytes?: number;
+    ttlMs?: number;
+}
+export interface PluginStateDeclaration {
+    version: 1;
+    collections: Record<string, PluginStateCollection>;
+}
+export interface PluginStateEntry {
+    key: string;
+    exists: boolean;
+    /** Live entry revision, or the collection revision for absence; opaque to callers. */
+    version: string;
+    value?: unknown;
+    expiresAt?: number;
+}
+export interface PluginStateSnapshot extends PluginStateEntry {
+    revision: number;
+    schemaVersion: number;
+}
+export interface PluginStateList {
+    entries: PluginStateEntry[];
+    revision: number;
+    schemaVersion: number;
+    nextCursor?: string;
+}
+export type PluginStateMutation = {
+    type: 'put';
+    key: string;
+    expectedVersion: string;
+    value: unknown;
+    ttlMs?: number;
+} | {
+    type: 'delete';
+    key: string;
+    expectedVersion: string;
+};
+export interface PluginStateTransaction {
+    operations: PluginStateMutation[];
+    expectedRevision?: number;
+    migrateFromVersion?: number;
+    idempotencyKey?: string;
+}
+export type PluginStateOperation = 'get' | 'get-many' | 'list' | 'transact';

package/dist/generated-plugin-state.js

@@ -0,0 +1 @@
+export {};

package/dist/generated-plugin-tasks.d.ts

@@ -0,0 +1,74 @@
+import type { PluginExecutionError, PluginExecutionHost, PluginInvocationSource } from './generated-plugin-execution.js';
+import type { PluginTaskCheckpointReference } from './generated-plugin-recovery.js';
+export declare const PLUGIN_TASK_PROTOCOL_VERSION = 5;
+export type PluginTaskState = 'queued' | 'running' | 'cancelling' | 'success' | 'error' | 'cancelled' | 'interrupted';
+export interface PluginTaskResultReference {
+    bytes: number;
+    sha256: string;
+    chunks: number;
+}
+export interface PluginTask {
+    taskId: string;
+    host: PluginExecutionHost;
+    plugin: string;
+    installationId: string;
+    revision: string;
+    command: string;
+    kind?: 'command' | 'model';
+    parentTaskId?: string;
+    resumedFrom?: {
+        taskId: string;
+        revision: string;
+        checkpointSequence: number;
+        checkpointVersion: number;
+    };
+    checkpoint?: PluginTaskCheckpointReference;
+    input: Record<string, unknown>;
+    source: PluginInvocationSource;
+    cwd: string;
+    state: PluginTaskState;
+    sequence: number;
+    createdAt: number;
+    updatedAt: number;
+    progress?: string | {
+        message: string;
+        data?: Record<string, unknown>;
+    };
+    result?: PluginTaskResultReference;
+    error?: PluginExecutionError;
+}
+export interface PluginTaskEvent {
+    sequence: number;
+    time: number;
+    type: 'state' | 'progress' | 'checkpoint' | 'diagnostic';
+    checkpoint?: PluginTaskCheckpointReference;
+    state: PluginTaskState;
+    progress?: PluginTask['progress'];
+}
+export interface PluginTaskEvents {
+    task: PluginTask;
+    events: PluginTaskEvent[];
+    firstAvailableSequence: number;
+    nextCursor: number;
+    gap: boolean;
+}
+export interface PluginTaskStartResult {
+    taskId: string;
+    state: PluginTaskState;
+    host: PluginExecutionHost;
+    reused?: true;
+}
+export interface PluginTaskListResult {
+    tasks: PluginTask[];
+    nextCursor?: string;
+}
+export interface PluginTaskResultChunk {
+    taskId: string;
+    index: number;
+    data: string;
+    bytes: number;
+    sha256: string;
+    chunks: number;
+}
+export declare function isPluginTaskActive(state: PluginTaskState): boolean;
+export declare function isPluginTaskId(value: unknown): value is string;

package/dist/generated-plugin-tasks.js

@@ -0,0 +1,7 @@
+export const PLUGIN_TASK_PROTOCOL_VERSION = 5;
+export function isPluginTaskActive(state) {
+    return state === 'queued' || state === 'running' || state === 'cancelling';
+}
+export function isPluginTaskId(value) {
+    return typeof value === 'string' && /^pt_[0-9a-f-]{36}_[0-9a-f-]{36}$/i.test(value);
+}

package/dist/generated-toolbox-icon.d.ts

@@ -0,0 +1,10 @@
+export type ParsedToolboxIcon = {
+    kind: 'name';
+    name: string;
+} | {
+    kind: 'image';
+    src: string;
+    monochrome?: true;
+};
+/** SVG is an image source so its markup never becomes executable extension DOM. */
+export declare function parseToolboxIcon(value: unknown): ParsedToolboxIcon | undefined;

package/dist/generated-toolbox-icon.js

@@ -0,0 +1,37 @@
+/** SVG is an image source so its markup never becomes executable extension DOM. */
+export function parseToolboxIcon(value) {
+    if (typeof value !== 'string')
+        return;
+    const icon = value.trim();
+    if (!icon || icon.length > 32 * 1024)
+        return;
+    if (/^[a-z][a-z0-9-]{0,39}$/.test(icon))
+        return { kind: 'name', name: icon };
+    if (/^(?:<\?xml\s[^>]*\?>\s*)?<svg\b[^>]*(?:\/>|>[\s\S]*<\/svg\s*>)$/i.test(icon)) {
+        const svg = /<svg\b[^>]*\sxmlns\s*=/i.test(icon)
+            ? icon
+            : icon.replace(/<svg\b/i, '<svg xmlns="http://www.w3.org/2000/svg"');
+        try {
+            return {
+                kind: 'image',
+                src: `data:image/svg+xml,${encodeURIComponent(svg)}`,
+                ...(/\bcurrentColor\b/i.test(svg) ? { monochrome: true } : {}),
+            };
+        }
+        catch {
+            return;
+        }
+    }
+    const dataHeader = /^data:image\/(?:svg\+xml|png|jpeg|gif|webp|avif)(?:;charset=utf-8|;utf8)?(?:;base64)?,/i.exec(icon);
+    if (dataHeader && icon.length > dataHeader[0].length)
+        return { kind: 'image', src: icon };
+    try {
+        const url = new URL(icon);
+        if (['http:', 'https:'].includes(url.protocol) && !url.username && !url.password) {
+            return { kind: 'image', src: url.href };
+        }
+    }
+    catch {
+        /* Non-URL values cannot be image sources. */
+    }
+}

package/dist/index.d.ts

@@ -1,9 +1,14 @@
+export { PluginHostConnection, type PluginHostConnectionOptions, type PluginHostClientOptions, } from './pluginHostConnection.js';
 /**
  * @mearl/client — unified Mearl browser client
  *
  * Discovers browser targets on this machine and every configured cloud connector,
  * then routes actions using the global browser ids returned by browser_list.
  */
+export { PluginTaskClient, type PluginTaskStartOptions, type PluginTaskWaitOptions, type PluginTaskClientOptions, type PluginTask, type PluginTaskEvents, type PluginTaskListResult, type PluginTaskStartResult, } from './pluginTasks.js';
+export { PluginPageClient } from './pluginPages.js';
+export type { PluginPageInstance, PluginPageEvents, PluginPageRuntime, PluginPageActivation, PluginPageTarget, PluginPageOperation, } from './pluginPages.js';
+export { executeRegisteredPlugin, type PluginExecutorOptions, type PluginExecutorDependencies, type PluginCommandContext, type PluginExecutionHost, type PluginInvocationIdentity, type PluginInvocationSource, } from './plugin.js';
 export { UnifiedClient, UnifiedClient as MearlClient, decodeBrowserTarget, invoke, invokePlugin, listCloudConnectors, } from './unified.js';
 export type { UnifiedClientOptions, UnifiedInvokeOptions, UnifiedInvokeOptions as InvokeOptions, } from './unified.js';
 export type { PluginInvocation, PluginInvokeOptions, PluginProgress, StructuredPluginProgress, } from './plugin.js';
@@ -61,3 +66,9 @@ export declare function saveArtifact(artifact: Protocol.BrowserArtifact & {
     outputPath: string;
     bytes: number;
 }>;
+export { PluginStateClient } from './pluginState.js';
+export { PluginModelClient } from './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';

package/dist/index.js

@@ -1,9 +1,13 @@
+export { PluginHostConnection, } from './pluginHostConnection.js';
 /**
  * @mearl/client — unified Mearl browser client
  *
  * Discovers browser targets on this machine and every configured cloud connector,
  * then routes actions using the global browser ids returned by browser_list.
  */
+export { PluginTaskClient, } from './pluginTasks.js';
+export { PluginPageClient } from './pluginPages.js';
+export { executeRegisteredPlugin, } from './plugin.js';
 export { UnifiedClient, UnifiedClient as MearlClient, decodeBrowserTarget, invoke, invokePlugin, listCloudConnectors, } from './unified.js';
 export { APP_PROFILE_NAMES, BROWSER_DEVICE_PRESET_NAMES, BROWSER_ACTIONS, BROWSER_CAPABILITY_ACTIONS, BROWSER_COMMAND_ACTIONS, EXTENSION_BROWSER_ACTIONS, PAGE_ACT_ACTIONS, SEND_REQUEST_MAX_FILES, SEND_REQUEST_MAX_TOTAL_BASE64_FILE_BYTES, SEND_REQUEST_MAX_TOTAL_FILE_BYTES, isBrowserAction, isBrowserCapabilityAction, isBrowserCommandAction, isExtensionBrowserAction, } from './generated-browser-action-protocol.js';
 import { invoke } from './unified.js';
@@ -140,3 +144,5 @@ export async function saveArtifact(artifact, outputPath, options = {}) {
     const { exportArtifact } = await import('./artifacts.js');
     return exportArtifact({ invoke }, artifact, outputPath, options);
 }
+export { PluginStateClient } from './pluginState.js';
+export { PluginModelClient } from './pluginModels.js';

package/dist/plugin-task-host.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/plugin-task-host.js

@@ -0,0 +1,14 @@
+import { startPluginHostServer } from './pluginHostServer.js';
+try {
+    const server = await startPluginHostServer();
+    const close = () => {
+        void server.close().then(() => process.exit(0));
+    };
+    process.once('SIGTERM', close);
+    process.once('SIGINT', close);
+}
+catch (error) {
+    if (error.code !== 'PLUGIN_TASK_HOST_OWNED')
+        process.stderr.write(`${error instanceof Error ? error.stack : String(error)}\n`);
+    process.exitCode = error.code === 'PLUGIN_TASK_HOST_OWNED' ? 0 : 1;
+}

package/dist/plugin-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/plugin-worker.js

@@ -0,0 +1,17 @@
+import { supervisePluginExecutor } from './pluginExecutorSupervisor.js';
+if (process.argv[2] === '--command') {
+    let command;
+    // Register IPC before loading command code so startup messages retain their order.
+    process.on('message', (message) => {
+        void (command ??= import('./pluginCommandWorker.js'))
+            .then(worker => worker.handlePluginWorkerMessage(message))
+            .catch(error => {
+            process.stderr.write(String(error));
+            process.exit(1);
+        });
+    });
+    process.on('disconnect', () => process.exit(1));
+}
+else {
+    supervisePluginExecutor(import.meta.url);
+}

package/dist/plugin.d.ts

@@ -1,10 +1,20 @@
+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 './pluginExecution.js';
 import type { UnifiedInvokeOptions } from './unified.js';
-export { assertPluginName, findPluginDirectoryEntry, findPluginEntry, findPluginRegistration, listPluginNames, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, readPluginPageBundleChunk, type PluginRegistration, type PluginRegistrationOptions, type PluginToolboxAgentConfig, type PluginPageBundleRegistration, type PluginToolboxContribution, type PluginToolboxLocale, type PluginToolboxSandboxPage, } from './pluginRegistry.js';
+export type { PluginCommandContext, PluginExecutionHost, PluginInvocationIdentity, PluginInvocationSource, } from './pluginExecution.js';
+export { executeRegisteredPlugin, type PluginExecutorOptions, type PluginExecutorDependencies, } 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, 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 {
@@ -18,48 +28,91 @@ export interface PluginInvocation {
 }
 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;
-    invoke(action: string, payload?: Record<string, any>, options?: UnifiedInvokeOptions): Promise<any>;
+    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>) => unknown | Promise<unknown>;
+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, 'invoke' | 'options' | 'progress'>, pluginName?: string): Promise<{
+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 './pluginState.js';
+export { PluginModelClient } from './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';