weichenandCursor
bd53e9ba79
Services can resolve legacy aliases and expose the catalog over CLI and HTTP instead of ad-hoc error strings. Co-authored-by: Cursor <cursoragent@cursor.com>
3.0 KiB
3.0 KiB
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。