# agent-native 错误码映射

本轮不修改 Agent-Native。接入时用下表把现有字符串换成规范码。别名已登记，`Registry.Lookup` / `Resolve` 可直接吃旧值。

## contract.ErrorCode

来源：`Agent-Native/contract/contract.go`。

| 现有码 | 规范码 | HTTP | retry | side_effects | 说明 |
|---|---|---|---|---|---|
| canceled | agent.canceled | 499 | never | possible | 取消必须传播；不可靠取消保持 Unknown，不伪报 Canceled |
| deadline_exceeded | agent.deadline_exceeded | 408 | never | possible | 与重试共享 ExecutionID、预算与截止时间 |
| budget_exceeded | agent.budget_exceeded | 429 | never | possible | 预算耗尽不是瞬时故障 |
| provider_unavailable | agent.provider_unavailable | 503 | transient | none | 传输级有界重试归 adapter |
| provider_rejected | agent.provider_rejected | 502 | never | none | 请求被拒绝，修正后再发 |
| tool_rejected | agent.tool_rejected | 403 | never | none | 不得自行扩大工具范围 |
| path_outside_workspace | agent.path_outside_workspace | 403 | never | none | 路径授权不是 OS 沙箱 |
| missing_capability | agent.missing_capability | 400 | never | none | 缺能力即拒绝，不降级 Stub |
| missing_deliverable | agent.missing_deliverable | 422 | transient | possible | 可能已有部分写入 |
| empty_output | agent.empty_output | 422 | never | none | 空输出不是成功 |
| unknown_outcome | agent.unknown_outcome | 500 | never | possible | 禁止降级为 Succeeded 或 Failed |
| internal | agent.internal | 500 | never | unknown | 副作用不明，禁止无条件重放 |

`contract.Error.Retryable` 仍是实例字段。规范码上的 `retry` 只是默认策略：`Retryable=true` 且 `side_effects=none` 才适合 adapter 有界重试。

## pitransport typed-result-v1

来源：`Agent-Native/adapters/pitransport/resultv1.go` 的 `allowedErrorCodes`。

| 现有码 | 规范码 | 备注 |
|---|---|---|
| PROMPT_EMPTY | agent.prompt_empty | 永久失败，与 `AssessStepFailure` 的 prompt_empty 一致 |
| UNAUTHORIZED | agent.unauthorized | 永久失败 |
| TIMEOUT | agent.timeout | 可重试 |
| CANCELLED | agent.canceled | 并入契约取消码，不另起含义 |
| TRANSIENT | agent.transient | 可重试 |
| MISSING_TARGET | agent.missing_deliverable | 并入契约交付物缺失 |
| RUN_FAILED | agent.run_failed | 永久失败，副作用按 possible |

`TypedRetryable` 只承认 TIMEOUT / CANCELLED / TRANSIENT。映射后对应 `agent.timeout`、`agent.canceled`、`agent.transient`。其中 `agent.canceled` 的默认策略是 never：实例上的 `retryable` 仍可表达「传输层把取消当成可重试」，调用方必须再看副作用。

## exec 失败分类

`exec.FailureClass`（none / transient / permanent）不是错误码。步骤评估继续用 `AssessStepFailure`；对外报告时再选上表中的规范码。永久原因（prompt_empty、unauthorized、治理拦截）对应 never，提供方连接类对应 transient。