@hopping-dev/hub 0.1.0

package/node_modules/@hopping/shared/types.ts

@@ -0,0 +1,895 @@
+// ============================================
+// HopPing 共享型別定義
+// 跨 Hub / Backend / Mobile / Hooks 共用
+// ============================================
+
+// ============================================
+// Section 1：通用 Enums / Literal Unions
+// ============================================
+
+/** 風險等級（Cloud ApprovalSummary.riskLevel + Hub operations.risk_level） */
+export type RiskLevel = 'low' | 'medium' | 'high' | 'critical';
+
+/** 審核決策（Cloud ApprovalSummary.decision） */
+export type ApprovalDecision = 'approved' | 'denied' | 'conditional' | 'timeout' | 'pending';
+
+/** 超時行為子集（toApprovalDecision() 的輸出集合，不含 conditional） */
+export type TimeoutDecision = 'approved' | 'denied' | 'timeout' | 'pending';
+
+/** Agent 連線狀態（Cloud Agent.status） */
+export type AgentStatus = 'online' | 'offline' | 'error';
+
+// ============================================
+// Section 2：Agent Types
+// ============================================
+
+export type AgentType = 'claude_code' | 'cursor' | 'generic_mcp';
+
+export type AgentCapability =
+  | 'shell_execution'
+  | 'file_operations'
+  | 'mcp_tools'
+  | 'composer_mode'
+  | 'web_scraping'
+  | 'code_generation';
+
+/** @deprecated 請改用 AgentStatus */
+export type AgentConnectionStatus = AgentStatus;
+
+export interface AgentInfo {
+  id: string;
+  type: AgentType;
+  name: string;
+  version: string;
+  capabilities: AgentCapability[];
+  connectedAt: string;
+  status: AgentStatus;
+}
+
+/**
+ * 根據 clientInfo.name 識別 Agent 類型
+ */
+export function identifyAgentType(clientName: string): AgentType {
+  const normalized = clientName.toLowerCase();
+
+  const mapping: Record<string, AgentType> = {
+    cursor: 'cursor',
+    'cursor-agent': 'cursor',
+    'claude-code': 'claude_code',
+    claudecode: 'claude_code',
+    'claude code': 'claude_code',
+  };
+
+  if (mapping[normalized]) {
+    return mapping[normalized];
+  }
+
+  for (const [key, type] of Object.entries(mapping)) {
+    if (normalized.includes(key)) {
+      return type;
+    }
+  }
+
+  return 'generic_mcp';
+}
+
+// ============================================
+// Section 3：Policy Types
+// ============================================
+
+export type PolicyAction = 'WARN' | 'ASK' | 'ALLOW';
+
+export type PolicyType =
+  | 'command_filter'
+  | 'file_protection'
+  | 'cost_limit'
+  | 'time_restriction'
+  | 'network_filter'
+  | 'custom';
+
+export type PolicyConditionField =
+  | 'command'
+  | 'command_args'
+  | 'file_path'
+  | 'file_extension'
+  | 'file_action'
+  | 'sql_statement'
+  | 'api_endpoint'
+  | 'token_cost'
+  | 'session_cost'
+  | 'time_of_day'
+  | 'agent_type'
+  | 'action_type'
+  | 'target'
+  | 'tool_name';
+
+export type PolicyConditionOperator =
+  | 'equals'
+  | 'not_equals'
+  | 'contains'
+  | 'not_contains'
+  | 'matches_regex'
+  | 'greater_than'
+  | 'less_than'
+  | 'in_list'
+  | 'not_in_list';
+
+export interface PolicyCondition {
+  field: PolicyConditionField;
+  operator: PolicyConditionOperator;
+  value: string | number | string[];
+  caseSensitive?: boolean;
+}
+
+export interface Policy {
+  id: string;
+  name: string;
+  description: string;
+  type: PolicyType;
+  enabled: boolean;
+  priority: number;
+  isSystem: boolean;
+  conditions: PolicyCondition[];
+  action: PolicyAction;
+  scope: {
+    agentTypes?: AgentType[];
+    agentIds?: string[];
+  };
+}
+
+export interface TriggeredPolicy {
+  policyId: string;
+  policyName: string;
+  action: PolicyAction;
+  matchedConditions: MatchedCondition[];
+}
+
+export interface MatchedCondition {
+  field: string;
+  operator: string;
+  expected: unknown;
+  actual: unknown;
+}
+
+export interface PolicyEvaluationResult {
+  requestId: string;
+  finalAction: PolicyAction;
+  triggeredPolicies: TriggeredPolicy[];
+  evaluationTimeMs: number;
+  evaluatedAt: string;
+}
+
+export interface EvaluationContext {
+  requestId: string;
+  agentId: string;
+  agentType: AgentType;
+  operation: {
+    type: string;
+    target?: string;
+    toolName?: string;
+    command?: string;
+    filePath?: string;
+    sqlStatement?: string;
+    apiEndpoint?: string;
+  };
+  session: {
+    costUsd: number;
+    durationSeconds: number;
+    approvalCount: number;
+  };
+  timestamp: string;
+}
+
+// ============================================
+// Section 3b：Rich Permission 基礎型別（PermissionPromptPayload 的依賴型別）
+// ============================================
+
+/** Prompt 互動類型（預設 'approval'） */
+export type PromptType = 'approval' | 'native_permission' | 'question';
+
+/** 回應格式類型（預設 'binary'） */
+export type ResponseType = 'binary' | 'choice' | 'freetext';
+
+/** hopping.ask 支援的回應格式（排除 binary，ask 不支援二元回應） */
+export type AskResponseType = Exclude<ResponseType, 'binary'>;
+
+/** 選擇題選項 */
+export interface PromptOption {
+  id: string;
+  label: string;
+  description?: string;
+  /** 若為 true，Mobile 選中後展開 textarea 讓用戶輸入自訂文字。
+   *  回應時 answer = option.id，customText = 用戶輸入內容。
+   *  Agent 應優先讀取 customText（若有值）作為實際指令。 */
+  isOther?: boolean;
+}
+
+/** 被審核工具的上下文（描述「要執行什麼」，與 taskContext 的「在做什麼」語意不同） */
+export interface ToolContext {
+  /** 工具的人類可讀描述（如 "執行 Shell 指令"） */
+  description?: string;
+  /** 工具的完整參數（型別與 HoppingCheckInput.toolInput 一致；
+   *  結構化工具參數屬 Tool Registry 層，不在此處定義） */
+  parameters?: Record<string, unknown>;
+}
+
+// ============================================
+// Section 4：WebSocket 事件型別（Socket.IO 型別安全）
+// Hub ↔ Cloud ↔ Mobile 全 9 事件
+// ============================================
+
+// --- Hub → Cloud → Mobile ---
+
+export interface PermissionPromptPayload {
+  id: string; // approval ID
+  agentId: string;
+  toolName: string;
+  riskLevel: RiskLevel;
+  summary: string; // 簡短摘要（顯示在通知/卡片）
+  policyAction: PolicyAction; // WARN | ASK
+  sessionId?: string;
+  timestamp: string;
+  /** Hub 對此審核實際使用的超時時間（ms）。Cloud 用此值排程自己的超時清理 job（delay = timeoutMs + buffer）。
+   *  舊版 Hub 不包含此欄位時，Cloud 使用 300,000ms (5 min) 作為 fallback。 */
+  timeoutMs?: number;
+  /** Hub 配置的超時行為（TimeoutDecision — 不含 conditional）。Cloud 用此值決定排程策略：
+   *  'pending' → 使用 PENDING_SAFETY_NET_MS（12h）延長排程；其他值 → 使用 timeoutMs + buffer。
+   *  undefined → 向下相容，使用預設排程（same as 'timeout'）。 */
+  onTimeout?: TimeoutDecision;
+  /** 任務上下文（truncated 200 chars each，不含 userPrompt） */
+  taskContext?: {
+    taskDescription?: string;
+    reasoning?: string;
+  };
+  /** Prompt 互動類型（預設 'approval'；舊版 Hub 不送此欄位時 Mobile 使用 'approval'） */
+  promptType?: PromptType;
+  /** 回應格式（預設 'binary'；舊版 Hub 不送此欄位時 Mobile 使用 'binary'） */
+  responseType?: ResponseType;
+  /** 選擇題選項（responseType='choice' 時有效） */
+  options?: PromptOption[];
+  /** 自由輸入提示文字（responseType='freetext' 時有效） */
+  placeholder?: string;
+  /** 被審核工具的上下文（工具描述 + 完整參數，Mobile 用於顯示更豐富的審核資訊） */
+  toolContext?: ToolContext;
+}
+
+export interface AgentStatusPayload {
+  agentId: string;
+  status: AgentStatus;
+  agentName?: string;
+  agentType?: AgentType;
+  timestamp: string;
+  agentMode?: AgentMode; // YOLO 模式時為 'yolo'，一般為 'normal' 或省略
+  agentModeChangedAt?: string; // ISO 8601 UTC — Hub 進入 YOLO 模式的時間戳，切回 normal 時省略
+}
+
+export type ProgressMessageType =
+  | 'progress'
+  | 'command_ack'
+  | 'status_report'
+  | 'operation_report'
+  | 'task_completed'
+  | 'yolo_observation';
+
+export interface ProgressUpdatePayload {
+  agentId: string;
+  sessionId: string;
+  message: string;
+  progress?: number; // 0–100
+  timestamp: string;
+  messageType?: ProgressMessageType;
+  // YOLO 觀測欄位（全部 optional，向下相容）
+  toolName?: string; // YOLO: 被 auto-approved 的工具名
+  riskLevel?: RiskLevel; // YOLO: Policy Engine 評估的風險等級
+  decision?: string; // YOLO: 'auto_approved'
+  filePaths?: string[]; // YOLO: 受影響的檔案路徑
+}
+
+// --- Mobile → Cloud → Hub ---
+
+export interface PermissionResponsePayload {
+  id: string; // 對應 approval ID
+  decision: ApprovalDecision;
+  reason?: string;
+  respondedBy?: string; // user ID
+  timestamp?: string; // Mobile 回應時間（Cloud 可用於 decidedAt）
+  /** 用戶選擇的選項 ID（responseType='choice' 時） */
+  selectedOption?: string;
+  /** 用戶輸入的自由文字（responseType='freetext' 時） */
+  freetext?: string;
+  /** 當選擇 isOther=true 選項時，用戶輸入的自訂文字（選擇題 + 自訂輸入的組合回應） */
+  customText?: string;
+}
+
+export interface DetailRequestPayload {
+  operationId: string;
+}
+
+/** YOLO session 操作歷史項目（Hub → Cloud → Mobile，透過 stats_response.timeline 傳遞） */
+export interface SessionTimelineItem {
+  operationId: string;
+  toolName: string;
+  riskLevel: RiskLevel | null;
+  decision: string | null;
+  durationMs: number | null;
+  source: string | null;
+  createdAt: string;
+}
+
+export interface StatsRequestPayload {
+  agentId: string;
+  period?: 'day' | 'week' | 'month';
+  /** JS getTimezoneOffset() semantics: minutes west of UTC. UTC+8 = -480, UTC-7 = 420. Defaults to 0 (UTC). */
+  timezoneOffset?: number;
+  /** 查詢類型：'stats'（預設）或 'session_timeline'（YOLO 歷史補齊） */
+  type?: 'stats' | 'session_timeline';
+  /** session_timeline 專用：最多回傳筆數（預設 100） */
+  limit?: number;
+  /** session_timeline 專用：指定 session（不傳則由 Hub 查最近操作） */
+  sessionId?: string;
+}
+
+export interface CommandPayload {
+  agentId: string;
+  command: string;
+  args?: Record<string, unknown>;
+}
+
+export interface StatsRequestBatchPayload {
+  agentIds: string[];
+  period?: 'day' | 'week' | 'month';
+  /** JS getTimezoneOffset() semantics: minutes west of UTC. UTC+8 = -480, UTC-7 = 420. Defaults to 0 (UTC). */
+  timezoneOffset?: number;
+}
+
+export interface StatsResponseBatchPayload {
+  results: StatsResponsePayload[];
+  period: 'day' | 'week' | 'month';
+}
+
+// --- Hub → Cloud → Mobile（回應）---
+
+/** detail_response 錯誤碼 — Gateway 透傳層產生 */
+export const DETAIL_RESPONSE_ERRORS = {
+  INVALID_OPERATION_ID: 'INVALID_OPERATION_ID',
+  NOT_FOUND: 'NOT_FOUND',
+  FORBIDDEN: 'FORBIDDEN',
+  HUB_OFFLINE: 'HUB_OFFLINE',
+  INTERNAL_ERROR: 'INTERNAL_ERROR',
+} as const;
+
+export type DetailResponseError =
+  (typeof DETAIL_RESPONSE_ERRORS)[keyof typeof DETAIL_RESPONSE_ERRORS];
+
+export interface DetailResponsePayload {
+  operationId: string;
+  toolName: string;
+  toolParams?: Record<string, unknown>;
+  filePaths?: string[];
+  riskLevel?: RiskLevel;
+  decision?: ApprovalDecision;
+  createdAt: string;
+  decidedAt?: string;
+  /** 操作元資料（來自 Hub SQLite metadata 表，透過 detail_request 透傳） */
+  metadata?: {
+    agentType?: string;
+    sessionId?: string;
+    durationMs?: number | null;
+    contextTags?: Record<string, unknown> | null;
+    source?: OperationSource;
+    resultStatus?: ResultStatus;
+    toolResultSummary?: string;
+  };
+  /** Gateway 錯誤碼 — 存在時表示無法取得詳情 */
+  error?: DetailResponseError;
+}
+
+/** stats_response 錯誤碼 — Gateway 透傳層產生 */
+export const STATS_RESPONSE_ERRORS = {
+  INVALID_AGENT_ID: 'INVALID_AGENT_ID',
+  AGENT_NOT_FOUND: 'AGENT_NOT_FOUND',
+  HUB_OFFLINE: 'HUB_OFFLINE',
+  TIMEOUT: 'TIMEOUT',
+  INTERNAL_ERROR: 'INTERNAL_ERROR',
+} as const;
+
+export type StatsResponseError = (typeof STATS_RESPONSE_ERRORS)[keyof typeof STATS_RESPONSE_ERRORS];
+
+export interface StatsResponsePayload {
+  agentId: string;
+  period: 'day' | 'week' | 'month';
+  totalOperations: number;
+  approvedCount: number;
+  deniedCount: number;
+  autoApprovedCount: number;
+  topTools: Array<{ toolName: string; count: number }>;
+  /** Gateway 錯誤碼 — 存在時表示無法取得統計資料 */
+  error?: StatsResponseError;
+  /** YOLO session 操作歷史（type=session_timeline 時填充） */
+  timeline?: SessionTimelineItem[];
+}
+
+// --- Socket.IO Typed Events ---
+
+export interface ServerToClientEvents {
+  permission_prompt: (payload: PermissionPromptPayload) => void;
+  agent_status: (payload: AgentStatusPayload) => void;
+  progress_update: (payload: ProgressUpdatePayload) => void;
+  detail_response: (payload: DetailResponsePayload) => void;
+  stats_response: (payload: StatsResponsePayload) => void;
+  stats_response_batch: (payload: StatsResponseBatchPayload) => void;
+}
+
+export interface ClientToServerEvents {
+  permission_response: (payload: PermissionResponsePayload) => void;
+  detail_request: (payload: DetailRequestPayload) => void;
+  stats_request: (payload: StatsRequestPayload) => void;
+  stats_request_batch: (payload: StatsRequestBatchPayload) => void;
+  command: (payload: CommandPayload) => void;
+}
+
+// Hub → Cloud（同 ServerToClient，Cloud 透傳）
+export type HubToCloudEvents = ServerToClientEvents;
+
+// Cloud → Hub（同 ClientToServer，Cloud 透傳）
+export type CloudToHubEvents = ClientToServerEvents;
+
+// ============================================
+// Section 5：MCP Tool 型別
+// ============================================
+
+export type HoppingToolName =
+  | 'hopping.check'
+  | 'hopping.report'
+  | 'hopping.status'
+  | 'hopping.pair'
+  | 'hopping.respond'
+  | 'hopping.ask'
+  | 'hopping.mode';
+
+// hopping.check — Agent 呼叫審核
+export interface HoppingCheckInput {
+  toolName: string; // 被檢查的工具名
+  toolInput: Record<string, unknown>; // 被檢查工具的參數
+  sessionId?: string;
+  cwd?: string;
+  context?: {
+    recentFiles?: string[];
+    branch?: string;
+    project?: string;
+    /** Agent 正在執行的任務描述（由 Skill 引導提供） */
+    taskDescription?: string;
+    /** Agent 為什麼需要此操作的推理（由 Skill 引導提供） */
+    reasoning?: string;
+    /** 用戶的原始 prompt（敏感資料，僅存本地 Hub SQLite，不送 Cloud） */
+    userPrompt?: string;
+  };
+}
+
+export interface HoppingCheckOutput {
+  approvalId: string;
+  decision: ApprovalDecision;
+  riskLevel: RiskLevel;
+  policyResult: PolicyEvaluationResult;
+  message: string; // human-readable 結果說明
+  waitedForRemote: boolean; // 是否等了手機回覆
+}
+
+// hopping.report — Agent 自報操作（無 Hook 的 Agent 用）
+export interface HoppingReportInput {
+  toolName: string;
+  toolParams?: Record<string, unknown>;
+  result?: string;
+  duration?: number; // ms
+  success?: boolean;
+  filePaths?: string[];
+  sessionId?: string; // Agent session ID（覆蓋 deps.agentId fallback）
+  agentType?: string; // Agent 類型（覆蓋 deps.agentType）
+  context?: {
+    branch?: string;
+    project?: string;
+    cwd?: string;
+    taskCompleted?: boolean;
+  };
+}
+
+export interface HoppingReportOutput {
+  recorded: boolean;
+  operationId: string;
+}
+
+// hopping.status — 查詢 Hub 狀態
+export interface HoppingStatusInput {
+  query?: 'sessions' | 'pending' | 'stats' | 'all';
+  agentId?: string;
+}
+
+export interface HoppingStatusOutput {
+  activeSessions: number;
+  pendingApprovals: number;
+  todayOperations: number;
+  hubUptime: number; // seconds
+  connectedToCloud: boolean;
+  /** S4-HUB-DONTASK-001: Don't-ask-again tools currently in session memory */
+  sessionMemory?: Array<{ toolName: string; riskLevel: RiskLevel; addedAt: number }>;
+}
+
+// hopping.respond — Skill 驅動的本地審核（S2-HUB-APR-002）
+export interface HoppingRespondInput {
+  approvalId: string;
+  decision: 'approved' | 'denied';
+  reason?: string;
+}
+
+export interface HoppingRespondOutput {
+  success: boolean;
+  decision?: ApprovalDecision;
+  source?: 'local' | 'remote';
+  error?: string;
+}
+
+// hopping.ask — Agent 向用戶發送非審核類問題（選擇題或自由填寫）
+export interface HoppingAskInput {
+  question: string;
+  responseType: AskResponseType;
+  options?: PromptOption[];
+  placeholder?: string;
+  context?: {
+    taskDescription?: string;
+    reasoning?: string;
+  };
+}
+
+/** hopping.ask 回應狀態 */
+export type AskStatus = 'ask_locally' | 'answered' | 'timeout';
+
+export interface HoppingAskOutput {
+  questionId: string;
+  /** 回應狀態：ask_locally（local 模式立即回傳）、answered（away 模式收到回答）、timeout（away 模式超時） */
+  status: AskStatus;
+  /** responseType='choice' 時為選中的 option.id；responseType='freetext' 時為用戶輸入文字 */
+  answer: string;
+  /** 當用戶選擇 isOther=true 選項時，用戶輸入的自訂文字。
+   *  Agent 應優先讀取 customText（若有值）作為實際指令，answer 為選項 id。 */
+  customText?: string;
+  respondedBy: 'mobile' | 'local';
+  message: string;
+}
+
+// hopping.mode — Local/Away 模式切換
+export type AskMode = 'local' | 'away';
+
+export interface HoppingModeInput {
+  mode: AskMode;
+}
+
+export interface HoppingModeOutput {
+  mode: AskMode;
+  message: string;
+}
+
+/** hopping.ask 的 timeout 設定（~/.hopping/config.json askConfig section） */
+export interface AskConfig {
+  timeoutEnabled: boolean;
+  timeoutMs: number;
+}
+
+// hopping.pair — Agent 呼叫配對流程
+export interface HoppingPairInput {
+  pairingCode: string;
+  cloudUrl?: string; // 覆蓋預設 Cloud URL
+}
+
+export interface HoppingPairOutput {
+  paired: boolean;
+  agentId?: string;
+  agentName?: string;
+  connectedToCloud: boolean;
+  message: string;
+}
+
+// ============================================
+// Section 6：Hub SQLite 記錄型別
+// ============================================
+
+/** operations 表對應 */
+export interface OperationRecord {
+  id: string;
+  approvalId: string | null;
+  toolName: string;
+  toolParams: string | null; // JSON string
+  filePaths: string | null; // JSON array string
+  riskLevel: RiskLevel | null;
+  decision: ApprovalDecision | null;
+  createdAt: string; // ISO 8601
+  decidedAt: string | null;
+  /** Claude Code tool_use_id — pre/post 關聯鍵（v3 新增） */
+  toolUseId: string | null;
+  /** Prompt 互動類型（v4 新增） */
+  promptType?: PromptType | null;
+  /** 回應格式類型（v4 新增） */
+  responseType?: ResponseType | null;
+  /** Rich response JSON：{ selectedOption?, freetext?, customText? }（v4 新增） */
+  responseData?: string | null;
+}
+
+/** metadata.source 的值域 */
+export type OperationSource = 'check' | 'report' | 'hook';
+
+/** metadata.result_status 的值域 */
+export type ResultStatus = 'success' | 'failure' | 'unknown';
+
+/** metadata 表對應 */
+export interface OperationMetadataRecord {
+  id: number;
+  operationId: string;
+  agentType: string;
+  sessionId: string;
+  durationMs: number | null;
+  tokenUsage: number | null;
+  contextTags: string | null; // JSON string
+  source: OperationSource | null;
+  resultStatus: ResultStatus | null;
+  toolResultSummary: string | null; // 截斷結果摘要（max 500 chars）
+  createdAt: string;
+}
+
+// ============================================
+// Section 7：API 共享 DTO
+// ============================================
+
+export interface PaginatedResponse<T> {
+  data: T[];
+  meta: {
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+    timestamp: string;
+  };
+}
+
+export interface PaginationQuery {
+  page?: number;
+  limit?: number;
+  sortBy?: string;
+  sortOrder?: 'asc' | 'desc';
+}
+
+/** User 公開資訊（不含 OAuth 敏感欄位） */
+export interface UserDto {
+  id: string;
+  email: string;
+  name: string | null;
+  avatarUrl: string | null;
+  createdAt: string;
+}
+
+/** Agent 公開資訊（不含 token） */
+export interface AgentDto {
+  id: string;
+  name: string;
+  agentType: AgentType;
+  status: AgentStatus;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** Approval 摘要 DTO */
+export interface ApprovalSummaryDto {
+  id: string;
+  agentId: string;
+  toolName: string;
+  riskLevel: RiskLevel;
+  summary: string;
+  decision: ApprovalDecision | null;
+  reason: string | null;
+  policyAction: PolicyAction | null;
+  sessionId: string | null;
+  taskDescription: string | null;
+  reasoning: string | null;
+  createdAt: string;
+  decidedAt: string | null;
+  promptType: PromptType | null;
+  responseType: ResponseType | null;
+  selectedOption: string | null;
+  freetext: string | null;
+  customText: string | null;
+  // S4-BE-RPERM-002: 冷啟動資料補齊
+  options: PromptOption[] | null;
+  placeholder: string | null;
+  timeoutMs: number | null;
+  toolDescription: string | null;
+}
+
+// ============================================
+// Section 8：Session Types
+// ============================================
+
+export type SessionStatus = 'active' | 'idle' | 'disconnected' | 'closed';
+
+export interface SessionMessage {
+  id: string;
+  sessionId: string;
+  sender: 'user' | 'agent' | 'system';
+  content: string;
+  status?: 'pending' | 'executing' | 'awaiting_approval' | 'done' | 'error';
+  timestamp: string;
+  metadata?: {
+    tokensUsed?: number;
+    operationType?: string;
+    approvalId?: string;
+  };
+}
+
+export interface Session {
+  id: string;
+  agentId: string;
+  agentType: AgentType;
+  agentName: string;
+  status: SessionStatus;
+  createdAt: string;
+  lastActivity: string;
+  messages: SessionMessage[];
+  metadata: {
+    totalTokens: number;
+    totalApprovals: number;
+    totalRejections: number;
+    costUsd: number;
+  };
+}
+
+// ============================================
+// Section 9：Dev Mode（雞生蛋解法）
+// ============================================
+
+export type DevMode = 'isolated' | 'allowlist' | 'full' | 'yolo';
+
+/** Agent 操作模式（'normal' = 一般審核模式，'yolo' = 觀測模式自動放行） */
+export type AgentMode = 'normal' | 'yolo';
+
+// ============================================
+// Section 9b：Hub 本地設定（~/.hopping/config.json）
+// ============================================
+
+/** Hub 本地持久化設定（配對後寫入，token 讀取優先順序：env > 此檔 > 無） */
+export interface HubLocalConfig {
+  agentId: string;
+  token: string;
+  cloudUrl: string;
+  pairedAt: string; // ISO 8601
+}
+
+// ============================================
+// Section 10：Hook ↔ Hub IPC（檔案交換 + 共享 SQLite）
+// ============================================
+
+/** 審核請求：Hook 寫入 ~/.hopping/pending/{id}.json */
+export interface IpcPendingRequest {
+  id: string;
+  toolName: string;
+  toolInput: Record<string, unknown>;
+  sessionId?: string;
+  cwd?: string;
+  /** Claude Code 提供的 tool_use_id，用於追蹤同一次工具呼叫的 pre/post 事件 */
+  toolUseId?: string;
+  timestamp: string;
+}
+
+/** 審核結果：Hub 寫入 ~/.hopping/resolved/{id}.json */
+export interface IpcResolvedResponse {
+  id: string;
+  approved: boolean;
+  reason?: string;
+  timestamp: string;
+}
+
+/** 觀測記錄：post-tool-use Hook 直接寫入 Hub SQLite */
+export interface IpcOperationRecord {
+  id: string;
+  toolName: string;
+  toolParams?: string;
+  filePaths?: string;
+  riskLevel?: RiskLevel;
+  decision?: ApprovalDecision;
+  createdAt: string;
+}
+
+// ============================================
+// Section 11：WebSocket Connection（連線控制）
+// ============================================
+
+export interface ConnectedMessage {
+  type: 'connected';
+  message: string;
+  timestamp: string;
+}
+
+export interface PingMessage {
+  type: 'ping';
+}
+
+export interface PongMessage {
+  type: 'pong';
+}
+
+// ============================================
+// Section 12：Auth Types
+// ============================================
+
+export type OAuthProvider = 'github' | 'google';
+
+/** Token Exchange request (Mobile → Backend) */
+export interface TokenExchangeRequest {
+  provider: OAuthProvider;
+  code: string;
+  codeVerifier: string;
+  redirectUri: string;
+}
+
+/** Auth token response (Backend → Mobile) — includes refresh token */
+export interface AuthTokenResponse {
+  accessToken: string;
+  refreshToken: string;
+  tokenType: 'Bearer';
+  expiresIn: number;
+  user: {
+    id: string;
+    email: string;
+    name: string | null;
+    avatarUrl: string | null;
+  };
+}
+
+/** Refresh token request (Mobile → Backend) */
+export interface RefreshTokenRequest {
+  refreshToken: string;
+}
+
+/** Refresh token response (Backend → Mobile) — no user object */
+export interface RefreshTokenResponse {
+  accessToken: string;
+  refreshToken: string;
+  tokenType: 'Bearer';
+  expiresIn: number;
+}
+
+/** JWT payload stored in token */
+export interface JwtTokenPayload {
+  sub: string; // user ID
+  email: string;
+  provider: OAuthProvider;
+  iat: number; // issued at
+  exp: number; // expiry
+}
+
+// ============================================
+// Section 13：Deduplication
+// ============================================
+
+export interface DeduplicationEntry {
+  operationId: string;
+  result: 'approved' | 'rejected';
+  timestamp: number;
+}
+
+// ============================================
+// Section 14：Local Approval（S3-HUB-LOCAL-001）
+// ============================================
+
+/** 本地審核通道設定（~/.hopping/config.json localApproval section） */
+export interface LocalApprovalConfig {
+  enabled: boolean; // default: true — 本地審核通道開關
+  dialogEnabled: boolean; // default: true — 原生對話框開關（false = 只顯示通知）
+  soundEnabled: boolean; // default: true — 通知音效
+  raceMode: boolean; // default: true — Cloud 連線時也啟動本地通道（雙通道競速）
+}
+
+/** 本地審核決策來源 */
+export type LocalApprovalSource = 'local_dialog' | 'local_respond' | 'timeout';
+
+/** LocalApprovalChannel.requestApproval() 回傳結果 */
+export interface LocalApprovalResult {
+  decision: 'approved' | 'denied' | 'timeout';
+  source: LocalApprovalSource;
+}