@bitkyc08/opencodex 2.10.0 → 2.10.1

package/src/adapters/google-antigravity-replay.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { enforceAppOwnedMemoryBudget } from "../lib/app-owned-memory";
 
 /**
@@ -34,6 +35,8 @@ const REPLAY_MAX_CALLS_PER_SESSION = 256;
 export const ANTIGRAVITY_REPLAY_MAX_BYTES_PER_SESSION = 2 * 1024 * 1024;
 export const ANTIGRAVITY_REPLAY_MAX_TOTAL_BYTES = 64 * 1024 * 1024;
 const REPLAY_MAX_SIGNATURE_BYTES = 64 * 1024;
+/** Fixed 64-hex outer key length, counted once per session entry. */
+const REPLAY_SESSION_KEY_BYTES = 64;
 
 interface ReplayLimits {
   maxCallsPerSession: number;
@@ -54,29 +57,202 @@ let replayBytes = 0;
 let replayOldestSessionKey: string | undefined;
 let replayOldestAt: number | null = null;
 
+/**
+ * Fixed-size identity for a (model, sessionId) pair: SHA-256 over
+ * length-prefixed UTF-16 code units fed incrementally (no separator ambiguity
+ * — `("a\0b","c")` and `("a","b\0c")` derive different keys — and no raw
+ * model/session strings retained as Map keys, which the byte caps never
+ * counted).
+ */
+/**
+ * Injective string feed for key derivation: length-prefixed in CODE UNITS,
+ * then each code unit as two little-endian bytes. TextEncoder/UTF-8 would
+ * fold lone surrogates into U+FFFD, colliding distinct strings (e.g.
+ * "�" and "�") into the same key.
+ */
+function updateHashWithString(hash: ReturnType<typeof createHash>, value: string): void {
+  hash.update(String(value.length));
+  hash.update("\0");
+  const buf = Buffer.allocUnsafe(8192);
+  let offset = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    buf.writeUInt16LE(value.charCodeAt(index), offset);
+    offset += 2;
+    if (offset === buf.length) {
+      hash.update(buf);
+      offset = 0;
+    }
+  }
+  if (offset > 0) hash.update(buf.subarray(0, offset));
+}
+
 function replayKey(model: string, sessionId: string): string {
-  return `${model}::session:${sessionId}`;
+  const hash = createHash("sha256");
+  updateHashWithString(hash, model);
+  updateHashWithString(hash, sessionId);
+  return hash.digest("hex");
+}
+
+/** Canonical output exceeding this budget is rejected DURING the walk — the
+ * pre-fix path materialized an unbounded canonical string before admission. */
+const REPLAY_MAX_CANONICAL_ARGS_BYTES = 64 * 1024;
+const CANONICAL_OVERFLOW = Symbol("canonical-overflow");
+
+/** Byte-identical output to the old recursive canonicalJson, written incrementally. */
+/**
+ * Key-count pre-check: every object key costs at least 4 canonical bytes
+ * (two quotes, colon, separator), so a wider object ALWAYS overflows the
+ * canonical budget — skip the sort and the walk. Object.keys allocation
+ * itself is linear and irreducible in JS (there is no streaming key API),
+ * but it is transient and never sorted or walked past this bound.
+ */
+const CANONICAL_MAX_KEYS_PER_OBJECT = REPLAY_MAX_CANONICAL_ARGS_BYTES / 4;
+
+/** Test-only scan instrumentation: proves overflow aborts the walk near the
+ * cap instead of scanning/materializing the whole input. */
+let canonicalScanUnitsForTests = 0;
+export function canonicalScanUnitsForTestsValue(): number {
+  return canonicalScanUnitsForTests;
 }
+export function resetCanonicalScanUnitsForTests(): void {
+  canonicalScanUnitsForTests = 0;
+}
+
+const MAX_CANONICAL_DEPTH = 128;
 
-/** Recursively canonicalize a JSON value: object keys sorted, arrays preserved. */
-function canonicalJson(value: unknown): string {
-  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
-  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
-  const entries = Object.keys(value as Record<string, unknown>).sort()
-    .map(k => `${JSON.stringify(k)}:${canonicalJson((value as Record<string, unknown>)[k])}`);
-  return `{${entries.join(",")}}`;
+function writeCanonicalJson(value: unknown, sink: (chunk: string) => void, depth = 0): void {
+  canonicalScanUnitsForTests += 1;
+  // Depth overflow is the same class as byte overflow: skip replay for this
+  // call instead of exhausting the stack on a pathological argument shape.
+  if (depth > MAX_CANONICAL_DEPTH) throw CANONICAL_OVERFLOW;
+  if (typeof value === "string") {
+    writeJsonStringEscaped(value, sink);
+    return;
+  }
+  if (value === null || typeof value !== "object") {
+    sink(JSON.stringify(value) ?? "null");
+    return;
+  }
+  if (Array.isArray(value)) {
+    sink("[");
+    for (let index = 0; index < value.length; index += 1) {
+      if (index > 0) sink(",");
+      // Array.prototype.map parity: holes produce NOTHING between the commas
+      // (old output `[1,,3]`), while an explicit undefined element is "null".
+      if (index in value) writeCanonicalJson(value[index], sink, depth + 1);
+    }
+    sink("]");
+    return;
+  }
+  const keys = Object.keys(value as Record<string, unknown>);
+  if (keys.length > CANONICAL_MAX_KEYS_PER_OBJECT) throw CANONICAL_OVERFLOW;
+  keys.sort();
+  sink("{");
+  keys.forEach((k, index) => {
+    if (index > 0) sink(",");
+    writeJsonStringEscaped(k, sink);
+    sink(":");
+    writeCanonicalJson((value as Record<string, unknown>)[k], sink, depth + 1);
+  });
+  sink("}");
 }
 
-/** Stable identity for a functionCall part: name + recursively canonicalized args. */
+/**
+ * JSON.stringify string escaping, streamed in small chunks so the budget can
+ * reject mid-string — calling JSON.stringify on a multi-MiB primitive would
+ * materialize its full escaped form before the sink could refuse it.
+ * Semantics mirror JSON.stringify for strings exactly (ES2019 JSON
+ * superset): quotes/backslash and control characters are escaped, LONE
+ * surrogates become \uXXXX, and valid surrogate pairs pass through raw.
+ */
+function writeJsonStringEscaped(value: string, sink: (chunk: string) => void): void {
+  sink('"');
+  let buffer = "";
+  for (const cp of value) {
+    canonicalScanUnitsForTests += 1;
+    const code = cp.codePointAt(0)!;
+    let escaped: string;
+    if (cp === '"') escaped = '\\"';
+    else if (cp === "\\") escaped = "\\\\";
+    else if (cp === "\b") escaped = "\\b";
+    else if (cp === "\f") escaped = "\\f";
+    else if (cp === "\n") escaped = "\\n";
+    else if (cp === "\r") escaped = "\\r";
+    else if (cp === "\t") escaped = "\\t";
+    else if (code < 0x20) escaped = `\\u${code.toString(16).padStart(4, "0")}`;
+    // Lone surrogates: JSON.stringify emits \uXXXX (a raw one would decode
+    // back as U+FFFD and collide with real U+FFFD content).
+    else if (code >= 0xd800 && code <= 0xdfff) escaped = `\\u${code.toString(16).padStart(4, "0")}`;
+    else escaped = cp;
+    buffer += escaped;
+    if (buffer.length >= 4096) {
+      sink(buffer);
+      buffer = "";
+    }
+  }
+  if (buffer.length > 0) sink(buffer);
+  sink('"');
+}
+
+/** Bounded canonicalization: null on overflow (skip replay for that call). */
+function canonicalJsonBounded(value: unknown, maxBytes: number): string | null {
+  let written = 0;
+  const parts: string[] = [];
+  const sink = (chunk: string) => {
+    written += utf8.encode(chunk).byteLength;
+    if (written > maxBytes) throw CANONICAL_OVERFLOW;
+    parts.push(chunk);
+  };
+  try {
+    writeCanonicalJson(value, sink);
+  } catch (error) {
+    if (error === CANONICAL_OVERFLOW) return null;
+    throw error;
+  }
+  return parts.join("");
+}
+
+/**
+ * Stable identity for a functionCall part: fixed-size SHA-256 over
+ * length-prefixed name + canonical args. Overflow during canonicalization
+ * skips replay for that call (never materializes an unbounded string); other
+ * canonicalization failures keep the old name-only fallback semantics.
+ */
 function functionCallKey(name: unknown, args: unknown): string | undefined {
   if (typeof name !== "string" || name.length === 0) return undefined;
-  let argsKey = "";
+  let canonical: string | null;
   try {
-    argsKey = canonicalJson(args ?? {});
+    canonical = canonicalJsonBounded(args ?? {}, REPLAY_MAX_CANONICAL_ARGS_BYTES);
   } catch {
-    argsKey = "";
+    canonical = "";
   }
-  return `${name}::${argsKey}`;
+  if (canonical === null) return undefined;
+  const hash = createHash("sha256");
+  updateHashWithString(hash, name);
+  updateHashWithString(hash, canonical);
+  return hash.digest("hex");
+}
+
+/** Test-only key-derivation seam: the fixed-key regression cannot go red
+ * through snapshot.bytes (that metric never counted raw outer keys). */
+export function antigravityReplayKeyForTests(model: string, sessionId: string): string {
+  return replayKey(model, sessionId);
+}
+
+export function antigravityFunctionCallKeyForTests(name: unknown, args: unknown): string | undefined {
+  return functionCallKey(name, args);
+}
+
+/** Test-only bounded-canonicalization seam: proves mid-walk rejection without
+ * materializing the escaped form (allocation guard). */
+export function antigravityCanonicalJsonBoundedForTests(value: unknown, maxBytes: number): string | null {
+  return canonicalJsonBounded(value, maxBytes);
+}
+
+/** Test-only: the ACTUAL internal session keys, so tests can prove raw
+ * model/session strings are never retained as Map keys. */
+export function antigravityReplaySessionKeysForTests(): string[] {
+  return [...replayCache.keys()];
 }
 
 function extractSignature(part: Record<string, unknown>): string | undefined {
@@ -123,6 +299,22 @@ function deleteExpiredReplaySessions(now: number): void {
   for (const [key, entry] of replayCache) if (entry.expiresAtMs <= now) deleteReplaySession(key);
 }
 
+/**
+ * The lazy per-call expiry scan is O(sessions); at the 10,240-session cap
+ * every observe/apply would rescan the whole map — O(n²) under load. The 60s
+ * state-store sweeper is already the periodic expiry authority, so lazy scans
+ * are throttled to at most one per interval (expired entries may linger a few
+ * extra seconds; TTL is fuzzy at that scale by design).
+ */
+const LAZY_SWEEP_INTERVAL_MS = 30_000;
+let lastLazySweepAt = Number.NEGATIVE_INFINITY;
+
+function deleteExpiredReplaySessionsThrottled(now: number): void {
+  if (now - lastLazySweepAt < LAZY_SWEEP_INTERVAL_MS) return;
+  lastLazySweepAt = now;
+  deleteExpiredReplaySessions(now);
+}
+
 export function sweepExpiredAntigravityReplay(now = Date.now()): number {
   const before = replayCache.size;
   deleteExpiredReplaySessions(now);
@@ -173,39 +365,62 @@ export function antigravityUsesReplayCache(model: string): boolean {
  * Observe a parsed CCA chunk's `candidates[0].content.parts` and record thought signatures keyed by
  * the functionCall identity (name + args). Accumulates across the whole session so a sequential
  * multi-step tool loop keeps EVERY prior call's signature, not just the latest part-index slot.
+ * A signature on a standalone thought part is paired with the next functionCall in the same
+ * array (#897); a call's own signature takes precedence and an unpaired one is dropped.
  * `parts` is the already-unwrapped `response.candidates[0].content.parts`.
  */
 export function observeAntigravityReplay(model: string, sessionId: string, parts: unknown[]): void {
   if (!antigravityUsesReplayCache(model) || !Array.isArray(parts) || parts.length === 0) return;
   const now = Date.now();
-  deleteExpiredReplaySessions(now);
+  deleteExpiredReplaySessionsThrottled(now);
   const key = replayKey(model, sessionId);
-  const entry = replayCache.get(key) ?? {
+  const existing = replayCache.get(key);
+  const entry = existing ?? {
     byCall: new Map<string, ReplayCall>(),
-    bytes: 0,
+    bytes: REPLAY_SESSION_KEY_BYTES,
     expiresAtMs: 0,
     oldestAtMs: null,
   };
   let inserted = false;
+  let pendingThoughtSig: string | undefined;
   for (const raw of parts) {
     if (!raw || typeof raw !== "object") continue;
     const part = raw as Record<string, unknown>;
     const sig = extractSignature(part);
-    if (!sig) continue;
     const fc = part.functionCall as { name?: unknown; args?: unknown } | undefined;
-    const ck = fc ? functionCallKey(fc.name, fc.args) : undefined;
+    if (!fc) {
+      // A signature on a standalone thought part pairs with the NEXT functionCall in this
+      // array: thought parts are stripped from replayed history, so the call part is the only
+      // carrier that survives (#897). Non-thought parts keep their own signature in history.
+      if (sig && part.thought === true) pendingThoughtSig = sig;
+      continue;
+    }
+    const callSig = sig ?? pendingThoughtSig; // a signature on the call part itself wins
+    pendingThoughtSig = undefined;
+    if (!callSig) continue;
+    const ck = functionCallKey(fc.name, fc.args);
     if (!ck) continue; // only function-call signatures are replayable by identity
-    const signatureBytes = utf8.encode(sig).byteLength;
+    const signatureBytes = utf8.encode(callSig).byteLength;
     const sizeBytes = utf8.encode(ck).byteLength + signatureBytes;
     if (signatureBytes > replayLimits.maxSignatureBytes || sizeBytes > replayLimits.maxBytesPerSession) continue;
     deleteReplayCall(entry, ck);
-    entry.byCall.set(ck, { signature: sig, sizeBytes, touchedAtMs: now });
+    entry.byCall.set(ck, { signature: callSig, sizeBytes, touchedAtMs: now });
     entry.bytes += sizeBytes;
     replayBytes += sizeBytes;
     inserted = true;
   }
   if (!inserted) return;
+  // Charge the fixed outer key only when the session is actually stored.
+  if (!existing) replayBytes += REPLAY_SESSION_KEY_BYTES;
   evictInnerCalls(entry);
+  if (entry.byCall.size === 0) {
+    // The fixed session overhead can exceed the per-session cap on its own
+    // (test-sized limits): an entry holding zero calls is unusable — drop it
+    // instead of retaining an unevictable shell.
+    if (existing) deleteReplaySession(key);
+    else replayBytes -= REPLAY_SESSION_KEY_BYTES;
+    return;
+  }
   entry.expiresAtMs = now + REPLAY_TTL_MS;
   replayCache.set(key, entry);
   refreshReplaySessionCandidate(key, entry);
@@ -221,7 +436,7 @@ export function observeAntigravityReplay(model: string, sessionId: string, parts
 export function applyAntigravityReplay(model: string, sessionId: string, contents: unknown[]): unknown[] {
   if (!antigravityUsesReplayCache(model) || !Array.isArray(contents)) return contents;
   const now = Date.now();
-  deleteExpiredReplaySessions(now);
+  deleteExpiredReplaySessionsThrottled(now);
   const entry = replayCache.get(replayKey(model, sessionId));
   if (!entry) {
     return contents;
@@ -296,6 +511,7 @@ export function setAntigravityReplayLimitsForTests(limits?: Partial<ReplayLimits
 
 /** Test seam. */
 export function __resetAntigravityReplayCache(): void {
+  lastLazySweepAt = Number.NEGATIVE_INFINITY;
   replayCache.clear();
   replayBytes = 0;
   replayOldestSessionKey = undefined;

package/src/adapters/google-truncation.ts

@@ -11,3 +11,14 @@ export function vertexTruncationErrorMessage(reason?: string): string {
   const suffix = reason ? ` (${redactSecretString(reason).slice(0, 160)})` : "";
   return `Vertex AI response truncated upstream before the turn completed${suffix}`;
 }
+
+/**
+ * Whether a finished turn must fail closed. A truncation reason arriving mid tool call always
+ * does. MALFORMED_FUNCTION_CALL fails closed even with zero started calls: the malformed call
+ * is dropped upstream and usually never materializes as a part, so the turn is incomplete
+ * despite looking empty. MAX_TOKENS with no started call stays a plain token-limit stop.
+ */
+export function isVertexTruncatedTurn(finishReason: string | undefined, toolCallsStarted: number): boolean {
+  if (!isVertexTruncationReason(finishReason)) return false;
+  return toolCallsStarted > 0 || finishReason === "MALFORMED_FUNCTION_CALL";
+}

package/src/adapters/google.ts

@@ -12,15 +12,15 @@ import type {
   OcxToolCall,
   OcxUsage,
 } from "../types";
-import { isAllowedToolChoice, namespacedToolName, toolAllowedByChoice } from "../types";
+import { isAllowedToolChoice, namespacedToolName, resolveToolChoiceWireName, toolAllowedByChoice } from "../types";
 import { contentPartsToText, parseDataUrl } from "./image";
 import { getVertexAccessToken } from "../lib/gcp-adc";
 import { fetchAntigravityWithRetry, fetchVertexWithRetry } from "./google-http";
 import { safeAntigravityHttpErrorMessage, safeVertexHttpErrorMessage } from "./google-errors";
-import { isVertexTruncationReason, vertexTruncationErrorMessage } from "./google-truncation";
+import { isVertexTruncatedTurn, vertexTruncationErrorMessage } from "./google-truncation";
 import { ANTIGRAVITY_REQUEST_UA, antigravitySessionId, isLikelyRealThoughtSignature, sanitizeAntigravityClaudeSignatures } from "./google-antigravity-wire";
 import { compileGoogleWireBody } from "./google-wire-compiler";
-import { neutralizeIdentity } from "./identity";
+import { identifyRoutedModel } from "./identity";
 import { antigravityUsesReplayCache, applyAntigravityReplay, clearAntigravityReplay, observeAntigravityReplay } from "./google-antigravity-replay";
 import { resolveAntigravityEffortWireModel } from "../providers/antigravity-models";
 import {
@@ -122,15 +122,18 @@ function geminiToolResultText(content: string | OcxContentPart[]): string {
   return hasContent ? contentPartsToText(content) : GEMINI_EMPTY_TOOL_OUTPUT_PLACEHOLDER;
 }
 
-function messagesToGeminiFormat(parsed: OcxParsedRequest): { systemInstruction?: unknown; contents: unknown[] } {
+function messagesToGeminiFormat(
+  parsed: OcxParsedRequest,
+  routedModelId = parsed.modelId,
+): { systemInstruction?: unknown; contents: unknown[] } {
   // Neutralize Codex's GPT-5 identity line (Gemini/Antigravity share this path) so a routed model
   // never misreports as GPT-5/OpenAI, and never leaks the proxy identity upstream.
   const toolCatalogNudge = buildNonOpenAIToolCatalogNudgeForTools(parsed.context.tools, parsed.options.toolChoice);
-  const systemText = neutralizeIdentity([
+  const systemText = identifyRoutedModel([
     ...(parsed.context.systemPrompt ?? []),
     ...(toolCatalogNudge ? [toolCatalogNudge] : []),
     GOOGLE_BREVITY_INSTRUCTION,
-  ].join("\n\n"));
+  ].join("\n\n"), routedModelId);
   const systemInstruction = { parts: [{ text: systemText }] };
 
   const contents: unknown[] = [];
@@ -229,6 +232,28 @@ function toolsToGeminiFormat(parsed: OcxParsedRequest): unknown[] | undefined {
   }];
 }
 
+/**
+ * Client tool_choice enforcement on the wire. The catalog nudge states the same contract in
+ * prose, but without functionCallingConfig the model is free to ignore it. "auto" stays absent
+ * so the common case is byte-identical. The allowedTools variant already filters the
+ * declarations in toolsToGeminiFormat; only its "required" half needs a wire mode.
+ */
+function toolChoiceToGeminiToolConfig(parsed: OcxParsedRequest): Record<string, unknown> | undefined {
+  const choice = parsed.options.toolChoice;
+  if (!choice || choice === "auto") return undefined;
+  if (choice === "none") return { functionCallingConfig: { mode: "NONE" } };
+  if (choice === "required") return { functionCallingConfig: { mode: "ANY" } };
+  if (isAllowedToolChoice(choice)) {
+    return choice.mode === "required" ? { functionCallingConfig: { mode: "ANY" } } : undefined;
+  }
+  return {
+    functionCallingConfig: {
+      mode: "ANY",
+      allowedFunctionNames: [resolveToolChoiceWireName(parsed.context.tools, choice.name)],
+    },
+  };
+}
+
 function usageFromGemini(usage: Record<string, number> | undefined): OcxUsage | undefined {
   if (!usage) return undefined;
   return {
@@ -292,12 +317,22 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
       : {}),
 
     async buildRequest(parsed: OcxParsedRequest) {
-      const { systemInstruction, contents } = messagesToGeminiFormat(parsed);
+      const routedModelId = provider.googleMode === "cloud-code-assist"
+        ? resolveAntigravityEffortWireModel(
+            parsed.modelId,
+            mapReasoningEffort(provider, parsed.modelId, parsed.options.reasoning),
+          ).wireModelId
+        : parsed.modelId;
+      const { systemInstruction, contents } = messagesToGeminiFormat(parsed, routedModelId);
       const tools = toolsToGeminiFormat(parsed);
 
       const body: Record<string, unknown> = { contents };
       if (systemInstruction) body.systemInstruction = systemInstruction;
       if (tools) body.tools = tools;
+      // Only meaningful with declarations on the wire: mode ANY with an empty
+      // catalog is a guaranteed upstream 400.
+      const toolConfig = tools ? toolChoiceToGeminiToolConfig(parsed) : undefined;
+      if (toolConfig) body.toolConfig = toolConfig;
 
       const generationConfig: Record<string, unknown> = {};
       if (parsed.options.maxOutputTokens) generationConfig.maxOutputTokens = parsed.options.maxOutputTokens;
@@ -349,6 +384,12 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
         const draftRequest: Record<string, unknown> = { ...body, sessionId };
         // Claude-on-Antigravity forces VALIDATED function calling (the real client always sets it).
         if (/claude/i.test(wireModelId)) {
+          // VALIDATED would defeat a client's tool_choice "none": honor it by dropping the
+          // declarations instead, the wire shape of a tool-less Claude turn.
+          if (parsed.options.toolChoice === "none") {
+            delete draftRequest.tools;
+            delete draftRequest.toolConfig;
+          }
           const existing = (draftRequest.toolConfig ?? {}) as Record<string, unknown>;
           const fcc = (existing.functionCallingConfig ?? {}) as Record<string, unknown>;
           draftRequest.toolConfig = { ...existing, functionCallingConfig: { ...fcc, mode: "VALIDATED" } };
@@ -587,7 +628,7 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
         // Fail-closed: a turn cut off mid tool call (MAX_TOKENS / MALFORMED_FUNCTION_CALL) surfaces
         // an error instead of a silently-incomplete done. Mirrors kiro-truncation.
         if ((provider.googleMode === "vertex" || provider.googleMode === "cloud-code-assist")
-          && toolCallsStarted > 0 && isVertexTruncationReason(lastFinishReason)) {
+          && isVertexTruncatedTurn(lastFinishReason, toolCallsStarted)) {
           yield { type: "error", message: vertexTruncationErrorMessage(lastFinishReason) };
           return;
         }
@@ -743,7 +784,7 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
       // Fail-closed truncation, same as the stream path: a non-stream turn cut off mid tool call
       // (MAX_TOKENS / MALFORMED_FUNCTION_CALL) surfaces an error instead of a silent done.
       if ((provider.googleMode === "vertex" || provider.googleMode === "cloud-code-assist")
-        && toolCallsStarted > 0 && isVertexTruncationReason(candidates?.[0]?.finishReason)) {
+        && isVertexTruncatedTurn(candidates?.[0]?.finishReason, toolCallsStarted)) {
         return finish([{ type: "error", message: vertexTruncationErrorMessage(candidates?.[0]?.finishReason) }]);
       }
 

package/src/adapters/identity.ts

@@ -1,5 +1,5 @@
 /**
- * Central identity neutralization.
+ * Central routed-model identity repair.
  *
  * Codex sends the SAME GPT-5 identity line to EVERY model at request time (the per-model catalog
  * `base_instructions` is ignored on the wire). For routed, non-OpenAI providers that line is both
@@ -8,10 +8,11 @@
  * into the upstream payload — a signature no first-party client (Claude Code, Gemini CLI, Kiro) ever
  * sends, and a likely ToS trigger.
  *
- * The neutral replacement keeps ONLY the necessary instruction (don't misreport as GPT-5/OpenAI)
- * and names no proxy. Provider-native identity blocks (e.g. the anthropic OAuth "You are a Claude
- * agent..." prefix) are layered on TOP of this by the individual adapters; this module never claims
- * to be a specific first-party client.
+ * The replacement keeps the necessary instruction (don't misreport as GPT-5/OpenAI), names the
+ * model id that is actually sent on the wire when it is safe to interpolate, and names no proxy.
+ * Provider-native identity blocks (e.g. the anthropic OAuth "You are a Claude agent..." prefix)
+ * are layered on TOP of this by the individual adapters; this module never claims to be a specific
+ * first-party client.
  */
 
 /** Historical exact identity line Codex injected for every model. */
@@ -37,7 +38,39 @@ export const NEUTRAL_IDENTITY_LINE = "You are a coding agent. Do not claim to be
  * the leak can't reappear in one adapter while being fixed in another.
  */
 export function neutralizeIdentity(systemText: string): string {
-  return systemText.replace(CODEX_GPT5_IDENTITY_RE, NEUTRAL_IDENTITY_LINE);
+  // A callback avoids `$&`, `$'`, and other replacement-string substitutions if this constant ever
+  // becomes configurable. Keep the same safe form in identifyRoutedModel below.
+  return systemText.replace(CODEX_GPT5_IDENTITY_RE, () => NEUTRAL_IDENTITY_LINE);
+}
+
+function safeRoutedModelIdentity(modelName: string): string | null {
+  // Callers pass the model id after adapter-specific wire normalization. Brackets remain valid for
+  // providers that intentionally send a suffix such as `[1m]`; the OpenAI-chat adapter strips that
+  // suffix before calling us only when modelSuffixBracketStrip is enabled.
+  const trimmed = modelName.trim();
+  if (trimmed.length === 0 || trimmed.length > 128) return null;
+  const allowedPunctuation = "._/@:+-[]~";
+  for (const char of trimmed) {
+    const code = char.charCodeAt(0);
+    const isAsciiAlphaNumeric = (code >= 48 && code <= 57)
+      || (code >= 65 && code <= 90)
+      || (code >= 97 && code <= 122);
+    if (!isAsciiAlphaNumeric && !allowedPunctuation.includes(char)) return null;
+  }
+  return trimmed;
+}
+
+/**
+ * Identity for a routed model. Callers pass the concrete model id that will be sent upstream, so
+ * identity questions can name it instead of falling back to Codex/GPT identity inherited from the
+ * native template.
+ */
+export function identifyRoutedModel(systemText: string, modelName: string): string {
+  const identity = safeRoutedModelIdentity(modelName);
+  const replacement = identity
+    ? `You are a coding agent powered by the ${identity}. If asked which model you are, identify as ${identity}. Do not claim to be a different model or to have a different creator.`
+    : "You are a coding agent powered by the configured model. If asked which model you are, identify as configured model. Do not claim to be GPT-5 or made by OpenAI.";
+  return systemText.replace(CODEX_GPT5_IDENTITY_RE, () => replacement);
 }
 
 /** The catalog (static, on-disk) replacement for `base_instructions`. Same neutral wording. */

package/src/adapters/kiro-errors.ts

@@ -109,6 +109,17 @@ function classifyKiroFailure(
       retryable: false,
     };
   }
+  // #993: a gated model demanding a profileArn gets a stable, actionable code
+  // instead of the generic validation bucket. Non-retryable by definition.
+  if (evidence.includes("profilearn") && evidence.includes("required")) {
+    return {
+      message: "kiro_profile_required: Kiro requires a CodeWhisperer profileArn for this account and model. Re-login or re-import the matching Kiro account (ocx account login kiro --reauth) so the profile is captured, then retry.",
+      status: 400,
+      errorType: "invalid_request_error",
+      code: "kiro_profile_required",
+      retryable: false,
+    };
+  }
   if (
     evidence.includes("insufficient_quota")
     || evidence.includes("quota exhausted")

package/src/adapters/kiro-events.ts

@@ -3,7 +3,8 @@ import { kiroTruncationReason } from "./kiro-truncation";
 
 export type ParsedKiroEvent =
   | { type: "content"; data?: string; modelId?: string }
-  | { type: "reasoning"; data?: string }
+  | { type: "reasoning"; data?: string; redactedContent?: string }
+  | { type: "context_usage"; contextUsagePercentage: number }
   | { type: "tool"; name?: string; toolUseId?: string; input?: string; stop?: boolean }
   | { type: "truncation"; data: string }
   | { type: "metadata"; usage?: OcxUsage; contextUsagePercentage?: number; stopReason?: string }
@@ -17,6 +18,10 @@ const KNOWN_EVENT_TYPES = new Set([
   "toolUseEvent",
   "messageMetadataEvent",
   "metadataEvent",
+  // Authoritative context pressure. Every capture (kiro-cli 2.14.1 and 2.16.0) put the percentage
+  // HERE and left `metadataEvent` carrying only `stopReason`; metadataEvent's own
+  // contextUsagePercentage stays supported as a fallback rather than being dropped.
+  "contextUsageEvent",
   "invalidStateEvent",
   "error",
 ]);
@@ -114,11 +119,17 @@ export function parseKiroEvent(eventType: string, payload: Uint8Array): ParsedKi
           : {}),
       };
     case "reasoningContentEvent":
+      // `text` is plaintext reasoning; `redactedContent` is the encrypted blob the GPT-5.6 family
+      // (sol/terra/luna) actually returns — they never send `text`. Keyed off the wire field, not
+      // the model id. Both may be absent on a bare event.
       return {
         type: "reasoning",
         ...(optionalString(eventType, parsed, "text") !== undefined
           ? { data: optionalString(eventType, parsed, "text") }
           : {}),
+        ...(optionalString(eventType, parsed, "redactedContent") !== undefined
+          ? { redactedContent: optionalString(eventType, parsed, "redactedContent") }
+          : {}),
       };
     case "toolUseEvent":
       return {
@@ -161,6 +172,13 @@ export function parseKiroEvent(eventType: string, payload: Uint8Array): ParsedKi
         ...(stopReason !== undefined ? { stopReason } : {}),
       };
     }
+    case "contextUsageEvent": {
+      const contextUsagePercentage = parsed.contextUsagePercentage;
+      if (typeof contextUsagePercentage !== "number" || !Number.isFinite(contextUsagePercentage)) {
+        return malformed(eventType, "contextUsagePercentage must be a finite number");
+      }
+      return { type: "context_usage", contextUsagePercentage };
+    }
     case "invalidStateEvent":
       return { type: "invalid_state", message: optionalString(eventType, parsed, "message") };
     case "error":

package/src/adapters/kiro-thinking.ts

@@ -89,8 +89,16 @@ export class KiroThinkingParser {
       return events;
     }
     if (this.thinkingBuffer.length <= MAX_CLOSE_TAG) return [];
-    const send = this.thinkingBuffer.slice(0, -MAX_CLOSE_TAG);
-    this.replaceCarry("thinkingBuffer", this.thinkingBuffer.slice(-MAX_CLOSE_TAG));
+    // Never split a surrogate pair at the send boundary: a lone high
+    // surrogate at the end of one delta encodes as U+FFFD. Move the cut one
+    // unit earlier so the whole pair stays in the carry.
+    let cut = this.thinkingBuffer.length - MAX_CLOSE_TAG;
+    if (cut > 0 && cut < this.thinkingBuffer.length) {
+      const atCut = this.thinkingBuffer.charCodeAt(cut - 1);
+      if (atCut >= 0xd800 && atCut <= 0xdbff) cut -= 1;
+    }
+    const send = this.thinkingBuffer.slice(0, cut);
+    this.replaceCarry("thinkingBuffer", this.thinkingBuffer.slice(cut));
     return send ? [{ type: "reasoning_raw_delta", text: send }] : [];
   }
 }

package/src/adapters/kiro-tools.ts

@@ -149,7 +149,16 @@ function toolDescriptionLimit(modelId: string): number {
 function truncateDescription(description: string, limit: number): string {
   if (description.length <= limit) return description;
   if (limit <= 1) return description.slice(0, limit);
-  return `${description.slice(0, limit - 1)}…`;
+  let end = limit - 1;
+  // Never end the kept text on a lone high surrogate; one step back keeps
+  // the whole pair out instead of a U+FFFD-producing half.
+  if (description.charCodeAt(end - 1) >= 0xd800 && description.charCodeAt(end - 1) <= 0xdbff) end -= 1;
+  return `${description.slice(0, end)}…`;
+}
+
+/** Test-only: exercise the surrogate-safe description truncation directly. */
+export function truncateDescriptionForTests(description: string, limit: number): string {
+  return truncateDescription(description, limit);
 }
 
 function serializedToolCatalogBytes(tools: readonly unknown[]): number {