@mearl/client 2.20.6 → 2.21.0

package/dist/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('./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/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/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/pluginModelDefinition.d.ts

@@ -0,0 +1,6 @@
+import type { PluginModelCapability, PluginModelRequest, PluginModelResult } from './generated-plugin-models.js';
+export declare function pluginModelCapabilities(): {
+    providers: PluginModelCapability[];
+};
+export declare function normalizePluginModel(value: unknown): PluginModelRequest;
+export declare function validatePluginModelResult(request: PluginModelRequest, value: unknown): PluginModelResult;

package/dist/pluginModelDefinition.js

@@ -0,0 +1,75 @@
+import { CODEX_MODEL_CAPABILITY } from '@mearl/agent-runtime/capabilities';
+import { compilePluginStateSchema } from './pluginStateDefinition.js';
+export function pluginModelCapabilities() {
+    return { providers: [CODEX_MODEL_CAPABILITY] };
+}
+export function normalizePluginModel(value) {
+    const request = value;
+    if (!request ||
+        typeof request !== 'object' ||
+        Array.isArray(request) ||
+        typeof request.prompt !== 'string' ||
+        !request.prompt.trim() ||
+        Buffer.byteLength(JSON.stringify(request)) > 256 * 1024 ||
+        (request.instructions !== undefined && typeof request.instructions !== 'string') ||
+        (request.conversation !== undefined &&
+            (typeof request.conversation !== 'string' ||
+                !/^[a-zA-Z0-9:_-]{1,80}$/.test(request.conversation))) ||
+        (request.model !== undefined &&
+            (typeof request.model !== 'string' || !request.model.trim() || request.model.length > 256)) ||
+        (request.reasoningEffort !== undefined &&
+            !['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'].includes(request.reasoningEffort)) ||
+        Object.keys(request).some(key => ![
+            'provider',
+            'mode',
+            'prompt',
+            'instructions',
+            'model',
+            'reasoningEffort',
+            'outputSchema',
+            'permissions',
+            'conversation',
+        ].includes(key)))
+        throw new Error('Invalid model execution request');
+    const capability = pluginModelCapabilities().providers.find(item => item.provider === request.provider);
+    if (!capability?.modes.includes(request.mode) ||
+        (request.mode === 'agent' && !capability.permissions.includes(request.permissions)) ||
+        (request.mode === 'generate' && request.permissions !== undefined))
+        throw Object.assign(new Error('Requested model mode or permissions are unsupported; choose an advertised capability explicitly'), { code: 'PLUGIN_MODEL_CAPABILITY_UNSUPPORTED' });
+    if (request.outputSchema !== undefined) {
+        if (!capability.structuredOutput ||
+            !request.outputSchema ||
+            typeof request.outputSchema !== 'object' ||
+            Array.isArray(request.outputSchema) ||
+            request.outputSchema.$async ||
+            Buffer.byteLength(JSON.stringify(request.outputSchema)) > 64 * 1024)
+            throw new Error('Invalid model output schema');
+        compilePluginStateSchema(request.outputSchema);
+    }
+    return JSON.parse(JSON.stringify(request));
+}
+export function validatePluginModelResult(request, value) {
+    const result = value;
+    if (!result ||
+        typeof result.text !== 'string' ||
+        result.provider !== request.provider ||
+        result.mode !== request.mode)
+        throw new Error('Invalid model execution result');
+    if (request.outputSchema) {
+        let output;
+        try {
+            output = JSON.parse(result.text);
+        }
+        catch {
+            throw Object.assign(new Error('Model returned invalid JSON'), {
+                code: 'PLUGIN_MODEL_SCHEMA_INVALID',
+            });
+        }
+        if (!compilePluginStateSchema(request.outputSchema)(output))
+            throw Object.assign(new Error('Model result does not match the output schema'), {
+                code: 'PLUGIN_MODEL_SCHEMA_INVALID',
+            });
+        return { ...result, output };
+    }
+    return result;
+}

package/dist/pluginModelSessionWorker.d.ts

@@ -0,0 +1,23 @@
+import type { PluginModelDiagnostic, PluginModelRequest, PluginModelResult } from './generated-plugin-models.js';
+import type { PluginExecutionError } from './generated-plugin-execution.js';
+export type ModelSessionRequest = {
+    request: PluginModelRequest;
+};
+export type ModelSessionEvent = {
+    type: 'diagnostic';
+    metadata: PluginModelDiagnostic;
+} | {
+    type: 'delta';
+    delta: string;
+    index: number;
+    metadata?: {
+        itemId?: string;
+        phase?: string;
+    };
+} | {
+    type: 'result';
+    result: PluginModelResult;
+} | {
+    type: 'error';
+    error: PluginExecutionError;
+};

package/dist/pluginModelSessionWorker.js

@@ -0,0 +1,60 @@
+import { readFileSync } from 'node:fs';
+import { serializePluginExecutionError } from './pluginExecutorProtocol.js';
+import { supervisePluginExecutor } from './pluginExecutorSupervisor.js';
+if (process.argv[2] !== '--command') {
+    supervisePluginExecutor(import.meta.url);
+}
+else {
+    const ready = import('@mearl/agent-runtime/codex').then(runtime => ({
+        runtime,
+        provider: new runtime.CodexAgentProvider(() => { }, JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version),
+    }));
+    const conversation = {};
+    let busy = false;
+    let turns = 0;
+    const diagnostic = {};
+    const send = (value) => {
+        if (process.connected)
+            process.send?.(value);
+    };
+    process.on('disconnect', () => process.exit(1));
+    process.on('message', (message) => {
+        if (busy) {
+            process.exit(1);
+            return;
+        }
+        busy = true;
+        void ready
+            .then(async ({ runtime, provider }) => {
+            send({ type: 'diagnostic', metadata: diagnostic });
+            if (turns >= 32) {
+                if (conversation.threadId)
+                    await provider.closeSession(conversation.threadId);
+                delete conversation.threadId;
+                turns = 0;
+            }
+            const result = await runtime.runCodexModel(message.request, {
+                cwd: process.cwd(),
+                conversation,
+                signal: new AbortController().signal,
+                onDiagnostic: metadata => {
+                    for (const [key, value] of Object.entries(metadata)) {
+                        if (!['retryCount', 'activeModel'].includes(key))
+                            Object.assign(diagnostic, { [key]: value });
+                    }
+                    send({ type: 'diagnostic', metadata });
+                },
+                onDelta: (delta, index, metadata) => send({ type: 'delta', delta, index, metadata }),
+            }, provider);
+            turns++;
+            return result;
+        })
+            .then(result => {
+            busy = false;
+            send({ type: 'result', result });
+        }, error => {
+            busy = false;
+            send({ type: 'error', error: serializePluginExecutionError(error) });
+        });
+    });
+}

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