helloagents 3.0.12 → 3.0.15-beta.1

package/scripts/replay-state.mjs

@@ -1,76 +1,11 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
-import { dirname, join, normalize, resolve } from 'node:path'
-import { homedir } from 'node:os'
+import { dirname } from 'node:path'
 
-const RUNTIME_DIR = join(homedir(), '.helloagents', 'runtime')
-const REPLAY_CONTEXT_PATH = join(RUNTIME_DIR, 'replay-context.json')
-const REPLAY_SESSION_TTL_MS = 12 * 60 * 60 * 1000
-const MAX_REPLAY_SESSIONS = 3
-
-function normalizePath(filePath = '') {
-  return filePath ? normalize(resolve(filePath)) : ''
-}
-
-function ensureRuntimeDir() {
-  mkdirSync(dirname(REPLAY_CONTEXT_PATH), { recursive: true })
-}
-
-function readReplayContext() {
-  try {
-    return JSON.parse(readFileSync(REPLAY_CONTEXT_PATH, 'utf-8'))
-  } catch {
-    return {}
-  }
-}
-
-function writeReplayContext(context) {
-  ensureRuntimeDir()
-  writeFileSync(REPLAY_CONTEXT_PATH, `${JSON.stringify(context, null, 2)}\n`, 'utf-8')
-}
-
-function getReplayKey(cwd, host = '') {
-  return `${normalizePath(cwd)}::${host || 'unknown'}`
-}
-
-function findLatestReplaySession(context, cwd) {
-  const normalizedCwd = normalizePath(cwd)
-  const entries = Object.values(context)
-    .filter((entry) => entry?.cwd === normalizedCwd && entry.filePath && existsSync(entry.filePath))
-    .sort((left, right) => (right.updatedAt || 0) - (left.updatedAt || 0))
-  return entries[0] || null
-}
-
-function getProjectRoot(cwd) {
-  const projectRoot = join(cwd, '.helloagents')
-  return existsSync(projectRoot) ? projectRoot : ''
-}
-
-export function getReplayDir(cwd) {
-  const projectRoot = getProjectRoot(cwd)
-  return projectRoot ? join(projectRoot, 'replay') : ''
-}
-
-function ensureReplayDir(cwd) {
-  const replayDir = getReplayDir(cwd)
-  if (!replayDir) return ''
-  mkdirSync(replayDir, { recursive: true })
-  return replayDir
-}
-
-function listReplaySessionFiles(replayDir) {
-  if (!replayDir || !existsSync(replayDir)) return []
-  return readdirSync(replayDir)
-    .filter((name) => name.endsWith('.jsonl'))
-    .sort()
-}
-
-function trimReplaySessions(replayDir) {
-  const files = listReplaySessionFiles(replayDir)
-  const staleFiles = files.slice(0, Math.max(0, files.length - MAX_REPLAY_SESSIONS))
-  for (const fileName of staleFiles) {
-    rmSync(join(replayDir, fileName), { force: true })
-  }
-}
+import {
+  appendSessionEvent,
+  getSessionEventsPath,
+  resetSessionEvents,
+} from './session-capsule.mjs'
+import { getProjectSessionScope } from './runtime-scope.mjs'
 
 function sanitizeReplayValue(value) {
   if (typeof value === 'string') {
@@ -102,43 +37,6 @@ function sanitizeReplayValue(value) {
   return value
 }
 
-function getReplaySession(cwd, { host = '', create = false, reset = false } = {}) {
-  const replayDir = ensureReplayDir(cwd)
-  if (!replayDir) return null
-
-  const key = getReplayKey(cwd, host)
-  const context = readReplayContext()
-  const current = context[key] || (!host ? findLatestReplaySession(context, cwd) : null)
-  const isExpired = !current?.updatedAt || (Date.now() - current.updatedAt > REPLAY_SESSION_TTL_MS)
-  const isMissing = !current?.filePath || !existsSync(current.filePath)
-
-  if (!reset && !isExpired && !isMissing) {
-    context[key] = {
-      ...current,
-      updatedAt: Date.now(),
-    }
-    writeReplayContext(context)
-    return context[key]
-  }
-
-  if (!create) return null
-
-  const stamp = new Date().toISOString().replace(/[:.]/g, '-')
-  const suffix = Math.random().toString(36).slice(2, 8)
-  const sessionId = `${stamp}-${host || 'unknown'}-${suffix}`
-  const filePath = join(replayDir, `${sessionId}.jsonl`)
-  const next = {
-    cwd: normalizePath(cwd),
-    host: host || 'unknown',
-    sessionId,
-    filePath,
-    updatedAt: Date.now(),
-  }
-  context[key] = next
-  writeReplayContext(context)
-  return next
-}
-
 function buildReplayRecommendation(recommendation) {
   if (!recommendation) return {}
   return {
@@ -151,24 +49,35 @@ function buildReplayRecommendation(recommendation) {
   }
 }
 
+export function getReplayDir(cwd, options = {}) {
+  const eventPath = getSessionEventsPath(cwd, options)
+  return eventPath ? dirname(eventPath) : ''
+}
+
 export function startReplaySession(cwd, {
   host = '',
   source = 'startup',
   bootstrapFile = '',
   installMode = '',
+  payload = {},
+  env,
+  ppid,
 } = {}) {
-  const session = getReplaySession(cwd, { host, create: true, reset: true })
-  if (!session) return ''
+  const scope = getProjectSessionScope(cwd, { payload, env, ppid })
+  if (!scope.active) return ''
 
+  const filePath = resetSessionEvents(cwd, { payload, env, ppid })
   appendReplayEvent(cwd, {
     host,
     event: 'session_started',
     source,
     bootstrapFile,
     installMode,
-    sessionId: session.sessionId,
+    payload,
+    env,
+    ppid,
   })
-  return session.filePath
+  return filePath
 }
 
 export function appendReplayEvent(cwd, {
@@ -182,29 +91,23 @@ export function appendReplayEvent(cwd, {
   artifacts = [],
   details = {},
   sessionId = '',
+  payload = {},
+  env,
+  ppid,
 } = {}) {
-  if (!event) return ''
-  const session = getReplaySession(cwd, { host, create: true })
-  if (!session?.filePath) return ''
+  const scope = getProjectSessionScope(cwd, { payload, env, ppid })
+  if (!scope.active || !event) return ''
 
-  const payload = sanitizeReplayValue({
-    ts: new Date().toISOString(),
+  return appendSessionEvent(cwd, sanitizeReplayValue({
     event,
-    host: host || session.host,
+    host: host || 'unknown',
     source,
-    sessionId: sessionId || session.sessionId,
+    sessionId: sessionId || scope.session,
     skillName,
     sourceSkillName,
     recommendation: buildReplayRecommendation(recommendation),
     reason,
     artifacts,
     details,
-  })
-
-  writeFileSync(session.filePath, `${JSON.stringify(payload)}\n`, {
-    encoding: 'utf-8',
-    flag: 'a',
-  })
-  trimReplaySessions(getReplayDir(cwd))
-  return session.filePath
+  }), { payload, env, ppid })
 }

package/scripts/review-state.mjs

@@ -1,11 +1,18 @@
-import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
-import { join } from 'node:path'
-import { captureWorkspaceFingerprint } from './verify-state.mjs'
 import { appendReplayEvent } from './replay-state.mjs'
-
-export const REVIEW_EVIDENCE_FILE_NAME = '.ralph-review.json'
-const REVIEW_EVIDENCE_MAX_AGE_MS = 30 * 60 * 1000
+import {
+  captureWorkspaceFingerprint,
+  clearRuntimeEvidence,
+  getRuntimeEvidencePath,
+  getRuntimeEvidenceRelativePath,
+  readRuntimeEvidence,
+  validateEvidenceFingerprint,
+  validateEvidenceTimestamp,
+  writeRuntimeEvidence,
+} from './runtime-artifacts.mjs'
+
+export const REVIEW_EVIDENCE_FILE_NAME = 'review.json'
 const VALID_REVIEW_OUTCOMES = new Set(['clean', 'findings'])
 
 function normalizeStringArray(values) {
@@ -20,20 +27,16 @@ function normalizeReviewOutcome(value) {
   return VALID_REVIEW_OUTCOMES.has(normalized) ? normalized : ''
 }
 
-export function getReviewEvidencePath(cwd) {
-  return join(cwd, '.helloagents', REVIEW_EVIDENCE_FILE_NAME)
+export function getReviewEvidencePath(cwd, options = {}) {
+  return getRuntimeEvidencePath(cwd, REVIEW_EVIDENCE_FILE_NAME, options)
 }
 
-export function readReviewEvidence(cwd) {
-  try {
-    return JSON.parse(readFileSync(getReviewEvidencePath(cwd), 'utf-8'))
-  } catch {
-    return null
-  }
+export function readReviewEvidence(cwd, options = {}) {
+  return readRuntimeEvidence(cwd, REVIEW_EVIDENCE_FILE_NAME, options)
 }
 
-export function clearReviewEvidence(cwd) {
-  rmSync(getReviewEvidencePath(cwd), { force: true })
+export function clearReviewEvidence(cwd, options = {}) {
+  clearRuntimeEvidence(cwd, REVIEW_EVIDENCE_FILE_NAME, options)
 }
 
 export function normalizeReviewEvidence(input = {}) {
@@ -56,8 +59,7 @@ export function writeReviewEvidence(cwd, {
   conclusion = '',
   findings = [],
   fileReferences = [],
-} = {}) {
-  mkdirSync(join(cwd, '.helloagents'), { recursive: true })
+} = {}, options = {}) {
   const normalized = normalizeReviewEvidence({
     source,
     originCommand,
@@ -78,11 +80,12 @@ export function writeReviewEvidence(cwd, {
     fileReferences: normalized.fileReferences,
     fingerprint: captureWorkspaceFingerprint(cwd),
   }
-  writeFileSync(getReviewEvidencePath(cwd), `${JSON.stringify(payload, null, 2)}\n`, 'utf-8')
+  writeRuntimeEvidence(cwd, REVIEW_EVIDENCE_FILE_NAME, payload, options)
   appendReplayEvent(cwd, {
     event: 'review_evidence_written',
     source: normalized.source,
     skillName: normalized.originCommand,
+    payload: options.payload || {},
     details: {
       reviewMode: normalized.reviewMode,
       outcome: normalized.outcome,
@@ -90,59 +93,29 @@ export function writeReviewEvidence(cwd, {
       findings: normalized.findings,
       fileReferences: normalized.fileReferences,
     },
-    artifacts: ['.helloagents/.ralph-review.json'],
+    artifacts: [getRuntimeEvidenceRelativePath(cwd, REVIEW_EVIDENCE_FILE_NAME, options)],
   })
   return payload
 }
 
-function readRequiredReviewEvidence(cwd) {
-  const evidence = readReviewEvidence(cwd)
+function readRequiredReviewEvidence(cwd, options = {}) {
+  const evidence = readReviewEvidence(cwd, options)
   if (evidence) return { evidence }
   return {
     error: {
       required: true,
       status: 'missing',
-      details: ['missing successful review evidence for review-first closeout'],
+      details: ['缺少 review-first 收尾所需的成功审查证据'],
     },
   }
 }
 
 function validateReviewTimestamp(evidence, now) {
-  const updatedAt = Date.parse(evidence.updatedAt || '')
-  if (!Number.isFinite(updatedAt)) {
-    return {
-      required: true,
-      status: 'invalid',
-      evidence,
-      details: ['review evidence timestamp is invalid'],
-    }
-  }
-  if (now - updatedAt > REVIEW_EVIDENCE_MAX_AGE_MS) {
-    return {
-      required: true,
-      status: 'stale-time',
-      evidence,
-      details: ['review evidence is older than 30 minutes'],
-    }
-  }
-  return null
+  return validateEvidenceTimestamp(evidence, now, '审查证据')
 }
 
 function validateReviewFingerprint(cwd, evidence) {
-  const currentFingerprint = captureWorkspaceFingerprint(cwd)
-  if (
-    currentFingerprint.available
-    && evidence.fingerprint?.available
-    && currentFingerprint.combined !== evidence.fingerprint.combined
-  ) {
-    return {
-      required: true,
-      status: 'stale-diff',
-      evidence,
-      details: ['workspace diff changed after the last successful review evidence'],
-    }
-  }
-  return null
+  return validateEvidenceFingerprint(cwd, evidence, '成功审查证据')
 }
 
 function validateReviewOutcome(evidence) {
@@ -151,7 +124,7 @@ function validateReviewOutcome(evidence) {
       required: true,
       status: 'invalid',
       evidence,
-      details: ['review evidence must record explicit outcome and conclusion'],
+      details: ['审查证据必须记录明确的 outcome 和 conclusion'],
     }
   }
   if (normalizeReviewOutcome(evidence.outcome) !== 'clean') {
@@ -159,13 +132,13 @@ function validateReviewOutcome(evidence) {
       required: true,
       status: 'blocked',
       evidence,
-      details: ['latest review evidence still records blocking findings'],
+      details: ['最新审查证据仍记录阻塞问题'],
     }
   }
   return null
 }
 
-export function getReviewEvidenceStatus(cwd, { required = false, now = Date.now() } = {}) {
+export function getReviewEvidenceStatus(cwd, { required = false, now = Date.now(), ...options } = {}) {
   if (!required) {
     return {
       required: false,
@@ -173,7 +146,7 @@ export function getReviewEvidenceStatus(cwd, { required = false, now = Date.now(
     }
   }
 
-  const requiredEvidence = readRequiredReviewEvidence(cwd)
+  const requiredEvidence = readRequiredReviewEvidence(cwd, options)
   if (requiredEvidence.error) return requiredEvidence.error
 
   const { evidence } = requiredEvidence
@@ -207,10 +180,10 @@ function main() {
 
   const input = readStdinJson()
   const cwd = input.cwd || process.cwd()
-  const payload = writeReviewEvidence(cwd, input)
+  const payload = writeReviewEvidence(cwd, input, { payload: input })
   process.stdout.write(JSON.stringify({
     suppressOutput: true,
-    path: getReviewEvidencePath(cwd),
+    path: getReviewEvidencePath(cwd, { payload: input }),
     payload,
   }))
 }

package/scripts/runtime-artifacts.mjs

@@ -0,0 +1,95 @@
+import { execSync } from 'node:child_process'
+
+import {
+  clearSessionArtifact,
+  getSessionArtifactPath,
+  getSessionArtifactRelativePath,
+  readSessionArtifact,
+  writeSessionArtifact,
+} from './session-capsule.mjs'
+
+export const EVIDENCE_MAX_AGE_MS = 30 * 60 * 1000
+
+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 getRuntimeEvidencePath(cwd, fileName, options = {}) {
+  return getSessionArtifactPath(cwd, fileName, options)
+}
+
+export function getRuntimeEvidenceRelativePath(cwd, fileName, options = {}) {
+  return getSessionArtifactRelativePath(cwd, fileName, options)
+}
+
+export function readRuntimeEvidence(cwd, fileName, options = {}) {
+  return readSessionArtifact(cwd, fileName, options)
+}
+
+export function clearRuntimeEvidence(cwd, fileName, options = {}) {
+  clearSessionArtifact(cwd, fileName, options)
+}
+
+export function writeRuntimeEvidence(cwd, fileName, payload, options = {}) {
+  return writeSessionArtifact(cwd, fileName, payload, options)
+}
+
+export function validateEvidenceTimestamp(evidence, now, label) {
+  const updatedAt = Date.parse(evidence.updatedAt || '')
+  if (!Number.isFinite(updatedAt)) {
+    return {
+      required: true,
+      status: 'invalid',
+      evidence,
+      details: [`${label}时间戳无效`],
+    }
+  }
+  if (now - updatedAt > EVIDENCE_MAX_AGE_MS) {
+    return {
+      required: true,
+      status: 'stale-time',
+      evidence,
+      details: [`${label}超过 30 分钟`],
+    }
+  }
+  return null
+}
+
+export function validateEvidenceFingerprint(cwd, evidence, label) {
+  const currentFingerprint = captureWorkspaceFingerprint(cwd)
+  if (
+    currentFingerprint.available
+    && evidence.fingerprint?.available
+    && currentFingerprint.combined !== evidence.fingerprint.combined
+  ) {
+    return {
+      required: true,
+      status: 'stale-diff',
+      evidence,
+      details: [`工作区变更已不同于最近一次${label}后的状态`],
+    }
+  }
+  return null
+}

package/scripts/runtime-context.mjs

@@ -1,56 +1,62 @@
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
-import { dirname, join, normalize, resolve } from 'node:path'
-import { homedir } from 'node:os'
+import { normalize, resolve } from 'node:path'
+
+import {
+  clearCapsuleSection,
+  getRuntimeScope,
+  readCapsuleSection,
+  writeCapsuleSection,
+} from './session-capsule.mjs'
 
-const RUNTIME_DIR = join(homedir(), '.helloagents', 'runtime')
-const ROUTE_CONTEXT_PATH = join(RUNTIME_DIR, 'route-context.json')
 const ROUTE_CONTEXT_TTL_MS = 30 * 60 * 1000
 
 function normalizePath(filePath = '') {
   return filePath ? normalize(resolve(filePath)) : ''
 }
 
-function ensureRuntimeDir() {
-  mkdirSync(dirname(ROUTE_CONTEXT_PATH), { recursive: true })
+function resolvePayload(options = {}) {
+  return options.payload && typeof options.payload === 'object' ? options.payload : options
 }
 
-export function clearRouteContext() {
-  rmSync(ROUTE_CONTEXT_PATH, { force: true })
+export function clearRouteContext(options = {}) {
+  const payload = resolvePayload(options)
+  const cwd = options.cwd || payload.cwd || process.cwd()
+  clearCapsuleSection(cwd, 'route', { payload, env: options.env, ppid: options.ppid })
 }
 
-export function writeRouteContext({ cwd, skillName, sourceSkillName = skillName }) {
-  ensureRuntimeDir()
+export function writeRouteContext({ cwd, skillName, sourceSkillName = skillName, payload = {}, env, ppid }) {
+  const scope = getRuntimeScope(cwd, { payload, env, ppid })
   const context = {
     cwd: normalizePath(cwd),
     skillName,
     sourceSkillName,
     zeroSideEffect: skillName === 'idea',
+    scope: scope.scope,
+    key: scope.key,
     updatedAt: Date.now(),
   }
-  writeFileSync(ROUTE_CONTEXT_PATH, `${JSON.stringify(context, null, 2)}\n`, 'utf-8')
+  writeCapsuleSection(cwd, 'route', context, { payload, env, ppid })
 }
 
-export function readRouteContext() {
-  if (!existsSync(ROUTE_CONTEXT_PATH)) return null
-
-  try {
-    const context = JSON.parse(readFileSync(ROUTE_CONTEXT_PATH, 'utf-8'))
-    if (!context?.cwd || !context?.skillName || !context?.updatedAt) return null
-    if (Date.now() - context.updatedAt > ROUTE_CONTEXT_TTL_MS) {
-      clearRouteContext()
-      return null
-    }
-    return {
-      ...context,
-      cwd: normalizePath(context.cwd),
-    }
-  } catch {
+export function readRouteContext(options = {}) {
+  const payload = resolvePayload(options)
+  const cwd = options.cwd || payload.cwd || process.cwd()
+  const context = readCapsuleSection(cwd, 'route', { payload, env: options.env, ppid: options.ppid })
+  if (!context?.cwd || !context?.skillName || !context?.updatedAt) {
+    return null
+  }
+  if (Date.now() - context.updatedAt > ROUTE_CONTEXT_TTL_MS) {
+    clearRouteContext({ cwd, payload, env: options.env, ppid: options.ppid })
     return null
   }
+
+  return {
+    ...context,
+    cwd: normalizePath(context.cwd),
+  }
 }
 
-export function getApplicableRouteContext({ cwd = '', filePath = '' } = {}) {
-  const context = readRouteContext()
+export function getApplicableRouteContext({ cwd = '', filePath = '', payload = {}, env, ppid } = {}) {
+  const context = readRouteContext({ cwd, payload, env, ppid })
   if (!context) return null
 
   const normalizedCwd = normalizePath(cwd)