What is the TencentCloud AgentObs SDK for DeepSeek Harness?

The TencentCloud AgentObs SDK for DSH (tencentcloud-agentobs-sdk-dsh) is a first-party observability plugin for DeepSeek Harness. Rather than treating DSH as a black box that you instrument from the outside, it hooks directly into the harness’s own lifecycle events. Those events — a session starting, an agent being invoked, each ReAct round, an LLM stream, and every tool execution — are converted into spans that follow Tencent Cloud’s AI Agent observability specification, then shipped to CLS through the official tencentcloud-cls-sdk-js transport.

The key architectural decision is that the plugin is transport-native to a cloud vendor’s log service. Where most DSH observability plugins speak OpenTelemetry and require an OTLP endpoint, this one talks Protobuf directly to Tencent Cloud Log Service. For teams already paying for CLS, that removes an entire class of operational burden.

How does DSH GenAI trace observability work without a collector?

The zero-collector architecture is the plugin’s defining feature. The data path is short and self-contained:

1. DeepSeek Harness fires native lifecycle events during a session.
2. The AgentObs plugin’s CLS Trace Coordinator receives those events.
3. Each event is normalized into Tencent Cloud’s 5-layer span model.
4. Spans are batched and serialized with tencentcloud-cls-sdk-js (Protobuf).
5. Batches are uploaded directly to a CLS topic over HTTPS.

There is no OpenTelemetry Collector to run, no Jaeger or SigNoz backend to maintain, and no sidecar container to schedule. Contrast that with the standard OpenTelemetry DeepSeek approach, which requires you to deploy an OTLP receiver and run opentelemetry-distro instrumentation on top of an OpenAI-compatible SDK. That approach is portable and vendor-neutral, but it is also infrastructure you must operate. The Tencent plugin trades portability for a dramatically simpler deploy.

What is the 5-layer span model for AI agent observability?

Tencent Cloud’s AI Agent observability spec organizes traces into a five-layer span hierarchy: entry, agent, step, chat, and tool. The plugin maps DSH’s native lifecycle onto that model, so a single DSH turn produces a nested trace:

This nesting is what makes the trace useful. Instead of a flat list of spans, you see the whole shape of an agent turn: which round of ReAct a tool call happened in, which model answered which prompt, and where the time and tokens actually went. When you open a trace in CLS, you can drill from the top-level entry down to a single tool invocation in a specific reasoning step.

What span semantics are recorded under the hood?

The plugin does not invent a proprietary trace format; it aligns with OpenTelemetry conventions. Each span carries the standard identifiers and metadata you would expect from a well-behaved tracer:

• traceID as a 32-hex-character string
• spanID and parentSpanID as 16-hex-character strings
• OpenTelemetry span kinds (INTERNAL, CLIENT, SERVER)
• Status codes (OK, ERROR, UNSET)
• Nanosecond-precision start, end, and duration fields
• Token usage and model identifiers on chat spans

This OTel alignment matters for two reasons. First, it keeps the data recognizable to engineers already comfortable with distributed tracing. Second, it makes correlation possible inside Tencent Cloud: because spans live in CLS, you can join GenAI traces against logs, metrics, and cost analytics in the same log platform, enabling session-to-token-cost analysis without a separate tracing database.

How do I install the DSH plugin?

Installation uses DeepSeek Harness’s native plugin mechanism. You add the plugin to whichever profile you are running, then restart the harness for it to take effect:

dsh plugin --profile web add tencentcloud-agentobs-sdk-dsh
# or
dsh plugin --profile headless add tencentcloud-agentobs-sdk-dsh
# or
dsh plugin --profile harness add tencentcloud-agentobs-sdk-dsh

Because the profile flag selects where the plugin applies, you can enable tracing only on the headless automation profile and leave interactive sessions untouched — or vice versa. The restart requirement is worth remembering: adding the plugin is not enough, DeepSeek Harness must be restarted before the observer attaches.

One installation pitfall applies to pnpm v9 or later. The plugin depends on protobufjs, which has a build script. Modern pnpm blocks build scripts by default, so you must approve them or the Protobuf serialization layer will not build:

pnpm approve-builds

How do I configure the plugin?

Configuration is handled either through environment variables or through a cordis.patch.yml file in the profile directory. The environment variable path is the quickest for a single deployment:

The four credentials — endpoint, topic, secret ID, and secret key — are mandatory; without them the plugin has nowhere to write spans. The service name is how you identify this deployment inside CLS, so give it a value that distinguishes environments, for example dsh-prod-web.

For teams that prefer declarative config checked into the repo, cordis.patch.yml under the profile is the alternative. It carries the same options in YAML form and keeps secrets out of shell history — though you should still externalize the actual secret values through your secret manager rather than committing them.

Should I capture prompts, responses, and tool content?

Content capture is on by default, and this is the feature that demands the most attention. With capture enabled, the plugin attaches prompts, LLM responses, and tool arguments and results to their spans. That gives you searchable, debuggable traces — but it also means credentials, source code, and personally identifiable information can be shipped to CLS as part of a trace.

The trade-off is real, and the brief is unambiguous: content capture can leak sensitive data into a cloud log service. You control the blast radius with two levers:

• captureContent: false (or OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=false) disables content attachment entirely, leaving only span structure, timing, and metadata.
• contentMaxChars, defaulting to 128000, caps how much content a single span carries so a pathological tool result does not bloat a topic.

For anything that touches production data, plan a content policy before you enable the plugin. Trace structure and timing usually survive with capture off; if you need content, apply the same redaction rules you use for your application logs.

How do batching, buffering, and retries behave?

The plugin buffers spans in memory and flushes them in batches to avoid hammering CLS with a request per span. Four knobs control that behavior:

The most important implication is the drop policy. When the in-memory queue hits maxQueueSize, the plugin drops the oldest span rather than blocking the agent. That is a deliberate availability choice: observability must never stall the harness. Under normal load 2048 buffered spans is generous, but a burst of heavy tool calls can fill it, so treat dropped spans as a signal that batching needs tuning or the flush interval needs lowering.

What are the compatibility requirements?

The plugin targets a specific window of DeepSeek Harness releases and a recent Node.js runtime:

The version pin matters. Because the plugin hooks DSH’s internal lifecycle events, it depends on the event shapes of a particular harness generation. If you are on a Harness older than 0.1.0-rc.6 or have already moved to 0.2.0 and beyond, verify plugin compatibility before assuming your traces will appear.

How does the Tencent plugin compare to other DSH observability options?

DeepSeek Harness already has an observability ecosystem, and the Tencent plugin is not the only choice. The realistic decision is less “which tracer” and more “which architecture”:

The structural difference is collector versus no collector. dsh-plugin-langfuse and the generic OpenTelemetry plugin both lean on OTLP and expect an endpoint you run or subscribe to. Langfuse, the incumbent open-source LLM observability platform, also auto-traces OpenAI-compatible DeepSeek API calls through langfuse.openai, but it still requires running Langfuse as a backend. The Tencent plugin is the first DSH plugin that targets a specific cloud vendor’s native log service, so it carries no collector and no extra backend — you only need the CLS topic you already pay for.

Who should use it, and who should skip it?

This plugin is a strong fit for teams that are already invested in Tencent Cloud. If your infrastructure, log pipeline, and alerting all live in CLS, pushing GenAI traces into the same platform gives you unified dashboards, cost correlation, and retention policy management without introducing a second observability silo. The zero-collector setup is genuinely attractive for a small agent fleet where running an OTLP stack is disproportionate overhead.

It is a less obvious fit when you are not on Tencent Cloud. The plugin locks your trace data to a single vendor’s log service, and if your organization standardizes on OpenTelemetry or a self-hosted stack, dsh-plugin-langfuse or the generic OTel plugin keeps you portable. If your DeepSeek Harness version has drifted outside the supported window, portability also wins. In short: Tencent Cloud users get the cleanest setup; everyone else should weigh vendor lock-in against the convenience.

Hands-on: from install to your first CLS trace

A minimal end-to-end run looks like this. First, add the plugin to the profile you run:

dsh plugin --profile harness add tencentcloud-agentobs-sdk-dsh
pnpm approve-builds   # required on pnpm v9+

Second, set the CLS credentials. With environment variables:

export CLS_ENDPOINT="ap-guangzhou.cls.tencentcs.com"
export CLS_TOPIC_ID="your-topic-id"
export CLS_SECRET_ID="your-secret-id"
export CLS_SECRET_KEY="your-secret-key"
export CLS_SERVICE_NAME="dsh-prod"

Third, restart DeepSeek Harness so the observer attaches. Fourth, run a session that invokes the agent and at least one tool. Within the flush interval, spans will appear in your CLS topic, nested as entry → agent → step → chat → tool. From there, build a dashboard for token usage and per-tool latency, and add an alert on ERROR-status spans — you now have deepseek harness observability without a single extra service to run.

What pitfalls should I watch for?

The practical gotchas cluster around configuration, privacy, and environment:

• Content leakage. Capture is on by default; disable it or set contentMaxChars before tracing anything sensitive.
• pnpm build scripts. On pnpm v9+, forgetting pnpm approve-builds breaks the Protobuf layer silently at build time.
• Restart required. Adding the plugin does not attach it; you must restart DeepSeek Harness.
• Queue overflow drops. At maxQueueSize the oldest span is dropped to keep the harness responsive — not a sign of a network failure.
• Version drift. Outside >=0.1.0-rc.6 <0.2.0 the lifecycle hooks may not fire, so traces can silently not appear.
• Secrets in config. Prefer a secret manager for CLS_SECRET_ID / CLS_SECRET_KEY over committing them to cordis.patch.yml.

FAQ

What does deepseek harness observability mean in practice?

It means capturing the full lifecycle of a DeepSeek Harness run — session, agent invocation, each ReAct step, LLM calls, and tool executions — as structured trace spans so you can inspect latency, token usage, and errors per agent turn.

Does the TencentCloud AgentObs SDK require an OTLP collector?

No. It uploads GenAI trace spans directly to Tencent Cloud Log Service via Protobuf using tencentcloud-cls-sdk-js. There is no OTLP collector, sidecar, or extra backend to deploy.

What span hierarchy does the plugin produce for a single DSH turn?

Each turn produces an ENTRY span containing an AGENT span, which contains STEP spans per ReAct round. Each STEP in turn has CHAT (model) and TOOL (tool execution) children, following Tencent Cloud’s 5-layer entry → agent → step → chat → tool model.

Is prompt and tool content captured by default?

Yes, content capture is enabled by default, attaching prompts, responses, and tool arguments to spans. Disable it with captureContent: false or the OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=false environment variable.

Which DeepSeek Harness versions does the plugin support?

It supports DeepSeek Harness >=0.1.0-rc.6 and <0.2.0, with Node.js >=18.0.0. It is Apache-2.0 licensed and written in TypeScript.

What Is dsh-whale-meter and Why You Need It Now (Post-8-17 Price Hike Context)

DeepSeek Harness is a powerful agentic coding harness, but for a long time it gave users almost no visibility into how many tokens they were actually consuming or what those tokens cost. That gap is exactly what dsh-whale-meter (仓库: Shiye-10Pages/dsh-whale-meter) was built to close. It is a native DSH plugin written in TypeScript under an MIT License, released on August 16, 2026, with a design goal of “one-line install, zero config, all data local.”

The timing is not accidental. On August 17, 2026, DeepSeek raised the prices of v4-flash and v4-pro and, for the first time, introduced peak/off-peak billing in China. That single change turned token spend from a background curiosity into a line item you must actively manage. As the broader industry scramble shows, teams are routinely blowing through their token budgets — TechCrunch reported in June 2026 that many teams were running at 3x their 2026 token budgets by April, with individual engineers seeing monthly token spikes in the $40,000 range. The days of “just let the model run” are over.

dsh-whale-meter answers the three questions every heavy DSH user now asks daily: How many tokens am I using? What am I actually spending? Is my usage tier creeping toward the top?

Key Features — Token Usage Tiers, Cost Dashboard, and the Whale Score Card

The headline feature is a gamified usage ladder with five tiers:

Each tier carries an estimated percentile — the project is careful to label this as an estimate, not a claimed global rank — plus a playful magnitude conversion that frames your usage as “≈ N reads of Three-Body.” It turns an abstract number of tokens into something you can actually feel.

The cost dashboard is the practical workhorse. It reports spend across four time windows — today, yesterday, month, and cumulative — in CNY by default, swappable to USD. Costs are estimated from the official DeepSeek pricing pages, so they track the real tariff rather than a stale hardcoded rate.

Two features make the dashboard genuinely useful rather than decorative:

• 8-17 price-hike comparison. The same usage is priced side-by-side under the old and new tariffs. Pre-August-17 usage is shown as a preview of what it would have cost under the new rate; post-August-17 usage gets a retroactive back-calculation of what it would have cost under the old rate. This makes the real impact of the hike measurable in one glance.
• Cross-price-day correctness. Price tables are organized by effective date ranges, so historical bills are never mis-computed against today’s rates.

How the 8-17 Price Change Works (v4-flash / v4-pro, Peak vs Off-Peak, Before-After Compare)

The August 17 change has two parts: a price hike and a new peak/off-peak structure. Both are baked into the whale-meter’s built-in price table (version 2026-08-16 already contains the new rates).

For v4-flash (per million tokens, cache miss), the changes are:

v4-pro adjusted in parallel: peak pricing of ¥0.30 / ¥9 / ¥27 (hit / miss / output), with off-peak exactly half. Peak hours are Beijing 9:00–12:00 and 14:00–18:00.

The non-obvious point most guides get wrong is this: even if you run entirely off-peak, the off-peak rate is still more expensive than the old flat pre-8-17 price. Look at the v4-flash table above — the off-peak miss rate of ¥1.50 beats the old ¥1.00 flat rate, and off-peak output at ¥4.50 is more than double the old ¥2.00. Off-peak is a discount relative to the new peak rate, not a return to the old prices. The whale-meter makes this visible with a ⚡½ badge shown during off-peak hours, and its before/after comparison panel surfaces exactly how much the hike costs you even on the cheapest schedule.

Multi-Vendor Precision Pricing: 46 Models Across 6 Providers, Including China Tiered Rates

whale-meter is not limited to DeepSeek. It ships with a pricing database covering 46 models across 6 vendors: DeepSeek, Anthropic, OpenAI, Google, Zhipu GLM, and Moonshot Kimi. Every model is itemized against the official pricing pages.

What sets it apart from most generic cost tools is how it handles tiered pricing from Chinese vendors, which most trackers simply ignore:

• GLM-5.1 input is priced by context length: <32K tokens costs ¥6, ≥32K costs ¥8 per million.
• GLM-4.7 sub-divides even further, tiering by output length.

Because the tier boundary depends on per-call context size, a flat price-table lookup produces wrong numbers. whale-meter applies the correct tier per call. When a model is not yet in the table, it is explicitly marked unpriced rather than silently estimated — an honest design choice that prevents fabricated cost figures.

Privacy & Data Locality: Fully On-Device, No Telemetry, Raw-Token-Only Storage

Privacy is a first-class design constraint, and it is the sharpest contrast with cloud-based dashboards. Everything runs on-device:

• Usage is stored in ~/.dsh/whale-meter/usage-YYYY-MM.jsonl.
• Only raw token counts are persisted — monetary amounts are recomputed on read, so no dollar figures are ever frozen into storage.
• There are no network requests except the optional balance query you explicitly enable.
• There is no telemetry of any kind.

For a tool that sits next to all of your agent activity, this matters. A cloud dashboard necessarily exfiltrates at least aggregate usage data; whale-meter keeps the entire ledger local. The raw-token-only design also means a later price change can be applied retroactively to historical usage without storing contradictory amounts.

Installation and Configuration (dsh plugin, zero-config, cordis.patch.yml options)

Installation is a single command. If you run DSH with a profile:

dsh plugin --profile <profile> add dsh-whale-meter

There is a web panel for TUI or headless setups at http://127.0.0.1:3080/whale-meter/api/summary. Configuration options live in cordis.patch.yml, letting you tweak behavior without touching source code. The project’s stated goal is zero-config for the common case: install, open the panel, and you immediately see your tiers and spend.

Limitations and Honest Caveats (Estimates Not Exact, Unknown Models Marked Unpriced, Community Plugin)

No cost tracker is perfect, and whale-meter is transparent about its boundaries:

• Costs are estimates, not invoices. Prices are drawn from official pages, but actual billing can differ due to rounding, promotions, or regional rules. Treat the dashboard as a budgeting guide, not an accounting record.
• Unknown models are marked unpriced. If whale-meter hasn’t been updated for a newly released model, it will not invent a price — you’ll see it flagged instead.
• It’s a community plugin. The repo is young (created August 16, 2026, roughly 3 stars at time of research) and MIT-licensed. You’re relying on an actively maintained community project rather than an official DeepSeek product.
• Tiers are percentile estimates, not confirmed global rankings. They give you a feel for where you sit, but “blue whale” is descriptive, not audited.

dsh-whale-meter vs Alternative Cost-Tracking Tools (CacheLens, AgentLedger, Agentic Metric)

How does the DSH-native plugin compare to the wider field of agent cost trackers?

The trade-off is clear. Generic proxy and ledger tools (CacheLens, AgentLedger, Agentic Metric) are broader — AgentLedger, for instance, tracks every real-world agent action with sub-second SSE latency rather than just LLM calls. But they require integration, a proxy, or an SDK, and they don’t understand DSH’s internals. whale-meter’s advantage is that it is a zero-config native plugin: no proxy to configure, no SDK to wire in, and it inherently knows the DSH data layout. If you’re all-in on DSH, the plugin approach wins on speed and locality; if you span many tools, a broader tracker makes more sense.

Verdict and Roadmap

For anyone running DeepSeek Harness seriously, dsh-whale-meter earns its place immediately. The 8-17 price hike means running blind on tokens now costs real money — and the peak/off-peak structure adds a scheduling decision you can only make with a meter. The gamified tiers make the abstract tangible, the before/after price comparison makes the hike measurable, and the fully-local, no-telemetry design makes it trustworthy.

The roadmap points in sensible directions: CSV/Markdown export for records and reporting, off-peak scheduling suggestions to help you shift work into the half-price window, and an enhanced TUI. Combined with the cache-ledger view — whose value grows after the hike, since the cache hit/miss price gap widened — these additions would round it into a complete cost-control tool.

If you use DSH and haven’t looked at your token bill yet, now is the moment. Install whale-meter, read your tier, and schedule your heavy runs off-peak. Your wallet will thank you.

FAQ

What exactly does dsh-whale-meter track? It tracks your DeepSeek Harness token usage across five gamified tiers (🐟 small fry through 🐳 blue whale) and estimates your cost over today, yesterday, the current month, and cumulative totals, in CNY or USD.

How does the 8-17 DeepSeek price change work? On August 17, 2026, DeepSeek raised v4-flash and v4-pro prices and introduced peak/off-peak billing. Peak hours are Beijing 9:00–12:00 and 14:00–18:00; off-peak costs exactly half the peak rate but is still more expensive than the old flat pre-8-17 price.

Is whale-meter data private? Yes. All data is stored locally in ~/.dsh/whale-meter/usage-YYYY-MM.jsonl, only raw token counts are persisted, and there is no telemetry or network traffic except an optional balance query you enable manually.

Does whale-meter support models beyond DeepSeek? Yes. It covers 46 models across 6 vendors — DeepSeek, Anthropic, OpenAI, Google, Zhipu GLM, and Moonshot Kimi — including China vendors’ tiered pricing such as GLM-5.1’s <32K vs ≥32K input rates.

Is whale-meter free and where do I get it? It is an MIT-licensed open-source project at Shiye-10Pages/dsh-whale-meter. Install with dsh plugin --profile <profile> add dsh-whale-meter, then open the web panel at http://127.0.0.1:3080/whale-meter/api/summary.

What is DeepSeek Harness and why it needs tracing

DeepSeek Harness is the official open-source agent framework from DeepSeek, written in TypeScript with the tagline “Everything is a Plugin.” Its official repository has roughly 123,000 GitHub stars, making it one of the most popular agent harnesses in the ecosystem. The framework orchestrates multi-step agent loops: it plans, calls LLMs, invokes tools, spawns subagents, and retries failed steps. Each of those steps is a potential failure point, and without tracing you are effectively debugging a black box.

Agent loops are non-deterministic. A single user request can trigger dozens of LLM calls, tool invocations, and retries, and the failure often lives in the interaction between them rather than in any single call. Traditional logging gives you a flat stream of text with no causal structure. OpenTelemetry tracing gives you a hierarchical span tree that shows exactly which step produced which LLM call, which tool ran under which step, and which retries happened along the way.

For DeepSeek Harness specifically, tracing matters because of its plugin architecture. Because “everything is a plugin,” the harness exposes a public telemetry seam that any plugin can implement. That means you are not locked into a single vendor’s exporter. You can swap the official OTLP-logs exporter for a community OTLP-traces plugin without forking the harness, and you can point the output at whichever backend your team already runs.

Understanding the telemetry seam (@deepseek-ai/dsh-session-telemetry)

The key architectural fact is that DeepSeek Harness ships a public telemetry seam called @deepseek-ai/dsh-session-telemetry. This is the contract that plugins implement to receive session, agent-loop, LLM-stream, and tool-lifecycle events. The official repository also ships an OTLP-logs exporter that implements this seam.

Community plugins implement the same seam as alternative backends. Instead of exporting logs, they convert the events into OpenTelemetry GenAI traces and metrics. Because they implement the same interface, you can drop them in without modifying the harness source code.

There is one critical gotcha: the telemetry seam accepts exactly one backend per context. If you load a duplicate backend — for example, the official OTLP-logs exporter and a tracing plugin at the same time — the load throws an error. You must choose one backend per context, not stack them.

Choosing an OpenTelemetry backend (Jaeger, Grafana Tempo, SigNoz, Langfuse)

Because the plugins export standard OTLP/HTTP protobuf, you can send traces to any compatible backend. The table below compares the most common choices.

The GenAI semantic conventions (semconv) are what make these traces portable. They standardize LLM span attributes — model name, provider, token usage, prompt and completion — so the same trace renders meaningfully in Jaeger, Tempo, SigNoz, and Langfuse alike. If you already run one of these backends, you do not need to stand up a new one.

Installing a dsh OpenTelemetry tracing plugin

The most popular community options are loongsuite/dsh-plugin, linyp/dsh-plugin-langfuse, CodePrometheus/dsh-observability, and TtTRz/dsh-langfuse. All of them implement the telemetry seam and export OTLP traces. The table below summarizes their differences.

Before installing, verify your environment meets the requirements. The telemetry plugins require Node.js version 22.19.0 or higher and a DeepSeek Harness version of at least 0.1.0-rc.6 and below 0.2.0. If your harness is older or newer than that range, the plugin may not load.

Installation is typically done as a profile bundle. For example, the Langfuse plugin installs via a cordis.patch.yml profile bundle, and it reads the LANGFUSE_HOST environment variable rather than LANGFUSE_BASE_URL. Check each plugin’s README for the exact install command, because the bundle mechanism differs slightly between plugins.

Configuring OTLP export and privacy modes (FULL / FEEDBACK_ONLY / DISABLED)

Privacy is a first-class concern in these plugins. The design principle is that sharing stays off until a mode explicitly says otherwise, and configuring an endpoint is not consent to upload session content. You must opt in to each level of data sharing.

The CodePrometheus/dsh-observability plugin exposes three modes through the DSH_OBSERVABILITY_MODE environment variable:

• FULL — exports the complete session content, including prompts, completions, and tool payloads. Use this only for backends you trust and for data you are allowed to share.
• FEEDBACK_ONLY — exports only feedback and scoring data, without the underlying session content. This is a middle ground for teams that want evaluation signals without shipping raw prompts.
• DISABLED — turns off sharing entirely. This is the safe default.

You also configure the OTLP endpoint, typically through a variable such as DSH_OBSERVABILITY_OTLP_URL or the plugin’s own endpoint setting. The endpoint points at your chosen backend’s OTLP/HTTP receiver. Remember that setting the endpoint alone does not enable content sharing; the mode controls that.

Reading the GenAI trace tree (ENTRY -> AGENT -> STEP -> LLM/TOOL)

The trace shape is the most valuable part of the setup. The loongsuite/dsh-plugin exports a hierarchy of ENTRY -> AGENT -> STEP -> LLM/TOOL. Here is what each level means:

• ENTRY — the root span for a session or a top-level request.
• AGENT — the agent loop that orchestrates the work.
• STEP — a single planning or execution step within the loop.
• LLM/TOOL — the individual LLM call or tool invocation that ran under that step.

The critical design detail is that each real LLM attempt gets its own LLM span. If the harness retries a failed LLM call, each retry appears as a separate span under the same step. This keeps retries and tool fallbacks visible under the same step, which is exactly what you need when debugging flaky agent loops. Instead of seeing one opaque “LLM call failed” message, you see the full sequence of attempts and their individual latencies and token usage.

Subagent sessions create their own trace and carry DeepSeek Harness parent-session and delegation attributes. This preserves fork and subagent lineage, so you can follow a request from the parent session down into each delegated subagent and back.

The plugins also export GenAI metrics. The loongsuite/dsh-plugin exports gen_ai.client.operation.duration and gen_ai.client.token.usage, giving you latency and token-cost telemetry alongside the traces.

Troubleshooting common issues (duplicate backend, version compatibility, restart required)

The most common problems fall into three buckets.

Duplicate backend error. Because the telemetry seam accepts exactly one backend per context, loading the official OTLP-logs exporter and a tracing plugin together throws an error. Remove or disable the official exporter before loading a tracing plugin. If you need both logs and traces, choose one backend that handles both, or run them in separate contexts.

Version incompatibility. The plugins require Node.js 22.19.0+ and DSH between 0.1.0-rc.6 and 0.2.0. If the plugin fails to load, check your Node and harness versions first. A harness outside the supported range will reject the plugin.

Restart required. Telemetry backends are typically loaded at startup. After installing a plugin or changing a mode or endpoint variable, restart the harness so the new backend is picked up. A running session will not hot-reload the telemetry seam.

No traces appearing. If your backend shows no traces, verify the OTLP endpoint is reachable, confirm the mode is not DISABLED, and check that the plugin actually loaded without a duplicate-backend error. Also confirm the backend’s OTLP/HTTP receiver is enabled, since some backends disable it by default.

FAQ

What is OpenTelemetry tracing for DeepSeek Harness? It is a way to export DeepSeek Harness agent sessions, LLM calls, and tool invocations as standard OTLP trace trees to backends like Jaeger, Grafana Tempo, SigNoz, or Langfuse, using community plugins that implement the official telemetry seam.

Which DeepSeek Harness versions support OpenTelemetry tracing plugins? The telemetry plugins require Node.js 22.19.0 or higher and a DeepSeek Harness version of at least 0.1.0-rc.6 and below 0.2.0.

Can I use OpenTelemetry tracing with Langfuse? Yes. Plugins like linyp/dsh-plugin-langfuse and TtTRz/dsh-langfuse export each session or turn as an OpenTelemetry trace to Langfuse’s OTLP endpoint, including feedback scores and subagent lineage.

Why do I get a duplicate backend error when installing a tracing plugin? The @deepseek-ai/dsh-session-telemetry seam accepts exactly one backend per context. If you load the official OTLP-logs exporter and a tracing plugin together, the load throws an error. Remove the official exporter before loading a tracing plugin.

How do privacy modes work in DeepSeek Harness tracing plugins? Plugins like CodePrometheus/dsh-observability use modes such as FULL, FEEDBACK_ONLY, and DISABLED. Sharing stays off until a mode explicitly enables it, and configuring an endpoint is not consent to upload session content.

What is DeepSeek Harness and why it needs a TUI

DeepSeek Harness (deepseek-ai/deepseek-harness) is the official open-source agent runtime from DeepSeek, and it is built around a simple but powerful philosophy: “Everything is a Plugin.” As of August 15, 2026, the repository holds 111,829 stars and 10,833 forks, making it one of the most-watched agent frameworks on GitHub. The harness is not a monolithic IDE; it is a modular runtime where prompts, tools, context providers, and even the user interface are all swappable plugins.

That modularity is exactly why a terminal UI matters. The stock dsh CLI is a capable but bare command-line interface. When you are running long agent sessions, reviewing tool calls, steering mid-turn, and inspecting reasoning traces, a plain prompt loop gets cramped. A TUI — a terminal user interface — gives you a full-screen workspace without leaving the terminal. It keeps the zero-chrome, scriptable, git-native workflow that terminal users prefer, while adding the visual density of an IDE.

The ecosystem has responded with at least five community TUI implementations. The most prominent is dsh-tianshu-tui, an official plugin by huiliyi37 that evolved from the Tianshu-Tui rendering core. It is the subject of this review.

dsh-tianshu-tui at a glance — the plugin that turns dsh into a terminal workspace

dsh-tianshu-tui is an npm package (@huiliyi37/dsh-tianshu-tui, Apache-2.0) that installs as a profile plugin for the official DeepSeek Harness CLI. It was created on August 13, 2026, and already has 158 stars and 6 forks, with the latest npm release at 0.1.2-rc.7 (August 15, 2026). The project co-evolved with the harness itself, accumulating 250+ commits between August 10 and August 13 on the August 9 baseline snapshot.

The key architectural decision is that the TUI is a pure display layer. It registers no prompts, no tools, and no context. Every piece of agent state — reasoning, tool calls, replies, subagent lifecycles — is derived from the session event stream. This means the TUI cannot interfere with the agent’s behavior; it only renders what the harness already produces. That is a deliberate contrast to monolithic AI IDEs, where the interface and the agent logic are tightly coupled.

The result is a full in-terminal workspace with:

• Live rendering of the agent’s activity
• Session restore across restarts
• /fork and /rewind for branching and replaying sessions
• /export to Markdown
• /steer for mid-turn steering

Installation and setup

Installing dsh-tianshu-tui requires three things: the official CLI, a recent Node.js, and pnpm.

Requirements:

The install command is a single line:

npx -y @deepseek-ai/dsh plugin --profile tui add @huiliyi37/dsh-tianshu-tui

This adds the plugin to the tui profile. You then launch the TUI through that profile.

Common pitfalls. The review notes two recurring install failures. The first is ERR_FS_EISDIR, which typically appears when the plugin path is misconfigured or a stale directory is being treated as a file. The second is a “stale dsh” problem, where an older CLI version is still on PATH and the plugin refuses to load. Both are resolved by pinning the official CLI to exactly 0.1.0-rc.6 and ensuring pnpm is reachable. Because the plugin co-evolves rapidly with the harness, keeping the CLI version in sync matters more than with a stable tool.

Core features — session workspace, images, input, and reasoning

Once running, dsh-tianshu-tui provides a dense but navigable interface. The core features fall into four groups.

Session workspace. The TUI supports live rendering, session restore, /fork, /rewind, and /export to Markdown. You can branch a session to try a different approach, rewind to an earlier checkpoint, and export the full transcript for sharing or documentation. /steer lets you redirect the agent mid-turn without killing the run.

End-to-end images. The plugin handles images from clipboard to inline render. You can paste an image from the clipboard, and it renders inline using the kitty or iTerm2 graphics protocol. The standout feature is the vision bridge: when the main model cannot see images, the TUI auto-detects an auxiliary vision model and routes image understanding through it, with graceful degradation if none is available. This is a practical solution to the common problem of a text-only main model being asked to reason about a screenshot.

Complete input surface. The input layer is grok-style: a slash menu for commands, @-path tab completion, bracketed paste support, optional vim keys, an external editor via Ctrl+E, and history search via Ctrl+F. For heavy terminal users, the vim keybindings and external editor integration make long sessions far more comfortable.

Reasoning visualization. The think channel streams live, then folds into compact rows to keep the screen readable. Ctrl+O expands a reasoning block inline when you want to inspect the model’s chain of thought. This is a meaningful improvement over a plain chat UI, where reasoning either floods the screen or is hidden entirely.

Harness-engineering differentiators — TDD evidence gate, memory, code intelligence

Beyond rendering, dsh-tianshu-tui exposes several harness-engineering features that set it apart from a plain chat interface.

TDD-driven workflow and evidence gate. The plugin supports a RED-first verification workflow: write a failing test, watch it fail, then implement until it passes. The evidence gate is an obligation state machine that tracks what must be verified before a task is considered done. If verification fails, the run is routed to failure handling rather than silently continuing. This is a real differentiator from chat UIs, which have no notion of “prove it works.”

Memory and cross-session recall. The /memory command opens a project memory browser, and the underlying Tianshu-Tui core uses a Stigmergy (pheromone) self-decaying memory model. This shifts the tool from a stateless chat to a persistent agent partner that remembers context across sessions.

Code intelligence and git tools. The plugin integrates code intelligence retrieval and git tooling, so you can inspect repository context and manage version control from within the TUI.

Personalized harness integration. A /doctor command runs diagnostics, /btw spawns a background agent, and /model plus /effort let you hot-switch models and effort levels mid-session.

The prefix-cache advantage — 95-99% hit rate and what it saves you

One of the most compelling technical details is the prefix-cache engineering in the Tianshu-Tui rendering core. In long sessions, the core reports a steady-state prefix-cache hit rate of 95-99% on DeepSeek V4.

What does that mean in practice? Prefix caching means the model provider does not recompute the shared prefix of a conversation on every request. When the hit rate is high, the cost and latency of each turn drop dramatically, because only the new tokens need to be processed. In a long agent session where the conversation history grows large, a 95-99% hit rate is the difference between a responsive, cheap workflow and one that degrades into slow, expensive recomputation.

This is a hidden cost lever that most TUI reviews miss. The interface itself does not save tokens, but by keeping sessions long-lived and well-structured, it maximizes the prefix-cache benefit. For teams running DeepSeek V4 at scale, this is a real operational advantage.

How it compares to other DeepSeek Harness TUIs

dsh-tianshu-tui is not the only TUI in the ecosystem. Here is how it stacks up against the main alternatives.

Tianshu-Tui is the rendering core that dsh-tianshu-tui evolved from. It is a full standalone terminal coding agent runtime with 229 stars, 13,000+ passing tests, and the Stigmergy memory model. If you want the complete runtime rather than a plugin for the official harness, this is the base.

openma-ai/deepseek-harness-tui is the Rust/ratatui option. It is lighter on features but strong on image handling (up to 8 images per prompt) and exposes token and cache metrics. It runs either as a dsh profile plugin or directly against the SDK JSON-RPC runtime.

gxinxing/deepseek-harness-tui is deliberately minimal — about 800 lines of Ink (React for terminals). It is a thin, readable UI that folds tool calls into cells and derives its theme from your terminal via an OSC 11 probe. It is the choice for users who want the least chrome possible.

oh-dsh takes a different approach: it packages the DSH runtime into Desktop, Web, and TUI distributions with a shared plugin marketplace and a Git Review sidebar. If you want the same sessions across a desktop app, a browser, and a terminal, oh-dsh is the unified option.

Who should use it and who should wait

dsh-tianshu-tui is best for developers who already live in the terminal and run DeepSeek Harness for real agent work — especially those doing TDD, long multi-turn sessions, or image-heavy tasks where the vision bridge matters. The prefix-cache benefit and the evidence gate make it a strong fit for teams that care about cost and verifiability.

You might wait if you prefer a minimal UI (gxinxing’s Ink plugin), need a full standalone runtime (Tianshu-Tui), want multi-form Desktop/Web/TUI access (oh-dsh), or need the Rust/ratatui stack with heavy image staging (openma). Because the plugin is young and co-evolves rapidly with the harness, you should also be comfortable with frequent updates and the CLI version pin.

Verdict and final thoughts

dsh-tianshu-tui is a well-engineered, feature-complete terminal UI for DeepSeek Harness. Its decision to be a pure display layer is the right one: it stays out of the agent’s way while giving you a dense, navigable workspace. The vision bridge, TDD evidence gate, memory browser, and 95-99% prefix-cache hit rate are genuine differentiators, not cosmetic additions.

The main caveats are the young age of the project and the install friction around the CLI version pin. But for terminal-native DeepSeek Harness users, dsh-tianshu-tui is currently the most complete and polished option in the ecosystem. If you run dsh for serious agent work, it is worth installing today.

FAQ

What is the DeepSeek Harness terminal UI? It is a TUI plugin (dsh-tianshu-tui) that turns the DeepSeek Harness CLI into a full interactive terminal workspace with live rendering, session restore, image support, and a TDD evidence gate.

How do I install dsh-tianshu-tui? Run npx -y @deepseek-ai/dsh plugin --profile tui add @huiliyi37/dsh-tianshu-tui. You need the official CLI @deepseek-ai/dsh 0.1.0-rc.6, Node.js ^22.19 or >=24, and pnpm on PATH.

Does dsh-tianshu-tui change how the agent behaves? No. It is a pure display layer that derives all state from the session event stream and registers no prompts, tools, or context, so it cannot alter agent behavior.

What is the vision bridge? When the main model cannot see images, the TUI auto-detects an auxiliary vision model and routes image understanding through it, with graceful degradation if none is available.

What is the prefix-cache hit rate and why does it matter? The Tianshu-Tui core reports a 95-99% steady-state prefix-cache hit rate on DeepSeek V4 in long sessions, which cuts token cost and latency by avoiding recomputation of the shared conversation prefix.