pi-cache-optimizer 2.8.16 → 2.8.18

package/src/stats-store.ts

@@ -0,0 +1,500 @@
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, mkdir, readFile, readdir, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { LOG_PREFIX, asRecord, getErrorCode, getNonNegativeNumber, isNonEmptyString, isProcessAlive } from "./common.ts";
+import { STATE_DIR } from "./paths.ts";
+
+export type CacheProviderId = "deepseek" | "openai" | "claude" | "gemini";
+
+export const STATE_FILE_PATH = join(STATE_DIR, "pi-cache-optimizer-stats.json");
+
+export const LEGACY_STATE_FILE_PATH = join(STATE_DIR, "deepseek-cache-optimizer-stats.json");
+
+export const SHARD_STATE_DIR = join(STATE_DIR, "pi-cache-optimizer-stats.d");
+
+export const SHARD_FILES_DIR = join(SHARD_STATE_DIR, "shards");
+
+export const SHARD_EPOCH_DIR = join(SHARD_STATE_DIR, "epochs");
+
+export const SHARD_MODEL_EPOCH_DIR = join(SHARD_EPOCH_DIR, "models");
+
+export const SHARD_MAINTENANCE_DIR = join(SHARD_STATE_DIR, "maintenance");
+
+export const SHARD_GLOBAL_EPOCH_PATH = join(SHARD_EPOCH_DIR, "global.json");
+
+export const SHARD_CLEANUP_LOCK_PATH = join(SHARD_MAINTENANCE_DIR, "cleanup.lock");
+
+export const SHARD_CLEANUP_MARKER_PATH = join(SHARD_MAINTENANCE_DIR, "last-cleanup");
+
+export const SHARD_RETENTION_MS = 48 * 60 * 60 * 1000;
+
+export const SHARD_TEMP_RETENTION_MS = 24 * 60 * 60 * 1000;
+
+export const SHARD_CLEANUP_INTERVAL_MS = 6 * 60 * 60 * 1000;
+
+export const SHARD_CLEANUP_LOCK_STALE_MS = 60 * 60 * 1000;
+
+export const CACHE_PROVIDER_IDS: CacheProviderId[] = ["deepseek", "openai", "claude", "gemini"];
+
+export type CacheStats = {
+  day: string;
+  totalRequests: number;
+  hitRequests: number;
+  cachedInputTokens: number;
+  cacheWriteInputTokens: number;
+  totalInputTokens: number;
+};
+
+/** Per-model-key scoped state. Used in memory and for v3 persistence. */
+export type PersistedRoutedModelRef = {
+  provider: string;
+  id: string;
+  name?: string;
+};
+
+export type UsageSnapshot = {
+  cacheRead: number;
+  cacheWrite: number;
+  totalInput: number;
+};
+
+/**
+ * Per-request sample stored for trend analysis and usage-field-missing detection.
+ * Contains only numeric counters and booleans — never message content, prompts,
+ * payloads, headers, API keys, or model outputs.
+ */
+export type PersistedStatsShardV7 = {
+  version: 7;
+  kind: "pi-cache-optimizer-shard";
+  instanceId: string;
+  sessionHash: string;
+  process: {
+    pid: number;
+    ppid: number;
+    instanceStartedAt: number;
+  };
+  lifecycle: {
+    state: "active" | "closed";
+    createdAt: number;
+    updatedAt: number;
+    closedAt?: number;
+  };
+  day: string;
+  globalEpoch: string;
+  models: Record<string, {
+    modelEpoch: string;
+    provider: string;
+    modelId: string;
+    modelName?: string;
+    api?: string;
+    stats: CacheStats;
+  }>;
+  lastRoutedModel?: PersistedRoutedModelRef;
+};
+
+export type ShardAggregate = {
+  bySession: Record<string, Record<string, CacheStats>>;
+  totalsByModel: Record<string, CacheStats>;
+  instancesBySession: Record<string, number>;
+  instancesBySessionModel: Record<string, Record<string, number>>;
+  sessionsByModel: Record<string, number>;
+  instancesByModel: Record<string, number>;
+  modelRefsByKey: Record<string, PersistedRoutedModelRef>;
+  lastRoutedModelBySession: Record<string, PersistedRoutedModelRef>;
+};
+
+export function currentLocalDay(): string {
+  const now = new Date();
+  const year = now.getFullYear();
+  const month = String(now.getMonth() + 1).padStart(2, "0");
+  const day = String(now.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+
+export function emptyCacheStats(day = currentLocalDay()): CacheStats {
+  return {
+    day,
+    totalRequests: 0,
+    hitRequests: 0,
+    cachedInputTokens: 0,
+    cacheWriteInputTokens: 0,
+    totalInputTokens: 0,
+  };
+}
+
+export function emptyAllCacheStats(day = currentLocalDay()): Partial<Record<CacheProviderId, CacheStats>> {
+  return Object.fromEntries(CACHE_PROVIDER_IDS.map((id) => [id, emptyCacheStats(day)])) as Partial<Record<CacheProviderId, CacheStats>>;
+}
+
+export function addUsageToCacheStats(stats: CacheStats, usage: UsageSnapshot): void {
+  stats.totalRequests += 1;
+  if (usage.cacheRead > 0) stats.hitRequests += 1;
+  stats.cachedInputTokens += usage.cacheRead;
+  stats.cacheWriteInputTokens += usage.cacheWrite;
+  stats.totalInputTokens += usage.totalInput;
+}
+
+export function parseCacheStats(value: unknown): CacheStats | undefined {
+  const stats = asRecord(value);
+  if (!stats || typeof stats.day !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(stats.day)) {
+    return undefined;
+  }
+
+  const totalRequests = getNonNegativeNumber(stats, "totalRequests");
+  const hitRequests = getNonNegativeNumber(stats, "hitRequests");
+  const cachedInputTokens = getNonNegativeNumber(stats, "cachedInputTokens");
+  const cacheWriteInputTokens = getNonNegativeNumber(stats, "cacheWriteInputTokens") ?? 0;
+  const totalInputTokens = getNonNegativeNumber(stats, "totalInputTokens");
+
+  if (
+    totalRequests === undefined ||
+    hitRequests === undefined ||
+    cachedInputTokens === undefined ||
+    totalInputTokens === undefined ||
+    hitRequests > totalRequests ||
+    cachedInputTokens > totalInputTokens ||
+    cacheWriteInputTokens > totalInputTokens
+  ) {
+    return undefined;
+  }
+
+  return {
+    day: stats.day,
+    totalRequests,
+    hitRequests,
+    cachedInputTokens,
+    cacheWriteInputTokens,
+    totalInputTokens,
+  };
+}
+
+export function cloneCacheStats(stats: CacheStats): CacheStats {
+  return { ...stats };
+}
+
+export function addCacheStatsTotals(target: CacheStats, source: CacheStats): void {
+  target.totalRequests += source.totalRequests;
+  target.hitRequests += source.hitRequests;
+  target.cachedInputTokens += source.cachedInputTokens;
+  target.cacheWriteInputTokens += source.cacheWriteInputTokens;
+  target.totalInputTokens += source.totalInputTokens;
+}
+
+export function mergeCacheStatsForTotal(existing: CacheStats | undefined, incoming: CacheStats): CacheStats {
+  if (!existing) return cloneCacheStats(incoming);
+  if (incoming.day > existing.day) return cloneCacheStats(incoming);
+  if (incoming.day < existing.day) return existing;
+  addCacheStatsTotals(existing, incoming);
+  return existing;
+}
+
+export function parsePersistedRoutedModelRef(value: unknown): PersistedRoutedModelRef | undefined {
+  const record = asRecord(value);
+  const provider = record?.provider;
+  const id = record?.id;
+  const name = record?.name;
+  if (!isNonEmptyString(provider) || !isNonEmptyString(id)) return undefined;
+
+  return {
+    provider: provider.trim(),
+    id: id.trim(),
+    name: isNonEmptyString(name) ? name.trim() : id.trim(),
+  };
+}
+
+export function modelEpochPath(modelKeyValue: string): string {
+  return join(SHARD_MODEL_EPOCH_DIR, `${createHash("sha256").update(modelKeyValue).digest("hex")}.json`);
+}
+
+export function initialEpoch(scope: string): string {
+  return `initial:${scope}`;
+}
+
+export function parseEpochRecord(value: unknown): string | undefined {
+  const record = asRecord(value);
+  return record?.version === 1 && isNonEmptyString(record.epoch) ? record.epoch.trim() : undefined;
+}
+
+export async function readEpochFile(path: string, fallback: string): Promise<string> {
+  try {
+    return parseEpochRecord(JSON.parse(await readFile(path, "utf8"))) ?? fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+export async function readGlobalStatsEpoch(): Promise<string> {
+  return readEpochFile(SHARD_GLOBAL_EPOCH_PATH, initialEpoch("global"));
+}
+
+export async function readModelStatsEpoch(modelKeyValue: string): Promise<string> {
+  return readEpochFile(modelEpochPath(modelKeyValue), initialEpoch(`model:${modelKeyValue}`));
+}
+
+export async function writeStatsEpoch(path: string, epoch: string): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  const tempPath = `${path}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`;
+  await writeFile(tempPath, JSON.stringify({ version: 1, epoch, createdAt: Date.now() }, null, 2) + "\n", "utf8");
+  await rename(tempPath, path);
+}
+
+export async function advanceGlobalStatsEpoch(): Promise<string> {
+  const epoch = `${Date.now()}-${randomUUID()}`;
+  await writeStatsEpoch(SHARD_GLOBAL_EPOCH_PATH, epoch);
+  return epoch;
+}
+
+export async function advanceModelStatsEpoch(modelKeyValue: string): Promise<string> {
+  const epoch = `${Date.now()}-${randomUUID()}`;
+  await writeStatsEpoch(modelEpochPath(modelKeyValue), epoch);
+  return epoch;
+}
+
+export function parsePersistedStatsShardV7(value: unknown): PersistedStatsShardV7 | undefined {
+  const record = asRecord(value);
+  const processRecord = asRecord(record?.process);
+  const lifecycle = asRecord(record?.lifecycle);
+  const rawModels = asRecord(record?.models);
+  if (
+    record?.version !== 7 ||
+    record.kind !== "pi-cache-optimizer-shard" ||
+    !isNonEmptyString(record.instanceId) ||
+    !isNonEmptyString(record.sessionHash) ||
+    !processRecord ||
+    !Number.isInteger(processRecord.pid) ||
+    !Number.isInteger(processRecord.ppid) ||
+    typeof processRecord.instanceStartedAt !== "number" ||
+    !lifecycle ||
+    (lifecycle.state !== "active" && lifecycle.state !== "closed") ||
+    typeof lifecycle.createdAt !== "number" ||
+    typeof lifecycle.updatedAt !== "number" ||
+    !isNonEmptyString(record.day) ||
+    !/^\d{4}-\d{2}-\d{2}$/.test(record.day) ||
+    !isNonEmptyString(record.globalEpoch) ||
+    !rawModels
+  ) return undefined;
+
+  const models: PersistedStatsShardV7["models"] = {};
+  for (const [key, rawEntry] of Object.entries(rawModels)) {
+    const entry = asRecord(rawEntry);
+    const stats = parseCacheStats(entry?.stats);
+    if (
+      !entry || !stats || !isNonEmptyString(entry.modelEpoch) ||
+      !isNonEmptyString(entry.provider) || !isNonEmptyString(entry.modelId) ||
+      key !== `${entry.provider.trim()}/${entry.modelId.trim()}`
+    ) continue;
+    models[key] = {
+      modelEpoch: entry.modelEpoch.trim(),
+      provider: entry.provider.trim(),
+      modelId: entry.modelId.trim(),
+      ...(isNonEmptyString(entry.modelName) ? { modelName: entry.modelName.trim() } : {}),
+      ...(isNonEmptyString(entry.api) ? { api: entry.api.trim() } : {}),
+      stats,
+    };
+  }
+
+  const lastRoutedModel = parsePersistedRoutedModelRef(record.lastRoutedModel);
+  return {
+    version: 7,
+    kind: "pi-cache-optimizer-shard",
+    instanceId: record.instanceId.trim(),
+    sessionHash: record.sessionHash.trim(),
+    process: {
+      pid: Number(processRecord.pid),
+      ppid: Number(processRecord.ppid),
+      instanceStartedAt: processRecord.instanceStartedAt,
+    },
+    lifecycle: {
+      state: lifecycle.state,
+      createdAt: lifecycle.createdAt,
+      updatedAt: lifecycle.updatedAt,
+      ...(typeof lifecycle.closedAt === "number" ? { closedAt: lifecycle.closedAt } : {}),
+    },
+    day: record.day,
+    globalEpoch: record.globalEpoch.trim(),
+    models,
+    ...(lastRoutedModel ? { lastRoutedModel } : {}),
+  };
+}
+
+export async function writeStatsShardV7(path: string, shard: PersistedStatsShardV7): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  const tempPath = `${path}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`;
+  await writeFile(tempPath, JSON.stringify(shard, null, 2) + "\n", "utf8");
+  await rename(tempPath, path);
+}
+
+export async function readValidStatsShardsV7(directory: string = SHARD_FILES_DIR): Promise<PersistedStatsShardV7[]> {
+  let names: string[];
+  try {
+    names = await readdir(directory);
+  } catch (error) {
+    if (getErrorCode(error) === "ENOENT") return [];
+    throw error;
+  }
+  const shards: PersistedStatsShardV7[] = [];
+  for (const name of names) {
+    if (!/^[0-9a-f-]+\.json$/i.test(name)) continue;
+    const path = join(directory, name);
+    try {
+      const info = await lstat(path);
+      if (!info.isFile() || info.isSymbolicLink()) continue;
+      const parsed = parsePersistedStatsShardV7(JSON.parse(await readFile(path, "utf8")));
+      const filenameInstanceId = name.slice(0, -".json".length);
+      if (parsed && parsed.instanceId === filenameInstanceId) shards.push(parsed);
+    } catch {
+      // Ignore malformed or transiently unavailable shards. Atomic writers will
+      // publish a complete replacement on the next successful update.
+    }
+  }
+  return shards;
+}
+
+export async function aggregateStatsShardsV7(
+  shards: PersistedStatsShardV7[],
+  day: string = currentLocalDay(),
+): Promise<ShardAggregate> {
+  const globalEpoch = await readGlobalStatsEpoch();
+  const modelEpochs = new Map<string, string>();
+  const result: ShardAggregate = {
+    bySession: {},
+    totalsByModel: {},
+    instancesBySession: {},
+    instancesBySessionModel: {},
+    sessionsByModel: {},
+    instancesByModel: {},
+    modelRefsByKey: {},
+    lastRoutedModelBySession: {},
+  };
+  const routedUpdatedAt = new Map<string, number>();
+  const modelRefUpdatedAt = new Map<string, number>();
+  const modelSessions = new Map<string, Set<string>>();
+
+  for (const shard of shards) {
+    if (shard.day !== day || shard.globalEpoch !== globalEpoch) continue;
+    let contributed = false;
+    if (shard.lastRoutedModel && (routedUpdatedAt.get(shard.sessionHash) ?? -1) < shard.lifecycle.updatedAt) {
+      routedUpdatedAt.set(shard.sessionHash, shard.lifecycle.updatedAt);
+      result.lastRoutedModelBySession[shard.sessionHash] = shard.lastRoutedModel;
+    }
+    for (const [key, entry] of Object.entries(shard.models)) {
+      let epoch = modelEpochs.get(key);
+      if (!epoch) {
+        epoch = await readModelStatsEpoch(key);
+        modelEpochs.set(key, epoch);
+      }
+      if (entry.modelEpoch !== epoch || entry.stats.day !== day) continue;
+      contributed = true;
+      const sessionModels = result.bySession[shard.sessionHash] ??= {};
+      sessionModels[key] = mergeCacheStatsForTotal(sessionModels[key], entry.stats);
+      result.totalsByModel[key] = mergeCacheStatsForTotal(result.totalsByModel[key], entry.stats);
+      result.instancesByModel[key] = (result.instancesByModel[key] ?? 0) + 1;
+      if ((modelRefUpdatedAt.get(key) ?? -1) < shard.lifecycle.updatedAt) {
+        modelRefUpdatedAt.set(key, shard.lifecycle.updatedAt);
+        result.modelRefsByKey[key] = {
+          provider: entry.provider,
+          id: entry.modelId,
+          name: entry.modelName ?? entry.modelId,
+        };
+      }
+      const sessionInstances = result.instancesBySessionModel[shard.sessionHash] ??= {};
+      sessionInstances[key] = (sessionInstances[key] ?? 0) + 1;
+      const sessions = modelSessions.get(key) ?? new Set<string>();
+      sessions.add(shard.sessionHash);
+      modelSessions.set(key, sessions);
+    }
+    if (contributed) {
+      result.instancesBySession[shard.sessionHash] = (result.instancesBySession[shard.sessionHash] ?? 0) + 1;
+    }
+  }
+  for (const [key, sessions] of modelSessions) result.sessionsByModel[key] = sessions.size;
+  return result;
+}
+
+export async function loadStatsShardAggregateV7(directory: string = SHARD_FILES_DIR): Promise<ShardAggregate> {
+  return aggregateStatsShardsV7(await readValidStatsShardsV7(directory));
+}
+
+export async function removeLegacyStatsFiles(): Promise<void> {
+  for (const path of [STATE_FILE_PATH, LEGACY_STATE_FILE_PATH]) {
+    try {
+      await unlink(path);
+    } catch (error) {
+      if (getErrorCode(error) !== "ENOENT") console.warn(`${LOG_PREFIX}: failed to remove obsolete stats file ${path}`, error);
+    }
+  }
+}
+
+export async function cleanupStatsShardsV7(now = Date.now(), directory: string = SHARD_FILES_DIR): Promise<number> {
+  let names: string[];
+  try {
+    names = await readdir(directory);
+  } catch (error) {
+    return getErrorCode(error) === "ENOENT" ? 0 : Promise.reject(error);
+  }
+  const today = currentLocalDay();
+  let removed = 0;
+  for (const name of names) {
+    const isShard = /^[0-9a-f-]+\.json$/i.test(name);
+    const isTemp = name.endsWith(".tmp");
+    if (!isShard && !isTemp) continue;
+    const path = join(directory, name);
+    try {
+      const info = await lstat(path);
+      if (!info.isFile() || info.isSymbolicLink()) continue;
+      if (isTemp) {
+        if (now - info.mtimeMs < SHARD_TEMP_RETENTION_MS) continue;
+      } else {
+        const text = await readFile(path, "utf8");
+        let parsed: PersistedStatsShardV7 | undefined;
+        try {
+          parsed = parsePersistedStatsShardV7(JSON.parse(text));
+        } catch {
+          // A corrupt JSON shard has no usable lifecycle metadata. Apply the
+          // same mtime retention as schema-invalid shards instead of keeping
+          // it forever; read failures still leave the file untouched.
+        }
+        if (parsed?.day === today) continue;
+        const updatedAt = parsed?.lifecycle.updatedAt ?? info.mtimeMs;
+        if (now - updatedAt < SHARD_RETENTION_MS) continue;
+        if (parsed?.lifecycle.state === "active" && isProcessAlive(parsed.process.pid)) continue;
+      }
+      await unlink(path);
+      removed += 1;
+    } catch {
+      // Best-effort maintenance must never block the extension.
+    }
+  }
+  return removed;
+}
+
+export async function maybeCleanupStatsShardsV7(now = Date.now()): Promise<void> {
+  await mkdir(SHARD_MAINTENANCE_DIR, { recursive: true });
+  try {
+    const marker = await stat(SHARD_CLEANUP_MARKER_PATH);
+    if (now - marker.mtimeMs < SHARD_CLEANUP_INTERVAL_MS) return;
+  } catch {}
+
+  try {
+    await mkdir(SHARD_CLEANUP_LOCK_PATH);
+  } catch (error) {
+    if (getErrorCode(error) !== "EEXIST") return;
+    try {
+      const lock = await stat(SHARD_CLEANUP_LOCK_PATH);
+      if (now - lock.mtimeMs <= SHARD_CLEANUP_LOCK_STALE_MS) return;
+      await rm(SHARD_CLEANUP_LOCK_PATH, { recursive: true, force: true });
+      await mkdir(SHARD_CLEANUP_LOCK_PATH);
+    } catch {
+      return;
+    }
+  }
+
+  try {
+    await cleanupStatsShardsV7(now);
+    const tempPath = `${SHARD_CLEANUP_MARKER_PATH}.${process.pid}.${randomUUID()}.tmp`;
+    await writeFile(tempPath, `${now}\n`, "utf8");
+    await rename(tempPath, SHARD_CLEANUP_MARKER_PATH);
+  } finally {
+    await rm(SHARD_CLEANUP_LOCK_PATH, { recursive: true, force: true });
+  }
+}

package/src/tool-ordering.ts

@@ -0,0 +1,209 @@
+import { type PiModel, type UnknownRecord, asRecord, isNonEmptyString } from "./common.ts";
+import { isResponsesPromptRewriteBypassApi } from "./model-identity.ts";
+
+export type ToolOrderApi =
+  | "openai-completions"
+  | "openai-responses"
+  | "anthropic-messages"
+  | "google-generative-ai"
+  | "google-vertex"
+  | "bedrock-converse-stream";
+
+export function isKnownToolOrderApi(api: unknown): api is ToolOrderApi {
+  return api === "openai-completions" || api === "openai-responses" ||
+    api === "anthropic-messages" || api === "google-generative-ai" ||
+    api === "google-vertex" || api === "bedrock-converse-stream";
+}
+
+export function isToolOrderingEligibleModel(model: PiModel | undefined): boolean {
+  // Responses/Codex prompt bypasses remain untouched. The pure helper still
+  // supports the verified Responses shape for fixture use, but the request
+  // hook must preserve Pi's server-managed/safety-sensitive bypass.
+  return !!model && isKnownToolOrderApi(model.api) && !isResponsesPromptRewriteBypassApi(model.api);
+}
+
+export function getToolNameForPayload(tool: unknown): string | undefined {
+  const record = asRecord(tool);
+  if (!record) return undefined;
+  if (isNonEmptyString(record.name)) return record.name;
+  const fn = asRecord(record.function);
+  if (isNonEmptyString(fn?.name)) return fn.name;
+  const custom = asRecord(record.custom);
+  if (isNonEmptyString(custom?.name)) return custom.name;
+  const spec = asRecord(record.toolSpec);
+  if (isNonEmptyString(spec?.name)) return spec.name;
+  return undefined;
+}
+
+export function compareToolOrderEntries(
+  left: { name: string; index: number },
+  right: { name: string; index: number },
+): number {
+  // Do not use localeCompare here: its result can vary with the host locale.
+  // Exact UTF-16 code-unit ordering plus the original index is reproducible.
+  return left.name < right.name ? -1 : left.name > right.name ? 1 : left.index - right.index;
+}
+
+export function isJsonObject(value: unknown): value is UnknownRecord {
+  return asRecord(value) !== undefined;
+}
+
+export function isVerifiedToolForApi(tool: unknown, api: ToolOrderApi): tool is UnknownRecord {
+  const record = asRecord(tool);
+  if (!record) return false;
+
+  if (api === "openai-completions") {
+    if (record.type === "function") {
+      const fn = asRecord(record.function);
+      return isNonEmptyString(fn?.name) && isJsonObject(fn.parameters);
+    }
+    if (record.type === "custom") {
+      const custom = asRecord(record.custom);
+      return isNonEmptyString(custom?.name) && isJsonObject(custom.format);
+    }
+    return false;
+  }
+
+  if (api === "openai-responses") {
+    if (record.type === "function") {
+      return isNonEmptyString(record.name) && isJsonObject(record.parameters);
+    }
+    if (record.type === "custom") {
+      return isNonEmptyString(record.name) && isJsonObject(record.format);
+    }
+    return false;
+  }
+
+  if (api === "anthropic-messages") {
+    return isNonEmptyString(record.name) && isJsonObject(record.input_schema);
+  }
+
+  if (api === "google-generative-ai" || api === "google-vertex") {
+    return isNonEmptyString(record.name) &&
+      (isJsonObject(record.parametersJsonSchema) || isJsonObject(record.parameters));
+  }
+
+  const spec = asRecord(record.toolSpec);
+  const inputSchema = asRecord(spec?.inputSchema);
+  return isNonEmptyString(spec?.name) && isJsonObject(inputSchema?.json);
+}
+
+export type ToolArrayInspection = {
+  sortedIndices: number[];
+  changed: boolean;
+};
+
+export function hasTopLevelCacheControl(tools: unknown): boolean {
+  return Array.isArray(tools) && tools.some((tool) => {
+    const record = asRecord(tool);
+    return !!record && Object.prototype.hasOwnProperty.call(record, "cache_control");
+  });
+}
+
+export function inspectToolArray(tools: unknown, api: ToolOrderApi): ToolArrayInspection | undefined {
+  if (!Array.isArray(tools)) return undefined;
+  // Native Anthropic and OpenAI-compatible transports can attach a cache
+  // breakpoint to a specific tool (normally the final one). Never move it,
+  // regardless of API id. Anthropic defer_loading also encodes immediate vs
+  // deferred tool groups in array order, so mixed/grouped payloads are no-ops.
+  if (hasTopLevelCacheControl(tools)) return undefined;
+  if (api === "anthropic-messages" && tools.some((tool) => {
+    const record = asRecord(tool);
+    return !!record && Object.prototype.hasOwnProperty.call(record, "defer_loading");
+  })) return undefined;
+  const entries = tools.map((tool, index) => {
+    if (!isVerifiedToolForApi(tool, api)) return undefined;
+    return { name: getToolNameForPayload(tool) ?? "", index };
+  });
+  if (entries.some((entry) => entry === undefined)) return undefined;
+
+  const verified = entries as Array<{ name: string; index: number }>;
+  const sorted = [...verified].sort(compareToolOrderEntries);
+  return {
+    sortedIndices: sorted.map((entry) => entry.index),
+    changed: sorted.some((entry, index) => entry.index !== index),
+  };
+}
+
+export type ToolArrayPath = {
+  kind: "root" | "bedrock" | "google";
+  groupIndex?: number;
+  sortedIndices: number[];
+};
+
+/**
+ * Pure deterministic tool-order normalizer for the exact payload shapes
+ * emitted by Pi's built-in transports. It returns the original object for a
+ * no-op/unsupported/malformed payload and shallow-clones only the verified
+ * path to a tool array when sorting is needed. Tool objects and unrelated
+ * request fields (including SDK objects and AbortSignal) retain their identity.
+ */
+export function normalizeToolsInPayload(
+  payload: unknown,
+  api: unknown,
+): { payload: unknown; changed: boolean } {
+  if (!isKnownToolOrderApi(api)) return { payload, changed: false };
+  const root = asRecord(payload);
+  if (!root) return { payload, changed: false };
+
+  if (api === "google-generative-ai" || api === "google-vertex") {
+    const config = asRecord(root.config);
+    const groups = config?.tools;
+    if (!Array.isArray(groups) || groups.length === 0) return { payload, changed: false };
+
+    const paths: ToolArrayPath[] = [];
+    for (let groupIndex = 0; groupIndex < groups.length; groupIndex++) {
+      const group = asRecord(groups[groupIndex]);
+      if (!group || !Array.isArray(group.functionDeclarations)) return { payload, changed: false };
+      const inspected = inspectToolArray(group.functionDeclarations, api);
+      if (!inspected) return { payload, changed: false };
+      if (inspected.changed) paths.push({ kind: "google", groupIndex, sortedIndices: inspected.sortedIndices });
+    }
+    if (paths.length === 0) return { payload, changed: false };
+
+    const sortedGroups = [...groups];
+    for (const path of paths) {
+      const groupIndex = path.groupIndex!;
+      const group = asRecord(groups[groupIndex])!;
+      const tools = group.functionDeclarations as unknown[];
+      sortedGroups[groupIndex] = {
+        ...group,
+        functionDeclarations: path.sortedIndices.map((index) => tools[index]),
+      };
+    }
+    return {
+      payload: { ...root, config: { ...config, tools: sortedGroups } },
+      changed: true,
+    };
+  }
+
+  if (api === "bedrock-converse-stream") {
+    const toolConfig = asRecord(root.toolConfig);
+    const tools = toolConfig?.tools;
+    const inspected = inspectToolArray(tools, api);
+    if (!inspected || !inspected.changed || !Array.isArray(tools)) return { payload, changed: false };
+    return {
+      payload: {
+        ...root,
+        toolConfig: {
+          ...toolConfig,
+          tools: inspected.sortedIndices.map((index) => tools[index]),
+        },
+      },
+      changed: true,
+    };
+  }
+
+  const tools = root.tools;
+  const inspected = inspectToolArray(tools, api);
+  if (!inspected || !inspected.changed || !Array.isArray(tools)) return { payload, changed: false };
+  return {
+    payload: { ...root, tools: inspected.sortedIndices.map((index) => tools[index]) },
+    changed: true,
+  };
+}
+
+/** Public test-facing alias: a pure payload transformation. */
+export function sortToolsInPayload(payload: unknown, api: unknown): unknown {
+  return normalizeToolsInPayload(payload, api).payload;
+}