pi-harness-runtime 0.10.13 → 0.10.15

package/RFC/0011_SHARED_BLACKBOARD.md

@@ -1,42 +0,0 @@
-# RFC 0011 - Shared Blackboard
-
-## Purpose
-Define durable file-based coordination so GPT/Codex, MiniMax, GLM, reviewers, and test agents communicate without the human acting as message bus.
-
-## Core Concept
-Agents communicate through runtime-owned files, not direct chat and not manual human copy/paste.
-
-## Blackboard Layout
-```text
-harness/blackboard/
-  status.json
-  next_action.json
-  tasks.json
-  agent_registry.json
-  locks/
-  reports/
-  context/
-  events.jsonl
-```
-
-## Key Rules
-1. Agents read `next_action.json` before starting.
-2. Agents write to expected output files.
-3. Agents never overwrite another agent's report.
-4. Runtime owns status transitions.
-5. Significant writes append to `events.jsonl`.
-
-## Required Events
-- BlackboardInitialized
-- TaskReady
-- AgentStarted
-- AgentReportWritten
-- NextActionUpdated
-- TaskCompleted
-- TaskBlocked
-
-## Acceptance Criteria
-- Planner can write a plan.
-- Coder can discover ready task.
-- Reviewer can discover review task.
-- Runtime can detect completion without human routing.

package/RFC/0012_AGENT_HANDOFF_PROTOCOL.md

@@ -1,41 +0,0 @@
-# RFC 0012 - Agent Handoff Protocol
-
-## Purpose
-Define how one agent's completed work becomes another agent's input without human intervention.
-
-## Handoff States
-```text
-draft -> ready -> accepted -> running -> completed
-draft -> ready -> accepted -> running -> failed
-draft -> ready -> blocked
-```
-
-## Agent Roles
-- master_planner
-- code_writer
-- bug_fixer
-- reviewer
-- test_runner
-- e2e_runner
-- summarizer
-- quota_observer
-
-## Handoff Record
-```json
-{
-  "handoff_id": "handoff_001",
-  "from_agent": "codex-planner",
-  "to_agent": "minimax-coder",
-  "task_id": "task_002",
-  "status": "ready",
-  "input_files": ["harness/blackboard/reports/task_001_plan.md"],
-  "expected_output": "harness/blackboard/reports/task_002_implementation.md",
-  "acceptance_criteria": ["Implementation follows plan", "Tests pass"]
-}
-```
-
-## Acceptance Criteria
-- Planner can hand off to coder.
-- Coder can hand off to reviewer.
-- Reviewer can hand off to repair agent.
-- Runtime can detect completion from handoff output.

package/RFC/0013_E2E_TEST_ENGINE.md

@@ -1,42 +0,0 @@
-# RFC 0013 - E2E Test Engine
-
-## Purpose
-Define browser-based end-to-end testing before work is marked ready for client.
-
-## Core Rule
-No client-ready status without required E2E scenarios passing or being explicitly waived by the human.
-
-## Motivation
-E2E testing is expensive because it requires environment readiness, login/session handling, dummy data, browser navigation, screenshots, traces, cleanup, and failure repair.
-
-## Runtime Stage
-```text
-code -> unit_test -> e2e_test -> review -> ready_for_client
-```
-
-## Tooling Modes
-1. Scripted Playwright tests.
-2. Playwright CLI / agent tool.
-3. Hybrid: generate script from observed browser interaction.
-
-## Artifact Layout
-```text
-harness/e2e/
-  scenarios/
-  test-data/
-  reports/
-  artifacts/screenshots/
-  artifacts/traces/
-  artifacts/videos/
-```
-
-## Failure Handling
-```text
-E2EFailed -> write report -> create repair task -> assign repair agent -> rerun E2E
-```
-
-## Acceptance Criteria
-- Runtime can run E2E scenario.
-- Runtime saves screenshot/trace paths.
-- Runtime creates repair task from failed E2E.
-- Runtime blocks ready_for_client on required E2E failure.

package/RFC/0014_PROJECT_DETECTOR_AND_TEST_DATA_ENGINE.md

@@ -1,35 +0,0 @@
-# RFC 0014 - Project Detector and Test Data Engine
-
-## Purpose
-Detect project framework and choose suitable dummy data, seed strategy, and E2E approach.
-
-## Motivation
-The runtime must work across Frappe/ERPNext, Frappe SPA, Next.js, React/Vite, Django, Laravel, and generic web apps.
-
-## Detection Table
-| Project Type | Signals |
-|---|---|
-| Frappe/ERPNext | `sites/`, `apps/`, `hooks.py`, `doctype/`, `bench` |
-| Frappe SPA | `frappe-bench/apps/*/frontend`, `vite.config.*`, Frappe APIs |
-| Next.js | `next.config.*`, `app/`, `pages/`, `next` dependency |
-| React/Vite | `vite.config.*`, `src/main.tsx`, `index.html` |
-| Django | `manage.py`, `settings.py` |
-| Laravel | `artisan`, `database/seeders` |
-| Generic Web | package.json or unknown web app signals |
-
-## Detection Output
-```json
-{
-  "project_type": "frappe_erpnext",
-  "confidence": 0.92,
-  "signals": ["frappe-bench/apps", "hooks.py", "doctype folders"],
-  "recommended_seed_strategy": "frappe_doc_insert",
-  "recommended_e2e_strategy": "bench_site_browser_flow"
-}
-```
-
-## Acceptance Criteria
-- Runtime can detect Frappe/ERPNext, Next.js, and Vite React.
-- Runtime can choose a seed strategy.
-- Runtime can generate framework-appropriate dummy data plan.
-- E2E engine can consume generated test data.

package/RFC/0015_JOB_STATE_MACHINE.md

@@ -1,45 +0,0 @@
-# RFC-0015 — Job State Machine
-
-## Status
-Proposed
-
-## Motivation
-
-Jobs (one-shot autonomous coding tasks) need a well-defined lifecycle so the harness can track, checkpoint, resume, and expose status throughout execution.
-
-## State Diagram
-
-```
-created -> planning -> queued -> running -> testing -> e2e_testing
-       -> reviewing -> repairing -> paused_quota -> waiting_human
-       -> ready_for_client -> archived
-```
-
-## States
-
-| State | Description |
-|-------|-------------|
-| `created` | Job submitted, not yet planned |
-| `planning` | Master Planner decomposing requirement |
-| `queued` | Waiting for scheduler slot |
-| `running` | Actively executing tasks |
-| `testing` | Unit/integration tests running |
-| `e2e_testing` | End-to-end tests running |
-| `reviewing` | Code review in progress |
-| `repairing` | Auto-fix loop after review failure |
-| `paused_quota` | Paused — quota exhausted |
-| `waiting_human` | Paused — needs human approval |
-| `ready_for_client` | Done — results available |
-| `archived` | Retired from active list |
-
-## Transitions
-
-Every transition emits a `job.state_changed` event to the Event Bus. The Checkpoint Engine snapshots state before each transition for crash-recovery.
-
-## Persistence
-
-Job state is persisted to SQLite after every transition. On restart, the scheduler reloads `queued`, `paused_*`, and `waiting_human` jobs.
-
-## Package
-
-`packages/job-state-machine/`

package/RFC/0016_TASK_GRAPH.md

@@ -1,31 +0,0 @@
-# RFC-0016 — Task Graph
-
-## Status
-Proposed
-
-## Motivation
-
-Complex work must be represented as a Directed Acyclic Graph (DAG) so tasks execute only when all dependencies are satisfied.
-
-## Core Concept
-
-A **TaskGraph** contains **nodes** (tasks) and **edges** (dependencies). A task's status is:
-
-- `PENDING` — not yet ready (dependencies not DONE)
-- `READY` — all dependencies DONE
-- `RUNNING` — currently executing
-- `DONE` — completed successfully
-- `FAILED` — failed (may trigger repair)
-- `SKIPPED` — explicitly skipped
-
-A task becomes `READY` only when all tasks it depends on reach `DONE`.
-
-## Graph Validation
-
-- No cycles allowed (validated on graph build)
-- Leaf tasks (no dependents) trigger graph completion
-- Critical path identification for progress estimation
-
-## Package
-
-`packages/task-graph/`

package/RFC/0017_MASTER_PLANNER.md

@@ -1,32 +0,0 @@
-# RFC-0017 — Master Planner
-
-## Status
-Proposed
-
-## Motivation
-
-Convert a natural-language requirement into an executable TaskGraph, then publish it to the Shared Blackboard for the Scheduler to pick up.
-
-## Pipeline
-
-1. **Requirement Intake** — Parse raw text, extract functional requirements, acceptance criteria
-2. **Decomposition** — Break into implementation tasks using LLM + learned patterns
-3. **Dependency Analysis** — Identify cross-task dependencies, build edges
-4. **Estimation** — Assign story points, deadlines
-5. **Graph Publish** — Write TaskGraph to Shared Blackboard, notify Scheduler
-
-## Output
-
-```ts
-interface PlannerOutput {
-  requirementId: string;
-  graph: TaskGraph;
-  estimates: Map<TaskId, StoryPoints>;
-  blockers: string[]; // requirements that can't be decomposed
-  publishedAt: number;
-}
-```
-
-## Package
-
-`packages/master-planner/`

package/RFC/0018_REPAIR_ENGINE.md

@@ -1,36 +0,0 @@
-# RFC-0018 — Repair Engine
-
-## Status
-Proposed
-
-## Motivation
-
-When a task fails, the Repair Engine automatically generates repair tasks with retry policies and escalation paths.
-
-## Flow
-
-1. Task reports failure with error context
-2. Repair Engine classifies failure type (test, lint, build, runtime, network)
-3. For each classification, generate repair tasks:
-   - **Test failure** -> re-run with verbose output, fix test or fix code
-   - **Build failure** -> fix compilation error, re-run build
-   - **Runtime failure** -> add error handling, retry
-   - **Network failure** -> retry with backoff
-4. Escalate to human if max retries exceeded
-
-## Retry Policy
-
-```ts
-interface RetryPolicy {
-  maxAttempts: number;
-  backoffMs: number;
-  backoffMultiplier: number;
-  jitter: boolean;
-}
-```
-
-Default: 3 attempts, exponential backoff starting at 1000ms.
-
-## Package
-
-`packages/repair-engine/`

package/RFC/0019_AUTO_COMPACT_AND_CONTINUE.md

@@ -1,51 +0,0 @@
-# RFC 0019 - Auto Compact and Continue
-
-## Purpose
-
-Automatically resume work after model/session compaction without requiring the human to type `resume`.
-
-## Motivation
-
-Observed behavior:
-
-```text
-[compaction]
-Compacted from 201,419 tokens
-Error: Model stopped because it reached the maximum output token limit.
-```
-
-Compaction is not completion. The runtime must own continuation.
-
-## Goals
-
-- Detect compaction markers from logs/output.
-- Save compaction artifacts.
-- Generate `continue_prompt.md`.
-- Continue the same task without repeating completed work.
-- Keep the human out of the message-bus role.
-
-## Artifact Layout
-
-```text
-harness/context/
-  compaction_events.jsonl
-  latest_compaction_summary.md
-  continue_prompt.md
-```
-
-## Runtime Flow
-
-```text
-AgentRunning
-  -> CompactionDetected
-  -> SaveCompactionArtifact
-  -> GenerateContinuePrompt
-  -> ContinueSameTask
-  -> ValidateExpectedOutput
-```
-
-## Acceptance Criteria
-
-- Runtime detects compaction.
-- Runtime writes continuation prompt.
-- Agent can continue without human typing `resume`.

package/RFC/0020_OUTPUT_TOKEN_LIMIT_HANDLER.md

@@ -1,49 +0,0 @@
-# RFC 0020 - Output Token Limit Handler
-
-## Purpose
-
-Handle model responses that stop because the maximum output token limit was reached.
-
-## Error Example
-
-```text
-Error: Model stopped because it reached the maximum output token limit.
-The response may be incomplete.
-```
-
-## Classification
-
-| Failure | Runtime Action |
-|---|---|
-| Quota exhausted | pause until reset |
-| Context full | compact and resume |
-| Output token limit | continue same task |
-| Unknown error | retry or escalate |
-
-## Policy
-
-```json
-{
-  "max_continue_attempts": 5,
-  "continuation_backoff_ms": 1000,
-  "require_expected_output_validation": true
-}
-```
-
-## Runtime Flow
-
-```text
-OutputLimitDetected
-  -> SavePartialResponse
-  -> GenerateContinuationPrompt
-  -> RetryContinuation
-  -> MergePartialOutputs
-  -> ValidateExpectedOutput
-```
-
-## Acceptance Criteria
-
-- Runtime detects output-limit messages.
-- Runtime saves partial output.
-- Runtime continues same task.
-- Runtime stops after configurable max attempts.

package/RFC/0021_PARTIAL_RESPONSE_RECOVERY.md

@@ -1,49 +0,0 @@
-# RFC 0021 - Partial Response Recovery
-
-## Purpose
-
-Persist and recover incomplete agent outputs.
-
-## Motivation
-
-Partial output may contain useful plan, code, tests, or reports. It must not be discarded.
-
-## Artifact Layout
-
-```text
-harness/partial/
-  task_004/
-    partial_001.md
-    partial_002.md
-    merged.md
-    recovery_status.json
-```
-
-## Recovery Status
-
-```json
-{
-  "task_id": "task_004",
-  "status": "continuing",
-  "partials": ["partial_001.md"],
-  "merged_output": "merged.md",
-  "attempts": 1,
-  "last_error": "output token limit"
-}
-```
-
-## Merge Strategy
-
-v0.1 merges partials as ordered markdown sections.
-
-Future:
-- JSON-aware merge
-- patch-aware merge
-- code-block extraction
-- semantic duplicate removal
-
-## Acceptance Criteria
-
-- Runtime never loses partial response text.
-- Runtime can continue from partial output.
-- Runtime escalates after repeated partial failures.

package/RFC/0022_NOTIFICATION_CENTER.md

@@ -1,47 +0,0 @@
-# RFC 0022 - Notification Center
-
-## Purpose
-
-Send runtime status, alerts, approvals, and completion messages to mobile phone/tablet.
-
-## Motivation
-
-Human-on-the-loop requires the human to know when the runtime is running, paused, blocked, or ready without sitting in front of pi.dev.
-
-## MVP Channels
-
-- Telegram
-- LINE Messaging / LINE alternative
-- ntfy
-- Email
-- Webhook
-
-OpenClaw can be a later adapter, not an MVP dependency.
-
-## Notification Events
-
-```text
-JobStarted
-TaskCompleted
-QuotaPaused
-ResumeScheduled
-ContextCompacted
-OutputLimitContinued
-E2EFailed
-HumanReviewNeeded
-ReadyForClient
-```
-
-## Security Rules
-
-- Do not send raw cookies.
-- Do not send passwords.
-- Do not send full provider tokens.
-- Do not send full source code by default.
-- Send summaries and file paths.
-
-## Acceptance Criteria
-
-- Runtime sends at least one mobile notification.
-- Notification failure does not crash runtime.
-- Sensitive data is redacted.

package/RFC/0023_LOCAL_BROWSER_AGENT.md

@@ -1,67 +0,0 @@
-# RFC 0023 - Local Browser Agent
-
-## Purpose
-
-Allow a headless server runtime to use a human-owned local browser session for authenticated provider pages such as MiniMax usage console.
-
-## Motivation
-
-Playwright opens a browser on the machine executing the command. A headless server cannot show a login window on the user's iMac.
-
-MiniMax usage page requires authentication:
-
-```text
-https://platform.minimax.io/console/usage
-```
-
-## Core Rule
-
-Authenticated browser sessions live where the human can interact with them.
-
-## Architecture
-
-```text
-Server Runtime
-  -> HTTP/RPC request
-      -> Local Browser Agent on iMac
-          -> Playwright persistent profile
-          -> Human login if needed
-          -> scrape usage/reset time
-      -> return safe quota summary
-```
-
-## Local Agent API
-
-```http
-GET /health
-POST /auth/minimax/start
-GET /quota/minimax
-POST /auth/minimax/reset
-```
-
-## Safe Response
-
-```json
-{
-  "provider": "minimax",
-  "authenticated": true,
-  "checked_at": "2026-07-03T09:00:00+07:00",
-  "usage_text_sample": "Token Plan usage ...",
-  "reset_at": "2026-07-03T14:30:00+07:00"
-}
-```
-
-## Security Rules
-
-- Never return raw cookies.
-- Never return localStorage.
-- Bind to localhost by default.
-- If remote access is needed, require VPN/Tailscale and token.
-- Log only safe summaries.
-
-## Acceptance Criteria
-
-- Local browser agent opens MiniMax console in headed Playwright.
-- Human logs in manually.
-- Persistent profile is reused.
-- Server receives only safe quota summary.

package/RFC/0024_LOCAL_RUNTIME_AGENT.md

@@ -1,3 +0,0 @@
-# RFC 0024
-
-LOCAL_RUNTIME_AGENT

package/RFC/0025_COMMAND_EXECUTOR.md

@@ -1,3 +0,0 @@
-# RFC 0025
-
-COMMAND_EXECUTOR

package/RFC/0026_WORKSPACE_MANAGER.md

@@ -1,3 +0,0 @@
-# RFC 0026
-
-WORKSPACE_MANAGER

package/RFC/0027_RUNTIME_API.md

@@ -1,3 +0,0 @@
-# RFC 0027
-
-RUNTIME_API

package/RFC/0028_POLICY_ENGINE.md

@@ -1,3 +0,0 @@
-# RFC 0028
-
-POLICY_ENGINE

package/RFC/0029_DEEPAGENTS_ADAPTER.md

@@ -1,2 +0,0 @@
-# RFC0029
-DeepAgents is an optional Agent Worker. Runtime keeps scheduler, quota, blackboard, policy.

package/RFC/0030_AGENT_WORKER_INTERFACE.md

@@ -1,2 +0,0 @@
-# RFC0030
-Define common AgentWorker interface for Codex, MiniMax, GLM, GPT and DeepAgents.