pi-harness-runtime 0.10.12 → 0.10.13

package/IMPLEMENTATION/RFC-0105/ACCEPTANCE_CRITERIA.md

@@ -0,0 +1,29 @@
+# RFC-0105 Acceptance Criteria
+
+## Functional Requirements
+
+- [ ] TencentDB-Agent-Memory server deployed and accessible
+- [ ] Skills sync from moocoding-skills to server
+- [ ] MCP tools available: tdai_memory_search
+- [ ] Hybrid search (BM25 + vector + RRF) working
+- [ ] OKF format for skill documents
+- [ ] Periodic sync configured
+
+## Non-Functional Requirements
+
+- [ ] Search latency < 200ms
+- [ ] Sync completes in < 5 minutes for full skills folder
+- [ ] Graceful handling of server unavailable
+
+## Integration Tests
+
+- [ ] Agent queries skills via MCP
+- [ ] Skills appear in search results
+- [ ] Sync detects new/updated/deleted skills
+- [ ] Ranked results with scores
+
+## Documentation
+
+- [ ] Server setup guide
+- [ ] MCP tool reference
+- [ ] Sync configuration

package/IMPLEMENTATION/RFC-0105/FILES.md

@@ -0,0 +1,41 @@
+# RFC-0105 Files
+
+## Source Files
+
+```
+packages/
+  knowledge-retrieval/
+    src/
+      index.ts              # Main exports
+      mcp-client.ts        # MCP client for TencentDB
+      sync.ts              # Skills sync pipeline
+      types.ts             # Shared types
+```
+
+## Configuration
+
+```
+configs/
+  knowledge-retrieval/
+    server.json            # TencentDB server URL
+    sync.json             # Sync schedule
+    embeddings.json       # Embedding config
+```
+
+## Scripts
+
+```
+scripts/
+  sync-skills.ts          # Sync skills to server
+  deploy-memory.sh        # Deploy server
+```
+
+## Documentation
+
+```
+docs/
+  knowledge-retrieval/
+    README.md
+    SERVER_SETUP.md
+    MCP_INTEGRATION.md
+```

package/IMPLEMENTATION/RFC-0106/ACCEPTANCE_CRITERIA.md

@@ -0,0 +1,29 @@
+# RFC-0106 Acceptance Criteria
+
+## Functional Requirements
+
+- [ ] SKILL.md files parsed as OKF documents
+- [ ] Knowledge graph with typed nodes (skill, rfc, implementation, concept)
+- [ ] Provenance edges (implements, documents, related_to)
+- [ ] Links to RFC/*and IMPLEMENTATION/* established
+- [ ] MCP tools: kg_query, kg_node, kg_edges, kg_path
+- [ ] Supersession tracking for skill versioning
+
+## Non-Functional Requirements
+
+- [ ] Graph extraction < 10s for full skills folder
+- [ ] Graph query < 100ms
+- [ ] Graph integrity validation
+
+## Integration Tests
+
+- [ ] Agent finds skill by RFC implementation
+- [ ] Graph path from RFC to Skill works
+- [ ] Supersession chain correct
+- [ ] Skills index updated on SKILL.md change
+
+## Documentation
+
+- [ ] Graph schema reference
+- [ ] Provenance mapping guide
+- [ ] Neo4j migration path

package/IMPLEMENTATION/RFC-0106/FILES.md

@@ -0,0 +1,43 @@
+# RFC-0106 Files
+
+## Source Files
+
+```
+packages/
+  knowledge-graph/
+    src/
+      index.ts              # Main exports
+      okf-parser.ts         # Parse SKILL.md to OKF
+      graph-extractor.ts    # Extract nodes and edges
+      provenance-linker.ts  # Link RFC/IMPLEMENTATION
+      mcp-client.ts         # Graph MCP tools
+      types.ts             # Shared types
+```
+
+## Configuration
+
+```
+configs/
+  knowledge-graph/
+    graph.json             # Graph settings
+    extraction.json       # Extraction rules
+    provenance.json       # Provenance mapping
+```
+
+## Scripts
+
+```
+scripts/
+  extract-knowledge-graph.ts  # Build graph from skills
+  migrate-neo4j.ts           # Future: Neo4j migration
+```
+
+## Documentation
+
+```
+docs/
+  knowledge-graph/
+    README.md
+    GRAPH_SCHEMA.md
+    PROVENANCE.md
+```

package/RFC/0001_LOOP_RUNTIME.md

@@ -0,0 +1,14 @@
+# RFC 0001 - Loop Runtime
+
+Purpose: define the autonomous execution loop.
+
+Loop:
+1. Pick task
+2. Assign provider
+3. Code
+4. Test
+5. Review
+6. Repair
+7. Checkpoint
+8. Pause/Resume
+9. Ready for client

package/RFC/0002_PROVIDER_ADAPTER.md

@@ -0,0 +1,3 @@
+# RFC 0002 - Provider Adapter
+
+Defines a provider-neutral interface. Providers implement invoke(), detectQuota(), estimateReset(), normalizeError(), normalizeUsage().

package/RFC/0003_QUOTA_MANAGER.md

@@ -0,0 +1,3 @@
+# RFC 0003 - Quota Manager
+
+Collects quota signals from API responses, provider status, Playwright, and local estimates. Produces provider availability state.

package/RFC/0004_PLAYWRIGHT_ADAPTER.md

@@ -0,0 +1,3 @@
+# RFC 0004 - Playwright Adapter
+
+Uses a persistent browser profile to read provider console information when no official usage API exists. Initial target: MiniMax usage console.

package/RFC/0005_GIT_WORKTREE.md

@@ -0,0 +1,3 @@
+# RFC 0005 - Git Worktree Manager
+
+Allocates one worktree per task, enabling parallel execution, review, resume, and safe merges.

package/RFC/0006_CHECKPOINT_MANAGER.md

@@ -0,0 +1,56 @@
+# RFC 0006 - Checkpoint Manager
+
+## Purpose
+Persist and restore long-running AI coding jobs.
+
+## Motivation
+The runtime must survive provider quota exhaustion, process crashes, network failures, machine restarts, and manual pause without losing progress.
+
+## Goals
+- Save state after every important transition.
+- Restore last known safe state.
+- Support task-level and job-level recovery.
+- Start local-first with JSON files.
+
+## Non-goals
+- Distributed consensus.
+- Multi-user locking.
+- Cloud checkpoint storage.
+
+## Checkpoint Model
+```json
+{
+  "version": 1,
+  "jobId": "job_001",
+  "status": "paused_quota",
+  "requirement": "Build MiniMax quota resume",
+  "currentTaskId": "task_003",
+  "provider": "minimax",
+  "resumeAt": "2026-07-01T20:30:00+07:00",
+  "lastError": "MiniMax 2056 quota exhausted",
+  "createdAt": "2026-07-01T15:20:00+07:00",
+  "updatedAt": "2026-07-01T15:21:00+07:00"
+}
+```
+
+## Storage Layout
+```text
+~/.pi-harness-runtime/jobs/<job_id>/
+  checkpoint.json
+  tasks.json
+  events.jsonl
+  resume_prompt.md
+  last_error.log
+```
+
+## Interface
+```ts
+interface CheckpointManager {
+  save(checkpoint: RuntimeCheckpoint): Promise<void>;
+  load(jobId: string): Promise<RuntimeCheckpoint | null>;
+  appendEvent(jobId: string, event: RuntimeEvent): Promise<void>;
+}
+```
+
+## Recovery Strategy
+Use atomic writes, append-only event logs, schema validation, and human escalation if state cannot be trusted.

package/RFC/0007_SCHEDULER.md

@@ -0,0 +1,32 @@
+# RFC 0007 - Scheduler
+
+## Purpose
+Decide when to run, pause, retry, or resume work.
+
+## Scheduling Reasons
+- quota_reset
+- retry_after_error
+- wait_for_human
+- run_next_task
+- cancelled
+
+## Goals
+- Resume jobs after quota reset.
+- Retry temporary failures with backoff.
+- Persist scheduled resume times.
+- Work locally without cloud services.
+
+## v0.1 Implementation
+Use a local JSON schedule file and polling.
+
+## Interface
+```ts
+interface RuntimeScheduler {
+  scheduleResume(jobId: string, resumeAt: string, reason: string): Promise<void>;
+  dueJobs(now: Date): Promise<string[]>;
+  cancel(jobId: string): Promise<void>;
+}
+```
+
+## Future
+SQLite queue, systemd timer, cron, BullMQ, or external orchestrator.

package/RFC/0008_PROVIDER_ROUTER.md

@@ -0,0 +1,44 @@
+# RFC 0008 - Provider Router
+
+## Purpose
+Select the best provider/model for each task.
+
+## Motivation
+Different providers have different strengths, prices, quotas, and failure modes. The runtime must not hard-code MiniMax, GLM, or Codex into the core loop.
+
+## Provider State
+```text
+available
+limited
+exhausted
+disabled
+unknown
+```
+
+## Routing Inputs
+- task type
+- provider capability
+- quota state
+- previous failures
+- user preference
+- cost policy
+- speed policy
+
+## Example Policy
+```text
+planner -> codex
+code_generation -> minimax
+bug_fix -> glm
+review -> codex
+fallback -> glm
+```
+
+## Interface
+```ts
+interface ProviderRouter {
+  selectProvider(task: RuntimeTask, context: RuntimeContext): Promise<ProviderSelection>;
+}
+```
+
+## Recovery
+If provider fails with quota, mark provider exhausted, ask quota manager for reset time, then schedule resume or select fallback provider.

package/RFC/0009_SHARED_CONTEXT.md

@@ -0,0 +1,32 @@
+# RFC 0009 - Shared Context
+
+## Purpose
+Define how agents share durable context during a long-running coding job.
+
+## Motivation
+A long-running multi-agent coding job needs shared durable state: requirement, plan, task list, decisions, test results, review comments, provider status, and resume prompt.
+
+## Context Layout
+```text
+~/.pi-harness-runtime/jobs/<job_id>/
+  requirement.md
+  plan.md
+  tasks.json
+  decisions.md
+  review.md
+  resume_prompt.md
+  events.jsonl
+```
+
+## Interface
+```ts
+interface SharedContextStore {
+  writeRequirement(jobId: string, text: string): Promise<void>;
+  readRequirement(jobId: string): Promise<string | null>;
+  writeResumePrompt(jobId: string, text: string): Promise<void>;
+  appendDecision(jobId: string, text: string): Promise<void>;
+}
+```
+
+## Design Rule
+Shared context is runtime-owned durable project memory, not one model's chat history.

package/RFC/0010_CONTEXT_WINDOW_MANAGER.md

@@ -0,0 +1,50 @@
+# RFC 0010 - Context Window Manager
+
+## Purpose
+Prevent model context overflow by extracting durable runtime state before the context window becomes full.
+
+## Core Rule
+Chat history is temporary. Runtime context is durable.
+
+## Motivation
+Long-running coding sessions eventually hit context pressure. When context is full, agents forget decisions, repeat work, or require the human to type `resume`.
+
+## Goals
+- Estimate context pressure per provider/model.
+- Trigger compaction before overflow.
+- Extract decisions, task state, open questions, errors, and next action.
+- Write `resume_prompt.md`.
+- Allow a new agent session to continue without human context routing.
+
+## Trigger Policy
+Recommended defaults:
+
+```text
+warning_threshold = 0.60
+compact_threshold = 0.70
+hard_stop_threshold = 0.85
+```
+
+## Artifact Layout
+```text
+harness/context/
+  current_state.md
+  compact_summary.md
+  decisions.md
+  open_questions.md
+  task_progress.json
+  resume_prompt.md
+  last_agent_report.md
+```
+
+## Runtime Events
+- ContextWarning
+- ContextCompactionStarted
+- ContextCompactionCompleted
+- ResumePromptGenerated
+- ContextHardStop
+
+## Acceptance Criteria
+- Runtime can detect context pressure.
+- Runtime can write compact summary and resume prompt.
+- New agent can continue from durable files.

package/RFC/0011_SHARED_BLACKBOARD.md

@@ -0,0 +1,42 @@
+# 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

@@ -0,0 +1,41 @@
+# 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

@@ -0,0 +1,42 @@
+# 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

@@ -0,0 +1,35 @@
+# 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

@@ -0,0 +1,45 @@
+# 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

@@ -0,0 +1,31 @@
+# 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

@@ -0,0 +1,32 @@
+# 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/`