@zvada/agent-server 0.3.5 → 0.3.7-attribution.1

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.3.7-attribution.1
+
+- Preserve per-turn harness, configured model and thinking level in lifecycle events, run summaries and the canonical conversation fold.
+- Keep primary model reports separate from requested aliases; collect Claude message models and Codex routing targets without attributing subagent models to the main run.
+- Execution metadata is an explicit allowlist and contains no credentials, environment variables or working-directory paths.
+
+## 0.3.7-replay.1
+
+- Add `AgentServerClient.onEventGap` for consumers using `startTurn` and `onEvent`.
+  Missing replay data and server restarts are reported before surviving events.
+  A gap describes incomplete delivery; native execution may still be running.
+- Track turns that disconnect before their first event and keep replay attempts
+  bound to the transport that started them. Preserve frames received during a
+  reconnect handshake even when they have already left the server's replay window.
+
+## 0.3.6
+
+- Unsupported Codex app-server requests now receive an explicit protocol error.
+  Previously, requests such as MCP elicitations were treated as file-edit
+  approvals and could leave a turn waiting in the permission broker. Command
+  and file approvals and host-managed credential refresh keep their existing behavior.
+
 ## 0.3.5
 
 - Switching Codex ChatGPT accounts or API keys now recreates the native process

package/docs/consuming.md

@@ -264,7 +264,19 @@ product that doesn't surface them debugs blind.
 and replays by default), `attach` (an accepted socket, e.g. the server dialed
 OUT to you via `--dial`). The client dedupes by per-session `seq` and heals
 gaps via `events/replay`; an unfillable gap raises `EventGapError` instead of
-silently losing events. The WebSocket wire itself carries no auth — keep it
+silently losing events. When using `startTurn` with `onEvent`, subscribe to
+`onEventGap` before starting work. It runs synchronously before any surviving
+suffix and returns an unsubscribe function. `runTurn().result` continues to
+reject on these same gaps.
+
+A gap describes incomplete delivery, not a successful stop. Keep the affected
+turn's output marked incomplete even if its native terminal says `end_turn`.
+`server_restarted` and `session_missing` mean the old terminal cannot arrive;
+`evicted`, `replay_failed`, and `log_reset` can require a turn-stamped
+`cancelTurn(sessionId, turnId)` to reconcile execution. Never cancel a successor
+by reading its ID after an asynchronous recovery operation.
+
+The WebSocket wire itself carries no auth — keep it
 on a trusted channel (localhost, sandbox-internal, or behind your own
 authenticated boundary).
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zvada/agent-server",
-	"version": "0.3.5",
+	"version": "0.3.7-attribution.1",
 	"description": "Harness-agnostic agent execution engine: run Claude Code, Codex (SDK/CLI + app-server), and any ACP agent behind one interface with a normalized event stream, multi-turn sessions, and resume. Root export is the wire contract; /core, /server, /client are the seats.",
 	"license": "MIT",
 	"type": "module",

package/src/client/client.ts

@@ -62,6 +62,13 @@ export class EventGapError extends Error {
 	override readonly name = "EventGapError";
 }
 
+/** A delivery failure, reported before surviving events. Execution may continue. */
+export interface SessionEventGap {
+	sessionId: string;
+	reason: "evicted" | "replay_failed" | "session_missing" | "server_restarted" | "log_reset";
+	error: EventGapError;
+}
+
 /**
  * A running turn: consume `events` (ends after `turn.ended`) or await `result`.
  *
@@ -145,11 +152,16 @@ export class AgentServerClient {
 	private readonly pending = new Map<JsonRpcId, PendingRequest>();
 	/** Per-session seq discipline — the shared `/protocol` implementation. */
 	private readonly cursor = createSeqCursor();
-	private readonly heldBack = new Map<string, DecodedWireEventEnvelope[]>();
+	private readonly heldBack = new Map<
+		string,
+		Array<{ envelope: DecodedWireEventEnvelope; transport: WireTransport | null }>
+	>();
 	/** The server process behind the transport, learned at `initialize`. */
 	private serverInstanceId: string | undefined;
-	private readonly syncing = new Set<string>();
+	private readonly syncing = new Map<string, WireTransport>();
 	private readonly eventHandlers = new Set<(envelope: DecodedWireEventEnvelope) => void>();
+	private readonly gapHandlers = new Set<(gap: SessionEventGap) => void>();
+	private awaitingHandshake = false;
 	private readonly turnBySession = new Map<string, InternalTurn>();
 	private initializePromise: Promise<InitializeResult> | null = null;
 	private closed = false;
@@ -266,16 +278,26 @@ export class AgentServerClient {
 		// log will ever emit THEIR turn.ended — an un-failed handle hangs forever
 		// (a session id the fresh process happens to reuse would even feed it
 		// someone else's events).
-		for (const sessionId of [...this.turnBySession.keys()]) {
-			this.failTurn(
+		const sessionIds = new Set([...this.cursor.sessions(), ...this.turnBySession.keys()]);
+		for (const sessionId of sessionIds) {
+			this.reportEventGap(
 				sessionId,
+				"server_restarted",
 				new EventGapError(
 					`server instance changed; the turn's session log died with the old process`,
 				),
 			);
 		}
 		for (const sessionId of this.cursor.sessions()) this.cursor.reset(sessionId);
-		this.heldBack.clear();
+		// Keep frames actually received from the fresh process: they may already
+		// have left its bounded replay window. Only old transport entries die.
+		for (const [sessionId, held] of this.heldBack) {
+			const fresh = held.filter((entry) => entry.transport === this.transport);
+			if (fresh.length) {
+				this.heldBack.set(sessionId, fresh);
+				this.cursor.seek(sessionId, 0);
+			} else this.heldBack.delete(sessionId);
+		}
 	}
 
 	/**
@@ -317,7 +339,14 @@ export class AgentServerClient {
 	/** Quick-ack only — observe the turn via `onEvent` / `replay`. */
 	async startTurn(params: TurnStartParams): Promise<{ sessionId: string; turnId: string }> {
 		await this.initialize();
-		return this.request(WIRE_METHODS.turnStart, params, TurnStartResultSchema);
+		const sessionId = params.sessionId ?? generateUUIDv7();
+		const turnId = params.turnId ?? generateUUIDv7();
+		this.cursor.seek(sessionId, this.cursor.last(sessionId));
+		return this.request(
+			WIRE_METHODS.turnStart,
+			{ ...params, sessionId, turnId },
+			TurnStartResultSchema,
+		);
 	}
 
 	/** Answer a `permission.requested` event. */
@@ -380,6 +409,12 @@ export class AgentServerClient {
 		return () => this.eventHandlers.delete(handler);
 	}
 
+	/** Observe unrecoverable delivery gaps even when using startTurn without a handle. */
+	onEventGap(handler: (gap: SessionEventGap) => void): () => void {
+		this.gapHandlers.add(handler);
+		return () => this.gapHandlers.delete(handler);
+	}
+
 	/** Ask the server to shut down, then close this client. */
 	async shutdownServer(): Promise<void> {
 		await this.request(WIRE_METHODS.shutdown, {}, ShutdownResultSchema).catch(() => undefined);
@@ -406,7 +441,10 @@ export class AgentServerClient {
 		}
 		if (transport.closed) throw new ConnectionClosedError("transport opened already closed");
 		this.transport = transport;
-		transport.onLine((line) => this.handleLine(line));
+		this.awaitingHandshake = this.reconnecting;
+		transport.onLine((line) => {
+			if (this.transport === transport) this.handleLine(line);
+		});
 		transport.onClose((reason) => this.handleTransportClose(transport, reason));
 	}
 
@@ -443,10 +481,15 @@ export class AgentServerClient {
 					this.initializePromise = null;
 					await this.initialize();
 					if (this.closed || !this.transport) continue;
+					this.awaitingHandshake = false;
 					// Heal every tracked session — including turns that saw no event
 					// before the drop (or none after it): without a resync they would
 					// never receive their turn.ended and would hang forever.
-					const sessionIds = new Set([...this.cursor.sessions(), ...this.turnBySession.keys()]);
+					const sessionIds = new Set([
+						...this.cursor.sessions(),
+						...this.turnBySession.keys(),
+						...this.heldBack.keys(),
+					]);
 					for (const sessionId of sessionIds) void this.syncSession(sessionId);
 					if (!this.transport) continue;
 					return;
@@ -500,7 +543,7 @@ export class AgentServerClient {
 		const sessionId = envelope.sessionId;
 		// While a replay is in flight, every envelope queues: the drain re-runs
 		// the cursor over the merged (replayed + live) backlog in seq order.
-		if (this.syncing.has(sessionId)) {
+		if (this.awaitingHandshake || this.syncing.get(sessionId) === this.transport) {
 			this.holdBack(sessionId, envelope);
 			return;
 		}
@@ -513,6 +556,11 @@ export class AgentServerClient {
 				// arm fires only if a fresh log appears with NO transport drop,
 				// which no current topology produces. If it does: the queue is
 				// dead-log state, the fresh frame is authoritative.
+				this.reportEventGap(
+					sessionId,
+					"log_reset",
+					new EventGapError(`session ${sessionId} log reset`),
+				);
 				this.heldBack.delete(sessionId);
 				this.deliver(envelope);
 				return;
@@ -529,16 +577,17 @@ export class AgentServerClient {
 
 	private holdBack(sessionId: string, envelope: DecodedWireEventEnvelope): void {
 		const held = this.heldBack.get(sessionId) ?? [];
-		held.push(envelope);
+		held.push({ envelope, transport: this.transport });
 		this.heldBack.set(sessionId, held);
 	}
 
 	private drainHeld(sessionId: string): void {
+		if (this.awaitingHandshake) return;
 		const held = this.heldBack.get(sessionId);
 		if (!held?.length) return;
-		held.sort((a, b) => a.seq - b.seq);
+		held.sort((a, b) => a.envelope.seq - b.envelope.seq);
 		while (held.length) {
-			const next = held[0] as DecodedWireEventEnvelope;
+			const next = held[0]!.envelope;
 			// `gap` leaves the cursor untouched, so breaking here is safe: the
 			// envelope stays queued for the replay that fills the hole.
 			const verdict = this.cursor.advance(sessionId, next.seq);
@@ -547,9 +596,15 @@ export class AgentServerClient {
 			if (verdict === "reset") {
 				// Defense-in-depth only (see the reset arm in handleEnvelope):
 				// drop the queue, deliver the fresh frame, resync for its tail.
+				this.reportEventGap(
+					sessionId,
+					"log_reset",
+					new EventGapError(`session ${sessionId} log reset`),
+				);
 				held.length = 0;
 				this.deliver(next);
-				void this.syncSession(sessionId);
+				// Let any replay owning this drain release its transport first.
+				queueMicrotask(() => void this.syncSession(sessionId));
 				break;
 			}
 			if (verdict !== "duplicate") this.deliver(next);
@@ -558,32 +613,48 @@ export class AgentServerClient {
 	}
 
 	private async syncSession(sessionId: string): Promise<void> {
-		if (this.syncing.has(sessionId) || this.closed || !this.transport) return;
-		this.syncing.add(sessionId);
+		const transport = this.transport;
+		if (
+			!transport ||
+			this.awaitingHandshake ||
+			this.closed ||
+			this.syncing.get(sessionId) === transport
+		)
+			return;
+		this.syncing.set(sessionId, transport);
+		const isCurrent = () => !this.closed && !this.awaitingHandshake && this.transport === transport;
 		try {
 			const maxAttempts = Math.max(1, this.options.maxReplayAttempts ?? 3);
 			const retryDelay = this.options.replayRetryDelayMs ?? this.options.reconnectDelayMs ?? 250;
-			for (let attempt = 1; attempt <= maxAttempts && !this.closed && this.transport; attempt++) {
+			for (let attempt = 1; attempt <= maxAttempts && isCurrent(); attempt++) {
+				this.drainHeld(sessionId);
+				if (!isCurrent()) return;
 				const fromSeq = this.cursor.last(sessionId) + 1;
 				try {
 					const replayed = await this.replay(sessionId, fromSeq);
-					if (replayed.firstAvailableSeq !== null && replayed.firstAvailableSeq > fromSeq) {
+					if (!isCurrent()) return;
+					for (const envelope of replayed.events) this.holdBack(sessionId, envelope);
+					this.drainHeld(sessionId);
+					const missingFrom = this.cursor.last(sessionId) + 1;
+					if (replayed.firstAvailableSeq !== null && replayed.firstAvailableSeq > missingFrom) {
 						// The prefix was evicted — the gap is unfillable. Fail the turn
 						// handle (its part reconstruction is broken) and jump forward.
-						this.failTurn(
+						this.reportEventGap(
 							sessionId,
+							"evicted",
 							new EventGapError(
-								`events ${fromSeq}..${replayed.firstAvailableSeq - 1} for session ${sessionId} were evicted`,
+								`events ${missingFrom}..${replayed.firstAvailableSeq - 1} for session ${sessionId} were evicted`,
 							),
 						);
 						this.cursor.seek(sessionId, replayed.firstAvailableSeq - 1);
 					}
-					for (const envelope of replayed.events) this.holdBack(sessionId, envelope);
 					break;
 				} catch (err) {
+					if (!isCurrent()) return;
 					if (err instanceof WireRequestError && err.code === WIRE_ERROR_CODES.unknownSession) {
-						this.failTurn(
+						this.reportEventGap(
 							sessionId,
+							"session_missing",
 							new EventGapError(`session ${sessionId} is unknown to the server (restarted?)`),
 						);
 						this.cursor.reset(sessionId);
@@ -592,8 +663,9 @@ export class AgentServerClient {
 					}
 					if (!this.transport || this.closed) break; // reconnect performs a fresh resync
 					if (attempt === maxAttempts) {
-						this.failTurn(
+						this.reportEventGap(
 							sessionId,
+							"replay_failed",
 							new EventGapError(
 								`failed to replay events from ${fromSeq} for session ${sessionId} after ${maxAttempts} attempts`,
 							),
@@ -605,9 +677,9 @@ export class AgentServerClient {
 				}
 			}
 		} finally {
-			this.syncing.delete(sessionId);
+			if (this.syncing.get(sessionId) === transport) this.syncing.delete(sessionId);
 		}
-		this.drainHeld(sessionId);
+		if (isCurrent()) this.drainHeld(sessionId);
 	}
 
 	/** Dispatch an envelope the cursor already accepted (it owns the watermark). */
@@ -630,6 +702,21 @@ export class AgentServerClient {
 		}
 	}
 
+	private reportEventGap(
+		sessionId: string,
+		reason: SessionEventGap["reason"],
+		error: EventGapError,
+	): void {
+		this.failTurn(sessionId, error);
+		for (const handler of [...this.gapHandlers]) {
+			try {
+				handler({ sessionId, reason, error });
+			} catch {
+				// A consumer callback cannot interrupt replay or other subscribers.
+			}
+		}
+	}
+
 	private failTurn(sessionId: string, error: Error): void {
 		const turn = this.turnBySession.get(sessionId);
 		if (!turn) return;

package/src/client/index.ts

@@ -6,6 +6,7 @@ export {
 	type AgentServerClientOptions,
 	ConnectionClosedError,
 	EventGapError,
+	type SessionEventGap,
 	type TurnHandle,
 	WireRequestError,
 } from "./client.ts";

package/src/core/agents/claude-code/adapter.ts

@@ -79,7 +79,7 @@ type ClaudeMessage =
 	| { type: "turn_interrupted" }
 	| {
 			type: "assistant";
-			message?: { content?: ContentBlock[]; usage?: RawUsage };
+			message?: { content?: ContentBlock[]; usage?: RawUsage; model?: string };
 			parent_tool_use_id?: string | null;
 	  }
 	| { type: "user"; message?: { content?: ContentBlock[] | string } }
@@ -227,6 +227,7 @@ export class ClaudeCodeTransformer implements EventTransformer<unknown> {
 	private hasStreamed = false;
 
 	private usage: TokenUsage = { ...DEFAULT_TOKEN_USAGE };
+	private readonly reportedModels = new Set<string>();
 	private stopReason?: StopReason;
 	private finishReason?: string;
 	private cost?: number;
@@ -287,6 +288,7 @@ export class ClaudeCodeTransformer implements EventTransformer<unknown> {
 				: undefined);
 		return {
 			usage: this.usage,
+			...(this.reportedModels.size && { reportedModels: [...this.reportedModels] }),
 			stopReason: this.stopReason,
 			finishReason: this.finishReason,
 			cost: this.cost,
@@ -308,6 +310,7 @@ export class ClaudeCodeTransformer implements EventTransformer<unknown> {
 	 * skip the duplicate. Otherwise emit its content blocks as finalized parts.
 	 */
 	private handleAssistant(msg: Extract<ClaudeMessage, { type: "assistant" }>): AdapterEvent[] {
+		if (!msg.parent_tool_use_id && msg.message?.model) this.reportedModels.add(msg.message.model);
 		// Context gauge: every top-level model message carries fresh usage (the
 		// sub-agent's context is its own and would misreport the session's).
 		const gauge: AdapterEvent[] =

package/src/core/agents/codex-app-server/adapter.ts

@@ -47,6 +47,7 @@ interface Notification {
 		error?: { message?: string; additionalDetails?: string | null };
 		willRetry?: boolean;
 		message?: string;
+		toModel?: string;
 	};
 }
 
@@ -55,6 +56,7 @@ export class CodexAppServerTransformer implements EventTransformer<unknown> {
 	private readonly partByItem = new Map<string, Part>();
 
 	private usage: TokenUsage = { ...DEFAULT_TOKEN_USAGE };
+	private readonly reportedModels = new Set<string>();
 	private stopReason?: StopReason;
 	private finishReason?: string;
 	private error?: string;
@@ -66,6 +68,9 @@ export class CodexAppServerTransformer implements EventTransformer<unknown> {
 	process(raw: unknown): AdapterEvent[] {
 		const { method, params } = raw as Notification;
 		switch (method) {
+			case "model/rerouted":
+				if (params.toModel) this.reportedModels.add(params.toModel);
+				return [];
 			case "item/started":
 				return params.item ? this.openItem(params.item) : [];
 			case "item/completed":
@@ -105,6 +110,7 @@ export class CodexAppServerTransformer implements EventTransformer<unknown> {
 	finish(): TransformResult {
 		return {
 			usage: this.usage,
+			...(this.reportedModels.size && { reportedModels: [...this.reportedModels] }),
 			stopReason: this.stopReason,
 			finishReason: this.finishReason,
 			error: this.error,

package/src/core/agents/codex-app-server/codex-app-server-agent.ts

@@ -395,6 +395,16 @@ export class CodexAppServerAgent extends BaseAgent {
 					chatgptPlanType: tokens.chatgptPlanType ?? null,
 				};
 			}
+			// Elicitations and other server requests have their own response shapes.
+			// Sending them to the approval broker can leave a turn waiting forever.
+			if (
+				method !== "item/commandExecution/requestApproval" &&
+				method !== "item/fileChange/requestApproval" &&
+				method !== "execCommandApproval" &&
+				method !== "applyPatchApproval"
+			) {
+				throw new Error(`Unsupported Codex server request: ${method}`);
+			}
 			const requestThread = params.threadId ?? params.conversationId;
 			const v2 = method.startsWith("item/");
 			const decline = v2 ? { decision: "decline" } : { decision: "denied" };

package/src/core/agents/types.ts

@@ -32,6 +32,8 @@ export type AdapterEvent =
 /** Terminal result of a turn, surfaced on `turn.ended`. */
 export interface TransformResult {
 	usage: TokenUsage;
+	/** Models observed on the primary run, excluding subagents and configured defaults. */
+	reportedModels?: string[];
 	/** Normalized terminal status, when the harness reported one. The engine
 	 * overrides with `cancelled`/`error` based on what it observed. */
 	stopReason?: StopReason;

package/src/core/runtime/agent-runtime.ts

@@ -14,6 +14,7 @@ import type {
 	RunRequest,
 	StopReason,
 	TokenUsage,
+	TurnExecution,
 } from "../../protocol/index.ts";
 import { DEFAULT_TOKEN_USAGE, generateUUIDv7 } from "../../protocol/index.ts";
 import type { AgentExecuteOptions, CancelResult, PermissionDecision } from "../agents/base.ts";
@@ -28,6 +29,7 @@ export interface RunSummary {
 	sessionId: string;
 	turnId: string;
 	harness: AgentHarness;
+	execution: TurnExecution;
 	/** Native session/thread id to persist for a future resume. */
 	nativeSessionId?: string;
 	/** When the turn requested a resume: whether the harness honored it. */
@@ -239,7 +241,12 @@ export class AgentRuntime {
 		const { sessionId, turnId, input, config } = request;
 		const agent = this.registry.getAgent(config.harness);
 		const transformer = this.registry.getAdapter(config.harness)({ sessionId });
-		const processor = new EventProcessor(sessionId, turnId, { model: config.model });
+		const execution: TurnExecution = {
+			harness: config.harness,
+			...(config.model !== undefined && { model: config.model }),
+			...(config.thinkingLevel !== undefined && { thinkingLevel: config.thinkingLevel }),
+		};
+		const processor = new EventProcessor(sessionId, turnId, execution);
 
 		// Isolate sink failures: a misbehaving transport must never break the
 		// turn's lifecycle bracketing (turn.started ... turn.ended).
@@ -374,7 +381,7 @@ export class AgentRuntime {
 			await Promise.all([...settles, ...settleEmits]);
 		};
 
-		await emit({ type: "turn.started", turnId, sessionId, timestamp: Date.now() });
+		await emit({ type: "turn.started", turnId, sessionId, execution, timestamp: Date.now() });
 
 		// The user echo (spec §7.2): the submitted input goes back onto the stream
 		// as a complete user message (outputIndex 0) before any harness output, so
@@ -474,6 +481,10 @@ export class AgentRuntime {
 			nativeSessionId,
 			...(resumed !== undefined && { resumed }),
 			usage: result.usage ?? DEFAULT_TOKEN_USAGE,
+			execution: {
+				...execution,
+				...(result.reportedModels && { reportedModels: result.reportedModels }),
+			},
 			stopReason,
 			finishReason: result.finishReason,
 			cost: result.cost,

package/src/core/runtime/event-processor.ts

@@ -4,7 +4,14 @@ import {
 	echoMessageId,
 	generateUUIDv7,
 } from "../../protocol/index.ts";
-import type { AgentInput, Delta, LifecycleEvent, Part, StopReason } from "../../protocol/index.ts";
+import type {
+	AgentInput,
+	Delta,
+	LifecycleEvent,
+	Part,
+	StopReason,
+	TurnExecution,
+} from "../../protocol/index.ts";
 import type { AdapterEvent, TransformResult } from "../agents/types.ts";
 
 /** Where a part lives on the wire — fixed at first emission for the whole turn. */
@@ -36,7 +43,7 @@ export class EventProcessor {
 	constructor(
 		private readonly sessionId: string,
 		private readonly turnId: string,
-		private readonly meta: { model?: string } = {},
+		private readonly execution?: TurnExecution,
 	) {}
 
 	/**
@@ -125,6 +132,12 @@ export class EventProcessor {
 			finishReason: result.finishReason,
 			tokens: result.usage,
 			cost: result.cost,
+			...(this.execution && {
+				execution: {
+					...this.execution,
+					...(result.reportedModels && { reportedModels: result.reportedModels }),
+				},
+			}),
 			error:
 				result.error && !result.cancelled
 					? { category: classifyError(result.error), message: result.error }
@@ -160,7 +173,7 @@ export class EventProcessor {
 			// user-authored. Gating here keeps it off every user message; every
 			// assistant message (top-level AND parented sub-agent output) keeps it,
 			// since `config.model` is the only per-turn model signal available.
-			...(role === "assistant" && this.meta.model && { model: this.meta.model }),
+			...(role === "assistant" && this.execution?.model && { model: this.execution?.model }),
 			timestamp: Date.now(),
 		};
 	}

package/src/protocol/execution.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import { AgentHarnessSchema } from "./harness.ts";
+import { ThinkingLevelSchema } from "./thinking.ts";
+
+/** Safe, per-turn execution metadata. Never serialize the full RunConfig here. */
+export const TurnExecutionSchema = z.object({
+	harness: AgentHarnessSchema,
+	/** Model id/alias passed to the harness. Absent means the harness chose its default. */
+	model: z.string().optional(),
+	/** Requested setting, not a measurement of the model's internal reasoning. */
+	thinkingLevel: ThinkingLevelSchema.optional(),
+	/** Distinct models reported by the primary harness during this turn, in observation order.
+	 * Excludes subagents. Absence means unreported, never a fallback to the requested alias. */
+	reportedModels: z.array(z.string()).optional(),
+});
+export type TurnExecution = z.infer<typeof TurnExecutionSchema>;

package/src/protocol/index.ts

@@ -17,6 +17,7 @@ export * from "./harness.ts";
 export * from "./thinking.ts";
 export * from "./models.ts";
 export * from "./config.ts";
+export * from "./execution.ts";
 export * from "./lifecycle.ts";
 export * from "./stop-reasons.ts";
 export * from "./seq-cursor.ts";

package/src/protocol/lifecycle.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { ErrorCategorySchema, ErrorInfoSchema } from "./errors.ts";
+import { TurnExecutionSchema } from "./execution.ts";
 import { isKnownLifecycleEventType } from "./guards.ts";
 import { AgentHarnessSchema } from "./harness.ts";
 import { MetaSchema } from "./meta.ts";
@@ -168,6 +169,7 @@ export const TurnStartedEventSchema = z.object({
 	type: z.literal("turn.started"),
 	sessionId: z.string(),
 	turnId: z.string(),
+	execution: TurnExecutionSchema.optional(),
 	timestamp: EpochMsSchema,
 	_meta: MetaSchema,
 });
@@ -177,6 +179,7 @@ export const TurnEndedEventSchema = z.object({
 	type: z.literal("turn.ended"),
 	sessionId: z.string(),
 	turnId: z.string(),
+	execution: TurnExecutionSchema.optional(),
 	/** Normalized terminal status — `cancelled` and `error` are first-class. */
 	stopReason: StopReasonSchema,
 	/** Raw provider finish string (`end_turn`, `completed`, …), always preserved when reported. */

package/src/protocol/reduce.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 // The package ships raw .ts — keep imports exactly-used, or every consumer
 // compiling with noUnusedLocals inherits the noise as build errors.
 import { ErrorCategorySchema, ErrorInfoSchema } from "./errors.ts";
+import { TurnExecutionSchema } from "./execution.ts";
 import { isUnknownEvent } from "./guards.ts";
 import { AgentHarnessSchema } from "./harness.ts";
 import {
@@ -115,6 +116,7 @@ export type TimelineEntry = z.infer<typeof TimelineEntrySchema>;
 
 export const ConversationTurnSchema = z.object({
 	turnId: z.string(),
+	execution: TurnExecutionSchema.optional(),
 	/** Derived view state, not wire vocabulary. */
 	status: z.enum(["active", "ended"]),
 	stopReason: StopReasonSchema.optional(),
@@ -496,6 +498,7 @@ function reduceWith(
 			if (existing !== -1) return state; // replay overlap — the turn is known
 			const turn: ConversationTurn = {
 				turnId: event.turnId,
+				...(event.execution !== undefined && { execution: event.execution }),
 				status: "active",
 				errors: [],
 				startedAt: event.timestamp,
@@ -603,6 +606,7 @@ function reduceWith(
 				...base,
 				status: "ended",
 				stopReason: event.stopReason,
+				...(event.execution !== undefined && { execution: event.execution }),
 				...(event.finishReason !== undefined && { finishReason: event.finishReason }),
 				...(event.tokens !== undefined && { tokens: event.tokens }),
 				...(event.cost !== undefined && { cost: event.cost }),