pi-harness-runtime 0.10.12 → 0.10.13

package/RFC/0018_REPAIR_ENGINE.md

@@ -0,0 +1,36 @@
+# RFC-0018 — Repair Engine
+
+## Status
+Proposed
+
+## Motivation
+
+When a task fails, the Repair Engine automatically generates repair tasks with retry policies and escalation paths.
+
+## Flow
+
+1. Task reports failure with error context
+2. Repair Engine classifies failure type (test, lint, build, runtime, network)
+3. For each classification, generate repair tasks:
+   - **Test failure** -> re-run with verbose output, fix test or fix code
+   - **Build failure** -> fix compilation error, re-run build
+   - **Runtime failure** -> add error handling, retry
+   - **Network failure** -> retry with backoff
+4. Escalate to human if max retries exceeded
+
+## Retry Policy
+
+```ts
+interface RetryPolicy {
+  maxAttempts: number;
+  backoffMs: number;
+  backoffMultiplier: number;
+  jitter: boolean;
+}
+```
+
+Default: 3 attempts, exponential backoff starting at 1000ms.
+
+## Package
+
+`packages/repair-engine/`

package/RFC/0019_AUTO_COMPACT_AND_CONTINUE.md

@@ -0,0 +1,51 @@
+# RFC 0019 - Auto Compact and Continue
+
+## Purpose
+
+Automatically resume work after model/session compaction without requiring the human to type `resume`.
+
+## Motivation
+
+Observed behavior:
+
+```text
+[compaction]
+Compacted from 201,419 tokens
+Error: Model stopped because it reached the maximum output token limit.
+```
+
+Compaction is not completion. The runtime must own continuation.
+
+## Goals
+
+- Detect compaction markers from logs/output.
+- Save compaction artifacts.
+- Generate `continue_prompt.md`.
+- Continue the same task without repeating completed work.
+- Keep the human out of the message-bus role.
+
+## Artifact Layout
+
+```text
+harness/context/
+  compaction_events.jsonl
+  latest_compaction_summary.md
+  continue_prompt.md
+```
+
+## Runtime Flow
+
+```text
+AgentRunning
+  -> CompactionDetected
+  -> SaveCompactionArtifact
+  -> GenerateContinuePrompt
+  -> ContinueSameTask
+  -> ValidateExpectedOutput
+```
+
+## Acceptance Criteria
+
+- Runtime detects compaction.
+- Runtime writes continuation prompt.
+- Agent can continue without human typing `resume`.

package/RFC/0020_OUTPUT_TOKEN_LIMIT_HANDLER.md

@@ -0,0 +1,49 @@
+# RFC 0020 - Output Token Limit Handler
+
+## Purpose
+
+Handle model responses that stop because the maximum output token limit was reached.
+
+## Error Example
+
+```text
+Error: Model stopped because it reached the maximum output token limit.
+The response may be incomplete.
+```
+
+## Classification
+
+| Failure | Runtime Action |
+|---|---|
+| Quota exhausted | pause until reset |
+| Context full | compact and resume |
+| Output token limit | continue same task |
+| Unknown error | retry or escalate |
+
+## Policy
+
+```json
+{
+  "max_continue_attempts": 5,
+  "continuation_backoff_ms": 1000,
+  "require_expected_output_validation": true
+}
+```
+
+## Runtime Flow
+
+```text
+OutputLimitDetected
+  -> SavePartialResponse
+  -> GenerateContinuationPrompt
+  -> RetryContinuation
+  -> MergePartialOutputs
+  -> ValidateExpectedOutput
+```
+
+## Acceptance Criteria
+
+- Runtime detects output-limit messages.
+- Runtime saves partial output.
+- Runtime continues same task.
+- Runtime stops after configurable max attempts.

package/RFC/0021_PARTIAL_RESPONSE_RECOVERY.md

@@ -0,0 +1,49 @@
+# RFC 0021 - Partial Response Recovery
+
+## Purpose
+
+Persist and recover incomplete agent outputs.
+
+## Motivation
+
+Partial output may contain useful plan, code, tests, or reports. It must not be discarded.
+
+## Artifact Layout
+
+```text
+harness/partial/
+  task_004/
+    partial_001.md
+    partial_002.md
+    merged.md
+    recovery_status.json
+```
+
+## Recovery Status
+
+```json
+{
+  "task_id": "task_004",
+  "status": "continuing",
+  "partials": ["partial_001.md"],
+  "merged_output": "merged.md",
+  "attempts": 1,
+  "last_error": "output token limit"
+}
+```
+
+## Merge Strategy
+
+v0.1 merges partials as ordered markdown sections.
+
+Future:
+- JSON-aware merge
+- patch-aware merge
+- code-block extraction
+- semantic duplicate removal
+
+## Acceptance Criteria
+
+- Runtime never loses partial response text.
+- Runtime can continue from partial output.
+- Runtime escalates after repeated partial failures.

package/RFC/0022_NOTIFICATION_CENTER.md

@@ -0,0 +1,47 @@
+# RFC 0022 - Notification Center
+
+## Purpose
+
+Send runtime status, alerts, approvals, and completion messages to mobile phone/tablet.
+
+## Motivation
+
+Human-on-the-loop requires the human to know when the runtime is running, paused, blocked, or ready without sitting in front of pi.dev.
+
+## MVP Channels
+
+- Telegram
+- LINE Messaging / LINE alternative
+- ntfy
+- Email
+- Webhook
+
+OpenClaw can be a later adapter, not an MVP dependency.
+
+## Notification Events
+
+```text
+JobStarted
+TaskCompleted
+QuotaPaused
+ResumeScheduled
+ContextCompacted
+OutputLimitContinued
+E2EFailed
+HumanReviewNeeded
+ReadyForClient
+```
+
+## Security Rules
+
+- Do not send raw cookies.
+- Do not send passwords.
+- Do not send full provider tokens.
+- Do not send full source code by default.
+- Send summaries and file paths.
+
+## Acceptance Criteria
+
+- Runtime sends at least one mobile notification.
+- Notification failure does not crash runtime.
+- Sensitive data is redacted.

package/RFC/0023_LOCAL_BROWSER_AGENT.md

@@ -0,0 +1,67 @@
+# RFC 0023 - Local Browser Agent
+
+## Purpose
+
+Allow a headless server runtime to use a human-owned local browser session for authenticated provider pages such as MiniMax usage console.
+
+## Motivation
+
+Playwright opens a browser on the machine executing the command. A headless server cannot show a login window on the user's iMac.
+
+MiniMax usage page requires authentication:
+
+```text
+https://platform.minimax.io/console/usage
+```
+
+## Core Rule
+
+Authenticated browser sessions live where the human can interact with them.
+
+## Architecture
+
+```text
+Server Runtime
+  -> HTTP/RPC request
+      -> Local Browser Agent on iMac
+          -> Playwright persistent profile
+          -> Human login if needed
+          -> scrape usage/reset time
+      -> return safe quota summary
+```
+
+## Local Agent API
+
+```http
+GET /health
+POST /auth/minimax/start
+GET /quota/minimax
+POST /auth/minimax/reset
+```
+
+## Safe Response
+
+```json
+{
+  "provider": "minimax",
+  "authenticated": true,
+  "checked_at": "2026-07-03T09:00:00+07:00",
+  "usage_text_sample": "Token Plan usage ...",
+  "reset_at": "2026-07-03T14:30:00+07:00"
+}
+```
+
+## Security Rules
+
+- Never return raw cookies.
+- Never return localStorage.
+- Bind to localhost by default.
+- If remote access is needed, require VPN/Tailscale and token.
+- Log only safe summaries.
+
+## Acceptance Criteria
+
+- Local browser agent opens MiniMax console in headed Playwright.
+- Human logs in manually.
+- Persistent profile is reused.
+- Server receives only safe quota summary.

package/RFC/0024_LOCAL_RUNTIME_AGENT.md

@@ -0,0 +1,3 @@
+# RFC 0024
+
+LOCAL_RUNTIME_AGENT

package/RFC/0025_COMMAND_EXECUTOR.md

@@ -0,0 +1,3 @@
+# RFC 0025
+
+COMMAND_EXECUTOR

package/RFC/0026_WORKSPACE_MANAGER.md

@@ -0,0 +1,3 @@
+# RFC 0026
+
+WORKSPACE_MANAGER

package/RFC/0027_RUNTIME_API.md

@@ -0,0 +1,3 @@
+# RFC 0027
+
+RUNTIME_API

package/RFC/0028_POLICY_ENGINE.md

@@ -0,0 +1,3 @@
+# RFC 0028
+
+POLICY_ENGINE

package/RFC/0029_DEEPAGENTS_ADAPTER.md

@@ -0,0 +1,2 @@
+# RFC0029
+DeepAgents is an optional Agent Worker. Runtime keeps scheduler, quota, blackboard, policy.

package/RFC/0030_AGENT_WORKER_INTERFACE.md

@@ -0,0 +1,2 @@
+# RFC0030
+Define common AgentWorker interface for Codex, MiniMax, GLM, GPT and DeepAgents.

package/RFC/0031_PROVIDER_ADAPTER_SDK.md

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