chore: initial commit with Phase 0 setup

2026-06-06 22:55:45 +08:00
commit 9e79e58f87
56 changed files with 16088 additions and 0 deletions
--- a/packages/contracts/src/errors/index.ts
+++ b/packages/contracts/src/errors/index.ts
@@ -0,0 +1,101 @@
+/**
+ * @agent-bounty/contracts — Error Codes
+ *
+ * 所有 API / MCP 層的標準錯誤碼。
+ * 格式：VW_<DOMAIN>_<CODE>
+ */
+
+// ─────────────────────────────────────────────
+// Task 操作錯誤
+// ─────────────────────────────────────────────
+
+export const TaskErrorCode = {
+  // claim_task
+  TASK_NOT_FOUND: "VW_TASK_NOT_FOUND",
+  TASK_NOT_OPEN: "VW_TASK_NOT_OPEN",                   // 狀態不是 OPEN，無法 claim
+  TASK_ALREADY_CLAIMED: "VW_TASK_ALREADY_CLAIMED",     // 409 Race Condition（SELECT FOR UPDATE 失敗）
+  TASK_CLAIM_LIMIT_REACHED: "VW_TASK_CLAIM_LIMIT_REACHED", // Agent 已達同時接案上限
+  TASK_AGENT_SUSPENDED: "VW_TASK_AGENT_SUSPENDED",     // Agent 被降權或封鎖
+
+  // submit_solution
+  TASK_NOT_EXECUTING: "VW_TASK_NOT_EXECUTING",         // 無法提交，任務不在 EXECUTING
+  TASK_SUBMIT_UNAUTHORIZED: "VW_TASK_SUBMIT_UNAUTHORIZED", // 403，非任務持有者提交
+  TASK_PAYLOAD_TOO_LARGE: "VW_TASK_PAYLOAD_TOO_LARGE", // 413，超過 payload 上限
+  TASK_FILE_COUNT_EXCEEDED: "VW_TASK_FILE_COUNT_EXCEEDED", // 超過最大檔案數（20）
+
+  // 通用
+  TASK_INVALID_INPUT: "VW_TASK_INVALID_INPUT",
+  TASK_FORBIDDEN: "VW_TASK_FORBIDDEN",
+} as const;
+export type TaskErrorCode = (typeof TaskErrorCode)[keyof typeof TaskErrorCode];
+
+// ─────────────────────────────────────────────
+// Judge 執行錯誤
+// ─────────────────────────────────────────────
+
+export const JudgeErrorCode = {
+  JUDGE_TIMEOUT: "VW_JUDGE_TIMEOUT",
+  JUDGE_SANDBOX_UNAVAILABLE: "VW_JUDGE_SANDBOX_UNAVAILABLE",
+  JUDGE_IMAGE_NOT_FOUND: "VW_JUDGE_IMAGE_NOT_FOUND",
+  JUDGE_INVALID_RESULT: "VW_JUDGE_INVALID_RESULT",
+  JUDGE_ALREADY_RUNNING: "VW_JUDGE_ALREADY_RUNNING",   // 冪等保護：同一任務重複觸發
+} as const;
+export type JudgeErrorCode = (typeof JudgeErrorCode)[keyof typeof JudgeErrorCode];
+
+// ─────────────────────────────────────────────
+// 金流錯誤
+// ─────────────────────────────────────────────
+
+export const SettlementErrorCode = {
+  PAYMENT_INTENT_NOT_FOUND: "VW_PAYMENT_INTENT_NOT_FOUND",
+  AUTH_HOLD_FAILED: "VW_AUTH_HOLD_FAILED",
+  CAPTURE_FAILED: "VW_CAPTURE_FAILED",
+  RELEASE_FAILED: "VW_RELEASE_FAILED",
+  REFUND_FAILED: "VW_REFUND_FAILED",
+  IDEMPOTENCY_CONFLICT: "VW_IDEMPOTENCY_CONFLICT",     // 同 key 但不同金額
+  LEDGER_DRIFT_DETECTED: "VW_LEDGER_DRIFT_DETECTED",  // 對帳漂移，啟動 incident
+  DUPLICATE_WEBHOOK: "VW_DUPLICATE_WEBHOOK",           // webhook 重複接收
+} as const;
+export type SettlementErrorCode = (typeof SettlementErrorCode)[keyof typeof SettlementErrorCode];
+
+// ─────────────────────────────────────────────
+// Lead / Scout 錯誤
+// ─────────────────────────────────────────────
+
+export const LeadErrorCode = {
+  LEAD_NOT_FOUND: "VW_LEAD_NOT_FOUND",
+  LEAD_EXPIRED: "VW_LEAD_EXPIRED",
+  LEAD_INVALID_TEMPLATE: "VW_LEAD_INVALID_TEMPLATE",   // Scout 使用未授權模板
+  SCOUT_RATE_LIMIT: "VW_SCOUT_RATE_LIMIT",
+  SCOUT_SUSPENDED: "VW_SCOUT_SUSPENDED",
+  ATTRIBUTION_TOKEN_INVALID: "VW_ATTRIBUTION_TOKEN_INVALID",
+} as const;
+export type LeadErrorCode = (typeof LeadErrorCode)[keyof typeof LeadErrorCode];
+
+// ─────────────────────────────────────────────
+// 通用 API 錯誤
+// ─────────────────────────────────────────────
+
+export const CommonErrorCode = {
+  UNAUTHORIZED: "VW_UNAUTHORIZED",
+  FORBIDDEN: "VW_FORBIDDEN",
+  VALIDATION_ERROR: "VW_VALIDATION_ERROR",
+  RATE_LIMITED: "VW_RATE_LIMITED",
+  INTERNAL_ERROR: "VW_INTERNAL_ERROR",
+  SERVICE_UNAVAILABLE: "VW_SERVICE_UNAVAILABLE",
+} as const;
+export type CommonErrorCode = (typeof CommonErrorCode)[keyof typeof CommonErrorCode];
+
+// ─────────────────────────────────────────────
+// 統一 error response 結構（MCP + REST 共用）
+// ─────────────────────────────────────────────
+
+export interface VWError {
+  code: string;
+  message: string;
+  details?: Record<string, unknown>;
+  /** 若為 true，呼叫方可在稍後重試 */
+  retryable?: boolean;
+  /** 建議的重試等待秒數 */
+  retryAfterSeconds?: number;
+}