im-agent 0.0.0-stage → 0.1.0

package/src/agents/codex/errors.ts

@@ -0,0 +1,158 @@
+// 把 app-server / codex 抛出的原始错误翻译成人能看懂、且知道下一步做什么的提示。
+//
+// 原则：聊天里给一句人话 + 一条明确动作；终端给完整修复步骤。
+// 不要把原始错误直接甩给用户 —— 那既吓人又没有信息量。
+import { config } from "../../core/config.js";
+
+export type DiagnosisKind =
+  | "auth_expired"
+  | "auth_missing"
+  | "cli_missing"
+  | "runtime_missing"
+  | "rate_limit"
+  | "billing"
+  | "turn_aborted"
+  | "protocol"
+  | "unknown";
+
+export type Diagnosis = {
+  kind: DiagnosisKind;
+  /** 发到聊天里的简短说明 */
+  chatMessage: string;
+  /** 打在终端的修复步骤 */
+  consoleHint: string;
+  /** 是否属于「配置好之前重试也没用」的问题 */
+  fatal: boolean;
+};
+
+const LOGIN_STEPS = [
+  "  1) codex login      # 用 ChatGPT 账号登录，或配 OPENAI_API_KEY",
+  "  2) codex doctor     # 确认认证与运行时都正常",
+  '  3) codex exec "回复 OK"   # 验证真的能跑',
+  "  4) 重启im-agent",
+].join("\n");
+
+export function diagnose(err: unknown): Diagnosis {
+  const raw = err instanceof Error ? err.message : String(err);
+  const text = raw.toLowerCase();
+
+  if (
+    text.includes("not logged in") ||
+    text.includes("session expired") ||
+    text.includes("token has expired") ||
+    text.includes("refresh token")
+  ) {
+    return {
+      kind: "auth_expired",
+      chatMessage:
+        "Codex 的登录状态已过期，我暂时无法工作。\n请机器主人在终端重新登录（`codex login`），完成后我就能继续。",
+      consoleHint: `Codex 登录已过期，需要重新登录：\n${LOGIN_STEPS}`,
+      fatal: true,
+    };
+  }
+
+  if (
+    text.includes("unauthorized") ||
+    text.includes("invalid api key") ||
+    text.includes("401")
+  ) {
+    return {
+      kind: "auth_missing",
+      chatMessage:
+        "Codex 的凭证无效，我暂时无法工作。\n请机器主人检查登录状态或 OPENAI_API_KEY。",
+      consoleHint: `Codex 凭证无效。若用 ChatGPT 账号，重新登录：\n${LOGIN_STEPS}\n若用 API key，检查 OPENAI_API_KEY 是否正确。`,
+      fatal: true,
+    };
+  }
+
+  // 本机没装 codex，或装在 PATH 之外（服务托管时的经典症状）
+  if (
+    text.includes("enoent") ||
+    text.includes("command not found") ||
+    text.includes("无法启动") ||
+    text.includes("spawn")
+  ) {
+    return {
+      kind: "cli_missing",
+      chatMessage: "本机还没装好 Codex，我暂时无法工作。\n请机器主人先完成安装。",
+      consoleHint:
+        `找不到可执行的 \`${config().agents.codex.path}\`。\n` +
+        "  1) npm i -g @openai/codex   # 或用你惯用的安装方式\n" +
+        "  2) command -v codex          # 确认它在 PATH 里\n" +
+        "  3) 装在非标准位置的话，在 .env 里设 BRIDGE_CODEX_PATH 指到绝对路径\n" +
+        `${LOGIN_STEPS}`,
+    fatal: true,
+    };
+  }
+
+  // codex 把执行器做成了单独下载的运行时二进制，CDN 拉不到时它就跑不了命令。
+  // 症状很隐蔽：模型照样回话，但每次要执行命令都失败。
+  if (text.includes("code-mode host") || text.includes("codex-code-mode-host")) {
+    return {
+      kind: "runtime_missing",
+      chatMessage:
+        "Codex 能说话，但执行不了命令 —— 本机缺少它的运行时组件。\n请机器主人跑一次 `codex doctor` 看看。",
+      consoleHint:
+        "Codex 的命令执行器（code-mode host）没能启动，通常是运行时二进制没下下来。\n" +
+        "  1) codex doctor    # 看 reachability 一节，多半是 CDN 拉不通\n" +
+        "  2) 确认能访问 chatgpt.com，必要时配好代理后重试\n" +
+        "  3) codex update    # 让它重新拉一次运行时",
+      fatal: false,
+    };
+  }
+
+  if (text.includes("rate limit") || text.includes("usage limit") || text.includes("429")) {
+    return {
+      kind: "rate_limit",
+      chatMessage: "Codex 的用量已达上限，请稍后再试。",
+      consoleHint: "已达用量上限。等配额恢复，或换用额度更充足的账号 / API key。",
+      fatal: false,
+    };
+  }
+
+  if (text.includes("quota") || text.includes("billing") || text.includes("credit")) {
+    return {
+      kind: "billing",
+      chatMessage: "Codex 账户余额或配额不足，请机器主人处理后再试。",
+      consoleHint: "余额 / 配额不足，去 OpenAI 控制台检查订阅与用量。",
+      fatal: false,
+    };
+  }
+
+  if (text.includes("interrupt") || text.includes("aborted") || text.includes("cancel")) {
+    return {
+      kind: "turn_aborted",
+      chatMessage:
+        "这一轮被中断了（/stop、审批超时，或 Codex 自己停了）。\n上下文没丢，把刚才的需求再说一遍就行。",
+      consoleHint:
+        "一轮执行被中途打断。常见原因：用户发了 /stop、审批超时按拒绝处理。\n偶发不用管，下一条消息会带着原 threadId 继续。",
+      fatal: false,
+    };
+  }
+
+  // app-server 标着 experimental，协议跟着 codex 版本走，没有版本协商。
+  // 方法名对不上多半就是 codex 升级过了。
+  if (text.includes("method not found") || text.includes("-32601")) {
+    return {
+      kind: "protocol",
+      chatMessage: "im-agent和本机 Codex 的协议对不上了，请机器主人升级im-agent。",
+      consoleHint:
+        "app-server 拒绝了某个方法，多半是 codex 升级后协议变了。\n" +
+        "  1) im-agent doctor   # 会比对版本\n" +
+        "  2) npm i -g im-agent@latest       # 升级 im-agent",
+      fatal: false,
+    };
+  }
+
+  return {
+    kind: "unknown",
+    // 未知错误才把原文带给用户 —— 有原文总比一句「出错了」强
+    chatMessage: `出错了：${raw}`,
+    consoleHint: raw,
+    fatal: false,
+  };
+}
+
+/** 同一类问题只在终端刷一次完整指引，避免每条消息都刷屏 */
+const announced = new Set<DiagnosisKind>();
+

package/src/agents/codex/protocol.ts

@@ -0,0 +1,284 @@
+// `codex app-server` 的 JSON-RPC 协议，只抄我们真正用到的那一小块。
+//
+// 为什么手写而不是用 `codex app-server generate-ts`：那条命令会吐出七百多个
+// ts-rs 生成的文件，其中绝大部分我们碰都不碰，而且它们互相 import，扔进仓库
+// 就是七百个必须跟着 codex 版本一起漂移的死代码。这里只声明用得上的字段，
+// 其余一律留给 `unknown` —— 协议加字段不会弄坏我们，删字段才会，而删字段
+// 本来就该炸出来。
+//
+// ⚠️ app-server 在 codex 里标着 [experimental]，`initialize` 的响应里**没有**
+// 协议版本号，也就没有版本协商这回事：协议跟着 codex 二进制走。所以下面记一个
+// 「开发时对着的版本」，doctor 会拿它和本机实际的 codex 比对，不一致时明确
+// 提醒，而不是让它在运行时以一个莫名其妙的形态崩掉。
+export const DEVELOPED_AGAINST_CODEX = "0.153.0";
+
+// ---------- 通用 JSON-RPC ----------
+
+export type RequestId = number | string;
+
+export type JsonRpcRequest = {
+  jsonrpc: "2.0";
+  id: RequestId;
+  method: string;
+  params?: unknown;
+};
+
+export type JsonRpcNotification = {
+  jsonrpc: "2.0";
+  method: string;
+  params?: unknown;
+};
+
+export type JsonRpcResponse = {
+  jsonrpc?: "2.0";
+  id: RequestId;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+};
+
+/** 服务端发来的一帧，可能是响应、通知，或它反过来向我们发起的请求。 */
+export type Incoming = JsonRpcResponse & Partial<JsonRpcRequest>;
+
+// ---------- 客户端 → 服务端 ----------
+
+export type InitializeResult = {
+  userAgent?: string;
+  codexHome?: string;
+  platformOs?: string;
+};
+
+export type ReasoningEffortOption = { reasoningEffort: string; description?: string };
+
+export type Model = {
+  id: string;
+  model: string;
+  displayName?: string;
+  description?: string;
+  hidden?: boolean;
+  isDefault?: boolean;
+  supportedReasoningEfforts?: ReasoningEffortOption[];
+  defaultReasoningEffort?: string;
+};
+
+export type ModelListResponse = { data: Model[]; nextCursor?: string | null };
+
+/** 只列出我们会传的那些；协议里还有一堆可选项。 */
+export type ThreadStartParams = {
+  cwd?: string;
+  model?: string | null;
+  approvalPolicy?: ApprovalPolicy;
+  sandbox?: SandboxMode;
+  config?: Record<string, unknown>;
+};
+
+export type Thread = {
+  id: string;
+  sessionId?: string;
+  preview?: string;
+  name?: string | null;
+  model?: string | null;
+  reasoningEffort?: string | null;
+  cwd?: string | null;
+  createdAt?: number;
+  updatedAt?: number;
+};
+
+export type ThreadResponse = { thread: Thread };
+export type ThreadListResponse = { data: Thread[]; nextCursor?: string | null };
+
+/** 只列出我们会发的：文字，以及落在本机的图片。 */
+export type UserInput = { type: "text"; text: string } | { type: "localImage"; path: string };
+
+export type TurnStartParams = {
+  threadId: string;
+  input: UserInput[];
+  cwd?: string;
+  model?: string;
+  effort?: string;
+  approvalPolicy?: ApprovalPolicy;
+  sandboxPolicy?: unknown;
+};
+
+/**
+ * 审批策略。
+ *
+ * ⚠️ 必须是 `on-request`。设成 `never` 会让审批请求根本不再发过来 ——
+ * 卡片授权那一整条路就成了死代码，Codex 在沙箱允许的范围内直接动手。
+ * 注意 codex 0.153 起 `untrusted` 已被移除，写进 config.toml 会让进程起不来。
+ */
+export type ApprovalPolicy = "never" | "on-request" | "on-failure";
+
+/**
+ * 沙箱模式 —— Codex 侧真正的第一道闸。
+ *
+ * 值得先建立的心智模型：命令**默认在沙箱里跑**，只有需要越界（写工作区外、
+ * 联网）才会请求审批。所以授权卡不会条条都弹 —— 而这并不意味着放松：挡住
+ * 越界的是操作系统级的沙箱，比一张需要人点的卡片更靠得住。
+ */
+export type SandboxMode = "read-only" | "workspace-write" | "danger-full-access";
+
+// ---------- 服务端 → 客户端：审批请求 ----------
+
+export type CommandAction =
+  | { type: "read"; command: string; name?: string; path?: string }
+  | { type: "listFiles"; command: string; path?: string | null }
+  | { type: "search"; command: string; query?: string | null; path?: string | null }
+  | { type: "unknown"; command: string };
+
+export type CommandExecutionApprovalParams = {
+  kind?: "command" | "writeStdin";
+  threadId: string;
+  turnId: string;
+  itemId: string;
+  approvalId?: string | null;
+  reason?: string | null;
+  command?: string | null;
+  cwd?: string | null;
+  commandActions?: CommandAction[] | null;
+  /**
+   * Codex 主动提出的「以后同类命令别再问」的 execpolicy 补丁。
+   * 这就是「总是允许」的原生实现 —— 粒度由 Codex 自己判断，
+   * 比我们在外面按命令首词瞎猜要准。
+   */
+  proposedExecpolicyAmendment?: string[] | null;
+};
+
+export type FileChangeApprovalParams = {
+  threadId: string;
+  turnId: string;
+  itemId: string;
+  reason?: string | null;
+  grantRoot?: string | null;
+};
+
+export type PermissionsApprovalParams = {
+  threadId: string;
+  turnId: string;
+  itemId: string;
+  cwd?: string;
+  reason?: string | null;
+  /** Codex 想额外拿到的网络 / 文件系统权限，批准时原样回给它即可。 */
+  permissions: { network?: unknown | null; fileSystem?: unknown | null };
+};
+
+/** 权限授予的范围：只这一轮，还是整条会话。 */
+export type PermissionGrantScope = "turn" | "session";
+
+/** 命令审批的决策。`acceptForSession` 对应卡片上的「本次会话内总是允许」。 */
+export type CommandApprovalDecision =
+  | "accept"
+  | "acceptForSession"
+  | "decline"
+  | "cancel"
+  | { acceptWithExecpolicyAmendment: { execpolicy_amendment: string[] } };
+
+export type FileChangeApprovalDecision = "accept" | "acceptForSession" | "decline" | "cancel";
+
+// ---------- 服务端 → 客户端：提问 ----------
+
+export type UserInputOption = { label: string; description?: string };
+
+/**
+ * 一问。
+ *
+ * `id` 是回答时的键 —— 回填 answers 表时用它，不是用问题原文。`isOther` 表示
+ * 这一问允许自由输入，`isSecret` 表示答案敏感（密码之类），后者我们一律不接：
+ * 飞书上的按钮和消息都不是填密码的地方。
+ */
+export type UserInputQuestion = {
+  id: string;
+  header?: string;
+  question: string;
+  isOther?: boolean;
+  isSecret?: boolean;
+  options?: UserInputOption[] | null;
+};
+
+export type ToolRequestUserInputParams = {
+  threadId: string;
+  turnId: string;
+  itemId: string;
+  questions: UserInputQuestion[];
+  isBlocking?: boolean;
+};
+
+/** 回答：问题 id → 选中的一个或多个答案文本。没答的问题不出现在表里。 */
+export type ToolRequestUserInputResponse = {
+  answers: Record<string, { answers: string[] }>;
+};
+
+// ---------- 服务端 → 客户端：通知 ----------
+
+export type ThreadItem =
+  | { type: "userMessage"; id: string }
+  | { type: "agentMessage"; id: string; text: string; phase?: string | null }
+  | { type: "reasoning"; id: string; summary?: string[]; content?: string[] }
+  | { type: "plan"; id: string; text: string }
+  | {
+      type: "commandExecution";
+      id: string;
+      command: string;
+      cwd?: string;
+      status: "inProgress" | "completed" | "failed";
+      exitCode?: number | null;
+      aggregatedOutput?: string | null;
+      commandActions?: CommandAction[];
+    }
+  | {
+      type: "fileChange";
+      id: string;
+      changes: { path: string; kind: "add" | "delete" | "update" }[];
+      status: "completed" | "failed";
+    }
+  | {
+      type: "mcpToolCall";
+      id: string;
+      server: string;
+      tool: string;
+      status: "inProgress" | "completed" | "failed";
+    }
+  | { type: "webSearch"; id: string; query?: string }
+  | { type: "error"; id: string; message: string }
+  | { type: string; id: string };
+
+export type ItemNotification = {
+  item: ThreadItem;
+  threadId: string;
+  turnId: string;
+};
+
+export type AgentMessageDeltaNotification = {
+  threadId: string;
+  turnId: string;
+  itemId: string;
+  delta: string;
+};
+
+export type TurnError = { message: string; additionalDetails?: string | null };
+
+export type Turn = {
+  id: string;
+  status: "inProgress" | "completed" | "failed" | "aborted" | string;
+  error?: TurnError | null;
+  durationMs?: number | null;
+};
+
+export type TurnCompletedNotification = { threadId: string; turn: Turn };
+export type TurnStartedNotification = { threadId: string; turnId?: string };
+export type ErrorNotification = {
+  error: TurnError;
+  willRetry: boolean;
+  threadId: string;
+  turnId: string;
+};
+
+export type TokenUsageNotification = {
+  threadId: string;
+  turnId: string;
+  tokenUsage?: {
+    totalTokens?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    cachedInputTokens?: number;
+  };
+};

package/src/agents/codex/refusals.ts

@@ -0,0 +1,62 @@
+// 「我不同意 / 我答不了」这句话，每一种反向请求都有自己的说法。
+//
+// 这件事值得单独一个模块，因为回错结构的代价特别不直观：Codex 那一轮会挂在
+// 等待上，而聊天这边只是安静地没反应 —— 既没有报错也没有超时，看不出哪儿坏了。
+// 实测就撞到过：MCP 的 elicitation 要的是 `{action}`，不是审批那套 `{decision}`。
+//
+// 所以这里把每种请求的「安全否定」集中列出来，任何新增的反向请求都必须先在
+// 这儿登记，否则一律走 unsupported 那条路 —— 明确报错，好过瞎猜一个形状。
+
+/** 无法应答的请求：交给 JSON-RPC 的 error 通道，而不是编一个结构出来。 */
+export class UnsupportedRequest extends Error {
+  constructor(method: string) {
+    super(`im-agent不支持 ${method}`);
+    this.name = "UnsupportedRequest";
+  }
+}
+
+/**
+ * 某种反向请求的「安全否定」。
+ *
+ * 用在两处：找不到对应会话时的兜底，以及处理器自己出错时的收尾。
+ * 认不出来的方法返回 null，调用方应当抛 UnsupportedRequest。
+ */
+export function refusalFor(method: string): unknown | null {
+  switch (method) {
+    // v2 的三种审批
+    case "item/commandExecution/requestApproval":
+    case "item/fileChange/requestApproval":
+      return { decision: "decline" };
+
+    case "item/permissions/requestApproval":
+      // 拒绝 = 一样都不给，而不是原样放行
+      return { permissions: {}, scope: "turn" };
+
+    case "item/tool/requestUserInput":
+      return { answers: {} };
+
+    // MCP 服务器想向用户要一份表单输入。我们还没做表单渲染，明确拒绝。
+    // 注意字段是 action 而不是 decision，content / _meta 必须显式给 null。
+    case "mcpServer/elicitation/request":
+      return { action: "decline", content: null, _meta: null };
+
+    // 老协议里的两种审批。新版 codex 走上面的 v2 方法，但握手后到底发哪一套
+    // 取决于对端版本，两边都接住才不会在升级时突然卡住。
+    // 它们用的是 ReviewDecision，拒绝要带一句理由。
+    case "execCommandApproval":
+    case "applyPatchApproval":
+      return { decision: { denied: { rejection: "im-agent未获授权" } } };
+
+    // 服务端让我们代为调一个工具。没实现，如实说失败。
+    case "item/tool/call":
+      return {
+        contentItems: [{ type: "text", text: "im-agent不提供客户端工具" }],
+        success: false,
+      };
+
+    // 刷新 ChatGPT 令牌、生成设备证明 —— 这两件事只有真正的 Codex 客户端做得了，
+    // 我们编不出合法的返回值，只能走 error 通道。
+    default:
+      return null;
+  }
+}