@mearl/client 2.20.6 → 2.21.0

package/dist/pluginTasks.js

@@ -0,0 +1,181 @@
+import { PluginHostConnection } from './pluginHostConnection.js';
+import { createHash } from 'node:crypto';
+import { isProcessOwnerAlive, readRecord } from '@mearl/daemon-core';
+import { pluginHostPaths } from './pluginHostPaths.js';
+import { UnifiedClient, decodeBrowserTarget } from './unified.js';
+import { isPluginTaskActive } from './generated-plugin-tasks.js';
+import { pluginExecutionError } from './pluginExecutorProtocol.js';
+function localWait(promise, signal, timeoutMs = Infinity) {
+    return new Promise((resolve, reject) => {
+        const abort = () => {
+            cleanup();
+            reject(signal?.reason ?? new Error('Plugin task wait aborted'));
+        };
+        const timer = Number.isFinite(timeoutMs)
+            ? setTimeout(() => {
+                cleanup();
+                reject(Object.assign(new Error('Waiting for the plugin task timed out; execution continues'), { code: 'PLUGIN_TASK_WAIT_TIMEOUT' }));
+            }, Math.max(0, timeoutMs))
+            : undefined;
+        const cleanup = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', abort);
+        };
+        signal?.addEventListener('abort', abort, { once: true });
+        promise.then(value => {
+            cleanup();
+            resolve(value);
+        }, error => {
+            cleanup();
+            reject(error);
+        });
+        if (signal?.aborted)
+            abort();
+    });
+}
+/** Background execution stays on this host; disconnecting a caller never cancels its tasks. */
+export class PluginTaskClient {
+    configuration;
+    connection;
+    constructor(configuration = {}) {
+        this.configuration = configuration;
+        this.connection = configuration.connection ?? new PluginHostConnection(configuration);
+    }
+    request(method, input = {}, timeoutMs) {
+        return this.connection.request(method, input, timeoutMs);
+    }
+    status() {
+        return this.request('status');
+    }
+    diagnose(options = {}) {
+        return this.request('diagnose', { ...options });
+    }
+    checkpoint(taskId) {
+        return this.request('checkpoint', { taskId });
+    }
+    resume(taskId, options = {}) {
+        return this.request('resume', {
+            taskId,
+            revision: options.revision,
+            environment: Object.fromEntries(Object.entries(options.environment ?? process.env).filter((entry) => entry[1] !== undefined)),
+        }, 45000);
+    }
+    async start(plugin, invocation, options = {}) {
+        const { cwd = process.cwd(), environment = process.env, executionTimeoutMs, idempotencyKey, ...routing } = options;
+        if (!this.connection.hasInvocationBridge &&
+            routing.browser &&
+            !decodeBrowserTarget(routing.browser)) {
+            const client = new UnifiedClient();
+            try {
+                const selection = await client.invoke('browser_select_browser', { browser: routing.browser }, routing);
+                if (!selection?.selected?.browserId)
+                    throw new Error('Cannot resolve plugin task browser target');
+                routing.browser = selection.selected.browserId;
+            }
+            finally {
+                client.disconnect();
+            }
+        }
+        return this.request('start', {
+            plugin,
+            command: invocation.command,
+            input: invocation.input,
+            cwd,
+            environment: Object.fromEntries(Object.entries(environment).filter((entry) => entry[1] !== undefined)),
+            options: routing,
+            executionTimeoutMs,
+            idempotencyKey,
+        });
+    }
+    get(taskId) {
+        return this.request('get', { taskId });
+    }
+    list(activeOnly = false, page = {}) {
+        return this.request('list', { activeOnly, ...page });
+    }
+    cancel(taskId) {
+        return this.request('cancel', { taskId });
+    }
+    events(taskId, cursor = 0, waitMs = 0) {
+        return this.request('events', { taskId, cursor, waitMs }, waitMs + 15000);
+    }
+    resultChunk(taskId, index) {
+        return this.request('result', { taskId, index });
+    }
+    async result(taskId) {
+        const task = await this.get(taskId);
+        if (task.state !== 'success' || !task.result)
+            throw new Error('Plugin task has no successful result');
+        const parts = [];
+        for (let index = 0; index < task.result.chunks; index++) {
+            const chunk = await this.resultChunk(taskId, index);
+            if (chunk.taskId !== taskId ||
+                chunk.index !== index ||
+                chunk.sha256 !== task.result.sha256 ||
+                chunk.bytes !== task.result.bytes ||
+                chunk.chunks !== task.result.chunks)
+                throw new Error('Plugin task result chunk identity mismatch');
+            parts.push(Buffer.from(chunk.data, 'base64'));
+        }
+        const bytes = Buffer.concat(parts);
+        if (bytes.length !== task.result.bytes ||
+            createHash('sha256').update(bytes).digest('hex') !== task.result.sha256)
+            throw new Error('Plugin task result integrity check failed');
+        return JSON.parse(bytes.toString('utf8')).value;
+    }
+    async *subscribe(taskId, options = {}) {
+        let cursor = options.cursor ?? 0;
+        while (true) {
+            options.signal?.throwIfAborted();
+            const page = await localWait(this.events(taskId, cursor, 25000), options.signal);
+            options.signal?.throwIfAborted();
+            yield page;
+            cursor = page.nextCursor;
+            if (!isPluginTaskActive(page.task.state) && cursor >= page.task.sequence)
+                return;
+        }
+    }
+    async wait(taskId, options = {}) {
+        if (options.timeoutMs !== undefined &&
+            (!Number.isSafeInteger(options.timeoutMs) || options.timeoutMs < 1))
+            throw new Error('Invalid plugin task wait timeout');
+        const deadline = options.timeoutMs === undefined ? Infinity : Date.now() + options.timeoutMs;
+        let cursor = 0;
+        let lastSequence = -1;
+        while (true) {
+            options.signal?.throwIfAborted();
+            if (Date.now() >= deadline)
+                throw Object.assign(new Error('Waiting for the plugin task timed out; execution continues'), { code: 'PLUGIN_TASK_WAIT_TIMEOUT' });
+            const page = await localWait(this.events(taskId, cursor, Math.min(1000, Math.max(0, deadline - Date.now()))), options.signal, deadline - Date.now());
+            options.signal?.throwIfAborted();
+            cursor = page.nextCursor;
+            if (page.task.progress && page.task.sequence !== lastSequence)
+                options.onProgress?.(page.task.progress, page.task);
+            lastSequence = page.task.sequence;
+            if (page.task.state === 'success')
+                return options.readResult === false
+                    ? page.task
+                    : localWait(this.result(taskId), options.signal, deadline - Date.now());
+            if (!isPluginTaskActive(page.task.state))
+                throw pluginExecutionError(page.task.error ?? { message: `Plugin task ended with ${page.task.state}` });
+        }
+    }
+    async stopHost() {
+        const original = await this.status();
+        await this.request('shutdown');
+        this.disconnect();
+        const deadline = Date.now() + 15000;
+        while (true) {
+            const lease = readRecord(pluginHostPaths().lease);
+            if (!lease || lease.epoch !== original.host.epoch || !isProcessOwnerAlive(lease))
+                return;
+            if (Date.now() >= deadline)
+                throw new Error('Plugin execution service did not finish stopping');
+            await new Promise(resolve => setTimeout(resolve, 50));
+        }
+    }
+    disconnect() {
+        if (!this.configuration.connection)
+            this.connection.disconnect();
+    }
+}

package/dist/pythonPlugin.d.ts

@@ -1,20 +1,31 @@
-import type { PluginOptions } from './plugin.js';
+import type { PluginOptions, PluginApp } from './plugin.js';
+import type { PluginCommandContext } from './pluginExecution.js';
 export interface PythonPluginCommand {
     description: string;
     signature: string;
     toolboxOnly: boolean;
+    runtimeOnly: boolean;
+    recoveryOnly: boolean;
+    migrationOnly: boolean;
 }
 export interface PythonPluginDescriptor {
     commands: PythonPluginCommand[];
     description?: string;
     name?: string;
     toolbox?: unknown;
+    pageRuntime?: unknown;
     appProfiles?: unknown;
+    stateStorage?: unknown;
+    taskRecovery?: unknown;
 }
 export interface PythonPluginApp {
+    state?: PluginApp['state'];
+    model?: PluginApp['model'];
+    checkpoint?: PluginApp['checkpoint'];
+    page?: PluginApp['page'];
     readonly options: Readonly<PluginOptions>;
     invoke(action: string, payload?: Record<string, any>, options?: PluginOptions): Promise<any>;
     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>, app: PythonPluginApp): 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>;