helloagents 3.0.8-beta.1 → 3.0.10-beta.1

package/scripts/notify-source.mjs

@@ -1,42 +1,13 @@
 import { basename, normalize, resolve } from 'node:path'
 
+import { resolveSessionToken } from './session-token.mjs'
+
 const HOST_LABELS = {
   codex: 'Codex',
   claude: 'Claude Code',
   gemini: 'Gemini',
 }
 
-const PAYLOAD_SESSION_KEYS = [
-  'sessionId',
-  'session_id',
-  'session',
-  'conversationId',
-  'conversation_id',
-  'conversation',
-  'threadId',
-  'thread_id',
-  'thread',
-  'windowId',
-  'window_id',
-  'window',
-  'tabId',
-  'tab_id',
-  'tab',
-  'requestId',
-  'request_id',
-]
-
-const ENV_SESSION_KEYS = [
-  'HELLOAGENTS_NOTIFY_SESSION_ID',
-  'WT_SESSION',
-  'TERM_SESSION_ID',
-  'KITTY_WINDOW_ID',
-  'ALACRITTY_WINDOW_ID',
-  'WINDOWID',
-  'WEZTERM_PANE',
-  'TAB_ID',
-]
-
 function normalizePath(filePath = '') {
   if (!filePath) return ''
   try {
@@ -61,34 +32,6 @@ function resolveProjectLabel(cwd = '') {
   return label || normalized.replace(/\\/g, '/')
 }
 
-function sanitizeSessionToken(value = '') {
-  const raw = String(value).trim().replace(/^[#:\s]+/, '')
-  const segments = raw
-    .split(/[^a-zA-Z0-9]+/)
-    .filter(Boolean)
-  const cleaned = segments.length > 1
-    ? segments[segments.length - 1]
-    : raw.replace(/[^a-zA-Z0-9_-]/g, '')
-
-  if (!cleaned) return ''
-  if (/^\d+$/.test(cleaned)) return cleaned
-  return cleaned.slice(0, 8)
-}
-
-function resolveSessionToken(payload, env, ppid) {
-  for (const key of PAYLOAD_SESSION_KEYS) {
-    const value = sanitizeSessionToken(readStringCandidate(payload, key))
-    if (value) return value
-  }
-
-  for (const key of ENV_SESSION_KEYS) {
-    const value = sanitizeSessionToken(env?.[key] || '')
-    if (value) return value
-  }
-
-  return ppid ? String(ppid) : ''
-}
-
 export function resolveNotificationSource({
   host = '',
   cwd = '',
@@ -98,7 +41,7 @@ export function resolveNotificationSource({
 } = {}) {
   const hostLabel = HOST_LABELS[host] || 'Agent'
   const projectLabel = resolveProjectLabel(readStringCandidate(payload, 'cwd') || cwd)
-  const sessionToken = resolveSessionToken(payload, env, ppid)
+  const sessionToken = resolveSessionToken({ payload, env, ppid })
   const parts = [hostLabel]
 
   if (projectLabel) parts.push(projectLabel)

package/scripts/notify-ui.mjs

@@ -18,6 +18,7 @@ const NOTIFY_MESSAGES = {
 };
 
 const WIN_APPID = 'HelloAgents.Notification';
+const DISABLE_OS_NOTIFICATIONS = process.env.HELLOAGENTS_DISABLE_OS_NOTIFICATIONS === '1';
 
 function escapeToastText(value = '') {
   return String(value)
@@ -55,6 +56,7 @@ function resolveWav(pkgRoot, event) {
 }
 
 export function playSound(pkgRoot, event) {
+  if (DISABLE_OS_NOTIFICATIONS) return;
   const wav = resolveWav(pkgRoot, event);
   if (!wav) { process.stderr.write('\x07'); return; }
   try {
@@ -83,6 +85,7 @@ function ensureWinAppId(pkgRoot) {
 }
 
 export function desktopNotify(pkgRoot, event, extra) {
+  if (DISABLE_OS_NOTIFICATIONS) return;
   const notification = buildDesktopNotificationContent(event, extra);
   try {
     if (PLAT === 'win32') {

package/scripts/notify.mjs

@@ -4,13 +4,13 @@
 
 import { join, dirname } from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
-import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { playSound as _playSound, desktopNotify as _desktopNotify } from './notify-ui.mjs';
 import { resolveNotificationSource } from './notify-source.mjs';
 import { buildCompactionContext, buildInjectContext, buildRouteInstruction, buildSemanticRouteInstruction, resolveCanonicalCommandSkill } from './notify-context.mjs';
-import { claimsTaskComplete, shouldIgnoreCodexNotifyClient } from './notify-events.mjs';
+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';
@@ -37,6 +37,17 @@ const EVENT_NAME = {
 const playSound = (event) => _playSound(PKG_ROOT, event);
 const desktopNotify = (event, extra) => _desktopNotify(PKG_ROOT, event, extra);
 
+function normalizeNotifyLevel(value) {
+  const level = Number(value);
+  return [0, 1, 2, 3].includes(level) ? level : 0;
+}
+
+function notifyByLevel(event, extra, settings = getSettings()) {
+  const level = normalizeNotifyLevel(settings.notify_level ?? 0);
+  if (level === 2 || level === 3) playSound(event);
+  if (level === 1 || level === 3) desktopNotify(event, extra);
+}
+
 function buildNotifyExtra(payload = {}, options = {}) {
   const source = resolveNotificationSource({
     host: HOST,
@@ -56,71 +67,44 @@ function getSettings() {
 function runRalphLoop(payload) {
   const settings = getSettings();
   if (settings.ralph_loop_enabled === false) return false;
-  try {
-    const rlPath = join(__dirname, 'ralph-loop.mjs');
-    if (!existsSync(rlPath)) return false;
-    const hostFlag = IS_GEMINI ? ['--gemini'] : HOST === 'codex' ? ['--codex'] : [];
-    const result = spawnSync(process.execPath, [rlPath, ...hostFlag], {
-      input: JSON.stringify(payload),
-      encoding: 'utf-8',
-      timeout: 120_000,
-    });
-    if (result.stdout) {
-      const rlOut = JSON.parse(result.stdout);
-      if (rlOut.decision === 'block') {
-        appendReplayEvent(payload.cwd || process.cwd(), {
-          host: HOST,
-          event: 'verify_gate_blocked',
-          source: 'ralph-loop',
-          reason: rlOut.reason || '',
-        });
-        output(rlOut);
-        return true;
-      }
-    }
-  } catch {}
-  return false;
+  return runGateScript({
+    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,
+  });
 }
 
 function runDeliveryGate(payload) {
-  try {
-    const gatePath = join(__dirname, 'delivery-gate.mjs');
-    if (!existsSync(gatePath)) return false;
-    const result = spawnSync(process.execPath, [gatePath], {
-      input: JSON.stringify(payload),
-      encoding: 'utf-8',
-      timeout: 30_000,
-    });
-    if (result.stdout) {
-      const gateOut = JSON.parse(result.stdout);
-      if (gateOut.decision === 'block') {
-        appendReplayEvent(payload.cwd || process.cwd(), {
-          host: HOST,
-          event: 'delivery_gate_blocked',
-          source: 'delivery-gate',
-          reason: gateOut.reason || '',
-        });
-        output(gateOut);
-        return true;
-      }
-    }
-  } catch {}
-  return false;
+  return runGateScript({
+    payload,
+    host: HOST,
+    scriptPath: join(__dirname, 'delivery-gate.mjs'),
+    source: 'delivery-gate',
+    blockEvent: 'delivery_gate_blocked',
+    timeout: 30_000,
+    appendReplayEvent,
+    output,
+  });
 }
 
-function readCompletionText(payload = {}) {
-  return payload['last-assistant-message']
-    || payload.last_assistant_message
-    || payload.lastAssistantMessage
-    || '';
+function readMainTurnState(cwd) {
+  const turnState = readTurnState(cwd);
+  return turnState?.role === 'main' ? turnState : null;
 }
 
-function shouldRunDeliveryGate(cwd, lastMsg) {
-  const turnState = readTurnState(cwd);
-  if (turnState?.role === 'main') {
-    return turnState.kind === 'complete';
-  }
-  return claimsTaskComplete(lastMsg);
+function consumeMainTurnState(cwd, turnState) {
+  if (turnState?.role === 'main') clearTurnState(cwd);
+}
+
+function shouldProcessCloseout(turnState) {
+  if (turnState) return turnState.kind === 'complete';
+  return false;
 }
 
 function cmdPreCompact() {
@@ -202,6 +186,7 @@ function cmdInject() {
     pkgRoot: PKG_ROOT,
     host: HOST,
     cwd,
+    payload,
   });
   clearRouteContext();
   clearTurnState(cwd);
@@ -210,24 +195,26 @@ function cmdInject() {
 
 function cmdStop() {
   const payload = readStdinJson();
-  const lastMsg = readCompletionText(payload);
   const cwd = payload.cwd || process.cwd();
+  const turnState = readMainTurnState(cwd);
+  const shouldProcess = shouldProcessCloseout(turnState);
   clearRouteContext();
-  if (runRalphLoop(payload)) {
-    playSound('warning');
-    desktopNotify('warning', buildNotifyExtra(payload));
+  if (shouldProcess && runRalphLoop(payload)) {
+    consumeMainTurnState(cwd, turnState);
+    notifyByLevel('warning', buildNotifyExtra(payload));
     return;
   }
-  if (shouldRunDeliveryGate(cwd, lastMsg) && runDeliveryGate(payload)) {
-    playSound('warning');
-    desktopNotify('warning', buildNotifyExtra(payload));
+  if (shouldProcess && runDeliveryGate(payload)) {
+    consumeMainTurnState(cwd, turnState);
+    notifyByLevel('warning', buildNotifyExtra(payload));
     return;
   }
 
   const settings = getSettings();
-  const level = settings.notify_level ?? 0;
-  if (level === 2 || level === 3) playSound('complete');
-  if (level === 1 || level === 3) desktopNotify('complete', buildNotifyExtra(payload));
+  if (shouldProcess) {
+    notifyByLevel('complete', buildNotifyExtra(payload), settings);
+  }
+  consumeMainTurnState(cwd, turnState);
   emptySuppress();
 }
 
@@ -248,31 +235,33 @@ function cmdCodexNotify() {
   if (shouldIgnoreCodexNotifyClient(client)) return;
 
   if (type === 'approval-requested') {
-    playSound('confirm');
-    desktopNotify('confirm', buildNotifyExtra(data));
+    notifyByLevel('confirm', buildNotifyExtra(data));
     return;
   }
   if (type !== 'agent-turn-complete') return;
 
   const cwd = data.cwd || process.cwd();
-  const turnState = readTurnState(cwd);
-  if (!turnState || turnState.role !== 'main') return;
+  const turnState = readMainTurnState(cwd);
+  if (!turnState) return;
+  if (turnState.kind !== 'complete') {
+    consumeMainTurnState(cwd, turnState);
+    return;
+  }
 
   const settings = getSettings();
-  if (turnState.kind === 'complete' && runRalphLoop({ cwd })) {
-    playSound('warning');
-    desktopNotify('warning', buildNotifyExtra(data));
+  if (runRalphLoop(data)) {
+    consumeMainTurnState(cwd, turnState);
+    notifyByLevel('warning', buildNotifyExtra(data), settings);
     return;
   }
-  if (turnState.kind === 'complete' && runDeliveryGate({ cwd })) {
-    playSound('warning');
-    desktopNotify('warning', buildNotifyExtra(data));
+  if (runDeliveryGate(data)) {
+    consumeMainTurnState(cwd, turnState);
+    notifyByLevel('warning', buildNotifyExtra(data), settings);
     return;
   }
 
-  const level = settings.notify_level ?? 0;
-  if (level === 2 || level === 3) playSound('complete');
-  if (level === 1 || level === 3) desktopNotify('complete', buildNotifyExtra(data));
+  notifyByLevel('complete', buildNotifyExtra(data), settings);
+  consumeMainTurnState(cwd, turnState);
 }
 
 const cmd = process.argv[2] || '';

package/scripts/project-storage.mjs

@@ -5,10 +5,13 @@ 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'
 
 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 {
@@ -31,6 +34,19 @@ 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)
@@ -54,6 +70,16 @@ 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)
@@ -87,6 +113,15 @@ 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
@@ -105,8 +140,38 @@ export function getProjectActivationDir(cwd) {
   return join(cwd, PROJECT_DIR_NAME)
 }
 
-export function getProjectStatePath(cwd) {
-  return join(getProjectActivationDir(cwd), 'STATE.md')
+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,
+  )
+
+  return {
+    stateScope: 'session',
+    stateSessionToken: sessionToken,
+    stateSessionMode: rawSessionToken ? 'host-session' : 'default',
+    stateBranch: branchName,
+    sessionDir,
+    statePath: join(sessionDir, 'STATE.md'),
+  }
+}
+
+export function getProjectStatePath(cwd, options = {}) {
+  return getProjectSessionStateScope(cwd, options).statePath
 }
 
 export function isRepoSharedProjectStore(cwd) {
@@ -122,10 +187,10 @@ export function getProjectStoreDir(cwd) {
   return join(homedir(), PROJECT_DIR_NAME, PROJECTS_DIR_NAME, projectKey.key)
 }
 
-export function getProjectStoreSummary(cwd) {
+export function getProjectStoreSummary(cwd, options = {}) {
   const activationDir = getProjectActivationDir(cwd)
   const storeDir = getProjectStoreDir(cwd)
-  const statePath = getProjectStatePath(cwd)
+  const stateScope = getProjectSessionStateScope(cwd, options)
   const projectKey = buildProjectKey(cwd)
   const projectStoreMode = getProjectStoreMode(cwd)
 
@@ -133,14 +198,20 @@ export function getProjectStoreSummary(cwd) {
     projectStoreMode,
     activationDir,
     storeDir,
-    statePath,
+    statePath: stateScope.statePath,
+    stateScope: stateScope.stateScope,
+    stateSessionToken: stateScope.stateSessionToken,
+    stateSessionMode: stateScope.stateSessionMode,
+    stateBranch: stateScope.stateBranch,
+    sessionStateDir: stateScope.sessionDir,
     usesSharedStore: projectStoreMode === 'repo-shared',
     projectKey: projectKey.key,
     repoRoot: projectKey.repoRoot,
     commonDir: projectKey.commonDir,
     promptActivationDir: formatPromptPath(activationDir),
     promptStoreDir: formatPromptPath(storeDir),
-    promptStatePath: formatPromptPath(statePath),
+    promptStatePath: formatPromptPath(stateScope.statePath),
+    promptSessionStateDir: formatPromptPath(stateScope.sessionDir),
   }
 }
 
@@ -203,14 +274,21 @@ export function describeProjectStoreFile(cwd, relativePath = '') {
   return `逻辑路径 \`${logicalPath}\`（实际存储：\`${actualPath}\`）`
 }
 
-export function buildProjectStorageHint(cwd) {
-  const summary = getProjectStoreSummary(cwd)
-  if (!summary.usesSharedStore) return ''
-  return `项目存储：\`project_store_mode=repo-shared\`；本地激活/运行态目录仍是 \`${summary.promptActivationDir}\`，知识库/方案目录改为 \`${summary.promptStoreDir}\`。`
+export function buildProjectStorageHint(cwd, options = {}) {
+  const summary = getProjectStoreSummary(cwd, options)
+  const hints = []
+  hints.push(`当前状态文件写入 \`${summary.promptStatePath}\``)
+  if (summary.stateSessionMode === 'default') {
+    hints.push(`当前宿主未提供稳定会话标识，因此使用分支默认位置 \`${summary.stateSessionToken}\``)
+  }
+  if (summary.usesSharedStore) {
+    hints.push(`项目存储：\`project_store_mode=repo-shared\`；本地激活/运行态目录仍是 \`${summary.promptActivationDir}\`，知识库/方案目录改为 \`${summary.promptStoreDir}\``)
+  }
+  return hints.join('。') + (hints.length > 0 ? '。' : '')
 }
 
-export function buildProjectStorageBlock(cwd) {
-  const summary = getProjectStoreSummary(cwd)
+export function buildProjectStorageBlock(cwd, options = {}) {
+  const summary = getProjectStoreSummary(cwd, options)
   if (!summary.usesSharedStore && !existsSync(summary.activationDir)) {
     return ''
   }
@@ -218,18 +296,32 @@ export function buildProjectStorageBlock(cwd) {
   const details = {
     project_store_mode: summary.projectStoreMode,
     activation_dir: summary.promptActivationDir,
+    state_scope: summary.stateScope,
     state_path: summary.promptStatePath,
+    state_branch: summary.stateBranch,
+    state_session_token: summary.stateSessionToken,
+    state_session_mode: summary.stateSessionMode,
+    session_state_dir: summary.promptSessionStateDir,
     knowledge_base_dir: summary.promptStoreDir,
     uses_shared_store: summary.usesSharedStore,
   }
 
+  const explanations = []
+  explanations.push('说明：状态文件只使用 `state_path`。')
+  if (summary.stateSessionMode === 'default') {
+    explanations.push('说明：当前宿主未提供稳定会话标识，因此使用分支默认位置。')
+  }
+  if (summary.usesSharedStore) {
+    explanations.push('说明：状态文件与 `.ralph-*.json` 写本地激活目录；`context.md`、`guidelines.md`、`DESIGN.md`、`verify.yaml`、`modules/`、`plans/`、`archive/` 写知识库/方案目录。')
+  } else {
+    explanations.push('说明：当前使用项目本地 `.helloagents/` 作为激活目录、知识库目录和方案目录。')
+  }
+
   return [
     '## 当前项目存储',
     '```json',
     JSON.stringify(details, null, 2),
     '```',
-    summary.usesSharedStore
-      ? '说明：`STATE.md` 与 `.ralph-*.json` 继续写本地激活目录；`context.md`、`guidelines.md`、`DESIGN.md`、`verify.yaml`、`modules/`、`plans/`、`archive/` 写知识库/方案目录。'
-      : '说明：当前使用项目本地 `.helloagents/` 作为激活目录、知识库目录和方案目录。',
+    ...explanations,
   ].join('\n')
 }

package/scripts/session-token.mjs

@@ -0,0 +1,73 @@
+const PAYLOAD_SESSION_KEYS = [
+  'sessionId',
+  'session_id',
+  'session',
+  'conversationId',
+  'conversation_id',
+  'conversation',
+  'threadId',
+  'thread_id',
+  'thread',
+  'windowId',
+  'window_id',
+  'window',
+  'tabId',
+  'tab_id',
+  'tab',
+  'requestId',
+  'request_id',
+]
+
+const ENV_SESSION_KEYS = [
+  'HELLOAGENTS_NOTIFY_SESSION_ID',
+  'WT_SESSION',
+  'TERM_SESSION_ID',
+  'KITTY_WINDOW_ID',
+  'ALACRITTY_WINDOW_ID',
+  'WINDOWID',
+  'WEZTERM_PANE',
+  'TAB_ID',
+]
+
+function readStringCandidate(input, key) {
+  if (!input || typeof input !== 'object') return ''
+  const value = input[key]
+  if (typeof value === 'string') return value.trim()
+  if (typeof value === 'number') return String(value)
+  return ''
+}
+
+export function sanitizeSessionToken(value = '') {
+  const raw = String(value).trim().replace(/^[#:\s]+/, '')
+  const segments = raw
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+  const cleaned = segments.length > 1
+    ? segments[segments.length - 1]
+    : raw.replace(/[^a-zA-Z0-9_-]/g, '')
+
+  if (!cleaned) return ''
+  if (/^\d+$/.test(cleaned)) return cleaned
+  return cleaned.slice(0, 8)
+}
+
+export function resolveSessionToken({
+  payload = {},
+  env = process.env,
+  ppid = process.ppid,
+  allowPpidFallback = true,
+} = {}) {
+  for (const key of PAYLOAD_SESSION_KEYS) {
+    const value = sanitizeSessionToken(readStringCandidate(payload, key))
+    if (value) return value
+  }
+
+  for (const key of ENV_SESSION_KEYS) {
+    const value = sanitizeSessionToken(env?.[key] || '')
+    if (value) return value
+  }
+
+  return allowPpidFallback && ppid ? String(ppid) : ''
+}
+
+export { ENV_SESSION_KEYS, PAYLOAD_SESSION_KEYS }