# What Is the Diagnostics Transport Layer in OpenWork? A Deep Dive into Safe Client-Server Communication

> Discover the diagnostics transport layer in OpenWork. Learn how this safe client-server communication subsystem prevents UI hangs and memory issues with strict limits.

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

---

**The diagnostics transport layer in OpenWork is a bounded, abort-safe network subsystem that transmits runtime diagnostic bundles from client to server, enforcing strict 1 MiB response limits, 30-second timeouts, and custom error types to prevent UI hangs and memory exhaustion.**

OpenWork collects comprehensive runtime diagnostics—including workspace state, server connections, and performance logs—to troubleshoot issues and monitor system health. This sensitive data flows through the **diagnostics transport layer**, a specialized subsystem implemented in [`apps/app/src/app/lib/agent-context-diagnostics-transport.ts`](https://github.com/different-ai/openwork/blob/main/apps/app/src/app/lib/agent-context-diagnostics-transport.ts) that guarantees reliable transmission regardless of network volatility or payload size.

## Protocol Limits and Bounded Responses

The transport layer enforces hard constraints to protect client resources. According to the source code in [`agent-context-diagnostics-transport.ts`](https://github.com/different-ai/openwork/blob/main/agent-context-diagnostics-transport.ts), two constants govern every request:

- **`AGENT_CONTEXT_DIAGNOSTICS_RESPONSE_MAX_BYTES`** – Caps the response size at **1 MiB**
- **`AGENT_CONTEXT_DIAGNOSTICS_REQUEST_TIMEOUT_MS`** – Sets a default request timeout of **30 seconds**

These limits prevent runaway memory consumption and ensure the UI remains responsive during diagnostic uploads.

### Streaming with Size Bounds

The function `readBoundedResponseText` handles response consumption. It streams the fetch `Response.body` incrementally, aborting immediately if the cumulative byte count exceeds the 1 MiB threshold or if the abort signal fires. When present, the implementation also respects the `Content-Length` header to pre-validate response size before streaming begins.

## Deadline-Driven Request Lifecycle

Every diagnostics request operates under a unified deadline managed by `requestAgentContextDiagnosticsPayload`. This function calculates a single `deadlineAtMs` timestamp that governs both the initial fetch and the subsequent bounded read operation.

An `AbortController` is wired to this deadline; if either phase exceeds the allotted time, the controller triggers cancellation, ensuring the request cannot outlive its 30-second window. This approach eliminates zombie requests that could otherwise exhaust connection pools.

## Desktop-Aware Fetch Implementation

OpenWork runs in both desktop (Tauri) and browser environments. The transport layer detects the runtime via `isDesktopRuntime()` and selects the appropriate fetch implementation:

- **Desktop**: Uses `desktopFetchAgentContextDiagnostics`, a Tauri-provided bridge that bypasses CORS restrictions and honors desktop-specific deadlines
- **Web**: Falls back to the native `fetch` API

This branching logic is orchestrated in [`apps/app/src/app/lib/openwork-server.ts`](https://github.com/different-ai/openwork/blob/main/apps/app/src/app/lib/openwork-server.ts), where `requestAgentContextDiagnosticsJson` invokes the transport with the correct fetch implementation based on the execution context.

## Custom Error Classification

The transport defines `AgentContextDiagnosticsTransportError` to distinguish between failure modes that generic network errors cannot capture:

- **`agent_context_diagnostics_request_timed_out`** – The request exceeded the 30-second deadline
- **`agent_context_diagnostics_response_too_large`** – The response body exceeded the 1 MiB limit

These specific error codes allow calling code to implement targeted retry logic or user-facing messages.

## Sending Diagnostics from the Client

To transmit a diagnostics bundle, the client builds the payload and invokes the high-level server client. The following example demonstrates the complete flow:

```typescript
import { createOpenworkServerClient } from "@/app/lib/openwork-server";
import { buildDiagnosticsBundleJson } from "@/app/lib/diagnostics-bundle";

// Build the bundle (e.g. from the current UI context)
const bundleJson = await buildDiagnosticsBundleJson({
  capturedAt: new Date().toISOString(),
  desktopRuntime: true,
  // …other required fields
});

// Create a client for the local OpenWork server
const client = createOpenworkServerClient({
  baseUrl: "http://localhost:8787",
  token: "my‑token",
});

// POST the diagnostics bundle
await client.requestAgentContextDiagnosticsJson(
  client.baseUrl,
  "/diagnostics",
  {
    token: "my‑token",
    body: JSON.parse(bundleJson),
    timeoutMs: 30_000, // optional override
  },
);

```

The call above delegates to `requestAgentContextDiagnosticsPayload`, which enforces the timeout and size limits defined in the transport layer.

## Handling Transport Errors

Client code should catch `AgentContextDiagnosticsTransportError` to handle transport-specific failures separately from application logic:

```typescript
try {
  await client.requestAgentContextDiagnosticsJson(...);
} catch (err) {
  if (err instanceof AgentContextDiagnosticsTransportError) {
    if (err.code === "agent_context_diagnostics_request_timed_out") {
      console.error("Diagnostics request timed out");
    } else if (err.code === "agent_context_diagnostics_response_too_large") {
      console.error("Diagnostics response exceeded size limit");
    }
  } else {
    console.error("Unexpected error", err);
  }
}

```

## Sanitizing Sensitive Data

Before transmission, secrets must be redacted. The `sanitizeDiagnosticString` function from [`apps/server/src/diagnostic-sanitizer.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/diagnostic-sanitizer.ts) removes tokens, JWTs, and other sensitive strings from the diagnostics bundle:

```typescript
import { sanitizeDiagnosticString } from "@/app/src/app/lib/diagnostic-sanitizer";

const safeToken = sanitizeDiagnosticString(secretToken);

```

This sanitization occurs during bundle construction in [`apps/app/src/app/lib/diagnostics-bundle.ts`](https://github.com/different-ai/openwork/blob/main/apps/app/src/app/lib/diagnostics-bundle.ts), ensuring that authentication credentials never leave the client machine.

## Summary

- The **diagnostics transport layer** lives in [`agent-context-diagnostics-transport.ts`](https://github.com/different-ai/openwork/blob/main/agent-context-diagnostics-transport.ts) and manages safe transmission of runtime state from OpenWork clients to servers.
- It enforces a **1 MiB response size limit** and a **30-second timeout** via `AGENT_CONTEXT_DIAGNOSTICS_RESPONSE_MAX_BYTES` and `AGENT_CONTEXT_DIAGNOSTICS_REQUEST_TIMEOUT_MS`.
- **`readBoundedResponseText`** streams responses while monitoring byte count, aborting if limits are exceeded.
- **Deadline-driven logic** in `requestAgentContextDiagnosticsPayload` uses `AbortController` to guarantee requests complete within their time window.
- **Desktop detection** routes requests through Tauri’s `desktopFetchAgentContextDiagnostics` when running in the desktop app, falling back to native `fetch` in browsers.
- Custom error codes distinguish between timeouts and oversized responses for precise error handling.

## Frequently Asked Questions

### What is the maximum size limit for diagnostics responses in OpenWork?

OpenWork caps diagnostics responses at **1 MiB** (1,048,576 bytes) via the `AGENT_CONTEXT_DIAGNOSTICS_RESPONSE_MAX_BYTES` constant. If a server response exceeds this limit, the transport layer aborts the connection and throws an `AgentContextDiagnosticsTransportError` with code `agent_context_diagnostics_response_too_large`.

### How does OpenWork prevent diagnostics requests from hanging the UI?

The transport layer implements a **deadline-driven architecture** using `AbortController`. Every request receives a 30-second timeout (`AGENT_CONTEXT_DIAGNOSTICS_REQUEST_TIMEOUT_MS`). If the deadline expires during the fetch or response reading phase, the abort signal triggers, immediately terminating the connection and freeing up the main thread.

### What is the difference between the desktop and web fetch implementations?

When running inside the Tauri-based desktop app (`isDesktopRuntime()` returns true), the transport uses `desktopFetchAgentContextDiagnostics` to avoid CORS restrictions and respect desktop-specific security policies. In web environments, it falls back to the standard `fetch` API. This branching occurs in [`openwork-server.ts`](https://github.com/different-ai/openwork/blob/main/openwork-server.ts) within the `requestAgentContextDiagnosticsJson` method.

### How does the transport layer handle sensitive data like tokens?

While the transport layer manages transmission safety, data sanitization happens upstream in [`diagnostics-bundle.ts`](https://github.com/different-ai/openwork/blob/main/diagnostics-bundle.ts) using `sanitizeDiagnosticString` from [`diagnostic-sanitizer.ts`](https://github.com/different-ai/openwork/blob/main/diagnostic-sanitizer.ts). This utility redacts JWTs, API tokens, and other secrets before the bundle ever reaches the transport layer, ensuring that sensitive credentials are never transmitted to the OpenWork server.