pi-harness-runtime 1.1.445 → 1.1.447

package/auto-resume-fix-prompt.md

@@ -1,189 +0,0 @@
-# Auto-Resume Fix After Context Overflow Compaction
-
-## Problem Statement
-
-After context overflow compaction with `willRetry=false`, the agent does NOT automatically resume. The session pauses waiting for user input, even though context-mode has a resume snapshot that should be delivered.
-
-## Root Cause Analysis
-
-### The Compaction Flow
-
-1. **Context overflow occurs** -> `_checkCompaction()` is called
-2. **For overflow with `stopReason === "stop"`** (the common case):
-   - `willRetry = assistantMessage.stopReason !== "stop"` -> **FALSE**
-   - Calls `_runAutoCompaction("overflow", false)`
-3. **Inside `_runAutoCompaction`** (line 1685):
-
-   ```javascript
-   return this.agent.hasQueuedMessages();  // <-  Returns FALSE for overflow case!
-   ```
-
-4. **Result**: Session pauses waiting for user input
-
-### Why Context-Mode Resume Wasn't Delivered
-
-Context-mode builds resume snapshot in `session_before_compact` and stores it in DB:
-
-```javascript
-// From extension.js
-pi.on("session_before_compact", () => {
-    const snapshot = buildResumeSnapshot(allEvents, { compactCount });
-    db.upsertResume(_sessionId, snapshot, allEvents.length);
-});
-```
-
-But resume was only injected in `before_agent_start` via the `context` hook:
-
-```javascript
-pi.on("before_agent_start", async (event, ctx) => {
-    const resume = db.getResume(_sessionId);
-    if (resume && !resume.consumed && resume.snapshot) {
-        parts.push(resume.snapshot);
-        db.markResumeConsumed(_sessionId);
-    }
-    // ...
-});
-```
-
-**Problem**: `before_agent_start` only fires when a **new prompt is submitted**. After overflow compaction with `willRetry=false`, no prompt is submitted -> resume is never delivered.
-
-## Solution Implemented: Post-Compaction Message Queue
-
-Added a new extension API `queuePostCompactionMessage()` that allows extensions to queue messages that should be delivered after compaction completes, even when `willRetry=false`.
-
-### Flow After Fix
-
-1. `session_before_compact` -> Build resume snapshot in DB
-2. `session_compact` -> Queue resume via `ctx.queuePostCompactionMessage()`
-3. After compaction completes -> `drainPostCompactionMessages()` delivers queued messages
-4. Agent continues and delivers resume automatically
-
-## Files Changed
-
-### 1. `pi-coding-agent/dist/core/extensions/types.d.ts`
-
-Added new API to `ExtensionContext` and `ExtensionContextActions`:
-
-```typescript
-// ExtensionContext
-/**
- * Queue a message to be delivered after compaction completes.
- * When willRetry=false (e.g. overflow without context recovery), the agent
- * will continue and deliver these queued messages before pausing for user input.
- * Useful for resuming context-mode's snapshot after overflow compaction.
- */
-queuePostCompactionMessage(message: { role: string; content: string }): void;
-
-// ExtensionContextActions
-queuePostCompactionMessage: (message: { role: string; content: string }) => void;
-```
-
-### 2. `pi-coding-agent/dist/core/extensions/runner.js`
-
-Added new methods to `ExtensionRunner`:
-
-```javascript
-// Instance variable
-_postCompactionMessages = [];
-
-// Method to queue messages (called from extension context)
-queuePostCompactionMessageFn = (message) => {
-    this._postCompactionMessages.push(message);
-};
-
-// Method to get and clear messages (called by agent-session after compaction)
-drainPostCompactionMessages() {
-    if (this.staleMessage) {
-        return [];  // Don't drain if stale
-    }
-    const messages = this._postCompactionMessages;
-    this._postCompactionMessages = [];
-    return messages;
-}
-
-// Check if runner is stale (without throwing)
-isStale() {
-    return Boolean(this.staleMessage);
-}
-```
-
-### 3. `pi-coding-agent/dist/core/agent-session.js`
-
-Modified `_runAutoCompaction()` to check for and deliver post-compaction messages:
-
-```javascript
-// After compaction completes (line 1682)
-this._emit({ type: "compaction_end", reason, result, aborted: false, willRetry });
-
-if (willRetry) {
-    // ... existing retry logic
-    return true;
-}
-
-// Check for post-compaction messages from extensions
-if (this._extensionRunner && !this._extensionRunner.isStale()) {
-    const postCompactionMessages = this._extensionRunner.drainPostCompactionMessages();
-    for (const msg of postCompactionMessages) {
-        await this.agent.followUp(msg.content);
-    }
-    if (postCompactionMessages.length > 0) {
-        return true; // Continue to deliver the queued messages
-    }
-}
-
-// Fall back to existing behavior
-return this.agent.hasQueuedMessages();
-```
-
-### 4. `context-mode/build/adapters/pi/extension.js`
-
-Modified `session_compact` handler to queue resume:
-
-```javascript
-pi.on("session_compact", (event, ctx) => {
-    try {
-        if (!_sessionId)
-            return;
-        db.incrementCompactCount(_sessionId);
-
-        // Queue resume snapshot for post-compaction delivery when willRetry=false
-        if (!event.willRetry) {
-            const resume = db.getResume(_sessionId);
-            if (resume && !resume.consumed && resume.snapshot) {
-                ctx.queuePostCompactionMessage?.({
-                    role: "user",
-                    content: resume.snapshot,
-                });
-                db.markResumeConsumed(_sessionId);
-            }
-        }
-    }
-    catch {
-        // best effort
-    }
-});
-```
-
-## Testing
-
-To verify the fix works:
-
-1. **Trigger context overflow** with a long conversation
-2. **Observe compaction happens automatically**
-3. **Agent continues WITHOUT user input**
-4. **Resume snapshot is delivered** and agent continues working
-
-Check with:
-
-```bash
-pi
-# Run a long conversation that triggers overflow
-# Verify agent continues automatically after compaction
-/ctx-stats
-```
-
-## Backward Compatibility
-
-- The new `queuePostCompactionMessage` API is optional (uses `?.` when calling)
-- Extensions that don't use it continue to work unchanged
-- Existing behavior for `willRetry=true` cases is preserved

package/harness/reports/PROJECT_STATE.md

@@ -1,342 +0,0 @@
-# Pi Harness Runtime - Project State Report
-
-**Generated:** 2026-07-06  
-**Last Updated:** 2026-07-06
-
----
-
-## Project Overview
-
-Pi Harness Runtime is a local-first, provider-agnostic AI coding harness for pi.dev. It provides:
-
-- Quota tracking and management
-- Multi-provider support (MiniMax, OpenRouter, etc.)
-- Job state machine with checkpoint/resume
-- Task graph with dependency management
-- Auto-compaction and continuation on output token limits
-- Mobile notifications via Telegram/Ntfy/Webhook
-
----
-
-## Directory Structure
-
-```
-pi-harness-runtime/
-+-- index.ts                    # Main CLI extension entry point
-+-- cli.ts                      # CLI commands
-+-- mirror.ts                   # Provider mirror store
-+-- renderer.ts                 # Status rendering
-+-- tracker.ts                  # Usage tracking
-+-- sync-form.ts                # Manual sync form
-+-- windows.ts                  # Windows aggregation
-+-- harness/                    # Core harness modules
-|   +-- agent-handoff.ts       # Agent handoff protocol
-|   +-- auto-compact.ts         # RFC-0019: Auto Compact
-|   +-- blackboard.ts           # Shared blackboard
-|   +-- context-window-manager.ts
-|   +-- job-state-machine.ts    # Job state machine
-|   +-- loop-runtime.ts         # RFC-0001: Main loop
-|   +-- master-planner.ts       # Task planning
-|   +-- notification-events.ts   # RFC-0022: Notification events
-|   +-- output-limit-handler.ts # RFC-0020: Output limit
-|   +-- partial-recovery.ts     # RFC-0021: Partial recovery
-|   +-- repair-engine.ts        # Repair/retry logic
-|   +-- task-graph.ts           # Task dependency graph
-|   +-- e2e/                    # E2E test engine
-|   +-- project-detector/       # Project type detection
-+-- packages/
-|   +-- auth/                   # Authentication
-|   +-- checkpoint/             # Checkpoint manager
-|   +-- notification/           # RFC-0022: Notification center
-|   |   +-- notification-center.ts
-|   |   +-- types.ts
-|   |   +-- base-adapter.ts
-|   |   +-- adapters/
-|   |       +-- telegram-adapter.ts
-|   |       +-- ntfy-adapter.ts
-|   |       +-- email-adapter.ts
-|   |       +-- webhook-adapter.ts
-|   +-- provider-router/         # Provider routing
-|   +-- providers/              # Provider adapters
-|   +-- quota-manager/         # Quota tracking
-|   +-- runtime/               # Runtime components (NEW)
-|   +-- scheduler/             # Job scheduling
-|   +-- shared-context/        # Shared context
-|   +-- tui/                   # Terminal UI
-|   +-- types/                 # Type definitions
-|   +-- worktree/              # Git worktree management
-+-- RFC/                       # RFC documents (0028 total)
-+-- IMPLEMENTATION/             # Implementation tracking
-|   +-- RFC-XXXX/              # Per-RFC implementation tracking
-|       +-- AI_BRIEF.md
-|       +-- TASKS.md
-|       +-- ACCEPTANCE_CRITERIA.md
-+-- schemas/                   # JSON schemas
-+-- profiles/                  # Provider profiles
-+-- test/                     # Tests
-```
-
----
-
-## RFC Status
-
-### Completed Implementations
-
-| RFC | Name | Status | File(s) |
-| ----- | ------ | -------- | --------- |
-| 0001 | Loop Runtime | ✅ Implemented | `harness/loop-runtime.ts` |
-| 0002 | Provider Adapter | ✅ Implemented | `packages/providers/adapters.ts` |
-| 0003 | Quota Manager | ✅ Implemented | `packages/quota-manager/` |
-| 0004 | Playwright Adapter | ✅ Implemented | `packages/providers/` |
-| 0005 | Git Worktree | ✅ Implemented | `packages/worktree/` |
-| 0006 | Checkpoint Manager | ✅ Implemented | `packages/checkpoint/` |
-| 0007 | Scheduler | ✅ Implemented | `packages/scheduler/` |
-| 0008 | Provider Router | ✅ Implemented | `packages/provider-router/` |
-| 0009 | Shared Context | ✅ Implemented | `packages/shared-context/` |
-| 0010 | Context Window Manager | ✅ Implemented | `harness/context-window-manager.ts` |
-| 0011 | Shared Blackboard | ✅ Implemented | `harness/blackboard.ts` |
-| 0012 | Agent Handoff Protocol | ✅ Implemented | `harness/agent-handoff.ts` |
-| 0013 | E2E Test Engine | ✅ Implemented | `harness/e2e/` |
-| 0014 | Project Detector | ✅ Implemented | `harness/project-detector/` |
-| 0015 | Job State Machine | ✅ Implemented | `harness/job-state-machine.ts` |
-| 0016 | Task Graph | ✅ Implemented | `harness/task-graph.ts` |
-| 0017 | Master Planner | ✅ Implemented | `harness/master-planner.ts` |
-| 0018 | Repair Engine | ✅ Implemented | `harness/repair-engine.ts` |
-| 0019 | Auto Compact and Continue | ✅ Implemented | `harness/auto-compact.ts` |
-| 0020 | Output Token Limit Handler | ✅ Implemented | `harness/output-limit-handler.ts` |
-| 0021 | Partial Response Recovery | ✅ Implemented | `harness/partial-recovery.ts` |
-| 0022 | Notification Center | ✅ Implemented | `packages/notification/` |
-| 0023 | Local Browser Agent | 🔲 Stub Only | - |
-
-### Stubs (Need Implementation)
-
-| RFC | Name | Status |
-| ----- | ------ | -------- |
-| 0024 | Local Runtime Agent | ✅ Implemented - `packages/runtime/local-runtime-agent.ts` |
-| 0025 | Command Executor | ✅ Implemented - `packages/runtime/command-executor.ts` |
-| 0026 | Workspace Manager | ✅ Implemented - `packages/runtime/workspace-manager.ts` |
-| 0027 | Runtime API | ✅ Implemented - `packages/runtime/runtime-api.ts` |
-| 0028 | Policy Engine | ✅ Implemented - `packages/runtime/policy-engine.ts` |
-
----
-
-## Key Implementation Patterns
-
-### 1. RFC Document Structure
-
-Each RFC in `/RFC/` follows this format:
-
-```markdown
-# RFC-XXXX - Title
-
-## Purpose
-## Motivation  
-## Goals
-## Artifact Layout (file structure)
-## Runtime Flow (state diagram)
-## Acceptance Criteria
-```
-
-### 2. Implementation Tracking
-
-Each RFC in `/IMPLEMENTATION/RFC-XXXX/` contains:
-
-- `AI_BRIEF.md` - Brief description of what to implement
-- `TASKS.md` - Task list (Read RFC, Implement, Test)
-- `ACCEPTANCE_CRITERIA.md` - Success criteria
-
-### 3. Class Naming Convention
-
-- **Core Engine:** `[Name]Engine` or `[Name]Manager`
-  - Example: `AutoCompactEngine`, `JobStateMachine`, `TaskGraphManager`
-- **Runtime:** `[Name]Runtime`
-  - Example: `LoopRuntime`, `LocalRuntimeAgent`
-- **Adapter:** `[Name]Adapter` extends `BaseChannelAdapter`
-  - Example: `TelegramAdapter`, `NtfyAdapter`
-- **Handler:** `[Name]Handler`
-  - Example: `OutputLimitHandler`, `PartialRecovery`
-
-### 4. TypeScript Conventions
-
-- Uses ESM (`import/export`)
-- JSDoc comments for documentation
-- Interfaces for public APIs, types for unions
-- Error handling with typed errors
-- Async/await pattern for I/O
-
-### 5. File Paths
-
-- Harness modules: `harness/[module-name].ts`
-- Package modules: `packages/[name]/[module-name].ts`
-- Adapters: `packages/notification/adapters/[name]-adapter.ts`
-
----
-
-## Configuration
-
-### Environment Variables
-
-```
-# Provider
-MINIMAX_API_KEY=
-OPENROUTER_API_KEY=
-
-# Notification
-TELEGRAM_BOT_TOKEN=
-TELEGRAM_CHAT_ID=
-NTFY_TOPIC=
-NTFY_SERVER=https://ntfy.sh
-NTFY_TOKEN=
-NOTIFICATION_WEBHOOK_URL=
-NOTIFICATION_WEBHOOK_METHOD=POST
-
-# Paths
-PI_USAGE_DIR=~/.pi/usage-status
-PI_HARNESS_DIR=~/.pi/harness
-```
-
-### Runtime Storage
-
-- **Usage tracking:** `~/.pi/usage-status/`
-- **Harness state:** `~/.pi/harness/[jobId]/`
-  - `checkpoint.json` - Job checkpoint
-  - `context/` - Compaction artifacts
-  - `partial/` - Partial responses
-  - `events.jsonl` - Event log
-
----
-
-## Event Types (RFC-0022)
-
-```typescript
-type NotificationEvent =
-  | "JobStarted"
-  | "TaskCompleted"
-  | "TaskFailed"
-  | "QuotaPaused"
-  | "ResumeScheduled"
-  | "ContextCompacted"
-  | "OutputLimitContinued"
-  | "E2EFailed"
-  | "HumanReviewNeeded"
-  | "ReadyForClient"
-  | "JobCancelled"
-  | "Error";
-```
-
----
-
-## State Machine States
-
-```
-pending -> planning -> running <-> repairing <-> testing <-> reviewing
-    |         |          |              |            |
-    v         v          v              v            v
- cancelled  paused   waiting_human   paused_quota  ready_for_client
-```
-
----
-
-## ✅ IMPLEMENTED: RFCs 0024-0028
-
-### RFC-0024: Local Runtime Agent ✅
-
-**File:** `packages/runtime/local-runtime-agent.ts`
-
-- HTTP server for quota checking
-- Coordinates with Local Browser Agent (RFC-0023)
-- Security: redact sensitive data, localhost binding
-
-### RFC-0025: Command Executor ✅
-
-**File:** `packages/runtime/command-executor.ts`
-
-- Safe shell command execution
-- Timeout, output capture
-- Security policies with allowlist/denylist
-
-### RFC-0026: Workspace Manager ✅
-
-**File:** `packages/runtime/workspace-manager.ts`
-
-- Workspace directory management
-- Worktree lifecycle
-- Automatic cleanup policies
-
-### RFC-0027: Runtime API ✅
-
-**File:** `packages/runtime/runtime-api.ts`
-
-- HTTP/RPC API for runtime control
-- Job management endpoints
-- WebSocket support for real-time events
-
-### RFC-0028: Policy Engine ✅
-
-**File:** `packages/runtime/policy-engine.ts`
-
-- Command execution policies
-- Network access policies
-- Rate limiting & audit logging
-
----
-
-## Provider Usage Data
-
-See: `harness/reports/PROVIDER_USAGE_RESEARCH.md`
-
-| Provider | Method | Status |
-| ---------- | -------- | -------- |
-| MiniMax | Browser scraping | 🔄 Testing |
-| OpenAI (GPT) | TUI parsing | ✅ Implemented |
-| GLM (Zhipu) | TUI parsing | ✅ Implemented |
-
-### Unified Approach
-
-All providers use TUI message parsing (except MiniMax which needs browser).
-No API keys needed - hooks into pi's error/status messages.
-
----
-
-## Dependencies
-
-```json
-{
-  "dependencies": {
-    "node:fs": "built-in",
-    "node:path": "built-in",
-    "node:os": "built-in",
-    "node:http": "built-in",
-    "node:events": "built-in",
-    "ws": "WebSocket support"
-  }
-}
-```
-
----
-
-## Testing
-
-Test files located in `/test/`:
-
-- Unit tests for core modules
-- Integration tests for state machine
-- E2E test engine in `harness/e2e/`
-
----
-
-## Next Steps
-
-1. ~~Complete RFC-0024~~ - Local Runtime Agent ✅
-2. ~~Implement RFC-0025~~ - Command Executor ✅
-3. ~~Implement RFC-0026~~ - Workspace Manager ✅
-4. ~~Implement RFC-0027~~ - Runtime API ✅
-5. ~~Implement RFC-0028~~ - Policy Engine ✅
-6. ~~Update index.ts~~ - Package exports ✅
-
-### New Priority Items
-
-1. **Implement OpenAI billing API** usage fetcher
-2. **Research GLM** usage API
-3. Debug MiniMax browser scraping
-4. Add acceptance tests for RFC-0024-0028

package/harness/reports/PROVIDER_USAGE_RESEARCH.md

@@ -1,115 +0,0 @@
-# Provider Usage API Research
-
-**Date:** 2026-07-06  
-**Updated:** Unified TUI Integration
-
----
-
-## Summary: Unified TUI Message Parsing
-
-All providers (except MiniMax) report quota exhaustion via TUI in pi.dev. No API keys needed!
-
-| Provider | Method | File | Status |
-| ---------- | -------- | ------ | -------- |
-| OpenAI (GPT) | TUI message | `tui-usage-monitor.ts` | ✅ |
-| GLM (Zhipu) | TUI message | `tui-usage-monitor.ts` | ✅ |
-| Anthropic (Claude) | TUI message | `tui-usage-monitor.ts` | ✅ |
-| OpenRouter | TUI message | `tui-usage-monitor.ts` | ✅ |
-| MiniMax | Browser scraping | `minimax-browser-auth.ts` | 🔄 |
-
----
-
-## Architecture
-
-### Unified TUI Usage Monitor
-
-**File:** `packages/quota-manager/tui-usage-monitor.ts`
-
-The `TUIUsageMonitor` handles all TUI-based providers:
-
-- Detects provider from message content
-- Parses reset time and limit type
-- Records to QuotaManager automatically
-
-### Integration
-
-```typescript
-import { QuotaManager, TUIUsageMonitor } from "@pi-harness/quota-manager";
-
-const quotaManager = new QuotaManager();
-
-const monitor = new TUIUsageMonitor({
-  quotaManager,
-  debug: true,
-});
-
-// Hook into pi
-pi.on("error", (event) => monitor.processMessage(event.message));
-pi.on("message", (event) => monitor.processMessage(event.message));
-
-// Check availability
-if (!quotaManager.isAvailable("openai")) {
-  const waitTime = quotaManager.getWaitTime("openai");
-  console.log(`Waiting ${waitTime}ms for OpenAI`);
-}
-```
-
-### Detected Patterns
-
-| Provider | Patterns |
-| ---------- | ---------- |
-| OpenAI | `OpenAI`, `GPT`, `insufficient_quota`, `429` |
-| GLM | `GLM`, `Zhipu`, `tokens exhausted` |
-| Anthropic | `Claude`, `Anthropic`, `rate_limit_error` |
-| OpenRouter | `OpenRouter`, `quota exhausted` |
-
----
-
-## MiniMax (Separate)
-
-**File:** `packages/auth/src/minimax-browser-auth.ts`
-
-MiniMax requires browser scraping because it doesn't expose usage via TUI.
-
-**Solution:** Local Browser Agent (RFC-0023 + RFC-0024)
-
----
-
-## Files Created/Updated
-
-```
-packages/
-+-- quota-manager/
-|   +-- quota-manager.ts       # Core quota tracking
-|   +-- tui-usage-monitor.ts  # ✅ NEW - Unified TUI parser
-|   +-- index.ts               # ✅ NEW - Exports
-|   +-- examples/
-|       +-- tui-usage-integration.ts  # ✅ NEW - Example
-+-- providers/
-|   +-- openai-usage.ts       # Legacy (can be removed)
-|   +-- glm-usage.ts          # Legacy (can be removed)
-packages/
-+-- types/src/
-    +-- runtime-types.ts       # Updated QuotaSignal.source
-```
-
----
-
-## TODO
-
-### ✅ Completed
-
-1. [x] TUIUsageMonitor - unified parser
-2. [x] QuotaManager integration
-3. [x] Multi-provider support
-
-### 🔄 In Progress
-
-4. [ ] Test with actual pi TUI messages
-2. [ ] Add to pi extension
-
-### 📋 MiniMax
-
-- Browser scraping exists but not 100%
-- Needs Local Browser Agent (RFC-0023)
-- Not blocking TUI providers