feat(dev): PR 2a — execution parity, provenance, and honest telemetry for Workbench route invocations (#600)

.changeset/wb600-pr2a-execution-parity.md

@@ -0,0 +1,5 @@
+---
+"agent-bundle": patch
+---
+
+Run Workbench route invocations (`POST /api/routes/invocations`) through the published compiler epoch by default, so compiler aliases and defines, generated CLI `mapInput` and confirmation, event preflight, operator `.env` layering, and measured provider and render telemetry match the installed artifact and MCP input is validated against the compiled `inputSchema` before the handler runs; `agent-bundle dev` pins `AGENT_BUNDLE_STATE_ROOT` for invocations and dev MCP sessions to `<project>/.agent-bundle/state` so state survives a republish. Requests replace `args`/`event` with a `surface` union (`mcp`, `cli`, `event`, `script`, `unit-render`) resolved from the route kind when omitted and recorded on every envelope, and a completed run reports an `outcome` (`success`, `represented-error`, or `process-exit` with the generated bin's exit code) separately from its execution `status` in the envelope, the `route.invocation` project event, and the Workbench. New diagnostics: `AB8239` (published revision moved while queued), `AB8250`–`AB8252` (compiled artifact, route executable, or preparation unavailable), `AB8253`/`AB8254` (CLI command or projected `cli:` id instead of the canonical `tool:` operation), and `AB8255` (preflight event route submitted without a concrete host). The unit-render loader rewrites only module specifiers from `.js` to `.tsx`, leaving string literals intact. (#643)

docs/diagnostics.md

@@ -45,6 +45,8 @@ even when no error diagnostic was reported.
 | `AB8219`–`AB8223` | Workbench live MCP probe route (user-initiated, read-only initialize + tools/list): `AB8219` invalid path, `AB8220` invalid request/method, `AB8221` probe target not found, `AB8222` response over the 16 MiB budget, `AB8223` probe unavailable. |
 | `AB8233`–`AB8235` | Workbench browser-side strict decoders rejecting a dev-server response: `AB8233` lifecycle replay, `AB8234` host discovery, `AB8235` MCP probe report. |
 | `AB8231`–`AB8232`, `AB8236`–`AB8238` | Workbench route invocation service (`/api/routes/invocations`): `AB8231` unknown route or invocation id, `AB8232` no published build / invocation manifest unavailable, `AB8236` render child timed out or crashed, `AB8237` malformed invocation request, and `AB8238` unknown fixture id. (`AB8233`–`AB8235` were already assigned to browser-side decoders.) |
+| `AB8239` | Workbench route invocation service (`/api/routes/invocations`): the published manifest digest or source revision moved while the request waited for a concurrency slot (409). Retry against the current revision so the recorded `manifestDigest`/`sourceRevision` cannot describe a different build than the one that ran. |
+| `AB8250`–`AB8255` | Workbench production route execution: `AB8250` no published compiler artifact is available, `AB8251` the selected route has no executable in the published artifact, `AB8252` compiled CLI projection or event preflight preparation failed, `AB8253` a selected CLI command does not project onto the canonical operation id, `AB8254` a projected `cli:<command>` id was used instead of its canonical `tool:<server>/<tool>` id plus CLI surface, and `AB8255` an event route with compiled preflight was submitted without a concrete host surface. Rebuild the project for `AB8250`/`AB8251`; fix the reported projection or preflight failure for `AB8252`; use the command or canonical operation named by `AB8253`/`AB8254`; select a generated host wrapper for `AB8255`. |
 | `AB8110`–`AB8113` | Workbench standalone MCP Inspector routes (`/api/inspector/status`, `/api/inspector/launch`): `AB8110` invalid path, `AB8111` invalid request shape or query, `AB8112` the Inspector could not be launched (spawn failure, exit before publishing a URL, or the 30 s startup budget elapsed; 502), `AB8113` routes not available (404 when the launcher is not composed, 503 after shutdown). |
 | `AB8120`–`AB8123` | Workbench route manifest (`/api/routes/manifest`): `AB8120` invalid path, `AB8121` not available (404/409/503), `AB8122` query string on the request, `AB8123` the browser client could not decode the response (see below). |
 | `AB8024`–`AB8025` | Live host MCP proxy: epoch drift behind a host connection and dev-server unavailability (see below). |

packages/agent-bundle/src/adapters/hook-contract.ts

@@ -668,7 +668,8 @@ const eventRouteHookWrapperSource = (
   // their session; only projects whose state is workspace-durable have one.
   const retiresLineage = standalone && durableLineage && route.event === 'session/end';
   const projectBindings = [
-    ...(standalone ? ['createCanonicalEventProps', 'projectEventDocument'] : []),
+    'createCanonicalEventProps',
+    ...(standalone ? ['projectEventDocument'] : []),
     'validateNativeEventEnvelope',
   ];
   return [
@@ -706,6 +707,11 @@ const eventRouteHookWrapperSource = (
     "const endpointId = `${artifactEpoch}:${dirname(dirname(resolve(process.argv[1])))}`;",
     '',
     'const fail = (message) => { throw new Error(`Agent Bundle event route error: ${message}`); };',
+    'export const prepareRouteInvocation = (nativeInput, signal) => {',
+    '  const native = validateNativeEventEnvelope(nativeInput, { canonicalEvent, nativeEvent, target });',
+    '  const props = createCanonicalEventProps(canonicalEvent, native, target, nativeEvent, capabilityRevision, signal);',
+    '  return Object.freeze({ gate: "execute", native, props, runtime: runtimeMode });',
+    '};',
     ...(standalone
       ? [
           // The wrapper lives in `hooks/`, so its code root is the parent
@@ -894,6 +900,19 @@ const eventRoutePreflightWrapperSource = (
     `const timeoutMs = ${String(entry.hook.timeoutMs ?? 5_000)};`,
     `const executor = fileURLToPath(new URL(/* webpackIgnore: true */ ${JSON.stringify(`./${executorFile}`)}, import.meta.url));`,
     'const fail = (message) => { throw new Error(`Agent Bundle event route error: ${message}`); };',
+    'export const prepareRouteInvocation = async (nativeInput, signal, observer) => {',
+    '  const native = validateNativeEventEnvelope(nativeInput, { canonicalEvent, nativeEvent, target });',
+    '  const props = createCanonicalEventProps(canonicalEvent, native, target, nativeEvent, capabilityRevision, signal);',
+    '  const trace = createEventTracer({ execution: eventTraceExecution({ event: canonicalEvent, host: target, nativeEvent }), ...(observer === undefined ? {} : { observer }) });',
+    '  const gate = await executeEventPreflight(preflight, {',
+    '    canonical: props.canonical,',
+    '    host: { name: target, nativeEvent },',
+    '    signal,',
+    '    terminal: { hostSurface: "hook", sharesTarget: false, stderr: { color: "none", kind: "none" }, stdout: { color: "none", kind: "none" } },',
+    '  }, trace);',
+    '  const projected = gate === "execute" ? undefined : projectEventPreflightResult(gate, canonicalEvent, target, nativeEvent, native);',
+    '  return Object.freeze({ gate, native, projected, props, runtime: runtimeMode, trace });',
+    '};',
     'const runExecutor = (input, signal) => new Promise((resolve, reject) => {',
     '  const child = spawn(process.execPath, [executor], { signal, stdio: ["pipe", "pipe", "pipe"] });',
     '  const stdout = [];',
@@ -921,19 +940,10 @@ const eventRoutePreflightWrapperSource = (
     '  const input = Buffer.concat(chunks);',
     '  let parsed;',
     '  try { parsed = JSON.parse(input.toString("utf8")); } catch { fail("stdin must contain exactly one JSON value"); }',
-    '  const native = validateNativeEventEnvelope(parsed, { canonicalEvent, nativeEvent, target });',
     '  const controller = new AbortController();',
     '  const signal = AbortSignal.any([controller.signal, AbortSignal.timeout(timeoutMs)]);',
-    '  const props = createCanonicalEventProps(canonicalEvent, native, target, nativeEvent, capabilityRevision, signal);',
-    '  const trace = createEventTracer({ execution: eventTraceExecution({ event: canonicalEvent, host: target, nativeEvent }) });',
-    '  const gate = await executeEventPreflight(preflight, {',
-    '    canonical: props.canonical,',
-    '    host: { name: target, nativeEvent },',
-    '    signal,',
-    '    terminal: { hostSurface: "hook", sharesTarget: false, stderr: { color: "none", kind: "none" }, stdout: { color: "none", kind: "none" } },',
-    '  }, trace);',
+    '  const { gate, native, projected, props, trace } = await prepareRouteInvocation(parsed, signal);',
     '  if (gate !== "execute") {',
-    '    const projected = projectEventPreflightResult(gate, canonicalEvent, target, nativeEvent, native);',
     '    if (projected !== undefined) process.stdout.write(JSON.stringify(projected));',
     '    return;',
     '  }',