helloagents 3.0.22 → 3.0.25

package/scripts/notify.mjs

@@ -7,13 +7,17 @@ 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';
-import { beginCodexCloseoutClaim, finalizeCodexCloseoutClaim } from './notify-closeout.mjs';
+import {
+  beginCodexCloseoutClaim,
+  finalizeCodexCloseoutClaim,
+  hasCodexQuickNotifyEvidence,
+  writeCodexQuickNotifyEvidence,
+} from './notify-closeout.mjs';
 import { resolveNotificationSource } from './notify-source.mjs';
 import { buildCompactionContext, buildInjectContext, buildRouteInstruction, buildSemanticRouteInstruction, resolveCanonicalCommandSkill } from './notify-context.mjs';
 import { resolveNotifyHost, shouldIgnoreCodexNotifyClient } from './notify-events.mjs';
-import { runGateScript } from './notify-gates.mjs';
 import { normalizeNotifyPayload } from './notify-payload.mjs';
-import { cleanupProjectSessions } from './project-session-cleanup.mjs';
+import { cleanupProjectSessions, PROJECT_SESSION_CLEANUP_COOLDOWN_MS } from './project-session-cleanup.mjs';
 import { handleRouteCommand, resolveBootstrapFile } from './notify-route.mjs';
 import { readSettings, readStdinJson, output, suppressedOutput, emptySuppress } from './notify-shared.mjs';
 import { clearRouteContext, getApplicableRouteContext, writeRouteContext } from './runtime-context.mjs';
@@ -38,8 +42,15 @@ const EVENT_NAME = {
   PreCompact: IS_GEMINI ? 'BeforeAgent' : 'PreCompact',
 };
 const RALPH_LOOP_ROUTE_COMMANDS = new Set(['verify', 'loop']);
+const CODEX_HOOKS_FILE = join(homedir(), '.codex', 'hooks.json');
+const GATE_MODULE_LOADERS = {
+  'turn-stop-gate': () => import('./turn-stop-gate.mjs'),
+  'delivery-gate': () => import('./delivery-gate.mjs'),
+  'ralph-loop': () => import('./ralph-loop.mjs'),
+};
+const gateEvaluatorCache = new Map();
 
-const playSound = (event) => _playSound(PKG_ROOT, event);
+const playSound = (event, options) => _playSound(PKG_ROOT, event, options);
 const desktopNotify = (event, extra) => _desktopNotify(PKG_ROOT, event, extra);
 
 function normalizeNotifyLevel(value) {
@@ -47,13 +58,13 @@ function normalizeNotifyLevel(value) {
   return [0, 1, 2, 3].includes(level) ? level : 0;
 }
 
-function notifyByLevel(event, extra, settings = getSettings()) {
+function notifyByLevel(event, extra, settings = getSettings(), options = {}) {
   const level = normalizeNotifyLevel(settings.notify_level ?? 0);
   if (level === 1) desktopNotify(event, extra);
-  if (level === 2) playSound(event);
+  if (level === 2) playSound(event, options);
   if (level === 3) {
     desktopNotify(event, extra);
-    playSound(event);
+    playSound(event, options);
   }
 }
 
@@ -84,50 +95,184 @@ function shouldRunRalphLoop(cwd, turnState, payload = {}) {
   return RALPH_LOOP_ROUTE_COMMANDS.has(routeContext?.skillName);
 }
 
-function runRalphLoop(payload, { turnState } = {}) {
+function buildGateErrorReason(source, detail = '') {
+  return [
+    `[HelloAGENTS Runtime] ${source} 执行失败，已暂停完成通知。`,
+    detail ? `原因：${detail}` : '',
+    '请修复脚本或重新运行验证后再报告完成。',
+  ].filter(Boolean).join('\n');
+}
+
+function emitInlineGateError(payload, source, detail = '') {
+  const reason = buildGateErrorReason(source, detail);
+  appendReplayEvent(payload.cwd || process.cwd(), {
+    host: HOST,
+    event: 'runtime_gate_error',
+    source,
+    reason,
+    payload,
+  });
+  output({
+    decision: 'block',
+    reason,
+    suppressOutput: true,
+  });
+  return true;
+}
+
+function stringifyStreamChunk(chunk, encoding) {
+  if (typeof chunk === 'string') return chunk;
+  if (chunk instanceof Uint8Array || Buffer.isBuffer(chunk)) {
+    return Buffer.from(chunk).toString(typeof encoding === 'string' ? encoding : 'utf-8');
+  }
+  return String(chunk ?? '');
+}
+
+async function importGateModule(source) {
+  const loader = GATE_MODULE_LOADERS[source];
+  if (!loader) {
+    throw new Error(`无法解析的 JSON：未知 gate 模块 ${source}。`);
+  }
+
+  const originalStdoutWrite = process.stdout.write.bind(process.stdout);
+  const originalStderrWrite = process.stderr.write.bind(process.stderr);
+  let capturedStdout = '';
+  let capturedStderr = '';
+
+  process.stdout.write = (chunk, encoding, callback) => {
+    capturedStdout += stringifyStreamChunk(chunk, encoding);
+    if (typeof encoding === 'function') encoding();
+    if (typeof callback === 'function') callback();
+    return true;
+  };
+  process.stderr.write = (chunk, encoding, callback) => {
+    capturedStderr += stringifyStreamChunk(chunk, encoding);
+    if (typeof encoding === 'function') encoding();
+    if (typeof callback === 'function') callback();
+    return true;
+  };
+
+  try {
+    const module = await loader();
+    if (capturedStdout.trim() || capturedStderr.trim()) {
+      throw new Error(`无法解析的 JSON：模块导入时输出了意外内容。${capturedStdout || capturedStderr}`);
+    }
+    return module;
+  } finally {
+    process.stdout.write = originalStdoutWrite;
+    process.stderr.write = originalStderrWrite;
+  }
+}
+
+async function loadGateEvaluator(source, exportName) {
+  let evaluatorPromise = gateEvaluatorCache.get(source);
+  if (!evaluatorPromise) {
+    evaluatorPromise = importGateModule(source).then((module) => {
+      const evaluate = module?.[exportName];
+      if (typeof evaluate !== 'function') {
+        throw new Error(`无法解析的 JSON：模块未导出 ${exportName}。`);
+      }
+      return evaluate;
+    });
+    gateEvaluatorCache.set(source, evaluatorPromise);
+  }
+
+  try {
+    return await evaluatorPromise;
+  } catch (error) {
+    gateEvaluatorCache.delete(source);
+    throw error;
+  }
+}
+
+async function runInlineGate({ payload, source, blockEvent, exportName, evaluateArgs }) {
+  let evaluate;
+  try {
+    evaluate = await loadGateEvaluator(source, exportName);
+  } catch (error) {
+    return emitInlineGateError(payload, source, error?.message || String(error));
+  }
+
+  let gateOutput;
+  try {
+    gateOutput = await evaluate(...evaluateArgs);
+  } catch (error) {
+    return emitInlineGateError(payload, source, error?.message || String(error));
+  }
+
+  if (!gateOutput || typeof gateOutput !== 'object' || Array.isArray(gateOutput)) {
+    return emitInlineGateError(payload, source, '无法解析的 JSON：gate 返回值不是对象。');
+  }
+
+  if (gateOutput?.decision === 'block') {
+    appendReplayEvent(payload.cwd || process.cwd(), {
+      host: HOST,
+      event: blockEvent,
+      source,
+      reason: gateOutput.reason || '',
+      payload,
+    });
+    output(gateOutput);
+    return true;
+  }
+
+  return false;
+}
+
+async 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({
+  return await runInlineGate({
     payload,
-    host: HOST,
-    scriptPath: join(__dirname, 'ralph-loop.mjs'),
-    args: IS_GEMINI ? ['--gemini'] : HOST === 'codex' ? ['--codex'] : [],
     source: 'ralph-loop',
     blockEvent: 'verify_gate_blocked',
-    timeout: 120_000,
-    appendReplayEvent,
-    output,
+    exportName: 'evaluateRalphLoop',
+    evaluateArgs: [payload, {
+      isSubagent: false,
+      isGemini: IS_GEMINI,
+      hookEventName: HOST === 'codex' ? 'Stop' : (IS_GEMINI ? 'SessionEnd' : 'Stop'),
+    }],
   });
 }
 
-function runDeliveryGate(payload) {
-  return runGateScript({
+async function runDeliveryGate(payload) {
+  return await runInlineGate({
     payload,
-    host: HOST,
-    scriptPath: join(__dirname, 'delivery-gate.mjs'),
     source: 'delivery-gate',
     blockEvent: 'delivery_gate_blocked',
-    timeout: 30_000,
-    appendReplayEvent,
-    output,
+    exportName: 'evaluateDeliveryGate',
+    evaluateArgs: [payload],
   });
 }
 
-function runTurnStopGate(payload) {
-  return runGateScript({
+async function runTurnStopGate(payload) {
+  return await runInlineGate({
     payload,
-    host: HOST,
-    scriptPath: join(__dirname, 'turn-stop-gate.mjs'),
     source: 'turn-stop-gate',
     blockEvent: 'turn_stop_blocked',
-    timeout: 30_000,
-    appendReplayEvent,
-    output,
+    exportName: 'evaluateTurnStopGate',
+    evaluateArgs: [payload],
   });
 }
 
+function hasManagedCodexStopHook() {
+  if (!IS_CODEX) return false;
+  try {
+    const hooksData = JSON.parse(readFileSync(CODEX_HOOKS_FILE, 'utf-8'));
+    const groups = Array.isArray(hooksData?.hooks?.Stop) ? hooksData.hooks.Stop : [];
+    return groups.some((group) => Array.isArray(group?.hooks) && group.hooks.some((handler) =>
+      handler?.type === 'command'
+      && typeof handler.command === 'string'
+      && handler.command.includes('helloagents-js')
+      && handler.command.includes('notify stop --codex'),
+    ));
+  } catch {
+    return false;
+  }
+}
+
 function attachTurnSession(payload = {}, cwd = payload.cwd || process.cwd()) {
   const sessionId = resolveSessionToken({
     payload,
@@ -148,21 +293,23 @@ function consumeMainTurnState(cwd, turnState, payload = {}) {
   if (turnState?.role === 'main') clearTurnState(cwd, { payload });
 }
 
-function shouldProcessCloseout(turnState) {
+function shouldEmitManagedCodexCompleteNotify(cwd, turnState, payload = {}) {
   if (turnState) return turnState.kind === 'complete';
-  return false;
+  const routeContext = getApplicableRouteContext({ cwd, payload });
+  return routeContext?.skillName !== 'auto';
 }
 
-function processTurnCloseout(payload, turnPayload, turnState, settings = getSettings()) {
+async function processTurnCloseout(payload, turnPayload, turnState, settings = getSettings(), options = {}) {
   const cwd = turnPayload.cwd || process.cwd();
+  const skipCompleteNotify = options.skipCompleteNotify === true;
 
-  if (runTurnStopGate(turnPayload)) {
+  if (await runTurnStopGate(turnPayload)) {
     if (turnState && turnState.kind !== 'complete') consumeMainTurnState(cwd, turnState, turnPayload);
     return { blocked: true };
   }
 
   if (!turnState) {
-    notifyByLevel('complete', buildNotifyExtra(turnPayload), settings);
+    if (!skipCompleteNotify) notifyByLevel('complete', buildNotifyExtra(turnPayload), settings);
     clearRouteContext({ cwd, payload: turnPayload });
     return { blocked: false };
   }
@@ -173,18 +320,18 @@ function processTurnCloseout(payload, turnPayload, turnState, settings = getSett
     return { blocked: false };
   }
 
-  if (runRalphLoop(turnPayload, { turnState })) {
+  if (await runRalphLoop(turnPayload, { turnState })) {
     consumeMainTurnState(cwd, turnState, turnPayload);
     notifyByLevel('warning', buildNotifyExtra(payload), settings);
     return { blocked: true };
   }
-  if (runDeliveryGate(turnPayload)) {
+  if (await runDeliveryGate(turnPayload)) {
     consumeMainTurnState(cwd, turnState, turnPayload);
     notifyByLevel('warning', buildNotifyExtra(payload), settings);
     return { blocked: true };
   }
 
-  notifyByLevel('complete', buildNotifyExtra(payload), settings);
+  if (!skipCompleteNotify) notifyByLevel('complete', buildNotifyExtra(payload), settings);
   consumeMainTurnState(cwd, turnState, turnPayload);
   clearRouteContext({ cwd, payload: turnPayload });
   return { blocked: false };
@@ -230,6 +377,7 @@ function cmdRoute() {
     clearRouteContext,
     appendReplayEvent,
     getWorkflowRecommendation,
+    recordReplayEvents: !IS_SILENT,
     suppress: (context) => IS_SILENT
       ? emptySuppress()
       : suppressedOutput(EVENT_NAME.UserPromptSubmit, context),
@@ -251,20 +399,24 @@ function cmdInject() {
     installMode: settings.install_mode || '',
     payload,
   });
-  appendReplayEvent(cwd, {
-    host: HOST,
-    event: 'session_injected',
-    source,
-    payload,
-    details: {
-      bootstrapFile,
-      installMode: settings.install_mode || '',
-      activatedProject: isProjectRuntimeActive(cwd),
-    },
-  });
+  if (!IS_SILENT) {
+    appendReplayEvent(cwd, {
+      host: HOST,
+      event: 'session_injected',
+      source,
+      payload,
+      details: {
+        bootstrapFile,
+        installMode: settings.install_mode || '',
+        activatedProject: isProjectRuntimeActive(cwd),
+      },
+    });
+  }
   clearRouteContext({ cwd, payload });
   clearTurnState(cwd, { payload });
-  cleanupProjectSessions(cwd);
+  cleanupProjectSessions(cwd, {
+    minIntervalMs: IS_SILENT ? PROJECT_SESSION_CLEANUP_COOLDOWN_MS : 0,
+  });
   if (IS_SILENT) {
     emptySuppress();
     return;
@@ -286,11 +438,16 @@ function cmdInject() {
   suppressedOutput(EVENT_NAME.SessionStart, context || undefined);
 }
 
-function cmdStop() {
+async function cmdStop() {
   const payload = readPayloadFromStdin();
   const cwd = payload.cwd || process.cwd();
   const turnPayload = attachTurnSession(payload, cwd);
   const turnState = readMainTurnState(cwd, turnPayload);
+  const managedCodexStopHook = IS_CODEX && hasManagedCodexStopHook();
+  const skipCompleteNotify = managedCodexStopHook && hasCodexQuickNotifyEvidence(cwd, {
+    payload: turnPayload,
+    turnState,
+  });
   const closeoutClaim = IS_CODEX
     ? beginCodexCloseoutClaim(cwd, { payload: turnPayload, turnState, source: 'stop' })
     : null;
@@ -302,7 +459,9 @@ function cmdStop() {
   let handled = false;
   let result = { blocked: false };
   try {
-    result = processTurnCloseout(payload, turnPayload, turnState, getSettings());
+    result = await processTurnCloseout(payload, turnPayload, turnState, getSettings(), {
+      skipCompleteNotify,
+    });
     handled = true;
   } finally {
     finalizeCodexCloseoutClaim(closeoutClaim, {
@@ -317,14 +476,14 @@ function cmdStop() {
 }
 
 function cmdSound() {
-  playSound(process.argv[3] || 'complete');
+  playSound(process.argv[3] || 'complete', { mode: 'blocking' });
 }
 
 function cmdDesktop() {
   desktopNotify(process.argv[3] || 'complete', buildNotifyExtra({ cwd: process.cwd() }));
 }
 
-function cmdCodexNotify() {
+async function cmdCodexNotify() {
   let data = {};
   try { data = JSON.parse(process.argv[3] || '{}'); } catch {}
   data = normalizeNotifyPayload(data);
@@ -336,10 +495,22 @@ function cmdCodexNotify() {
   if (shouldIgnoreCodexNotifyClient(client)) return;
 
   if (type === 'approval-requested') {
-    notifyByLevel('confirm', buildNotifyExtra(data));
+    notifyByLevel('confirm', buildNotifyExtra(data), getSettings(), { mode: 'blocking' });
     return;
   }
   if (type !== 'agent-turn-complete') return;
+  if (hasManagedCodexStopHook()) {
+    const turnState = readMainTurnState(cwd, turnPayload);
+    if (shouldEmitManagedCodexCompleteNotify(cwd, turnState, turnPayload)) {
+      notifyByLevel('complete', buildNotifyExtra(data), getSettings(), { mode: 'blocking' });
+      writeCodexQuickNotifyEvidence(cwd, {
+        payload: turnPayload,
+        turnState,
+        event: type,
+      });
+    }
+    return;
+  }
 
   const turnState = readMainTurnState(cwd, turnPayload);
   const closeoutClaim = beginCodexCloseoutClaim(cwd, {
@@ -351,7 +522,7 @@ function cmdCodexNotify() {
 
   let handled = false;
   try {
-    processTurnCloseout(data, turnPayload, turnState, getSettings());
+    await processTurnCloseout(data, turnPayload, turnState, getSettings());
     handled = true;
   } finally {
     finalizeCodexCloseoutClaim(closeoutClaim, {
@@ -363,15 +534,19 @@ function cmdCodexNotify() {
   }
 }
 
-switch (cmd) {
-  case 'inject':        cmdInject(); break;
-  case 'stop':          cmdStop(); break;
-  case 'pre-compact':   cmdPreCompact(); break;
-  case 'route':         cmdRoute(); break;
-  case 'sound':         cmdSound(); break;
-  case 'desktop':       cmdDesktop(); break;
-  case 'codex-notify':  cmdCodexNotify(); break;
-  default:
-    process.stderr.write(`notify.mjs: unknown command "${cmd}"\n`);
-    process.exit(1);
+async function main() {
+  switch (cmd) {
+    case 'inject':        cmdInject(); break;
+    case 'stop':          await cmdStop(); break;
+    case 'pre-compact':   cmdPreCompact(); break;
+    case 'route':         cmdRoute(); break;
+    case 'sound':         cmdSound(); break;
+    case 'desktop':       cmdDesktop(); break;
+    case 'codex-notify':  await cmdCodexNotify(); break;
+    default:
+      process.stderr.write(`notify.mjs: unknown command "${cmd}"\n`);
+      process.exit(1);
+  }
 }
+
+await main();

package/scripts/project-session-cleanup.mjs

@@ -10,8 +10,11 @@ import {
   getProjectActivationDir,
   getProjectRoot,
   readJsonFile,
+  writeJsonFileAtomic,
 } from './runtime-scope.mjs'
 
+export const PROJECT_SESSION_CLEANUP_COOLDOWN_MS = 10 * 60 * 1000
+
 function removePath(filePath, result, bucket) {
   try {
     rmSync(filePath, { recursive: true, force: true })
@@ -58,7 +61,21 @@ function shouldKeepSession(active, workspace, session) {
   return activeWorkspace === workspace && active.session === session
 }
 
-export function cleanupProjectSessions(cwd) {
+function readCleanupCheckedAt(active) {
+  const raw = active && typeof active === 'object' ? active.cleanupCheckedAt : ''
+  const timestamp = Date.parse(raw || '')
+  return Number.isFinite(timestamp) ? timestamp : 0
+}
+
+function writeCleanupCheckpoint(activePath, active, now) {
+  if (!active || typeof active !== 'object' || Object.keys(active).length === 0) return
+  writeJsonFileAtomic(activePath, {
+    ...active,
+    cleanupCheckedAt: new Date(now).toISOString(),
+  })
+}
+
+export function cleanupProjectSessions(cwd, { now = Date.now(), minIntervalMs = 0 } = {}) {
   const projectRoot = getProjectRoot(cwd)
   const activationDir = getProjectActivationDir(projectRoot)
   const sessionsDir = join(activationDir, PROJECT_SESSIONS_DIR_NAME)
@@ -69,9 +86,17 @@ export function cleanupProjectSessions(cwd) {
     removedEmptyDirs: [],
     removedRouteOnlyDirs: [],
     errors: [],
+    skipped: false,
   }
 
   if (!existsSync(sessionsDir)) return result
+  if (minIntervalMs > 0) {
+    const lastCleanupAt = readCleanupCheckedAt(active)
+    if (lastCleanupAt > 0 && now - lastCleanupAt < minIntervalMs) {
+      result.skipped = true
+      return result
+    }
+  }
 
   for (const workspaceEntry of readdirSync(sessionsDir, { withFileTypes: true })) {
     if (!workspaceEntry.isDirectory()) continue
@@ -102,5 +127,6 @@ export function cleanupProjectSessions(cwd) {
     }
   }
 
+  writeCleanupCheckpoint(activePath, active, now)
   return result
 }