feat(diagnostics): add Connect debug proxy

[reachjalil]

Summary

• add an access-gated Connect debug proxy to the existing Vercel-native diagnostics app
• forward the complete custom-Den path while preserving auth/cookies, streaming SSE and chunked responses, rewriting redirects/absolute and URL-encoded upstream URLs, and retaining the selected proxy through the desktop handoff
• keep root-relative Den web assets and API calls on the scenario during browser sign-in with a short-lived HTTP-only routing cookie that is stripped before upstream forwarding
• provide stateless URL-selected fault scenarios, allowlisted encoded upstream overrides, MCP-aware JSON/SSE tampering, and a redacted per-instance request ring
• document the exact desktop Developer mode and Cloud control plane URL workflow, credential boundaries, deployment, and recovery steps

This is a standalone diagnostics deployable. It does not modify Den API/Web, the OpenWork server, desktop, or OpenCode.

Related to #2975.

Scenario → expected diagnostics

Scenario	Injected behavior	Expected OpenWork result
default	Pure pass-through	Agent access reaches ready; no firstFailure; initialize and tools/list succeed
auth-expired	Agent endpoint returns 401 + WWW-Authenticate invalid token	engine_needs_auth / invalid_mcp_token; initialize trace shows HTTP 401
forbidden	Agent endpoint returns 403	engine_needs_auth / wrong_mcp_resource; initialize trace shows HTTP 403
down	Agent endpoint returns 502	Engine failure with upstream/fetch detail; initialize trace shows HTTP 502
den-outage	Every proxied Den route returns 503	Sign-in/token mint unavailable; Agent access cannot be established
slow	Agent endpoint waits configured 5–10 seconds	Slow probe steps; timeout outcome follows the caller deadline
hang	Agent endpoint remains pending until caller/function timeout	Engine fetch/timeout failure; direct probe records timeout/transport evidence
flaky-3	First three Agent requests per instance/window return 502	Transient engine/probe failure, then recovery after the failure count is exhausted
missing-tools	tools/list removes execute_capability in JSON and SSE	cloud_tools_missing / cloud_tools_missing; tools_list succeeds with missing tool evidence
bad-protocol	Initialize body and protocol header report 1900-01-01	Engine protocol failure; Advanced initialize trace exposes the unsupported version
corrupt	Agent endpoint returns invalid JSON	Engine parse/protocol failure; initialize/tools_list cannot be parsed
token-mint-fail	Only /v1/mcp/token and current /api/den/v1/mcp/token return 503	Sign-in remains usable; Repair and test reports cloud_mcp_token_mint_failed before engine delivery

Authentication and routing

• paste a generated scenario URL into Settings → Cloud → Account → Cloud control plane URL after enabling Settings → Advanced → Developer mode; it is a Den base URL, not a manual MCP entry
• DEBUG_PROXY_ACCESS_KEY authorizes proxy use, is consumed from the generated URL path, and is never forwarded to Den
• saving a different base signs the desktop out; browser sign-in, the one-time handoff grant, Den session bearer, token mint, and managed openwork-cloud MCP traffic then traverse the selected scenario
• the minted MCP resource and URL-encoded openwork://den-auth base are rewritten to the scenario URL so the desktop does not switch back to the upstream origin
• provider OAuth credentials remain encrypted in Den and do not enter the desktop or engine

Security and operations

• DEBUG_PROXY_ALLOWED_UPSTREAMS is enforced on decoded override hosts; non-HTTPS overrides are rejected except explicit loopback development origins
• the browser routing cookie is HTTP-only, expires after ten minutes, carries the same access-key path already present in the URL, and is stripped before upstream forwarding
• the app log never retains Authorization, cookies, query values, bodies, or raw upstream errors
• real Den credentials still transit the proxy; use staging/dev Den by default and treat generated URLs as secrets
• flaky-N counters and the 100-row log are intentionally best-effort per Vercel instance

Checks

• pnpm --filter @openwork-ee/diagnostics test — passed, 46 tests
• pnpm --filter @openwork-ee/diagnostics build — passed; Next production build recognizes the control, catch-all, and Proxy routes
• pnpm --filter @openwork-ee/diagnostics smoke:debug-proxy — passed against a spawned mock Den; verified Den HTML bootstrap, root-relative /_next routing, root-relative /api/den desktop handoff, encoded base rewrite, routing-cookie removal, default MCP initialize/tools-list pass-through, auth-expired 401, and missing-tools tampering

Manual/live verification

• Agent-observed local route journey: passed through the smoke above.
• Not run — live Vercel deployment with production project environment variables.
• Not run — real dev desktop sign-in/Ready, scenario switching, Advanced trace, and Repair and test recovery. These require a deployed preview plus an approved staging/dev Den and real user credentials.
• Not run — screenshots/video; the draft keeps live credential-bearing verification pending for the reviewer/developer environment.

Deployment and exact desktop recovery steps are documented in ee/apps/diagnostics/README.md.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
openwork-landing	Ready	Preview, Comment, Open in v0	Jul 22, 2026 6:58am

[vercel]

@reachjalil is attempting to deploy a commit to the Different AI Team on Vercel.

A member of the Team first needs to authorize it.