@downcity/plugins 1.0.4

package/src/task/runtime/TaskRunnerRound.ts

@@ -0,0 +1,337 @@
+/**
+ * TaskRunnerRound：task runner 单轮执行与输出解析模块。
+ *
+ * 关键点（中文）
+ * - 收敛 agent/script 单轮执行、assistant 输出提取、模拟用户判定解析等逻辑。
+ * - 这些逻辑可独立演进，不必与 run 目录产物写入混在一起。
+ */
+
+import path from "node:path";
+import fs from "fs-extra";
+import { stripInvocationAuthEnv } from "@downcity/agent/internal/runtime/server/http/auth/AuthEnv.js";
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import { runSandboxCommand } from "@downcity/agent/internal/runtime/sandbox/SandboxRunner.js";
+import type { SessionRunResult } from "@downcity/agent/internal/executor/types/SessionRun.js";
+import type { JsonObject } from "@downcity/agent/internal/types/common/Json.js";
+import type {
+  ChatSendOutputPick,
+  ScriptExecutionResult,
+  TaskResultValidation,
+  TaskSessionRuntimePort,
+  UserSimulatorDecision,
+} from "@/task/runtime/TaskRunnerTypes.js";
+import { withSessionRunScope } from "@downcity/agent/internal/executor/SessionRunScope.js";
+import { appendTaskRoundUserMessage } from "./TaskRunnerSession.js";
+
+/**
+ * 从文本中提取 JSON 对象（支持 ```json 代码块）。
+ */
+export function tryExtractJsonObject(text: string): JsonObject | null {
+  const raw = String(text ?? "").trim();
+  if (!raw) return null;
+
+  const tryParse = (s: string): JsonObject | null => {
+    try {
+      const parsed = JSON.parse(s);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        return parsed as JsonObject;
+      }
+      return null;
+    } catch {
+      return null;
+    }
+  };
+
+  const direct = tryParse(raw);
+  if (direct) return direct;
+
+  const fenced = raw.match(/```json\s*([\s\S]*?)\s*```/i);
+  if (fenced?.[1]) {
+    const parsed = tryParse(fenced[1].trim());
+    if (parsed) return parsed;
+  }
+
+  const loose = raw.match(/\{[\s\S]*\}/);
+  if (loose?.[0]) {
+    const parsed = tryParse(loose[0]);
+    if (parsed) return parsed;
+  }
+
+  return null;
+}
+
+function extractTextFromAssistantMessageParts(parts: unknown): string {
+  if (!Array.isArray(parts)) return "";
+  const texts: string[] = [];
+  for (const part of parts) {
+    if (!part || typeof part !== "object") continue;
+    const p = part as { type?: unknown; text?: unknown };
+    if (p.type !== "text" && p.type !== "input_text") continue;
+    if (typeof p.text !== "string") continue;
+    const value = p.text.trim();
+    if (!value) continue;
+    texts.push(value);
+  }
+  return texts.join("\n").trim();
+}
+
+/**
+ * 从 assistant 输出中提取 task 的最终结果文本。
+ *
+ * 关键点（中文）
+ * - 这里故意保持最简：只取最后 assistant 返回中的文本内容。
+ * - 不再额外解析 `chat_send` tool call，也不再区分“过程发送文本”与“最终结果文本”。
+ * - task 的过程内容保留在 `messages.jsonl / dialogue.md`；`output.md` 只记录最后 assistant 文本。
+ */
+export function pickAgentOutput(
+  assistantMessage: SessionRunResult["assistantMessage"],
+): ChatSendOutputPick {
+  return {
+    text: extractTextFromAssistantMessageParts(
+      (assistantMessage as { parts?: unknown } | null)?.parts,
+    ),
+    delivered: false,
+  };
+}
+
+/**
+ * 解析模拟用户 agent 的判定结果。
+ */
+export function parseUserSimulatorDecision(outputText: string): UserSimulatorDecision {
+  const raw = String(outputText ?? "").trim();
+  const obj = tryExtractJsonObject(raw);
+  if (obj) {
+    const satisfiedRaw = obj.satisfied;
+    const satisfied =
+      satisfiedRaw === true ||
+      (typeof satisfiedRaw === "string" && satisfiedRaw.trim().toLowerCase() === "true");
+    const reply = String(obj.reply ?? "").trim();
+    const reason = String(obj.reason ?? "").trim();
+    const scoreRaw = obj.score;
+    const score =
+      typeof scoreRaw === "number"
+        ? scoreRaw
+        : typeof scoreRaw === "string" && /^(\d+)(\.\d+)?$/.test(scoreRaw.trim())
+          ? Number(scoreRaw)
+          : undefined;
+    const normalizedScore =
+      typeof score === "number" && Number.isFinite(score) && score >= 0 && score <= 10
+        ? score
+        : undefined;
+    return {
+      satisfied,
+      reply,
+      reason,
+      ...(typeof normalizedScore === "number" ? { score: normalizedScore } : {}),
+      raw,
+    };
+  }
+
+  const lower = raw.toLowerCase();
+  const likelySatisfied =
+    (lower.includes("satisfied") || lower.includes("满意") || lower.includes("通过")) &&
+    !lower.includes("not satisfied") &&
+    !lower.includes("不满意");
+
+  return {
+    satisfied: likelySatisfied,
+    reply: raw,
+    reason: likelySatisfied ? "heuristic satisfied" : "heuristic not satisfied",
+    raw,
+  };
+}
+
+/**
+ * 构造执行 agent 的轮次输入。
+ */
+export function buildExecutorRoundQuery(params: {
+  taskBody: string;
+  round: number;
+  lastOutputText?: string;
+  lastFeedback?: string;
+}): string {
+  if (params.round <= 1) return params.taskBody;
+  return [
+    "# 任务目标（保持不变）",
+    "",
+    params.taskBody || "_(empty body)_",
+    "",
+    `# 这是第 ${params.round} 轮执行`,
+    "",
+    "请根据以下“模拟用户反馈”和“上一轮输出”进行修订，并给出新的完整结果。",
+    "",
+    "## 模拟用户反馈",
+    "",
+    params.lastFeedback ? params.lastFeedback : "_(no feedback)_",
+    "",
+    "## 上一轮输出",
+    "",
+    params.lastOutputText ? params.lastOutputText : "_(empty output)_",
+    "",
+  ].join("\n");
+}
+
+/**
+ * 构造模拟用户 agent 的判定输入。
+ */
+export function buildUserSimulatorQuery(params: {
+  taskTitle: string;
+  taskDescription: string;
+  taskBody: string;
+  round: number;
+  maxRounds: number;
+  executorOutputText: string;
+  ruleErrors: string[];
+}): string {
+  const ruleSection =
+    params.ruleErrors.length > 0
+      ? params.ruleErrors.map((x) => `- ${x}`).join("\n")
+      : "- (none)";
+  return [
+    "你是一个“模拟用户”Agent。你要根据任务目标审阅执行结果，并给出用户回复。",
+    "",
+    "请严格输出 JSON 对象（不要输出 markdown）：",
+    '{"satisfied": boolean, "reply": string, "reason": string, "score": number}',
+    "",
+    "规则：",
+    "1) 如果结果还不满足目标，satisfied 必须是 false，reply 要像用户一样明确提出修改要求。",
+    "2) 如果已经满足，satisfied=true，reply 给简短确认。",
+    "3) score 范围 0-10。",
+    "4) 如果系统规则校验有失败项（见下方），必须判定为不满意。",
+    "",
+    `任务标题: ${params.taskTitle}`,
+    `任务描述: ${params.taskDescription}`,
+    `当前轮次: ${params.round}/${params.maxRounds}`,
+    "",
+    "任务正文：",
+    params.taskBody || "_(empty body)_",
+    "",
+    "系统规则校验失败项：",
+    ruleSection,
+    "",
+    "执行 Agent 本轮输出：",
+    params.executorOutputText || "_(empty output)_",
+    "",
+  ].join("\n");
+}
+
+/**
+ * 执行一轮 agent.run。
+ */
+export async function runAgentRound(params: {
+  taskSessionRuntime: TaskSessionRuntimePort;
+  sessionId: string;
+  taskId: string;
+  query: string;
+  actorId: string;
+  actorName: string;
+}): Promise<{ outputText: string; delivered: boolean; rawResult: SessionRunResult }> {
+  try {
+    await appendTaskRoundUserMessage({
+      taskSessionRuntime: params.taskSessionRuntime,
+      sessionId: params.sessionId,
+      taskId: params.taskId,
+      query: params.query,
+      actorId: params.actorId,
+      actorName: params.actorName,
+    });
+  } catch {
+    // ignore
+  }
+
+  const result = await withSessionRunScope(
+    {
+      sessionId: params.sessionId,
+    },
+    () =>
+      params.taskSessionRuntime.getExecutor(params.sessionId).run({
+        query: params.query,
+      }),
+  );
+  const outputPick = pickAgentOutput(result.assistantMessage);
+
+  if (!result.success) {
+    const reason = outputPick.text || "agent run returned success=false";
+    throw new Error(reason);
+  }
+
+  if (!String(outputPick.text || "").trim()) {
+    throw new Error("agent produced no user-visible output");
+  }
+
+  return {
+    outputText: outputPick.text,
+    delivered: outputPick.delivered,
+    rawResult: result,
+  };
+}
+
+/**
+ * 执行 script 类型任务。
+ */
+export async function runScriptTask(params: {
+  context: AgentContext;
+  runDirAbs: string;
+  sessionId: string;
+  scriptBody: string;
+}): Promise<ScriptExecutionResult> {
+  const body = String(params.scriptBody || "");
+  if (!body.trim()) throw new Error("script task body cannot be empty");
+
+  const scriptAbs = path.join(params.runDirAbs, "task-script.sh");
+  await fs.writeFile(scriptAbs, body.endsWith("\n") ? body : `${body}\n`, "utf-8");
+
+  const execResult = await withSessionRunScope(
+    { sessionId: params.sessionId },
+    () => {
+      const childEnv: NodeJS.ProcessEnv = {
+        ...process.env,
+        DC_SESSION_ID: params.sessionId,
+      };
+      stripInvocationAuthEnv(childEnv);
+      return runSandboxCommand({
+        context: params.context,
+        shellId: `task-script:${params.sessionId}`,
+        shellDir: params.runDirAbs,
+        cmd: `sh "${scriptAbs.replace(/(["\\$`])/g, "\\$1")}"`,
+        cwd: params.runDirAbs,
+        shellPath: "/bin/sh",
+        login: false,
+        baseEnv: childEnv,
+      });
+    }
+  );
+
+  const stdout = String(execResult.stdout || "").trim();
+  const stderr = String(execResult.stderr || "").trim();
+  const combined = [stdout, stderr].filter(Boolean).join("\n");
+  return {
+    outputText: combined,
+  };
+}
+
+/**
+ * 校验任务结果是否满足“必须有结果”的规则。
+ */
+export async function validateTaskResult(params: {
+  outputText: string;
+}): Promise<TaskResultValidation> {
+  const errors: string[] = [];
+  const minOutputChars = 1;
+  const outputChars = String(params.outputText ?? "").trim().length;
+  if (outputChars < minOutputChars) {
+    errors.push(`output too short: got ${outputChars}, expected >= ${minOutputChars}`);
+  }
+
+  if (errors.length > 0) {
+    return {
+      resultStatus: "invalid",
+      errors,
+    };
+  }
+
+  return {
+    resultStatus: "valid",
+    errors: [],
+  };
+}

package/src/task/runtime/TaskRunnerScript.ts

@@ -0,0 +1,175 @@
+/**
+ * TaskRunnerScript：script 类型任务执行分支。
+ *
+ * 关键点（中文）
+ * - script 任务是 one-shot 执行，不进入 agent 多轮评审。
+ * - 这里集中处理 script 执行、结果校验与进度更新，Runner 主链只消费归一化结果。
+ */
+
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import type {
+  ShipTaskRunExecutionStatusV1,
+  ShipTaskRunResultStatusV1,
+  ShipTaskRunStatusV1,
+} from "@/task/types/Task.js";
+import type { createRunProgressWriter } from "./TaskRunnerProgress.js";
+import { summarizeText } from "./TaskRunnerProgress.js";
+import { runScriptTask, validateTaskResult } from "./TaskRunnerRound.js";
+
+/**
+ * script 任务分支执行参数。
+ */
+export interface RunScriptTaskBranchParams {
+  /**
+   * 当前 Agent 执行上下文。
+   */
+  context: AgentContext;
+  /**
+   * 当前 run 目录绝对路径。
+   */
+  runDirAbs: string;
+  /**
+   * script 任务绑定的 sessionId。
+   */
+  sessionId: string;
+  /**
+   * script 正文。
+   */
+  scriptBody: string;
+  /**
+   * run-progress.json 写入器。
+   */
+  runProgress: ReturnType<typeof createRunProgressWriter>;
+}
+
+/**
+ * script 任务分支执行结果。
+ */
+export interface RunScriptTaskBranchResult {
+  /**
+   * 当前任务是否整体成功。
+   */
+  ok: boolean;
+  /**
+   * run 最终状态。
+   */
+  status: ShipTaskRunStatusV1;
+  /**
+   * 执行器状态。
+   */
+  executionStatus: ShipTaskRunExecutionStatusV1;
+  /**
+   * 结果校验状态。
+   */
+  resultStatus: ShipTaskRunResultStatusV1;
+  /**
+   * 结果校验错误列表。
+   */
+  resultErrors: string[];
+  /**
+   * script 固定占用一轮 dialogue 计数。
+   */
+  dialogueRounds: number;
+  /**
+   * script 任务成功时视为用户模拟器已满意。
+   */
+  userSimulatorSatisfied: boolean;
+  /**
+   * script 标准输出文本。
+   */
+  outputText: string;
+  /**
+   * 失败时的错误文本。
+   */
+  errorText: string;
+}
+
+/**
+ * 执行 script 任务分支。
+ */
+export async function runScriptTaskBranch(
+  params: RunScriptTaskBranchParams,
+): Promise<RunScriptTaskBranchResult> {
+  let ok = false;
+  let status: ShipTaskRunStatusV1 = "failure";
+  let executionStatus: ShipTaskRunExecutionStatusV1 = "success";
+  let resultStatus: ShipTaskRunResultStatusV1 = "not_checked";
+  let resultErrors: string[] = [];
+  let userSimulatorSatisfied = false;
+  let outputText = "";
+  let errorText = "";
+
+  await params.runProgress.update({
+    status: "running",
+    phase: "script_running",
+    message: "正在执行 script 任务",
+    round: 1,
+    maxRounds: 1,
+  });
+
+  try {
+    const scriptResult = await runScriptTask({
+      context: params.context,
+      runDirAbs: params.runDirAbs,
+      sessionId: params.sessionId,
+      scriptBody: params.scriptBody,
+    });
+    outputText = scriptResult.outputText;
+    await params.runProgress.update({
+      status: "running",
+      phase: "validating",
+      message: "script 执行完成，正在校验输出与产物",
+      round: 1,
+      maxRounds: 1,
+    });
+    const validation = await validateTaskResult({ outputText });
+    if (validation.errors.length === 0) {
+      ok = true;
+      status = "success";
+      resultStatus = "valid";
+      resultErrors = [];
+      userSimulatorSatisfied = true;
+    } else {
+      ok = false;
+      status = "failure";
+      resultStatus = "invalid";
+      resultErrors = [...validation.errors];
+      errorText = [
+        "Script task result validation failed.",
+        ...resultErrors.map((item) => `- ${item}`),
+      ].join("\n");
+      await params.runProgress.update({
+        status: "running",
+        phase: "validating",
+        message: "输出校验未通过，准备写入失败产物",
+        round: 1,
+        maxRounds: 1,
+      });
+    }
+  } catch (error) {
+    executionStatus = "failure";
+    status = "failure";
+    resultStatus = "not_checked";
+    resultErrors = [];
+    errorText = `Script task execution failed: ${String(error)}`;
+    await params.runProgress.update({
+      status: "running",
+      phase: "script_running",
+      message: `script 执行失败: ${summarizeText(String(error), 160)}`,
+      round: 1,
+      maxRounds: 1,
+    });
+  }
+
+  return {
+    ok,
+    status,
+    executionStatus,
+    resultStatus,
+    resultErrors,
+    dialogueRounds: 1,
+    userSimulatorSatisfied,
+    outputText,
+    errorText,
+  };
+}

package/src/task/runtime/TaskRunnerSession.ts

@@ -0,0 +1,190 @@
+/**
+ * TaskRunnerSession：task runner 的 session 装配模块。
+ *
+ * 关键点（中文）
+ * - 负责构建 task 专用 Executor / JsonlSessionHistoryStore 运行时。
+ * - 负责把每轮 user/assistant 消息写入 run 目录对应的 messages.jsonl。
+ * - 这些能力与任务编排逻辑解耦后，task 主流程会更聚焦于状态流转。
+ * - 当前只有 api 执行模式。
+ */
+
+import path from "node:path";
+import type { LanguageModel } from "ai";
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import { Executor } from "@downcity/agent/internal/executor/Executor.js";
+import type { SessionRunResult } from "@downcity/agent/internal/executor/types/SessionRun.js";
+import type { TaskSessionRuntimePort } from "@/task/runtime/TaskRunnerTypes.js";
+import { drainDeferredPersistedUserMessages } from "@downcity/agent/internal/executor/SessionRunScope.js";
+import { JsonlSessionHistoryComposer } from "@downcity/agent/internal/executor/composer/history/jsonl/JsonlSessionHistoryComposer.js";
+import { JsonlSessionHistoryStore } from "@downcity/agent/internal/executor/store/history/jsonl/JsonlSessionHistoryStore.js";
+import { JsonlSessionCompactionComposer } from "@downcity/agent/internal/executor/composer/compaction/jsonl/JsonlSessionCompactionComposer.js";
+import { LocalSessionContextComposer } from "@downcity/agent/internal/executor/composer/context/LocalSessionContextComposer.js";
+import { DefaultSessionSystemComposer } from "@downcity/agent/internal/executor/composer/system/default/DefaultSessionSystemComposer.js";
+import { shellTools } from "@downcity/agent/internal/executor/tools/shell/ShellToolDefinition.js";
+import type { SessionExecutor } from "@downcity/agent/internal/executor/types/SessionExecutor.js";
+
+/**
+ * 把 task round 的 user query 落盘到对应 run context。
+ */
+export async function appendTaskRoundUserMessage(params: {
+  taskSessionRuntime: TaskSessionRuntimePort;
+  sessionId: string;
+  taskId: string;
+  query: string;
+  actorId: string;
+  actorName: string;
+}): Promise<void> {
+  const text = String(params.query || "").trim();
+  if (!text) return;
+  const historyStore = params.taskSessionRuntime.getHistoryStore(params.sessionId);
+  await historyStore.append(
+    historyStore.userText({
+      text,
+      metadata: {
+        sessionId: params.sessionId,
+        extra: {
+          taskId: params.taskId,
+          actorId: params.actorId,
+          actorName: params.actorName,
+        },
+      },
+    }),
+  );
+}
+
+/**
+ * 构建 task 专用 Session 运行时（独立于普通 Session 实例缓存）。
+ *
+ * 关键点（中文）
+ * - 使用 Executor 执行，但模型显式来自“任务绑定 session”的 session 级配置。
+ * - task runner 自己维护独立 history，不复用原 session 的消息落盘。
+ */
+export function createTaskSessionRuntimePort(params: {
+  context: AgentContext;
+  model: LanguageModel;
+  runDirAbs: string;
+  runSessionId: string;
+  userSimulatorSessionId: string;
+}): TaskSessionRuntimePort {
+  const {
+    context,
+    model,
+    runDirAbs,
+    runSessionId,
+    userSimulatorSessionId,
+  } = params;
+  const compactionComposer = new JsonlSessionCompactionComposer({
+    keepLastMessages: context.config.context?.messages?.keepLastMessages,
+    maxInputTokensApprox: context.config.context?.messages?.maxInputTokensApprox,
+    archiveOnCompact: context.config.context?.messages?.archiveOnCompact,
+    compactRatio: context.config.context?.messages?.compactRatio,
+  });
+  const systemComposer = new DefaultSessionSystemComposer({
+    projectRoot: context.rootPath,
+    getStaticSystemPrompts: () => context.systems,
+    getContext: () => context,
+    profile: "task",
+  });
+  const historyStoresBySessionId = new Map<string, JsonlSessionHistoryStore>();
+  const historyComposersBySessionId = new Map<string, JsonlSessionHistoryComposer>();
+  const runtimesBySessionId = new Map<string, SessionExecutor>();
+
+  const resolveTaskHistoryStore = (sessionId: string): JsonlSessionHistoryStore => {
+    const existing = historyStoresBySessionId.get(sessionId);
+    if (existing) return existing;
+
+    const key = String(sessionId || "").trim();
+    if (!key) {
+      throw new Error("TaskSessionRuntimePort requires a non-empty sessionId");
+    }
+    const runMessagesDirPath =
+      key === runSessionId
+        ? runDirAbs
+        : key === userSimulatorSessionId
+          ? path.join(runDirAbs, "user-simulator")
+          : undefined;
+
+    const created = new JsonlSessionHistoryStore({
+      rootPath: context.rootPath,
+      sessionId: key,
+      ...(runMessagesDirPath
+        ? {
+            paths: {
+              sessionDirPath: runMessagesDirPath,
+              messagesDirPath: runMessagesDirPath,
+              messagesFilePath: path.join(runMessagesDirPath, "messages.jsonl"),
+              metaFilePath: path.join(runMessagesDirPath, "meta.json"),
+              archiveDirPath: path.join(runMessagesDirPath, "archive"),
+            },
+          }
+        : {}),
+    });
+    historyStoresBySessionId.set(key, created);
+    return created;
+  };
+
+  const resolveTaskHistoryComposer = (sessionId: string): JsonlSessionHistoryComposer => {
+    const key = String(sessionId || "").trim();
+    const existing = historyComposersBySessionId.get(key);
+    if (existing) return existing;
+    const created = new JsonlSessionHistoryComposer({
+      store: resolveTaskHistoryStore(key),
+    });
+    historyComposersBySessionId.set(key, created);
+    return created;
+  };
+
+  return {
+    getHistoryStore(sessionId: string): JsonlSessionHistoryStore {
+      return resolveTaskHistoryStore(sessionId);
+    },
+    getExecutor(sessionId: string): SessionExecutor {
+      const key = String(sessionId || "").trim();
+      if (!key) {
+        throw new Error("TaskSessionRuntimePort.getExecutor requires a non-empty sessionId");
+      }
+      const existing = runtimesBySessionId.get(key);
+      if (existing) return existing;
+
+      const historyStore = resolveTaskHistoryStore(key);
+      const historyComposer = resolveTaskHistoryComposer(key);
+      const contextComposer = new LocalSessionContextComposer({
+        sessionId: key,
+        getTools: () => shellTools,
+      });
+      const created = new Executor({
+        sessionId: key,
+        getModel: () => model,
+        logger: context.logger,
+        historyStore,
+        historyComposer,
+        compactionComposer,
+        contextComposer,
+        systemComposer,
+        getTools: () => shellTools,
+      });
+      runtimesBySessionId.set(key, created);
+      return created;
+    },
+  };
+}
+
+/**
+ * 把 task session 的 assistant 消息落盘到对应 run context history Store。
+ */
+export async function appendTaskAssistantMessage(params: {
+  taskSessionRuntime: TaskSessionRuntimePort;
+  sessionId: string;
+  taskId: string;
+  rawResult: SessionRunResult;
+}): Promise<void> {
+  const { taskSessionRuntime, sessionId, rawResult } = params;
+  const historyStore = taskSessionRuntime.getHistoryStore(sessionId);
+  if (rawResult.assistantMessage) {
+    await historyStore.append(rawResult.assistantMessage);
+  }
+  const deferredUserMessages = drainDeferredPersistedUserMessages(sessionId);
+  for (const deferred of deferredUserMessages) {
+    await historyStore.append(deferred);
+  }
+}