Add a shared error-code catalog so failures can be traced by stable codes.

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>
2026-09-29 13:43:12 +00:00
commit bd53e9ba79
33 changed files with 2489 additions and 0 deletions
@@ -0,0 +1,209 @@
+[
+  {
+    "code": "agent.budget_exceeded",
+    "http": 429,
+    "severity": "error",
+    "retry": "never",
+    "side_effects": "possible",
+    "summary": "执行预算耗尽",
+    "hint": "提高预算或缩小任务后再发起新的执行",
+    "aliases": [
+      "budget_exceeded"
+    ]
+  },
+  {
+    "code": "agent.canceled",
+    "http": 499,
+    "severity": "info",
+    "retry": "never",
+    "side_effects": "possible",
+    "summary": "执行已取消",
+    "hint": "确认取消已传播到模型、工具与子进程；不要伪报成功",
+    "aliases": [
+      "CANCELLED",
+      "canceled"
+    ]
+  },
+  {
+    "code": "agent.deadline_exceeded",
+    "http": 408,
+    "severity": "error",
+    "retry": "never",
+    "side_effects": "possible",
+    "summary": "超过执行截止时间",
+    "hint": "预算与截止时间在同一 ExecutionID 内共享，不要换 ID 无条件重放",
+    "aliases": [
+      "deadline_exceeded"
+    ]
+  },
+  {
+    "code": "agent.empty_output",
+    "http": 422,
+    "severity": "error",
+    "retry": "never",
+    "side_effects": "none",
+    "summary": "输出为空",
+    "hint": "检查提示词与停止原因，不要把空输出当成成功",
+    "aliases": [
+      "empty_output"
+    ]
+  },
+  {
+    "code": "agent.internal",
+    "http": 500,
+    "severity": "error",
+    "retry": "never",
+    "side_effects": "unknown",
+    "summary": "执行器内部错误",
+    "hint": "保留执行日志与 trace_id，不要对未知副作用无条件重放",
+    "aliases": [
+      "internal"
+    ]
+  },
+  {
+    "code": "agent.missing_capability",
+    "http": 400,
+    "severity": "error",
+    "retry": "never",
+    "side_effects": "none",
+    "summary": "后端缺少必需能力",
+    "hint": "拒绝执行，不要静默降级到 Stub",
+    "aliases": [
+      "missing_capability"
+    ]
+  },
+  {
+    "code": "agent.missing_deliverable",
+    "http": 422,
+    "severity": "error",
+    "retry": "transient",
+    "side_effects": "possible",
+    "summary": "交付物缺失",
+    "hint": "确认目标文件未部分写入后再做一次有界重试",
+    "aliases": [
+      "MISSING_TARGET",
+      "missing_deliverable"
+    ]
+  },
+  {
+    "code": "agent.path_outside_workspace",
+    "http": 403,
+    "severity": "error",
+    "retry": "never",
+    "side_effects": "none",
+    "summary": "路径越出授权工作区",
+    "hint": "只访问 Workspace.Root 之内的路径",
+    "aliases": [
+      "path_outside_workspace"
+    ]
+  },
+  {
+    "code": "agent.prompt_empty",
+    "http": 400,
+    "severity": "warn",
+    "retry": "never",
+    "side_effects": "none",
+    "summary": "提示词为空",
+    "hint": "补齐 prompt 后重新发起；对应 pitransport PROMPT_EMPTY",
+    "aliases": [
+      "PROMPT_EMPTY",
+      "prompt_empty"
+    ]
+  },
+  {
+    "code": "agent.provider_rejected",
+    "http": 502,
+    "severity": "error",
+    "retry": "never",
+    "side_effects": "none",
+    "summary": "模型提供方拒绝请求",
+    "hint": "检查模型名、请求体与账号权限，不要当瞬时故障重试",
+    "aliases": [
+      "provider_rejected"
+    ]
+  },
+  {
+    "code": "agent.provider_unavailable",
+    "http": 503,
+    "severity": "error",
+    "retry": "transient",
+    "side_effects": "none",
+    "summary": "模型提供方不可用",
+    "hint": "视为传输级瞬时故障，只做有界重试",
+    "aliases": [
+      "provider_unavailable"
+    ]
+  },
+  {
+    "code": "agent.run_failed",
+    "http": 500,
+    "severity": "error",
+    "retry": "never",
+    "side_effects": "possible",
+    "summary": "执行运行失败",
+    "hint": "查看 error_code 以外的运行日志；对应 pitransport RUN_FAILED",
+    "aliases": [
+      "RUN_FAILED"
+    ]
+  },
+  {
+    "code": "agent.timeout",
+    "http": 504,
+    "severity": "error",
+    "retry": "transient",
+    "side_effects": "possible",
+    "summary": "执行超时",
+    "hint": "传输级超时可有界重试；对应 pitransport TIMEOUT",
+    "aliases": [
+      "TIMEOUT"
+    ]
+  },
+  {
+    "code": "agent.tool_rejected",
+    "http": 403,
+    "severity": "error",
+    "retry": "never",
+    "side_effects": "none",
+    "summary": "工具调用被拒绝",
+    "hint": "工具不在允许范围内；不要自行扩大工具策略",
+    "aliases": [
+      "tool_rejected"
+    ]
+  },
+  {
+    "code": "agent.transient",
+    "http": 503,
+    "severity": "error",
+    "retry": "transient",
+    "side_effects": "possible",
+    "summary": "执行瞬时故障",
+    "hint": "仅作有界重试；对应 pitransport TRANSIENT",
+    "aliases": [
+      "TRANSIENT"
+    ]
+  },
+  {
+    "code": "agent.unauthorized",
+    "http": 401,
+    "severity": "warn",
+    "retry": "never",
+    "side_effects": "none",
+    "summary": "执行器鉴权失败",
+    "hint": "检查 runner 凭证；对应 pitransport UNAUTHORIZED",
+    "aliases": [
+      "UNAUTHORIZED"
+    ]
+  },
+  {
+    "code": "agent.unknown_outcome",
+    "http": 500,
+    "severity": "error",
+    "retry": "never",
+    "side_effects": "possible",
+    "summary": "执行结果不确定",
+    "hint": "Unknown 不得降级为成功或失败；由调用方依据副作用决定能否重放",
+    "aliases": [
+      "unknown_outcome"
+    ]
+  }
+]