@harapter/adapter-dsh 0.1.1 → 0.1.2

package/README.ja.md

@@ -0,0 +1,117 @@
+<!-- markdownlint-disable MD033 MD041 -->
+
+<h1 align="center"><code>@harapter/adapter-dsh</code></h1>
+
+<p align="center"><strong>公式 DeepSeek Harness SDK Runtime protocol を Harapter に mapping します。</strong></p>
+
+<p align="center">
+  <a href="./README.md">English</a> · <a href="./README.zh-CN.md">简体中文</a> · <a href="./README.ja.md">日本語</a> · <a href="../../README.ja.md">Harapter</a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@harapter/adapter-dsh"><img src="https://img.shields.io/npm/v/%40harapter%2Fadapter-dsh/next?style=flat-square&amp;label=npm%20next" alt="npm next バージョン"></a>
+  <a href="https://www.npmjs.com/package/@harapter/adapter-dsh"><img src="https://img.shields.io/npm/dm/%40harapter%2Fadapter-dsh?style=flat-square" alt="npm ダウンロード数"></a>
+  <a href="https://github.com/yunfeizhu/harapter/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/yunfeizhu/harapter/ci.yml?branch=main&amp;style=flat-square&amp;label=ci" alt="CI ステータス"></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D24-339933?style=flat-square&amp;logo=nodedotjs&amp;logoColor=white" alt="Node.js 24 以上">
+  <a href="../../LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-0B7285?style=flat-square" alt="Apache-2.0 ライセンス"></a>
+  <img src="https://img.shields.io/badge/status-pre--alpha-EA580C?style=flat-square" alt="Pre-alpha ステータス">
+</p>
+
+<!-- markdownlint-enable MD033 -->
+
+`@harapter/adapter-dsh` は DeepSeek Harness SDK Runtime の newline-delimited
+JSON-RPC 2.0
+Server に接続し、Session、Run、Event、Interaction、cancellation、Error を Harapter に mapping します。Agent
+Loop 自体は埋め込みません。
+
+## 前提条件とインストール
+
+DeepSeek
+Harness の導入、composition、設定、認証はホストが行います。Harapter は DSH
+CLI、SDK package、Cordis Application、Plugin、Model
+Adapter、Credential を同梱しません。
+
+```bash
+pnpm add @harapter/core@next @harapter/adapter-dsh@next
+```
+
+## クイックスタート
+
+```ts
+import { HarnessRegistry, profileId } from '@harapter/core';
+import {
+  DSH_PROVIDER_ID,
+  createDshProviderFactory,
+} from '@harapter/adapter-dsh';
+
+const registry = new HarnessRegistry();
+registry.register(createDshProviderFactory());
+
+const client = await registry.connect({
+  profileId: profileId('dsh-local'),
+  providerId: DSH_PROVIDER_ID,
+  displayName: 'Local DeepSeek Harness',
+  connection: {
+    kind: 'process',
+    command: 'dsh',
+    args: ['--profile', 'sdk'],
+    ownership: 'adapter',
+  },
+  providerOptions: {
+    provider: 'host-configured-provider',
+    model: 'host-configured-model',
+  },
+});
+
+const session = await client.createSession();
+try {
+  const run = await session.start({
+    parts: [{ type: 'text', text: 'Describe the current project.' }],
+  });
+  for await (const event of run.events()) console.log(event.type);
+  console.log((await run.result()).status);
+} finally {
+  try {
+    await session.close();
+  } finally {
+    await client.close();
+  }
+}
+```
+
+## Profile とライフサイクル
+
+- Adapter-owned `process` Connection のみで、Shell は使用しません；
+- Profile に非空 `provider` と `model` が必要で、Reasoning、Token、bounded
+  transport 値も設定できます；
+- Workspace は Runtime 初期化 Directory と一致する必要があります；
+- 現 protocol に Resume と Native Session Close はなく、close は local
+  handle 解放です；
+- Connection 全体で active Run は一つです；
+- `session/prompt` が返すのは永続的な Inbox `messageId`
+  だけで、Result や終端の authority ではありません。所有する activity 区間内の唯一有効な
+  `turn/end.data.reason` が終端を決め、EOF と Process
+  Exit は success になりません；
+- 現 protocol に Prompt Cancel はなく、`run.cancel`
+  は未対応です。Timeout は所有する Connection を閉じて `connection_aborted`
+  となります。upstream で観測した `aborted` は `run.cancelled`
+  に mapping できますが、Harapter が Native
+  Cancel を要求した証拠にはなりません；
+- 未知 notification は bounded redacted
+  observation に残り、終端には変換されません。
+
+## Compatibility と Evidence
+
+接続は `deepseek-harness-sdk-runtime`
+identity と、使用する Response、Event、Terminal の structure を検証します。Runtime は診断 Version を返しますが protocol
+version
+negotiation がないため allowlist は使いません。新 Runtime は既定で試し、互換でない構造を使用した時点で fail
+closed します。
+
+公式 SDK Profile は Fixture、mapping test、shared conformance、real Runtime
+lifecycle で検証済みです。`experimental`
+は「未実装」ではなく、任意 Runtime を実行前に既存 evidence へ自動対応付けできないことを示します。production
+host は記録済み Version を pin して再現性を得られます。
+
+Native Client、Interaction、cancel、検証 Version、live test、全制限は
+[英語の詳細ドキュメント](./README.md)を参照してください。

package/README.md

@@ -1,4 +1,23 @@
-# `@harapter/adapter-dsh`
+<!-- markdownlint-disable MD033 MD041 -->
+
+<h1 align="center"><code>@harapter/adapter-dsh</code></h1>
+
+<p align="center"><strong>Map the official DeepSeek Harness SDK Runtime protocol to Harapter.</strong></p>
+
+<p align="center">
+  <a href="./README.md">English</a> · <a href="./README.zh-CN.md">简体中文</a> · <a href="./README.ja.md">日本語</a> · <a href="../../README.md">Harapter</a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@harapter/adapter-dsh"><img src="https://img.shields.io/npm/v/%40harapter%2Fadapter-dsh/next?style=flat-square&amp;label=npm%20next" alt="npm next version"></a>
+  <a href="https://www.npmjs.com/package/@harapter/adapter-dsh"><img src="https://img.shields.io/npm/dm/%40harapter%2Fadapter-dsh?style=flat-square" alt="npm downloads"></a>
+  <a href="https://github.com/yunfeizhu/harapter/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/yunfeizhu/harapter/ci.yml?branch=main&amp;style=flat-square&amp;label=ci" alt="CI status"></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D24-339933?style=flat-square&amp;logo=nodedotjs&amp;logoColor=white" alt="Node.js 24 or newer">
+  <a href="../../LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-0B7285?style=flat-square" alt="Apache-2.0 license"></a>
+  <img src="https://img.shields.io/badge/status-pre--alpha-EA580C?style=flat-square" alt="Pre-alpha status">
+</p>
+
+<!-- markdownlint-enable MD033 -->
 
 `@harapter/adapter-dsh` maps the official
 [DeepSeek Harness SDK protocol](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/sdk/protocol/README.md)
@@ -6,6 +25,14 @@ to the portable Harapter lifecycle. It connects to the newline-delimited
 JSON-RPC 2.0 server exposed by the SDK Runtime and does not embed or reproduce
 the DeepSeek Harness Agent Loop.
 
+## Use this Adapter when
+
+- your host installs and starts the official DeepSeek Harness SDK Runtime;
+- you need its Session, Run, Event, interaction, resume, and cancellation
+  behavior behind Harapter Core; or
+- you want runtime validation and bounded raw observations without embedding the
+  DeepSeek Harness Agent Loop in your application.
+
 ## Installation
 
 ```bash
@@ -92,17 +119,24 @@ const client = await registry.connect({
 });
 
 const session = await client.createSession();
-const run = await session.start({
-  parts: [{ type: 'text', text: 'Describe the current project.' }],
-});
-
-for await (const event of run.events()) {
-  // Render or persist according to the host's data policy.
+try {
+  const run = await session.start({
+    parts: [{ type: 'text', text: 'Describe the current project.' }],
+  });
+
+  for await (const event of run.events()) {
+    // Render or persist according to the host's data policy.
+  }
+
+  const result = await run.result();
+  console.log(result.status);
+} finally {
+  try {
+    await session.close();
+  } finally {
+    await client.close();
+  }
 }
-
-const result = await run.result();
-await session.close();
-await client.close();
 ```
 
 ## Profile and process ownership

package/README.zh-CN.md

@@ -0,0 +1,110 @@
+<!-- markdownlint-disable MD033 MD041 -->
+
+<h1 align="center"><code>@harapter/adapter-dsh</code></h1>
+
+<p align="center"><strong>把 DeepSeek Harness 官方 SDK Runtime 协议映射为 Harapter。</strong></p>
+
+<p align="center">
+  <a href="./README.md">English</a> · <a href="./README.zh-CN.md">简体中文</a> · <a href="./README.ja.md">日本語</a> · <a href="../../README.zh-CN.md">Harapter</a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@harapter/adapter-dsh"><img src="https://img.shields.io/npm/v/%40harapter%2Fadapter-dsh/next?style=flat-square&amp;label=npm%20next" alt="npm next 版本"></a>
+  <a href="https://www.npmjs.com/package/@harapter/adapter-dsh"><img src="https://img.shields.io/npm/dm/%40harapter%2Fadapter-dsh?style=flat-square" alt="npm 下载量"></a>
+  <a href="https://github.com/yunfeizhu/harapter/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/yunfeizhu/harapter/ci.yml?branch=main&amp;style=flat-square&amp;label=ci" alt="CI 状态"></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D24-339933?style=flat-square&amp;logo=nodedotjs&amp;logoColor=white" alt="Node.js 24 或更高版本">
+  <a href="../../LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-0B7285?style=flat-square" alt="Apache-2.0 许可证"></a>
+  <img src="https://img.shields.io/badge/status-pre--alpha-EA580C?style=flat-square" alt="Pre-alpha 状态">
+</p>
+
+<!-- markdownlint-enable MD033 -->
+
+`@harapter/adapter-dsh` 连接 DeepSeek Harness SDK
+Runtime 暴露的换行分隔 JSON-RPC 2.0
+Server，并把 Session、Run、Event、Interaction、取消和错误映射到 Harapter。它不会嵌入或复制 DeepSeek
+Harness Agent Loop。
+
+## 前置条件与安装
+
+宿主自行安装、组合、配置和认证 DeepSeek Harness。Harapter 不包含 DSH CLI、SDK
+Package、Cordis Application、Plugin、Model Adapter 或 Credential。
+
+```bash
+pnpm add @harapter/core@next @harapter/adapter-dsh@next
+```
+
+## 快速开始
+
+```ts
+import { HarnessRegistry, profileId } from '@harapter/core';
+import {
+  DSH_PROVIDER_ID,
+  createDshProviderFactory,
+} from '@harapter/adapter-dsh';
+
+const registry = new HarnessRegistry();
+registry.register(createDshProviderFactory());
+
+const client = await registry.connect({
+  profileId: profileId('dsh-local'),
+  providerId: DSH_PROVIDER_ID,
+  displayName: 'Local DeepSeek Harness',
+  connection: {
+    kind: 'process',
+    command: 'dsh',
+    args: ['--profile', 'sdk'],
+    ownership: 'adapter',
+  },
+  providerOptions: {
+    provider: 'host-configured-provider',
+    model: 'host-configured-model',
+  },
+});
+
+const session = await client.createSession();
+try {
+  const run = await session.start({
+    parts: [{ type: 'text', text: 'Describe the current project.' }],
+  });
+  for await (const event of run.events()) console.log(event.type);
+  console.log((await run.result()).status);
+} finally {
+  try {
+    await session.close();
+  } finally {
+    await client.close();
+  }
+}
+```
+
+## Profile 与生命周期
+
+- 只接受 Adapter 拥有的 `process` Connection，并且不会使用 Shell；
+- Profile 必须提供非空 `provider` 和
+  `model`，还可设置 Reasoning、Token 与有界传输参数；
+- Workspace 必须与 Runtime 初始化目录一致；Session 级 Model、System
+  Context 和 Metadata 不受支持；
+- 当前协议没有 Resume 与 Native Session Close；`session.close()`
+  只释放本地 Handle；
+- 整条 Connection 同时只有一个 Run；普通文本按官方 SDK 消息发送；
+- `session/prompt` 只返回持久的 Inbox
+  `messageId`，不是 Result 或终态 Authority；归属活动区间内唯一有效的
+  `turn/end.data.reason` 才决定终态，EOF 或 Process Exit 不会成为成功；
+- 当前协议没有 Prompt Cancel，`run.cancel`
+  因此不受支持；Timeout 会关闭所属 Connection 并得到
+  `connection_aborted`，上游观测到的 `aborted` 可映射为
+  `run.cancelled`，但不证明 Harapter 发起了 Native Cancel；
+- 未知通知进入有界、脱敏 Observation，不会被猜测为终态。
+
+## 兼容性与 Evidence
+
+连接会验证 `deepseek-harness-sdk-runtime`
+身份以及实际使用的每个 Response、Event 和 Terminal 结构。Runtime 会报告诊断 Version，但协议没有协商版本，因此不使用版本白名单：新版本默认尝试，结构不兼容时在边界 fail
+closed。
+
+官方 SDK Profile 已通过合成 Fixture、Mapping
+Test、共享 Conformance 和真实 Runtime 生命周期验证。Adapter 仍显示
+`experimental`，表示任意连接的 Runtime无法在执行前自动绑定到已验证证据，而不是“没有实现或没有跑过”。生产环境可以固定文档记录的验证版本以获得可复现部署。
+
+Native Client、Interaction、取消细节、最后验证版本、Live Test 与全部限制见
+[英文详细文档](./README.md)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harapter/adapter-dsh",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "DeepSeek Harness stdio JSON-RPC provider adapter for Harapter.",
   "keywords": [
     "agent",
@@ -17,11 +17,13 @@
   "bugs": {
     "url": "https://github.com/yunfeizhu/harapter/issues"
   },
-  "homepage": "https://github.com/yunfeizhu/harapter#readme",
+  "homepage": "https://github.com/yunfeizhu/harapter/tree/main/providers/dsh#readme",
   "type": "module",
   "sideEffects": false,
   "files": [
-    "dist"
+    "dist",
+    "README.zh-CN.md",
+    "README.ja.md"
   ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -41,11 +43,11 @@
     "tag": "next"
   },
   "dependencies": {
-    "@harapter/core": "0.1.1",
-    "@harapter/transport-jsonrpc-stdio": "0.1.1"
+    "@harapter/core": "0.1.2",
+    "@harapter/transport-jsonrpc-stdio": "0.1.2"
   },
   "devDependencies": {
-    "@harapter/conformance": "0.1.1"
+    "@harapter/conformance": "0.1.2"
   },
   "scripts": {
     "build": "tsc --project tsconfig.build.json"