@linxiraos/pi-agent-core 1.1.27 → 1.2.0

package/dist/types/telemetry.d.ts

@@ -2,7 +2,7 @@
  * OpenTelemetry instrumentation for the agent loop.
  *
  * Implements the OpenTelemetry GenAI semantic conventions
- * (https://opentelemetry.io/docs/specs/semconv/gen-ai/) plus `omp.gen_ai.*`
+ * (https://opentelemetry.io/docs/specs/semconv/gen-ai/) plus `zeta.gen_ai.*`
  * extension attributes for run summaries, dashboard summaries, and cost hints
  * that are useful to downstream observability UIs.
  *
@@ -79,40 +79,40 @@ export declare const enum OpenAIAttr {
 }
 /** Project extension attributes. Kept out of the reserved `gen_ai.*` namespace. */
 export declare const enum OmpGenAIAttr {
-    AgentStepNumber = "omp.gen_ai.agent.step.number",
-    AgentStepCount = "omp.gen_ai.agent.step.count",
-    RequestReasoningEffort = "omp.gen_ai.request.reasoning.effort",
-    RequestToolChoice = "omp.gen_ai.request.tool.choice",
-    RequestAvailableTools = "omp.gen_ai.request.available_tools",
-    RequestMessages = "omp.gen_ai.request.messages",
-    ResponseText = "omp.gen_ai.response.text",
-    ResponseToolCalls = "omp.gen_ai.response.tool_calls",
-    ResponseUpstreamProvider = "omp.gen_ai.response.upstream_provider",
-    UsageTotalTokens = "omp.gen_ai.usage.total_tokens",
-    UsageServerSideTools = "omp.gen_ai.usage.server_tool_requests",
-    CostEstimatedUsd = "omp.gen_ai.cost.estimated_usd",
-    CostInputUsd = "omp.gen_ai.cost.input_usd",
-    CostOutputUsd = "omp.gen_ai.cost.output_usd",
-    CostUnavailableReason = "omp.gen_ai.cost.unavailable_reason",
-    ToolStatus = "omp.gen_ai.tool.status",
-    ToolCallIntent = "omp.gen_ai.tool.call.intent",
-    HandoffFromAgentName = "omp.gen_ai.handoff.from_agent.name",
-    HandoffFromAgentId = "omp.gen_ai.handoff.from_agent.id",
-    HandoffToAgentName = "omp.gen_ai.handoff.to_agent.name",
-    HandoffToAgentId = "omp.gen_ai.handoff.to_agent.id",
-    OneshotKind = "omp.gen_ai.oneshot.kind",
-    GatewayName = "omp.gen_ai.gateway.name",
-    GatewayEndpoint = "omp.gen_ai.gateway.endpoint",
-    GatewayCallId = "omp.gen_ai.gateway.call_id",
-    GatewayRoutedTo = "omp.gen_ai.gateway.routed_to",
+    AgentStepNumber = "zeta.gen_ai.agent.step.number",
+    AgentStepCount = "zeta.gen_ai.agent.step.count",
+    RequestReasoningEffort = "zeta.gen_ai.request.reasoning.effort",
+    RequestToolChoice = "zeta.gen_ai.request.tool.choice",
+    RequestAvailableTools = "zeta.gen_ai.request.available_tools",
+    RequestMessages = "zeta.gen_ai.request.messages",
+    ResponseText = "zeta.gen_ai.response.text",
+    ResponseToolCalls = "zeta.gen_ai.response.tool_calls",
+    ResponseUpstreamProvider = "zeta.gen_ai.response.upstream_provider",
+    UsageTotalTokens = "zeta.gen_ai.usage.total_tokens",
+    UsageServerSideTools = "zeta.gen_ai.usage.server_tool_requests",
+    CostEstimatedUsd = "zeta.gen_ai.cost.estimated_usd",
+    CostInputUsd = "zeta.gen_ai.cost.input_usd",
+    CostOutputUsd = "zeta.gen_ai.cost.output_usd",
+    CostUnavailableReason = "zeta.gen_ai.cost.unavailable_reason",
+    ToolStatus = "zeta.gen_ai.tool.status",
+    ToolCallIntent = "zeta.gen_ai.tool.call.intent",
+    HandoffFromAgentName = "zeta.gen_ai.handoff.from_agent.name",
+    HandoffFromAgentId = "zeta.gen_ai.handoff.from_agent.id",
+    HandoffToAgentName = "zeta.gen_ai.handoff.to_agent.name",
+    HandoffToAgentId = "zeta.gen_ai.handoff.to_agent.id",
+    OneshotKind = "zeta.gen_ai.oneshot.kind",
+    GatewayName = "zeta.gen_ai.gateway.name",
+    GatewayEndpoint = "zeta.gen_ai.gateway.endpoint",
+    GatewayCallId = "zeta.gen_ai.gateway.call_id",
+    GatewayRoutedTo = "zeta.gen_ai.gateway.routed_to",
     /** Cloudflare AI Gateway response-cache status (`cf-aig-cache-status`), never prompt-cache. */
-    GatewayResponseCacheStatus = "omp.gen_ai.gateway.response_cache.status",
+    GatewayResponseCacheStatus = "zeta.gen_ai.gateway.response_cache.status",
     /** Caller-level reason a judgment ran (`find`, `ttsr`, `judge_batch`, …). */
-    JudgmentPurpose = "omp.gen_ai.judgment.purpose",
+    JudgmentPurpose = "zeta.gen_ai.judgment.purpose",
     /** Questions the caller asked in one judgment request. */
-    JudgmentQuestions = "omp.gen_ai.judgment.questions",
+    JudgmentQuestions = "zeta.gen_ai.judgment.questions",
     /** Questions answered from the local judgment cache instead of the provider. */
-    JudgmentCachedQuestions = "omp.gen_ai.judgment.cached_questions"
+    JudgmentCachedQuestions = "zeta.gen_ai.judgment.cached_questions"
 }
 /** GenAI operation names — values for {@link GenAIAttr.OperationName}. */
 export declare const GenAIOperation: {
@@ -160,9 +160,9 @@ export interface CostEstimatorContext {
 }
 /**
  * Cost estimator result.
- *   { usd: number }                — cost is known; emitted as omp.gen_ai.cost.estimated_usd
+ *   { usd: number }                — cost is known; emitted as zeta.gen_ai.cost.estimated_usd
  *   { unavailable: string }        — cost is intentionally unknown; emitted as
- *                                    omp.gen_ai.cost.unavailable_reason
+ *                                    zeta.gen_ai.cost.unavailable_reason
  *   undefined                      — no opinion; nothing emitted
  */
 export type CostEstimate = {
@@ -213,7 +213,7 @@ export interface ChatUsageEvent {
      *
      * Use this to reconcile gateway-issued ids (e.g. `x-litellm-call-id`) with
      * downstream billing / spend dashboards. Known gateway patterns are also
-     * auto-stamped on the chat span as `omp.gen_ai.gateway.*` attributes.
+     * auto-stamped on the chat span as `zeta.gen_ai.gateway.*` attributes.
      */
     readonly headers: Readonly<Record<string, string>> | undefined;
 }
@@ -518,10 +518,10 @@ export interface InstrumentedChatSpanOptions {
     /** Step index recorded on the span; defaults to `-1` for non-loop calls. */
     readonly stepNumber?: number;
     /**
-     * Tag stamped onto `omp.gen_ai.oneshot.kind`. Values used by the agent:
+     * Tag stamped onto `zeta.gen_ai.oneshot.kind`. Values used by the agent:
      * `compaction_summary`, `compaction_short_summary`, `compaction_turn_prefix`,
-     * `handoff`, `branch_summary`, `image_question`. Free-form to allow callers
-     * outside this package to add new kinds without bumping the helper.
+     * `handoff`, `branch_summary`, `image_question`, `skill_description`. Free-form
+     * to allow callers outside this package to add new kinds without bumping the helper.
      */
     readonly oneshotKind?: string;
     /** Extra span attributes applied verbatim. */
@@ -623,30 +623,30 @@ export declare function finishInvokeAgentSpan(telemetry: AgentTelemetry | undefi
  * calling this helper.
  */
 export declare function fireOnRunEnd(telemetry: AgentTelemetry, summary: AgentRunSummary, coverage: AgentRunCoverage): void;
-/** Aggregate `omp.gen_ai.agent.*` attributes stamped on the `invoke_agent` span. */
+/** Aggregate `zeta.gen_ai.agent.*` attributes stamped on the `invoke_agent` span. */
 export declare const enum OmpGenAIAggregateAttr {
-    ChatsCount = "omp.gen_ai.agent.chats.count",
-    ChatsTotalLatencyMs = "omp.gen_ai.agent.chats.total_latency_ms",
-    ChatsStopReasonPrefix = "omp.gen_ai.agent.chats.stop_reason.",
-    ToolsCount = "omp.gen_ai.agent.tools.count",
-    ToolsOkCount = "omp.gen_ai.agent.tools.ok.count",
-    ToolsErrorCount = "omp.gen_ai.agent.tools.error.count",
-    ToolsSkippedCount = "omp.gen_ai.agent.tools.skipped.count",
-    ToolsBlockedCount = "omp.gen_ai.agent.tools.blocked.count",
-    ToolsTimeoutCount = "omp.gen_ai.agent.tools.timeout.count",
-    ToolsAbortedCount = "omp.gen_ai.agent.tools.aborted.count",
-    ToolsTotalLatencyMs = "omp.gen_ai.agent.tools.total_latency_ms",
-    ToolsInvoked = "omp.gen_ai.agent.tools.invoked",
-    ToolsAvailable = "omp.gen_ai.agent.tools.available",
-    ToolsUnused = "omp.gen_ai.agent.tools.unused",
-    UsageInputTokensTotal = "omp.gen_ai.agent.usage.input_tokens.total",
-    UsageOutputTokensTotal = "omp.gen_ai.agent.usage.output_tokens.total",
-    UsageCacheReadInputTokensTotal = "omp.gen_ai.agent.usage.cache_read.input_tokens.total",
-    UsageCacheCreationInputTokensTotal = "omp.gen_ai.agent.usage.cache_creation.input_tokens.total",
-    UsageReasoningOutputTokensTotal = "omp.gen_ai.agent.usage.reasoning.output_tokens.total",
-    UsageTotalTokensTotal = "omp.gen_ai.agent.usage.total_tokens.total",
-    CostEstimatedUsdTotal = "omp.gen_ai.agent.cost.estimated_usd.total",
-    ErrorsCount = "omp.gen_ai.agent.errors.count"
+    ChatsCount = "zeta.gen_ai.agent.chats.count",
+    ChatsTotalLatencyMs = "zeta.gen_ai.agent.chats.total_latency_ms",
+    ChatsStopReasonPrefix = "zeta.gen_ai.agent.chats.stop_reason.",
+    ToolsCount = "zeta.gen_ai.agent.tools.count",
+    ToolsOkCount = "zeta.gen_ai.agent.tools.ok.count",
+    ToolsErrorCount = "zeta.gen_ai.agent.tools.error.count",
+    ToolsSkippedCount = "zeta.gen_ai.agent.tools.skipped.count",
+    ToolsBlockedCount = "zeta.gen_ai.agent.tools.blocked.count",
+    ToolsTimeoutCount = "zeta.gen_ai.agent.tools.timeout.count",
+    ToolsAbortedCount = "zeta.gen_ai.agent.tools.aborted.count",
+    ToolsTotalLatencyMs = "zeta.gen_ai.agent.tools.total_latency_ms",
+    ToolsInvoked = "zeta.gen_ai.agent.tools.invoked",
+    ToolsAvailable = "zeta.gen_ai.agent.tools.available",
+    ToolsUnused = "zeta.gen_ai.agent.tools.unused",
+    UsageInputTokensTotal = "zeta.gen_ai.agent.usage.input_tokens.total",
+    UsageOutputTokensTotal = "zeta.gen_ai.agent.usage.output_tokens.total",
+    UsageCacheReadInputTokensTotal = "zeta.gen_ai.agent.usage.cache_read.input_tokens.total",
+    UsageCacheCreationInputTokensTotal = "zeta.gen_ai.agent.usage.cache_creation.input_tokens.total",
+    UsageReasoningOutputTokensTotal = "zeta.gen_ai.agent.usage.reasoning.output_tokens.total",
+    UsageTotalTokensTotal = "zeta.gen_ai.agent.usage.total_tokens.total",
+    CostEstimatedUsdTotal = "zeta.gen_ai.agent.cost.estimated_usd.total",
+    ErrorsCount = "zeta.gen_ai.agent.errors.count"
 }
 /**
  * Run `fn` with `span` activated on the OTEL context. Spans created

package/dist/types/tool-arguments.d.ts

@@ -0,0 +1,19 @@
+import { type ToolCall } from "@linxiraos/pi-ai";
+import type { AgentTool } from "./types.js";
+/**
+ * Where a call's `__parseError`/`__rawJson` keys came from.
+ * - `"parsed"`: a provider stream parsed the arguments, so `__parseError` is a
+ *   genuine parse-failure sentinel and is never handed to a tool.
+ * - `"payload"`: the arguments are a payload the model wrote (eval tool bridge,
+ *   `xd://` device content), so those keys are forged and only stripped.
+ */
+export type ToolArgumentSource = "parsed" | "payload";
+/**
+ * Validate a call's arguments against `tool`'s schema, honoring
+ * {@link AgentTool.lenientArgValidation}: on a schema mismatch a lenient tool
+ * receives its raw arguments minus the internal `__parseError`/`__rawJson`
+ * sentinels. Malformed JSON from a provider stream is never lenient.
+ *
+ * @throws the validation error when the tool is strict or the arguments failed to parse.
+ */
+export declare function validateAgentToolArguments(tool: AgentTool, toolCall: ToolCall, source?: ToolArgumentSource): ToolCall["arguments"];

package/dist/types/types.d.ts

@@ -269,6 +269,16 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * background.
      */
     hasBackgroundCompletions?: () => boolean | Promise<boolean>;
+    /**
+     * Peeks whether a passive aside (an extension or user message queued with
+     * `deliverAs: "aside"`) is waiting for injection at the next boundary.
+     *
+     * Same rules as {@link hasBackgroundCompletions}: non-consuming, ends only
+     * *interruptible* waits, never raises {@link ToolCallContext.steeringSignal}.
+     * The host still injects the aside once at the boundary; ordinary running
+     * tools finish first.
+     */
+    hasQueuedAsides?: () => boolean | Promise<boolean>;
     /**
      * Returns follow-up messages to process after the agent would otherwise stop.
      *
@@ -281,7 +291,8 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * Returns non-interrupting "aside" messages to inject at a step boundary.
      *
      * Polled after each tool batch (before the next LLM call) AND at the yield
-     * check. Unlike steering, these NEVER abort in-flight tools — they are passive
+     * check. Unlike steering, these never abort foreground tools (only an
+     * interruptible `wait` ends early, via the peek hooks) — they are passive
      * notifications (e.g. background-job completions, late LSP diagnostics) that
      * should reach the model between requests without waiting for the agent to
      * fully stop. Returned messages are appended to the context with normal

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@linxiraos/pi-agent-core",
-	"version": "1.1.27",
+	"version": "1.2.0",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://linxira-os.github.io/zeta/",
 	"author": "Linxira-OS",
@@ -35,16 +35,16 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@linxiraos/pi-ai": "1.1.27",
-		"@linxiraos/pi-catalog": "1.1.27",
-		"@linxiraos/pi-natives": "1.1.27",
-		"@linxiraos/pi-utils": "1.1.27",
-		"@linxiraos/pi-wire": "1.1.27",
-		"@linxiraos/pi-snapcompact": "1.1.27",
+		"@linxiraos/pi-ai": "1.2.0",
+		"@linxiraos/pi-catalog": "1.2.0",
+		"@linxiraos/pi-natives": "1.2.0",
+		"@linxiraos/pi-utils": "1.2.0",
+		"@linxiraos/pi-wire": "1.2.0",
+		"@linxiraos/pi-snapcompact": "1.2.0",
 		"@opentelemetry/api": "^1.9.1"
 	},
 	"devDependencies": {
-		"@linxiraos/pi-omptype": "1.1.27",
+		"@linxiraos/pi-omptype": "1.2.0",
 		"@opentelemetry/context-async-hooks": "^2.9.0",
 		"@opentelemetry/sdk-trace-base": "^2.9.0",
 		"@types/bun": "^1.3.14"

package/src/agent-loop.ts

@@ -23,7 +23,6 @@ import {
 	type TSchema,
 	toolWireSchema,
 	type UserMessage,
-	validateToolArguments,
 } from "@linxiraos/pi-ai";
 import {
 	type Dialect,
@@ -76,6 +75,7 @@ import {
 	startExecuteToolSpan,
 	startInvokeAgentSpan,
 } from "./telemetry";
+import { validateAgentToolArguments } from "./tool-arguments";
 import { createAdditionalContextMessage, isNonBlankContext, joinAdditionalContext } from "./tool-context";
 import dsmlToolCallLeakPrompt from "./prompts/dsml-tool-call-leak.md" with { type: "text" };
 import type {
@@ -3062,15 +3062,9 @@ async function prepareToolCallDispatch(
 				if (!tool) {
 					throw new Error(formatToolNotFoundMessage(toolCall.name, context.tools, suggestFallbackToolNames?.()));
 				}
-				return validateToolArguments(tool, { ...toolCall, arguments: args });
+				return validateAgentToolArguments(tool, { ...toolCall, arguments: args });
 			} catch (validationError) {
-				// Lenience covers schema mismatches; a parse failure has no args to hand over.
 				const parseFailed = "__parseError" in args;
-				if (tool?.lenientArgValidation && !parseFailed) {
-					const fallback = { ...args };
-					delete fallback.__rawJson;
-					return fallback;
-				}
 				entry.args = parseFailed ? { __parseError: args.__parseError } : args;
 				entry.validationErrorMessage =
 					validationError instanceof Error ? validationError.message : String(validationError);
@@ -3210,6 +3204,7 @@ async function executeToolCalls(
 		hasSteeringMessages,
 		hasIrcInterrupts,
 		hasBackgroundCompletions,
+		hasQueuedAsides,
 		interruptMode = "immediate",
 		getToolContext,
 
@@ -3311,11 +3306,12 @@ async function executeToolCalls(
 		// (only when soft interrupts are enabled; otherwise nothing is left).
 		if (signal?.aborted) return;
 		if (interruptState.triggered && (!softInterrupts || steeringSoftController.signal.aborted)) return;
-		// Peer IRC and background completions (finished jobs, exited supervised
-		// processes) hard-abort interruptible waits only; foreground tools keep
-		// running (no partial side effects).
+		// Peer IRC, queued asides and background completions (finished jobs,
+		// exited supervised processes) hard-abort interruptible waits only;
+		// foreground tools keep running (no partial side effects).
 		let source: AsideInterruptSource | undefined;
 		if (hasIrcInterrupts && (await hasIrcInterrupts())) source = "irc";
+		else if (!interruptState.triggered && hasQueuedAsides && (await hasQueuedAsides())) source = "aside";
 		else if (!interruptState.triggered && hasBackgroundCompletions && (await hasBackgroundCompletions()))
 			source = "background";
 		if (!source) return;
@@ -3332,7 +3328,7 @@ async function executeToolCalls(
 		// also cascades: the freshly detached job's own completion re-triggers
 		// this check for the next command, so millisecond-long commands chain
 		// into separate background deliveries (#12869).
-		if (source !== "background" && softInterrupts) steeringSoftController.abort();
+		if (source === "irc" && softInterrupts) steeringSoftController.abort();
 	};
 
 	const checkSteering = async (): Promise<void> => {
@@ -3703,7 +3699,8 @@ async function executeToolCalls(
 	// (auto-background bash), so the boundary dequeue below injects the message
 	// promptly. In "wait" mode only a batch holding an interruptible wait needs
 	// the watch; checkSteering is idempotent (no-op once triggered).
-	const hasAsidePeek = hasIrcInterrupts !== undefined || hasBackgroundCompletions !== undefined;
+	const hasAsidePeek =
+		hasIrcInterrupts !== undefined || hasBackgroundCompletions !== undefined || hasQueuedAsides !== undefined;
 	const watchSteeringWhileRunning =
 		(softInterrupts || records.some(record => record.interruptible)) &&
 		(hasSteeringMessages !== undefined || hasAsidePeek);
@@ -3989,8 +3986,8 @@ function createToolSignalAbortedResult(signal: AbortSignal): AgentToolResult<unk
 	};
 }
 
-/** Origin of a mid-batch interrupt: queued steering, a peer IRC, or a background completion notice. */
-type AsideInterruptSource = SteeringInterruptSource | "irc" | "background";
+/** Origin of a mid-batch interrupt: queued steering, a peer IRC, a queued aside, or a background completion notice. */
+type AsideInterruptSource = SteeringInterruptSource | "irc" | "aside" | "background";
 
 function createSkippedToolResult(
 	source: AsideInterruptSource | undefined,
@@ -4010,6 +4007,9 @@ function createSkippedToolResult(
 	} else if (source === "irc") {
 		reason = "pending peer interrupt";
 		blocker = "interrupt";
+	} else if (source === "aside") {
+		reason = "a queued aside message";
+		blocker = "aside";
 	} else if (source === "background") {
 		reason = "a queued background completion (job or supervised process)";
 		blocker = "completion notice";

package/src/agent.ts

@@ -453,6 +453,7 @@ export class Agent {
 	#promptCacheKey?: string;
 	#metadata?: Record<string, unknown>;
 	#metadataResolver?: (provider: string) => Record<string, unknown> | undefined;
+	#modelResolver?: (model: Model) => Model;
 	#providerSessionState?: Map<string, ProviderSessionState>;
 	#thinkingBudgets?: ThinkingBudgets;
 	#temperature?: number;
@@ -539,6 +540,11 @@ export class Agent {
 	 * are queued for the next boundary.
 	 */
 	hasBackgroundCompletions?: AgentLoopConfig["hasBackgroundCompletions"];
+	/**
+	 * Hook that peeks whether a passive aside is queued for the next boundary;
+	 * ends an interruptible wait without interrupting other tools.
+	 */
+	hasQueuedAsides?: AgentLoopConfig["hasQueuedAsides"];
 
 	constructor(opts: AgentOptions = {}) {
 		this.#state = { ...this.#state, ...opts.initialState };
@@ -933,7 +939,8 @@ export class Agent {
 	}
 
 	/** Register a listener notified after any steering/follow-up queue mutator
-	 *  (enqueue, dequeue-on-delivery, clear, restore) runs. Internal-only signal —
+	 *  (enqueue, dequeue-on-delivery, clear, restore, live-steering adoption,
+	 *  withdrawal, and landing in the transcript) runs. Internal-only signal —
 	 *  the queue itself has no concept of display filtering — so listeners
 	 *  recompute their own snapshot from `peekSteeringQueue()`/`peekFollowUpQueue()`
 	 *  (or a higher-level view) on notification. */
@@ -1066,11 +1073,13 @@ export class Agent {
 
 	/** Move steering live steering took out of the queue-delivery records into {@link #liveSteered}. */
 	#adoptLiveSteering(taken: readonly AgentMessage[]): void {
+		let adopted = false;
 		for (const delivery of this.#queuedMessageDeliveries) {
 			const pending = delivery.messages.slice(delivery.next);
 			const kept = pending.filter(message => !taken.includes(message));
 			if (kept.length === pending.length) continue;
 			let last: LiveSteeredEntry | undefined;
+			adopted = true;
 			for (const message of pending) {
 				if (!taken.includes(message)) continue;
 				last = { message, controller: delivery.controller };
@@ -1085,6 +1094,10 @@ export class Agent {
 				delivery.next = 0;
 			}
 		}
+		// The adopted messages move into #liveSteered, which queue snapshots
+		// (peekLiveSteeredMessages) count as still pending; listeners must hear
+		// about the swap or their queue view goes stale for the rest of the turn.
+		if (adopted) this.#emitQueueChanged();
 	}
 
 	/**
@@ -1103,6 +1116,9 @@ export class Agent {
 			suppress(message, controller);
 			for (const context of additional ?? []) suppress(context, controller);
 		}
+		// Every snapshot counts live-steered messages as pending, so clearing
+		// them is a queue change even when the caller re-queues them right after.
+		const hadLiveSteered = this.#liveSteered.length > 0;
 		this.#liveSteered = [];
 		for (const delivery of this.#queuedMessageDeliveries) {
 			const pending = delivery.messages.slice(delivery.next);
@@ -1110,6 +1126,7 @@ export class Agent {
 			for (const message of [...pending, ...delivery.additional]) suppress(message, delivery.controller);
 		}
 		this.#queuedMessageDeliveries.clear();
+		if (hadLiveSteered) this.#emitQueueChanged();
 		return withdrawn;
 	}
 
@@ -1174,7 +1191,8 @@ export class Agent {
 	/**
 	 * Provide a source of non-interrupting "aside" messages (e.g. background-job
 	 * completions, late LSP diagnostics) drained at each step boundary. Never
-	 * aborts in-flight tools. See `AgentLoopConfig.getAsideMessages`.
+	 * aborts foreground tools; an interruptible `wait` may end early through the
+	 * peek hooks. See `AgentLoopConfig.getAsideMessages`.
 	 */
 	setAsideMessageProvider(fn: (() => AsideMessage[] | Promise<AsideMessage[]>) | undefined): void {
 		this.#asideMessageProvider = fn;
@@ -1207,8 +1225,20 @@ export class Agent {
 	}
 
 	setModel(model: Model) {
-		this.#state.model = model;
-		this.#syncTokenizer(model);
+		// Sessions may start with no model selected (`initialState.model: undefined`).
+		const resolved = this.#modelResolver && model ? this.#modelResolver(model) : model;
+		this.#state.model = resolved;
+		this.#syncTokenizer(resolved);
+	}
+
+	/**
+	 * Route every model this agent adopts through `resolver` (e.g. to fit a
+	 * shared catalog row to this agent's own settings), starting with the
+	 * current one; `undefined` adopts models as given from now on.
+	 */
+	setModelResolver(resolver: ((model: Model) => Model) | undefined): void {
+		this.#modelResolver = resolver;
+		if (resolver && this.#state.model) this.setModel(this.#state.model);
 	}
 
 	setThinkingLevel(l: Effort | undefined) {
@@ -1319,6 +1349,9 @@ export class Agent {
 		const live = this.#liveSteered.findIndex(entry => entry.message === m);
 		if (live >= 0) {
 			this.#liveSteered.splice(live, 1);
+			// The message landed in the transcript, so it stops counting as
+			// queued pending input; snapshots shrink and listeners must hear it.
+			this.#emitQueueChanged();
 			return;
 		}
 		for (const delivery of this.#queuedMessageDeliveries) {
@@ -1913,6 +1946,7 @@ export class Agent {
 			onLiveSteeringTaken: messages => this.#adoptLiveSteering(messages),
 			hasIrcInterrupts: this.hasIrcInterrupts,
 			hasBackgroundCompletions: this.hasBackgroundCompletions,
+			hasQueuedAsides: this.hasQueuedAsides,
 			getFollowUpMessages: signal => this.#dequeueFollowUpMessagesAfterHooks(signal ?? loopSignal),
 			getAsideMessages: async () => (await this.#asideMessageProvider?.()) ?? [],
 			onBeforeYield: () => this.#onBeforeYield?.(),
@@ -2118,8 +2152,19 @@ export class Agent {
 				turnOpen = false;
 				this.#emit({ type: "agent_end", messages: agentEndMessages });
 			} else {
+				// Context hooks can reject on abort before provider streaming starts.
+				// Publish the boundary just like a streaming abort so subscribers can
+				// persist it and recover the interrupted turn after a reload.
+				if (!turnOpen) this.#emit({ type: "turn_start" });
+				if (!hadAssistantStart) {
+					this.#state.streamMessage = errorMsg;
+					this.#emit({ type: "message_start", message: errorMsg });
+				}
+				this.#state.streamMessage = null;
 				this.appendMessage(errorMsg);
 				this.#state.error = errorMessage;
+				this.#emit({ type: "message_end", message: errorMsg });
+				this.#emit({ type: "turn_end", message: errorMsg, toolResults: [] });
 				this.#emit({ type: "agent_end", messages: [errorMsg] });
 			}
 		} finally {

package/src/append-only-context.ts

@@ -112,21 +112,23 @@ export class StablePrefix {
 	 * Build or rebuild from live context.
 	 * Returns `true` if the prefix actually changed (cache miss imminent).
 	 *
-	 * Steady-state fast path: when the live prompt reference is unchanged
-	 * AND every tool resolves to the same normalized parameters identity as
-	 * last build, the fingerprint cannot have changed, so the full snapshot
-	 * + stringify is skipped. Comparing resolved parameters (not the tool
+	 * Steady-state fast path: when the live prompt has the same segments as
+	 * last build AND every tool resolves to the same normalized parameters
+	 * identity, the fingerprint cannot have changed, so the full snapshot +
+	 * stringify is skipped. Comparing resolved parameters (not the tool
 	 * container) is load-bearing: tools like ReadTool expose `parameters` as
 	 * a getter over live settings (`skillful`, `memory.backend`), so the
 	 * schema can swap under stable tool references when a setting toggles.
 	 * Any other in-place mutation must go through `invalidate()`.
 	 */
-	#lastPrompt: readonly string[] | undefined;
-	// Joined prompt bytes snapshot: the prompt array is caller-owned and
+	// Segment-level prompt copy: the prompt array is caller-owned and
 	// mutable in place (Agent.setSystemPrompt stores the caller's array;
 	// anyone holding it can push/splice), so reference equality alone cannot
-	// prove the bytes are unchanged. Compared by value on the fast path.
-	#lastPromptText: string | undefined;
+	// prove the bytes are unchanged. Comparing the recorded segments against
+	// the live ones roots out that mutation without concatenating the whole
+	// prompt just to compare it — segments are immutable strings, so `!==`
+	// on two strings is a byte comparison.
+	#lastPromptSegments: readonly string[] | undefined;
 	// Per-tool wire-identity snapshot: every field normalizeTools and
 	// computeFingerprint read (name, description, resolved parameters,
 	// strict, customFormat, customWireName, intent mode, examples
@@ -138,11 +140,17 @@ export class StablePrefix {
 
 	build(context: AgentContext, options: BuildOptions): boolean {
 		const prev = this.#snapshot;
-		if (prev !== null && this.#fastPathHit(context, options)) {
+		// The per-tool keys are rendered once per build and thread from the
+		// fast-path check into the recorded key, so a miss does not re-render
+		// every live tool description a second time (`normalizeTools` reads
+		// the same getters inside takeSnapshot). `prev === null` skips the
+		// check entirely — there is nothing to compare against.
+		const toolKeys = (context.tools ?? []).map(tool => toolKeyForPrefix(tool));
+		if (prev !== null && this.#fastPathHit(context, options, toolKeys)) {
 			return false;
 		}
 		const snapshot = takeSnapshot(context, options);
-		this.#recordFastPathKey(context, options, snapshot.tools);
+		this.#recordFastPathKey(context, options, toolKeys);
 		if (prev && prev.fingerprint === snapshot.fingerprint) {
 			// Identity changed but bytes did not (e.g. equivalent rebuild):
 			// keep serving the cached snapshot so downstream memo identity
@@ -154,47 +162,48 @@ export class StablePrefix {
 		return true;
 	}
 
-	/** True when the cheap key matches: prompt + per-tool resolved identity. */
-	#fastPathHit(context: AgentContext, options: BuildOptions): boolean {
+	/** True when the cheap key matches: prompt segments + per-tool identity. */
+	#fastPathHit(context: AgentContext, options: BuildOptions, toolKeys: readonly string[]): boolean {
 		if (
 			this.#lastIntentTracing !== options.intentTracing ||
 			this.#lastPruneToolDescriptions !== options.pruneToolDescriptions
 		) {
 			return false;
 		}
-		// Prompt by reference first (steady state), then by joined bytes so
-		// an in-place push/splice of the same array still misses.
-		if (this.#lastPrompt !== context.systemPrompt) return false;
-		if (this.#lastPromptText !== undefined) {
-			const text = context.systemPrompt.join("\u0000");
-			if (text !== this.#lastPromptText) return false;
+		// Prompt segments: the caller may push/splice the live array in place
+		// without any reference change, so compare the recorded segments
+		// rather than concatenating the whole prompt just to compare it.
+		const liveSegments = context.systemPrompt;
+		const cachedSegments = this.#lastPromptSegments;
+		if (cachedSegments === undefined || cachedSegments.length !== liveSegments.length) {
+			return false;
+		}
+		for (let i = 0; i < cachedSegments.length; i++) {
+			if (cachedSegments[i] !== liveSegments[i]) return false;
 		}
-		const tools = context.tools ?? [];
-		if (this.#lastToolKey === undefined || this.#lastToolKey.length !== tools.length) {
+		const recorded = this.#lastToolKey;
+		if (recorded === undefined || recorded.length !== toolKeys.length) {
 			return false;
 		}
-		for (let i = 0; i < tools.length; i++) {
-			if (this.#lastToolKey[i] !== toolKeyForPrefix(tools[i]!)) {
+		for (let i = 0; i < toolKeys.length; i++) {
+			if (recorded[i] !== toolKeys[i]) {
 				return false;
 			}
 		}
 		return true;
 	}
 
-	#recordFastPathKey(context: AgentContext, options: BuildOptions, normalized: Tool[]): void {
-		this.#lastPrompt = context.systemPrompt;
-		this.#lastPromptText = context.systemPrompt.join("\u0000");
+	#recordFastPathKey(context: AgentContext, options: BuildOptions, renderedToolKeys: readonly string[]): void {
+		this.#lastPromptSegments = [...context.systemPrompt];
 		this.#lastIntentTracing = options.intentTracing;
 		this.#lastPruneToolDescriptions = options.pruneToolDescriptions;
-		this.#lastToolKey = (context.tools ?? []).map(tool => toolKeyForPrefix(tool));
-		void normalized;
+		this.#lastToolKey = renderedToolKeys;
 	}
 
 	/** Force rebuild on the next `build()` call. */
 	invalidate(): void {
 		this.#snapshot = null;
-		this.#lastPrompt = undefined;
-		this.#lastPromptText = undefined;
+		this.#lastPromptSegments = undefined;
 		this.#lastToolKey = undefined;
 		this.#lastIntentTracing = undefined;
 		this.#lastPruneToolDescriptions = undefined;

package/src/compaction/branch-summarization.ts

@@ -86,7 +86,7 @@ export interface GenerateBranchSummaryOptions {
 	convertToLlm?: ConvertToLlm;
 	/**
 	 * Optional telemetry handle. When provided, the branch summary LLM call is
-	 * wrapped in an OTEL chat span tagged with `omp.gen_ai.oneshot.kind = "branch_summary"`.
+	 * wrapped in an OTEL chat span tagged with `zeta.gen_ai.oneshot.kind = "branch_summary"`.
 	 */
 	telemetry?: AgentTelemetry;
 	/**

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

@@ -412,7 +412,16 @@ function buildCompactionV2Headers(
 			: {
 					"content-type": "application/json",
 					...resolveOpenAIRequestSetup(
-						{ provider: model.provider, id: model.id, baseUrl: model.baseUrl, headers: model.headers },
+						{
+							provider: model.provider,
+							id: model.id,
+							baseUrl: model.baseUrl,
+							headers: model.headers,
+							compat: {
+								sessionHeader:
+									model.compat && "sessionHeader" in model.compat ? model.compat.sessionHeader : undefined,
+							},
+						},
 						{ apiKey, messages: [], sessionId: request.sessionId ?? routingSessionId, promptCacheSessionId },
 					).headers,
 				};