Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

29.8 KB
Raw Blame
import { BRAND_NAME } from './branding.js';

export const DEVICE_LINK_SUBSCRIBE_CHANNEL = 'device-link:subscribe';
export const DEVICE_LINK_UNSUBSCRIBE_CHANNEL = 'device-link:unsubscribe';
/** Marker passed as sessions:get arg[1] only by background list reconciliation probes. */
export const DEVICE_LINK_RECONCILIATION_PROBE_MARKER =
  'device-link:sessions-reconciliation-probe';
export const DEVICE_LINK_MEDIA_FETCH_CHANNEL = 'device-link:media:fetch';
export const DEVICE_LINK_VOICE_TRANSCRIBE_CHANNEL = 'device-link:voice:transcribe';
export const DEVICE_LINK_VOICE_CREDENTIAL_SYNC_CHANNEL = 'device-link:voice:credential-sync';
export const DEVICE_LINK_VOICE_DICTIONARY_LEARNING_CHANNEL = 'device-link:voice:dictionary-learning';
export const DEVICE_LINK_VOICE_DICTIONARY_GET_CHANNEL = 'device-link:voice:dictionary:get';
/** 桌面主动推给手机的只读词典快照;push 不受 remoteControlEnabled 控制门禁。 */
export const DEVICE_LINK_VOICE_DICTIONARY_SNAPSHOT_CHANNEL =
  'device-link:voice:dictionary:snapshot';

export type MobileVoiceCredentialSyncAsr = {
  provider: string;
  model: string;
  auth: 'api-key' | 'codex';
  mode: string;
  endpointPath?: string;
  pcmSampleRate?: number;
  protocolProfile?: string;
  resourceId?: string;
  litellmHeaderModel?: string;
};

export type MobileVoiceCredentialSyncRefiner = {
  provider: string;
  model: string;
  auth: 'api-key' | 'codex';
  transport: 'litellm-chat-completions' | 'codex-responses';
  endpointPath?: '/v1/chat/completions';
};

export type MobileVoiceCredentialSyncDictionaryEntry = {
  text: string;
  frequency?: number;
  aliases?: Array<{
    text: string;
    count?: number;
  }>;
};

export type MobileVoiceCredentialSyncSettings = {
  language: string;
  refinementEnabled: boolean;
  playInteractionSound: boolean;
  refinementInstructions?: string;
  dictionaryEntries?: MobileVoiceCredentialSyncDictionaryEntry[];
  voiceInputHistory?: string[];
};

/**
 * Legacy mobile voice credential shape.
 *
 * The current mobile runtime builds this shape from the LiteLLM key saved in the
 * mobile app settings. The old controlled-desktop key sync channel is kept out
 * of the mobile remote invoke allowlist.
 */
export type MobileVoiceCredentialSyncResult = {
  temporary: true;
  credentialVersion: 1;
  issuedAt: string;
  proxyBaseUrl: string;
  proxyApiKey: string;
  asr: MobileVoiceCredentialSyncAsr;
  asrProviderChain?: MobileVoiceCredentialSyncAsr[];
  refiner: MobileVoiceCredentialSyncRefiner;
  refinerProviderChain?: MobileVoiceCredentialSyncRefiner[];
  settings?: MobileVoiceCredentialSyncSettings;
};

/**
 * 手机拉取被控桌面词典的只读快照。
 *
 * 手机不参与 CRDT 合并 —— 它在后台不维持 WebSocket,拿不到对等同步的 push 帧,
 * 也不该持有一份会分叉的可写词典。这里只投影 refine 真正用得上的字段。
 */
export type MobileVoiceDictionarySnapshotResult =
  | {
      ok: true;
      entries: MobileVoiceCredentialSyncDictionaryEntry[];
      /**
       * 该桌面同步状态的版本向量:`{ nodeId: 该节点的最大 HLC }`。
       *
       * 手机同时拉多台电脑时用它判断哪一份**包含**了另一份。不能用响应到达时间
       * (并发请求里慢的那个反而显得"更新"),也不能只比最大 HLC —— 两台电脑各自
       * 新增了不同的词、还没来得及互相同步时,最大 HLC 大的那份并不包含另一份,
       * 拿它当完整答案会漏词。老版本被控端不带这个字段,手机退回按到达时间比较。
       */
      stateVector?: Record<string, string>;
      /**
       * 桌面生成这份投影的本地时间(unix ms)。同一台电脑、同一代版本向量里,
       * 用它而不是手机到达时间判断谁先发出 —— 晚到的旧拉取不能盖掉先发出的新推送。
       * 老版本被控端不带这个字段。
       */
      emittedAt?: number;
    }
  | {
      ok: false;
      error: string;
    };

export type MobileVoiceDictionaryLearningRequest = {
  source: 'mobile';
  rawTranscriptText?: string;
  beforeText: string;
  afterText: string;
  context?: {
    uiLanguage?: string;
    sourceLanguage?: string;
    selectionBefore?: string;
    selectionAfter?: string;
  };
};

export type MobileVoiceDictionaryLearningAction = {
  action: 'add_candidate' | 'add_entry' | 'update_entry';
  term: string;
  aliases: string[];
  type:
    | 'product_name'
    | 'project_name'
    | 'technical_term'
    | 'person_name'
    | 'team_name'
    | 'code_name'
    | 'phrase'
    | 'other';
  confidence: 'high' | 'medium' | 'low';
  reason?: string;
};

export type MobileVoiceDictionaryLearningResult =
  | {
      ok: true;
      actions: MobileVoiceDictionaryLearningAction[];
      elapsedMs: number;
      ignoreReason?: string | null;
    }
  | {
      ok: false;
      error: string;
    };

/**
 * goal 状态(目标模式)跨端契约 —— 镜像被控端 goal-host/types.ts 的 GoalStatusPayload。
 * 控制端(手机)经 `maker:goal:get-status` 拉取、经 `maker:goal:status-changed` push 增量刷新;
 * goal 状态机只在被控端 GoalController 执行,这里只是显示投影。
 */
export type MobileGoalStatus = 'active' | 'paused' | 'blocked' | 'complete' | 'budgetLimited' | 'usageLimited';

export interface MobileGoalStatusPayload {
  sessionId: string;
  status: MobileGoalStatus;
  objective: string;
  turnsUsed: number;
  tokensUsed: number;
  maxTurns: number | null;
  noProgressLimit: number | null;
  budgetTokens: number | null;
  usageResetAt: number | null;
  startedAt: number;
  lastReason: string | null;
}

/** goal 状态变化 push 的 payload(goal=null 表示已清除)。 */
export interface MobileGoalStatusUpdate {
  sessionId: string;
  goal: MobileGoalStatusPayload | null;
}

/** `maker:goal:set` / `maker:goal:update` 的 limits 入参(null = 不设该上限)。 */
export interface MobileGoalLimitsInput {
  maxTurns: number | null;
  budgetTokens: number | null;
  noProgressLimit: number | null;
}

/** One Codex subscription quota window sent from the controlled desktop. */
export interface MobileCodexRateLimitWindow {
  usedPercent: number;
  windowMinutes?: number | null;
  resetsAt?: number | null;
}

/** One Codex subscription quota bucket sent to a control-only client. */
export interface MobileCodexRateLimitSnapshot {
  limitId?: string | null;
  limitName?: string | null;
  primary?: MobileCodexRateLimitWindow | null;
  secondary?: MobileCodexRateLimitWindow | null;
  planType?: string | null;
  rateLimitReachedType?: string | null;
}

/** Display-safe identity for the exact ChatGPT account/workspace used by desktop Codex. */
export interface MobileCodexRateLimitAccount {
  email: string | null;
  accountId: string | null;
  planType: string | null;
}

/** Display-safe metadata for one banked reset credit; its opaque backend id stays on desktop. */
export interface MobileCodexRateLimitResetCredit {
  /** Optional per-credit offer; older hosts/clients keep using the account-level offer. */
  resetOffer?: MobileCodexRateLimitResetOffer | null;
  status: 'available' | 'redeeming' | 'redeemed' | 'unknown';
  resetType: 'codexRateLimits' | 'unknown';
  grantedAt: number;
  expiresAt: number | null;
  title: string | null;
  description: string | null;
}

/** Desktop-issued, account-bound reset offer used as the idempotency key for one attempt. */
export interface MobileCodexRateLimitResetOffer {
  /** Only retry the existing attempt; do not consume another credit. */
  retryOnly?: boolean;
  idempotencyKey: string;
  /** Unix epoch seconds for the selected banked credit, when details are available. */
  expiresAt: number | null;
  /** Unix epoch milliseconds after which desktop discards this retry key. */
  validUntil: number;
}

/** Full read-only Codex quota view plus an optional manually redeemable reset offer. */
export interface MobileCodexRateLimitsResult {
  /** Absent on older hosts. Settings belong to this computer and exact ChatGPT account. */
  autoUse?: CodexResetAutoUseState;
  /** Echoed account scope; custom-account clients reject unscoped legacy responses. */
  providerId?: string;
  account: MobileCodexRateLimitAccount;
  rateLimits: MobileCodexRateLimitSnapshot;
  rateLimitsByLimitId: Record<string, MobileCodexRateLimitSnapshot> | null;
  rateLimitResetCredits: {
    availableCount: number;
    credits: MobileCodexRateLimitResetCredit[] | null;
  } | null;
  resetOffer: MobileCodexRateLimitResetOffer | null;
}

export interface CodexResetAutoUseSettings {
  enabled: boolean;
  lowQuota: boolean;
  /** Inclusive days until the weekly quota resets; zero means no time condition. */
  minimumDays: number;
  expiring: boolean;
  expiryMinutes: number;
}

export interface CodexResetAutoUseState {
  /** Opaque account binding, never an auth credential. Required when saving. */
  accountKey: string;
  settings: CodexResetAutoUseSettings;
  customized: boolean;
  lastUsedAt: number | null;
}

/** Stable terminal result for one desktop-issued reset offer. */
export interface MobileCodexRateLimitResetResult {
  providerId?: string;
  outcome: 'reset' | 'nothingToReset' | 'noCredit' | 'alreadyRedeemed';
  /** Fresh snapshot when the post-consume read succeeded. */
  rateLimits: MobileCodexRateLimitsResult | null;
}

/** 下一条消息发送时才会应用的跨 Agent 切换意图。 */
export interface MobileSessionAgentSwitchIntent {
  targetAgentKind: 'claude-code' | 'codex' | 'pi';
  model: string;
  providerId: string | null;
  effort?: string;
  fastMode?: boolean | 'ultrafast';
}

/** desktop 登记 / 取消跨 Agent 意图后的稳定结果。 */
export interface MobileSessionAgentSwitchResult {
  switched: boolean;
  agentKind: 'claude-code' | 'codex' | 'pi';
  model: string;
  engineReady: boolean;
  deferred?: boolean;
}

export const MOBILE_REMOTE_INVOKE_CHANNELS = [
  'ghosts:composer-list',
  'maker:create-session',
  'maker:get-capabilities',
  'maker:provider:list',
  'local-db:sessions:get',
  // 只读任务搜索(对齐桌面侧栏 / Composer @)。老被控端 CHANNEL_NOT_ALLOWED →
  // 手机端降级为已缓存会话的本地匹配,不阻断搜索。
  'local-db:conversations:search',
  'local-db:sessions:patch-meta',
  // error-tail / interrupted 收尾入口(对齐桌面 error-tail banner / InterruptedTurnBanner):
  // 「忽略」错误尾行 → 被控端持久化 merge dismissed:true;「忽略」中断提示 → 被控端写
  // ended 时间戳。老被控端 CHANNEL_NOT_ALLOWED → 手机端吞掉降级为本视图内存隐藏。
  'local-db:messages:dismiss-error',
  'local-db:sessions:ack-interrupted',
  // 会话菜单重命名的「自动起名」:被控端读该会话素材重新生成标题(与桌面 Magic 按钮
  // 同一 handler;老被控端 CHANNEL_NOT_ALLOWED → 手机端展示失败提示,不阻塞手动改名)。
  'maker:regenerate-title',
  // 输入框推荐提示词:由被控端读取真实会话素材生成。
  'maker:predict-prompt',
  'local-db:messages:list',
  'local-db:messages:view',
  'local-db:messages:work-details',
  'local-db:messages:view-intent',
  'local-db:messages:around',
  'local-db:messages:around-client-id',
  'maker:send',
  'maker:list-active',
  'maker:set-model',
  'maker:switch-session-agent',
  'maker:get-session-agent-switch-intent',
  'maker:set-effort',
  'maker:set-permission-mode',
  'maker:set-fast-mode',
  'maker:set-thinking-enabled',
  'maker:set-extra-dirs',
  // 模型列表「非选中行」effort/fast 写穿(会话镜像 + 草稿默认双写;老被控端
  // CHANNEL_NOT_ALLOWED → 手机端吞掉降级,见 sessionModelMirror)。
  'maker:set-session-model-pref',
  'maker:apply-new-maker-draft-pref',
  // 工作端「新建会话默认启用 worktree」勾选记忆的读 / 写:
  //  - get-new-maker-defaults(只读):工作端草稿默认值镜像,手机新建页据 worktreeEnabled
  //    播种 worktree 开关(桌面控制端早已消费同通道)。老被控端 CHANNEL_NOT_ALLOWED →
  //    播种回落默认不勾选。
  //  - apply-new-maker-worktree-pref:用户在手机上显式切换开关时写穿工作端 newMakerDraft
  //    根字段。老被控端 CHANNEL_NOT_ALLOWED → 吞掉降级(勾选仅本次草稿生效)。
  'maker:get-new-maker-defaults',
  'maker:apply-new-maker-worktree-pref',
  // 工作端 canonical baseRepo scoped 的 worktree 源分支 live 镜像。GET 未命中返回 null;
  // APPLY 返回并广播 { baseRepo, sourceBranch, revision },同值写也推进 revision。
  'maker:get-new-maker-worktree-branch-pref',
  'maker:apply-new-maker-worktree-branch-pref',
  // 模型选择列表元信息:被控端视角的模型单价表(只读;拉不到 → 隐藏价格)。
  'maker:usage:model-pricing',
  'local-db:messages:estimatedSessionValue',
  // Codex app-server 官方控制面:只读额度/reset 次数 + 人工确认后的单次 reset。
  // reset 使用 desktop 预签发、账号绑定的幂等 offer,手机不能自行指定 creditId。
  'maker:usage:codex-rate-limits',
  'maker:usage:codex-rate-limit-reset',
  'maker:usage:codex-reset-auto-use',
  // 订阅账号余量快照(只读;Claude / SuperGrok)与 cc 默认路由会话的生效计费路由。
  // 老被控端 CHANNEL_NOT_ALLOWED → 任务菜单保留「暂未获取账号配额」。
  'maker:usage:claude-subscription',
  'maker:usage:xai-subscription',
  'maker:claude-session-route:get',
  // 网关 API key presence-only 探测(只回 boolean;拉不到 → unknown,折扣版不置灰)。
  'maker:api-key:present',
  'maker:list-agent-commands',
  'maker:list-agent-skills',
  'maker:scan-at-resources',
  DEVICE_LINK_MEDIA_FETCH_CHANNEL,
  DEVICE_LINK_VOICE_TRANSCRIBE_CHANNEL,
  DEVICE_LINK_VOICE_DICTIONARY_LEARNING_CHANNEL,
  DEVICE_LINK_VOICE_DICTIONARY_GET_CHANNEL,
  'maker:get-pending-interactions',
  'maker:resolve-interaction',
  'maker:get-context-usage',
  'maker:goal:set',
  'maker:goal:clear',
  'maker:goal:get-status',
  'maker:goal:pause',
  'maker:goal:resume',
  'maker:goal:update',
  'maker:fork',
  'maker:side-chat:v1',
  'maker:side-chat:list:v1',
  'maker:fork-strip-encrypted',
  'maker:get-session-tree',
  'maker:navigate-session-tree',
  'maker:rewind:preview',
  'maker:rewind:commit',
  'maker:message:delete',
  'maker:close-session',
  // —— Orca 协同(Lead / Worker 团队真身在被控端,手机只做编排入口)——
  // 均已在被控端 REMOTE_INVOKE_ALLOWLIST 的 Orca 段;worker-changed 推送经
  // `session:<leadId>` topic 转发。老被控端 CHANNEL_NOT_ALLOWED → 协同入口 fail-closed
  // 提示设备版本过旧,不放行到 enable-orca 才撞错。
  'maker:plugins:get-state',
  'maker:session:enable-orca',
  'maker:session:disable-orca',
  'maker:worker:create',
  // 只读 Lead 所在电脑视角下的运行设备;旧端拒绝时保留本机 Worker 创建。
  'maker:orca:execution-devices',
  'maker:worker:switch-focus',
  'maker:worker:acknowledge-done',
  'maker:worker:archive',
  'maker:collaboration-settings:get',
  'local-db:orca-workflows:list-workers-by-lead',
  'local-db:orca-workflows:get-by-worker-session',
  'maker:schedule:list',
  'maker:schedule:get',
  'maker:schedule:list-templates',
  'maker:schedule:create-from-template',
  'maker:schedule:create',
  'maker:schedule:update',
  'maker:schedule:list-runs',
  'maker:schedule:run-now',
  'maker:schedule:pause',
  'maker:schedule:resume',
  'maker:schedule:delete',
  'maker:schedule:get-inflight-count',
  'maker:schedule:mark-run-read',
  'maker:schedule:mark-schedule-runs-read',
  'maker:schedule:delete-run',
  // 会话未读已读回执:手机端真实展示会话内容后,清掉被控端的会话未读
  // (灵动岛 / Dock 角标 / 侧栏红绿点)。老被控端 CHANNEL_NOT_ALLOWED → 吞掉降级。
  'notification:clear-session-attention',
  'maker:project-automation:remove-schedule',
  'maker:input:get-projection',
  'maker:input:enqueue',
  'maker:input:compact',
  // 手动压缩(pi 原生 compact,capability-aware):移动端控制远程 pi 会话同样隧道到
  // 被控端执行;长 LLM 摘要请求的超时覆盖见 INVOKE_TIMEOUT_OVERRIDES_MS。
  'maker:compact-session',
  'maker:input:steer',
  'maker:input:stop',
  'maker:input:resume',
  'maker:input:retry-last-error',
  'maker:input:clear-error',
  'maker:input:cancel-usage-limit-wait',
  'maker:input:remove',
  'maker:input:update-text',
  'maker:input:update-content',
  'maker:input:move',
  'maker:input:set-expanded',
  'maker:input:set-interaction-lock',
  'maker:input:set-edit-lock',
  'maker:input:clear-session',
  'fs:list-dir',
  'fs:stat-path',
  'fs:mkdir-p',
  // —— Worktree(新建会话前在工作端预建隔离 worktree;git/fs 全在被控端执行)——
  //  - detect-cwd:资格探测(git 已装 / 是 git 仓库 / 未在 worktree 内)+ repoRoot/currentBranch;
  //  - list-branches:工作端返回本地分支列表 + 当前分支,供控制端选择 sourceBranch;
  //  - suggest-name:工作端按仓库上下文生成 worktree 名;
  //  - create:两步建会话第一步——同预生成 sessionId 先建 worktree 拿路径,再以该路径调
  //    maker:create-session(与桌面控制端 NewMakerDraftRoute 的远程流程同构);
  //  - discard-precreated:第二步确定失败且用户放弃时,按 sessionId + 精确 path 补偿回收。
  // 四者均已在被控端 REMOTE_INVOKE_ALLOWLIST(create / discard 的 60s 超时见
  // INVOKE_TIMEOUT_OVERRIDES_MS,移动端 invoke 必须带同一映射)。
  // 老被控端无这些 channel → CHANNEL_NOT_ALLOWED → 手机端按「worktree 不可用」降级。
  'worktree:detect-cwd',
  'worktree:list-branches',
  'worktree:suggest-name',
  'worktree:create',
  'worktree:discard-precreated',
  'worktree:cancel-precreated',
  'text-file:read-preview',
  // 完整文件浏览(网格/预览/缩略图/大文件导出)走桌面同款聚合通道,
  // op 分发与响应形状见 apps/desktop/src/main/file-browser/device-op.ts。
  'file-browser:remote-op',
] as const;

export type MobileRemoteInvokeChannel = (typeof MOBILE_REMOTE_INVOKE_CHANNELS)[number];
export type DeviceLinkRelayStatus = 'online' | 'connecting' | 'stopped';

const PERMANENT_REMOTE_ERROR_MARKERS = [
  'REMOTE_DISABLED',
  'CHANNEL_NOT_ALLOWED',
  // 控制端「目标设备无响应」熔断器的快速失败(见 apps/mobile 的
  // unresponsiveDevicesStore):被控端连续 INVOKE_TIMEOUT 后熔断 open,新请求
  // 本地直拒。必须归为 permanent——否则 withTransientRemoteRetry 会把熔断
  // 快速失败再原地重试 6 次,熔断等于白做。
  'DEVICE_UNRESPONSIVE',
] as const;

const TRANSIENT_REMOTE_ERROR_MARKERS = [
  'DbClient not ready',
  'NOT_CONNECTED',
  'LINK_NOT_OPEN',
  'BACKPRESSURE',
  'DEVICE_LINK_BUSY',
  'DEVICE_OFFLINE',
  'DEVICE_LINK_TIMEOUT',
  'INVOKE_TIMEOUT',
  // HTTP 层(apps/mobile src/api/client.ts 的 ApiError)的弱网错误码:
  // 超时与离线同属典型瞬时故障,必须能被 withTransientRemoteRetry 识别重试。
  'REQUEST_TIMEOUT',
  'NETWORK_UNAVAILABLE',
  // RN 原生 fetch 离线原文(绕过 api client 的直连路径,如 OSS 直传 PUT):
  // 同样是瞬时故障,且中文兜底文案好过把英文原文透传给用户。
  'Network request failed',
] as const;

const DEFAULT_MAX_ATTEMPTS = 6;

export interface RemoteRetryOptions {
  maxAttempts?: number;
  sleep?: (ms: number) => Promise<void>;
}

export function isMobileRemoteInvokeChannel(channel: string): channel is MobileRemoteInvokeChannel {
  return (MOBILE_REMOTE_INVOKE_CHANNELS as readonly string[]).includes(channel);
}

export function relayStatusLabel(status: DeviceLinkRelayStatus): string {
  switch (status) {
    case 'online':
      return 'Relay 已连接';
    case 'connecting':
      return '正在连接 Relay';
    case 'stopped':
      return 'Relay 未连接';
  }
}

export function relayStatusHint(status: DeviceLinkRelayStatus, lastSyncedAt: number | null): string {
  if (status === 'online') {
    return lastSyncedAt ? `上次同步 ${formatClock(lastSyncedAt)}` : '可以同步远程任务。';
  }
  if (status === 'connecting') return '网络恢复后会自动重新订阅远程任务。';
  return '回到前台或重新登录后会恢复连接。';
}

/**
 * 镜像 @cindy/device-link 的 DeviceLinkConnectionIssueKind。
 * maker-shared 保持零运行时依赖(与 DeviceLinkRelayStatus 同款处理),两边字面量
 * 必须一致;deviceLinkContract.test.ts 校验两处字面量,避免消费端迁移后静默漂移。
 */
export type DeviceLinkConnectionIssueKind =
  | 'auth-failed'
  | 'device-removed'
  | 'replaced'
  | 'too-many-connections'
  | 'version-mismatch'
  | 'unstable';

/** 连接问题标题(手机端直出文案;桌面端走 i18n,不用这组)。 */
export function connectionIssueTitle(kind: DeviceLinkConnectionIssueKind): string {
  switch (kind) {
    case 'auth-failed':
      return '登录已失效';
    case 'device-removed':
      return '设备已移除';
    case 'replaced':
      return '连接被顶替';
    case 'too-many-connections':
      return '连接数已达上限';
    case 'version-mismatch':
      return '版本不匹配';
    case 'unstable':
      return '连接反复断开';
  }
}

/** 连接问题说明与建议动作(手机端直出文案)。 */
export function connectionIssueHint(kind: DeviceLinkConnectionIssueKind): string {
  switch (kind) {
    case 'auth-failed':
      return '登录状态已过期,请退出后重新登录。';
    case 'device-removed':
      return '请退出后重新登录,以重新加入设备列表。';
    case 'replaced':
      return '本设备的连接被另一处相同设备顶替,正在重新连接。';
    case 'too-many-connections':
      return '当前账号同时在线的设备过多,请断开其它设备后重试。';
    case 'version-mismatch':
      return '当前 App 版本与服务端协议不一致,请升级到最新版本。';
    case 'unstable':
      return '本机连接反复断开又重连,远程操作可能一直超时。请检查网络;若持续如此,重启 App 后重试。';
  }
}

/**
 * agent 鉴权失败 message 的固定模板。maker-core 的 claude-code / codex 在
 * startSession / 首次 send 的鉴权门禁抛 AgentNotAuthenticatedError 时统一用
 * `<agentKind> not authenticated: <reason>` 这个格式;reason(no_key 等)目前只
 * 存在于 message 字符串里,不随事件结构化下发,relay 又是哑中继原样透传——手机端
 * 要给出可读提示只能按模板识别。formatRemoteError / throwIpcError 会给部分链路的
 * message 加 `[CODE] ` 头,识别时一并容忍。
 */
const AGENT_NOT_AUTHENTICATED_RE = /^(?:\[[A-Z_]+\] )?(claude-code|codex|pi) not authenticated: ?(.*)$/;

/**
 * agent 未鉴权错误 → 手机端直出文案(桌面端走 i18n,不用这组)。
 *
 * 密钥 / OAuth 都存在被控电脑的 Cindy 里(safeStorage),手机端改不了,文案统一
 * 引导用户回电脑端「设置 → 模型供应商」处理。识别不了的输入返回 null,由调用方
 * 展示原文,不误伤其它错误。
 */
export function describeAgentAuthError(error: string | null | undefined): string | null {
  if (!error) return null;
  const matched = AGENT_NOT_AUTHENTICATED_RE.exec(error.trim());
  if (!matched) return null;
  const agentLabel = matched[1] === 'claude-code' ? 'Claude' : matched[1] === 'pi' ? 'Pi' : 'Codex';
  const goSettings = `请在电脑端 ${BRAND_NAME} 的「设置 → 模型供应商」`;
  switch (matched[2]) {
    case 'no_key':
      return `${agentLabel} 无法使用:电脑端还没有配置可用的 API Key。${goSettings}完成配置后再试。`;
    case 'no_oauth':
      return `${agentLabel} 无法使用:电脑端尚未完成账号授权。${goSettings}重新连接账号后再试。`;
    case 'no_credentials':
      return `${agentLabel} 无法使用:电脑端尚未登录 ${agentLabel}。${goSettings}完成登录后再试。`;
    case 'no_encryption':
      return `${agentLabel} 无法使用:电脑端系统安全存储不可用,读取不到已保存的密钥。请在电脑端检查系统钥匙串(macOS)或系统账户加密(Windows)后重启 ${BRAND_NAME}。`;
    case 'proxy_not_ready':
      return `${agentLabel} 暂时无法使用:电脑端组件尚未就绪。请稍候重试;若持续出现,请重启电脑端 ${BRAND_NAME}。`;
    default:
      // 动态 reason(如 OAuth 被服务端作废的具体原因):不逐一枚举,统一按登录失效引导,
      // 原始 reason 附在句尾便于反馈排查。
      return `${agentLabel} 无法使用:电脑端登录凭证不可用。${goSettings}重新登录后再试。(${matched[2] || 'unknown'})`;
  }
}

export function describeRemoteError(error: string | null): string | null {
  if (!error) return null;
  const agentAuth = describeAgentAuthError(error);
  if (agentAuth) return agentAuth;
  if (error.includes('REMOTE_DISABLED')) return '被控电脑已关闭允许远程控制。';
  if (error.includes('CHANNEL_NOT_ALLOWED')) return '当前电脑端版本不支持这个远程能力。';
  if (error.includes('ACCESS_REVOKED')) return '这台电脑已撤销手机访问权限。';
  if (error.includes('DEVICE_UNRESPONSIVE')) return '电脑端未响应,正在自动重试,请稍后再试。';
  if (error.includes('VERSION_MISMATCH')) return '与服务端协议版本不一致,请升级 App 后重试。';
  if (error.includes('PAYLOAD_TOO_LARGE')) return '这次传输的内容过大,请拆分后重试。';
  if (error.includes('MEDIA_FETCH_FAILED')) return '获取电脑端文件失败,可以稍后重试。';
  if (error.includes('VOICE_TRANSCRIBE_FAILED')) return '语音转写失败,可以重试或改用键盘输入。';
  if (error.includes('LINK_NOT_OPEN')) return '与被控电脑的控制链路已断开,正在重新建立。';
  if (error.includes('PRECONDITION_FAILED')) {
    if (error.includes('ACCOUNT_CHANGED')) return 'Codex 账号或工作区已变化,请刷新额度后重新确认。';
    if (error.includes('OFFER_EXPIRED')) return 'Codex 重置凭证已失效,请刷新额度后重新确认。';
    return '操作条件已变化,请刷新后重新确认。';
  }
  if (error.includes('BACKPRESSURE') || error.includes('DEVICE_LINK_BUSY')) {
    return '远端繁忙,请稍后重试。';
  }
  if (TRANSIENT_REMOTE_ERROR_MARKERS.some((marker) => error.includes(marker))) {
    return '网络或被控端暂时不可用,可以稍后重新同步。';
  }
  // BAD_REQUEST / INTERNAL / 未识别错误:给可理解的兜底句,把原始信息放在后面便于反馈排查。
  if (error.includes('BAD_REQUEST') || error.includes('INTERNAL')) {
    return `远程调用失败,可以稍后重试。(${error})`;
  }
  return error;
}

export function formatRemoteError(error: unknown): string {
  const code = readStringField(error, 'code');
  const message = error instanceof Error ? error.message : String(error);
  if (!code || message.includes(code)) return message;
  return `[${code}] ${message}`;
}

/**
 * unknown 错误 → 直接给用户看的文案:先 formatRemoteError 展平成 `[CODE] message`,
 * 再过 describeRemoteError 的人话映射;识别不了的原文透出,便于用户反馈时排查。
 * Alert / toast 等直面用户的出口用这个,不要裸用 formatRemoteError——那会把
 * `[NOT_CONNECTED] not online within 1500ms` 这类原始错误直接怼给用户。
 */
export function humanizeRemoteError(error: unknown): string {
  const text = formatRemoteError(error);
  return describeRemoteError(text) ?? text;
}

export function isAccessRevokedRemoteError(error: unknown): boolean {
  const code = readStringField(error, 'code');
  if (code === 'ACCESS_REVOKED') return true;
  const message = error instanceof Error ? error.message : typeof error === 'string' ? error : '';
  return message.includes('ACCESS_REVOKED') || message.includes('DEVICE_LINK_ACCESS_REVOKED');
}

/** 控制端熔断器快速失败(目标设备无响应)的识别;code 与 message 两种形态都认。 */
export function isDeviceUnresponsiveRemoteError(error: unknown): boolean {
  const code = readStringField(error, 'code');
  if (code === 'DEVICE_UNRESPONSIVE') return true;
  const message = error instanceof Error ? error.message : typeof error === 'string' ? error : '';
  return message.includes('DEVICE_UNRESPONSIVE');
}

export function isPreconditionFailedRemoteError(error: unknown): boolean {
  const code = readStringField(error, 'code');
  if (code === 'PRECONDITION_FAILED') return true;
  const message = error instanceof Error ? error.message : typeof error === 'string' ? error : '';
  return message.includes('PRECONDITION_FAILED');
}

export function isTransientRemoteError(error: unknown): boolean {
  const text = formatRemoteError(error);
  if (PERMANENT_REMOTE_ERROR_MARKERS.some((marker) => text.includes(marker))) return false;
  return TRANSIENT_REMOTE_ERROR_MARKERS.some((marker) => text.includes(marker));
}

export async function withTransientRemoteRetry<T>(
  operation: () => Promise<T>,
  opts: RemoteRetryOptions = {},
): Promise<T> {
  const maxAttempts = opts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
  const sleep = opts.sleep ?? realSleep;
  let lastError: unknown;

  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      return await operation();
    } catch (err) {
      lastError = err;
      const canRetry = attempt < maxAttempts - 1 && isTransientRemoteError(err);
      if (!canRetry) throw err;
      await sleep(backoffMs(attempt));
    }
  }

  throw lastError;
}

function backoffMs(attempt: number): number {
  return Math.min(250 * 2 ** attempt, 3000);
}

function realSleep(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

function formatClock(timestamp: number): string {
  const date = new Date(timestamp);
  return [
    date.getHours().toString().padStart(2, '0'),
    date.getMinutes().toString().padStart(2, '0'),
    date.getSeconds().toString().padStart(2, '0'),
  ].join(':');
}

function readStringField(value: unknown, key: string): string | null {
  if (!value || typeof value !== 'object') return null;
  const raw = (value as Record<string, unknown>)[key];
  return typeof raw === 'string' ? raw : null;
}