helloloop 0.3.1 → 0.6.1

package/src/runner_execution_support.mjs

@@ -0,0 +1,155 @@
+import {
+  rememberEngineSelection,
+  resolveEngineSelection,
+} from "./engine_selection.mjs";
+import { nowIso } from "./common.mjs";
+import {
+  loadBacklog,
+  loadPolicy,
+  loadProjectConfig,
+  loadRepoStateText,
+  loadVerifyCommands,
+  saveBacklog,
+} from "./config.mjs";
+import { getTask, selectNextTask, unresolvedDependencies, updateTask } from "./backlog.mjs";
+import { makeRunDir } from "./runner_status.mjs";
+import { resolveRuntimeRecoveryPolicy } from "./runtime_recovery.mjs";
+
+function resolveTask(backlog, options) {
+  if (options.taskId) {
+    const task = getTask(backlog, options.taskId);
+    if (!task) {
+      throw new Error(`未找到任务：${options.taskId}`);
+    }
+    return task;
+  }
+  return selectNextTask(backlog, options);
+}
+
+export async function resolveExecutionSetup(context, options = {}) {
+  const policy = loadPolicy(context);
+  const projectConfig = loadProjectConfig(context);
+  const backlog = loadBacklog(context);
+  const task = resolveTask(backlog, options);
+  if (!task) {
+    return {
+      idleResult: { ok: true, kind: "idle", task: null },
+    };
+  }
+
+  const unresolved = unresolvedDependencies(backlog, task);
+  if (unresolved.length) {
+    throw new Error(`任务 ${task.id} 仍有未完成依赖：${unresolved.join(", ")}`);
+  }
+
+  const verifyCommands = Array.isArray(task.verify) && task.verify.length
+    ? task.verify
+    : loadVerifyCommands(context);
+  const maxAttemptsPerStrategy = Math.max(1, Number(options.maxAttempts || policy.maxTaskAttempts || 1));
+  const configuredStrategies = Math.max(1, Number(options.maxStrategies || policy.maxTaskStrategies || 1));
+  const engineResolution = options.engineResolution?.ok
+    ? options.engineResolution
+    : await resolveEngineSelection({
+      context,
+      policy,
+      options,
+      interactive: !options.yes,
+    });
+
+  return {
+    context,
+    options,
+    policy,
+    backlog,
+    projectConfig,
+    repoStateText: loadRepoStateText(context),
+    task,
+    verifyCommands,
+    runDir: makeRunDir(context, task.id),
+    requiredDocs: [...(projectConfig.requiredDocs || []), ...(options.requiredDocs || [])],
+    constraints: [...(projectConfig.constraints || []), ...(options.constraints || [])],
+    maxAttemptsPerStrategy,
+    maxStrategies: policy.stopOnFailure ? 1 : configuredStrategies,
+    engineResolution,
+  };
+}
+
+function updateTaskAndBuildResult(execution, status, result) {
+  updateTask(execution.backlog, execution.task.id, {
+    status,
+    finishedAt: nowIso(),
+    lastFailure: result.ok ? "" : (result.summary || ""),
+    attempts: result.attempts,
+  });
+  saveBacklog(execution.context, execution.backlog);
+  return result;
+}
+
+export function buildFailureResult(execution, kind, summary, attempts, engineResolution) {
+  return updateTaskAndBuildResult(execution, "failed", {
+    ok: false,
+    kind,
+    task: execution.task,
+    runDir: execution.runDir,
+    summary,
+    attempts,
+    engineResolution,
+  });
+}
+
+export function buildBlockedResult(execution, summary, attempts, engineResolution) {
+  return updateTaskAndBuildResult(execution, "blocked", {
+    ok: false,
+    kind: "task-blocked",
+    task: execution.task,
+    runDir: execution.runDir,
+    summary,
+    attempts,
+    engineResolution,
+  });
+}
+
+export function buildDoneResult(execution, finalMessage, attempts, engineResolution) {
+  return updateTaskAndBuildResult(execution, "done", {
+    ok: true,
+    kind: "done",
+    task: execution.task,
+    runDir: execution.runDir,
+    finalMessage,
+    attempts,
+    engineResolution,
+  });
+}
+
+export async function maybeSwitchEngine(execution, engineResolution, previousFailure, phaseLabel) {
+  const recoveryPolicy = resolveRuntimeRecoveryPolicy(execution.policy);
+  if (!recoveryPolicy.allowEngineSwitch) {
+    return null;
+  }
+  return null;
+}
+
+export function recordFailure(failureHistory, strategyIndex, attemptIndex, kind, summary) {
+  failureHistory.push({
+    strategyIndex,
+    attemptIndex,
+    kind,
+    summary,
+  });
+}
+
+export function buildAttemptState(runDir, strategyIndex, attemptIndex, makeAttemptDir) {
+  return {
+    strategyIndex,
+    attemptIndex,
+    attemptDir: makeAttemptDir(runDir, strategyIndex, attemptIndex),
+  };
+}
+
+export function bumpFailureForNextStrategy(previousFailure, maxAttemptsPerStrategy) {
+  return [
+    previousFailure,
+    "",
+    `上一种策略已连续失败 ${maxAttemptsPerStrategy} 次。下一轮必须明确更换实现或排查思路，不能重复原路径。`,
+  ].join("\n").trim();
+}

package/src/runner_loop.mjs

@@ -0,0 +1,106 @@
+import { selectNextTask, summarizeBacklog } from "./backlog.mjs";
+import { loadBacklog, loadPolicy } from "./config.mjs";
+import { reanalyzeCurrentWorkspace } from "./analyzer.mjs";
+import { runOnce } from "./runner_once.mjs";
+
+function shouldRunMainlineReanalysis(options, summary, reanalysisPasses, maxReanalysisPasses) {
+  return Boolean(options.fullAutoMainline)
+    && summary.pending === 0
+    && summary.inProgress === 0
+    && summary.failed === 0
+    && summary.blocked === 0
+    && reanalysisPasses < maxReanalysisPasses;
+}
+
+function buildMainlineReopenedResult(nextTask, engineResolution) {
+  return {
+    ok: true,
+    kind: "mainline-reopened",
+    task: null,
+    summary: [
+      "主线终态复核发现仍有剩余工作，已自动重建 backlog 并继续推进。",
+      `下一任务：${nextTask.title}`,
+    ].join("\n"),
+    engineResolution,
+  };
+}
+
+function buildMainlineCompleteResult(engineResolution) {
+  return {
+    ok: true,
+    kind: "mainline-complete",
+    task: null,
+    summary: "主线终态复核通过：开发文档目标已闭合，没有发现新的剩余任务。",
+    engineResolution,
+  };
+}
+
+function buildMainlineFailureResult(continuation, engineResolution) {
+  return {
+    ok: false,
+    kind: "mainline-reanalysis-failed",
+    task: null,
+    summary: continuation.summary || "主线终态复核失败。",
+    engineResolution,
+  };
+}
+
+export async function runLoop(context, options = {}) {
+  const policy = loadPolicy(context);
+  const explicitMaxTasks = Number(options.maxTasks);
+  const maxTasks = Number.isFinite(explicitMaxTasks) && explicitMaxTasks > 0
+    ? explicitMaxTasks
+    : (options.fullAutoMainline ? Number.POSITIVE_INFINITY : Math.max(1, Number(policy.maxLoopTasks || 1)));
+  const maxReanalysisPasses = Math.max(0, Number(options.maxReanalysisPasses || policy.maxReanalysisPasses || 0));
+  const results = [];
+  let engineResolution = options.engineResolution || null;
+  let completedTasks = 0;
+  let reanalysisPasses = 0;
+
+  while (completedTasks < maxTasks) {
+    const result = await runOnce(context, { ...options, engineResolution });
+    results.push(result);
+    if (result.engineResolution?.ok) {
+      engineResolution = result.engineResolution;
+    }
+    if (options.dryRun || !result.ok || !result.task) {
+      break;
+    }
+
+    completedTasks += 1;
+    const backlog = loadBacklog(context);
+    if (selectNextTask(backlog, options)) {
+      continue;
+    }
+
+    const summary = summarizeBacklog(backlog);
+    if (!shouldRunMainlineReanalysis(options, summary, reanalysisPasses, maxReanalysisPasses)) {
+      break;
+    }
+
+    reanalysisPasses += 1;
+    const continuation = await reanalyzeCurrentWorkspace(context, {
+      ...options,
+      engineResolution,
+      yes: true,
+    });
+    if (continuation.engineResolution?.ok) {
+      engineResolution = continuation.engineResolution;
+    }
+    if (!continuation.ok) {
+      results.push(buildMainlineFailureResult(continuation, engineResolution));
+      break;
+    }
+
+    const continuedNextTask = selectNextTask(loadBacklog(context), options);
+    if (continuedNextTask) {
+      results.push(buildMainlineReopenedResult(continuedNextTask, engineResolution));
+      continue;
+    }
+
+    results.push(buildMainlineCompleteResult(engineResolution));
+    break;
+  }
+
+  return results;
+}

package/src/runner_once.mjs

@@ -0,0 +1,29 @@
+import { selectNextTask, summarizeBacklog } from "./backlog.mjs";
+import { loadBacklog, writeStateMarkdown, writeStatus } from "./config.mjs";
+import { executeSingleTask } from "./runner_execute_task.mjs";
+import { renderStatusMarkdown } from "./runner_status.mjs";
+
+export async function runOnce(context, options = {}) {
+  const result = await executeSingleTask(context, options);
+  const backlog = loadBacklog(context);
+  const summary = summarizeBacklog(backlog);
+  const nextTask = selectNextTask(backlog, options);
+
+  writeStatus(context, {
+    ok: result.ok,
+    stage: result.kind,
+    taskId: result.task?.id || null,
+    taskTitle: result.task?.title || "",
+    runDir: result.runDir || "",
+    summary,
+    message: result.summary || result.finalMessage || "",
+  });
+  writeStateMarkdown(context, renderStatusMarkdown(context, {
+    summary,
+    currentTask: result.task,
+    lastResult: result.ok ? "本轮成功" : (result.summary || result.kind),
+    nextTask,
+  }));
+
+  return result;
+}

package/src/runner_status.mjs

@@ -0,0 +1,104 @@
+import path from "node:path";
+
+import { sanitizeId, tailText, timestampForFile } from "./common.mjs";
+import { renderTaskSummary, selectNextTask, summarizeBacklog } from "./backlog.mjs";
+import { loadBacklog } from "./config.mjs";
+
+export function makeRunDir(context, taskId) {
+  return path.join(context.runsDir, `${timestampForFile()}-${sanitizeId(taskId)}`);
+}
+
+export function makeAttemptDir(runDir, strategyIndex, attemptIndex) {
+  return path.join(
+    runDir,
+    `strategy-${String(strategyIndex).padStart(2, "0")}-attempt-${String(attemptIndex).padStart(2, "0")}`,
+  );
+}
+
+export function isHardStopFailure(kind, summary) {
+  const normalized = String(summary || "").toLowerCase();
+  if (!normalized) {
+    return false;
+  }
+  if (kind === "engine" && normalized.includes("enoent")) {
+    return true;
+  }
+
+  return [
+    "command not found",
+    "is not recognized",
+    "无法将",
+    "找不到路径",
+    "no such file or directory",
+    "permission denied",
+    "access is denied",
+  ].some((signal) => normalized.includes(signal));
+}
+
+export function buildFailureSummary(kind, payload) {
+  if (kind !== "engine") {
+    return payload.summary;
+  }
+
+  return [
+    `${payload.displayName} 执行失败，退出码：${payload.code}`,
+    payload.recoverySummary || "",
+    "",
+    "stdout 尾部：",
+    tailText(payload.stdout, 60),
+    "",
+    "stderr 尾部：",
+    tailText(payload.stderr, 60),
+  ].join("\n").trim();
+}
+
+export function buildExhaustedSummary({
+  failureHistory,
+  maxStrategies,
+  maxAttemptsPerStrategy,
+}) {
+  const lastFailure = failureHistory.at(-1)?.summary || "未知失败。";
+  return [
+    `已按 Ralph Loop 执行 ${maxStrategies} 轮策略、每轮最多 ${maxAttemptsPerStrategy} 次重试，当前任务仍未收敛。`,
+    "",
+    "最后一次失败信息：",
+    lastFailure,
+  ].join("\n").trim();
+}
+
+export function renderStatusMarkdown(context, { summary, currentTask, lastResult, nextTask }) {
+  return [
+    "## 当前状态",
+    `- backlog 文件：${context.backlogFile.replaceAll("\\", "/")}`,
+    `- 总任务数：${summary.total}`,
+    `- 已完成：${summary.done}`,
+    `- 待处理：${summary.pending}`,
+    `- 进行中：${summary.inProgress}`,
+    `- 失败：${summary.failed}`,
+    `- 阻塞：${summary.blocked}`,
+    `- 当前任务：${currentTask ? currentTask.title : "无"}`,
+    `- 最近结果：${lastResult || "暂无"}`,
+    `- 下一建议：${nextTask ? nextTask.title : "暂无可执行任务"}`,
+  ].join("\n");
+}
+
+export function renderStatusText(context, options = {}) {
+  const backlog = loadBacklog(context);
+  const summary = summarizeBacklog(backlog);
+  const nextTask = selectNextTask(backlog, options);
+
+  return [
+    "HelloLoop 状态",
+    "============",
+    `仓库：${context.repoRoot}`,
+    `总任务：${summary.total}`,
+    `已完成：${summary.done}`,
+    `待处理：${summary.pending}`,
+    `进行中：${summary.inProgress}`,
+    `失败：${summary.failed}`,
+    `阻塞：${summary.blocked}`,
+    "",
+    nextTask ? "下一任务：" : "下一任务：无",
+    nextTask ? renderTaskSummary(nextTask) : "",
+  ].filter(Boolean).join("\n");
+}

package/src/runtime_recovery.mjs

@@ -0,0 +1,301 @@
+import { getEngineDisplayName } from "./engine_metadata.mjs";
+import { tailText } from "./common.mjs";
+
+const defaultRuntimeRecoveryPolicy = {
+  enabled: true,
+  allowEngineSwitch: false,
+  heartbeatIntervalSeconds: 60,
+  stallWarningSeconds: 900,
+  maxIdleSeconds: 2700,
+  killGraceSeconds: 10,
+  maxPhaseRecoveries: 4,
+  retryDelaysSeconds: [120, 300, 900, 1800],
+  retryOnUnknownFailure: true,
+  maxUnknownRecoveries: 1,
+};
+
+const HARD_STOP_MATCHERS = [
+  {
+    code: "invalid_request",
+    reason: "当前错误更像请求、参数、协议或输出格式问题，继续原样自动重试大概率无效。",
+    patterns: [
+      " 400 ",
+      "400 bad request",
+      "bad request",
+      "invalid request",
+      "invalid argument",
+      "invalid_argument",
+      "failed to parse",
+      "parse error",
+      "malformed",
+      "schema validation",
+      "json schema",
+      "unexpected argument",
+      "unknown option",
+    ],
+  },
+  {
+    code: "auth",
+    reason: "当前错误更像登录、鉴权、订阅或权限问题，需要先修复环境。",
+    patterns: [
+      "401",
+      "403",
+      "unauthorized",
+      "forbidden",
+      "not authenticated",
+      "authentication",
+      "login",
+      "sign in",
+      "api key",
+      "token",
+      "subscription",
+      "insufficient permissions",
+    ],
+  },
+  {
+    code: "environment",
+    reason: "当前错误更像本地 CLI 缺失、权限不足或文件系统问题，继续自动重试没有意义。",
+    patterns: [
+      "command not found",
+      "is not recognized",
+      "enoent",
+      "no such file or directory",
+      "permission denied",
+      "access is denied",
+    ],
+  },
+];
+
+const RECOVERABLE_MATCHERS = [
+  {
+    code: "rate_limit",
+    reason: "当前引擎可能遇到配额、限流或临时容量不足。",
+    patterns: [
+      "429",
+      "rate limit",
+      "too many requests",
+      "quota",
+      "credit",
+      "usage limit",
+      "capacity",
+      "overloaded",
+      "insufficient balance",
+      "try again later",
+    ],
+  },
+  {
+    code: "server",
+    reason: "当前引擎可能遇到临时服务端错误。",
+    patterns: [
+      "500",
+      "501",
+      "502",
+      "503",
+      "504",
+      "internal server error",
+      "bad gateway",
+      "service unavailable",
+      "gateway timeout",
+      "server error",
+      "upstream",
+      "temporarily unavailable",
+    ],
+  },
+  {
+    code: "network",
+    reason: "当前引擎可能遇到临时网络、连接或结果流中断。",
+    patterns: [
+      "network error",
+      "fetch failed",
+      "econnreset",
+      "etimedout",
+      "timed out",
+      "timeout",
+      "connection reset",
+      "connection aborted",
+      "connection closed",
+      "stream closed",
+      "socket hang up",
+      "transport error",
+      "broken pipe",
+      "http2",
+    ],
+  },
+];
+
+function normalizeSeconds(value, fallback) {
+  const numberValue = Number(value);
+  if (!Number.isFinite(numberValue) || numberValue < 0) {
+    return fallback;
+  }
+  return numberValue;
+}
+
+function normalizeSecondsList(value, fallback) {
+  if (!Array.isArray(value) || !value.length) {
+    return fallback;
+  }
+  const normalized = value
+    .map((item) => normalizeSeconds(item, -1))
+    .filter((item) => item >= 0);
+  return normalized.length ? normalized : fallback;
+}
+
+function normalizeText(value) {
+  return String(value || "").toLowerCase();
+}
+
+function hasMatcher(normalizedText, matcher) {
+  return matcher.patterns.some((pattern) => normalizedText.includes(String(pattern).toLowerCase()));
+}
+
+export function resolveRuntimeRecoveryPolicy(policy = {}) {
+  const configured = policy?.runtimeRecovery || {};
+  return {
+    enabled: configured.enabled !== false,
+    allowEngineSwitch: configured.allowEngineSwitch === true,
+    heartbeatIntervalSeconds: normalizeSeconds(
+      configured.heartbeatIntervalSeconds,
+      defaultRuntimeRecoveryPolicy.heartbeatIntervalSeconds,
+    ),
+    stallWarningSeconds: normalizeSeconds(
+      configured.stallWarningSeconds,
+      defaultRuntimeRecoveryPolicy.stallWarningSeconds,
+    ),
+    maxIdleSeconds: normalizeSeconds(
+      configured.maxIdleSeconds,
+      defaultRuntimeRecoveryPolicy.maxIdleSeconds,
+    ),
+    killGraceSeconds: normalizeSeconds(
+      configured.killGraceSeconds,
+      defaultRuntimeRecoveryPolicy.killGraceSeconds,
+    ),
+    maxPhaseRecoveries: Math.max(
+      0,
+      Math.trunc(normalizeSeconds(configured.maxPhaseRecoveries, defaultRuntimeRecoveryPolicy.maxPhaseRecoveries)),
+    ),
+    retryDelaysSeconds: normalizeSecondsList(
+      configured.retryDelaysSeconds,
+      defaultRuntimeRecoveryPolicy.retryDelaysSeconds,
+    ),
+    retryOnUnknownFailure: configured.retryOnUnknownFailure !== false,
+    maxUnknownRecoveries: Math.max(
+      0,
+      Math.trunc(normalizeSeconds(configured.maxUnknownRecoveries, defaultRuntimeRecoveryPolicy.maxUnknownRecoveries)),
+    ),
+  };
+}
+
+export function selectRuntimeRecoveryDelayMs(recoveryPolicy, nextRecoveryIndex) {
+  const delays = Array.isArray(recoveryPolicy?.retryDelaysSeconds) && recoveryPolicy.retryDelaysSeconds.length
+    ? recoveryPolicy.retryDelaysSeconds
+    : defaultRuntimeRecoveryPolicy.retryDelaysSeconds;
+  const offset = Math.max(0, Number(nextRecoveryIndex || 1) - 1);
+  const seconds = delays[Math.min(offset, delays.length - 1)] || 0;
+  return Math.max(0, seconds) * 1000;
+}
+
+export function classifyRuntimeRecoveryFailure({
+  result = {},
+  recoveryPolicy = defaultRuntimeRecoveryPolicy,
+  recoveryCount = 0,
+} = {}) {
+  const normalized = normalizeText([
+    result.stderr,
+    result.stdout,
+    result.finalMessage,
+    result.watchdogReason,
+  ].filter(Boolean).join("\n"));
+
+  if (result.watchdogTriggered || result.idleTimeout) {
+    return {
+      recoverable: true,
+      code: "watchdog_idle",
+      reason: "当前进程长时间没有可见进展，HelloLoop 已按看门狗策略终止并准备同引擎恢复。",
+    };
+  }
+
+  for (const matcher of HARD_STOP_MATCHERS) {
+    if (hasMatcher(normalized, matcher)) {
+      return {
+        recoverable: false,
+        code: matcher.code,
+        reason: matcher.reason,
+      };
+    }
+  }
+
+  for (const matcher of RECOVERABLE_MATCHERS) {
+    if (hasMatcher(normalized, matcher)) {
+      return {
+        recoverable: true,
+        code: matcher.code,
+        reason: matcher.reason,
+      };
+    }
+  }
+
+  const emptyFailure = !normalized.trim() && !result.ok;
+  if (emptyFailure) {
+    return {
+      recoverable: recoveryCount < (recoveryPolicy.maxUnknownRecoveries || 0),
+      code: "empty_failure",
+      reason: "当前失败没有返回可判定的错误文本，HelloLoop 将按无人值守策略先尝试一次同引擎恢复。",
+    };
+  }
+
+  if (recoveryPolicy.retryOnUnknownFailure && recoveryCount < (recoveryPolicy.maxUnknownRecoveries || 0)) {
+    return {
+      recoverable: true,
+      code: "unknown_failure",
+      reason: "当前错误类型无法稳定归类，HelloLoop 将按无人值守策略先尝试一次同引擎恢复。",
+    };
+  }
+
+  return {
+    recoverable: false,
+    code: "unknown_failure",
+    reason: "当前错误无法判断为可安全自动恢复，已停止本轮自动恢复。",
+  };
+}
+
+export function buildRuntimeRecoveryPrompt({
+  basePrompt,
+  engine,
+  phaseLabel,
+  failure,
+  result = {},
+  nextRecoveryIndex,
+  maxRecoveries,
+}) {
+  return [
+    basePrompt,
+    "",
+    "## HelloLoop 自动恢复上下文",
+    `- 执行引擎：${getEngineDisplayName(engine)}`,
+    `- 当前阶段：${phaseLabel}`,
+    `- 自动恢复序号：${nextRecoveryIndex}/${maxRecoveries}`,
+    `- 恢复原因：${failure?.reason || "当前引擎在上一轮执行中断，需要在同一主线下继续恢复。"}`,
+    "",
+    "你必须把当前仓库视为唯一事实源，直接复用已经完成的修改、进度和中间结果。",
+    "不要从头重做，不要另起一套实现，不要等待用户，不要把“下一步建议”当成交付。",
+    "先快速检查仓库当前状态与最近失败点，然后从中断位置继续完成本轮任务。",
+    "",
+    "最近失败片段：",
+    `- stdout 尾部：${tailText(result.stdout, 10) || "无"}`,
+    `- stderr 尾部：${tailText(result.stderr, 10) || "无"}`,
+  ].join("\n");
+}
+
+export function renderRuntimeRecoverySummary(recoveryHistory = []) {
+  if (!Array.isArray(recoveryHistory) || !recoveryHistory.length) {
+    return "";
+  }
+
+  return [
+    `HelloLoop 已按无人值守策略进行 ${recoveryHistory.length} 次同引擎自动恢复。`,
+    ...recoveryHistory.map((item) => (
+      `- 第 ${item.recoveryIndex} 次恢复：${item.reason}（等待 ${item.delaySeconds} 秒）`
+    )),
+  ].join("\n");
+}