openma-ai/deepseek-harness-typescript-sdk
TypeScript SDK for DeepSeek Harness (dsh) — drive AI agent turns in a runtime subprocess over JSON-RPC stdio. Mirrors the official Python SDK.
安装Install
dsh plugin --profile web add github:openma-ai/deepseek-harness-typescript-sdk把 openma-ai/deepseek-harness-typescript-sdk 加入你的 DSH 配置（web profile）即可启用。
READMEREADME
DeepSeek Harness TypeScript SDK
English | 中文
TypeScript / Node.js SDK for DeepSeek Harness (dsh), the open-source AI agent harness by DeepSeek: run coding-agent turns in a runtime subprocess over newline-delimited JSON-RPC stdio. A standalone implementation referencing the upstream packages/sdk/{protocol,client} packages and mirroring the official Python SDK's (python/sdk) API surface.
The runtime inherits normal DeepSeek Harness environment variables such as DEEPSEEK_BASE_URL and DEEPSEEK_API_KEY, so callers can use real model endpoints directly or point those variables at a local proxy.
Install
npm install @openma/deepseek-harness-sdk
Quick start
import { DeepSeekHarness } from '@openma/deepseek-harness-sdk'
await using harness = new DeepSeekHarness()
const result = await harness.run('Say hi.')
console.log(result.finalResponse)
DeepSeekHarness keeps its lazily started runtime subprocess for reuse across calls. Use it with await using, as above, or call close() explicitly when finished so the child is always reaped.
Features
- High-level turns API —
DeepSeekHarness.run()sends a prompt and resolves with the final assistant response, finish reason, and the full event/notification stream of the owned activity interval - Low-level protocol client —
HarnessClientfor raw JSON-RPC requests, notification subscriptions, and session-tree scoping - Faithful to the official protocol — a standalone mirror of the upstream wire types and run semantics, API-aligned with the official Python SDK (
deepseek-harness-sdkon PyPI) - Robust process ownership — lazy spawn, protocol
shutdown, and an stdin-EOF → SIGTERM → SIGKILL teardown ladder with exit-code + stderr-tail diagnostics - Subagent aware — descendant sessions discovered from
subagent.startedlineage are streamed alongside the root session, while root events stay authoritative - Zero runtime dependencies — Node.js ≥ 20, ESM, strict TypeScript types throughout
Runtime selection
The SDK spawns a DeepSeek Harness runtime process that serves the SDK protocol (the @deepseek-ai/dsh-sdk-jsonrpc-server plugin must be part of its composition). A launch resolves in this order:
launchArgsOverride— a full argv, verbatim.runtimeBin— a single runtime executable (for example a packageddsh-jsonrpc-agent-pkg-<platform>-<arch>exe).- The
DSH_RUNTIME_BINenvironment variable. - An installed
@deepseek-ai/dsh-sdk-jsonrpc-demopackage, launched asnode <https://github.com/openma-ai/deepseek-harness-typescript-sdk/blob/HEAD/bin.js>. When that package ships a bundled default composition (runtime/cordis.yml), its path is injected viaDSH_CORDIS_CONFIGfor zero-config runs — only when you set no non-empty config of your own.
The runtime itself always demands an explicit Cordis composition and exits loudly without one, so with routes 1–3 (and route 4 without a bundled default) pass the config through the cordis option or DSH_CORDIS_CONFIG. The upstream jsonrpc-agent example owns a complete standalone composition.
import { DeepSeekHarness } from '@openma/deepseek-harness-sdk'
await using harness = new DeepSeekHarness({
provider: 'deepseek-official',
model: 'deepseek-v4-flash',
maxTokens: 49_152,
cwd: '/absolute/path/to/workspace',
sessionRoot: '/absolute/path/to/sessions',
cordis: 'examples/jsonrpc-agent/cordis.yml',
runtimeBin: '/path/to/dsh-jsonrpc-agent',
})
const result = await harness.run('Make the requested code change.', { sessionId: 'example-001' })
console.log(result.finalResponse, result.finishReason)
provider selects a provider route registered by the chosen Cordis composition; model is the model id resolved by that adapter. maxTokens is an optional positive per-request output-token cap for the root agent and its in-process descendants; omission leaves the provider default in control.
Options
| Option | Effect |
|---|---|
provider / model / maxTokens |
The route sent in the initialize handshake (defaults deepseek-official / deepseek-v4-flash) |
cwd |
Agent workspace, resolved to an absolute path; sent as the wire cwd and injected as DSH_CWD |
runtimeCwd |
Working directory of the runtime process itself (default: cwd) |
sessionRoot |
Injected as DSH_SESSION_ROOT (JSONL session directory) |
cordis |
Injected as DSH_CORDIS_CONFIG (Cordis composition path) |
env |
Variables merged over the inherited parent environment |
baseUrl / apiKey |
Injected as DEEPSEEK_BASE_URL / DEEPSEEK_API_KEY |
runtimeBin / launchArgsOverride |
Explicit runtime launch (disables default resolution and config injection) |
requestTimeoutMs |
Per-request timeout; undefined waits indefinitely (a turn can legitimately run long) |
shutdownTimeoutMs |
Bound on the protocol shutdown exchange inside close() (default 1000) |
disposeEofGraceMs / disposeGraceMs |
Grace windows of the stdin-EOF → SIGTERM → SIGKILL teardown ladder |
Run semantics
HarnessSession.run() owns an activity interval from its prompt's durable inbox receipt through the next whole-agent idle and returns RunResult { sessionId, finalResponse, finishReason, events, notifications, sessionRoot }.
finalResponseis the last committed root-session assistant text in the interval.finishReasonis thekindof the last root-sessionturn/endin the interval —completed,max-tokens,error, ... — andundefinedwhen no turn ended. Aturn/endwithout a stringdata.reason.kindviolates the runtime protocol and throwsSdkProtocolError.eventscontains root-session events only, so descendant messages cannot replace the root response.notifications(and theonNotificationobserver) receive the root session and all known descendant notifications in wire order, including nested subagent lifecycle and session events.
Both result fields describe the owned interval rather than an output causally assigned to the prompt: steering, injected context, and other queued work may contribute before idle.
const session = harness.session('session-001') // stable id; reused across runs
const first = await session.run('Inspect the repository.')
const second = await session.run('Now fix the failing tests.', {
onNotification: (notification) => console.error(notification.method),
})
Low-level client
HarnessClient is the lower-level JSON-RPC client underneath DeepSeekHarness: it owns the child process, speaks the wire protocol, and fans notifications out to subscriptions. The low-level prompt() returns the queued message id immediately; callers that bypass run() own any later activity boundary themselves.
import { HarnessClient } from '@openma/deepseek-harness-sdk'
const client = new HarnessClient({ command: '/path/to/dsh-jsonrpc-agent', env: { ...process.env, DSH_CORDIS_CONFIG: 'cordis.yml' } })
await client.initialize({ cwd: process.cwd(), provider: 'deepseek-official', model: 'deepseek-v4-flash' })
const subscription = client.subscribeSessionTree('session-a')
const messageId = await client.prompt('session-a', [{ type: 'text', text: 'Say hi.' }])
for await (const notification of subscription) {
console.log(notification.method)
if (notification.method === 'session.status' && notification.params.status === 'idle') break
}
await client.close()
Errors all extend HarnessError: TransportClosedError (runtime gone, with exit code + stderr tail), RequestTimeoutError, SdkProtocolError (wire shape violations), JsonRpcResponseError (protocol error responses, preserving code/data), and RuntimeResolutionError (no runtime found).
Wire protocol
Requests: initialize → { serverInfo }, session/prompt → { messageId }, shutdown → {}. Server notifications: session.event, session.status, subagent.started, subagent.finished. See src/protocol.ts for the named payload types; serverInfo.name stays the wire-stable deepseek-harness-sdk-runtime.
Development
npm install
npm run typecheck
npm test # runs against a scripted fake runtime; no network or model needed
npm run build
License
相关推荐Related
- deepseek-ai/deepseek-harness DeepSeek Harness: Everything is a Plugin.
- deepseek-ai/deepseek-harness DeepSeek Harness (dsh) — 由 DeepSeek AI 开发的开源 agent harness（智能体框架）。一切皆插件：核心 + 插件 + 技能 = 可热插拔的 AI 编程工作台。DeepSeek Harness: …
-
nexu-io/open-design
🎨 Best DeepSeek Harness Design Plugin. The open-source Claude Design alternative. 🖥️ Local-first desktop app. 🖼️ Your…
-
ruvnet/ruflo
🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build c…
-
amruthpillai/reactive-resume
A one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source a…
-
esengine/DeepSeek-Reasonix
DeepSeek-native AI coding agent for your terminal. Engineered around prefix-cache stability — leave it running.
-
volcengine/OpenViking
Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
-
Molunerfinn/PicGo
:rocket: The Ultimate Image Uploader for Efficient Creators. Supports Obsidian, Typora, VS Code etc. and 60+ image hosti…