@sebastianandreasson/pi-autonomous-agents 0.9.0 → 0.10.0

package/README.md

@@ -89,6 +89,7 @@ pi-harness report
 pi-harness clear-history
 pi-harness visual-once
 pi-harness visualize
+pi-harness debug-live
 pi-harness visual-review-worker
 ```
 
@@ -319,4 +320,26 @@ npm run check
 npm test
 ```
 
+For local visualizer iteration against fake live SDK agent:
+
+```bash
+npm run debug:live-ui
+```
+
+For React/Vite visualizer UI dev loop:
+
+```bash
+npm run dev:visualizer:ui
+```
+
+For production visualizer UI build:
+
+```bash
+npm run build:visualizer:ui
+```
+
+This seeds `.pi-debug/live-ui/`, runs harness there with streaming fake SDK fixture, hosts visualizer, and gives stable local repro loop for UI work. React app lives in `visualizer-ui/`. Visualizer server now serves built assets from `visualizer-ui/dist/` and falls back to build-instructions page if build artifacts are missing.
+
+See `docs/VISUALIZER_UI_PLAN.md` for migration plan.
+
 The package requires Node `>=20`.

package/docs/PI_SUPERVISOR.md

@@ -35,8 +35,10 @@ Main package files:
 - `src/pi-prompts.mjs`: default prompt builders
 - `src/pi-visual-review.mjs`: multimodal visual-review worker
 - `src/pi-visual-once.mjs`: one-shot manual visual review runner
-- `src/pi-visualizer.mjs`: local web UI for orchestration flow and active stage
+- `src/pi-visualizer.mjs`: local web UI entrypoint
+- `src/pi-visualizer-server.mjs`: shared visualizer server/runtime
 - `src/pi-visualizer-shared.mjs`: flow-state helpers for visualizer
+- `src/pi-debug-live.mjs`: local fake-live sandbox runner for visualizer debugging
 - `src/pi-report.mjs`: telemetry summary report
 - `templates/DEVELOPER.md`: default developer-role instructions template
 - `templates/TESTER.md`: default tester-role instructions template
@@ -49,6 +51,7 @@ pi-harness run
 pi-harness report
 pi-harness visual-once
 pi-harness visualize
+pi-harness debug-live
 ```
 
 The package reads `PI_CONFIG_FILE` if provided. Otherwise it falls back to the bundled generic `pi.config.json`.
@@ -59,6 +62,8 @@ The package reads `PI_CONFIG_FILE` if provided. Otherwise it falls back to the b
 
 Visualizer reads active-run lock, TODO file, per-run state, per-run iteration summary, per-run last output snapshot, live feed JSONL, and telemetry to show current stage plus historical runs.
 
+For local UI iteration in this package repo, use `pi-harness debug-live` to run against seeded fake live SDK sandbox.
+
 ## Config Contract
 
 Projects typically provide their own `pi.config.json` with fields such as:

package/docs/VISUALIZER_UI_PLAN.md

@@ -0,0 +1,117 @@
+# Visualizer UI migration plan
+
+## Goal
+
+Replace inline browser JS/HTML in `src/pi-visualizer-server.mjs` with maintainable React frontend, while keeping Node visualizer server as API + SSE + static asset host.
+
+## Chosen stack
+
+- React
+- Vite
+- TypeScript
+- Zustand
+- Plain CSS
+
+## Repo layout
+
+```text
+src/
+  pi-visualizer-server.mjs   # API, SSE, static asset host
+visualizer-ui/
+  package.json
+  tsconfig.json
+  vite.config.ts
+  index.html
+  src/
+    main.tsx
+    App.tsx
+    api.ts
+    store.ts
+    types.ts
+    styles.css
+    components/
+      TodoList.tsx
+      FlowStrip.tsx
+      LiveFeed.tsx
+      CurrentEdits.tsx
+      DiagnosticsPanel.tsx
+```
+
+## State model
+
+Zustand store owns:
+
+- latest snapshot
+- selected run
+- selected todo
+- selected event
+- feed toggles
+- SSE lifecycle
+- initial load status / error
+
+## API contract
+
+Current server routes:
+
+- `GET /api/state` → full snapshot
+- `GET /api/stream` → SSE full snapshots
+
+Short term: React app consumes current full-snapshot SSE.
+
+Next improvement:
+
+- add monotonic `seq` to live feed entries
+- optionally move SSE from full snapshots to patch events
+- add snapshot version to ignore stale payloads
+
+## Migration phases
+
+### Phase 1
+- scaffold `visualizer-ui/`
+- keep current inline HTML as fallback
+- add built asset serving from `visualizer-ui/dist`
+- add `/api/state` alias
+
+### Phase 2
+- port current layout into React components
+- use Zustand store + initial snapshot fetch
+- use SSE reconnect from frontend
+
+### Phase 3
+- move feed/timeline ordering to stable `seq`
+- reduce full rerenders
+- preserve scroll behavior inside components
+
+### Phase 4
+- remove inline browser app from server once built UI covers current features
+- keep server only as API/static host
+
+## Dev workflow
+
+Backend + fake live harness:
+
+```bash
+npm run debug:live-ui
+```
+
+Frontend dev server:
+
+```bash
+npm run dev:visualizer:ui
+```
+
+Frontend build:
+
+```bash
+npm run build:visualizer:ui
+```
+
+## Notes
+
+Current state:
+
+- React/Vite/Zustand UI scaffold added
+- built assets generated under `visualizer-ui/dist/`
+- server serves built UI directly
+- legacy inline browser app removed
+- fallback page only shows build instructions when dist missing

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sebastianandreasson/pi-autonomous-agents",
   "private": false,
-  "version": "0.9.0",
+  "version": "0.10.0",
   "type": "module",
   "description": "Portable unattended PI harness for developer/tester/visual-review loops.",
   "license": "MIT",
@@ -19,13 +19,17 @@
     "@mariozechner/pi-coding-agent": "^0.66.1"
   },
   "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-sdk-turn.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/pi-visualizer.mjs && node --check src/pi-visualizer-server.mjs && node --check src/pi-visualizer-shared.mjs && node --check src/index.mjs && node --check test/pi-heartbeat.test.mjs && node --check test/pi-lifecycle.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-sdk-supervisor.test.mjs && node --check test/pi-sdk-turn.test.mjs && node --check test/pi-telemetry.test.mjs && node --check test/pi-visualizer-shared.test.mjs && node --check test/fixtures/fake-pi.mjs && node --check test/fixtures/fake-pi-sdk.mjs",
-    "test": "node --test test/pi-heartbeat.test.mjs test/pi-lifecycle.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-sdk-supervisor.test.mjs test/pi-sdk-turn.test.mjs test/pi-telemetry.test.mjs test/pi-visualizer-shared.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-debug-live.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-sdk-turn.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/pi-visualizer.mjs && node --check src/pi-visualizer-server.mjs && node --check src/pi-visualizer-shared.mjs && node --check src/index.mjs && node --check test/pi-heartbeat.test.mjs && node --check test/pi-lifecycle.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-sdk-supervisor.test.mjs && node --check test/pi-sdk-turn.test.mjs && node --check test/pi-telemetry.test.mjs && node --check test/pi-visualizer-shared.test.mjs && node --check test/fixtures/fake-pi.mjs && node --check test/fixtures/fake-pi-sdk.mjs && node --check test/fixtures/fake-live-pi-sdk.mjs",
+    "test": "node --test test/pi-heartbeat.test.mjs test/pi-lifecycle.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-sdk-supervisor.test.mjs test/pi-sdk-turn.test.mjs test/pi-telemetry.test.mjs test/pi-visualizer-shared.test.mjs",
+    "debug:live-ui": "node src/cli.mjs debug-live --reset",
+    "dev:visualizer:ui": "npm --prefix visualizer-ui run dev",
+    "build:visualizer:ui": "npm --prefix visualizer-ui run build"
   },
   "files": [
     "src",
     "templates",
     "docs",
+    "visualizer-ui/dist",
     "pi.config.json",
     "SETUP.md",
     "README.md"

package/src/cli.mjs

@@ -19,6 +19,7 @@ const COMMANDS = new Map([
   ['clear-history', 'pi-clear-history.mjs'],
   ['visual-once', 'pi-visual-once.mjs'],
   ['visualize', 'pi-visualizer.mjs'],
+  ['debug-live', 'pi-debug-live.mjs'],
   ['visual-review-worker', 'pi-visual-review.mjs'],
 ])
 

package/src/pi-client.mjs

@@ -1,6 +1,11 @@
 import fs from 'node:fs/promises'
 import path from 'node:path'
 import { randomUUID } from 'node:crypto'
+
+const liveFeedWriteQueues = new Map()
+const liveFeedSequences = new Map()
+const MAX_LIVE_FEED_TEXT = 2000
+const MAX_LIVE_FEED_SUMMARY = 600
 import {
   appendLog,
   writeTextFile,
@@ -39,12 +44,80 @@ async function writeAgentOutputSnapshot(config, content) {
   }
 }
 
+function truncateText(value, maxChars) {
+  const text = String(value ?? '')
+  if (text.length <= maxChars) {
+    return text
+  }
+  return `${text.slice(0, maxChars - 16)}\n... [truncated]`
+}
+
+function summarizeValue(value, maxChars = MAX_LIVE_FEED_SUMMARY) {
+  if (value === null || value === undefined) {
+    return ''
+  }
+  if (typeof value === 'string') {
+    return truncateText(value, maxChars)
+  }
+  try {
+    return truncateText(JSON.stringify(value), maxChars)
+  } catch {
+    return truncateText(String(value), maxChars)
+  }
+}
+
+function sanitizeLiveFeedEvent(filePath, event) {
+  const nextSeq = (liveFeedSequences.get(filePath) ?? 0) + 1
+  liveFeedSequences.set(filePath, nextSeq)
+
+  const normalized = {
+    seq: nextSeq,
+    timestamp: String(event?.timestamp ?? new Date().toISOString()),
+    iteration: Number(event?.iteration ?? 0),
+    retryCount: Number(event?.retryCount ?? 0),
+    reason: String(event?.reason ?? ''),
+    phase: String(event?.phase ?? ''),
+    role: String(event?.role ?? ''),
+    kind: String(event?.kind ?? ''),
+    type: String(event?.type ?? 'event'),
+    toolName: String(event?.toolName ?? ''),
+    isError: event?.isError === true,
+    text: truncateText(event?.text ?? '', MAX_LIVE_FEED_TEXT),
+  }
+
+  const argsSummary = summarizeValue(event?.args)
+  const partialSummary = summarizeValue(event?.partialResult)
+  const resultSummary = summarizeValue(event?.result)
+  if (argsSummary !== '') {
+    normalized.argsSummary = argsSummary
+  }
+  if (partialSummary !== '') {
+    normalized.partialSummary = partialSummary
+  }
+  if (resultSummary !== '') {
+    normalized.resultSummary = resultSummary
+  }
+
+  return normalized
+}
+
 async function appendLiveFeedEvent(config, event) {
   if (!config.runLiveFeedFile) {
     return
   }
-  await fs.mkdir(path.dirname(config.runLiveFeedFile), { recursive: true })
-  await fs.appendFile(config.runLiveFeedFile, `${JSON.stringify(event)}\n`, 'utf8')
+
+  const filePath = config.runLiveFeedFile
+  const previous = liveFeedWriteQueues.get(filePath) ?? Promise.resolve()
+  const next = previous
+    .catch(() => {})
+    .then(async () => {
+      const sanitized = sanitizeLiveFeedEvent(filePath, event)
+      await fs.mkdir(path.dirname(filePath), { recursive: true })
+      await fs.appendFile(filePath, `${JSON.stringify(sanitized)}\n`, 'utf8')
+    })
+
+  liveFeedWriteQueues.set(filePath, next)
+  await next
 }
 
 async function runMockTurn({ config, sessionId, sessionFile, prompt, reason }) {

package/src/pi-debug-live.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import process from 'node:process'
+import { spawn, execFileSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url))
+const packageRoot = path.resolve(scriptDir, '..')
+const cliFile = path.join(scriptDir, 'cli.mjs')
+const fakePiFile = path.join(packageRoot, 'test', 'fixtures', 'fake-pi.mjs')
+const fakeLiveSdkFile = path.join(packageRoot, 'test', 'fixtures', 'fake-live-pi-sdk.mjs')
+const sandboxDir = path.join(packageRoot, '.pi-debug', 'live-ui')
+
+function shellQuote(value) {
+  return JSON.stringify(String(value))
+}
+
+async function ensureRepo(cwd) {
+  try {
+    execFileSync('git', ['rev-parse', '--is-inside-work-tree'], { cwd, stdio: 'ignore' })
+  } catch {
+    execFileSync('git', ['init'], { cwd, stdio: 'ignore' })
+    execFileSync('git', ['config', 'user.name', 'PI Harness Debug'], { cwd, stdio: 'ignore' })
+    execFileSync('git', ['config', 'user.email', 'pi-harness-debug@example.com'], { cwd, stdio: 'ignore' })
+  }
+}
+
+async function seedFiles(cwd) {
+  await fs.mkdir(path.join(cwd, 'pi'), { recursive: true })
+  await fs.writeFile(path.join(cwd, 'TODOS.md'), [
+    '## Phase 1',
+    '',
+    '- [ ] Fake live task one',
+    '- [ ] Fake live task two',
+    '- [ ] Fake live task three',
+    '',
+    '## Phase 2',
+    '',
+    '- [ ] Fake live task four',
+  ].join('\n') + '\n', 'utf8')
+  await fs.writeFile(path.join(cwd, 'DEVELOPER.md'), 'Developer instructions for local visualizer debugging.\n', 'utf8')
+  await fs.writeFile(path.join(cwd, 'TESTER.md'), 'Tester instructions for local visualizer debugging.\n', 'utf8')
+  await fs.writeFile(path.join(cwd, 'pi.config.json'), `${JSON.stringify({
+    transport: 'sdk',
+    taskFile: 'TODOS.md',
+    developerInstructionsFile: 'DEVELOPER.md',
+    testerInstructionsFile: 'TESTER.md',
+    piCli: fakePiFile,
+    piModel: 'fake-model',
+    roleModels: {
+      developer: 'fake-model',
+      developerRetry: 'fake-model',
+      developerFix: 'fake-model',
+      tester: 'fake-model',
+      testerCommit: 'fake-model',
+    },
+    testCommand: `${shellQuote(process.execPath)} -e ${shellQuote('setTimeout(()=>process.exit(0), 250)')}`,
+    streamTerminal: true,
+    continueAfterSeconds: 3600,
+    noEventTimeoutSeconds: 3600,
+    toolContinueAfterSeconds: 3600,
+    toolNoEventTimeoutSeconds: 3600,
+    sleepBetweenSeconds: 1,
+    maxIterations: 20,
+  }, null, 2)}\n`, 'utf8')
+}
+
+async function ensureInitialCommit(cwd) {
+  try {
+    execFileSync('git', ['rev-parse', 'HEAD'], { cwd, stdio: 'ignore' })
+  } catch {
+    execFileSync('git', ['add', '.'], { cwd, stdio: 'ignore' })
+    execFileSync('git', ['commit', '-m', 'chore(debug): seed fake live sandbox'], { cwd, stdio: 'ignore' })
+  }
+}
+
+async function main() {
+  const reset = process.argv.includes('--reset')
+  if (reset) {
+    await fs.rm(sandboxDir, { recursive: true, force: true })
+  }
+
+  await fs.mkdir(sandboxDir, { recursive: true })
+  await ensureRepo(sandboxDir)
+  await seedFiles(sandboxDir)
+  await ensureInitialCommit(sandboxDir)
+
+  process.stdout.write(`PI debug sandbox: ${sandboxDir}\n`)
+  process.stdout.write(`Using fake live SDK fixture: ${fakeLiveSdkFile}\n`)
+
+  const child = spawn(process.execPath, [cliFile, 'run'], {
+    cwd: sandboxDir,
+    env: {
+      ...process.env,
+      PI_CONFIG_FILE: 'pi.config.json',
+      PI_SDK_MODULE: fakeLiveSdkFile,
+      PI_VISUALIZER_HOST: process.env.PI_VISUALIZER_HOST || '127.0.0.1',
+      PI_VISUALIZER_PORT: process.env.PI_VISUALIZER_PORT || '4317',
+    },
+    stdio: 'inherit',
+  })
+
+  child.on('exit', (code, signal) => {
+    if (signal) {
+      process.exitCode = 128
+      return
+    }
+    process.exitCode = code ?? 1
+  })
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.stack ?? error.message : String(error))
+  process.exitCode = 1
+})

package/src/pi-telemetry.mjs

@@ -2,6 +2,8 @@ import fs from 'node:fs/promises'
 import path from 'node:path'
 
 const CSV_HEADER = 'timestamp,run_id,iteration,phase,kind,status,transport,session_id,timed_out,exit_code,duration_seconds,commit_before,commit_after,repo_changed,changed_files_count,verification_status,retry_count,role,model,tool_calls,tool_errors,message_updates,stop_reason,loop_detected,loop_signature,tester_verdict,commit_plan_found,terminal_reason,risk_warnings,notes\n'
+const DEFAULT_JSONL_TAIL_BYTES = 512 * 1024
+const JSONL_TAIL_CHUNK_BYTES = 64 * 1024
 
 function csvEscape(value) {
   const text = String(value ?? '')
@@ -95,15 +97,78 @@ export async function appendTelemetry(config, event) {
   }
 }
 
+function parseJsonlLines(raw, { dropFirstLine = false, maxItems = Infinity } = {}) {
+  const lines = raw.split('\n')
+  if (dropFirstLine && lines.length > 0) {
+    lines.shift()
+  }
+
+  const items = []
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (trimmed === '') {
+      continue
+    }
+    try {
+      items.push(JSON.parse(trimmed))
+    } catch {
+      // Ignore partial/truncated JSONL records while file is actively being appended.
+    }
+  }
+
+  return Number.isFinite(maxItems) ? items.slice(-maxItems) : items
+}
+
+export async function readJsonlTail(filePath, options = {}) {
+  const maxItems = Number.isFinite(Number(options.maxItems)) ? Number(options.maxItems) : 200
+  const maxBytes = Number.isFinite(Number(options.maxBytes)) ? Number(options.maxBytes) : DEFAULT_JSONL_TAIL_BYTES
+
+  let handle
+  try {
+    handle = await fs.open(filePath, 'r')
+    const stat = await handle.stat()
+    if (!Number.isFinite(stat.size) || stat.size <= 0) {
+      return []
+    }
+
+    let position = stat.size
+    let text = ''
+    let newlineCount = 0
+
+    while (position > 0 && Buffer.byteLength(text, 'utf8') < maxBytes && newlineCount <= (maxItems + 1)) {
+      const remainingBudget = maxBytes - Buffer.byteLength(text, 'utf8')
+      const chunkSize = Math.min(JSONL_TAIL_CHUNK_BYTES, position, remainingBudget)
+      if (chunkSize <= 0) {
+        break
+      }
+
+      position -= chunkSize
+      const buffer = Buffer.alloc(chunkSize)
+      const { bytesRead } = await handle.read(buffer, 0, chunkSize, position)
+      text = buffer.subarray(0, bytesRead).toString('utf8') + text
+      newlineCount = (text.match(/\n/g) ?? []).length
+    }
+
+    return parseJsonlLines(text, {
+      dropFirstLine: position > 0,
+      maxItems,
+    })
+  } catch {
+    return []
+  } finally {
+    await handle?.close().catch(() => {})
+  }
+}
+
 export async function readTelemetry(config) {
   try {
     const raw = await fs.readFile(config.telemetryJsonl, 'utf8')
-    return raw
-      .split('\n')
-      .map((line) => line.trim())
-      .filter(Boolean)
-      .map((line) => JSON.parse(line))
+    return parseJsonlLines(raw)
   } catch {
     return []
   }
 }
+
+export async function readTelemetryTail(config, maxItems = 200, maxBytes = DEFAULT_JSONL_TAIL_BYTES) {
+  return await readJsonlTail(config.telemetryJsonl, { maxItems, maxBytes })
+}