krislavten / ai-sdk-provider-dsh

ai-sdk-provider-dsh

AI SDK provider that drives a DeepSeek Harness (dsh) runtime as a language model.

dsh is a full agent harness (agent loop, tools, skills, MCP, sessions) from DeepSeek AI. This provider wraps a dsh runtime subprocess behind the AI SDK LanguageModel interface, so you can drive a harness agent from AI SDK generateText / streamText the same way ai-sdk-provider-claude-code drives Claude Code — while keeping the AI SDK as the single orchestration surface.

Version Compatibility

This provider implements the LanguageModelV3 specification (specificationVersion: 'v3'), the interface shared across AI SDK majors. A single build serves both:

AI SDK	@ai-sdk/provider	Status
ai@^6	@ai-sdk/provider@^3	✅ supported
ai@^7	@ai-sdk/provider@^4	✅ supported (V3 models are first-class in v7)

Requirement	Value
Node.js	>=22.19
Module format	ESM only
DeepSeek Harness family	pinned exact 0.1.0-rc.6

Upstream status: dsh is in developer preview (0.1.0-rc.x); DeepSeek documents breaking changes as their release policy. This provider pins the harness SDK family to exact versions, so the runtime version is a deliberate platform-side decision — upgrade the pin explicitly, never by range drift.

Install

npm install ai-sdk-provider-dsh

The dsh runtime is bundled: the package ships a default runtime composition (runtime/cordis.yml) plus the dsh-jsonrpc-agent bin (via @deepseek-ai/dsh-sdk-jsonrpc-demo), and all runtime plugins are pinned exact versions in dependencies. A provider instance spawns a working runtime out of the box — no separate install.

Credentials come from the runtime's environment:

export DEEPSEEK_API_KEY=sk-...                                        # required
export DEEPSEEK_BASE_URL=https://api.deepseek.com                     # optional; any OpenAI-compatible gateway works

Quick Start

streamText (AI SDK v7)

import { streamText } from "ai";
import { createDsh } from "ai-sdk-provider-dsh";

const dsh = createDsh({
  runtime: { provider: "deepseek-official", model: "deepseek-v4-flash" },
});

const result = streamText({
  model: dsh.languageModel("deepseek-v4-flash"),
  instructions: "You are a coding agent.",
  prompt: "run the tests",
});

const text = await result.text;
console.log(text);

streamText (AI SDK v6)

import { streamText } from "ai";
import { createDsh } from "ai-sdk-provider-dsh";

const dsh = createDsh({ runtime: { provider: "deepseek-official", model: "deepseek-v4-flash" } });

const result = streamText({
  model: dsh.languageModel("deepseek-v4-flash"),
  system: "You are a coding agent.", // v6 name; v7 uses `instructions`
  prompt: "run the tests",
});

generateText

import { generateText } from "ai";
import { createDsh } from "ai-sdk-provider-dsh";

const dsh = createDsh({ runtime: { provider: "deepseek-official", model: "deepseek-v4-flash" } });
const { text } = await generateText({
  model: dsh.languageModel("deepseek-v4-flash"),
  prompt: "say hello",
});

Provider factory

const dsh = createDsh(options);        // returns the provider
dsh.languageModel("deepseek-v4-flash") // the LanguageModel
dsh("deepseek-v4-flash")               // callable alias (AI SDK provider convention)
await dsh.close();                     // tear down the runtime subprocess (idempotent)

Runtime Options

Option	Default	Meaning
provider	required	model provider route passed to the runtime handshake (deepseek-official, or a pi-ai catalog route)
model	required	model id passed to the runtime handshake
env	inherits process.env	environment for the runtime subprocess: credentials (DEEPSEEK_API_KEY), DEEPSEEK_BASE_URL, DSH_CWD, DSH_SESSION_ROOT, …
cwd	process.cwd()	subprocess working directory
configPath	bundled runtime/cordis.yml	a different cordis.yml composition
binPath	bundled dsh-jsonrpc-agent	a different runtime bin
command / args	node + [bin, config]	full custom launch vector (set both together)
maxTokens	—	positive output-token cap per root-agent request
requestTimeoutMs	SDK default	per-request timeout for the JSON-RPC transport
disposeEofGraceMs / disposeGraceMs	SDK defaults	subprocess teardown ladders (EOF → SIGTERM → SIGKILL)
sessionId	fresh UUID	fixed session id; keep it to continue one harness session across turns

The bundled runtime

The default composition (runtime/cordis.yml) exposes:

• bash (foreground), read/write/edit (fs), subagent, todo_write — tools execute inside the harness
• JSONL session persistence with automatic context compaction
• $DSH_SYSTEM_PROMPT selects the deployment persona

For environments that cannot build node-pty (no Linux prebuild — e.g. minimal containers, WSL without libc6-dev), use the no-pty composition:

runtime: {
  provider: "deepseek-official",
  model: "deepseek-v4-flash",
  configPath: require.resolve("ai-sdk-provider-dsh/runtime/cordis.minimal.yml"),
}

How it works

• Each provider instance spawns (lazily) one dsh runtime subprocess speaking stdio JSON-RPC (the dsh SDK protocol).
• doGenerate / doStream translate AI SDK LanguageModelV3CallOptions into a dsh prompt, then map the runtime's session.event stream back into AI SDK stream parts (text-start/delta/end, reasoning-start/delta/end, tool-input-start/delta/end, tool-call, finish).
• Tools execute inside the harness — the provider is a thin pass-through (like ai-sdk-provider-claude-code): tool calls surface as providerExecuted: true parts and the AI SDK never re-executes them.
• Multi-turn sessions: one provider instance keeps one runtime subprocess; with a fixed sessionId, follow-up turns continue the same harness session (the runtime persists the session log). Verified end-to-end: turn 1 stores a secret code, turn 2 recalls it.
• Abort: an aborted call surfaces the original abort reason (never a wrapped transport error); pre-aborted signals throw immediately; the abort listener is removed on completion.

Provider Metadata

Each response exposes dsh metadata under providerMetadata['dsh'] (AI SDK v7: result.finalStep.providerMetadata, or await stream.finalStep for streamText; v6: result.providerMetadata):

Field	Type	Meaning
sessionId	string	the harness session id this call ran on
turnId	number?	last observed turn number
terminalReason	string?	final turn end kind when not completed (aborted, error, max-tokens, blocked, interrupted)

Error Diagnostics

Errors from the runtime boundary are classified into AI SDK APICallErrors. A sanitized stderr tail is appended to the message so CLI failures are visible in logs:

dsh runtime subprocess failed: runtime exited | stderr (tail): ...; ...

import { generateText } from "ai";
import { createDsh, getErrorMetadata, isAPICallError } from "ai-sdk-provider-dsh";

try {
  await generateText({ model: dsh.languageModel("deepseek-v4-flash"), prompt: "Hello!" });
} catch (error) {
  if (isAPICallError(error)) {
    console.error(getErrorMetadata(error)?.stderr);
    console.error("retryable:", error.isRetryable);
  }
}

Classification map:

Runtime failure	AI SDK error	Retryable
TransportClosedError (subprocess died / stdio closed)	APICallError	✅
RequestTimeoutError	APICallError	✅
SdkProtocolError (wire violation)	APICallError	❌
JsonRpcResponseError (runtime rejected request)	APICallError	❌
Node spawn failure (ENOENT bin, …)	APICallError	only EAGAIN/EMFILE
Missing/invalid API key	LoadAPIKeyError (via createAuthenticationError)	—

Limitations

• Requires Node.js >=22.19; ESM only.
• No mid-turn cancel on the SDK wire: aborting a turn rejects the current call; the runtime subprocess and session log remain for follow-up turns. dsh.close() tears the subprocess down (EOF → SIGTERM → SIGKILL).
• Skills use the dsh native mechanism (SKILL.md bundles discovered from .dsh/skills, .agents/skills, $DSH_HOME/skills) — the reskill skills.json/skills.lock convention is not applied by this provider.
• Tool execution is harness-internal: AI SDK tools / toolChoice are not executed by the AI SDK; configure tools through the runtime composition (cordis.yml) or $DSH_* env.
• Some AI SDK call options are accepted but not forwarded to the harness: temperature, topP, topK, stopSequences, seed — the harness owns sampling.
• dsh is in developer preview; DeepSeek documents breaking changes as release policy. Pin the provider version and the harness family (0.1.0-rc.6) deliberately.
• The bundled default runtime needs node-pty on Linux (compiled at install; no prebuild). Use cordis.minimal.yml (no bash) where that is unavailable.

Development

pnpm install
pnpm run check    # typecheck
pnpm run test     # unit tests (fake runtime) + e2e (real runtime, keyless replay)
pnpm run lint     # biome
pnpm run build    # tsup → dist/

Tests never need a real API key: unit tests drive a fake runtime with synthetic event streams (the ai-sdk-provider-claude-code philosophy), and e2e tests boot the real dsh runtime against recorded session fixtures replayed by @deepseek-ai/dsh-llm-replay.

Recording new fixtures (requires a live key)

DEEPSEEK_API_KEY=sk-... node scripts/record-fixture.mjs   # writes tests/fixtures/*.jsonl

License

MIT