Understanding the Agent Context Diagnostics Transport Layer in OpenWork

The agent context diagnostics transport layer is a typed, schema-driven framework that inspects HTTP connectivity between OpenWork agents and Cloud endpoints, categorizing transport failures like TLS errors and DNS timeouts while sanitizing sensitive data from diagnostic reports.

OpenWork's agent context diagnostics system provides runtime visibility into how agents communicate with remote infrastructure. The transport layer component specifically validates the HTTP connection health between an OpenWork agent and its designated Cloud endpoint, ensuring secure data transmission without exposing credentials in diagnostic outputs.

How the Transport Layer Diagnostic Works

The transport layer diagnostic follows a strict six-step pipeline defined in packages/types/src/agent-context-diagnostics.ts and implemented in evals/packages/behaviors/src/diagnostics.ts. This process ensures that connectivity issues are detected, categorized, and reported without compromising security.

Diagnostic Definition and Schema

The transport check is identified by the string cloud-endpoint-transport, which appears in the ordered list of diagnostic IDs within the types file. The diagnostic result adheres to agentContextDiagnosticCheckSchema, which includes a transportCause field that enumerates specific failure modes.

The transportCauseSchema uses a Zod enum to define possible transport failures:

• tls_incomplete_chain
• tls_untrusted_ca
• dns_error
• timeout
• http_error
• unknown

This schema ensures that all transport errors are normalized into predictable, type-safe values rather than free-form error strings.

Data Collection and Error Mapping

When OpenWork executes a product diagnostics probe, the system performs an HTTP request to the Cloud endpoint using the implementation in evals/packages/behaviors/src/diagnostics.ts. The request is wrapped in a helper that captures either the raw HTTP response or the thrown error.

The helper function maps network failures to the enumerated transportCause values. For example, TLS certificate validation failures map to tls_untrusted_ca, while DNS resolution failures map to dns_error. This mapping occurs before the data enters the diagnostic report, ensuring consistency across different runtime environments.

Data Sanitization and Safety Guarantees

Before any textual data from the transport layer enters the diagnostic report, it undergoes dual-stage sanitization. The scrubAgentContextDiagnosticText function performs initial redaction, followed by sanitizeAgentContextDiagnosticText, which guarantees that no credential-like strings leak into the output.

The final AgentContextDiagnosticsReport includes a safety sub-object that enforces strict privacy controls:

• tokenValuesIncluded: false
• authorizationHeaderValuesIncluded: false

These boolean flags ensure that even if the underlying HTTP request fails with a 401 Unauthorized or a TLS handshake error, the diagnostic report never exposes secrets, tokens, or authorization headers.

Implementation Code Examples

The following example demonstrates how to sanitize user-provided text before adding it to a diagnostic report:

import {
  sanitizeAgentContextDiagnosticText,
  scrubAgentContextDiagnosticText,
} from "@openwork/types/agent-context-diagnostics";

// Example: clean a user-provided label before adding it to a diagnostic.
const rawLabel = "https://my-secret-token.example.com/api?key=ABC123";
const safeLabel = sanitizeAgentContextDiagnosticText(
  scrubAgentContextDiagnosticText(rawLabel)
);
// safeLabel === "[redacted-sensitive-label]"

This example shows how to map transport errors to the transportCause enum during a connectivity probe:

import { TransportCause } from "@openwork/types/agent-context-diagnostics";

// Simulated transport probe – maps errors to a transportCause.
async function transportProbe(url: string): Promise<{
  ok: boolean;
  cause?: TransportCause;
}> {
  try {
    const resp = await fetch(url);
    return { ok: resp.ok };
  } catch (e) {
    // Very simplified mapping – real code uses the exhaustive enum.
    const msg = (e as Error).message;
    if (msg.includes("TLS")) return { ok: false, cause: "tls_untrusted_ca" };
    if (msg.includes("DNS")) return { ok: false, cause: "dns_error" };
    return { ok: false, cause: "unknown" };
  }
}

Key Source Files

Understanding the transport layer requires familiarity with these specific files in the different-ai/openwork repository:

• packages/types/src/agent-context-diagnostics.ts — Defines the full diagnostics schema, the ordered list of check IDs (including cloud-endpoint-transport), sanitization helpers, and safety flags.

• evals/packages/behaviors/src/diagnostics.ts — Executes the transport probe, collects the transportCause, and constructs the AgentContextDiagnosticsReport.

• packages/types/src/den/connect-diagnostics.ts — Contains related diagnostics for Den connectivity, demonstrating how transport diagnostics integrate with broader connection checks.

Summary

• The agent context diagnostics transport layer validates HTTP connectivity between OpenWork agents and Cloud endpoints through the cloud-endpoint-transport diagnostic check.

• Transport failures are categorized into type-safe enum values including tls_untrusted_ca, dns_error, and timeout via the transportCauseSchema.

• All diagnostic data passes through scrubAgentContextDiagnosticText and sanitizeAgentContextDiagnosticText to prevent credential exposure.

• The implementation in evals/packages/behaviors/src/diagnostics.ts wraps HTTP requests to capture errors and map them to standardized transport causes.

• Safety flags in agentContextDiagnosticsReportSchema enforce that tokenValuesIncluded and authorizationHeaderValuesIncluded remain false, ensuring diagnostic reports contain no secrets.

Frequently Asked Questions

What specific transport errors can the diagnostic detect?

The transport layer diagnostic detects TLS validation failures (tls_incomplete_chain, tls_untrusted_ca), DNS resolution errors (dns_error), network timeouts (timeout), general HTTP errors (http_error), and unknown connection failures (unknown). These values are defined in the transportCauseSchema enum located in packages/types/src/agent-context-diagnostics.ts.

How does OpenWork prevent sensitive data from leaking in transport diagnostics?

OpenWork implements a dual-stage sanitization process using scrubAgentContextDiagnosticText followed by sanitizeAgentContextDiagnosticText. Additionally, the AgentContextDiagnosticsReport schema enforces safety flags that guarantee tokenValuesIncluded and authorizationHeaderValuesIncluded are always false, ensuring URLs, headers, and error messages never expose credentials.

Where is the transport diagnostic check implemented in the codebase?

The transport diagnostic check is implemented in evals/packages/behaviors/src/diagnostics.ts, which executes the HTTP probe to the Cloud endpoint. The type definitions, schema validations, and safety checks reside in packages/types/src/agent-context-diagnostics.ts.

What happens when a transport diagnostic fails?

When the transport diagnostic fails, the system populates the transportCause field with the specific error type (such as tls_untrusted_ca or dns_error), sets the check status to failed or warning, and includes a human-readable message. The report is then sent to the /diagnostics endpoint while maintaining strict privacy guarantees through the schema-enforced safety flags.

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