@oh-my-pi/pi-agent-core 18.16.0 → 18.17.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+## [18.17.0] - 2026-11-06
+
+### Added
+
+- Added `Agent.queuedMessageGate` to filter queued messages before delivery and observe claimed messages returned undelivered.
+- Added `wireToolsFingerprint()`, returning a hash of the tool specs sent with a request.
+
 ## [18.16.0] - 2026-11-02
 
 ### Changed

package/dist/types/agent-loop.d.ts

@@ -102,6 +102,8 @@ export declare function normalizeMessagesForProvider(messages: Context["messages
 export interface NormalizeToolsOptions {
     /** Inject the `i` intent field into tool schemas (subject to `PI_NO_INTENT`). */
     injectIntent: boolean;
+    /** Schema description of the injected `i` field; `PI_INTENT_DESC` overrides it. Default `concise intent`. */
+    intentDescription?: string;
     /** Strip descriptions from the wire specs when the catalog rides in the system prompt. */
     pruneDescriptions?: boolean;
 }

package/dist/types/agent.d.ts

@@ -4,7 +4,7 @@ import type { HarmonyAuditEvent } from "@oh-my-pi/pi-ai/utils/harmony-leak";
 import type { AppendOnlyContextManager } from "./append-only-context.js";
 import { SentToolDefinitions } from "./sent-tool-definitions.js";
 import { Tokenizer } from "./tokenizer.js";
-import type { AgentBeforeModelCall, AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, AgentState, AgentTool, AgentToolContext, AgentTurnEndContext, AsideBoundary, AsideMessage, PrepareQueuedMessages, SpeculativeToolExecutionConfig, StreamFn, ToolCallContext, ToolChoiceDirective } from "./types.js";
+import type { AgentBeforeModelCall, AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, AgentState, AgentTool, AgentToolContext, AgentTurnEndContext, AsideBoundary, AsideMessage, PrepareQueuedMessages, QueuedMessageGate, SpeculativeToolExecutionConfig, StreamFn, ToolCallContext, ToolChoiceDirective } from "./types.js";
 export declare class AgentBusyError extends Error {
     constructor(message?: string);
 }
@@ -157,6 +157,8 @@ export interface AgentOptions {
     suggestFallbackToolNames?: () => Iterable<string>;
     /** Enable intent tracing schema injection/stripping in the harness. */
     intentTracing?: boolean;
+    /** Schema description of the injected intent field; `PI_INTENT_DESC` overrides it. Default `concise intent`. */
+    intentDescription?: string;
     /**
      * Strip tool descriptions from provider-bound tool specs (top-level + nested
      * schema annotations). Use when the full catalog is rendered into the system
@@ -252,6 +254,12 @@ export declare class Agent {
     getApiKey?: (model: Model) => Promise<ApiKey | undefined> | ApiKey | undefined;
     /** Prepare actual queue deliveries after dequeue gates; commit runs only while ownership remains valid. */
     prepareQueuedMessages?: PrepareQueuedMessages;
+    /**
+     * Consulted synchronously whenever queued messages are removed for delivery and
+     * told about claimed messages that went back undelivered (see {@link QueuedMessageGate}).
+     * Unset, batches are taken as they are.
+     */
+    queuedMessageGate?: QueuedMessageGate;
     /**
      * Hook invoked after tool arguments are validated and before execution.
      * Reassign at any time to swap the implementation (e.g. on extension reload).
@@ -405,6 +413,8 @@ export declare class Agent {
     /** Inject/strip the intent field on tool calls; applies from the next prompt run. */
     get intentTracing(): boolean;
     set intentTracing(value: boolean);
+    /** The intent field's schema description this agent was built with (`PI_INTENT_DESC` still overrides it). */
+    get intentDescription(): string | undefined;
     /** Abort the provider request on a fabricated tool result; applies from the next prompt run. */
     get abortOnFabricatedToolResult(): boolean | undefined;
     set abortOnFabricatedToolResult(value: boolean | undefined);

package/dist/types/append-only-context.d.ts

@@ -25,6 +25,8 @@ export interface StablePrefixSnapshot {
 export interface BuildOptions {
     /** Inject the `i` intent field into tool schemas (must match agent-loop's normalizeTools). */
     intentTracing: boolean;
+    /** Schema description of the injected `i` field (must match agent-loop's normalizeTools). */
+    intentDescription?: string;
     /** Strip tool descriptions from the provider-bound specs (must match normalizeTools). */
     pruneToolDescriptions?: boolean;
 }
@@ -125,3 +127,10 @@ export declare class AppendOnlyContextManager {
     invalidate(): void;
     reset(context: AgentContext, options: BuildOptions): void;
 }
+/**
+ * Fingerprint of the tool specs a request built with `options` sends: the
+ * tools half of the prefix fingerprint, for a caller that compares tool sets
+ * across requests. A same-name tool whose description, schema, examples,
+ * `strict`, `customFormat` or `customWireName` changed makes another one.
+ */
+export declare function wireToolsFingerprint(tools: AgentContext["tools"], options: BuildOptions): string;

package/dist/types/telemetry.d.ts

@@ -558,7 +558,9 @@ export interface InstrumentedChatSpanOptions {
  * Short-circuits when `telemetry` is `undefined` so cost / overhead stays at
  * zero for installations without an OTEL SDK.
  */
-export declare function instrumentedCompleteSimple<TApi extends Api>(model: Model<TApi>, ctx: Context, options: SimpleStreamOptions, span: InstrumentedChatSpanOptions): Promise<AssistantMessage>;
+export declare function instrumentedCompleteSimple<TApi extends Api>(model: Model<TApi>, ctx: Context, options: SimpleStreamOptions & {
+    onAttempt?: (message: AssistantMessage) => void;
+}, span: InstrumentedChatSpanOptions): Promise<AssistantMessage>;
 /**
  * Start an `execute_tool` span representing one tool invocation. Parented
  * under the supplied `invoke_agent` span by default — pass `parent` to

package/dist/types/types.d.ts

@@ -16,6 +16,21 @@ export interface QueuedMessagePreparation {
 export type QueuedMessageQueue = "steering" | "followUp";
 /** Prepare an exclusively claimed batch. Undefined delivers unchanged; the signal also aborts when the claim is cancelled. */
 export type PrepareQueuedMessages = (messages: readonly AgentMessage[], signal: AbortSignal, queue: QueuedMessageQueue) => QueuedMessagePreparation | undefined | Promise<QueuedMessagePreparation | undefined>;
+/**
+ * Synchronous arbiter over queued messages leaving a queue for delivery, for a
+ * queue whose messages someone else may withdraw concurrently (a session homed
+ * on another thread whose view pops them).
+ */
+export interface QueuedMessageGate {
+    /**
+     * Called with the batch about to be removed from `queue` for delivery; returns
+     * the candidates that must be dropped from the queue instead. The others are
+     * claimed for delivery.
+     */
+    claim(queue: QueuedMessageQueue, candidates: readonly AgentMessage[]): readonly AgentMessage[];
+    /** Called with claimed messages that left delivery undelivered (requeued, withdrawn, or cancelled). */
+    release(messages: readonly AgentMessage[]): void;
+}
 /** Called once an aside has been inserted into the agent's live context. */
 export declare const ASIDE_MESSAGE_COMMIT: unique symbol;
 /** Symbol-keyed handoff for one finalized, tool-owned stream speculation session. */
@@ -218,6 +233,8 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * never consumes the queue.
      */
     getSteeringMessages?: (signal?: AbortSignal) => Promise<AgentMessage[]>;
+    /** Whether input is still owned by a queue and must be restored if a model call is aborted before it starts. */
+    isUndeliveredQueuedMessage?: (message: AgentMessage) => boolean;
     /**
      * Peeks whether steering messages are queued, without consuming them.
      *
@@ -390,6 +407,8 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * then strips from arguments before executing tools.
      */
     intentTracing?: boolean;
+    /** Schema description of the injected intent field; `PI_INTENT_DESC` overrides it. Default `concise intent`. */
+    intentDescription?: string;
     /**
      * Strip tool descriptions (top-level + nested schema annotations) from the
      * provider-bound tool specs. Use when the full catalog is rendered into the

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-agent-core",
-	"version": "18.16.0",
+	"version": "18.17.0",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://omp.sh",
 	"author": {
@@ -31,25 +31,25 @@
 	"types": "./dist/types/index.d.ts",
 	"scripts": {
 		"check": "oxlint . && oxfmt --check --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts' && bun run check:types",
-		"check:types": "tsgo -p tsconfig.json --noEmit",
+		"check:types": "bun check --no-script -p tsconfig.json",
 		"lint": "oxlint .",
 		"test": "bun test --parallel",
 		"fix": "oxlint --fix --fix-suggestions . && bun run fmt",
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-ai": "18.16.0",
-		"@oh-my-pi/pi-catalog": "18.16.0",
-		"@oh-my-pi/pi-natives": "18.16.0",
-		"@oh-my-pi/pi-utils": "18.16.0",
-		"@oh-my-pi/pi-wire": "18.16.0",
-		"@oh-my-pi/snapcompact": "18.16.0",
+		"@oh-my-pi/pi-ai": "18.17.0",
+		"@oh-my-pi/pi-catalog": "18.17.0",
+		"@oh-my-pi/pi-natives": "18.17.0",
+		"@oh-my-pi/pi-utils": "18.17.0",
+		"@oh-my-pi/pi-wire": "18.17.0",
+		"@oh-my-pi/snapcompact": "18.17.0",
 		"@opentelemetry/api": "^1.9.1"
 	},
 	"devDependencies": {
-		"@oh-my-pi/omptype": "18.16.0",
-		"@opentelemetry/context-async-hooks": "^2.9.0",
-		"@opentelemetry/sdk-trace-base": "^2.9.0",
+		"@oh-my-pi/omptype": "18.17.0",
+		"@opentelemetry/context-async-hooks": "2.9.0",
+		"@opentelemetry/sdk-trace-base": "2.9.0",
 		"@types/bun": "^1.3.14"
 	},
 	"engines": {

package/src/agent-loop.ts

@@ -943,7 +943,7 @@ export function normalizeMessagesForProvider(
 	});
 }
 
-/** Schema description of the injected `i` field; `PI_INTENT_DESC` replaces it. */
+/** Schema description of the injected `i` field when neither `PI_INTENT_DESC` nor the caller sets one. */
 const DEFAULT_INTENT_FIELD_DESCRIPTION = "concise intent";
 const INTENT_SCHEMA_UNION_KEYS = ["anyOf", "oneOf"] as const;
 
@@ -954,26 +954,30 @@ const INTENT_SCHEMA_UNION_KEYS = ["anyOf", "oneOf"] as const;
 // the whole catalog per request). The injected object is shared across
 // requests — the same profile as the intent-off path, where parameters IS the
 // shared memoized wire schema (see schema-immutability.test.ts). One stamp
-// key per (mode, describeIntent) variant; index 0 = bare, 1 = described.
-const INTENT_STAMPS = {
-	require: [Symbol("intent:require"), Symbol("intent:require:described")],
-	optional: [Symbol("intent:optional"), Symbol("intent:optional:described")],
-} as const;
+// key per (mode, description) variant, "" keying the bare one: agents in one
+// process may describe `i` differently over the same shared tool schemas.
+const INTENT_STAMPS = { require: new Map<string, symbol>(), optional: new Map<string, symbol>() } as const;
 
 function memoizedInjectIntentIntoSchema(
 	schema: Record<string, unknown>,
 	mode: "require" | "optional",
-	describeIntent: boolean,
+	description: string | undefined,
 ): unknown {
-	return stamp(schema, INTENT_STAMPS[mode][describeIntent ? 1 : 0], host =>
-		injectIntentIntoSchema(host, mode, describeIntent),
-	);
+	const stamps = INTENT_STAMPS[mode];
+	const variant = description ?? "";
+	let key = stamps.get(variant);
+	if (!key) {
+		key = Symbol(`intent:${mode}`);
+		stamps.set(variant, key);
+	}
+	return stamp(schema, key, host => injectIntentIntoSchema(host, mode, description));
 }
 
+/** `schema` with the `i` field first (and required in `require` mode); `description` unset injects it bare. */
 function injectIntentIntoSchema(
 	schema: unknown,
-	mode: "require" | "optional" = "require",
-	describeIntent = true,
+	mode: "require" | "optional",
+	description: string | undefined,
 ): unknown {
 	if (!schema || typeof schema !== "object" || Array.isArray(schema)) return schema;
 	const schemaRecord = schema as Record<string, unknown>;
@@ -996,7 +1000,7 @@ function injectIntentIntoSchema(
 			if (!Array.isArray(variants)) continue;
 			return {
 				...schemaRecord,
-				[key]: variants.map(variant => injectIntentIntoSchema(variant, mode, describeIntent)),
+				[key]: variants.map(variant => injectIntentIntoSchema(variant, mode, description)),
 			};
 		}
 	}
@@ -1020,9 +1024,7 @@ function injectIntentIntoSchema(
 	return {
 		...schemaRecord,
 		properties: {
-			[INTENT_FIELD]: describeIntent
-				? { type: "string", description: Bun.env.PI_INTENT_DESC || DEFAULT_INTENT_FIELD_DESCRIPTION }
-				: { type: "string" },
+			[INTENT_FIELD]: description === undefined ? { type: "string" } : { type: "string", description },
 			...properties,
 		},
 		...(mode === "require" ? { required: [...required, INTENT_FIELD] } : {}),
@@ -1032,6 +1034,8 @@ function injectIntentIntoSchema(
 export interface NormalizeToolsOptions {
 	/** Inject the `i` intent field into tool schemas (subject to `PI_NO_INTENT`). */
 	injectIntent: boolean;
+	/** Schema description of the injected `i` field; `PI_INTENT_DESC` overrides it. Default `concise intent`. */
+	intentDescription?: string;
 	/** Strip descriptions from the wire specs when the catalog rides in the system prompt. */
 	pruneDescriptions?: boolean;
 }
@@ -1039,6 +1043,7 @@ export interface NormalizeToolsOptions {
 export function normalizeTools(tools: AgentContext["tools"], options: NormalizeToolsOptions): Context["tools"] {
 	const pruneDescriptions = options.pruneDescriptions === true;
 	const injectIntent = options.injectIntent && Bun.env.PI_NO_INTENT !== "1";
+	const intentDescription = Bun.env.PI_INTENT_DESC || options.intentDescription || DEFAULT_INTENT_FIELD_DESCRIPTION;
 	return tools?.map(t => {
 		const intentMode = resolveIntentMode(t.intent);
 		const doInjectIntent =
@@ -1047,17 +1052,19 @@ export function normalizeTools(tools: AgentContext["tools"], options: NormalizeT
 		// specs without their descriptions (top-level + nested schema annotations)
 		// so they are not duplicated on the wire. Strip the STABLE wire schema (the
 		// memoized `stripSchemaDescriptions` result is reused across requests), then
-		// re-inject `i` (without its hint, which `describeIntent: false` omits) so
+		// re-inject `i` (without its hint, which an unset description omits) so
 		// intent tracing keeps the field while no descriptions ride the wire.
 		if (pruneDescriptions) {
 			const stripped = stripSchemaDescriptions(toolWireSchema(t));
 			const parameters = (
-				doInjectIntent ? memoizedInjectIntentIntoSchema(stripped, intentMode, false) : stripped
+				doInjectIntent ? memoizedInjectIntentIntoSchema(stripped, intentMode, undefined) : stripped
 			) as TSchema;
 			return { ...t, parameters, description: "" };
 		}
 		const wire = toolWireSchema(t);
-		const parameters = (doInjectIntent ? memoizedInjectIntentIntoSchema(wire, intentMode, true) : wire) as TSchema;
+		const parameters = (
+			doInjectIntent ? memoizedInjectIntentIntoSchema(wire, intentMode, intentDescription) : wire
+		) as TSchema;
 		const description = t.description ?? "";
 		const examplesBlock = renderToolExamples({ ...t, parameters }, doInjectIntent ? INTENT_FIELD : undefined);
 		const finalDescription = examplesBlock ? `${description}\n\n${examplesBlock}` : description;
@@ -1240,6 +1247,25 @@ async function runLoopBody(
 	// `liveAccepted` reached the model inside it, `liveDeferred` did not.
 	let liveAccepted: AgentMessage[] = [];
 	let liveDeferred: AgentMessage[] = [];
+	const endAbortedBeforeModel = async (messages: AgentMessage[], turnOpen: boolean): Promise<boolean> => {
+		if (!signal?.aborted || !config.isUndeliveredQueuedMessage) return false;
+		const undelivered = new Set(messages.filter(message => config.isUndeliveredQueuedMessage?.(message)));
+		for (const list of [currentContext.messages, newMessages]) {
+			for (let i = list.length - 1; i >= 0; i--) {
+				if (undelivered.has(list[i])) list.splice(i, 1);
+			}
+		}
+		if (!turnOpen) stream.push({ type: "turn_start" });
+		emitInputMessages(
+			stream,
+			messages.filter(message => !undelivered.has(message)),
+		);
+		const aborted = emitAbortedAssistantMessage(null, false, new Set(), currentContext, config, stream, signal);
+		newMessages.push(aborted);
+		await emitTurnEnd(stream, currentContext, aborted, [], config, signal, { willContinue: false });
+		endAgentStream(stream, newMessages, telemetry, stepCounter.count);
+		return true;
+	};
 	try {
 		let messagesToEmit = [...initialMessages];
 		if (isDeadlineExceeded(config.deadline)) {
@@ -1253,6 +1279,7 @@ async function runLoopBody(
 		try {
 			pendingMessages = signal?.aborted ? [] : (await config.getSteeringMessages?.(signal)) || [];
 		} catch (error) {
+			if (signal?.aborted && (await endAbortedBeforeModel(messagesToEmit, false))) return;
 			stream.push({ type: "turn_start" });
 			emitInputMessages(stream, messagesToEmit);
 			throw error;
@@ -1351,10 +1378,19 @@ async function runLoopBody(
 
 				let preparedProviderCall: PreparedProviderCall;
 				let gateResult: AgentPreModelCallResult;
+				const emitTurnInputs = () => {
+					emitInputMessages(
+						stream,
+						signal?.aborted
+							? turnMessages.filter(message => !config.isUndeliveredQueuedMessage?.(message))
+							: turnMessages,
+					);
+				};
 				try {
 					if (config.syncContextBeforeModelCall) {
 						await config.syncContextBeforeModelCall(currentContext, signal);
 					}
+					if (signal?.aborted && (await endAbortedBeforeModel(turnMessages, turnOpen))) return;
 
 					if (!directiveResolvedForTurn) {
 						const directive = signal?.aborted ? undefined : config.getToolChoice?.();
@@ -1383,16 +1419,19 @@ async function runLoopBody(
 					}
 
 					preparedProviderCall = await prepareProviderCall(currentContext, config, signal);
+					if (signal?.aborted && (await endAbortedBeforeModel(turnMessages, turnOpen))) return;
 					preparedProviderCall.liveSteering = openLiveSteering(config, signal, preparedProviderCall);
 					gateResult = (await config.beforeModelCall?.(preparedProviderCall.context, signal)) || undefined;
 				} catch (error) {
+					if (signal?.aborted && (await endAbortedBeforeModel(turnMessages, turnOpen))) return;
 					if (!turnOpen) {
 						stream.push({ type: "turn_start" });
-						emitInputMessages(stream, turnMessages);
+						emitTurnInputs();
 						turnOpen = true;
 					}
 					throw error;
 				}
+				if (signal?.aborted && (await endAbortedBeforeModel(turnMessages, turnOpen))) return;
 				if (config.beforeModelCall && signal?.aborted) {
 					gateResult = { stop: true };
 				}
@@ -1436,13 +1475,13 @@ async function runLoopBody(
 
 				if (!turnOpen) {
 					stream.push({ type: "turn_start" });
-					emitInputMessages(stream, turnMessages);
 					turnOpen = true;
 				}
 
 				// Stream assistant response
 				let recovered: HarmonyRecoveredToolCall | undefined;
 				let message: AssistantMessage;
+				let inputsEmitted = false;
 				try {
 					if (agentPauseGate.paused) await waitForProcessPause(config, signal);
 					message = await streamAssistantResponse(
@@ -1458,6 +1497,11 @@ async function runLoopBody(
 						hostToolChoice,
 						softRequirementState.forcedToolChoice,
 						preparedProviderCall,
+						() => {
+							if (config.isUndeliveredQueuedMessage) signal?.throwIfAborted();
+							emitTurnInputs();
+							inputsEmitted = true;
+						},
 						message => {
 							const finalToolCalls = message.content.filter(
 								(content): content is Extract<AssistantMessage["content"][number], { type: "toolCall" }> =>
@@ -1484,6 +1528,10 @@ async function runLoopBody(
 					harmonyRetryAttempt = 0;
 					harmonyTruncateResumeCount = 0;
 				} catch (err) {
+					if (!inputsEmitted) {
+						if (signal?.aborted && (await endAbortedBeforeModel(turnMessages, turnOpen))) return;
+						emitTurnInputs();
+					}
 					if (!(err instanceof HarmonyLeakInterruption)) throw err;
 					if (err.recovered) {
 						if (harmonyTruncateResumeCount >= 2) {
@@ -1958,6 +2006,7 @@ async function prepareProviderCall(
 		config.appendOnlyContext.syncMessages(normalizedMessages);
 		llmContext = config.appendOnlyContext.build(context, {
 			intentTracing: !!config.intentTracing,
+			intentDescription: config.intentDescription,
 			pruneToolDescriptions,
 		});
 	} else {
@@ -1966,6 +2015,7 @@ async function prepareProviderCall(
 			messages: normalizedMessages,
 			tools: normalizeTools(context.tools, {
 				injectIntent: !!config.intentTracing,
+				intentDescription: config.intentDescription,
 				pruneDescriptions: pruneToolDescriptions,
 			}),
 		};
@@ -2012,6 +2062,7 @@ async function streamAssistantResponse(
 	hostToolChoice?: ToolChoice,
 	forcedToolChoice?: ToolChoice,
 	prepared?: PreparedProviderCall,
+	onProviderStart?: () => void,
 	canDispatchFinalToolCalls?: (message: AssistantMessage) => boolean,
 ): Promise<AssistantMessage> {
 	const providerCall = prepared ?? (await prepareProviderCall(context, config, signal));
@@ -2156,6 +2207,7 @@ async function streamAssistantResponse(
 
 	try {
 		return await runInActiveSpan(chatSpan, async () => {
+			onProviderStart?.();
 			let response = await streamFunction(model, llmContext, {
 				...config,
 				apiKey,

package/src/agent.ts

@@ -62,6 +62,7 @@ import type {
 	AsideBoundary,
 	AsideMessage,
 	PrepareQueuedMessages,
+	QueuedMessageGate,
 	QueuedMessageQueue,
 	SpeculativeToolExecutionConfig,
 	StreamFn,
@@ -279,6 +280,8 @@ export interface AgentOptions {
 
 	/** Enable intent tracing schema injection/stripping in the harness. */
 	intentTracing?: boolean;
+	/** Schema description of the injected intent field; `PI_INTENT_DESC` overrides it. Default `concise intent`. */
+	intentDescription?: string;
 	/**
 	 * Strip tool descriptions from provider-bound tool specs (top-level + nested
 	 * schema annotations). Use when the full catalog is rendered into the system
@@ -493,6 +496,7 @@ export class Agent {
 	#resolveFallbackTool?: (name: string, advertised: readonly AgentTool<any>[]) => AgentTool<any> | undefined;
 	#suggestFallbackToolNames?: () => Iterable<string>;
 	#intentTracing: boolean;
+	#intentDescription?: string;
 	#pruneToolDescriptions: boolean;
 	#dialect?: Dialect;
 	#dialectResolver?: (model: Model) => Dialect | undefined;
@@ -525,6 +529,12 @@ export class Agent {
 	getApiKey?: (model: Model) => Promise<ApiKey | undefined> | ApiKey | undefined;
 	/** Prepare actual queue deliveries after dequeue gates; commit runs only while ownership remains valid. */
 	prepareQueuedMessages?: PrepareQueuedMessages;
+	/**
+	 * Consulted synchronously whenever queued messages are removed for delivery and
+	 * told about claimed messages that went back undelivered (see {@link QueuedMessageGate}).
+	 * Unset, batches are taken as they are.
+	 */
+	queuedMessageGate?: QueuedMessageGate;
 	/**
 	 * Hook invoked after tool arguments are validated and before execution.
 	 * Reassign at any time to swap the implementation (e.g. on extension reload).
@@ -602,6 +612,7 @@ export class Agent {
 		this.#resolveFallbackTool = opts.resolveFallbackTool;
 		this.#suggestFallbackToolNames = opts.suggestFallbackToolNames;
 		this.#intentTracing = opts.intentTracing === true;
+		this.#intentDescription = opts.intentDescription;
 		this.#pruneToolDescriptions = opts.pruneToolDescriptions === true;
 		this.#dialect = opts.dialect;
 		this.#dialectResolver = opts.dialectResolver;
@@ -864,6 +875,11 @@ export class Agent {
 		this.#intentTracing = value;
 	}
 
+	/** The intent field's schema description this agent was built with (`PI_INTENT_DESC` still overrides it). */
+	get intentDescription(): string | undefined {
+		return this.#intentDescription;
+	}
+
 	/** Abort the provider request on a fabricated tool result; applies from the next prompt run. */
 	get abortOnFabricatedToolResult(): boolean | undefined {
 		return this.#abortOnFabricatedToolResult;
@@ -970,6 +986,7 @@ export class Agent {
 			? []
 			: (normalizeTools(this.#toolsForModel(model), {
 					injectIntent: this.#intentTracing,
+					intentDescription: this.#intentDescription,
 					pruneDescriptions: this.#pruneToolDescriptions,
 				}) ?? []);
 		let context: Context = { systemPrompt, messages, tools };
@@ -1042,12 +1059,14 @@ export class Agent {
 		const runController = this.#abortController;
 		if (!prepare) {
 			this.#queuedMessageDeliveries.add({ queue, controller: runController, messages, next: 0, additional: [] });
+			this.#emitQueueChanged();
 			return messages;
 		}
 
 		const claim: QueuedMessageClaim = { messages, controller: new AbortController() };
 		this.#queuedMessageClaims[queue] = claim;
 		const preparationSignal = AbortSignal.any([signal, claim.controller.signal]);
+		this.#emitQueueChanged();
 		try {
 			const preparation = await prepare(messages, preparationSignal, queue);
 			signal.throwIfAborted();
@@ -1067,6 +1086,7 @@ export class Agent {
 				next: 0,
 				additional: additional ?? [],
 			});
+			this.#emitQueueChanged();
 			return additional?.length ? [...messages, ...additional] : messages;
 		} catch (error) {
 			if (signal.aborted) throw error;
@@ -1086,6 +1106,7 @@ export class Agent {
 		const claim = this.#queuedMessageClaims[queue];
 		if (!claim) return;
 		delete this.#queuedMessageClaims[queue];
+		this.queuedMessageGate?.release(claim.messages);
 		if (restore) {
 			if (queue === "steering") {
 				this.#steeringQueue = [...claim.messages, ...this.#steeringQueue];
@@ -1104,6 +1125,7 @@ export class Agent {
 		// Live steering was taken before anything the run still holds undelivered.
 		this.#liveSteered = this.#liveSteered.filter(entry => {
 			if (entry.controller !== controller) return true;
+			if (entry.message.role === "user") delete entry.message.liveSteered;
 			restored.steering.push(entry.message);
 			return false;
 		});
@@ -1114,12 +1136,14 @@ export class Agent {
 				restored[delivery.queue].push(delivery.messages[i]);
 			}
 		}
+		if (restored.steering.length === 0 && restored.followUp.length === 0) return;
+		this.queuedMessageGate?.release([...restored.steering, ...restored.followUp]);
 		if (restored.steering.length > 0) {
 			this.#steeringQueue = [...restored.steering, ...this.#steeringQueue];
 			this.#notifySteeringWaiters();
 		}
 		if (restored.followUp.length > 0) this.#followUpQueue = [...restored.followUp, ...this.#followUpQueue];
-		if (restored.steering.length > 0 || restored.followUp.length > 0) this.#emitQueueChanged();
+		this.#emitQueueChanged();
 	}
 
 	/** Move steering live steering took out of the queue-delivery records into {@link #liveSteered}. */
@@ -1177,6 +1201,9 @@ export class Agent {
 			for (const message of [...pending, ...delivery.additional]) suppress(message, delivery.controller);
 		}
 		this.#queuedMessageDeliveries.clear();
+		if (withdrawn.steering.length > 0 || withdrawn.followUp.length > 0) {
+			this.queuedMessageGate?.release([...withdrawn.steering, ...withdrawn.followUp]);
+		}
 		if (hadLiveSteered) this.#emitQueueChanged();
 		return withdrawn;
 	}
@@ -1336,11 +1363,9 @@ export class Agent {
 		this.#state.messages = ms.slice();
 	}
 
-	/** Signal that the steering/follow-up queue contents may have changed. Every
-	 *  queue mutator below calls this once after mutating, so external layers
-	 *  (AgentSession's `queue_update` coalescing) have a single seam to observe
-	 *  enqueue, dequeue-on-delivery, clear, and restore without emits scattered
-	 *  across every call site that queues or dequeues a message. */
+	/** Signal after a queue transition has settled its pending, claim, and
+	 *  delivery state, so AgentSession's `queue_update` coalescing observes
+	 *  a consistent snapshot across enqueue, preparation, delivery, and restore. */
 	#emitQueueChanged(): void {
 		for (const listener of this.#queueListeners) {
 			try {
@@ -1507,6 +1532,19 @@ export class Agent {
 		return claim ? [...claim.messages, ...this.#steeringQueue] : this.#steeringQueue;
 	}
 
+	#isUndeliveredQueuedMessage(message: AgentMessage): boolean {
+		for (const entry of this.#liveSteered) {
+			if (entry.message === message || entry.additional?.includes(message)) return true;
+		}
+		for (const delivery of this.#queuedMessageDeliveries) {
+			if (delivery.additional.includes(message)) return true;
+			for (let i = delivery.next; i < delivery.messages.length; i++) {
+				if (delivery.messages[i] === message) return true;
+			}
+		}
+		return false;
+	}
+
 	/** Dequeued messages not yet in the transcript, e.g. steering a provider
 	 *  took into its in-flight response via live steering. Aborting the run
 	 *  requeues them, so the session's empty-submit interrupt counts them as
@@ -1553,17 +1591,50 @@ export class Agent {
 		return queue.slice(0, count);
 	}
 
+	/**
+	 * The next delivery batch of `queue`. With a {@link queuedMessageGate}, the
+	 * gate sees each candidate batch first; what it vetoes leaves the queue and
+	 * the batch is recomputed, and candidates it claimed that the final batch no
+	 * longer holds are released again.
+	 */
+	#nextDeliveryBatch(queue: QueuedMessageQueue): AgentMessage[] {
+		const mode = queue === "steering" ? this.#steeringMode : this.#followUpMode;
+		let batch = this.#dequeueMessages(queue === "steering" ? this.#steeringQueue : this.#followUpQueue, mode);
+		const gate = this.queuedMessageGate;
+		if (!gate || batch.length === 0) return batch;
+		let claimedEarlier: AgentMessage[] | undefined;
+		let dropped = false;
+		while (batch.length > 0) {
+			const veto = gate.claim(queue, batch);
+			if (veto.length === 0) break;
+			const drop = new Set(veto);
+			const pending = queue === "steering" ? this.#steeringQueue : this.#followUpQueue;
+			const kept = pending.filter(message => !drop.has(message));
+			if (kept.length === pending.length) break;
+			for (const message of batch) if (!drop.has(message)) (claimedEarlier ??= []).push(message);
+			if (queue === "steering") this.#steeringQueue = kept;
+			else this.#followUpQueue = kept;
+			dropped = true;
+			batch = this.#dequeueMessages(kept, mode);
+		}
+		if (claimedEarlier) {
+			const final = new Set(batch);
+			const stale = claimedEarlier.filter(message => !final.has(message));
+			if (stale.length > 0) gate.release(stale);
+		}
+		if (dropped && batch.length === 0) this.#emitQueueChanged();
+		return batch;
+	}
+
 	#dequeueSteeringMessages(): AgentMessage[] {
-		const messages = this.#dequeueMessages(this.#steeringQueue, this.#steeringMode);
+		const messages = this.#nextDeliveryBatch("steering");
 		this.#steeringQueue = this.#steeringQueue.slice(messages.length);
-		if (messages.length > 0) this.#emitQueueChanged();
 		return messages;
 	}
 
 	#dequeueFollowUpMessages(): AgentMessage[] {
-		const messages = this.#dequeueMessages(this.#followUpQueue, this.#followUpMode);
+		const messages = this.#nextDeliveryBatch("followUp");
 		this.#followUpQueue = this.#followUpQueue.slice(messages.length);
-		if (messages.length > 0) this.#emitQueueChanged();
 		return messages;
 	}
 
@@ -1991,6 +2062,7 @@ export class Agent {
 			resolveFallbackTool: this.#resolveFallbackTool,
 			suggestFallbackToolNames: this.#suggestFallbackToolNames,
 			intentTracing: this.#intentTracing,
+			intentDescription: this.#intentDescription,
 			pruneToolDescriptions: this.#pruneToolDescriptions,
 			dialect: this.#dialect,
 			getDialect: this.#dialectResolver,
@@ -2024,6 +2096,7 @@ export class Agent {
 				}
 				return this.#dequeueSteeringMessagesAfterHooks(signal ?? loopSignal);
 			},
+			isUndeliveredQueuedMessage: message => this.#isUndeliveredQueuedMessage(message),
 			hasSteeringMessages: () =>
 				steeringQueueState(
 					this.#steeringQueue,

package/src/append-only-context.ts

@@ -82,6 +82,8 @@ export interface StablePrefixSnapshot {
 export interface BuildOptions {
 	/** Inject the `i` intent field into tool schemas (must match agent-loop's normalizeTools). */
 	intentTracing: boolean;
+	/** Schema description of the injected `i` field (must match agent-loop's normalizeTools). */
+	intentDescription?: string;
 	/** Strip tool descriptions from the provider-bound specs (must match normalizeTools). */
 	pruneToolDescriptions?: boolean;
 }
@@ -136,6 +138,7 @@ export class StablePrefix {
 	// but changes any of these must miss the fast path.
 	#lastToolKey: readonly string[] | undefined;
 	#lastIntentTracing: boolean | undefined;
+	#lastIntentDescription: string | undefined;
 	#lastPruneToolDescriptions: boolean | undefined;
 
 	build(context: AgentContext, options: BuildOptions): boolean {
@@ -166,6 +169,7 @@ export class StablePrefix {
 	#fastPathHit(context: AgentContext, options: BuildOptions, toolKeys: readonly string[]): boolean {
 		if (
 			this.#lastIntentTracing !== options.intentTracing ||
+			this.#lastIntentDescription !== options.intentDescription ||
 			this.#lastPruneToolDescriptions !== options.pruneToolDescriptions
 		) {
 			return false;
@@ -196,6 +200,7 @@ export class StablePrefix {
 	#recordFastPathKey(context: AgentContext, options: BuildOptions, renderedToolKeys: readonly string[]): void {
 		this.#lastPromptSegments = [...context.systemPrompt];
 		this.#lastIntentTracing = options.intentTracing;
+		this.#lastIntentDescription = options.intentDescription;
 		this.#lastPruneToolDescriptions = options.pruneToolDescriptions;
 		this.#lastToolKey = renderedToolKeys;
 	}
@@ -470,11 +475,7 @@ export class AppendOnlyContextManager {
 
 function takeSnapshot(context: AgentContext, options: BuildOptions): StablePrefixSnapshot {
 	const systemPrompt = [...context.systemPrompt];
-	const tools =
-		normalizeTools(context.tools, {
-			injectIntent: options.intentTracing,
-			pruneDescriptions: options.pruneToolDescriptions,
-		}) ?? [];
+	const tools = normalizeWireTools(context.tools, options);
 	return {
 		systemPrompt,
 		tools,
@@ -482,20 +483,50 @@ function takeSnapshot(context: AgentContext, options: BuildOptions): StablePrefi
 	};
 }
 
+function normalizeWireTools(tools: AgentContext["tools"], options: BuildOptions): Tool[] {
+	return (
+		normalizeTools(tools, {
+			injectIntent: options.intentTracing,
+			intentDescription: options.intentDescription,
+			pruneDescriptions: options.pruneToolDescriptions,
+		}) ?? []
+	);
+}
+
+/** The fields of a provider-bound tool spec the wire carries; `normalizeTools` has rendered `examples` into the description. */
+function wireToolFields(t: Tool) {
+	return {
+		n: t.name,
+		d: t.description,
+		p: t.parameters,
+		s: t.strict,
+		cf: t.customFormat,
+		cw: t.customWireName,
+	};
+}
+
+/**
+ * Fingerprint of the tool specs a request built with `options` sends: the
+ * tools half of the prefix fingerprint, for a caller that compares tool sets
+ * across requests. A same-name tool whose description, schema, examples,
+ * `strict`, `customFormat` or `customWireName` changed makes another one.
+ */
+export function wireToolsFingerprint(tools: AgentContext["tools"], options: BuildOptions): string {
+	return hashPayload(JSON.stringify(normalizeWireTools(tools, options).map(wireToolFields)));
+}
+
 function computeFingerprint(systemPrompt: string[], tools: Tool[], options: BuildOptions): string {
-	const payload = JSON.stringify({
-		s: systemPrompt,
-		t: tools.map(t => ({
-			n: t.name,
-			d: t.description,
-			p: t.parameters,
-			s: t.strict,
-			cf: t.customFormat,
-			cw: t.customWireName,
-		})),
-		i: options.intentTracing,
-		pd: options.pruneToolDescriptions,
-	});
+	return hashPayload(
+		JSON.stringify({
+			s: systemPrompt,
+			t: tools.map(wireToolFields),
+			i: options.intentTracing,
+			pd: options.pruneToolDescriptions,
+		}),
+	);
+}
+
+function hashPayload(payload: string): string {
 	let hash = 0;
 	for (let i = 0; i < payload.length; i++) {
 		hash = ((hash << 5) - hash + payload.charCodeAt(i)) | 0;

package/src/compaction/compaction-v2-streaming.ts

@@ -472,7 +472,6 @@ function buildCompactionV2Headers(
 			headers[OPENAI_HEADERS.SESSION_ID] = routingSessionId;
 			headers["x-client-request-id"] = routingSessionId;
 		}
-		headers[OPENAI_HEADERS.BETA] = OPENAI_HEADER_VALUES.BETA_RESPONSES;
 		headers[OPENAI_HEADERS.ORIGINATOR] = OPENAI_HEADER_VALUES.ORIGINATOR_CODEX;
 		headers[OPENAI_HEADERS.CODEX_BETA_FEATURES] = OPENAI_HEADER_VALUES.REMOTE_COMPACTION_V2;
 		headers[OPENAI_HEADERS.ROUTING_HINT] = codexRoutingHint(request.body.model, undefined);

package/src/compaction/openai.ts

@@ -965,7 +965,6 @@ export async function requestOpenAiRemoteCompaction(
 		if (attestation) {
 			headers[OPENAI_HEADERS.ATTESTATION] = attestation;
 		}
-		headers[OPENAI_HEADERS.BETA] = OPENAI_HEADER_VALUES.BETA_RESPONSES;
 		headers[OPENAI_HEADERS.ORIGINATOR] = OPENAI_HEADER_VALUES.ORIGINATOR_CODEX;
 		// This compaction request sends no `service_tier`, so the hint is model-only.
 		headers[OPENAI_HEADERS.ROUTING_HINT] = codexRoutingHint(request.model, undefined);

package/src/telemetry.ts

@@ -1836,7 +1836,7 @@ export interface InstrumentedChatSpanOptions {
 export async function instrumentedCompleteSimple<TApi extends Api>(
 	model: Model<TApi>,
 	ctx: Context,
-	options: SimpleStreamOptions,
+	options: SimpleStreamOptions & { onAttempt?: (message: AssistantMessage) => void },
 	span: InstrumentedChatSpanOptions,
 ): Promise<AssistantMessage> {
 	const { telemetry, parent, oneshotKind } = span;

package/src/types.ts

@@ -48,6 +48,22 @@ export type PrepareQueuedMessages = (
 	queue: QueuedMessageQueue,
 ) => QueuedMessagePreparation | undefined | Promise<QueuedMessagePreparation | undefined>;
 
+/**
+ * Synchronous arbiter over queued messages leaving a queue for delivery, for a
+ * queue whose messages someone else may withdraw concurrently (a session homed
+ * on another thread whose view pops them).
+ */
+export interface QueuedMessageGate {
+	/**
+	 * Called with the batch about to be removed from `queue` for delivery; returns
+	 * the candidates that must be dropped from the queue instead. The others are
+	 * claimed for delivery.
+	 */
+	claim(queue: QueuedMessageQueue, candidates: readonly AgentMessage[]): readonly AgentMessage[];
+	/** Called with claimed messages that left delivery undelivered (requeued, withdrawn, or cancelled). */
+	release(messages: readonly AgentMessage[]): void;
+}
+
 /** Called once an aside has been inserted into the agent's live context. */
 export const ASIDE_MESSAGE_COMMIT = Symbol("aside-message-commit");
 /** Symbol-keyed handoff for one finalized, tool-owned stream speculation session. */
@@ -278,6 +294,9 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 */
 	getSteeringMessages?: (signal?: AbortSignal) => Promise<AgentMessage[]>;
 
+	/** Whether input is still owned by a queue and must be restored if a model call is aborted before it starts. */
+	isUndeliveredQueuedMessage?: (message: AgentMessage) => boolean;
+
 	/**
 	 * Peeks whether steering messages are queued, without consuming them.
 	 *
@@ -457,6 +476,8 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 * then strips from arguments before executing tools.
 	 */
 	intentTracing?: boolean;
+	/** Schema description of the injected intent field; `PI_INTENT_DESC` overrides it. Default `concise intent`. */
+	intentDescription?: string;
 	/**
 	 * Strip tool descriptions (top-level + nested schema annotations) from the
 	 * provider-bound tool specs. Use when the full catalog is rendered into the