How Agent Context Diagnostics Work in OpenWork for Troubleshooting

Agent context diagnostics in OpenWork generate structured, validated reports via the /workspace/:id/diagnostics/agent-context endpoint, using a strict Zod schema to evaluate 19 distinct health criteria across the execution environment while sanitizing sensitive data to prevent credential leakage.

OpenWork, developed by different-ai, provides a comprehensive agent-context diagnostics subsystem that enables developers and AI agents to troubleshoot execution failures programmatically. This system produces deterministic health reports that detail workspace configuration, engine status, MCP inventory, and safety flags, allowing rapid identification of why a particular agent run failed or which components are unavailable.

The Three-Layer Diagnostic Architecture

The diagnostic flow operates through three logical layers that transform raw system data into a safe, consumable report.

Data Collection Layer

The first layer gathers raw facts from every component influencing an agent run. According to the OpenWork source code, this includes workspace metadata, engine configuration, registered plugins, MCP inventory, cloud tool catalogs, organization-connection status, and safety-related flags.

Workspace metadata is assembled in the server handler that serves the diagnostics endpoint, while engine, MCP, and plugin information are pulled from respective client libraries including enterprise-mcp-client and enterprise-mcp-server.

Validation and Normalization Layer

Raw payloads are converted into AgentContextDiagnosticsReport objects that satisfy the Zod schema defined in agentContextDiagnosticsReportSchema. This step, implemented in [packages/types/src/agent-context-diagnostics.ts](https://github.com/different-ai/openwork/blob/dev/packages/types/src/agent-context-diagnostics.ts), guarantees a deterministic shape and enforces the canonical order of checks.

The schema contains:

• AGENT_CONTEXT_DIAGNOSTIC_CHECK_IDS – an ordered list of 19 distinct checks
• agentContextDiagnosticCheckSchema – per-check fields including status, evidence kind, owner, action, and details
• Cross-field superRefine logic that derives the overall status, identifies firstFailedCheck, and validates consistency between safety flags and observed data

Sanitization and Safety Layer

Before transmission, the system removes potentially sensitive content from free-form diagnostic text to prevent credentials, URLs, or absolute paths from leaking through user-controlled labels.

The utilities sanitizeAgentContextDiagnosticText and scrubAgentContextDiagnosticText, both exported from the types package, perform exhaustive pattern-based redaction. The helper containsSensitiveDiagnosticText walks normalized variants, decodes percent-encoded payloads, and checks against regexes for URLs, JWTs, known token patterns, and path patterns. If a label exceeds 500 characters or contains sensitive data, it is replaced with "[redacted-sensitive-label]".

The Diagnostic Request Flow

Understanding the end-to-end flow clarifies how troubleshooting data moves from the server to the client.

Client Request Initiation

An OpenWork client—whether the desktop app, OpenCode, or any MCP-aware agent—issues a GET request to https://api.openworklabs.com/mcp/agent/workspace/<workspace-id>/diagnostics/agent-context.

Server Handler Orchestration

The server route, implemented in [ee/apps/den-api/src/routes/diagnostics.ts](https://github.com/different-ai/openwork/blob/dev/ee/apps/den-api/src/routes/diagnostics.ts), performs the following actions:

1. Queries the workspace record for ID, name, and type
2. Invokes the engine-client to fetch engine-config and engine-agent evidence
3. Collects MCP inventory via engine-mcp-sync and engine-mcp-status
4. Probes organization connections using organizationConnectionsProbe
5. Assembles the static list of checks from AGENT_CONTEXT_DIAGNOSTIC_CHECK_IDS and populates each entry with a status (passed, warning, failed, or skipped) derived from collected evidence
6. Runs the safety-sanitizer to ensure no diagnostic text leaks secret data
7. Validates the entire payload against agentContextDiagnosticsReportSchema

Response Structure

The validated, sanitized JSON object returns to the caller with a versioned schema (AGENT_CONTEXT_DIAGNOSTICS_SCHEMA_VERSION = 1). Consumers can programmatically inspect the overall field, locate the firstFailedCheck, or drill into any checks[i] entry to view detailed messages, owners, and corrective actions.

Working with Agent Context Diagnostics Programmatically

Developers can interact with the diagnostics system using the enterprise MCP client and validation utilities.

Fetching Diagnostics Reports

Use the enterprise-mcp-client to retrieve structured diagnostic data:

import { createEnterpriseMcpClient } from "@openwork/enterprise-mcp-client";

async function getAgentContextDiagnostics(workspaceId: string) {
  // Initialise the MCP client
  const client = createEnterpriseMcpClient({ fetch });

  // Request the diagnostics report
  const report = await client.fetchWorkspaceDiagnostics(workspaceId, {
    organizationConnectionsProbe: { status: "observed", totalCount: 0, truncated: false },
    organizationConnections: [],
  });

  // Inspect the results
  console.log("Overall status:", report.overall);
  if (report.firstFailedCheck) {
    console.log("First failure:", report.firstFailedCheck);
  }
  return report;
}

Sanitizing Diagnostic Text

When handling user-provided labels or external data, apply the safety utilities:

import {
  sanitizeAgentContextDiagnosticText,
  scrubAgentContextDiagnosticText,
} from "@openwork/types";

// Example with potential API key exposure
const userProvidedLabel = "my-token: sk-abcd1234efgh5678ijkl";
const safeLabel = sanitizeAgentContextDiagnosticText(userProvidedLabel);
// → "[redacted-sensitive-label]"

// Example with URL scrubbing
const urlLabel = "Visit https://example.com/secret?token=owt_12345";
const scrubbed = scrubAgentContextDiagnosticText(urlLabel);
// → "Visit [url]?token=[url]"

Validating Custom Payloads

For testing or custom implementations, validate payloads against the official schema:

import { agentContextDiagnosticsReportSchema } from "@openwork/types";

const rawPayload = /* JSON received from the server */;
const result = agentContextDiagnosticsReportSchema.safeParse(rawPayload);

if (!result.success) {
  console.error("Diagnostics payload failed validation:", result.error);
} else {
  console.log("Valid report with", result.data.checks.length, "checks");
}

Key Implementation Files

The diagnostics pipeline spans several critical files in the OpenWork monorepo:

• [packages/types/src/agent-context-diagnostics.ts](https://github.com/different-ai/openwork/blob/dev/packages/types/src/agent-context-diagnostics.ts) – Central Zod schema, check IDs, sanitization helpers, and safety logic
• [ee/apps/den-api/src/routes/diagnostics.ts](https://github.com/different-ai/openwork/blob/dev/ee/apps/den-api/src/routes/diagnostics.ts) – HTTP handler orchestrating report assembly and subsystem invocation
• [packages/enterprise-mcp-client/src/client.ts](https://github.com/different-ai/openwork/blob/dev/packages/enterprise-mcp-client/src/client.ts) – High-level client API with fetchWorkspaceDiagnostics
• [packages/types/src/den/connect-diagnostics.ts](https://github.com/different-ai/openwork/blob/dev/packages/types/src/den/connect-diagnostics.ts) – Connect evidence schema referenced in main reports
• [packages/types/src/den/egress-diagnostics.ts](https://github.com/different-ai/openwork/blob/dev/packages/types/src/den/egress-diagnostics.ts) – Header-level diagnostics for egress-side tracing

Summary

• Agent context diagnostics in OpenWork provide structured troubleshooting reports via the /workspace/:id/diagnostics/agent-context endpoint, accessible through the enterprise MCP client.
• The system validates all reports against agentContextDiagnosticsReportSchema in packages/types/src/agent-context-diagnostics.ts, ensuring 19 distinct health checks follow a canonical order.
• Sanitization utilities sanitizeAgentContextDiagnosticText and scrubAgentContextDiagnosticText prevent credential leakage by redacting URLs, tokens, and paths exceeding 500 characters.
• The versioned schema (AGENT_CONTEXT_DIAGNOSTICS_SCHEMA_VERSION = 1) ensures backward compatibility, allowing new checks to be appended without breaking existing clients.
• Server-side implementation in ee/apps/den-api/src/routes/diagnostics.ts orchestrates data collection from workspace metadata, engine configuration, and MCP inventory to produce the final report.

Frequently Asked Questions

What is the agent context diagnostics endpoint in OpenWork?

The agent context diagnostics endpoint is available at /workspace/:id/diagnostics/agent-context and returns a JSON report describing the health of the entire execution environment. Clients access this via GET request to https://api.openworklabs.com/mcp/agent/workspace/<workspace-id>/diagnostics/agent-context or through the fetchWorkspaceDiagnostics method in the enterprise MCP client.

How does OpenWork prevent sensitive data leakage in diagnostic reports?

OpenWork employs sanitizeAgentContextDiagnosticText and scrubAgentContextDiagnosticText utilities that use regex-based pattern matching to detect URLs, JWTs, API keys, and absolute paths. The containsSensitiveDiagnosticText helper decodes percent-encoded payloads and checks against normalized variants, replacing any sensitive label with "[redacted-sensitive-label]" or scrubbing specific patterns like URLs with [url] placeholders.

What are the 19 diagnostic checks in the agent context report?

The 19 checks are defined in the AGENT_CONTEXT_DIAGNOSTIC_CHECK_IDS constant within packages/types/src/agent-context-diagnostics.ts. While the specific check names aren't enumerated in the public schema, they cover workspace metadata validation, engine configuration status, MCP inventory availability, plugin registration state, organization connection health, and safety-related flags, each returning a status of passed, warning, failed, or skipped.

How is the agent context diagnostics schema versioned?

The schema uses AGENT_CONTEXT_DIAGNOSTICS_SCHEMA_VERSION = 1 to ensure backward compatibility. When new checks are introduced, they are appended to the end of the ordered AGENT_CONTEXT_DIAGNOSTIC_CHECK_IDS list without modifying existing check positions. This versioning strategy allows older clients to parse newer reports safely while ignoring checks they don't recognize.

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