@mearl/client 2.20.6 → 2.22.0

package/dist/plugins/runtime/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/plugins/runtime/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/plugins/runtime/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/plugins/runtime/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/plugins/runtime/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/plugins/runtime/pluginHostFiles.d.ts

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

package/dist/plugins/runtime/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/plugins/runtime/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/plugins/runtime/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/plugins/runtime/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;
+}>;

package/dist/plugins/runtime/pluginHostServer.js

@@ -0,0 +1,252 @@
+import { randomUUID } from 'node:crypto';
+import { createServer } from 'node:net';
+import { chmodSync, rmSync } from 'node:fs';
+import { claimRecord, isProcessOwnerAlive, processIdentity, readRecord, removeInvalidRecord, removeRecordIfPid, writeRecordIfPid, } from '@mearl/daemon-core';
+import { PLUGIN_TASK_PROTOCOL_VERSION } from '../../generated/plugin-tasks.js';
+import { pluginHostPaths } from './pluginHostPaths.js';
+import { PluginHost } from './pluginHost.js';
+import { readPluginTaskMessages, writePluginTaskMessage } from '../pluginTaskWire.js';
+import { pluginExecutionError, serializePluginExecutionError } from './pluginExecutorProtocol.js';
+export async function startPluginHostServer(configuration = {}) {
+    const paths = pluginHostPaths();
+    const existing = readRecord(paths.lease);
+    if (existing && !isProcessOwnerAlive(existing))
+        removeRecordIfPid(paths.lease, existing.pid);
+    else if (!existing)
+        removeInvalidRecord(paths.lease);
+    const owner = {
+        pid: process.pid,
+        protocolVersion: PLUGIN_TASK_PROTOCOL_VERSION,
+        processIdentity: processIdentity(process.pid),
+    };
+    if (!claimRecord(paths.lease, owner))
+        throw Object.assign(new Error('Plugin execution service already has an owner'), {
+            code: 'PLUGIN_TASK_HOST_OWNED',
+        });
+    let host;
+    try {
+        host = new PluginHost(configuration);
+    }
+    catch (error) {
+        removeRecordIfPid(paths.lease, process.pid);
+        throw error;
+    }
+    const { tasks: manager, pages, state, models } = host;
+    if (!writeRecordIfPid(paths.lease, process.pid, {
+        ...owner,
+        ...manager.host,
+        socketPath: paths.socket,
+        startedAt: new Date().toISOString(),
+    }))
+        throw new Error('Plugin host lease ownership was lost');
+    const sessions = new Set();
+    let closing;
+    const server = createServer(socket => {
+        sessions.add(socket);
+        const disconnected = new AbortController();
+        let scope;
+        let sequence = 0;
+        let requests = 0;
+        const pending = new Map();
+        const bridge = {
+            id: randomUUID(),
+            get scope() {
+                if (!scope)
+                    throw new Error('Plugin task connection is not initialized');
+                return scope;
+            },
+            invoke(action, payload, options) {
+                if (socket.destroyed)
+                    return Promise.reject(Object.assign(new Error('The browser invocation bridge is unavailable'), {
+                        code: 'PLUGIN_TASK_BRIDGE_UNAVAILABLE',
+                    }));
+                const id = ++sequence;
+                return new Promise((resolve, reject) => {
+                    const timer = setTimeout(() => {
+                        pending.delete(id);
+                        reject(Object.assign(new Error('The browser invocation bridge timed out; external operation status is unknown'), { code: 'PLUGIN_TASK_BRIDGE_UNAVAILABLE', details: { action } }));
+                    }, Math.min(Math.max(options.timeoutSec ?? 180, 1), 3600) * 1000);
+                    pending.set(id, { resolve, reject, timer });
+                    void writePluginTaskMessage(socket, {
+                        type: 'invoke',
+                        id,
+                        action,
+                        payload,
+                        options,
+                    }).catch(error => {
+                        pending.delete(id);
+                        clearTimeout(timer);
+                        reject(error);
+                    });
+                });
+            },
+        };
+        const handle = async (method, input) => {
+            if (method === 'hello') {
+                if (scope || input.protocolVersion !== PLUGIN_TASK_PROTOCOL_VERSION)
+                    throw new Error('Plugin task protocol version mismatch');
+                if (!['public', 'toolbox', 'runtime'].includes(String(input.access)) ||
+                    !['service', 'caller'].includes(String(input.bridge)) ||
+                    !['cli', 'sdk', 'mcp', 'toolbox', 'runtime'].includes(String(input.source)) ||
+                    (input.plugin !== undefined &&
+                        (typeof input.plugin !== 'string' || !/^[a-z][a-z0-9-]*$/.test(input.plugin))) ||
+                    (input.scopeId !== undefined &&
+                        (typeof input.scopeId !== 'string' || input.scopeId.length > 256)) ||
+                    (input.access !== 'public' && (!input.plugin || input.bridge !== 'caller')))
+                    throw new Error('Invalid plugin task caller scope');
+                scope = {
+                    access: input.access,
+                    bridge: input.bridge,
+                    source: input.source,
+                    ...(input.plugin ? { plugin: String(input.plugin) } : {}),
+                    ...(input.scopeId ? { scopeId: String(input.scopeId) } : {}),
+                };
+                return {
+                    protocolVersion: PLUGIN_TASK_PROTOCOL_VERSION,
+                    host: manager.host,
+                    pid: process.pid,
+                };
+            }
+            if (!scope)
+                throw new Error('Plugin task connection requires a handshake');
+            if (method === 'status')
+                return {
+                    protocolVersion: PLUGIN_TASK_PROTOCOL_VERSION,
+                    host: manager.host,
+                    pid: process.pid,
+                };
+            if (method === 'diagnose')
+                return host.diagnose(input, scope);
+            if (method === 'state.call')
+                return state.call(String(input.plugin), input.input, bridge, input.options);
+            if (method === 'model.list')
+                return models.list(input.provider);
+            if (method === 'model.capabilities')
+                return (await import('../sdk/pluginModelDefinition.js')).pluginModelCapabilities();
+            if (method === 'page.call') {
+                const execution = input.execution;
+                return pages.call(String(input.plugin), input.input, bridge, input.options, execution
+                    ? {
+                        cwd: execution.cwd,
+                        environment: execution.environment,
+                        signal: disconnected.signal,
+                    }
+                    : undefined);
+            }
+            if (method === 'page.event') {
+                if (scope.access !== 'runtime')
+                    throw new Error('Page events require the browser runtime bridge');
+                return pages.receive(String(input.plugin), input.input, bridge, input.options);
+            }
+            if (method === 'start')
+                return manager.start(input, bridge);
+            if (method === 'resume')
+                return manager.resume(input, bridge);
+            if (method === 'list')
+                return manager.list(scope, input.activeOnly === true, input.cursor, input.limit);
+            if (method === 'shutdown') {
+                if (scope.access !== 'public')
+                    throw new Error('Tool pages cannot stop the plugin host');
+                return { stopped: true };
+            }
+            if (typeof input.taskId !== 'string')
+                throw new Error('Plugin task ID is required');
+            switch (method) {
+                case 'get':
+                    return manager.get(input.taskId, scope);
+                case 'checkpoint':
+                    return manager.checkpoint(input.taskId, scope);
+                case 'cancel':
+                    return manager.cancel(input.taskId, scope);
+                case 'events':
+                    return manager.events(input.taskId, scope, input.cursor, input.waitMs, disconnected.signal);
+                case 'result':
+                    return manager.resultChunk(input.taskId, scope, input.index);
+                default:
+                    throw new Error(`Unknown plugin task method: ${method}`);
+            }
+        };
+        readPluginTaskMessages(socket, message => {
+            if (message.type === 'invoke-result') {
+                const request = pending.get(message.id);
+                if (!request)
+                    return;
+                clearTimeout(request.timer);
+                pending.delete(message.id);
+                if (message.error)
+                    request.reject(pluginExecutionError(message.error));
+                else
+                    request.resolve(message.result);
+            }
+            else if (message.type === 'request') {
+                if (++requests > 64 ||
+                    !message.input ||
+                    typeof message.input !== 'object' ||
+                    Array.isArray(message.input)) {
+                    socket.destroy(new Error('Invalid or excessive plugin task requests'));
+                    return;
+                }
+                void Promise.resolve()
+                    .then(() => handle(message.method, message.input))
+                    .then(async (result) => {
+                    await writePluginTaskMessage(socket, { type: 'response', id: message.id, result });
+                    if (message.method === 'shutdown')
+                        setImmediate(() => {
+                            void close().catch(() => { });
+                        });
+                }, error => writePluginTaskMessage(socket, {
+                    type: 'response',
+                    id: message.id,
+                    error: serializePluginExecutionError(error),
+                }))
+                    .catch(() => socket.destroy())
+                    .finally(() => {
+                    requests--;
+                });
+            }
+            else
+                socket.destroy(new Error('Invalid plugin task message direction'));
+        });
+        socket.on('error', () => { });
+        socket.once('close', () => {
+            disconnected.abort();
+            sessions.delete(socket);
+            for (const request of pending.values()) {
+                clearTimeout(request.timer);
+                request.reject(Object.assign(new Error('The invocation bridge disconnected; external operation status may need reconciliation'), { code: 'PLUGIN_TASK_BRIDGE_UNAVAILABLE' }));
+            }
+            pending.clear();
+        });
+    });
+    async function close() {
+        closing ??= (async () => {
+            const servicesClosed = host.close();
+            for (const socket of sessions)
+                socket.destroy();
+            await servicesClosed;
+            await new Promise(resolve => server.close(() => resolve()));
+            if (removeRecordIfPid(paths.lease, process.pid) && process.platform !== 'win32')
+                rmSync(paths.socket, { force: true });
+        })();
+        return closing;
+    }
+    try {
+        if (process.platform !== 'win32')
+            rmSync(paths.socket, { force: true });
+        await new Promise((resolve, reject) => {
+            server.once('error', reject);
+            server.listen(paths.socket, () => {
+                server.off('error', reject);
+                resolve();
+            });
+        });
+        if (process.platform !== 'win32')
+            chmodSync(paths.socket, 0o600);
+    }
+    catch (error) {
+        removeRecordIfPid(paths.lease, process.pid);
+        await host.close();
+        throw error;
+    }
+    return { close, host, socketPath: paths.socket };
+}

package/dist/plugins/runtime/pluginModelCatalog.d.ts

@@ -0,0 +1,14 @@
+import type { PluginModelList, PluginModelOption } from '../../generated/plugin-models.js';
+/** A bounded shared lookup avoids starting a discovery process for each open tool. */
+export declare class PluginModelCatalog {
+    private readonly discover;
+    private readonly now;
+    private readonly controller;
+    private cached?;
+    private pending?;
+    constructor(discover?: (signal: AbortSignal) => Promise<PluginModelOption[]>, now?: () => number);
+    list(provider?: unknown): Promise<PluginModelList>;
+    private refresh;
+    private load;
+    close(): Promise<void>;
+}

package/dist/plugins/runtime/pluginModelCatalog.js

@@ -0,0 +1,51 @@
+/** A bounded shared lookup avoids starting a discovery process for each open tool. */
+export class PluginModelCatalog {
+    discover;
+    now;
+    controller = new AbortController();
+    cached;
+    pending;
+    constructor(discover = async (signal) => {
+        const { listCodexModels } = await import('@mearl/agent-runtime/codex');
+        return listCodexModels(signal);
+    }, now = Date.now) {
+        this.discover = discover;
+        this.now = now;
+    }
+    list(provider = 'codex') {
+        this.controller.signal.throwIfAborted();
+        if (provider !== 'codex')
+            throw new Error('Unsupported model provider');
+        if (this.cached) {
+            if (this.cached.expires <= this.now())
+                void this.refresh().catch(() => { });
+            return Promise.resolve(structuredClone(this.cached.value));
+        }
+        return this.refresh().then(value => structuredClone(value));
+    }
+    refresh() {
+        this.pending ??= this.load()
+            .catch(error => {
+            // A failed refresh keeps the last usable catalog and bounds repeat discovery.
+            if (this.cached)
+                this.cached.expires = this.now() + 30000;
+            throw error;
+        })
+            .finally(() => {
+            this.pending = undefined;
+        });
+        return this.pending;
+    }
+    async load() {
+        const signal = AbortSignal.any([this.controller.signal, AbortSignal.timeout(15000)]);
+        const value = { provider: 'codex', models: await this.discover(signal) };
+        signal.throwIfAborted();
+        this.cached = { value, expires: this.now() + 120000 };
+        return value;
+    }
+    async close() {
+        this.controller.abort();
+        await this.pending?.catch(() => { });
+        this.cached = undefined;
+    }
+}

package/dist/plugins/runtime/pluginModelSessions.d.ts

@@ -0,0 +1,16 @@
+import type { executeRegisteredPlugin } from './pluginExecutor.js';
+/** Opt-in conversations retain a supervised process and thread within one execution owner. */
+export declare class PluginModelSessions {
+    private readonly idleMs;
+    private readonly limit;
+    private readonly workerPath;
+    private readonly sessions;
+    private readonly closing;
+    private closed;
+    constructor(idleMs?: number, limit?: number, workerPath?: string);
+    execute(owner: string, ...args: Parameters<typeof executeRegisteredPlugin>): Promise<unknown>;
+    private run;
+    private remove;
+    release(owner: string): Promise<void>;
+    close(): Promise<void>;
+}