@mobileaidev/ai-app-bridge 0.2.15 → 0.3.0-rc.2

package/bin/runtime-client.js

@@ -0,0 +1,154 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const http = require('node:http');
+const { fork } = require('node:child_process');
+const { CommandError, commandFailure } = require('./command-errors');
+const { validateRunRequest } = require('./command-request');
+const { protocol, maxMessageBytes, readJson, decodeReply } = require('./runtime-protocol');
+const { runtimeLocation, runtimeIdentity, acquireRuntimeLock, readEndpoint, prepareDirectory } = require('./runtime-directory');
+const starting = new Map();
+
+// Transport failures do not retry execution or cancel its owner. Once the
+// request has been written, the device outcome is unknown to this connection.
+function exchange(endpoint, method, args, { identity, signal, timeoutMs, cwd = process.cwd() } = {}) {
+  if (signal?.aborted) return Promise.reject(new CommandError('runtime_client_disconnected', 'The client connection was closed.'));
+  const body = JSON.stringify({ protocol, runtimeId: endpoint.runtimeId, method, identity, arguments: args, cwd });
+  if (Buffer.byteLength(body) > maxMessageBytes) return Promise.reject(new CommandError('runtime_message_too_large', 'Runtime messages are limited to 128 MiB.'));
+  return new Promise((resolve, reject) => {
+    let written = false;
+    let settled = false;
+    let timer;
+    const finish = (error, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', abort);
+      error ? reject(error) : resolve(value);
+    };
+    const failure = (code, message) => new CommandError(code, message, {
+      dispatched: written ? null : false, ambiguous: written,
+      details: { runtimeId: endpoint.runtimeId, pid: endpoint.pid },
+    });
+    const request = http.request({ hostname: '127.0.0.1', port: endpoint.port, path: '/rpc', method: 'POST', agent: false,
+      headers: { Authorization: `Bearer ${endpoint.token}`, 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body), Connection: 'close' } }, async response => {
+      try {
+        const message = await readJson(response);
+        if (message.protocol !== protocol || message.runtimeId !== endpoint.runtimeId) throw failure('runtime_protocol_error', 'Runtime reply identity did not match the connection.');
+        finish(null, decodeReply(message.reply));
+      } catch (error) { finish(failure('runtime_protocol_error', error.message)); }
+    });
+    const abort = () => request.destroy(failure('runtime_client_disconnected', 'The client disconnected; execution was not cancelled.'));
+    request.once('finish', () => { written = true; });
+    request.once('error', error => finish(error instanceof CommandError ? error : failure('runtime_connection_lost', error.message)));
+    if (timeoutMs !== undefined) timer = setTimeout(() => request.destroy(failure('runtime_connection_timeout', 'The runtime did not answer the connection probe.')), timeoutMs);
+    signal?.addEventListener('abort', abort, { once: true });
+    request.end(body);
+  });
+}
+
+async function probe(location, signal) {
+  const endpoint = readEndpoint(location);
+  let cause;
+  if (endpoint) {
+    try {
+      const reply = await exchange(endpoint, 'status', {}, { signal, timeoutMs: 1500 });
+      if (reply.value.ok !== true) throw new CommandError(reply.value.error, reply.value.message);
+      return { state: 'running', endpoint, status: reply.value };
+    } catch (error) { cause = error; if (signal?.aborted) throw error; }
+  }
+  const lock = acquireRuntimeLock(location);
+  if (lock) { lock.close(); return { state: 'stopped' }; }
+  // A busy OS lock is authoritative even when health or startup publication
+  // times out. Never replace this owner based on elapsed time or its PID file.
+  return { state: endpoint ? 'unresponsive' : 'starting', cause };
+}
+
+function requireCompatible(status, expected) {
+  if (status.identity.code !== expected.code) throw new CommandError('runtime_code_mismatch', 'The running runtime uses different code. Inspect runtime status and explicitly stop it before starting this build.', { details: { runtimeId: status.runtimeId, pid: status.pid } });
+  if (status.identity.config !== expected.config) throw new CommandError('runtime_configuration_mismatch', 'The running runtime uses different persistent/provider configuration. Use the same configuration or explicitly stop it first.', { details: { runtimeId: status.runtimeId, pid: status.pid } });
+}
+
+function launch(location) {
+  prepareDirectory(location);
+  const log = fs.openSync(location.logFile, 'a', 0o600);
+  let child;
+  try {
+    child = fork(path.join(__dirname, 'execution-runtime.js'), [], {
+      detached: true, execArgv: [], stdio: ['ignore', log, log, 'ipc'],
+      env: { ...process.env, AI_APP_BRIDGE_FACT_STORE_DIR: location.facts },
+    });
+  } finally { fs.closeSync(log); }
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => finish(new CommandError('runtime_start_timeout', 'Runtime startup did not report readiness. No running owner was terminated.', { details: { logFile: location.logFile } })), 10000);
+    let done = false;
+    function finish(error, message) {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      child.removeAllListeners('message');
+      if (child.connected) child.disconnect();
+      child.unref();
+      error ? reject(error) : resolve(message);
+    }
+    child.once('message', message => {
+      if (message.status === 'ready' || message.status === 'owned') finish(null, message);
+      else finish(new CommandError(message.error || 'runtime_start_failed', message.message || 'Runtime startup failed.', { details: { logFile: location.logFile } }));
+    });
+    child.once('error', error => finish(new CommandError('runtime_start_failed', error.message)));
+    child.once('exit', (code, signal) => finish(new CommandError('runtime_start_failed', `Runtime exited before readiness: ${code ?? signal}.`, { details: { logFile: location.logFile } })));
+  });
+}
+
+async function ensureRuntime(location, identity, signal) {
+  let state = await probe(location, signal);
+  if (state.state === 'running') { requireCompatible(state.status, identity); return state.endpoint; }
+  if (state.state === 'unresponsive') throw new CommandError('runtime_unresponsive', 'The runtime still owns its OS lock but did not answer. It was not restarted.');
+  if (!starting.has(location.directory)) {
+    const pending = (async () => {
+      const deadline = Date.now() + 10000;
+      do {
+        let launched;
+        if (state.state === 'stopped') launched = await launch(location);
+        state = await probe(location, signal);
+        if (state.state === 'running') { requireCompatible(state.status, identity); return state.endpoint; }
+        if (state.state === 'stopped' && launched?.status === 'ready')
+          throw new CommandError('runtime_start_failed', 'The runtime exited after reporting readiness.');
+        // A candidate may lose to another client's short ownership probe,
+        // rather than to a running server. A now-free OS lock allows another
+        // startup election. No execute request has been sent at this point.
+        await new Promise(resolve => setTimeout(resolve, 100));
+      } while (Date.now() < deadline);
+      throw new CommandError('runtime_start_timeout', 'The existing runtime owner has not reported readiness.');
+    })();
+    starting.set(location.directory, pending);
+    pending.then(() => starting.delete(location.directory), () => starting.delete(location.directory));
+  }
+  return starting.get(location.directory);
+}
+
+async function run(request, { signal } = {}) {
+  try {
+    request = validateRunRequest(request);
+    // Verification is an offline command in both transports; it neither
+    // opens FactStore nor depends on a running owner or valid store profile.
+    if (request.command === 'evidence' && request.arguments.operation === 'verify') {
+      return { value: await require('./shared-kernel/evidence-archive').handle(request.arguments) };
+    }
+    const location = runtimeLocation();
+    const identity = runtimeIdentity(location);
+    if (request.command === 'runtime' && request.arguments.operation !== 'start') {
+      const state = await probe(location, signal);
+      if (state.state === 'stopped') return { value: { ok: true, command: 'runtime', status: 'stopped', facts: location.facts } };
+      if (state.state !== 'running') throw new CommandError('runtime_unresponsive', 'A runtime owns the OS lock but has not answered. It was not restarted.');
+      if (request.arguments.operation === 'stop') return await exchange(state.endpoint, 'stop', {}, { signal });
+      return { value: { ...state.status, compatible: state.status.identity.code === identity.code && state.status.identity.config === identity.config } };
+    }
+    const endpoint = await ensureRuntime(location, identity, signal);
+    if (request.command === 'runtime') return await exchange(endpoint, 'status', {}, { signal });
+    return await exchange(endpoint, 'execute', request, { identity, signal });
+  } catch (error) { return { value: commandFailure(error, request?.command) }; }
+}
+
+module.exports = { run, exchange };

package/bin/runtime-directory.js

@@ -0,0 +1,107 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { createHash, randomUUID } = require('node:crypto');
+const { CommandError } = require('./command-errors');
+const { hostFactStoreTarget } = require('./shared-kernel/host-fact-store');
+const { defaultDirectory: ownershipDirectory } = require('./shared-kernel/device-ownership-store');
+const { protocol } = require('./runtime-protocol');
+const { canonicalPath } = require('./shared-kernel/canonical-path');
+
+let fingerprint;
+function codeFingerprint() {
+  if (fingerprint) return fingerprint;
+  const hash = createHash('sha256');
+  function visit(directory) {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const file = path.join(directory, entry.name);
+      if (entry.isDirectory()) visit(file);
+      else if (entry.isFile()) { hash.update(path.relative(__dirname, file)); hash.update(fs.readFileSync(file)); }
+    }
+  }
+  visit(__dirname);
+  visit(path.join(__dirname, '../runtime'));
+  hash.update(fs.readFileSync(path.join(__dirname, '../package.json')));
+  // Execution also depends on bundled device code and the actually installed
+  // native store. A changed jar, WDA integration or addon is a different build.
+  for (const name of ['ws', 'appium-webdriveragent', '@mobileaidev/segmented-fact-store-native']) {
+    hash.update(name);
+    hash.update(fs.readFileSync(require.resolve(`${name}/package.json`)));
+  }
+  const nativeDirectory = path.dirname(require.resolve('@mobileaidev/segmented-fact-store-native'));
+  hash.update(fs.readFileSync(path.join(nativeDirectory, 'index.js')));
+  hash.update(fs.readFileSync(path.join(nativeDirectory, 'build/Release/segmented_fact_store.node')));
+  hash.update(JSON.stringify({ node: process.versions.node, modules: process.versions.modules }));
+  fingerprint = hash.digest('hex');
+  return fingerprint;
+}
+
+function runtimeLocation() {
+  const target = hostFactStoreTarget();
+  const facts = canonicalPath(target.directory);
+  const key = createHash('sha256').update(facts).digest('hex');
+  const home = path.resolve(process.env.AI_APP_BRIDGE_RUNTIME_HOME || path.join(os.homedir(), '.ai-app-bridge', 'runtimes', 'v1'));
+  const directory = path.join(home, key);
+  return { directory, facts, profile: target.profile, endpointFile: path.join(directory, 'endpoint.json'),
+    lockFile: path.join(directory, 'owner.sqlite'), logFile: path.join(directory, 'runtime.log') };
+}
+
+function runtimeIdentity(location = runtimeLocation()) {
+  const names = ['ADB', 'AI_APP_BRIDGE_ADB_TIMEOUT_MS', 'AI_APP_BRIDGE_DEVICECTL', 'AI_APP_BRIDGE_FACT_CACHE',
+    'AI_APP_BRIDGE_IOS_TEAM_ID', 'AI_APP_BRIDGE_PYTHON', 'ANDROID_HOME', 'ANDROID_SDK_ROOT', 'DEVELOPMENT_TEAM', 'DEVELOPER_DIR', 'XCODEBUILD'];
+  const config = { facts: location.facts, profile: location.profile, ownership: canonicalPath(ownershipDirectory()),
+    environment: Object.fromEntries(names.map(name => [name, process.env[name] ?? null])) };
+  return { protocol, code: codeFingerprint(), config: createHash('sha256').update(JSON.stringify(config)).digest('hex') };
+}
+
+function prepareDirectory(location) {
+  fs.mkdirSync(location.directory, { recursive: true, mode: 0o700 });
+  const info = fs.lstatSync(location.directory);
+  if (!info.isDirectory() || (process.getuid && info.uid !== process.getuid())) {
+    throw new CommandError('runtime_directory_unsafe', 'The runtime directory must belong to the current user.');
+  }
+  fs.chmodSync(location.directory, 0o700);
+}
+
+// The OS lock, not a PID or timeout, proves whether a runtime still owns this
+// namespace. Never unlink the SQLite file: doing so would split its inode lock.
+function acquireRuntimeLock(location) {
+  prepareDirectory(location);
+  const { DatabaseSync } = require('node:sqlite');
+  let db;
+  try {
+    db = new DatabaseSync(location.lockFile);
+    fs.chmodSync(location.lockFile, 0o600);
+    db.exec('PRAGMA busy_timeout=0; BEGIN EXCLUSIVE');
+  } catch (error) {
+    db?.close();
+    if (error.errcode === 5) return null;
+    throw new CommandError('runtime_lock_unavailable', 'Cannot acquire the local runtime lock.', { details: { cause: error.message } });
+  }
+  let closed = false;
+  return { close() { if (!closed) { closed = true; try { db.exec('ROLLBACK'); } finally { db.close(); } } } };
+}
+
+function readEndpoint(location) {
+  let bytes;
+  try { bytes = fs.readFileSync(location.endpointFile); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+  let value;
+  try { if (bytes.length > 16384) throw new Error(); value = JSON.parse(bytes); }
+  catch { throw new CommandError('runtime_endpoint_invalid', 'The runtime endpoint record is invalid.'); }
+  if (value.protocol !== protocol || !Number.isInteger(value.port) || value.port < 1 || value.port > 65535
+    || typeof value.token !== 'string' || !/^[a-f0-9]{64}$/.test(value.token)
+    || typeof value.runtimeId !== 'string' || !Number.isSafeInteger(value.pid)
+    || value.facts !== location.facts) throw new CommandError('runtime_endpoint_invalid', 'The runtime endpoint identity is invalid.');
+  return value;
+}
+
+function publishEndpoint(location, endpoint) {
+  const temporary = `${location.endpointFile}.${randomUUID()}.tmp`;
+  fs.writeFileSync(temporary, JSON.stringify(endpoint), { mode: 0o600, flag: 'wx' });
+  fs.renameSync(temporary, location.endpointFile);
+}
+
+module.exports = { runtimeLocation, runtimeIdentity, prepareDirectory, acquireRuntimeLock, readEndpoint, publishEndpoint };

package/bin/runtime-protocol.js

@@ -0,0 +1,36 @@
+'use strict';
+
+const { CommandError } = require('./command-errors');
+const protocol = 'aab.runtime/v1';
+const maxMessageBytes = 128 * 1024 * 1024;
+
+// The wire distinguishes JSON, text and bytes. History never replaces a raw
+// observation, and an absent provider result is not a successful command.
+function encodeReply({ value, history }) {
+  if (value === undefined) throw new CommandError('runtime_result_missing', 'Execution returned no result.', { dispatched: null, ambiguous: true });
+  const kind = Buffer.isBuffer(value) ? 'bytes' : typeof value === 'string' ? 'text' : 'json';
+  return { kind, value: kind === 'bytes' ? value.toString('base64') : value, ...(history ? { history } : {}) };
+}
+
+function decodeReply(reply) {
+  if (!reply || !['json', 'text', 'bytes'].includes(reply.kind) || !Object.hasOwn(reply, 'value')
+    || (reply.kind !== 'json' && typeof reply.value !== 'string')) {
+    throw new CommandError('runtime_protocol_error', 'The runtime returned an invalid execution reply.', { dispatched: null, ambiguous: true });
+  }
+  return { value: reply.kind === 'bytes' ? Buffer.from(reply.value, 'base64') : reply.value,
+    ...(reply.history ? { history: reply.history } : {}) };
+}
+
+async function readJson(stream) {
+  const chunks = [];
+  let bytes = 0;
+  for await (const chunk of stream) {
+    bytes += chunk.length;
+    if (bytes > maxMessageBytes) throw new CommandError('runtime_message_too_large', 'Runtime messages are limited to 128 MiB.');
+    chunks.push(chunk);
+  }
+  try { return JSON.parse(Buffer.concat(chunks).toString('utf8')); }
+  catch { throw new CommandError('runtime_protocol_error', 'Expected one JSON runtime message.'); }
+}
+
+module.exports = { protocol, maxMessageBytes, encodeReply, decodeReply, readJson };

package/bin/script/bounded-script-registry.js

@@ -0,0 +1,103 @@
+'use strict';
+
+function createBoundedScriptRegistry({
+  maxOperations = 256,
+  maxEvents = 256,
+  maxEventBytes = 256 * 1024,
+} = {}) {
+  const operations = new Map();
+
+  function put(operationId, record) {
+    const existing = operations.get(operationId);
+    if (existing && !isTerminal(existing.status)) {
+      return { ok: false, error: 'operation_exists' };
+    }
+    if (!existing && operations.size >= maxOperations) evict();
+    if (!existing && operations.size >= maxOperations) {
+      return { ok: false, error: 'registry_full' };
+    }
+    operations.set(operationId, record);
+    return { ok: true, record };
+  }
+
+  function get(operationId) {
+    return operations.get(operationId) || null;
+  }
+
+  function evict() {
+    for (const [id, record] of operations) {
+      if (operations.size < maxOperations) return;
+      if (isTerminal(record.status)) operations.delete(id);
+    }
+  }
+
+  function retainedBytes() {
+    let total = 0;
+    for (const record of operations.values()) {
+      total += record.events?.bytes || 0;
+    }
+    return total;
+  }
+
+  return {
+    put,
+    get,
+    values: () => [...operations.values()],
+    evict,
+    retainedBytes,
+    get size() { return operations.size; },
+    maxOperations,
+    maxEvents,
+    maxEventBytes,
+  };
+}
+
+function createBoundedEventLog({ maxEvents = 256, maxEventBytes = 256 * 1024 } = {}) {
+  const events = [];
+  const waiters = new Set();
+  let sequence = 0;
+  let bytes = 0;
+
+  function emit(type, extra = {}, now = Date.now) {
+    sequence += 1;
+    const event = { sequence, type, atMs: typeof now === 'function' ? now() : now, ...extra };
+    const encoded = Buffer.byteLength(JSON.stringify(event), 'utf8');
+    events.push({ event, encoded });
+    bytes += encoded;
+    while (events.length > maxEvents || bytes > maxEventBytes) {
+      const removed = events.shift();
+      if (!removed) break;
+      bytes -= removed.encoded;
+    }
+    for (const waiter of waiters) waiter();
+    return event;
+  }
+
+  function subscribe(waiter) {
+    waiters.add(waiter);
+    return () => waiters.delete(waiter);
+  }
+
+  function after(afterSequence = 0, limit = null) {
+    const selected = events
+      .map((item) => item.event)
+      .filter((event) => event.sequence > afterSequence);
+    if (limit == null) return selected;
+    return selected.slice(0, Number(limit));
+  }
+
+  return {
+    emit,
+    after,
+    subscribe,
+    get sequence() { return sequence; },
+    get size() { return events.length; },
+    get bytes() { return bytes; },
+  };
+}
+
+function isTerminal(status) {
+  return status === 'completed' || status === 'cancelled' || status === 'failed';
+}
+
+module.exports = { createBoundedScriptRegistry, createBoundedEventLog };

package/bin/script/node-runtime-adapter.js

@@ -0,0 +1,233 @@
+'use strict';
+
+const { spawn } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { requestDirectory, inRequestDirectory } = require('../shared-kernel/request-context');
+const { createScriptSessionChannel } = require('./script-session-channel');
+
+function jsonBytes(value) {
+  return Buffer.byteLength(JSON.stringify(value ?? null), 'utf8');
+}
+
+function childExitPromise(child, onSpawnFailure) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+    child.on('exit', (code) => done({ type: 'exit', code }));
+    child.on('error', (error) => {
+      if (typeof onSpawnFailure === 'function') onSpawnFailure(error);
+      if (child.pid == null) {
+        done({ type: 'exit', code: null, error: error.message });
+      }
+    });
+  });
+}
+
+function createChildRuntimeAdapter({
+  kind,
+  executable,
+  argsPrefix = [],
+  sdkFile,
+  extension,
+  onSpawnFailure,
+} = {}) {
+  let channel = null;
+  let exited = Promise.resolve();
+  let readControl = () => ({ status: 'running', pauseReason: null });
+
+  async function terminate() {
+    if (channel) channel.stop();
+    await exited;
+  }
+
+  function start(args) {
+    return inRequestDirectory(args.spec.cwd ?? requestDirectory(), () => startInDirectory(args));
+  }
+
+  async function startInDirectory({ spec, host, agent, emit, control }) {
+    readControl = typeof control === 'function' ? control : () => control || { status: 'running', pauseReason: null };
+    const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'aab-script-'));
+    const artifact = path.join(directory, `main${extension}`);
+    fs.writeFileSync(artifact, spec.source);
+    const sdk = path.join(__dirname, sdkFile);
+    const child = spawn(executable, argsPrefix.concat([sdk, artifact]), {
+      shell: false,
+      cwd: requestDirectory(),
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    channel = createScriptSessionChannel(child, {
+      maxFrameBytes: Math.max(spec.policy.maxOutputBytes, spec.policy.maxProgressBytes, 1024 * 1024) + 64 * 1024,
+    });
+    exited = childExitPromise(child, onSpawnFailure);
+    const finished = exited;
+    let timer = null;
+    const timedOut = new Promise((resolve) => {
+      timer = setTimeout(() => resolve({ type: 'timeout' }), spec.policy.timeoutMs);
+    });
+    const rpc = pending => Promise.race([pending, timedOut, finished.then(() => { throw new Error('child_crashed'); })]);
+    try {
+    const ready = await Promise.race([
+      channel.nextMessage(),
+      finished,
+      timedOut,
+    ]);
+    if (ready && ready.type === 'timeout') {
+      await terminate();
+      return { ok: false, error: 'timeout' };
+    }
+    if (!ready || ready.type !== 'ready') {
+      await terminate();
+      return { ok: false, error: ready && ready.type === 'fail' && ready.error === 'handshake_failed' ? 'handshake_failed' : 'child_crashed' };
+    }
+    emit('child_started', { kind });
+    channel.send({
+      type: 'start',
+      inputs: spec.inputs,
+      entrypoint: spec.entrypoint,
+      control: control(),
+    });
+    while (true) {
+      const message = await Promise.race([
+        channel.nextMessage(),
+        finished,
+        timedOut,
+      ]);
+      if (message.type === 'timeout') {
+        await terminate();
+        emit('script_failed', { error: 'timeout' });
+        return { ok: false, error: 'timeout' };
+      }
+      if (message.type === 'call') {
+        const value = await rpc(host.call(message.command, message.args, message.options));
+        if (value && value.type === 'timeout') {
+          await terminate();
+          emit('script_failed', { error: 'timeout' });
+          return { ok: false, error: 'timeout' };
+        }
+        channel.send({ type: 'result', id: message.id, value, control: readControl() });
+        continue;
+      }
+      if (message.type === 'assert') {
+        const value = await rpc(host.assert(message.assertion));
+        if (value && value.type === 'timeout') {
+          await terminate();
+          emit('script_failed', { error: 'timeout' });
+          return { ok: false, error: 'timeout' };
+        }
+        channel.send({ type: 'verdict', id: message.id, value, control: readControl() });
+        continue;
+      }
+      if (message.type === 'control-point') {
+        channel.send({ type: 'control-state', id: message.id, control: readControl() });
+        continue;
+      }
+      if (message.type === 'progress') {
+        if (jsonBytes(message.event) > spec.policy.maxProgressBytes) {
+          await terminate();
+          emit('script_failed', { error: 'progress_too_large' });
+          return { ok: false, error: 'progress_too_large' };
+        }
+        emit('progress', message.event);
+        continue;
+      }
+      if (message.type === 'checkpoint') {
+        if (jsonBytes(message.state) > spec.policy.maxOutputBytes) {
+          await terminate();
+          emit('script_failed', { error: 'checkpoint_too_large' });
+          return { ok: false, error: 'checkpoint_too_large' };
+        }
+        const receipt = await rpc(Promise.resolve(emit('checkpoint', { name: message.name, state: message.state })));
+        if (receipt && receipt.type === 'timeout') {
+          await terminate();
+          emit('script_failed', { error: 'timeout' });
+          return { ok: false, error: 'timeout' };
+        }
+        if (receipt && receipt.ok === false) {
+          await terminate();
+          const error = receipt.error || 'checkpoint_not_persisted';
+          emit('script_failed', { error });
+          return { ok: false, error };
+        }
+        channel.send({ type: 'checkpoint-receipt', id: message.id, value: receipt, control: readControl() });
+        continue;
+      }
+      if (message.type === 'ask') {
+        const value = await rpc(agent.askAgent(message.request));
+        if (value && value.type === 'timeout') {
+          await terminate();
+          emit('script_failed', { error: 'timeout' });
+          return { ok: false, error: 'timeout' };
+        }
+        channel.send({ type: 'decision', id: message.id, value, control: readControl() });
+        continue;
+      }
+      if (message.type === 'return') {
+        if (jsonBytes(message.result) > spec.policy.maxOutputBytes) {
+          await terminate();
+          emit('script_failed', { error: 'output_too_large' });
+          return { ok: false, error: 'output_too_large' };
+        }
+        child.stdin.end();
+        const ended = await Promise.race([finished, timedOut]);
+        if (ended && ended.type === 'timeout') {
+          await terminate();
+        } else {
+          await finished;
+        }
+        emit('script_completed', { result: message.result });
+        return { ok: true, result: message.result };
+      }
+      if (message.type === 'fail') {
+        await terminate();
+        const error = message.error === 'channel_closed' || message.error === 'stopped'
+          ? 'child_crashed'
+          : (message.error || 'script_failed');
+        emit('script_failed', { error });
+        return { ok: false, error };
+      }
+      if (message.type === 'exit') {
+        await terminate();
+        emit('script_failed', { error: 'child_crashed' });
+        return { ok: false, error: 'child_crashed' };
+      }
+      await terminate();
+      emit('script_failed', { error: 'child_crashed' });
+      return { ok: false, error: 'child_crashed' };
+    }
+    } catch {
+      await terminate();
+      emit('script_failed', { error: 'child_crashed' });
+      return { ok: false, error: 'child_crashed' };
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+
+  function stop() {
+    return terminate();
+  }
+
+  function setControl(next) {
+    if (!channel) return;
+    channel.send({ type: 'control', control: next || readControl() });
+  }
+
+  return { kind, start, stop, setControl };
+}
+
+function createNodeRuntimeAdapter() {
+  return createChildRuntimeAdapter({
+    kind: 'javascript',
+    executable: process.execPath,
+    sdkFile: 'script-sdk.js',
+    extension: '.js',
+  });
+}
+
+module.exports = { createNodeRuntimeAdapter, createChildRuntimeAdapter, childExitPromise };