pi-harness-runtime 0.10.7 → 0.10.11

package/skills/harness-runtime/SKILL.md

@@ -1,237 +0,0 @@
----
-description: Local-first, provider-agnostic AI coding harness runtime for pi.dev with quota management and multi-model coordination
----
-
-# Harness Runtime — pi Extension
-
-**Status:** v0.3.0 | **RFCs:** 18 defined | **Implementation:** Phase 1-6
-
-## Overview
-
-pi-harness-runtime is a local-first, provider-agnostic AI coding harness runtime for pi.dev. It coordinates multiple AI models to complete software engineering tasks with minimal human intervention.
-
-## Core Architecture
-
-```
-Human Requirement
-  -> /harness start <requirement>
-      -> Master Planner (creates task graph)
-      -> Loop Runtime (executes tasks)
-          -> Provider Router (selects best model)
-          -> BlackBoard (coordination)
-          -> Checkpoint Manager (resumability)
-          -> Quota Manager (avoid exhaustion)
-          -> Scheduler (pause/resume)
-          -> Repair Engine (auto-fix failures)
-      -> /harness status (report)
-```
-
-## Commands
-
-### Usage Commands
-
-| Command | Description |
-|---------|-------------|
-| `/usage` | Show full status (local tracking + provider mirror) |
-| `/usage refresh` | Force refresh quota from MiniMax console |
-| `/usage today` | Today's usage + 5h window |
-| `/usage week` | This week's usage + lifetime |
-| `/usage reset` | Clear provider mirror |
-
-### Harness Commands
-
-| Command | Description |
-|---------|-------------|
-| `/harness start <requirement>` | Start a new harness job |
-| `/harness status` | Show current job status |
-| `/harness tasks` | List all tasks |
-| `/harness pause` | Pause the current job |
-| `/harness resume` | Resume a paused job |
-| `/harness cancel` | Cancel the current job |
-
-### Authentication Commands
-
-| Command | Description |
-|---------|-------------|
-| `/harness auth minimax` | Authenticate with MiniMax (opens browser) |
-| `/harness auth check` | Check MiniMax auth status |
-| `/harness auth scrape` | Scrape MiniMax usage (silent, uses saved profile) |
-
-**First-time setup:**
-
-```bash
-harness-auth auth
-# -> Opens Chrome browser, login once, profile auto-saves
-# Or: bun packages/auth/src/run-minimax-auth.ts auth
-```
-
-**Subsequent usage:**
-
-```bash
-harness-auth scrape
-# -> Silent scraping with saved profile
-# Or: bun packages/auth/src/run-minimax-auth.ts scrape
-```
-
-## Job State Machine
-
-```
-created -> planning -> queued -> running -> testing -> reviewing
-    v        v         v        v         v
-cancelled  blocked   waiting_human  repairing  ready_for_client
-                                        v            v
-                                  paused_quota    archived
-```
-
-### State Transitions
-
-| From | Valid Transitions |
-|------|-----------------|
-| created | planning |
-| planning | queued, cancelled |
-| queued | running, cancelled, waiting_human |
-| running | testing, reviewing, repairing, paused_quota, blocked, waiting_human, cancelled |
-| testing | reviewing, running, repairing, paused_quota, waiting_human, cancelled |
-| reviewing | repairing, running, ready_for_client, paused_quota, waiting_human, cancelled |
-| repairing | running, testing, reviewing, paused_quota, waiting_human, cancelled |
-| paused_quota | running, waiting_human, cancelled |
-
-## Task Graph
-
-Tasks are organized as a DAG (Directed Acyclic Graph):
-
-- Tasks with dependencies are marked `pending` until all dependencies are `done`
-- Tasks without dependencies start as `ready`
-- Only `ready` tasks are picked for execution
-
-## Key Components
-
-### JobStateMachine (`harness/job-state-machine.ts`)
-
-- Manages job lifecycle states
-- Emits events on every transition
-- Auto-checkpoints to disk
-
-### TaskGraphManager (`harness/task-graph.ts`)
-
-- DAG-based task representation
-- Tracks task status and dependencies
-- Computes topological execution order
-
-### MasterPlanner (`harness/master-planner.ts`)
-
-- Converts requirements to task graphs
-- Heuristic planner (no LLM needed)
-- LLM-based planner (with provider config)
-
-### RepairEngine (`harness/repair-engine.ts`)
-
-- Converts failures to repair tasks
-- Retry policy with exponential backoff
-- Auto-escalation after max retries
-
-### SharedBlackboard (`harness/blackboard.ts`)
-
-- File-based agent coordination
-- Next-action queue
-- Agent registry and locks
-
-### LoopRuntime (`harness/loop-runtime.ts`)
-
-- Core execution loop
-- Picks ready tasks, executes, tests, reviews
-- Handles failures and quota exhaustion
-
-### ContextWindowManager (`harness/context-window-manager.ts`)
-
-- Tracks context usage per provider
-- Warning at 80%, critical at 95%
-- Truncation strategy
-
-### AgentHandoffProtocol (`harness/agent-handoff.ts`)
-
-- Clean agent transitions
-- Context transfer
-- Handoff validation
-
-### E2ETestEngine (`harness/e2e/test-engine.ts`)
-
-- Scenario-based E2E testing
-- Screenshot/video on failure
-- Playwright runner integration
-
-### ProjectDetector (`harness/project-detector/detector.ts`)
-
-- Auto-detect: Frappe, Next.js, React, Django, Laravel
-- Seed strategy recommendation
-- E2E strategy recommendation
-
-## Providers
-
-### Provider Adapter (`packages/providers/adapters.ts`)
-
-- MiniMax, OpenAI adapters
-- Unified error parsing
-- Quota signal extraction
-
-### Quota Manager (`packages/quota-manager/quota-manager.ts`)
-
-- Collects signals from API, Playwright, local estimates
-- Tracks 5h, daily, weekly, monthly windows
-- Selects best available provider
-
-### Worktree Manager (`packages/worktree/worktree.ts`)
-
-- Git worktree per task
-- Isolated workspaces
-- Diff tracking
-
-## Usage Example
-
-```typescript
-// Start a new job
-/harness start Build a REST API with authentication
-
-// Monitor progress
-/harness status
-/harness tasks
-
-// Pause when quota is low
-/harness pause
-
-// Resume when quota resets
-/harness resume
-
-// Cancel if needed
-/harness cancel
-```
-
-## Data Directory
-
-All harness data is stored in `~/.pi/harness/`:
-
-```
-~/.pi/harness/
-  jobs/
-    <job-id>/
-      checkpoint.json
-      events.jsonl
-      task-graph.json
-      blackboard/
-      repair-tasks.jsonl
-      handoffs/
-```
-
-## Testing
-
-Run tests with:
-
-```bash
-pi-harness-runtime@latest
-```
-
-## Related Skills
-
-- `form-state-persistence-fix` — Step data persistence patterns
-- `frappe-gl-preview` — GL entry preview pattern
-- `frappe-workflow` — Workflow debugging patterns

package/status-parsers.ts

@@ -1,84 +0,0 @@
-/**
- * Status Line Parsers
- *
- * Keep quota usage data and model context usage separate:
- * - Quota usage data: h5_used_pct / weekly_used_pct
- * - Context window usage: 68.4%/205k
- */
-
-export interface ParsedQuotaUsageData {
-	h5UsedPct: number | null;
-	weeklyUsedPct: number | null;
-}
-
-export interface ParsedContextWindowUsage {
-	usagePct: number;
-	contextWindowTokens: number;
-	usedTokens: number;
-}
-
-function parseTokenCount(raw: string): number | null {
-	const trimmed = raw.trim().replace(/,/g, '');
-	const match = trimmed.match(/^(\d+(?:\.\d+)?)([kKmMbB]?)$/);
-	if (!match) return null;
-
-	const value = Number.parseFloat(match[1]);
-	if (!Number.isFinite(value)) return null;
-
-	const suffix = match[2].toLowerCase();
-	if (suffix === 'k') return Math.round(value * 1_000);
-	if (suffix === 'm') return Math.round(value * 1_000_000);
-	if (suffix === 'b') return Math.round(value * 1_000_000_000);
-	return Math.round(value);
-}
-
-/**
- * Parse a quota usage status line such as `5h: 100% left · week: 26% left`.
- * Returns the underlying usage fields used by the mirror: `h5_used_pct` and
- * `weekly_used_pct`.
- */
-export function parseQuotaUsageStatusLine(
-	value: string,
-): ParsedQuotaUsageData | null {
-	const h5Match = value.match(/5h:\s*(\d+(?:\.\d+)?)%\s*left/i);
-	const weeklyMatch = value.match(/week:\s*(\d+(?:\.\d+)?)%\s*left/i);
-
-	if (!h5Match && !weeklyMatch) {
-		return null;
-	}
-
-	const h5Left = h5Match ? Number.parseFloat(h5Match[1]) : null;
-	const weeklyLeft = weeklyMatch ? Number.parseFloat(weeklyMatch[1]) : null;
-
-	return {
-		h5UsedPct:
-			h5Left === null || !Number.isFinite(h5Left) ? null : 100 - h5Left,
-		weeklyUsedPct:
-			weeklyLeft === null || !Number.isFinite(weeklyLeft)
-				? null
-				: 100 - weeklyLeft,
-	};
-}
-
-/**
- * Parse a context-window status line such as `68.4%/205k`.
- * Returns the usage percentage, total context window, and inferred used tokens.
- */
-export function parseContextWindowStatusLine(
-	value: string,
-): ParsedContextWindowUsage | null {
-	const match = value.match(/(\d+(?:\.\d+)?)%\s*\/\s*([\d,.]+(?:[kKmMbB])?)/);
-	if (!match) return null;
-
-	const usagePct = Number.parseFloat(match[1]);
-	const contextWindowTokens = parseTokenCount(match[2]);
-	if (!Number.isFinite(usagePct) || contextWindowTokens === null) {
-		return null;
-	}
-
-	return {
-		usagePct,
-		contextWindowTokens,
-		usedTokens: Math.round((contextWindowTokens * usagePct) / 100),
-	};
-}

package/tracker.ts

@@ -1,72 +0,0 @@
-/**
- * UsageTracker — append-only JSONL log of every assistant message.
- *
- * Stores one record per assistant message with: timestamp, model id,
- * input/output tokens, cache read/write tokens, total cost USD.
- *
- * File: ~/.pi/usage-status/usage.jsonl (one JSON object per line)
- *
- * No locking — single-process pi uses single-writer. Multi-process safety
- * is not a goal; SQLite would be needed for that.
- */
-
-import {
-	appendJsonl,
-	ensureUsageDir,
-	getUsageLogPath,
-	readJsonl,
-} from "./cli.ts";
-import { unlinkSync } from "node:fs";
-
-export interface UsageRecord {
-	ts: number;          // unix ms
-	model: string;       // model id, e.g. "minimax/MiniMax-M3"
-	input: number;
-	output: number;
-	cache_read: number;
-	cache_write: number;
-	cost: number;        // USD total
-}
-
-export class UsageTracker {
-	private path: string;
-
-	constructor(path: string = getUsageLogPath()) {
-		this.path = path;
-		ensureUsageDir();
-	}
-
-	/** Append one usage record. */
-	append(record: UsageRecord): void {
-		appendJsonl(this.path, record);
-	}
-
-	/** Read all records (newest last). Returns [] if file missing. */
-	all(): UsageRecord[] {
-		return readJsonl<UsageRecord>(this.path);
-	}
-
-	/** Filter records newer than `sinceMs` (inclusive). */
-	since(sinceMs: number): UsageRecord[] {
-		return this.all().filter((r) => r.ts >= sinceMs);
-	}
-
-	/** Filter records within [fromMs, toMs). */
-	between(fromMs: number, toMs: number): UsageRecord[] {
-		return this.all().filter((r) => r.ts >= fromMs && r.ts < toMs);
-	}
-
-	/** Clear all records (testing only). */
-	clear(): void {
-		try {
-			unlinkSync(this.path);
-		} catch {
-			// ignore
-		}
-	}
-
-	/** Total record count. */
-	count(): number {
-		return this.all().length;
-	}
-}

package/windows.ts

@@ -1,121 +0,0 @@
-/**
- * WindowAggregator — compute rolling 5h + weekly windows from local records.
- *
- * We do NOT need provider-reported reset times — we can DERIVE them from our
- * own data: oldest record in window + window duration = when that record
- * will fall out of the window = the "reset" moment for OUR local usage.
- *
- * For provider-mirror reset times, we just read them from MirrorStore.
- */
-
-import type { UsageRecord } from "./tracker.ts";
-
-export const FIVE_HOURS_MS = 5 * 60 * 60 * 1000;
-export const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
-
-export interface WindowStats {
-	tokens: number;
-	requests: number;
-	cost: number;
-	oldest_ts: number | null;   // oldest record in window (for reset calculation)
-}
-
-export interface AggregatedWindows {
-	five_h: WindowStats;
-	weekly: WindowStats;
-	today: WindowStats;         // since midnight UTC (computed too — handy)
-	lifetime: WindowStats;
-}
-
-function emptyWindow(): WindowStats {
-	return { tokens: 0, requests: 0, cost: 0, oldest_ts: null };
-}
-
-function rollUp(records: UsageRecord[]): WindowStats {
-	const stats = emptyWindow();
-	for (const r of records) {
-		const tokens = r.input + r.output + r.cache_read + r.cache_write;
-		stats.tokens += tokens;
-		stats.requests += 1;
-		stats.cost += r.cost;
-		if (stats.oldest_ts === null || r.ts < stats.oldest_ts) {
-			stats.oldest_ts = r.ts;
-		}
-	}
-	return stats;
-}
-
-/** Compute reset time for a rolling window from its oldest record. */
-export function computeLocalResetTime(stats: WindowStats, windowMs: number): number | null {
-	if (stats.oldest_ts === null) return null;
-	return stats.oldest_ts + windowMs;
-}
-
-/** Filter records within a rolling window. */
-function withinWindow(records: UsageRecord[], nowMs: number, windowMs: number): UsageRecord[] {
-	const cutoff = nowMs - windowMs;
-	return records.filter((r) => r.ts >= cutoff);
-}
-
-/** UTC midnight (ms) of the day containing `nowMs`. */
-function utcMidnight(nowMs: number): number {
-	const d = new Date(nowMs);
-	return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate());
-}
-
-/** Monday 00:00 UTC of the week containing `nowMs`. */
-function weeklyCutoff(nowMs: number): number {
-	const d = new Date(nowMs);
-	const day = d.getUTCDay();           // 0=Sun..6=Sat
-	const diff = (day + 6) % 7;          // days since Monday
-	const mondayMidnight = utcMidnight(nowMs) - diff * 86400 * 1000;
-	return mondayMidnight;
-}
-
-/** Main entry: aggregate all windows from raw records. */
-export function aggregateWindows(records: UsageRecord[], nowMs: number = Date.now()): AggregatedWindows {
-	const five_h = rollUp(withinWindow(records, nowMs, FIVE_HOURS_MS));
-	const weekly = rollUp(withinWindow(records, nowMs, SEVEN_DAYS_MS));
-	const today = rollUp(records.filter((r) => r.ts >= utcMidnight(nowMs)));
-	const lifetime = rollUp(records);
-	return { five_h, weekly, today, lifetime };
-}
-
-/**
- * Compute burn rate (% per day) from the weekly mirror.
- * mirror.weekly_used_pct used, time since weekly reset = nowMs - weekly_resets_at.
- */
-export function computeBurnRate(
-	mirrorWeeklyUsedPct: number,
-	weeklyResetsAtMs: number,
-	nowMs: number,
-): { pct_per_day: number; days_until_full: number | null } {
-	const elapsedMs = nowMs - weeklyResetsAtMs;
-	if (elapsedMs <= 0) {
-		return { pct_per_day: 0, days_until_full: null };
-	}
-	const elapsedDays = elapsedMs / (24 * 60 * 60 * 1000);
-	const pctPerDay = mirrorWeeklyUsedPct / elapsedDays;
-	const remainingPct = 100 - mirrorWeeklyUsedPct;
-	if (pctPerDay <= 0) {
-		return { pct_per_day: 0, days_until_full: null };
-	}
-	const daysUntilFull = remainingPct / pctPerDay;
-	return { pct_per_day: pctPerDay, days_until_full: daysUntilFull };
-}
-
-/**
- * Compute the divergence between local-tracked usage and provider mirror.
- * Returns the difference in percentage points (positive = local > mirror).
- *
- * This is a rough check: if local tracking shows 5% used but provider
- * mirror shows 30%, you know other clients (or pre-existing quota) are
- * using the same provider account.
- */
-export function computeLocalVsMirrorDelta(
-	localFiveHPct: number,
-	mirrorFiveHPct: number | undefined,
-): number | null {
-	if (mirrorFiveHPct === undefined) return null;
-	return localFiveHPct - mirrorFiveHPct;
-}