@xopcai/xopc 0.0.221 → 0.0.223

package/dist/src/agent/embedded/runs.js

@@ -1,91 +1,70 @@
-import { createLogger } from "../../utils/logger/index.js";
-import { init_logger } from "../../utils/logger.js";
 //#region src/agent/embedded/runs.ts
-init_logger();
-const log = createLogger("EmbeddedRunRegistry");
-/**
-* Tracks in-flight embedded agent turns so we can abort/steer them by sessionKey or runId.
-*
-* The previous implementation used two module-level Maps; this class is the supported
-* single-instance state, while {@link defaultEmbeddedRunRegistry} preserves the previous
-* free-function API for callers that have not yet been moved to dependency injection.
-*/
+var EmbeddedRunConflictError = class extends Error {
+	constructor(sessionKey, activeRunId) {
+		super(`Session '${sessionKey}' already has active embedded run '${activeRunId}'`);
+		this.sessionKey = sessionKey;
+		this.activeRunId = activeRunId;
+		this.name = "EmbeddedRunConflictError";
+	}
+};
+/** Owns one process-local execution lease per session while leaving steer/abort on the control plane. */
 var EmbeddedRunRegistry = class {
 	bySessionKey = /* @__PURE__ */ new Map();
-	byRunId = /* @__PURE__ */ new Map();
-	/**
-	* Register a new in-flight run. If a run is already registered for the same
-	* sessionKey we drop the stale handle (the new run takes ownership). The caller
-	* is responsible for aborting the previous run before re-registering if needed —
-	* we warn loudly so this does not happen silently.
-	*/
-	register(handle) {
-		const previous = this.bySessionKey.get(handle.sessionKey);
-		if (previous && previous !== handle) {
-			log.warn({
-				sessionKey: handle.sessionKey,
-				previousRunId: previous.runId,
-				newRunId: handle.runId
-			}, "Replacing already-registered embedded run for sessionKey (caller did not unregister first)");
-			this.byRunId.delete(previous.runId);
-		}
-		this.bySessionKey.set(handle.sessionKey, handle);
-		this.byRunId.set(handle.runId, handle);
-	}
-	unregister(handle) {
-		if (this.bySessionKey.get(handle.sessionKey) === handle) this.bySessionKey.delete(handle.sessionKey);
-		this.byRunId.delete(handle.runId);
+	acquire(identity) {
+		const active = this.bySessionKey.get(identity.sessionKey);
+		if (active) throw new EmbeddedRunConflictError(identity.sessionKey, active.runId);
+		const entry = {
+			...identity,
+			abortController: new AbortController()
+		};
+		this.bySessionKey.set(identity.sessionKey, entry);
+		return {
+			signal: entry.abortController.signal,
+			attach: async (session, abort) => {
+				entry.handle = {
+					...identity,
+					session,
+					abort
+				};
+				if (entry.abortController.signal.aborted) await abort();
+			},
+			release: () => {
+				if (this.bySessionKey.get(identity.sessionKey) === entry) this.bySessionKey.delete(identity.sessionKey);
+			}
+		};
 	}
 	getBySessionKey(sessionKey) {
-		return this.bySessionKey.get(sessionKey);
-	}
-	getByRunId(runId) {
-		return this.byRunId.get(runId);
+		return this.bySessionKey.get(sessionKey)?.handle;
 	}
 	async abortBySessionKey(sessionKey) {
-		const handle = this.bySessionKey.get(sessionKey);
-		if (!handle) return false;
-		await handle.abort();
+		const entry = this.bySessionKey.get(sessionKey);
+		if (!entry) return false;
+		entry.abortController.abort(/* @__PURE__ */ new Error("Embedded run aborted"));
+		if (entry.handle) await entry.handle.abort();
 		return true;
 	}
 	async steerBySessionKey(sessionKey, text) {
-		const handle = this.bySessionKey.get(sessionKey);
+		const handle = this.getBySessionKey(sessionKey);
 		if (!handle) return false;
 		await handle.session.steer(text);
 		return true;
 	}
-	/** Test-only helper to drop all registrations without touching live sessions. */
-	resetForTest() {
-		this.bySessionKey.clear();
-		this.byRunId.clear();
-	}
 	size() {
 		return this.bySessionKey.size;
 	}
 };
-/**
-* Process-wide default registry. Prefer constructing a dedicated `EmbeddedRunRegistry`
-* and injecting it; the module-level singleton stays so the existing free functions
-* keep working until every caller has been migrated.
-*/
-const defaultEmbeddedRunRegistry = new EmbeddedRunRegistry();
-function registerEmbeddedRun(handle) {
-	defaultEmbeddedRunRegistry.register(handle);
-}
-function unregisterEmbeddedRun(handle) {
-	defaultEmbeddedRunRegistry.unregister(handle);
+const embeddedRunRegistry = new EmbeddedRunRegistry();
+function acquireEmbeddedRunLease(identity) {
+	return embeddedRunRegistry.acquire(identity);
 }
 function getEmbeddedRunBySessionKey(sessionKey) {
-	return defaultEmbeddedRunRegistry.getBySessionKey(sessionKey);
-}
-function getEmbeddedRunByRunId(runId) {
-	return defaultEmbeddedRunRegistry.getByRunId(runId);
+	return embeddedRunRegistry.getBySessionKey(sessionKey);
 }
 function abortEmbeddedRun(sessionKey) {
-	return defaultEmbeddedRunRegistry.abortBySessionKey(sessionKey);
+	return embeddedRunRegistry.abortBySessionKey(sessionKey);
 }
 function queueEmbeddedSteer(sessionKey, text) {
-	return defaultEmbeddedRunRegistry.steerBySessionKey(sessionKey, text);
+	return embeddedRunRegistry.steerBySessionKey(sessionKey, text);
 }
 //#endregion
-export { EmbeddedRunRegistry, abortEmbeddedRun, defaultEmbeddedRunRegistry, getEmbeddedRunByRunId, getEmbeddedRunBySessionKey, queueEmbeddedSteer, registerEmbeddedRun, unregisterEmbeddedRun };
+export { EmbeddedRunConflictError, EmbeddedRunRegistry, abortEmbeddedRun, acquireEmbeddedRunLease, getEmbeddedRunBySessionKey, queueEmbeddedSteer };

package/dist/src/agent/embedded/types.d.ts

@@ -2,6 +2,7 @@ import type { AgentMessage, AgentToolResult, ThinkingLevel } from '@earendil-wor
 import type { AssistantMessageEvent, Model, Api, ImageContent } from '@earendil-works/pi-ai';
 import type { SessionStore } from '../../session/store.js';
 import type { EmbeddedTranscriptRuntime } from './transcript-runtime.js';
+import type { AgentTurnPolicy } from '../orchestration/agent-turn-policy.js';
 export type EmbeddedStreamEvent = {
     type: 'agent_start';
     runId?: string;
@@ -97,6 +98,7 @@ export type RunXopcEmbeddedTurnParams = {
     sessionStore?: SessionStore;
     transcriptRuntime?: EmbeddedTranscriptRuntime;
     timeoutMs: number;
+    turnPolicy?: AgentTurnPolicy;
     abortSignal?: AbortSignal;
     onEvent?: (event: EmbeddedStreamEvent) => void;
     images?: ImageContent[];
@@ -105,6 +107,8 @@ export type RunXopcEmbeddedTurnParams = {
 };
 export type RunXopcEmbeddedTurnResult = {
     ok: boolean;
+    /** False for harness failures that must not trigger another model attempt. */
+    retryable?: boolean;
     errorMessage?: string;
     lastAssistantText?: string;
 };

package/dist/src/agent/image/tool-model-config.js

@@ -1,7 +1,7 @@
 import { getAgentDefaultImageModelConfig, getAgentDefaultModelRef, init_schema, parseModelRef } from "../../config/schema.js";
 import { init_agent_scope, resolveDefaultAgentId } from "../agent-scope.js";
-import { getDefaultModelSync, getModelsByProvider, init_providers, isProviderConfiguredSync, resolveModel } from "../../providers/index.js";
 import { resolveEffectiveAgentManifestForAgent } from "../../config/agent-profile.js";
+import { getDefaultModelSync, getModelsByProvider, init_providers, isProviderConfiguredSync, resolveModel } from "../../providers/index.js";
 import { resolveAgentModelFallbackValues, resolveAgentModelPrimaryValue } from "../../config/model-input.js";
 import { buildCapabilityPlansForConfig } from "../../capabilities/readiness/from-config.js";
 import "../../capabilities/readiness/index.js";

package/dist/src/agent/ipc/inbox.js

@@ -1,7 +1,7 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
-import { init_write_file_atomic, writeTextAtomic } from "../../infra/write-file-atomic.js";
 import { init_paths, resolveAgentDir } from "../../config/paths.js";
+import { init_write_file_atomic, writeTextAtomic } from "../../infra/write-file-atomic.js";
 import { join } from "path";
 import { existsSync, watch } from "fs";
 import { mkdir, readFile, readdir, rename } from "fs/promises";

package/dist/src/agent/memory/create-memory-manager.js

@@ -1,8 +1,8 @@
-import { buildMemoryRuntime } from "../../agent-runtime/memory-runtime.js";
 import { isMemorySubsystemEnabled } from "./memory-config.js";
 import { BuiltinMemoryProvider } from "./builtin-provider.js";
 import { MemoryManager } from "./manager.js";
 import { loadMemoryPluginProviders } from "./plugin-discovery.js";
+import { buildMemoryRuntime } from "../../agent-runtime/memory-runtime.js";
 //#region src/agent/memory/create-memory-manager.ts
 function createMemoryManagerFromConfig(config) {
 	const routing = resolveMemoryManagerOptions(config);

package/dist/src/agent/orchestration/agent-run-supervisor.d.ts

@@ -0,0 +1,28 @@
+export type ModelAttemptPlan = {
+    ok: true;
+    timeoutMs: number;
+    remainingMs: number;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface AgentRunSupervisorOptions {
+    timeoutMs: number;
+    deadlineAtMs?: number;
+    parentSignal?: AbortSignal;
+    minimumFallbackMs?: number;
+}
+/** Minimal run-level coordination: root cancellation and per-attempt deadline planning. */
+export declare class AgentRunSupervisor {
+    readonly deadlineAtMs: number;
+    readonly signal: AbortSignal;
+    private readonly controller;
+    private readonly timeout;
+    private readonly forwardParentAbort;
+    private readonly timeoutMs;
+    private readonly minimumFallbackMs;
+    private readonly parentSignal?;
+    constructor(options: AgentRunSupervisorOptions);
+    planModelAttempt(isFallback: boolean): ModelAttemptPlan;
+    dispose(): void;
+}

package/dist/src/agent/orchestration/agent-run-supervisor.js

@@ -0,0 +1,49 @@
+//#region src/agent/orchestration/agent-run-supervisor.ts
+/** Minimal run-level coordination: root cancellation and per-attempt deadline planning. */
+var AgentRunSupervisor = class {
+	deadlineAtMs;
+	signal;
+	controller = new AbortController();
+	timeout;
+	forwardParentAbort;
+	timeoutMs;
+	minimumFallbackMs;
+	parentSignal;
+	constructor(options) {
+		this.timeoutMs = options.timeoutMs;
+		this.minimumFallbackMs = options.minimumFallbackMs ?? 5e3;
+		this.deadlineAtMs = options.deadlineAtMs ?? Date.now() + options.timeoutMs;
+		this.parentSignal = options.parentSignal;
+		this.signal = this.controller.signal;
+		this.forwardParentAbort = () => this.controller.abort(this.parentSignal?.reason);
+		if (this.parentSignal?.aborted) this.forwardParentAbort();
+		else this.parentSignal?.addEventListener("abort", this.forwardParentAbort, { once: true });
+		this.timeout = setTimeout(() => this.controller.abort(/* @__PURE__ */ new Error("Agent run deadline expired")), Math.max(0, this.deadlineAtMs - Date.now()));
+	}
+	planModelAttempt(isFallback) {
+		if (this.signal.aborted) return {
+			ok: false,
+			reason: "Agent run aborted"
+		};
+		const remainingMs = this.deadlineAtMs - Date.now();
+		if (remainingMs <= 0) return {
+			ok: false,
+			reason: "Agent run deadline expired before the next model attempt"
+		};
+		if (isFallback && remainingMs < this.minimumFallbackMs) return {
+			ok: false,
+			reason: "Agent run deadline left too little time for a fallback model attempt"
+		};
+		return {
+			ok: true,
+			remainingMs,
+			timeoutMs: Math.max(1, Math.min(this.timeoutMs, remainingMs))
+		};
+	}
+	dispose() {
+		clearTimeout(this.timeout);
+		this.parentSignal?.removeEventListener("abort", this.forwardParentAbort);
+	}
+};
+//#endregion
+export { AgentRunSupervisor };

package/dist/src/agent/orchestration/agent-turn-policy.d.ts

@@ -0,0 +1,18 @@
+import type { AfterToolCallContext, BeforeToolCallContext, BeforeToolCallResult, ShouldStopAfterTurnContext } from '@earendil-works/pi-agent-core';
+export interface AgentTurnPolicy {
+    reset(): void;
+    beforeToolCall(context: BeforeToolCallContext, signal?: AbortSignal): Promise<BeforeToolCallResult | undefined>;
+    afterToolCall(context: AfterToolCallContext): Promise<undefined>;
+    shouldStopAfterTurn(context: ShouldStopAfterTurnContext): boolean;
+}
+export interface AgentTurnPolicyOptions {
+    maxTurns?: number;
+    maxToolFailures?: number;
+    resolveToolLimit?: (toolName: string, args: unknown) => {
+        id: string;
+        maxCalls: number;
+    } | undefined;
+    authorizeToolCall?: (context: BeforeToolCallContext, signal?: AbortSignal) => Promise<BeforeToolCallResult | undefined>;
+}
+/** One user-visible run policy. A fresh instance is created for every embedded run. */
+export declare function createAgentTurnPolicy(options: AgentTurnPolicyOptions): AgentTurnPolicy;

package/dist/src/agent/orchestration/agent-turn-policy.js

@@ -0,0 +1,36 @@
+//#region src/agent/orchestration/agent-turn-policy.ts
+function assistantMessageCount(messages) {
+	return messages.filter((message) => message.role === "assistant").length;
+}
+/** One user-visible run policy. A fresh instance is created for every embedded run. */
+function createAgentTurnPolicy(options) {
+	const toolCalls = /* @__PURE__ */ new Map();
+	let toolFailures = 0;
+	return {
+		reset() {
+			toolCalls.clear();
+			toolFailures = 0;
+		},
+		async beforeToolCall(context, signal) {
+			const limit = options.resolveToolLimit?.(context.toolCall.name, context.args);
+			if (limit) {
+				const count = (toolCalls.get(limit.id) ?? 0) + 1;
+				toolCalls.set(limit.id, count);
+				if (count > limit.maxCalls) return {
+					block: true,
+					terminate: true,
+					reason: `${limit.id} exceeded its per-turn call limit.`
+				};
+			}
+			return options.authorizeToolCall?.(context, signal);
+		},
+		async afterToolCall(context) {
+			if (context.isError) toolFailures += 1;
+		},
+		shouldStopAfterTurn(context) {
+			return Boolean(options.maxTurns && assistantMessageCount(context.newMessages) >= options.maxTurns || options.maxToolFailures && toolFailures >= options.maxToolFailures);
+		}
+	};
+}
+//#endregion
+export { createAgentTurnPolicy };

package/dist/src/agent/orchestration/llm-turn-retry.d.ts

@@ -6,6 +6,8 @@
  */
 import type { Agent, AgentMessage } from '@earendil-works/pi-agent-core';
 export declare function isTransientLlmErrorMessage(message: string): boolean;
+export type LlmFailureKind = 'transient_network' | 'context_overflow' | 'aborted' | 'permanent';
+export declare function classifyLlmFailure(message: string): LlmFailureKind;
 export declare function getLastAssistantMessage(messages: AgentMessage[]): AgentMessage | undefined;
 /** Raw provider/LLM error from the last failed assistant message, if any. */
 export declare function getAssistantTurnErrorMessage(agent: Agent): string | undefined;
@@ -20,6 +22,9 @@ export declare function stripTrailingErrorAssistantMessages(messages: AgentMessa
 export interface RetryTransientTurnOptions {
     /** Extra turns after a failed assistant message (default 2). */
     maxContinues?: number;
+    /** Initial deterministic backoff. Each later retry doubles it. */
+    baseDelayMs?: number;
+    signal?: AbortSignal;
     sessionKey: string;
     log: {
         warn: (obj: Record<string, unknown>, msg: string) => void;

package/dist/src/agent/orchestration/llm-turn-retry.js

@@ -1,3 +1,4 @@
+import { isContextOverflowError } from "./context-overflow.js";
 //#region src/agent/orchestration/llm-turn-retry.ts
 const TRANSIENT_LLM_ERROR_SUBSTRINGS = [
 	"fetch failed",
@@ -16,6 +17,13 @@ function isTransientLlmErrorMessage(message) {
 	const lower = message.toLowerCase();
 	return TRANSIENT_LLM_ERROR_SUBSTRINGS.some((s) => lower.includes(s));
 }
+function classifyLlmFailure(message) {
+	const normalized = message.trim().toLowerCase();
+	if (normalized === "aborted" || normalized.includes("aborterror")) return "aborted";
+	if (isContextOverflowError(message)) return "context_overflow";
+	if (isTransientLlmErrorMessage(message)) return "transient_network";
+	return "permanent";
+}
 function getLastAssistantMessage(messages) {
 	for (let i = messages.length - 1; i >= 0; i--) if (messages[i].role === "assistant") return messages[i];
 }
@@ -56,32 +64,54 @@ function stripTrailingErrorAssistantMessages(messages) {
 	}
 	return out;
 }
+async function waitForRetryDelay(delayMs, signal) {
+	signal?.throwIfAborted();
+	if (delayMs <= 0) return;
+	await new Promise((resolve, reject) => {
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(signal?.reason ?? new DOMException("Aborted", "AbortError"));
+		};
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, delayMs);
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
 /**
 * After waitForIdle(), call this to optionally re-run the last user turn when the
 * assistant message only contains a transient provider/network error.
 */
 async function maybeRetryTurnAfterTransientLlmFailure(agent, options) {
 	const maxContinues = options.maxContinues ?? 2;
+	const baseDelayMs = Math.max(0, options.baseDelayMs ?? 300);
 	let continues = 0;
 	while (continues < maxContinues) {
 		const last = getLastAssistantMessage(agent.state.messages);
 		if (!last) return;
 		if (last.stopReason !== "error") return;
 		const errMsg = String(last.errorMessage || "");
-		if (!isTransientLlmErrorMessage(errMsg)) {
+		const failureKind = classifyLlmFailure(errMsg);
+		if (failureKind !== "transient_network") {
 			options.log.warn({
 				sessionKey: options.sessionKey,
-				errorMessage: errMsg
+				errorMessage: errMsg,
+				failureKind
 			}, "Assistant turn ended with error (not retrying as transient)");
 			return;
 		}
 		continues += 1;
+		const retryDelayMs = baseDelayMs * 2 ** (continues - 1);
 		options.log.warn({
 			sessionKey: options.sessionKey,
 			errorMessage: errMsg,
+			failureKind,
 			continueAttempt: continues,
-			maxContinues
+			maxContinues,
+			retryDelayMs
 		}, "LLM request failed with a transient network error; retrying the same turn. If this persists, check outbound HTTPS to the provider API and HTTP(S)_PROXY.");
+		await waitForRetryDelay(retryDelayMs, options.signal);
 		const trimmed = stripTrailingErrorAssistantMessages(agent.state.messages);
 		agent.state.messages = trimmed;
 		await agent.continue();
@@ -89,4 +119,4 @@ async function maybeRetryTurnAfterTransientLlmFailure(agent, options) {
 	}
 }
 //#endregion
-export { getAssistantTurnErrorMessage, getLastAssistantMessage, isAssistantTurnAborted, isAssistantTurnFailed, isTransientLlmErrorMessage, maybeRetryTurnAfterTransientLlmFailure, stripTrailingErrorAssistantMessages };
+export { classifyLlmFailure, getAssistantTurnErrorMessage, getLastAssistantMessage, isAssistantTurnAborted, isAssistantTurnFailed, isTransientLlmErrorMessage, maybeRetryTurnAfterTransientLlmFailure, stripTrailingErrorAssistantMessages };

package/dist/src/agent/orchestration/run-agent-turn-with-timeout.d.ts

@@ -10,6 +10,15 @@ export declare const MIN_AGENT_TURN_TIMEOUT_MS = 60000;
 export declare const MAX_AGENT_TURN_TIMEOUT_MS: number;
 /** Default per-turn timeout (30 minutes). */
 export declare const DEFAULT_AGENT_TURN_TIMEOUT_MS: number;
+export declare const DEFAULT_AGENT_ABORT_GRACE_MS = 5000;
+export declare class AgentTurnUnsettledError extends Error {
+    readonly timeoutMs: number;
+    readonly abortGraceMs: number;
+    constructor(timeoutMs: number, abortGraceMs: number);
+}
+export declare function isAgentTurnUnsettledError(err: unknown): err is AgentTurnUnsettledError;
 export declare function resolveAgentTurnTimeoutMs(config?: Config, sessionKey?: string): number;
 export declare function isAgentTurnTimeoutError(err: unknown): boolean;
-export declare function runAgentTurnWithTimeout(agent: Agent, runTurn: () => Promise<void>, timeoutMs: number): Promise<void>;
+export declare function runAgentTurnWithTimeout(agent: Agent, runTurn: () => Promise<void>, timeoutMs: number, options?: {
+    abortGraceMs?: number;
+}): Promise<void>;

package/dist/src/agent/orchestration/run-agent-turn-with-timeout.js

@@ -6,6 +6,18 @@ const MIN_AGENT_TURN_TIMEOUT_MS = 6e4;
 const MAX_AGENT_TURN_TIMEOUT_MS = 14400 * 1e3;
 /** Default per-turn timeout (30 minutes). */
 const DEFAULT_AGENT_TURN_TIMEOUT_MS = 1800 * 1e3;
+const DEFAULT_AGENT_ABORT_GRACE_MS = 5e3;
+var AgentTurnUnsettledError = class extends Error {
+	constructor(timeoutMs, abortGraceMs) {
+		super(`Agent turn timed out after ${timeoutMs / 1e3}s and did not settle within ${abortGraceMs / 1e3}s`);
+		this.timeoutMs = timeoutMs;
+		this.abortGraceMs = abortGraceMs;
+		this.name = "AgentTurnUnsettledError";
+	}
+};
+function isAgentTurnUnsettledError(err) {
+	return err instanceof AgentTurnUnsettledError;
+}
 function resolveAgentTurnTimeoutMs(config, sessionKey) {
 	if (!config) return DEFAULT_AGENT_TURN_TIMEOUT_MS;
 	const configured = resolveEffectiveAgentManifestForSession(config, sessionKey).runtime?.timeoutMs;
@@ -15,22 +27,31 @@ function resolveAgentTurnTimeoutMs(config, sessionKey) {
 function isAgentTurnTimeoutError(err) {
 	return err instanceof Error && err.message.startsWith("Agent turn timed out after");
 }
-async function runAgentTurnWithTimeout(agent, runTurn, timeoutMs) {
+async function runAgentTurnWithTimeout(agent, runTurn, timeoutMs, options = {}) {
 	let timeoutId;
 	const timeoutPromise = new Promise((_, reject) => {
 		timeoutId = setTimeout(() => reject(/* @__PURE__ */ new Error(`Agent turn timed out after ${timeoutMs / 1e3}s`)), timeoutMs);
 	});
+	const runTurnPromise = Promise.resolve().then(runTurn);
 	try {
-		await Promise.race([runTurn().finally(() => {
+		await Promise.race([runTurnPromise.finally(() => {
 			if (timeoutId !== void 0) clearTimeout(timeoutId);
 		}), timeoutPromise]);
 	} catch (err) {
 		if (isAgentTurnTimeoutError(err)) {
 			agent.abort();
-			await agent.waitForIdle();
+			const abortGraceMs = options.abortGraceMs ?? 5e3;
+			let graceTimer;
+			try {
+				await Promise.race([Promise.allSettled([runTurnPromise, agent.waitForIdle()]), new Promise((_, reject) => {
+					graceTimer = setTimeout(() => reject(new AgentTurnUnsettledError(timeoutMs, abortGraceMs)), abortGraceMs);
+				})]);
+			} finally {
+				if (graceTimer !== void 0) clearTimeout(graceTimer);
+			}
 		}
 		throw err;
 	}
 }
 //#endregion
-export { DEFAULT_AGENT_TURN_TIMEOUT_MS, MAX_AGENT_TURN_TIMEOUT_MS, MIN_AGENT_TURN_TIMEOUT_MS, isAgentTurnTimeoutError, resolveAgentTurnTimeoutMs, runAgentTurnWithTimeout };
+export { AgentTurnUnsettledError, DEFAULT_AGENT_ABORT_GRACE_MS, DEFAULT_AGENT_TURN_TIMEOUT_MS, MAX_AGENT_TURN_TIMEOUT_MS, MIN_AGENT_TURN_TIMEOUT_MS, isAgentTurnTimeoutError, isAgentTurnUnsettledError, resolveAgentTurnTimeoutMs, runAgentTurnWithTimeout };

package/dist/src/agent/service/async-queue.d.ts

@@ -3,15 +3,28 @@
  *
  * Replaces the ad-hoc `eventQueue + resolveWaiting` single-slot pattern that
  * the streaming direct turn used to manage run events. The previous pattern was
- * lossy if two pushes landed before the single waiter resumed; this queue keeps
- * the buffer growing until consumed, and closes cleanly so the iterator drains.
+ * lossy if two pushes landed before the single waiter resumed; this queue buffers
+ * until consumed, supports an explicit bound, and drains cleanly on close.
  */
+export interface AsyncQueueOptions<T> {
+    /** Maximum buffer size. Lossy events are evicted; critical-only overflow fails fast. */
+    maxBuffered?: number;
+    isDroppable?: (value: T) => boolean;
+}
+export declare class AsyncQueueOverflowError extends Error {
+    readonly maxBuffered: number;
+    constructor(maxBuffered: number);
+}
 export declare class AsyncQueue<T> implements AsyncIterable<T> {
+    private readonly options;
     private readonly buffer;
     private readonly waiters;
     private closed;
+    private dropped;
+    constructor(options?: AsyncQueueOptions<T>);
     /** Push a value to the queue. No-op when the queue is closed. */
-    push(value: T): void;
+    push(value: T): boolean;
+    get droppedCount(): number;
     /** Close the queue. Pending iterators drain any buffered values and then complete. */
     close(): void;
     /** True if the queue is closed and the internal buffer is drained. */

package/dist/src/agent/service/async-queue.js

@@ -1,25 +1,43 @@
 //#region src/agent/service/async-queue.ts
-/**
-* Async FIFO queue with `for await` support.
-*
-* Replaces the ad-hoc `eventQueue + resolveWaiting` single-slot pattern that
-* the streaming direct turn used to manage run events. The previous pattern was
-* lossy if two pushes landed before the single waiter resumed; this queue keeps
-* the buffer growing until consumed, and closes cleanly so the iterator drains.
-*/
+var AsyncQueueOverflowError = class extends Error {
+	constructor(maxBuffered) {
+		super(`Async queue exceeded its ${maxBuffered}-event buffer`);
+		this.maxBuffered = maxBuffered;
+		this.name = "AsyncQueueOverflowError";
+	}
+};
 var AsyncQueue = class {
 	buffer = [];
 	waiters = [];
 	closed = false;
+	dropped = 0;
+	constructor(options = {}) {
+		this.options = options;
+	}
 	/** Push a value to the queue. No-op when the queue is closed. */
 	push(value) {
-		if (this.closed) return;
+		if (this.closed) return false;
 		const waiter = this.waiters.shift();
 		if (waiter) {
 			waiter(value);
-			return;
+			return true;
+		}
+		const maxBuffered = this.options.maxBuffered;
+		if (maxBuffered && this.buffer.length >= maxBuffered) {
+			const droppableIndex = this.options.isDroppable ? this.buffer.findIndex(this.options.isDroppable) : -1;
+			if (droppableIndex >= 0) {
+				this.buffer.splice(droppableIndex, 1);
+				this.dropped += 1;
+			} else if (this.options.isDroppable?.(value)) {
+				this.dropped += 1;
+				return false;
+			} else throw new AsyncQueueOverflowError(maxBuffered);
 		}
 		this.buffer.push(value);
+		return true;
+	}
+	get droppedCount() {
+		return this.dropped;
 	}
 	/** Close the queue. Pending iterators drain any buffered values and then complete. */
 	close() {
@@ -48,4 +66,4 @@ var AsyncQueue = class {
 };
 const CLOSE_SENTINEL = Symbol("AsyncQueue.close");
 //#endregion
-export { AsyncQueue };
+export { AsyncQueue, AsyncQueueOverflowError };