@mearl/client 2.20.6 → 2.21.0

package/dist/pluginExecutorProtocol.d.ts

@@ -0,0 +1,55 @@
+import type { PluginModelDiagnostic, PluginModelRequest } from './generated-plugin-models.js';
+import type { PluginInvocationIdentity, PluginExecutionError } from './generated-plugin-execution.js';
+import type { PluginInvocation, PluginOptions, PluginProgress } from './plugin.js';
+import type { PluginRegistration } from './pluginRegistry.js';
+export type PluginWorkerRequest = {
+    type: 'start';
+    plugin: string;
+    invocation: PluginInvocation;
+    options: PluginOptions;
+    identity: PluginInvocationIdentity;
+    entry: string;
+    entryVersion: string;
+    access: 'public' | 'toolbox' | 'runtime';
+    registration?: PluginRegistration;
+    describe?: boolean;
+    model?: PluginModelRequest;
+    recovery?: boolean;
+    migration?: boolean;
+    expectedRecovery?: string;
+} | {
+    type: 'cancel';
+    error: PluginExecutionError;
+} | {
+    type: 'invoke-progress';
+    id: number;
+    progress: PluginProgress;
+} | {
+    type: 'response';
+    id: number;
+    result?: unknown;
+    error?: PluginExecutionError;
+};
+export type PluginWorkerEvent = {
+    type: 'invoke';
+    id: number;
+    action: string;
+    payload: Record<string, unknown>;
+    options: PluginOptions;
+    stream?: boolean;
+} | {
+    type: 'diagnostic';
+    metadata: PluginModelDiagnostic;
+} | {
+    type: 'progress';
+    progress: PluginProgress;
+} | {
+    type: 'result';
+    json: string;
+} | {
+    type: 'error';
+    error: PluginExecutionError;
+};
+export declare const MAX_PLUGIN_RESULT_BYTES: number;
+export declare function serializePluginExecutionError(error: unknown): PluginExecutionError;
+export declare function pluginExecutionError(value: PluginExecutionError): Error;

package/dist/pluginExecutorProtocol.js

@@ -0,0 +1,47 @@
+export const MAX_PLUGIN_RESULT_BYTES = 64 * 1024 * 1024;
+export function serializePluginExecutionError(error) {
+    const value = error;
+    const metadata = Object.fromEntries(Object.entries(value && typeof value === 'object' ? value : {}).filter(([key, field]) => !['__proto__', 'prototype', 'constructor', 'message', 'stack', 'code', 'details'].includes(key) &&
+        (field === null || ['string', 'number', 'boolean'].includes(typeof field))));
+    const serialized = {
+        message: typeof value?.message === 'string' ? value.message : String(error),
+        ...(typeof value?.code === 'string' ? { code: value.code } : {}),
+        ...(value?.details && typeof value.details === 'object' && !Array.isArray(value.details)
+            ? { details: value.details }
+            : {}),
+        ...(Object.keys(metadata).length ? { metadata } : {}),
+    };
+    try {
+        if (Buffer.byteLength(JSON.stringify(serialized)) <= 64 * 1024)
+            return serialized;
+    }
+    catch {
+        /* Non-JSON diagnostic data cannot cross the executor boundary. */
+    }
+    return {
+        message: Buffer.from(serialized.message).subarray(0, 8192).toString('utf8'),
+        ...(serialized.code ? { code: serialized.code.slice(0, 256) } : {}),
+        details: { diagnosticTruncated: true },
+        metadata: Object.fromEntries(Object.entries(metadata)
+            .slice(0, 32)
+            .map(([key, field]) => [
+            key.slice(0, 128),
+            typeof field === 'string' ? field.slice(0, 512) : field,
+        ])),
+    };
+}
+export function pluginExecutionError(value) {
+    return Object.assign(new Error(value.message), {
+        ...Object.fromEntries(Object.entries(value.metadata ?? {}).filter(([key]) => ![
+            '__proto__',
+            'prototype',
+            'constructor',
+            'message',
+            'stack',
+            'code',
+            'details',
+        ].includes(key))),
+        ...(value.code ? { code: value.code } : {}),
+        ...(value.details ? { details: value.details } : {}),
+    });
+}

package/dist/pluginExecutorSupervisor.d.ts

@@ -0,0 +1,4 @@
+import { type Serializable } from 'node:child_process';
+import type { PluginWorkerEvent, PluginWorkerRequest } from './pluginExecutorProtocol.js';
+/** Ownership monitoring runs outside the event loop that executes plugin code. */
+export declare function supervisePluginExecutor<Request extends Serializable = PluginWorkerRequest, Event extends Serializable = PluginWorkerEvent>(workerUrl: string): void;

package/dist/pluginExecutorSupervisor.js

@@ -0,0 +1,63 @@
+import { execFileSync, fork } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+/** Ownership monitoring runs outside the event loop that executes plugin code. */
+export function supervisePluginExecutor(workerUrl) {
+    const child = fork(fileURLToPath(workerUrl), ['--command'], {
+        stdio: ['ignore', 'ignore', 'pipe', 'ipc'],
+        serialization: 'advanced',
+        execArgv: [],
+    });
+    let ending = false;
+    let forwarded = Promise.resolve();
+    child.stderr?.on('data', chunk => process.stderr.write(chunk));
+    const terminate = () => {
+        if (process.platform === 'win32') {
+            try {
+                execFileSync('taskkill', ['/PID', String(process.pid), '/T', '/F'], {
+                    stdio: 'ignore',
+                    windowsHide: true,
+                });
+            }
+            catch {
+                child.kill('SIGKILL');
+            }
+        }
+        else {
+            try {
+                process.kill(-process.pid, 'SIGKILL');
+            }
+            catch {
+                child.kill('SIGKILL');
+            }
+        }
+        process.exit(1);
+    };
+    process.on('disconnect', terminate);
+    process.on('message', (message) => {
+        if (!child.connected || ending)
+            return;
+        child.send(message, error => {
+            if (error && !ending)
+                terminate();
+        });
+    });
+    child.on('message', (message) => {
+        forwarded = forwarded.then(() => new Promise((resolve, reject) => {
+            if (!process.send || !process.connected) {
+                reject(new Error('Plugin owner disconnected'));
+                return;
+            }
+            process.send(message, error => (error ? reject(error) : resolve()));
+        }));
+        void forwarded.catch(terminate);
+    });
+    child.once('error', error => {
+        process.stderr.write(error.message);
+        terminate();
+    });
+    child.once('exit', code => {
+        ending = true;
+        child.stderr?.destroy();
+        void forwarded.then(() => process.exit(code ?? 1), terminate);
+    });
+}

package/dist/pluginHost.d.ts

@@ -0,0 +1,20 @@
+import { PluginTaskManager } from './pluginTaskManager.js';
+import type { PluginTaskManagerOptions } from './pluginTaskManager.js';
+import { PluginStateManager } from './pluginStateManager.js';
+import { PluginPageManager } from './pluginPageManager.js';
+import { PluginModelCatalog } from './pluginModelCatalog.js';
+import { PluginModelSessions } from './pluginModelSessions.js';
+import type { PluginDiagnosticOptions } from './generated-plugin-diagnostics.js';
+import type { PluginTaskScope } from './pluginTaskProtocol.js';
+/** The host owns service composition; task execution receives explicit service dependencies. */
+export declare class PluginHost {
+    readonly tasks: PluginTaskManager;
+    readonly state: PluginStateManager;
+    readonly pages: PluginPageManager;
+    readonly models: PluginModelCatalog;
+    readonly modelSessions: PluginModelSessions;
+    private closing?;
+    constructor(configuration?: PluginTaskManagerOptions);
+    diagnose(value: PluginDiagnosticOptions, scope: PluginTaskScope): import("./generated-plugin-diagnostics.js").PluginDiagnosticReport;
+    close(): Promise<void>;
+}

package/dist/pluginHost.js

@@ -0,0 +1,53 @@
+import { PluginTaskManager } from './pluginTaskManager.js';
+import { PluginStateManager } from './pluginStateManager.js';
+import { PluginPageManager } from './pluginPageManager.js';
+import { PluginModelCatalog } from './pluginModelCatalog.js';
+import { PluginModelSessions } from './pluginModelSessions.js';
+import { dirname, join } from 'node:path';
+import { buildDiagnosticReport, normalizeDiagnosticOptions } from './pluginDiagnostics.js';
+/** The host owns service composition; task execution receives explicit service dependencies. */
+export class PluginHost {
+    tasks;
+    state;
+    pages;
+    models = new PluginModelCatalog();
+    modelSessions;
+    closing;
+    constructor(configuration = {}) {
+        this.modelSessions = new PluginModelSessions(undefined, Math.max(2, configuration.modelConcurrency ?? 2), configuration.workerPath
+            ? join(dirname(configuration.workerPath), 'pluginModelSessionWorker.js')
+            : undefined);
+        this.tasks = new PluginTaskManager(configuration, {
+            state: (...args) => this.state.call(...args),
+            page: (...args) => this.pages.call(...args),
+            listModels: provider => this.models.list(provider),
+            model: (owner, ...args) => this.modelSessions.execute(owner, ...args),
+            releaseModels: owner => this.modelSessions.release(owner),
+        });
+        this.state = new PluginStateManager(this.tasks);
+        this.pages = new PluginPageManager(this.tasks, this.state, owner => this.modelSessions.release(owner));
+        this.state.resolveTarget = (...args) => this.pages.resolveStateTarget(...args);
+    }
+    diagnose(value, scope) {
+        const options = normalizeDiagnosticOptions(value);
+        if (scope.plugin && options.plugin && scope.plugin !== options.plugin)
+            throw Object.assign(new Error('Plugin task was not found'), {
+                code: 'PLUGIN_TASK_NOT_FOUND',
+            });
+        return buildDiagnosticReport(this.tasks.host, scope, options, this.tasks.store.diagnosticRecords(options.taskId), this.pages.diagnosticSnapshot());
+    }
+    close() {
+        this.closing ??= Promise.allSettled([
+            this.pages.close(),
+            this.tasks.close(),
+            this.state.close(),
+            this.models.close(),
+            this.modelSessions.close(),
+        ]).then(results => {
+            const failures = results.flatMap(result => result.status === 'rejected' ? [result.reason] : []);
+            if (failures.length)
+                throw new AggregateError(failures, 'Plugin host cleanup failed');
+        });
+        return this.closing;
+    }
+}

package/dist/pluginHostConnection.d.ts

@@ -0,0 +1,35 @@
+import type { PluginInvocationSource, PluginExecutionHost } from './generated-plugin-execution.js';
+import type { PluginExecutionContext } from './plugin.js';
+export interface PluginHostConnectionOptions {
+    source?: PluginInvocationSource;
+    plugin?: string;
+    access?: 'public' | 'toolbox' | 'runtime';
+    invoke?: PluginExecutionContext['invoke'];
+    runtimePath?: string;
+    socketPath?: string;
+    autoStart?: boolean;
+    scopeId?: string;
+}
+export interface PluginHostClientOptions extends PluginHostConnectionOptions {
+    /** The creator owns an injected connection; disconnecting a service client leaves it open. */
+    connection?: PluginHostConnection;
+}
+export interface HostStatus {
+    protocolVersion: number;
+    host: PluginExecutionHost;
+    pid: number;
+}
+/** One connection owns caller scope, discovery and bridge lifetime. */
+export declare class PluginHostConnection {
+    private readonly configuration;
+    get hasInvocationBridge(): boolean;
+    private connection?;
+    private socket?;
+    private readonly opening;
+    private generation;
+    constructor(configuration?: PluginHostConnectionOptions);
+    private connect;
+    private open;
+    request(method: string, input?: Record<string, unknown>, timeoutMs?: number): Promise<any>;
+    disconnect(): void;
+}

package/dist/pluginHostConnection.js

@@ -0,0 +1,257 @@
+import { spawn } from 'node:child_process';
+import { closeSync, mkdirSync, openSync } from 'node:fs';
+import { createConnection } from 'node:net';
+import { fileURLToPath } from 'node:url';
+import { claimRecord, isProcessOwnerAlive, processIdentity, readRecord, removeInvalidRecord, removeRecordIfPid, rotateLogIfNeeded, } from '@mearl/daemon-core';
+import { pluginHostPaths } from './pluginHostPaths.js';
+import { PLUGIN_TASK_PROTOCOL_VERSION } from './generated-plugin-tasks.js';
+import { readPluginTaskMessages, writePluginTaskMessage } from './pluginTaskWire.js';
+import { pluginExecutionError, serializePluginExecutionError } from './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 ??
+            fileURLToPath(new URL('./plugin-task-host.js', import.meta.url)));
+        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/pluginHostFiles.d.ts

@@ -0,0 +1 @@
+export declare function writePluginHostFile(file: string, data: string | Buffer): void;

package/dist/pluginHostFiles.js

@@ -0,0 +1,21 @@
+import { randomUUID } from 'node:crypto';
+import { closeSync, fsyncSync, mkdirSync, openSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import { dirname } from 'node:path';
+export function writePluginHostFile(file, data) {
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    let descriptor;
+    try {
+        descriptor = openSync(temporary, 'wx', 0o600);
+        writeFileSync(descriptor, data);
+        fsyncSync(descriptor);
+        closeSync(descriptor);
+        descriptor = undefined;
+        renameSync(temporary, file);
+    }
+    finally {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
+        rmSync(temporary, { force: true });
+    }
+}

package/dist/pluginHostPaths.d.ts

@@ -0,0 +1,11 @@
+export declare function pluginHostPaths(): {
+    registry: string;
+    home: string;
+    lease: string;
+    log: string;
+    installations: string;
+    revisions: string;
+    tasks: string;
+    state: string;
+    socket: string;
+};

package/dist/pluginHostPaths.js

@@ -0,0 +1,22 @@
+import { createHash } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pluginDirectory } from './pluginRegistry.js';
+export function pluginHostPaths() {
+    const registry = pluginDirectory();
+    const key = createHash('sha256').update(registry).digest('hex').slice(0, 16);
+    const home = join(registry, '.host');
+    return {
+        registry,
+        home,
+        lease: join(home, 'service.json'),
+        log: join(home, 'service.log'),
+        installations: join(home, 'installations'),
+        revisions: join(home, 'revisions'),
+        tasks: join(home, 'tasks'),
+        state: join(home, 'state'),
+        socket: process.platform === 'win32'
+            ? `\\\\.\\pipe\\mearl-plugin-${key}`
+            : join(tmpdir(), `mp-${key}.sock`),
+    };
+}

package/dist/pluginHostServer.d.ts

@@ -0,0 +1,7 @@
+import { PluginHost } from './pluginHost.js';
+import type { PluginTaskManagerOptions } from './pluginTaskManager.js';
+export declare function startPluginHostServer(configuration?: PluginTaskManagerOptions): Promise<{
+    close: () => Promise<void>;
+    host: PluginHost;
+    socketPath: string;
+}>;