@oh-my-pi/pi-ai 18.2.0 → 18.2.2

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

@@ -19,6 +19,7 @@ import type {
 	ToolResultMessage,
 	UserMessage,
 } from "../types";
+import { isCursorExecResolved } from "../utils/block-symbols";
 import {
 	type AnthropicAssistantContentBlock,
 	type AnthropicMessage,
@@ -354,6 +355,23 @@ const REASONING_EFFORT_BY_WIRE: Partial<Record<string, Effort>> = {
 	max: Effort.Max,
 };
 
+/**
+ * Recover the id of the model this request will actually reach, for labelling
+ * replayed assistant turns.
+ *
+ * `/v1/models` advertises `<provider>/<id>` and nothing else, so that is what
+ * clients send, but `resolveModel` resolves a catalog model whose id is the
+ * bare half. Labelling a replayed turn with the full id the client sent leaves
+ * `transform-messages` reading it as written by some other model.
+ *
+ * A prefix naming another provider is left intact: it describes a different
+ * route, so removing it would invent history rather than recover it.
+ */
+function stampedAssistantModelId(wireModelId: string, provider: string): string {
+	const prefix = `${provider}/`;
+	return wireModelId.startsWith(prefix) ? wireModelId.slice(prefix.length) : wireModelId;
+}
+
 export function parseRequest(body: unknown, headers?: Headers): ParsedRequest {
 	const data = anthropicMessagesRequestSchema(body);
 	if (data instanceof type.errors) {
@@ -368,14 +386,18 @@ export function parseRequest(body: unknown, headers?: Headers): ParsedRequest {
 		} else if (message.role === "system") {
 			messages.push(walkSystemMessage(message, now));
 		} else {
+			const content = walkAssistantContent(message.content);
 			const assistant: AssistantMessage = {
 				role: "assistant",
-				content: walkAssistantContent(message.content),
+				content,
 				api: "anthropic-messages",
 				provider: "anthropic",
-				model: data.model,
+				model: stampedAssistantModelId(data.model, "anthropic"),
 				usage: emptyUsage(),
-				stopReason: "stop",
+				// The wire carries no stop reason, but tool calls answered by their
+				// `tool_result` blocks did request execution. A constant "stop" reads
+				// as an abandoned tool-use turn and strips the turn's signatures.
+				stopReason: content.some(block => block.type === "toolCall") ? "toolUse" : "stop",
 				timestamp: now,
 			};
 			messages.push(assistant);
@@ -484,14 +506,33 @@ function randomFallback(): string {
 	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
 }
 
-function mapStopReasonOut(reason: StopReason): "end_turn" | "max_tokens" | "tool_use" {
+/**
+ * True for a `toolCall` block the client is expected to execute.
+ *
+ * Cursor's exec channel stamps {@link kCursorExecResolved} on calls it already
+ * ran server-side — `todo`, `web_fetch`, `connect_scm`, a native it declined —
+ * and those are not handoffs: the client never declared the tool, has no
+ * implementation to run, and repeating one would reapply a side effect the
+ * server already committed. Only unresolved calls are real external handoffs.
+ */
+function isClientToolUse(content: AssistantMessage["content"][number]): content is ToolCall {
+	return content.type === "toolCall" && !isCursorExecResolved(content);
+}
+
+function mapStopReasonOut(reason: StopReason, hasToolUse: boolean): "end_turn" | "max_tokens" | "tool_use" {
 	switch (reason) {
 		case "length":
 			return "max_tokens";
 		case "toolUse":
 			return "tool_use";
 		default:
-			return "end_turn";
+			// A provider whose protocol has no separate tool-use stop — Cursor
+			// ends the turn with `stop` when it hands a client-declared tool
+			// back for the caller to execute — still owes the client
+			// `tool_use`, or the canonical Anthropic loop (run tools while
+			// `stop_reason === "tool_use"`) never runs the tool it asked for.
+			// The OpenAI chat wire maps the same case to `tool_calls`.
+			return hasToolUse ? "tool_use" : "end_turn";
 	}
 }
 
@@ -515,6 +556,9 @@ function encodeContentBlocks(message: AssistantMessage): Record<string, unknown>
 				blocks.push(c.block);
 				break;
 			case "toolCall":
+				// Cursor already executed this one; the client must not run it
+				// again and cannot answer it. See `isClientToolUse`.
+				if (!isClientToolUse(c)) break;
 				blocks.push({ type: "tool_use", id: c.id, name: c.name, input: c.arguments ?? {} });
 				break;
 		}
@@ -547,7 +591,7 @@ export function encodeResponse(message: AssistantMessage, requestedModelId: stri
 		role: "assistant",
 		model: requestedModelId,
 		content: encodeContentBlocks(message),
-		stop_reason: mapStopReasonOut(message.stopReason),
+		stop_reason: mapStopReasonOut(message.stopReason, message.content.some(isClientToolUse)),
 		// TODO: surface the matched stop sequence once pi-ai's
 		// `AssistantMessage.stopReason` carries the matched string. Intentionally
 		// `null` for now (Anthropic schema allows it).
@@ -612,6 +656,23 @@ export function encodeStream(
 			const messageId = newMessageId();
 			let started = false;
 			const open = new Map<number, OpenBlock>();
+			// Cursor's exec channel hands back calls it already ran server-side;
+			// `isClientToolUse` keeps them off the wire. Anthropic clients (the
+			// official SDK included) append every `content_block_start` to their
+			// snapshot and then address deltas by `index`, so a hole in the
+			// numbering misroutes each later delta. Shift emitted indices down by
+			// the number of blocks suppressed before them — identity while
+			// nothing is suppressed. A suppressed call always closes the
+			// preceding text/thinking block before it opens, so no block that is
+			// still open is ever renumbered.
+			const suppressed = new Set<number>();
+			const wireIndex = (contentIndex: number): number => {
+				let shift = 0;
+				for (const index of suppressed) {
+					if (index < contentIndex) shift++;
+				}
+				return contentIndex - shift;
+			};
 
 			const ensureStart = (partial: AssistantMessage | undefined) => {
 				if (started) return;
@@ -642,10 +703,11 @@ export function encodeStream(
 			const emitServerToolBlocksBefore = (message: AssistantMessage, beforeIndex: number) => {
 				const limit = Math.min(beforeIndex, message.content.length);
 				while (nextContentIndexToInspect < limit) {
-					const index = nextContentIndexToInspect++;
-					const content = message.content[index];
+					const contentIndex = nextContentIndexToInspect++;
+					const content = message.content[contentIndex];
 					if (content?.type !== "anthropicServerTool") continue;
 					ensureStart(message);
+					const index = wireIndex(contentIndex);
 					controller.enqueue(
 						sseFrame("content_block_start", {
 							type: "content_block_start",
@@ -657,10 +719,11 @@ export function encodeStream(
 				}
 			};
 
-			const closeBlock = (index: number) => {
-				if (!open.has(index)) return;
-				controller.enqueue(sseFrame("content_block_stop", { type: "content_block_stop", index }));
-				open.delete(index);
+			const closeBlock = (contentIndex: number) => {
+				const block = open.get(contentIndex);
+				if (!block) return;
+				controller.enqueue(sseFrame("content_block_stop", { type: "content_block_stop", index: block.index }));
+				open.delete(contentIndex);
 			};
 
 			pingTimer = setInterval(() => {
@@ -690,11 +753,12 @@ export function encodeStream(
 						case "text_start": {
 							emitServerToolBlocksBefore(ev.partial, ev.contentIndex);
 							ensureStart(ev.partial);
-							open.set(ev.contentIndex, { index: ev.contentIndex, kind: "text" });
+							const index = wireIndex(ev.contentIndex);
+							open.set(ev.contentIndex, { index, kind: "text" });
 							controller.enqueue(
 								sseFrame("content_block_start", {
 									type: "content_block_start",
-									index: ev.contentIndex,
+									index,
 									content_block: { type: "text", text: "" },
 								}),
 							);
@@ -704,7 +768,7 @@ export function encodeStream(
 							controller.enqueue(
 								sseFrame("content_block_delta", {
 									type: "content_block_delta",
-									index: ev.contentIndex,
+									index: wireIndex(ev.contentIndex),
 									delta: { type: "text_delta", text: ev.delta },
 								}),
 							);
@@ -715,11 +779,12 @@ export function encodeStream(
 						case "thinking_start": {
 							emitServerToolBlocksBefore(ev.partial, ev.contentIndex);
 							ensureStart(ev.partial);
-							open.set(ev.contentIndex, { index: ev.contentIndex, kind: "thinking" });
+							const index = wireIndex(ev.contentIndex);
+							open.set(ev.contentIndex, { index, kind: "thinking" });
 							controller.enqueue(
 								sseFrame("content_block_start", {
 									type: "content_block_start",
-									index: ev.contentIndex,
+									index,
 									content_block: { type: "thinking", thinking: "" },
 								}),
 							);
@@ -729,7 +794,7 @@ export function encodeStream(
 							controller.enqueue(
 								sseFrame("content_block_delta", {
 									type: "content_block_delta",
-									index: ev.contentIndex,
+									index: wireIndex(ev.contentIndex),
 									delta: { type: "thinking_delta", thinking: ev.delta },
 								}),
 							);
@@ -740,7 +805,7 @@ export function encodeStream(
 								controller.enqueue(
 									sseFrame("content_block_delta", {
 										type: "content_block_delta",
-										index: ev.contentIndex,
+										index: wireIndex(ev.contentIndex),
 										delta: { type: "signature_delta", signature: c.thinkingSignature },
 									}),
 								);
@@ -752,11 +817,21 @@ export function encodeStream(
 							emitServerToolBlocksBefore(ev.partial, ev.contentIndex);
 							ensureStart(ev.partial);
 							const tc = ev.partial.content[ev.contentIndex] as ToolCall | undefined;
-							open.set(ev.contentIndex, { index: ev.contentIndex, kind: "tool_use" });
+							if (tc && !isClientToolUse(tc)) {
+								// Cursor's exec channel already ran this call and
+								// buffered its result. Streaming it would invite the
+								// client to repeat a committed side effect and answer
+								// a tool it never declared, so drop the whole block —
+								// start, deltas and stop — from the wire.
+								suppressed.add(ev.contentIndex);
+								break;
+							}
+							const index = wireIndex(ev.contentIndex);
+							open.set(ev.contentIndex, { index, kind: "tool_use" });
 							controller.enqueue(
 								sseFrame("content_block_start", {
 									type: "content_block_start",
-									index: ev.contentIndex,
+									index,
 									content_block: {
 										type: "tool_use",
 										id: tc?.id ?? "",
@@ -768,10 +843,11 @@ export function encodeStream(
 							break;
 						}
 						case "toolcall_delta":
+							if (suppressed.has(ev.contentIndex)) break;
 							controller.enqueue(
 								sseFrame("content_block_delta", {
 									type: "content_block_delta",
-									index: ev.contentIndex,
+									index: wireIndex(ev.contentIndex),
 									delta: { type: "input_json_delta", partial_json: ev.delta },
 								}),
 							);
@@ -788,7 +864,12 @@ export function encodeStream(
 									// TODO: surface matched stop sequence once pi-ai
 									// propagates it on the `done` event.
 									delta: {
-										stop_reason: mapStopReasonOut(ev.reason),
+										// A call Cursor resolved after it opened (an MCP
+										// frame answered by a local handler) already
+										// streamed; the client still must not be told to
+										// run it, so it does not terminate the turn with
+										// `tool_use` either.
+										stop_reason: mapStopReasonOut(ev.reason, ev.message.content.some(isClientToolUse)),
 										stop_sequence: null,
 									},
 									...(bindingControlsRequested

package/src/providers/anthropic-signature.ts

@@ -17,7 +17,7 @@ const HEADER_MODEL_FIELD = 6;
 const MAX_MODEL_ID_LENGTH = 128;
 const MODEL_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:/-]*$/;
 
-/** Returns the first length-delimited field `field` in `message`, or undefined. */
+/** Finds a length-delimited field, rejecting tags and lengths that exceed uint32. */
 function lengthDelimitedField(message: Uint8Array, field: number): Uint8Array | undefined {
 	let offset = 0;
 	while (offset < message.length) {
@@ -27,6 +27,7 @@ function lengthDelimitedField(message: Uint8Array, field: number): Uint8Array |
 		do {
 			if (offset >= message.length) return undefined;
 			byte = message[offset++];
+			if (shift === 28 && byte > 0x0f) return undefined;
 			tag |= (byte & 0x7f) << shift;
 			shift += 7;
 		} while (byte & 0x80);
@@ -49,10 +50,12 @@ function lengthDelimitedField(message: Uint8Array, field: number): Uint8Array |
 				do {
 					if (offset >= message.length) return undefined;
 					byte = message[offset++];
+					if (shift === 28 && byte > 0x0f) return undefined;
 					length |= (byte & 0x7f) << shift;
 					shift += 7;
 				} while (byte & 0x80);
-				if (offset + length > message.length) return undefined;
+				length >>>= 0;
+				if (length > message.length - offset) return undefined;
 				if (fieldNumber === field) return message.subarray(offset, offset + length);
 				offset += length;
 				break;

package/src/providers/anthropic.ts

@@ -60,8 +60,10 @@ import {
 import { createAbortSourceTracker } from "../utils/abort";
 import {
 	clearStreamingPartialJson,
+	copyPerCallContextMessage,
 	type ConversationalUserCarrier,
 	isConversationalUser,
+	isPerCallContextMessage,
 	isSyntheticUser,
 	kConversationalUser,
 	kStreamingBlockIndex,
@@ -454,6 +456,15 @@ type AnthropicProviderSessionState = ProviderSessionState & {
 	 * `compat.replayUnsignedThinking: false`. Cleared on session close.
 	 */
 	replayUnsignedThinkingDisabled: boolean;
+	/**
+	 * Runtime-learned: this endpoint kept rejecting replayed thinking
+	 * signatures even after unsigned demotion — every surviving block is
+	 * signed by a foreign signer (e.g. a failover proxy swapped upstreams
+	 * mid-conversation and minted signatures the restored upstream cannot
+	 * verify). All subsequent requests drop replayed thinking entirely for
+	 * this (baseUrl, modelId). Cleared on session close.
+	 */
+	thinkingReplayDisabled: boolean;
 	/** Thinking blocks the API permanently dropped after a prefix mismatch. */
 	prefixDroppedThinkingBlocks: Set<string>;
 	/** Conversation-scoped control baselines, isolated from side requests and advisors. */
@@ -478,12 +489,14 @@ function createAnthropicProviderSessionState(): AnthropicProviderSessionState {
 		strictToolsDisabled: false,
 		fastModeDisabled: false,
 		replayUnsignedThinkingDisabled: false,
+		thinkingReplayDisabled: false,
 		prefixDroppedThinkingBlocks: new Set(),
 		controlStates: new Map(),
 		close: () => {
 			state.strictToolsDisabled = false;
 			state.fastModeDisabled = false;
 			state.replayUnsignedThinkingDisabled = false;
+			state.thinkingReplayDisabled = false;
 			state.prefixDroppedThinkingBlocks.clear();
 			state.controlStates.clear();
 		},
@@ -2296,7 +2309,8 @@ const streamAnthropicOnce = (
 				(providerSessionState?.strictToolsDisabled ?? false) || (model.compat?.disableStrictTools ?? false);
 			let dropFastMode = providerSessionState?.fastModeDisabled ?? false;
 			let forceDemoteUnsignedThinking = providerSessionState?.replayUnsignedThinkingDisabled ?? false;
-			let dropAllThinking = false;
+			let droppedAllThinkingForSignature = providerSessionState?.thinkingReplayDisabled ?? false;
+			let dropAllThinking = droppedAllThinkingForSignature;
 			let prefixBindingRetryAttempted = false;
 			let prefixMismatchBehavior =
 				model.thinking?.prefixBinding && model.compat.supportsThinkingBindingControls
@@ -3367,6 +3381,48 @@ const streamAnthropicOnce = (
 						firstTokenTime = undefined;
 						continue;
 					}
+					if (
+						!dropAllThinking &&
+						firstTokenTime === undefined &&
+						!streamedReplayUnsafeContent &&
+						!isThinkingPrefixBindingError(streamFailureMessage) &&
+						isInvalidThinkingSignatureError(streamFailureMessage)
+					) {
+						// The unsigned-demotion retry only rewrites UNSIGNED blocks;
+						// when every replayed block carries a signature the signer no
+						// longer accepts (e.g. a failover proxy swapped upstreams
+						// mid-conversation and minted foreign signatures), the retry
+						// resends a byte-identical body and the session 400s forever.
+						// Escalate: drop all replayed thinking — prior-turn reasoning
+						// is optional context — and retry once. Stored history keeps
+						// its thinking blocks; only the wire payload changes.
+						logger.warn(
+							"anthropic: thinking signatures still rejected after unsigned demotion, dropping replayed thinking and retrying",
+							{
+								provider: model.provider,
+								model: model.id,
+								baseUrl,
+								error: streamFailureMessage,
+							},
+						);
+						if (providerSessionState) {
+							providerSessionState.thinkingReplayDisabled = true;
+						}
+						droppedAllThinkingForSignature = true;
+						dropAllThinking = true;
+						params = await prepareParams();
+						providerRetryAttempt = 0;
+						output.content.length = 0;
+						output.model = model.id;
+						output.responseId = undefined;
+						output.errorMessage = undefined;
+						output.inputTransformations = undefined;
+						output.providerPayload = undefined;
+						output.usage = createEmptyUsage(copilotDynamicHeaders?.premiumRequests);
+						output.stopReason = "stop";
+						firstTokenTime = undefined;
+						continue;
+					}
 					if (
 						!dropFastMode &&
 						model.provider === "anthropic" &&
@@ -3451,6 +3507,9 @@ const streamAnthropicOnce = (
 			if (forceDemoteUnsignedThinking && model.compat.replayUnsignedThinking) {
 				output.disabledFeatures = [...(output.disabledFeatures ?? []), "unsigned-thinking-replay"];
 			}
+			if (droppedAllThinkingForSignature) {
+				output.disabledFeatures = [...(output.disabledFeatures ?? []), "thinking-replay"];
+			}
 			stream.push({ type: "done", reason: output.stopReason, message: output });
 			stream.end();
 		} catch (error) {
@@ -3892,14 +3951,26 @@ function applyPromptCaching(params: MessageCreateParamsStreaming, cacheControl?:
 		params.messages[trailingIndex - 1]?.role === "assistant";
 	const messageEnd = hasTrailingAssistantPad ? trailingIndex - 1 : trailingIndex;
 
+	// A breakpoint caches every preceding byte, not only the decorated message.
+	// Once per-call or turn-scoped content appears, no later message can anchor a
+	// prefix reusable by the next request.
+	let stableMessageEnd = messageEnd;
+	for (let index = 0; index <= messageEnd; index++) {
+		const message = params.messages[index];
+		if (message && (message.clear_at === "next_user_message" || isPerCallContextMessage(message))) {
+			stableMessageEnd = index - 1;
+			break;
+		}
+	}
+
 	// Decimation counts conversational turns, so it reads the provenance marker
 	// `convertAnthropicMessages` records rather than the wire role. A wire `user`
 	// can also be a serialized `developer` message, a tool_result run, or an
 	// interior `Continue.` pad, none of which advance the user turn ordinal.
 	const userIndices: number[] = [];
-	for (let index = 0; index <= messageEnd; index++) {
+	for (let index = 0; index <= stableMessageEnd; index++) {
 		const message = params.messages[index];
-		if (message && message.clear_at !== "next_user_message" && isConversationalUser(message)) {
+		if (message && isConversationalUser(message)) {
 			userIndices.push(index);
 		}
 	}
@@ -3907,11 +3978,11 @@ function applyPromptCaching(params: MessageCreateParamsStreaming, cacheControl?:
 	// Stable historical decimation checkpoint every 15 user turns (15th, 30th, 45th...)
 	const decimationIndices = userIndices.filter((_, ordinal) => (ordinal + 1) % ANTHROPIC_DECIMATION_INTERVAL === 0);
 
-	// Collect eligible trailing candidates (up to 2 messages walking backward from messageEnd).
+	// Collect up to 2 trailing candidates from the reusable prefix.
 	const trailingCandidates: number[] = [];
-	for (let index = messageEnd; index >= 0 && trailingCandidates.length < 2; index--) {
+	for (let index = stableMessageEnd; index >= 0 && trailingCandidates.length < 2; index--) {
 		const message = params.messages[index];
-		if (!message || message.clear_at === "next_user_message") continue;
+		if (!message) continue;
 		trailingCandidates.push(index);
 	}
 
@@ -4774,7 +4845,12 @@ export function convertAnthropicMessages(
 			(msg.role === "user" || msg.role === "developer") &&
 			isReplayableAnthropicCompaction(msg.providerPayload, model)
 		) {
-			params.push({ role: "assistant", content: [compactionBlockParam(msg.providerPayload)] });
+			const compactionParam: AnthropicMessageParam = {
+				role: "assistant",
+				content: [compactionBlockParam(msg.providerPayload)],
+			};
+			copyPerCallContextMessage(compactionParam, msg);
+			params.push(compactionParam);
 			// The block carries the verbatim API summary, so the message text
 			// (which holds the harness file lists) would be dropped with it.
 			// Queue the file metadata for after the block: it sits past the
@@ -4845,6 +4921,7 @@ export function convertAnthropicMessages(
 			if (msg.role === "user" && !agentAuthored && !isSyntheticUser(msg)) {
 				param[kConversationalUser] = true;
 			}
+			copyPerCallContextMessage(param, msg);
 			params.push(param);
 		} else if (msg.role === "assistant") {
 			const blocks: ContentBlockParam[] = [];
@@ -4982,10 +5059,12 @@ export function convertAnthropicMessages(
 				blocks.push(...nonToolUse, ...toolUse);
 			}
 			if (blocks.length === 0) continue;
-			params.push({
+			const assistantParam: AnthropicMessageParam = {
 				role: "assistant",
 				content: blocks,
-			});
+			};
+			copyPerCallContextMessage(assistantParam, msg);
+			params.push(assistantParam);
 			// Flush queued file metadata unless this turn left tool calls open:
 			// their results must follow the turn contiguously, so the metadata
 			// waits for the merged result message (or the end of the list).
@@ -4997,15 +5076,21 @@ export function convertAnthropicMessages(
 			const toolResults: ContentBlockParam[] = [];
 			// Images stripped out of error tool results, re-attached after the run.
 			const hoistedImages: ContentBlockParam[] = [];
+			const toolResultParam: AnthropicMessageParam = {
+				role: "user",
+				content: toolResults,
+			};
 
 			// Add the current tool result
 			toolResults.push(buildToolResultBlock(model, msg, hoistedImages));
+			copyPerCallContextMessage(toolResultParam, msg);
 
 			// Look ahead for consecutive toolResult messages
 			let j = i + 1;
 			while (j < transformedMessages.length && transformedMessages[j].role === "toolResult") {
 				const nextMsg = transformedMessages[j] as ToolResultMessage; // We know it's a toolResult
 				toolResults.push(buildToolResultBlock(model, nextMsg, hoistedImages));
+				copyPerCallContextMessage(toolResultParam, nextMsg);
 				j++;
 			}
 
@@ -5020,10 +5105,7 @@ export function convertAnthropicMessages(
 			}
 
 			// Add a single user message with all tool results
-			params.push({
-				role: "user",
-				content: toolResults,
-			});
+			params.push(toolResultParam);
 			// An open tool_use turn's results are whole again; queued file
 			// metadata can follow without splitting the pairing.
 			flushCompactionFiles();
@@ -5060,20 +5142,24 @@ export function convertAnthropicMessages(
 				const controlContent = content.filter(block => block.type !== "text");
 				if (scopedContent.length > 0) {
 					params[idx] = {
+						...params[idx],
 						role: "system",
 						content: scopedContent,
 						clear_at: "next_user_message",
 					};
-					params.splice(idx + 1, 0, {
+					const controlParam: AnthropicMessageParam = {
 						role: "system",
 						content: controlContent,
 						...(hasEffort ? { output_config: { effort: developer.payload?.effort } } : {}),
-					});
+					};
+					copyPerCallContextMessage(controlParam, params[idx]);
+					params.splice(idx + 1, 0, controlParam);
 					continue;
 				}
 			}
 
 			params[idx] = {
+				...params[idx],
 				role: "system",
 				content,
 				...(turnScoped && !hasEffort && !hasToolChanges ? { clear_at: "next_user_message" } : {}),

package/src/providers/aws-sigv4.ts

@@ -137,18 +137,29 @@ function encodeRfc3986(str: string): string {
 	return encodeURIComponent(str).replace(/[!'()*]/g, c => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
 }
 
-function canonicalQuery(query: string | undefined): string {
+/**
+ * AWS's canonical-request spec encodes each name/value first, THEN sorts by
+ * the encoded form ("Sort the encoded parameter names by character code" —
+ * https://docs.aws.amazon.com/IAM/latest/UserGuide/create-canonical-request.html).
+ * Sorting the decoded form instead gives the wrong order whenever encoding
+ * changes a character's relative position — e.g. raw key `%7B` (decodes to
+ * `{`, 0x7B) vs `x` (0x78): decoded, `x` < `{`; encoded, `%` (0x25) < `x`, so
+ * `%7B` sorts first. A gateway that validates SigV4 (or AWS itself) computes
+ * the signature over ITS OWN canonicalization and rejects ours if the two
+ * disagree on order.
+ */
+export function canonicalQuery(query: string | undefined): string {
 	if (!query) return "";
 	const pairs: Array<[string, string]> = [];
 	for (const part of query.split("&")) {
 		if (!part) continue;
 		const eq = part.indexOf("=");
-		const k = eq === -1 ? part : part.slice(0, eq);
-		const v = eq === -1 ? "" : part.slice(eq + 1);
-		pairs.push([decodeURIComponent(k), decodeURIComponent(v)]);
+		const rawKey = eq === -1 ? part : part.slice(0, eq);
+		const rawValue = eq === -1 ? "" : part.slice(eq + 1);
+		pairs.push([encodeRfc3986(decodeURIComponent(rawKey)), encodeRfc3986(decodeURIComponent(rawValue))]);
 	}
 	pairs.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0));
-	return pairs.map(([k, v]) => `${encodeRfc3986(k)}=${encodeRfc3986(v)}`).join("&");
+	return pairs.map(([k, v]) => `${k}=${v}`).join("&");
 }
 
 export interface SignedHeaders {