pi-harness-runtime 0.10.13 → 0.10.15

package/RFC/0059_EXPERIENCE_REPLAY.md

@@ -1,107 +0,0 @@
-# RFC-0059 — Experience Replay
-
-## 1. Purpose
-
-Experience Replay reconstructs prior runtime execution from persisted events, checkpoints, prompts, outputs, and evaluation evidence. It supports debugging, regression analysis, and reproducibility.
-
-Replay is read-only by default.
-
-## 2. Inputs
-
-```ts
-export interface ReplayRequest {
-  jobId: string;
-  mode: "inspect" | "simulate" | "reexecute";
-  fromSequence?: number;
-  toSequence?: number;
-  allowExternalCalls: boolean;
-}
-```
-
-## 3. Outputs
-
-```ts
-export interface ReplayResult {
-  jobId: string;
-  reconstructedState: JobStateSnapshot;
-  timeline: ReplayEvent[];
-  divergences: ReplayDivergence[];
-  artifacts: string[];
-}
-```
-
-## 4. Modes
-
-### Inspect
-
-Rebuilds state without executing tasks or provider calls.
-
-### Simulate
-
-Runs deterministic runtime transitions using recorded inputs but no external model/provider calls.
-
-### Reexecute
-
-Runs selected steps again. This mode requires explicit approval and isolated worktree.
-
-## 5. Replay Sources
-
-```text
-checkpoint.json
-events.jsonl
-task-graph.json
-prompt packages
-agent reports
-test results
-evaluation results
-repair attempts
-OKF knowledge references
-```
-
-## 6. Determinism
-
-A replay records divergence when:
-
-- Source file hash differs.
-- Project rules changed.
-- Provider output differs.
-- Test environment changed.
-- Required artifact is missing.
-- Runtime version differs.
-
-## 7. Safety
-
-Replay must never:
-
-- Re-run destructive commands without approval.
-- Modify the original worktree.
-- Reuse expired credentials.
-- Send notifications as if replay were live.
-- Mark original tasks complete.
-
-## 8. Runtime Events
-
-```ts
-type ReplayRuntimeEvent =
-  | { type: "replay.started"; jobId: string; mode: string }
-  | { type: "replay.state.reconstructed"; jobId: string; sequence: number }
-  | { type: "replay.divergence.detected"; jobId: string; reason: string }
-  | { type: "replay.completed"; jobId: string };
-```
-
-## 9. Tests
-
-- Reconstructs state from event log.
-- Detects changed source hash.
-- Inspect mode performs no writes.
-- Reexecute mode requires approval.
-- Original task state remains unchanged.
-- Missing artifact creates divergence entry.
-
-## 10. Acceptance Criteria
-
-- Replay can reconstruct any checkpointed job.
-- Inspect mode is strictly read-only.
-- Divergences are explicit.
-- Reexecution is isolated.
-- Original job data is immutable.

package/RFC/0060_MEMORY_ENGINE_OKF.md

@@ -1,152 +0,0 @@
-# RFC-0060 — Memory Engine with OKF Integration
-
-## 1. Purpose
-
-The Memory Engine converts runtime knowledge into durable, human-readable, agent-readable project memory using Google's Open Knowledge Format (OKF).
-
-It bridges temporary Shared Blackboard state and long-term project knowledge.
-
-## 2. Responsibilities
-
-- Read OKF bundles.
-- Validate OKF concept documents.
-- Index concepts.
-- Resolve links.
-- Retrieve relevant knowledge.
-- Export approved lessons.
-- Preserve version history.
-- Generate directory indexes.
-- Record update logs.
-
-## 3. OKF Bundle Structure
-
-```text
-knowledge/
-+-- index.md
-+-- log.md
-+-- runtime/
-|   +-- index.md
-|   +-- loop-runtime.md
-|   +-- shared-blackboard.md
-+-- providers/
-+-- frameworks/
-+-- failures/
-+-- patterns/
-+-- lessons/
-```
-
-## 4. Concept Model
-
-```ts
-export interface OkfConcept {
-  id: string;
-  type: string;
-  title?: string;
-  description?: string;
-  resource?: string;
-  tags: string[];
-  timestamp?: string;
-  metadata: Record<string, unknown>;
-  body: string;
-  links: OkfLink[];
-}
-```
-
-The only required OKF frontmatter field is `type`. Unknown metadata must be preserved.
-
-## 5. Public Interface
-
-```ts
-export interface MemoryEngine {
-  loadBundle(path: string): Promise<KnowledgeBundle>;
-  validateBundle(bundle: KnowledgeBundle): Promise<ValidationResult>;
-  search(query: KnowledgeQuery): Promise<KnowledgeResult[]>;
-  writeConcept(input: WriteConceptRequest): Promise<OkfConcept>;
-  rebuildIndex(path: string): Promise<void>;
-}
-```
-
-## 6. Retrieval
-
-Retrieval combines:
-
-- Exact title match
-- Tag match
-- Concept type
-- Link traversal
-- Framework relevance
-- Task relevance
-- Freshness
-- Authority metadata
-
-## 7. Authority
-
-Recommended extension:
-
-```yaml
-authority: approved | generated | unverified
-```
-
-Consumers should prioritize approved concepts, but must preserve generated and unverified concepts.
-
-## 8. Blackboard Promotion
-
-```text
-runtime state
- -> candidate knowledge
- -> deduplicate
- -> review
- -> approved concept
- -> write OKF
- -> update index.md
- -> append log.md
-```
-
-Temporary status updates should not automatically become durable knowledge.
-
-## 9. Validation
-
-A conformant concept:
-
-- Is UTF-8 Markdown.
-- Contains YAML frontmatter.
-- Contains non-empty `type`.
-- Preserves unknown fields.
-- May contain broken links without failing the entire bundle.
-
-Reserved files:
-
-- `index.md`
-- `log.md`
-
-## 10. Security
-
-The Memory Engine must never persist:
-
-- API keys
-- Cookies
-- Passwords
-- Raw secrets
-- Private user data unrelated to engineering
-- Complete confidential files unless explicitly approved
-
-## 11. Tests
-
-- Loads valid OKF concept.
-- Rejects concept missing `type`.
-- Preserves unknown frontmatter.
-- Tolerates broken link.
-- Generates `index.md`.
-- Appends `log.md`.
-- Searches by tag and type.
-- Exports approved learning item.
-- Rejects secret-like content.
-
-## 12. Acceptance Criteria
-
-- Bundle validation follows OKF v0.1.
-- Unknown frontmatter survives round-trip.
-- Search returns source references.
-- Blackboard content requires promotion review.
-- Index and log generation are deterministic.
-- Secret filtering occurs before persistence.

package/RFC/0061_FRAPPE_PLUGIN.md

@@ -1,9 +0,0 @@
-# RFC-0061 FRAPPE_PLUGIN
-
-Purpose
-- Framework integration
-
-Interface
-```ts
-export interface FrameworkPlugin{detect(root:string):Promise<boolean>;analyze(root:string):Promise<any>;}
-```

package/RFC/0062_NEXTJS_PLUGIN.md

@@ -1,9 +0,0 @@
-# RFC-0062 NEXTJS_PLUGIN
-
-Purpose
-- Framework integration
-
-Interface
-```ts
-export interface FrameworkPlugin{detect(root:string):Promise<boolean>;analyze(root:string):Promise<any>;}
-```

package/RFC/0063_REACT_VITE_PLUGIN.md

@@ -1,9 +0,0 @@
-# RFC-0063 REACT_VITE_PLUGIN
-
-Purpose
-- Framework integration
-
-Interface
-```ts
-export interface FrameworkPlugin{detect(root:string):Promise<boolean>;analyze(root:string):Promise<any>;}
-```

package/RFC/0064_DJANGO_PLUGIN.md

@@ -1,9 +0,0 @@
-# RFC-0064 DJANGO_PLUGIN
-
-Purpose
-- Framework integration
-
-Interface
-```ts
-export interface FrameworkPlugin{detect(root:string):Promise<boolean>;analyze(root:string):Promise<any>;}
-```

package/RFC/0065_LARAVEL_PLUGIN.md

@@ -1,9 +0,0 @@
-# RFC-0065 LARAVEL_PLUGIN
-
-Purpose
-- Framework integration
-
-Interface
-```ts
-export interface FrameworkPlugin{detect(root:string):Promise<boolean>;analyze(root:string):Promise<any>;}
-```

package/RFC/0066_GENERIC_WEB_PLUGIN.md

@@ -1,24 +0,0 @@
-# RFC-0066 — GENERIC WEB PLUGIN
-
-## Purpose
-Defines the architecture contract for the generic web plugin subsystem.
-
-## Scope
-- Responsibilities
-- Public interfaces
-- Runtime events
-- Integration points
-- Acceptance criteria
-
-## Key Interfaces
-- Service
-- Configuration
-- Events
-
-## Dependencies
-To be refined during implementation review.
-
-## Acceptance
-- Typed API
-- Deterministic behavior
-- Unit tests

package/RFC/0067_CLI_PLUGIN_SDK.md

@@ -1,101 +0,0 @@
-# RFC-0067 — CLI Plugin SDK
-
-## Summary
-
-A Node.js CLI SDK for managing pi-harness plugins — install, list, update, remove, and invoke plugin commands. Provides both a programmatic API (`PluginCLI`) and a standalone CLI (`pi-plugin`).
-
-## Architecture
-
-```
-packages/cli-plugin-sdk/
-+-- src/
-|   +-- index.ts          # PluginCLI class + CLI entry
-|   +-- commands/         # Install, list, remove, invoke, update
-|   +-- registry.ts       # npm registry client
-|   +-- plugin-fs.ts      # Filesystem operations
-|   +-- types.ts
-+-- bin/
-|   +-- pi-plugin.js      # CLI entry point
-+-- package.json
-+-- README.md
-```
-
-## CLI Commands
-
-```bash
-pi-plugin install <name> [--version <v>] [--global]
-pi-plugin list [--json]
-pi-plugin remove <name>
-pi-plugin update [name]
-pi-plugin invoke <name> <command> [--args <json>]
-pi-plugin search <query>
-```
-
-## Programmatic API
-
-```typescript
-import { PluginCLI } from '@pi/cli-plugin-sdk';
-
-const cli = new PluginCLI({ cwd: process.cwd() });
-await cli.install('my-plugin');
-await cli.invoke('my-plugin', 'analyze', { path: './src' });
-const plugins = await cli.list();
-await cli.remove('my-plugin');
-```
-
-## Interfaces
-
-```typescript
-// packages/cli-plugin-sdk/src/types.ts
-
-export interface PluginCLIConfig {
-  cwd?: string;
-  globalDir?: string;
-  registry?: string;
-  npmBin?: string;
-}
-
-export interface InstalledPlugin {
-  name: string;
-  version: string;
-  path: string;
-  manifest: PluginManifest;
-}
-
-export interface PluginSearchResult {
-  name: string;
-  version: string;
-  description: string;
-  downloads: number;
-}
-
-export class PluginCLI {
-  constructor(config?: PluginCLIConfig);
-  install(name: string, options?: { version?: string; global?: boolean }): Promise<void>;
-  remove(name: string): Promise<void>;
-  list(options?: { json?: boolean }): Promise<InstalledPlugin[]>;
-  update(name?: string): Promise<void>;
-  search(query: string): Promise<PluginSearchResult[]>;
-  invoke(pluginName: string, command: string, args?: Record<string, unknown>): Promise<unknown>;
-  getPluginPath(name: string): string | null;
-}
-```
-
-## Key Implementation Details
-
-- **Installation**: Uses `npm install` with `--save` or `--global` flag
-- **Plugin directory**: `{cwd}/node_modules/@pi/plugins/` for local, `~/.pi/plugins/` for global
-- **Manifest validation**: Validates `package.json` has `pi` field with `sdkVersion`
-- **Invoke**: Loads plugin module and calls exported function by name
-- **Search**: Queries npm registry for packages matching `@pi/plugin-*` or `@pi/*-plugin`
-
-## Acceptance Criteria
-
-- [ ] `pi-plugin install` installs from npm and validates manifest
-- [ ] `pi-plugin list` shows all installed plugins with versions
-- [ ] `pi-plugin remove` uninstalls and cleans up
-- [ ] `pi-plugin update` updates to latest compatible version
-- [ ] `pi-plugin invoke` calls plugin exported function
-- [ ] `pi-plugin search` queries npm registry
-- [ ] Programmatic `PluginCLI` API works
-- [ ] Unit tests for all commands

package/RFC/0068_MCP_ADAPTER.md

@@ -1,114 +0,0 @@
-# RFC-0068 — MCP Adapter
-
-## Summary
-
-Exposes the pi-harness runtime as a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server. External MCP-compatible clients (Claude Desktop, Cursor, etc.) can discover and invoke harness capabilities as MCP tools, prompts, and resources.
-
-## Architecture
-
-```
-packages/mcp-adapter/
-+-- src/
-|   +-- server.ts           # MCP server (stdio transport)
-|   +-- tools.ts            # Tool definitions (4 core tools)
-|   +-- resources.ts        # Read-only resource handlers
-|   +-- prompts.ts          # Prompt templates
-|   +-- types.ts
-|   +-- index.ts
-+-- package.json
-+-- README.md
-```
-
-## MCP Protocol Compliance
-
-- **Transport**: STDIO (JSON-RPC 2.0 over stdin/stdout)
-- **Protocol version**: 2024-11-05
-- **Schema**: Follows MCP JSON-RPC request/response convention
-
-## Exposed Tools
-
-| Tool | Description | Parameters |
-|------|-------------|------------|
-| `analyze_workspace` | Analyze a codebase directory | `{ path: string, framework?: string }` |
-| `search_memory` | Search harness memory store | `{ query: string, limit?: number }` |
-| `list_skills` | List available harness skills | `{ capability?: string }` |
-| `invoke_skill` | Invoke a named skill | `{ name: string, trigger: object }` |
-
-## Exposed Resources
-
-| URI | Description |
-|-----|-------------|
-| `harness://skills` | JSON list of all registered skills |
-| `harness://capabilities` | Current capability registry |
-| `harness://framework/{name}` | Framework analysis result |
-
-## Exposed Prompts
-
-| Prompt | Description |
-|--------|-------------|
-| `analyze_project` | Full project analysis with recommendations |
-| `review_code` | Code review with context from workspace |
-
-## Server Entry
-
-```typescript
-// src/server.ts
-export async function createMCPServer(options?: MCPServerOptions): Promise<void> {
-  // Read JSON-RPC requests from stdin
-  // Write responses to stdout
-  // Log errors to stderr
-}
-```
-
-## Key Implementation
-
-- **Transport**: STDIO — reads JSON-RPC requests from `process.stdin`, writes to `process.stdout`
-- **Protocol**: MCP 2024-11-05 JSON-RPC 2.0
-- **Server initialization**: Sends `initialize` response with server name/version/capabilities
-- **Tool invocation**: Maps MCP `tools/call` to harness internal calls
-- **Resources**: Read-only, served as `resources/list` + `resources/read`
-- **Prompts**: Served as `prompts/list` + `prompts/get`
-- **No network**: STDIO-only for security
-
-## Types
-
-```typescript
-// src/types.ts
-
-export interface MCPServerOptions {
-  name?: string;
-  version?: string;
-  capabilities?: ServerCapabilities;
-}
-
-export interface ServerCapabilities {
-  tools?: { listChanged?: boolean };
-  resources?: { subscribe?: boolean; listChanged?: boolean };
-  prompts?: { listChanged?: boolean };
-}
-
-// MCP JSON-RPC types
-export interface MCPRequest {
-  jsonrpc: "2.0";
-  id: number | string;
-  method: string;
-  params?: Record<string, unknown>;
-}
-
-export interface MCPResponse {
-  jsonrpc: "2.0";
-  id: number | string;
-  result?: unknown;
-  error?: { code: number; message: string; data?: unknown };
-}
-```
-
-## Acceptance Criteria
-
-- [ ] MCP server starts and responds to `initialize`
-- [ ] `tools/list` returns 4 harness tools
-- [ ] `tools/call` invokes tool and returns result
-- [ ] `resources/list` returns harness resources
-- [ ] `prompts/list` returns harness prompts
-- [ ] STDIO transport works correctly
-- [ ] Unit tests for tool handlers

package/RFC/0069_GOOGLE_A2A_ADAPTER.md

@@ -1,139 +0,0 @@
-# RFC-0069 — Google A2A Adapter
-
-## Summary
-
-Implements the [Google Agent-to-Agent (A2A) protocol](https://google.github.io/A2A/) to enable pi-harness agents to discover, communicate, and delegate tasks to other A2A-compatible agents. Bridges the harness agent system with the broader A2A ecosystem.
-
-## Architecture
-
-```
-packages/a2a-adapter/
-+-- src/
-|   +-- agent.ts              # A2AAgent class (agentcard, task handling)
-|   +-- client.ts             # A2AClient class (agent discovery, delegation)
-|   +-- protocol.ts           # A2A protocol types and constants
-|   +-- transport.ts          # HTTP transport with SSE support
-|   +-- types.ts
-|   +-- index.ts
-+-- package.json
-+-- README.md
-```
-
-## A2A Protocol Overview
-
-A2A defines:
-
-- **AgentCard**: JSON document at `/.well-known/agent.json` describing agent capabilities
-- **Tasks**: Long-running task objects with status updates
-- **Messages**: Task input/output as JSON
-- **Skills**: Agent capability descriptors
-- **Transport**: HTTP + Server-Sent Events (SSE) for streaming
-
-## A2AAgent (Server Side)
-
-```typescript
-// Expose this harness agent as an A2A agent
-export class A2AAgent {
-  constructor(config: A2AAgentConfig);
-
-  // Serve AgentCard at /.well-known/agent.json
-  async serveAgentCard(): Promise<AgentCard>;
-
-  // Handle incoming A2A requests
-  async handleRequest(req: A2ARequest): Promise<A2AResponse>;
-
-  // Send task result back (for push notifications)
-  async sendTaskResult(taskId: string, result: TaskResult): Promise<void>;
-
-  // Stream task updates via SSE
-  streamTaskUpdates(taskId: string): AsyncGenerator<TaskUpdate>;
-}
-```
-
-## A2AClient (Delegate Side)
-
-```typescript
-// Discover and delegate to remote A2A agents
-export class A2AClient {
-  constructor(config?: A2AClientConfig);
-
-  // Discover agent via URL or well-known endpoint
-  async discoverAgent(url: string): Promise<AgentCard>;
-
-  // Search for agents by skill/capability
-  async findAgents(criteria: AgentSearchCriteria): Promise<AgentCard[]>;
-
-  // Send task to agent
-  async sendTask(agentUrl: string, task: Task): Promise<TaskHandle>;
-
-  // Get task result
-  async getTaskResult(taskId: string, agentUrl: string): Promise<TaskResult>;
-
-  // Subscribe to task updates (SSE)
-  subscribeToTask(taskId: string, agentUrl: string): AsyncGenerator<TaskUpdate>;
-}
-```
-
-## AgentCard
-
-```typescript
-export interface AgentCard {
-  name: string;
-  description: string;
-  url: string;
-  version: string;
-  capabilities: {
-    streaming?: boolean;
-    pushNotifications?: boolean;
-    stateTransitionHistory?: boolean;
-  };
-  skills: Skill[];
-  authentication?: { schemes: string[] };
-  defaultInputModes?: string[];
-  defaultOutputModes?: string[];
-}
-
-export interface Skill {
-  id: string;
-  name: string;
-  description: string;
-  tags?: string[];
-  inputModes?: string[];
-  outputModes?: string[];
-}
-```
-
-## Task Lifecycle
-
-```
-SendingAgent -> [send_task] -> ReceivingAgent
-                         -> Task created (status: working)
-                         -> TaskUpdate events (optional)
-                         -> Task completed/cancelled/failed
-SendingAgent <-  [task_result] <-  ReceivingAgent
-```
-
-## Harness Integration
-
-```typescript
-// Integrate with harness agent system
-export interface A2AIntegrationConfig {
-  agentUrl: string;
-  agentPort: number;
-  pushUrl?: string;           // For push notifications
-  agentCard: Partial<AgentCard>;
-}
-
-// When harness receives A2A task, route to skill-registry
-// When harness delegates, use A2AClient
-```
-
-## Acceptance Criteria
-
-- [ ] `A2AAgent` serves valid AgentCard at well-known endpoint
-- [ ] `A2AAgent` handles `send_task` requests and returns task result
-- [ ] `A2AClient` discovers agents via well-known URL
-- [ ] `A2AClient` sends tasks and retrieves results
-- [ ] SSE streaming for task updates works
-- [ ] Harness skill-registry used for task routing
-- [ ] Unit tests for all components