helloloop 0.3.1 → 0.7.0

package/src/runner_execution_support.mjs

@@ -0,0 +1,146 @@
+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";
+
+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 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,302 @@
+import { getEngineDisplayName } from "./engine_metadata.mjs";
+import { tailText } from "./common.mjs";
+
+const defaultRuntimeRecoveryPolicy = {
+  enabled: true,
+  heartbeatIntervalSeconds: 60,
+  stallWarningSeconds: 900,
+  maxIdleSeconds: 2700,
+  killGraceSeconds: 10,
+  healthProbeTimeoutSeconds: 120,
+  hardRetryDelaysSeconds: [900, 900, 900, 900, 900],
+  softRetryDelaysSeconds: [900, 900, 900, 900, 900, 1800, 1800, 3600, 5400, 7200, 9000, 10800],
+};
+
+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: "billing",
+    reason: "当前错误更像额度、余额、支付或账单问题，短时间内通常不会自行消失。",
+    patterns: [
+      "payment required",
+      "billing",
+      "insufficient balance",
+      "credit",
+      "quota exceeded",
+      "hard limit",
+      "balance",
+    ],
+  },
+  {
+    code: "environment",
+    reason: "当前错误更像本地 CLI 缺失、权限不足或文件系统问题，需要人工修复环境。",
+    patterns: [
+      "command not found",
+      "is not recognized",
+      "enoent",
+      "no such file or directory",
+      "permission denied",
+      "access is denied",
+    ],
+  },
+];
+
+const SOFT_STOP_MATCHERS = [
+  {
+    code: "rate_limit",
+    reason: "当前引擎可能遇到配额、限流或临时容量不足。",
+    patterns: [
+      "429",
+      "rate limit",
+      "too many requests",
+      "quota",
+      "usage limit",
+      "capacity",
+      "overloaded",
+      "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,
+    heartbeatIntervalSeconds: normalizeSeconds(
+      configured.heartbeatIntervalSeconds,
+      defaultRuntimeRecoveryPolicy.heartbeatIntervalSeconds,
+    ),
+    stallWarningSeconds: normalizeSeconds(
+      configured.stallWarningSeconds,
+      defaultRuntimeRecoveryPolicy.stallWarningSeconds,
+    ),
+    maxIdleSeconds: normalizeSeconds(
+      configured.maxIdleSeconds,
+      defaultRuntimeRecoveryPolicy.maxIdleSeconds,
+    ),
+    killGraceSeconds: normalizeSeconds(
+      configured.killGraceSeconds,
+      defaultRuntimeRecoveryPolicy.killGraceSeconds,
+    ),
+    healthProbeTimeoutSeconds: normalizeSeconds(
+      configured.healthProbeTimeoutSeconds,
+      defaultRuntimeRecoveryPolicy.healthProbeTimeoutSeconds,
+    ),
+    hardRetryDelaysSeconds: normalizeSecondsList(
+      configured.hardRetryDelaysSeconds,
+      defaultRuntimeRecoveryPolicy.hardRetryDelaysSeconds,
+    ),
+    softRetryDelaysSeconds: normalizeSecondsList(
+      configured.softRetryDelaysSeconds,
+      defaultRuntimeRecoveryPolicy.softRetryDelaysSeconds,
+    ),
+  };
+}
+
+export function getRuntimeRecoverySchedule(recoveryPolicy, family = "soft") {
+  return family === "hard"
+    ? recoveryPolicy.hardRetryDelaysSeconds
+    : recoveryPolicy.softRetryDelaysSeconds;
+}
+
+export function selectRuntimeRecoveryDelayMs(recoveryPolicy, family, nextRecoveryIndex) {
+  const delays = getRuntimeRecoverySchedule(recoveryPolicy, family);
+  const offset = Math.max(0, Number(nextRecoveryIndex || 1) - 1);
+  const seconds = delays[offset] ?? null;
+  return seconds == null ? -1 : Math.max(0, seconds) * 1000;
+}
+
+export function classifyRuntimeRecoveryFailure({ result = {} } = {}) {
+  const normalized = normalizeText([
+    result.stderr,
+    result.stdout,
+    result.finalMessage,
+    result.watchdogReason,
+  ].filter(Boolean).join("\n"));
+
+  if (result.watchdogTriggered || result.idleTimeout) {
+    return {
+      code: "watchdog_idle",
+      family: "soft",
+      reason: "当前进程长时间没有可见进展，HelloLoop 将按软阻塞策略继续探测并恢复。",
+    };
+  }
+
+  for (const matcher of HARD_STOP_MATCHERS) {
+    if (hasMatcher(normalized, matcher)) {
+      return {
+        code: matcher.code,
+        family: "hard",
+        reason: matcher.reason,
+      };
+    }
+  }
+
+  for (const matcher of SOFT_STOP_MATCHERS) {
+    if (hasMatcher(normalized, matcher)) {
+      return {
+        code: matcher.code,
+        family: "soft",
+        reason: matcher.reason,
+      };
+    }
+  }
+
+  return {
+    code: "unknown_failure",
+    family: "soft",
+    reason: "当前错误类型无法稳定归类，HelloLoop 将按软阻塞策略持续探测并恢复。",
+  };
+}
+
+export function buildEngineHealthProbePrompt(engine) {
+  return [
+    "HELLOLOOP_ENGINE_HEALTH_PROBE",
+    `当前只做 ${getEngineDisplayName(engine)} 引擎健康探测。`,
+    "禁止修改仓库、禁止执行开发任务、禁止输出解释。",
+    "只需确认自己当前能正常接收请求并返回简短结果。",
+    "若当前可用，请直接回复：HELLOLOOP_ENGINE_OK",
+  ].join("\n");
+}
+
+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 = [], failure = null) {
+  if (!Array.isArray(recoveryHistory) || !recoveryHistory.length) {
+    return "";
+  }
+
+  return [
+    `HelloLoop 已按${failure?.family === "hard" ? "硬阻塞" : "软阻塞"}策略进行 ${recoveryHistory.length} 次自动探测/恢复。`,
+    ...recoveryHistory.map((item) => (
+      `- 第 ${item.recoveryIndex} 次：等待 ${item.delaySeconds} 秒；探测 ${item.probeStatus || "unknown"}；任务 ${item.taskStatus || "unknown"}`
+    )),
+    "自动恢复额度已用尽，当前已暂停等待用户介入。",
+  ].join("\n");
+}

package/src/shell_invocation.mjs

@@ -223,3 +223,19 @@ export function resolveCodexInvocation(options = {}) {
     toolDisplayName: "Codex",
   });
 }
+
+export function resolveClaudeInvocation(options = {}) {
+  return resolveCliInvocation({
+    ...options,
+    commandName: "claude",
+    toolDisplayName: "Claude",
+  });
+}
+
+export function resolveGeminiInvocation(options = {}) {
+  return resolveCliInvocation({
+    ...options,
+    commandName: "gemini",
+    toolDisplayName: "Gemini",
+  });
+}