@mearl/client 3.0.0-beta.3 → 3.0.0-beta.5

package/dist/plugins/runtime/pluginRevision.js

@@ -2,13 +2,10 @@ import { createHash, randomUUID } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { claimRecord, readRecord, writeRecord } from '@mearl/daemon-core';
-import { isBuiltin } from 'node:module';
-import { parse } from 'acorn';
 import { pluginHostPaths } from './pluginHostPaths.js';
 import { skillManifestPath } from '../skillManifest.js';
 import { findPluginRegistration, PluginError } from '../pluginRegistry.js';
 const MAX_REVISION_BYTES = 64 * 1024 * 1024;
-const validatedSources = new Set();
 function within(root, file) {
     const path = relative(root, file);
     return path === '' || (!path.startsWith(`..${sep}`) && path !== '..' && !isAbsolute(path));
@@ -68,48 +65,6 @@ function readSources(root) {
     visit(root, new Set());
     return files;
 }
-function validateDependencies(files) {
-    const paths = new Set(files.map(file => file.path));
-    for (const file of files) {
-        if (!/\.[cm]?js$/.test(file.path))
-            continue;
-        const tree = parse(file.bytes.toString('utf8'), {
-            ecmaVersion: 'latest',
-            sourceType: 'module',
-            allowReturnOutsideFunction: true,
-        });
-        const check = (specifier) => {
-            if (typeof specifier !== 'string' || isBuiltin(specifier))
-                return;
-            if (!specifier.startsWith('./') && !specifier.startsWith('../'))
-                throw new PluginError('PLUGIN_SOURCE_NOT_SELF_CONTAINED', `后台任务需要自包含 Skill，请先打包依赖: ${file.path}: ${specifier}`);
-            const local = resolve('/source', dirname(file.path), specifier);
-            const normalized = relative('/source', local).split(sep).join('/');
-            if (!within('/source', local) ||
-                ![normalized, `${normalized}.js`, `${normalized}.json`, `${normalized}/index.js`].some(path => paths.has(path)))
-                throw new PluginError('PLUGIN_SOURCE_NOT_SELF_CONTAINED', `依赖不在 Skill 快照中: ${file.path}: ${specifier}`);
-        };
-        const visit = (node) => {
-            if (!node || typeof node !== 'object')
-                return;
-            if (['ImportDeclaration', 'ExportNamedDeclaration', 'ExportAllDeclaration'].includes(node.type))
-                check(node.source?.value);
-            if (node.type === 'ImportExpression')
-                check(node.source?.value);
-            if (node.type === 'CallExpression' &&
-                node.callee?.type === 'Identifier' &&
-                node.callee.name === 'require')
-                check(node.arguments[0]?.value);
-            for (const value of Object.values(node)) {
-                if (Array.isArray(value))
-                    value.forEach(visit);
-                else if (value && typeof value === 'object')
-                    visit(value);
-            }
-        };
-        visit(tree);
-    }
-}
 function fingerprint(files, entry) {
     return createHash('sha256')
         .update(JSON.stringify({ entry, files: files.map(file => [file.path, file.hash, file.executable]) }))
@@ -139,12 +94,6 @@ export function capturePluginRevision(plugin) {
     const relativeEntry = relative(root, entry).split(sep).join('/');
     const files = readSources(root);
     const revision = fingerprint(files, relativeEntry);
-    if (!validatedSources.has(revision)) {
-        validateDependencies(files);
-        if (validatedSources.size >= 64)
-            validatedSources.delete(validatedSources.values().next().value);
-        validatedSources.add(revision);
-    }
     const revisionRoot = join(paths.revisions, installation.installationId, revision);
     if (!existsSync(revisionRoot)) {
         const temporary = `${revisionRoot}.${randomUUID()}.tmp`;

package/dist/plugins/runtime/pluginStateStore.js

@@ -3,7 +3,6 @@ import { existsSync, readFileSync, readdirSync, statSync, rmSync } from 'node:fs
 import { join, sep } from 'node:path';
 import { pluginHostPaths } from './pluginHostPaths.js';
 import { writePluginHostFile } from './pluginHostFiles.js';
-import { compilePluginStateSchema } from '../sdk/pluginStateDefinition.js';
 function fail(code, message) {
     throw Object.assign(new Error(message), { code });
 }
@@ -316,7 +315,6 @@ export class PluginStateStore {
                 else
                     delete entry.expiresAt;
             }
-        const validate = compilePluginStateSchema(definition.schema);
         for (const operation of input.operations) {
             key(operation.key);
             if (names.has(operation.key) ||
@@ -328,9 +326,9 @@ export class PluginStateStore {
                 delete entries[operation.key];
                 continue;
             }
-            if (!validate(operation.value) ||
-                Buffer.byteLength(JSON.stringify(operation.value)) > 256 * 1024)
-                fail('PLUGIN_STATE_SCHEMA_INVALID', 'State value does not match the declared schema or exceeds 256 KiB');
+            const json = JSON.stringify(operation.value);
+            if (json === undefined || Buffer.byteLength(json) > 256 * 1024)
+                fail('PLUGIN_STATE_INVALID', 'State value must be JSON within 256 KiB');
             const ttl = operation.ttlMs ?? definition.ttlMs ?? 86400000;
             if (definition.storage === 'persistent' && operation.ttlMs !== undefined)
                 fail('PLUGIN_STATE_INVALID', 'Persistent state does not accept TTL');
@@ -342,9 +340,6 @@ export class PluginStateStore {
                 ...(definition.storage !== 'persistent' ? { expiresAt: now + ttl } : {}),
             };
         }
-        for (const entry of Object.values(entries))
-            if (!validate(entry.value))
-                fail('PLUGIN_STATE_SCHEMA_INVALID', 'Migration leaves entries incompatible with the target schema');
         const commit = {
             revision,
             schemaVersion: definition.schemaVersion,

package/dist/plugins/runtime/pluginTaskManager.js

@@ -1,7 +1,6 @@
 import { normalizeModelDiagnostic, diagnosticBinding } from './pluginDiagnostics.js';
 import { pluginModelCapabilities, normalizePluginModel, validatePluginModelResult, } from '../sdk/pluginModelDefinition.js';
 import { pluginRecoverySignature } from '../sdk/pluginRecoveryDefinition.js';
-import { compilePluginStateSchema } from '../sdk/pluginStateDefinition.js';
 import { createHash, randomUUID } from 'node:crypto';
 import { EventEmitter } from 'node:events';
 import { isAbsolute, join, relative, sep } from 'node:path';
@@ -482,8 +481,7 @@ export class PluginTaskManager {
             signal.throwIfAborted();
             if (!sourceDefinition ||
                 sourceDefinition.checkpointVersion !== record.checkpoint.version ||
-                digest(sourceDefinition.schema) !== record.checkpoint.schemaHash ||
-                !compilePluginStateSchema(sourceDefinition.schema)(record.checkpoint.data))
+                digest(sourceDefinition.schema) !== record.checkpoint.schemaHash)
                 throw error('PLUGIN_TASK_RECOVERY_UNAVAILABLE', 'Checkpoint does not match the retained recovery declaration');
             let checkpoint = structuredClone(record.checkpoint);
             let declarationHash = pluginRecoverySignature(sourceDefinition);
@@ -542,8 +540,6 @@ export class PluginTaskManager {
                         data: JSON.parse(json),
                     };
                 }
-                if (!compilePluginStateSchema(target.schema)(checkpoint.data))
-                    throw error('PLUGIN_TASK_CHECKPOINT_INVALID', 'Migrated checkpoint does not match the target schema');
             }
             signal.throwIfAborted();
             // Admission is synchronous after both immutable snapshots and execution ownership are verified.
@@ -809,8 +805,8 @@ export class PluginTaskManager {
                         if (declaration &&
                             payload.expectedDeclaration !== pluginRecoverySignature(declaration))
                             throw error('PLUGIN_RECOVERY_DECLARATION_CHANGED', 'Checkpoint declaration differs from the executing command');
-                        if (!declaration || !compilePluginStateSchema(declaration.schema)(data))
-                            throw error('PLUGIN_TASK_CHECKPOINT_INVALID', 'Checkpoint is undeclared or does not match its schema');
+                        if (!declaration)
+                            throw error('PLUGIN_TASK_CHECKPOINT_INVALID', 'Checkpoint is undeclared');
                         const current = this.store.read(taskId);
                         if (current.task.state !== 'running' ||
                             payload.expectedSequence !== (current.checkpoint?.sequence ?? 0))

package/dist/plugins/sdk/plugin.js

@@ -72,7 +72,7 @@ function missingPluginEntryMessage(entry, pluginName) {
         `插件：${name}`,
         `入口：${entry}`,
         '',
-        `卸载命令：npx --@mearl:registry=https://registry.npmjs.org @mearl/setup plugin uninstall ${name}`,
+        `卸载命令：npx @mearl/setup plugin uninstall ${name}`,
     ].join('\n');
 }
 const registrationRefreshes = new Map();

package/dist/plugins/sdk/pluginModelDefinition.js

@@ -1,5 +1,4 @@
 import { CODEX_MODEL_CAPABILITY } from '@mearl/agent-runtime/capabilities';
-import { compilePluginStateSchema } from './pluginStateDefinition.js';
 export function pluginModelCapabilities() {
     return { providers: [CODEX_MODEL_CAPABILITY] };
 }
@@ -44,7 +43,6 @@ export function normalizePluginModel(value) {
             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));
 }
@@ -65,10 +63,6 @@ export function validatePluginModelResult(request, value) {
                 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/plugins/sdk/pluginPageDefinition.d.ts

@@ -1,3 +1,2 @@
 import type { PluginPageRuntime } from '@mearl/browser-core';
 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/plugins/sdk/pluginPageDefinition.js

@@ -1,7 +1,5 @@
-import { parse } from 'acorn';
-import { Ajv } from 'ajv';
+import { Script } from 'node:vm';
 import { isPluginPageMatchPattern } from '@mearl/browser-core';
-const validators = new WeakMap();
 export function normalizePluginPageRuntime(value) {
     if (value === undefined)
         return undefined;
@@ -16,12 +14,7 @@ export function normalizePluginPageRuntime(value) {
         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');
+    new Script(`(${runtime.code}\n)`, { filename: 'plugin-page-runtime.js' });
     if (runtime.events !== undefined &&
         (!runtime.events ||
             typeof runtime.events !== 'object' ||
@@ -46,17 +39,8 @@ export function normalizePluginPageRuntime(value) {
                     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/plugins/sdk/pluginRecoveryDefinition.js

@@ -1,5 +1,4 @@
 import { createHash } from 'node:crypto';
-import { compilePluginStateSchema } from './pluginStateDefinition.js';
 export function normalizePluginTaskRecovery(value) {
     if (value === undefined)
         return;
@@ -22,7 +21,6 @@ export function normalizePluginTaskRecovery(value) {
             Array.isArray(definition.schema) ||
             definition.schema.$async)
             throw new Error('Invalid task checkpoint definition');
-        compilePluginStateSchema(definition.schema);
         if (definition.migrateFrom !== undefined) {
             if (!Array.isArray(definition.migrateFrom) ||
                 definition.migrateFrom.length < 1 ||
@@ -40,7 +38,6 @@ export function normalizePluginTaskRecovery(value) {
                     Array.isArray(source.schema) ||
                     source.schema.$async)
                     throw new Error('Checkpoint migrations require distinct older versions and schemas');
-                compilePluginStateSchema(source.schema);
                 versions.add(source.version);
             }
         }

package/dist/plugins/sdk/pluginStateDefinition.d.ts

@@ -1,4 +1,3 @@
 import type { PluginStateDeclaration } from '@mearl/browser-core';
-export declare function compilePluginStateSchema(schema: Record<string, unknown>): import("ajv/dist/core.js").AnyValidateFunction<unknown>;
 export declare function normalizePluginState(value: unknown): PluginStateDeclaration | undefined;
 export declare function pluginStateSignature(collection: import('@mearl/browser-core').PluginStateCollection): string;

package/dist/plugins/sdk/pluginStateDefinition.js

@@ -1,14 +1,4 @@
 import { createHash } from 'node:crypto';
-import { Ajv } from 'ajv';
-const validators = new WeakMap();
-export function compilePluginStateSchema(schema) {
-    let validate = validators.get(schema);
-    if (!validate) {
-        validate = new Ajv({ strict: true }).compile(schema);
-        validators.set(schema, validate);
-    }
-    return validate;
-}
 export function normalizePluginState(value) {
     if (value === undefined)
         return;
@@ -55,7 +45,6 @@ export function normalizePluginState(value) {
             throw new Error('State TTL must be between 1 ms and 7 days');
         if (collection.storage === 'persistent' && collection.ttlMs !== undefined)
             throw new Error('Persistent state does not accept TTL');
-        compilePluginStateSchema(collection.schema);
     }
     return declaration;
 }

package/dist/runtimePaths.d.ts

@@ -1,4 +1,5 @@
 export declare const CLIENT_VERSION: string;
 export declare const PLUGIN_TASK_HOST_PATH: string;
 export declare const PLUGIN_WORKER_PATH: string;
+export declare const SCRIPT_WORKER_PATH: string;
 export declare const PLUGIN_MODEL_SESSION_WORKER_PATH: string;

package/dist/runtimePaths.js

@@ -5,4 +5,5 @@ const require = createRequire(import.meta.url);
 export const CLIENT_VERSION = require('../package.json').version;
 export const PLUGIN_TASK_HOST_PATH = fileURLToPath(new URL('./plugin-task-host.js', import.meta.url));
 export const PLUGIN_WORKER_PATH = fileURLToPath(new URL('./plugin-worker.js', import.meta.url));
+export const SCRIPT_WORKER_PATH = fileURLToPath(new URL('./scriptWorker.js', import.meta.url));
 export const PLUGIN_MODEL_SESSION_WORKER_PATH = fileURLToPath(new URL('./pluginModelSessionWorker.js', import.meta.url));

package/dist/script.d.ts

@@ -0,0 +1,30 @@
+import { type UnifiedInvokeOptions } from './unified.js';
+export interface ScriptExecutionOptions extends UnifiedInvokeOptions {
+    serverUrl?: string;
+    /** Overall deadline, independent of individual action timeouts. Default: 60 seconds. */
+    executionTimeoutSec?: number;
+    /** Combined stdout/stderr limit in bytes. Default: 256 KiB; maximum: 1 MiB. */
+    maxOutputBytes?: number;
+    signal?: AbortSignal;
+    source?: 'cli' | 'mcp' | 'sdk';
+}
+export interface ScriptExecutionResult {
+    success: boolean;
+    stdout: string;
+    stderr: string;
+    session?: Record<string, unknown>;
+    error?: {
+        code: string;
+        message: string;
+        stack?: string;
+        details?: unknown;
+        stage?: string;
+        attempt?: unknown;
+    };
+    executionStopped: boolean;
+    /** Dispatched browser/plugin calls can finish after the script has stopped. */
+    mayHaveLateEffects: boolean;
+    pendingActions: string[];
+}
+/** Runs trusted agent code in a short-lived Node process, with one shared SDK client. */
+export declare function executeScript(code: string, options?: ScriptExecutionOptions): Promise<ScriptExecutionResult>;

package/dist/script.js

@@ -0,0 +1,260 @@
+import { spawn } from 'node:child_process';
+import { isBrowserCommandAction } from '@mearl/browser-core/browserActionProtocol';
+import { exportArtifact } from './artifacts.js';
+import { UnifiedClient } from './unified.js';
+import { loadCloudServerConfig } from './unifiedConfig.js';
+import { stopPluginProcessTree } from './plugins/runtime/pluginProcessTree.js';
+import { SCRIPT_WORKER_PATH } from './runtimePaths.js';
+import { SDK_METHOD_ACTIONS as METHOD_ACTIONS, SDK_OPTIONS_ONLY_METHODS as OPTIONS_ONLY, } from './sdkMethods.js';
+import { getCommandHelp } from './commandHelp.js';
+import { executeRegisteredPlugin } from './plugins/runtime/pluginExecutor.js';
+import { findPluginRegistration } from './plugins/pluginRegistry.js';
+import { findOfficialPlugin } from './plugins/officialPluginCatalog.js';
+import { ensureOfficialPluginRegistered } from './plugins/officialPluginInstaller.js';
+import { serializeScriptError as serializeError } from './scriptErrors.js';
+const METHODS = [...METHOD_ACTIONS.keys(), 'invoke', 'invokePlugin', 'saveArtifact', 'help'];
+const MAX_SCRIPT_BYTES = 1024 * 1024;
+/** Runs trusted agent code in a short-lived Node process, with one shared SDK client. */
+export async function executeScript(code, options = {}) {
+    if (typeof code !== 'string' || !code.trim() || Buffer.byteLength(code) > MAX_SCRIPT_BYTES)
+        throw new Error('Script must be non-empty JavaScript of at most 1 MiB');
+    const { serverUrl, executionTimeoutSec = 60, maxOutputBytes = 256 * 1024, signal, source = 'sdk', ...defaults } = options;
+    if (!Number.isFinite(executionTimeoutSec) ||
+        executionTimeoutSec <= 0 ||
+        executionTimeoutSec * 1000 > 2_147_483_647)
+        throw new Error('executionTimeoutSec must be positive and within the timer range');
+    if (!Number.isSafeInteger(maxOutputBytes) || maxOutputBytes < 1 || maxOutputBytes > 1024 * 1024)
+        throw new Error('maxOutputBytes must be an integer between 1 and 1048576');
+    const client = new UnifiedClient({
+        serverUrl: serverUrl ?? process.env.MEARL_SERVER_URL ?? loadCloudServerConfig()?.server,
+    });
+    let session = defaults.session && defaults.session !== 'new' ? { sessionId: defaults.session } : undefined;
+    let sessionId = defaults.session;
+    let uncertainEffects = false;
+    const pending = new Map();
+    const controller = new AbortController();
+    const invoke = async (action, payload, overrides = {}) => {
+        controller.signal.throwIfAborted();
+        const result = await client.invoke(action, payload, {
+            ...defaults,
+            session: sessionId,
+            ...overrides,
+        });
+        if (result?.action?.stage === 'dispatch-uncertain' || result?.stage === 'dispatch-uncertain')
+            uncertainEffects = true;
+        if (result?.session?.sessionId &&
+            (!overrides.session || overrides.session === 'new' || overrides.session === sessionId)) {
+            session = result.session;
+            if (!overrides.session || overrides.session === 'new')
+                sessionId = result.session.sessionId;
+        }
+        return result;
+    };
+    try {
+        return await new Promise((resolve, reject) => {
+            if (signal?.aborted) {
+                resolve({
+                    success: false,
+                    stdout: '',
+                    stderr: '',
+                    ...(session ? { session } : {}),
+                    error: { code: 'SCRIPT_CANCELLED', message: 'Script execution cancelled' },
+                    executionStopped: true,
+                    mayHaveLateEffects: false,
+                    pendingActions: [],
+                });
+                return;
+            }
+            const child = spawn(process.execPath, [SCRIPT_WORKER_PATH], {
+                stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
+                serialization: 'advanced',
+                detached: process.platform !== 'win32',
+            });
+            const output = { stdout: [], stderr: [] };
+            let outputBytes = 0;
+            let outcome;
+            let cleanup;
+            let cleanupError;
+            let pendingActions = [];
+            let closed = false;
+            const pluginCalls = new Set();
+            const stop = (error) => {
+                if (outcome !== undefined || closed)
+                    return;
+                outcome = error ?? true;
+                pendingActions = [...pending.values()];
+                controller.abort();
+                client.disconnect();
+                if (child.pid) {
+                    cleanup = stopPluginProcessTree(child.pid).catch(error => {
+                        cleanupError = error;
+                        child.kill('SIGKILL');
+                    });
+                }
+            };
+            const abort = () => stop({ code: 'SCRIPT_CANCELLED', message: 'Script execution cancelled' });
+            const deadline = setTimeout(() => stop({ code: 'SCRIPT_TIMEOUT', message: 'Script execution deadline exceeded' }), executionTimeoutSec * 1000);
+            signal?.addEventListener('abort', abort, { once: true });
+            if (signal?.aborted)
+                abort();
+            const appendOutput = (stream, chunk) => {
+                const remaining = maxOutputBytes - outputBytes;
+                output[stream].push(chunk.subarray(0, Math.max(0, remaining)));
+                outputBytes += Math.min(chunk.length, Math.max(0, remaining));
+                if (chunk.length > remaining)
+                    stop({
+                        code: 'SCRIPT_OUTPUT_LIMIT',
+                        message: `Script output exceeded ${maxOutputBytes} bytes`,
+                    });
+            };
+            for (const stream of ['stdout', 'stderr']) {
+                child[stream].on('data', (chunk) => appendOutput(stream, chunk));
+            }
+            const runPlugin = async (name, invocation, overrides = {}, help) => {
+                if (!findPluginRegistration(name) && findOfficialPlugin(name))
+                    await ensureOfficialPluginRegistered(name);
+                controller.signal.throwIfAborted();
+                const pluginOptions = { ...defaults, session: sessionId, ...overrides };
+                if (pluginOptions.session === 'new' && !help)
+                    throw new Error('Create the control session with a browser action before calling a Skill command');
+                const operation = executeRegisteredPlugin(name, invocation, {
+                    invoke: (action, payload = {}, options) => invoke(action, payload, options),
+                }, {
+                    ...pluginOptions,
+                    source,
+                    signal: controller.signal,
+                    cancellationGraceMs: 50,
+                    onOutput: appendOutput,
+                    ...(help ? { help } : {}),
+                });
+                pluginCalls.add(operation);
+                try {
+                    return await operation;
+                }
+                finally {
+                    pluginCalls.delete(operation);
+                }
+            };
+            const send = (message) => {
+                if (outcome !== undefined || !child.connected)
+                    return;
+                child.send(message, error => {
+                    if (error)
+                        stop(serializeError(error));
+                });
+            };
+            child.on('message', (message) => {
+                if (outcome !== undefined || !message || typeof message !== 'object')
+                    return;
+                if (message.type === 'done' || message.type === 'error') {
+                    stop(message.type === 'error'
+                        ? serializeError(message.error)
+                        : pending.size
+                            ? {
+                                code: 'SCRIPT_PENDING_CALLS',
+                                message: 'Script finished with unawaited SDK calls',
+                            }
+                            : undefined);
+                    return;
+                }
+                if (message.type !== 'call')
+                    return;
+                const { id, method, args } = message;
+                if (!Number.isSafeInteger(id) ||
+                    pending.has(id) ||
+                    !METHODS.includes(method) ||
+                    !Array.isArray(args)) {
+                    stop({ code: 'SCRIPT_PROTOCOL_ERROR', message: 'Invalid script SDK call' });
+                    return;
+                }
+                if (method !== 'help' && sessionId === 'new' && pending.size) {
+                    send({
+                        type: 'response',
+                        id,
+                        error: {
+                            code: 'SCRIPT_SESSION_INITIALIZING',
+                            message: 'Await the first session call before starting concurrent calls',
+                        },
+                    });
+                    return;
+                }
+                pending.set(id, method === 'invoke' || method === 'invokePlugin' ? String(args[0]) : method);
+                void Promise.resolve()
+                    .then(async () => {
+                    if (outcome !== undefined)
+                        throw new Error('Script execution stopped');
+                    if (method === 'help') {
+                        const target = args[0];
+                        if (target && typeof target === 'object') {
+                            if (typeof target.plugin !== 'string' ||
+                                !target.plugin.trim() ||
+                                (target.command !== undefined && typeof target.command !== 'string'))
+                                throw new Error('Plugin help requires { plugin, command? }');
+                            return runPlugin(target.plugin, { command: '', input: {} }, {}, { namespace: `mearl ${target.plugin}`, command: target.command });
+                        }
+                        return getCommandHelp(target);
+                    }
+                    if (method === 'invoke') {
+                        if (!isBrowserCommandAction(args[0]) && args[0] !== 'browser_select_browser')
+                            throw new Error(`Unsupported browser action: ${args[0]}; use invokePlugin for registered Skill commands`);
+                        return invoke(args[0], args[1] ?? {}, args[2]);
+                    }
+                    if (method === 'invokePlugin') {
+                        return runPlugin(args[0], args[1], args[2]);
+                    }
+                    if (method === 'saveArtifact')
+                        return exportArtifact({ invoke }, args[0], args[1], {
+                            ...defaults,
+                            session: sessionId,
+                            ...args[2],
+                        });
+                    const optionsOnly = OPTIONS_ONLY.has(method) || (method === 'browserRelease' && args.length < 2);
+                    return invoke(METHOD_ACTIONS.get(method), optionsOnly ? {} : (args[0] ?? {}), optionsOnly ? args[0] : args[1]);
+                })
+                    .then(result => send({ type: 'response', id, result, session }), error => send({ type: 'response', id, error: serializeError(error), session }))
+                    .finally(() => pending.delete(id));
+            });
+            child.once('error', error => {
+                stop(serializeError(error));
+            });
+            child.once('exit', () => {
+                if (outcome === undefined)
+                    stop({
+                        code: 'SCRIPT_EXITED',
+                        message: 'Script process exited before reporting completion',
+                    });
+            });
+            child.once('close', () => {
+                closed = true;
+                clearTimeout(deadline);
+                signal?.removeEventListener('abort', abort);
+                void Promise.allSettled([cleanup, ...pluginCalls])
+                    .then(outcomes => {
+                    if (outcomes.some(result => result.status === 'rejected' &&
+                        result.reason?.code === 'PLUGIN_EXECUTOR_CLEANUP_FAILED'))
+                        cleanupError = new Error('Unable to confirm Skill process cleanup');
+                    const error = cleanupError
+                        ? serializeError(cleanupError, 'SCRIPT_CLEANUP_FAILED')
+                        : outcome === true
+                            ? undefined
+                            : outcome;
+                    resolve({
+                        success: !error && outcome === true,
+                        stdout: Buffer.concat(output.stdout).toString('utf8'),
+                        stderr: Buffer.concat(output.stderr).toString('utf8'),
+                        ...(session ? { session } : {}),
+                        ...(error ? { error } : {}),
+                        executionStopped: !cleanupError,
+                        mayHaveLateEffects: pendingActions.length > 0 || uncertainEffects,
+                        pendingActions,
+                    });
+                })
+                    .catch(reject);
+            });
+            send({ type: 'start', code, methods: METHODS, session });
+        });
+    }
+    finally {
+        client.disconnect();
+    }
+}

package/dist/scriptCli.d.ts

@@ -0,0 +1 @@
+export declare function runScriptCli(args: string[], commandName: string): Promise<number>;