2026-06-11implementedarchitecture

Structured error taxonomy

结构化错误分类体系

Failures crossed seams as bare strings. A tool error flattened to a text block — name, code, and stack lost — so a future sandbox/retry plugin couldn't tell ENOENT from EACCES, and the model got less actionable feedback than it could. A non-Error throw degraded further: the loop wrapped it in `new Error(String(x))`, dropping any code. And `LlmError` was the only typed error in the system, with no shared base, so ther

.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.md

English

Problem

Failures crossed seams as bare strings. A tool error flattened to a text block — name, code, and stack lost — so a future sandbox/retry plugin couldn't tell ENOENT from EACCES, and the model got less actionable feedback than it could. A non-Error throw degraded further: the loop wrapped it in new Error(String(x)), dropping any code. And LlmError was the only typed error in the system, with no shared base, so there was nothing for a consumer to instanceof against generically.

Decision

A single HarnessError extends Error base in dsh-llm (the leaf package every other imports — no new dependency edge): a stable code distinct from message, cause chaining via ErrorOptions, and name defaulting to the subclass. isHarnessError narrows at seams.

LlmError and ToolArgsError (dsh-tools) extend it, keeping their existing codes.
ToolExecutionResult gains optional error: { name, code }, populated in the registry's catch when the thrown value is a HarnessError. The agent loop forwards it onto the tool/result session event (which gained the same optional field), so the structured failure survives into the log for retry/sandbox plugins and replay. The model-facing text block is unchanged.
The loop's toError wraps a non-Error throw in a HarnessError (code: 'UNKNOWN', original chained as cause) instead of a bare Error, so even a bad throw carries a routable code into the session error event (which already surfaced code).

Consequences

Errors are machine-routable end-to-end: a plugin can branch on error.code rather than substring-matching a message.
One base class is imported widely, but it lives in the package everyone already depends on, so the cost is a single import, not a new edge.
deriveMessages does not surface error into model history — the model still sees the text block; the structured field is for code and replay.
Argument validation retains its existing code and behavior; package-owned diagnostic invariants carry their stable code independently so the invariant registry does not import a product package. The shared base adds cross-seam routing metadata without changing model-facing text.

中文

问题

故障跨越 seam 时只是裸字符串。工具错误被扁平化为一个文本块（name、code 和 stack 全部丢失），导致未来的沙箱/重试插件无法区分 ENOENT 和 EACCES，模型也未能获得本可提供的更具可操作性的反馈。非 Error 的 throw 退化更严重：agent loop（智能体循环）将其包装为 new Error(String(x))，丢弃了所有 code。而 LlmError 是系统中唯一的类型化错误，没有共享基类，消费方无法对其进行通用的 instanceof 判断。

决策

在 dsh-llm（叶子包，所有其他包都已依赖它，不引入新的依赖边）中引入一个 HarnessError extends Error 基类：稳定的 code（与 message 分离）、通过 ErrorOptions 进行 cause 链接、name 默认为子类名。isHarnessError 在 seam 处做类型收窄。

LlmError 和 ToolArgsError（dsh-tools）继承该基类，保留各自既有的 code。
ToolExecutionResult 新增可选字段 error: { name, code }，在注册表的 catch 中当抛出值为 HarnessError 时填充。agent loop 将其转发到 tool/result 会话事件（该事件也新增了同一可选字段），使结构化的失败信息保留在日志中，供重试/沙箱插件和回放使用。面向模型的文本块保持不变。
agent loop 的 toError 将非 Error 的 throw 包装为 HarnessError（code: 'UNKNOWN'，原始值作为 cause 链接），而非裸 Error；这样即使是不规范的 throw 也能携带可路由的 code 进入会话的 error 事件（该事件此前已暴露 code）。

后果

错误端到端可机器路由：插件可以基于 error.code 分支，而无需对消息做子串匹配。
一个基类被广泛导入，但它位于所有包已经依赖的包中，代价仅是一条 import 语句，而非新的依赖边。
deriveMessages 不会将 error 暴露到模型历史中——模型仍然看到文本块；结构化字段服务于代码和回放。
参数校验保留其既有的 code 和行为；包自有的诊断不变式独立携带稳定 code，使不变式注册表无需导入产品包。共享基类增加了跨 seam 的路由元数据，不改变面向模型的文本。