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

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 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, 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, 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:

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:

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 removes tokens, JWTs, and other sensitive strings from the diagnostics bundle:

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, ensuring that authentication credentials never leave the client machine.

Summary

• The diagnostics transport layer lives in 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 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 using sanitizeDiagnosticString from 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.

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