feat(diagnostics): add independent runtime MCP verification with detailed failure attribution

[reachjalil]

What this does

Extends the Agent Context diagnostic so it can verify the configured openwork-cloud MCP endpoint independently of OpenCode, from the OpenWork runtime's own network stack, and then answer the differential question support actually needs:

• Did the independent Node/Bun runtime path reach the endpoint?
• What did OpenCode report for the same managed entry?
• If they disagree, which runtime boundary is implicated?
• At exactly which network or protocol stage did the independent probe fail?

The probe runs the complete bounded MCP handshake — initialize (with protocol-version validation), notifications/initialized, tools/list, and a bounded best-effort DELETE session cleanup. It never calls an MCP tool, never mutates configuration, never reconnects OpenCode, and never remints credentials.

Runtime transport is now explicit

apps/server/src/server-fetch.ts gains runtimeDiagnosticFetch and runtimeDiagnosticTransportInfo(). The probe reports runtimeFamily (electron-node | node | bun | unknown) and transport (node-undici | bun-fetch | test-seam | unknown), so a Bun standalone result is never claimed to have come from Node, and the deliberate Node/undici path inside Electron main is a named seam instead of an accidental ?? fetch fallback.

The bare-fetch guard test now flags bare fetch references, not just call sites, so input.fetchImpl ?? fetch can no longer bypass it. The sweep surfaced and fixed three more accidental fallbacks: opencode-models-url.ts (→ loopbackFetch), worker-activity-heartbeat.ts (→ externalFetch), and the engine-client default in server.ts (→ explicit globalThis.fetch).

Eligibility is decoupled from OpenCode state

Cached registration states (failed, needs-auth, needs-client-registration, not-recorded) and agent tool policy no longer gate the probe — the probe exists precisely to diagnose those situations. They are now comparison inputs and separate reported dimensions. A denied or unavailable tool policy is never reported as endpoint unavailability.

The probe still skips (as not-performed, stage eligibility) for: remote-workspace privacy, disabled MCP config, missing/malformed/duplicate credentials, invalid endpoints, untrusted origins, expired overall deadline, and probe-concurrency exhaustion.

Reviewer note (deliberate behavior change): the credentialed probe now runs in states where it previously did not (engine-failed registration, denied/unavailable tool policy). It remains bounded to explicit user-initiated diagnostics runs, local workspaces, the exact managed entry, and explicitly trusted origins only.

Trust boundary preserved; on-prem audit result

Only built-in OpenWork Cloud origins, exact administrator-configured origins (OPENWORK_AGENT_DIAGNOSTICS_TRUSTED_ORIGINS), and loopback may receive the credentialed request. Renderer/user-supplied URLs cannot widen this.

Audit: the enterprise/on-prem Den base origin (denBaseUrl) is provisioned desktop-side (desktop bootstrap / enterprise activation / connect-link claims in apps/desktop/electron/workspace-store.mjs) and is not visible to the server process, so the diagnostic cannot derive a trusted origin from it today. Per that result, untrusted_endpoint is reported as probe not performed (warning, stage eligibility) with an actionable admin-configuration explanation — explicitly not as a network/TLS/MCP failure. Plumbing the activation denBaseUrl into the server's trust list is left as a follow-up because the desktop runtime env wiring is owned by #3118's area (see overlap below).

Detailed failure attribution

Failures no longer collapse into network_error/invalid_response. The typed result includes performed, stage, code, networkCode, retryable, runtimeFamily, transport, httpStatus, durationMs, toolsListPerformed, sessionEstablished, cleanupAttempted, cleanupSucceeded, engineRegistrationStatus, engineEvidenceSource, engineEvidenceAgeMs, proxyConfigured/extraCaConfigured (booleans only), a strictly validated referenceId (x-request-id), aggregate catalog counts, and a bounded list of sanitized step summaries.

• Closed stage enum: eligibility, dns, connect, tls, proxy, initialize_request|_http|_protocol, initialized_notification, tools_list_request|_http|_protocol, catalog_validation, session_cleanup, complete.
• Closed network codes: ENOTFOUND, EAI_AGAIN, ECONNREFUSED, ECONNRESET, ETIMEDOUT, UND_ERR_CONNECT_TIMEOUT, four TLS-validation codes + ERR_TLS_CERT_ALTNAME_INVALID, PROXY_ERROR, UNKNOWN_NETWORK_ERROR.
• HTTP classes: 401 credential, 403 membership/scope/policy, 404 MCP route/deployment mismatch, 429 rate limit, 502/503/504 gateway, redirects rejected, bounded generic otherwise.
• Protocol classes: content-type, oversize, invalid UTF-8, invalid JSON, malformed JSON-RPC envelope, request-ID mismatch, JSON-RPC error, unsupported protocol version, invalid session header, invalid catalog, required tools missing, pagination unsupported.
• Retryability is derived deterministically from the closed sets (transient DNS, timeouts, resets, 429, 502-504, probe-busy → retryable; TLS validation, 401/403/404, protocol/catalog defects → not), never from raw message text.

Raw exception messages, cause objects, errno numbers, certificate subjects, paths, proxy values, response bodies, headers, and stack traces are never exported. Catalog validation is forward-compatible: extra provider tools no longer fail the check, but only the allowlisted expected IDs and aggregate counts are exported — provider-controlled names are never reflected.

Differential verdict

A new cloud-endpoint-differential check compares the runtime observation with the engine's cached registration evidence for the same entry: runtime_and_engine_connected, runtime_connected_engine_failed (implicates the engine-side path/lifecycle — endpoint is reachable), runtime_failed_engine_connected (implicates the OpenWork runtime network path — proxy/trust-store/DNS as seen by Node or Bun), runtime_and_engine_failed (shared outage), runtime_probe_not_performed, and engine_evidence_stale_or_unavailable (record missing, or a failure record older than 60s while the engine is reachable and could have refreshed it — mirroring the existing mcp_registration_stale_failure semantics; aged connected records are the engine's standing state and stay trusted so healthy steady-state runs do not warn).

Schema changes (server + shared types kept in exact sync)

• New check ID cloud-endpoint-differential (canonical position after cloud-tool-catalog); one new label key in the report page + en.ts.
• New safety field cloudSessionCleanupRequested disclosing the DELETE.
• The cloudCatalogToolsListPerformed cross-invariant no longer requires syncStatus === "connected" or a passed tool-policy check (those were the schema-level encoding of the removed gates); it still requires the retained runtime openwork-cloud entry with the /mcp/agent terminal path, proving which managed entry was probed.

The fail-closed redaction principles from #2997 are preserved: all new detail values pass the existing safe-text schema (no URLs, paths, or credential-shaped text), and eligibility/trust failures stay "no request occurred" states.

Overlap with open PRs (checked 2026-07-27)

• perf(startup): stop unnecessary engine disposes, unblock first load on restricted networks, add startup benchmark #3118 (perf/startup, open): identified as material overlap in planning. Its diff was inspected hunk-by-hunk: cloud-mcp-health.ts (pollConnected tracing), server.ts (reload-event stores + dispose avoidance), runtime.mjs/main.mjs (startup tracing + updater-manifest electronNet.fetch). This PR does not touch any of those regions — cloud-mcp-health.ts and all Electron files are untouched here, and the two-line server.ts change (engine-client fetch default) is far from its hunks. Based directly on dev; no stacking needed; none of its lifecycle/networking work is rewritten or absorbed. The on-prem trust plumbing follow-up should coordinate with its owner since it owns the runtime env wiring area.
• feat(context): add controllable OpenCode prompt observability #3029 (draft prompt observability): touches the same diagnostics modules broadly; this PR keeps its own changes additive and schema-mirrored so rebasing either direction stays mechanical.
• feat(connect): report desktop connection incidents #3074 (Connect incidents): adds a header passthrough inside readDirectCloudTools in cloud-mcp-health.ts — untouched here, no conflict.
• fix(mcp): redact provider payloads at diagnostic boundaries #2997 (Den diagnostic redaction): no file overlap; its fail-closed principles are preserved as described above.

Tests run

From apps/server (Bun 1.3.9; BUN_RUNTIME_TRANSPILER_CACHE_PATH=0 to avoid a pre-existing flaky node:sqlite transpiler-cache resolution on this machine):

• bun test (full package): 555 pass, 10 skip, 1 fail — the single failure is workspace-kv-store.node.test.ts failing to resolve node:sqlite under Bun; verified identical on the pristine base commit (git stash → same failure), unrelated to this change.
• bun test src/agent-context-cloud-probe.test.ts src/no-bare-fetch.test.ts — 29 pass.
• bun test src/agent-context-diagnostics.test.ts — 44 pass.
• bun test src/agent-context-diagnostics.schema.test.ts src/agent-context-diagnostics-local-schema.test.ts src/agent-context-diagnostics.plugin-label.test.ts src/agent-context-engine-inspection.test.ts src/opencode-models-url.test.ts — pass.
• bun test src/worker-activity-heartbeat.test.ts src/cloud-mcp-health.test.ts — 26 pass.
• npx tsc --noEmit in apps/server, packages/types, and apps/app — clean.

From apps/app: bun test tests/agent-context-diagnostics-report.test.tsx — 13 pass.

Validation limitations

No video/fraimz run is attached: this is a server-side diagnostic-evidence change whose only UI delta is one additional check row rendered by the existing generic check renderer (label added to en.ts). To reproduce end-to-end: run the desktop app with a connected OpenWork Cloud workspace, open Settings → Connect → Agent Context diagnostics, run diagnostics, and inspect the cloud-tool-catalog details (stage/networkCode/transport/steps) and the new Runtime probe vs engine verdict check; to see the differential in action, stop or break the engine registration (e.g. revoke Cloud auth) and rerun — the catalog check now still probes and the differential reports runtime_connected_engine_failed.

🤖 Generated with Claude Code

[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 27, 2026 6:42pm

[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.