@sebastianandreasson/pi-autonomous-agents 0.1.0

package/src/pi-client.mjs

@@ -0,0 +1,195 @@
+import { randomUUID } from 'node:crypto'
+import {
+  appendLog,
+  runShellCommand,
+  writeTextFile,
+} from './pi-repo.mjs'
+
+function truncateForNotes(text) {
+  const trimmed = text.trim()
+  if (trimmed.length <= 300) {
+    return trimmed
+  }
+  return `${trimmed.slice(0, 297)}...`
+}
+
+function formatLastAgentOutput(response) {
+  const sections = [
+    `status: ${String(response.status ?? '')}`,
+    `sessionId: ${String(response.sessionId ?? '')}`,
+    `sessionFile: ${String(response.sessionFile ?? '')}`,
+    `notes: ${String(response.notes ?? '').trim()}`,
+  ]
+
+  const output = String(response.output ?? '').trim()
+  if (output !== '') {
+    sections.push('', output)
+  }
+
+  return `${sections.join('\n')}\n`
+}
+
+async function runMockTurn({ config, sessionId, sessionFile, prompt, reason }) {
+  const nextSessionId = sessionId || `mock-${randomUUID()}`
+  const nextSessionFile = sessionFile || `${config.piRuntimeDir}/mock-${nextSessionId}.jsonl`
+  const output = [
+    `[mock transport] ${config.agentName} session ${nextSessionId}`,
+    `reason: ${reason}`,
+    '',
+    'Prompt preview:',
+    prompt,
+    '',
+    'Mock mode does not edit files. Point PI_TRANSPORT=adapter at a real adapter to enable unattended work.',
+  ].join('\n')
+
+  await writeTextFile(config.lastAgentOutputFile, `${output}\n`)
+  await appendLog(config.logFile, `Mock agent turn completed for session ${nextSessionId}`)
+  if (config.streamTerminal) {
+    process.stderr.write(`[PI mock] ${reason}\n`)
+    process.stderr.write('[PI mock] no live agent output in mock mode\n')
+  }
+
+  return {
+    sessionId: nextSessionId,
+    sessionFile: nextSessionFile,
+    status: 'success',
+    exitCode: 0,
+    timedOut: false,
+    durationSeconds: 0,
+    output,
+    notes: 'Mock transport completed without repo edits.',
+  }
+}
+
+function parseAdapterResponse(stdout) {
+  const trimmed = stdout.trim()
+  if (trimmed === '') {
+    throw new Error('Adapter returned no JSON on stdout.')
+  }
+
+  try {
+    return JSON.parse(trimmed)
+  } catch {
+    const lines = trimmed.split('\n').map((line) => line.trim()).filter(Boolean)
+    const lastLine = lines.at(-1)
+    if (!lastLine) {
+      throw new Error('Adapter returned no parseable JSON on stdout.')
+    }
+    return JSON.parse(lastLine)
+  }
+}
+
+async function runAdapterTurn({ config, model, sessionId, sessionFile, prompt, iteration, retryCount, reason }) {
+  if (config.adapterCommand.trim() === '') {
+    throw new Error('PI_TRANSPORT=adapter requires PI_ADAPTER_COMMAND to be set.')
+  }
+
+  const request = {
+    sessionId,
+    sessionFile,
+    prompt,
+    cwd: config.cwd,
+    taskFile: config.taskFile,
+    instructionsFile: config.instructionsFile,
+    developerInstructionsFile: config.developerInstructionsFile,
+    testerInstructionsFile: config.testerInstructionsFile,
+    runtimeDir: config.piRuntimeDir,
+    piCli: config.piCli,
+    model: model ?? config.piModel,
+    tools: config.piTools,
+    thinking: config.piThinking,
+    noExtensions: config.piNoExtensions,
+    noSkills: config.piNoSkills,
+    noPromptTemplates: config.piNoPromptTemplates,
+    noThemes: config.piNoThemes,
+    streamTerminal: config.streamTerminal,
+    loopRepeatThreshold: config.loopRepeatThreshold,
+    samePathRepeatThreshold: config.samePathRepeatThreshold,
+    continueAfterSeconds: config.continueAfterSeconds,
+    toolContinueAfterSeconds: config.toolContinueAfterSeconds,
+    continueMessage: config.continueMessage,
+    noEventTimeoutSeconds: config.noEventTimeoutSeconds,
+    toolNoEventTimeoutSeconds: config.toolNoEventTimeoutSeconds,
+    metadata: {
+      iteration,
+      retryCount,
+      reason,
+    },
+  }
+
+  await appendLog(
+    config.logFile,
+    `Starting adapter turn via: ${config.adapterCommand} iteration=${iteration} retry=${retryCount} reason=${reason}`
+  )
+  const result = await runShellCommand({
+    cwd: config.cwd,
+    command: config.adapterCommand,
+    timeoutSeconds: config.agentTimeoutSeconds,
+    stdinText: `${JSON.stringify(request)}\n`,
+    streamStderrToParent: config.streamTerminal,
+  })
+
+  await writeTextFile(config.lastAgentOutputFile, result.combinedOutput)
+
+  if (result.timedOut) {
+    await appendLog(config.logFile, 'Adapter turn timed out')
+    return {
+      sessionId: sessionId || '',
+      sessionFile: sessionFile || '',
+      status: 'timed_out',
+      exitCode: result.exitCode,
+      timedOut: true,
+      durationSeconds: result.durationSeconds,
+      output: result.combinedOutput,
+      notes: 'Adapter process exceeded the configured timeout.',
+    }
+  }
+
+  if (result.exitCode !== 0) {
+    await appendLog(config.logFile, `Adapter turn failed with exit code ${result.exitCode}`)
+    await writeTextFile(config.lastAgentOutputFile, result.combinedOutput)
+    return {
+      sessionId: sessionId || '',
+      sessionFile: sessionFile || '',
+      status: 'failed',
+      exitCode: result.exitCode,
+      timedOut: false,
+      durationSeconds: result.durationSeconds,
+      output: result.combinedOutput,
+      notes: truncateForNotes(result.combinedOutput) || 'Adapter exited non-zero.',
+    }
+  }
+
+  const response = parseAdapterResponse(result.stdout)
+  await writeTextFile(config.lastAgentOutputFile, formatLastAgentOutput(response))
+  const nextSessionId = String(response.sessionId ?? sessionId ?? '')
+  const nextSessionFile = String(response.sessionFile ?? sessionFile ?? '')
+  const status = String(response.status ?? 'success')
+  const output = String(response.output ?? result.combinedOutput)
+  const notes = String(response.notes ?? truncateForNotes(output))
+
+  await appendLog(config.logFile, `Adapter turn completed with status ${status}`)
+
+  return {
+    sessionId: nextSessionId,
+    sessionFile: nextSessionFile,
+    status,
+    exitCode: result.exitCode,
+    timedOut: false,
+    durationSeconds: result.durationSeconds,
+    output,
+    notes,
+  }
+}
+
+export async function runAgentTurn(args) {
+  if (args.config.transport === 'mock') {
+    return await runMockTurn(args)
+  }
+
+  if (args.config.transport === 'adapter') {
+    return await runAdapterTurn(args)
+  }
+
+  throw new Error(`Unsupported PI transport "${args.config.transport}". Expected "mock" or "adapter".`)
+}

package/src/pi-config.mjs

@@ -0,0 +1,296 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url))
+const packageRoot = path.resolve(scriptDir, '..')
+const bundledConfigFile = path.join(packageRoot, 'pi.config.json')
+
+function hasValue(value) {
+  return value !== undefined && value !== null && value !== ''
+}
+
+function normalizeString(value, fallback) {
+  return hasValue(value) ? String(value) : fallback
+}
+
+function readString(name, fileValue, fallback) {
+  const value = process.env[name]
+  if (value !== undefined) {
+    return value
+  }
+  return normalizeString(fileValue, fallback)
+}
+
+function normalizeInt(name, raw, fallback) {
+  if (!hasValue(raw)) {
+    return fallback
+  }
+
+  const value = Number.parseInt(String(raw), 10)
+  if (!Number.isFinite(value) || value < 0) {
+    throw new Error(`Expected ${name} to be a non-negative integer, received "${raw}"`)
+  }
+
+  return value
+}
+
+function readInt(name, fileValue, fallback) {
+  const raw = process.env[name]
+  if (raw !== undefined && raw !== '') {
+    return normalizeInt(name, raw, fallback)
+  }
+  return normalizeInt(name, fileValue, fallback)
+}
+
+function normalizeBool(name, raw, fallback) {
+  if (!hasValue(raw)) {
+    return fallback
+  }
+
+  if (typeof raw === 'boolean') {
+    return raw
+  }
+
+  const normalized = String(raw).toLowerCase()
+  if (normalized === '1' || normalized === 'true' || normalized === 'yes') {
+    return true
+  }
+  if (normalized === '0' || normalized === 'false' || normalized === 'no') {
+    return false
+  }
+
+  throw new Error(`Expected ${name} to be a boolean flag, received "${raw}"`)
+}
+
+function readBool(name, fileValue, fallback) {
+  const raw = process.env[name]
+  if (raw !== undefined && raw !== '') {
+    return normalizeBool(name, raw, fallback)
+  }
+  return normalizeBool(name, fileValue, fallback)
+}
+
+function readRepoConfig(cwd) {
+  const configFallback = fs.existsSync(bundledConfigFile) ? bundledConfigFile : 'pi.config.json'
+  const configFile = path.resolve(cwd, normalizeString(process.env.PI_CONFIG_FILE, configFallback))
+
+  if (!fs.existsSync(configFile)) {
+    return {
+      configFile,
+      values: {},
+    }
+  }
+
+  const raw = fs.readFileSync(configFile, 'utf8')
+  const parsed = JSON.parse(raw)
+
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`Expected ${configFile} to contain a JSON object.`)
+  }
+
+  return {
+    configFile,
+    values: parsed,
+  }
+}
+
+function resolveFromCwd(cwd, name, fileValue, fallback) {
+  return path.resolve(cwd, readString(name, fileValue, fallback))
+}
+
+function resolveInstructionsFile(cwd, envName, fileValue, fallback) {
+  if (!hasValue(fileValue) && process.env[envName] === undefined) {
+    return path.resolve(cwd, fallback)
+  }
+  return resolveFromCwd(cwd, envName, fileValue, fallback)
+}
+
+function readObject(name, raw, fallback) {
+  const value = raw === undefined ? fallback : raw
+  if (value === undefined || value === null) {
+    return fallback
+  }
+  if (typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`Expected ${name} to be an object.`)
+  }
+  return value
+}
+
+function normalizeRoleModels(raw) {
+  const value = readObject('roleModels', raw, {})
+  const normalized = {}
+  for (const [role, modelName] of Object.entries(value)) {
+    if (!hasValue(modelName)) {
+      continue
+    }
+    normalized[String(role)] = String(modelName)
+  }
+  return normalized
+}
+
+function resolveModelProfile(modelProfiles, modelName) {
+  if (!modelName || typeof modelName !== 'string') {
+    return null
+  }
+
+  const profile = modelProfiles[modelName]
+  if (!profile || typeof profile !== 'object' || Array.isArray(profile)) {
+    return null
+  }
+
+  const apiKey = hasValue(profile.apiKey)
+    ? String(profile.apiKey)
+    : hasValue(profile.apiKeyEnv) && process.env[String(profile.apiKeyEnv)] !== undefined
+      ? String(process.env[String(profile.apiKeyEnv)])
+      : ''
+
+  return {
+    name: modelName,
+    baseUrl: normalizeString(profile.baseUrl, ''),
+    apiKey,
+    apiKeyEnv: normalizeString(profile.apiKeyEnv, ''),
+    vision: normalizeBool(`${modelName}.vision`, profile.vision, false),
+  }
+}
+
+export function resolveRoleModelName(config, role) {
+  const roleName = String(role ?? '').trim()
+  if (roleName !== '' && hasValue(config?.roleModels?.[roleName])) {
+    return String(config.roleModels[roleName])
+  }
+
+  if (roleName === 'visualReview') {
+    return String(config?.visualReviewModel ?? '')
+  }
+
+  return String(config?.piModel ?? '')
+}
+
+export function resolveRoleModel(config, role) {
+  const model = resolveRoleModelName(config, role)
+  return {
+    model,
+    modelProfile: resolveModelProfile(config?.modelProfiles ?? {}, model),
+  }
+}
+
+export function loadConfig(mode = 'once') {
+  const cwd = process.cwd()
+  const repoConfig = readRepoConfig(cwd)
+  const file = repoConfig.values
+  const bundledAdapterCommand = 'pi-harness adapter'
+  const modelProfiles = readObject('models', file.models, {})
+  const roleModels = normalizeRoleModels(file.roleModels)
+  const piModel = readString('PI_MODEL', file.piModel, '')
+  const visualReviewModel = readString('PI_VISUAL_REVIEW_MODEL', file.visualReviewModel, '')
+  const resolvedPiModel = resolveModelProfile(modelProfiles, piModel)
+  const resolvedVisualReviewModel = resolveModelProfile(modelProfiles, visualReviewModel)
+
+  return {
+    cwd,
+    configFile: repoConfig.configFile,
+    mode: mode === 'run' ? 'run' : 'once',
+    transport: readString('PI_TRANSPORT', file.transport, 'adapter'),
+    agentName: readString('PI_AGENT_NAME', file.agentName, 'PI'),
+    adapterCommand: readString('PI_ADAPTER_COMMAND', file.adapterCommand, bundledAdapterCommand),
+    taskFile: resolveFromCwd(cwd, 'PI_TASK_FILE', file.taskFile, 'TODOS.md'),
+    instructionsFile: resolveInstructionsFile(cwd, 'PI_INSTRUCTIONS_FILE', file.instructionsFile, path.join(packageRoot, 'templates', 'DEVELOPER.md')),
+    developerInstructionsFile: resolveInstructionsFile(
+      cwd,
+      'PI_DEVELOPER_INSTRUCTIONS_FILE',
+      file.developerInstructionsFile,
+      hasValue(file.instructionsFile)
+        ? String(file.instructionsFile)
+        : path.join(packageRoot, 'templates', 'DEVELOPER.md')
+    ),
+    testerInstructionsFile: resolveInstructionsFile(
+      cwd,
+      'PI_TESTER_INSTRUCTIONS_FILE',
+      file.testerInstructionsFile,
+      hasValue(file.instructionsFile)
+        ? String(file.instructionsFile)
+        : path.join(packageRoot, 'templates', 'TESTER.md')
+    ),
+    logFile: resolveFromCwd(cwd, 'PI_LOG_FILE', file.logFile, 'pi.log'),
+    telemetryJsonl: resolveFromCwd(cwd, 'PI_TELEMETRY_JSONL', file.telemetryJsonl, 'pi_telemetry.jsonl'),
+    telemetryCsv: resolveFromCwd(cwd, 'PI_TELEMETRY_CSV', file.telemetryCsv, 'pi_telemetry.csv'),
+    stateFile: resolveFromCwd(cwd, 'PI_STATE_FILE', file.stateFile, '.pi-state.json'),
+    sessionFile: resolveFromCwd(cwd, 'PI_SESSION_FILE', file.sessionFile, '.pi-session-id'),
+    lastAgentOutputFile: resolveFromCwd(cwd, 'PI_LAST_AGENT_OUTPUT_FILE', file.lastAgentOutputFile, '.pi-last-output.txt'),
+    lastVerificationOutputFile: resolveFromCwd(cwd, 'PI_LAST_VERIFICATION_OUTPUT_FILE', file.lastVerificationOutputFile, '.pi-last-verification.txt'),
+    changedFilesFile: resolveFromCwd(cwd, 'PI_CHANGED_FILES_FILE', file.changedFilesFile, '.pi-changed-files.txt'),
+    piRuntimeDir: resolveFromCwd(cwd, 'PI_RUNTIME_DIR', file.piRuntimeDir, '.pi-runtime'),
+    piCli: readString('PI_CLI', file.piCli, 'pi'),
+    piModel,
+    piModelProfile: resolvedPiModel,
+    modelProfiles,
+    roleModels,
+    piTools: readString('PI_TOOLS', file.piTools, 'read,bash,edit,write,grep,find,ls'),
+    piThinking: readString('PI_THINKING', file.piThinking, ''),
+    piNoExtensions: readBool('PI_NO_EXTENSIONS', file.piNoExtensions, false),
+    piNoSkills: readBool('PI_NO_SKILLS', file.piNoSkills, false),
+    piNoPromptTemplates: readBool('PI_NO_PROMPT_TEMPLATES', file.piNoPromptTemplates, false),
+    piNoThemes: readBool('PI_NO_THEMES', file.piNoThemes, true),
+    streamTerminal: readBool('PI_STREAM_TERMINAL', file.streamTerminal, false),
+    loopRepeatThreshold: readInt('PI_LOOP_REPEAT_THRESHOLD', file.loopRepeatThreshold, 12),
+    samePathRepeatThreshold: readInt('PI_SAME_PATH_REPEAT_THRESHOLD', file.samePathRepeatThreshold, 8),
+    continueAfterSeconds: readInt('PI_CONTINUE_AFTER', file.continueAfterSeconds, 300),
+    continueMessage: readString('PI_CONTINUE_MESSAGE', file.continueMessage, 'continue'),
+    noEventTimeoutSeconds: readInt('PI_NO_EVENT_TIMEOUT', file.noEventTimeoutSeconds, 900),
+    toolContinueAfterSeconds: readInt('PI_TOOL_CONTINUE_AFTER', file.toolContinueAfterSeconds, 900),
+    toolNoEventTimeoutSeconds: readInt('PI_TOOL_NO_EVENT_TIMEOUT', file.toolNoEventTimeoutSeconds, 1800),
+    testCommand: readString('PI_TEST_CMD', file.testCommand, ''),
+    agentTimeoutSeconds: readInt('PI_AGENT_TIMEOUT', file.agentTimeoutSeconds, 3600),
+    verificationTimeoutSeconds: readInt('PI_VERIFICATION_TIMEOUT', file.verificationTimeoutSeconds, 300),
+    idleRetryLimit: readInt('PI_IDLE_RETRY_LIMIT', file.idleRetryLimit, 1),
+    noChangeRetryLimit: readInt('PI_NO_CHANGE_RETRY_LIMIT', file.noChangeRetryLimit, 1),
+    visualFeedbackFile: resolveFromCwd(
+      cwd,
+      'PI_VISUAL_FEEDBACK_FILE',
+      file.visualFeedbackFile,
+      'pi-output/visual-review/FEEDBACK.md'
+    ),
+    testerFeedbackFile: resolveFromCwd(
+      cwd,
+      'PI_TESTER_FEEDBACK_FILE',
+      file.testerFeedbackFile,
+      'pi-output/tester-feedback/FEEDBACK.md'
+    ),
+    testerFeedbackHistoryDir: resolveFromCwd(
+      cwd,
+      'PI_TESTER_FEEDBACK_HISTORY_DIR',
+      file.testerFeedbackHistoryDir,
+      'pi-output/tester-feedback/history'
+    ),
+    visualReviewHistoryDir: resolveFromCwd(
+      cwd,
+      'PI_VISUAL_REVIEW_HISTORY_DIR',
+      file.visualReviewHistoryDir,
+      'pi-output/visual-review/history'
+    ),
+    visualCaptureDir: resolveFromCwd(
+      cwd,
+      'PI_VISUAL_CAPTURE_DIR',
+      file.visualCaptureDir,
+      'pi-output/visual-capture'
+    ),
+    visualCaptureCommand: readString('PI_VISUAL_CAPTURE_CMD', file.visualCaptureCommand, ''),
+    visualCaptureTimeoutSeconds: readInt('PI_VISUAL_CAPTURE_TIMEOUT', file.visualCaptureTimeoutSeconds, 300),
+    visualReviewEnabled: readBool('PI_VISUAL_REVIEW_ENABLED', file.visualReviewEnabled, false),
+    visualReviewEveryNSuccesses: readInt('PI_VISUAL_REVIEW_EVERY', file.visualReviewEveryNSuccesses, 5),
+    visualReviewModel,
+    visualReviewModelProfile: resolvedVisualReviewModel,
+    visualReviewCommand: readString(
+      'PI_VISUAL_REVIEW_COMMAND',
+      file.visualReviewCommand,
+      'pi-harness visual-review-worker'
+    ),
+    visualReviewMaxImages: readInt('PI_VISUAL_REVIEW_MAX_IMAGES', file.visualReviewMaxImages, 8),
+    visualReviewTimeoutSeconds: readInt('PI_VISUAL_REVIEW_TIMEOUT', file.visualReviewTimeoutSeconds, 300),
+    maxIterations: readInt('PI_MAX_ITERS', file.maxIterations, 200),
+    sleepBetweenSeconds: readInt('PI_SLEEP_BETWEEN', file.sleepBetweenSeconds, 2),
+    reportLimit: readInt('PI_REPORT_LIMIT', file.reportLimit, 20),
+  }
+}

package/src/pi-flow.mjs

@@ -0,0 +1,42 @@
+export function shouldPersistLatestTesterFeedback(source) {
+  return String(source ?? '').trim() !== 'tester_commit_plan'
+}
+
+export function deriveWorkflowStatus({
+  developerStatus,
+  testerStatus,
+  verificationStatus,
+}) {
+  return (
+    developerStatus === 'success'
+    && testerStatus === 'success'
+    && (
+      verificationStatus === 'passed'
+      || verificationStatus === 'skipped'
+      || verificationStatus === 'not_run'
+    )
+  )
+    ? 'success'
+    : developerStatus === 'complete'
+      ? 'complete'
+      : developerStatus !== 'success'
+        ? developerStatus
+        : testerStatus !== 'success'
+          ? testerStatus
+          : verificationStatus
+}
+
+export function deriveFinalStatusWithVisualReview({
+  workflowStatus,
+  visualStatus,
+}) {
+  if (workflowStatus !== 'success') {
+    return workflowStatus
+  }
+
+  if (visualStatus === 'failed' || visualStatus === 'timed_out' || visualStatus === 'blocked') {
+    return visualStatus
+  }
+
+  return workflowStatus
+}

package/src/pi-heartbeat.mjs

@@ -0,0 +1,152 @@
+function readTimeout(raw, fallback) {
+  const value = Number(raw)
+  return Number.isFinite(value) && value >= 0 ? value : fallback
+}
+
+export function resolveHeartbeatConfig(request = {}) {
+  const continueAfterSeconds = readTimeout(request.continueAfterSeconds, 300)
+  const noEventTimeoutSeconds = readTimeout(request.noEventTimeoutSeconds, 900)
+  const toolContinueAfterSeconds = readTimeout(request.toolContinueAfterSeconds, 900)
+  const toolNoEventTimeoutSeconds = readTimeout(request.toolNoEventTimeoutSeconds, 1800)
+
+  return {
+    continueAfterSeconds,
+    noEventTimeoutSeconds,
+    toolContinueAfterSeconds,
+    toolNoEventTimeoutSeconds,
+  }
+}
+
+export function getHeartbeatThresholds({
+  continueAfterSeconds,
+  noEventTimeoutSeconds,
+  toolContinueAfterSeconds,
+  toolNoEventTimeoutSeconds,
+  activeToolName,
+}) {
+  if (activeToolName) {
+    return {
+      continueAfterSeconds: toolContinueAfterSeconds,
+      noEventTimeoutSeconds: toolNoEventTimeoutSeconds,
+      timeoutClass: 'tool_idle',
+    }
+  }
+
+  return {
+    continueAfterSeconds,
+    noEventTimeoutSeconds,
+    timeoutClass: 'agent_idle',
+  }
+}
+
+export function getActiveToolInfo(activeToolName, activeToolStartedAt, now = Date.now()) {
+  if (!activeToolName || !Number.isFinite(activeToolStartedAt)) {
+    return {
+      activeToolName: '',
+      toolRuntimeSeconds: 0,
+      isToolActive: false,
+    }
+  }
+
+  return {
+    activeToolName,
+    toolRuntimeSeconds: Math.max(0, Math.floor((now - activeToolStartedAt) / 1000)),
+    isToolActive: true,
+  }
+}
+
+export function getHeartbeatDecision({
+  now = Date.now(),
+  agentStarted,
+  agentEnded,
+  heartbeatTimedOut,
+  childExited,
+  lastEventAt,
+  continueAttempted,
+  activeToolName = '',
+  activeToolStartedAt = 0,
+  continueAfterSeconds,
+  noEventTimeoutSeconds,
+  toolContinueAfterSeconds,
+  toolNoEventTimeoutSeconds,
+}) {
+  if (!agentStarted || agentEnded || heartbeatTimedOut || childExited) {
+    return { action: 'none' }
+  }
+
+  const idleSeconds = Math.max(0, Math.floor((now - lastEventAt) / 1000))
+  const { activeToolName: resolvedToolName, toolRuntimeSeconds, isToolActive } = getActiveToolInfo(
+    activeToolName,
+    activeToolStartedAt,
+    now
+  )
+  const thresholds = getHeartbeatThresholds({
+    continueAfterSeconds,
+    noEventTimeoutSeconds,
+    toolContinueAfterSeconds,
+    toolNoEventTimeoutSeconds,
+    activeToolName: resolvedToolName,
+  })
+
+  if (!continueAttempted && thresholds.continueAfterSeconds > 0 && idleSeconds > thresholds.continueAfterSeconds) {
+    return {
+      action: 'soft_continue',
+      idleSeconds,
+      ...thresholds,
+      activeToolName: resolvedToolName,
+      toolRuntimeSeconds,
+      isToolActive,
+    }
+  }
+
+  if (thresholds.noEventTimeoutSeconds > 0 && idleSeconds > thresholds.noEventTimeoutSeconds) {
+    return {
+      action: 'abort',
+      idleSeconds,
+      ...thresholds,
+      activeToolName: resolvedToolName,
+      toolRuntimeSeconds,
+      isToolActive,
+    }
+  }
+
+  return {
+    action: 'none',
+    idleSeconds,
+    ...thresholds,
+    activeToolName: resolvedToolName,
+    toolRuntimeSeconds,
+    isToolActive,
+  }
+}
+
+export function formatHeartbeatReason({
+  timeoutClass,
+  noEventTimeoutSeconds,
+  activeToolName,
+  toolRuntimeSeconds,
+}) {
+  const parts = [
+    `timeout_class=${timeoutClass}`,
+    `no_pi_events_for=${noEventTimeoutSeconds}s`,
+  ]
+
+  if (activeToolName) {
+    parts.push(`active_tool=${activeToolName}`)
+    parts.push(`tool_runtime_seconds=${toolRuntimeSeconds}`)
+  }
+
+  return parts.join(' ')
+}
+
+export function formatHeartbeatTimeoutMessage({
+  noEventTimeoutSeconds,
+  activeToolName,
+  toolRuntimeSeconds,
+}) {
+  if (activeToolName) {
+    return `No PI RPC events were received for ${noEventTimeoutSeconds} seconds while tool "${activeToolName}" was running (runtime ${toolRuntimeSeconds}s).`
+  }
+
+  return `No PI RPC events were received for ${noEventTimeoutSeconds} seconds.`
+}