# Understanding the Agent Context Diagnostics Transport Layer in OpenWork

> Explore the agent context diagnostics transport layer in OpenWork. This framework inspects HTTP connectivity, identifies TLS and DNS failures, and sanitizes sensitive data for better troubleshooting.

- Repository: [Different AI/openwork](https://github.com/different-ai/openwork)
- Tags: deep-dive
- Published: 2026-08-06

---

**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`](https://github.com/different-ai/openwork/blob/main/packages/types/src/agent-context-diagnostics.ts) and implemented in [`evals/packages/behaviors/src/diagnostics.ts`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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:

```typescript
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:

```typescript
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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/evals/packages/behaviors/src/diagnostics.ts)** — Executes the transport probe, collects the `transportCause`, and constructs the `AgentContextDiagnosticsReport`.

- **[`packages/types/src/den/connect-diagnostics.ts`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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.