@sebastianandreasson/pi-autonomous-agents 0.1.0 → 0.2.0

package/README.md

@@ -59,6 +59,7 @@ packages/pi-harness/
 pi-harness once
 pi-harness run
 pi-harness report
+pi-harness clear-history
 pi-harness visual-once
 pi-harness adapter
 pi-harness visual-review-worker
@@ -82,6 +83,14 @@ Find SETUP.md in @sebastianandreasson/pi-autonomous-agents and set everything up
 
 The package ships a top-level [SETUP.md](./SETUP.md) specifically for that workflow.
 
+If you want to wipe all harness-generated state and start over cleanly in a repo, run:
+
+```bash
+PI_CONFIG_FILE=pi.config.json pi-harness clear-history
+```
+
+The command removes configured harness history/runtime files and verifies that no configured history paths remain afterward.
+
 ## Generic Contracts
 
 - `taskFile`: usually `TODOS.md`

package/SETUP.md

@@ -50,6 +50,11 @@ If the repo uses another package manager already, use the repo-native equivalent
   - `visualCaptureCommand`: only if this repo has a real screenshot capture flow
   - `models` / `piModel` / `visualReviewModel` / `roleModels`: configure the models actually available in this environment
 
+Important:
+
+- Do not assume a local provider’s served model id matches a GGUF filename or a guessed name.
+- If the repo uses custom OpenAI-compatible providers, verify the exact served ids from each provider’s `/v1/models` response before finalizing `piModel`, `visualReviewModel`, or `roleModels`.
+
 3. Create role instruction files.
 
 - Copy `node_modules/@sebastianandreasson/pi-autonomous-agents/templates/DEVELOPER.md` to `pi/DEVELOPER.md`.
@@ -136,6 +141,21 @@ Example shape:
 }
 ```
 
+If the repo uses a custom OpenAI-compatible local provider, validate it directly:
+
+1. Verify the endpoint is reachable.
+2. Query `<baseUrl>/models`.
+3. Use the exact returned model id.
+4. Do not assume the served id equals a GGUF filename on disk.
+
+If the repo overrides `PI_CODING_AGENT_DIR`:
+
+- do not point it at an empty directory
+- ensure that PI home is already bootstrapped
+- ensure `models.json` exists there before running the harness
+
+If `PI_CODING_AGENT_DIR` is set to a repo-local PI home and `models.json` is missing, setup is incomplete.
+
 9. Validate the setup.
 
 Run at least:
@@ -152,6 +172,13 @@ PI_CONFIG_FILE=pi.config.json PI_TRANSPORT=mock PI_TEST_CMD= pi-harness once
 
 If setup validation fails, fix the config rather than leaving a half-configured repo.
 
+The harness should fail fast if:
+
+- PI cannot list models
+- a configured PI role model does not exist
+- a configured provider endpoint is unreachable
+- a configured provider does not serve the configured model id
+
 ## Agent Rules
 
 - Reuse existing repo conventions where possible.
@@ -169,3 +196,13 @@ When setup is complete, report:
 - whether visual review was enabled
 - which roles were mapped to which models
 - whether validation was run successfully
+
+## Resetting Harness State
+
+If the user wants to start over from a clean slate later, use:
+
+```bash
+PI_CONFIG_FILE=pi.config.json pi-harness clear-history
+```
+
+This should remove harness-generated runtime/history state only, not project source files.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sebastianandreasson/pi-autonomous-agents",
   "private": false,
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "Portable unattended PI harness for developer/tester/visual-review loops.",
   "license": "MIT",
@@ -16,8 +16,8 @@
     "pi-harness": "./src/cli.mjs"
   },
   "scripts": {
-    "check": "node --check src/cli.mjs && node --check src/pi-client.mjs && node --check src/pi-config.mjs && node --check src/pi-flow.mjs && node --check src/pi-heartbeat.mjs && node --check src/pi-prompts.mjs && node --check src/pi-repo.mjs && node --check src/pi-report.mjs && node --check src/pi-rpc-adapter.mjs && node --check src/pi-supervisor.mjs && node --check src/pi-telemetry.mjs && node --check src/pi-visual-once.mjs && node --check src/pi-visual-review.mjs && node --check src/index.mjs && node --check test/pi-heartbeat.test.mjs && node --check test/pi-role-models.test.mjs && node --check test/pi-flow.test.mjs",
-    "test": "node --test test/pi-heartbeat.test.mjs test/pi-role-models.test.mjs test/pi-flow.test.mjs"
+    "check": "node --check src/cli.mjs && node --check src/pi-clear-history.mjs && node --check src/pi-client.mjs && node --check src/pi-config.mjs && node --check src/pi-flow.mjs && node --check src/pi-heartbeat.mjs && node --check src/pi-history.mjs && node --check src/pi-preflight.mjs && node --check src/pi-prompts.mjs && node --check src/pi-repo.mjs && node --check src/pi-report.mjs && node --check src/pi-rpc-adapter.mjs && node --check src/pi-supervisor.mjs && node --check src/pi-telemetry.mjs && node --check src/pi-visual-once.mjs && node --check src/pi-visual-review.mjs && node --check src/index.mjs && node --check test/pi-heartbeat.test.mjs && node --check test/pi-role-models.test.mjs && node --check test/pi-flow.test.mjs && node --check test/pi-history.test.mjs && node --check test/pi-prompts.test.mjs && node --check test/pi-preflight.test.mjs",
+    "test": "node --test test/pi-heartbeat.test.mjs test/pi-role-models.test.mjs test/pi-flow.test.mjs test/pi-history.test.mjs test/pi-prompts.test.mjs test/pi-preflight.test.mjs"
   },
   "files": [
     "src",

package/src/cli.mjs

@@ -11,6 +11,7 @@ const COMMANDS = new Map([
   ['once', 'pi-supervisor.mjs'],
   ['run', 'pi-supervisor.mjs'],
   ['report', 'pi-report.mjs'],
+  ['clear-history', 'pi-clear-history.mjs'],
   ['visual-once', 'pi-visual-once.mjs'],
   ['adapter', 'pi-rpc-adapter.mjs'],
   ['visual-review-worker', 'pi-visual-review.mjs'],

package/src/index.mjs

@@ -4,4 +4,10 @@ export {
   deriveWorkflowStatus,
   shouldPersistLatestTesterFeedback,
 } from './pi-flow.mjs'
+export {
+  extractModelIdsFromProviderResponse,
+  parsePiListModelsOutput,
+  runStartupPreflight,
+} from './pi-preflight.mjs'
+export { clearHarnessHistory, collectHistoryTargets } from './pi-history.mjs'
 export { runAgentTurn } from './pi-client.mjs'

package/src/pi-clear-history.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+import { loadConfig } from './pi-config.mjs'
+import { ensureRepo } from './pi-repo.mjs'
+import { clearHarnessHistory } from './pi-history.mjs'
+
+async function main() {
+  const config = loadConfig('once')
+  ensureRepo(config.cwd)
+
+  const result = await clearHarnessHistory(config)
+
+  console.log(`Cleared harness history for ${result.clearedTargets.length} existing paths.`)
+  if (result.clearedTargets.length > 0) {
+    console.log('Cleared:')
+    for (const targetPath of result.clearedTargets) {
+      console.log(`- ${targetPath}`)
+    }
+  }
+  console.log('Verification passed: no configured harness history paths remain.')
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error))
+  process.exitCode = 1
+})

package/src/pi-history.mjs

@@ -0,0 +1,90 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+function unique(values) {
+  return [...new Set(values)]
+}
+
+function isWithinCwd(cwd, targetPath) {
+  const relativePath = path.relative(cwd, targetPath)
+  return relativePath !== '' && !relativePath.startsWith('..') && !path.isAbsolute(relativePath)
+}
+
+export function collectHistoryTargets(config) {
+  return unique([
+    config.logFile,
+    config.telemetryJsonl,
+    config.telemetryCsv,
+    config.stateFile,
+    config.sessionFile,
+    config.lastAgentOutputFile,
+    config.lastVerificationOutputFile,
+    config.changedFilesFile,
+    config.piRuntimeDir,
+    config.visualFeedbackFile,
+    config.testerFeedbackFile,
+    config.testerFeedbackHistoryDir,
+    config.visualReviewHistoryDir,
+    config.visualCaptureDir,
+  ].map((value) => String(value ?? '').trim()).filter(Boolean))
+}
+
+async function pathExists(targetPath) {
+  try {
+    await fs.access(targetPath)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function validateHistoryTargets(config, targets) {
+  const invalidTargets = targets.filter((targetPath) => {
+    if (!path.isAbsolute(targetPath)) {
+      return true
+    }
+    if (targetPath === config.cwd || targetPath === path.parse(targetPath).root) {
+      return true
+    }
+    return !isWithinCwd(config.cwd, targetPath)
+  })
+
+  if (invalidTargets.length > 0) {
+    throw new Error(
+      `Refusing to clear history outside the repo root. Invalid targets: ${invalidTargets.join(', ')}`
+    )
+  }
+}
+
+export async function clearHarnessHistory(config) {
+  const targets = collectHistoryTargets(config)
+  validateHistoryTargets(config, targets)
+
+  const existingTargets = []
+  for (const targetPath of targets) {
+    if (await pathExists(targetPath)) {
+      existingTargets.push(targetPath)
+    }
+  }
+
+  for (const targetPath of [...existingTargets].sort((left, right) => right.length - left.length)) {
+    await fs.rm(targetPath, { recursive: true, force: true })
+  }
+
+  const remainingTargets = []
+  for (const targetPath of targets) {
+    if (await pathExists(targetPath)) {
+      remainingTargets.push(targetPath)
+    }
+  }
+
+  if (remainingTargets.length > 0) {
+    throw new Error(`Failed to clear harness history for: ${remainingTargets.join(', ')}`)
+  }
+
+  return {
+    targets,
+    clearedTargets: existingTargets,
+    remainingTargets,
+  }
+}

package/src/pi-preflight.mjs

@@ -0,0 +1,222 @@
+import fs from 'node:fs/promises'
+import { execFileSync } from 'node:child_process'
+import path from 'node:path'
+import process from 'node:process'
+
+import { resolveRoleModelName } from './pi-config.mjs'
+
+function uniqueNonEmpty(values) {
+  return [...new Set(values.map((value) => String(value ?? '').trim()).filter(Boolean))]
+}
+
+function formatAvailableModels(models) {
+  const uniqueModels = uniqueNonEmpty(models)
+  if (uniqueModels.length === 0) {
+    return '(none)'
+  }
+  if (uniqueModels.length <= 20) {
+    return uniqueModels.join(', ')
+  }
+  return `${uniqueModels.slice(0, 20).join(', ')}, ...`
+}
+
+export function parsePiListModelsOutput(output) {
+  const text = String(output ?? '').trim()
+  if (text === '') {
+    return []
+  }
+
+  try {
+    const parsed = JSON.parse(text)
+    return extractModelIdsFromProviderResponse(parsed)
+  } catch {
+    // fall through
+  }
+
+  const ids = []
+  for (const rawLine of text.split('\n')) {
+    const line = rawLine.trim()
+    if (
+      line === ''
+      || /^available models:?$/i.test(line)
+      || /^models:?$/i.test(line)
+      || /^id\s+/i.test(line)
+      || /^name\s+/i.test(line)
+    ) {
+      continue
+    }
+
+    const stripped = line.replace(/^[-*]\s+/, '').trim()
+    const firstToken = stripped.split(/\s+/)[0]?.trim() ?? ''
+    if (firstToken !== '') {
+      ids.push(firstToken)
+    }
+  }
+
+  return uniqueNonEmpty(ids)
+}
+
+export function extractModelIdsFromProviderResponse(payload) {
+  if (Array.isArray(payload)) {
+    return uniqueNonEmpty(payload.map((entry) => {
+      if (typeof entry === 'string') {
+        return entry
+      }
+      if (entry && typeof entry === 'object') {
+        return entry.id ?? entry.name ?? entry.model ?? ''
+      }
+      return ''
+    }))
+  }
+
+  if (!payload || typeof payload !== 'object') {
+    return []
+  }
+
+  if (Array.isArray(payload.data)) {
+    return extractModelIdsFromProviderResponse(payload.data)
+  }
+
+  if (Array.isArray(payload.models)) {
+    return extractModelIdsFromProviderResponse(payload.models)
+  }
+
+  return uniqueNonEmpty([
+    payload.id ?? '',
+    payload.name ?? '',
+    payload.model ?? '',
+  ])
+}
+
+async function ensurePiHomeModelsConfig() {
+  const piHome = process.env.PI_CODING_AGENT_DIR
+  if (!piHome) {
+    return
+  }
+
+  const resolvedPiHome = path.resolve(piHome)
+  const modelsFile = path.join(resolvedPiHome, 'models.json')
+  try {
+    await fs.access(modelsFile)
+  } catch {
+    throw new Error(
+      `PI_CODING_AGENT_DIR points at "${resolvedPiHome}", but "${modelsFile}" is missing. Either remove PI_CODING_AGENT_DIR or bootstrap that PI home before running the harness.`
+    )
+  }
+}
+
+function listPiModels(config) {
+  try {
+    const output = execFileSync(config.piCli, ['--list-models'], {
+      cwd: config.cwd,
+      env: process.env,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    return parsePiListModelsOutput(output)
+  } catch (error) {
+    const stdout = error?.stdout ? String(error.stdout).trim() : ''
+    const stderr = error?.stderr ? String(error.stderr).trim() : ''
+    const details = [stdout, stderr].filter(Boolean).join('\n')
+    throw new Error(
+      details === ''
+        ? `Failed to list PI models via "${config.piCli} --list-models".`
+        : `Failed to list PI models via "${config.piCli} --list-models".\n${details}`
+    )
+  }
+}
+
+function getConfiguredTextModels(config) {
+  return uniqueNonEmpty([
+    resolveRoleModelName(config, 'developer'),
+    resolveRoleModelName(config, 'developerRetry'),
+    resolveRoleModelName(config, 'developerFix'),
+    resolveRoleModelName(config, 'tester'),
+    resolveRoleModelName(config, 'testerCommit'),
+  ])
+}
+
+async function listProviderModels(modelName, modelProfile) {
+  const baseUrl = String(modelProfile?.baseUrl ?? '').replace(/\/$/, '')
+  if (baseUrl === '') {
+    return []
+  }
+
+  let response
+  try {
+    response = await fetch(`${baseUrl}/models`, {
+      method: 'GET',
+      headers: {
+        ...(modelProfile?.apiKey ? { authorization: `Bearer ${modelProfile.apiKey}` } : {}),
+      },
+      signal: AbortSignal.timeout(10_000),
+    })
+  } catch (error) {
+    throw new Error(
+      `Configured provider for model "${modelName}" is unreachable at ${baseUrl}/models: ${error instanceof Error ? error.message : String(error)}`
+    )
+  }
+
+  if (!response.ok) {
+    const errorText = (await response.text()).trim()
+    throw new Error(
+      `Configured provider for model "${modelName}" returned ${response.status} from ${baseUrl}/models.${errorText !== '' ? ` ${errorText}` : ''}`
+    )
+  }
+
+  const payload = await response.json()
+  return extractModelIdsFromProviderResponse(payload)
+}
+
+async function validateProviderModels(config) {
+  const configuredModels = uniqueNonEmpty([
+    ...getConfiguredTextModels(config),
+    config.visualReviewEnabled ? resolveRoleModelName(config, 'visualReview') : '',
+  ])
+
+  for (const modelName of configuredModels) {
+    const modelProfile = config.modelProfiles?.[modelName] ?? null
+    if (!modelProfile?.baseUrl) {
+      continue
+    }
+
+    const availableModels = await listProviderModels(modelName, modelProfile)
+    if (availableModels.length === 0) {
+      throw new Error(
+        `Configured provider for model "${modelName}" at ${String(modelProfile.baseUrl).replace(/\/$/, '')}/models returned no models.`
+      )
+    }
+
+    if (!availableModels.includes(modelName)) {
+      throw new Error(
+        `Configured model "${modelName}" not found at provider ${String(modelProfile.baseUrl).replace(/\/$/, '')}/models. Available models: ${formatAvailableModels(availableModels)}`
+      )
+    }
+  }
+}
+
+export async function runStartupPreflight(config) {
+  if (config.transport === 'mock') {
+    return
+  }
+
+  await ensurePiHomeModelsConfig()
+
+  const availablePiModels = listPiModels(config)
+  if (availablePiModels.length === 0) {
+    throw new Error(
+      `PI reported no models via "${config.piCli} --list-models". Ensure your PI home and model registry are configured before running the harness.`
+    )
+  }
+
+  const configuredTextModels = getConfiguredTextModels(config)
+  for (const modelName of configuredTextModels) {
+    if (!availablePiModels.includes(modelName)) {
+      throw new Error(
+        `Configured PI model "${modelName}" is not available from "${config.piCli} --list-models". Available models: ${formatAvailableModels(availablePiModels)}`
+      )
+    }
+  }
+
+  await validateProviderModels(config)
+}

package/src/pi-prompts.mjs

@@ -1,6 +1,15 @@
 import path from 'node:path'
 
-function shortName(filePath) {
+function displayPath(config, filePath) {
+  const relativePath = path.relative(config.cwd, filePath)
+  if (
+    relativePath !== ''
+    && !relativePath.startsWith('..')
+    && !path.isAbsolute(relativePath)
+  ) {
+    return relativePath.split(path.sep).join('/')
+  }
+
   return path.basename(filePath)
 }
 
@@ -46,8 +55,8 @@ function staleEditRecoveryRules() {
 }
 
 export function buildMainPrompt(config, options = {}) {
-  const taskFile = shortName(config.taskFile)
-  const instructionsFile = shortName(config.developerInstructionsFile)
+  const taskFile = displayPath(config, config.taskFile)
+  const instructionsFile = displayPath(config, config.developerInstructionsFile)
   const visualFeedbackSection = formatVisualFeedback(options.visualFeedback)
   const testerFeedbackSection = formatTesterFeedback(options.testerFeedback)
 
@@ -85,8 +94,8 @@ Before stopping:
 }
 
 export function buildFixPrompt(config, recentVerificationOutput, options = {}) {
-  const taskFile = shortName(config.taskFile)
-  const instructionsFile = shortName(config.developerInstructionsFile)
+  const taskFile = displayPath(config, config.taskFile)
+  const instructionsFile = displayPath(config, config.developerInstructionsFile)
   const visualFeedbackSection = formatVisualFeedback(options.visualFeedback)
   const testerFeedbackSection = formatTesterFeedback(options.testerFeedback)
 
@@ -120,7 +129,7 @@ Before stopping:
 }
 
 export function buildSteeringPrompt(config, reason, options = {}) {
-  const taskFile = shortName(config.taskFile)
+  const taskFile = displayPath(config, config.taskFile)
   const visualFeedbackSection = formatVisualFeedback(options.visualFeedback)
   const testerFeedbackSection = formatTesterFeedback(options.testerFeedback)
 
@@ -149,8 +158,8 @@ export function buildTesterPrompt(config, {
   visualFeedback = '',
   testerFeedback = '',
 }) {
-  const taskFile = shortName(config.taskFile)
-  const instructionsFile = shortName(config.testerInstructionsFile)
+  const taskFile = displayPath(config, config.taskFile)
+  const instructionsFile = displayPath(config, config.testerInstructionsFile)
   const visualFeedbackSection = formatVisualFeedback(visualFeedback)
   const testerFeedbackSection = formatTesterFeedback(testerFeedback)
   const changedFilesSection = changedFiles.length > 0
@@ -229,8 +238,8 @@ export function buildCommitPrompt(config, {
   visualFeedback = '',
   testerFeedback = '',
 }) {
-  const taskFile = shortName(config.taskFile)
-  const instructionsFile = shortName(config.testerInstructionsFile)
+  const taskFile = displayPath(config, config.taskFile)
+  const instructionsFile = displayPath(config, config.testerInstructionsFile)
   const visualFeedbackSection = formatVisualFeedback(visualFeedback)
   const testerFeedbackSection = formatTesterFeedback(testerFeedback)
   const changedFilesSection = changedFiles.length > 0

package/src/pi-supervisor.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import process from 'node:process'
+import path from 'node:path'
 import { loadConfig, resolveRoleModelName, resolveRoleModel } from './pi-config.mjs'
 import {
   buildCommitPrompt,
@@ -40,6 +41,7 @@ import {
   deriveWorkflowStatus,
   shouldPersistLatestTesterFeedback,
 } from './pi-flow.mjs'
+import { runStartupPreflight } from './pi-preflight.mjs'
 
 let stopRequested = false
 
@@ -64,6 +66,7 @@ function printTerminalSummary(config, summary) {
 
   const lines = [
     `[PI supervisor] iteration=${summary.iteration} phase="${summary.phase}"`,
+    `[PI supervisor] task=${summary.taskFile || toDisplayPath(config, config.taskFile)} developer_instructions=${summary.developerInstructionsFile || toDisplayPath(config, config.developerInstructionsFile)} tester_instructions=${summary.testerInstructionsFile || toDisplayPath(config, config.testerInstructionsFile)}`,
     `[PI supervisor] transport=${config.transport} developer_model=${summary.developerModel || resolveRoleModelName(config, 'developer') || '(PI default)'} tester_model=${summary.testerModel || resolveRoleModelName(config, 'tester') || '(PI default)'}`,
     `[PI supervisor] developer=${summary.developerStatus} tester=${summary.testerStatus} verification=${summary.verificationStatus}`,
   ]
@@ -87,6 +90,19 @@ function printTerminalSummary(config, summary) {
   process.stderr.write(`${lines.join('\n')}\n`)
 }
 
+function toDisplayPath(config, filePath) {
+  const relativePath = path.relative(config.cwd, filePath)
+  if (
+    relativePath !== ''
+    && !relativePath.startsWith('..')
+    && !path.isAbsolute(relativePath)
+  ) {
+    return relativePath.split(path.sep).join('/')
+  }
+
+  return filePath
+}
+
 function parseTesterVerdict(output) {
   const raw = String(output ?? '')
   const match = raw.match(/VERDICT:\s*(PASS|FAIL|BLOCKED)\s*$/im)
@@ -798,6 +814,9 @@ async function runIteration({ config, state, iteration }) {
         notes: 'No unchecked tasks remain in TODOS.md.',
         sessionId: state.sessionId || '',
         outputPath: config.lastAgentOutputFile,
+        taskFile: toDisplayPath(config, config.taskFile),
+        developerInstructionsFile: toDisplayPath(config, config.developerInstructionsFile),
+        testerInstructionsFile: toDisplayPath(config, config.testerInstructionsFile),
         developerModel: developerModelName,
         testerModel: testerModelName,
         visualModel: visualModelName,
@@ -820,7 +839,7 @@ async function runIteration({ config, state, iteration }) {
 
   await appendLog(
     config.logFile,
-    `Starting iteration ${iteration} in phase "${phase}" with transport "${config.transport}"`
+    `Starting iteration ${iteration} in phase "${phase}" with transport "${config.transport}" task=${toDisplayPath(config, config.taskFile)} developer_instructions=${toDisplayPath(config, config.developerInstructionsFile)} tester_instructions=${toDisplayPath(config, config.testerInstructionsFile)} developer_model=${developerModelName || '(PI default)'} tester_model=${testerModelName || '(PI default)'}`
   )
 
   const mainInvocation = await runMainTurnWithRetries({
@@ -1108,6 +1127,9 @@ async function runIteration({ config, state, iteration }) {
       notes: noteParts.join(' | '),
       sessionId,
       outputPath: config.lastAgentOutputFile,
+      taskFile: toDisplayPath(config, config.taskFile),
+      developerInstructionsFile: toDisplayPath(config, config.developerInstructionsFile),
+      testerInstructionsFile: toDisplayPath(config, config.testerInstructionsFile),
       developerModel: developerModelName,
       testerModel: testerModelName,
       visualModel: visualModelName,
@@ -1123,6 +1145,7 @@ async function main() {
   await ensureFileExists(config.developerInstructionsFile, 'developer instructions file')
   await ensureFileExists(config.testerInstructionsFile, 'tester instructions file')
   await ensureTelemetryFiles(config)
+  await runStartupPreflight(config)
 
   let state = await readState(config.stateFile)
   let completedIterations = 0