@gajae-code/agent-core 0.12.0 → 0.12.1

package/CHANGELOG.md

@@ -2,7 +2,13 @@
 
 ## [Unreleased]
 
-## [0.12.0] - 2026-07-28
+## [0.12.1] - 2026-07-29
+- Agent session configuration can carry an explicit first-event stream timeout while preserving provider defaults when the setting is absent.
+
+### Fixed
+
+- The `invalid_prompt` circuit breaker no longer replays the rejected turn on its repaired resend. The streaming path commits the failed assistant message to the context before the breaker runs, so the one repaired resend re-sent that errored turn as if the model had spoken it — re-triggering `Request blocked (code=invalid_prompt)` and leaving a second assistant tail that no continuation can resume from. The breaker now repairs and resends only the history that preceded the rejection.
+- Compaction pruning now protects the newest two user/`bashExecution` turns, uses conservative read supersession, preserves bounded error-first diagnostics, and exposes reversible artifact-backed originals with exact savings accounting.
 
 ## [0.11.11] - 2026-07-26
 

package/dist/types/agent.d.ts

@@ -4,7 +4,7 @@
 import { type AssistantMessage, type AssistantMessageEvent, type CursorExecHandlers, type CursorToolResultHandler, type Effort, type ImageContent, type Message, type Model, type ProviderSessionState, type ServiceTier, type SimpleStreamOptions, type ThinkingBudgets, type ToolChoice } from "@gajae-code/ai";
 import type { AppendOnlyContextManager } from "./append-only-context";
 import type { HarmonyAuditEvent } from "./harmony-leak";
-import type { AgentEvent, AgentLoopConfig, AgentMessage, AgentState, AgentTool, AgentToolContext, ManagedLogicalRunId, RunTerminalRequest, StreamFn, ToolCallContext } from "./types";
+import type { AgentEvent, AgentLoopConfig, AgentMessage, AgentState, AgentTool, AgentToolContext, ManagedLogicalRunId, RunResourceLedger, RunTerminalRequest, StreamFn, ToolCallContext } from "./types";
 /**
  * Whether persisted history ends at a point where a new model turn can resume.
  * Assistant-ended histories require an in-memory queued message and are handled
@@ -127,6 +127,8 @@ export interface AgentOptions {
     requestMaxRetries?: number;
     /** Provider stream replay retry budget. Counts retries, not the initial attempt. */
     streamMaxRetries?: number;
+    /** Explicit first-event stream watchdog override in milliseconds. Set to 0 to disable. */
+    streamFirstEventTimeoutMs?: number;
     /**
      * Provides tool execution context, resolved per tool call.
      * Use for late-bound UI or session state access.
@@ -191,6 +193,7 @@ export type AgentQueueSnapshot = {
 export declare class Agent {
     #private;
     get intentTracing(): boolean;
+    readonly resourceLedger: RunResourceLedger;
     streamFn: StreamFn;
     getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
     getAuthCredentialType?: (provider: string) => "api_key" | "oauth" | undefined;
@@ -314,6 +317,8 @@ export declare class Agent {
     set requestMaxRetries(value: number | undefined);
     get streamMaxRetries(): number | undefined;
     set streamMaxRetries(value: number | undefined);
+    get streamFirstEventTimeoutMs(): number | undefined;
+    set streamFirstEventTimeoutMs(value: number | undefined);
     get state(): AgentState;
     get contextRevision(): number;
     get appendOnlyContext(): AppendOnlyContextManager | undefined;
@@ -415,6 +420,8 @@ export declare class Agent {
     waitForIdle(): Promise<void>;
     /** The active per-attempt run identifier. */
     get activeRunId(): number | undefined;
+    /** Stable resource ownership identifier for the active prompt run. */
+    get activeResourceRunId(): string | undefined;
     /**
      * Stable identifier for the active managed logical run, shared by every retry
      * attempt. Pass this value to requestRunTerminal(); never retain activeRunId

package/dist/types/compaction/pruning.d.ts

@@ -15,6 +15,8 @@ export interface PruneConfig {
     minimumSavings: number;
     /** Tool names that should never be pruned. */
     protectedTools: string[];
+    /** Number of newest user turns whose tool outputs must remain intact. Defaults to 2. */
+    protectRecentTurns?: number;
     /**
      * Tools in `protectedTools` whose protection is waived once the result is
      * superseded (a later result for the same target, or a later successful
@@ -24,9 +26,18 @@ export interface PruneConfig {
     staleOverridableTools?: string[];
 }
 export declare const DEFAULT_PRUNE_CONFIG: PruneConfig;
+export interface PrunedOriginal {
+    entryId: string;
+    toolName?: string;
+    originalText: string;
+    tokens: number;
+    /** Whether originalText captures all-text result content without omission. */
+    complete?: boolean;
+}
 export interface PruneResult {
     prunedCount: number;
     tokensSaved: number;
+    originals: PrunedOriginal[];
     /**
      * The mutated message entries. Callers whose entry source returns
      * materialized copies (not live references) must write these back into
@@ -45,9 +56,11 @@ export interface AssistantArgumentPruneResult {
 }
 export declare function pruneAssistantToolArguments(entries: SessionEntry[], config?: PruneConfig): AssistantArgumentPruneResult;
 /**
- * Estimate the token savings {@link pruneToolOutputs} would achieve, without
- * mutating any entry. Returns 0 savings when below the configured minimum so the
- * caller sees the same gate the real prune enforces.
+ * Estimate the conservative final token savings {@link pruneToolOutputs} would
+ * achieve, without mutating entries or invoking the artifact-reference planner.
+ * When `artifactRefMaxChars` is present, the estimate budgets that full length
+ * for every complete candidate so the real artifact-backed prune cannot save
+ * less than the estimate.
  */
 export declare function estimateToolOutputPruneSavings(entries: SessionEntry[], config?: PruneConfig, options?: PruneToolOutputsOptions): {
     prunableCount: number;
@@ -69,5 +82,18 @@ export declare function shouldRunMaintenancePrune(args: {
 export interface PruneToolOutputsOptions {
     /** Lower the usual minimum only when the caller is already over its compaction threshold. */
     relaxedMinimum?: number;
+    /**
+     * Conservative maximum ASCII length of every planned artifact reference.
+     * Required when `artifactRef` is provided so estimation and final admission
+     * use the same worst-case notice size.
+     */
+    artifactRefMaxChars?: number;
+    /**
+     * Plan a numeric `artifact://<id>` reference for a candidate's original
+     * text. The callback may reserve an in-memory identifier, but MUST NOT publish
+     * files or mutate session entries; publish only the originals returned by a
+     * successful {@link pruneToolOutputs} result.
+     */
+    artifactRef?: (candidate: PrunedOriginal) => string | undefined;
 }
 export declare function pruneToolOutputs(entries: SessionEntry[], config?: PruneConfig, options?: PruneToolOutputsOptions): PruneResult;

package/dist/types/index.d.ts

@@ -6,6 +6,7 @@ export * from "./harmony-leak";
 export * from "./image-placeholder-guard";
 export * from "./proxy";
 export * from "./run-collector";
+export * from "./run-resource-ledger";
 export * from "./telemetry";
 export * from "./thinking";
 export * from "./types";

package/dist/types/run-resource-ledger.d.ts

@@ -0,0 +1,2 @@
+import type { RunResourceLedger } from "./types";
+export declare function createRunResourceLedger(): RunResourceLedger;

package/dist/types/types.d.ts

@@ -7,6 +7,33 @@ import type { AgentTelemetryConfig } from "./telemetry";
 export type StreamFn = (...args: Parameters<typeof streamSimple>) => AssistantMessageEventStream | Promise<AssistantMessageEventStream>;
 /** Stable identifier for a managed logical run, shared by all of its retry attempts. */
 export type ManagedLogicalRunId = number;
+/** A resource owned by a prompt run until its promise settles. */
+export type RunResourceKind = "provider_factory" | "provider_iterator" | "tool" | "post_prompt";
+export interface RunResourceEntry {
+    id: string;
+    kind: RunResourceKind;
+    label: string;
+    registeredAt: number;
+}
+export type RunSettlementProof = {
+    status: "settled";
+} | {
+    status: "unfenced";
+    pending: RunResourceEntry[];
+};
+export interface RunResourceLedger {
+    /** Reserve a run handle before publishing its `agent_start` event. */
+    open(resourceRunId: string): void;
+    track(resourceRunId: string, kind: RunResourceKind, label: string, settled: PromiseLike<unknown>): void;
+    pending(resourceRunId: string): RunResourceEntry[];
+    /** Seal a run after terminal event publication; only sealed empty runs settle. */
+    seal(resourceRunId: string): void;
+    waitForSettlement(resourceRunId: string, options: {
+        graceMs: number;
+    }): Promise<RunSettlementProof>;
+    /** Terminally detach a run; its bounded tombstone remains unfenced forever. */
+    quarantine(resourceRunId: string): RunResourceEntry[];
+}
 /** Terminal completion requested for a logical run. */
 export interface RunTerminalRequest {
     stopReason: "cancelled" | "error" | "exhausted";
@@ -302,6 +329,13 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * capture, cost estimator, agent identity).
      */
     telemetry?: AgentTelemetryConfig;
+    /**
+     * Optional prompt-run resource ownership ledger. Provider and scheduler-level tool
+     * work is tracked until its owned lifecycle promise settles.
+     */
+    resourceLedger?: RunResourceLedger;
+    /** Stable resource ownership identifier for this prompt run. */
+    resourceRunId?: string;
 }
 /**
  * Batch/sequencing metadata for the tool call currently being processed.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/agent-core",
-	"version": "0.12.0",
+	"version": "0.12.1",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo and Gajae Code Contributors",
@@ -32,9 +32,9 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/ai": "0.12.0",
-		"@gajae-code/natives": "0.12.0",
-		"@gajae-code/utils": "0.12.0",
+		"@gajae-code/ai": "0.12.1",
+		"@gajae-code/natives": "0.12.1",
+		"@gajae-code/utils": "0.12.1",
 		"@opentelemetry/api": "^1.9.0"
 	},
 	"devDependencies": {

package/src/agent-loop.ts

@@ -305,6 +305,7 @@ export function agentLoop(
 			? new ManagedAttemptTransaction(stream, config.onAssistantMessageEvent, config.model)
 			: undefined;
 		const attemptStream = transaction ?? stream;
+		openResourceRun(config);
 		if (!config.fallbackManaged || emitManagedAgentStart) stream.push({ type: "agent_start" });
 		attemptStream.push({ type: "turn_start" });
 		for (const prompt of prompts) {
@@ -315,6 +316,7 @@ export function agentLoop(
 		try {
 			await runLoop(currentContext, newMessages, config, signal, stream, streamFn, transaction);
 		} catch (err) {
+			if (config.resourceLedger && config.resourceRunId) config.resourceLedger.seal(config.resourceRunId);
 			stream.fail(err);
 		}
 	})();
@@ -354,12 +356,14 @@ export function agentLoopContinue(
 			? new ManagedAttemptTransaction(stream, config.onAssistantMessageEvent, config.model)
 			: undefined;
 		const attemptStream = transaction ?? stream;
+		openResourceRun(config);
 		if (!config.fallbackManaged || emitManagedAgentStart) stream.push({ type: "agent_start" });
 		attemptStream.push({ type: "turn_start" });
 
 		try {
 			await runLoop(currentContext, newMessages, config, signal, stream, streamFn, transaction);
 		} catch (err) {
+			if (config.resourceLedger && config.resourceRunId) config.resourceLedger.seal(config.resourceRunId);
 			stream.fail(err);
 		}
 	})();
@@ -374,6 +378,21 @@ function createAgentStream(): EventStream<AgentEvent, AgentMessage[]> {
 	);
 }
 
+function openResourceRun(config: AgentLoopConfig): void {
+	if (config.resourceLedger && config.resourceRunId) config.resourceLedger.open(config.resourceRunId);
+}
+
+function publishAgentEnd(
+	stream: EventStream<AgentEvent, AgentMessage[]>,
+	config: AgentLoopConfig,
+	event: Extract<AgentEvent, { type: "agent_end" }>,
+): void {
+	stream.push(event);
+	if (event.stopReason !== "maintenance" && config.resourceLedger && config.resourceRunId) {
+		config.resourceLedger.seal(config.resourceRunId);
+	}
+}
+
 /**
  * Hard work budget for one degraded snapshot: every visited node AND every
  * enumerated own key is debited against this budget before it is processed
@@ -1475,7 +1494,19 @@ async function runLoopBody(
 				isInvalidPromptError(message)
 			) {
 				invalidPromptRepairAttempted = true;
-				if (repairInvalidPromptHistory(currentContext.messages)) {
+				// The rejected turn was already committed to the context by the
+				// streaming path. Repair (and resend) only the history that
+				// preceded it: replaying an errored assistant turn re-poisons the
+				// request and leaves a second assistant tail behind, which no
+				// continuation can resume from.
+				const rejectedIndex = currentContext.messages.length - 1;
+				const rejectedCommitted =
+					rejectedIndex >= 0 && currentContext.messages[rejectedIndex]?.role === "assistant";
+				const retained = rejectedCommitted
+					? currentContext.messages.slice(0, rejectedIndex)
+					: currentContext.messages;
+				if (repairInvalidPromptHistory(retained)) {
+					if (rejectedCommitted) currentContext.messages.splice(rejectedIndex, 1);
 					continue;
 				}
 			}
@@ -1558,7 +1589,7 @@ async function runLoopBody(
 					});
 				}
 				stream.push({ type: "turn_end", message, toolResults });
-				stream.push(buildAgentEndEvent(newMessages, telemetry, stepCounter.count));
+				publishAgentEnd(stream, config, buildAgentEndEvent(newMessages, telemetry, stepCounter.count));
 				stream.end(newMessages);
 				return;
 			}
@@ -1638,7 +1669,7 @@ async function runLoopBody(
 			pendingMessages = (await config.getSteeringMessages?.()) || [];
 			if (pendingMessages.length > 0) continue;
 			if (config.shouldPause?.()) {
-				stream.push(buildAgentEndEvent(newMessages, telemetry, stepCounter.count, "paused"));
+				publishAgentEnd(stream, config, buildAgentEndEvent(newMessages, telemetry, stepCounter.count, "paused"));
 				stream.end(newMessages);
 				return;
 			}
@@ -1659,7 +1690,7 @@ async function runLoopBody(
 				message.errorMessage = message.errorMessage
 					? `${message.errorMessage} | ${breakerMessage}`
 					: breakerMessage;
-				stream.push(buildAgentEndEvent(newMessages, telemetry, stepCounter.count));
+				publishAgentEnd(stream, config, buildAgentEndEvent(newMessages, telemetry, stepCounter.count));
 				stream.end(newMessages);
 				return;
 			}
@@ -1668,7 +1699,7 @@ async function runLoopBody(
 		// Agent would stop here. Check for follow-up messages.
 		await config.onBeforeYield?.();
 		if (config.shouldPause?.()) {
-			stream.push(buildAgentEndEvent(newMessages, telemetry, stepCounter.count, "paused"));
+			publishAgentEnd(stream, config, buildAgentEndEvent(newMessages, telemetry, stepCounter.count, "paused"));
 			stream.end(newMessages);
 			return;
 		}
@@ -1683,7 +1714,7 @@ async function runLoopBody(
 		break;
 	}
 
-	stream.push(buildAgentEndEvent(newMessages, telemetry, stepCounter.count));
+	publishAgentEnd(stream, config, buildAgentEndEvent(newMessages, telemetry, stepCounter.count));
 	stream.end(newMessages);
 }
 
@@ -1831,24 +1862,64 @@ async function streamAssistantResponse(
 	try {
 		return await runInActiveSpan(chatSpan, async () => {
 			const fallbackAttempt = config.fallbackManaged ? config.nextFallbackAttempt?.(config.model) : undefined;
-			const response = await streamFunction(config.model, llmContext, {
-				...config,
-				fallbackAttempt,
-				apiKey: resolvedApiKey,
-				authCredentialType,
-				metadata: resolvedMetadata,
-				sessionId: config.providerSessionId ?? config.sessionId,
-				toolChoice: effectiveToolChoice,
-				reasoning: effectiveReasoning,
-				temperature: effectiveTemperature,
-				signal: requestSignal,
-				onResponse: captureOnResponse,
+			const responsePromise = Promise.resolve().then(() =>
+				streamFunction(config.model, llmContext, {
+					...config,
+					fallbackAttempt,
+					apiKey: resolvedApiKey,
+					authCredentialType,
+					metadata: resolvedMetadata,
+					sessionId: config.providerSessionId ?? config.sessionId,
+					toolChoice: effectiveToolChoice,
+					reasoning: effectiveReasoning,
+					temperature: effectiveTemperature,
+					signal: requestSignal,
+					onResponse: captureOnResponse,
+				}),
+			);
+			const { promise: iteratorSettled, resolve: settleIterator } = Promise.withResolvers<void>();
+			let responseResultPromise: Promise<AssistantMessage> | undefined;
+			let responseForResult: { result(): Promise<AssistantMessage> } | undefined;
+			const getResponseResult = (): Promise<AssistantMessage> =>
+				(responseResultPromise ??= Promise.resolve().then(() => responseForResult!.result()));
+			const providerLifecycle = responsePromise.then(async response => {
+				responseForResult = response;
+				await iteratorSettled;
+				await Promise.allSettled([getResponseResult()]);
 			});
+			if (config.resourceLedger && config.resourceRunId) {
+				// One ownership spans factory creation, iterator close, and trailing result.
+				config.resourceLedger.track(
+					config.resourceRunId,
+					"provider_factory",
+					`${config.model.provider}/${config.model.id}`,
+					providerLifecycle,
+				);
+			}
+			const response = await responsePromise;
+			responseForResult = response;
 
 			let partialMessage: AssistantMessage | null = null;
 			let addedPartial = false;
 
 			const responseIterator = response[Symbol.asyncIterator]();
+			let iteratorClosed = false;
+			const closeIterator = (): void => {
+				if (iteratorClosed) return;
+				iteratorClosed = true;
+
+				void Promise.resolve()
+					.then(() => responseIterator.return?.())
+					.then(
+						() => settleIterator(),
+						() => settleIterator(),
+					);
+			};
+			const finishResponse = async (): Promise<AssistantMessage> => {
+				closeIterator();
+				await iteratorSettled;
+				return getResponseResult();
+			};
 
 			// Set up a single abort race: register the abort listener once for the whole
 			// stream and reuse the same race promise for every iterator.next() instead of
@@ -1857,6 +1928,7 @@ async function streamAssistantResponse(
 			let detachAbortListener: (() => void) | undefined;
 			if (requestSignal) {
 				if (requestSignal.aborted) {
+					closeIterator();
 					const aborted = emitAbortedAssistantMessage(partialMessage, addedPartial, context, config, stream);
 					await finishChat(aborted);
 					return aborted;
@@ -1874,7 +1946,7 @@ async function streamAssistantResponse(
 					if (abortRacePromise) {
 						const result = await Promise.race([responseIterator.next(), abortRacePromise]);
 						if (result === ABORTED) {
-							responseIterator.return?.()?.catch(() => {});
+							closeIterator();
 							const aborted = emitAbortedAssistantMessage(partialMessage, addedPartial, context, config, stream);
 							await finishChat(aborted);
 							return aborted;
@@ -1888,7 +1960,11 @@ async function streamAssistantResponse(
 						await finishChat(aborted);
 						return aborted;
 					}
-					if (next.done) break;
+					if (next.done) {
+						iteratorClosed = true;
+						settleIterator();
+						break;
+					}
 
 					const event = next.value;
 
@@ -1937,8 +2013,8 @@ async function streamAssistantResponse(
 						case "done":
 						case "error": {
 							const finalMessage = config.fallbackManaged
-								? managedAssistantShell(await response.result(), config.model)
-								: await response.result();
+								? managedAssistantShell(await finishResponse(), config.model)
+								: await finishResponse();
 							if (addedPartial) {
 								context.messages[context.messages.length - 1] = finalMessage;
 							} else {
@@ -1955,11 +2031,12 @@ async function streamAssistantResponse(
 				}
 			} finally {
 				detachAbortListener?.();
+				closeIterator();
 			}
 
 			const trailing = config.fallbackManaged
-				? managedAssistantShell(await response.result(), config.model)
-				: await response.result();
+				? managedAssistantShell(await finishResponse(), config.model)
+				: await finishResponse();
 			await finishChat(trailing);
 			return trailing;
 		});
@@ -2142,10 +2219,8 @@ async function executeToolCalls(
 	const runTool = async (record: (typeof records)[number], index: number): Promise<void> => {
 		if (interruptState.triggered) {
 			// Skip both span emission and the collector orphan record here. The
-			// tail sweep below (after `Promise.allSettled`) is the single path
-			// that handles "no result message was produced" — it calls
-			// `recordSkippedTool` and `emitToolResult` once per record, so any
-			// work we did here would double-count.
+			// scheduler-task finalizer emits the skipped result and collector record;
+			// the tail sweep below remains a defensive fallback for unexpected throws.
 			record.skipped = true;
 			return;
 		}
@@ -2261,7 +2336,7 @@ async function executeToolCalls(
 							toolCalls: toolCallInfos,
 						})
 					: undefined;
-				const rawResult = await tool.execute(
+				const execution = tool.execute(
 					toolCall.id,
 					transformToolCallArguments ? transformToolCallArguments(effectiveArgs, toolCall.name) : effectiveArgs,
 					tool.nonAbortable ? undefined : toolSignal,
@@ -2276,6 +2351,7 @@ async function executeToolCalls(
 					},
 					toolContext,
 				);
+				const rawResult = await execution;
 				const coerced = coerceToolResult(rawResult);
 				result = coerced.result;
 				if (coerced.malformed || result.isError) isError = true;
@@ -2359,8 +2435,30 @@ async function executeToolCalls(
 		const record = records[index];
 		const concurrency = record.tool?.concurrency ?? "shared";
 		const start = concurrency === "exclusive" ? Promise.all([lastExclusive, ...sharedTasks]) : lastExclusive;
-		const task = start.then(() => runTool(record, index));
+		const task = start
+			.then(() => runTool(record, index))
+			.finally(() => {
+				// Scheduler ownership includes dependency waits and the fallback skip
+				// emission, not only tool.execute().
+				if (!record.toolResultMessage) {
+					record.skipped = true;
+					recordSkippedTool(telemetry, {
+						toolCallId: record.toolCall.id,
+						toolName: record.toolCall.name,
+						status: "skipped",
+					});
+					emitToolResult(record, createSkippedToolResult(), true);
+				}
+			});
 		tasks.push(task);
+		if (config.resourceLedger && config.resourceRunId) {
+			config.resourceLedger.track(
+				config.resourceRunId,
+				"tool",
+				`${record.toolCall.name}:${record.toolCall.id}`,
+				task,
+			);
+		}
 		if (concurrency === "exclusive") {
 			lastExclusive = task;
 			sharedTasks = [];

package/src/agent.ts

@@ -25,6 +25,7 @@ import { agentLoop, agentLoopContinue } from "./agent-loop";
 import type { AppendOnlyContextManager } from "./append-only-context";
 import type { HarmonyAuditEvent } from "./harmony-leak";
 import { assertImagePlaceholdersHavePayload } from "./image-placeholder-guard";
+import { createRunResourceLedger } from "./run-resource-ledger";
 import type {
 	AgentContext,
 	AgentEvent,
@@ -38,6 +39,7 @@ import type {
 	ManagedAttemptDecision,
 	ManagedAttemptOutcome,
 	ManagedLogicalRunId,
+	RunResourceLedger,
 	RunTerminalRequest,
 	StreamFn,
 	ToolCallContext,
@@ -235,6 +237,8 @@ export interface AgentOptions {
 	requestMaxRetries?: number;
 	/** Provider stream replay retry budget. Counts retries, not the initial attempt. */
 	streamMaxRetries?: number;
+	/** Explicit first-event stream watchdog override in milliseconds. Set to 0 to disable. */
+	streamFirstEventTimeoutMs?: number;
 
 	/**
 	 * Provides tool execution context, resolved per tool call.
@@ -354,6 +358,7 @@ export class Agent {
 	#maxRetryDelayMs?: number;
 	#requestMaxRetries?: number;
 	#streamMaxRetries?: number;
+	#streamFirstEventTimeoutMs?: number;
 	#getToolContext?: (toolCall?: ToolCallContext) => AgentToolContext | undefined;
 	#cursorExecHandlers?: CursorExecHandlers;
 	#cursorOnToolResult?: CursorToolResultHandler;
@@ -361,6 +366,7 @@ export class Agent {
 	#resolveRunningPrompt?: () => void;
 	#runSequence = 0;
 	#activeRunId?: number;
+	#activeResourceRunId?: string;
 	#continuationGeneration = 0;
 	#activeFallbackManaged = false;
 	#kimiApiFormat?: "openai" | "anthropic";
@@ -388,6 +394,7 @@ export class Agent {
 	#cursorToolResultBuffer: CursorToolResultEntry[] = [];
 	#terminalizedLogicalRunIds = new Set<ManagedLogicalRunId>();
 	#managedLogicalRunOwner?: ManagedLogicalRunId;
+	readonly resourceLedger: RunResourceLedger = createRunResourceLedger();
 
 	streamFn: StreamFn;
 	getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
@@ -426,6 +433,7 @@ export class Agent {
 		this.#maxRetryDelayMs = opts.maxRetryDelayMs;
 		this.#requestMaxRetries = opts.requestMaxRetries;
 		this.#streamMaxRetries = opts.streamMaxRetries;
+		this.#streamFirstEventTimeoutMs = opts.streamFirstEventTimeoutMs;
 		this.getApiKey = opts.getApiKey;
 		this.getAuthCredentialType = opts.getAuthCredentialType;
 		this.#onPayload = opts.onPayload;
@@ -671,6 +679,14 @@ export class Agent {
 		this.#streamMaxRetries = value;
 	}
 
+	get streamFirstEventTimeoutMs(): number | undefined {
+		return this.#streamFirstEventTimeoutMs;
+	}
+
+	set streamFirstEventTimeoutMs(value: number | undefined) {
+		this.#streamFirstEventTimeoutMs = value;
+	}
+
 	get state(): AgentState {
 		return this.#state;
 	}
@@ -1152,12 +1168,14 @@ export class Agent {
 		this.#state.pendingToolCalls = new Set<string>();
 		this.#abortController = undefined;
 		this.#cursorToolResultBuffer = [];
+		this.resourceLedger.quarantine(this.#activeResourceRunId ?? String(managedLogicalRunId ?? runId));
 		this.#managedLogicalRunOwner = undefined;
 
 		const resolve = this.#resolveRunningPrompt;
 		this.#runningPrompt = undefined;
 		this.#resolveRunningPrompt = undefined;
 		this.#activeRunId = undefined;
+		this.#activeResourceRunId = undefined;
 		resolve?.();
 		if (this.#activeFallbackManaged) {
 			this.requestRunTerminal(managedLogicalRunId ?? runId, { stopReason: "cancelled" });
@@ -1175,6 +1193,10 @@ export class Agent {
 	get activeRunId(): number | undefined {
 		return this.#activeRunId;
 	}
+	/** Stable resource ownership identifier for the active prompt run. */
+	get activeResourceRunId(): string | undefined {
+		return this.#activeResourceRunId;
+	}
 
 	/**
 	 * Stable identifier for the active managed logical run, shared by every retry
@@ -1342,11 +1364,13 @@ export class Agent {
 		this.#state.isStreaming = true;
 		this.#state.streamMessage = null;
 		this.#state.error = undefined;
-		options?.onRunAccepted?.();
 
 		const fallbackManaged = options?.fallbackManaged === true;
 		const managedLogicalRunOwner = fallbackManaged ? (this.#managedLogicalRunOwner ?? runId) : undefined;
 		const startsManagedLogicalRun = fallbackManaged && this.#managedLogicalRunOwner === undefined;
+		this.#activeResourceRunId = String(managedLogicalRunOwner ?? runId);
+		this.resourceLedger.open(this.#activeResourceRunId);
+		options?.onRunAccepted?.();
 		if (startsManagedLogicalRun) {
 			this.#managedLogicalRunOwner = managedLogicalRunOwner;
 			this.#emit({ type: "agent_start" });
@@ -1358,6 +1382,7 @@ export class Agent {
 			this.#state.isStreaming = false;
 			this.#abortController = undefined;
 			this.#activeRunId = undefined;
+			this.#activeResourceRunId = undefined;
 			this.#runningPrompt = undefined;
 			this.#resolveRunningPrompt = undefined;
 			resolve();
@@ -1431,6 +1456,7 @@ export class Agent {
 			maxRetryDelayMs: this.#maxRetryDelayMs,
 			requestMaxRetries: this.#requestMaxRetries,
 			streamMaxRetries: this.#streamMaxRetries,
+			streamFirstEventTimeoutMs: this.#streamFirstEventTimeoutMs,
 			...(fallbackManaged
 				? {
 						fallbackManaged: true,
@@ -1454,6 +1480,8 @@ export class Agent {
 			onResponse: this.#onResponse,
 			onSseEvent: this.#onSseEvent,
 			signal: abortController.signal,
+			resourceLedger: this.resourceLedger,
+			resourceRunId: this.#activeResourceRunId,
 			getApiKey: this.getApiKey,
 			getAuthCredentialType: this.getAuthCredentialType,
 			getToolContext: this.#getToolContext,
@@ -1700,6 +1728,7 @@ export class Agent {
 				this.#state.pendingToolCalls = new Set<string>();
 				this.#abortController = undefined;
 				this.#activeRunId = undefined;
+				this.#activeResourceRunId = undefined;
 				this.#activeFallbackManaged = false;
 				this.#resolveRunningPrompt?.();
 				this.#runningPrompt = undefined;
@@ -1758,8 +1787,13 @@ export class Agent {
 		if (this.#terminalizedLogicalRunIds.size > 256) {
 			this.#terminalizedLogicalRunIds.delete(this.#terminalizedLogicalRunIds.values().next().value!);
 		}
-		beforeEvent?.();
-		if (event) this.#emit(event);
+		try {
+			beforeEvent?.();
+			if (event) this.#emit(event);
+		} finally {
+			// Publish terminal lifecycle synchronously before sealing the stable handle.
+			this.resourceLedger.seal(String(logicalRunId));
+		}
 	}
 
 	#getAssistantTextLength(message: AgentMessage | null): number {