@mobileaidev/ai-app-bridge 0.3.5 → 0.3.7

package/bin/executors/command-schema.js

@@ -0,0 +1,102 @@
+'use strict';
+
+const { object, text, integer } = require('../shared-kernel/argument-schema');
+const identifier = { ...text, maxLength: 1024 };
+const timeoutMs = integer(1, 300000);
+const execution = { timeoutMs, requestId: identifier, feedback: { enum: ['auto', 'off', 'full'] } };
+const webIdentity = { sessionId: identifier, runtimeEpoch: identifier, targetId: identifier };
+const documentIdentity = { frameId: identifier, documentId: identifier };
+const selector = {
+  anyOf: [
+    object({ by: { const: 'role' }, value: identifier, name: { type: 'string', maxLength: 4096 } }, ['by', 'value', 'name']),
+    object({ by: { enum: ['testId', 'text', 'label', 'placeholder', 'css'] }, value: identifier }, ['by', 'value']),
+  ],
+};
+const browserAction = {
+  anyOf: [
+    object({ type: { enum: ['click', 'doubleClick', 'hover', 'scrollIntoView'] }, selector }, ['type', 'selector']),
+    object({ type: { enum: ['fill', 'type', 'press'] }, selector, text: { type: 'string', maxLength: 65536 } }, ['type', 'selector', 'text']),
+    object({ type: { const: 'check' }, selector, checked: { type: 'boolean' } }, ['type', 'selector', 'checked']),
+    object({ type: { const: 'select' }, selector, values: { type: 'array', items: { type: 'string' }, minItems: 1, maxItems: 100 } }, ['type', 'selector', 'values']),
+    object({ type: { const: 'drag' }, selector, destination: selector }, ['type', 'selector', 'destination']),
+    object({ type: { const: 'upload' }, selector, files: { type: 'array', items: identifier, maxItems: 100 } }, ['type', 'selector', 'files']),
+  ],
+};
+
+function operationSchema(definitions) {
+  const branches = Object.entries(definitions).map(([operation, definition]) =>
+    object({ operation: { const: operation }, ...execution, ...definition.properties }, ['operation', ...definition.required]));
+  const properties = Object.assign({}, ...branches.map(branch => branch.properties));
+  properties.operation = { enum: Object.keys(definitions) };
+  return { type: 'object', additionalProperties: false, properties, required: ['operation'], anyOf: branches };
+}
+
+function webExecutorSchema() {
+  const bound = (properties = {}, required = []) => ({ properties: { ...webIdentity, ...properties }, required: [...Object.keys(webIdentity), ...required] });
+  return operationSchema({
+    status: { properties: { browser: { enum: ['chromium', 'firefox', 'webkit'] } }, required: [] },
+    prepare: { properties: { browser: { enum: ['chromium', 'firefox', 'webkit'] } }, required: [] },
+    open: { properties: { url: identifier, browser: { enum: ['chromium', 'firefox', 'webkit'] }, headless: { type: 'boolean' },
+      viewport: object({ width: integer(320, 7680), height: integer(240, 4320) }, ['width', 'height']) }, required: ['url'] },
+    observe: bound({ maxControls: integer(1, 1000) }),
+    act: bound({ ...documentIdentity, actionId: identifier, action: browserAction,
+      dialog: object({ action: { enum: ['accept', 'dismiss'] }, promptText: { type: 'string', maxLength: 4096 } }, ['action']) }, [...Object.keys(documentIdentity), 'action']),
+    navigate: bound({ ...documentIdentity, url: identifier, actionId: identifier }, [...Object.keys(documentIdentity), 'url']),
+    wait: bound({ ...documentIdentity, selector, state: { enum: ['visible', 'hidden', 'attached', 'detached'] }, text: { type: 'string', maxLength: 65536 } }, [...Object.keys(documentIdentity), 'selector']),
+    screenshot: bound({ outFile: identifier, fullPage: { type: 'boolean' } }, ['outFile']),
+    events: bound({ afterSequence: integer(0, Number.MAX_SAFE_INTEGER), limit: integer(1, 1000) }),
+    receipt: bound({ actionId: identifier }, ['actionId']),
+    close: bound(),
+  });
+}
+
+function androidExecutorSchema() {
+  const target = { serial: identifier, packageName: identifier, adb: identifier };
+  const session = { sessionId: identifier, runtimeEpoch: identifier };
+  const bound = (properties = {}, required = []) => ({ properties: { ...target, ...session, ...properties }, required: ['serial', 'packageName', 'sessionId', 'runtimeEpoch', ...required] });
+  const action = { anyOf: [
+    object({ type: { enum: ['click', 'longClick', 'scrollTo', 'swipeUp', 'swipeDown', 'swipeLeft', 'swipeRight', 'webClick', 'webClear', 'webScrollIntoView', 'semanticLongClick', 'composeClearText'] }, nodeId: identifier }, ['type', 'nodeId']),
+    object({ type: { enum: ['setText', 'typeText', 'replaceText', 'webKeys', 'composeInput', 'composeReplaceText'] }, nodeId: identifier, text: { type: 'string', maxLength: 65536 } }, ['type', 'nodeId', 'text']),
+    object({ type: { const: 'composeScrollToIndex' }, nodeId: identifier, index: integer(0, 1000000) }, ['type', 'nodeId', 'index']),
+    object({ type: { const: 'scroll' }, nodeId: identifier, direction: { enum: ['up', 'down', 'left', 'right'] }, percent: { type: 'number', exclusiveMinimum: 0, maximum: 10 } }, ['type', 'nodeId', 'direction', 'percent']),
+    object({ type: { enum: ['back', 'home', 'closeKeyboard'] } }, ['type']),
+  ] };
+  return operationSchema({
+    status: { properties: target, required: ['serial'] },
+    open: { properties: { ...target,
+      instrumentation: { ...identifier, pattern: '^[A-Za-z0-9_.]+/[A-Za-z0-9_.$]+$' }, testClass: { ...identifier, pattern: '^[A-Za-z0-9_.$]+$' },
+      activity: { ...identifier, pattern: '^[A-Za-z0-9_.$]+$' }, leaseMs: integer(10000, 3600000) }, required: ['serial', 'packageName', 'instrumentation', 'testClass', 'activity'] },
+    observe: bound({ engine: identifier,
+      composeUnmergedTree: { type: 'boolean' },
+      webView: object({ by: { enum: ['resourceId', 'description'] }, value: identifier }, ['by', 'value']),
+      framePath: { type: 'array', maxItems: 16, items: { anyOf: [object({ index: integer(0, 1000) }, ['index']), object({ name: identifier }, ['name'])] } }
+    }, ['engine']),
+    act: bound({ snapshotId: identifier, actionId: identifier, action }, ['snapshotId', 'action']),
+    receipt: bound({ actionId: identifier }, ['actionId']),
+    close: bound(),
+  });
+}
+
+function flutterExecutorSchema() {
+  const target = { serial: identifier, packageName: identifier, adb: identifier };
+  const session = { sessionId: identifier, runtimeEpoch: identifier };
+  const bound = (properties = {}, required = []) => ({ properties: { ...target, ...session, ...properties }, required: ['serial', 'packageName', 'sessionId', 'runtimeEpoch', ...required] });
+  const action = { anyOf: [
+    object({ type: { enum: ['tap', 'longPress', 'ensureVisible'] }, nodeId: identifier }, ['type', 'nodeId']),
+    object({ type: { const: 'enterText' }, nodeId: identifier, text: { type: 'string', maxLength: 65536 } }, ['type', 'nodeId', 'text']),
+    object({ type: { const: 'drag' }, nodeId: identifier, dx: { type: 'number' }, dy: { type: 'number' } }, ['type', 'nodeId', 'dx', 'dy']),
+    object({ type: { const: 'fling' }, nodeId: identifier, dx: { type: 'number' }, dy: { type: 'number' }, speed: { type: 'number', exclusiveMinimum: 0, maximum: 100000 } }, ['type', 'nodeId', 'dx', 'dy', 'speed']),
+    object({ type: { const: 'pageBack' } }, ['type']),
+    object({ type: { const: 'pump' }, count: integer(1, 120), durationMs: integer(0, 1000) }, ['type', 'count', 'durationMs']),
+  ] };
+  return operationSchema({
+    status: { properties: target, required: ['serial'] },
+    open: { properties: { ...target, activity: { ...identifier, pattern: '^[A-Za-z0-9_.$]+$' }, leaseMs: integer(10000, 3600000) }, required: ['serial', 'packageName', 'activity'] },
+    observe: bound(),
+    act: bound({ snapshotId: identifier, actionId: identifier, action }, ['snapshotId', 'action']),
+    receipt: bound({ actionId: identifier }, ['actionId']),
+    close: bound(),
+  });
+}
+
+module.exports = { webExecutorSchema, androidExecutorSchema, flutterExecutorSchema, operationSchema, selector, browserAction };

package/bin/executors/flutter-host.js

@@ -0,0 +1,123 @@
+'use strict';
+
+const path = require('node:path');
+const { randomUUID, randomBytes } = require('node:crypto');
+const { AndroidExecutorHost, recoverAndroidExecutor, settlement } = require('./android-host');
+const { AndroidExecutorPort, quote } = require('./android-port');
+const { atomicJson, readJson } = require('./managed-runtime');
+const { runDeviceEffect } = require('../shared-kernel/device-mutation-lease');
+const { checkExecution, markExecutionDispatched, executionSleep } = require('../shared-kernel/execution-scope');
+const { CommandError } = require('../command-errors');
+const protocol = 'aab.flutter-integration-executor/v1';
+
+class FlutterExecutorPort extends AndroidExecutorPort {
+  constructor(descriptor) { super(descriptor, { protocolVersion: protocol }); }
+  forwardEndpoint() {
+    if (!Number.isInteger(this.descriptor.port) || this.descriptor.port < 1 || this.descriptor.port > 65535)
+      throw new CommandError('executor_forward_invalid', 'The Flutter test has not published a valid port.');
+    return `tcp:${this.descriptor.port}`;
+  }
+  recordDirectory() { return `no_backup/ai-app-bridge-integration/${this.descriptor.sessionId}`; }
+  async terminateClosedProcess() {
+    if (await this.processEnded()) return;
+    const { pid, bootId, processStartTicks, targetPackage } = this.descriptor;
+    // Kill only the exact drained test process, even if the app has since restarted.
+    const script = `if [ "$(cat /proc/sys/kernel/random/boot_id)" = ${quote(bootId)} ] && [ -f /proc/${pid}/stat ]; then
+aab_stat=$(cat /proc/${pid}/stat) || exit 1
+aab_fields=\${aab_stat##*) }
+set -- $aab_fields
+shift 19
+if [ "$1" = ${quote(processStartTicks)} ]; then kill -TERM ${pid}; fi
+fi`;
+    await this.invoke(['shell', 'run-as', targetPackage, 'sh', '-c', quote(script)]);
+  }
+}
+
+class FlutterExecutorHost extends AndroidExecutorHost {
+  get kind() { return 'flutter-test-executor'; }
+  createPort(descriptor) { return new FlutterExecutorPort(descriptor); }
+  directory(sessionId) {
+    const validated = super.directory(sessionId);
+    return path.join(path.dirname(path.dirname(validated)), 'flutter', sessionId);
+  }
+  async finishClose(port) {
+    await port.terminateClosedProcess();
+    return port.processEnded();
+  }
+  async run(args) {
+    if (args.operation === 'status') {
+      const port = this.createPort({ adb: args.adb || process.env.ADB || 'adb', serial: args.serial });
+      const bootId = await port.bootId();
+      return { ok: true, serial: args.serial, bootId, engine: 'flutter-integration-test',
+        prerequisite: 'Install the application debug build with integration_test/bridge_test.dart as its entrypoint. Add ai_app_bridge_test only to dev_dependencies. Opening restarts the application; closing terminates the drained test process.' };
+    }
+    return super.run(args);
+  }
+  async open(args) {
+    const sessionId = randomUUID();
+    const descriptor = { protocol, sessionId, serial: args.serial, packageName: args.packageName, targetPackage: args.packageName,
+      adb: args.adb, token: randomBytes(32).toString('hex') };
+    const file = path.join(this.directory(sessionId), 'session.json');
+    const port = this.createPort(descriptor);
+    descriptor.bootId = await port.bootId();
+    atomicJson(file, descriptor);
+    const pending = { kind: this.kind, protocol, operation: 'open', sessionId, runtimeEpoch: null,
+      target: { serial: args.serial, packageName: args.packageName, adb: args.adb }, descriptorFile: file };
+    return runDeviceEffect(pending, async () => {
+      await require('./automation-owner').assertAvailable(args.serial);
+      const launch = { sessionId, token: descriptor.token, packageName: args.packageName, leaseMs: args.leaseMs ?? 600000 };
+      const prepare = `umask 077\nmkdir -p no_backup/ai-app-bridge-integration\nprintf '%s' ${quote(JSON.stringify(launch))} > no_backup/ai-app-bridge-integration/launch.json`;
+      checkExecution(); markExecutionDispatched();
+      await port.invoke(['shell', 'run-as', args.packageName, 'sh', '-c', quote(prepare)]);
+      await port.invoke(['shell', 'am', 'start', '-S', '-W', '-n', `${args.packageName}/${args.activity}`], 30000);
+      this.sessions.set(sessionId, port);
+      while (true) {
+        checkExecution();
+        if (!descriptor.pid) {
+          const starting = await port.readRecord('starting.json');
+          if (starting) {
+            Object.assign(descriptor, { runtimeEpoch: starting.runtimeEpoch, pid: starting.pid, processStartTicks: starting.processStartTicks });
+            atomicJson(file, descriptor);
+          }
+        }
+        const failed = await port.readRecord('failed.json');
+        if (failed) {
+          const closed = await port.readRecord('closed.json');
+          if (closed?.settled && await this.finishClose(port)) return { ok: false, error: 'executor_initialization_failed', message: failed.error,
+            sessionId, runtimeEpoch: descriptor.runtimeEpoch, dispatched: true, ambiguous: true, closed };
+        }
+        const session = await port.readRecord('session.json');
+        if (session) {
+          if (session.bootId !== descriptor.bootId || session.targetPackage !== args.packageName || session.capabilities?.engine !== 'flutter-integration-test')
+            throw new CommandError('executor_engine_mismatch', 'The running Flutter test does not match the requested target.', { dispatched: true, ambiguous: true });
+          Object.assign(descriptor, { runtimeEpoch: session.runtimeEpoch, pid: session.pid, processStartTicks: session.processStartTicks, port: session.port });
+          atomicJson(file, descriptor);
+          const status = await port.request({ operation: 'status', timeoutMs: 5000 });
+          if (!status.ok || status.closing) throw new CommandError('executor_not_ready', 'The Flutter test did not become ready.', { dispatched: true, ambiguous: true });
+          return { ...session, ok: true, serial: args.serial, packageName: args.packageName, lifecycle: 'test-entrypoint-application-restarted' };
+        }
+        await executionSleep(100);
+      }
+    }, result => settlement(result, pending));
+  }
+}
+
+async function recoverFlutterExecutor(pending) {
+  const descriptor = readJson(pending.descriptorFile);
+  if (!descriptor || descriptor.sessionId !== pending.sessionId || descriptor.serial !== pending.target?.serial)
+    return { settled: false, error: 'executor_descriptor_mismatch' };
+  const port = new FlutterExecutorPort(descriptor);
+  if (!await port.bootChanged()) {
+    if (!descriptor.pid) {
+      const starting = await port.readRecord('starting.json');
+      if (starting) {
+        Object.assign(descriptor, { runtimeEpoch: starting.runtimeEpoch, pid: starting.pid, processStartTicks: starting.processStartTicks });
+        atomicJson(pending.descriptorFile, descriptor);
+      }
+    }
+    const closed = await port.readRecord('closed.json');
+    if (closed?.settled && descriptor.pid) await port.terminateClosedProcess();
+  }
+  return recoverAndroidExecutor(pending, value => new FlutterExecutorPort(value));
+}
+module.exports = { FlutterExecutorHost, FlutterExecutorPort, protocol, recoverFlutterExecutor };

package/bin/executors/managed-runtime.js

@@ -0,0 +1,85 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { createHash, randomUUID } = require('node:crypto');
+const { CommandError } = require('../command-errors');
+const { execFileBounded } = require('../shared-kernel/execution-io');
+
+const executorHome = () => path.resolve(process.env.AI_APP_BRIDGE_EXECUTOR_HOME || path.join(os.homedir(), '.ai-app-bridge', 'executors'));
+
+function atomicJson(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  const fd = fs.openSync(temporary, 'wx', 0o600);
+  try { fs.writeFileSync(fd, JSON.stringify(value) + '\n'); fs.fsyncSync(fd); }
+  finally { fs.closeSync(fd); }
+  fs.renameSync(temporary, file);
+  const parent = fs.openSync(path.dirname(file), 'r');
+  try { fs.fsyncSync(parent); } finally { fs.closeSync(parent); }
+}
+
+function readJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+
+function packageLocation(name = 'playwright', home = executorHome()) {
+  if (name !== 'playwright') throw new CommandError('executor_unknown', 'Unknown managed executor.');
+  const source = path.resolve(__dirname, '../../runtime/executors', name);
+  const manifest = JSON.parse(fs.readFileSync(path.join(source, 'package.json'), 'utf8'));
+  const lock = fs.readFileSync(path.join(source, 'package-lock.json'));
+  const digest = createHash('sha256').update(JSON.stringify(manifest)).update(lock).digest('hex');
+  const directory = path.join(home, 'packages', name, `${process.platform}-${process.arch}`, digest);
+  return { name, source, directory, digest, version: manifest.dependencies.playwright,
+    browsersPath: path.join(directory, 'browsers'), readyFile: path.join(directory, 'prepared.json') };
+}
+
+function packageStatus(browser = 'chromium', home = executorHome()) {
+  const location = packageLocation('playwright', home);
+  const ready = readJson(location.readyFile);
+  const installed = readJson(path.join(location.directory, 'node_modules/playwright/package.json'));
+  const matching = ready?.digest === location.digest && installed?.version === location.version;
+  const executable = matching ? ready.browsers?.[browser] : null;
+  return { ok: true, engine: 'playwright', version: location.version, browser,
+    available: Boolean(executable && fs.existsSync(executable)),
+    reason: executable && fs.existsSync(executable) ? null : 'executor_not_prepared',
+    directory: location.directory, dependencyDigest: location.digest,
+    ...(executable ? { executablePath: executable } : {}) };
+}
+
+async function preparePackage(browser = 'chromium', { home = executorHome(), run = execFileBounded } = {}) {
+  if (!['chromium', 'firefox', 'webkit'].includes(browser)) throw new CommandError('invalid_argument', 'Unknown browser.', { field: 'browser' });
+  const location = packageLocation('playwright', home);
+  fs.mkdirSync(location.directory, { recursive: true, mode: 0o700 });
+  const { DatabaseSync } = require('node:sqlite');
+  const lock = new DatabaseSync(path.join(location.directory, 'prepare.sqlite'));
+  let locked = false;
+  const startedAtMs = Date.now();
+  try {
+    try { lock.exec('PRAGMA busy_timeout=0; BEGIN EXCLUSIVE'); locked = true; }
+    catch (error) { if (error.errcode === 5) throw new CommandError('executor_preparing', 'This exact executor package is being prepared by another process.'); throw error; }
+    const status = packageStatus(browser, home);
+    if (status.available) return { ...status, reused: true, elapsedMs: Date.now() - startedAtMs };
+    const old = readJson(location.readyFile);
+    const installed = readJson(path.join(location.directory, 'node_modules/playwright/package.json'));
+    if (old?.digest !== location.digest || installed?.version !== location.version) {
+      for (const name of ['package.json', 'package-lock.json']) fs.copyFileSync(path.join(location.source, name), path.join(location.directory, name));
+      await run(process.platform === 'win32' ? 'npm.cmd' : 'npm', ['ci', '--ignore-scripts', '--no-audit', '--no-fund'],
+        { cwd: location.directory, timeoutMs: 300000, maxBuffer: 4 * 1024 * 1024 });
+    }
+    const environment = { ...process.env, PLAYWRIGHT_BROWSERS_PATH: location.browsersPath };
+    await run(process.execPath, [path.join(location.directory, 'node_modules/playwright/cli.js'), 'install', browser],
+      { cwd: location.directory, env: environment, timeoutMs: 300000, maxBuffer: 4 * 1024 * 1024 });
+    const probe = await run(process.execPath, ['-e', 'process.stdout.write(require("playwright")[process.argv[1]].executablePath())', browser],
+      { cwd: location.directory, env: environment, timeoutMs: 10000 });
+    const executable = probe.stdout.trim();
+    if (!fs.existsSync(executable)) throw new CommandError('executor_browser_missing', 'Browser installation did not produce its declared executable.');
+    atomicJson(location.readyFile, { schemaVersion: 'aab.executor-package/v1', digest: location.digest,
+      version: location.version, preparedAtMs: Date.now(), browsers: { ...(old?.digest === location.digest ? old.browsers : {}), [browser]: executable } });
+    return { ...packageStatus(browser, home), reused: false, elapsedMs: Date.now() - startedAtMs };
+  } finally { if (locked) lock.exec('ROLLBACK'); lock.close(); }
+}
+
+module.exports = { executorHome, atomicJson, readJson, packageLocation, packageStatus, preparePackage };

package/bin/executors/playwright-host.js

@@ -0,0 +1,146 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { fork } = require('node:child_process');
+const { randomUUID } = require('node:crypto');
+const { CommandError } = require('../command-errors');
+const { currentExecution, markExecutionDispatched, checkExecution } = require('../shared-kernel/execution-scope');
+const { executorHome, packageLocation, packageStatus, preparePackage, readJson } = require('./managed-runtime');
+const { ReceiptJournal } = require('./receipt-journal');
+
+const protocol = 'aab.playwright-worker/v1';
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const mutation = args => ['open', 'act', 'navigate', 'close'].includes(args.operation);
+
+class PlaywrightHost {
+  constructor({ home = executorHome() } = {}) { this.home = home; this.sessions = new Map(); this.closed = false; }
+
+  async run(args) {
+    if (this.closed) throw new CommandError('executor_host_closed', 'Browser executor Host is closed.');
+    for (const [id, worker] of this.sessions) if (worker.closed) this.sessions.delete(id);
+    if (args.operation === 'status') return { ...packageStatus(args.browser || 'chromium', this.home),
+      sessions: [...this.sessions.values()].map(worker => ({ ...worker.identity, state: worker.closed ? 'closed' : 'running' })) };
+    if (args.operation === 'prepare') return preparePackage(args.browser || 'chromium', { home: this.home });
+    if (args.operation === 'open') {
+      let url;
+      try { url = new URL(args.url); } catch { /* rejected below */ }
+      if (!url || !['http:', 'https:'].includes(url.protocol) || url.username || url.password) throw new CommandError('invalid_argument', 'Browser URLs must use HTTP(S) without embedded credentials.', { field: 'url' });
+      const status = packageStatus(args.browser || 'chromium', this.home);
+      if (!status.available) throw new CommandError('executor_not_prepared', 'Prepare this browser executor before opening a session.', { details: status });
+      if (this.sessions.size >= 16) throw new CommandError('executor_session_capacity', 'Close a browser executor session before opening another.');
+      const identity = { sessionId: randomUUID(), runtimeEpoch: randomUUID() };
+      const directory = path.join(this.home, 'sessions', 'playwright', identity.sessionId);
+      const location = packageLocation('playwright', this.home);
+      const worker = new WorkerClient(location, directory, identity);
+      this.sessions.set(identity.sessionId, worker);
+      try {
+        const result = await worker.request(args);
+        if (!result.ok) { await worker.stop(); this.sessions.delete(identity.sessionId); }
+        return result;
+      } catch (error) { await worker.stop(); this.sessions.delete(identity.sessionId); throw error; }
+    }
+    for (const field of ['sessionId', 'runtimeEpoch', 'targetId']) if (!uuid.test(args[field] || '')) throw new CommandError('executor_session_mismatch', 'Executor identity is invalid.', { field });
+    if (args.operation === 'receipt') {
+      const directory = path.join(this.home, 'sessions', 'playwright', args.sessionId);
+      const descriptor = readJson(path.join(directory, 'session.json'));
+      if (!descriptor || descriptor.runtimeEpoch !== args.runtimeEpoch) throw new CommandError('executor_session_mismatch', 'No retained executor session matches this identity.');
+      const receipt = new ReceiptJournal(path.join(directory, 'receipts'),
+        { sessionId: args.sessionId, runtimeEpoch: args.runtimeEpoch, targetId: args.targetId }).receipt(args.actionId);
+      return { ok: Boolean(receipt), ...(receipt ? { receipt } : { error: 'executor_receipt_not_found' }) };
+    }
+    const worker = this.sessions.get(args.sessionId);
+    if (!worker || worker.closed || worker.identity.runtimeEpoch !== args.runtimeEpoch) throw new CommandError('executor_session_unavailable', 'This browser session is no longer live. Retained receipts remain queryable.');
+    if (args.operation === 'navigate') {
+      let url;
+      try { url = new URL(args.url); } catch { /* rejected below */ }
+      if (!url || !['http:', 'https:'].includes(url.protocol) || url.username || url.password) throw new CommandError('invalid_argument', 'Navigation requires an HTTP(S) URL without credentials.', { field: 'url' });
+    }
+    const request = { ...args };
+    if (['act', 'navigate'].includes(args.operation)) request.actionId = args.actionId || args.runtimeActionId || randomUUID();
+    const result = await worker.request(request);
+    if (args.operation === 'close' && result.ok) { await worker.stop(); this.sessions.delete(args.sessionId); }
+    return result;
+  }
+
+  async close() {
+    this.closed = true;
+    await Promise.allSettled([...this.sessions.values()].map(worker => worker.stop()));
+    this.sessions.clear();
+  }
+}
+
+class WorkerClient {
+  constructor(location, directory, identity) {
+    this.identity = identity; this.pending = new Map(); this.closed = false;
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    this.child = fork(path.join(__dirname, 'playwright-worker.js'), [location.directory, directory, identity.sessionId, identity.runtimeEpoch],
+      { stdio: ['ignore', 'ignore', 'pipe', 'ipc'], detached: process.platform !== 'win32', serialization: 'json',
+        env: { ...process.env, PLAYWRIGHT_BROWSERS_PATH: location.browsersPath } });
+    this.stderr = '';
+    this.child.stderr.on('data', data => { this.stderr = (this.stderr + data.toString()).slice(-8192); });
+    this.ready = new Promise((resolve, reject) => { this.resolveReady = resolve; this.rejectReady = reject; });
+    this.ready.catch(() => {});
+    this.ended = new Promise(resolve => this.child.once('close', () => {
+      this.closed = true;
+      const error = new CommandError('executor_worker_closed', 'The browser worker closed before completion.', { details: { stderr: this.stderr } });
+      this.rejectReady(error);
+      for (const pending of this.pending.values()) pending.fail(error);
+      this.pending.clear(); resolve();
+    }));
+    this.child.on('error', error => this.rejectReady(error));
+    this.child.on('message', message => {
+      if (message?.protocol !== protocol) return;
+      if (message.type === 'ready') { this.resolveReady(); return; }
+      const pending = this.pending.get(message.id);
+      if (pending) { this.pending.delete(message.id); pending.finish(message.result); }
+    });
+    this.startTimer = setTimeout(() => { this.rejectReady(new CommandError('executor_start_timeout', 'Browser worker did not initialize.')); void this.stop(); }, 15000);
+    this.ready.finally(() => clearTimeout(this.startTimer)).catch(() => {});
+  }
+
+  async request(args) {
+    await this.ready;
+    checkExecution();
+    if (this.closed) throw new CommandError('executor_worker_closed', 'Browser worker is closed.');
+    const id = randomUUID(), scope = currentExecution();
+    return new Promise((resolve, reject) => {
+      let timer, killTimer;
+      const clean = () => { clearTimeout(timer); clearTimeout(killTimer); scope?.signal.removeEventListener('abort', abort); };
+      const abort = () => {
+        if (this.child.connected) this.child.send({ protocol, type: 'cancel', id });
+        killTimer ||= setTimeout(() => { void this.stop(); }, 5000);
+      };
+      this.pending.set(id, {
+        finish: result => { clean(); resolve(result); },
+        fail: error => { clean(); reject(new CommandError(error.code || 'executor_worker_closed', error.message,
+          { dispatched: mutation(args), ambiguous: mutation(args), details: { ...error.details, ...this.identity, actionId: args.actionId } })); },
+      });
+      scope?.signal.addEventListener('abort', abort, { once: true });
+      timer = setTimeout(abort, args.timeoutMs ?? 30000);
+      if (mutation(args)) markExecutionDispatched();
+      this.child.send({ protocol, type: 'request', id, args }, error => {
+        if (error) { const pending = this.pending.get(id); this.pending.delete(id); pending?.fail(error); }
+      });
+      if (scope?.signal.aborted) abort();
+    });
+  }
+
+  stop() {
+    if (this.stopPromise) return this.stopPromise;
+    this.stopPromise = (async () => {
+      clearTimeout(this.startTimer);
+      if (this.closed) return;
+      const kill = signal => {
+        try { if (process.platform === 'win32') this.child.kill(signal); else process.kill(-this.child.pid, signal); }
+        catch (error) { if (error.code !== 'ESRCH') throw error; }
+      };
+      kill('SIGTERM');
+      const timer = setTimeout(() => kill('SIGKILL'), 1000);
+      try { await this.ended; } finally { clearTimeout(timer); }
+    })();
+    return this.stopPromise;
+  }
+}
+
+module.exports = { PlaywrightHost };