DeepSeek Harness Go SDK

English | 中文

Go SDK for driving DeepSeek Harness. The SDK starts the Harness runtime as a
subprocess and speaks the line-delimited JSON-RPC 2.0 protocol over stdio. It
is a clean-room Go implementation of the protocol and mirrors the layering and
activity semantics of the upstream Python SDK.

Requirements

• Go 1.26 or newer.
• macOS arm64 or Linux amd64/arm64 when using the bundled runtime downloader.
• A DEEPSEEK_API_KEY environment variable, unless the selected Cordis
  composition uses another credential path or a local model proxy.

Install

go get github.com/theoneLee/deepseek-harness-sdk-go

The SDK targets the single-file runtime published by the DeepSeek Harness
project. With no explicit executable, the first Start or Run resolves the
matching platform wheel from a PyPI-style index, verifies SHA-256, extracts it
into a cache, and reuses it on later starts. The default target is runtime
0.1.1-rc.2, corresponding to upstream tag dsh-v0.1.1-rc.2.

Quick start

package main

import (
    "fmt"

    deepseekharness "github.com/theoneLee/deepseek-harness-sdk-go"
)

func main() {
    harness := deepseekharness.NewDeepSeekHarness()
    defer harness.Close()

    result, err := harness.Run("Say hi.")
    if err != nil {
        panic(err)
    }
    fmt.Println(result.FinalResponse)
}

DeepSeekHarness starts lazily and keeps the subprocess alive across runs.
Always call Close when the harness is no longer needed so the runtime is
reaped promptly.

Configuration

harness := deepseekharness.NewDeepSeekHarness(deepseekharness.DeepSeekHarnessConfig{
    Provider:   "deepseek-official",
    Model:      "deepseek-v4-flash",
    MaxTokens:  49_152,
    Cordis:     "examples/jsonrpc-agent/cordis.yml",
    SessionRoot: ".dsh-sessions",
})
defer harness.Close()

The runtime inherits the parent environment. Env overlays it for the child;
BaseURL and APIKey are convenience fields for
DEEPSEEK_BASE_URL and DEEPSEEK_API_KEY. CWD becomes DSH_CWD and the
initialize payload; RuntimeCWD controls the subprocess working directory.
MaxTokens == 0 omits maxTokens from initialize.

Launch channels are resolved from most explicit to least explicit:

1. LaunchArgsOverride.
2. Command with Args.
3. RuntimeBin or BridgeBin.
4. DSH_RUNTIME_BIN.
5. The bundled runtime downloader.

Explicit launch channels do not inject a downloaded default cordis.yml.
When the downloader is selected, its default configuration is injected through
DSH_CORDIS_CONFIG only when that variable is absent or empty.

Sessions and results

session, err := harness.StartSession("session-reuse")
if err != nil {
    panic(err)
}

result, err := session.Run(
    deepseekharness.BlocksInput([]deepseekharness.JSONObject{
        {"type": "text", "text": "Inspect this task."},
    }),
    func(notification deepseekharness.Notification) {
        if notification.Method == "session.event" {
            // Render or persist the event as needed.
        }
    },
)

Run waits for the prompt's durable agent/inbox/spliced receipt, then
collects notifications until the root session reaches its next idle state.
Notifications from known descendant sessions are included through
subagent.started lineage edges. RunResult.Events contains root-session
events only. FinalResponse is the last committed root assistant text in the
interval, and FinishReason is the last turn/end reason kind when present.
Those values describe the owned activity interval, not an output causally
assigned to only the submitted prompt.

The callback is invoked for each collected notification after the inbox
receipt. FinishReason is a *string; it is nil when no turn ended.

Low-level client

HarnessClient exposes the protocol surface used by advanced integrations:

client := deepseekharness.NewHarnessClient(deepseekharness.HarnessClientOptions{
    RuntimeBin: "/path/to/dsh-jsonrpc-agent-pkg-macos-arm64",
})
defer client.Close()

if err := client.Start(); err != nil {
    panic(err)
}
_, err := client.Initialize(deepseekharness.InitializeParams{
    CWD: "./workspace", Provider: "deepseek-official", Model: "deepseek-v4-flash",
})

The client supports Request, Notify, SessionPrompt, Subscribe,
SubscribeSessionTree, NextNotification, NextRequest, Respond, and
RespondError. Server-to-client requests are queued until the caller answers
them. Notifications that no subscription matched are available through
NextNotification.

Errors

Errors are concrete types suitable for errors.As: JsonRpcError,
RequestTimeoutError, ProtocolError, TransportClosedError,
RuntimeResolveError, and IOError. TransportClosedError includes the
process exit code when available and the last 400 stderr lines.

Development

gofmt -w *.go
go vet ./...
go test -race ./...

GitHub Actions runs formatting, vet, race-enabled tests, and the regular test
suite on Linux and macOS. Releases are created from matching v* tags; see
docs/ROADMAP.md for planned parity work.
For the next upstream tag update, follow the tag update runbook.

Code Contribution Guide

The full contributor workflow, including branch, commit, and pull request
guidance, is in docs/CONTRIBUTING.md.

Relationship to DeepSeek Harness

This repository owns the Go SDK. The runtime is published by the
DeepSeek Harness project as
deepseek-harness-runtime-bin. The SDK follows the documented
stdio JSON-RPC protocol
and tracks the Python SDK's public behavior as that implementation evolves.