pi-harness-runtime 0.10.12 → 0.10.13

package/IMPLEMENTATION/RFC-0029/TASKS.md

@@ -0,0 +1,4 @@
+- [x] Read RFC
+- [x] Implement - AgentWorker interface (RFC-0030)
+- [x] Implement - DeepAgentsAdapter (packages/providers/deepagents-adapter.ts)
+- [x] Test - Types compile cleanly

package/IMPLEMENTATION/RFC-0030/AI_BRIEF.md

@@ -0,0 +1 @@
+Implement RFC-0030. Runtime remains orchestrator.

package/IMPLEMENTATION/RFC-0030/TASKS.md

@@ -0,0 +1,3 @@
+- [x] Read RFC
+- [x] Implement - AgentWorker interface (packages/types/src/agent-worker-types.ts)
+- [x] Test - Types compile cleanly

package/IMPLEMENTATION/RFC-0031/AI_BRIEF.md

@@ -0,0 +1,45 @@
+# RFC-0031 AI Brief: Provider Adapter SDK
+
+## Summary
+
+A comprehensive SDK for building, testing, and registering provider adapters that normalize AI provider behavior for MiniMax, OpenAI, Claude, and custom providers.
+
+## Implementation Overview
+
+### Key Classes to Implement
+
+1. **AdapterBuilder** (`builder.ts`)
+   - Fluent API for creating adapters
+   - Configurable capabilities, models, rate limits
+   - Invoke and parseError function registration
+
+2. **AdapterRegistry** (`registry.ts`)
+   - Lifecycle hooks (init, healthCheck, teardown)
+   - Adapter versioning and compatibility
+   - Factory pattern support
+
+3. **AdapterTester** (`tester.ts`)
+   - Test basic invocation
+   - Test quota detection
+   - Test error parsing
+   - Generate mock responses
+
+### Dependencies
+
+- `packages/types` - for runtime-types
+- `packages/providers` - existing adapters to migrate
+
+### Files to Create
+
+- `packages/provider-adapter-sdk/src/builder.ts`
+- `packages/provider-adapter-sdk/src/registry.ts`
+- `packages/provider-adapter-sdk/src/tester.ts`
+- `packages/provider-adapter-sdk/src/types.ts`
+- `packages/provider-adapter-sdk/src/compatibility.ts`
+- `packages/provider-adapter-sdk/src/errors.ts`
+- `packages/provider-adapter-sdk/src/index.ts`
+
+### Integration Points
+
+- Migrate existing adapters from `packages/providers/adapters.ts`
+- Register with RuntimeApi for provider management

package/IMPLEMENTATION/RFC-0031/TASKS.md

@@ -0,0 +1,48 @@
+# RFC-0031 Implementation Tasks
+
+## Phase 1: SDK Foundation
+
+- [ ] Create `packages/provider-adapter-sdk/` directory
+- [ ] Set up package.json with dependencies
+- [ ] Create `src/types.ts` with SDK types
+- [ ] Create `src/errors.ts` with custom errors
+- [ ] Create `src/index.ts` public exports
+
+## Phase 2: Core Classes
+
+- [ ] Implement `AdapterBuilder` class
+  - [ ] Constructor with name parameter
+  - [ ] `config()` method
+  - [ ] `capabilities()` method
+  - [ ] `models()` method
+  - [ ] `rateLimits()` method
+  - [ ] `invoke()` method
+  - [ ] `parseError()` method
+  - [ ] `build()` method
+- [ ] Implement `AdapterRegistry` class
+  - [ ] `register()` with lifecycle hooks
+  - [ ] `unregister()` method
+  - [ ] `getAdapter()` method
+  - [ ] `listAdapters()` method
+  - [ ] `healthCheckAll()` method
+- [ ] Implement `AdapterTester` class
+  - [ ] `testBasicInvocation()`
+  - [ ] `testQuotaDetection()`
+  - [ ] `testErrorParsing()`
+  - [ ] `runAllTests()`
+
+## Phase 3: Compatibility & Migration
+
+- [ ] Implement version compatibility checks
+- [ ] Migrate MiniMax adapter to SDK
+- [ ] Migrate OpenAI adapter to SDK
+- [ ] Migrate Claude adapter to SDK
+- [ ] Add examples in `examples/` directory
+- [ ] Write unit tests
+
+## Phase 4: Documentation
+
+- [ ] Write README.md
+- [ ] Document all public APIs
+- [ ] Add JSDoc comments
+- [ ] Create migration guide

package/IMPLEMENTATION/RFC-0032/AI_BRIEF.md

@@ -0,0 +1,45 @@
+# RFC-0032 AI Brief: Checkpoint Engine
+
+## Summary
+
+An enhanced checkpoint system with incremental snapshots, diff-based storage, compression, and intelligent recovery strategies.
+
+## Implementation Overview
+
+### Key Classes to Implement
+
+1. **CheckpointEngine** (`engine.ts`)
+   - Incremental vs full snapshot handling
+   - Recovery strategies (latest, fullest, specific, timestamp)
+   - Auto-pruning logic
+   - Checksum verification
+
+2. **StorageManager** (`storage.ts`)
+   - Parallel I/O for faster saves
+   - Gzip compression
+   - File rotation and management
+
+3. **DiffCalculator** (`differ.ts`)
+   - Calculate state diffs
+   - Apply incremental changes
+   - Merge delta changes
+
+### Dependencies
+
+- `packages/types` - for runtime-types
+- Existing `packages/checkpoint/checkpoint-manager.ts` (enhance, don't replace)
+
+### Files to Create/Modify
+
+- `packages/checkpoint/src/engine.ts` - main engine
+- `packages/checkpoint/src/storage.ts` - enhanced storage
+- `packages/checkpoint/src/differ.ts` - diff calculations
+- `packages/checkpoint/src/recovery.ts` - recovery strategies
+- `packages/checkpoint/src/indexer.ts` - metadata index
+- `packages/checkpoint/src/types.ts` - extended types
+
+### Backward Compatibility
+
+- Maintain JSON format compatibility
+- Detect and load legacy checkpoints
+- Export to legacy format if needed

package/IMPLEMENTATION/RFC-0032/TASKS.md

@@ -0,0 +1,44 @@
+# RFC-0032 Implementation Tasks
+
+## Phase 1: Engine Core
+
+- [ ] Create `packages/checkpoint/src/engine.ts`
+- [ ] Define `CheckpointEngineConfig` interface
+- [ ] Implement `save()` method with compression
+- [ ] Implement `load()` method
+- [ ] Add checksum generation and verification
+
+## Phase 2: Incremental Storage
+
+- [ ] Implement `saveIncremental()` method
+- [ ] Implement `loadIncremental()` method
+- [ ] Create `DiffCalculator` class
+- [ ] Define `StateDelta` interface
+- [ ] Implement delta application logic
+
+## Phase 3: Recovery System
+
+- [ ] Implement `recover()` method
+- [ ] Create recovery strategies:
+  - [ ] `latest` strategy
+  - [ ] `fullest` strategy
+  - [ ] `specific:version` strategy
+  - [ ] `timestamp:ISO` strategy
+  - [ ] `interactive` strategy
+- [ ] Implement `getMetadata()` for checkpoint listing
+
+## Phase 4: Storage & Performance
+
+- [ ] Implement parallel file I/O
+- [ ] Add gzip compression
+- [ ] Implement `prune()` method
+- [ ] Implement `verify()` for checksum validation
+- [ ] Add caching layer for frequent loads
+
+## Phase 5: Testing & Migration
+
+- [ ] Write migration tests from legacy format
+- [ ] Benchmark incremental vs full saves
+- [ ] Test recovery with various strategies
+- [ ] Verify backward compatibility
+- [ ] Performance testing with large jobs

package/IMPLEMENTATION/RFC-0033/AI_BRIEF.md

@@ -0,0 +1,46 @@
+# RFC-0033 AI Brief: Session Manager
+
+## Summary
+
+A comprehensive session management system for tracking user sessions, maintaining conversation history, and providing session persistence.
+
+## Implementation Overview
+
+### Key Classes to Implement
+
+1. **SessionManager** (`manager.ts`)
+   - Session lifecycle (create, get, close, suspend, resume)
+   - Message history management
+   - Token accounting
+   - Metrics collection
+
+2. **SessionStore** (`store.ts`)
+   - Session persistence to disk
+   - Session indexing and retrieval
+   - Auto-cleanup of expired sessions
+
+3. **SessionPolicyEngine** (`policy.ts`)
+   - Evaluate session limits
+   - Token budget enforcement
+   - Cost tracking
+
+### Dependencies
+
+- `packages/types` - for runtime-types
+- `packages/checkpoint` - for session persistence
+- `packages/quota-manager` - for cost tracking
+
+### Files to Create
+
+- `packages/session/src/manager.ts`
+- `packages/session/src/store.ts`
+- `packages/session/src/history.ts`
+- `packages/session/src/policy.ts`
+- `packages/session/src/metrics.ts`
+- `packages/session/src/types.ts`
+- `packages/session/src/index.ts`
+
+### Integration Points
+
+- Integrate with RuntimeApi for session CRUD endpoints
+- Integrate with ContextWindowManager for token tracking

package/IMPLEMENTATION/RFC-0033/TASKS.md

@@ -0,0 +1,49 @@
+# RFC-0033 Implementation Tasks
+
+## Phase 1: Session Core
+
+- [ ] Create `packages/session/` directory
+- [ ] Define `Session`, `SessionMetadata`, `SessionContext` types
+- [ ] Create `SessionManager` class
+- [ ] Implement `createSession()`
+- [ ] Implement `getSession()`
+- [ ] Implement `closeSession()`
+
+## Phase 2: Lifecycle & State
+
+- [ ] Implement `suspendSession()`
+- [ ] Implement `resumeSession()`
+- [ ] Implement `listSessions()`
+- [ ] Add session timeout handling
+- [ ] Implement auto-suspend for idle sessions
+
+## Phase 3: Message History
+
+- [ ] Create `Message` types
+- [ ] Implement `addMessage()`
+- [ ] Implement `getHistory()` with pagination
+- [ ] Add full-text search support
+- [ ] Implement history pruning
+
+## Phase 4: Policy & Metrics
+
+- [ ] Create `SessionPolicyEngine`
+- [ ] Implement token budget evaluation
+- [ ] Implement cost tracking
+- [ ] Create `getMetrics()` method
+- [ ] Implement `getAllMetrics()`
+
+## Phase 5: Persistence
+
+- [ ] Create `SessionStore` class
+- [ ] Implement session serialization
+- [ ] Implement session restoration
+- [ ] Implement `pruneSessions()`
+- [ ] Implement `cleanupExpired()`
+
+## Phase 6: Integration
+
+- [ ] Integrate with RuntimeApi
+- [ ] Integrate with ContextWindowManager
+- [ ] Write integration tests
+- [ ] Performance benchmarks

package/IMPLEMENTATION/RFC-0034/AI_BRIEF.md

@@ -0,0 +1,54 @@
+# RFC-0034 AI Brief: Observability
+
+## Summary
+
+A comprehensive observability system with structured logging, distributed tracing, metrics collection, health monitoring, and alerting.
+
+## Implementation Overview
+
+### Key Classes to Implement
+
+1. **Logger** (`logger.ts`)
+   - Structured JSON logging
+   - Correlation ID tracking
+   - Log levels and formatting
+   - Child loggers with defaults
+
+2. **Tracer** (`tracer.ts`)
+   - OpenTelemetry compatible
+   - Span management
+   - Distributed tracing
+   - Async wrapper utilities
+
+3. **Metrics** (`metrics.ts`)
+   - Counters, Gauges, Histograms
+   - Prometheus export format
+   - Built-in runtime metrics
+
+4. **HealthMonitor** (`health.ts`)
+   - Health check registration
+   - Liveness/readiness probes
+   - Component health tracking
+
+5. **AlertEngine** (`alerts.ts`)
+   - Alert rule evaluation
+   - Alert actions (log, notify, webhook)
+   - Alert history
+
+### Dependencies
+
+- `packages/types` - for runtime-types
+- Optional: `@opentelemetry/sdk-node` - OTLP export
+- Optional: `prom-client` - Prometheus format
+
+### Files to Create
+
+- `packages/observability/src/logger.ts`
+- `packages/observability/src/tracer.ts`
+- `packages/observability/src/metrics.ts`
+- `packages/observability/src/health.ts`
+- `packages/observability/src/alerts.ts`
+- `packages/observability/src/exporters/prometheus.ts`
+- `packages/observability/src/exporters/otlp.ts`
+- `packages/observability/src/middleware.ts`
+- `packages/observability/src/index.ts`

package/IMPLEMENTATION/RFC-0034/TASKS.md

@@ -0,0 +1,57 @@
+# RFC-0034 Implementation Tasks
+
+## Phase 1: Logger
+
+- [ ] Create `packages/observability/` directory
+- [ ] Define `LoggerConfig` and `LogEntry` types
+- [ ] Implement `Logger` class
+- [ ] Implement correlation ID tracking
+- [ ] Add child logger support
+- [ ] Add file rotation support
+
+## Phase 2: Tracer
+
+- [ ] Define span types
+- [ ] Implement `Tracer` class
+- [ ] Implement `startSpan()` and `endSpan()`
+- [ ] Add OpenTelemetry compatible output
+- [ ] Implement `trace()` async wrapper
+- [ ] Add span attributes and events
+
+## Phase 3: Metrics
+
+- [ ] Implement `Metrics` class
+- [ ] Add counter, gauge, histogram support
+- [ ] Add built-in runtime metrics
+- [ ] Implement Prometheus export
+- [ ] Create `asyncTimer()` helper
+
+## Phase 4: Health Monitor
+
+- [ ] Implement `HealthMonitor` class
+- [ ] Add health check registration
+- [ ] Implement `checkHealth()`
+- [ ] Add liveness probe endpoint
+- [ ] Add readiness probe endpoint
+
+## Phase 5: Alerting
+
+- [ ] Define `AlertRule` and `AlertCondition` types
+- [ ] Implement `AlertEngine` class
+- [ ] Implement rule evaluation
+- [ ] Add alert actions (log, notify, webhook)
+- [ ] Implement alert history
+
+## Phase 6: Exporters & Middleware
+
+- [ ] Create Prometheus exporter
+- [ ] Create OTLP exporter
+- [ ] Create Express/HTTP middleware
+- [ ] Add metrics endpoint
+
+## Phase 7: Integration
+
+- [ ] Integrate with RuntimeApi
+- [ ] Add correlation IDs to all components
+- [ ] Export default metrics
+- [ ] Performance testing

package/IMPLEMENTATION/RFC-0035/AI_BRIEF.md

@@ -0,0 +1,55 @@
+# RFC-0035 AI Brief: Roadmap V1
+
+## Summary
+
+Implementation roadmap for RFCs 0031-0040 with phases, dependencies, and milestones.
+
+## Phases Overview
+
+### Phase 1: Foundation (Weeks 1-2)
+
+- RFC-0031: Provider Adapter SDK
+- RFC-0034: Observability
+
+### Phase 2: Core Systems (Weeks 3-5)
+
+- RFC-0032: Checkpoint Engine
+- RFC-0033: Session Manager
+- Integration testing
+
+### Phase 3: Advanced Features (Weeks 6-10)
+
+- RFC-0036: Code Review Engine
+- RFC-0037: Code Generation Pipeline
+- RFC-0038: Framework Detector
+- RFC-0039: Test Data Generator
+- RFC-0040: Framework Plugin SDK
+
+## Key Dependencies
+
+```
+RFC-0031 (Adapter SDK) --+--► RFC-0036 (Code Review Engine)
+                          |
+RFC-0032 (Checkpoint) ◄--+
+                          |
+RFC-0033 (Session) ◄-----+--► RFC-0034 (Observability)
+                          |
+RFC-0034 (Observability) ◄+
+
+RFC-0038 (Framework Detector) --+--► RFC-0039 (Test Data Generator)
+                                 |
+RFC-0037 (Code Generation) ◄-----+
+                                 |
+RFC-0040 (Plugin SDK) ◄----------+
+```
+
+## Success Metrics
+
+- Checkpoint storage reduction: >60%
+- Recovery time: <100ms
+- Session restore success rate: >99%
+- Framework detection accuracy: >90%
+
+## Files to Create
+
+This RFC is documentation-only - no implementation files needed.

package/IMPLEMENTATION/RFC-0035/TASKS.md

@@ -0,0 +1,75 @@
+# RFC-0035 Implementation Tasks
+
+## Phase 1: Foundation (Weeks 1-2)
+
+### Week 1: RFC-0031 Provider Adapter SDK
+
+- [ ] Complete RFC-0031 implementation (see RFC-0031 TASKS.md)
+- [ ] Migration of existing adapters
+- [ ] SDK documentation
+
+### Week 2: RFC-0034 Observability
+
+- [ ] Complete RFC-0034 implementation (see RFC-0034 TASKS.md)
+- [ ] Structured logging integration
+- [ ] Metrics endpoint
+- [ ] Health check endpoints
+
+## Phase 2: Core Systems (Weeks 3-5)
+
+### Week 3: RFC-0032 Checkpoint Engine
+
+- [ ] Complete RFC-0032 implementation (see RFC-0032 TASKS.md)
+- [ ] Incremental storage
+- [ ] Compression
+- [ ] Recovery strategies
+
+### Week 4: RFC-0033 Session Manager
+
+- [ ] Complete RFC-0033 implementation (see RFC-0033 TASKS.md)
+- [ ] Session persistence
+- [ ] Policy engine
+- [ ] Metrics collection
+
+### Week 5: Integration Testing
+
+- [ ] Integration tests for all Phase 1-2 components
+- [ ] Performance benchmarks
+- [ ] Documentation updates
+- [ ] Bug fixes
+
+## Phase 3: Advanced Features (Weeks 6-10)
+
+### Week 6-7: RFC-0036 Code Review Engine
+
+- [ ] Complete RFC-0036 implementation (see RFC-0036 TASKS.md)
+- [ ] Integration with AgentWorker
+- [ ] CI/CD examples
+
+### Week 7-8: RFC-0037 Code Generation Pipeline
+
+- [ ] Complete RFC-0037 implementation (see RFC-0037 TASKS.md)
+- [ ] Template system
+- [ ] Validation pipeline
+- [ ] Rollback mechanism
+
+### Week 8-9: RFC-0038 Framework Detector
+
+- [ ] Complete RFC-0038 implementation (see RFC-0038 TASKS.md)
+- [ ] Detection signatures
+- [ ] Version detection
+- [ ] Real-time watching
+
+### Week 9-10: RFC-0039 & RFC-0040
+
+- [ ] Complete RFC-0039 Test Data Generator
+- [ ] Complete RFC-0040 Framework Plugin SDK
+- [ ] Plugin examples
+- [ ] Final integration testing
+
+## Ongoing Tasks
+
+- [ ] Update CHANGELOG.md with each release
+- [ ] Maintain README.md with progress
+- [ ] Performance monitoring
+- [ ] User feedback integration

package/IMPLEMENTATION/RFC-0036/AI_BRIEF.md

@@ -0,0 +1,62 @@
+# RFC-0036 AI Brief: Code Review Engine
+
+## Summary
+
+An automated code review engine that performs static analysis, runs linters, and integrates AI-powered review suggestions.
+
+## Implementation Overview
+
+### Key Classes to Implement
+
+1. **CodeReviewEngine** (`engine.ts`)
+   - Pattern-based rule matching
+   - Multi-file review
+   - Git diff review
+   - Report generation
+
+2. **Review DSL Parser** (`dsl/parser.ts`)
+   - Parse review-rules.config.ts
+   - Validate rule definitions
+   - Load ESLint/TypeScript configs
+
+3. **Linter Adapters** (`linters/`)
+   - ESLint adapter
+   - TypeScript adapter
+   - Prettier adapter
+   - Custom linter support
+
+4. **AIReviewer** (`ai-reviewer/`)
+   - OpenAI integration
+   - Anthropic/Claude integration
+   - Security, performance, best-practices focus areas
+
+5. **Report Generator** (`reports/`)
+   - Text format
+   - JSON format
+   - HTML format
+   - Markdown format
+
+### Dependencies
+
+- `packages/types` - for runtime-types
+- `packages/provider-adapter-sdk` - for AI provider integration
+- `eslint` - optional, for ESLint integration
+- `typescript` - optional, for TS checking
+
+### Files to Create
+
+- `packages/code-review/src/engine.ts`
+- `packages/code-review/src/dsl/parser.ts`
+- `packages/code-review/src/dsl/validator.ts`
+- `packages/code-review/src/linters/base.ts`
+- `packages/code-review/src/linters/eslint.ts`
+- `packages/code-review/src/linters/typescript.ts`
+- `packages/code-review/src/linters/prettier.ts`
+- `packages/code-review/src/linters/registry.ts`
+- `packages/code-review/src/ai-reviewer/index.ts`
+- `packages/code-review/src/reports/text.ts`
+- `packages/code-review/src/reports/html.ts`
+- `packages/code-review/src/reports/markdown.ts`
+- `packages/code-review/src/history/tracker.ts`
+- `packages/code-review/src/types.ts`
+- `packages/code-review/src/index.ts`

package/IMPLEMENTATION/RFC-0036/TASKS.md

@@ -0,0 +1,60 @@
+# RFC-0036 Implementation Tasks
+
+## Phase 1: Engine Core
+
+- [ ] Create `packages/code-review/` directory
+- [ ] Define types (`Finding`, `ReviewResult`, `ReviewRule`)
+- [ ] Create `CodeReviewEngine` class
+- [ ] Implement `reviewFiles()` method
+- [ ] Implement `reviewDiff()` method
+- [ ] Implement pattern matching engine
+
+## Phase 2: DSL & Rules
+
+- [ ] Create `dsl/parser.ts`
+- [ ] Implement rules configuration parsing
+- [ ] Implement pattern validation
+- [ ] Create default rules:
+  - [ ] no-console-log
+  - [ ] no-any-type
+  - [ ] security-no-eval
+- [ ] Add support for external config files
+
+## Phase 3: Linter Integration
+
+- [ ] Create `LinterAdapter` interface
+- [ ] Implement `ESLintAdapter`
+- [ ] Implement `TypeScriptAdapter`
+- [ ] Implement `PrettierAdapter`
+- [ ] Create `LinterRegistry`
+- [ ] Add support for custom linters
+
+## Phase 4: AI Reviewer
+
+- [ ] Create `AIReviewer` class
+- [ ] Implement `AIReviewerConfig`
+- [ ] Implement OpenAI integration
+- [ ] Implement Anthropic/Claude integration
+- [ ] Add focus areas (security, performance, etc.)
+
+## Phase 5: Reporting
+
+- [ ] Create `ReviewReportGenerator`
+- [ ] Implement text report format
+- [ ] Implement JSON report format
+- [ ] Implement HTML report format
+- [ ] Implement Markdown report format
+
+## Phase 6: History & Trends
+
+- [ ] Create `ReviewHistoryTracker`
+- [ ] Implement `getTrends()`
+- [ ] Add comparison between reviews
+- [ ] Create trend visualization data
+
+## Phase 7: Integration
+
+- [ ] Integrate with AgentWorker
+- [ ] Add CI/CD examples (GitHub Actions, GitLab CI)
+- [ ] Create review-rules.config.ts examples
+- [ ] Write unit tests