helloagents 3.0.3-beta.1 → 3.0.8-beta.1

package/scripts/notify-route.mjs

@@ -0,0 +1,111 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+export function resolveBootstrapFile(cwd, installMode) {
+  const isActivated = existsSync(join(cwd, '.helloagents'))
+  return (installMode === 'global' || isActivated) ? 'bootstrap.md' : 'bootstrap-lite.md'
+}
+
+function shouldBypassRoute(prompt) {
+  return !prompt || /^\[子代理任务\]/.test(prompt)
+}
+
+function buildHelpExtraRules(skillName) {
+  if (skillName !== 'help') return ''
+  return ' 这是 HelloAGENTS 的帮助命令，不是宿主 CLI 的内置帮助。仅显示 HelloAGENTS 的帮助和当前设置；优先使用当前上下文中已注入的“当前用户设置”，只有上下文不存在该信息时才尝试读取 ~/.helloagents/helloagents.json；自动激活技能说明仅在全局模式或已激活项目中生效。不要调用宿主 CLI 的帮助工具（如 cli_help 或 /help），不要使用子代理，不要读取项目文件；若受工作区限制无法读取配置，必须明确说明并按已知默认值或已注入设置展示。'
+}
+
+function routeExplicitCommand({
+  prompt,
+  cwd,
+  host,
+  pkgRoot,
+  settings,
+  resolveCanonicalCommandSkill,
+  writeRouteContext,
+  appendReplayEvent,
+  buildRouteInstruction,
+  suppress,
+}) {
+  const cmdMatch = prompt.match(/^~(\w+)/)
+  if (!cmdMatch) return false
+
+  const skillName = cmdMatch[1]
+  const canonicalSkillName = resolveCanonicalCommandSkill(skillName)
+  writeRouteContext({
+    cwd,
+    skillName: canonicalSkillName,
+    sourceSkillName: skillName,
+  })
+  appendReplayEvent(cwd, {
+    host,
+    event: 'command_route_selected',
+    source: 'route',
+    skillName: canonicalSkillName,
+    sourceSkillName: skillName,
+  })
+  suppress(buildRouteInstruction({
+    skillName,
+    extraRules: buildHelpExtraRules(skillName),
+    cwd,
+    pkgRoot,
+    host,
+    settings,
+  }))
+  return true
+}
+
+export function handleRouteCommand({
+  payload,
+  host,
+  pkgRoot,
+  settings,
+  buildRouteInstruction,
+  buildSemanticRouteInstruction,
+  resolveCanonicalCommandSkill,
+  writeRouteContext,
+  clearRouteContext,
+  appendReplayEvent,
+  getWorkflowRecommendation,
+  suppress,
+  emptySuppress,
+}) {
+  const prompt = (payload.prompt || '').trim()
+  const cwd = payload.cwd || process.cwd()
+  if (shouldBypassRoute(prompt)) {
+    clearRouteContext()
+    emptySuppress()
+    return
+  }
+
+  if (routeExplicitCommand({
+    prompt,
+    cwd,
+    host,
+    pkgRoot,
+    settings,
+    resolveCanonicalCommandSkill,
+    writeRouteContext,
+    appendReplayEvent,
+    buildRouteInstruction,
+    suppress,
+  })) {
+    return
+  }
+
+  const bootstrapFile = resolveBootstrapFile(cwd, settings.install_mode)
+  if (bootstrapFile === 'bootstrap.md') {
+    clearRouteContext()
+    appendReplayEvent(cwd, {
+      host,
+      event: 'semantic_route_prompted',
+      source: 'route',
+      recommendation: getWorkflowRecommendation(cwd),
+    })
+    suppress(buildSemanticRouteInstruction(cwd))
+    return
+  }
+
+  clearRouteContext()
+  emptySuppress()
+}

package/scripts/notify-shared.mjs

@@ -43,5 +43,3 @@ export function suppressedOutput(hookEventName, additionalContext) {
 export function emptySuppress() {
   output({ suppressOutput: true });
 }
-
-export function versionCheckBackground() {}

package/scripts/notify-source.mjs

@@ -0,0 +1,113 @@
+import { basename, normalize, resolve } from 'node:path'
+
+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 {
+    return normalize(resolve(filePath))
+  } catch {
+    return filePath
+  }
+}
+
+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 ''
+}
+
+function resolveProjectLabel(cwd = '') {
+  const normalized = normalizePath(cwd)
+  if (!normalized) return ''
+  const label = basename(normalized)
+  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 = '',
+  payload = {},
+  env = process.env,
+  ppid = process.ppid,
+} = {}) {
+  const hostLabel = HOST_LABELS[host] || 'Agent'
+  const projectLabel = resolveProjectLabel(readStringCandidate(payload, 'cwd') || cwd)
+  const sessionToken = resolveSessionToken(payload, env, ppid)
+  const parts = [hostLabel]
+
+  if (projectLabel) parts.push(projectLabel)
+  if (sessionToken) parts.push(`会话 ${sessionToken}`)
+
+  return {
+    hostLabel,
+    projectLabel,
+    sessionToken,
+    sourceLabel: parts.join(' · '),
+  }
+}

package/scripts/notify-ui.mjs

@@ -19,6 +19,36 @@ const NOTIFY_MESSAGES = {
 
 const WIN_APPID = 'HelloAgents.Notification';
 
+function escapeToastText(value = '') {
+  return String(value)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+function escapeAppleScriptText(value = '') {
+  return String(value).replace(/"/g, '\\"');
+}
+
+export function buildDesktopNotificationContent(event, extra) {
+  const options = extra && typeof extra === 'object'
+    ? extra
+    : { message: extra || '' };
+  const message = options.message || NOTIFY_MESSAGES[event] || event;
+  const title = options.title || 'HelloAgents 通知';
+  const sourceLabel = options.sourceLabel || '';
+  const body = sourceLabel ? `${sourceLabel}\n${message}` : message;
+  const toastLines = sourceLabel ? [sourceLabel, message] : [message];
+
+  return {
+    title,
+    message,
+    sourceLabel,
+    body,
+    toastLines,
+  };
+}
+
 function resolveWav(pkgRoot, event) {
   const p = join(pkgRoot, 'assets', 'sounds', `${event}.wav`);
   return existsSync(p) ? p : null;
@@ -53,14 +83,15 @@ function ensureWinAppId(pkgRoot) {
 }
 
 export function desktopNotify(pkgRoot, event, extra) {
-  const msg = extra || NOTIFY_MESSAGES[event] || event;
-  const title = 'HelloAgents 通知';
+  const notification = buildDesktopNotificationContent(event, extra);
   try {
     if (PLAT === 'win32') {
       ensureWinAppId(pkgRoot);
-      const safeMsg = msg.replace(/'/g, "''");
       const iconPath = join(pkgRoot, 'assets', 'icons', 'icon.png').replace(/\//g, '\\');
       const iconXml = existsSync(iconPath) ? `<image placement="appLogoOverride" src="${iconPath}" />` : '';
+      const textXml = notification.toastLines
+        .map((line) => `<text>${escapeToastText(line)}</text>`)
+        .join('\n      ');
       const ps = `
 [Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null
 [Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom, ContentType = WindowsRuntime] | Out-Null
@@ -69,7 +100,7 @@ $xml = @"
   <visual>
     <binding template="ToastGeneric">
       ${iconXml}
-      <text>${safeMsg}</text>
+      ${textXml}
     </binding>
   </visual>
 </toast>
@@ -81,11 +112,14 @@ $toast = [Windows.UI.Notifications.ToastNotification]::new($doc)
 `.trim();
       spawnSync('powershell', ['-NoProfile', '-c', ps], { stdio: 'ignore', windowsHide: true });
     } else if (PLAT === 'darwin') {
+      const subtitle = notification.sourceLabel
+        ? ` subtitle "${escapeAppleScriptText(notification.sourceLabel)}"`
+        : '';
       spawnSync('osascript', ['-e',
-        `display notification "${msg.replace(/"/g, '\\"')}" with title "${title}"`],
+        `display notification "${escapeAppleScriptText(notification.message)}" with title "${escapeAppleScriptText(notification.title)}"${subtitle}`],
         { stdio: 'ignore' });
     } else {
-      const result = spawnSync('notify-send', [title, msg], { stdio: 'ignore' });
+      const result = spawnSync('notify-send', [notification.title, notification.body], { stdio: 'ignore' });
       if (result.status !== 0) process.stderr.write('\x07');
     }
   } catch { process.stderr.write('\x07'); }

package/scripts/notify.mjs

@@ -8,9 +8,15 @@ 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 { buildCompactionContext, buildInjectContext, buildRouteInstruction, detectNewProjectRoute } from './notify-context.mjs';
-import { claimsTaskComplete, shouldIgnoreCodexNotifyClient, shouldIgnoreFormattedSubagent } from './notify-events.mjs';
-import { readSettings, readStdinJson, output, suppressedOutput, emptySuppress, versionCheckBackground } from './notify-shared.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 { handleRouteCommand, resolveBootstrapFile } from './notify-route.mjs';
+import { readSettings, readStdinJson, output, suppressedOutput, emptySuppress } from './notify-shared.mjs';
+import { clearRouteContext, 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';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -31,6 +37,18 @@ const EVENT_NAME = {
 const playSound = (event) => _playSound(PKG_ROOT, event);
 const desktopNotify = (event, extra) => _desktopNotify(PKG_ROOT, event, extra);
 
+function buildNotifyExtra(payload = {}, options = {}) {
+  const source = resolveNotificationSource({
+    host: HOST,
+    cwd: payload.cwd || process.cwd(),
+    payload,
+  });
+  return {
+    message: options.message || '',
+    sourceLabel: source.sourceLabel,
+  };
+}
+
 function getSettings() {
   return readSettings(CONFIG_FILE);
 }
@@ -41,7 +59,8 @@ function runRalphLoop(payload) {
   try {
     const rlPath = join(__dirname, 'ralph-loop.mjs');
     if (!existsSync(rlPath)) return false;
-    const result = spawnSync(process.execPath, [rlPath, ...(IS_GEMINI ? ['--gemini'] : [])], {
+    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,
@@ -49,6 +68,12 @@ function runRalphLoop(payload) {
     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;
       }
@@ -57,17 +82,52 @@ function runRalphLoop(payload) {
   return false;
 }
 
-function resolveBootstrapFile(cwd, settings) {
-  const isGlobal = settings.install_mode === 'global';
-  const isActivated = existsSync(join(cwd, '.helloagents'));
-  return (isGlobal || isActivated) ? 'bootstrap.md' : 'bootstrap-lite.md';
+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;
+}
+
+function readCompletionText(payload = {}) {
+  return payload['last-assistant-message']
+    || payload.last_assistant_message
+    || payload.lastAssistantMessage
+    || '';
+}
+
+function shouldRunDeliveryGate(cwd, lastMsg) {
+  const turnState = readTurnState(cwd);
+  if (turnState?.role === 'main') {
+    return turnState.kind === 'complete';
+  }
+  return claimsTaskComplete(lastMsg);
 }
 
 function cmdPreCompact() {
   const payload = readStdinJson();
   const cwd = payload.cwd || process.cwd();
   const settings = getSettings();
-  const bootstrapFile = resolveBootstrapFile(cwd, settings);
+  const bootstrapFile = resolveBootstrapFile(cwd, settings.install_mode);
   const context = buildCompactionContext({
     payload,
     pkgRoot: PKG_ROOT,
@@ -75,50 +135,36 @@ function cmdPreCompact() {
     bootstrapFile,
     host: HOST,
   });
+  appendReplayEvent(cwd, {
+    host: HOST,
+    event: 'pre_compact_snapshot',
+    source: 'pre-compact',
+    details: {
+      bootstrapFile,
+      installMode: settings.install_mode || '',
+    },
+  });
   suppressedOutput(EVENT_NAME.PreCompact, context);
 }
 
 function cmdRoute() {
   const payload = readStdinJson();
-  const prompt = (payload.prompt || '').trim();
-  const cwd = payload.cwd || process.cwd();
-  const settings = getSettings();
-  if (!prompt) {
-    emptySuppress();
-    return;
-  }
-  if (/^\[子代理任务\]/.test(prompt)) {
-    emptySuppress();
-    return;
-  }
-
-  const cmdMatch = prompt.match(/^~(\w+)/);
-  if (cmdMatch) {
-    const skillName = cmdMatch[1];
-    const extraRules = skillName === 'help'
-      ? ' 这是 HelloAGENTS 的帮助命令，不是宿主 CLI 的内置帮助。适用条件：仅显示 HelloAGENTS 的帮助和当前设置；优先使用当前上下文中已注入的“当前用户设置”，只有上下文不存在该信息时才尝试读取 ~/.helloagents/helloagents.json；自动激活技能说明仅在全局模式，或当前项目已存在 .helloagents/（例如执行过 ~wiki 或 ~init）时生效。排除条件：不要调用宿主 CLI 的帮助工具（如 cli_help 或 /help），不要使用子代理，不要读取项目文件；若受工作区限制无法读取配置，必须明确说明并按已知默认值或已注入设置展示；纯标准模式未激活项目不会自动触发。'
-      : '';
-    suppressedOutput(EVENT_NAME.UserPromptSubmit, buildRouteInstruction({
-      skillName,
-      extraRules,
-      cwd,
-      pkgRoot: PKG_ROOT,
-      host: HOST,
-      settings,
-    }));
-    return;
-  }
-
-  const bootstrapFile = resolveBootstrapFile(cwd, settings);
-  if (bootstrapFile === 'bootstrap.md') {
-    const routeMessage = detectNewProjectRoute(prompt);
-    if (routeMessage) {
-      suppressedOutput(EVENT_NAME.UserPromptSubmit, routeMessage);
-      return;
-    }
-  }
-
-  emptySuppress();
+  clearTurnState(payload.cwd || process.cwd());
+  handleRouteCommand({
+    payload,
+    host: HOST,
+    pkgRoot: PKG_ROOT,
+    settings: getSettings(),
+    buildRouteInstruction,
+    buildSemanticRouteInstruction,
+    resolveCanonicalCommandSkill,
+    writeRouteContext,
+    clearRouteContext,
+    appendReplayEvent,
+    getWorkflowRecommendation,
+    suppress: (context) => suppressedOutput(EVENT_NAME.UserPromptSubmit, context),
+    emptySuppress,
+  });
 }
 
 function cmdInject() {
@@ -126,13 +172,29 @@ function cmdInject() {
   const source = payload.source || 'startup';
   const cwd = payload.cwd || process.cwd();
   const settings = getSettings();
-  const bootstrapFile = resolveBootstrapFile(cwd, settings);
+  const bootstrapFile = resolveBootstrapFile(cwd, settings.install_mode);
 
   let bootstrap = '';
   try {
     bootstrap = readFileSync(join(PKG_ROOT, bootstrapFile), 'utf-8');
   } catch {}
 
+  startReplaySession(cwd, {
+    host: HOST,
+    source,
+    bootstrapFile,
+    installMode: settings.install_mode || '',
+  });
+  appendReplayEvent(cwd, {
+    host: HOST,
+    event: 'session_injected',
+    source,
+    details: {
+      bootstrapFile,
+      installMode: settings.install_mode || '',
+      activatedProject: existsSync(join(cwd, '.helloagents')),
+    },
+  });
   const context = buildInjectContext({
     source,
     bootstrap,
@@ -141,22 +203,31 @@ function cmdInject() {
     host: HOST,
     cwd,
   });
+  clearRouteContext();
+  clearTurnState(cwd);
   suppressedOutput(EVENT_NAME.SessionStart, context || undefined);
-  versionCheckBackground();
 }
 
 function cmdStop() {
   const payload = readStdinJson();
+  const lastMsg = readCompletionText(payload);
+  const cwd = payload.cwd || process.cwd();
+  clearRouteContext();
   if (runRalphLoop(payload)) {
     playSound('warning');
-    desktopNotify('warning');
+    desktopNotify('warning', buildNotifyExtra(payload));
+    return;
+  }
+  if (shouldRunDeliveryGate(cwd, lastMsg) && runDeliveryGate(payload)) {
+    playSound('warning');
+    desktopNotify('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');
+  if (level === 1 || level === 3) desktopNotify('complete', buildNotifyExtra(payload));
   emptySuppress();
 }
 
@@ -165,7 +236,7 @@ function cmdSound() {
 }
 
 function cmdDesktop() {
-  desktopNotify(process.argv[3] || 'complete');
+  desktopNotify(process.argv[3] || 'complete', buildNotifyExtra({ cwd: process.cwd() }));
 }
 
 function cmdCodexNotify() {
@@ -178,30 +249,32 @@ function cmdCodexNotify() {
 
   if (type === 'approval-requested') {
     playSound('confirm');
-    desktopNotify('confirm');
+    desktopNotify('confirm', buildNotifyExtra(data));
     return;
   }
   if (type !== 'agent-turn-complete') return;
 
-  const lastMsg = data['last-assistant-message'] || '';
-  const settings = getSettings();
-  if (shouldIgnoreFormattedSubagent(lastMsg, settings.output_format !== false)) return;
-
   const cwd = data.cwd || process.cwd();
-  if (claimsTaskComplete(lastMsg) && runRalphLoop({ cwd })) {
+  const turnState = readTurnState(cwd);
+  if (!turnState || turnState.role !== 'main') return;
+
+  const settings = getSettings();
+  if (turnState.kind === 'complete' && runRalphLoop({ cwd })) {
     playSound('warning');
-    desktopNotify('warning');
+    desktopNotify('warning', buildNotifyExtra(data));
+    return;
+  }
+  if (turnState.kind === 'complete' && runDeliveryGate({ cwd })) {
+    playSound('warning');
+    desktopNotify('warning', buildNotifyExtra(data));
     return;
   }
 
   const level = settings.notify_level ?? 0;
   if (level === 2 || level === 3) playSound('complete');
-  if (level === 1 || level === 3) desktopNotify('complete');
-  versionCheckBackground();
+  if (level === 1 || level === 3) desktopNotify('complete', buildNotifyExtra(data));
 }
 
-function cmdVersionCheck() {}
-
 const cmd = process.argv[2] || '';
 
 switch (cmd) {
@@ -212,7 +285,6 @@ switch (cmd) {
   case 'sound':         cmdSound(); break;
   case 'desktop':       cmdDesktop(); break;
   case 'codex-notify':  cmdCodexNotify(); break;
-  case 'version-check': cmdVersionCheck(); break;
   default:
     process.stderr.write(`notify.mjs: unknown command "${cmd}"\n`);
     process.exit(1);