@sebastianandreasson/pi-autonomous-agents 0.2.0 → 0.3.0

package/README.md

@@ -91,12 +91,17 @@ 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.
 
+For prompt debugging, the harness also writes the exact assembled prompt for the current role to `.pi-last-prompt.txt` by default.
+For flow debugging, it also writes a machine-readable `.pi-last-iteration.json` summary with the selected task, tester verdict, commit-plan state, and terminal reason.
+
 ## Generic Contracts
 
 - `taskFile`: usually `TODOS.md`
 - `developerInstructionsFile`: per-project developer instructions
 - `testerInstructionsFile`: per-project tester instructions
 - `roleModels`: optional per-role model overrides
+- `commitMode`: `agent` by default, `plan` only for legacy harness-managed commit parsing
+- `promptMode`: `compact` by default
 - `testCommand`: fast verification command
 - `visualCaptureCommand`: project-defined screenshot capture command
 - `visualFeedbackFile`: latest visual-review handoff
@@ -104,8 +109,14 @@ The command removes configured harness history/runtime files and verifies that n
 
 For unattended loops, keep `testCommand` fast and bounded, such as a smoke suite. Long real-time Playwright happy-path specs belong in an explicit nightly or post-run lane, not the default developer/tester inner loop.
 
+Keep TODO items extremely small and implementation-shaped when using weaker local models. Broad tasks tend to produce much longer turns, more retries, and more tester drift than narrow one-step tasks.
+
 The adapter heartbeat is PI-RPC-event based. Streaming shell output does not count as progress on its own, so long-running tools should rely on the tool-aware watchdog thresholds rather than terminal streaming.
 
-`piModel` remains the default text model, but you can override specific roles with `roleModels` such as `developer`, `developerRetry`, `developerFix`, `tester`, `testerCommit`, and `visualReview`.
+`piModel` remains the default text model, but you can override specific roles with `roleModels` such as `developer`, `developerRetry`, `developerFix`, `tester`, and `visualReview`. `testerCommit` is only relevant if you opt back into `commitMode: "plan"`.
+
+By default, successful tester passes should stage and create the commit directly in the same PI turn. The old commit-plan parsing flow is still available as `commitMode: "plan"`, but it is now a compatibility mode rather than the default.
+
+Prompt/context handoff is compact by default. The harness now caps prior feedback excerpts, changed-file lists, verification excerpts, and prompt note handoff. If needed, tune `maxPromptChangedFiles`, `maxVisualFeedbackLines`, `maxTesterFeedbackLines`, `maxPromptNotesLines`, and `maxVerificationExcerptLines`.
 
 The harness expects screenshot capture to produce a `manifest.json` plus image files under the configured visual capture directory.

package/SETUP.md

@@ -46,6 +46,7 @@ If the repo uses another package manager already, use the repo-native equivalent
   - `taskFile`: usually `TODOS.md`
   - `developerInstructionsFile`: `pi/DEVELOPER.md`
   - `testerInstructionsFile`: `pi/TESTER.md`
+  - `commitMode`: normally `agent`
   - `testCommand`: a fast bounded verification command for this repo
   - `visualCaptureCommand`: only if this repo has a real screenshot capture flow
   - `models` / `piModel` / `visualReviewModel` / `roleModels`: configure the models actually available in this environment
@@ -123,6 +124,7 @@ Recommended pattern:
 - local model for `developerFix`
 - local or slightly stronger model for `tester`
 - stronger frontier model for `visualReview` only if available
+- keep `commitMode` as `agent` unless the repo explicitly needs legacy harness-managed commit-plan parsing
 
 Example shape:
 
@@ -179,6 +181,9 @@ The harness should fail fast if:
 - a configured provider endpoint is unreachable
 - a configured provider does not serve the configured model id
 
+For prompt debugging, inspect `.pi-last-prompt.txt` after a run. It contains the exact assembled prompt that was sent for the active role.
+For flow debugging, inspect `.pi-last-iteration.json` after a run. It summarizes the selected task, repo-change outcome, tester verdict, commit-plan state, and terminal reason.
+
 ## Agent Rules
 
 - Reuse existing repo conventions where possible.
@@ -186,6 +191,7 @@ The harness should fail fast if:
 - Do not invent fake test commands or model endpoints.
 - Do not enable visual review unless the repo actually has a usable capture command and model config.
 - Keep changes minimal and local to harness setup.
+- Prefer very small, implementation-shaped TODO items for local models. Broad tasks tend to create long turns, retries, and weak tester behavior.
 
 ## What To Report Back
 

package/docs/PI_SUPERVISOR.md

@@ -18,7 +18,7 @@ Each real iteration follows this sequence:
 2. A fast local verification command runs immediately after the developer round.
 3. If verification passes, `tester` reviews the change independently from a skeptical user-facing perspective.
 4. If tester or verification finds a real issue, the supervisor gives the findings back to `developer` for one focused repair pass.
-5. If tester reaches `PASS`, tester provides a commit plan and the harness performs the actual git finalization.
+5. If tester reaches `PASS`, tester creates the commit directly in the same turn by default.
 6. Optionally, every `N` successful iterations, the harness runs a read-only visual review over screenshots and persists the feedback for later runs.
 7. If that visual review returns `FAIL`, `BLOCKED`, or times out, the iteration is not counted as a success and the feedback is carried into later prompts.
 
@@ -69,6 +69,7 @@ Projects typically provide their own `pi.config.json` with fields such as:
 - `models`
 - `piModel`
 - `visualReviewModel`
+- `commitMode`
 
 Model entries may carry their own OpenAI-compatible endpoint settings, so the PI text loop and the multimodal visual reviewer can point at different backends without changing code.
 
@@ -83,7 +84,6 @@ Model entries may carry their own OpenAI-compatible endpoint settings, so the PI
     "developerRetry": "local/dev-model",
     "developerFix": "local/dev-model",
     "tester": "local/tester-model",
-    "testerCommit": "local/tester-model",
     "visualReview": "cloud/vision-model"
   }
 }
@@ -162,15 +162,13 @@ Allowed response `status` values:
 
 ## Git Finalization
 
-The harness is designed to keep commit history structured:
+The default flow keeps commit ownership with the active agent:
 
 1. `developer` should leave a clean, reviewable diff and should not commit.
-2. `tester` should review functionality and, on `PASS`, provide a commit plan:
-   - `COMMIT_MESSAGE: ...`
-   - `COMMIT_FILES:`
-   - `- path/to/file`
-3. The harness stages only those requested files and performs the commit itself.
-4. If the requested plan cannot be isolated safely, the iteration is blocked or failed instead of committing unrelated work.
+2. `tester` should review functionality and, on `PASS`, stage only the task-related files and create the commit directly.
+3. If the working tree is too messy to isolate safely, tester should return `VERDICT: BLOCKED` instead of guessing.
+
+If a repo explicitly needs the older harness-managed commit-plan flow, set `commitMode` to `plan`. In that mode, `testerCommit` and parsed commit plans are used as a compatibility path rather than the default.
 
 ## Persistent Handoffs
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sebastianandreasson/pi-autonomous-agents",
   "private": false,
-  "version": "0.2.0",
+  "version": "0.3.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-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"
+    "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 && node --check test/pi-repo.test.mjs && node --check test/pi-telemetry.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 test/pi-repo.test.mjs test/pi-telemetry.test.mjs"
   },
   "files": [
     "src",

package/pi.config.json

@@ -3,6 +3,7 @@
   "adapterCommand": "pi-harness adapter",
   "instructionsFile": "",
   "taskFile": "TODOS.md",
+  "commitMode": "agent",
   "streamTerminal": false,
   "loopRepeatThreshold": 12,
   "samePathRepeatThreshold": 8,

package/src/pi-client.mjs

@@ -18,6 +18,7 @@ function formatLastAgentOutput(response) {
     `status: ${String(response.status ?? '')}`,
     `sessionId: ${String(response.sessionId ?? '')}`,
     `sessionFile: ${String(response.sessionFile ?? '')}`,
+    `terminalReason: ${String(response.terminalReason ?? '')}`,
     `notes: ${String(response.notes ?? '').trim()}`,
   ]
 
@@ -58,6 +59,15 @@ async function runMockTurn({ config, sessionId, sessionFile, prompt, reason }) {
     durationSeconds: 0,
     output,
     notes: 'Mock transport completed without repo edits.',
+    role: '',
+    model: '',
+    toolCalls: 0,
+    toolErrors: 0,
+    messageUpdates: 0,
+    stopReason: '',
+    loopDetected: false,
+    loopSignature: '',
+    terminalReason: 'mock_completed',
   }
 }
 
@@ -142,6 +152,15 @@ async function runAdapterTurn({ config, model, sessionId, sessionFile, prompt, i
       durationSeconds: result.durationSeconds,
       output: result.combinedOutput,
       notes: 'Adapter process exceeded the configured timeout.',
+      role: '',
+      model: model ?? config.piModel,
+      toolCalls: 0,
+      toolErrors: 0,
+      messageUpdates: 0,
+      stopReason: '',
+      loopDetected: false,
+      loopSignature: '',
+      terminalReason: 'agent_timeout',
     }
   }
 
@@ -157,6 +176,15 @@ async function runAdapterTurn({ config, model, sessionId, sessionFile, prompt, i
       durationSeconds: result.durationSeconds,
       output: result.combinedOutput,
       notes: truncateForNotes(result.combinedOutput) || 'Adapter exited non-zero.',
+      role: '',
+      model: model ?? config.piModel,
+      toolCalls: 0,
+      toolErrors: 0,
+      messageUpdates: 0,
+      stopReason: '',
+      loopDetected: false,
+      loopSignature: '',
+      terminalReason: 'adapter_failed',
     }
   }
 
@@ -179,6 +207,15 @@ async function runAdapterTurn({ config, model, sessionId, sessionFile, prompt, i
     durationSeconds: result.durationSeconds,
     output,
     notes,
+    role: String(response.role ?? ''),
+    model: String(response.model ?? model ?? config.piModel ?? ''),
+    toolCalls: Number.isFinite(Number(response.toolCalls)) ? Number(response.toolCalls) : 0,
+    toolErrors: Number.isFinite(Number(response.toolErrors)) ? Number(response.toolErrors) : 0,
+    messageUpdates: Number.isFinite(Number(response.messageUpdates)) ? Number(response.messageUpdates) : 0,
+    stopReason: String(response.stopReason ?? ''),
+    loopDetected: response.loopDetected === true,
+    loopSignature: String(response.loopSignature ?? ''),
+    terminalReason: String(response.terminalReason ?? ''),
   }
 }
 

package/src/pi-config.mjs

@@ -130,6 +130,22 @@ function normalizeRoleModels(raw) {
   return normalized
 }
 
+function normalizeCommitMode(raw) {
+  const value = normalizeString(raw, 'agent').trim().toLowerCase()
+  if (value === 'agent' || value === 'plan') {
+    return value
+  }
+  throw new Error(`Expected commitMode to be "agent" or "plan", received "${raw}"`)
+}
+
+function normalizePromptMode(raw) {
+  const value = normalizeString(raw, 'compact').trim().toLowerCase()
+  if (value === 'compact' || value === 'full') {
+    return value
+  }
+  throw new Error(`Expected promptMode to be "compact" or "full", received "${raw}"`)
+}
+
 function resolveModelProfile(modelProfiles, modelName) {
   if (!modelName || typeof modelName !== 'string') {
     return null
@@ -181,12 +197,30 @@ export function loadConfig(mode = 'once') {
   const repoConfig = readRepoConfig(cwd)
   const file = repoConfig.values
   const bundledAdapterCommand = 'pi-harness adapter'
+  const bundledDeveloperInstructionsFile = path.join(packageRoot, 'templates', 'DEVELOPER.md')
+  const bundledTesterInstructionsFile = path.join(packageRoot, 'templates', 'TESTER.md')
   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)
+  const developerInstructionsFile = resolveInstructionsFile(
+    cwd,
+    'PI_DEVELOPER_INSTRUCTIONS_FILE',
+    file.developerInstructionsFile,
+    hasValue(file.instructionsFile)
+      ? String(file.instructionsFile)
+      : bundledDeveloperInstructionsFile
+  )
+  const testerInstructionsFile = resolveInstructionsFile(
+    cwd,
+    'PI_TESTER_INSTRUCTIONS_FILE',
+    file.testerInstructionsFile,
+    hasValue(file.instructionsFile)
+      ? String(file.instructionsFile)
+      : bundledTesterInstructionsFile
+  )
 
   return {
     cwd,
@@ -196,23 +230,11 @@ export function loadConfig(mode = 'once') {
     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')
-    ),
+    instructionsFile: resolveInstructionsFile(cwd, 'PI_INSTRUCTIONS_FILE', file.instructionsFile, bundledDeveloperInstructionsFile),
+    developerInstructionsFile,
+    testerInstructionsFile,
+    usingBundledDeveloperInstructions: developerInstructionsFile === bundledDeveloperInstructionsFile,
+    usingBundledTesterInstructions: testerInstructionsFile === bundledTesterInstructionsFile,
     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'),
@@ -221,12 +243,21 @@ export function loadConfig(mode = 'once') {
     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'),
+    lastPromptFile: resolveFromCwd(cwd, 'PI_LAST_PROMPT_FILE', file.lastPromptFile, '.pi-last-prompt.txt'),
+    lastIterationSummaryFile: resolveFromCwd(cwd, 'PI_LAST_ITERATION_SUMMARY_FILE', file.lastIterationSummaryFile, '.pi-last-iteration.json'),
     piRuntimeDir: resolveFromCwd(cwd, 'PI_RUNTIME_DIR', file.piRuntimeDir, '.pi-runtime'),
     piCli: readString('PI_CLI', file.piCli, 'pi'),
     piModel,
     piModelProfile: resolvedPiModel,
     modelProfiles,
     roleModels,
+    commitMode: normalizeCommitMode(readString('PI_COMMIT_MODE', file.commitMode, 'agent')),
+    promptMode: normalizePromptMode(readString('PI_PROMPT_MODE', file.promptMode, 'compact')),
+    maxPromptChangedFiles: readInt('PI_MAX_PROMPT_CHANGED_FILES', file.maxPromptChangedFiles, 10),
+    maxVisualFeedbackLines: readInt('PI_MAX_VISUAL_FEEDBACK_LINES', file.maxVisualFeedbackLines, 20),
+    maxTesterFeedbackLines: readInt('PI_MAX_TESTER_FEEDBACK_LINES', file.maxTesterFeedbackLines, 32),
+    maxPromptNotesLines: readInt('PI_MAX_PROMPT_NOTES_LINES', file.maxPromptNotesLines, 16),
+    maxVerificationExcerptLines: readInt('PI_MAX_VERIFICATION_EXCERPT_LINES', file.maxVerificationExcerptLines, 40),
     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),

package/src/pi-history.mjs

@@ -20,6 +20,8 @@ export function collectHistoryTargets(config) {
     config.lastAgentOutputFile,
     config.lastVerificationOutputFile,
     config.changedFilesFile,
+    config.lastPromptFile,
+    config.lastIterationSummaryFile,
     config.piRuntimeDir,
     config.visualFeedbackFile,
     config.testerFeedbackFile,

package/src/pi-preflight.mjs

@@ -1,5 +1,5 @@
 import fs from 'node:fs/promises'
-import { execFileSync } from 'node:child_process'
+import { spawnSync } from 'node:child_process'
 import path from 'node:path'
 import process from 'node:process'
 
@@ -34,20 +34,42 @@ export function parsePiListModelsOutput(output) {
   }
 
   const ids = []
+  let modelColumnIndex = -1
   for (const rawLine of text.split('\n')) {
     const line = rawLine.trim()
+    const stripped = line.replace(/^[-*]\s+/, '').trim()
+    const columns = stripped.split(/\s+/).filter(Boolean)
+    const normalizedColumns = columns.map((value) => value.toLowerCase())
+
+    if (
+      modelColumnIndex === -1
+      && normalizedColumns.includes('model')
+      && normalizedColumns.some((value) => value === 'provider' || value === 'id' || value === 'name')
+    ) {
+      modelColumnIndex = normalizedColumns.indexOf('model')
+      continue
+    }
+
     if (
       line === ''
       || /^available models:?$/i.test(line)
       || /^models:?$/i.test(line)
       || /^id\s+/i.test(line)
       || /^name\s+/i.test(line)
+      || /^[-=\s]+$/.test(line)
     ) {
       continue
     }
 
-    const stripped = line.replace(/^[-*]\s+/, '').trim()
-    const firstToken = stripped.split(/\s+/)[0]?.trim() ?? ''
+    if (modelColumnIndex >= 0) {
+      const modelToken = columns[modelColumnIndex]?.trim() ?? ''
+      if (modelToken !== '') {
+        ids.push(modelToken)
+      }
+      continue
+    }
+
+    const firstToken = columns[0]?.trim() ?? ''
     if (firstToken !== '') {
       ids.push(firstToken)
     }
@@ -106,24 +128,33 @@ async function ensurePiHomeModelsConfig() {
 }
 
 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')
+  const result = spawnSync(config.piCli, ['--list-models'], {
+    cwd: config.cwd,
+    env: process.env,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  })
+  const stdout = String(result.stdout ?? '').trim()
+  const stderr = String(result.stderr ?? '').trim()
+  const combinedOutput = [stdout, stderr].filter(Boolean).join('\n').trim()
+
+  if (result.error) {
+    throw new Error(
+      combinedOutput === ''
+        ? `Failed to list PI models via "${config.piCli} --list-models".`
+        : `Failed to list PI models via "${config.piCli} --list-models".\n${combinedOutput}`
+    )
+  }
+
+  if (result.status !== 0) {
     throw new Error(
-      details === ''
+      combinedOutput === ''
         ? `Failed to list PI models via "${config.piCli} --list-models".`
-        : `Failed to list PI models via "${config.piCli} --list-models".\n${details}`
+        : `Failed to list PI models via "${config.piCli} --list-models".\n${combinedOutput}`
     )
   }
+
+  return parsePiListModelsOutput(combinedOutput)
 }
 
 function getConfiguredTextModels(config) {