@dogpile/sdk 0.5.0 → 0.6.0

package/src/runtime/coordinator.ts

@@ -87,6 +87,7 @@ export type RunProtocolFn = (input: {
   readonly currentDepth?: number;
   readonly effectiveMaxDepth?: number;
   readonly effectiveMaxConcurrentChildren?: number;
+  readonly effectiveMaxConcurrentAgentTurns?: number;
   readonly onChildFailure?: DogpileOptions["onChildFailure"];
   /**
    * Root-run deadline (epoch ms). Children inherit `parentDeadlineMs - now()`
@@ -126,11 +127,12 @@ interface CoordinatorRunOptions {
    */
   readonly currentDepth?: number;
   /**
-   * Effective max recursion depth resolved at run start. Plan 04 enforces;
-   * Plan 03 only plumbs the value.
+   * Effective max recursion depth resolved at run start and enforced before
+   * delegate dispatch.
    */
   readonly effectiveMaxDepth?: number;
   readonly effectiveMaxConcurrentChildren?: number;
+  readonly effectiveMaxConcurrentAgentTurns?: number;
   readonly onChildFailure?: DogpileOptions["onChildFailure"];
   /**
    * Engine `runProtocol` callback used by the delegate dispatch loop to
@@ -162,6 +164,7 @@ interface CoordinatorRunOptions {
  */
 const MAX_DISPATCH_PER_TURN = 8;
 const DEFAULT_MAX_CONCURRENT_CHILDREN = 4;
+const DEFAULT_MAX_CONCURRENT_AGENT_TURNS = 4;
 
 type DispatchWaveFailure = {
   readonly childRunId: string;
@@ -183,7 +186,8 @@ interface Semaphore {
 
 function createSemaphore(maxConcurrent: number): Semaphore {
   let inFlight = 0;
-  const waiters: Array<() => void> = [];
+  const waiters: Array<(() => void) | undefined> = [];
+  let waiterHead = 0;
   return {
     acquire(): Promise<void> {
       if (inFlight < maxConcurrent) {
@@ -199,8 +203,14 @@ function createSemaphore(maxConcurrent: number): Semaphore {
     },
     release(): void {
       inFlight -= 1;
-      const next = waiters.shift();
+      const next = waiters[waiterHead];
       if (next !== undefined) {
+        waiters[waiterHead] = undefined;
+        waiterHead += 1;
+        if (waiterHead > 32 && waiterHead * 2 > waiters.length) {
+          waiters.splice(0, waiterHead);
+          waiterHead = 0;
+        }
         next();
       }
     },
@@ -208,7 +218,7 @@ function createSemaphore(maxConcurrent: number): Semaphore {
       return inFlight;
     },
     get queued() {
-      return waiters.length;
+      return waiters.length - waiterHead;
     }
   };
 }
@@ -218,15 +228,16 @@ function createSemaphore(maxConcurrent: number): Semaphore {
  * whose metadata.locality === "local", or undefined if none found.
  *
  * Walk order (forward-compat): options.model first, then options.agents in
- * declaration order. AgentSpec has no `model` field today (Phase 3 D-11
- * forward-compat scaffolding); the agent walk uses optional chaining and
- * effectively no-ops until a future phase adds AgentSpec.model.
+ * declaration order. AgentSpec has no `model` field today; the agent walk
+ * uses optional chaining and effectively no-ops until a future caller-defined
+ * tree surface adds AgentSpec.model.
  */
 function findFirstLocalProvider(options: CoordinatorRunOptions): ConfiguredModelProvider | undefined {
   if (options.model.metadata?.locality === "local") {
     return options.model;
   }
-  // Forward-compat: AgentSpec.model not yet declared (Phase 3 D-11). Walk no-ops today; ready for caller-defined trees in a future milestone.
+  // Forward-compat: AgentSpec.model is not yet declared; this no-ops today and
+  // is ready for a future caller-defined tree surface.
   for (const agent of options.agents) {
     const agentModel = (agent as { readonly model?: ConfiguredModelProvider }).model;
     if (agentModel?.metadata?.locality === "local") {
@@ -363,13 +374,12 @@ export async function runCoordinator(options: CoordinatorRunOptions): Promise<Ru
 
   if (coordinator) {
     if (!stopIfNeeded()) {
-      // Delegate dispatch loop (D-11/D-16/D-17/D-18). Phase 1 limits delegation
-      // to the coordinator's plan turn; workers cannot delegate. The loop
-      // re-issues the coordinator plan turn after each successful sub-run with
-      // the projected D-17 result tagged into the next prompt and a synthetic
-      // D-18 transcript entry already appended. `partialTrace` for failed
-      // sub-runs is captured via a tee'd emit buffer locally — `runProtocol`'s
-      // error contract is unchanged.
+      // Delegate dispatch is restricted to the coordinator's plan turn.
+      // Workers and final synthesis cannot delegate. The loop re-issues the
+      // coordinator plan turn after each successful sub-run with the tagged
+      // child result in the next prompt and a synthetic transcript entry
+      // already appended. Failed children use the local tee buffer for
+      // partialTrace capture; runProtocol's error contract stays unchanged.
       let dispatchInput = buildCoordinatorPlanInput(options.intent, coordinator);
       let dispatchCount = 0;
       while (true) {
@@ -644,29 +654,39 @@ export async function runCoordinator(options: CoordinatorRunOptions): Promise<Ru
       const workers = activeAgents.slice(1);
       const providerCallSlots: ReplayTraceProviderCall[] = [];
       const planTranscript = [...transcript];
-      const workerResults = await Promise.all(
-        workers.map((agent, index) =>
-          runCoordinatorWorkerTurn({
-            agent,
-            coordinator,
-            input: buildWorkerInput(options.intent, planTranscript, coordinator),
-            options,
-            runId,
-            turn: transcript.length + index + 1,
-            providerCallId: providerCallIdFor(runId, providerCalls.length + index + 1),
-            providerCallIndex: index,
-            providerCallSlots,
-            toolExecutor,
-            toolAvailability,
-            totalCost,
-            events,
-            transcript: planTranscript,
-            startedAtMs,
-            wrapUpHint,
-            emit
-          })
-        )
-      );
+      const fanout = createFanoutAbortController(options.signal);
+      const workerResults = await (async () => {
+        try {
+          return await mapWithConcurrency(
+            workers,
+            options.effectiveMaxConcurrentAgentTurns ?? DEFAULT_MAX_CONCURRENT_AGENT_TURNS,
+            fanout,
+            (agent, index) =>
+              runCoordinatorWorkerTurn({
+                agent,
+                coordinator,
+                input: buildWorkerInput(options.intent, planTranscript, coordinator),
+                options,
+                runId,
+                turn: transcript.length + index + 1,
+                providerCallId: providerCallIdFor(runId, providerCalls.length + index + 1),
+                providerCallIndex: index,
+                providerCallSlots,
+                toolExecutor,
+                toolAvailability,
+                totalCost,
+                events,
+                transcript: planTranscript,
+                startedAtMs,
+                wrapUpHint,
+                emit,
+                fanoutSignal: fanout.signal
+              })
+          );
+        } finally {
+          fanout.cleanup();
+        }
+      })();
       providerCalls.push(...providerCallSlots.filter((call): call is ReplayTraceProviderCall => call !== undefined));
 
       for (const result of workerResults) {
@@ -721,11 +741,11 @@ export async function runCoordinator(options: CoordinatorRunOptions): Promise<Ru
         recordProtocolDecision
       });
       totalCost = synthesisOutcome.totalCost;
-      // Phase 1: final-synthesis turn cannot delegate.
+      // Final synthesis is terminal and cannot dispatch children.
       if (Array.isArray(synthesisOutcome.decision) || synthesisOutcome.decision?.type === "delegate") {
         throw new DogpileError({
           code: "invalid-configuration",
-          message: "Coordinator final-synthesis turn cannot emit a delegate decision in Phase 1",
+          message: "Coordinator final-synthesis turn cannot emit a delegate decision.",
           retryable: false,
           detail: {
             kind: "delegate-validation",
@@ -1016,6 +1036,7 @@ interface CoordinatorWorkerTurnOptions {
   readonly startedAtMs: number;
   readonly wrapUpHint: ReturnType<typeof createWrapUpHintController>;
   readonly emit: (event: RunEvent) => void;
+  readonly fanoutSignal?: AbortSignal;
 }
 
 interface CoordinatorWorkerTurnResult {
@@ -1029,10 +1050,11 @@ interface CoordinatorWorkerTurnResult {
 
 async function runCoordinatorWorkerTurn(turn: CoordinatorWorkerTurnOptions): Promise<CoordinatorWorkerTurnResult> {
   throwIfAborted(turn.options.signal, turn.options.model.id);
+  throwIfAborted(turn.fanoutSignal, turn.options.model.id);
 
   const request: ModelRequest = {
     temperature: turn.options.temperature,
-    ...(turn.options.signal !== undefined ? { signal: turn.options.signal } : {}),
+    ...(turn.fanoutSignal !== undefined ? { signal: turn.fanoutSignal } : turn.options.signal !== undefined ? { signal: turn.options.signal } : {}),
     metadata: {
       runId: turn.runId,
       protocol: "coordinator",
@@ -1085,7 +1107,7 @@ async function runCoordinatorWorkerTurn(turn: CoordinatorWorkerTurnOptions): Pro
   if (Array.isArray(decision) || decision?.type === "delegate") {
     throw new DogpileError({
       code: "invalid-configuration",
-      message: "Workers cannot emit delegate decisions in Phase 1",
+      message: "Workers cannot emit delegate decisions.",
       retryable: false,
       detail: {
         kind: "delegate-validation",
@@ -1105,6 +1127,7 @@ async function runCoordinatorWorkerTurn(turn: CoordinatorWorkerTurnOptions): Pro
     }
   });
   throwIfAborted(turn.options.signal, turn.options.model.id);
+  throwIfAborted(turn.fanoutSignal, turn.options.model.id);
 
   return {
     agent: turn.agent,
@@ -1193,6 +1216,76 @@ function responseCost(response: ModelResponse): CostSummary {
   };
 }
 
+interface FanoutAbortController {
+  readonly signal: AbortSignal;
+  abort(reason: unknown): void;
+  cleanup(): void;
+}
+
+function createFanoutAbortController(parentSignal: AbortSignal | undefined): FanoutAbortController {
+  const controller = new AbortController();
+  let removeParentListener = (): void => {};
+
+  if (parentSignal?.aborted) {
+    controller.abort(parentSignal.reason);
+  } else if (parentSignal !== undefined) {
+    const abortFromParent = (): void => {
+      controller.abort(parentSignal.reason);
+    };
+    parentSignal.addEventListener("abort", abortFromParent, { once: true });
+    removeParentListener = (): void => {
+      parentSignal.removeEventListener("abort", abortFromParent);
+    };
+  }
+
+  return {
+    signal: controller.signal,
+    abort(reason: unknown): void {
+      if (!controller.signal.aborted) {
+        controller.abort(reason);
+      }
+    },
+    cleanup(): void {
+      removeParentListener();
+    }
+  };
+}
+
+async function mapWithConcurrency<T, R>(
+  items: readonly T[],
+  maxConcurrent: number,
+  fanout: FanoutAbortController,
+  mapper: (item: T, index: number) => Promise<R>
+): Promise<R[]> {
+  if (items.length === 0) {
+    return [];
+  }
+
+  const results: R[] = new Array(items.length);
+  let nextIndex = 0;
+  let firstError: unknown;
+  const workerCount = Math.min(maxConcurrent, items.length);
+
+  await Promise.all(Array.from({ length: workerCount }, async () => {
+    while (nextIndex < items.length && firstError === undefined) {
+      const index = nextIndex;
+      nextIndex += 1;
+      try {
+        results[index] = await mapper(items[index]!, index);
+      } catch (error) {
+        firstError ??= error;
+        fanout.abort(error);
+      }
+    }
+  }));
+
+  if (firstError !== undefined) {
+    throw firstError;
+  }
+
+  return results;
+}
+
 interface DispatchDelegateOptions {
   readonly decision: DelegateAgentDecision;
   readonly childRunId?: string;
@@ -1238,7 +1331,7 @@ interface DispatchedChild {
   startedAtMs: number;
   childTimeoutMs: number | undefined;
   failure: DispatchWaveFailure | undefined;
-  /** STREAM-03 hook (Phase 4). Reserved; do not use. */
+  /** Reserved child stream handle slot; do not use. */
   readonly streamHandle?: never;
 }
 
@@ -1324,7 +1417,7 @@ async function dispatchDelegate(input: DispatchDelegateOptions): Promise<Dispatc
     });
   }
 
-  // Buffered tee for partialTrace capture — see Plan 03 step 8.
+  // Buffered tee captures the child event prefix used for partialTrace.
   const childEvents = input.dispatchedChild.childEvents;
   const parentEmit = input.emit;
   const teedEmit = (event: RunEvent): void => {
@@ -1381,7 +1474,7 @@ async function dispatchDelegate(input: DispatchDelegateOptions): Promise<Dispatc
   // BUDGET-01 / D-07: derive a per-child AbortController so child engines see
   // their own signal. Listener forwards parent.signal.reason verbatim, so
   // detail.reason classification (parent-aborted vs timeout) is preserved.
-  // Phase 4 STREAM-03 hook: per-child cancel handle attaches here.
+  // Reserved per-child stream cancel hook attaches here if that surface ships.
   const parentSignal = options.signal;
   let removeParentAbortListener: (() => void) | undefined;
   if (parentSignal !== undefined) {
@@ -1429,6 +1522,9 @@ async function dispatchDelegate(input: DispatchDelegateOptions): Promise<Dispatc
     ...(options.effectiveMaxConcurrentChildren !== undefined
       ? { effectiveMaxConcurrentChildren: options.effectiveMaxConcurrentChildren }
       : {}),
+    ...(options.effectiveMaxConcurrentAgentTurns !== undefined
+      ? { effectiveMaxConcurrentAgentTurns: options.effectiveMaxConcurrentAgentTurns }
+      : {}),
     ...(options.onChildFailure !== undefined ? { onChildFailure: options.onChildFailure } : {}),
     // BUDGET-02 / D-12: forward the ROOT deadline so depth-N grandchildren
     // see the same `parentDeadlineMs` rather than a fresh per-level snapshot.
@@ -1644,7 +1740,7 @@ function eventTimestamp(event: RunEvent | undefined): string | undefined {
 /**
  * Build a JSON-serializable {@link Trace} for `sub-run-failed.partialTrace`
  * from a buffered tee of child emits. Keeps `runProtocol`'s error contract
- * unchanged — Plan 03 step 8.
+ * unchanged.
  */
 function buildPartialTrace(input: {
   readonly childRunId: string;

package/src/runtime/defaults.ts

@@ -404,7 +404,8 @@ export function createReplayTraceProtocolDecision(
         agentId: event.agentId,
         role: event.role,
         input: event.input,
-        output: event.output
+        output: event.text,
+        outputLength: event.outputLength
       };
     case "tool-call":
       return {

package/src/runtime/engine.ts

@@ -69,6 +69,7 @@ import type { MetricsHook, RunMetricsSnapshot } from "./metrics.js";
 
 const DEFAULT_MAX_DEPTH = 4;
 const DEFAULT_MAX_CONCURRENT_CHILDREN = 4;
+const DEFAULT_MAX_CONCURRENT_AGENT_TURNS = 4;
 
 const defaultHighLevelProtocol = "sequential";
 const defaultHighLevelTier = "balanced";
@@ -99,6 +100,7 @@ export function createEngine(options: EngineOptions): Engine {
   const terminate = options.terminate ?? (options.budget ? conditionFromBudget(options.budget) : undefined);
   const engineMaxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
   const engineMaxConcurrentChildren = options.maxConcurrentChildren ?? DEFAULT_MAX_CONCURRENT_CHILDREN;
+  const engineMaxConcurrentAgentTurns = options.maxConcurrentAgentTurns ?? DEFAULT_MAX_CONCURRENT_AGENT_TURNS;
   const engineOnChildFailure = options.onChildFailure;
 
   return {
@@ -120,6 +122,15 @@ export function createEngine(options: EngineOptions): Engine {
         engineMaxConcurrentChildren,
         runOptions?.maxConcurrentChildren ?? Number.POSITIVE_INFINITY
       );
+      assertRunDoesNotRaiseEngineMax(
+        "maxConcurrentAgentTurns",
+        runOptions?.maxConcurrentAgentTurns,
+        engineMaxConcurrentAgentTurns
+      );
+      const effectiveMaxConcurrentAgentTurns = Math.min(
+        engineMaxConcurrentAgentTurns,
+        runOptions?.maxConcurrentAgentTurns ?? Number.POSITIVE_INFINITY
+      );
       const onChildFailure = resolveOnChildFailure(runOptions?.onChildFailure, engineOnChildFailure);
 
       const startedAtMs = Date.now();
@@ -146,6 +157,7 @@ export function createEngine(options: EngineOptions): Engine {
         currentDepth: 0,
         effectiveMaxDepth,
         effectiveMaxConcurrentChildren,
+        effectiveMaxConcurrentAgentTurns,
         onChildFailure,
         ...(parentDeadlineMs !== undefined ? { parentDeadlineMs } : {}),
         ...(options.defaultSubRunTimeoutMs !== undefined
@@ -172,10 +184,18 @@ export function createEngine(options: EngineOptions): Engine {
         engineMaxConcurrentChildren,
         runOptions?.maxConcurrentChildren ?? Number.POSITIVE_INFINITY
       );
+      assertRunDoesNotRaiseEngineMax(
+        "maxConcurrentAgentTurns",
+        runOptions?.maxConcurrentAgentTurns,
+        engineMaxConcurrentAgentTurns
+      );
+      const effectiveMaxConcurrentAgentTurns = Math.min(
+        engineMaxConcurrentAgentTurns,
+        runOptions?.maxConcurrentAgentTurns ?? Number.POSITIVE_INFINITY
+      );
       const onChildFailure = resolveOnChildFailure(runOptions?.onChildFailure, engineOnChildFailure);
 
-      const pendingEvents: StreamEvent[] = [];
-      const pendingResolvers: Array<(value: IteratorResult<StreamEvent>) => void> = [];
+      const pendingIteratorResolvers: Array<() => void> = [];
       const emittedEvents: StreamEvent[] = [];
       const subscribers = new Set<StreamEventSubscriber>();
       const abortController = new AbortController();
@@ -212,12 +232,20 @@ export function createEngine(options: EngineOptions): Engine {
           cancelRun();
         },
         subscribe(subscriber: StreamEventSubscriber) {
-          subscribers.add(subscriber);
-
           for (const event of emittedEvents) {
             subscriber(event);
           }
 
+          if (complete) {
+            return {
+              unsubscribe(): void {
+                // Completed streams replay synchronously and have no live source.
+              }
+            };
+          }
+
+          subscribers.add(subscriber);
+
           return {
             unsubscribe(): void {
               subscribers.delete(subscriber);
@@ -225,20 +253,29 @@ export function createEngine(options: EngineOptions): Engine {
           };
         },
         [Symbol.asyncIterator](): AsyncIterator<StreamEvent> {
+          let cursor = 0;
+
           return {
             next(): Promise<IteratorResult<StreamEvent>> {
-              const event = pendingEvents.shift();
-              if (event) {
-                return Promise.resolve({ done: false, value: event });
-              }
-              if (complete) {
-                return Promise.resolve({ done: true, value: undefined });
-              }
-              return new Promise<IteratorResult<StreamEvent>>((resolve) => {
-                pendingResolvers.push(resolve);
-              });
+              return readNext();
             }
           };
+
+          function readNext(): Promise<IteratorResult<StreamEvent>> {
+            const event = emittedEvents[cursor];
+            if (event !== undefined) {
+              cursor += 1;
+              return Promise.resolve({ done: false, value: event });
+            }
+            if (complete) {
+              return Promise.resolve({ done: true, value: undefined });
+            }
+            return new Promise<IteratorResult<StreamEvent>>((resolve) => {
+              pendingIteratorResolvers.push(() => {
+                void readNext().then(resolve);
+              });
+            });
+          }
         }
       };
 
@@ -266,6 +303,7 @@ export function createEngine(options: EngineOptions): Engine {
             currentDepth: 0,
             effectiveMaxDepth,
             effectiveMaxConcurrentChildren,
+            effectiveMaxConcurrentAgentTurns,
             onChildFailure,
             ...(streamParentDeadlineMs !== undefined ? { parentDeadlineMs: streamParentDeadlineMs } : {}),
             ...(options.defaultSubRunTimeoutMs !== undefined
@@ -362,8 +400,8 @@ export function createEngine(options: EngineOptions): Engine {
         timeoutLifecycle.cleanup();
         abortRace.cleanup();
         subscribers.clear();
-        for (const resolver of pendingResolvers.splice(0)) {
-          resolver({ done: true, value: undefined });
+        for (const resolvePending of pendingIteratorResolvers.splice(0)) {
+          resolvePending();
         }
       }
 
@@ -383,12 +421,9 @@ export function createEngine(options: EngineOptions): Engine {
           }
         }
 
-        const resolver = pendingResolvers.shift();
-        if (resolver) {
-          resolver({ done: false, value: canonicalEvent });
-          return;
+        for (const resolvePending of pendingIteratorResolvers.splice(0)) {
+          resolvePending();
         }
-        pendingEvents.push(canonicalEvent);
       }
     }
   };
@@ -675,15 +710,17 @@ interface RunProtocolOptions {
   /**
    * Current recursion depth. Top-level runs use 0; the coordinator dispatch
    * loop increments before invoking {@link runProtocol} for a child run.
-   * Plan 04 will wire `effectiveMaxDepth` validation around this value.
+   * Depth validation is enforced before delegate dispatch.
    */
   readonly currentDepth?: number;
   /**
-   * Effective max recursion depth. Plan 04 enforces; Plan 03 plumbs the param.
+   * Effective max recursion depth after engine and per-run ceilings are merged.
    */
   readonly effectiveMaxDepth?: number;
   /** Effective max delegated child concurrency resolved at run start. */
   readonly effectiveMaxConcurrentChildren?: number;
+  /** Effective max agent-turn fan-out resolved at run start. */
+  readonly effectiveMaxConcurrentAgentTurns?: number;
   readonly onChildFailure?: EngineOptions["onChildFailure"];
   /**
    * Root-run deadline (epoch ms) threaded through every recursive coordinator
@@ -1363,6 +1400,9 @@ function runProtocolInner(
         ...(options.signal !== undefined ? { signal: options.signal } : {}),
         ...(options.terminate ? { terminate: options.terminate } : {}),
         ...(options.wrapUpHint ? { wrapUpHint: options.wrapUpHint } : {}),
+        ...(options.effectiveMaxConcurrentAgentTurns !== undefined
+          ? { maxConcurrentAgentTurns: options.effectiveMaxConcurrentAgentTurns }
+          : {}),
         ...(emitForProtocol ? { emit: emitForProtocol } : {})
       });
     case "coordinator":
@@ -1379,11 +1419,16 @@ function runProtocolInner(
         ...(options.signal !== undefined ? { signal: options.signal } : {}),
         ...(options.terminate ? { terminate: options.terminate } : {}),
         ...(options.wrapUpHint ? { wrapUpHint: options.wrapUpHint } : {}),
+        ...(options.effectiveMaxConcurrentAgentTurns !== undefined
+          ? { maxConcurrentAgentTurns: options.effectiveMaxConcurrentAgentTurns }
+          : {}),
         ...(emitForProtocol ? { emit: emitForProtocol } : {}),
         ...(options.streamEvents !== undefined ? { streamEvents: options.streamEvents } : {}),
         currentDepth: options.currentDepth ?? 0,
         effectiveMaxDepth: options.effectiveMaxDepth ?? Infinity,
         effectiveMaxConcurrentChildren: options.effectiveMaxConcurrentChildren ?? DEFAULT_MAX_CONCURRENT_CHILDREN,
+        effectiveMaxConcurrentAgentTurns:
+          options.effectiveMaxConcurrentAgentTurns ?? DEFAULT_MAX_CONCURRENT_AGENT_TURNS,
         onChildFailure: options.onChildFailure ?? "continue",
         ...(options.parentDeadlineMs !== undefined ? { parentDeadlineMs: options.parentDeadlineMs } : {}),
         ...(options.defaultSubRunTimeoutMs !== undefined
@@ -1419,6 +1464,9 @@ function runProtocolInner(
         ...(options.signal !== undefined ? { signal: options.signal } : {}),
         ...(options.terminate ? { terminate: options.terminate } : {}),
         ...(options.wrapUpHint ? { wrapUpHint: options.wrapUpHint } : {}),
+        ...(options.effectiveMaxConcurrentAgentTurns !== undefined
+          ? { maxConcurrentAgentTurns: options.effectiveMaxConcurrentAgentTurns }
+          : {}),
         ...(emitForProtocol ? { emit: emitForProtocol } : {})
       });
   }
@@ -1697,7 +1745,6 @@ function dogpileErrorFromSerializedPayload(input: {
 // Tracing/metrics-free: replayStream never uses EngineOptions tracer or metricsHook.
 export function replayStream(trace: Trace): StreamHandle {
   const result = Promise.resolve(replay(trace));
-  const replayEvents = replayStreamEvents(trace);
 
   return {
     get status(): StreamHandleStatus {
@@ -1708,7 +1755,7 @@ export function replayStream(trace: Trace): StreamHandle {
       // Replay streams are already completed snapshots, so cancellation is a no-op.
     },
     subscribe(subscriber: StreamEventSubscriber) {
-      for (const event of replayEvents) {
+      for (const event of replayStreamEvents(trace)) {
         subscriber(event);
       }
 
@@ -1719,34 +1766,24 @@ export function replayStream(trace: Trace): StreamHandle {
       };
     },
     [Symbol.asyncIterator](): AsyncIterator<StreamEvent> {
-      let index = 0;
+      const iterator = replayStreamEvents(trace)[Symbol.iterator]();
 
       return {
         next(): Promise<IteratorResult<StreamEvent>> {
-          const event = replayEvents[index];
-          if (event) {
-            index += 1;
-            return Promise.resolve({ done: false, value: event });
-          }
-
-          return Promise.resolve({ done: true, value: undefined });
+          return Promise.resolve(iterator.next());
         }
       };
     }
   };
 }
 
-function replayStreamEvents(trace: Trace, parentRunIds: readonly string[] = []): StreamEvent[] {
-  const events: StreamEvent[] = [];
-
+function* replayStreamEvents(trace: Trace, parentRunIds: readonly string[] = []): IterableIterator<StreamEvent> {
   for (const event of synthesizeProviderEvents(trace, trace.providerCalls)) {
     if (event.type === "sub-run-completed") {
-      events.push(...replayStreamEvents(event.subResult.trace, [...parentRunIds, trace.runId]));
+      yield* replayStreamEvents(event.subResult.trace, [...parentRunIds, trace.runId]);
     }
-    events.push(wrapReplayStreamEvent(event, parentRunIds));
+    yield wrapReplayStreamEvent(event, parentRunIds);
   }
-
-  return events;
 }
 
 function wrapReplayStreamEvent(event: RunEvent, parentRunIds: readonly string[]): StreamEvent {

package/src/runtime/model.ts

@@ -49,7 +49,8 @@ export async function generateModelTurn(options: GenerateModelTurnOptions): Prom
     return response;
   }
 
-  let text = "";
+  const chunks: string[] = [];
+  let outputLength = 0;
   let chunkIndex = 0;
   let usage: ModelUsage | undefined;
   let costUsd: number | undefined;
@@ -59,7 +60,8 @@ export async function generateModelTurn(options: GenerateModelTurnOptions): Prom
 
   for await (const chunk of options.model.stream(options.request)) {
     throwIfAborted(options.request.signal, options.model.id);
-    text += chunk.text;
+    chunks.push(chunk.text);
+    outputLength += chunk.text.length;
 
     options.emit({
       type: "model-output-chunk",
@@ -70,7 +72,7 @@ export async function generateModelTurn(options: GenerateModelTurnOptions): Prom
       input: options.input,
       chunkIndex,
       text: chunk.text,
-      output: text
+      outputLength
     });
     chunkIndex += 1;
 
@@ -91,6 +93,7 @@ export async function generateModelTurn(options: GenerateModelTurnOptions): Prom
     }
   }
 
+  const text = chunks.join("");
   response = {
     text,
     ...(finishReason !== undefined ? { finishReason } : {}),