cartethyia 2.5.10 → 2.6.1

package/src/transport/routing/candidate-index.ts

@@ -0,0 +1,88 @@
+// Immutable per-snapshot candidate index for model resolution.
+import type { RouteCandidate, RouteSnapshot } from "./route-model";
+
+/** One parsed model reference: `provider/model` or a bare `model`. */
+export interface ParsedModel {
+  readonly providerId: string | null;
+  readonly modelId: string;
+}
+
+/** Parse one model reference into its provider and bare model id. */
+export function parseModelReference(model: string): ParsedModel {
+  const slash = model.indexOf("/");
+  if (slash === -1) return { providerId: null, modelId: model };
+  return { providerId: model.slice(0, slash), modelId: model.slice(slash + 1) };
+}
+
+/**
+ * An immutable, per-snapshot index of route candidates.
+ *
+ * Snapshots are immutable by contract (rebuilt wholesale on catalog change),
+ * so the index is built once per snapshot — O(C) — and reused by every plan,
+ * instead of the previous behavior of rescanning the full candidate list per
+ * resolved model inside one plan: a combo with K unique members over C
+ * candidates cost K×C `candidateMatches` calls (each re-parsing the model
+ * string), repeated on every request.
+ */
+export interface RouteCandidateIndex {
+  /** Candidates keyed by `provider_id/model_id`, snapshot order preserved. */
+  readonly qualified: ReadonlyMap<string, readonly RouteCandidate[]>;
+  /** Candidates keyed by bare `model_id`, snapshot order preserved. */
+  readonly bare: ReadonlyMap<string, readonly RouteCandidate[]>;
+}
+
+/** WeakMap cache: an evicted/rebuilt snapshot releases its index automatically. */
+const indexBySnapshot = new WeakMap<RouteSnapshot, RouteCandidateIndex>();
+
+/**
+ * Builds (once per snapshot) the lookup index for `resolveMatchingCandidates`.
+ *
+ * Each candidate is visited exactly once and filed under both its qualified and
+ * bare key, so a lookup later is one `Map.get` regardless of catalog size.
+ * Snapshot order is preserved within each bucket because `Map` iterates in
+ * insertion order and candidates are appended in one pass.
+ */
+export function routeCandidateIndex(snapshot: RouteSnapshot): RouteCandidateIndex {
+  const cached = indexBySnapshot.get(snapshot);
+  if (cached) return cached;
+  const qualified = new Map<string, RouteCandidate[]>();
+  const bare = new Map<string, RouteCandidate[]>();
+  for (const candidate of snapshot.candidates) {
+    const qualifiedKey = `${candidate.provider_id}/${candidate.model_id}`;
+    const qualifiedList = qualified.get(qualifiedKey);
+    if (qualifiedList) qualifiedList.push(candidate);
+    else qualified.set(qualifiedKey, [candidate]);
+
+    const bareList = bare.get(candidate.model_id);
+    if (bareList) bareList.push(candidate);
+    else bare.set(candidate.model_id, [candidate]);
+  }
+  const index: RouteCandidateIndex = { qualified, bare };
+  indexBySnapshot.set(snapshot, index);
+  return index;
+}
+
+/**
+ * Looks up the candidates a parsed model reference resolves to, filtered by
+ * tenant.
+ *
+ * A qualified reference (`provider/model`) reads the exact bucket and requires
+ * the provider to match; a bare reference reads every provider's bucket for
+ * that model. The tenant rule is the resolver's existing one, unchanged:
+ * a candidate is visible only when it is global (`tenant_id == null`) or
+ * belongs to the requesting tenant.
+ */
+export function lookupRouteCandidates(
+  index: RouteCandidateIndex,
+  parsedModel: ParsedModel,
+  tenantId: string | null,
+): readonly RouteCandidate[] {
+  const group =
+    parsedModel.providerId === null
+      ? index.bare.get(parsedModel.modelId)
+      : index.qualified.get(`${parsedModel.providerId}/${parsedModel.modelId}`);
+  if (group === undefined || group.length === 0) return [];
+  return group.filter(
+    (candidate) => candidate.tenant_id == null || candidate.tenant_id === tenantId,
+  );
+}

package/src/transport/routing/reservations.ts

@@ -1,25 +1,136 @@
-// In-memory reservation lease store with lazy TTL cleanup.
+// In-memory reservation lease store with expiry-ordered cleanup.
 import type { Reservation, RouteCandidate, RoutingRevision } from "./route-model";
 
+/** One heap node: when a lease expires, and which lease it names. */
+interface ExpiryNode {
+  readonly expiresAt: number;
+  readonly leaseId: string;
+}
+
 /**
- * In-memory reservation lease store with lazy TTL cleanup. The bounded sweep
- * runs before acquisition so abandoned local metadata cannot grow forever.
+ * Binary min-heap on `expiresAt`.
+ *
+ * The sweep only ever needs the *earliest* expiring reservations, so a heap
+ * answers "which nodes are expired right now" by examining heads only — the
+ * previous implementation walked the entire lease map per sweep interval.
+ * Stale nodes (a lease released before its expiry) are harmless: the sweep
+ * verifies against the map before deleting and drops the node.
+ */
+class ExpiryHeap {
+  private nodes: ExpiryNode[] = [];
+
+  get size(): number {
+    return this.nodes.length;
+  }
+
+  insert(node: ExpiryNode): void {
+    this.nodes.push(node);
+    this.bubbleUp(this.nodes.length - 1);
+  }
+
+  /** The earliest-expiring node, without removing it. */
+  peek(): ExpiryNode | undefined {
+    return this.nodes[0];
+  }
+
+  pop(): ExpiryNode | undefined {
+    const top = this.nodes[0];
+    const last = this.nodes.pop();
+    if (this.nodes.length > 0 && last !== undefined) {
+      this.nodes[0] = last;
+      this.bubbleDown(0);
+    }
+    return top;
+  }
+
+  private bubbleUp(index: number): void {
+    let current = index;
+    while (current > 0) {
+      const parent = (current - 1) >> 1;
+      if (this.nodes[current]!.expiresAt >= this.nodes[parent]!.expiresAt) break;
+      [this.nodes[current], this.nodes[parent]] = [this.nodes[parent]!, this.nodes[current]!];
+      current = parent;
+    }
+  }
+
+  private bubbleDown(index: number): void {
+    let current = index;
+    for (;;) {
+      const left = current * 2 + 1;
+      const right = left + 1;
+      let smallest = current;
+      if (left < this.nodes.length && this.nodes[left]!.expiresAt < this.nodes[smallest]!.expiresAt) {
+        smallest = left;
+      }
+      if (
+        right < this.nodes.length &&
+        this.nodes[right]!.expiresAt < this.nodes[smallest]!.expiresAt
+      ) {
+        smallest = right;
+      }
+      if (smallest === current) break;
+      [this.nodes[current], this.nodes[smallest]] = [this.nodes[smallest]!, this.nodes[current]!];
+      current = smallest;
+    }
+  }
+}
+
+/**
+ * In-memory reservation lease store with expiry-ordered cleanup.
+ *
+ * Acquisitions insert into an expiry min-heap; the bounded sweep examines only
+ * expired heads and verifies the map still holds that exact reservation before
+ * deleting (a released entry leaves a harmless stale node behind, dropped on
+ * the next sweep that reaches it or by periodic compaction). Stale nodes are
+ * compacted when they dominate the heap, so a long stream of short-lived
+ * released reservations cannot grow the heap without bound.
+ *
+ * The sweep interval stays 30 s and the lease TTL stays 30 s by default. Live
+ * reservations are not capped — capacity is admission's job, not the lease
+ * bookkeeping's. `expires_at` is NOT used to skip admission release: the
+ * admission counters protect the real limits and carry their own TTL
+ * (`INFLIGHT_TTL_SECONDS`); this map is local bookkeeping only.
  */
 export class ReservationManager {
   private leases = new Map<string, Reservation>();
+  private expiry = new ExpiryHeap();
   private lastSweepAt = 0;
   private static readonly SWEEP_INTERVAL_MS = 30_000;
 
+  constructor(private readonly now: () => number = Date.now) {}
+
   private sweepExpired(now: number): void {
     if (now - this.lastSweepAt < ReservationManager.SWEEP_INTERVAL_MS) return;
     this.lastSweepAt = now;
-    for (const [leaseId, reservation] of this.leases) {
-      if (reservation.expires_at < now) this.leases.delete(leaseId);
+    // Only expired heads are examined: once the head expires later than `now`,
+    // every remaining node does too, so the loop stops without touching them.
+    while (this.expiry.size > 0) {
+      const head = this.expiry.peek()!;
+      if (head.expiresAt >= now) break;
+      this.expiry.pop();
+      const lease = this.leases.get(head.leaseId);
+      // A released reservation is a harmless stale node: nothing to delete.
+      // (Lease identity is the unique lease id, so a reused id cannot alias —
+      // the id embeds acquisition time plus randomness.)
+      if (lease && lease.expires_at === head.expiresAt && lease.expires_at < now) {
+        this.leases.delete(head.leaseId);
+      }
+    }
+    // Periodic compaction of stale nodes (entries whose lease was released or
+    // re-keyed before expiry): rebuild the heap only when stale nodes make up
+    // the bulk of it, so the common all-live case pays nothing.
+    if (this.expiry.size > this.leases.size * 2) {
+      const live: ExpiryNode[] = [];
+      for (const [leaseId, lease] of this.leases) {
+        live.push({ expiresAt: lease.expires_at, leaseId });
+      }
+      this.expiry = new ExpiryHeap();
+      for (const node of live) this.expiry.insert(node);
     }
   }
 
   acquire(candidate: RouteCandidate, _revision: RoutingRevision, ttlMs = 30_000): Reservation {
-    const now = Date.now();
+    const now = this.now();
     this.sweepExpired(now);
     const lease_id = `${candidate.provider_id}:${candidate.model_id}:${now}:${Math.random().toString(16).slice(2)}`;
     const r: Reservation = {
@@ -29,17 +140,20 @@ export class ReservationManager {
       expires_at: now + ttlMs,
     };
     this.leases.set(lease_id, r);
+    this.expiry.insert({ expiresAt: r.expires_at, leaseId: lease_id });
     return r;
   }
 
   release(lease_id: string): void {
+    // The heap node stays until its expiry passes — the sweep treats it as
+    // stale and drops it. Cheaper than a heap search per release.
     this.leases.delete(lease_id);
   }
 
   get(lease_id: string): Reservation | undefined {
     const r = this.leases.get(lease_id);
     if (!r) return undefined;
-    if (r.expires_at < Date.now()) {
+    if (r.expires_at < this.now()) {
       this.leases.delete(lease_id);
       return undefined;
     }

package/src/transport/routing/round-robin.ts

@@ -1,5 +1,6 @@
 // Round-robin rotation state and its bounded per-key LRU.
 import type { RouteCandidate } from "./route-model";
+import { BoundedLruMap } from "./bounded-lru";
 
 export class RoundRobinState {
   private idx = 0;
@@ -22,29 +23,16 @@ export class RoundRobinState {
  * combinations would retain one entry forever. 1000 is far above the working
  * set of any real catalog, so eviction only ever targets genuinely cold keys.
  */
-const MAX_ROUND_ROBIN_ENTRIES = 1000;
+export const MAX_ROUND_ROBIN_ENTRIES = 1000;
 
 /**
- * Bounded LRU accessor for round-robin state: an existing key is refreshed to
- * the tail (most-recently-used), and inserting past the cap evicts the head
- * (least-recently-used). Keeps the hot routing working set while guaranteeing
- * the map cannot grow without bound.
+ * Creates the bounded LRU map the router keeps round-robin state in.
+ *
+ * The bound is the same 1000-entry cap the hand-rolled version enforced;
+ * `BoundedLruMap` is now the single implementation of that behavior, so the
+ * eviction rule (get refreshes recency, overflow evicts the LRU head) cannot
+ * drift between this cache and the capability-profile cache.
  */
-export function getOrCreateRoundRobin(
-  map: Map<string, RoundRobinState>,
-  key: string,
-): RoundRobinState {
-  const existing = map.get(key);
-  if (existing) {
-    map.delete(key);
-    map.set(key, existing);
-    return existing;
-  }
-  if (map.size >= MAX_ROUND_ROBIN_ENTRIES) {
-    const oldest = map.keys().next().value;
-    if (oldest !== undefined) map.delete(oldest);
-  }
-  const created = new RoundRobinState();
-  map.set(key, created);
-  return created;
+export function createRoundRobinMap(): BoundedLruMap<string, RoundRobinState> {
+  return new BoundedLruMap<string, RoundRobinState>(MAX_ROUND_ROBIN_ENTRIES);
 }

package/src/transport/routing/route-catalog.ts

@@ -30,6 +30,7 @@ import { DEFAULT_PROXY_SKIP_PROVIDER_IDS } from "../../providers/provider-metada
 import { buildClaudeCliUserAgent } from "../../providers/operations/custom-cli-headers";
 import { isBundledProviderId } from "../../providers/provider-contracts";
 import type { ServiceKind, WireFamily } from "../../protocol/canonical-model";
+import { BoundedLruMap } from "./bounded-lru";
 import { providerHasAdapterUserAgent, providerUsesBespokeWire } from "../../providers/provider-metadata";
 
 const CLAUDE_MODEL_FAMILIES = new Set(["opus", "sonnet", "haiku", "fable", "mythos"]);
@@ -156,17 +157,28 @@ export function buildCapabilityProfile(row: {
 }
 
 /**
- * The capability profile for one model row, memoized across rebuilds.
- *
- * Bounded LRU keyed by `providerId/modelId`: the value is a pure function of
- * the row's metadata, so two rebuilds that see the same row get the same object
- * instead of two identical ones. The bound keeps a long-lived process from
- * pinning one profile per row it has ever seen — a model deleted from the
- * catalog must not leave its profile behind forever.
+ * Upper bound on the capability-profile memo. Same value as the hand-rolled
+ * bound it replaces: far above any real catalog, so eviction only ever targets
+ * rows deleted from the catalog.
  */
 const CAPABILITY_PROFILE_CACHE_MAX_ENTRIES = 4096;
-const capabilityProfileCache = new Map<string, Record<string, boolean>>();
+const capabilityProfileCache = new BoundedLruMap<string, Record<string, boolean>>(
+  CAPABILITY_PROFILE_CACHE_MAX_ENTRIES,
+);
 
+/**
+ * The capability profile for one model row, memoized across rebuilds.
+ *
+ * The value is a pure function of the row's metadata, so two rebuilds that see
+ * the same row get the same object instead of two identical ones. The cache is
+ * a {@link BoundedLruMap} keyed by `providerId/modelId` **plus the row's
+ * modalities**: the key must change when the operator edits a row's modalities
+ * (text-only → vision), otherwise the rebuild would hand routing the stale
+ * pre-edit profile until the entry aged out of the LRU. A row that has never
+ * carried modality metadata keys with `null`, which only collides with another
+ * metadata-less row for the same provider/model — the same profile by
+ * construction.
+ */
 function capabilityProfileFor(row: {
   modalities: unknown;
   reasoning: boolean;
@@ -174,14 +186,10 @@ function capabilityProfileFor(row: {
   providerId: string;
   modelId: string;
 }): Record<string, boolean> {
-  const key = `${row.providerId}/${row.modelId}`;
+  const key = `${row.providerId}/${row.modelId}/${JSON.stringify(row.modalities ?? null)}`;
   const cached = capabilityProfileCache.get(key);
   if (cached !== undefined) return cached;
   const profile = buildCapabilityProfile(row);
-  if (capabilityProfileCache.size >= CAPABILITY_PROFILE_CACHE_MAX_ENTRIES) {
-    const oldest = capabilityProfileCache.keys().next().value;
-    if (oldest !== undefined) capabilityProfileCache.delete(oldest);
-  }
   capabilityProfileCache.set(key, profile);
   return profile;
 }
@@ -421,10 +429,14 @@ class RouteCatalogRepository {
      * preference's own doc.
      */
     const cooldownOverrideTenants = new Set<string>();
+    const invokeDisabledTenants = new Set<string>();
     for (const row of settingsRows ?? []) {
       if (row.preferences?.forceDisableCooldown === true && row.tenantId) {
         cooldownOverrideTenants.add(row.tenantId);
       }
+      if (row.preferences?.invokeDisabled === true && row.tenantId) {
+        invokeDisabledTenants.add(row.tenantId);
+      }
     }
     /**
      * A shared account has no tenant of its own (`tenant_id IS NULL`), so a
@@ -843,6 +855,7 @@ class RouteCatalogRepository {
       combos,
       ...(routingMap ? { providerRouting: routingMap } : {}),
       ...(Object.keys(poolRouting).length > 0 ? { poolRouting } : {}),
+      ...(invokeDisabledTenants.size > 0 ? { invokeDisabledTenants } : {}),
     };
   }
 }

package/src/transport/routing/route-model.ts

@@ -199,6 +199,15 @@ export interface RouteSnapshot {
   readonly providerRouting?: ProviderRoutingMap;
   /** Optional per-tenant pool selection strategy (absent = `least_loaded`). */
   readonly poolRouting?: Readonly<Record<string, PoolRoutingSetting>>;
+  /**
+   * Tenants whose invoke switch is off, so `/v1/*` must be refused outright.
+   *
+   * Read from the cached snapshot rather than per request: it is a console
+   * preference write, and the snapshot is already invalidated when one lands, so
+   * the switch takes effect on the next request without adding a query to the
+   * proxy path.
+   */
+  readonly invokeDisabledTenants?: ReadonlySet<string>;
 }
 
 export type EligibilityReason =
@@ -247,8 +256,19 @@ export interface AdmissionDecision {
 export interface AdmissionController {
   admit(candidate: RouteCandidate): Promise<AdmissionDecision>;
   release(reservation: Reservation): Promise<void>;
-  /** Observable current counters by admission bucket (`provider:model[:account]`). */
-  snapshotAccountInflight?(): Promise<ReadonlyMap<string, number>> | ReadonlyMap<string, number>;
+  /**
+   * Current inflight counts for exactly the buckets the given candidates draw
+   * from, keyed by the unprefixed admission bucket (`provider:model[:account]`).
+   *
+   * Required, not optional: the previous fleet-wide
+   * `snapshotAccountInflight()` was the only reason `plan()` could issue a
+   * Redis `KEYS` on the request path. Scoped reads make the ordering cost
+   * proportional to the candidates being ordered, and an empty input must be
+   * answerable with zero backend commands.
+   */
+  readAccountInflight(
+    candidates: readonly RouteCandidate[],
+  ): Promise<ReadonlyMap<string, number>> | ReadonlyMap<string, number>;
 }
 
 /**

package/src/transport/routing/router.ts

@@ -25,24 +25,17 @@ import {
 import { planAllowsCandidate } from "./plan-gate";
 import { InMemoryAdmissionController, admissionKey } from "./admission";
 import { ReservationManager } from "./reservations";
-import { getOrCreateRoundRobin, RoundRobinState } from "./round-robin";
+import { createRoundRobinMap, RoundRobinState } from "./round-robin";
+import {
+  lookupRouteCandidates,
+  parseModelReference,
+  routeCandidateIndex,
+} from "./candidate-index";
 import { totalRemainingCredit, totalRemainingPercent, type ProviderQuotaWindow } from "../../providers/quota/quota-contracts";
 import { getCachedQuotaEntry, quotaLens } from "../../console/quota/cache";
 import type { RedisClient } from "../../persistence/redis";
 import { sharedClaudeSlowLanes } from "../../providers/integrations/claude/claude-slow-lane";
 
-function parseModel(model: string): { providerId: string | null; bare: string } {
-  const slash = model.indexOf("/");
-  if (slash === -1) return { providerId: null, bare: model };
-  return { providerId: model.slice(0, slash), bare: model.slice(slash + 1) };
-}
-
-function candidateMatches(candidate: RouteCandidate, model: string): boolean {
-  const parsed = parseModel(model);
-  if (parsed.providerId === null) return candidate.model_id === parsed.bare;
-  return candidate.model_id === parsed.bare && candidate.provider_id === parsed.providerId;
-}
-
 /**
  * True when the account's remaining allowance is at or below its provider's
  * floor. Credit mode sums the absolute remaining credit; percent mode uses the
@@ -352,8 +345,8 @@ export class EligibilityEvaluator {
 }
 
 export class RoutingEngine {
-  private readonly _roundRobinByCombo = new Map<string, RoundRobinState>();
-  private readonly _roundRobinByProvider = new Map<string, RoundRobinState>();
+  private readonly _roundRobinByCombo = createRoundRobinMap();
+  private readonly _roundRobinByProvider = createRoundRobinMap();
   private readonly eligibility = new EligibilityEvaluator();
   private readonly reservations = new ReservationManager();
 
@@ -363,11 +356,19 @@ export class RoutingEngine {
   ) {}
 
   private getRoundRobin(key: string): RoundRobinState {
-    return getOrCreateRoundRobin(this._roundRobinByCombo, key);
+    const existing = this._roundRobinByCombo.get(key);
+    if (existing) return existing;
+    const created = new RoundRobinState();
+    this._roundRobinByCombo.set(key, created);
+    return created;
   }
 
   private getProviderRoundRobin(key: string): RoundRobinState {
-    return getOrCreateRoundRobin(this._roundRobinByProvider, key);
+    const existing = this._roundRobinByProvider.get(key);
+    if (existing) return existing;
+    const created = new RoundRobinState();
+    this._roundRobinByProvider.set(key, created);
+    return created;
   }
 
   /** Observable bounded-collection sizes for the runtime metrics sampler. */
@@ -375,11 +376,20 @@ export class RoutingEngine {
     return { combo: this._roundRobinByCombo.size, provider: this._roundRobinByProvider.size };
   }
 
-  /** Live admission counters by `provider:model[:account]` bucket. */
-  async accountInflightSnapshot(): Promise<ReadonlyMap<string, number>> {
-    // Both controllers hand back a fresh map, so no defensive copy here —
-    // this feeds an admin read, not a mutation site.
-    return (await this.admission.snapshotAccountInflight?.()) ?? new Map();
+  /**
+   * Live admission counters for the buckets the given candidates draw from.
+   *
+   * Takes candidates rather than returning a fleet-wide snapshot: the scoped
+   * read is what keeps `plan()` off Redis `KEYS` (the fleet-wide read had no
+   * other implementation) and bounds the console's per-provider read to the
+   * accounts it will actually report on. Both controllers hand back a fresh
+   * map, so no defensive copy here — this feeds an admin read, not a mutation
+   * site.
+   */
+  async accountInflightSnapshot(
+    candidates: readonly RouteCandidate[],
+  ): Promise<ReadonlyMap<string, number>> {
+    return this.admission.readAccountInflight(candidates);
   }
 
   /**
@@ -402,7 +412,12 @@ export class RoutingEngine {
       (candidate) => typeof candidate.max_inflight === "number" && candidate.max_inflight > 0,
     );
     if (bounded.length === 0) return new Set();
-    const snapshot = await this.accountInflightSnapshot().catch(() => new Map<string, number>());
+    // Only the bounded candidates can be saturated, so only their buckets are
+    // read. A failed ordering read must never fail routing — the admission
+    // attempt itself is the real gate; this read only optimizes attempt order.
+    const snapshot = await this.accountInflightSnapshot(bounded).catch(
+      () => new Map<string, number>(),
+    );
     if (snapshot.size === 0) return new Set();
     const saturated = new Set<RouteCandidate>();
     for (const candidate of bounded) {
@@ -792,16 +807,23 @@ export class RoutingEngine {
       ? combo.members.flatMap((name) => expandMember(name, new Set([resolved.model])))
       : [resolved.model];
     const modelIds = [...new Set(rawModelIds)];
-    let matching = snapshot.candidates.filter(
-      (candidate) =>
-        modelIds.some((id) => candidateMatches(candidate, id)) &&
-        (candidate.tenant_id == null || candidate.tenant_id === tid),
-    );
+    // One index build per snapshot (cached on the immutable snapshot), one
+    // lookup per unique resolved model. The previous shape rescanned every
+    // candidate per model — O(C×K) string parses per plan — which was the
+    // quadratic cost the catalog rebuild had already paid once and the request
+    // path was paying again on every plan.
+    const index = routeCandidateIndex(snapshot);
+    const parsedModels = modelIds.map((id) => ({ id, parsed: parseModelReference(id) }));
+    let matching = parsedModels.flatMap((entry) => lookupRouteCandidates(index, entry.parsed, tid));
+    // Preserve the resolver's flatten-then-dedupe contract: one candidate can
+    // serve two member groups only via a combo listing the same model twice,
+    // and the plan must not dial it twice.
+    matching = [...new Set(matching)];
     let unmatchedMembers: readonly string[] = [];
     if (combo) {
-      const perId = modelIds.map((id) => ({
-        id,
-        group: matching.filter((c) => candidateMatches(c, id)),
+      const perId = parsedModels.map((entry) => ({
+        id: entry.id,
+        group: lookupRouteCandidates(index, entry.parsed, tid),
       }));
       unmatchedMembers = perId.filter((entry) => entry.group.length === 0).map((entry) => entry.id);
       const groups = perId.map((entry) => entry.group).filter((g) => g.length > 0);

package/src/transport/surface/chat/encode.ts

@@ -1,6 +1,7 @@
 import type { CanonicalEvent, CanonicalStopReason } from "../../../protocol/canonical-model";
 import { jsonrepair } from "jsonrepair";
 import { reasoningSummaryIdentity, reasoningSummarySeparator, type ReasoningSummaryIdentity } from "../reasoning-summary";
+import { reasoningTextOf } from "../../../protocol/reasoning-text";
 import { eventText } from "../adapters";
 import { isRecord } from "../../../protocol/codecs";
 import {
@@ -113,9 +114,7 @@ export function eventAudio(event: CanonicalEvent): Record<string, unknown> | und
 
 export function eventReasoningText(event: CanonicalEvent): string | undefined {
   if (event.type !== "content_delta" || event.content.kind !== "reasoning") return undefined;
-  if (event.content.opaque === true) return undefined;
-  if (typeof event.content.payload === "string") return event.content.payload;
-  return typeof event.content.summary === "string" ? event.content.summary : undefined;
+  return reasoningTextOf(event.content);
 }
 
 function mergedReasoningText(events: readonly CanonicalEvent[]): string {

package/src/transport/surface/chat/parse.ts

@@ -1,6 +1,7 @@
 import type { CanonicalMessage, ContentPart, GenerationControls } from "../../../protocol/canonical-model";
 import type { SurfaceInput } from "../adapters";
 import { isRecord } from "../../../protocol/codecs";
+import { asNumber } from "../../../shared/coerce";
 import { textPart, normalizeInlineFile } from "../content-parts";
 import { SERVICE_TIERS } from "../dialects";
 import { readNumber, readString } from "../../../protocol/codecs";
@@ -75,7 +76,7 @@ export function requestBody(input: unknown): unknown {
 }
 
 export function nonNegativeNumber(value: unknown): number | undefined {
-  const number = typeof value === "number" && Number.isFinite(value) ? value : undefined;
+  const number = asNumber(value);
   return number !== undefined && number >= 0 ? number : undefined;
 }
 

package/src/transport/surface/dialects.ts

@@ -71,11 +71,14 @@ function parseToolObject(item: Record<string, unknown>, dialect: ToolDialect): T
     } else {
       const functionValue = item["function"];
       schema = isRecord(functionValue)
-        ? functionValue["parameters"] ?? functionValue["jsonSchema"] ?? {}
+        ? functionValue["parameters"] ??
+          functionValue["jsonSchema"] ??
+          functionValue["parametersJsonSchema"] ??
+          {}
         : // The Responses flat spelling (`{type:"function", parameters:…}`) is
           // common here too; without this a tool arrived with an empty schema
           // and the upstream rejected it.
-          item["parameters"] ?? item["input_schema"] ?? {};
+          item["parameters"] ?? item["input_schema"] ?? item["parametersJsonSchema"] ?? {};
     }
   } else if (dialect === "responses") {
     // A Responses caller may still send the Chat-shaped envelope — the two
@@ -88,8 +91,13 @@ function parseToolObject(item: Record<string, unknown>, dialect: ToolDialect): T
     schema =
       item["input_schema"] ??
       item["parameters"] ??
+      item["parametersJsonSchema"] ??
       (wrapped !== undefined
-        ? wrapped["parameters"] ?? wrapped["input_schema"] ?? wrapped["jsonSchema"] ?? {}
+        ? wrapped["parameters"] ??
+          wrapped["input_schema"] ??
+          wrapped["jsonSchema"] ??
+          wrapped["parametersJsonSchema"] ??
+          {}
         : item);
   } else {
     schema = item["input_schema"] ?? item["inputSchema"] ?? {};

package/src/transport/surface/messages/encode.ts

@@ -1,6 +1,7 @@
 import type { CanonicalEvent, CanonicalStopReason, ContentPart, UsageRecord } from "../../../protocol/canonical-model";
 import { assertBoundedJsonDepth, isRecord } from "../../../protocol/codecs";
 import { messagesStopReason } from "../../../protocol/stop-reason";
+import { reasoningTextOf } from "../../../protocol/reasoning-text";
 import {
   reasoningSummaryHasBoundary,
   reasoningSummaryIdentity,
@@ -111,7 +112,7 @@ export function blockFromPart(part: ContentPart): MessagesWireObject | undefined
           : { type: "redacted_thinking", data: part.payload };
       return {
         type: "thinking",
-        thinking: part.summary ?? (typeof part.payload === "string" ? part.payload : ""),
+        thinking: reasoningTextOf(part) ?? "",
         ...(part.signature === undefined ? {} : { signature: part.signature }),
       };
     }

package/src/transport/surface/messages/parse.ts

@@ -145,8 +145,10 @@ export function parseBlock(value: unknown): ContentPart {
     const thinking = stringValue(value.thinking) ? value.thinking : "";
     return {
       kind: "reasoning",
+      // Readable thinking lives in `payload` only. Duplicating it into
+      // `summary` too emitted the same text twice on surfaces that carry both
+      // channels (Responses `reasoning_text` + `reasoning_summary_text`).
       payload: thinking,
-      summary: thinking,
       ...(stringValue(value.signature) ? { signature: value.signature } : {}),
     };
   }