@fieldwangai/agentflow 0.1.165 → 0.1.167

package/bin/lib/agent-runners.mjs

@@ -7,13 +7,19 @@ import { normalizeCursorModelForCli } from "./model-config.mjs";
 import { t } from "./i18n.mjs";
 import { readMergedEnvObject } from "./user-env.mjs";
 import {
+  classifyCursorApiKeyLimitError,
+  clearCursorApiKeyLaneCooldown,
   createCursorApiKeyAttempts,
   cursorApiKeyCooldownMinutes,
   cursorApiKeyEnv,
   cursorApiKeyLabel,
+  isCursorAutoFallbackEligible,
   isCursorQuotaError,
-  markCursorApiKeyQuotaBlocked,
+  markCursorApiKeyLaneBlocked,
+  recordCursorApiKeyFallbackModel,
+  recordCursorApiKeyUsage,
 } from "./cursor-api-key-pool.mjs";
+import { discoverCursorModels } from "./cursor-model-catalog.mjs";
 import { outputNodeBasename } from "../pipeline/get-exec-id.mjs";
 
 function shouldPassCursorModelArg(model) {
@@ -53,6 +59,16 @@ function nextCursorAttemptOptions(options = {}, attempts = [], attemptIndex = 0)
     ...options,
     _agentflowCursorApiKeyAttempts: attempts,
     _agentflowCursorApiKeyAttemptIndex: attemptIndex + 1,
+    _agentflowCursorModelSelection: undefined,
+  };
+}
+
+function cursorModelAttemptOptions(options = {}, attempts = [], attemptIndex = 0, modelSelection) {
+  return {
+    ...options,
+    _agentflowCursorApiKeyAttempts: attempts,
+    _agentflowCursorApiKeyAttemptIndex: attemptIndex,
+    _agentflowCursorModelSelection: modelSelection,
   };
 }
 
@@ -108,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();
@@ -122,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");
@@ -402,7 +418,7 @@ function tryEmitOpenCodeLineAsNatural(line, emit) {
 export function runCursorAgentWithPrompt(cliWorkspace, promptText, options = {}) {
   const onStreamEvent = typeof options.onStreamEvent === "function" ? options.onStreamEvent : null;
   const ws = path.resolve(cliWorkspace);
-  const model = normalizeCursorModelForCli(options.model ?? process.env.CURSOR_AGENT_MODEL ?? null);
+  const requestedModel = normalizeCursorModelForCli(options.model ?? process.env.CURSOR_AGENT_MODEL ?? null);
   const agentCmd = process.env.CURSOR_AGENT_CMD || "agent";
   const {
     baseEnv: cursorBaseEnv,
@@ -410,11 +426,23 @@ export function runCursorAgentWithPrompt(cliWorkspace, promptText, options = {})
     attemptIndex: cursorAttemptIndex,
     selection: cursorSelection,
   } = cursorAttemptOptions(options);
+  const hasExplicitModel = shouldPassCursorModelArg(requestedModel);
+  const cursorModelSelection = hasExplicitModel
+    ? { lane: "auto", modelId: requestedModel, modelName: requestedModel }
+    : options._agentflowCursorModelSelection
+      || 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);
 
@@ -448,6 +476,12 @@ export function runCursorAgentWithPrompt(cliWorkspace, promptText, options = {})
       line: `Cursor API Key ${cursorApiKeyLabel(cursorSelection)} / ${cursorAttempts.length}`,
     });
   }
+  if (cursorModelSelection.lane === "fallback") {
+    emit({
+      type: "status",
+      line: `Cursor is using Composer fallback: ${cursorModelSelection.modelName}`,
+    });
+  }
 
   if (!useStderrInherit) {
     child.stderr.on("data", (chunk) => {
@@ -523,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",
@@ -588,20 +626,88 @@ export function runCursorAgentWithPrompt(cliWorkspace, promptText, options = {})
       }
       const retryCursorQuota = (errorText) => {
         if (!cursorSelection) return false;
-        if (cursorAttemptIndex >= cursorAttempts.length - 1) return false;
         if (hadToolActivity) return false;
         if (!isCursorQuotaError(errorText)) return false;
-        markCursorApiKeyQuotaBlocked(cursorSelection, cursorApiKeyCooldownMinutes(cursorBaseEnv));
-        emit({
-          type: "status",
-          line: `Cursor API Key ${cursorApiKeyLabel(cursorSelection)} reached quota, retrying ${cursorAttemptIndex + 2}/${cursorAttempts.length}`,
-        });
-        const next = runCursorAgentWithPrompt(
-          cliWorkspace,
-          promptText,
-          nextCursorAttemptOptions(options, cursorAttempts, cursorAttemptIndex),
+        const errorCategory = classifyCursorApiKeyLimitError(errorText);
+        const cooldownMinutes = cursorApiKeyCooldownMinutes(cursorBaseEnv, errorText);
+        markCursorApiKeyLaneBlocked(
+          cursorSelection,
+          cursorModelSelection.lane,
+          cooldownMinutes,
+          errorText,
+          Date.now(),
+          {
+            modelId: cursorModelSelection.modelId,
+            modelName: cursorModelSelection.modelName,
+          },
         );
-        next.finished.then(resolve).catch(reject);
+        const canTryComposer = !hasExplicitModel
+          && cursorModelSelection.lane === "auto"
+          && errorCategory === "explicit_limit"
+          && isCursorAutoFallbackEligible(errorText);
+        const hasNextKey = cursorAttemptIndex < cursorAttempts.length - 1;
+        if (!canTryComposer && !hasNextKey) return false;
+
+        const retry = async () => {
+          if (canTryComposer) {
+            emit({
+              type: "status",
+              line: `Cursor Auto on API Key ${cursorApiKeyLabel(cursorSelection)} is out of usage; discovering Composer fallback...`,
+            });
+            const catalog = await discoverCursorModels({
+              keyId: cursorSelection.id,
+              cwd: ws,
+              command: agentCmd,
+              env: childEnv(options, cursorApiKeyEnv(cursorSelection)),
+            });
+            if (catalog.fallbackModel) {
+              recordCursorApiKeyFallbackModel(cursorSelection, catalog.fallbackModel);
+              const fallbackSelection = {
+                lane: "fallback",
+                modelId: catalog.fallbackModel.id,
+                modelName: catalog.fallbackModel.displayName,
+              };
+              emit({
+                type: "status",
+                line: `Switching the same Cursor API Key to ${fallbackSelection.modelName}.`,
+              });
+              emit({
+                type: "raw",
+                source: "cursor",
+                stream: "runner",
+                eventType: "model_fallback",
+                text: `auto -> ${fallbackSelection.modelId}`,
+              });
+              const fallback = runCursorAgentWithPrompt(
+                cliWorkspace,
+                promptText,
+                cursorModelAttemptOptions(options, cursorAttempts, cursorAttemptIndex, fallbackSelection),
+              );
+              await fallback.finished;
+              return;
+            }
+            emit({
+              type: "status",
+              line: `Composer fallback is unavailable${catalog.error ? `: ${catalog.error}` : "."}`,
+            });
+          }
+
+          if (hasNextKey) {
+            emit({
+              type: "status",
+              line: `Cursor API Key ${cursorApiKeyLabel(cursorSelection)} reached its limit; retrying ${cursorAttemptIndex + 2}/${cursorAttempts.length}.`,
+            });
+            const next = runCursorAgentWithPrompt(
+              cliWorkspace,
+              promptText,
+              nextCursorAttemptOptions(options, cursorAttempts, cursorAttemptIndex),
+            );
+            await next.finished;
+            return;
+          }
+          throw new Error(errorText || "Cursor API Key reached its limit.");
+        };
+        retry().then(resolve).catch(reject);
         return true;
       };
       if (code !== 0 && lastResult == null) {
@@ -622,6 +728,7 @@ export function runCursorAgentWithPrompt(cliWorkspace, promptText, options = {})
         reject(new Error(msg));
         return;
       }
+      if (cursorSelection) clearCursorApiKeyLaneCooldown(cursorSelection, cursorModelSelection.lane);
       resolve();
     });
   });
@@ -748,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];
@@ -941,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)