CLI/MCP calls join the run's distributed-trace ledger

The web app's HttpClient sends a traceparent on its own, but mcporter's
plain fetch does not — so the terminal half of a session was invisible
in traces.json. The MCP surface now wraps the global fetch: every POST
to the target's MCP endpoint gets a minted traceparent (the worker and
DO already join whatever arrives) and lands in the ledger with the
JSON-RPC method or tool name as its label, duration, status, and
source: terminal. traces.json becomes a shared append-merge ledger
(src/trace-harvest.ts) so the browser surface's harvested entries and
the MCP surface's minted ones interleave by wall clock, and the trace
rail tags each row with its window (⌨ terminal / ⊕ browser).

Author: RhysSullivan

apps/cloud/vite.config.ts

@@ -20,10 +20,7 @@ const devCrashGuard = (): Plugin => {
     if (installed) return;
     installed = true;
     process.on("uncaughtException", (err, origin) => {
-      console.error(
-        `[dev-crash-guard] uncaughtException (origin=${origin}):`,
-        err,
-      );
+      console.error(`[dev-crash-guard] uncaughtException (origin=${origin}):`, err);
     });
     process.on("unhandledRejection", (reason, promise) => {
       console.error("[dev-crash-guard] unhandledRejection:", reason, promise);
@@ -42,9 +39,7 @@ const loadWranglerPublicVars = () => {
     { hideWarnings: true },
   );
   return Object.fromEntries(
-    Object.entries(wranglerConfig.vars ?? {}).filter(([key]) =>
-      key.startsWith("VITE_PUBLIC_"),
-    ),
+    Object.entries(wranglerConfig.vars ?? {}).filter(([key]) => key.startsWith("VITE_PUBLIC_")),
   );
 };
 
@@ -66,10 +61,7 @@ export default defineConfig(({ mode }) => {
     define: Object.fromEntries(
       Object.entries(publicEnv)
         .filter(([key]) => key.startsWith("VITE_PUBLIC_"))
-        .map(([key, value]) => [
-          `import.meta.env.${key}`,
-          JSON.stringify(value),
-        ]),
+        .map(([key, value]) => [`import.meta.env.${key}`, JSON.stringify(value)]),
     ),
     // Browser OTLP spans (VITE_PUBLIC_OTLP_TRACES_URL=/v1/traces, set by the
     // e2e global setup) go same-origin and proxy to the local motel server —
@@ -98,11 +90,7 @@ export default defineConfig(({ mode }) => {
           virtualRouteConfig: rootRoute("__root.tsx", [
             ...consoleRoutes({
               dir: "../../../../packages/react/src/routes",
-              exclude: [
-                "/secrets",
-                "/resume/$executionId",
-                "/plugins/$pluginId/$",
-              ],
+              exclude: ["/secrets", "/resume/$executionId", "/plugins/$pluginId/$"],
             }),
             physical("", "app"),
           ]),

e2e/package.json

@@ -14,7 +14,7 @@
     "viewer:build": "bun scripts/rebuild-viewer.ts",
     "serve": "bun scripts/rebuild-viewer.ts && bun scripts/serve.ts",
     "typecheck": "tsc --noEmit",
-"test:desktop": "vitest run --project desktop",
+    "test:desktop": "vitest run --project desktop",
     "motel": "MOTEL_OTEL_BASE_URL=http://127.0.0.1:4796 MOTEL_OTEL_DB_PATH=runs/.motel/telemetry.sqlite motel server"
   },
   "dependencies": {

e2e/setup/cloud.boot.ts

@@ -12,9 +12,7 @@ import { createEmulator } from "@executor-js/emulate";
 
 import { bootProcesses, waitForHttp } from "./boot";
 
-export const cloudDir = fileURLToPath(
-  new URL("../../apps/cloud/", import.meta.url),
-);
+export const cloudDir = fileURLToPath(new URL("../../apps/cloud/", import.meta.url));
 
 export interface CloudBootOptions {
   readonly cloudPort: number;
@@ -48,9 +46,7 @@ export interface CloudBooted {
   readonly autumnUrl: string;
 }
 
-export const bootCloud = async (
-  options: CloudBootOptions,
-): Promise<CloudBooted> => {
+export const bootCloud = async (options: CloudBootOptions): Promise<CloudBooted> => {
   // Fresh dev DB per boot — the WorkOS emulator mints org ids from a
   // per-process counter, so a persisted DB from a previous invocation
   // collides with the new boot's ids (identities land in polluted orgs /
@@ -81,8 +77,7 @@ export const bootCloud = async (
     WORKOS_CLIENT_ID: options.workosClientId,
     WORKOS_COOKIE_PASSWORD: options.cookiePassword,
     AUTUMN_SECRET_KEY: "am_test_emulate",
-    ENCRYPTION_KEY:
-      "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+    ENCRYPTION_KEY: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
     DATABASE_URL: `postgresql://postgres:postgres@127.0.0.1:${options.dbPort}/postgres`,
     EXECUTOR_DIRECT_DATABASE_URL: "true",
     CLOUDFLARE_INCLUDE_PROCESS_ENV: "true",

e2e/src/scenario.ts

@@ -58,7 +58,7 @@ const contextFor = (target: TargetShape, dir: string): Context.Context<AllServic
   const has = target.capabilities.has.bind(target.capabilities);
   if (has("api")) context = Context.add(context, Api, makeApiSurface(target));
   if (has("browser")) context = Context.add(context, Browser, makeBrowserSurface(dir, target));
-  if (has("mcp-oauth")) context = Context.add(context, Mcp, makeMcpSurface(target));
+  if (has("mcp-oauth")) context = Context.add(context, Mcp, makeMcpSurface(target, dir));
   if (has("billing")) context = Context.add(context, Billing, true);
   if (hasOpenCode()) {
     context = Context.add(context, OpenCode, {
@@ -218,7 +218,11 @@ const extractScenarioSource = (filePath: string, name: string): string | undefin
         }
       }
       if (end === -1) return undefined; // unbalanced — bail to be safe
-      blocks.push({ start: index, end, mine: source.slice(index, end).includes(`"${name}"`) });
+      blocks.push({
+        start: index,
+        end,
+        mine: source.slice(index, end).includes(`"${name}"`),
+      });
       index = end;
     }
     if (!blocks.some((b) => b.mine)) return undefined;

e2e/src/surfaces/browser.ts

@@ -4,14 +4,15 @@
 // everywhere), per-step screenshots, and a failure screenshot. The scenario
 // drives `page` directly; assertions are vitest's job.
 import { execFile } from "node:child_process";
-import { copyFileSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { copyFileSync, mkdirSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { promisify } from "node:util";
 
 import { Effect } from "effect";
 import { chromium, type Page } from "playwright";
 
 import { markFocus, markRecordingStart } from "../timeline";
+import { appendTraces, type TraceEntry } from "../trace-harvest";
 import type { Identity, Target } from "../target";
 
 export interface BrowserSession {
@@ -60,10 +61,17 @@ export const makeBrowserSurface = (dir: string, target: Target): BrowserSurface
           recordVideo: { dir: videoTmp, size: { width: 1280, height: 800 } },
           baseURL: target.baseUrl,
         });
-        await context.tracing.start({ screenshots: true, snapshots: true, sources: true });
+        await context.tracing.start({
+          screenshots: true,
+          snapshots: true,
+          sources: true,
+        });
         if (identity.cookies?.length) {
           await context.addCookies(
-            identity.cookies.map((cookie) => ({ ...cookie, url: target.baseUrl })),
+            identity.cookies.map((cookie) => ({
+              ...cookie,
+              url: target.baseUrl,
+            })),
           );
         }
         const page = await context.newPage();
@@ -73,17 +81,48 @@ export const makeBrowserSurface = (dir: string, target: Target): BrowserSurface
         // Harvest distributed-trace ids: every app API request carries a W3C
         // traceparent (Effect's HttpClient), and each id names one
         // click→server→DB trace in whatever OTLP store the run exported to
-        // (motel locally). Written to traces.json so the runs viewer can
-        // link a recording to its traces.
-        const traceIds: { id: string; at: number; url: string }[] = [];
+        // (motel locally). Appended to traces.json (shared with the MCP
+        // surface's terminal-side entries) so the runs viewer can link a
+        // recording to its traces. Duration comes from the finished/failed
+        // event so the viewer can answer "why did that take so long"
+        // without leaving the run page.
+        const traceIds: Array<TraceEntry & { ms?: number; status?: number }> = [];
+        const inflight = new Map<unknown, (typeof traceIds)[number]>();
         page.on("request", (request) => {
           const traceparent = request.headers()["traceparent"];
           const match = traceparent ? /^[0-9a-f]{2}-([0-9a-f]{32})-/.exec(traceparent) : null;
           if (match?.[1]) {
-            traceIds.push({ id: match[1], at: Date.now(), url: request.url() });
+            const entry: (typeof traceIds)[number] = {
+              id: match[1],
+              at: Date.now(),
+              url: request.url(),
+              source: "browser",
+            };
+            traceIds.push(entry);
+            inflight.set(request, entry);
           }
         });
-        return { browser, context, page, videoTmp, shots: { count: 0 }, traceIds };
+        page.on("requestfinished", async (request) => {
+          const entry = inflight.get(request);
+          if (!entry) return;
+          inflight.delete(request);
+          entry.ms = Date.now() - entry.at;
+          entry.status = (await request.response().catch(() => null))?.status();
+        });
+        page.on("requestfailed", (request) => {
+          const entry = inflight.get(request);
+          if (!entry) return;
+          inflight.delete(request);
+          entry.ms = Date.now() - entry.at;
+        });
+        return {
+          browser,
+          context,
+          page,
+          videoTmp,
+          shots: { count: 0 },
+          traceIds,
+        };
       }),
       ({ page, context, shots }) =>
         Effect.promise(async () => {
@@ -110,9 +149,7 @@ export const makeBrowserSurface = (dir: string, target: Target): BrowserSurface
         }),
       ({ browser, context, page, videoTmp, traceIds }) =>
         Effect.promise(async () => {
-          if (traceIds.length > 0) {
-            writeFileSync(join(dir, "traces.json"), JSON.stringify(traceIds, null, 1));
-          }
+          appendTraces(dir, traceIds);
           await context.tracing.stop({ path: join(dir, "trace.zip") }).catch(() => {});
           const video = page.video();
           await context.close(); // flushes the recording

e2e/src/surfaces/mcp.ts

@@ -11,8 +11,83 @@ import { Effect } from "effect";
 
 import { createRuntime, type Runtime } from "@executor-js/mcporter";
 
+import { appendTraces } from "../trace-harvest";
 import type { Identity, Target } from "../target";
 
+// ---------------------------------------------------------------------------
+// Distributed traces for MCP calls. The web app's HttpClient sends a W3C
+// traceparent on its own; mcporter's plain fetch does not — so the agent/CLI
+// side of a session was invisible in the run's trace ledger. mcporter rides
+// the global fetch, so the surface wraps it once per process: every POST to
+// the target's MCP endpoint gets a freshly minted traceparent (the server
+// joins whatever arrives — worker and DO both parse the header), and the
+// request lands in traces.json with the JSON-RPC method as its label,
+// duration, status, and source: "terminal".
+// ---------------------------------------------------------------------------
+
+let traceFetchInstalled = false;
+let traceSink: { mcpUrl: string; runDir: string } | null = null;
+
+/** JSON-RPC body → a human label: tool name for tools/call, else method. */
+const rpcLabel = (body: unknown): string | undefined => {
+  if (typeof body !== "string") return undefined;
+  try {
+    const parsed = JSON.parse(body) as {
+      method?: string;
+      params?: { name?: string };
+    };
+    if (!parsed.method) return undefined;
+    return parsed.method === "tools/call" && parsed.params?.name
+      ? `${parsed.params.name}()`
+      : parsed.method;
+  } catch {
+    return undefined;
+  }
+};
+
+const installTraceparentFetch = (mcpUrl: string, runDir: string): void => {
+  traceSink = { mcpUrl, runDir };
+  if (traceFetchInstalled) return;
+  traceFetchInstalled = true;
+  const original = globalThis.fetch;
+  globalThis.fetch = async (input, init) => {
+    const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    const method = (
+      init?.method ?? (input instanceof Request ? input.method : "GET")
+    ).toUpperCase();
+    const sink = traceSink;
+    if (!sink || method !== "POST" || !url.startsWith(sink.mcpUrl)) {
+      return original(input, init);
+    }
+    const traceId = randomBytes(16).toString("hex");
+    const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : {}));
+    headers.set("traceparent", `00-${traceId}-${randomBytes(8).toString("hex")}-01`);
+    const at = Date.now();
+    const finish = (status?: number) =>
+      appendTraces(sink.runDir, [
+        {
+          id: traceId,
+          at,
+          url,
+          ms: Date.now() - at,
+          ...(status === undefined ? {} : { status }),
+          source: "terminal" as const,
+          label: rpcLabel(init?.body),
+        },
+      ]);
+    try {
+      const response = await original(input, { ...init, headers });
+      finish(response.status);
+      return response;
+      // oxlint-disable-next-line executor/no-try-catch-or-throw -- fetch adapter boundary
+    } catch (error) {
+      finish();
+      // oxlint-disable-next-line executor/no-try-catch-or-throw -- fetch adapter boundary
+      throw error;
+    }
+  };
+};
+
 export interface McpCallResult {
   readonly raw: unknown;
   readonly text: string;
@@ -128,10 +203,11 @@ const mintBearerFlow = async (target: Target, email: string): Promise<string> =>
   return token.access_token;
 };
 
-export const makeMcpSurface = (target: Target): McpSurface => ({
+export const makeMcpSurface = (target: Target, runDir?: string): McpSurface => ({
   url: target.mcpUrl,
   mintBearer: (email) => Effect.promise(() => mintBearerFlow(target, email)),
   session: (identity) => {
+    if (runDir) installTraceparentFetch(target.mcpUrl, runDir);
     const serverName = target.name;
     let runtimePromise: Promise<Runtime> | undefined;
     let connected = false;

e2e/src/trace-harvest.ts

@@ -0,0 +1,36 @@
+// The run's distributed-trace ledger (traces.json): every request the
+// session made against the target, with the trace id that names its
+// click→server→DB waterfall in the OTLP store the run exported to.
+//
+// Two writers share it — the browser surface (ids harvested off the wire,
+// the web app sends traceparent itself) and the MCP surface (ids MINTED
+// here, since mcporter's plain fetch sends none; the server joins whatever
+// traceparent arrives). Append is read-merge-write so neither clobbers the
+// other; entries stay sorted by wall clock.
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export interface TraceEntry {
+  readonly id: string;
+  readonly at: number;
+  readonly url: string;
+  readonly ms?: number;
+  readonly status?: number;
+  /** Which window made the request — the viewer's rail tags rows with it. */
+  readonly source?: "terminal" | "browser";
+  /** Readable name when the URL alone says nothing (MCP: every call POSTs
+   *  the same endpoint; the JSON-RPC method/tool is the real identity). */
+  readonly label?: string;
+}
+
+const fileFor = (runDir: string) => join(runDir, "traces.json");
+
+export const appendTraces = (runDir: string, entries: ReadonlyArray<TraceEntry>): void => {
+  if (entries.length === 0) return;
+  const file = fileFor(runDir);
+  const existing: TraceEntry[] = existsSync(file)
+    ? (JSON.parse(readFileSync(file, "utf8")) as TraceEntry[])
+    : [];
+  const merged = [...existing, ...entries].sort((a, b) => a.at - b.at);
+  writeFileSync(file, JSON.stringify(merged, null, 1));
+};