helloagents 3.0.12 → 3.0.15-beta.1

package/scripts/notify.mjs

@@ -3,7 +3,7 @@
 // Zero external dependencies, ES module, cross-platform
 
 import { join, dirname } from 'node:path';
-import { existsSync, readFileSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { playSound as _playSound, desktopNotify as _desktopNotify } from './notify-ui.mjs';
@@ -13,10 +13,12 @@ import { shouldIgnoreCodexNotifyClient } from './notify-events.mjs';
 import { runGateScript } from './notify-gates.mjs';
 import { handleRouteCommand, resolveBootstrapFile } from './notify-route.mjs';
 import { readSettings, readStdinJson, output, suppressedOutput, emptySuppress } from './notify-shared.mjs';
-import { clearRouteContext, writeRouteContext } from './runtime-context.mjs';
+import { clearRouteContext, getApplicableRouteContext, writeRouteContext } from './runtime-context.mjs';
 import { appendReplayEvent, startReplaySession } from './replay-state.mjs';
 import { clearTurnState, readTurnState } from './turn-state.mjs';
 import { getWorkflowRecommendation } from './workflow-state.mjs';
+import { resolveSessionToken } from './session-token.mjs';
+import { isProjectRuntimeActive } from './runtime-scope.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -33,6 +35,7 @@ const EVENT_NAME = {
   UserPromptSubmit: IS_GEMINI ? 'BeforeAgent' : 'UserPromptSubmit',
   PreCompact: IS_GEMINI ? 'BeforeAgent' : 'PreCompact',
 };
+const RALPH_LOOP_ROUTE_COMMANDS = new Set(['verify', 'loop']);
 
 const playSound = (event) => _playSound(PKG_ROOT, event);
 const desktopNotify = (event, extra) => _desktopNotify(PKG_ROOT, event, extra);
@@ -64,9 +67,18 @@ function getSettings() {
   return readSettings(CONFIG_FILE);
 }
 
-function runRalphLoop(payload) {
+function shouldRunRalphLoop(cwd, turnState, payload = {}) {
+  if (!turnState || turnState.kind !== 'complete') return false;
+  if (turnState.requiresDeliveryGate) return true;
+  const routeContext = getApplicableRouteContext({ cwd, payload });
+  return RALPH_LOOP_ROUTE_COMMANDS.has(routeContext?.skillName);
+}
+
+function runRalphLoop(payload, { turnState } = {}) {
   const settings = getSettings();
   if (settings.ralph_loop_enabled === false) return false;
+  const cwd = payload.cwd || process.cwd();
+  if (!shouldRunRalphLoop(cwd, turnState, payload)) return false;
   return runGateScript({
     payload,
     host: HOST,
@@ -106,13 +118,24 @@ function runTurnStopGate(payload) {
   });
 }
 
-function readMainTurnState(cwd) {
-  const turnState = readTurnState(cwd);
+function attachTurnSession(payload = {}, cwd = payload.cwd || process.cwd()) {
+  const sessionId = resolveSessionToken({
+    payload,
+    env: process.env,
+    ppid: process.ppid,
+    allowPpidFallback: !isProjectRuntimeActive(cwd),
+  });
+  if (!sessionId || payload.sessionId) return payload;
+  return { ...payload, sessionId };
+}
+
+function readMainTurnState(cwd, payload = {}) {
+  const turnState = readTurnState(cwd, { payload });
   return turnState?.role === 'main' ? turnState : null;
 }
 
-function consumeMainTurnState(cwd, turnState) {
-  if (turnState?.role === 'main') clearTurnState(cwd);
+function consumeMainTurnState(cwd, turnState, payload = {}) {
+  if (turnState?.role === 'main') clearTurnState(cwd, { payload });
 }
 
 function shouldProcessCloseout(turnState) {
@@ -136,6 +159,7 @@ function cmdPreCompact() {
     host: HOST,
     event: 'pre_compact_snapshot',
     source: 'pre-compact',
+    payload,
     details: {
       bootstrapFile,
       installMode: settings.install_mode || '',
@@ -146,7 +170,7 @@ function cmdPreCompact() {
 
 function cmdRoute() {
   const payload = readStdinJson();
-  clearTurnState(payload.cwd || process.cwd());
+  clearTurnState(payload.cwd || process.cwd(), { payload });
   handleRouteCommand({
     payload,
     host: HOST,
@@ -181,15 +205,17 @@ function cmdInject() {
     source,
     bootstrapFile,
     installMode: settings.install_mode || '',
+    payload,
   });
   appendReplayEvent(cwd, {
     host: HOST,
     event: 'session_injected',
     source,
+    payload,
     details: {
       bootstrapFile,
       installMode: settings.install_mode || '',
-      activatedProject: existsSync(join(cwd, '.helloagents')),
+      activatedProject: isProjectRuntimeActive(cwd),
     },
   });
   const context = buildInjectContext({
@@ -201,27 +227,28 @@ function cmdInject() {
     cwd,
     payload,
   });
-  clearRouteContext();
-  clearTurnState(cwd);
+  clearRouteContext({ cwd, payload });
+  clearTurnState(cwd, { payload });
   suppressedOutput(EVENT_NAME.SessionStart, context || undefined);
 }
 
 function cmdStop() {
   const payload = readStdinJson();
   const cwd = payload.cwd || process.cwd();
-  const turnState = readMainTurnState(cwd);
-  if (runTurnStopGate(payload)) {
-    if (turnState && turnState.kind !== 'complete') consumeMainTurnState(cwd, turnState);
+  const turnPayload = attachTurnSession(payload, cwd);
+  const turnState = readMainTurnState(cwd, turnPayload);
+  if (runTurnStopGate(turnPayload)) {
+    if (turnState && turnState.kind !== 'complete') consumeMainTurnState(cwd, turnState, turnPayload);
     return;
   }
   const shouldProcess = shouldProcessCloseout(turnState);
-  if (shouldProcess && runRalphLoop(payload)) {
-    consumeMainTurnState(cwd, turnState);
+  if (shouldProcess && runRalphLoop(turnPayload, { turnState })) {
+    consumeMainTurnState(cwd, turnState, turnPayload);
     notifyByLevel('warning', buildNotifyExtra(payload));
     return;
   }
-  if (shouldProcess && runDeliveryGate(payload)) {
-    consumeMainTurnState(cwd, turnState);
+  if (shouldProcess && runDeliveryGate(turnPayload)) {
+    consumeMainTurnState(cwd, turnState, turnPayload);
     notifyByLevel('warning', buildNotifyExtra(payload));
     return;
   }
@@ -230,8 +257,8 @@ function cmdStop() {
   if (shouldProcess) {
     notifyByLevel('complete', buildNotifyExtra(payload), settings);
   }
-  consumeMainTurnState(cwd, turnState);
-  clearRouteContext();
+  consumeMainTurnState(cwd, turnState, turnPayload);
+  clearRouteContext({ cwd, payload: turnPayload });
   emptySuppress();
 }
 
@@ -246,6 +273,8 @@ function cmdDesktop() {
 function cmdCodexNotify() {
   let data = {};
   try { data = JSON.parse(process.argv[3] || '{}'); } catch {}
+  const cwd = data.cwd || process.cwd();
+  const turnPayload = attachTurnSession(data, cwd);
 
   const type = data.type || '';
   const client = data.client || '';
@@ -257,34 +286,33 @@ function cmdCodexNotify() {
   }
   if (type !== 'agent-turn-complete') return;
 
-  const cwd = data.cwd || process.cwd();
-  const turnState = readMainTurnState(cwd);
-  if (runTurnStopGate(data)) {
-    if (turnState && turnState.kind !== 'complete') consumeMainTurnState(cwd, turnState);
+  const turnState = readMainTurnState(cwd, turnPayload);
+  if (runTurnStopGate(turnPayload)) {
+    if (turnState && turnState.kind !== 'complete') consumeMainTurnState(cwd, turnState, turnPayload);
     return;
   }
   if (!turnState) return;
   if (turnState.kind !== 'complete') {
-    consumeMainTurnState(cwd, turnState);
-    clearRouteContext();
+    consumeMainTurnState(cwd, turnState, turnPayload);
+    clearRouteContext({ cwd, payload: turnPayload });
     return;
   }
 
   const settings = getSettings();
-  if (runRalphLoop(data)) {
-    consumeMainTurnState(cwd, turnState);
+  if (runRalphLoop(turnPayload, { turnState })) {
+    consumeMainTurnState(cwd, turnState, turnPayload);
     notifyByLevel('warning', buildNotifyExtra(data), settings);
     return;
   }
-  if (runDeliveryGate(data)) {
-    consumeMainTurnState(cwd, turnState);
+  if (runDeliveryGate(turnPayload)) {
+    consumeMainTurnState(cwd, turnState, turnPayload);
     notifyByLevel('warning', buildNotifyExtra(data), settings);
     return;
   }
 
   notifyByLevel('complete', buildNotifyExtra(data), settings);
-  consumeMainTurnState(cwd, turnState);
-  clearRouteContext();
+  consumeMainTurnState(cwd, turnState, turnPayload);
+  clearRouteContext({ cwd, payload: turnPayload });
 }
 
 const cmd = process.argv[2] || '';

package/scripts/project-storage.mjs

@@ -5,13 +5,19 @@ import { homedir } from 'node:os'
 import { basename, dirname, isAbsolute, join, normalize, resolve } from 'node:path'
 
 import { DEFAULTS } from './cli-config.mjs'
-import { resolveSessionToken } from './session-token.mjs'
+import {
+  PROJECT_DIR_NAME,
+  getProjectActivationDir,
+  getProjectSessionScope,
+  normalizeRuntimeOptions,
+} from './runtime-scope.mjs'
+import {
+  getSessionArtifactPath,
+  getSessionArtifactRelativePath,
+} from './session-capsule.mjs'
 
-export const PROJECT_DIR_NAME = '.helloagents'
 const PROJECTS_DIR_NAME = 'projects'
-const PROJECT_SESSIONS_DIR_NAME = 'sessions'
 const PROJECT_STORE_MODES = new Set(['local', 'repo-shared'])
-const DEFAULT_STATE_SESSION_TOKEN = 'default'
 
 function safeJson(filePath) {
   try {
@@ -34,19 +40,6 @@ function runGitRevParse(cwd, args = []) {
   }
 }
 
-function runGitCommand(cwd, args = []) {
-  try {
-    return execFileSync('git', args, {
-      cwd,
-      encoding: 'utf-8',
-      timeout: 5_000,
-      stdio: ['ignore', 'pipe', 'ignore'],
-    }).trim()
-  } catch {
-    return ''
-  }
-}
-
 function resolveGitTopLevel(cwd) {
   const absolute = runGitRevParse(cwd, ['--path-format=absolute', '--show-toplevel'])
   if (absolute) return normalize(absolute)
@@ -70,16 +63,6 @@ function sanitizeRepoName(value = '') {
   return normalized || 'project'
 }
 
-function sanitizeStateScopeSegment(value = '', fallback = '') {
-  const normalized = String(value)
-    .trim()
-    .toLowerCase()
-    .replace(/[^a-z0-9._-]+/g, '-')
-    .replace(/^-+|-+$/g, '')
-    .slice(0, 48)
-  return normalized || fallback
-}
-
 function buildProjectKey(cwd) {
   const repoRoot = resolveGitTopLevel(cwd)
   const commonDir = resolveGitCommonDir(cwd, repoRoot)
@@ -113,15 +96,6 @@ function formatPromptPath(pathValue = '') {
   return pathValue ? normalize(pathValue).replace(/\\/g, '/') : ''
 }
 
-function resolveGitBranchName(cwd) {
-  const branchName = runGitRevParse(cwd, ['--abbrev-ref', 'HEAD'])
-  if (branchName && branchName !== 'HEAD') return branchName
-
-  const symbolicBranchName = runGitCommand(cwd, ['symbolic-ref', '--quiet', '--short', 'HEAD'])
-  if (symbolicBranchName && symbolicBranchName !== 'HEAD') return symbolicBranchName
-  return ''
-}
-
 export function normalizeProjectStoreMode(value) {
   const normalized = typeof value === 'string' ? value.trim().toLowerCase() : ''
   return PROJECT_STORE_MODES.has(normalized) ? normalized : DEFAULTS.project_store_mode
@@ -136,37 +110,16 @@ export function getProjectStoreMode() {
   return normalizeProjectStoreMode(settings.project_store_mode)
 }
 
-export function getProjectActivationDir(cwd) {
-  return join(cwd, PROJECT_DIR_NAME)
-}
-
-export function getProjectSessionStateScope(cwd, {
-  payload = {},
-  env = process.env,
-  ppid = process.ppid,
-} = {}) {
-  const rawSessionToken = resolveSessionToken({
-    payload,
-    env,
-    ppid,
-    allowPpidFallback: false,
-  })
-  const branchName = sanitizeStateScopeSegment(resolveGitBranchName(cwd), 'detached')
-  const sessionToken = sanitizeStateScopeSegment(rawSessionToken, DEFAULT_STATE_SESSION_TOKEN)
-  const sessionDir = join(
-    getProjectActivationDir(cwd),
-    PROJECT_SESSIONS_DIR_NAME,
-    branchName,
-    sessionToken,
-  )
+export function getProjectSessionStateScope(cwd, options = {}) {
+  const scope = getProjectSessionScope(cwd, normalizeRuntimeOptions(options))
 
   return {
     stateScope: 'session',
-    stateSessionToken: sessionToken,
-    stateSessionMode: rawSessionToken ? 'host-session' : 'default',
-    stateBranch: branchName,
-    sessionDir,
-    statePath: join(sessionDir, 'STATE.md'),
+    stateSessionToken: scope.session,
+    stateSessionMode: scope.sessionMode,
+    stateBranch: scope.branch,
+    sessionDir: scope.sessionDir,
+    statePath: scope.statePath,
   }
 }
 
@@ -174,6 +127,18 @@ export function getProjectStatePath(cwd, options = {}) {
   return getProjectSessionStateScope(cwd, options).statePath
 }
 
+export function getProjectEvidenceDir(cwd, options = {}) {
+  return getProjectSessionScope(cwd, normalizeRuntimeOptions(options)).artifactsDir
+}
+
+export function getProjectEvidencePath(cwd, fileName, options = {}) {
+  return getSessionArtifactPath(cwd, fileName, options)
+}
+
+export function getProjectEvidenceRelativePath(cwd, fileName, options = {}) {
+  return getSessionArtifactRelativePath(cwd, fileName, options)
+}
+
 export function isRepoSharedProjectStore(cwd) {
   return getProjectStoreMode(cwd) === 'repo-shared'
 }
@@ -191,6 +156,7 @@ export function getProjectStoreSummary(cwd, options = {}) {
   const activationDir = getProjectActivationDir(cwd)
   const storeDir = getProjectStoreDir(cwd)
   const stateScope = getProjectSessionStateScope(cwd, options)
+  const artifactsDir = getProjectEvidenceDir(cwd, options)
   const projectKey = buildProjectKey(cwd)
   const projectStoreMode = getProjectStoreMode(cwd)
 
@@ -204,6 +170,7 @@ export function getProjectStoreSummary(cwd, options = {}) {
     stateSessionMode: stateScope.stateSessionMode,
     stateBranch: stateScope.stateBranch,
     sessionStateDir: stateScope.sessionDir,
+    artifactsDir,
     usesSharedStore: projectStoreMode === 'repo-shared',
     projectKey: projectKey.key,
     repoRoot: projectKey.repoRoot,
@@ -212,6 +179,7 @@ export function getProjectStoreSummary(cwd, options = {}) {
     promptStoreDir: formatPromptPath(storeDir),
     promptStatePath: formatPromptPath(stateScope.statePath),
     promptSessionStateDir: formatPromptPath(stateScope.sessionDir),
+    promptArtifactsDir: formatPromptPath(artifactsDir),
   }
 }
 
@@ -282,7 +250,7 @@ export function buildProjectStorageHint(cwd, options = {}) {
     hints.push(`当前宿主未提供稳定会话标识，因此使用分支默认位置 \`${summary.stateSessionToken}\``)
   }
   if (summary.usesSharedStore) {
-    hints.push(`项目存储：\`project_store_mode=repo-shared\`；本地激活/运行态目录仍是 \`${summary.promptActivationDir}\`，知识库/方案目录改为 \`${summary.promptStoreDir}\``)
+    hints.push(`项目存储：\`project_store_mode=repo-shared\`；本地激活/会话运行态目录仍是 \`${summary.promptActivationDir}\`，知识库/方案目录改为 \`${summary.promptStoreDir}\``)
   }
   return hints.join('。') + (hints.length > 0 ? '。' : '')
 }
@@ -302,6 +270,7 @@ export function buildProjectStorageBlock(cwd, options = {}) {
     state_session_token: summary.stateSessionToken,
     state_session_mode: summary.stateSessionMode,
     session_state_dir: summary.promptSessionStateDir,
+    artifacts_dir: summary.promptArtifactsDir,
     knowledge_base_dir: summary.promptStoreDir,
     uses_shared_store: summary.usesSharedStore,
   }
@@ -312,7 +281,7 @@ export function buildProjectStorageBlock(cwd, options = {}) {
     explanations.push('说明：当前宿主未提供稳定会话标识，因此使用分支默认位置。')
   }
   if (summary.usesSharedStore) {
-    explanations.push('说明：状态文件与 `.ralph-*.json` 写本地激活目录；`context.md`、`guidelines.md`、`DESIGN.md`、`verify.yaml`、`modules/`、`plans/`、`archive/` 写知识库/方案目录。')
+    explanations.push('说明：状态文件与会话产物写本地激活目录；`context.md`、`guidelines.md`、`DESIGN.md`、`verify.yaml`、`modules/`、`plans/`、`archive/` 写知识库/方案目录。')
   } else {
     explanations.push('说明：当前使用项目本地 `.helloagents/` 作为激活目录、知识库目录和方案目录。')
   }

package/scripts/ralph-loop.mjs

@@ -4,11 +4,16 @@
  * Runs on SubagentStop (Claude Code) and Stop (Codex CLI).
  * Auto-detects lint/test commands and blocks if they fail.
  */
-import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { execSync } from 'node:child_process';
 import { homedir } from 'node:os';
 import { clearVerifyEvidence, detectCommands, hasUnsafeVerifyCommand, writeVerifyEvidence } from './verify-state.mjs';
+import {
+  getRuntimeEvidencePath,
+  readRuntimeEvidence,
+  writeRuntimeEvidence,
+} from './runtime-artifacts.mjs';
 
 const CONFIG_FILE = join(homedir(), '.helloagents', 'helloagents.json');
 const CMD_TIMEOUT = 60_000; // 60s
@@ -27,28 +32,23 @@ function readSettings() {
 }
 
 // ── Circuit Breaker (consecutive failure tracking) ───────────────────
-const BREAKER_FILE_NAME = '.ralph-breaker.json';
+const BREAKER_FILE_NAME = 'loop-breaker.json';
 
-function getBreakerPath(cwd) {
-  return join(cwd, '.helloagents', BREAKER_FILE_NAME);
+function getBreakerPath(cwd, options = {}) {
+  return getRuntimeEvidencePath(cwd, BREAKER_FILE_NAME, options);
 }
 
-function readBreaker(cwd) {
-  try {
-    return JSON.parse(readFileSync(getBreakerPath(cwd), 'utf-8'));
-  } catch {
-    return { consecutive_failures: 0, last_failure: null };
-  }
+function readBreaker(cwd, options = {}) {
+  return readRuntimeEvidence(cwd, BREAKER_FILE_NAME, options)
+    || { consecutive_failures: 0, last_failure: null };
 }
 
-function writeBreaker(cwd, state) {
-  const dir = join(cwd, '.helloagents');
-  try { mkdirSync(dir, { recursive: true }); } catch {}
-  writeFileSync(getBreakerPath(cwd), JSON.stringify(state, null, 2));
+function writeBreaker(cwd, state, options = {}) {
+  writeRuntimeEvidence(cwd, BREAKER_FILE_NAME, state, options);
 }
 
-function resetBreaker(cwd) {
-  writeBreaker(cwd, { consecutive_failures: 0, last_failure: null });
+function resetBreaker(cwd, options = {}) {
+  writeBreaker(cwd, { consecutive_failures: 0, last_failure: null }, options);
 }
 
 // ── Progress Detection (git diff check) ──────────────────────────────
@@ -74,7 +74,7 @@ function runVerify(commands, cwd) {
   const failures = [];
   for (const cmd of commands) {
     if (hasUnsafeVerifyCommand([cmd])) {
-      failures.push({ cmd, output: 'Blocked: shell operators not allowed in verify commands' });
+      failures.push({ cmd, output: '已阻止：验证命令不允许使用 shell 组合操作符' });
       continue;
     }
     try {
@@ -85,8 +85,8 @@ function runVerify(commands, cwd) {
         continue;
       }
       let output = ((err.stdout || '') + (err.stderr || '')).trim();
-      if (output.length > 1000) output = output.slice(0, 1000) + '\n...(truncated)';
-      failures.push({ cmd, output: output || `exit code ${err.status}` });
+      if (output.length > 1000) output = output.slice(0, 1000) + '\n…已截断';
+      failures.push({ cmd, output: output || `退出码 ${err.status}` });
     }
   }
   return failures;
@@ -94,13 +94,13 @@ function runVerify(commands, cwd) {
 
 // ── Result Handlers ──────────────────────────────────────────────────
 
-function handleSuccess(cwd, isSubagent) {
-  resetBreaker(cwd);
+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({
@@ -127,12 +127,12 @@ function handleSuccess(cwd, isSubagent) {
   }
 }
 
-function handleFailure(failures, cwd) {
-  clearVerifyEvidence(cwd);
-  const breaker = readBreaker(cwd);
+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);
+  writeBreaker(cwd, breaker, options);
 
   const breakerWarning = breaker.consecutive_failures >= 3
     ? `\n\n⚠️ [断路器] 已连续 ${breaker.consecutive_failures} 次验证失败。当前修复思路可能有误，建议：\n  1. 重新分析根因，不要继续在同一方向上硬修\n  2. 检查是否存在架构层面的问题\n  3. 考虑回退到上一个正常状态重新开始`
@@ -141,7 +141,7 @@ function handleFailure(failures, cwd) {
   const details = failures.map(f => `\u2717 ${f.cmd}\n${f.output}`).join('\n\n');
   process.stdout.write(JSON.stringify({
     decision: 'block',
-    reason: `[Ralph Loop] Verification failed:\n\n${details}\n\nFix the issues above before completing.${breakerWarning}`,
+    reason: `[Ralph Loop] 验证失败：\n\n${details}\n\n请先修复以上问题，再报告完成。${breakerWarning}`,
     suppressOutput: true,
   }));
 }
@@ -175,6 +175,7 @@ async function main() {
   let data = {};
   try { data = JSON.parse(readFileSync(0, 'utf-8')); } catch {}
   const cwd = data.cwd || process.cwd();
+  const runtimeOptions = { payload: data };
 
   let commands = detectCommands(cwd);
   if (!commands?.length) {
@@ -188,10 +189,14 @@ async function main() {
   }
 
   const failures = runVerify(commands, cwd);
-  if (failures.length === 0) handleSuccess(cwd, IS_SUBAGENT);
-  else handleFailure(failures, cwd);
+  if (failures.length === 0) handleSuccess(cwd, IS_SUBAGENT, runtimeOptions);
+  else handleFailure(failures, cwd, runtimeOptions);
 }
 
-main().catch(() => {
-  process.stdout.write(JSON.stringify({ suppressOutput: true }));
+main().catch((error) => {
+  process.stdout.write(JSON.stringify({
+    decision: 'block',
+    reason: `[Ralph Loop] 验证脚本执行异常，已暂停完成通知。\n原因：${error?.message || error}`,
+    suppressOutput: true,
+  }));
 });