@mobileaidev/ai-app-bridge 0.3.8 → 0.4.0

package/bin/runtime-client.js

@@ -4,10 +4,11 @@ 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 { CommandError } = require('./command-errors');
+const { validateRunRequest, publicOutputLimit } = require('./command-request');
+const { publicReply, publicFailure, isPublicReply, finishReply } = require('./public-reply');
 const { protocol, maxMessageBytes, readJson, decodeReply } = require('./runtime-protocol');
-const { runtimeLocation, runtimeIdentity, acquireRuntimeLock, readEndpoint, prepareDirectory } = require('./runtime-directory');
+const { runtimeLocation, runtimeIdentity, requireCompatible, acquireRuntimeLock, readEndpoint, prepareDirectory } = require('./runtime-directory');
 const { executablePath } = require('./shared-kernel/executable-path');
 const starting = new Map();
 
@@ -66,11 +67,6 @@ async function probe(location, signal) {
   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);
@@ -132,27 +128,48 @@ async function ensureRuntime(location, identity, signal) {
   return starting.get(location.directory);
 }
 
+// The reply is always the public reply of the request. Executed commands
+// arrive assembled by the Runtime; local paths and client failures are
+// assembled here with the same module.
 async function run(request, { signal } = {}) {
+  const command = typeof request?.command === 'string' ? request.command : undefined;
+  const maxBytes = publicOutputLimit(request);
+  let extract;
   try {
     request = validateRunRequest(request);
+    if (request.command === 'runtime' || (request.command === 'evidence' && request.arguments.operation === 'verify')) {
+      extract = require('./extraction/prepare').prepareExtraction(request.extract);
+    }
+  }
+  catch (error) { return { value: publicFailure({ command, stage: 'validation', error, maxBytes }) }; }
+  const local = async reply => ({ value: await finishReply({ body: publicReply({ command: request.command, reply, completed: true }),
+    extract, output: request.output }) });
+  try {
     // 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) };
+      return local({ 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 === 'stopped') return local({ 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 } };
+      if (request.arguments.operation === 'stop') return local(await exchange(state.endpoint, 'stop', {}, { signal }));
+      return local({ 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) }; }
+    if (request.command === 'runtime') return local(await exchange(endpoint, 'status', {}, { signal }));
+    const reply = await exchange(endpoint, 'execute', request, { identity, signal });
+    if (isPublicReply(reply.value)) return reply;
+    // Authentication and request-decoding failures precede execute dispatch,
+    // so the internal RPC cannot yet identify the requested public command.
+    if (reply.value?.ok === false && reply.value.dispatched === false
+      && ['runtime_access_denied', 'runtime_protocol_error', 'runtime_message_too_large'].includes(reply.value.error)) return { value: publicFailure({
+        command: request.command, stage: 'execution', error: new CommandError(reply.value.error, reply.value.message), maxBytes: request.output?.maxBytes }) };
+    throw new CommandError('runtime_protocol_error', 'Execute returned no public reply.', { dispatched: null, ambiguous: true });
+  } catch (error) { return { value: publicFailure({ command: request.command, stage: 'execution', error, maxBytes: request.output?.maxBytes }) }; }
 }
 
 module.exports = { run, exchange };

package/bin/runtime-directory.js

@@ -11,9 +11,7 @@ const { protocol } = require('./runtime-protocol');
 const { canonicalPath } = require('./shared-kernel/canonical-path');
 const { executablePath } = require('./shared-kernel/executable-path');
 
-let fingerprint;
-function codeFingerprint() {
-  if (fingerprint) return fingerprint;
+function calculateCodeFingerprint() {
   const hash = createHash('sha256');
   function visit(directory) {
     for (const entry of fs.readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
@@ -33,12 +31,19 @@ function codeFingerprint() {
   }
   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(fs.readFileSync(path.join(nativeDirectory, 'binding-path.js')));
+  hash.update(fs.readFileSync(path.join(nativeDirectory, 'prebuilds/manifest.json')));
+  const nativeBinding = require('@mobileaidev/segmented-fact-store-native/binding-path').resolveBinding();
+  hash.update(fs.readFileSync(nativeBinding.path));
   hash.update(JSON.stringify({ node: process.versions.node, modules: process.versions.modules }));
-  fingerprint = hash.digest('hex');
-  return fingerprint;
+  return hash.digest('hex');
 }
 
+// Pin the running client's code when this entrypoint loads, before the first
+// request. Replacing installed files cannot make this process claim new code.
+const fingerprint = calculateCodeFingerprint();
+const packageVersion = require('../package.json').version;
+
 function runtimeLocation() {
   const target = hostFactStoreTarget();
   const facts = canonicalPath(target.directory);
@@ -55,7 +60,31 @@ function runtimeIdentity(location = runtimeLocation()) {
   const config = { facts: location.facts, profile: location.profile, ownership: canonicalPath(ownershipDirectory()),
     adb: executablePath(process.env.ADB || 'adb') ?? { unavailable: process.env.ADB || 'adb' },
     environment: Object.fromEntries(names.map(name => [name, process.env[name] ?? null])) };
-  return { protocol, code: codeFingerprint(), config: createHash('sha256').update(JSON.stringify(config)).digest('hex') };
+  return { protocol, code: fingerprint, config: createHash('sha256').update(JSON.stringify(config)).digest('hex'),
+    version: packageVersion, node: { version: process.versions.node, modules: process.versions.modules, napi: process.versions.napi } };
+}
+
+function requireCompatible(status, client) {
+  const runtime = status.identity;
+  const codeMismatch = runtime?.code !== client?.code;
+  const configMismatch = runtime?.config !== client?.config;
+  if (!codeMismatch && !configMismatch) return;
+  const parse = version => typeof version === 'string' && /^\d+\.\d+\.\d+$/.test(version) ? version.split('.').map(Number) : null;
+  const runtimeVersion = parse(runtime?.version), clientVersion = parse(client?.version);
+  let outdatedSide = 'undetermined';
+  if (runtimeVersion && clientVersion) {
+    const index = runtimeVersion.findIndex((part, i) => part !== clientVersion[i]);
+    if (index >= 0) outdatedSide = runtimeVersion[index] < clientVersion[index] ? 'runtime' : 'client';
+  }
+  const describe = identity => `package ${identity?.version ?? 'unknown'}, Node ${identity?.node?.version ?? 'unknown'}, ABI ${identity?.node?.modules ?? 'unknown'}, code ${identity?.code ?? 'unknown'}, config ${identity?.config ?? 'unknown'}`;
+  let next;
+  if (!codeMismatch) next = 'Use matching persistent/provider configuration; the running Runtime was not restarted.';
+  else if (outdatedSide === 'client') next = 'The client package is older. Update and reconnect the client; do not stop the newer Runtime to fix this client.';
+  else if (outdatedSide === 'runtime') next = 'The Runtime package is older. Finish its active tasks, then explicitly run runtime --operation stop --extract null and reconnect with the updated installation.';
+  else next = 'Builds or Node environments differ. Align the installations and reconnect; fingerprints alone cannot identify an older side.';
+  throw new CommandError(codeMismatch ? 'runtime_code_mismatch' : 'runtime_configuration_mismatch',
+    `Client: ${describe(client)}. Runtime: ${describe(runtime)}. ${next}`,
+    { details: { runtimeId: status.runtimeId, pid: status.pid, client, runtime, outdatedSide } });
 }
 
 function prepareDirectory(location) {
@@ -106,4 +135,4 @@ function publishEndpoint(location, endpoint) {
   fs.renameSync(temporary, location.endpointFile);
 }
 
-module.exports = { runtimeLocation, runtimeIdentity, prepareDirectory, acquireRuntimeLock, readEndpoint, publishEndpoint };
+module.exports = { runtimeLocation, runtimeIdentity, requireCompatible, prepareDirectory, acquireRuntimeLock, readEndpoint, publishEndpoint };

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

@@ -38,174 +38,190 @@ function createChildRuntimeAdapter({
   onSpawnFailure,
 } = {}) {
   let channel = null;
+  let child = null;
   let exited = Promise.resolve();
   let readControl = () => ({ status: 'running', pauseReason: null });
 
   async function terminate() {
     if (channel) channel.stop();
     await exited;
+    child?.stdin?.destroy(); child?.stdout?.destroy(); child?.stderr?.destroy();
   }
 
-  function start(args) {
-    return inRequestDirectory(args.spec.cwd ?? requestDirectory(), () => startInDirectory(args));
+  async function start(args) {
+    const result = await inRequestDirectory(args.spec.cwd ?? requestDirectory(), () => startInDirectory(args));
+    if (!result.ok && channel) {
+      const diagnostics = { ...channel.diagnostics(), ...result.diagnostics };
+      if (Object.keys(diagnostics).length) result.diagnostics = diagnostics;
+    }
+    return result;
   }
 
   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 directory;
     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'); })]);
+    channel = null;
+    exited = Promise.resolve();
     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([
+      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);
+      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;
+      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'); })]);
+      const ready = await Promise.race([
         channel.nextMessage(),
         finished,
         timedOut,
       ]);
-      if (message.type === 'timeout') {
+      if (ready && ready.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 (!ready || ready.type !== 'ready') {
+        await terminate();
+        return { ok: false, error: ready && ready.type === 'fail' && ready.error === 'handshake_failed' ? 'handshake_failed' : 'child_crashed' };
       }
-      if (message.type === 'assert') {
-        const value = await rpc(host.assert(message.assertion));
-        if (value && value.type === 'timeout') {
+      emit('child_started', { kind });
+      channel.send({
+        type: 'start',
+        inputs: spec.inputs,
+        entrypoint: spec.entrypoint,
+        sourceName: spec.sourcePath || artifact,
+        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' };
         }
-        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' };
+        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;
         }
-        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' };
+        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;
         }
-        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 (message.type === 'control-point') {
+          channel.send({ type: 'control-state', id: message.id, control: readControl() });
+          continue;
         }
-        if (receipt && receipt.ok === false) {
-          await terminate();
-          const error = receipt.error || 'checkpoint_not_persisted';
-          emit('script_failed', { error });
-          return { ok: false, error };
+        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;
         }
-        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' };
+        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;
         }
-        channel.send({ type: 'decision', id: message.id, value, control: readControl() });
-        continue;
-      }
-      if (message.type === 'return') {
-        if (jsonBytes(message.result) > spec.policy.maxOutputBytes) {
+        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();
-          emit('script_failed', { error: 'output_too_large' });
-          return { ok: false, error: 'output_too_large' };
+          const error = message.error === 'channel_closed' || message.error === 'stopped'
+            ? 'child_crashed'
+            : (message.error || 'script_failed');
+          const captured = channel.diagnostics();
+          const diagnostics = { ...captured, ...(message.diagnostic ? { error: message.diagnostic } : {}) };
+          const extra = Object.keys(diagnostics).length ? { diagnostics } : {};
+          emit('script_failed', { error, ...extra });
+          return { ok: false, error, ...extra };
         }
-        child.stdin.end();
-        const ended = await Promise.race([finished, timedOut]);
-        if (ended && ended.type === 'timeout') {
+        if (message.type === 'exit') {
           await terminate();
-        } else {
-          await finished;
+          emit('script_failed', { error: 'child_crashed' });
+          return { ok: false, error: 'child_crashed' };
         }
-        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);
+      await terminate();
+      if (directory) fs.rmSync(directory, { recursive: true, force: true });
     }
   }
 

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

@@ -35,7 +35,7 @@ function pythonCandidates({ pythonPath, env = process.env } = {}) {
 }
 
 function probePython(executable, env) {
-  const options = { encoding: 'utf8', shell: false };
+  const options = { encoding: 'utf8', shell: false, timeout: 5000, killSignal: 'SIGKILL', maxBuffer: 16384 };
   if (env) options.env = env;
   const probe = spawnSync(executable, ['-c', 'import sys; print("%d.%d" % sys.version_info[:2])'], options);
   if (probe.status !== 0 || !probe.stdout) {

package/bin/script/script-diagnostics.js

@@ -0,0 +1,21 @@
+'use strict';
+
+function boundedText(value, maxBytes) {
+  return Buffer.from(String(value)).subarray(0, maxBytes).toString('utf8').replace(/\uFFFD$/, '');
+}
+
+function errorDiagnostic(error) {
+  const stack = typeof error?.stack === 'string' ? error.stack : '';
+  let frameCount = 0;
+  const limitedStack = stack.split('\n').filter(line => !/^\s*at /.test(line) || ++frameCount <= 20).join('\n');
+  const frame = stack.split('\n').find(line => /:(\d+):(\d+)\)?$/.test(line));
+  const location = frame?.match(/(?:at .*?\(|at )(.*):(\d+):(\d+)\)?$/);
+  const syntaxLocation = error?.name === 'SyntaxError' ? stack.split('\n')[0].match(/^(.*):(\d+)$/) : null;
+  return { type: boundedText(error?.name || 'Error', 128), message: boundedText(error?.message ?? error, 2048),
+    ...(stack ? { stack: boundedText(limitedStack, 8192), stackTruncated: frameCount > 20 || Buffer.byteLength(limitedStack) > 8192 } : {}),
+    ...(syntaxLocation ? { location: { file: boundedText(syntaxLocation[1], 1024), line: Number(syntaxLocation[2]) } }
+      : location ? { location: { file: boundedText(location[1], 1024), line: Number(location[2]), column: Number(location[3]) } } : {}),
+    ...(typeof error?.valuePath === 'string' ? { valuePath: boundedText(error.valuePath, 1024) } : {}) };
+}
+
+module.exports = { boundedText, errorDiagnostic };

package/bin/script/script-durable-restore.js

@@ -157,6 +157,7 @@ async function restoreUnknownOperation(args = {}) {
       operationId,
       status: terminal ? checkpoint.status : 'failed',
       error: terminal ? checkpoint.error || null : 'runtime_lost',
+      ...(checkpoint.diagnostics ? { diagnostics: checkpoint.diagnostics } : {}),
       persisted: true,
       restored: true,
       resumeMode: gate.ok ? 'checkpoint' : 'none',

package/bin/script/script-sdk.js

@@ -2,8 +2,9 @@
 
 const fs = require('node:fs');
 const readline = require('node:readline');
+const { boundedText, errorDiagnostic } = require('./script-diagnostics');
 
-const artifactPath = process.argv[2];
+const artifactPath = fs.realpathSync(process.argv[2]);
 const replies = new Map();
 const controlWaiters = [];
 let nextId = 0;
@@ -37,6 +38,7 @@ function waitReply(id) {
 rl.on('line', (line) => {
   if (!line) return;
   let message;
+  const parseStarted = performance.now();
   try {
     message = JSON.parse(line);
   } catch {
@@ -44,10 +46,21 @@ rl.on('line', (line) => {
     process.exit(1);
     return;
   }
+  const inputParseMs = performance.now() - parseStarted;
   if (message.type === 'start') {
     applyControl(message.control);
-    run(message).catch((error) => {
-      send({ type: 'fail', error: error.message || String(error) });
+    run(message, inputParseMs).catch((error) => {
+      const diagnostic = errorDiagnostic(error);
+      if (message.sourceName && message.sourceName !== artifactPath) {
+        if (diagnostic.stack) {
+          const mapped = diagnostic.stack.replaceAll(artifactPath, message.sourceName);
+          diagnostic.stack = boundedText(mapped, 8192);
+          diagnostic.stackTruncated ||= Buffer.byteLength(mapped) > 8192;
+        }
+        if (diagnostic.location?.file === artifactPath) diagnostic.location.file = boundedText(message.sourceName, 1024);
+      }
+      send({ type: 'fail', error: message.extraction ? (error.code || 'extraction_failed') : diagnostic.message,
+        message: diagnostic.message, diagnostic });
       process.exit(1);
     });
     return;
@@ -92,7 +105,29 @@ function holdIfPaused() {
   });
 }
 
-async function run(start) {
+async function run(start, inputParseMs) {
+  if (start.extraction) {
+    const executionStarted = performance.now();
+    let result;
+    if (start.extraction.mode === 'regex') result = require('../extraction/regex').extractRegex(start.inputs.response, start.extraction);
+    else {
+      const Module = require('node:module');
+      const path = require('node:path');
+      const filename = path.resolve(start.sourceName || artifactPath);
+      const loaded = new Module(filename, module);
+      loaded.filename = filename;
+      loaded.paths = Module._nodeModulePaths(path.dirname(filename));
+      loaded._compile(fs.readFileSync(artifactPath, 'utf8'), filename);
+      const main = typeof loaded.exports === 'function' ? loaded.exports : loaded.exports.main;
+      if (typeof main !== 'function') throw new TypeError('Extraction source must export main(ctx).');
+      result = await main({ inputs: start.inputs });
+    }
+    require('../extraction/json-value').validateJsonValue(result);
+    if (Buffer.byteLength(JSON.stringify(result)) > 256 * 1024) throw Object.assign(new Error('Extraction result exceeds 256 KiB.'), { code: 'extraction_output_too_large' });
+    send({ type: 'return', result, timings: { inputParseMs, executionMs: performance.now() - executionStarted } });
+    process.exit(0);
+    return;
+  }
   const loaded = require(artifactPath);
   const entry = start.entrypoint || 'main';
   const main = typeof loaded === 'function' && entry === 'main' ? loaded : loaded[entry];