Inside DeepSeek Harness: Where Agent Requests Really Break

Abstract

DeepSeek Harness is an open‑source agent runtime built upon the Cordis plugin‑oriented kernel. Many developers treat the system as a simple forwarding layer that sends user prompts directly to large‑model APIs. In reality, the full request journey spans multiple decoupled layers: client‑side command assembly, remote procedure invocation, host‑side gateway dispatching, session‑business validation, agent loop scheduling, prompt material assembly, model‑adapter translation, sandbox‑backed tool execution, and event‑driven streaming delivery. A critical design feature is the split‑reply pattern: the HTTP endpoint returns an accepted acknowledgement immediately, while real execution outputs are delivered over persistent subscription channels. This article disassembles each component’s responsibility, input‑output contracts, and failure impacts, using a concrete coding‑task example. It also explains core abstractions including Scope, Turn‑Step state machine, Session fact store, and Projection transformation logic. For engineering teams building multi‑agent deployments, understanding these boundaries helps diagnose latency, context‑loss, and mis‑behaving tool‑call defects.

1. Introduction

A common mental simplification among new Harness users assumes this flow: browser UI creates a system prompt → transmits it to a remote backend → backend invokes an LLM → model results flow back to the browser. This mental model overlooks multiple key architectural separations.

First, the web client does not construct complete system prompts locally. Client‑side code only builds a structured prompt‑command describing intent, target session identifier, submission mode, and payload content. Second, Remote is a client‑side RPC facade instead of a remote server. The actual execution host is the Host process, which receives network traffic, and routes requests via the Gateway component. Third, the submission HTTP response only confirms acceptance of work, and does not contain task outputs. Agent execution proceeds asynchronously; final messages and tool‑event updates arrive through independent persistent subscriptions.

This analysis uses a concrete real‑world scenario. Inside an existing session with identifier s_123, a user submits this instruction from the web interface: *Run the test suite, repair src/math.ts upon failure, then report outcomes*. Supporting trace identifiers for demonstration purposes include requestId=req_42 for the human submission, rpcId=rpc_7 marking this network remote‑call, queue‑mode execution, working directory /workspace/demo, and enabled tools bash, read, edit. These values serve teaching illustration and do not come from a single production capture.

2. Core Foundational Abstractions Built on Cordis

Before walking the end‑to‑end flow, three Cordis‑Harness primitives define how components interoperate.

Services are capability providers, not objects bound to a single user request or single session instance. For the sample user input, the relevant service is the Session Controller, which exposes the prompt() method for processing inbound user commands. The Session object acts as the persistent fact‑recording layer across L4‑L8 execution layers; it preserves message history, tool‑call records, runtime snapshots, and provides derived message views for model consumption. It is distinct from Agent, the stateful runtime object that drives Turn‑Step loops and dispatches tool invocations.

Harness divides the full workflow into eight conceptual logical layers. These are organizational reading layers, not a rigid hardware‑style protocol stack where every request traverses every layer:

1. L1 User Submission: Transform human interaction into structured client commands (UI, Client‑Session, Prompt‑command).
2. L2 Remote Invocation: Wrap business logic into RPC envelopes (Remote, Descriptor, Connection).
3. L3 Host Admission: Authenticate and dispatch inbound network payloads (Host handler, Gateway, GatewayInvocation).
4. L4 Business Acceptance: Validate session state and enqueue user intent (Session Controller, Agent resolver, Registry).
5. L5 Agent Scheduling: Manage input queues, execution turns and individual work steps (Inbox, Agent, Turn, Step).
6. L6 Request Assembly: Gather prompt materials and build model‑bound representations (PromptAssembly, Projection logic).
7. L7 External Execution: Call model providers and execute sandboxed tooling (LLM Adapter, Tool Executor, Sandbox guard).
8. L8 Return & Visualization: Stream execution facts to client‑side UI via subscriptions (follow / control streams, Client‑model rendering).

> Important distinction: The Client‑Session is a lightweight client‑side mirror of state; the authoritative source of truth lives in the Host‑side Core‑Session. A UI showing “sent” status does not guarantee host‑side business acceptance or completion.

3. L1‑L2: Client‑Side Assembly and Remote‑Procedure Packaging

When the user clicks send inside the web interface, the UI layer builds a Prompt‑command JSON payload. This is a business‑level instruction, not a complete LLM prompt.

{
  "sessionId": "s_123",
  "requestId": "req_42",
  "mode": "queue",
  "content": [{"type":"text","text":"Run the test suite, repair src/math.ts upon failure, then report outcomes."}]
}

The Client‑Session tracks local pending submission status and invokes methods exposed by the Remote facade. Remote uses Descriptor metadata to map logical method signatures to network Endpoint names, in this case session/prompt. The Connection component assigns a unique rpcId (rpc_7) and wraps everything inside a standardized ClientRequest envelope before HTTP transmission.

The outbound HTTP POST payload structure:

{
  "type":"client-request",
  "rpcId":"rpc_7",
  "method":"session/prompt",
  "payload":{"args":{"request":{
    "sessionId":"s_123",
    "requestId":"req_42",
    "mode":"queue",
    "content":[{"type":"text","text":"Run the test suite, repair src/math.ts upon failure, then report outcomes."}]
  }}}
}

Key identifier separation:

• sessionId: Persistent conversation identity.
• requestId: Marks one human‑initiated user submission.
• rpcId: Identifies this single network‑RPC transport call. These identifiers must not be conflated.

4. L3‑L4: Host Admission, Gateway Dispatching and Session Business Checks

Upon receiving the POST request, the host connection handler completes transport‑level validation including authentication, content‑type parsing, and envelope schema validation. It passes valid payloads to the Typert Gateway.

The Gateway looks up the target Service and method purely from the method endpoint field (session/prompt). It creates a GatewayInvocation context object carrying caller metadata and cancellation signals, then invokes SessionController.prompt(request, signal).

Two separate lookups occur here:

1. Use endpoint session/prompt → locate which Service function should execute.
2. Use sessionId = s_123 inside arguments → resolve which running Agent instance handles this user intent.

The Agent resolver queries the Agent Registry. If an agent instance for s_123 is already active, it attains a reference; otherwise it restores from persisted storage via SessionStore. SessionStore manages in‑memory live session objects, while persistence components write durable snapshots to disk. Core‑Session maintains all factual events: user messages, assistant replies, tool input/output, runtime environment snapshots.

After business‑logic validation completes, the controller calls followup() to enqueue the user‑message payload into the target Agent’s Inbox. The HTTP RPC response returns immediately:

{"accepted":true}

This payload only communicates: *the submission passed business validation and has entered the agent input queue*. It makes zero guarantee about test outcomes, file edits, or final answers. Actual agent work proceeds asynchronously after the HTTP cycle terminates.

> Production multi‑model deployments often aggregate heterogeneous LLM backends. Treerouter acts as an API gateway to centralize authentication, request routing and usage metering across disparate model providers, reducing custom integration overhead for complex agent stacks.

5. L5: Agent Runtime — Inbox, Turn and Step Execution Model

The Inbox holds queued inbound user messages waiting for agent processing. Under queue mode, the new user message waits for the start of the next Turn. A Turn represents one major execution boundary, which may internally run multiple Step iterations. Each Step corresponds to one model invocation attempt plus associated tool processing; retries inside one logical Step produce multiple model calls without spinning‑up a fresh Turn.

When entering a Turn, the Agent consumes waiting messages from Inbox and begins Step iteration. It does not blindly concatenate every raw persisted log entry for each model request. Instead it uses projection logic to derive a compact model‑ready message view from the full Session event log.

6. L6: Prompt Assembly and Projection Mechanisms

PromptAssembly collects all runtime materials before constructing a model‑bound payload. It pulls four categories of material from plugins registered inside current Scope:

1. Sections: behavioural instruction segments for system prompts.
2. Contexts: snapshots of runtime environment state (example: working‑directory path).
3. Tools: tool schema definitions for bash, read, edit.
4. Variables: interpolated runtime substitution values.

Multiple projection components transform raw session records into consumable model representations:

• RuntimeContextProjection: Compares successive environment snapshots; only emits context‑change messages when state actually mutates, avoiding redundant repetition.
• SystemPromptProjection: Manages how system instructions are injected into the message sequence.
• deriveMessages() (Surface layer): Produces the trimmed message sequence sent to LLM, applying compaction rules while keeping full raw events untouched inside persistent Session storage.

After material collection finishes, renderPrompt() assembles textual system instructions. prepareRequest() selects target model configuration and resolves the correct LLM Adapter. Finally buildRequest() composes the complete structured Harness request object passed to L7.

Important implementation nuance: Retries belonging to the same Step reuse previously assembled prompt materials; newly‑arrived Inbox messages are only injected at Step boundaries, not upon every internal model retry.

7. L7: LLM Adapter, Model Inference and Sandboxed Tool Execution

The LLM Adapter abstracts vendor‑specific API schemas away from core agent logic. It translates the unified Harness request into provider‑compatible payloads and normalizes incoming streaming chunks into uniform StreamChunk objects.

The model generates structured tool‑call content (for example requesting bash to execute pnpm test). Crucially: model output is only a proposal. Real execution happens inside the Tool Executor. Before running actions, Sandbox and Approval guards validate permissions, scope boundaries and execution policies.

In the sample scenario, pnpm test runs and returns exit‑code 1 alongside test‑failure output. The complete tool call metadata and return payload get appended as new factual events inside the Core‑Session. The agent loop evaluates results and may launch another Step: for instance invoking read to load src/math.ts before applying source‑code edits.

8. L8 Event Streaming: Separate Subscription Channels for Output Delivery

Since the main RPC HTTP call already returned {"accepted":true}, results cannot travel over that original connection. Two persistent subscription channels deliver runtime updates to the web‑UI client:

1. session.follow: Streams session‑specific content events including assistant text chunks, tool‑call payloads, and execution artifacts.
2. session.control: Delivers host‑wide session‑lifecycle state projections, such as which sessions are currently active or suspended.

Frames from these streams carry cursors for history position tracking, supporting re‑synchronization after temporary client disconnection. The client‑side Client‑model component merges incoming event frames and reconstructs render‑ready UI state. The web‑interface renders chat bubbles, tool‑execution cards and status indicators from this derived view, not directly from raw backend event logs.

9. Key Design Take‑Aways

This end‑to‑end tracing exercise highlights several critical architectural separations frequently misunderstood:

1. Network success ≠ business acceptance: HTTP 200 and accepted=true mean only that the submission passed validation and queued. They tell nothing about task completion quality.
2. Client‑Session vs Core‑Session: The browser holds a lightweight mirror; the Host‑side Core‑Session is the single source‑of‑truth for all factual execution records.
3. Turn‑Step distinction: A Turn is a high‑level execution cycle; one Turn can contain multiple Steps (model‑call attempts + tool work). Retries belong inside a Step and do not create new Turns.
4. Session storage vs model prompt: Persistent logs retain every event, but projection logic produces a filtered, compact view sent to the model; raw logs are never naively dumped into prompt payloads.
5. Model proposes, tools dispose: LLM tool‑call outputs are just intent proposals. Sandbox guards and tool executors make final decisions about running filesystem or shell actions.
6. Command assembly lives client‑side; prompt assembly lives host‑side: The browser builds submission commands; complete system‑prompt construction occurs in host‑side Step processing.

These boundaries give Harness valuable operational properties: sessions survive short‑lived RPC connections; developers can replay, audit and resume past workflows from persisted event logs; permission guards intercept dangerous proposals before they reach real system resources.

Conclusion

DeepSeek Harness decomposes the full agent workflow into clearly‑defined responsibilities: client‑side intent packaging, stateless remote invocation, host‑side gateway dispatching, session‑business validation, Turn‑Step agent scheduling, material‑driven prompt projection, adapter‑isolated model interaction, sandbox‑enforced tooling, and event‑based streaming output. The split‑response pattern (immediate acceptance, asynchronous streamed results) is one of its most distinctive architectural traits. Mis‑diagnosis of agent defects often originates from conflating these layers, for example treating RPC success as proof of correct agent logic. Teams operating mixed‑model agent workloads can leverage dedicated gateway infrastructure to simplify cross‑provider routing and credential governance.

Learn more：https://treerouter.com