@bluecopa/harness 0.0.0-snapshot.137

package/README.md

@@ -0,0 +1,316 @@
+# harness
+
+Provider-agnostic TypeScript agent framework with Claude-code-compatible tool semantics.
+
+Published on npm as **`@bluecopa/harness`**.
+
+Two execution modes: a simple single-agent loop (`createAgent` + `VercelAgentLoop`) and a process-based orchestrator (`ArcLoop`) that dispatches parallel processes with context management, memory, and resilience.
+
+## Install
+
+```bash
+pnpm add @bluecopa/harness
+```
+
+## Development
+
+```bash
+pnpm install
+pnpm test
+```
+
+## Architecture
+
+### Single-Agent Loop
+
+```
+┌──────────────┐     ┌──────────────┐     ┌──────────────────┐
+│  createAgent │────►│  AgentLoop   │────►│  LLM (Claude)    │
+│  (turn loop) │     │  (nextAction)│     │                  │
+└──────┬───────┘     └──────────────┘     └──────────────────┘
+       │                                           │
+       │  tool call                    returns ToolCallAction
+       ▼                                   or FinalAction
+┌──────────────┐
+│ ToolProvider │──── bash, read, write, edit, glob, grep
+│ (executor)   │     runs in sandbox or local machine
+└──────────────┘
+```
+
+### ArcLoop Orchestrator
+
+```
+Orchestrator (ArcLoop — Opus 4.6 by default)
+  │  tools: Thread, Check, Cancel, Remember, ReadEpisode
+  │
+  │  Turn 1 (parallel):
+  ├──► Process 0 ("read auth", model=fast)        ─┐
+  ├──► Process 1 ("read routes", model=fast)       ─┼──► Episodes
+  ├──► Process 2 ("read tests", model=fast)        ─┘
+  │
+  │  Turn 2 (dispatch dependent work):
+  ├──► Thread("fix bug", context=[ep0,ep1,ep2])    ──► Episode
+  │
+  │  Turn 3 (parallel):
+  ├──► Thread("run tests", context=[ep3])          ─┐
+  ├──► Thread("update docs", context=[ep3])        ─┘
+  │
+  └──► Final text response
+```
+
+Full architecture doc: [`docs/arc.md`](../docs/arc.md)
+
+---
+
+## ToolProvider
+
+The contract for tool execution. All agent modes use this interface.
+
+```typescript
+interface ToolProvider {
+  bash(command: string, options?: BashOptions): Promise<ToolResult>;
+  readFile(path: string, options?: ReadOptions): Promise<ToolResult>;
+  writeFile(path: string, content: string): Promise<ToolResult>;
+  editFile(path: string, oldText: string, newText: string): Promise<ToolResult>;
+  glob(pattern: string, options?: GlobOptions): Promise<ToolResult>;
+  grep(pattern: string, path?: string, options?: GrepOptions): Promise<ToolResult>;
+  webFetch?(options: WebFetchOptions): Promise<ToolResult>;
+  webSearch?(query: string): Promise<ToolResult>;
+  capabilities(): ToolProviderCapabilities;
+}
+
+interface ToolResult {
+  success: boolean;
+  output: string;
+  error?: string;
+}
+```
+
+Built-in implementations:
+
+| Provider | Description |
+|----------|-------------|
+| `LocalToolProvider` | Runs tools on the local filesystem |
+| `E2BToolProvider` | Routes tools to a sandbox VM via `ControlPlaneE2BExecutor` |
+| `CompositeToolProvider` | Combines multiple providers (e.g. local filesystem + sandbox bash) |
+
+## SandboxProvider
+
+Higher-level sandbox operations beyond basic tool calls:
+
+```typescript
+interface SandboxProvider {
+  exec(command: string, options?: SandboxExecOptions): Promise<SandboxExecResult>;
+  readSandboxFile(path: string): Promise<SandboxFileBlob>;
+  writeSandboxFile(path: string, content: SandboxFileBlob): Promise<void>;
+}
+```
+
+Used by `SkillManager` for executing skill scripts in isolated VMs.
+
+## Connecting to a Sandbox
+
+```typescript
+import { ControlPlaneE2BExecutor } from './src/providers/control-plane-e2b-executor';
+import { E2BToolProvider } from './src/providers/e2b-tool-provider';
+
+// Connect to sandbox service
+const executor = new ControlPlaneE2BExecutor({
+  baseUrl: process.env.SAMYX_BASE_URL!,
+  apiKey: process.env.SAMYX_API_KEY!,
+  templateId: 'polyglot-v1',
+});
+await executor.initialize();  // creates a Firecracker VM
+
+const toolProvider = new E2BToolProvider(executor);
+
+// ... use with createAgent or ArcLoop
+
+await executor.destroy();  // tears down the VM
+```
+
+From environment variables: `ControlPlaneE2BExecutor.fromEnv()` reads `SAMYX_BASE_URL` and `SAMYX_API_KEY`.
+
+---
+
+## Single-Agent Mode (`createAgent`)
+
+For simple tasks that don't need orchestration:
+
+```typescript
+import { createAgent } from './src/agent/create-agent';
+import { LocalToolProvider } from './src/providers/local-tool-provider';
+
+const agent = createAgent({
+  toolProvider: new LocalToolProvider(process.cwd()),
+  loop: new VercelAgentLoop(),  // needs ANTHROPIC_API_KEY
+});
+
+const result = await agent.run('list all TypeScript files');
+console.log(result.output);
+```
+
+### Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `toolProvider` | `ToolProvider` | required | Executes tool calls |
+| `loop` | `AgentLoop` | `VercelAgentLoop` | LLM decision loop |
+| `sandboxProvider` | `SandboxProvider` | — | Higher-level sandbox operations |
+| `maxSteps` | `number` | 30 | Max tool steps per run |
+| `telemetry` | `HarnessTelemetry` | — | OpenTelemetry-style tracing |
+| `skillIndexPath` | `string` | — | Path to skill index JSON for routing |
+
+### VercelAgentLoop
+
+Calls Claude via the Vercel AI SDK. Supports parallel tool calls and configurable system prompt.
+
+```typescript
+const loop = new VercelAgentLoop({
+  systemPrompt: 'You are a helpful coding assistant.',
+  model: 'claude-sonnet-4-5',  // or HARNESS_MODEL env var
+});
+```
+
+### LCMToolLoop
+
+Wraps another loop to add Lossless Context Management and optional REPL orchestration:
+
+```typescript
+import { LCMToolLoop } from './src/loop/lcm-tool-loop';
+import { VercelAgentLoop } from './src/loop/vercel-agent-loop';
+
+const loop = new LCMToolLoop({
+  innerLoop: new VercelAgentLoop(),
+  toolProvider: mySandboxProvider,
+  enableRepl: true,           // default: true
+  bridgeDir: '/var/run/bridge',
+  onActivity: (entry) => console.log(entry),
+  onLlmRequest: async (prompt) => callLLM(prompt),
+  onWebFetchRequest: async (url) => fetch(url),
+});
+```
+
+**Standard mode**: Lossless context trimming — the LLM always sees a coherent, budget-fitting view of the full conversation.
+
+**REPL mode**: When the LLM returns a Bash action with the REPL marker, the loop writes a Python script into the sandbox, injects the bridge module, runs the script, and polls for sub-requests (LLM, web_fetch, ask_user) that the harness fulfills.
+
+---
+
+## ArcLoop (Orchestrator Mode)
+
+For complex tasks that benefit from parallel processes, context management, and memory:
+
+```typescript
+import { createArcAgent } from './src/arc/create-arc-agent';
+
+const agent = await createArcAgent({
+  toolProvider: myToolProvider,
+  episodeStore: myEpisodeStore,       // required
+  sessionMemoStore: mySessionMemoStore, // required
+  longTermStore: myLongTermStore,       // required
+  taskId: 'task-1',
+  sessionId: 'session-1',
+});
+
+// Streaming
+for await (const event of agent.stream(messages, signal)) {
+  if (event.type === 'text_delta') process.stdout.write(event.text);
+  if (event.type === 'process_dispatched') console.log(`  → ${event.action}`);
+  if (event.type === 'done') console.log(`Done in ${event.stats.durationMs}ms`);
+}
+
+// Non-streaming
+const result = await agent.run(messages, signal);
+```
+
+### ArcLoopConfig
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `model` | `string` | `'claude-opus-4-6'` | Orchestrator model (ID or tier name) |
+| `modelMap` | `Record<ModelTier, string>` | haiku/sonnet/opus | Maps fast/medium/strong to model IDs |
+| `apiKey` | `string` | — | Anthropic API key |
+| `systemPrompt` | `string` | built-in | Custom orchestrator system prompt |
+| `maxTurns` | `number` | 30 | Max orchestrator turns |
+| `processTimeout` | `number` | 120_000 | Per-process timeout (ms) |
+| `processMaxSteps` | `number` | 20 | Per-process max tool steps |
+| `contextWindowSize` | `number` | 200_000 | Context window in tokens |
+| `outputReserve` | `number` | 20_000 | Tokens reserved for output |
+| `autoMemory` | `boolean` | true | Auto-detect patterns from episodes |
+| `episodeStore` | `EpisodeStore` | required | Stores episode summaries + traces |
+| `sessionMemoStore` | `SessionMemoStore` | required | Stores session memos |
+| `longTermStore` | `LongTermStore` | required | Stores long-term memories |
+| `taskId` | `string` | required | Task identifier |
+| `sessionId` | `string` | required | Session identifier |
+| `toolProvider` | `ToolProvider` | required | Tool execution |
+| `processTools` | `Record<string, AnyTool>` | builtinTools | Tools available inside processes |
+| `extraOrchestratorTools` | `Record<string, AnyTool>` | — | Custom orchestrator tools |
+| `onOrchestratorTool` | `function` | — | Handler for custom orchestrator tools |
+| `resilience` | `ResiliencePolicy` | — | Composable resilience pipeline |
+| `traceWriter` | `function` | — | Callback for trace event emission |
+
+### Resilience
+
+```typescript
+import { resilience } from './src/arc/resilience';
+
+const pipeline = resilience()
+  .retry({ maxRetries: 2, baseDelay: 1000 })
+  .timeout({ durationMs: 30_000 })
+  .circuitBreaker({ failureThreshold: 5 })
+  .build();
+
+const agent = await createArcAgent({
+  // ...config
+  resilience: pipeline,
+});
+```
+
+### Trace Emission
+
+```typescript
+const traces: TraceEvent[] = [];
+const agent = await createArcAgent({
+  // ...config
+  traceWriter: (event) => traces.push(event),
+});
+```
+
+Traces can be validated against the formal model: `cd verify && cargo run -- trace file.ndjson`
+
+---
+
+## Package Layout
+
+```
+src/
+├── agent/          # createAgent, step executor, types
+├── arc/            # ArcLoop orchestrator, processes, memory, resilience
+│   ├── resilience/ # Retry, circuit breaker, timeout, bulkhead, fallback
+│   ├── stores/     # RxDB + in-memory store implementations
+│   └── object-store/ # Pluggable cloud sync (fs, memory)
+├── interfaces/     # ToolProvider, SandboxProvider, AgentLoop contracts
+├── loop/           # VercelAgentLoop, LCMToolLoop
+├── providers/      # LocalToolProvider, E2BToolProvider, ControlPlaneE2BExecutor
+├── context/        # Token tracking and compaction
+├── hooks/          # Pre/post tool call hooks
+├── permissions/    # Tool permission checks
+├── sessions/       # Session persistence
+├── subagents/      # Subagent spawning
+├── skills/         # Skill index, routing, and management
+├── optimization/   # Benchmark runner
+└── observability/  # OpenTelemetry integration
+
+verify/             # Rust formal verification (Stateright model checker)
+testing/            # Adversarial scenario replay harness
+tests/              # Vitest test suite
+```
+
+## Documentation
+
+- [Arc architecture](../docs/arc.md) — process model, context window, memory, resilience, verification
+- [Testing](../docs/testing.md) — test layers, running tests, writing new tests
+- [Sandbox setup](../docs/PUBLIC_SANDBOX.md) — deploying the sandbox service
+- [Release process](../docs/RELEASE.md) — versioning and publishing
+- [Example](../examples/chat-assistant/src/chat.ts) — complete working chat assistant