@zvada/agent-server 0.2.2 → 0.3.0

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

@@ -3,9 +3,11 @@ import {
 	type ReasoningPart,
 	type StopReason,
 	type StreamContext,
+	type SubagentMetadata,
 	type TextPart,
 	type TokenUsage,
 	type ToolPart,
+	type ToolResultContent,
 	appendToolInput,
 	completeToolPart,
 	createPendingToolPart,
@@ -41,6 +43,8 @@ interface StreamEvent {
 		type?: string;
 		text?: string;
 		thinking?: string;
+		/** Withheld-thinking placeholder: running size of a thought whose text never streams. */
+		estimated_tokens?: number;
 		partial_json?: string;
 		stop_reason?: string;
 	};
@@ -150,6 +154,61 @@ function stringifyToolResult(content: unknown): string {
 	return JSON.stringify(content);
 }
 
+/**
+ * The display-grade view of a tool_result's content blocks (spec §3.4): the
+ * flattened string stays the model-facing record, this preserves what
+ * flattening drops — images especially, which contribute "" to the string.
+ * Block shapes we can't express are skipped, never guessed.
+ */
+function toolResultContent(content: unknown): ToolResultContent[] | undefined {
+	if (!Array.isArray(content)) return undefined;
+	const out: ToolResultContent[] = [];
+	for (const raw of content) {
+		if (!raw || typeof raw !== "object") continue;
+		const block = raw as {
+			type?: unknown;
+			text?: unknown;
+			source?: { data?: unknown; media_type?: unknown } | null;
+		};
+		if (block.type === "text" && typeof block.text === "string") {
+			out.push({ type: "text", text: block.text });
+			continue;
+		}
+		if (block.type === "image") {
+			const { data, media_type } = block.source ?? {};
+			// Only the base64 source form is expressible — ToolResultContent has no url variant.
+			if (typeof data === "string" && typeof media_type === "string") {
+				out.push({ type: "image", data, mimeType: media_type });
+			}
+		}
+	}
+	return out.length ? out : undefined;
+}
+
+/**
+ * SubagentMetadata from a spawning tool's input, shared by the streamed and
+ * non-streaming paths. `subagent_type` in the input identifies a spawn on any
+ * tool name; `Task` is Claude's own spawn tool and counts even before its
+ * input parses into anything useful (presence of `subagent` is what promotes
+ * the part to `kind: "task"` — see protocol §3.5).
+ */
+function subagentFromInput(
+	toolName: string,
+	input: Record<string, unknown>,
+): SubagentMetadata | undefined {
+	const str = (key: string): string | undefined =>
+		typeof input[key] === "string" ? (input[key] as string) : undefined;
+	const type = str("subagent_type");
+	if (type === undefined && toolName !== "Task") return undefined;
+	const description = str("description");
+	const model = str("model");
+	return {
+		...(type !== undefined && { type }),
+		...(description !== undefined && { description }),
+		...(model !== undefined && { model }),
+	};
+}
+
 export class ClaudeCodeTransformer implements EventTransformer<unknown> {
 	private readonly ctx: StreamContext;
 	/** Anthropic content blocks of the in-flight message, by stream index. */
@@ -237,7 +296,10 @@ export class ClaudeCodeTransformer implements EventTransformer<unknown> {
 	}
 
 	private ctxFor(): StreamContext {
-		return { ...this.ctx, ...(this.currentParent ? { parentToolUseId: this.currentParent } : {}) };
+		// `parentToolCallId` is the protocol spelling; Claude's own wire field is
+		// `parent_tool_use_id`. Spelling this the provider's way silently dropped
+		// every subagent linkage (a conditional spread dodges excess-property checks).
+		return { ...this.ctx, ...(this.currentParent ? { parentToolCallId: this.currentParent } : {}) };
 	}
 
 	/**
@@ -264,24 +326,25 @@ export class ClaudeCodeTransformer implements EventTransformer<unknown> {
 		for (const block of content) {
 			if (block.type === "text" && block.text) {
 				events.push({ kind: "part-open", part: createTextPart(this.ctxFor(), block.text, false) });
-			} else if (
-				(block.type === "thinking" || block.type === "redacted_thinking") &&
-				block.thinking
-			) {
-				events.push({
-					kind: "part-open",
-					part: createReasoningPart(this.ctxFor(), block.thinking, false),
-				});
+			} else if (block.type === "thinking" || block.type === "redacted_thinking") {
+				const redacted = block.type === "redacted_thinking";
+				// A redacted block carries no plaintext (its `data` is an encrypted
+				// blob), so emit it on the flag alone — the redaction is the signal.
+				if (!block.thinking && !redacted) continue;
+				// A complete block opens and closes at once: one stamp for both ends.
+				const now = Date.now();
+				const part = createReasoningPart(this.ctxFor(), block.thinking ?? "", false);
+				part.time = { start: now, end: now };
+				if (redacted) part.providerMetadata = { redacted: true };
+				events.push({ kind: "part-open", part });
 			} else if (block.type === "tool_use" && block.id) {
 				const name = block.name ?? "tool";
 				const input = block.input ?? {};
-				const part = createToolPart(
-					this.ctxFor(),
-					block.id,
-					name,
-					input,
-					claudeToolMeta(name, input),
-				);
+				const subagent = subagentFromInput(name, input);
+				const part = createToolPart(this.ctxFor(), block.id, name, input, {
+					...claudeToolMeta(name, input),
+					...(subagent && { subagent }),
+				});
 				this.toolPartsById.set(block.id, part);
 				events.push({ kind: "part-open", part });
 			}
@@ -290,17 +353,17 @@ export class ClaudeCodeTransformer implements EventTransformer<unknown> {
 		return [...gauge, ...events];
 	}
 
-	private handleStream(event: StreamEvent, parentToolUseId?: string): AdapterEvent[] {
+	private handleStream(event: StreamEvent, parentToolCallId?: string): AdapterEvent[] {
 		// Sticky for the whole turn: any stream event means the trailing complete
 		// `assistant` snapshot is a duplicate of what we streamed.
 		this.hasStreamed = true;
 		switch (event.type) {
 			case "message_start":
 				this.blocks.clear();
-				this.currentParent = parentToolUseId;
+				this.currentParent = parentToolCallId;
 				// Each top-level model message becomes a wire message. Sub-agent
-				// messages don't open one — their parts nest via parentToolUseId.
-				return parentToolUseId ? [] : [{ kind: "message-start", role: "assistant" }];
+				// messages don't open one — their parts nest via parentToolCallId.
+				return parentToolCallId ? [] : [{ kind: "message-start", role: "assistant" }];
 			case "content_block_start":
 				return this.openBlock(event);
 			case "content_block_delta":
@@ -313,7 +376,7 @@ export class ClaudeCodeTransformer implements EventTransformer<unknown> {
 				if (event.usage?.output_tokens) this.usage.output = event.usage.output_tokens;
 				return [];
 			case "message_stop":
-				return parentToolUseId || this.currentParent ? [] : [{ kind: "message-end" }];
+				return parentToolCallId || this.currentParent ? [] : [{ kind: "message-end" }];
 			default:
 				return [];
 		}
@@ -330,6 +393,11 @@ export class ClaudeCodeTransformer implements EventTransformer<unknown> {
 		}
 		if (cb.type === "thinking" || cb.type === "redacted_thinking") {
 			const part = createReasoningPart(this.ctxFor(), "", true);
+			// Thought duration starts here; content_block_stop closes it.
+			part.time = { start: Date.now() };
+			// The plaintext never arrives for a redacted block — keep the flag so a
+			// consumer can render "[redacted]" instead of an empty thought.
+			if (cb.type === "redacted_thinking") part.providerMetadata = { redacted: true };
 			this.blocks.set(index, { partId: part.id, kind: "reasoning", part });
 			return [{ kind: "part-open", part }];
 		}
@@ -351,8 +419,18 @@ export class ClaudeCodeTransformer implements EventTransformer<unknown> {
 			(entry.part as TextPart).text += d.text;
 			return [{ kind: "text-delta", partId: entry.partId, text: d.text }];
 		}
-		if (d.type === "thinking_delta" && entry.kind === "reasoning" && d.thinking) {
-			(entry.part as ReasoningPart).text += d.thinking;
+		if (d.type === "thinking_delta" && entry.kind === "reasoning") {
+			const reasoning = entry.part as ReasoningPart;
+			// Withheld thinking streams placeholder deltas: a token estimate, no
+			// text. Keep the estimate so a text-less thought still has a size.
+			if (typeof d.estimated_tokens === "number") {
+				reasoning.providerMetadata = {
+					...reasoning.providerMetadata,
+					estimatedThinkingTokens: d.estimated_tokens,
+				};
+			}
+			if (!d.thinking) return [];
+			reasoning.text += d.thinking;
 			return [{ kind: "reasoning-delta", partId: entry.partId, text: d.thinking }];
 		}
 		if (d.type === "input_json_delta" && entry.kind === "tool" && d.partial_json) {
@@ -375,15 +453,25 @@ export class ClaudeCodeTransformer implements EventTransformer<unknown> {
 		const entry = this.blocks.get(event.index ?? 0);
 		if (!entry) return [];
 		if (entry.kind === "text" || entry.kind === "reasoning") {
-			(entry.part as TextPart | ReasoningPart).state = "done";
-			return [{ kind: "part-update", part: entry.part }];
+			const part = entry.part as TextPart | ReasoningPart;
+			part.state = "done";
+			if (entry.kind === "reasoning") {
+				const reasoning = part as ReasoningPart;
+				reasoning.time = { start: reasoning.time?.start ?? Date.now(), end: Date.now() };
+			}
+			return [{ kind: "part-update", part }];
 		}
 		const tool = entry.part as ToolPart;
 		const partial = tool.state.status === "pending" ? tool.state.partialInput : "";
 		const input = safeParseJson(partial);
 		startToolPart(tool, input);
+		// The streamed open carried no input, so subagent metadata can only be
+		// read now that the partial JSON has parsed.
 		const locations = toolLocationsFromInput(input);
-		if (locations) setToolMeta(tool, { locations });
+		const subagent = subagentFromInput(tool.toolName, input);
+		if (locations || subagent) {
+			setToolMeta(tool, { ...(locations && { locations }), ...(subagent && { subagent }) });
+		}
 		return [{ kind: "part-update", part: tool }];
 	}
 
@@ -394,9 +482,11 @@ export class ClaudeCodeTransformer implements EventTransformer<unknown> {
 			if (block.type !== "tool_result" || !block.tool_use_id) continue;
 			const tool = this.toolPartsById.get(block.tool_use_id);
 			if (!tool) continue;
+			const content = toolResultContent(block.content);
 			completeToolPart(tool, {
 				output: stringifyToolResult(block.content),
 				isError: block.is_error === true,
+				...(content && { content }),
 			});
 			events.push({ kind: "part-update", part: tool });
 		}

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

@@ -1,10 +1,12 @@
 import type { SDKMessage, SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
 import type { McpSetServersResult } from "@anthropic-ai/claude-agent-sdk";
 import type { AgentCapabilities, AgentInput, McpServerConfig } from "../../../protocol/index.ts";
+import { type DiagnosticHandler, emitDiagnostic } from "../../diagnostics.ts";
 import type { AgentExecuteOptions, CancelResult, RawAgentEvent } from "../base.ts";
 import { BaseAgent } from "../base.ts";
 import type {
 	ClaudeHooksFactory,
+	ClaudeSessionEndReason,
 	ClaudeSessionExtras,
 	ClaudeToolPolicy,
 } from "./generator-session.ts";
@@ -30,13 +32,13 @@ function toClaudeContent(input: AgentInput): ClaudeContent {
 		if (part.type === "text") return { type: "text", text: part.text };
 		const source = part.url
 			? { type: "url", url: part.url }
-			: { type: "base64", media_type: part.mediaType, data: part.data ?? "" };
+			: { type: "base64", media_type: part.mimeType, data: part.data ?? "" };
 		// `file` inputs (PDFs etc.) are document blocks, not images.
 		return { type: part.type === "file" ? "document" : "image", source };
 	});
 	// Kept cast: the SDK's block sources require literal media_type unions
 	// ("image/jpeg" | ... and "application/pdf") while our PartInput carries an
-	// open string mediaType, so these blocks cannot satisfy the union as typed.
+	// open string mimeType, so these blocks cannot satisfy the union as typed.
 	return blocks as unknown as ClaudeContent;
 }
 
@@ -96,6 +98,18 @@ export interface ClaudeCodeAgentOptions {
 	toolPolicy?: ClaudeToolPolicy;
 	/** SDK lifecycle hooks factory (decision-capable). Operator embed-tier only. */
 	hooks?: ClaudeHooksFactory;
+	/**
+	 * Called exactly once when a live session's subprocess ends, with why:
+	 * `idle` (idle-timeout eviction), `replaced` (config change forced a
+	 * restart), `released` (explicit release/close), `shutdown`
+	 * (terminateAll). The seam for host-managed per-session resources — BYOK
+	 * proxy keys, recorders — instead of re-deriving termination from side
+	 * effects. NOTE: `replaced` sessions usually respawn immediately with
+	 * context preserved; drop only resources bound to the dead subprocess.
+	 */
+	onSessionEnd?: (sessionId: string, reason: ClaudeSessionEndReason) => void;
+	/** Operational diagnostics (interrupt timeouts, resume fallbacks). */
+	onDiagnostic?: DiagnosticHandler;
 	/**
 	 * Raw SDK option overrides merged over the engine's options at session
 	 * spawn (embedder escape hatch for SDK surface the engine does not model:
@@ -113,10 +127,11 @@ export interface ClaudeCodeAgentOptions {
 export class ClaudeCodeAgent extends BaseAgent {
 	readonly harness = "claude-code" as const;
 	readonly capabilities = CAPABILITIES;
-	private readonly manager = new ClaudeSessionManager();
+	private readonly manager: ClaudeSessionManager;
 
 	constructor(private readonly agentOptions: ClaudeCodeAgentOptions = {}) {
 		super();
+		this.manager = new ClaudeSessionManager(agentOptions.onSessionEnd);
 	}
 
 	private sessionExtras(): ClaudeSessionExtras {
@@ -193,6 +208,12 @@ export class ClaudeCodeAgent extends BaseAgent {
 				}
 
 				if (!resumeFailed) break;
+				emitDiagnostic(this.agentOptions.onDiagnostic, {
+					type: "resumeFallback",
+					sessionId: options.sessionId,
+					message: `resume of ${options.resumeSessionId} failed; re-running on a fresh session`,
+					detail: { resumeSessionId: options.resumeSessionId },
+				});
 				await this.manager.terminate(options.sessionId);
 			}
 
@@ -229,6 +250,13 @@ export class ClaudeCodeAgent extends BaseAgent {
 		const base = await super.cancel(sessionId);
 		if (!session || !base.hadTurn) return base;
 		const interrupted = await session.interruptTurn();
+		if (!interrupted) {
+			emitDiagnostic(this.agentOptions.onDiagnostic, {
+				type: "interruptTimeout",
+				sessionId,
+				message: "cancel dispatched but the SDK interrupt was not acknowledged in time",
+			});
+		}
 		return { confirmed: interrupted, hadTurn: true };
 	}
 

package/src/core/agents/claude-code/generator-session.ts

@@ -49,6 +49,9 @@ export type ClaudeHooksFactory = (ctx: {
 }) => CCOptions["hooks"];
 
 /** Embed-tier extras threaded from ClaudeCodeAgentOptions into each session. */
+/** Why a live claude session's subprocess ended (see `onSessionEnd`). */
+export type ClaudeSessionEndReason = "idle" | "replaced" | "released" | "shutdown";
+
 export interface ClaudeSessionExtras {
 	/** Factory for in-process MCP servers; invoked ONCE at session spawn. */
 	sdkMcpServers?: (ctx: {
@@ -115,7 +118,7 @@ export class ClaudeGeneratorSession {
 	constructor(
 		readonly id: string,
 		config: ClaudeSessionConfig,
-		private readonly onTerminated?: () => void,
+		private readonly onTerminated?: (reason: ClaudeSessionEndReason) => void,
 		private readonly extras?: ClaudeSessionExtras,
 	) {
 		this.config = { ...config };
@@ -250,7 +253,7 @@ export class ClaudeGeneratorSession {
 		}
 	}
 
-	async terminate(): Promise<void> {
+	async terminate(reason: ClaudeSessionEndReason = "released"): Promise<void> {
 		if (this.state === "terminated") return;
 		this.clearIdleTimer();
 		this.state = "terminated";
@@ -265,7 +268,12 @@ export class ClaudeGeneratorSession {
 			// The SDK documents close() as the forceful subprocess/MCP cleanup path.
 			query?.close();
 		} finally {
-			this.onTerminated?.();
+			try {
+				this.onTerminated?.(reason);
+			} catch {
+				// Observer failures (incl. the host's onSessionEnd) must never make
+				// terminate() reject — the idle timer calls it unawaited.
+			}
 		}
 	}
 
@@ -314,7 +322,7 @@ export class ClaudeGeneratorSession {
 	private resetIdleTimer(): void {
 		this.clearIdleTimer();
 		if (this.idleTimeoutMs > 0) {
-			this.idleTimer = setTimeout(() => void this.terminate(), this.idleTimeoutMs);
+			this.idleTimer = setTimeout(() => void this.terminate("idle"), this.idleTimeoutMs);
 			this.idleTimer.unref?.();
 		}
 	}
@@ -362,7 +370,10 @@ export function createCanUseTool(deps: {
 			{ signal },
 		);
 		return decision.decision === "allow"
-			? { behavior: "allow", updatedInput: input }
+			? // What was approved is what runs: an edited input from the broker
+				// replaces the original (C1 — silent divergence between the approved
+				// and executed input is the worst failure mode in an approval path).
+				{ behavior: "allow", updatedInput: decision.updatedInput ?? input }
 			: {
 					behavior: "deny",
 					message: (decision.decision === "deny" && decision.reason) || "Denied by user",

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

@@ -68,13 +68,13 @@ export interface ClaudeSessionConfig {
  */
 function toSdkPermissionMode(mode: PermissionMode | undefined): CCOptions["permissionMode"] {
 	switch (mode) {
-		case "bypassPermissions":
+		case "bypass_permissions":
 			return "bypassPermissions";
 		case "plan":
 			return "plan";
-		case "acceptEdits":
+		case "accept_edits":
 			return "acceptEdits";
-		case "dontAsk":
+		case "dont_ask":
 			// Native SDK mode: never prompt, deny unapproved. Unlike
 			// bypassPermissions it needs no dangerous flag (and the CLI keeps
 			// extended thinking enabled, which bypass turns off).
@@ -157,5 +157,15 @@ export function buildClaudeOptions(
 	// ClaudeSdkOptionOverrides type excludes them anyway).
 	if (overrides) Object.assign(options, overrides);
 
+	// Fable-class models withhold thinking plaintext by default: blocks stream
+	// structure + token estimates only, so every reasoning part arrives with
+	// empty text. The hidden `--thinking-display summarized` flag opts into
+	// summary text (ignored by CLIs that don't honor it). Applied after operator
+	// overrides so an unrelated operator extraArgs can't drop it, while an
+	// explicit operator `thinking-display` key still wins.
+	if (config.thinkingLevel !== "off") {
+		options.extraArgs = { "thinking-display": "summarized", ...options.extraArgs };
+	}
+
 	return options;
 }

package/src/core/agents/claude-code/session-manager.ts

@@ -2,7 +2,7 @@ import type { McpSetServersResult } from "@anthropic-ai/claude-agent-sdk";
 import type { McpServerConfig } from "../../../protocol/index.ts";
 import { configFingerprint } from "../config-fingerprint.ts";
 import { ClaudeGeneratorSession } from "./generator-session.ts";
-import type { ClaudeSessionExtras } from "./generator-session.ts";
+import type { ClaudeSessionEndReason, ClaudeSessionExtras } from "./generator-session.ts";
 import type { ClaudeSessionConfig } from "./options.ts";
 
 /** Directory-set identity: order and duplicates don't change the sandbox surface. */
@@ -66,6 +66,10 @@ export function claudeRestartConfig(
 export class ClaudeSessionManager {
 	private readonly sessions = new Map<string, ClaudeGeneratorSession>();
 
+	constructor(
+		private readonly onSessionEnd?: (sessionId: string, reason: ClaudeSessionEndReason) => void,
+	) {}
+
 	async getOrCreate(
 		sessionId: string,
 		config: ClaudeSessionConfig,
@@ -80,7 +84,7 @@ export class ClaudeSessionManager {
 					config,
 					existing.currentSessionId,
 				);
-				await existing.terminate();
+				await existing.terminate("replaced");
 				this.sessions.delete(sessionId);
 			} else {
 				await this.hotSwapIfNeeded(existing, config);
@@ -91,8 +95,9 @@ export class ClaudeSessionManager {
 		const session = new ClaudeGeneratorSession(
 			sessionId,
 			startConfig,
-			() => {
+			(reason) => {
 				if (this.sessions.get(sessionId) === session) this.sessions.delete(sessionId);
+				this.onSessionEnd?.(sessionId, reason);
 			},
 			extras,
 		);
@@ -119,7 +124,7 @@ export class ClaudeSessionManager {
 	}
 
 	async terminateAll(): Promise<void> {
-		await Promise.all([...this.sessions.values()].map((s) => s.terminate()));
+		await Promise.all([...this.sessions.values()].map((s) => s.terminate("shutdown")));
 		this.sessions.clear();
 	}
 

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

@@ -64,10 +64,10 @@ type UserInput = { type: "text"; text: string; text_elements: [] } | { type: "im
 
 function mapSandbox(mode: PermissionMode | undefined): string {
 	switch (mode) {
-		case "bypassPermissions":
+		case "bypass_permissions":
 			return "danger-full-access";
-		case "acceptEdits":
-		case "dontAsk":
+		case "accept_edits":
+		case "dont_ask":
 			// Never-ask posture, but inside the normal sandbox — danger-full is
 			// reserved for the explicitly dangerous mode.
 			return "workspace-write";
@@ -82,6 +82,14 @@ function toUserInput(input: AgentInput): UserInput[] {
 	for (const part of input) {
 		if (part.type === "text") out.push({ type: "text", text: part.text, text_elements: [] });
 		else if (part.url) out.push({ type: "image", url: part.url });
+		else if (part.type === "image" && part.data) {
+			// Codex's user input carries images by URL only; a pasted image arrives
+			// as base64 `data` and used to be dropped SILENTLY while the negotiated
+			// capability said supported. A data URL delivers it on the same field —
+			// and a Codex build that rejects it fails the turn loudly instead of
+			// the prompt losing its attachment with no trace.
+			out.push({ type: "image", url: `data:${part.mimeType};base64,${part.data}` });
+		}
 	}
 	return out.length ? out : [{ type: "text", text: "", text_elements: [] }];
 }
@@ -260,8 +268,14 @@ export class CodexAppServerAgent extends BaseAgent {
 			const handler = session.permissionHandler;
 			if (!handler) return decline;
 			const decision = await handler(approvalToolCall(method, params));
+			// Codex's approval reply is a bare verdict — no slot for
+			// `decision.updatedInput`, so an edited input cannot be honoured here
+			// (only claude-code's `canUseTool` can execute the edit). An edited
+			// approval therefore DECLINES: accepting would run input nobody
+			// approved.
 			switch (decision.decision) {
 				case "allow":
+					if (decision.updatedInput !== undefined) return decline;
 					return v2 ? { decision: "accept" } : { decision: "approved" };
 				case "cancel":
 					return v2 ? { decision: "cancel" } : { decision: "abort" };

package/src/core/agents/codex-sdk/codex-sdk-agent.ts

@@ -77,10 +77,10 @@ export function codexThreadCompatible(
 
 function mapSandbox(mode: PermissionMode | undefined): ThreadOptions["sandboxMode"] {
 	switch (mode) {
-		case "bypassPermissions":
+		case "bypass_permissions":
 			return "danger-full-access";
-		case "acceptEdits":
-		case "dontAsk":
+		case "accept_edits":
+		case "dont_ask":
 			// Never-ask posture, but inside the normal sandbox — danger-full is
 			// reserved for the explicitly dangerous mode.
 			return "workspace-write";

package/src/core/agents/types.ts

@@ -26,7 +26,7 @@ export type AdapterEvent =
 	  }
 	/** Context-window gauge snapshot (→ `session.usage`). */
 	| { kind: "usage"; used: number; size?: number; cost?: number }
-	/** History-compaction boundary (→ `session.compacted`). */
+	/** History-compaction boundary (→ the `session.compaction` entity). */
 	| { kind: "compacted"; trigger?: string; preTokens?: number; postTokens?: number };
 
 /** Terminal result of a turn, surfaced on `turn.ended`. */

package/src/core/diagnostics.ts

@@ -0,0 +1,59 @@
+/**
+ * The engine's diagnostics port: operational signals the engine used to
+ * swallow (best-effort paths that must not fail a turn) surfaced to the host
+ * instead. Products log/metric these; the engine never does its own logging.
+ * Handler errors are always swallowed — a diagnostics sink must never be able
+ * to break a turn.
+ */
+
+/**
+ * Known diagnostic kinds (open set — new kinds may appear in minor versions;
+ * the `(string & {})` arm keeps the union open without losing autocomplete):
+ *  - `interruptTimeout` — a cancel's SDK interrupt round-trip timed out
+ *    (the turn was reported `confirmed: false`; the agent may still run).
+ *  - `resumeFallback` — a requested resume failed and the turn re-ran on a
+ *    fresh session (also visible as `session.created.resumed: false`).
+ *  - `sinkError` — an EventSink emit threw; the event was dropped for that
+ *    sink and the turn continued.
+ *  - `proxyUpstreamAuth` — the BYOK proxy's upstream rejected the real key
+ *    (401/403): the stored key is invalid/expired, not the placeholder.
+ */
+export type DiagnosticKind =
+	| "interruptTimeout"
+	| "resumeFallback"
+	| "sinkError"
+	| "proxyUpstreamAuth"
+	| (string & {});
+
+export interface EngineDiagnostic {
+	type: DiagnosticKind;
+	sessionId?: string;
+	message: string;
+	detail?: unknown;
+	timestamp: number;
+}
+
+/**
+ * Declared `=> void` so any callback shape is assignable (TS's void-return
+ * exemption covers `() => diagnostics.push(d)` AND async handlers); a
+ * returned promise is still detected at runtime and its rejection swallowed.
+ */
+export type DiagnosticHandler = (diagnostic: EngineDiagnostic) => void;
+
+/** Invoke a handler without letting it break the calling path — sync throws
+ * AND async rejections are swallowed (the diagnostics sink owns its own
+ * reliability). Stamps the timestamp so call sites don't repeat it. */
+export function emitDiagnostic(
+	handler: DiagnosticHandler | undefined,
+	diagnostic: Omit<EngineDiagnostic, "timestamp">,
+): void {
+	if (!handler) return;
+	try {
+		const result = handler({ ...diagnostic, timestamp: Date.now() }) as unknown;
+		if (result instanceof Promise) {
+			result.catch(() => {});
+		}
+	} catch {
+		// see above
+	}
+}

package/src/core/index.ts

@@ -2,6 +2,7 @@
 
 // Runtime
 export { AgentRuntime, type RunSummary, type TurnAdmission } from "./runtime/agent-runtime.ts";
+export { type DiagnosticHandler, type EngineDiagnostic, emitDiagnostic } from "./diagnostics.ts";
 export {
 	type EventSink,
 	callbackSink,
@@ -25,7 +26,7 @@ export {
 	classifyError,
 	isRecoverable,
 	isCancellation,
-} from "./agents/error-classifier.ts";
+} from "../protocol/errors.ts";
 
 // Adapter contract
 export type {
@@ -58,6 +59,7 @@ export {
 export type { ClaudeSdkOptionOverrides, SdkMcpServers } from "./agents/claude-code/options.ts";
 export type {
 	ClaudeHooksFactory,
+	ClaudeSessionEndReason,
 	ClaudeSessionExtras,
 	ClaudeToolPolicy,
 } from "./agents/claude-code/generator-session.ts";

package/src/core/presets.ts

@@ -8,6 +8,7 @@ import { CodexAppServerAgent } from "./agents/codex-app-server/codex-app-server-
 import { createCodexSdkTransformer } from "./agents/codex-sdk/adapter.ts";
 import { CodexSdkAgent } from "./agents/codex-sdk/codex-sdk-agent.ts";
 import { AgentRegistry } from "./agents/registry.ts";
+import type { DiagnosticHandler } from "./diagnostics.ts";
 import { CliProvisioner, type ProvisionOptions } from "./provision/provisioner.ts";
 import { AgentRuntime } from "./runtime/agent-runtime.ts";
 
@@ -32,6 +33,14 @@ export interface CreateRegistryOptions {
 	 * `resolveCliPath` stays provisioner-wired here.
 	 */
 	claudeCode?: Omit<ClaudeCodeAgentOptions, "resolveCliPath">;
+	/**
+	 * Operational diagnostics port (see `EngineDiagnostic`): interrupt
+	 * timeouts, resume fallbacks, sink failures — signals the engine must not
+	 * fail a turn over, surfaced for the host to log/metric. Applied to the
+	 * runtime and every harness that emits them; a harness-level
+	 * `claudeCode.onDiagnostic` overrides for that harness.
+	 */
+	onDiagnostic?: DiagnosticHandler;
 }
 
 /** Build a registry with the standard harnesses wired to their adapters. */
@@ -50,7 +59,11 @@ export function createAgentRegistry(opts: CreateRegistryOptions = {}): AgentRegi
 	const registry = new AgentRegistry();
 	if (enabled.has("claude-code")) {
 		registry.register(
-			new ClaudeCodeAgent({ ...opts.claudeCode, resolveCliPath: claudeCli }),
+			new ClaudeCodeAgent({
+				onDiagnostic: opts.onDiagnostic,
+				...opts.claudeCode,
+				resolveCliPath: claudeCli,
+			}),
 			createClaudeCodeTransformer,
 		);
 	}
@@ -74,5 +87,5 @@ export function createAgentRegistry(opts: CreateRegistryOptions = {}): AgentRegi
 
 /** Convenience: a ready-to-use runtime with the standard harnesses. */
 export function createAgentRuntime(opts: CreateRegistryOptions = {}): AgentRuntime {
-	return new AgentRuntime(createAgentRegistry(opts));
+	return new AgentRuntime(createAgentRegistry(opts), { onDiagnostic: opts.onDiagnostic });
 }