@fieldwangai/agentflow 0.1.166 → 0.1.167

package/bin/lib/agent-runners.mjs

@@ -17,6 +17,7 @@ import {
   isCursorQuotaError,
   markCursorApiKeyLaneBlocked,
   recordCursorApiKeyFallbackModel,
+  recordCursorApiKeyUsage,
 } from "./cursor-api-key-pool.mjs";
 import { discoverCursorModels } from "./cursor-model-catalog.mjs";
 import { outputNodeBasename } from "../pipeline/get-exec-id.mjs";
@@ -123,7 +124,7 @@ function shouldSkipCodexGitCheck(workspace) {
   return !hasGitMetadataAncestor(workspace);
 }
 
-function buildCodexExecArgs({ workspace, addDirs = [], model, outputLastMessagePath, promptText, configArgs = [] }) {
+function buildCodexExecArgs({ workspace, addDirs = [], model, outputLastMessagePath, promptText, configArgs = [], sandboxMode = "", allowDanger = true }) {
   const args = [];
   for (const cfg of Array.isArray(configArgs) ? configArgs : []) {
     const value = String(cfg || "").trim();
@@ -137,10 +138,10 @@ function buildCodexExecArgs({ workspace, addDirs = [], model, outputLastMessageP
     const abs = path.resolve(dir);
     if (abs && abs !== workspace) args.push("--add-dir", abs);
   }
-  if (envFlag("AGENTFLOW_CODEX_DANGER", false)) {
+  if (allowDanger && envFlag("AGENTFLOW_CODEX_DANGER", false)) {
     args.push("--dangerously-bypass-approvals-and-sandbox");
   } else {
-    args.push("--sandbox", String(process.env.AGENTFLOW_CODEX_SANDBOX || "workspace-write").trim() || "workspace-write");
+    args.push("--sandbox", String(sandboxMode || process.env.AGENTFLOW_CODEX_SANDBOX || "workspace-write").trim() || "workspace-write");
   }
   if (shouldSkipCodexGitCheck(workspace)) args.push("--skip-git-repo-check");
   if (envFlag("AGENTFLOW_CODEX_EPHEMERAL", false)) args.push("--ephemeral");
@@ -432,11 +433,16 @@ export function runCursorAgentWithPrompt(cliWorkspace, promptText, options = {})
       || cursorSelection?.modelSelection
       || { lane: "auto", modelId: "auto", modelName: "Auto" };
   const model = hasExplicitModel ? requestedModel : cursorModelSelection.modelId;
+  if (cursorSelection) recordCursorApiKeyUsage(cursorSelection, cursorModelSelection);
   // Web UI Composer 需要能无交互执行本机 curl 等命令来刷新画布。
-  const args = ["--print", "--output-format", "stream-json", "--trust", "--sandbox", "disabled", "--workspace", ws];
-  const approveMcps = process.env.AGENTFLOW_CURSOR_APPROVE_MCPS !== "0" && process.env.AGENTFLOW_CURSOR_APPROVE_MCPS !== "false";
+  const args = ["--print", "--output-format", "stream-json"];
+  if (options.mode) args.push("--mode", String(options.mode));
+  args.push("--trust");
+  if (options.sandboxDisabled !== false) args.push("--sandbox", "disabled");
+  args.push("--workspace", ws);
+  const approveMcps = options.approveMcps ?? (process.env.AGENTFLOW_CURSOR_APPROVE_MCPS !== "0" && process.env.AGENTFLOW_CURSOR_APPROVE_MCPS !== "false");
   if (approveMcps) args.push("--approve-mcps");
-  args.push("--force");
+  if (options.force !== false) args.push("--force");
   if (shouldPassCursorModelArg(model)) args.push("--model", model);
   args.push(promptText);
 
@@ -551,14 +557,18 @@ export function runCursorAgentWithPrompt(cliWorkspace, promptText, options = {})
           if (options.onToolCall) options.onToolCall("thinking", "");
         } else if (event.type === "result") {
           lastResult = event;
-          const resultNl = extractCursorResultNl(event);
+          const resultNl = options.includeJsonResult && typeof event.result === "string"
+            ? normalizeStreamTextChunk(event.result)
+            : extractCursorResultNl(event);
           if (resultNl) emit({ type: "natural", kind: "result", text: resultNl });
           if (event.subtype === "success" && !event.is_error) {
             hadError = false;
             emit({ type: "status", line: t("runner.completed") });
           } else {
             hadError = true;
-            const errNl = extractCursorResultNl(event);
+            const errNl = options.includeJsonResult && typeof event.result === "string"
+              ? normalizeStreamTextChunk(event.result)
+              : extractCursorResultNl(event);
             if (errNl) emit({ type: "natural", kind: "error", text: errNl });
             emit({
               type: "status",
@@ -619,12 +629,17 @@ export function runCursorAgentWithPrompt(cliWorkspace, promptText, options = {})
         if (hadToolActivity) return false;
         if (!isCursorQuotaError(errorText)) return false;
         const errorCategory = classifyCursorApiKeyLimitError(errorText);
-        const cooldownMinutes = cursorApiKeyCooldownMinutes(cursorBaseEnv);
+        const cooldownMinutes = cursorApiKeyCooldownMinutes(cursorBaseEnv, errorText);
         markCursorApiKeyLaneBlocked(
           cursorSelection,
           cursorModelSelection.lane,
           cooldownMinutes,
           errorText,
+          Date.now(),
+          {
+            modelId: cursorModelSelection.modelId,
+            modelName: cursorModelSelection.modelName,
+          },
         );
         const canTryComposer = !hasExplicitModel
           && cursorModelSelection.lane === "auto"
@@ -840,6 +855,7 @@ export function runClaudeCodeAgentWithPrompt(cliWorkspace, promptText, options =
   const model = options.model && String(options.model).trim();
   const claudeCmd = process.env.CLAUDE_CODE_CMD || "claude";
   const bypassPermissions =
+    options.allowDanger !== false &&
     process.env.AGENTFLOW_CLAUDE_CODE_BYPASS_PERMISSIONS !== "0" &&
     process.env.AGENTFLOW_CLAUDE_CODE_BYPASS_PERMISSIONS !== "false";
   const args = ["-p", "--output-format", "stream-json", "--verbose", "--add-dir", ws];
@@ -1033,6 +1049,8 @@ export function runCodexAgentWithPrompt(cliWorkspace, promptText, options = {})
     outputLastMessagePath,
     promptText,
     configArgs: options.codexConfigArgs,
+    sandboxMode: options.sandboxMode,
+    allowDanger: options.allowDanger !== false,
   });
 
   const useStderrInherit =

package/bin/lib/ai-exploration.mjs

@@ -0,0 +1,293 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+const EXPLORATION_DIR = path.join(".workspace", "agentflow", "explorations");
+const SESSION_ID_RE = /^exp_[a-z0-9_-]{8,80}$/i;
+const EVENT_TYPES = new Set(["run", "turn", "decision", "agent", "tool", "command", "file", "artifact", "status"]);
+const EVENT_STATUSES = new Set(["planned", "running", "success", "error", "blocked", "skipped"]);
+const EVENT_PHASES = new Set(["planned", "simulated", "observed", "materialized"]);
+const SIDE_EFFECTS = new Set(["none", "read", "write", "external"]);
+
+function explorationRoot(workspaceRoot) {
+  return path.join(path.resolve(workspaceRoot), EXPLORATION_DIR);
+}
+
+function sessionDir(workspaceRoot, sessionId) {
+  const id = normalizeSessionId(sessionId);
+  return path.join(explorationRoot(workspaceRoot), id);
+}
+
+function sessionMetadataPath(workspaceRoot, sessionId) {
+  return path.join(sessionDir(workspaceRoot, sessionId), "session.json");
+}
+
+function sessionEventsPath(workspaceRoot, sessionId) {
+  return path.join(sessionDir(workspaceRoot, sessionId), "trace.jsonl");
+}
+
+function normalizeSessionId(value) {
+  const id = String(value || "").trim();
+  if (!SESSION_ID_RE.test(id)) throw new Error("Invalid exploration session id");
+  return id;
+}
+
+function clip(value, max = 2000) {
+  return redactSecrets(String(value ?? "")).trim().slice(0, max);
+}
+
+function redactSecrets(value) {
+  return String(value || "")
+    .replace(/\b(?:sk|key|token|secret)[-_][A-Za-z0-9_.-]{8,}\b/gi, "[redacted]")
+    .replace(/(authorization\s*[:=]\s*bearer\s+)[^\s,;]+/gi, "$1[redacted]")
+    .replace(/((?:api[_-]?key|access[_-]?token|password|secret)\s*[:=]\s*)[^\s,;]+/gi, "$1[redacted]");
+}
+
+function writeJsonAtomic(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`;
+  fs.writeFileSync(tempPath, JSON.stringify(value, null, 2) + "\n", { encoding: "utf-8", mode: 0o600 });
+  fs.renameSync(tempPath, filePath);
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+}
+
+function sessionSummary(raw = {}) {
+  return {
+    version: 1,
+    id: normalizeSessionId(raw.id),
+    title: clip(raw.title || "AI 探索运行", 160),
+    goal: clip(raw.goal || "", 4000),
+    summary: clip(raw.summary || "", 2000),
+    mode: EVENT_PHASES.has(String(raw.mode || "")) ? String(raw.mode) : "planned",
+    status: ["draft", "planning", "ready", "running", "completed", "failed"].includes(String(raw.status || ""))
+      ? String(raw.status)
+      : "draft",
+    source: {
+      provider: clip(raw.source?.provider || "agentflow", 80),
+      agent: clip(raw.source?.agent || "workspace", 120),
+    },
+    eventCount: Math.max(0, Number(raw.eventCount || 0) || 0),
+    createdAt: String(raw.createdAt || new Date().toISOString()),
+    updatedAt: String(raw.updatedAt || raw.createdAt || new Date().toISOString()),
+    ...(raw.materializedAt ? { materializedAt: String(raw.materializedAt) } : {}),
+  };
+}
+
+export function createAiExplorationSession(workspaceRoot, input = {}) {
+  const now = new Date().toISOString();
+  const id = `exp_${crypto.randomUUID().replace(/-/g, "").slice(0, 20)}`;
+  const session = sessionSummary({
+    id,
+    title: input.title,
+    goal: input.goal,
+    mode: input.mode,
+    status: input.status || "draft",
+    source: input.source,
+    createdAt: now,
+    updatedAt: now,
+  });
+  const dir = sessionDir(workspaceRoot, id);
+  fs.mkdirSync(path.join(dir, "artifacts"), { recursive: true, mode: 0o700 });
+  writeJsonAtomic(sessionMetadataPath(workspaceRoot, id), session);
+  fs.writeFileSync(sessionEventsPath(workspaceRoot, id), "", { encoding: "utf-8", mode: 0o600 });
+  return session;
+}
+
+export function listAiExplorationSessions(workspaceRoot, limit = 50) {
+  const root = explorationRoot(workspaceRoot);
+  if (!fs.existsSync(root)) return [];
+  const sessions = [];
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory() || !SESSION_ID_RE.test(entry.name)) continue;
+    try {
+      sessions.push(sessionSummary(readJson(sessionMetadataPath(workspaceRoot, entry.name))));
+    } catch {
+      // A corrupt exploration is omitted instead of breaking the Workspace.
+    }
+  }
+  return sessions
+    .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt) || b.id.localeCompare(a.id))
+    .slice(0, Math.max(1, Math.min(200, Number(limit) || 50)));
+}
+
+export function readAiExplorationSession(workspaceRoot, sessionId) {
+  const session = sessionSummary(readJson(sessionMetadataPath(workspaceRoot, sessionId)));
+  const events = [];
+  const eventPath = sessionEventsPath(workspaceRoot, session.id);
+  if (fs.existsSync(eventPath)) {
+    for (const line of fs.readFileSync(eventPath, "utf-8").split("\n")) {
+      if (!line.trim()) continue;
+      try { events.push(JSON.parse(line)); } catch { /* retain readable events */ }
+    }
+  }
+  return { ...session, events };
+}
+
+export function updateAiExplorationSession(workspaceRoot, sessionId, patch = {}) {
+  const current = readAiExplorationSession(workspaceRoot, sessionId);
+  const next = sessionSummary({
+    ...current,
+    ...patch,
+    source: patch.source ? { ...current.source, ...patch.source } : current.source,
+    updatedAt: new Date().toISOString(),
+  });
+  writeJsonAtomic(sessionMetadataPath(workspaceRoot, next.id), next);
+  return next;
+}
+
+function normalizeArtifacts(raw) {
+  return (Array.isArray(raw) ? raw : []).slice(0, 20).map((artifact) => ({
+    kind: clip(artifact?.kind || "file", 40),
+    path: clip(artifact?.path || "", 500),
+    label: clip(artifact?.label || artifact?.path || "artifact", 160),
+    ...(artifact?.sha256 ? { sha256: clip(artifact.sha256, 80) } : {}),
+  })).filter((artifact) => artifact.path || artifact.label);
+}
+
+export function normalizeAiTraceEvent(raw = {}, defaults = {}) {
+  const now = new Date().toISOString();
+  const phase = EVENT_PHASES.has(String(raw.phase || defaults.phase || "")) ? String(raw.phase || defaults.phase) : "observed";
+  const type = EVENT_TYPES.has(String(raw.type || "")) ? String(raw.type) : "status";
+  const status = EVENT_STATUSES.has(String(raw.status || "")) ? String(raw.status) : (phase === "planned" ? "planned" : "running");
+  const sideEffect = SIDE_EFFECTS.has(String(raw.sideEffect || "")) ? String(raw.sideEffect) : "none";
+  return {
+    id: clip(raw.id || `evt_${crypto.randomUUID().replace(/-/g, "").slice(0, 18)}`, 100),
+    traceId: clip(raw.traceId || defaults.traceId || "", 100),
+    spanId: clip(raw.spanId || raw.id || `span_${crypto.randomUUID().replace(/-/g, "").slice(0, 18)}`, 100),
+    parentSpanId: clip(raw.parentSpanId || "", 100),
+    sequence: Math.max(1, Number(raw.sequence || defaults.sequence || 1) || 1),
+    phase,
+    type,
+    name: clip(raw.name || type, 160),
+    summary: clip(raw.summary || raw.description || "", 2000),
+    status,
+    sideEffect,
+    requiresApproval: raw.requiresApproval === true || ["write", "external"].includes(sideEffect),
+    startedAt: String(raw.startedAt || now),
+    ...(raw.endedAt ? { endedAt: String(raw.endedAt) } : {}),
+    ...(raw.inputPreview ? { inputPreview: clip(raw.inputPreview, 2000) } : {}),
+    ...(raw.outputPreview ? { outputPreview: clip(raw.outputPreview, 2000) } : {}),
+    artifacts: normalizeArtifacts(raw.artifacts),
+  };
+}
+
+export function appendAiTraceEvents(workspaceRoot, sessionId, rawEvents = [], defaults = {}) {
+  const session = readAiExplorationSession(workspaceRoot, sessionId);
+  const incoming = Array.isArray(rawEvents) ? rawEvents : [rawEvents];
+  if (!incoming.length) return { session, events: [] };
+  if (session.eventCount + incoming.length > 5000) throw new Error("Exploration trace exceeds 5000 events");
+  const events = incoming.map((event, index) => normalizeAiTraceEvent(event, {
+    ...defaults,
+    traceId: session.id,
+    sequence: session.eventCount + index + 1,
+  }));
+  fs.appendFileSync(sessionEventsPath(workspaceRoot, session.id), events.map((event) => JSON.stringify(event)).join("\n") + "\n", "utf-8");
+  const next = updateAiExplorationSession(workspaceRoot, session.id, {
+    eventCount: session.eventCount + events.length,
+    mode: defaults.phase || session.mode,
+  });
+  return { session: next, events };
+}
+
+export function parseAiPlanResult(text, sessionId) {
+  const raw = String(text || "").trim();
+  const fenced = raw.match(/```(?:json)?\s*([\s\S]*?)```/i)?.[1]?.trim();
+  const candidates = [raw, fenced].filter(Boolean);
+  let parsed;
+  for (const candidate of candidates) {
+    try {
+      parsed = JSON.parse(candidate);
+      break;
+    } catch {
+      const start = candidate.indexOf("{");
+      const end = candidate.lastIndexOf("}");
+      if (start >= 0 && end > start) {
+        try { parsed = JSON.parse(candidate.slice(start, end + 1)); break; } catch { /* next */ }
+      }
+    }
+  }
+  if (!parsed || typeof parsed !== "object") throw new Error("Plan agent did not return valid JSON");
+  const spans = Array.isArray(parsed.spans) ? parsed.spans : Array.isArray(parsed.steps) ? parsed.steps : [];
+  if (!spans.length) throw new Error("Plan agent returned no executable spans");
+  return {
+    title: clip(parsed.title || "AI 执行计划", 160),
+    summary: clip(parsed.summary || "", 2000),
+    events: spans.slice(0, 120).map((span, index) => normalizeAiTraceEvent({
+      ...span,
+      id: span.id || `plan_${index + 1}`,
+      spanId: span.spanId || span.id || `plan_${index + 1}`,
+      parentSpanId: span.parentSpanId || span.parentId || "",
+      type: span.type || "turn",
+      status: "planned",
+      phase: "planned",
+      sideEffect: span.sideEffect || "none",
+      startedAt: new Date().toISOString(),
+    }, { traceId: sessionId, phase: "planned", sequence: index + 1 })),
+  };
+}
+
+export function materializableAiTraceEvents(session) {
+  const events = Array.isArray(session?.events) ? session.events : [];
+  const planned = events.filter((event) => event.phase === "planned");
+  if (planned.length) return planned;
+  return events.filter((event) => event.phase === "observed");
+}
+
+export function classifyAiToolSideEffect(toolName, subtype = "") {
+  const value = `${toolName || ""} ${subtype || ""}`.trim().toLowerCase();
+  if (/(?:^|[_\W])thinking(?:$|[_\W])/.test(value)) return "none";
+  if (/(?:^|[_\W])(web|http|curl|fetch|mcp|publish|send|notify|deploy)(?:$|[_\W])/.test(value)) return "external";
+  if (/(?:^|[_\W])(read|search|find|grep|glob|list|inspect|status|stat|cat|head|tail)(?:$|[_\W])/.test(value)) return "read";
+  return "write";
+}
+
+export function aiPlanPrompt({ goal = "", workspaceSource = "" } = {}) {
+  return [
+    "你是 AgentFlow 的只读 Plan Agent。只规划，不执行工具，不修改文件。",
+    "把用户目标转换为一张预计 AI 运行图。只输出合法 JSON，不要 Markdown 代码围栏。",
+    "JSON 格式：",
+    '{"title":"短标题","summary":"计划摘要","spans":[{"id":"step_1","parentSpanId":"","type":"turn|decision|agent|tool|command|file|artifact","name":"步骤名","summary":"做什么以及为什么","sideEffect":"none|read|write|external","requiresApproval":false,"inputPreview":"预计输入","outputPreview":"预期输出"}]}',
+    "要求：id 唯一；parentSpanId 表达父子关系；写文件、发布、发送、删除、外部写请求必须标记 requiresApproval=true；搜索与读取标记 read；不要假装已经得到任何执行结果。",
+    workspaceSource ? `\n## 当前 Workspace DSL\n\n${workspaceSource}` : "",
+    `\n## 用户目标\n\n${clip(goal, 12000)}`,
+  ].filter(Boolean).join("\n");
+}
+
+export function aiMaterializationPrompt(session, workspaceSource = "") {
+  const events = materializableAiTraceEvents(session);
+  const plan = events.map((event) => ({
+    spanId: event.spanId,
+    parentSpanId: event.parentSpanId,
+    type: event.type,
+    name: event.name,
+    summary: event.summary,
+    sideEffect: event.sideEffect,
+    requiresApproval: event.requiresApproval,
+  }));
+  return [
+    "你是 AgentFlow 流程固化 Agent。把已审核的 AI Plan 固化到当前 Workspace DSL 调整态。",
+    "必须实际编辑 workspace.flow.js；稳定脚本放入 nodes/<name>/index.mjs；不要执行该流程，不要发布。",
+    "过滤纯搜索噪声；把输入参数化；把判断映射为 control.if，把受控重复映射为 control.while，把产物映射为 Display；副作用步骤必须保留清晰名称和输入。",
+    "修改完成后运行 `agentflow flow dsl lint <当前流程目录>`。最终只简短说明生成了哪些节点以及仍需人工确认的副作用。",
+    workspaceSource ? `\n## 当前 Workspace DSL\n\n${workspaceSource}` : "",
+    `\n## 探索目标\n\n${clip(session?.goal || "", 8000)}`,
+    `\n## 已审核 Plan Trace\n\n${JSON.stringify(plan, null, 2)}`,
+  ].filter(Boolean).join("\n");
+}
+
+export function writeAiExplorationMaterialization(workspaceRoot, sessionId, value = {}) {
+  const session = readAiExplorationSession(workspaceRoot, sessionId);
+  const payload = {
+    version: 1,
+    sessionId: session.id,
+    materializedAt: new Date().toISOString(),
+    spanIds: materializableAiTraceEvents(session).map((event) => event.spanId).filter(Boolean),
+    nodeIds: (Array.isArray(value.nodeIds) ? value.nodeIds : []).map((id) => clip(id, 160)).filter(Boolean),
+    ...(value.designRevision ? { designRevision: clip(value.designRevision, 160) } : {}),
+  };
+  writeJsonAtomic(path.join(sessionDir(workspaceRoot, session.id), "materialization.json"), payload);
+  return payload;
+}

package/bin/lib/composer-agent.mjs

@@ -319,6 +319,11 @@ function runCursorAgentWithPrivateMcp(cliWorkspace, prompt, options, userId) {
  * @param {string} [opts.modelKey]
  * @param {Record<string, string>} [opts.extraEnv]
  * @param {boolean} [opts.force]
+ * @param {"ask" | "plan"} [opts.mode]
+ * @param {boolean} [opts.sandboxDisabled]
+ * @param {boolean} [opts.approveMcps]
+ * @param {"read-only" | "workspace-write" | "danger-full-access"} [opts.sandboxMode]
+ * @param {boolean} [opts.includeJsonResult]
  * @param {(ev: object) => void} [opts.onStreamEvent]
  * @param {(subtype: string, toolName: string) => void} [opts.onToolCall]
  * @returns {{ child: import('child_process').ChildProcess, finished: Promise<void> }}
@@ -343,6 +348,12 @@ export function startComposerAgent(opts) {
     onChild: opts.onChild,
     detached: Boolean(opts.detached),
     force: Boolean(opts.force),
+    ...(opts.mode ? { mode: String(opts.mode) } : {}),
+    ...(opts.sandboxDisabled === false ? { sandboxDisabled: false } : {}),
+    ...(typeof opts.approveMcps === "boolean" ? { approveMcps: opts.approveMcps } : {}),
+    ...(opts.sandboxMode ? { sandboxMode: String(opts.sandboxMode) } : {}),
+    ...(opts.allowDanger === false ? { allowDanger: false } : {}),
+    ...(opts.includeJsonResult === true ? { includeJsonResult: true } : {}),
     env,
     addDirs: Array.isArray(opts.writableDirs)
       ? opts.writableDirs.map((dir) => String(dir || "").trim()).filter(Boolean)

package/bin/lib/cursor-api-key-pool.mjs

@@ -18,6 +18,7 @@ export function parseCursorApiKeyRecords(value = "") {
       id: String(item.id || "").trim() || legacyKeyId(key),
       name: String(item.name || "").trim() || `Key ${index + 1}`,
       key,
+      createdAt: String(item.createdAt || "").trim(),
     };
   };
   try {
@@ -89,6 +90,7 @@ export function markCursorApiKeyLaneBlocked(
   cooldownMinutes = 30,
   errorText = "",
   now = Date.now(),
+  evidence = {},
 ) {
   const keyId = selectionId(keyOrSelection);
   if (!keyId || !["auto", "fallback"].includes(lane)) return 0;
@@ -97,12 +99,23 @@ export function markCursorApiKeyLaneBlocked(
   const currentLane = keyState[lane] || {};
   const blockedUntil = Math.max(currentLane.blockedUntil || 0, now + minutes * 60 * 1000);
   const errorCategory = classifyCursorApiKeyLimitError(errorText);
+  const fallbackModel = keyState.fallbackModel;
+  const lastFailure = {
+    triggeredAt: new Date(now).toISOString(),
+    ...(errorCategory ? { errorCategory } : {}),
+    errorPreview: sanitizeErrorPreview(errorText),
+    lane,
+    modelId: String(evidence?.modelId || (lane === "auto" ? "auto" : fallbackModel?.id || "fallback")),
+    modelName: String(evidence?.modelName || (lane === "auto" ? "Auto" : fallbackModel?.displayName || "降级模型")),
+  };
   keyState[lane] = {
     ...currentLane,
     blockedUntil,
     ...(errorCategory ? { errorCategory } : {}),
     ...(lane === "auto" ? { fallbackEligible: isCursorAutoFallbackEligible(errorText) } : {}),
+    lastFailure,
   };
+  keyState.lastFailure = lastFailure;
   cursorApiKeyStates.set(keyId, keyState);
   return blockedUntil;
 }
@@ -116,6 +129,72 @@ export function clearCursorApiKeyLaneCooldown(keyOrSelection, lane) {
   return true;
 }
 
+export function clearCursorApiKeyCooldown(keyOrSelection) {
+  const keyState = cursorApiKeyStates.get(selectionId(keyOrSelection));
+  if (!keyState) return false;
+  let changed = false;
+  for (const lane of ["auto", "fallback"]) {
+    if (!keyState[lane] || (keyState[lane].blockedUntil || 0) <= 0) continue;
+    keyState[lane].blockedUntil = 0;
+    delete keyState[lane].errorCategory;
+    delete keyState[lane].fallbackEligible;
+    changed = true;
+  }
+  return changed;
+}
+
+export function recordCursorApiKeyUsage(keyOrSelection, selection = {}, now = Date.now()) {
+  const keyId = selectionId(keyOrSelection);
+  if (!keyId || keyId === "default") return;
+  const keyState = cursorApiKeyStates.get(keyId) || {};
+  keyState.lastUsedAt = new Date(now).toISOString();
+  keyState.lastSelection = {
+    lane: selection?.lane === "fallback" ? "fallback" : "auto",
+    modelId: String(selection?.modelId || "auto"),
+    modelName: String(selection?.modelName || "Auto"),
+  };
+  cursorApiKeyStates.set(keyId, keyState);
+}
+
+export function getCursorApiKeyPoolStatuses(records = [], now = Date.now()) {
+  return (Array.isArray(records) ? records : []).map((record) => {
+    const id = selectionId(record);
+    const keyState = cursorApiKeyStates.get(id);
+    const selection = getCursorApiKeyModelSelection(id, now);
+    const laneCooldowns = buildLaneCooldowns(keyState, now);
+    const common = {
+      id,
+      ...(keyState?.lastUsedAt ? { lastUsedAt: keyState.lastUsedAt } : {}),
+      ...(keyState?.fallbackModel ? { fallbackModel: keyState.fallbackModel } : {}),
+      laneCooldowns,
+      ...(keyState?.lastFailure ? { lastFailure: keyState.lastFailure } : {}),
+    };
+    if (selection) {
+      return {
+        ...common,
+        status: "available",
+        activeLane: selection.lane,
+        activeModelId: selection.modelId,
+        activeModelName: selection.modelName,
+        degraded: selection.lane === "fallback",
+      };
+    }
+    const activeCooldowns = laneCooldowns.filter((item) => item.remainingSeconds > 0);
+    const earliest = activeCooldowns.reduce(
+      (result, item) => !result || item.remainingSeconds < result.remainingSeconds ? item : result,
+      undefined,
+    );
+    const autoState = keyState?.auto;
+    return {
+      ...common,
+      status: "cooling_down",
+      ...(autoState?.errorCategory ? { errorCategory: autoState.errorCategory } : {}),
+      blockedUntil: earliest?.blockedUntil || new Date(Math.max(now, autoState?.blockedUntil || now)).toISOString(),
+      remainingSeconds: earliest?.remainingSeconds || Math.max(0, Math.ceil(((autoState?.blockedUntil || now) - now) / 1000)),
+    };
+  });
+}
+
 export function cursorApiKeyEnv(selection) {
   return selection?.key ? { CURSOR_API_KEY: selection.key } : {};
 }
@@ -159,7 +238,10 @@ export function isCursorQuotaError(error = "") {
   return classifyCursorApiKeyLimitError(error) !== undefined;
 }
 
-export function cursorApiKeyCooldownMinutes(env = {}) {
+export function cursorApiKeyCooldownMinutes(env = {}, errorText = "") {
+  if (classifyCursorApiKeyLimitError(errorText) === "resource_exhausted") {
+    return Math.max(1, Number(env.AGENTFLOW_CURSOR_API_KEY_RESOURCE_EXHAUSTED_COOLDOWN_MINUTES || 3) || 3);
+  }
   return Math.max(1, Number(env.AGENTFLOW_CURSOR_API_KEY_COOLDOWN_MINUTES || env.CURSOR_API_KEY_COOLDOWN_MINUTES || 30) || 30);
 }
 
@@ -178,3 +260,26 @@ function selectionId(keyOrSelection) {
 function legacyKeyId(key) {
   return `legacy_${createHash("sha256").update(String(key || "")).digest("hex").slice(0, 16)}`;
 }
+
+function buildLaneCooldowns(keyState, now) {
+  if (!keyState) return [];
+  const lanes = [];
+  for (const lane of ["auto", "fallback"]) {
+    const laneState = keyState[lane];
+    if (!laneState || (laneState.blockedUntil || 0) <= now) continue;
+    const fallbackModel = keyState.fallbackModel;
+    lanes.push({
+      lane,
+      modelId: lane === "auto" ? "auto" : fallbackModel?.id || "fallback",
+      modelName: lane === "auto" ? "Auto" : fallbackModel?.displayName || "降级模型",
+      ...(laneState.errorCategory ? { errorCategory: laneState.errorCategory } : {}),
+      blockedUntil: new Date(laneState.blockedUntil).toISOString(),
+      remainingSeconds: Math.ceil((laneState.blockedUntil - now) / 1000),
+    });
+  }
+  return lanes;
+}
+
+function sanitizeErrorPreview(errorText) {
+  return String(errorText || "").replace(/(?:sk|key)[-_][A-Za-z0-9_-]{8,}/gi, "[redacted]").trim().slice(0, 500);
+}

package/bin/lib/repository-index-events.mjs

@@ -0,0 +1,17 @@
+const runFinishedListeners = new Set();
+
+export function onRepositoryRunFinished(listener) {
+  if (typeof listener !== "function") return () => {};
+  runFinishedListeners.add(listener);
+  return () => runFinishedListeners.delete(listener);
+}
+
+export function emitRepositoryRunFinished(workspaceRoot, run, status) {
+  for (const listener of runFinishedListeners) {
+    try {
+      listener(workspaceRoot, run, status);
+    } catch {
+      // Derived repository updates must never break the authoritative run ledger.
+    }
+  }
+}