feat(adapters): add DeepSeek Harness as deepseek_local

cli/package.json

@@ -41,6 +41,7 @@
     "@paperclipai/adapter-codex-local": "workspace:*",
     "@paperclipai/adapter-cursor-cloud": "workspace:*",
     "@paperclipai/adapter-cursor-local": "workspace:*",
+    "@paperclipai/adapter-deepseek-harness": "workspace:*",
     "@paperclipai/adapter-gemini-local": "workspace:*",
     "@paperclipai/adapter-grok-local": "workspace:*",
     "@paperclipai/adapter-kimi-local": "workspace:*",

cli/src/adapters/registry.ts

@@ -10,6 +10,7 @@ import { formatStdoutEvent as printHermesGatewayStreamEvent } from "@paperclipai
 import { printHermesStreamEvent } from "@paperclipai/hermes-paperclip-adapter/cli";
 import { printOpenCodeStreamEvent } from "@paperclipai/adapter-opencode-local/cli";
 import { printPiStreamEvent } from "@paperclipai/adapter-pi-local/cli";
+import { printDeepseekStreamEvent } from "@paperclipai/adapter-deepseek-harness/cli";
 import { printOpenClawGatewayStreamEvent } from "@paperclipai/adapter-openclaw-gateway/cli";
 import { processCLIAdapter } from "./process/index.js";
 import { httpCLIAdapter } from "./http/index.js";
@@ -34,6 +35,11 @@ const piLocalCLIAdapter: CLIAdapterModule = {
   formatStdoutEvent: printPiStreamEvent,
 };
 
+const deepseekLocalCLIAdapter: CLIAdapterModule = {
+  type: "deepseek_local",
+  formatStdoutEvent: printDeepseekStreamEvent,
+};
+
 const cursorLocalCLIAdapter: CLIAdapterModule = {
   type: "cursor",
   formatStdoutEvent: printCursorStreamEvent,
@@ -80,6 +86,7 @@ const adaptersByType = new Map<string, CLIAdapterModule>(
     codexLocalCLIAdapter,
     openCodeLocalCLIAdapter,
     piLocalCLIAdapter,
+    deepseekLocalCLIAdapter,
     cursorLocalCLIAdapter,
     cursorCloudCLIAdapter,
     geminiLocalCLIAdapter,

docs/adapters/deepseek-local.md

@@ -0,0 +1,62 @@
+---
+title: DeepSeek Harness
+summary: DeepSeek Harness JSON-RPC adapter setup and configuration
+---
+
+The `deepseek_local` adapter runs [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) as a Paperclip coding agent. Heartbeats talk to `dsh-jsonrpc-agent` over NDJSON JSON-RPC (`initialize`, `session/prompt`, `shutdown`) and resume the same `sessionId`. Compatible with DeepSeek Harness `0.1.1-rc.2`.
+
+This adapter does **not** use `dsh --profile headless` or `dsh-acp`. ACP cannot resume sessions and keeps tools off the wire.
+
+## Prerequisites
+
+A working runtime is three pieces, not `npm i -g @deepseek-ai/dsh-sdk-jsonrpc-demo` alone:
+
+1. `dsh-jsonrpc-agent` on `PATH`, or `adapterConfig.command`
+2. A DeepSeek Harness install (`adapterConfig.harnessRoot` or `DSH_HARNESS_ROOT`) so `NODE_PATH=<harnessRoot>/node_modules` can load `@deepseek-ai/dsh-*` plugins
+3. Paperclip's shipped `paperclip.cordis.yml` (or `cordisConfigPath`)
+
+Closed alternative: the Python `deepseek-harness-runtime-bin` executable.
+
+Stdout is the protocol. Do not add a stdout logger to the Cordis composition.
+
+## Auth
+
+- `DEEPSEEK_API_KEY` (required)
+- `DEEPSEEK_BASE_URL` (optional OpenAI-compatible proxy)
+
+There is no Claude `setup-token` login.
+
+## Configuration fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `model` | string | `deepseek-v4-flash` | JSON-RPC `initialize.model` |
+| `provider` | string | `deepseek-official` | JSON-RPC `initialize.provider` |
+| `harnessRoot` | string | — | Harness install used for plugin `NODE_PATH` |
+| `command` | string | `dsh-jsonrpc-agent` | JSON-RPC stdio binary |
+| `cordisConfigPath` | string | shipped composition | Override `DSH_CORDIS_CONFIG` |
+| `cwd` | string | workspace cwd | Absolute fallback working directory |
+| `persistSession` | boolean | true | Reuse `sessionId` across heartbeats |
+| `timeoutSec` | number | 0 | Wall-clock timeout; 0 disables |
+| `graceSec` | number | 15 | SIGTERM grace |
+| `maxTokens` | number | — | Optional `initialize.maxTokens` |
+| `instructionsFilePath` | string | — | Injected as `DSH_SYSTEM_PROMPT` |
+| `env` | object | {} | Secret refs allowed |
+
+Cheap model profile: `deepseek-v4-flash`.
+
+## Sessions
+
+Paperclip generates a `sessionId` and sends it on every `session/prompt`. Session files live under `$PAPERCLIP_HOME/adapter-state/<company>/<agent>/deepseek/sessions` (`DSH_SESSION_ROOT`), not `~/.dsh`. A cwd or session-root mismatch starts a fresh session.
+
+## Skills
+
+Desired Paperclip skills are copied into `$PAPERCLIP_HOME/adapter-state/<company>/<agent>/deepseek/skills` and passed as `dsh-skill-filesystem` `customSkillDirs` via `DSH_BUNDLED_SKILL_DIR`. `~/.dsh/skills` and `~/.agents/skills` remain visible as read-only external roots.
+
+## Remote / sandbox
+
+`deepseek_local` is a remote-managed adapter (local, SSH, and sandbox). Execution targets only accept one-shot stdin, so Paperclip uploads a one-shot JSON-RPC bridge plus the shipped Cordis file, skill root, and session root. The bridge owns the duplex `initialize` / `session/prompt` / idle interval on the target and prints `paperclipDeepseek` JSONL plus a final `bridge-result`.
+
+`getRuntimeCommandSpec.installCommand` is `null`. The remote host must already have `dsh-jsonrpc-agent` (or `adapterConfig.command`) and a harness install that can resolve `@deepseek-ai/dsh-*` plugins. Workspace restore runs in `finally` and never `git push`. After each remote turn the bridge writes `.paperclip-session-export.json` so Paperclip can copy session files back onto the host `DSH_SESSION_ROOT`.
+
+Local Linux hosts can also set `filesystemScope=workspace` and/or `networkScope=deny|allowlist` to wrap the JSON-RPC runtime with the same `bwrap` confinement other local adapters use.

docs/adapters/overview.md

@@ -25,6 +25,7 @@ When a heartbeat fires, Paperclip:
 | OpenCode | `opencode_local` | Runs OpenCode CLI locally (multi-provider `provider/model`) |
 | Cursor | `cursor` | Runs Cursor in background mode |
 | Pi | `pi_local` | Runs an embedded Pi agent locally |
+| [DeepSeek Harness](/adapters/deepseek-local) | `deepseek_local` | Runs DeepSeek Harness over JSON-RPC stdio (local, SSH, or sandbox via a one-shot bridge) |
 | Hermes | `hermes_local` | Runs the local Hermes CLI through `@paperclipai/hermes-paperclip-adapter` |
 | Hermes Gateway | `hermes_gateway` | Calls an already-running Hermes API server through `@paperclipai/hermes-paperclip-adapter/gateway` |
 | OpenClaw Gateway | `openclaw_gateway` | Connects to an OpenClaw gateway endpoint |

docs/docs.json

@@ -99,6 +99,7 @@
             "group": "Agent Adapters",
             "pages": [
               "adapters/overview",
+              "adapters/deepseek-local",
               "adapters/claude-local",
               "adapters/codex-local",
               "adapters/process",

packages/adapter-utils/src/session-compaction.ts

@@ -41,6 +41,7 @@ export const LEGACY_SESSIONED_ADAPTER_TYPES = new Set([
   "codex_local",
   "cursor_cloud",
   "cursor",
+  "deepseek_local",
   "gemini_local",
   "hermes_local",
   "kimi_local",
@@ -69,6 +70,11 @@ export const ADAPTER_SESSION_MANAGEMENT: Record<string, AdapterSessionManagement
     nativeContextManagement: "unknown",
     defaultSessionCompaction: DEFAULT_SESSION_COMPACTION_POLICY,
   },
+  deepseek_local: {
+    supportsSessionResume: true,
+    nativeContextManagement: "confirmed",
+    defaultSessionCompaction: ADAPTER_MANAGED_SESSION_POLICY,
+  },
   gemini_local: {
     supportsSessionResume: true,
     nativeContextManagement: "unknown",

packages/adapters/deepseek-harness/README.md

@@ -0,0 +1,32 @@
+# @paperclipai/adapter-deepseek-harness
+
+Paperclip adapter for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`deepseek_local`).
+
+Heartbeat execute talks to `dsh-jsonrpc-agent` over NDJSON JSON-RPC (`initialize`, `session/prompt`, `shutdown`). Compatible with DeepSeek Harness `0.1.1-rc.2`.
+
+## This is not `npm i -g @deepseek-ai/dsh-sdk-jsonrpc-demo`
+
+That package only ships the JSON-RPC bin. The bin boots `$DSH_CORDIS_CONFIG` (required) and resolves bare `@deepseek-ai/dsh-*` plugins from the **configuration project** / `NODE_PATH`. A working runtime is:
+
+1. `dsh-jsonrpc-agent` on `PATH`, or `adapterConfig.command`
+2. A DeepSeek Harness install (`adapterConfig.harnessRoot` or `DSH_HARNESS_ROOT`) so `NODE_PATH=<harnessRoot>/node_modules` can load plugins
+3. Paperclip's shipped `paperclip.cordis.yml` (or `adapterConfig.cordisConfigPath`)
+
+Closed alternative: the Python `deepseek-harness-runtime-bin` executable.
+
+Do not add a stdout logger to the Cordis composition. Stdout is the protocol.
+
+## Auth
+
+- `DEEPSEEK_API_KEY` (required)
+- `DEEPSEEK_BASE_URL` (optional)
+
+There is no Claude `setup-token` login. ACP is not advertised: dsh ACP is fresh-session-only and keeps tools off the wire.
+
+## Sessions
+
+Paperclip generates a `sessionId` and reuses it on `session/prompt`. Session files live under `$PAPERCLIP_HOME/adapter-state/<company>/<agent>/deepseek/sessions` (`DSH_SESSION_ROOT`), not `~/.dsh`.
+
+## Remote / sandbox
+
+SSH and sandbox runs upload a one-shot JSON-RPC bridge (`remote-bridge.mjs`), the shipped Cordis file, and the session/skill roots. The remote host must already have `dsh-jsonrpc-agent` and harness plugins; `installCommand` is `null`. Workspace restore runs in `finally` and never `git push`.

packages/adapters/deepseek-harness/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@paperclipai/adapter-deepseek-harness",
+  "version": "0.3.1",
+  "license": "MIT",
+  "homepage": "https://github.com/paperclipai/paperclip",
+  "bugs": {
+    "url": "https://github.com/paperclipai/paperclip/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/paperclipai/paperclip",
+    "directory": "packages/adapters/deepseek-harness"
+  },
+  "description": "Paperclip adapter for DeepSeek Harness over JSON-RPC stdio",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./server": "./src/server/index.ts",
+    "./ui": "./src/ui/index.ts",
+    "./cli": "./src/cli/index.ts",
+    "./ui-parser": "./src/ui-parser.ts"
+  },
+  "paperclip": {
+    "adapterUiParser": "1.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      },
+      "./server": {
+        "types": "./dist/server/index.d.ts",
+        "import": "./dist/server/index.js"
+      },
+      "./ui": {
+        "types": "./dist/ui/index.d.ts",
+        "import": "./dist/ui/index.js"
+      },
+      "./cli": {
+        "types": "./dist/cli/index.d.ts",
+        "import": "./dist/cli/index.js"
+      },
+      "./ui-parser": "./dist/ui-parser.js"
+    },
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc && cp src/server/paperclip.cordis.yml dist/server/paperclip.cordis.yml && cp src/server/remote-bridge.mjs dist/server/remote-bridge.mjs",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@paperclipai/adapter-utils": "workspace:*",
+    "@paperclipai/shared": "workspace:*",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.7.3",
+    "vitest": "^4.1.10"
+  },
+  "engines": {
+    "node": ">=24.11.0"
+  }
+}

packages/adapters/deepseek-harness/src/cli/format-event.ts

@@ -0,0 +1,38 @@
+import pc from "picocolors";
+import { parseStdoutLine } from "../ui-parser.js";
+
+export function printDeepseekStreamEvent(raw: string, _debug: boolean): void {
+  const line = raw.trim();
+  if (!line) return;
+  const entries = parseStdoutLine(line, new Date().toISOString());
+  if (entries.length === 0) return;
+  for (const entry of entries) {
+    const kind = typeof entry.kind === "string" ? entry.kind : "stdout";
+    if (kind === "assistant") {
+      console.log(pc.green(String(entry.text ?? "")));
+      continue;
+    }
+    if (kind === "thinking") {
+      console.log(pc.magenta(String(entry.text ?? "")));
+      continue;
+    }
+    if (kind === "tool_call") {
+      console.log(pc.yellow(`tool ${String(entry.name ?? "tool")}`));
+      continue;
+    }
+    if (kind === "tool_result") {
+      const printer = entry.isError ? pc.red : pc.gray;
+      console.log(printer(String(entry.content ?? "")));
+      continue;
+    }
+    if (kind === "stderr") {
+      console.log(pc.red(String(entry.text ?? "")));
+      continue;
+    }
+    if (kind === "system" || kind === "result") {
+      console.log(pc.cyan(String(entry.text ?? kind)));
+      continue;
+    }
+    if (typeof entry.text === "string" && entry.text) console.log(entry.text);
+  }
+}

packages/adapters/deepseek-harness/src/cli/index.ts

@@ -0,0 +1 @@
+export { printDeepseekStreamEvent } from "./format-event.js";

packages/adapters/deepseek-harness/src/index.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { createServerAdapter, type, label } from "./index.js";
+
+describe("createServerAdapter", () => {
+  it("exports a hireable deepseek_local module", () => {
+    const adapter = createServerAdapter();
+    expect(type).toBe("deepseek_local");
+    expect(label).toBe("DeepSeek Harness");
+    expect(adapter.type).toBe("deepseek_local");
+    expect(adapter.supportsLocalAgentJwt).toBe(true);
+    expect(adapter.requiresMaterializedRuntimeSkills).toBe(true);
+    expect(adapter.sessionCodec).toBeDefined();
+    expect(adapter.getRuntimeCommandSpec?.({})?.installCommand).toBeNull();
+    expect(adapter.runtimeToolDelivery).toBe("environment");
+    expect(adapter.loginCapability).toBeUndefined();
+    expect(adapter.acp).toBeUndefined();
+    expect(adapter.listSkills).toBeTypeOf("function");
+    expect(adapter.detectModel).toBeTypeOf("function");
+  });
+});