helloagents 3.0.12 → 3.0.16-beta.1

package/scripts/turn-state.mjs

@@ -1,11 +1,16 @@
-import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
-import { dirname, join, normalize, resolve } from 'node:path'
-import { homedir } from 'node:os'
+import { readFileSync } from 'node:fs'
+import { normalize, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-import { appendReplayEvent } from './replay-state.mjs'
+import {
+  appendSessionEvent,
+  clearCapsuleSection,
+  getSessionCapsulePath,
+  getRuntimeScope,
+  readCapsuleSection,
+  writeCapsuleSection,
+} from './session-capsule.mjs'
 
-const TURN_STATE_PATH = join(homedir(), '.helloagents', 'runtime', 'turn-state.json')
 const TURN_STATE_TTL_MS = 30 * 60 * 1000
 const VALID_KINDS = new Set(['complete', 'waiting', 'blocked', 'progress'])
 const VALID_ROLES = new Set(['main', 'subagent'])
@@ -19,38 +24,31 @@ const VALID_REASON_CATEGORIES = new Set([
   'external-dependency',
   'error',
 ])
+const HELP_TEXT = `Usage:
+  helloagents-turn-state write --kind complete --role main
+  helloagents-turn-state write --kind waiting --role main --reason-category missing-input --reason "..."
+  echo {"kind":"complete","role":"main"} | helloagents-turn-state write
+  helloagents-turn-state read [--cwd <path>]
+  helloagents-turn-state clear [--cwd <path>]
+
+Options:
+  --cwd <path>
+  --kind <complete|waiting|blocked|progress>
+  --role <main|subagent>
+  --phase <name>
+  --source <name>
+  --reason-category <category>
+  --reason <text>
+  --requires-delivery-gate
+  --blocker-target <text>
+  --blocker-evidence <text>
+  --blocker-required-action <text>
+`
 
 function normalizePath(filePath = '') {
   return filePath ? normalize(resolve(filePath)) : ''
 }
 
-function ensureRuntimeDir() {
-  mkdirSync(dirname(TURN_STATE_PATH), { recursive: true })
-}
-
-function readStore() {
-  try {
-    return JSON.parse(readFileSync(TURN_STATE_PATH, 'utf-8'))
-  } catch {
-    return {}
-  }
-}
-
-function writeStore(store) {
-  const keys = Object.keys(store)
-  if (keys.length === 0) {
-    rmSync(TURN_STATE_PATH, { force: true })
-    return
-  }
-
-  ensureRuntimeDir()
-  writeFileSync(TURN_STATE_PATH, `${JSON.stringify(store, null, 2)}\n`, 'utf-8')
-}
-
-function getTurnStateKey(cwd = process.cwd()) {
-  return normalizePath(cwd)
-}
-
 function normalizeTurnState(input = {}) {
   const kind = typeof input.kind === 'string' ? input.kind.trim().toLowerCase() : ''
   const role = typeof input.role === 'string' ? input.role.trim().toLowerCase() : 'main'
@@ -58,6 +56,7 @@ function normalizeTurnState(input = {}) {
     ? input.reasonCategory.trim().toLowerCase()
     : ''
   const reason = typeof input.reason === 'string' ? input.reason.trim() : ''
+  const blocker = normalizeBlocker(input.blocker)
 
   return {
     kind: VALID_KINDS.has(kind) ? kind : '',
@@ -67,59 +66,64 @@ function normalizeTurnState(input = {}) {
     requiresDeliveryGate: Boolean(input.requiresDeliveryGate),
     reasonCategory: VALID_REASON_CATEGORIES.has(reasonCategory) ? reasonCategory : '',
     reason,
+    ...(blocker ? { blocker } : {}),
   }
 }
 
-function pruneInvalidEntry(store, key) {
-  delete store[key]
-  writeStore(store)
-}
+function normalizeBlocker(input = {}) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return null
+
+  const target = typeof input.target === 'string' ? input.target.trim() : ''
+  const evidence = typeof input.evidence === 'string' ? input.evidence.trim() : ''
+  const requiredAction = typeof input.requiredAction === 'string'
+    ? input.requiredAction.trim()
+    : ''
 
-export function clearTurnState(cwd = process.cwd()) {
-  const key = getTurnStateKey(cwd)
-  if (!key) return false
-  const store = readStore()
-  if (!(key in store)) return false
-  delete store[key]
-  writeStore(store)
-  return true
+  if (!target && !evidence && !requiredAction) return null
+  return { target, evidence, requiredAction }
 }
 
-export function readTurnState(cwd = process.cwd(), { now = Date.now() } = {}) {
-  const key = getTurnStateKey(cwd)
-  if (!key) return null
+export function clearTurnState(cwd = process.cwd(), options = {}) {
+  return clearCapsuleSection(cwd, 'turn', options)
+}
 
-  const store = readStore()
-  const entry = store[key]
+export function readTurnState(cwd = process.cwd(), { now = Date.now(), ...options } = {}) {
+  const entry = readCapsuleSection(cwd, 'turn', options)
   if (!entry?.cwd || !entry?.kind || !entry?.updatedAt) {
-    if (entry) pruneInvalidEntry(store, key)
     return null
   }
 
   const updatedAt = Date.parse(entry.updatedAt)
   if (!Number.isFinite(updatedAt) || (now - updatedAt > TURN_STATE_TTL_MS)) {
-    pruneInvalidEntry(store, key)
+    clearTurnState(cwd, options)
     return null
   }
 
   const normalized = normalizeTurnState(entry)
   if (!normalized.kind) {
-    pruneInvalidEntry(store, key)
+    clearTurnState(cwd, options)
     return null
   }
 
   return {
     cwd: normalizePath(entry.cwd),
+    key: entry.key || '',
+    path: getSessionCapsulePath(cwd, options),
     updatedAt: entry.updatedAt,
     ...normalized,
   }
 }
 
 export function writeTurnState(cwd = process.cwd(), input = {}) {
-  const key = getTurnStateKey(cwd)
+  const runtimeOptions = {
+    payload: input.payload && typeof input.payload === 'object' ? input.payload : input,
+    env: input.env || process.env,
+    ppid: input.ppid ?? process.ppid,
+  }
+  const scope = getRuntimeScope(cwd, runtimeOptions)
   const normalized = normalizeTurnState(input)
-  if (!key || !normalized.kind) {
-    throw new Error('turn-state requires cwd and a valid kind')
+  if (!normalized.kind) {
+    throw new Error('turn-state write requires a valid kind. Example: helloagents-turn-state write --kind complete --role main')
   }
   if (
     (normalized.kind === 'waiting' || normalized.kind === 'blocked')
@@ -128,16 +132,16 @@ export function writeTurnState(cwd = process.cwd(), input = {}) {
     throw new Error('turn-state waiting/blocked requires reasonCategory and reason')
   }
 
-  const store = readStore()
   const payload = {
-    cwd: key,
+    cwd: normalizePath(cwd),
+    key: scope.key,
+    scope: scope.scope,
     updatedAt: new Date().toISOString(),
     ...normalized,
   }
-  store[key] = payload
-  writeStore(store)
+  writeCapsuleSection(cwd, 'turn', payload, runtimeOptions)
 
-  appendReplayEvent(cwd, {
+  appendSessionEvent(cwd, {
     event: 'turn_state_written',
     source: normalized.source,
     details: {
@@ -154,23 +158,130 @@ export function writeTurnState(cwd = process.cwd(), input = {}) {
 }
 
 function readStdinJson() {
+  if (process.stdin.isTTY) return {}
   try {
-    return JSON.parse(readFileSync(0, 'utf-8'))
+    const text = readFileSync(0, 'utf-8').trim()
+    return text ? JSON.parse(text) : {}
   } catch {
     return {}
   }
 }
 
+function normalizeOptionName(rawName = '') {
+  return rawName.replace(/^-+/, '').replace(/-([a-z])/g, (_, char) => char.toUpperCase())
+}
+
+function readOptionValue(args, index, name) {
+  const raw = args[index]
+  const eqIndex = raw.indexOf('=')
+  if (eqIndex >= 0) {
+    return { value: raw.slice(eqIndex + 1), nextIndex: index }
+  }
+
+  const next = args[index + 1]
+  if (next === undefined || next.startsWith('--')) {
+    return { value: true, nextIndex: index }
+  }
+  return { value: next, nextIndex: index + 1 }
+}
+
+function assignCliOption(input, name, value) {
+  const key = normalizeOptionName(name)
+  const aliases = {
+    reasonCategory: 'reasonCategory',
+    requiresDeliveryGate: 'requiresDeliveryGate',
+    blockerTarget: 'blocker.target',
+    blockerEvidence: 'blocker.evidence',
+    blockerRequiredAction: 'blocker.requiredAction',
+  }
+  const target = aliases[key] || key
+  const allowed = new Set([
+    'cwd',
+    'kind',
+    'role',
+    'phase',
+    'source',
+    'reasonCategory',
+    'reason',
+    'requiresDeliveryGate',
+    'blocker.target',
+    'blocker.evidence',
+    'blocker.requiredAction',
+  ])
+  if (!allowed.has(target)) {
+    throw new Error(`unknown turn-state option: --${name}`)
+  }
+
+  if (target.startsWith('blocker.')) {
+    input.blocker = input.blocker || {}
+    input.blocker[target.slice('blocker.'.length)] = String(value)
+    return
+  }
+
+  input[target] = target === 'requiresDeliveryGate'
+    ? value === true || String(value).toLowerCase() === 'true'
+    : String(value)
+}
+
+function parseCliArgs(args = []) {
+  const input = {}
+  let wantsHelp = false
+
+  for (let index = 0; index < args.length; index += 1) {
+    const raw = args[index]
+    if (raw === '--help' || raw === '-h') {
+      wantsHelp = true
+      continue
+    }
+    if (!raw.startsWith('--')) {
+      throw new Error(`unexpected turn-state argument: ${raw}`)
+    }
+
+    const optionName = raw.slice(2).split('=')[0]
+    const { value, nextIndex } = readOptionValue(args, index, optionName)
+    assignCliOption(input, optionName, value)
+    index = nextIndex
+  }
+
+  return { input, wantsHelp }
+}
+
+function mergeInputs(stdinInput, cliInput) {
+  return {
+    ...stdinInput,
+    ...cliInput,
+    blocker: {
+      ...(stdinInput.blocker || {}),
+      ...(cliInput.blocker || {}),
+    },
+  }
+}
+
+function printHelp() {
+  process.stdout.write(HELP_TEXT)
+}
+
 function main() {
   const command = process.argv[2] || ''
-  const input = readStdinJson()
+  if (!command || command === '--help' || command === '-h' || command === 'help') {
+    printHelp()
+    return
+  }
+
+  const { input: cliInput, wantsHelp } = parseCliArgs(process.argv.slice(3))
+  if (wantsHelp) {
+    printHelp()
+    return
+  }
+
+  const input = mergeInputs(readStdinJson(), cliInput)
   const cwd = input.cwd || process.cwd()
 
   if (command === 'write') {
     const payload = writeTurnState(cwd, input)
     process.stdout.write(JSON.stringify({
       suppressOutput: true,
-      path: TURN_STATE_PATH,
+      path: getSessionCapsulePath(cwd, input),
       payload,
     }))
     return
@@ -179,7 +290,7 @@ function main() {
   if (command === 'clear') {
     process.stdout.write(JSON.stringify({
       suppressOutput: true,
-      cleared: clearTurnState(cwd),
+      cleared: clearTurnState(cwd, input),
     }))
     return
   }
@@ -187,11 +298,19 @@ function main() {
   if (command === 'read') {
     process.stdout.write(JSON.stringify({
       suppressOutput: true,
-      state: readTurnState(cwd),
+      state: readTurnState(cwd, input),
     }))
+    return
   }
+
+  throw new Error(`unknown turn-state command: ${command}`)
 }
 
 if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
-  main()
+  try {
+    main()
+  } catch (error) {
+    process.stderr.write(`${error.message}\n\n${HELP_TEXT}`)
+    process.exit(1)
+  }
 }

package/scripts/turn-stop-gate.mjs

@@ -30,7 +30,7 @@ function buildWorkflowHint(cwd) {
   if (!recommendation) return ''
   return [
     `当前工作流：${recommendation.summary}`,
-    `建议路径：${recommendation.nextPath}`,
+    `应执行路径：${recommendation.nextPath}`,
     recommendation.guidance,
   ].filter(Boolean).join('\n')
 }
@@ -43,16 +43,27 @@ function buildBlockReason(routeContext, detail, cwd) {
     detail,
     workflowHint,
     '若无真实阻塞，请继续沿当前路径执行。',
-    `若确需停下，先调用 \`scripts/turn-state.mjs write\` 写结构化状态：\`kind=waiting\` 或 \`kind=blocked\`，并同时填写 \`reasonCategory\` 与 \`reason\`。`,
+    `若确需停下，先调用 \`helloagents-turn-state write --kind waiting --role main --reason-category <category> --reason "..."\` 写结构化状态；阻塞则把 \`waiting\` 改为 \`blocked\`。`,
     `允许的 \`reasonCategory\`：${ALLOWED_STOP_REASON_CATEGORIES.join(' | ')}。`,
   ].filter(Boolean).join('\n')
 }
 
-function getMainTurnState(cwd) {
-  const turnState = readTurnState(cwd)
+function getMainTurnState(cwd, payload = {}) {
+  const turnState = readTurnState(cwd, { payload })
   return turnState?.role === 'main' ? turnState : null
 }
 
+function hasStructuredBlocker(turnState) {
+  const blocker = turnState?.blocker
+  return Boolean(
+    blocker
+    && typeof blocker === 'object'
+    && blocker.target
+    && blocker.evidence
+    && blocker.requiredAction,
+  )
+}
+
 function validateTurnState(routeContext, turnState, cwd) {
   if (!turnState) {
     return buildBlockReason(routeContext, '缺少主代理 turn-state。', cwd)
@@ -62,6 +73,13 @@ function validateTurnState(routeContext, turnState, cwd) {
   }
   if (turnState.kind === 'waiting' || turnState.kind === 'blocked') {
     if (turnState.reasonCategory && turnState.reason) {
+      if (!hasStructuredBlocker(turnState)) {
+        return buildBlockReason(
+          routeContext,
+          '当前 waiting/blocked 缺少结构化 `blocker.target`、`blocker.evidence` 或 `blocker.requiredAction`，不能证明存在可核实的真实阻塞。',
+          cwd,
+        )
+      }
       return ''
     }
     return buildBlockReason(
@@ -76,14 +94,14 @@ function validateTurnState(routeContext, turnState, cwd) {
 function main() {
   const payload = readStdinJson()
   const cwd = payload.cwd || process.cwd()
-  const routeContext = getApplicableRouteContext({ cwd })
+  const routeContext = getApplicableRouteContext({ cwd, payload })
 
   if (!routeContext || !ENFORCED_COMMANDS.has(routeContext.skillName)) {
     process.stdout.write(JSON.stringify({ decision: 'continue' }))
     return
   }
 
-  const reason = validateTurnState(routeContext, getMainTurnState(cwd), cwd)
+  const reason = validateTurnState(routeContext, getMainTurnState(cwd, payload), cwd)
   process.stdout.write(JSON.stringify(reason ? { decision: 'block', reason } : { decision: 'continue' }))
 }
 

package/scripts/verify-state.mjs

@@ -1,27 +1,33 @@
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
-import { execSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { appendReplayEvent } from './replay-state.mjs'
-import { getProjectVerifyYamlPath } from './project-storage.mjs'
-
-export const VERIFY_EVIDENCE_FILE_NAME = '.ralph-verify.json'
-const VERIFY_EVIDENCE_MAX_AGE_MS = 30 * 60 * 1000
+import {
+  getProjectVerifyYamlPath,
+} from './project-storage.mjs'
+import {
+  captureWorkspaceFingerprint,
+  clearRuntimeEvidence,
+  getRuntimeEvidencePath,
+  getRuntimeEvidenceRelativePath,
+  readRuntimeEvidence,
+  validateEvidenceFingerprint,
+  validateEvidenceTimestamp,
+  writeRuntimeEvidence,
+} from './runtime-artifacts.mjs'
+
+export const VERIFY_EVIDENCE_FILE_NAME = 'verify.json'
 const SHELL_OPERATORS = /[;&|`$(){}\n\r]/
 
-export function getVerifyEvidencePath(cwd) {
-  return join(cwd, '.helloagents', VERIFY_EVIDENCE_FILE_NAME)
+export function getVerifyEvidencePath(cwd, options = {}) {
+  return getRuntimeEvidencePath(cwd, VERIFY_EVIDENCE_FILE_NAME, options)
 }
 
-export function readVerifyEvidence(cwd) {
-  try {
-    return JSON.parse(readFileSync(getVerifyEvidencePath(cwd), 'utf-8'))
-  } catch {
-    return null
-  }
+export function readVerifyEvidence(cwd, options = {}) {
+  return readRuntimeEvidence(cwd, VERIFY_EVIDENCE_FILE_NAME, options)
 }
 
-export function clearVerifyEvidence(cwd) {
-  rmSync(getVerifyEvidencePath(cwd), { force: true })
+export function clearVerifyEvidence(cwd, options = {}) {
+  clearRuntimeEvidence(cwd, VERIFY_EVIDENCE_FILE_NAME, options)
 }
 
 function loadVerifyYaml(cwd) {
@@ -89,34 +95,7 @@ export function hasUnsafeVerifyCommand(commands = []) {
   return commands.some((cmd) => SHELL_OPERATORS.test(cmd))
 }
 
-function readGitDiffStat(cwd, args) {
-  try {
-    return execSync(`git diff --stat ${args}`.trim(), {
-      cwd,
-      encoding: 'utf-8',
-      timeout: 10_000,
-      stdio: ['pipe', 'pipe', 'pipe'],
-    }).trim()
-  } catch {
-    return null
-  }
-}
-
-export function captureWorkspaceFingerprint(cwd) {
-  const unstaged = readGitDiffStat(cwd, 'HEAD')
-  const staged = readGitDiffStat(cwd, '--cached')
-  const available = unstaged !== null || staged !== null
-
-  return {
-    available,
-    unstaged: unstaged || '',
-    staged: staged || '',
-    combined: `${unstaged || ''}\n---\n${staged || ''}`.trim(),
-  }
-}
-
-export function writeVerifyEvidence(cwd, { commands = [], fastOnly = false, source = 'ralph-loop' } = {}) {
-  mkdirSync(join(cwd, '.helloagents'), { recursive: true })
+export function writeVerifyEvidence(cwd, { commands = [], fastOnly = false, source = 'ralph-loop' } = {}, options = {}) {
   const payload = {
     updatedAt: new Date().toISOString(),
     commands,
@@ -124,15 +103,16 @@ export function writeVerifyEvidence(cwd, { commands = [], fastOnly = false, sour
     source,
     fingerprint: captureWorkspaceFingerprint(cwd),
   }
-  writeFileSync(getVerifyEvidencePath(cwd), `${JSON.stringify(payload, null, 2)}\n`, 'utf-8')
+  writeRuntimeEvidence(cwd, VERIFY_EVIDENCE_FILE_NAME, payload, options)
   appendReplayEvent(cwd, {
     event: 'verify_evidence_written',
     source,
+    payload: options.payload || {},
     details: {
       commands,
       fastOnly,
     },
-    artifacts: ['.helloagents/.ralph-verify.json'],
+    artifacts: [getRuntimeEvidenceRelativePath(cwd, VERIFY_EVIDENCE_FILE_NAME, options)],
   })
 }
 
@@ -142,7 +122,7 @@ function validateVerifyEvidencePresence(commands, evidence) {
     required: true,
     status: 'missing',
     commands,
-    details: ['missing successful verification evidence for the current workflow'],
+    details: ['缺少当前工作流的成功验证证据'],
   }
 }
 
@@ -153,51 +133,20 @@ function validateVerifyEvidenceFreshness(cwd, commands, evidence, now) {
       status: 'fast-only',
       commands,
       evidence,
-      details: ['latest verification evidence only covers subagent fast checks'],
+      details: ['最新验证证据只覆盖子代理快速检查'],
     }
   }
 
-  const updatedAt = Date.parse(evidence.updatedAt || '')
-  if (!Number.isFinite(updatedAt)) {
-    return {
-      required: true,
-      status: 'invalid',
-      commands,
-      evidence,
-      details: ['verification evidence timestamp is invalid'],
-    }
-  }
-  if (now - updatedAt > VERIFY_EVIDENCE_MAX_AGE_MS) {
-    return {
-      required: true,
-      status: 'stale-time',
-      commands,
-      evidence,
-      details: ['verification evidence is older than 30 minutes'],
-    }
-  }
-  return null
+  const timestampError = validateEvidenceTimestamp(evidence, now, '验证证据')
+  return timestampError ? { ...timestampError, commands } : null
 }
 
 function validateVerifyFingerprint(cwd, commands, evidence) {
-  const currentFingerprint = captureWorkspaceFingerprint(cwd)
-  if (
-    currentFingerprint.available
-    && evidence.fingerprint?.available
-    && currentFingerprint.combined !== evidence.fingerprint.combined
-  ) {
-    return {
-      required: true,
-      status: 'stale-diff',
-      commands,
-      evidence,
-      details: ['workspace diff changed after the last successful verification evidence'],
-    }
-  }
-  return null
+  const fingerprintError = validateEvidenceFingerprint(cwd, evidence, '成功验证证据')
+  return fingerprintError ? { ...fingerprintError, commands } : null
 }
 
-export function getVerifyEvidenceStatus(cwd, now = Date.now()) {
+export function getVerifyEvidenceStatus(cwd, { now = Date.now(), ...options } = {}) {
   const commands = detectCommands(cwd)
   if (!commands.length) {
     return {
@@ -207,7 +156,7 @@ export function getVerifyEvidenceStatus(cwd, now = Date.now()) {
     }
   }
 
-  const evidence = readVerifyEvidence(cwd)
+  const evidence = readVerifyEvidence(cwd, options)
   const missingError = validateVerifyEvidencePresence(commands, evidence)
   if (missingError) return missingError