pi-harness-runtime 0.10.12 → 0.10.13

package/RFC/0059_EXPERIENCE_REPLAY.md

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

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

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

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

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

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

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

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

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

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

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