@linxiraos/pi-ai 1.2.0 → 1.3.0

package/src/judgment/wire.ts

@@ -3,7 +3,8 @@
  * encodes, and decodes one request for each API it serves. Internal to the
  * judgment module; `native.ts` maps every judgment API to its dialect.
  */
-import type { Usage } from "../types";
+import type { ImageContent, Usage } from "../types";
+import type { JudgmentImageInput } from "@linxiraos/pi-catalog/compat/judgment-images";
 import type { JudgmentRequest } from "./types";
 
 /** Where one attempt posts and which bearer token it sends. */
@@ -23,6 +24,9 @@ export interface DecodedJudgment {
 	usage: Usage;
 }
 
+/** Image assets kept separately from judgment state for asset-aware native wires. */
+export type JudgmentImageAssets = Readonly<Record<string, ImageContent>>;
+
 /** How one judgment API addresses, encodes, and decodes a request. */
 export interface JudgmentWire {
 	/**
@@ -30,8 +34,18 @@ export interface JudgmentWire {
 	 * Throws when the credential cannot address the endpoint (e.g. no account id).
 	 */
 	target(baseUrl: string, model: string, key: string): JudgmentTarget;
-	/** Request body for `model`. */
-	encode(request: JudgmentRequest, model: string): unknown;
+	/** Request body for `model`, with optional asset context for dialects that preserve references. */
+	encode(request: JudgmentRequest, model: string, imageAssets?: JudgmentImageAssets): unknown;
+	/** Headers this dialect adds to requests that carry images. */
+	imageHeaders?: Readonly<Record<string, string>>;
+	/** Image input this dialect accepts; absent means text-only. */
+	images?: JudgmentImageInput;
+	/** Whether raw asset maps can be transported without loss by this dialect. */
+	supportsImageAssets?: boolean;
+	/** Whether image support must be enabled explicitly for direct NativeJudge construction. */
+	imagesRequireOptIn?: boolean;
+	/** Whether this wire drops per-image detail metadata. */
+	ignoresImageDetail?: boolean;
 	/** The response's answers and usage; `undefined` when the payload is not this API's response shape. */
 	decode(payload: unknown): DecodedJudgment | undefined;
 }

package/src/provider-session-state.ts

@@ -18,8 +18,8 @@
  *   siblings are endpoint-scoped and stay: `strictToolsDisabled`
  *   (grammar-too-large 400 for the model's tool schema),
  *   `replayUnsignedThinkingDisabled` / `thinkingReplayDisabled` (the endpoint
- *   is a signing proxy), `prefixDroppedThinkingBlocks` (blocks a prefix-binding
- *   400 made the client strip).
+ *   is a signing proxy), `prefixDroppedThinkingBlocks` (blocks a rejected
+ *   replay made the client strip).
  * - **OpenAI Responses** — the `previous_response_id` chain baselines are
  *   account-scoped: a stored response belongs to the account that created it.
  *   Strict-tools / reasoning-effort fallbacks, replay warmup and the chaining

package/src/providers/amazon-bedrock.ts

@@ -50,6 +50,7 @@ import { invalidateAwsCredentialCache, resolveAwsCredentials } from "./aws-crede
 import { decodeEventStream } from "./aws-eventstream";
 import { signRequest } from "./aws-sigv4";
 import { isThinkingPrefixBindingError } from "./anthropic";
+import { isAnthropicNarrationSignature } from "./anthropic-signature";
 import { parseAnthropicInputTransformations, THINKING_BINDING_CONTROLS_BETA } from "./anthropic-wire";
 import { isBedrockRequestMetadataValue } from "./bedrock-request-metadata";
 import { transformMessages } from "./transform-messages";
@@ -977,6 +978,8 @@ function handleContentBlockStop(
 			stream.push({ type: "text_end", contentIndex: index, content: block.text, partial: output });
 			break;
 		case "thinking":
+			// Claude on Bedrock carries Anthropic's signature format, narration kind included.
+			if (block.thinkingSignature && isAnthropicNarrationSignature(block.thinkingSignature)) block.narration = true;
 			stream.push({ type: "thinking_end", contentIndex: index, content: block.thinking, partial: output });
 			break;
 		case "toolCall":
@@ -1087,7 +1090,7 @@ function convertMessages(
 	promptCachePolicy: BedrockPromptCachePolicy,
 ): WireMessage[] {
 	const result: WireMessage[] = [];
-	const transformedMessages = transformMessages(context.messages, model, normalizeToolCallId);
+	const transformedMessages = transformMessages(context.messages, model, id => normalizeToolCallId(id));
 
 	for (let i = 0; i < transformedMessages.length; i++) {
 		const m = transformedMessages[i];

package/src/providers/anthropic-client.ts

@@ -278,7 +278,7 @@ export class AnthropicHttpClient {
 					continue;
 				}
 				if (error instanceof AIError.AnthropicConnectionTimeoutError) throw error;
-				throw new AIError.AnthropicConnectionError(error);
+				throw new AIError.AnthropicConnectionError(error, url);
 			}
 
 			if (response.ok) return response;

package/src/providers/anthropic-images.ts

@@ -0,0 +1,263 @@
+/**
+ * Claude's image contract, enforced before a request leaves the client. Every
+ * wire that delivers images to a Claude reader shares it: `anthropic-messages`
+ * always, and Google's Cloud Code Assist wire when resolved policy declares
+ * the host's limits (`max-image-dimension` / `max-image-payload-bytes`).
+ */
+import { logger } from "@linxiraos/pi-utils";
+import type { Context, ImageContent, Message, Model, TextContent } from "../types";
+
+const ANTHROPIC_MANY_IMAGE_THRESHOLD = 20;
+const ANTHROPIC_MANY_IMAGE_MAX_DIMENSION = 2000;
+/**
+ * Image contract of the canonical Anthropic Messages API, used when resolved
+ * model policy names no other: 8000px per side ("At least one of the image
+ * dimensions exceed max allowed size: 8000 pixels") and a 10 MB base64
+ * payload per block ("image exceeds 10 MB maximum: 14012300 bytes >
+ * 10485760 bytes"), measured on the encoded string rather than the decoded
+ * bytes. Either rejection poisons every retry and model fallback because the
+ * block stays in context, so both are clamped before the request goes out.
+ * A host with a different image contract sets `max-image-dimension` /
+ * `max-image-payload-bytes` in the KDL compatibility rules.
+ */
+const ANTHROPIC_MAX_IMAGE_DIMENSION = 8000;
+const ANTHROPIC_MAX_IMAGE_PAYLOAD_BYTES = 10 * 1024 * 1024;
+/** Headroom for the surrounding JSON and any provider-side accounting. */
+const ANTHROPIC_IMAGE_PAYLOAD_HEADROOM = 0.9;
+/** Re-encode passes allowed to bring one image under the byte budget. */
+const ANTHROPIC_IMAGE_RESIZE_ATTEMPTS = 4;
+
+/**
+ * Image bounds for one request. `maxDimension` and `payloadBudget` come from
+ * resolved model policy (`max-image-dimension`, `max-image-payload-bytes`) so
+ * a deployment whose image contract differs from the canonical API can
+ * override them, and the many-image path tightens `maxDimension` further
+ * because many images share one request budget.
+ */
+interface AnthropicImageCaps {
+	maxDimension: number;
+	payloadBudget: number;
+}
+
+function countAnthropicImageBlocks(messages: Message[]): number {
+	let count = 0;
+	for (const message of messages) {
+		if (message.role !== "user" && message.role !== "developer" && message.role !== "toolResult") continue;
+		if (!Array.isArray(message.content)) continue;
+		for (const block of message.content) {
+			if (block.type === "image") count++;
+		}
+	}
+	return count;
+}
+
+/**
+ * Ceiling on encoder output pixels in flight. One 8000x8000 RGBA surface is
+ * roughly 256 MiB, so admitting four of them would spike the CLI by a
+ * gigabyte; at the full-resolution cap this yields a single pipeline, while
+ * the many-image cap encodes at most 2000px and keeps the four-way fan-out.
+ */
+const ANTHROPIC_IMAGE_RESIZE_PIXEL_BUDGET = 16_000_000;
+const ANTHROPIC_IMAGE_RESIZE_MAX_CONCURRENCY = 4;
+
+function anthropicImageResizeConcurrency(maxDimension: number): number {
+	const perPipeline = maxDimension * maxDimension;
+	if (perPipeline <= 0) return ANTHROPIC_IMAGE_RESIZE_MAX_CONCURRENCY;
+	return Math.max(
+		1,
+		Math.min(ANTHROPIC_IMAGE_RESIZE_MAX_CONCURRENCY, Math.floor(ANTHROPIC_IMAGE_RESIZE_PIXEL_BUDGET / perPipeline)),
+	);
+}
+
+/**
+ * Memoized resize results keyed on ImageContent identity, per cap pair.
+ * Callers keep message objects stable across turns, so without this every
+ * request (and every in-provider retry of a fresh turn) re-decodes and
+ * re-encodes the same oversized screenshots. A cached value identical to the
+ * key means "already within bounds / unresizable — skip the decode". The caps
+ * depend on image count and on resolved policy, so each pair keeps its own
+ * cache: a value cached at 8000px is not reusable at 2000px.
+ */
+const anthropicImageResizeCaches = new Map<string, WeakMap<ImageContent, ImageContent>>();
+
+function anthropicImageResizeCache(caps: AnthropicImageCaps): WeakMap<ImageContent, ImageContent> {
+	const key = `${caps.maxDimension}:${caps.payloadBudget}`;
+	const existing = anthropicImageResizeCaches.get(key);
+	if (existing) return existing;
+	const created = new WeakMap<ImageContent, ImageContent>();
+	anthropicImageResizeCaches.set(key, created);
+	return created;
+}
+
+type ResizeLimiter = <R>(fn: () => Promise<R>) => Promise<R>;
+
+/**
+ * Bounded-concurrency gate for image decode/encode work. The many-image path
+ * fans out over every block of every message; unbounded, 100+ oversized images
+ * would decode concurrently and spike memory by gigabytes. Slots are handed
+ * off directly to the next waiter on release.
+ */
+function createResizeLimiter(limit: number): ResizeLimiter {
+	let active = 0;
+	const queue: (() => void)[] = [];
+	return async fn => {
+		if (active >= limit) {
+			const { promise, resolve } = Promise.withResolvers<void>();
+			queue.push(resolve);
+			await promise;
+		} else {
+			active++;
+		}
+		try {
+			return await fn();
+		} finally {
+			const next = queue.shift();
+			if (next) next();
+			else active--;
+		}
+	};
+}
+
+async function resizeAnthropicImageBlock(block: ImageContent, caps: AnthropicImageCaps): Promise<ImageContent> {
+	const { maxDimension, payloadBudget } = caps;
+	try {
+		const inputBuffer = Buffer.from(block.data, "base64");
+		const { width, height } = await new Bun.Image(inputBuffer).metadata();
+		if (!width || !height) return block;
+		const overDimension = width > maxDimension || height > maxDimension;
+		const overBudget = block.data.length > payloadBudget;
+		if (!overDimension && !overBudget) return block;
+
+		// Fitting the pixel cap does not imply fitting the byte cap: a dense
+		// screenshot re-encodes large even at the cap. Shrink by the overshoot in
+		// area terms until the payload fits or the passes run out.
+		let scale = Math.min(1, maxDimension / width, maxDimension / height);
+		let best: { buffer: Uint8Array; mimeType: string } | undefined;
+		for (let attempt = 0; attempt < ANTHROPIC_IMAGE_RESIZE_ATTEMPTS; attempt++) {
+			const targetWidth = Math.max(1, Math.min(maxDimension, Math.round(width * scale)));
+			const targetHeight = Math.max(1, Math.min(maxDimension, Math.round(height * scale)));
+			// One encoder at a time: a full-resolution surface is hundreds of
+			// megabytes, so the two candidates never coexist.
+			const png = await new Bun.Image(inputBuffer).resize(targetWidth, targetHeight).png().bytes();
+			const jpeg = await new Bun.Image(inputBuffer).resize(targetWidth, targetHeight).jpeg({ quality: 85 }).bytes();
+			best =
+				png.length <= jpeg.length
+					? { buffer: png, mimeType: "image/png" }
+					: { buffer: jpeg, mimeType: "image/jpeg" };
+
+			// Base64 expands three bytes into four characters; the encoded length
+			// is what Anthropic measures, so derive it without encoding.
+			const encoded = Math.ceil(best.buffer.length / 3) * 4;
+			if (encoded <= payloadBudget) break;
+			if (targetWidth === 1 && targetHeight === 1) break;
+			scale *= Math.max(0.25, Math.sqrt(payloadBudget / encoded) * 0.9);
+		}
+		if (!best) return block;
+
+		const data = Buffer.from(best.buffer).toString("base64");
+		// An image inside the pixel cap is only worth replacing if it shrank.
+		if (!overDimension && data.length >= block.data.length) return block;
+		// The rebuilt block carries no `url` or `providerFile`: those reference
+		// the original bytes, and Anthropic validates a referenced image after
+		// fetching it, so keeping either would resend the oversized copy.
+		return {
+			type: "image",
+			data,
+			mimeType: best.mimeType,
+		};
+	} catch (error) {
+		logger.warn("anthropic: failed to resize oversized image", {
+			mimeType: block.mimeType,
+			error: error instanceof Error ? error.message : String(error),
+		});
+		return block;
+	}
+}
+
+async function resizeAnthropicImageContent(
+	content: (TextContent | ImageContent)[],
+	state: { resized: number },
+	limit: ResizeLimiter,
+	caps: AnthropicImageCaps,
+): Promise<(TextContent | ImageContent)[]> {
+	let changed = false;
+	const cache = anthropicImageResizeCache(caps);
+	const next = await Promise.all(
+		content.map(async block => {
+			if (block.type !== "image") return block;
+			let resized = cache.get(block);
+			if (resized === undefined) {
+				resized = await limit(() => resizeAnthropicImageBlock(block, caps));
+				cache.set(block, resized);
+			}
+			if (resized !== block) {
+				changed = true;
+				state.resized++;
+			}
+			return resized;
+		}),
+	);
+	return changed ? next : content;
+}
+
+async function resizeAnthropicImageMessage(
+	message: Message,
+	state: { resized: number },
+	limit: ResizeLimiter,
+	caps: AnthropicImageCaps,
+): Promise<Message> {
+	if (message.role === "user" || message.role === "developer") {
+		if (!Array.isArray(message.content)) return message;
+		const content = await resizeAnthropicImageContent(message.content, state, limit, caps);
+		return content === message.content ? message : { ...message, content };
+	}
+	if (message.role === "toolResult") {
+		const content = await resizeAnthropicImageContent(message.content, state, limit, caps);
+		return content === message.content ? message : { ...message, content };
+	}
+	return message;
+}
+
+/**
+ * Clamp every image a Claude reader would receive to the host's contract.
+ * Limits the model's policy leaves unset fall back to the canonical Anthropic
+ * API. Returns `context` itself when nothing needed resizing.
+ */
+export async function prepareAnthropicImageContext(
+	context: Context,
+	model: Model<"anthropic-messages"> | Model<"google-gemini-cli">,
+): Promise<Context> {
+	if (!model.input.includes("image")) return context;
+	const imageCount = countAnthropicImageBlocks(context.messages);
+	if (imageCount === 0) return context;
+	// Many images share one request size budget, so they get the tighter cap.
+	// A smaller set only has to clear the host's per-image limit.
+	const hostMaxDimension = model.compat.maxImageDimension ?? ANTHROPIC_MAX_IMAGE_DIMENSION;
+	const maxDimension =
+		imageCount > ANTHROPIC_MANY_IMAGE_THRESHOLD
+			? Math.min(ANTHROPIC_MANY_IMAGE_MAX_DIMENSION, hostMaxDimension)
+			: hostMaxDimension;
+	const maxPayloadBytes = model.compat.maxImagePayloadBytes ?? ANTHROPIC_MAX_IMAGE_PAYLOAD_BYTES;
+	const caps: AnthropicImageCaps = {
+		maxDimension,
+		payloadBudget: Math.floor(maxPayloadBytes * ANTHROPIC_IMAGE_PAYLOAD_HEADROOM),
+	};
+
+	let changed = false;
+	const state = { resized: 0 };
+	const limit = createResizeLimiter(anthropicImageResizeConcurrency(maxDimension));
+	const messages = await Promise.all(
+		context.messages.map(async message => {
+			const next = await resizeAnthropicImageMessage(message, state, limit, caps);
+			if (next !== message) changed = true;
+			return next;
+		}),
+	);
+	if (!changed) return context;
+	logger.debug("anthropic: resized oversized images", {
+		imageCount,
+		resized: state.resized,
+		maxDimension,
+	});
+	return { ...context, messages };
+}

package/src/providers/anthropic-messages-server.ts

@@ -538,9 +538,53 @@ function mapStopReasonOut(reason: StopReason, hasToolUse: boolean): "end_turn" |
 	}
 }
 
+/**
+ * Collapse a server-side-fallback turn for a bridge client that never opted
+ * into the beta: drop the `fallback` markers and keep reasoning from one
+ * model only. The downstream client never accepted a `fallbacks` request
+ * param and the bridge does not forward one, so the marker cannot go on the
+ * wire; without it, two models' signed reasoning replayed back-to-back reads
+ * as one modified chain and is the shape Anthropic rejects.
+ *
+ * The segment kept is the first that has any reasoning, not the last. The
+ * streaming encoder has already sent the first segment's blocks when the
+ * boundary arrives and cannot retract them, so first-segment is the only
+ * rule it can decide online; this path uses the same rule so streamed and
+ * non-streamed turns present the same reasoning. The offline converter
+ * (`collapseFallbackSegments` in `anthropic.ts`) can see the whole turn and
+ * keeps the last segment instead — both guarantee a single chain survives.
+ */
+function collapseFallbackSegmentsKeepFirst(content: AssistantMessage["content"]): AssistantMessage["content"] {
+	let firstReasoningSegment = -1;
+	let segment = 0;
+	for (const block of content) {
+		if (block.type === "fallback") segment++;
+		else if (block.type === "thinking" || block.type === "redactedThinking") {
+			firstReasoningSegment = segment;
+			break;
+		}
+	}
+	if (firstReasoningSegment === -1) {
+		return content.filter(block => block.type !== "fallback");
+	}
+	const collapsed: AssistantMessage["content"] = [];
+	segment = 0;
+	for (const block of content) {
+		if (block.type === "fallback") {
+			segment++;
+			continue;
+		}
+		if ((block.type === "thinking" || block.type === "redactedThinking") && segment !== firstReasoningSegment) {
+			continue;
+		}
+		collapsed.push(block);
+	}
+	return collapsed;
+}
+
 function encodeContentBlocks(message: AssistantMessage): Record<string, unknown>[] {
 	const blocks: Record<string, unknown>[] = [];
-	for (const c of message.content) {
+	for (const c of collapseFallbackSegmentsKeepFirst(message.content)) {
 		switch (c.type) {
 			case "text":
 				blocks.push({ type: "text", text: c.text });
@@ -668,6 +712,20 @@ export function encodeStream(
 			// preceding text/thinking block before it opens, so no block that is
 			// still open is ever renumbered.
 			const suppressed = new Set<number>();
+			// A persisted `fallback` marker occupies a content index but is
+			// never emitted — the bridge client never opted into the beta, so
+			// the marker cannot go on the wire. The walk below records each
+			// marker (and every other block this encoder cannot emit) in
+			// `suppressed` so `wireIndex` stays dense. Once a boundary has been
+			// passed with reasoning already sent, every later segment's
+			// reasoning is a second signed chain the client must not receive;
+			// the first chain is already on the wire and cannot be retracted,
+			// so it is the one that survives (see
+			// `collapseFallbackSegmentsKeepFirst`). `reasoningSeen` tracks what
+			// the client actually received, which is why redacted reasoning —
+			// which this encoder has no event for — does not set it.
+			let reasoningSeen = false;
+			let suppressLaterReasoning = false;
 			const wireIndex = (contentIndex: number): number => {
 				let shift = 0;
 				for (const index of suppressed) {
@@ -707,6 +765,20 @@ export function encodeStream(
 				while (nextContentIndexToInspect < limit) {
 					const contentIndex = nextContentIndexToInspect++;
 					const content = message.content[contentIndex];
+					if (content?.type === "fallback") {
+						// Never on the wire, so keep the numbering dense. Latch the
+						// collapse only when the client already has this turn's first
+						// chain: what follows would be a second one.
+						suppressed.add(contentIndex);
+						if (reasoningSeen) suppressLaterReasoning = true;
+						continue;
+					}
+					if (content?.type === "redactedThinking") {
+						// Redacted reasoning has no stream event, so it never reaches
+						// the client; account for its index like any other hole.
+						suppressed.add(contentIndex);
+						continue;
+					}
 					if (content?.type !== "anthropicServerTool") continue;
 					ensureStart(message);
 					const index = wireIndex(contentIndex);
@@ -781,6 +853,15 @@ export function encodeStream(
 						case "thinking_start": {
 							emitServerToolBlocksBefore(ev.partial, ev.contentIndex);
 							ensureStart(ev.partial);
+							if (suppressLaterReasoning) {
+								// A later segment's reasoning is a second signed
+								// chain; drop the whole block — start, deltas,
+								// signature and stop — and account for its index
+								// so later blocks stay densely numbered.
+								suppressed.add(ev.contentIndex);
+								break;
+							}
+							reasoningSeen = true;
 							const index = wireIndex(ev.contentIndex);
 							open.set(ev.contentIndex, { index, kind: "thinking" });
 							controller.enqueue(
@@ -793,6 +874,7 @@ export function encodeStream(
 							break;
 						}
 						case "thinking_delta":
+							if (suppressed.has(ev.contentIndex)) break;
 							controller.enqueue(
 								sseFrame("content_block_delta", {
 									type: "content_block_delta",
@@ -802,6 +884,7 @@ export function encodeStream(
 							);
 							break;
 						case "thinking_end": {
+							if (suppressed.has(ev.contentIndex)) break;
 							const c = ev.partial.content[ev.contentIndex];
 							if (c?.type === "thinking" && c.thinkingSignature) {
 								controller.enqueue(

package/src/providers/anthropic-signature.ts

@@ -1,21 +1,26 @@
 /**
- * Recovers the serving model id Anthropic embeds in thinking-block signatures.
+ * Reads the cleartext header Anthropic embeds in thinking-block signatures.
  *
  * A signature is a base64 protobuf: outer `{1: version, 2: envelope}`, envelope
  * `{1: header, 2..5: nonce/ciphertext/tag}`, header
- * `{1: schema, 5: hash, 6: model, 8: "thinking", 11: org uuid, 15: profile, 21: unix ts}`.
+ * `{1: schema, 5: hash, 6: model, 8: kind, 11: org uuid, 15: profile, 21: unix ts}`.
  * Field 6 names the model that actually produced the block — a concrete
  * snapshot (`claude-haiku-4-5-20251001`) or an internal codename
  * (`numbat-v6-…`) — which lets a caller notice a gateway serving something other
  * than the requested model. The v4 outer format (`CAQS…`) ships a header
  * without field 6; the decoder then yields nothing.
+ * Field 8 names the block kind: `thinking` for reasoning, `narration` for the
+ * user-facing prose the API converts into a thinking block when the model
+ * writes it between tool calls (connector-text summarization).
  */
 
 const OUTER_ENVELOPE_FIELD = 2;
 const ENVELOPE_HEADER_FIELD = 1;
 const HEADER_MODEL_FIELD = 6;
+const HEADER_KIND_FIELD = 8;
 const MAX_MODEL_ID_LENGTH = 128;
 const MODEL_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:/-]*$/;
+const NARRATION_KIND = Buffer.from("narration");
 
 /** Finds a length-delimited field, rejecting tags and lengths that exceed uint32. */
 function lengthDelimitedField(message: Uint8Array, field: number): Uint8Array | undefined {
@@ -71,12 +76,12 @@ function lengthDelimitedField(message: Uint8Array, field: number): Uint8Array |
 }
 
 /**
- * Model id embedded in an Anthropic thinking signature, or undefined when the
- * signature is malformed, uses a format without a cleartext header, or names
- * nothing resembling a model id.
+ * Cleartext header of an Anthropic thinking signature, or undefined when malformed or absent.
+ * No upper length bound: the signature grows with its block, and a long reply's
+ * narration signature runs past 13k characters.
  */
-export function servedModelFromAnthropicSignature(signature: string): string | undefined {
-	if (signature.length < 8 || signature.length > 8192) return undefined;
+function anthropicSignatureHeader(signature: string): Uint8Array | undefined {
+	if (signature.length < 8) return undefined;
 	let raw: Uint8Array;
 	try {
 		raw = Buffer.from(signature, "base64");
@@ -85,7 +90,16 @@ export function servedModelFromAnthropicSignature(signature: string): string | u
 	}
 	const envelope = lengthDelimitedField(raw, OUTER_ENVELOPE_FIELD);
 	if (!envelope) return undefined;
-	const header = lengthDelimitedField(envelope, ENVELOPE_HEADER_FIELD);
+	return lengthDelimitedField(envelope, ENVELOPE_HEADER_FIELD);
+}
+
+/**
+ * Model id embedded in an Anthropic thinking signature, or undefined when the
+ * signature is malformed, uses a format without a cleartext header, or names
+ * nothing resembling a model id.
+ */
+export function servedModelFromAnthropicSignature(signature: string): string | undefined {
+	const header = anthropicSignatureHeader(signature);
 	if (!header) return undefined;
 	const modelBytes = lengthDelimitedField(header, HEADER_MODEL_FIELD);
 	if (!modelBytes || modelBytes.length === 0 || modelBytes.length > MAX_MODEL_ID_LENGTH) return undefined;
@@ -93,6 +107,19 @@ export function servedModelFromAnthropicSignature(signature: string): string | u
 	return MODEL_ID_PATTERN.test(model) ? model : undefined;
 }
 
+/**
+ * Whether an Anthropic thinking signature marks its block as narration: prose
+ * the model addressed to the user between tool calls, which the API returns as
+ * a thinking block. Only an exact `narration` kind matches; any other or
+ * unreadable header stays reasoning.
+ */
+export function isAnthropicNarrationSignature(signature: string): boolean {
+	const header = anthropicSignatureHeader(signature);
+	if (!header) return false;
+	const kind = lengthDelimitedField(header, HEADER_KIND_FIELD);
+	return kind !== undefined && Buffer.from(kind).equals(NARRATION_KIND);
+}
+
 /**
  * Model id from an OpenRouter reasoning item — a `reasoning_details` entry on
  * chat completions or a Responses `reasoning` output item — which forwards the

package/src/providers/anthropic-state.ts

@@ -27,6 +27,19 @@ export function resolveDirectAnthropicBaseUrl(model: Model<Api>): string {
 	return normalizeAnthropicBaseUrl($env.ANTHROPIC_BASE_URL) ?? configured ?? "https://api.anthropic.com";
 }
 
+/**
+ * Whether a request to `model` reaches the official endpoint its compat was built for. `compat.officialEndpoint`
+ * classifies the configured `baseUrl`, but a first-party Anthropic model is rerouted at request time by
+ * `ANTHROPIC_BASE_URL` or Foundry's `FOUNDRY_BASE_URL` without rebuilding compat. Gates official-only host
+ * limits such as the catalog's inline image byte and image count budgets.
+ */
+export function reachesOfficialEndpoint(model: Model<Api>): boolean {
+	const compat = model.compat;
+	if (!compat || !("officialEndpoint" in compat) || !compat.officialEndpoint) return false;
+	if (model.provider !== "anthropic" || model.api !== "anthropic-messages") return true;
+	return isOfficialAnthropicApiUrl(resolveDirectAnthropicBaseUrl(model));
+}
+
 /** Build the endpoint-and-model-scoped Anthropic session-state key. */
 export function anthropicProviderSessionStateKey(baseUrl: string, modelId: string): string {
 	return `${ANTHROPIC_PROVIDER_SESSION_STATE_KEY}:${baseUrl}\u0000${modelId}`;