pi-harness-runtime 0.10.13 → 0.10.15

package/RFC/0031_PROVIDER_ADAPTER_SDK.md

@@ -1,171 +0,0 @@
-# RFC 0031: Provider Adapter SDK
-
-## Summary
-
-A comprehensive SDK for building, testing, and registering provider adapters that normalize AI provider behavior.
-
-## Motivation
-
-The current adapter system is ad-hoc with adapters defined in `packages/providers/adapters.ts`. We need:
-
-1. A standardized SDK for creating new adapters
-2. Built-in testing utilities
-3. Version management and compatibility checks
-4. Clear extension points for custom adapters
-
-## Architecture
-
-```
-+-------------------------------------------------------------+
-|                    Provider Adapter SDK                     |
-+-------------------------------------------------------------+
-|  +-------------+  +-------------+  +-------------+         |
-|  |   Builder   |  |  Registry   |  |   Tester    |         |
-|  |   Class     |  |   Manager   |  |  Utilities  |         |
-|  +-------------+  +-------------+  +-------------+         |
-+-------------------------------------------------------------+
-|                    Adapter Interface                        |
-+-------------------------------------------------------------+
-|  +-------------+  +-------------+  +-------------+         |
-|  | MiniMax     |  |  OpenAI     |  |  Claude     |         |
-|  | Adapter     |  |  Adapter    |  |  Adapter    |         |
-|  +-------------+  +-------------+  +-------------+         |
-+-------------------------------------------------------------+
-```
-
-## Key Components
-
-### 1. AdapterBuilder Class
-
-```typescript
-class AdapterBuilder<T extends ProviderAdapter> {
-  constructor(name: string);
-  config(config: ProviderConfig): AdapterBuilder<T>;
-  capabilities(...caps: ProviderCapability[]): AdapterBuilder<T>;
-  models(...models: string[]): AdapterBuilder<T>;
-  rateLimits(limits: RateLimitConfig): AdapterBuilder<T>;
-  invoke(fn: (req: ProviderRequest) => Promise<ProviderResponse>): AdapterBuilder<T>;
-  parseError(fn: (err: unknown) => ErrorAnalysis): AdapterBuilder<T>;
-  build(): T;
-}
-```
-
-### 2. AdapterTester Utility
-
-```typescript
-class AdapterTester {
-  constructor(adapter: ProviderAdapter);
-  testBasicInvocation(): Promise<TestResult>;
-  testQuotaDetection(): Promise<TestResult>;
-  testErrorParsing(): Promise<TestResult>;
-  testRateLimiting(): Promise<TestResult>;
-  generateMockResponses(): void;
-}
-```
-
-### 3. Adapter Registry with Lifecycle
-
-```typescript
-interface AdapterLifecycle {
-  onInit?: () => Promise<void>;
-  onHealthCheck?: () => Promise<HealthStatus>;
-  onTeardown?: () => Promise<void>;
-}
-
-class AdapterRegistry {
-  register(adapter: ProviderAdapter, lifecycle?: AdapterLifecycle): void;
-  unregister(id: string): void;
-  getAdapter(id: string): ProviderAdapter | undefined;
-  listAdapters(): ProviderAdapterInfo[];
-  healthCheckAll(): Promise<Map<string, HealthStatus>>;
-}
-```
-
-### 4. SDK Version Compatibility
-
-```typescript
-interface AdapterVersion {
-  sdk: string; // "1.0.0"
-  minRuntime: string;
-  capabilities: ProviderCapability[];
-}
-```
-
-## File Structure
-
-```
-packages/provider-adapter-sdk/
-+-- src/
-|   +-- index.ts                    # Public exports
-|   +-- builder.ts                  # AdapterBuilder class
-|   +-- registry.ts                 # AdapterRegistry with lifecycle
-|   +-- tester.ts                   # AdapterTester utilities
-|   +-- types.ts                    # SDK-specific types
-|   +-- compatibility.ts             # Version checks
-|   +-- errors.ts                   # SDK-specific errors
-+-- test/
-|   +-- builder.test.ts
-|   +-- registry.test.ts
-|   +-- tester.test.ts
-+-- examples/
-|   +-- custom-provider.ts          # Example custom adapter
-|   +-- testing-adapter.ts          # Example testing setup
-+-- package.json
-+-- README.md
-```
-
-## Usage Examples
-
-### Creating a Custom Adapter
-
-```typescript
-import { AdapterBuilder, type ProviderAdapter } from '@pi/provider-adapter-sdk';
-
-const myAdapter = new AdapterBuilder('myprovider')
-  .config({
-    id: 'myprovider',
-    name: 'My Custom Provider',
-    models: ['myprovider/model-x', 'myprovider/model-y'],
-    capabilities: ['code', 'review'],
-    rateLimits: { requestsPerMinute: 60 }
-  })
-  .invoke(async (req) => {
-    const response = await myApi.call(req);
-    return response;
-  })
-  .parseError((err) => {
-    return {
-      quotaExceeded: err.code === 'QUOTA_EXCEEDED',
-      rateLimited: err.code === 'RATE_LIMIT',
-      // ...
-    };
-  })
-  .build();
-```
-
-### Testing an Adapter
-
-```typescript
-const tester = new AdapterTester(myAdapter);
-const results = await tester.runAllTests();
-
-if (results.failed > 0) {
-  console.log('Failed:', results.failures);
-}
-```
-
-## Acceptance Criteria
-
-1. ✅ SDK provides AdapterBuilder for creating adapters
-2. ✅ SDK includes AdapterTester for validation
-3. ✅ AdapterRegistry supports lifecycle hooks
-4. ✅ Version compatibility checks prevent mismatches
-5. ✅ All existing adapters (MiniMax, OpenAI, Claude) work with SDK
-6. ✅ Custom adapters can be registered and used seamlessly
-7. ✅ SDK exports TypeScript types and documentation
-
-## Dependencies
-
-- `packages/types` - for runtime-types
-- `packages/providers` - existing adapter implementations
-- No new external dependencies

package/RFC/0032_CHECKPOINT_ENGINE.md

@@ -1,217 +0,0 @@
-# RFC 0032: Checkpoint Engine
-
-## Summary
-
-An enhanced checkpoint system with incremental snapshots, diff-based storage, and intelligent recovery strategies.
-
-## Motivation
-
-The current checkpoint system (`packages/checkpoint/checkpoint-manager.ts`) only saves full JSON snapshots. For large jobs with many events, this is inefficient. We need:
-
-1. Incremental checkpoints with diff storage
-2. Compression for large checkpoints
-3. Parallel I/O for faster saves
-4. Checksum verification
-5. Checkpoint metadata and pruning
-
-## Architecture
-
-```
-+-----------------------------------------------------------------+
-|                      Checkpoint Engine                           |
-+-----------------------------------------------------------------+
-|  +--------------+  +--------------+  +--------------+           |
-|  |   Manager    |  |   Storage    |  |   Recovery   |           |
-|  |   (API)      |  |   (I/O)      |  |   (Restore) |           |
-|  +--------------+  +--------------+  +--------------+           |
-+-----------------------------------------------------------------+
-|  +--------------+  +--------------+  +--------------+           |
-|  |   Snapshot   |  |    Diff      |  |   Metadata   |           |
-|  |   Full       |  |   Incremental|  |   Index      |           |
-|  +--------------+  +--------------+  +--------------+           |
-+-----------------------------------------------------------------+
-```
-
-## Key Components
-
-### 1. Enhanced CheckpointManager
-
-```typescript
-interface CheckpointEngineConfig {
-  rootDir: string;
-  compression: boolean;           // Enable gzip compression
-  incremental: boolean;            // Enable incremental diffs
-  maxCheckpoints: number;          // Keep last N checkpoints
-  autoPrune: boolean;              // Auto-delete old checkpoints
-  checksumAlgorithm: 'md5' | 'sha256';
-  parallelWrites: boolean;         // Parallel file I/O
-}
-
-class CheckpointEngine {
-  constructor(config: CheckpointEngineConfig);
-  
-  // Save operations
-  save(jobId: string, state: RuntimeState): Promise<CheckpointMetadata>;
-  saveIncremental(jobId: string, delta: StateDelta): Promise<CheckpointMetadata>;
-  
-  // Load operations
-  load(jobId: string): Promise<RuntimeState | null>;
-  loadIncremental(jobId: string, version: number): Promise<RuntimeState>;
-  
-  // Recovery
-  recover(jobId: string, strategy: RecoveryStrategy): Promise<RecoveryResult>;
-  
-  // Management
-  prune(jobId: string, keepCount: number): Promise<PruneResult>;
-  verify(jobId: string): Promise<VerificationResult>;
-  getMetadata(jobId: string): Promise<CheckpointMetadata[]>;
-}
-```
-
-### 2. State Delta for Incremental Saves
-
-```typescript
-interface StateDelta {
-  jobId: string;
-  baseVersion: number;              // Previous checkpoint version
-  targetVersion: number;            // New checkpoint version
-  changes: {
-    status?: JobStatus;
-    tasks?: TaskDelta[];
-    context?: ContextDiff;
-    errors?: ErrorEntry[];
-  };
-  timestamp: string;
-  checksum: string;
-}
-
-interface TaskDelta {
-  taskId: string;
-  action: 'added' | 'updated' | 'removed';
-  before?: Partial<RuntimeTask>;
-  after?: Partial<RuntimeTask>;
-}
-```
-
-### 3. Recovery Strategies
-
-```typescript
-type RecoveryStrategy = 
-  | 'latest'           // Use most recent checkpoint
-  | 'fullest'          // Use checkpoint with most completed tasks
-  | 'specific:version' // Use specific version number
-  | 'timestamp:ISO'    // Use checkpoint closest to timestamp
-  | 'interactive';     // Prompt user to choose
-
-interface RecoveryResult {
-  success: boolean;
-  recoveredVersion: number;
-  lostEvents: number;
-  recoveryTimeMs: number;
-  warnings?: string[];
-}
-```
-
-### 4. Checkpoint Metadata
-
-```typescript
-interface CheckpointMetadata {
-  jobId: string;
-  version: number;
-  type: 'full' | 'incremental';
-  sizeBytes: number;
-  compressed: boolean;
-  checksum: string;
-  taskProgress: {
-    total: number;
-    completed: number;
-    failed: number;
-  };
-  createdAt: string;
-  expiresAt?: string;
-}
-```
-
-## File Structure
-
-```
-packages/checkpoint/
-+-- src/
-|   +-- index.ts                    # Public exports
-|   +-- engine.ts                   # CheckpointEngine main class
-|   +-- storage.ts                  # File I/O with compression
-|   +-- differ.ts                   # Diff calculation
-|   +-- recovery.ts                 # Recovery strategies
-|   +-- indexer.ts                  # Metadata index
-|   +-- types.ts                    # Extended types
-|   +-- errors.ts                   # Checkpoint errors
-+-- test/
-|   +-- engine.test.ts
-|   +-- differ.test.ts
-|   +-- recovery.test.ts
-+-- package.json
-+-- README.md
-```
-
-## Usage Examples
-
-### Basic Usage
-
-```typescript
-const engine = new CheckpointEngine({
-  rootDir: './checkpoints',
-  compression: true,
-  incremental: true,
-  maxCheckpoints: 10,
-  autoPrune: true
-});
-
-await engine.save('job-123', {
-  jobId: 'job-123',
-  status: 'running',
-  tasks: [...],
-  // ...
-});
-```
-
-### Recovery
-
-```typescript
-const result = await engine.recover('job-123', 'latest');
-console.log(`Recovered version ${result.recoveredVersion}`);
-console.log(`Lost ${result.lostEvents} events`);
-```
-
-### Pruning Old Checkpoints
-
-```typescript
-await engine.prune('job-123', 5); // Keep last 5 checkpoints
-```
-
-## Comparison with Current Implementation
-
-| Feature | Current | RFC-0032 |
-| --------- | --------- | ---------- |
-| Full snapshots | ✅ | ✅ |
-| Incremental diffs | ❌ | ✅ |
-| Compression | ❌ | ✅ |
-| Checksums | ❌ | ✅ |
-| Parallel I/O | ❌ | ✅ |
-| Recovery strategies | ❌ | ✅ |
-| Auto-pruning | ❌ | ✅ |
-
-## Acceptance Criteria
-
-1. ✅ Incremental checkpoints reduce storage by 60%+ for typical jobs
-2. ✅ Compression reduces checkpoint size by 50%+
-3. ✅ Recovery can restore job state within 100ms for cached checkpoints
-4. ✅ Checksum verification detects corruption
-5. ✅ Parallel writes don't block main thread
-6. ✅ Auto-pruning maintains disk space limits
-7. ✅ Backward compatible with existing checkpoint format
-
-## Dependencies
-
-- `packages/types` - for runtime-types
-- `zlib` (Node.js built-in) - for compression
-- No new external dependencies

package/RFC/0033_SESSION_MANAGER.md

@@ -1,262 +0,0 @@
-# RFC 0033: Session Manager
-
-## Summary
-
-A comprehensive session management system for tracking user sessions, maintaining conversation history, and providing session persistence across restarts.
-
-## Motivation
-
-Currently, session state is managed ad-hoc within individual components. We need:
-
-1. Centralized session tracking
-2. Conversation history with token accounting
-3. Session persistence and restoration
-4. Multi-session support (parallel jobs)
-5. Session metrics and analytics
-
-## Architecture
-
-```
-+-----------------------------------------------------------------+
-|                       Session Manager                             |
-+-----------------------------------------------------------------+
-|  +--------------+  +--------------+  +--------------+             |
-|  |   Session    |  |   History    |  |   Metrics    |             |
-|  |   Store      |  |   Manager    |  |   Collector  |             |
-|  +--------------+  +--------------+  +--------------+             |
-+-----------------------------------------------------------------+
-|  +--------------+  +--------------+  +--------------+             |
-|  |   Session    |  |   Message    |  |   Context    |             |
-|  |   Policy     |  |   Index      |  |   Cache      |             |
-|  +--------------+  +--------------+  +--------------+             |
-+-----------------------------------------------------------------+
-```
-
-## Key Components
-
-### 1. Session Types
-
-```typescript
-interface Session {
-  id: string;
-  userId?: string;
-  jobId?: string;
-  status: SessionStatus;
-  createdAt: string;
-  updatedAt: string;
-  lastActivityAt: string;
-  expiresAt?: string;
-  metadata: SessionMetadata;
-  context: SessionContext;
-}
-
-type SessionStatus = 'active' | 'idle' | 'suspended' | 'closed';
-
-interface SessionMetadata {
-  provider: string;
-  model: string;
-  tokenUsage: TokenUsage;
-  messageCount: number;
-  turnCount: number;
-  costEstimate: number;
-  tags: string[];
-}
-
-interface TokenUsage {
-  input: number;
-  output: number;
-  cacheRead: number;
-  cacheWrite: number;
-  total: number;
-}
-
-interface SessionContext {
-  systemPrompt?: string;
-  workingDirectory?: string;
-  variables: Record<string, unknown>;
-  attachments: Attachment[];
-}
-```
-
-### 2. SessionManager Class
-
-```typescript
-interface SessionManagerConfig {
-  storageDir: string;                // Where to persist sessions
-  maxSessions: number;               // Max concurrent sessions
-  sessionTimeout: number;            // Idle timeout in ms
-  maxHistoryLength: number;          // Max messages to retain
-  autoCheckpoint: boolean;           // Auto-save session state
-  checkpointInterval: number;        // Checkpoint frequency in ms
-}
-
-class SessionManager {
-  constructor(config: SessionManagerConfig);
-  
-  // Session lifecycle
-  createSession(init?: Partial<Session>): Promise<Session>;
-  getSession(id: string): Promise<Session | null>;
-  closeSession(id: string): Promise<void>;
-  suspendSession(id: string): Promise<void>;
-  resumeSession(id: string): Promise<Session>;
-  
-  // Message handling
-  addMessage(sessionId: string, message: Message): Promise<void>;
-  getHistory(sessionId: string, options?: HistoryOptions): Promise<Message[]>;
-  
-  // Metrics
-  getMetrics(sessionId: string): Promise<SessionMetrics>;
-  getAllMetrics(): Promise<GlobalMetrics>;
-  
-  // Cleanup
-  pruneSessions(olderThan: Date): Promise<PruneResult>;
-  cleanupExpired(): Promise<CleanupResult>;
-}
-```
-
-### 3. Message Types
-
-```typescript
-interface Message {
-  id: string;
-  sessionId: string;
-  role: 'system' | 'user' | 'assistant' | 'tool';
-  content: string;
-  timestamp: string;
-  tokens?: number;
-  attachments?: Attachment[];
-  metadata?: Record<string, unknown>;
-}
-
-interface HistoryOptions {
-  limit?: number;                    // Max messages to return
-  before?: string;                   // Cursor for pagination
-  roles?: ('system' | 'user' | 'assistant' | 'tool')[];
-  search?: string;                  // Full-text search
-}
-```
-
-### 4. Session Policy Engine
-
-```typescript
-interface SessionPolicy {
-  maxTokensPerSession?: number;
-  maxCostPerSession?: number;
-  autoSuspendIdle?: boolean;
-  idleTimeoutMs?: number;
-  allowContextOverflow?: boolean;
-  summarizationStrategy?: 'never' | 'when_near' | 'always';
-}
-
-class SessionPolicyEngine {
-  constructor(policies: SessionPolicy[]);
-  evaluate(session: Session): PolicyResult;
-  apply(session: Session, result: PolicyResult): Promise<void>;
-}
-```
-
-## File Structure
-
-```
-packages/session/
-+-- src/
-|   +-- index.ts                    # Public exports
-|   +-- manager.ts                  # SessionManager class
-|   +-- store.ts                    # Session persistence
-|   +-- history.ts                  # Message history management
-|   +-- policy.ts                   # Policy engine
-|   +-- metrics.ts                  # Metrics collection
-|   +-- types.ts                    # Session types
-|   +-- errors.ts                   # Session errors
-+-- test/
-|   +-- manager.test.ts
-|   +-- history.test.ts
-|   +-- policy.test.ts
-+-- examples/
-|   +-- basic-usage.ts
-|   +-- policy-examples.ts
-+-- package.json
-+-- README.md
-```
-
-## Usage Examples
-
-### Creating and Using a Session
-
-```typescript
-const manager = new SessionManager({
-  storageDir: './sessions',
-  maxSessions: 100,
-  sessionTimeout: 3600000, // 1 hour
-  maxHistoryLength: 1000,
-  autoCheckpoint: true
-});
-
-const session = await manager.createSession({
-  userId: 'user-123',
-  metadata: { provider: 'anthropic', model: 'claude-3-5-sonnet' }
-});
-
-await session.addMessage({
-  role: 'user',
-  content: 'Hello, help me build a React app'
-});
-
-const history = await session.getHistory({ limit: 10 });
-```
-
-### Policy Enforcement
-
-```typescript
-const policyEngine = new SessionPolicyEngine([
-  { maxTokensPerSession: 100000 },
-  { maxCostPerSession: 10.00 },
-  { autoSuspendIdle: true, idleTimeoutMs: 300000 }
-]);
-
-const result = policyEngine.evaluate(session);
-if (!result.allowed) {
-  console.log(`Policy violation: ${result.reason}`);
-  await session.suspend();
-}
-```
-
-### Metrics
-
-```typescript
-const metrics = await session.getMetrics();
-console.log({
-  tokensUsed: metrics.tokenUsage.total,
-  messages: metrics.messageCount,
-  estimatedCost: metrics.costEstimate
-});
-```
-
-## Integration with Existing Components
-
-```
-SessionManager ------+------> CheckpointEngine (save/restore sessions)
-                    |
-                    +------> ContextWindowManager (token accounting)
-                    |
-                    +------> QuotaManager (cost tracking)
-                    |
-                    +------> RuntimeApi (session CRUD endpoints)
-```
-
-## Acceptance Criteria
-
-1. ✅ Sessions persist across process restarts
-2. ✅ Message history is queryable with pagination
-3. ✅ Token usage is accurately tracked per session
-4. ✅ Policy engine enforces session limits
-5. ✅ Idle sessions auto-suspend after timeout
-6. ✅ Session metrics are available for analytics
-7. ✅ Multiple concurrent sessions are supported
-
-## Dependencies
-
-- `packages/types` - for runtime-types
-- `packages/checkpoint` - for session persistence
-- `packages/quota-manager` - for cost tracking
-- No new external dependencies