@deepseek-ai/dsh-error 0.0.0-stage → 0.2.2-rc.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,34 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/util/error/README.md
+/:
+  en: 765d60b0cc7f8cf1
+  zh: 66b731f7143ccc5c
+/deepseek-ai-dsh-error:
+  en: 78fc89983568c13f
+  zh: 12bb37d45b49562b
+/deepseek-ai-dsh-error/summary:
+  en: eefb4278f326243a
+  zh: 681e25fc7d65865e
+/deepseek-ai-dsh-error/table-of-contents:
+  en: c992e0cd2e7042d6
+  zh: 2e8cd826664632d1
+/deepseek-ai-dsh-error/use-this-package:
+  en: 1b8c9b68ec9b48fc
+  zh: 4b0b54d3330b288b
+/deepseek-ai-dsh-error/understand-the-implementation:
+  en: 42b15ac6321706aa
+  zh: 4ed0861911abaf5d
+/deepseek-ai-dsh-error/understand-the-implementation/source-map:
+  en: a2e80abfe169f97f
+  zh: eb37e22c32f66add
+/deepseek-ai-dsh-error/understand-the-implementation/why-it-stays-dependency-free:
+  en: 79564181c4c59db6
+  zh: 845856fa121b3ff7
+/deepseek-ai-dsh-error/further-exploration:
+  en: 530bc3a0690a4012
+  zh: 192682c5a8571dfe
+/deepseek-ai-dsh-error/dev-note:
+  en: 5de1d6304e00c58f
+  zh: 0087361e6f535488

package/README.md

@@ -1,3 +1,76 @@
-# Temporary Holding Version
+---
+description: "Dependency-free HarnessError base class whose stable code lets tool results, retries, and replay route failures."
+kind: "package-library"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @deepseek-ai/dsh-error
+
+English | [中文](README.zh.md)
+
+## Summary
+
+`dsh-error` holds `HarnessError`, the base class for every expected Harness failure. A `HarnessError` carries a stable machine-routable `code` beside its human-readable `message` and optional `cause`, and its `name` is the constructing class name. The tool registry records `name` and `code` of a thrown `HarnessError` on `tool/result`, so retry policy, UI, replay, and analytics route on the code instead of parsing text. The package has no dependencies, so packages below `dsh-llm` in the dependency graph can extend the base too; `dsh-llm` re-exports the same class.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Extend `HarnessError` with one class per owning package or domain and give each failure a stable `UPPER_SNAKE_CASE` code:
+
+```ts
+import { HarnessError } from '@deepseek-ai/dsh-error'
+
+export class ArchiveError extends HarnessError {}
+
+throw new ArchiveError('archive entry is missing', 'ARCHIVE_ENTRY_NOT_FOUND')
+```
+
+Assign `this.name` a string literal in a subclass constructor when a bundler could rename the class, because `name` is persisted. Import the class from `@deepseek-ai/dsh-error` or from its `@deepseek-ai/dsh-llm` re-export; both name the same class, so `instanceof` checks agree. The [error class and code guide](../../../.agents/skills/dsh-error-handling/references/error-codes.md) defines class choice, naming, and code conventions.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | The `HarnessError` base class |
+
+### Why it stays dependency-free
+
+`dsh-llm` depends on lower packages such as `dsh-attachment` and `dsh-typert-protocol`, so a base class defined there could not be extended below it without a dependency cycle. Keeping the class in a package without dependencies lets every package extend it; the [decision note](../../../.agents/notes/implemented/architecture/2026-11-05-harness-error-dependency-free-base.md) records the relocation.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [Tools subsystem](../../../docs/subsystems/tools.md) — how the registry records `ToolErrorInfo` from a thrown `HarnessError`.
+- [Error-handling rules](../../../.agents/skills/dsh-error-handling/SKILL.md) — when code must throw a `HarnessError`.
+
+-----
+
+<a id="dev-note"></a>
+## Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,76 @@
+---
+description: "无依赖的 HarnessError 基类，其稳定 code 让工具结果、重试与回放能够按失败类别路由。"
+kind: "package-library"
+---
+
+# @deepseek-ai/dsh-error
+
+[English](README.md) | 中文
+
+## 概述
+
+`dsh-error` 存放 `HarnessError`，即所有预期 Harness 失败的基类。`HarnessError` 在人类可读的 `message` 与可选的 `cause` 之外，携带稳定、可供机器路由的 `code`，其 `name` 为构造它的类名。工具注册表会把抛出的 `HarnessError` 的 `name` 与 `code` 记录到 `tool/result` 上，使重试策略、UI、回放与数据分析按 code 路由，而不必解析文本。本包没有任何依赖，因此依赖图中位于 `dsh-llm` 之下的包也能继承该基类；`dsh-llm` 会重新导出同一个类。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+每个所属包或领域继承出一个 `HarnessError` 子类，并为每种失败指定稳定的 `UPPER_SNAKE_CASE` code：
+
+```ts
+import { HarnessError } from '@deepseek-ai/dsh-error'
+
+export class ArchiveError extends HarnessError {}
+
+throw new ArchiveError('archive entry is missing', 'ARCHIVE_ENTRY_NOT_FOUND')
+```
+
+打包工具可能重命名类时，在子类构造函数中把 `this.name` 赋为字符串字面量，因为 `name` 会被持久化。可以从 `@deepseek-ai/dsh-error` 导入该类，也可以使用 `@deepseek-ai/dsh-llm` 的重新导出；两者是同一个类，因此 `instanceof` 判断结果一致。[错误类与 code 指南](../../../.agents/skills/dsh-error-handling/references/error-codes.md)规定了类的选择、命名与 code 约定。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | `HarnessError` 基类 |
+
+### 为什么保持无依赖
+
+`dsh-llm` 依赖 `dsh-attachment`、`dsh-typert-protocol` 等更底层的包，定义在其中的基类无法被这些包继承，否则会形成依赖环。把该类放在没有依赖的包中，所有包都可以继承它；[决策记录](../../../.agents/notes/implemented/architecture/2026-11-05-harness-error-dependency-free-base.zh.md)记录了这次迁移。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+- [工具子系统](../../../docs/subsystems/tools.zh.md) — 注册表如何根据抛出的 `HarnessError` 记录 `ToolErrorInfo`。
+- [错误处理规则](../../../.agents/skills/dsh-error-handling/SKILL.md) — 何时必须抛出 `HarnessError`。
+
+-----
+
+<a id="dev-note"></a>
+## 开发备注
+
+<details>
+<summary>维护者的工作背景——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,23 @@
+//#region lib/types/index.js
+/**
+* Harness error base with a stable machine-routable code and chained cause.
+* Package errors extend it so tool results and replay can retain failure class.
+* @module @deepseek-ai/dsh-error
+*/
+/**
+* Base class for all harness errors. Carries a `code` (stable, programmatic —
+* e.g. `NO_ADAPTER`, `INVALID_ARGS`) distinct from the
+* human-readable `message`, and supports `cause` chaining via the standard
+* `ErrorOptions`. `name` defaults to the subclass constructor name.
+*/
+var HarnessError = class extends Error {
+	/** Stable machine-routable failure class (e.g. `RATE_LIMIT`); route on this, never by parsing `message`. */
+	code;
+	constructor(message, code, options) {
+		super(message, options);
+		this.code = code;
+		this.name = new.target.name;
+	}
+};
+//#endregion
+export { HarnessError };

package/lib/types/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Harness error base with a stable machine-routable code and chained cause.
+ * Package errors extend it so tool results and replay can retain failure class.
+ * @module @deepseek-ai/dsh-error
+ */
+/**
+ * Base class for all harness errors. Carries a `code` (stable, programmatic —
+ * e.g. `NO_ADAPTER`, `INVALID_ARGS`) distinct from the
+ * human-readable `message`, and supports `cause` chaining via the standard
+ * `ErrorOptions`. `name` defaults to the subclass constructor name.
+ */
+export declare class HarnessError extends Error {
+    /** Stable machine-routable failure class (e.g. `RATE_LIMIT`); route on this, never by parsing `message`. */
+    readonly code: string;
+    constructor(message: string, code: string, options?: ErrorOptions);
+}
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;GAKG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,4GAA4G;IAC5G,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;gBAET,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAKlE"}

package/lib/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;GAKG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IACrC,4GAA4G;IACnG,IAAI,CAAQ;IAErB,YAAY,OAAe,EAAE,IAAY,EAAE,OAAsB;QAC/D,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAA;IAC7B,CAAC;CACF"}

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@deepseek-ai/dsh-error",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Dependency-free HarnessError base class with a stable machine-routable code for the DeepSeek Harness",
+  "version": "0.2.2-rc.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/util/error"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "lib/**/*.js.map",
+    "src"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.1.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "~4.1.0"
+  }
 }

package/src/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Harness error base with a stable machine-routable code and chained cause.
+ * Package errors extend it so tool results and replay can retain failure class.
+ * @module @deepseek-ai/dsh-error
+ */
+
+/**
+ * Base class for all harness errors. Carries a `code` (stable, programmatic —
+ * e.g. `NO_ADAPTER`, `INVALID_ARGS`) distinct from the
+ * human-readable `message`, and supports `cause` chaining via the standard
+ * `ErrorOptions`. `name` defaults to the subclass constructor name.
+ */
+export class HarnessError extends Error {
+  /** Stable machine-routable failure class (e.g. `RATE_LIMIT`); route on this, never by parsing `message`. */
+  readonly code: string
+
+  constructor(message: string, code: string, options?: ErrorOptions) {
+    super(message, options)
+    this.code = code
+    this.name = new.target.name
+  }
+}