helloagents 3.0.2-beta.1 → 3.0.7

package/scripts/replay-state.mjs

@@ -0,0 +1,210 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join, normalize, resolve } from 'node:path'
+import { homedir } from 'node:os'
+
+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 })
+  }
+}
+
+function sanitizeReplayValue(value) {
+  if (typeof value === 'string') {
+    return value.replace(/\s+/g, ' ').trim().slice(0, 280)
+  }
+  if (Array.isArray(value)) {
+    return value
+      .slice(0, 8)
+      .map((entry) => sanitizeReplayValue(entry))
+      .filter((entry) => entry !== '' && entry !== undefined)
+  }
+  if (value && typeof value === 'object') {
+    const output = {}
+    for (const [key, entry] of Object.entries(value)) {
+      const sanitized = sanitizeReplayValue(entry)
+      if (
+        sanitized === ''
+        || sanitized === undefined
+        || sanitized === null
+        || (Array.isArray(sanitized) && sanitized.length === 0)
+        || (typeof sanitized === 'object' && !Array.isArray(sanitized) && Object.keys(sanitized).length === 0)
+      ) {
+        continue
+      }
+      output[key] = sanitized
+    }
+    return output
+  }
+  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 {
+    nextCommand: recommendation.nextCommand,
+    nextPath: recommendation.nextPath,
+    stage: recommendation.stage || '',
+    status: recommendation.status || '',
+    planName: recommendation.plan?.planName || '',
+    summary: recommendation.summary || '',
+  }
+}
+
+export function startReplaySession(cwd, {
+  host = '',
+  source = 'startup',
+  bootstrapFile = '',
+  installMode = '',
+} = {}) {
+  const session = getReplaySession(cwd, { host, create: true, reset: true })
+  if (!session) return ''
+
+  appendReplayEvent(cwd, {
+    host,
+    event: 'session_started',
+    source,
+    bootstrapFile,
+    installMode,
+    sessionId: session.sessionId,
+  })
+  return session.filePath
+}
+
+export function appendReplayEvent(cwd, {
+  host = '',
+  event = '',
+  source = '',
+  skillName = '',
+  sourceSkillName = '',
+  recommendation = null,
+  reason = '',
+  artifacts = [],
+  details = {},
+  sessionId = '',
+} = {}) {
+  if (!event) return ''
+  const session = getReplaySession(cwd, { host, create: true })
+  if (!session?.filePath) return ''
+
+  const payload = sanitizeReplayValue({
+    ts: new Date().toISOString(),
+    event,
+    host: host || session.host,
+    source,
+    sessionId: sessionId || session.sessionId,
+    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
+}

package/scripts/review-state.mjs

@@ -0,0 +1,220 @@
+import { mkdirSync, readFileSync, rmSync, writeFileSync } 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
+const VALID_REVIEW_OUTCOMES = new Set(['clean', 'findings'])
+
+function normalizeStringArray(values) {
+  if (!Array.isArray(values)) return []
+  return [...new Set(values
+    .map((value) => (typeof value === 'string' ? value.trim() : ''))
+    .filter(Boolean))]
+}
+
+function normalizeReviewOutcome(value) {
+  const normalized = typeof value === 'string' ? value.trim().toLowerCase() : ''
+  return VALID_REVIEW_OUTCOMES.has(normalized) ? normalized : ''
+}
+
+export function getReviewEvidencePath(cwd) {
+  return join(cwd, '.helloagents', REVIEW_EVIDENCE_FILE_NAME)
+}
+
+export function readReviewEvidence(cwd) {
+  try {
+    return JSON.parse(readFileSync(getReviewEvidencePath(cwd), 'utf-8'))
+  } catch {
+    return null
+  }
+}
+
+export function clearReviewEvidence(cwd) {
+  rmSync(getReviewEvidencePath(cwd), { force: true })
+}
+
+export function normalizeReviewEvidence(input = {}) {
+  return {
+    source: typeof input.source === 'string' && input.source.trim() ? input.source.trim() : 'manual',
+    originCommand: typeof input.originCommand === 'string' ? input.originCommand.trim() : '',
+    reviewMode: typeof input.reviewMode === 'string' ? input.reviewMode.trim() : '',
+    outcome: normalizeReviewOutcome(input.outcome),
+    conclusion: typeof input.conclusion === 'string' ? input.conclusion.trim() : '',
+    findings: normalizeStringArray(input.findings),
+    fileReferences: normalizeStringArray(input.fileReferences),
+  }
+}
+
+export function writeReviewEvidence(cwd, {
+  source = 'stop',
+  originCommand = '',
+  reviewMode = '',
+  outcome = '',
+  conclusion = '',
+  findings = [],
+  fileReferences = [],
+} = {}) {
+  mkdirSync(join(cwd, '.helloagents'), { recursive: true })
+  const normalized = normalizeReviewEvidence({
+    source,
+    originCommand,
+    reviewMode,
+    outcome,
+    conclusion,
+    findings,
+    fileReferences,
+  })
+  const payload = {
+    updatedAt: new Date().toISOString(),
+    source: normalized.source,
+    originCommand: normalized.originCommand,
+    reviewMode: normalized.reviewMode,
+    conclusion: normalized.conclusion,
+    outcome: normalized.outcome,
+    findings: normalized.findings,
+    fileReferences: normalized.fileReferences,
+    fingerprint: captureWorkspaceFingerprint(cwd),
+  }
+  writeFileSync(getReviewEvidencePath(cwd), `${JSON.stringify(payload, null, 2)}\n`, 'utf-8')
+  appendReplayEvent(cwd, {
+    event: 'review_evidence_written',
+    source: normalized.source,
+    skillName: normalized.originCommand,
+    details: {
+      reviewMode: normalized.reviewMode,
+      outcome: normalized.outcome,
+      conclusion: normalized.conclusion,
+      findings: normalized.findings,
+      fileReferences: normalized.fileReferences,
+    },
+    artifacts: ['.helloagents/.ralph-review.json'],
+  })
+  return payload
+}
+
+function readRequiredReviewEvidence(cwd) {
+  const evidence = readReviewEvidence(cwd)
+  if (evidence) return { evidence }
+  return {
+    error: {
+      required: true,
+      status: 'missing',
+      details: ['missing successful review evidence for review-first closeout'],
+    },
+  }
+}
+
+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
+}
+
+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
+}
+
+function validateReviewOutcome(evidence) {
+  if (!normalizeReviewOutcome(evidence.outcome) || !String(evidence.conclusion || '').trim()) {
+    return {
+      required: true,
+      status: 'invalid',
+      evidence,
+      details: ['review evidence must record explicit outcome and conclusion'],
+    }
+  }
+  if (normalizeReviewOutcome(evidence.outcome) !== 'clean') {
+    return {
+      required: true,
+      status: 'blocked',
+      evidence,
+      details: ['latest review evidence still records blocking findings'],
+    }
+  }
+  return null
+}
+
+export function getReviewEvidenceStatus(cwd, { required = false, now = Date.now() } = {}) {
+  if (!required) {
+    return {
+      required: false,
+      status: 'not-applicable',
+    }
+  }
+
+  const requiredEvidence = readRequiredReviewEvidence(cwd)
+  if (requiredEvidence.error) return requiredEvidence.error
+
+  const { evidence } = requiredEvidence
+  const timestampError = validateReviewTimestamp(evidence, now)
+  if (timestampError) return timestampError
+
+  const fingerprintError = validateReviewFingerprint(cwd, evidence)
+  if (fingerprintError) return fingerprintError
+
+  const outcomeError = validateReviewOutcome(evidence)
+  if (outcomeError) return outcomeError
+
+  return {
+    required: true,
+    status: 'valid',
+    evidence,
+  }
+}
+
+function readStdinJson() {
+  try {
+    return JSON.parse(readFileSync(0, 'utf-8'))
+  } catch {
+    return {}
+  }
+}
+
+function main() {
+  const command = process.argv[2] || ''
+  if (command !== 'write') return
+
+  const input = readStdinJson()
+  const cwd = input.cwd || process.cwd()
+  const payload = writeReviewEvidence(cwd, input)
+  process.stdout.write(JSON.stringify({
+    suppressOutput: true,
+    path: getReviewEvidencePath(cwd),
+    payload,
+  }))
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  main()
+}

package/scripts/runtime-context.mjs

@@ -0,0 +1,74 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join, normalize, resolve } from 'node:path'
+import { homedir } from 'node:os'
+
+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 })
+}
+
+export function clearRouteContext() {
+  rmSync(ROUTE_CONTEXT_PATH, { force: true })
+}
+
+export function writeRouteContext({ cwd, skillName, sourceSkillName = skillName }) {
+  ensureRuntimeDir()
+  const context = {
+    cwd: normalizePath(cwd),
+    skillName,
+    sourceSkillName,
+    zeroSideEffect: skillName === 'idea',
+    updatedAt: Date.now(),
+  }
+  writeFileSync(ROUTE_CONTEXT_PATH, `${JSON.stringify(context, null, 2)}\n`, 'utf-8')
+}
+
+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 {
+    return null
+  }
+}
+
+export function getApplicableRouteContext({ cwd = '', filePath = '' } = {}) {
+  const context = readRouteContext()
+  if (!context) return null
+
+  const normalizedCwd = normalizePath(cwd)
+  if (normalizedCwd && normalizedCwd === context.cwd) {
+    return context
+  }
+
+  const normalizedFilePath = normalizePath(filePath)
+  if (
+    normalizedFilePath
+    && (
+      normalizedFilePath === context.cwd
+      || normalizedFilePath.startsWith(`${context.cwd}\\`)
+      || normalizedFilePath.startsWith(`${context.cwd}/`)
+    )
+  ) {
+    return context
+  }
+
+  return null
+}