[v3 backport] Implement tail-based logging for realish preview

[devin-ai-integration]

Backport of #11135 to v3-maintenance branch.

This PR implements tail-based logging for wrangler dev --remote sessions behind the --x-tail-logs experimental flag. Instead of using the Chrome DevTools Protocol inspector for logs, this creates a tail consumer WebSocket connection to receive runtime logs, similar to wrangler tail.

Changes Overview

Core tail logging implementation:

• Added --experimental-tail-logs (alias --x-tail-logs) flag to wrangler dev
• Modified createPreviewSession() to conditionally skip inspector URL creation when tail logs are enabled
• Made inspectorUrl optional in CfPreviewToken and CfPreviewSession types
• Added tailUrl to preview token response
• Implemented tail-based log streaming in RemoteRuntimeController using WebSocket
• Added simplified realishPrintLogs() for printing tail messages (compared to the full prettyPrintLogs() used in wrangler tail)
• Disabled devtools hotkey when tail logs are enabled

v3-maintenance compatibility fixes:

• Added tailConsumers: TailConsumer[] property to StartDevWorkerOptions type
• Made userWorkerInspectorUrl optional in ProxyData type
• Fixed inspector type checks (v3 doesn't support inspector: false string value, only boolean or object)
• Added REALISH_TAIL_LOGS to experimental flags in all 7 command initialization points
• Updated test configuration helpers to include tailConsumers: []
• Fixed optional inspector URL handling in tests using assert() instead of non-null assertion
• Added CLOUDFLARE_ACCOUNT_ID global type declaration for e2e tests

Test modifications:

• Relaxed error message expectations in e2e tests (looking for "monkey" instead of full error details with stack traces, since tail logs don't include source maps)
• Skipped inspector test for remote runtime (inspector not available when using tail logs)
• Added workaround comment for EWC bug requiring bindings for remote dev workers to log properly

Human Review Checklist

Critical items:

1. 🚨 Runtime testing required: This PR was validated with pnpm check and pnpm fix but was NOT runtime tested with actual wrangler dev --remote --x-tail-logs. This should be tested in a real v3 environment before merging to verify:

   • Tail logs are received and printed correctly
   • No inspector errors when inspector is disabled
   • Proper fallback when tail URL is not available
   • WebSocket cleanup on errors and teardown

2. Optional inspector URL: Verify that making inspectorUrl optional doesn't break existing code paths:

   • ProxyController event emission handles undefined inspector URL correctly
   • Devtools hotkey is properly disabled when tail logs are enabled (line in hotkeys.ts)
   • Tests properly handle undefined inspector URLs with assert() statements

3. Type compatibility changes: Review the TypeScript fixes made for v3-maintenance:

   • Is keeping switchedExchangeUrl as URL object (instead of string) correct for v3?
   • Are the inspector type check changes (typeof config.inspector !== "object") safe for all v3 code paths?
   • Does v3 actually not support inspector: false string value?

4. WebSocket lifecycle: Verify the tail WebSocket is properly cleaned up:

   • this.#activeTail?.terminate() is called in teardown and before creating new preview
   • Abort signal is passed to WebSocket constructor
   • Error handling for WebSocket connection failures

5. Experimental flags coverage: Verify all 7 locations where experimental flags are initialized include REALISH_TAIL_LOGS: false:

   • ✅ core/register-yargs-command.ts
   • ✅ deploy/index.ts
   • ✅ dev.ts
   • ✅ pages/dev.ts
   • ✅ versions/upload.ts
   • ✅ api/integrations/platform/index.ts
   • ✅ configuration.test.ts (3 locations)

6. Test expectation changes: The e2e tests now only check for "monkey" in error messages instead of full error details with stack traces. Is this acceptable for tail-based logs? Should we document this limitation?

7. CI expectation: The "v3 Maintenance / Is original PR merged" CI check will fail until PR Implement tail-based logging for realish preview #11135 is merged to main. This is expected and should be ignored until the original PR merges.

---

Link to Devin run: https://app.devin.ai/sessions/de6e732841fc4f8ab637b03d5efd847e

Requested by: smacleod@cloudflare.com

• Tests
  • Tests included (inherited from original PR Implement tail-based logging for realish preview #11135)
  • Additional test fixes for v3-maintenance compatibility
• Wrangler E2E Tests CI Job required?
  • Required - should test with --x-tail-logs flag in remote mode
• Public documentation
  • Documentation not necessary because: experimental feature behind flag, v3 backport
• Wrangler V3 Backport
  • This IS the v3 backport of PR Implement tail-based logging for realish preview #11135

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[changeset-bot]

🦋 Changeset detected

Latest commit: 4ae576a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
wrangler	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR