@linzumi/cli 1.0.166 → 1.0.168

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linzumi/cli",
-  "version": "1.0.166",
+  "version": "1.0.168",
   "description": "Linzumi CLI \u2014 point a Codex agent at the real code on your laptop, with your team watching and steering from shared threads.",
   "type": "module",
   "bin": {

package/scripts/bump-cli-version.mjs

@@ -246,7 +246,21 @@ function scanTargets() {
     }
 
     for (const entry of entries) {
-      files.push(relative(packageRoot, entry));
+      const relativePath = relative(packageRoot, entry);
+
+      // Recorded agent-replay captures are FROZEN evidence (the same
+      // doctrine as the replay_harness corpus): a capture recorded while
+      // the CLI was at version X legitimately carries that version string
+      // in its recorded wire payloads forever, and the bump must neither
+      // rewrite it nor refuse because of it
+      // (spec/codex-wire-capture-replay.spec.md).
+      if (
+        relativePath.startsWith(join('test', 'fixtures', 'agent-raw-replay'))
+      ) {
+        continue;
+      }
+
+      files.push(relativePath);
     }
   }
 

package/scripts/codex-wire-replay-bin.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# Codex wire replay thin launcher (spec/codex-wire-capture-replay.spec.md).
+#
+# Point the commander's `--codex-bin` at this script to swap the real codex
+# engine for the wire replay server: same spawn contract (`--version`,
+# `login status`, `app-server ... --listen <ws-url>`), zero runner code
+# changes, no codex auth anywhere. The implementation is ReScript
+# (HarnessCodexWireReplayBinMain.res); this launcher only resolves the
+# compiled module beside this checkout and execs node on it - build first
+# with `npx rescript build packages/linzumi-cli-rescript` (the CLI test
+# script already does).
+#
+# Env (read by the bin): LINZUMI_WIRE_REPLAY_CAPTURE (required),
+# LINZUMI_WIRE_REPLAY_STRICTNESS, LINZUMI_WIRE_REPLAY_CLOCK,
+# LINZUMI_WIRE_REPLAY_REPORT.
+set -euo pipefail
+
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+bin_module="$here/../../linzumi-cli-rescript/src/harness/HarnessCodexWireReplayBinMain.res.mjs"
+
+if [[ ! -f "$bin_module" ]]; then
+  echo "codex-wire-replay-bin: compiled module missing at $bin_module - run: npx rescript build <repo>/packages/linzumi-cli-rescript" >&2
+  exit 66
+fi
+
+exec node "$bin_module" "$@"

package/scripts/replay-agent-backend.ts

@@ -61,8 +61,59 @@ type BackendReplayOptions = {
   readonly browserAuth: BackendReplayBrowserAuth | undefined;
   readonly requiredFeatureId: string | undefined;
   readonly oracleFeatureId: string | undefined;
+  // Wire replay mode (spec/codex-wire-capture-replay.spec.md): serve the
+  // fixture from the stub codex app-server websocket instead of the
+  // in-process provider-boundary client, so the runner's REAL socket
+  // machinery is exercised against the REAL backend.
+  readonly wire: boolean;
+  readonly wireStrictness: string | undefined;
 };
 
+type WireReplayServerHandle = {
+  readonly url: string;
+  readonly port: number;
+  readonly report: () => JsonObject;
+  readonly waitForCompletion: (timeoutMs: number) => Promise<boolean>;
+  readonly close: () => Promise<void>;
+};
+
+async function startWireReplayServerForFixture(
+  options: BackendReplayOptions
+): Promise<WireReplayServerHandle> {
+  // The implementation is ReScript (zero-TS/zero-raw-JS ratchets); the
+  // compiled module is loaded through a non-literal specifier so the type
+  // checker does not require declarations. The CLI test/build pipeline
+  // compiles the package (`rescript build ../linzumi-cli-rescript`).
+  const wireModulePath = new URL(
+    '../../linzumi-cli-rescript/src/harness/HarnessCodexWireReplay.res.mjs',
+    import.meta.url
+  ).href;
+  const wireModule = (await import(wireModulePath)) as {
+    startWireReplayServerJs: (serverOptions: {
+      readonly capturePath?: string;
+      readonly strictness?: string | undefined;
+      readonly clock?: string | undefined;
+    }) => Promise<WireReplayServerHandle>;
+    wireReplayClockForBackendSpeed: (
+      speed: string | undefined
+    ) => string | undefined;
+  };
+
+  // Translate the orchestrator's --speed grammar into the wire clock
+  // grammar (realtime -> recorded, <n>x passes through, <n>ms refuses
+  // loudly - it has no wire counterpart); property-pinned in
+  // test/agentReplayFixture.test.ts.
+  const wireClock = wireModule.wireReplayClockForBackendSpeed(options.speed);
+
+  return wireModule.startWireReplayServerJs({
+    capturePath: options.fixturePath,
+    ...(options.wireStrictness === undefined
+      ? {}
+      : { strictness: options.wireStrictness }),
+    ...(wireClock === undefined ? {} : { clock: wireClock }),
+  });
+}
+
 type BackendReplayBrowserAuth = {
   readonly accessToken: string;
   readonly refreshToken: string | undefined;
@@ -350,6 +401,8 @@ function parseArgs(args: readonly string[]): BackendReplayOptions {
     browserAuth: undefined,
     requiredFeatureId: argValue(args, '--require-feature'),
     oracleFeatureId: argValue(args, '--oracle-feature'),
+    wire: args.includes('--wire'),
+    wireStrictness: argValue(args, '--wire-strictness'),
   };
 }
 
@@ -753,24 +806,38 @@ async function runBackendReplay(
   }
 
   const runnerToken = await resolveBackendReplayToken(options);
-  const runner = await runLocalCodexRunner(
-    backendReplayRunnerOptions(options, provider, runnerToken)
-  );
+  const wireServer = options.wire
+    ? await startWireReplayServerForFixture(options)
+    : undefined;
 
   try {
-    const start = await startLocalCodexRunnerInstance(options, provider);
-    const oracles = await runBackendReplayOracles(options, start, provider);
+    const runner = await runLocalCodexRunner(
+      backendReplayRunnerOptions(
+        options,
+        provider,
+        runnerToken,
+        wireServer?.url
+      )
+    );
 
-    return {
-      runnerId: options.runnerId,
-      instanceId: runner.instanceId,
-      codexUrl: runner.codexUrl,
-      frontendTarget: frontendReplayTarget(options, start.threadId),
-      start,
-      oracles,
-    };
+    try {
+      const start = await startLocalCodexRunnerInstance(options, provider);
+      const oracles = await runBackendReplayOracles(options, start, provider);
+
+      return {
+        runnerId: options.runnerId,
+        instanceId: runner.instanceId,
+        codexUrl: runner.codexUrl,
+        frontendTarget: frontendReplayTarget(options, start.threadId),
+        start,
+        oracles,
+        ...(wireServer === undefined ? {} : { wire: wireServer.report() }),
+      };
+    } finally {
+      await runner.close();
+    }
   } finally {
-    await runner.close();
+    await wireServer?.close();
   }
 }
 
@@ -1357,7 +1424,8 @@ const backendReplayThreadOutputQuery = `
 function backendReplayRunnerOptions(
   options: BackendReplayOptions,
   provider: string,
-  token: string
+  token: string,
+  wireCodexUrl?: string | undefined
 ): RunnerOptions {
   return {
     kandanUrl: options.backendUrl ?? '',
@@ -1367,15 +1435,21 @@ function backendReplayRunnerOptions(
     workspaceSlug: options.workspace,
     cwd: options.cwd,
     codexBin: process.env.CODEX_BIN ?? 'codex',
-    codexUrl: undefined,
+    // Wire mode: the runner connects its REAL websocket client to the stub
+    // codex app-server through the same --codex-url seam it uses for a real
+    // pre-started codex, instead of substituting an in-process fake client.
+    codexUrl: wireCodexUrl,
     launchTui: false,
     allowedCwds: [options.cwd],
     channelSession: undefined,
-    agentReplay: {
-      fixturePath: options.fixturePath,
-      provider: options.provider,
-      clockMode: parseAgentReplayClockMode(options.speed),
-    },
+    agentReplay:
+      wireCodexUrl !== undefined
+        ? undefined
+        : {
+            fixturePath: options.fixturePath,
+            provider: options.provider,
+            clockMode: parseAgentReplayClockMode(options.speed),
+          },
   };
 }
 
@@ -1832,7 +1906,7 @@ function argValue(args: readonly string[], name: string): string | undefined {
 
 function printHelp(): void {
   process.stdout.write(
-    `Usage: pnpm run replay:agent-backend -- --fixture <path> [options]\n\nOptions:\n  --dry-run                         Validate fixture/manifest/diagnostics without backend connection\n  --probe-backend                   Also join the real Phoenix local_runner channel, then exit\n  --provider auto|codex|claude-code Replay provider. Default: auto\n  --speed immediate|realtime|<n>x|<n>ms\n                                      Replay speed. Default: immediate\n  --backend-url <url>               Local Phoenix backend URL; required by --probe-backend/replay\n  --setup-fixture                   Create a throwaway fixture user/workspace/channel first; requires local fixture registration\n  --setup-label <label>             Prefix for throwaway fixture setup. Default: agent-backend-replay\n  --workspace <slug>                Target workspace slug for session-token exchange and future replay\n  --channel <slug>                  Target channel slug for token scoping and future replay\n  --thread-id <id>                  Target thread id for the future backend replay slice\n  --runner-id <id>                  Local runner id for backend probing. Default: generated\n  --cwd <path>                      Cwd advertised in backend probe/replay. Default: current directory\n  --work-description <text>         Work description sent through the normal start mutation\n  --token <token>                   Local-runner token; also reads LINZUMI_AGENT_BACKEND_REPLAY_TOKEN\n  --session-token <token>           Browser/session token to exchange for a local-runner token; also reads LINZUMI_AGENT_BACKEND_REPLAY_SESSION_TOKEN\n  --out-dir <path>                  Artifact directory for summary.json. Default: agent-backend-replay-output\n  --require-feature <featureId>     Fail before backend setup unless manifest readiness says the feature is ready\n  --oracle-feature <featureId>      Run feature-specific backend oracles without using readiness as a preflight gate\n  --no-summary                      Do not write summary.json; stdout JSON is still printed\n\nExamples:\n  pnpm --filter @linzumi/cli run replay:agent-backend -- --fixture test/fixtures/agent-raw-replay/real-probe/claude.ndjson --provider claude-code --dry-run\n  pnpm --filter @linzumi/cli run replay:agent-backend -- --fixture test/fixtures/agent-raw-replay/real-probe/claude.ndjson --provider claude-code --probe-backend --backend-url http://127.0.0.1:4140 --workspace default --session-token <browser-session-token>\n  pnpm --filter @linzumi/cli run replay:agent-backend -- --fixture test/fixtures/agent-raw-replay/real-probe/claude.ndjson --provider claude-code --backend-url http://127.0.0.1:4140 --setup-fixture\n`
+    `Usage: pnpm run replay:agent-backend -- --fixture <path> [options]\n\nOptions:\n  --dry-run                         Validate fixture/manifest/diagnostics without backend connection\n  --probe-backend                   Also join the real Phoenix local_runner channel, then exit\n  --provider auto|codex|claude-code Replay provider. Default: auto\n  --speed immediate|realtime|<n>x|<n>ms\n                                      Replay speed. Default: immediate\n  --backend-url <url>               Local Phoenix backend URL; required by --probe-backend/replay\n  --setup-fixture                   Create a throwaway fixture user/workspace/channel first; requires local fixture registration\n  --setup-label <label>             Prefix for throwaway fixture setup. Default: agent-backend-replay\n  --workspace <slug>                Target workspace slug for session-token exchange and future replay\n  --channel <slug>                  Target channel slug for token scoping and future replay\n  --thread-id <id>                  Target thread id for the future backend replay slice\n  --runner-id <id>                  Local runner id for backend probing. Default: generated\n  --cwd <path>                      Cwd advertised in backend probe/replay. Default: current directory\n  --work-description <text>         Work description sent through the normal start mutation\n  --token <token>                   Local-runner token; also reads LINZUMI_AGENT_BACKEND_REPLAY_TOKEN\n  --session-token <token>           Browser/session token to exchange for a local-runner token; also reads LINZUMI_AGENT_BACKEND_REPLAY_SESSION_TOKEN\n  --out-dir <path>                  Artifact directory for summary.json. Default: agent-backend-replay-output\n  --wire                            Serve the fixture from the stub codex app-server websocket (spec/codex-wire-capture-replay.spec.md) so the runner's real socket machinery is exercised\n  --wire-strictness shape|exact     Wire mode validation of runner-sent packets against the recording. Default: shape\n  --require-feature <featureId>     Fail before backend setup unless manifest readiness says the feature is ready\n  --oracle-feature <featureId>      Run feature-specific backend oracles without using readiness as a preflight gate\n  --no-summary                      Do not write summary.json; stdout JSON is still printed\n\nExamples:\n  pnpm --filter @linzumi/cli run replay:agent-backend -- --fixture test/fixtures/agent-raw-replay/real-probe/claude.ndjson --provider claude-code --dry-run\n  pnpm --filter @linzumi/cli run replay:agent-backend -- --fixture test/fixtures/agent-raw-replay/real-probe/claude.ndjson --provider claude-code --probe-backend --backend-url http://127.0.0.1:4140 --workspace default --session-token <browser-session-token>\n  pnpm --filter @linzumi/cli run replay:agent-backend -- --fixture test/fixtures/agent-raw-replay/real-probe/claude.ndjson --provider claude-code --backend-url http://127.0.0.1:4140 --setup-fixture\n`
   );
 }