pi-harness-runtime 0.2.0 → 0.3.1

package/README.md

@@ -1,207 +1,182 @@
 # Pi Harness Runtime
 
-**Codex-style `/usage` status for pi coding agent: local token tracking + manual provider mirror.**
-
-[![npm version](https://img.shields.io/npm/v/pi-harness-runtime?style=for-the-badge)](https://www.npmjs.com/package/pi-harness-runtime)
+[![Beta](https://img.shields.io/badge/version-beta-orange?style=for-the-badge)](https://github.com/ManotLuijiu/pi-harness-runtime)
+[![npm downloads](https://img.shields.io/npm/dm/pi-harness-runtime?style=for-the-badge)](https://www.npmjs.com/package/pi-harness-runtime)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
-[![Platform](https://img.shields.io/badge/Platform-macOS%20|20|Linux-blue?style=for-the-badge)]()
+[![Platform](https://img.shields.io/badge/Platform-macOS%20|Linux-blue?style=for-the-badge)]()
 
-## Why Pi Harness Runtime
+> ⚠️ **⚠️ Beta Notice — Not Production Ready ⚠️**
+> This project is in active development. Core features work but E2E testing is not yet implemented.
+> **148+ downloads** and counting — we appreciate the interest! Help us test by filing issues.
 
-**3-Source Honest Tracking** — Codex-style `/status` for pi: local-tracked tokens + manually-mirrored provider quota + derived projections. No fake precision, no scraping, no password storage.
+**Autonomous AI coding harness for pi: local token tracking + provider mirror + task orchestration.**
 
-**Zero Config** — Works immediately. Auto-tracks every assistant message. Run `/usage sync` once a day to mirror provider quota from `https://platform.minimax.io/console/usage`.
+## Two Flavors
 
-**Local-First Privacy** — All data stays in `~/.pi/usage-status/`. No telemetry, no remote calls, no credential storage. The provider mirror is a 5-second manual entry.
+### 1. `/usage` — Token Tracking (stable ✅)
 
-**Derived Insights** — Auto-computes reset times from your data (no provider API needed), burn rate projections, local-vs-mirror divergence warnings.
+Codex-style usage tracking with local tokens + provider mirror.
 
-## Install
+### 2. `/harness` — Autonomous Coding Loop (beta 🔨)
 
-```bash
-pi install npm:pi-harness-runtime
-```
+Give the runtime a requirement. It keeps working, survives interruption, and returns with code ready for review.
 
-Or install locally for development:
+## Install
 
 ```bash
-git clone https://github.com/ManotLuijiu/pi-harness-runtime.git
-ln -s pi-harness-runtime ~/.pi/agent/extensions/pi-harness-runtime
-pi reload
+pi install npm:pi-harness-runtime
 ```
 
-**Important**: Symlink the **directory** into `~/.pi/agent/extensions/`. Pi's loader scans that directory and reads `package.json`'s `pi.extensions` field for multi-file extensions. Don't symlink a single file (relative imports break) or symlink into `node_modules/` (pi doesn't auto-scan there).
-
-No API keys required. No build step (Bun runs `.ts` directly).
-
 Requires Pi v0.37.3+.
 
-## Quick Start
+## Usage Commands
 
 ```bash
-/usage           # show full status (model, local tracking, provider mirror)
-/usage sync      # open form to mirror provider-side quota
-/usage today     # focused: today's usage + 5h window
-/usage week      # focused: this week's usage + lifetime totals
-/usage reset     # clear provider mirror (force re-sync)
+/usage           # show full status (local tracking + provider mirror)
+/usage sync      # mirror provider quota from console.minimax.io
+/usage today     # today's usage + 5h window
+/usage week      # this week's usage + lifetime totals
+/usage reset     # clear provider mirror
 ```
 
-## Commands
+## Harness Commands
 
-### `/usage`
+```bash
+/harness start <requirement>   # Start a new harness job (beta)
+/harness status               # Show current job status
+/harness tasks                # List all tasks
+/harness pause                # Pause when quota low
+/harness resume               # Resume after quota reset
+/harness cancel               # Cancel job
+```
 
-Show Codex-style usage status. Renders three sections:
+## Example Session
 
 ```
-Codex-style usage status for pi
-────────────────────────────────────────────────────────────────
- Model:        minimax/MiniMax-M3
- Directory:    ~/frappe-bench/apps/thai_business_suite
-
- ① LOCAL TRACKED (ground truth — we count this)
-    This session:   $0.17 · 142k tokens · 17 requests
-    This 5h:        384k tokens · 23 requests · $0.04
-    This week:      1.2M tokens · 67 requests · $0.13
-    Lifetime:       4592 requests · $81.61
-
- ② PROVIDER MIRROR (you enter from console.minimax.io)
-    Last sync:      2 min ago [fresh]
-    Provider:       minimax
-    5h limit:       [████████░░░░░░░░░░░░] 18% left (resets in 4h 54m)
-    Weekly limit:   [████████████████░░░░] 81% left (resets in 2d 13h)
-
- ③ LOCAL RESET TIMES (derived from your data)
-    Local 5h reset:    in 3h 12m (oldest request falls out of window)
-    Local week reset:  in 5d 7h (oldest request falls out of window)
-    Local-vs-mirror:  -12.4% ⚠️  divergence > 5%
-    Burn rate:        11.4% / day → 100% in 2.5 d
-────────────────────────────────────────────────────────────────
+/harness start Build a REST API with JWT authentication
+
+# Runtime creates task graph:
+# task-001: Analyze requirements → ready
+# task-002: Implement API → depends on task-001
+# task-003: Write tests → depends on task-002
+# task-004: Code review → depends on task-003
+
+/harness status
+# Job: job-123, Status: running
+# Tasks: 1/4 done, 1 running
+
+# When quota runs low:
+/harness pause
+# Job paused. Resume when quota resets.
+
+# When quota resets:
+/harness resume
+# Job resumed. Continue working.
+
+# When all tasks complete:
+/harness status
+# Job: job-123, Status: ready_for_client
+# Tasks: 4/4 done ✓
 ```
 
-### `/usage sync`
-
-Open a 6-prompt form to mirror provider-side quota:
+## Architecture
 
 ```
-5h used % (0-100) for minimax: [18]
-5h resets in (hours): [4]
-5h resets in (minutes, 0-59): [56]
-Weekly used % (0-100): [72]
-Weekly resets in (days, 0-7): [2]
-Weekly resets in (hours, 0-23): [13]
+pi-harness-runtime/
+├── index.ts                    # Extension entry point
+├── harness/
+│   ├── job-state-machine.ts   # 14-state lifecycle machine
+│   ├── task-graph.ts           # DAG-based task management
+│   ├── master-planner.ts       # Requirement → task graph
+│   ├── loop-runtime.ts         # Core execution loop
+│   ├── repair-engine.ts        # Auto-fix failures
+│   ├── blackboard.ts           # Agent coordination
+│   ├── context-window-manager.ts # Context tracking
+│   ├── agent-handoff.ts        # Clean agent transitions
+│   ├── e2e/
+│   │   ├── test-engine.ts     # E2E test runner (coming soon)
+│   │   └── playwright-runner.ts # Browser automation
+│   └── project-detector/
+│       └── detector.ts         # Auto-detect project type
+├── packages/
+│   ├── providers/adapters.ts   # MiniMax, OpenAI adapters
+│   ├── quota-manager/          # Quota signal collection
+│   └── worktree/              # Git worktree per task
+└── skills/
+    └── harness-runtime/
+        └── SKILL.md           # Skill documentation
 ```
 
-Saves to `~/.pi/usage-status/mirror.json` and updates the next `/usage` output.
-
-### `/usage today`
-
-Focused view: today's usage + 5h window. Quick check before starting a long session.
-
-### `/usage week`
-
-Focused view: this week's usage + lifetime totals. Good for end-of-week review.
-
-### `/usage reset`
-
-Clear the provider mirror. Local usage log is preserved. Asks for confirmation.
-
-## How It Works
+## Job State Machine
 
-### Data Sources (3-source model)
-
-1. **Local tracked** — every assistant message is logged to `~/.pi/usage-status/usage.jsonl`
-   - Auto-tracked via `message_end` event
-   - Contains: timestamp, model, input/output/cache tokens, cost
-   - Real-time, exact, but only counts THIS pi session
-
-2. **Provider mirror** — manually entered from `https://platform.minimax.io/console/usage`
-   - Stored at `~/.pi/usage-status/mirror.json`
-   - Synced via `/usage sync` form
-   - Ground truth for TOTAL quota (across all clients)
-
-3. **Derived** — burn rate, reset times, divergence
-   - Local reset time = oldest request in window + window duration
-   - Burn rate = mirror weekly % / elapsed days
-   - Divergence warning if local tracking differs from mirror by >5%
-
-### Files Written
-
-| Path | Contents |
-|---|---|
-| `~/.pi/usage-status/usage.jsonl` | Append-only usage log |
-| `~/.pi/usage-status/mirror.json` | Manual provider mirror |
-| (none — pure functions) | CLI helpers in `cli.ts` |
-
-Override location with `PI_USAGE_DIR` env var (useful for testing).
-
-### What's NOT Stored
-
-- Your password (we don't ask for it, ever)
-- Provider session tokens (we don't read browser cookies)
-- Telemetry or remote calls (all local)
-- Auto-send quota (you always confirm any sync)
-
-## Why Manual Mirror?
+```
+created → planning → queued → running → testing → reviewing
+    ↓        ↓         ↓        ↓         ↓
+cancelled  blocked   waiting_human  repairing  ready_for_client
+                                        ↓            ↓
+                                  paused_quota    archived
+```
 
-Most AI providers (MiniMax, Anthropic, OpenAI) don't expose rate limit headers publicly. Two alternatives exist:
+## Key Features
 
-| Approach | Pros | Cons |
-|---|---|---|
-| **Manual mirror** (this) | Zero security risk, 5 sec/day | 1 manual entry |
-| **Browser cookie extraction** (pi-web-access does for Gemini Web) | Fully automatic | ~400 LOC platform-specific code, fragile to auth changes |
-| **HTML scraping** (assumes cookies work) | Once cookies extracted, parsing is easy | Breaks if page redesigns |
+- **Resumable**: Every state change is checkpointed to disk
+- **Quota-aware**: Detects quota exhaustion, pauses, resumes after reset
+- **Provider-agnostic**: MiniMax, OpenAI, Claude adapters
+- **Task DAG**: Dependencies tracked, topological execution
+- **Auto-repair**: Failure classification + retry with exponential backoff
+- **E2E testing**: Scenario-based Playwright integration (coming soon)
+- **Project detection**: Auto-detects Frappe, Next.js, React, Django, Laravel
 
-We chose the manual approach because:
+## Data Directory
 
-1. MiniMax's UI shows reset times like "Resets in 4 hr 56 min" — manual entry is genuinely 5 seconds
-2. Cookie extraction has ongoing maintenance burden
-3. Password storage is a security anti-pattern
+All data stored locally in `~/.pi/`:
 
-If you find yourself needing to sync more than 3x/day, we may add browser cookie extraction as a future enhancement.
+```
+~/.pi/
+├── usage-status/         # /usage data
+│   ├── usage.jsonl
+│   └── mirror.json
+└── harness/            # /harness data
+    └── jobs/
+        └── <job-id>/
+            ├── checkpoint.json
+            ├── events.jsonl
+            ├── task-graph.json
+            ├── blackboard/
+            └── repair-tasks.jsonl
+```
 
 ## Safety Properties
 
-- ✅ **No auto-tracking of other clients** — local data is just this pi session
-- ✅ **No scraping** — provider mirror is manual
-- ✅ **No fabrication** — divergence warning if local and mirror disagree
-- ✅ **Idempotent** — running `/usage` repeatedly has no side effects
-- ✅ **Privacy-respecting** — all data stays on local disk
-- ✅ **No credentials stored** — passwords, tokens, cookies: none
+- ✅ **Local-first**: All data stays on disk
+- ✅ **No credentials stored**: No passwords, tokens, or cookies
+- ✅ **Human-on-the-loop**: Clear intervention points
+- ✅ **Checkpointed**: Resume from any state
+- ✅ **Idempotent**: Safe to run multiple times
 
-## Architecture
+## Testing
 
-```
-pi-harness-runtime/
-├── index.ts              # entry — exports default (pi: ExtensionAPI)
-├── tracker.ts            # UsageTracker — JSONL writer/reader
-├── mirror.ts             # MirrorStore — JSON read/write + freshness check
-├── windows.ts            # WindowAggregator — pure aggregation functions
-├── renderer.ts           # StatusRenderer — Codex-style progress bars
-├── sync-form.ts          # /usage sync form handling
-├── cli.ts                # shared pure helpers (paths, formatting, IO)
-├── skills/
-│   └── harness-runtime/
-│       └── SKILL.md      # bundled skill (auto-loaded)
-├── test/                 # node --test
-│   ├── cli.test.mjs
-│   ├── tracker.test.mjs
-│   ├── mirror.test.mjs
-│   ├── windows.test.mjs
-│   ├── renderer.test.mjs
-│   └── sync-form.test.mjs
-├── package.json          # "pi" field declares extensions + skills
-├── README.md
-├── CHANGELOG.md
-├── LICENSE               # MIT
-└── .gitignore
+```bash
+bun test   # 131+ tests passing
 ```
 
-## Related
+## Roadmap
 
-- [pi-web-access](https://github.com/nicobailon/pi-web-access) — web search + URL fetching for pi (inspiration for this package's structure)
-- [context-mode](https://github.com/MiniMax-AI/context-mode) — context-window tracking (complementary)
-- [pi-coding-agent](https://github.com/earendil-works/pi-coding-agent) — the underlying pi agent
+- [x] Core harness infrastructure (job state machine, task graph)
+- [x] Master planner
+- [x] Repair engine
+- [x] Shared blackboard
+- [ ] E2E test engine integration
+- [ ] MiniMax Web automatic quota detection
+- [ ] Claude adapter
+- [ ] Production stress testing
 
 ## License
 
 MIT © 2026 MooCoding
+
+## Related
+
+- [pi-coding-agent](https://github.com/earendil-works/pi-coding-agent) — Underlying pi agent
+- [context-mode](https://github.com/MiniMax-AI/context-mode) — Context window tracking
+- [pi-web-access](https://github.com/nicobailon/pi-web-access) — Web search for pi

package/harness/agent-handoff.ts

@@ -0,0 +1,189 @@
+/**
+ * Agent Handoff Protocol — RFC-0012
+ *
+ * Clean handoff between agents with context transfer.
+ * Ensures continuity when switching agents mid-task.
+ */
+
+import type {
+	HandoffContext,
+	HandoffEvent,
+} from "../packages/types/src/runtime-types.ts";
+import { writeJson, readJson } from "../cli.ts";
+// @ts-expect-error - Bun has built-in Node.js types
+import { join } from "node:path";
+
+export interface HandoffData {
+	fromAgent: string;
+	toAgent: string;
+	taskId: string;
+	taskSummary: string;
+	contextFiles: string[];
+	recentHistory: string[];
+	currentState: Record<string, unknown>;
+}
+
+export class AgentHandoffProtocol {
+	private readonly rootDir: string;
+
+	constructor(rootDir: string) {
+		this.rootDir = rootDir;
+	}
+
+	/**
+	 * Create a handoff context for switching agents
+	 */
+	createHandoff(
+		jobId: string,
+		taskId: string,
+		fromAgent: string,
+		toAgent: string,
+		currentState?: Record<string, unknown>,
+	): HandoffContext {
+		const events = this.loadHandoffHistory(jobId, taskId);
+
+		return {
+			jobId,
+			taskId,
+			fromAgent,
+			toAgent,
+			sharedFiles: [],
+			taskHistory: events,
+			summary: this.generateSummary(taskId, currentState),
+		};
+	}
+
+	/**
+	 * Record a handoff event
+	 */
+	recordHandoff(context: HandoffContext, result?: string): void {
+		const path = join(
+			this.rootDir,
+			"jobs",
+			context.jobId,
+			"handoffs",
+			`${context.taskId}.json`,
+		);
+		const event: HandoffEvent = {
+			ts: new Date().toISOString(),
+			agentId: context.toAgent,
+			action: "handoff_received",
+			result,
+		};
+		context.taskHistory.push(event);
+		writeJson(path, context);
+	}
+
+	/**
+	 * Generate handoff prompt for the receiving agent
+	 */
+	generateHandoffPrompt(context: HandoffContext): string {
+		const lines = [
+			`## Agent Handoff`,
+			``,
+			`**From Agent:** ${context.fromAgent}`,
+			`**To Agent:** ${context.toAgent}`,
+			`**Task:** ${context.taskId}`,
+			``,
+			`### Task History`,
+		];
+
+		for (const event of context.taskHistory) {
+			lines.push(`- [${event.ts}] ${event.agentId}: ${event.action}`);
+			if (event.result) {
+				lines.push(`  Result: ${event.result}`);
+			}
+		}
+
+		lines.push(``);
+		lines.push(`### Summary`);
+		lines.push(context.summary);
+
+		if (context.sharedFiles.length > 0) {
+			lines.push(``);
+			lines.push(`### Shared Files`);
+			for (const file of context.sharedFiles) {
+				lines.push(`- ${file}`);
+			}
+		}
+
+		return lines.join("\n");
+	}
+
+	/**
+	 * Validate handoff readiness
+	 */
+	validateHandoff(context: HandoffContext): {
+		valid: boolean;
+		issues: string[];
+	} {
+		const issues: string[] = [];
+
+		if (!context.summary) {
+			issues.push("Task summary is empty");
+		}
+
+		if (context.taskHistory.length === 0) {
+			issues.push("No task history recorded");
+		}
+
+		// Check for recent handoffs
+		const recentHandoffs = context.taskHistory.filter((h) => {
+			const age = Date.now() - Date.parse(h.ts);
+			return age < 5 * 60 * 1000; // 5 minutes
+		});
+
+		if (recentHandoffs.length > 3) {
+			issues.push(
+				`Too many recent handoffs (${recentHandoffs.length}). Possible ping-pong.`,
+			);
+		}
+
+		return { valid: issues.length === 0, issues };
+	}
+
+	/**
+	 * Load handoff history for a task
+	 */
+	private loadHandoffHistory(jobId: string, taskId: string): HandoffEvent[] {
+		const path = join(
+			this.rootDir,
+			"jobs",
+			jobId,
+			"handoffs",
+			`${taskId}.json`,
+		);
+		const data = readJson(path) as HandoffContext | null;
+		return data?.taskHistory ?? [];
+	}
+
+	/**
+	 * Generate a summary of the task state
+	 */
+	private generateSummary(
+		taskId: string,
+		currentState?: Record<string, unknown>,
+	): string {
+		if (!currentState) {
+			return `Task ${taskId} requires continuation. Check task files for current state.`;
+		}
+
+		const lines = [`Task ${taskId} is in progress.`];
+
+		if (currentState.filesModified) {
+			lines.push(
+				`Files modified: ${(currentState.filesModified as string[]).join(", ")}`,
+			);
+		}
+
+		if (currentState.lastAction) {
+			lines.push(`Last action: ${currentState.lastAction}`);
+		}
+
+		if (currentState.blockers) {
+			lines.push(`Blockers: ${currentState.blockers}`);
+		}
+
+		return lines.join("\n");
+	}
+}