How to Troubleshoot OpenWork Agent-Context Connectivity and Egress Issues

OpenWork diagnoses agent-context connectivity and egress problems through a layered Agent-Context Diagnostics system that performs three independent checks—Cloud Catalog Probe, Cloud-Endpoint Transport Probe, and Differential Runtime-Engine Check—to isolate network, TLS, and registration failures.

When your OpenWork client cannot reach the OpenWork Cloud MCP or local engines fail to register, you need systematic visibility into where the chain breaks. The different-ai/openwork repository implements a comprehensive diagnostics stack exposed via the POST /workspace/:id/diagnostics/agent-context endpoint in apps/server/src/agent-context-diagnostics.ts. This system returns a unified report that distinguishes between egress proxy blocks, certificate validation errors, catalog mismatches, and engine lifecycle issues.

Understanding the Three-Layer Diagnostic Architecture

The Agent-Context Diagnostics engine performs three independent probes that run inside the runtime (the OpenWork process executing the workspace). Each layer targets a specific failure domain.

Layer 1: Cloud Catalog Probe

The Cloud Catalog Probe retrieves the OpenWork Cloud catalog and validates that required tools—specifically search_capabilities and execute_capability—are present. This check runs via a network request from the runtime to the Cloud endpoint.

If this probe fails with HTTP 401 or 403, the stored credential lacks permission or the organization connection is invalid. A HTTP 451 response indicates an egress proxy or firewall block. A cloud_catalog_mismatch status means the catalog structure does not match the expected schema, requiring a refresh from Settings → Connect.

Layer 2: Cloud-Endpoint Transport Probe

Before transmitting credentials, the runtime performs a credential-free TLS handshake against the Cloud MCP /mcp/agent endpoint. This Cloud-Endpoint Transport Probe validates TLS 1.2 and TLS 1.3 connectivity.

Common failure codes include:

• tls_incomplete_chain — Intermediate certificate missing from the server chain.
• tls_untrusted_ca — Corporate TLS inspection root not trusted by the runtime.
• timeout during TLS 1.3 — Egress proxy stalls the handshake.

To resolve CA issues, append the corporate root certificate to NODE_EXTRA_CA_CERTS or disable inspection for *.openwork.dev.

Layer 3: Differential Runtime-Engine Check

The Differential Check compares the transport probe result against the engine snapshot—the merged configuration that the engine reports about its own reachability. This identifies split-brain scenarios where the runtime can reach the Cloud but the engine cannot, or vice versa.

A status of engine_evidence_stale_or_unavailable indicates the engine has not recorded fresh registration evidence, typically resolved by restarting the workspace engine.

Diagnosing Common Connectivity and Egress Failures

The diagnostics report aggregates findings from agent-context-cloud-probe.ts, agent-context-transport-probe.ts, and agent-context-engine-inspection.ts into actionable entries with status, owner, and action fields.

Network and Egress Proxy Blocks

When the transport probe returns tls_error or timeout statuses, verify DNS resolution and firewall egress rules. If your corporate proxy intercepts TLS, ensure the proxy root is trusted or bypassed for OpenWork domains. The OPENWORK_AGENT_DIAGNOSTICS_TRUSTED_ORIGINS environment variable can whitelist on-prem Den installations.

Cloud Catalog Mismatches

If the probe reports cloud_catalog_mismatch, re-connect OpenWork Cloud from Settings → Connect to refresh the local catalog cache. If the error persists, contact OpenWork support to verify the canonical Cloud catalog state.

Stale Engine Registration

When the differential check shows the runtime reachable but the engine unreachable, restart the selected workspace engine. Run openwork engine start for the specific workspace or stop/start the OpenWork server process to generate fresh registration evidence in the engine snapshot.

Credential and Permission Errors

HTTP 401 (unauthorized) or 403 (forbidden) from the catalog probe indicates token expiration or scope mismatch. Re-authenticate via Settings → Connect and confirm the account belongs to the correct organization with required MCP scopes.

MCP Endpoint Misconfiguration

Errors like invalid_endpoint or untrusted_endpoint suggest the Cloud MCP URL is malformed. Verify in Settings → Connect that the endpoint uses https:// and ends with /mcp/agent. For on-prem deployments, ensure the origin is added to OPENWORK_AGENT_DIAGNOSTICS_TRUSTED_ORIGINS.

Running Agent-Context Diagnostics Programmatically

You can trigger the diagnostics endpoint from custom clients to monitor connectivity health.

Web Client Implementation

import { fetch } from "node-fetch";

async function runDiagnostics(workspaceId: string, baseUrl: string, bearer: string) {
  const url = `${baseUrl}/workspace/${encodeURIComponent(workspaceId)}/diagnostics/agent-context`;
  const response = await fetch(url, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${bearer}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      // Optional: request specific probes via schema defined in agent-context-diagnostics-request-schema.ts
    }),
  });

  if (!response.ok) throw new Error(`Diagnostics request failed: ${response.status}`);
  const report = await response.json();
  
  // report.checks contains entries with id, status, owner, and action
  console.log("Diagnostics report:", report);
}

React UI Integration

import { useEffect, useState } from "react";
import { fetchAgentContextDiagnosticsResponse } from "@/app/lib/agent-context-diagnostics";

export function AgentContextDiagnosticsReport({ workspaceId }: { workspaceId: string }) {
  const [report, setReport] = useState<AgentContextDiagnosticsReport | null>(null);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    fetchAgentContextDiagnosticsResponse(workspaceId)
      .then(setReport)
      .catch((e) => setError(e.message));
  }, [workspaceId]);

  if (error) return <div className="text-red-600">⚠️ {error}</div>;
  if (!report) return <div className="animate-pulse">Loading…</div>;

  return (
    <ul className="space-y-2">
      {report.checks.map((c) => (
        <li key={c.id} className={c.status === "failed" ? "text-red-600" : "text-green-600"}>
          <strong>{c.id}</strong>: {c.message}
          {c.action && <p className="ml-4">{c.action}</p>}
        </li>
      ))}
    </ul>
  );
}

The desktop client wraps this logic in apps/desktop/electron/agent-context-diagnostics-fetch.mjs, validated by the test suite in agent-context-diagnostics-fetch.test.mjs.

Core Implementation Files in the OpenWork Repository

The diagnostics stack spans server, client, and type definitions:

• apps/server/src/agent-context-diagnostics.ts — Main endpoint implementation that assembles the full report.
• apps/server/src/agent-context-diagnostics-schema.ts — Zod schemas for request and response validation.
• apps/server/src/agent-context-cloud-probe.ts — Catalog retrieval and tool validation logic.
• apps/server/src/agent-context-transport-probe.ts — TLS handshake execution and error classification.
• apps/server/src/agent-context-engine-inspection.ts — Engine snapshot reading and differential comparison.
• apps/desktop/electron/agent-context-diagnostics-fetch.mjs — Desktop client helper for server communication.
• apps/app/src/react-app/domains/settings/pages/agent-context-diagnostics-report.tsx — Settings UI component rendering the report.
• packages/types/src/agent-context-diagnostics.ts — Shared TypeScript interfaces.
• evals/packages/behaviors/src/diagnostics.ts — CI test harness for automated diagnostics validation.

Summary

• OpenWork isolates connectivity issues through three distinct probes: Cloud Catalog validation, TLS transport handshake, and Runtime-Engine differential analysis.
• HTTP 451 and TLS timeout errors typically indicate egress proxy or firewall interference requiring certificate trust configuration via NODE_EXTRA_CA_CERTS.
• cloud_catalog_mismatch and 401/403 errors resolve by re-authenticating OpenWork Cloud or refreshing the catalog from Settings.
• engine_evidence_stale_or_unavailable indicates the engine needs restart to record fresh registration evidence.
• The POST /workspace/:id/diagnostics/agent-context endpoint in agent-context-diagnostics.ts returns structured reports with specific remediation actions for each failure domain.

Frequently Asked Questions

What does HTTP 451 indicate in OpenWork diagnostics?

HTTP 451 signals that an egress proxy or firewall is blocking access to the OpenWork Cloud endpoint. Unlike 401 or 403 (which indicate authentication issues), 451 suggests network-level filtering. Verify corporate firewall rules and ensure *.openwork.dev domains are allowlisted, or configure NODE_EXTRA_CA_CERTS if TLS inspection is intercepting the connection.

How do I fix TLS certificate errors when probing the Cloud MCP endpoint?

When agent-context-transport-probe.ts returns tls_incomplete_chain, tls_untrusted_ca, or TLS timeout errors, the runtime cannot validate the server certificate. Add your organization's root CA certificate to the NODE_EXTRA_CA_CERTS environment variable, or disable TLS inspection for OpenWork Cloud domains. For on-prem Den deployments, add the custom origin to OPENWORK_AGENT_DIAGNOSTICS_TRUSTED_ORIGINS.

What is the difference between the runtime and engine checks?

The runtime refers to the OpenWork process executing your workspace code, while the engine is the persistent service managing MCP registrations and configuration. The differential check compares whether both can reach the Cloud MCP. If the runtime passes but the engine fails, the issue is engine-side registration (resolved by restart); if both fail, the problem is network or endpoint configuration.

Where can I find the agent-context diagnostics endpoint?

The server endpoint is implemented in apps/server/src/agent-context-diagnostics.ts and exposed at POST /workspace/:id/diagnostics/agent-context. It aggregates data from agent-context-cloud-probe.ts, agent-context-transport-probe.ts, and agent-context-engine-inspection.ts to produce a unified report consumed by both the desktop client (agent-context-diagnostics-fetch.mjs) and the React settings UI.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}