@mearl/client 2.20.5 → 2.21.0

package/dist/pluginModelSessions.js

@@ -0,0 +1,234 @@
+import { fork } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { processIdentity } from '@mearl/daemon-core';
+import { pluginExecutionError } from './pluginExecutorProtocol.js';
+import { stopPluginProcessTree } from './pluginProcessTree.js';
+import { validatePluginModelResult } from './pluginModelDefinition.js';
+/** Opt-in conversations retain a supervised process and thread within one execution owner. */
+export class PluginModelSessions {
+    idleMs;
+    limit;
+    workerPath;
+    sessions = new Map();
+    closing = new Set();
+    closed = false;
+    constructor(idleMs = 5 * 60_000, limit = 2, workerPath = fileURLToPath(new URL('./pluginModelSessionWorker.js', import.meta.url))) {
+        this.idleMs = idleMs;
+        this.limit = limit;
+        this.workerPath = workerPath;
+    }
+    execute(owner, ...args) {
+        const [plugin, , context, options = {}] = args;
+        const request = options.model;
+        const configuration = Object.fromEntries(Object.entries(request)
+            .filter(([key]) => !['prompt', 'outputSchema'].includes(key))
+            .sort(([a], [b]) => a.localeCompare(b)));
+        const key = createHash('sha256')
+            .update(JSON.stringify([
+            owner,
+            plugin,
+            context.invocation?.installationId,
+            context.invocation?.revision,
+            options.cwd,
+            Object.entries(options.environment ?? {}).sort(([a], [b]) => a.localeCompare(b)),
+            configuration,
+        ]))
+            .digest('hex');
+        options.signal?.throwIfAborted();
+        if (this.closed)
+            return Promise.reject(new Error('Model conversations are closed'));
+        let session = this.sessions.get(key);
+        if (!session || session.closed) {
+            if (this.sessions.size >= this.limit) {
+                const idle = [...this.sessions.values()].find(value => !value.queued);
+                if (!idle)
+                    return Promise.reject(new Error('Model conversation limit reached'));
+                void this.remove(idle).catch(error => console.error('Model conversation cleanup failed:', error));
+            }
+            const child = fork(this.workerPath, [], {
+                stdio: ['ignore', 'ignore', 'pipe', 'ipc'],
+                serialization: 'advanced',
+                execArgv: [],
+                detached: process.platform !== 'win32',
+                cwd: options.cwd,
+                env: options.environment,
+            });
+            // The supervisor remains responsible for process-tree cleanup if its host disconnects.
+            const exited = new Promise(resolve => child.once('close', () => resolve()));
+            session = { owner, child, tail: Promise.resolve(), queued: 0, closed: false, exited };
+            const current = session;
+            child.on('error', () => {
+                void this.remove(current).catch(error => console.error('Model conversation cleanup failed:', error));
+            });
+            child.once('exit', () => {
+                void this.remove(current).catch(error => console.error('Model conversation cleanup failed:', error));
+            });
+            this.sessions.set(key, session);
+        }
+        this.sessions.delete(key);
+        this.sessions.set(key, session);
+        clearTimeout(session.timer);
+        const current = session;
+        current.queued++;
+        let started = false;
+        const operation = current.tail
+            .catch(() => { })
+            .then(async () => {
+            options.signal?.throwIfAborted();
+            if (current.closed)
+                throw new Error('Model conversation has ended');
+            started = true;
+            return this.run(current, args);
+        });
+        current.tail = operation.finally(() => {
+            current.queued--;
+            if (!current.queued && !current.closed) {
+                current.timer = setTimeout(() => {
+                    void this.remove(current).catch(error => console.error('Model conversation cleanup failed:', error));
+                }, this.idleMs);
+                current.timer.unref();
+            }
+        });
+        void current.tail.catch(() => { });
+        if (!options.signal)
+            return operation;
+        const signal = options.signal;
+        return new Promise((resolve, reject) => {
+            const abort = () => {
+                if (!started)
+                    reject(Object.assign(new Error('Model execution cancelled'), {
+                        code: 'PLUGIN_EXECUTION_CANCELLED',
+                    }));
+            };
+            signal.addEventListener('abort', abort, { once: true });
+            if (signal.aborted)
+                abort();
+            void operation
+                .then(resolve, reject)
+                .finally(() => signal.removeEventListener('abort', abort));
+        });
+    }
+    run(session, args) {
+        const options = args[3], request = options.model, child = session.child;
+        return new Promise((resolve, reject) => {
+            let finished = false, stderr = '';
+            let timer;
+            const finish = async (failure, result) => {
+                if (finished)
+                    return;
+                finished = true;
+                clearTimeout(timer);
+                options.signal?.removeEventListener('abort', abort);
+                child.removeListener('message', message);
+                child.removeListener('error', failed);
+                child.removeListener('exit', exited);
+                child.stderr?.removeListener('data', capture);
+                try {
+                    if (failure)
+                        await this.remove(session);
+                    options.onExecutorStopped?.();
+                    if (failure)
+                        reject(failure);
+                    else
+                        resolve(result);
+                }
+                catch (error) {
+                    reject(error);
+                }
+            };
+            const failed = (error) => {
+                void finish(error);
+            };
+            const exited = () => failed(new Error(stderr || 'Model conversation executor exited'));
+            const abort = () => failed(Object.assign(new Error('Model execution cancelled'), {
+                code: 'PLUGIN_EXECUTION_CANCELLED',
+            }));
+            const capture = (chunk) => {
+                stderr = (stderr + chunk.toString()).slice(-65536);
+            };
+            const message = (event) => {
+                if (finished)
+                    return;
+                try {
+                    if (event.type === 'result')
+                        void finish(undefined, validatePluginModelResult(request, event.result));
+                    else if (event.type === 'error')
+                        failed(pluginExecutionError(event.error));
+                    else if (event.type === 'diagnostic')
+                        options.onDiagnostic?.(event.metadata);
+                    else if (event.type === 'delta')
+                        options.onProgress?.({
+                            message: 'model.delta',
+                            data: { delta: event.delta, index: event.index, ...event.metadata, partial: true },
+                        });
+                }
+                catch (error) {
+                    void finish(error);
+                }
+            };
+            child.on('message', message);
+            child.once('error', failed);
+            child.once('exit', exited);
+            child.stderr?.on('data', capture);
+            options.signal?.addEventListener('abort', abort, { once: true });
+            if (options.executionTimeoutMs)
+                timer = setTimeout(() => failed(Object.assign(new Error('Model execution deadline exceeded'), {
+                    code: 'PLUGIN_EXECUTION_DEADLINE',
+                })), options.executionTimeoutMs);
+            try {
+                if (options.signal?.aborted) {
+                    abort();
+                    return;
+                }
+                if (child.pid)
+                    options.onExecutorStarted?.({
+                        pid: child.pid,
+                        processIdentity: processIdentity(child.pid),
+                    });
+                child.send({ request }, error => {
+                    if (error)
+                        failed(error);
+                });
+            }
+            catch (error) {
+                void finish(error);
+            }
+        });
+    }
+    remove(session) {
+        if (session.closing)
+            return session.closing;
+        session.closed = true;
+        clearTimeout(session.timer);
+        for (const [key, value] of this.sessions)
+            if (value === session)
+                this.sessions.delete(key);
+        session.closing = (session.child.pid ? stopPluginProcessTree(session.child.pid) : Promise.resolve())
+            .then(() => {
+            let timer;
+            const timeout = new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error('Model conversation did not exit')), 2000);
+            });
+            return Promise.race([session.exited, timeout]).finally(() => clearTimeout(timer));
+        })
+            .catch(cause => {
+            throw Object.assign(new Error('Unable to confirm model conversation cleanup', { cause }), {
+                code: 'PLUGIN_EXECUTOR_CLEANUP_FAILED',
+                details: { executionStopped: false },
+            });
+        });
+        this.closing.add(session);
+        void session.closing.finally(() => this.closing.delete(session)).catch(() => { });
+        return session.closing;
+    }
+    async release(owner) {
+        await Promise.all([...new Set([...this.sessions.values(), ...this.closing])]
+            .filter(value => value.owner === owner)
+            .map(value => this.remove(value)));
+    }
+    async close() {
+        this.closed = true;
+        await Promise.all([...new Set([...this.sessions.values(), ...this.closing])].map(value => this.remove(value)));
+    }
+}

package/dist/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/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/pluginPageBundle.js

@@ -29,9 +29,7 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
   let port = null;
   let requestSequence = 0;
   const pending = new Map();
-  const pageEventListeners = new Map();
   const contextListeners = new Set();
-  let subscriptionSequence = 0;
   let resolveReady;
   const ready = new Promise(resolve => { resolveReady = resolve; });
 
@@ -87,17 +85,24 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
   };
 
   const subscribe = async (source, target, listener) => {
-    if (source !== 'page' || !target || !Number.isSafeInteger(target.tabId) || target.tabId < 0 ||
-        typeof target.runtimeId !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(target.runtimeId) ||
-        typeof listener !== 'function') throw new Error('Invalid event subscription');
-    const subscriptionId = String(++subscriptionSequence);
-    pageEventListeners.set(subscriptionId, listener);
-    try { await requestHost('subscribe', { source, target, subscriptionId }); }
-    catch (error) { pageEventListeners.delete(subscriptionId); throw error; }
-    return () => {
-      if (!pageEventListeners.delete(subscriptionId)) return;
-      void requestHost('unsubscribe', { subscriptionId }).catch(() => {});
+    if (source !== 'page' || !target || typeof target.instanceId !== 'string' ||
+        !/^pi_[0-9a-f-]{36}$/i.test(target.instanceId) || typeof listener !== 'function') throw new Error('Invalid page event subscription');
+    let stopped = false, timer, cursor = target.cursor ?? 0;
+    const poll = async (waitMs = 0) => {
+      let delay = 0;
+      try {
+        const page = await invoke('host.page.events', { instanceId: target.instanceId, cursor, waitMs });
+        if (stopped) return;
+        const metadata = { url: page.instance.target.url, instance: page.instance, gap: page.gap };
+        if (page.gap) listener({ type: 'resync' }, metadata);
+        for (const event of page.events) { if (stopped) return; listener(event, metadata); }
+        cursor = page.nextCursor;
+        if (page.instance.state !== 'active') return;
+      } catch (error) { if (stopped) return; delay = 500; listener({ type: 'connection-error', error: { message: error.message } }); }
+      if (!stopped) timer = setTimeout(() => { void poll(25000); }, delay);
     };
+    await poll();
+    return () => { stopped = true; clearTimeout(timer); };
   };
 
   const handleExternalLinkClick = event => {
@@ -404,7 +409,62 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
     if (context) listener(context);
     return () => contextListeners.delete(listener);
   };
-  const api = { invoke, subscribe, onContextChange, ready: async () => { await ready; return context; }, runAgentTask, setAgentGuides, setAgentPanelVisible, setQueryParam };
+  const readTaskResult = async taskId => {
+    const task = await invoke('host.task.get', { taskId });
+    const reference = task.result;
+    if (task.state !== 'success' || !reference || !Number.isSafeInteger(reference.bytes) ||
+        reference.bytes < 1 || reference.bytes > 64 * 1024 * 1024 ||
+        !Number.isSafeInteger(reference.chunks) || reference.chunks < 1 || reference.chunks > 1024 ||
+        !/^[a-f0-9]{64}$/.test(reference.sha256)) throw new Error('Invalid task result reference');
+    const data = new Uint8Array(reference.bytes);
+    let offset = 0;
+    for (let index = 0; index < reference.chunks; index++) {
+      const chunk = await invoke('host.task.result', { taskId, index });
+      if (chunk.taskId !== taskId || chunk.index !== index || chunk.sha256 !== reference.sha256 ||
+          chunk.bytes !== reference.bytes || chunk.chunks !== reference.chunks) throw new Error('Task result chunk identity mismatch');
+      const binary = atob(chunk.data);
+      if (offset + binary.length > data.length) throw new Error('Task result size mismatch');
+      for (let i = 0; i < binary.length; i++) data[offset++] = binary.charCodeAt(i);
+    }
+    const hash = Array.from(new Uint8Array(await crypto.subtle.digest('SHA-256', data)),
+      value => value.toString(16).padStart(2, '0')).join('');
+    if (offset !== reference.bytes || hash !== reference.sha256) throw new Error('Task result integrity check failed');
+    return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(data)).value;
+  };
+  const waitTask = async (taskId, options = {}) => {
+    if (options.timeoutMs !== undefined && (!Number.isSafeInteger(options.timeoutMs) || options.timeoutMs < 1)) throw new Error('Invalid task wait timeout');
+    const deadline = options.timeoutMs === undefined ? Infinity : Date.now() + options.timeoutMs;
+    let cursor = 0, lastSequence = -1;
+    for (;;) {
+      options.signal?.throwIfAborted();
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) throw Object.assign(new Error('Waiting for the task timed out; execution continues'), { code: 'PLUGIN_TASK_WAIT_TIMEOUT' });
+      let page;
+      try {
+        page = await invoke('host.task.events', { taskId, cursor, waitMs: Math.min(1000, remaining) });
+        options.onConnectionChange?.(false);
+      } catch (error) { options.onConnectionChange?.(true); throw error; }
+      options.signal?.throwIfAborted();
+      const task = page.task;
+      cursor = page.nextCursor;
+      if (task.progress && task.sequence !== lastSequence) options.onProgress?.(task.progress, task);
+      lastSequence = task.sequence;
+      if (task.state === 'success') return readTaskResult(taskId);
+      if (!['queued', 'running', 'cancelling'].includes(task.state))
+        throw Object.assign(new Error(task.error?.message || 'Plugin task ended with ' + task.state), { code: task.error?.code });
+    }
+  };
+  const listTasks = async (options = {}) => {
+    const tasks = [];
+    let cursor;
+    do {
+      const page = await invoke('host.task.list', { activeOnly: options.activeOnly !== false, ...(cursor ? { cursor } : {}) });
+      tasks.push(...page.tasks);
+      cursor = page.nextCursor;
+    } while (cursor);
+    return { tasks };
+  };
+  const api = { invoke, subscribe, readTaskResult, waitTask, listTasks, onContextChange, ready: async () => { await ready; return context; }, runAgentTask, setAgentGuides, setAgentPanelVisible, setQueryParam };
   const ui = globalThis.__mearlToolboxUi;
   if (ui !== undefined) {
     if (!ui || typeof ui !== 'object' || ui.runtime !== 'preact') {
@@ -448,10 +508,7 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
     port = nextPort;
     port.onmessage = responseEvent => {
       const response = responseEvent.data;
-      if (response?.type === 'event' && typeof response.subscriptionId === 'string') {
-        pageEventListeners.get(response.subscriptionId)?.(response.event, response.metadata);
-        return;
-      }
+
       if (response?.type === 'context') {
         applyContext(response.context);
         return;

package/dist/pluginPageDefinition.d.ts

@@ -0,0 +1,3 @@
+import type { PluginPageRuntime } from './generated-plugin-pages.js';
+export declare function normalizePluginPageRuntime(value: unknown): PluginPageRuntime | undefined;
+export declare function compilePluginPageSchema(schema: Record<string, unknown>): import("ajv/dist/core.js").AnyValidateFunction<unknown>;

package/dist/pluginPageDefinition.js

@@ -0,0 +1,62 @@
+import { parse } from 'acorn';
+import { Ajv } from 'ajv';
+import { isPluginPageMatchPattern } from './generated-plugin-pages.js';
+const validators = new WeakMap();
+export function normalizePluginPageRuntime(value) {
+    if (value === undefined)
+        return undefined;
+    const runtime = value;
+    if (!runtime ||
+        runtime.version !== 1 ||
+        !Array.isArray(runtime.matches) ||
+        !runtime.matches.length ||
+        runtime.matches.length > 64 ||
+        !runtime.matches.every(isPluginPageMatchPattern) ||
+        typeof runtime.code !== 'string' ||
+        Buffer.byteLength(runtime.code) > 384 * 1024 ||
+        Buffer.byteLength(JSON.stringify(runtime)) > 448 * 1024)
+        throw new Error('Invalid plugin pageRuntime declaration');
+    const program = parse(`(${runtime.code}\n)`, { ecmaVersion: 'latest' });
+    const statement = program.body[0];
+    if (program.body.length !== 1 ||
+        statement.type !== 'ExpressionStatement' ||
+        !['ArrowFunctionExpression', 'FunctionExpression'].includes(statement.expression?.type ?? ''))
+        throw new Error('pageRuntime.code must be a self-contained function expression');
+    if (runtime.events !== undefined &&
+        (!runtime.events ||
+            typeof runtime.events !== 'object' ||
+            Array.isArray(runtime.events) ||
+            Object.keys(runtime.events).length > 32))
+        throw new Error('Invalid page runtime events');
+    for (const [name, event] of Object.entries(runtime.events ?? {})) {
+        if (!/^[a-z][a-z0-9-]{0,63}$/.test(name) ||
+            !event ||
+            !/^[a-z][a-z0-9-]*$/.test(event.command) ||
+            !event.schema ||
+            typeof event.schema !== 'object' ||
+            Array.isArray(event.schema) ||
+            (event.policy !== undefined && !['serial', 'latest', 'parallel'].includes(event.policy)) ||
+            (event.concurrency !== undefined &&
+                (!Number.isSafeInteger(event.concurrency) ||
+                    event.concurrency < 1 ||
+                    event.concurrency > 8)) ||
+            (event.maxPending !== undefined &&
+                (!Number.isSafeInteger(event.maxPending) ||
+                    event.maxPending < 1 ||
+                    event.maxPending > 64)) ||
+            event.schema.$async)
+            throw new Error(`Invalid page event binding: ${name}`);
+        compilePluginPageSchema(event.schema);
+    }
+    if (runtime.initialize !== undefined && !/^[a-z][a-z0-9-]*$/.test(runtime.initialize))
+        throw new Error('Invalid page runtime initialize command');
+    return JSON.parse(JSON.stringify(runtime));
+}
+export function compilePluginPageSchema(schema) {
+    let validate = validators.get(schema);
+    if (!validate) {
+        validate = new Ajv({ strict: true, allErrors: false }).compile(schema);
+        validators.set(schema, validate);
+    }
+    return validate;
+}

package/dist/pluginPageManager.d.ts

@@ -0,0 +1,57 @@
+import type { PluginDiagnosticPage } from './generated-plugin-diagnostics.js';
+import type { PluginStateManager } from './pluginStateManager.js';
+import type { PluginInvocationIdentity } from './generated-plugin-execution.js';
+import type { PluginRevision } from './pluginRevision.js';
+import type { PluginOptions } from './plugin.js';
+import type { PluginPageTarget } from './generated-plugin-pages.js';
+import type { PluginTaskBridge, PluginTaskManager } from './pluginTaskManager.js';
+interface Execution {
+    cwd: string;
+    environment: Record<string, string>;
+    signal?: AbortSignal;
+    revision?: PluginRevision;
+    expectedTarget?: PluginPageTarget;
+    parentIdentity?: PluginInvocationIdentity;
+}
+/** The browser owns document identity; this service owns revisions and event execution. */
+export declare class PluginPageManager {
+    private readonly tasks;
+    private readonly states;
+    private readonly releaseModels?;
+    private readonly instances;
+    private readonly changes;
+    private readonly heartbeat;
+    private readonly reconciling;
+    private closed;
+    private readonly describing;
+    constructor(tasks: PluginTaskManager, states: PluginStateManager, releaseModels?: ((owner: string) => Promise<void>) | undefined);
+    resolveStateTarget(plugin: string, instanceId: unknown, bridge: PluginTaskBridge, options: PluginOptions): Promise<{
+        target: {
+            browserSessionId: string;
+            tabId: number;
+            frameId: string | number;
+            documentId: string;
+            url: string;
+        };
+        assertActive: () => void;
+    }>;
+    diagnosticSnapshot(): PluginDiagnosticPage[];
+    private reconcile;
+    private bounded;
+    private invoke;
+    private unavailable;
+    private validate;
+    private own;
+    private bind;
+    private append;
+    private waitForChange;
+    private invalidate;
+    call(plugin: string, input: Record<string, unknown>, bridge: PluginTaskBridge, options?: PluginOptions, execution?: Execution): Promise<any>;
+    receive(plugin: string, input: Record<string, unknown>, bridge: PluginTaskBridge, options?: PluginOptions): Promise<unknown>;
+    private drain;
+    private execute;
+    private start;
+    private wait;
+    close(): Promise<void>;
+}
+export {};