@bluecopa/harness 0.1.0-snapshot.49 → 0.1.0-snapshot.5

package/README.md

@@ -2,17 +2,9 @@
 
 Provider-agnostic TypeScript agent framework with Claude-code-compatible tool semantics.
 
-Published on npm as **`@bluecopa/harness`**.
+The harness provides the core loop that drives an AI agent: send messages to an LLM, execute the tool calls it returns, feed results back, and repeat until the LLM produces a final text response.
 
-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
+## Quickstart
 
 ```bash
 pnpm install
@@ -21,11 +13,9 @@ pnpm test
 
 ## Architecture
 
-### Single-Agent Loop
-
 ```
 ┌──────────────┐     ┌──────────────┐     ┌──────────────────┐
-│  createAgent │────►│  AgentLoop   │────►│  LLM (Claude)    │
+│  createAgent │────▶│  AgentLoop   │────▶│  LLM (Claude)    │
 │  (turn loop) │     │  (nextAction)│     │                  │
 └──────┬───────┘     └──────────────┘     └──────────────────┘
        │                                           │
@@ -37,82 +27,20 @@ pnpm test
 └──────────────┘
 ```
 
-### 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:
+1. `createAgent` drives a deterministic step loop
+2. Each step calls `loop.nextAction(messages)` to get the LLM's decision
+3. If it's a tool call, the harness executes it via `ToolProvider` and appends the result
+4. If it's a final action, the loop ends and returns the result
 
-| 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) |
+## Using with the sandbox
 
-## SandboxProvider
+The most common setup connects the harness to a running sandbox service via `ControlPlaneE2BExecutor`:
 
-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';
+```ts
+import { createAgent } from './src/agent/create-agent';
 import { E2BToolProvider } from './src/providers/e2b-tool-provider';
+import { ControlPlaneE2BExecutor } from './src/providers/control-plane-e2b-executor';
+import { VercelAgentLoop } from './src/loop/vercel-agent-loop';
 
 // Connect to sandbox service
 const executor = new ControlPlaneE2BExecutor({
@@ -122,174 +50,155 @@ const executor = new ControlPlaneE2BExecutor({
 });
 await executor.initialize();  // creates a Firecracker VM
 
-const toolProvider = new E2BToolProvider(executor);
+// Build and run the agent
+const agent = createAgent({
+  toolProvider: new E2BToolProvider(executor),
+  loop: new VercelAgentLoop(),  // needs ANTHROPIC_API_KEY
+});
 
-// ... use with createAgent or ArcLoop
+const result = await agent.run('create a bar chart of sales data');
+console.log(result.output);   // LLM's final response
+console.log(result.steps);    // number of tool steps
 
-await executor.destroy();  // tears down the VM
+await executor.destroy();     // tears down the VM
 ```
 
-From environment variables: `ControlPlaneE2BExecutor.fromEnv()` reads `SAMYX_BASE_URL` and `SAMYX_API_KEY`.
+For a complete working example, see [`examples/chat-assistant/src/chat.ts`](../examples/chat-assistant/src/chat.ts).
+
+### From environment variables
 
----
+`ControlPlaneE2BExecutor.fromEnv()` reads `SAMYX_BASE_URL` and `SAMYX_API_KEY` automatically:
 
-## Single-Agent Mode (`createAgent`)
+```ts
+const executor = ControlPlaneE2BExecutor.fromEnv();
+```
 
-For simple tasks that don't need orchestration:
+## Using locally (no sandbox)
 
-```typescript
+For development without a sandbox service, use `LocalToolProvider` which runs tools on the local machine:
+
+```ts
 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
+  loop: new VercelAgentLoop(),
 });
 
 const result = await agent.run('list all TypeScript files');
-console.log(result.output);
 ```
 
-### Configuration
+## Key modules
+
+### Agent creation (`src/agent/create-agent.ts`)
 
-| 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 |
+`createAgent(options)` returns an agent with a `.run(prompt, options?)` method. Options:
 
-### VercelAgentLoop
+| Option | Type | Description |
+|--------|------|-------------|
+| `toolProvider` | `ToolProvider` | Required. Executes tool calls |
+| `loop` | `AgentLoop` | LLM decision loop (default: `VercelAgentLoop`) |
+| `sandboxProvider` | `SandboxProvider` | Optional. Higher-level sandbox ops (file download, exec with env) |
+| `maxSteps` | `number` | Max tool steps per run (default: 30) |
+| `telemetry` | `HarnessTelemetry` | Optional. OpenTelemetry-style tracing |
+| `skillIndexPath` | `string` | Optional. Path to skill index JSON |
 
-Calls Claude via the Vercel AI SDK. Supports parallel tool calls and configurable system prompt.
+### Agent loop (`src/loop/vercel-agent-loop.ts`)
 
-```typescript
+`VercelAgentLoop` calls Claude via the Vercel AI SDK. It supports:
+- Parallel tool calls (returns `ToolBatchAction` when the LLM requests multiple tools at once)
+- Configurable system prompt
+- Model selection via `HARNESS_MODEL` env var (default: `claude-sonnet-4-5`)
+
+```ts
 const loop = new VercelAgentLoop({
   systemPrompt: 'You are a helpful coding assistant.',
-  model: 'claude-sonnet-4-5',  // or HARNESS_MODEL env var
 });
 ```
 
-### LCMToolLoop
+### Tool provider (`src/interfaces/tool-provider.ts`)
 
-Wraps another loop to add Lossless Context Management and optional REPL orchestration:
+The contract for tool execution:
 
-```typescript
-import { LCMToolLoop } from './src/loop/lcm-tool-loop';
-import { VercelAgentLoop } from './src/loop/vercel-agent-loop';
+```ts
+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;
+}
 
-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),
-});
+interface ToolResult {
+  success: boolean;
+  output: string;
+  error?: string;
+}
 ```
 
-**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.
-
----
+Built-in implementations:
 
-## ArcLoop (Orchestrator Mode)
+| Provider | Description |
+|----------|-------------|
+| `LocalToolProvider` | Runs tools on the local filesystem |
+| `E2BToolProvider` | Routes tools to an E2B-compatible executor over HTTP |
+| `CompositeToolProvider` | Combines multiple providers (e.g. sandbox + web) |
 
-For complex tasks that benefit from parallel processes, context management, and memory:
+### Action types (`src/agent/types.ts`)
 
-```typescript
-import { createArcAgent } from './src/arc/create-arc-agent';
+The LLM returns one of these action types each turn:
 
-const agent = await createArcAgent({
-  toolProvider: myToolProvider,
-  episodeStore: myEpisodeStore,       // required
-  sessionMemoStore: mySessionMemoStore, // required
-  longTermStore: myLongTermStore,       // required
-  taskId: 'task-1',
-  sessionId: 'session-1',
-});
+```ts
+// Single tool call
+interface ToolCallAction {
+  type: 'tool';
+  name: 'Bash' | 'Read' | 'Write' | 'Edit' | 'Glob' | 'Grep' | ...;
+  args: Record<string, unknown>;
+}
 
-// 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`);
+// Multiple independent tool calls (executed in parallel)
+interface ToolBatchAction {
+  type: 'tool_batch';
+  calls: ToolCallAction[];
 }
 
-// Non-streaming
-const result = await agent.run(messages, signal);
+// Final text response (ends the loop)
+interface FinalAction {
+  type: 'final';
+  content: string;
+}
 ```
 
-### 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,
-});
-```
+### LCM tool loop (`src/loop/lcm-tool-loop.ts`)
 
-### Trace Emission
+`LCMToolLoop` wraps another loop to add LCM-based tool routing, REPL script execution, and bridge-based tool dispatch. Used in the chat-assistant example.
 
-```typescript
-const traces: TraceEvent[] = [];
-const agent = await createArcAgent({
-  // ...config
-  traceWriter: (event) => traces.push(event),
-});
+### Sandbox provider (`src/interfaces/sandbox-provider.ts`)
+
+Higher-level sandbox operations beyond basic tool calls:
+
+```ts
+interface SandboxProvider {
+  exec(command: string, options?: SandboxExecOptions): Promise<SandboxExecResult>;
+  readSandboxFile(path: string): Promise<SandboxFileBlob>;
+  writeSandboxFile(path: string, content: SandboxFileBlob): Promise<void>;
+}
 ```
 
-Traces can be validated against the formal model: `cd verify && cargo run -- trace file.ndjson`
+### Observability (`src/observability/otel.ts`)
 
----
+`HarnessTelemetry` provides OpenTelemetry-style spans and metrics for agent runs.
 
-## Package Layout
+## 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
@@ -297,20 +206,16 @@ src/
 ├── hooks/          # Pre/post tool call hooks
 ├── permissions/    # Tool permission checks
 ├── sessions/       # Session persistence
-├── subagents/      # Subagent spawning
+├── subagents/      # Subagent spawning and task tools
 ├── 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
+- Provider guide: `docs/guides/providers.md`
+- Skills guide: `docs/guides/skills.md`
+- Observability guide: `docs/guides/observability.md`
+- Release process: `../docs/RELEASE.md`
+- Full example: [`../examples/chat-assistant/src/chat.ts`](../examples/chat-assistant/src/chat.ts)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluecopa/harness",
-  "version": "0.1.0-snapshot.49",
+  "version": "0.1.0-snapshot.5",
   "description": "Provider-agnostic TypeScript agent framework",
   "license": "UNLICENSED",
   "scripts": {
@@ -10,7 +10,6 @@
   "dependencies": {
     "@ai-sdk/anthropic": "^3.0.48",
     "ai": "^6.0.101",
-    "rxdb": "^15.39.0",
     "zod": "^4.1.11"
   },
   "devDependencies": {

package/src/agent/create-agent.ts

@@ -7,12 +7,14 @@ import type { HarnessTelemetry } from '../observability/otel';
 import { HookRunner } from '../hooks/hook-runner';
 import { PermissionManager } from '../permissions/permission-manager';
 import { VercelAgentLoop } from '../loop/vercel-agent-loop';
+export type { SystemPromptBlock, VercelAgentLoopConfig } from '../loop/vercel-agent-loop';
+export type { PrepareStepContext, PrepareStepResult } from './types';
 import { SkillManager } from '../skills/skill-manager';
 import { SkillRouter } from '../skills/skill-router';
 import type { SkillSummary } from '../skills/skill-types';
 import { SingleFlightStepExecutor } from './step-executor';
-import type { AgentAction, AgentLoop, AgentMessage, AgentRunResult, AgentStreamEvent, ToolCallAction, ToolBatchAction, ToolCallInfo, ToolResultInfo } from './types';
-export type { AgentAction, AgentLoop, AgentMessage, AgentRunResult, AgentStreamEvent, ToolCallAction, ToolBatchAction, ToolCallInfo, ToolResultInfo };
+import type { AgentAction, AgentLoop, AgentMessage, AgentRunResult, AgentStreamEvent, StepUsage, ToolCallAction, ToolBatchAction, ToolCallInfo, ToolResultInfo } from './types';
+export type { AgentAction, AgentLoop, AgentMessage, AgentRunResult, AgentStreamEvent, StepUsage, ToolCallAction, ToolBatchAction, ToolCallInfo, ToolResultInfo };
 export { HookRunner } from '../hooks/hook-runner';
 export { PermissionManager } from '../permissions/permission-manager';
 export type { PermissionMode, PermissionResolver, PermissionRequest } from '../permissions/permission-manager';
@@ -37,8 +39,6 @@ export interface AgentRuntime {
   /** Custom tool executor. Called for every tool action. Return null to fall through to built-in dispatch.
    *  When hookRunner/permissionManager are provided on the runtime, they are automatically applied before/after this callback — no manual wiring needed. */
   executeToolAction?: (action: ToolCallAction) => Promise<ToolResult | null>;
-  /** Progress callback fired before/after each tool call during run(). */
-  onToolProgress?: (event: { type: 'tool_start'; name: string; args: Record<string, unknown> } | { type: 'tool_end'; name: string; success: boolean; durationMs: number }) => void;
 }
 
 /**
@@ -220,9 +220,12 @@ function toStreamResult(r: ToolResult): { success: boolean; output: string; erro
   return base;
 }
 
-/** Format a display-friendly content string for tool results (used in content field). */
+/** Format content string for LLM context. Uses modelOutput (compact summary) when available. */
 function formatToolResultContent(call: ToolCallAction, result: ToolResult): string {
-  const content = result.success ? result.output : `ERROR: ${result.error ?? 'unknown failure'}`;
+  // Use modelOutput for LLM context when available — keeps context compact
+  const content = result.success
+    ? (result.modelOutput ?? result.output)
+    : `ERROR: ${result.error ?? 'unknown failure'}`;
   switch (call.name) {
     case 'Write':
       return `Write(${call.args.path}): ${result.success ? 'ok' : content}`;
@@ -517,6 +520,11 @@ export function createAgent(runtime: AgentRuntime) {
       ? { nextAction: runtime.nextAction }
       : new VercelAgentLoop());
 
+  /** Read lastUsage from the loop if it's a VercelAgentLoop. */
+  function getLoopUsage(): StepUsage | undefined {
+    return loop instanceof VercelAgentLoop ? loop.lastUsage : undefined;
+  }
+
   async function resolveSkillContext(prompt: string): Promise<string> {
     if (!skillManager || !skillIndexPath) return '';
 
@@ -598,18 +606,14 @@ export function createAgent(runtime: AgentRuntime) {
 
             // Execute valid calls via batch (sequential sandbox ops) or parallel fallback
             if (validCalls.length > 0) {
-              for (const c of validCalls) runtime.onToolProgress?.({ type: 'tool_start', name: c.name, args: c.args });
-              const batchStart = Date.now();
               const results = await executeBatch(validCalls, runtime.toolProvider, runtime);
-              const batchMs = Date.now() - batchStart;
               for (let i = 0; i < validCalls.length; i++) {
                 const call = validCalls[i]!;
                 const r = results[i]!;
-                runtime.onToolProgress?.({ type: 'tool_end', name: call.name, success: r.success, durationMs: batchMs });
                 if (!r.success) {
                   recordAgentError(runtime.telemetry);
                 }
-                const resultText = r.success ? r.output : `ERROR: ${r.error ?? 'unknown failure'}`;
+                const resultText = r.success ? (r.modelOutput ?? r.output) : `ERROR: ${r.error ?? 'unknown failure'}`;
                 messages.push({
                   role: 'tool',
                   content: formatToolResultContent(call, r),
@@ -665,8 +669,6 @@ export function createAgent(runtime: AgentRuntime) {
           } else {
             consecutiveInvalid = 0;
           }
-          runtime.onToolProgress?.({ type: 'tool_start', name: action.name, args: action.args });
-          const singleStart = Date.now();
           const result = validationError
             ? ({ success: false, output: '', error: validationError } as ToolResult)
             : await executor.run(async () => {
@@ -680,11 +682,10 @@ export function createAgent(runtime: AgentRuntime) {
                   };
                 }
               });
-          runtime.onToolProgress?.({ type: 'tool_end', name: action.name, success: result.success, durationMs: Date.now() - singleStart });
           if (!result.success) {
             recordAgentError(runtime.telemetry);
           }
-          const singleResultText = result.success ? result.output : `ERROR: ${result.error ?? 'unknown failure'}`;
+          const singleResultText = result.success ? (result.modelOutput ?? result.output) : `ERROR: ${result.error ?? 'unknown failure'}`;
           messages.push({
             role: 'tool',
             content: formatToolResultContent(action, result),
@@ -727,7 +728,8 @@ export function createAgent(runtime: AgentRuntime) {
             if (event.type === 'text_delta') {
               finalText += event.text;
               yield event;
-            } else if (event.type === 'tool_start') {
+            }
+            if (event.type === 'tool_start') {
               pendingTools.push({
                 type: 'tool',
                 name: event.name,
@@ -735,18 +737,13 @@ export function createAgent(runtime: AgentRuntime) {
                 ...(event.toolCallId != null ? { toolCallId: event.toolCallId } : {}),
               });
               yield event;
-            } else {
-              // Forward all other events (tool_end, step_start, step_end, done)
-              // from self-managing loops like ArcLoop
-              yield event;
-              if (event.type === 'done') return;
             }
           }
 
           // If no tools → final response
           if (pendingTools.length === 0) {
             messages.push({ role: 'assistant', content: finalText });
-            yield { type: 'step_end', step };
+            { const u = getLoopUsage(); yield u ? { type: 'step_end' as const, step, usage: u } : { type: 'step_end' as const, step }; }
             yield { type: 'done', output: finalText, steps: step };
             return;
           }
@@ -772,7 +769,7 @@ export function createAgent(runtime: AgentRuntime) {
             if (action.type === 'final') {
               yield { type: 'text_delta', text: action.content };
               messages.push({ role: 'assistant', content: action.content });
-              yield { type: 'step_end', step };
+              { const u = getLoopUsage(); yield u ? { type: 'step_end' as const, step, usage: u } : { type: 'step_end' as const, step }; }
               yield { type: 'done', output: action.content, steps: step };
               return;
             }
@@ -784,7 +781,7 @@ export function createAgent(runtime: AgentRuntime) {
                 try {
                   const r = await executeTool(runtime.toolProvider, call, runtime);
                   yield { type: 'tool_end', name: call.name, result: toStreamResult(r) };
-                  const rText = r.success ? r.output : `ERROR: ${r.error ?? 'unknown failure'}`;
+                  const rText = r.success ? (r.modelOutput ?? r.output) : `ERROR: ${r.error ?? 'unknown failure'}`;
                   messages.push({
                     role: 'tool',
                     content: formatToolResultContent(call, r),
@@ -806,7 +803,7 @@ export function createAgent(runtime: AgentRuntime) {
               try {
                 const r = await executeTool(runtime.toolProvider, action, runtime);
                 yield { type: 'tool_end', name: action.name, result: toStreamResult(r) };
-                const rText = r.success ? r.output : `ERROR: ${r.error ?? 'unknown failure'}`;
+                const rText = r.success ? (r.modelOutput ?? r.output) : `ERROR: ${r.error ?? 'unknown failure'}`;
                 messages.push({
                   role: 'tool',
                   content: formatToolResultContent(action, r),
@@ -822,7 +819,7 @@ export function createAgent(runtime: AgentRuntime) {
                 });
               }
             }
-            yield { type: 'step_end', step };
+            { const u = getLoopUsage(); yield u ? { type: 'step_end' as const, step, usage: u } : { type: 'step_end' as const, step }; }
             continue;
           }
 
@@ -832,7 +829,7 @@ export function createAgent(runtime: AgentRuntime) {
             const call = pendingTools[i]!;
             const r = results[i]!;
             yield { type: 'tool_end', name: call.name, result: toStreamResult(r) };
-            const rText = r.success ? r.output : `ERROR: ${r.error ?? 'unknown failure'}`;
+            const rText = r.success ? (r.modelOutput ?? r.output) : `ERROR: ${r.error ?? 'unknown failure'}`;
             messages.push({
               role: 'tool',
               content: formatToolResultContent(call, r),
@@ -850,7 +847,7 @@ export function createAgent(runtime: AgentRuntime) {
 
           if (action.type === 'final') {
             messages.push({ role: 'assistant', content: action.content });
-            yield { type: 'step_end', step };
+            { const u = getLoopUsage(); yield u ? { type: 'step_end' as const, step, usage: u } : { type: 'step_end' as const, step }; }
             yield { type: 'done', output: action.content, steps: step };
             return;
           }
@@ -874,7 +871,7 @@ export function createAgent(runtime: AgentRuntime) {
             const call = calls[i]!;
             const r = results[i]!;
             yield { type: 'tool_end', name: call.name, result: toStreamResult(r) };
-            const rText = r.success ? r.output : `ERROR: ${r.error ?? 'unknown failure'}`;
+            const rText = r.success ? (r.modelOutput ?? r.output) : `ERROR: ${r.error ?? 'unknown failure'}`;
             messages.push({
               role: 'tool',
               content: formatToolResultContent(call, r),
@@ -888,7 +885,7 @@ export function createAgent(runtime: AgentRuntime) {
           }
         }
 
-        yield { type: 'step_end', step };
+        { const u = getLoopUsage(); yield u ? { type: 'step_end' as const, step, usage: u } : { type: 'step_end' as const, step }; }
       }
 
       yield { type: 'done', output: 'ERROR: max steps exceeded', steps: maxSteps };