@mearl/client 2.20.6 → 2.22.0

package/dist/plugins/clients/pluginHostConnection.js

@@ -0,0 +1,256 @@
+import { spawn } from 'node:child_process';
+import { closeSync, mkdirSync, openSync } from 'node:fs';
+import { createConnection } from 'node:net';
+import { PLUGIN_TASK_HOST_PATH } from '../../runtimePaths.js';
+import { claimRecord, isProcessOwnerAlive, processIdentity, readRecord, removeInvalidRecord, removeRecordIfPid, rotateLogIfNeeded, } from '@mearl/daemon-core';
+import { pluginHostPaths } from '../runtime/pluginHostPaths.js';
+import { PLUGIN_TASK_PROTOCOL_VERSION } from '../../generated/plugin-tasks.js';
+import { readPluginTaskMessages, writePluginTaskMessage } from '../pluginTaskWire.js';
+import { pluginExecutionError, serializePluginExecutionError, } from '../runtime/pluginExecutorProtocol.js';
+const starting = new Map();
+async function ensureHost(runtimePath) {
+    const paths = pluginHostPaths();
+    let work = starting.get(paths.registry);
+    if (!work) {
+        work = (async () => {
+            const lease = readRecord(paths.lease);
+            if (lease && isProcessOwnerAlive(lease)) {
+                if (lease.protocolVersion !== PLUGIN_TASK_PROTOCOL_VERSION)
+                    throw new Error('Plugin execution service protocol differs; stop the service before updating');
+                return;
+            }
+            const lock = `${paths.lease}.start`;
+            const existing = readRecord(lock);
+            if (existing && isProcessOwnerAlive(existing))
+                return;
+            if (existing)
+                removeRecordIfPid(lock, existing.pid);
+            else
+                removeInvalidRecord(lock);
+            if (!claimRecord(lock, { pid: process.pid, processIdentity: processIdentity(process.pid) }))
+                return;
+            try {
+                const owner = readRecord(paths.lease);
+                if (owner && isProcessOwnerAlive(owner))
+                    return;
+                mkdirSync(paths.home, { recursive: true, mode: 0o700 });
+                rotateLogIfNeeded(paths.log);
+                const log = openSync(paths.log, 'a', 0o600);
+                try {
+                    const child = spawn(process.execPath, [runtimePath], {
+                        detached: true,
+                        stdio: ['ignore', log, log],
+                        windowsHide: true,
+                    });
+                    await new Promise((resolve, reject) => {
+                        child.once('spawn', resolve);
+                        child.once('error', reject);
+                    });
+                    child.unref();
+                }
+                finally {
+                    closeSync(log);
+                }
+                const deadline = Date.now() + 10000;
+                while (Date.now() < deadline) {
+                    const ready = await new Promise(resolve => {
+                        const probe = createConnection(paths.socket);
+                        const finish = (value) => {
+                            probe.destroy();
+                            resolve(value);
+                        };
+                        probe.once('connect', () => finish(true));
+                        probe.once('error', () => finish(false));
+                        probe.setTimeout(200, () => finish(false));
+                    });
+                    if (ready)
+                        return;
+                    await new Promise(resolve => setTimeout(resolve, 50));
+                }
+                throw new Error('Plugin execution service startup timed out');
+            }
+            finally {
+                removeRecordIfPid(lock, process.pid);
+            }
+        })().finally(() => starting.delete(paths.registry));
+        starting.set(paths.registry, work);
+    }
+    await work;
+}
+/** One connection owns caller scope, discovery and bridge lifetime. */
+export class PluginHostConnection {
+    configuration;
+    get hasInvocationBridge() {
+        return Boolean(this.configuration.invoke);
+    }
+    connection;
+    socket;
+    opening = new Set();
+    generation = 0;
+    constructor(configuration = {}) {
+        this.configuration = configuration;
+    }
+    async connect(generation) {
+        const check = () => {
+            if (generation !== this.generation)
+                throw Object.assign(new Error('Plugin task client was disconnected'), {
+                    code: 'PLUGIN_TASK_CLIENT_DISCONNECTED',
+                });
+        };
+        const connectOnce = () => {
+            check();
+            return this.open(this.configuration.socketPath ?? pluginHostPaths().socket, generation);
+        };
+        try {
+            return await connectOnce();
+        }
+        catch (error) {
+            check();
+            if (this.configuration.autoStart === false || this.configuration.socketPath)
+                throw error;
+            const code = error.code;
+            if (!['ENOENT', 'ECONNREFUSED', 'PLUGIN_TASK_CONNECTION_LOST'].includes(code ?? ''))
+                throw error;
+        }
+        await ensureHost(this.configuration.runtimePath ?? PLUGIN_TASK_HOST_PATH);
+        const deadline = Date.now() + 10000;
+        let failure;
+        do {
+            check();
+            try {
+                return await connectOnce();
+            }
+            catch (error) {
+                failure = error;
+                await new Promise(resolve => setTimeout(resolve, 100));
+            }
+        } while (Date.now() < deadline);
+        throw new Error('Plugin execution service did not become ready; inspect its service.log', {
+            cause: failure,
+        });
+    }
+    async open(socketPath, generation) {
+        const socket = createConnection(socketPath);
+        this.opening.add(socket);
+        const pending = new Map();
+        let sequence = 0;
+        const fail = (error) => {
+            for (const request of pending.values()) {
+                clearTimeout(request.timer);
+                request.reject(error);
+            }
+            pending.clear();
+        };
+        socket.on('error', fail);
+        socket.once('close', () => {
+            fail(Object.assign(new Error('Plugin execution service connection was lost'), {
+                code: 'PLUGIN_TASK_CONNECTION_LOST',
+            }));
+            if (this.socket === socket) {
+                this.connection = undefined;
+                this.socket = undefined;
+            }
+        });
+        const request = (method, input = {}, timeoutMs = 15000) => new Promise((resolve, reject) => {
+            const id = ++sequence;
+            const timer = setTimeout(() => {
+                pending.delete(id);
+                reject(Object.assign(new Error('Plugin task request timed out; the task may still be running'), { code: 'PLUGIN_TASK_REQUEST_TIMEOUT' }));
+            }, timeoutMs);
+            pending.set(id, { resolve, reject, timer });
+            void writePluginTaskMessage(socket, { type: 'request', id, method, input }).catch(error => {
+                clearTimeout(timer);
+                pending.delete(id);
+                reject(error);
+            });
+        });
+        readPluginTaskMessages(socket, message => {
+            if (message.type === 'response') {
+                const call = pending.get(message.id);
+                if (!call)
+                    return;
+                clearTimeout(call.timer);
+                pending.delete(message.id);
+                if (message.error)
+                    call.reject(pluginExecutionError(message.error));
+                else
+                    call.resolve(message.result);
+            }
+            else if (message.type === 'invoke') {
+                void Promise.resolve()
+                    .then(() => {
+                    if (!this.configuration.invoke)
+                        throw new Error('Plugin task client has no invocation bridge');
+                    return this.configuration.invoke(message.action, message.payload, message.options);
+                })
+                    .then(result => writePluginTaskMessage(socket, { type: 'invoke-result', id: message.id, result }), error => writePluginTaskMessage(socket, {
+                    type: 'invoke-result',
+                    id: message.id,
+                    error: serializePluginExecutionError(error),
+                }))
+                    .catch(() => { });
+            }
+            else
+                socket.destroy(new Error('Invalid plugin task response direction'));
+        });
+        try {
+            await new Promise((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    socket.destroy();
+                    reject(new Error('Plugin task connection timed out'));
+                }, 2000);
+                socket.once('connect', () => {
+                    clearTimeout(timer);
+                    resolve();
+                });
+                socket.once('error', error => {
+                    clearTimeout(timer);
+                    reject(error);
+                });
+            });
+            const scope = {
+                access: this.configuration.access ?? 'public',
+                source: this.configuration.source ?? 'sdk',
+                bridge: this.configuration.invoke ? 'caller' : 'service',
+                ...(this.configuration.plugin ? { plugin: this.configuration.plugin } : {}),
+                ...(this.configuration.scopeId ? { scopeId: this.configuration.scopeId } : {}),
+            };
+            const status = await request('hello', {
+                ...scope,
+                protocolVersion: PLUGIN_TASK_PROTOCOL_VERSION,
+            });
+            if (status.protocolVersion !== PLUGIN_TASK_PROTOCOL_VERSION)
+                throw new Error('Plugin task protocol version mismatch');
+            if (generation !== this.generation || socket.destroyed)
+                throw new Error('Plugin task client was disconnected');
+            this.socket = socket;
+            return { socket, request, status };
+        }
+        catch (error) {
+            socket.destroy();
+            throw error;
+        }
+        finally {
+            this.opening.delete(socket);
+        }
+    }
+    async request(method, input = {}, timeoutMs) {
+        if (!this.connection) {
+            const attempt = this.connect(this.generation);
+            this.connection = attempt;
+            void attempt.catch(() => {
+                if (this.connection === attempt)
+                    this.connection = undefined;
+            });
+        }
+        return (await this.connection).request(method, input, timeoutMs);
+    }
+    disconnect() {
+        this.generation++;
+        this.socket?.destroy();
+        for (const socket of this.opening)
+            socket.destroy();
+        this.socket = undefined;
+        this.connection = undefined;
+    }
+}

package/dist/plugins/clients/pluginModels.d.ts

@@ -0,0 +1,17 @@
+import type { PluginHostClientOptions } from './pluginHostConnection.js';
+import { PluginTaskClient } from './pluginTasks.js';
+import type { PluginTaskStartOptions, PluginTaskWaitOptions } from './pluginTasks.js';
+import type { PluginModelRequest, PluginModelResult, PluginModelCapability, PluginModelList } from '../../generated/plugin-models.js';
+import type { PluginTaskStartResult } from '../../generated/plugin-tasks.js';
+export type * from '../../generated/plugin-models.js';
+export declare class PluginModelClient {
+    readonly tasks: PluginTaskClient;
+    constructor(options?: PluginHostClientOptions);
+    capabilities(): Promise<{
+        providers: PluginModelCapability[];
+    }>;
+    list(provider?: string): Promise<PluginModelList>;
+    start(plugin: string, request: PluginModelRequest, options?: PluginTaskStartOptions): Promise<PluginTaskStartResult>;
+    run(plugin: string, request: PluginModelRequest, options?: PluginTaskStartOptions & Pick<PluginTaskWaitOptions, 'signal' | 'onProgress'>): Promise<PluginModelResult>;
+    disconnect(): void;
+}

package/dist/plugins/clients/pluginModels.js

@@ -0,0 +1,47 @@
+import { PluginTaskClient } from './pluginTasks.js';
+export class PluginModelClient {
+    tasks;
+    constructor(options = {}) {
+        this.tasks = new PluginTaskClient(options);
+    }
+    capabilities() {
+        return this.tasks.connection.request('model.capabilities');
+    }
+    list(provider = 'codex') {
+        return this.tasks.connection.request('model.list', { provider }, 20000);
+    }
+    async start(plugin, request, options = {}) {
+        const { cwd = process.cwd(), environment = process.env, executionTimeoutMs, idempotencyKey, ...routing } = options;
+        return this.tasks.connection.request('start', {
+            kind: 'model',
+            plugin,
+            command: 'model',
+            input: { request },
+            cwd,
+            environment: Object.fromEntries(Object.entries(environment).filter((entry) => entry[1] !== undefined)),
+            options: routing,
+            executionTimeoutMs,
+            idempotencyKey,
+        });
+    }
+    async run(plugin, request, options = {}) {
+        const { signal, onProgress, ...execution } = options;
+        signal?.throwIfAborted();
+        const started = await this.start(plugin, request, execution);
+        const cancel = () => {
+            void this.tasks.cancel(started.taskId).catch(() => { });
+        };
+        signal?.addEventListener('abort', cancel, { once: true });
+        try {
+            if (signal?.aborted)
+                cancel();
+            return (await this.tasks.wait(started.taskId, { onProgress }));
+        }
+        finally {
+            signal?.removeEventListener('abort', cancel);
+        }
+    }
+    disconnect() {
+        this.tasks.disconnect();
+    }
+}

package/dist/plugins/clients/pluginPages.d.ts

@@ -0,0 +1,21 @@
+import type { PluginHostConnection } from './pluginHostConnection.js';
+import type { UnifiedClientOptions, UnifiedInvokeOptions } from '../../unified.js';
+import type { PluginPageInstance, PluginPageEvents, PluginPageOperation } from '../../generated/plugin-pages.js';
+export type { PluginPageInstance, PluginPageEvents, PluginPageRuntime, PluginPageActivation, PluginPageTarget, PluginPageOperation, } from '../../generated/plugin-pages.js';
+export declare class PluginPageClient {
+    private readonly connection?;
+    private readonly client?;
+    constructor(configuration?: UnifiedClientOptions, connection?: PluginHostConnection | undefined);
+    call(plugin: string, operation: PluginPageOperation, input?: Record<string, unknown>, options?: UnifiedInvokeOptions): Promise<any>;
+    attach(plugin: string, input: Record<string, unknown>, options?: UnifiedInvokeOptions): Promise<PluginPageInstance>;
+    get(plugin: string, instanceId: string): Promise<PluginPageInstance>;
+    list(plugin: string): Promise<{
+        instances: PluginPageInstance[];
+    }>;
+    send(plugin: string, instanceId: string, message: unknown, options?: {
+        timeoutSec?: number;
+    }): Promise<unknown>;
+    detach(plugin: string, instanceId: string): Promise<PluginPageInstance>;
+    events(plugin: string, instanceId: string, cursor?: number, waitMs?: number): Promise<PluginPageEvents>;
+    disconnect(): void;
+}

package/dist/plugins/clients/pluginPages.js

@@ -0,0 +1,46 @@
+import { UnifiedClient } from '../../unified.js';
+export class PluginPageClient {
+    connection;
+    client;
+    constructor(configuration = {}, connection) {
+        this.connection = connection;
+        if (!connection)
+            this.client = new UnifiedClient(configuration);
+    }
+    call(plugin, operation, input = {}, options = {}) {
+        if (this.connection)
+            return this.connection.request('page.call', {
+                plugin,
+                input: { ...input, operation },
+                options,
+                execution: {
+                    cwd: process.cwd(),
+                    environment: Object.fromEntries(Object.entries(process.env).filter(entry => entry[1] !== undefined)),
+                },
+            }, Math.max(120000, typeof input.timeoutSec === 'number' && Number.isFinite(input.timeoutSec)
+                ? (Math.min(300, input.timeoutSec) + 5) * 1000
+                : 0));
+        return this.client.invoke('plugin_page', { ...input, plugin, operation }, options);
+    }
+    attach(plugin, input, options = {}) {
+        return this.call(plugin, 'attach', input, options);
+    }
+    get(plugin, instanceId) {
+        return this.call(plugin, 'get', { instanceId });
+    }
+    list(plugin) {
+        return this.call(plugin, 'list');
+    }
+    send(plugin, instanceId, message, options = {}) {
+        return this.call(plugin, 'send', { instanceId, message, ...options }, options);
+    }
+    detach(plugin, instanceId) {
+        return this.call(plugin, 'detach', { instanceId });
+    }
+    events(plugin, instanceId, cursor = 0, waitMs = 0) {
+        return this.call(plugin, 'events', { instanceId, cursor, waitMs });
+    }
+    disconnect() {
+        this.client?.disconnect();
+    }
+}

package/dist/plugins/clients/pluginState.d.ts

@@ -0,0 +1,26 @@
+import { PluginHostConnection } from './pluginHostConnection.js';
+import type { PluginHostClientOptions } from './pluginHostConnection.js';
+import type { PluginOptions } from '../sdk/plugin.js';
+import type { PluginStateOperation, PluginStateSnapshot, PluginStateList, PluginStateTransaction } from '../../generated/plugin-state.js';
+export type * from '../../generated/plugin-state.js';
+export declare class PluginStateClient {
+    private readonly options;
+    readonly connection: PluginHostConnection;
+    constructor(options?: PluginHostClientOptions);
+    call(plugin: string, collection: string, operation: PluginStateOperation, input?: Record<string, unknown>, options?: PluginOptions): Promise<any>;
+    get(plugin: string, collection: string, key: string, input?: {
+        instanceId?: string;
+    }): Promise<PluginStateSnapshot>;
+    getMany(plugin: string, collection: string, keys: string[], input?: {
+        instanceId?: string;
+    }): Promise<PluginStateList>;
+    list(plugin: string, collection: string, input?: Record<string, unknown>): Promise<PluginStateList>;
+    transact(plugin: string, collection: string, transaction: PluginStateTransaction, input?: {
+        instanceId?: string;
+    }): Promise<{
+        revision: number;
+        schemaVersion: number;
+        reused?: boolean;
+    }>;
+    disconnect(): void;
+}

package/dist/plugins/clients/pluginState.js

@@ -0,0 +1,28 @@
+import { PluginHostConnection } from './pluginHostConnection.js';
+export class PluginStateClient {
+    options;
+    connection;
+    constructor(options = {}) {
+        this.options = options;
+        this.connection = options.connection ?? new PluginHostConnection(options);
+    }
+    call(plugin, collection, operation, input = {}, options = {}) {
+        return this.connection.request('state.call', { plugin, input: { ...input, collection, operation }, options }, 30000);
+    }
+    get(plugin, collection, key, input = {}) {
+        return this.call(plugin, collection, 'get', { ...input, key });
+    }
+    getMany(plugin, collection, keys, input = {}) {
+        return this.call(plugin, collection, 'get-many', { ...input, keys });
+    }
+    list(plugin, collection, input = {}) {
+        return this.call(plugin, collection, 'list', input);
+    }
+    transact(plugin, collection, transaction, input = {}) {
+        return this.call(plugin, collection, 'transact', { ...input, transaction });
+    }
+    disconnect() {
+        if (!this.options.connection)
+            this.connection.disconnect();
+    }
+}

package/dist/plugins/clients/pluginTasks.d.ts

@@ -0,0 +1,51 @@
+import { PluginHostConnection } from './pluginHostConnection.js';
+import type { PluginHostClientOptions, HostStatus as PluginHostStatus } from './pluginHostConnection.js';
+import type { PluginTaskCheckpoint } from '../../generated/plugin-recovery.js';
+import type { PluginDiagnosticOptions, PluginDiagnosticReport } from '../../generated/plugin-diagnostics.js';
+import type { PluginTask, PluginTaskEvents, PluginTaskListResult, PluginTaskResultChunk, PluginTaskStartResult } from '../../generated/plugin-tasks.js';
+import type { PluginInvocation, PluginOptions } from '../sdk/plugin.js';
+export type { PluginTask, PluginTaskEvents, PluginTaskListResult, PluginTaskStartResult };
+export interface PluginTaskStartOptions extends PluginOptions {
+    cwd?: string;
+    environment?: NodeJS.ProcessEnv;
+    executionTimeoutMs?: number;
+    idempotencyKey?: string;
+}
+export interface PluginTaskWaitOptions {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    readResult?: boolean;
+    onProgress?: (progress: PluginTask['progress'], task: PluginTask) => void;
+}
+export type PluginTaskClientOptions = PluginHostClientOptions;
+/** Background execution stays on this host; disconnecting a caller never cancels its tasks. */
+export declare class PluginTaskClient {
+    private readonly configuration;
+    readonly connection: PluginHostConnection;
+    constructor(configuration?: PluginTaskClientOptions);
+    private request;
+    status(): Promise<PluginHostStatus>;
+    diagnose(options?: PluginDiagnosticOptions): Promise<PluginDiagnosticReport>;
+    checkpoint(taskId: string): Promise<PluginTaskCheckpoint | null>;
+    resume(taskId: string, options?: {
+        environment?: NodeJS.ProcessEnv;
+        revision?: 'original' | 'current';
+    }): Promise<PluginTaskStartResult>;
+    start(plugin: string, invocation: PluginInvocation, options?: PluginTaskStartOptions): Promise<PluginTaskStartResult>;
+    get(taskId: string): Promise<PluginTask>;
+    list(activeOnly?: boolean, page?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<PluginTaskListResult>;
+    cancel(taskId: string): Promise<PluginTask>;
+    events(taskId: string, cursor?: number, waitMs?: number): Promise<PluginTaskEvents>;
+    resultChunk(taskId: string, index: number): Promise<PluginTaskResultChunk>;
+    result(taskId: string): Promise<unknown>;
+    subscribe(taskId: string, options?: {
+        cursor?: number;
+        signal?: AbortSignal;
+    }): AsyncGenerator<PluginTaskEvents>;
+    wait(taskId: string, options?: PluginTaskWaitOptions): Promise<unknown>;
+    stopHost(): Promise<void>;
+    disconnect(): void;
+}

package/dist/plugins/clients/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 '../runtime/pluginHostPaths.js';
+import { UnifiedClient, decodeBrowserTarget } from '../../unified.js';
+import { isPluginTaskActive } from '../../generated/plugin-tasks.js';
+import { pluginExecutionError } from '../runtime/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();
+    }
+}