@linxiraos/pi-agent-core 1.1.26 → 1.2.0

package/src/image-tokens.ts

@@ -0,0 +1,77 @@
+import type { ImageContent } from "@linxiraos/pi-ai";
+import {
+	type ImageSize,
+	type ImageTokenization,
+	imageTokens,
+	resolveImageTokenization,
+} from "@linxiraos/pi-catalog/compat/image-tokenization";
+import { parseImageMetadata } from "@linxiraos/pi-utils";
+
+/**
+ * Dimension-based image token estimates shared by the local context counter
+ * ({@link Tokenizer.countMessage}) and the native remote-compaction fit probe.
+ * Both sides must price the same image the same way: when they disagreed
+ * (1.2k flat locally vs a 12k flat worst case remotely) an image-heavy session
+ * stayed under the local compaction trigger yet was refused as over-window by
+ * the remote probe.
+ *
+ * Follows the catalog's image rule for the OpenAI Responses wire (GPT-5.5's
+ * 32px patches, a per-detail pixel limit and patch budget, x1.2 multiplier),
+ * which is also a close upper estimate for other providers once omp has
+ * downscaled the image (≤1568px by default).
+ */
+
+/** OpenAI image `detail` values; `undefined` means the provider default (`auto`). */
+export type ImageDetail = ImageContent["detail"];
+
+export type { ImageSize };
+
+// Larger than every detail level's pixel limit, so an unknown size charges
+// the level's full patch budget.
+const UNKNOWN_SIZE: ImageSize = { width: 65_535, height: 65_535 };
+
+let wireRule: ImageTokenization | undefined;
+
+/** The OpenAI Responses wire's image rule, resolved from the catalog once. */
+function openAiWireRule(): ImageTokenization {
+	if (wireRule) return wireRule;
+	const rule = resolveImageTokenization({ api: "openai-responses" });
+	if (!rule) throw new Error("The catalog has no image-tokenization rule for the openai-responses wire");
+	wireRule = rule;
+	return rule;
+}
+
+/**
+ * Estimated input tokens for one image. Unknown dimensions (undecodable data,
+ * remote URLs, provider file ids) charge the detail level's full patch budget.
+ */
+export function estimateImageTokens(size: ImageSize | null | undefined, detail?: ImageDetail): number {
+	return imageTokens(openAiWireRule(), size && size.width > 0 && size.height > 0 ? size : UNKNOWN_SIZE, detail);
+}
+
+// Enough decoded bytes to reach a JPEG SOF marker behind typical EXIF/ICC
+// segments; PNG/GIF/WebP need only the first 30 bytes. Multiple of 4 so the
+// base64 slice decodes cleanly.
+const HEADER_BASE64_CHARS = 4 * Math.ceil((64 * 1024) / 3);
+
+/** Pixel size read from the header of base64-encoded image data, or null. */
+export function base64ImageSize(base64: string): ImageSize | null {
+	if (base64.length === 0) return null;
+	const header = Buffer.from(base64.slice(0, HEADER_BASE64_CHARS), "base64");
+	const metadata = parseImageMetadata(header);
+	if (!metadata?.width || !metadata.height) return null;
+	return { width: metadata.width, height: metadata.height };
+}
+
+/** Pixel size of a `data:<mime>;base64,` URL, or null for any other URL. */
+export function dataUrlImageSize(url: string): ImageSize | null {
+	if (!url.startsWith("data:")) return null;
+	const comma = url.indexOf(",");
+	if (comma < 0 || !url.slice(0, comma).endsWith(";base64")) return null;
+	return base64ImageSize(url.slice(comma + 1));
+}
+
+/** {@link estimateImageTokens} for an in-memory image block. */
+export function estimateImageContentTokens(image: Pick<ImageContent, "data" | "detail">): number {
+	return estimateImageTokens(base64ImageSize(image.data), image.detail);
+}

package/src/index.ts

@@ -28,6 +28,8 @@ export * from "./thinking";
 export * from "./tool-context";
 // Tokenizer choice
 export * from "./tokenizer";
+// Lenient-aware tool argument validation
+export * from "./tool-arguments";
 // Types
 export * from "./types";
 // Yield utilities for Bun event-loop busy-wait prevention

package/src/prompts/dsml-tool-call-leak.md

@@ -0,0 +1,19 @@
+Tool call failed: your previous response tried to invoke a tool, but the DSML markup was malformed, so it arrived as plain text, no tool was executed, and the broken markup was removed from your response. Usually the opening `<｜DSML｜tool_calls>` and/or `<｜DSML｜invoke name="…">` tags are missing, or the tool name was written as a plain line.
+
+A tool call must be one complete envelope:
+
+```
+<｜DSML｜tool_calls>
+<｜DSML｜invoke name="TOOL_NAME">
+<｜DSML｜parameter name="ARG_NAME" string="true">text value</｜DSML｜parameter>
+<｜DSML｜parameter name="OTHER_ARG" string="false">{"json": "value"}</｜DSML｜parameter>
+</｜DSML｜invoke>
+</｜DSML｜tool_calls>
+```
+
+- `<｜DSML｜tool_calls>` wraps every call; put one `<｜DSML｜invoke>` per call inside it.
+- The tool name goes in the `name` attribute of `<｜DSML｜invoke>`, never on its own line.
+- Use `string="true"` for raw text values and `string="false"` for numbers, booleans, arrays, and objects (JSON).
+- Close every tag.
+
+Re-issue the intended call now in this shape, or reply in plain prose if no tool is needed.

package/src/speculative-execution.ts

@@ -1,5 +1,6 @@
 import * as path from "node:path";
-import { type AssistantMessage, validateToolArguments } from "@linxiraos/pi-ai";
+import type { AssistantMessage } from "@linxiraos/pi-ai";
+import { validateAgentToolArguments } from "./tool-arguments";
 import type {
 	AgentContext,
 	AgentLoopConfig,
@@ -712,15 +713,10 @@ export class SpeculativeOperationCoordinator {
 		}
 		let validatedArgs: Record<string, unknown>;
 		try {
-			validatedArgs = validateToolArguments(tool, toolCall);
+			validatedArgs = validateAgentToolArguments(tool, toolCall);
 		} catch {
-			// Lenience covers schema mismatches; a parse failure has no args to hand over.
-			if (!tool.lenientArgValidation || "__parseError" in toolCall.arguments) {
-				this.ineligible(toolCall, "tool arguments are not valid", source, parentToolCallId);
-				return undefined;
-			}
-			validatedArgs = { ...toolCall.arguments };
-			delete validatedArgs.__rawJson;
+			this.ineligible(toolCall, "tool arguments are not valid", source, parentToolCallId);
+			return undefined;
 		}
 		let executionArgs: Record<string, unknown>;
 		try {

package/src/telemetry.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.
  *
@@ -126,47 +126,47 @@ export const enum OpenAIAttr {
 
 /** Project extension attributes. Kept out of the reserved `gen_ai.*` namespace. */
 export 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",
+	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",
 	// Marks chat spans emitted outside the agent loop (compaction, handoff, branch
 	// summary, image inspection, …). Lets dashboards split oneshot cost / latency
 	// from main-turn cost without overloading the semconv `gen_ai.operation.name`.
-	OneshotKind = "omp.gen_ai.oneshot.kind",
+	OneshotKind = "zeta.gen_ai.oneshot.kind",
 	// Gateway / proxy (LiteLLM, Helicone, Portkey, …) — populated when a known
 	// gateway header pattern is detected on the upstream response. The base
 	// `gen_ai.provider.name` continues to track the *upstream* provider (e.g.
 	// `anthropic`) that the gateway routed to.
-	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",
+	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}. */
@@ -204,17 +204,25 @@ export interface ChatUsageSnapshot {
 
 /** Context passed to the cost estimator. */
 export interface CostEstimatorContext {
+	/** OTel provider label (`gen_ai.provider.name`). */
 	readonly provider: string;
+	/** Provider id before OTel normalization (e.g. `openai-codex` for the `openai` label). */
+	readonly providerId: string | undefined;
+	/** Model id reported on the response; a provider may report a served model instead of the requested one. */
 	readonly model: string;
+	/** Requested model id, when the caller knows it. */
+	readonly modelId: string | undefined;
 	readonly serviceTier: ServiceTier | undefined;
 	readonly usage: ChatUsageSnapshot;
+	/** Cost the provider already computed for this request; the value persisted with the message. */
+	readonly usageCost: Usage["cost"];
 }
 
 /**
  * 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 =
@@ -263,7 +271,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;
 }
@@ -828,15 +836,27 @@ function serializeRequestMessagesForTelemetry(
 ): string | undefined {
 	const serializer = telemetry.config.contentSerializer?.requestMessages;
 	if (serializer) return callContentSerializer(telemetry, "requestMessages", () => serializer(request));
+	const systemParts = normalizeSystemPromptParts(request.systemPrompt);
+	const requestMessages = request.messages ?? [];
+	const total = systemParts.length + requestMessages.length;
+	if (total === 0) return undefined;
+	// Summarize only what survives the message cap; the rest is counted.
 	const messages: TelemetryMessageSummary[] = [];
-	for (const text of normalizeSystemPromptParts(request.systemPrompt))
+	for (const text of systemParts) {
+		if (messages.length === MAX_TELEMETRY_MESSAGE_COUNT) break;
 		messages.push({ role: "system", content: summarizeTelemetryValue(text) });
-	if (request.messages) {
-		for (const message of request.messages) {
-			messages.push({ role: message.role, content: summarizeTelemetryValue(message.content) });
-		}
 	}
-	return messages.length === 0 ? undefined : stringifyJsonAttribute(limitTelemetryMessages(messages));
+	for (const message of requestMessages) {
+		if (messages.length === MAX_TELEMETRY_MESSAGE_COUNT) break;
+		messages.push({ role: message.role, content: summarizeTelemetryValue(message.content) });
+	}
+	if (total > MAX_TELEMETRY_MESSAGE_COUNT) {
+		messages.push({
+			role: "system",
+			content: { kind: "truncated", omittedMessages: total - MAX_TELEMETRY_MESSAGE_COUNT },
+		});
+	}
+	return stringifyJsonAttribute(messages);
 }
 
 function serializeResponseTextForTelemetry(telemetry: AgentTelemetry, message: AssistantMessage): string | undefined {
@@ -1014,17 +1034,6 @@ function callContentSerializer(
 	}
 }
 
-function limitTelemetryMessages(messages: readonly TelemetryMessageSummary[]): TelemetryMessageSummary[] {
-	const limited = messages.slice(0, MAX_TELEMETRY_MESSAGE_COUNT);
-	if (messages.length > MAX_TELEMETRY_MESSAGE_COUNT) {
-		limited.push({
-			role: "system",
-			content: { kind: "truncated", omittedMessages: messages.length - MAX_TELEMETRY_MESSAGE_COUNT },
-		});
-	}
-	return limited;
-}
-
 function limitTelemetryToolCalls(toolCalls: readonly TelemetryToolCallSummary[]): TelemetryToolCallSummary[] {
 	const limited = toolCalls.slice(0, MAX_TELEMETRY_ARRAY_ITEMS);
 	if (toolCalls.length > MAX_TELEMETRY_ARRAY_ITEMS) {
@@ -1138,6 +1147,8 @@ export async function finishChatSpan(
 	message: AssistantMessage,
 	options: {
 		readonly stepNumber: number;
+		/** Requested model id; `message.model` may name a served fallback model instead. */
+		readonly modelId?: string;
 		readonly serviceTier?: ServiceTier;
 		readonly responseHeaders?: Readonly<Record<string, string>>;
 		readonly baseUrl?: string;
@@ -1147,7 +1158,7 @@ export async function finishChatSpan(
 	applyChatResponseAttributes(span, message);
 	applyUsageAttributes(span, message.usage);
 	applyGatewayAttributes(span, options.responseHeaders, options.baseUrl);
-	const cost = applyCostEstimate(telemetry, span, message, options.serviceTier, options.stepNumber);
+	const cost = applyCostEstimate(telemetry, span, message, options.serviceTier, options.stepNumber, options.modelId);
 	if (telemetry) {
 		await emitChatUsage(telemetry, span, {
 			operation: GenAIOperation.Chat,
@@ -1367,10 +1378,12 @@ function applyCostEstimate(
 	message: AssistantMessage,
 	serviceTier: ServiceTier | undefined,
 	stepNumber: number | undefined,
+	modelId: string | undefined,
 ): AppliedCostEstimate {
 	if (!telemetry) return EMPTY_COST;
 	return applyCostEstimateForUsage(telemetry, span, {
 		model: message.model,
+		modelId,
 		provider: message.provider,
 		serviceTier,
 		stepNumber,
@@ -1383,6 +1396,7 @@ function applyCostEstimateForUsage(
 	span: Span,
 	input: {
 		readonly model: string;
+		readonly modelId: string | undefined;
 		readonly provider: string | undefined;
 		readonly serviceTier: ServiceTier | undefined;
 		readonly stepNumber: number | undefined;
@@ -1398,9 +1412,12 @@ function applyCostEstimateForUsage(
 	try {
 		result = estimator({
 			provider,
+			providerId: input.provider,
 			model: input.model,
+			modelId: input.modelId,
 			serviceTier: input.serviceTier,
 			usage,
+			usageCost: input.usage.cost,
 		});
 	} catch (err) {
 		emitTelemetryWarning(telemetry, {
@@ -1620,6 +1637,7 @@ export async function recordManualChatTelemetry(
 	if (telemetry) {
 		const applied = applyCostEstimateForUsage(telemetry, span, {
 			model: options.responseModel ?? options.model.id,
+			modelId: options.model.id,
 			provider: options.model.provider,
 			serviceTier: options.serviceTier,
 			stepNumber: options.stepNumber,
@@ -1771,10 +1789,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. */
@@ -1889,6 +1907,7 @@ export async function instrumentedCompleteSimple<TApi extends Api>(
 				: await runOnce();
 			await finishChatSpan(telemetry, chatSpan, message, {
 				stepNumber,
+				modelId: model.id,
 				serviceTier: options.serviceTier,
 				responseHeaders: capturedHeaders,
 				baseUrl: model.baseUrl,
@@ -2098,33 +2117,33 @@ export function fireOnRunEnd(telemetry: AgentTelemetry, summary: AgentRunSummary
 	}
 }
 
-/** 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 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",
-}
-
-/** Stamp the aggregate `omp.gen_ai.agent.*` attributes on the given span. */
+	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",
+}
+
+/** Stamp the aggregate `zeta.gen_ai.agent.*` attributes on the given span. */
 function applyAggregateAttributes(span: Span, summary: AgentRunSummary, coverage: AgentRunCoverage): void {
 	span.setAttribute(OmpGenAIAggregateAttr.ChatsCount, summary.chats.total);
 	span.setAttribute(OmpGenAIAggregateAttr.ChatsTotalLatencyMs, summary.chats.totalLatencyMs);

package/src/tokenizer.ts

@@ -5,6 +5,7 @@ import { materializeString, stringifyJson } from "@linxiraos/pi-utils";
 import { LRUCache } from "@linxiraos/pi-utils/lru";
 import * as snapcompact from "@linxiraos/pi-snapcompact";
 import { isEstimateCacheable, messageEstimateVersion } from "./compaction/message-cache";
+import { base64ImageSize, estimateImageContentTokens } from "./image-tokens";
 import type { AgentMessage } from "./types";
 
 const testEnv = Bun.env.NODE_ENV === "test";
@@ -131,12 +132,6 @@ export interface TokenBudgetCheck {
 	exact: boolean;
 }
 
-/**
- * Image content has no tokenizer representation; charge a fixed estimate
- * matching what providers typically bill for inline images.
- */
-const IMAGE_TOKEN_ESTIMATE = 1200;
-
 /**
  * Memoized estimates for one message under this tokenizer's encoding, split by
  * the {@link MessageCountOptions.excludeEncryptedReasoning} option so the two
@@ -154,13 +149,15 @@ interface MessageEstimate {
  * Model-aware local token counter. Immutable: the catalog-resolved encoding
  * is fixed at construction, so a cached count can never straddle two
  * encodings. An `Agent` owns one for its active model (swapping the instance
- * when the model's encoding changes); one-shot flows construct their own for
- * the model that will be billed. Known tokenizer families use exact native
- * counts; unknown models keep the fast byte estimate (or o200k when
- * `PI_TOKENIZER_ACCURATE=1`).
+ * when the model's encoding or snapcompact frame pricing changes); one-shot
+ * flows construct their own for the model that will be billed. Known
+ * tokenizer families use exact native counts; unknown models keep the fast
+ * byte estimate (or o200k when `PI_TOKENIZER_ACCURATE=1`).
  */
 export class Tokenizer {
 	readonly #encoding: natives.Encoding | null;
+	readonly #frameBilling: snapcompact.FrameBilling;
+	readonly frameBillingKey: string;
 
 	/** Exact counts only; byte fallbacks remain mode-dependent and uncached. */
 	readonly #nativeCounts = new LRUCache<string, number>({
@@ -179,8 +176,10 @@ export class Tokenizer {
 	 */
 	#estimates = new WeakMap<AgentMessage, MessageEstimate>();
 
-	constructor(model?: Pick<Model, "tokenizer"> | null) {
+	constructor(model?: (Pick<Model, "tokenizer"> & snapcompact.ShapeTarget) | null) {
 		this.#encoding = tokenizerEncodingForModel(model);
+		this.#frameBilling = snapcompact.frameBilling(model ?? undefined);
+		this.frameBillingKey = snapcompact.frameBillingKey(this.#frameBilling);
 	}
 
 	get encoding(): natives.Encoding | null {
@@ -219,7 +218,8 @@ export class Tokenizer {
 	 * Settled historical messages are counted once and reused until an owner
 	 * (prune/shake/strip-images) calls `invalidateMessageCache`; streaming
 	 * assistants bypass the memo entirely (see the message-cache settle-gate
-	 * invariant). Image blocks charge a fixed per-image estimate.
+	 * invariant). Image blocks charge {@link estimateImageContentTokens}, the
+	 * same dimension-based estimate the native remote-compaction probe applies.
 	 */
 	countMessage(message: AgentMessage, options?: MessageCountOptions): number {
 		const floored = options?.excludeEncryptedReasoning === true;
@@ -273,7 +273,7 @@ export class Tokenizer {
 						if (block.type === "text" && block.text) {
 							fragments.push(block.text);
 						} else if (block.type === "image") {
-							extra += IMAGE_TOKEN_ESTIMATE;
+							extra += estimateImageContentTokens(block);
 						}
 					}
 				}
@@ -323,7 +323,7 @@ export class Tokenizer {
 						if (block.type === "text" && block.text) {
 							fragments.push(block.text);
 						} else if (block.type === "image") {
-							extra += IMAGE_TOKEN_ESTIMATE;
+							extra += estimateImageContentTokens(block);
 						}
 					}
 				}
@@ -336,11 +336,12 @@ export class Tokenizer {
 					if (message.blocks) {
 						for (const block of message.blocks) {
 							if (block.type === "text") fragments.push(block.text);
-							else extra += snapcompact.FRAME_TOKEN_ESTIMATE;
+							else extra += this.#frameTokens(block.data);
 						}
 					} else if (message.images) {
-						// Snapcompact frames render at ≥1568px; providers bill the downscaled cap.
-						extra += message.images.length * snapcompact.FRAME_TOKEN_ESTIMATE;
+						for (const image of message.images) {
+							extra += this.#frameTokens(image.data);
+						}
 					}
 				}
 				break;
@@ -352,4 +353,10 @@ export class Tokenizer {
 		if (fragments.length === 0) return extra;
 		return extra + this.countTokens(fragments);
 	}
+
+	/** One snapcompact frame at the active model's price for its pixel size; unreadable frames cost the ceiling. */
+	#frameTokens(data: string): number {
+		const size = base64ImageSize(data);
+		return size ? snapcompact.frameTokens(this.#frameBilling, size) : snapcompact.FRAME_TOKEN_ESTIMATE;
+	}
 }

package/src/tool-arguments.ts

@@ -0,0 +1,38 @@
+import { type ToolCall, validateToolArguments } from "@linxiraos/pi-ai";
+import type { AgentTool } from "./types";
+
+/**
+ * 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 function validateAgentToolArguments(
+	tool: AgentTool,
+	toolCall: ToolCall,
+	source: ToolArgumentSource = "parsed",
+): ToolCall["arguments"] {
+	try {
+		return validateToolArguments(tool, toolCall);
+	} catch (error) {
+		const args: unknown = toolCall.arguments;
+		if (!tool.lenientArgValidation) throw error;
+		if (args === null || typeof args !== "object" || Array.isArray(args)) return args as ToolCall["arguments"];
+		if (source === "parsed" && "__parseError" in args) throw error;
+		const fallback = { ...(args as Record<string, unknown>) };
+		delete fallback.__parseError;
+		delete fallback.__rawJson;
+		return fallback;
+	}
+}

package/src/types.ts

@@ -328,6 +328,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.
@@ -341,7 +351,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