helloagents 3.0.22 → 3.0.25

package/scripts/ralph-loop.mjs

@@ -8,6 +8,7 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { execSync } from 'node:child_process';
 import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
 import { clearVerifyEvidence, detectCommands, hasUnsafeVerifyCommand, writeVerifyEvidence } from './verify-state.mjs';
 import {
   getRuntimeEvidencePath,
@@ -34,10 +35,6 @@ function readSettings() {
 // ── Circuit Breaker (consecutive failure tracking) ───────────────────
 const BREAKER_FILE_NAME = 'loop-breaker.json';
 
-function getBreakerPath(cwd, options = {}) {
-  return getRuntimeEvidencePath(cwd, BREAKER_FILE_NAME, options);
-}
-
 function readBreaker(cwd, options = {}) {
   return readRuntimeEvidence(cwd, BREAKER_FILE_NAME, options)
     || { consecutive_failures: 0, last_failure: null };
@@ -92,111 +89,109 @@ function runVerify(commands, cwd) {
   return failures;
 }
 
-// ── Result Handlers ──────────────────────────────────────────────────
-
-function handleSuccess(cwd, isSubagent, options = {}) {
-  resetBreaker(cwd, options);
-  writeVerifyEvidence(cwd, {
-    commands: detectCommands(cwd),
-    fastOnly: isSubagent,
-    source: isSubagent ? 'subagent' : 'stop',
-  }, options);
-
-  if (isSubagent) {
-    process.stdout.write(JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: HOOK_EVENT,
-        additionalContext: '子代理快速验证通过（lint/typecheck）。请控制器审查变更后继续。',
-      },
-      suppressOutput: true,
-    }));
-    return;
-  }
-
-  // Progress detection: warn if claiming done but no git changes
-  if (!hasGitChanges(cwd)) {
-    process.stdout.write(JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: HOOK_EVENT,
-        additionalContext: '⚠️ [Ralph Loop] 验证通过但未检测到代码变更（git diff 为空）。如果确实完成了编码任务，请确认变更已保存。',
-      },
-      suppressOutput: true,
-    }));
-  } else {
-    process.stdout.write(JSON.stringify({ suppressOutput: true }));
-  }
-}
-
-function handleFailure(failures, cwd, options = {}) {
-  clearVerifyEvidence(cwd, options);
-  const breaker = readBreaker(cwd, options);
-  breaker.consecutive_failures += 1;
-  breaker.last_failure = new Date().toISOString();
-  writeBreaker(cwd, breaker, options);
-
-  const breakerWarning = breaker.consecutive_failures >= 3
-    ? `\n\n⚠️ [断路器] 已连续 ${breaker.consecutive_failures} 次验证失败。当前修复思路可能有误，先处理：\n  1. 重新分析根因，不要继续在同一方向上硬修\n  2. 检查是否存在架构层面的问题\n  3. 考虑回退到上一个正常状态重新开始`
-    : '';
-
-  const details = failures.map(f => `\u2717 ${f.cmd}\n${f.output}`).join('\n\n');
-  process.stdout.write(JSON.stringify({
-    decision: 'block',
-    reason: `[Ralph Loop] 验证失败：\n\n${details}\n\n请先修复以上问题，再报告完成。${breakerWarning}`,
-    suppressOutput: true,
-  }));
-}
-
 /** Filter commands to fast checks only for subagent mode. Returns null if no fast commands found. */
 function filterSubagentCommands(commands) {
   const fast = commands.filter(cmd =>
     /lint|typecheck|type-check|ruff check|mypy|eslint|tsc/.test(cmd)
   );
   if (fast.length === 0) {
-    process.stdout.write(JSON.stringify({
+    return {
       hookSpecificOutput: {
         hookEventName: HOOK_EVENT,
         additionalContext: '子代理完成。未找到快速验证命令，请控制器手动审查变更。',
       },
       suppressOutput: true,
-    }));
-    return null;
+    };
   }
-  return fast;
+  return { commands: fast };
 }
 
-// ── Main ──────────────────────────────────────────────────────────────
-async function main() {
+export function evaluateRalphLoop(data = {}, runtime = {}) {
   const settings = readSettings();
   if (settings.ralph_loop_enabled === false) {
-    process.stdout.write(JSON.stringify({ suppressOutput: true }));
-    return;
+    return { suppressOutput: true };
   }
 
-  let data = {};
-  try { data = JSON.parse(readFileSync(0, 'utf-8')); } catch {}
   const cwd = data.cwd || process.cwd();
   const runtimeOptions = { payload: data };
+  const isSubagent = runtime.isSubagent ?? IS_SUBAGENT;
+  const hookEventName = runtime.hookEventName || HOOK_EVENT;
 
   let commands = detectCommands(cwd);
   if (!commands?.length) {
-    process.stdout.write(JSON.stringify({ suppressOutput: true }));
-    return;
+    return { suppressOutput: true };
   }
 
-  if (IS_SUBAGENT) {
-    commands = filterSubagentCommands(commands);
-    if (!commands) return;
+  if (isSubagent) {
+    const filtered = filterSubagentCommands(commands);
+    if (!filtered?.commands) return filtered || { suppressOutput: true };
+    commands = filtered.commands;
   }
 
   const failures = runVerify(commands, cwd);
-  if (failures.length === 0) handleSuccess(cwd, IS_SUBAGENT, runtimeOptions);
-  else handleFailure(failures, cwd, runtimeOptions);
-}
+  if (failures.length === 0) {
+    resetBreaker(cwd, runtimeOptions);
+    writeVerifyEvidence(cwd, {
+      commands: detectCommands(cwd),
+      fastOnly: isSubagent,
+      source: isSubagent ? 'subagent' : 'stop',
+    }, runtimeOptions);
+
+    if (isSubagent) {
+      return {
+        hookSpecificOutput: {
+          hookEventName,
+          additionalContext: '子代理快速验证通过（lint/typecheck）。请控制器审查变更后继续。',
+        },
+        suppressOutput: true,
+      };
+    }
 
-main().catch((error) => {
-  process.stdout.write(JSON.stringify({
+    if (!hasGitChanges(cwd)) {
+      return {
+        hookSpecificOutput: {
+          hookEventName,
+          additionalContext: '⚠️ [Ralph Loop] 验证通过但未检测到代码变更（git diff 为空）。如果确实完成了编码任务，请确认变更已保存。',
+        },
+        suppressOutput: true,
+      };
+    }
+
+    return { suppressOutput: true };
+  }
+
+  clearVerifyEvidence(cwd, runtimeOptions);
+  const breaker = readBreaker(cwd, runtimeOptions);
+  breaker.consecutive_failures += 1;
+  breaker.last_failure = new Date().toISOString();
+  writeBreaker(cwd, breaker, runtimeOptions);
+
+  const breakerWarning = breaker.consecutive_failures >= 3
+    ? `\n\n⚠️ [断路器] 已连续 ${breaker.consecutive_failures} 次验证失败。当前修复思路可能有误，先处理：\n  1. 重新分析根因，不要继续在同一方向上硬修\n  2. 检查是否存在架构层面的问题\n  3. 考虑回退到上一个正常状态重新开始`
+    : '';
+  const details = failures.map(f => `\u2717 ${f.cmd}\n${f.output}`).join('\n\n');
+  return {
     decision: 'block',
-    reason: `[Ralph Loop] 验证脚本执行异常，已暂停完成通知。\n原因：${error?.message || error}`,
+    reason: `[Ralph Loop] 验证失败：\n\n${details}\n\n请先修复以上问题，再报告完成。${breakerWarning}`,
     suppressOutput: true,
-  }));
-});
+  };
+}
+
+// ── Main ──────────────────────────────────────────────────────────────
+function main() {
+  let data = {};
+  try { data = JSON.parse(readFileSync(0, 'utf-8')); } catch {}
+  process.stdout.write(JSON.stringify(evaluateRalphLoop(data)));
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  try {
+    main();
+  } catch (error) {
+    process.stdout.write(JSON.stringify({
+      decision: 'block',
+      reason: `[Ralph Loop] 验证脚本执行异常，已暂停完成通知。\n原因：${error?.message || error}`,
+      suppressOutput: true,
+    }));
+  }
+}

package/scripts/runtime-scope.mjs

@@ -18,6 +18,12 @@ export const DEFAULT_STATE_SESSION_TOKEN = 'default'
 export const USER_RUNTIME_DIR_NAME = 'runtime'
 export { cleanupUserRuntimeRoot, getUserRuntimeRoot, USER_RUNTIME_MAX_AGE_MS }
 
+const gitTopLevelCache = new Map()
+const gitBranchNameCache = new Map()
+const gitShortHeadCache = new Map()
+const workspaceNameCache = new Map()
+let userRuntimeCleanupDone = false
+
 function normalizePath(filePath = '') {
   return filePath ? normalize(resolve(filePath)) : ''
 }
@@ -35,6 +41,13 @@ function runGit(cwd, args = []) {
   }
 }
 
+function readCachedValue(cache, key, loader) {
+  if (cache.has(key)) return cache.get(key)
+  const value = loader()
+  cache.set(key, value)
+  return value
+}
+
 function getHomeDir(env = process.env) {
   return env.HOME || env.USERPROFILE || homedir()
 }
@@ -55,35 +68,46 @@ function samePath(left, right) {
 }
 
 function resolveGitTopLevel(cwd) {
-  const absolute = runGit(cwd, ['rev-parse', '--path-format=absolute', '--show-toplevel'])
-  if (absolute) return normalize(resolve(absolute))
+  const normalizedCwd = normalizePath(cwd || process.cwd())
+  return readCachedValue(gitTopLevelCache, normalizedCwd, () => {
+    const absolute = runGit(normalizedCwd, ['rev-parse', '--path-format=absolute', '--show-toplevel'])
+    if (absolute) return normalize(resolve(absolute))
 
-  const raw = runGit(cwd, ['rev-parse', '--show-toplevel'])
-  return raw ? normalize(resolve(cwd, raw)) : ''
+    const raw = runGit(normalizedCwd, ['rev-parse', '--show-toplevel'])
+    return raw ? normalize(resolve(normalizedCwd, raw)) : ''
+  })
 }
 
 function resolveGitBranchName(cwd) {
-  const branchName = runGit(cwd, ['rev-parse', '--abbrev-ref', 'HEAD'])
-  if (branchName && branchName !== 'HEAD') return branchName
+  const normalizedCwd = normalizePath(cwd || process.cwd())
+  return readCachedValue(gitBranchNameCache, normalizedCwd, () => {
+    const branchName = runGit(normalizedCwd, ['rev-parse', '--abbrev-ref', 'HEAD'])
+    if (branchName && branchName !== 'HEAD') return branchName
 
-  const symbolicName = runGit(cwd, ['symbolic-ref', '--quiet', '--short', 'HEAD'])
-  return symbolicName && symbolicName !== 'HEAD' ? symbolicName : ''
+    const symbolicName = runGit(normalizedCwd, ['symbolic-ref', '--quiet', '--short', 'HEAD'])
+    return symbolicName && symbolicName !== 'HEAD' ? symbolicName : ''
+  })
 }
 
 function resolveGitShortHead(cwd) {
-  return runGit(cwd, ['rev-parse', '--short', 'HEAD'])
+  const normalizedCwd = normalizePath(cwd || process.cwd())
+  return readCachedValue(gitShortHeadCache, normalizedCwd, () =>
+    runGit(normalizedCwd, ['rev-parse', '--short', 'HEAD']))
 }
 
 function resolveWorkspaceName(cwd) {
-  const branchName = resolveGitBranchName(cwd)
-  if (branchName) return sanitizeRuntimeSegment(branchName, 'workspace')
+  const normalizedCwd = normalizePath(cwd || process.cwd())
+  return readCachedValue(workspaceNameCache, normalizedCwd, () => {
+    const branchName = resolveGitBranchName(normalizedCwd)
+    if (branchName) return sanitizeRuntimeSegment(branchName, 'workspace')
 
-  if (resolveGitTopLevel(cwd)) {
-    const shortHead = sanitizeRuntimeSegment(resolveGitShortHead(cwd), '')
-    return shortHead ? `detached-${shortHead}` : 'detached'
-  }
+    if (resolveGitTopLevel(normalizedCwd)) {
+      const shortHead = sanitizeRuntimeSegment(resolveGitShortHead(normalizedCwd), '')
+      return shortHead ? `detached-${shortHead}` : 'detached'
+    }
 
-  return 'workspace'
+    return 'workspace'
+  })
 }
 
 export function sanitizeRuntimeSegment(value = '', fallback = '') {
@@ -245,6 +269,7 @@ export function writeActiveProjectSession(scope, { host = '', source = '', env =
     host,
     source,
     aliases,
+    ...(current.cleanupCheckedAt ? { cleanupCheckedAt: current.cleanupCheckedAt } : {}),
     updatedAt: new Date().toISOString(),
   })
   return activePath
@@ -323,7 +348,10 @@ function buildTransientRuntimeDir(cwd, options = {}) {
     .update(`${normalizedCwd.toLowerCase()}::${token}`)
     .digest('hex')
     .slice(0, 16)
-  cleanupUserRuntimeRoot()
+  if (!userRuntimeCleanupDone) {
+    cleanupUserRuntimeRoot()
+    userRuntimeCleanupDone = true
+  }
 
   return {
     cwd: normalizedCwd,

package/scripts/session-capsule.mjs

@@ -142,6 +142,7 @@ export function clearCapsuleSection(cwd, section, options = {}) {
 
   const capsule = readSessionCapsule(cwd, options)
   if (!Object.prototype.hasOwnProperty.call(capsule, section)) return false
+  if (capsule[section] == null) return false
   capsule[section] = null
   capsule[`${section}UpdatedAt`] = new Date().toISOString()
   writeSessionCapsule(cwd, capsule, options)

package/scripts/turn-state-cli.mjs

@@ -1,9 +1,31 @@
 #!/usr/bin/env node
 import { spawnSync } from 'node:child_process'
-import { dirname, join } from 'node:path'
+import { existsSync, realpathSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-const scriptPath = join(dirname(fileURLToPath(import.meta.url)), 'turn-state.mjs')
+function normalizePath(filePath = '') {
+  const resolved = resolve(filePath)
+  try {
+    return realpathSync(resolved)
+  } catch {
+    return resolved
+  }
+}
+
+function samePath(left, right) {
+  const a = normalizePath(left)
+  const b = normalizePath(right)
+  return process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b
+}
+
+const localScriptPath = join(dirname(fileURLToPath(import.meta.url)), 'turn-state.mjs')
+const runtimeScriptPath = join(homedir(), '.helloagents', 'helloagents', 'scripts', 'turn-state.mjs')
+const scriptPath = existsSync(runtimeScriptPath) && !samePath(runtimeScriptPath, localScriptPath)
+  ? runtimeScriptPath
+  : localScriptPath
+
 const result = spawnSync(process.execPath, [scriptPath, ...process.argv.slice(2)], {
   stdio: 'inherit',
   windowsHide: true,

package/scripts/turn-stop-gate.mjs

@@ -48,6 +48,56 @@ function buildBlockReason(routeContext, detail, cwd) {
   ].filter(Boolean).join('\n')
 }
 
+function getLastAssistantMessage(payload = {}) {
+  return String(
+    payload.lastAssistantMessage
+    || payload.last_assistant_message
+    || payload['last-assistant-message']
+    || '',
+  ).trim()
+}
+
+function countMatches(text, pattern) {
+  const matches = text.match(pattern)
+  return matches ? matches.length : 0
+}
+
+function validateFormattedCloseoutMessage(routeContext, payload, cwd) {
+  const message = getLastAssistantMessage(payload)
+  if (!message || !message.includes('【HelloAGENTS】')) return ''
+
+  const firstNonEmptyLine = message
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find(Boolean)
+
+  if (!firstNonEmptyLine || !/^[💡⚡🔵✅❓⚠️❌]【HelloAGENTS】- /.test(firstNonEmptyLine)) {
+    return buildBlockReason(
+      routeContext,
+      '最终收尾消息使用了 HelloAGENTS 外层格式，但首个非空行不是规范标题行。',
+      cwd,
+    )
+  }
+
+  if (countMatches(message, /[💡⚡🔵✅❓⚠️❌]【HelloAGENTS】-/g) > 1) {
+    return buildBlockReason(
+      routeContext,
+      '最终收尾消息重复输出了 HelloAGENTS 标题；请把所有内容合并到同一个外层块内。',
+      cwd,
+    )
+  }
+
+  if (countMatches(message, /^🔄 下一步:/gm) > 1) {
+    return buildBlockReason(
+      routeContext,
+      '最终收尾消息重复输出了 `🔄 下一步`；请只保留一个真实下一步。',
+      cwd,
+    )
+  }
+
+  return ''
+}
+
 function getMainTurnState(cwd, payload = {}) {
   const turnState = readTurnState(cwd, { payload })
   return turnState?.role === 'main' ? turnState : null
@@ -64,11 +114,13 @@ function hasStructuredBlocker(turnState) {
   )
 }
 
-function validateTurnState(routeContext, turnState, cwd) {
+function validateTurnState(routeContext, turnState, cwd, payload = {}) {
   if (!turnState) {
     return buildBlockReason(routeContext, '缺少主代理 turn-state。', cwd)
   }
   if (turnState.kind === 'complete') {
+    const formatReason = validateFormattedCloseoutMessage(routeContext, payload, cwd)
+    if (formatReason) return formatReason
     return ''
   }
   if (turnState.kind === 'waiting' || turnState.kind === 'blocked') {
@@ -91,18 +143,20 @@ function validateTurnState(routeContext, turnState, cwd) {
   return buildBlockReason(routeContext, `当前 turn-state 为 \`${turnState.kind}\`，不能作为本轮结束状态。`, cwd)
 }
 
-function main() {
-  const payload = readStdinJson()
+export function evaluateTurnStopGate(payload = {}) {
   const cwd = payload.cwd || process.cwd()
   const routeContext = getApplicableRouteContext({ cwd, payload })
 
   if (!routeContext || !ENFORCED_COMMANDS.has(routeContext.skillName)) {
-    process.stdout.write(JSON.stringify({ decision: 'continue' }))
-    return
+    return { decision: 'continue' }
   }
 
-  const reason = validateTurnState(routeContext, getMainTurnState(cwd, payload), cwd)
-  process.stdout.write(JSON.stringify(reason ? { decision: 'block', reason } : { decision: 'continue' }))
+  const reason = validateTurnState(routeContext, getMainTurnState(cwd, payload), cwd, payload)
+  return reason ? { decision: 'block', reason } : { decision: 'continue' }
+}
+
+function main() {
+  process.stdout.write(JSON.stringify(evaluateTurnStopGate(readStdinJson())))
 }
 
 if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {

package/skills/commands/help/SKILL.md

@@ -39,7 +39,7 @@ Trigger: ~help
 完成时：hello-verify, hello-reflect
 
 ### 当前设置
-优先使用当前会话上下文中已注入的“当前用户设置”、该配置文件原始 JSON 或此前读取结果摘要显示；若会话上下文不存在该信息，或缺少下表任一配置项，才读取一次 `~/.helloagents/helloagents.json`，并在后续轮次复用。
+优先使用当前会话上下文中已注入的“当前用户设置”、该配置文件原始 JSON 或此前读取结果摘要显示；若会话上下文不存在该信息，或缺少下表任一配置项，才读取一次 `~/.helloagents/helloagents.json`，并在后续轮次复用。对 Codex 来说，首次对话前若当前上下文仍缺少这些配置项，或刚经历压缩/恢复后的首次对话，同样先读取一次再继续。
 如果当前 CLI 存在工作区限制导致家目录不可读，则明确说明“无法直接读取配置文件，以下按已注入设置或默认值展示”，不要改用无关工具或伪造已读取结果。
 | 配置项 | 默认值 | 作用 | 适用 CLI |
 |--------|-------|------|---------|

package/skills/helloagents/SKILL.md

@@ -5,7 +5,7 @@ description: 按任务类型适用 — 建立质量驱动工作流，通过技
 
 # HelloAGENTS
 
-主代理触发或读取任意 skill 时，只有本轮最终收尾消息才按通用输出格式包装；流式内容、进度或状态汇报、中间文本，以及任何仍将继续执行的文本，都保持自然输出。最终收尾中的 `🔄 下一步` 写真实动作，不写当前状态；等待用户授权时使用等待输入态收尾，已获授权且可继续执行时不得收尾。
+主代理触发或读取任意 skill 时，只有本轮最终收尾消息才按通用输出格式包装；流式内容、进度或状态汇报、中间文本，以及任何仍将继续执行的文本，都保持自然输出。最终收尾中的 `🔄 下一步` 写真实动作，不写当前状态；等待用户授权时使用等待输入态收尾，已获授权且可继续执行时不得收尾。同一条最终收尾消息只包装一次；若需要分段，在同一个外层块内展开，不在正文里再次输出 `【HelloAGENTS】` 或第二个 `🔄 下一步`。
 子代理只豁免路由与收尾要求，直接执行任务；安全、质量、验证和失败处理规则仍持续生效，且不得包装 HelloAGENTS 外层输出格式。
 只有运行时必须识别本轮“完成 / 等待输入 / 阻塞”时，主代理才写 turn-state；普通问候、普通问答、T0 只读分析和一次性解释不调用。必须调用场景：显式 `~auto` / `~loop`、非只读任务完成验证并进入收尾、需要 delivery gate / Ralph Loop / closeout evidence、需要等待或阻塞且运行时必须识别状态、已进入项目连续流程或方案包闭环。首选 `helloagents-turn-state write --kind complete --role main`；等待或阻塞时写 `kind=waiting` / `kind=blocked`，并同时写 `reasonCategory` 与 `reason`。显式 `~auto` / `~loop` 下，还必须写入 `blocker.target`、`blocker.evidence`、`blocker.requiredAction`。不要查找、读取或拼接 `turn-state.mjs` 源码路径。子代理不得写 turn-state。