cartethyia 2.4.6 → 2.5.1

package/src/transport/dispatch/generation.ts

@@ -52,6 +52,37 @@ export interface GenerationHandlerDeps {
 /** Which surface a handler serves. Drives candidate filtering and error copy. */
 export type GenerationKind = Extract<ServiceKind, "imageGeneration" | "videoGeneration">;
 
+/**
+ * Surfaces the gateway routes but does not model.
+ *
+ * Embeddings and audio have no adapter method and no media shape — there is
+ * nothing for this repo to translate — so they exist purely so a caller can
+ * reach a compatible upstream through the normal pipeline. Opening the route
+ * is the whole feature: routing, admission, failover, and accounting still
+ * apply, and the upstream's own bytes come back untouched.
+ */
+export type PassthroughKind = Extract<ServiceKind, "embedding" | "audioTranscription" | "audioSpeech">;
+
+/** Error-copy noun per surface, so a refusal names what the caller asked for. */
+const SURFACE_NOUNS: Record<GenerationKind | PassthroughKind, string> = {
+  imageGeneration: "image",
+  videoGeneration: "video",
+  embedding: "embedding",
+  audioTranscription: "transcription",
+  audioSpeech: "speech",
+};
+
+/**
+ * Only the two media surfaces carry `prompt`/`n`.
+ *
+ * An embedding body is `{model, input}` and a transcription is multipart —
+ * neither has a prompt, so validating one here would reject every legitimate
+ * request to a surface the gateway just opened.
+ */
+function isMediaKind(kind: GenerationKind | PassthroughKind): kind is GenerationKind {
+  return kind === "imageGeneration" || kind === "videoGeneration";
+}
+
 /**
  * Maximum items one request may ask for.
  *
@@ -126,7 +157,15 @@ async function passThrough(
 
 /** Builds the handler for one generation surface. */
 export function createGenerationHandler(kind: GenerationKind, deps: GenerationHandlerDeps) {
-  const noun = kind === "videoGeneration" ? "video" : "image";
+  return createNativeSurfaceHandler(kind, deps);
+}
+
+/** Builds the handler for one routed surface, media or passthrough. */
+export function createNativeSurfaceHandler(
+  kind: GenerationKind | PassthroughKind,
+  deps: GenerationHandlerDeps,
+) {
+  const noun = SURFACE_NOUNS[kind];
   return async ({ request }: { request: Request }): Promise<Response> => {
     const state = deps.stateStore.require(request);
     const authorization = state.authorization;
@@ -151,19 +190,21 @@ export function createGenerationHandler(kind: GenerationKind, deps: GenerationHa
     }
     // Trust boundary only. Keep accepting `messages` for chat-backed providers
     // while native image/video endpoints can use the simpler `prompt` field.
-    const hasPrompt = typeof generation.prompt === "string" && generation.prompt.trim().length > 0;
-    const hasMessages = Array.isArray(generation.messages) && generation.messages.length > 0;
-    if (!hasPrompt && !hasMessages) {
-      throw new GatewayError("invalid_request", 400, "prompt is required");
-    }
-    if (generation.n !== undefined) {
-      const n = generation.n;
-      if (typeof n !== "number" || !Number.isInteger(n) || n < 1 || n > MAX_ITEMS_PER_REQUEST) {
-        throw new GatewayError(
-          "invalid_request",
-          400,
-          `n must be an integer between 1 and ${MAX_ITEMS_PER_REQUEST}`,
-        );
+    if (isMediaKind(kind)) {
+      const hasPrompt = typeof generation.prompt === "string" && generation.prompt.trim().length > 0;
+      const hasMessages = Array.isArray(generation.messages) && generation.messages.length > 0;
+      if (!hasPrompt && !hasMessages) {
+        throw new GatewayError("invalid_request", 400, "prompt is required");
+      }
+      if (generation.n !== undefined) {
+        const n = generation.n;
+        if (typeof n !== "number" || !Number.isInteger(n) || n < 1 || n > MAX_ITEMS_PER_REQUEST) {
+          throw new GatewayError(
+            "invalid_request",
+            400,
+            `n must be an integer between 1 and ${MAX_ITEMS_PER_REQUEST}`,
+          );
+        }
       }
     }
 
@@ -293,14 +334,20 @@ export function createGenerationHandler(kind: GenerationKind, deps: GenerationHa
         // body to the candidate's endpoint through the adapter, which owns the
         // upstream base URL. Either way the gateway does not interpret the
         // media — it returns what the upstream produced.
+        //
+        // A passthrough surface has no media method to prefer: the whole point
+        // is that this repo does not model it, so it goes straight to the
+        // adapter's native dispatch, which is plain forwarding.
         const media =
-          kind === "videoGeneration"
-            ? typeof adapter.generateVideo === "function"
-              ? adapter.generateVideo(upstreamBody, target, mediaContext).then((outcome) => finish(outcome))
-              : undefined
-            : typeof adapter.generateImage === "function"
-              ? adapter.generateImage(upstreamBody, target, mediaContext).then((outcome) => finish(outcome))
-              : undefined;
+          !isMediaKind(kind)
+            ? undefined
+            : kind === "videoGeneration"
+              ? typeof adapter.generateVideo === "function"
+                ? adapter.generateVideo(upstreamBody, target, mediaContext).then((outcome) => finish(outcome))
+                : undefined
+              : typeof adapter.generateImage === "function"
+                ? adapter.generateImage(upstreamBody, target, mediaContext).then((outcome) => finish(outcome))
+                : undefined;
         const upstream =
           media !== undefined
             ? await media
@@ -348,3 +395,23 @@ export function createImageGenerationHandler(deps: GenerationHandlerDeps) {
 export function createVideoGenerationHandler(deps: GenerationHandlerDeps) {
   return createGenerationHandler("videoGeneration", deps);
 }
+
+/**
+ * `POST /v1/embeddings`.
+ *
+ * Routed with no provider implementation behind it: a model row carrying the
+ * `embedding` kind is enough, and the adapter forwards the body as-is.
+ */
+export function createEmbeddingHandler(deps: GenerationHandlerDeps) {
+  return createNativeSurfaceHandler("embedding", deps);
+}
+
+/** `POST /v1/audio/transcriptions`. Same passthrough shape as embeddings. */
+export function createAudioTranscriptionHandler(deps: GenerationHandlerDeps) {
+  return createNativeSurfaceHandler("audioTranscription", deps);
+}
+
+/** `POST /v1/audio/speech`. Same passthrough shape as embeddings. */
+export function createAudioSpeechHandler(deps: GenerationHandlerDeps) {
+  return createNativeSurfaceHandler("audioSpeech", deps);
+}

package/src/transport/dispatch/leases.ts

@@ -14,6 +14,63 @@ export interface AttemptLeases {
   readonly reservation: Reservation;
   readonly proxySlot?: { poolId: string; release: () => void };
   readonly networkPoolId?: string;
+  /**
+   * Ownership of this attempt's account/network-pool release.
+   *
+   * A provider session that outlives the HTTP request — Cursor's Run, held open
+   * for the client's next tool-result request — takes the release over instead
+   * of having the request release it when the response is flushed. Request-scoped
+   * accounting (admission, per-request telemetry) still settles per request;
+   * only the *slot and pool inflight* move to the session's lifetime.
+   */
+  readonly ownership?: AttemptLeaseOwnership;
+}
+
+/**
+ * Request-scoped accounting versus session-scoped ownership.
+ *
+ * One HTTP request = one admission lease, one reservation, one pool slot. One
+ * Cursor Run = one upstream turn that can span several HTTP requests, and it
+ * must keep the slot for the whole turn. Transferring ownership is the only way
+ * to satisfy both: the request settles its own accounting and stops owning the
+ * release; the session owns it until the Run terminates.
+ *
+ * Idempotent by construction — the release is handed over at most once, and a
+ * second transfer attempt gets `undefined` so nothing is released twice.
+ */
+export class AttemptLeaseOwnership {
+  #transferred = false;
+
+  constructor(private readonly release: () => void) {}
+
+  /**
+   * Hands the release to a provider session. Returns the release to call
+   * exactly once when the session terminates, or `undefined` when this attempt
+   * already transferred it (or released it itself).
+   */
+  transferToProviderSession(): (() => void) | undefined {
+    if (this.#transferred) return undefined;
+    this.#transferred = true;
+    const release = this.release;
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      release();
+    };
+  }
+
+  /**
+   * Releases only when ownership was never transferred — the ordinary
+   * end-of-request path. Returns false when a session owns it, so the caller
+   * can see that the slot outlives this request.
+   */
+  releaseByResponse(): boolean {
+    if (this.#transferred) return false;
+    this.#transferred = true;
+    this.release();
+    return true;
+  }
 }
 
 export interface AttemptLeaseSource {
@@ -23,6 +80,21 @@ export interface AttemptLeaseSource {
   readonly estimatedInputTokens: number;
   readonly estimatedOutputTokens: number;
   readonly authorizationSnapshot: ApiKeyAuthorizationSnapshot;
+  /**
+   * True when this request continues a provider session the gateway already
+   * holds, so its account and network-pool slot are already occupied by that
+   * session.
+   *
+   * A Cursor tool-result request borrows the held Run: it talks to the socket
+   * that is already open and does not open another connection. Acquiring a
+   * second pool slot would charge one logical upstream turn two concurrency
+   * slots — and, with a pool at its limit, would make the continuation fail
+   * with `proxy_pool_capacity_exceeded` for a turn that is already inside it.
+   *
+   * Admission (API-key authorization) and the routing reservation still run:
+   * per-request accounting is per request.
+   */
+  readonly borrowsHeldSession?: boolean;
 }
 
 async function acquirePoolSlot(
@@ -196,7 +268,10 @@ export async function acquireAttemptLeases(
     // address per request, so storing it here would only pin a stale answer.
     if (input.networkBindingFactory && input.host)
       await input.networkBindingFactory.resolve(input.host.hostname, input.signal, input.host.port);
-    const slot = await acquirePoolSlot(candidate, source, input.poolSelector, input.strictPoolSelection);
+    // A continuation borrows the session's slot; see `borrowsHeldSession`.
+    const slot = source.borrowsHeldSession === true
+      ? undefined
+      : await acquirePoolSlot(candidate, source, input.poolSelector, input.strictPoolSelection);
     if (slot) partial.proxySlot = slot;
     if (input.strictPoolSelection && input.signal.aborted)
       throw new GatewayError("transport_closed", 499, "request was cancelled");
@@ -209,6 +284,14 @@ export async function acquireAttemptLeases(
       reservation: partial.reservation,
       ...(partial.proxySlot ? { proxySlot: partial.proxySlot } : {}),
       ...(partial.proxySlot ? { networkPoolId: partial.proxySlot.poolId } : {}),
+      // The pool slot is the one resource a provider session can outlive, so it
+      // is the one wrapped in a transferable owner. The admission lease and the
+      // routing reservation stay request-scoped: the account's concurrency slot
+      // is held for the Run's duration, while per-request usage settles per
+      // request.
+      ...(partial.proxySlot
+        ? { ownership: new AttemptLeaseOwnership(partial.proxySlot.release) }
+        : {}),
     };
   } catch (error) {
     await releaseAttemptLeases(partial, source.routingEngine);
@@ -221,14 +304,28 @@ export async function releaseAttemptLeases(
     readonly lease?: AdmissionLease | undefined;
     readonly reservation?: Reservation | undefined;
     readonly proxySlot?: { release: () => void } | undefined;
+    /**
+     * When present, the pool slot's release is owned rather than called
+     * directly: `releaseByResponse()` releases only if a provider session did
+     * not take it over. A slot a live Cursor Run is holding must not be freed
+     * at response time — the Run's next request needs it, and releasing early
+     * is what lets another tenant's request occupy a slot that is still in use.
+     */
+    readonly ownership?: AttemptLeaseOwnership | undefined;
   },
   routingEngine: Pick<RoutingEngine, "release">,
 ): Promise<void> {
   // Every release runs inside the settled set: a throwing pool-slot release
   // must not skip the admission lease or routing reservation (slot + inflight
   // leak). Sync release is wrapped so it participates in the same guarantee.
+  // When ownership exists it supersedes the raw slot release: calling both
+  // would release twice, and `releaseByResponse` is the single-shot gate.
   await Promise.allSettled([
-    ...(leases.proxySlot ? [Promise.resolve().then(() => leases.proxySlot?.release())] : []),
+    ...(leases.ownership
+      ? [Promise.resolve().then(() => leases.ownership?.releaseByResponse())]
+      : leases.proxySlot
+        ? [Promise.resolve().then(() => leases.proxySlot?.release())]
+        : []),
     ...(leases.lease ? [leases.lease.release()] : []),
     ...(leases.reservation ? [routingEngine.release(leases.reservation)] : []),
   ]);

package/src/transport/dispatch/proxy-request.ts

@@ -28,12 +28,14 @@ import {
   completionContext,
   estimatedUsage,
   parseCapturedBody,
-  shouldCaptureProviderBody,
+  shouldCaptureProviderBodyForRequest,
   terminalFailure,
 } from "./attempt-finalize";
 import { runAttemptLoop } from "./attempt-loop";
 import { projectForRoute, routeCapabilitiesFor } from "../translation/capabilities";
 import { dispatchStreamingAttempt } from "./streaming/stream";
+import type { ProviderContinuationScope } from "../../providers/provider-contracts";
+import type { PreparedProxyRequest } from "../request/preparer";
 
 export interface ProviderProxyHandlerDeps {
   readonly db: CartethyiaDatabase;
@@ -52,6 +54,24 @@ export interface ProviderProxyHandlerDeps {
   readonly oauthRefreshService?: OAuthRefreshService;
 }
 
+/**
+ * The continuation scope one dispatch carries.
+ *
+ * Present only for a route that has an account: a provider session held across
+ * requests is authorized by tenant + API key + provider + account, and a route
+ * with no account cannot be scoped — so it must not hold a session open at all.
+ */
+function continuationScopeFor(prepared: PreparedProxyRequest): ProviderContinuationScope | undefined {
+  const accountId = prepared.candidate.provider_account_id;
+  if (accountId === undefined) return undefined;
+  return {
+    tenantId: prepared.authorization.tenantId,
+    apiKeyId: prepared.authorization.id,
+    providerId: prepared.candidate.provider_id,
+    providerAccountId: accountId,
+  };
+}
+
 /**
  * First-token latency for one attempt, in the spread shape `completeAttempt`
  * takes: `{}` when there is nothing to measure — no first byte arrived (a
@@ -127,6 +147,9 @@ export async function handleProviderProxyRequest(
       estimatedInputTokens: prepared.estimatedInputTokens,
       estimatedOutputTokens: prepared.estimatedOutputTokens,
       authorizationSnapshot: prepared.authorization.snapshot,
+      // A continuation borrows the held Cursor Run: one upstream turn must not
+      // occupy two account/pool concurrency slots.
+      ...(prepared.continuationAffinity === undefined ? {} : { borrowsHeldSession: true }),
     },
     candidates: attemptCandidates,
     tenantId: prepared.authorization.tenantId,
@@ -175,6 +198,8 @@ export async function handleProviderProxyRequest(
       const lease = context.leases.lease;
       const reservation = context.leases.reservation;
       const proxySlot = context.leases.proxySlot;
+      const leaseOwnership = context.leases.ownership;
+      const continuationScope = continuationScopeFor(prepared);
       const providerRouteCandidate = {
         provider_id: candidate.provider_id,
         model_id: candidate.model_id,
@@ -209,13 +234,35 @@ export async function handleProviderProxyRequest(
                   prepared.authorization.snapshot.tenant_id,
                 ),
                 providerCapture,
-                await shouldCaptureProviderBody(deps.db, prepared.authorization.snapshot.tenant_id),
+                await shouldCaptureProviderBodyForRequest(
+                  deps.db,
+                  prepared.authorization.snapshot.tenant_id,
+                  state,
+                ),
+              ),
+            }
+          : {}),
+        ...(deps.networkBindingFactory
+          ? {
+              outboundAttachmentFetch: deps.networkBindingFactory.fetch(
+                networkPoolId,
+                prepared.authorization.snapshot.tenant_id,
               ),
             }
           : {}),
         ...(deps.networkBindingFactory
           ? { outboundWebSocket: deps.networkBindingFactory.webSocket(networkPoolId, prepared.authorization.snapshot.tenant_id) }
           : {}),
+        ...(deps.networkBindingFactory
+          ? {
+              outboundHttp2: deps.networkBindingFactory.http2Bidi(
+                networkPoolId,
+                prepared.authorization.snapshot.tenant_id,
+              ),
+            }
+          : {}),
+        ...(leaseOwnership === undefined ? {} : { leaseOwnership }),
+        ...(continuationScope === undefined ? {} : { continuationScope }),
       });
       if (dispatchRequest.stream) {
         return dispatchStreamingAttempt({
@@ -237,6 +284,8 @@ export async function handleProviderProxyRequest(
           providerCapture,
           retainLeases: context.retainLeases,
           ttfbFields,
+          ...(leaseOwnership === undefined ? {} : { leaseOwnership }),
+          ...(continuationScope === undefined ? {} : { continuationScope }),
         });
       }
       // Pool slot ownership belongs to the candidate attempt: the slot was
@@ -269,6 +318,11 @@ export async function handleProviderProxyRequest(
       if (terminal === undefined) throw terminalFailure(undefined);
       const terminalError = terminalFailure(terminal);
       if (terminalError !== undefined) throw terminalError;
+      // An interim `tool_use` terminal defers usage: the provider's turn is not
+      // over, so its authoritative usage arrives with the *next* request that
+      // continues the same upstream turn. Charging an estimate here would bill
+      // the turn twice — the estimate now and the real usage later.
+      const deferredUsage = terminal.usage_deferred === true;
       const usage =
         terminal.usage ??
         estimatedUsage(prepared.estimatedInputTokens, prepared.estimatedOutputTokens);
@@ -316,7 +370,10 @@ export async function handleProviderProxyRequest(
           return reported === undefined ? {} : { reportedModel: reported };
         })(),
         usage: pricedUsage,
-        commitUsage: pricedUsage,
+        // Deferred: the request consumed upstream resources (it is mid-turn), so
+        // the *recorded* usage stays for the row, but nothing is committed —
+        // the Run's own `turn_ended` commits once, on the final response.
+        ...(deferredUsage ? {} : { commitUsage: pricedUsage }),
         // Decode once: `output.bytes` is a `Uint8Array`, which
         // `parseCapturedBody` returns untouched — the Server panel would store
         // a byte-index map (`{"0":123,…}`) after redaction instead of the

package/src/transport/dispatch/streaming/finalize.ts

@@ -26,6 +26,7 @@ import { metrics } from "../../../observability/metrics";
 import { flagPoolBlocked, flagPoolCooldown } from "../../../network/pool-health";
 import { isFreeTierIpBlock, shouldCooldownPool } from "../retry-policy";
 import { releaseAttemptLeases } from "../leases";
+import type { AttemptLeaseOwnership } from "../leases";
 import { finalizeRequestTelemetry } from "../../guards/error-lifecycle";
 import { drainAbortReason } from "../../shutdown-notice";
 import {
@@ -69,6 +70,12 @@ export interface StreamFinalizeInput {
    * single pre-content Responses retry rebinds it mid-stream.
    */
   readonly getIterator: () => AsyncIterator<CanonicalEvent>;
+  /**
+   * Ownership of this attempt's account/network-pool release. A provider
+   * session that outlived this request already took it over, so
+   * `releaseByResponse()` is a no-op and the slot stays held for the session.
+   */
+  readonly leaseOwnership?: AttemptLeaseOwnership | undefined;
   /** First-token latency in the spread shape `completeAttempt` accepts. */
   readonly ttfbFields: (
     firstByteAt: number | undefined,
@@ -338,6 +345,9 @@ export class StreamFinalizer {
         lease,
         reservation,
         proxySlot,
+        ...(this.input.leaseOwnership === undefined
+          ? {}
+          : { ownership: this.input.leaseOwnership }),
       },
       prepared.routingEngine,
     );
@@ -392,6 +402,11 @@ export class StreamFinalizer {
         candidate.providerId,
         candidate.modelId,
       );
+      // A deferred terminal means the provider's turn is not over: the stream
+      // ended because the model asked for a tool the client must answer, and the
+      // authoritative usage arrives with the request that continues the same
+      // upstream turn. Committing an estimate here would bill that turn twice.
+      const deferredUsage = pipeline.terminal.usage_deferred === true;
       await completeAttempt(state, {
         status: upstreamTruncated ? "truncated" : "completed",
         ...this.streamCompletionContext(),
@@ -404,7 +419,7 @@ export class StreamFinalizer {
             }
           : {}),
         usage: finalUsage,
-        commitUsage: finalUsage,
+        ...(deferredUsage ? {} : { commitUsage: finalUsage }),
         responseBody: pipeline.telemetryEventTranscript,
         ...(pipeline.clientResponseText ? { clientResponseText: pipeline.clientResponseText } : {}),
         ...(pipeline.firstContentDeltaAtMs !== undefined ? { firstContentDeltaAtMs: pipeline.firstContentDeltaAtMs } : {}),

package/src/transport/dispatch/streaming/stream.ts

@@ -43,8 +43,10 @@ import type { AdmissionLease } from "../../../security/admission/contracts";
 import type { NetworkPoolSelector } from "../../../network/pool/selector";
 import type { TelemetryBatchBuffer } from "../../../observability/telemetry-buffer";
 import type { ProviderExchangeCapture } from "../attempt-finalize";
-import { captureProviderExchange, shouldCaptureProviderBody } from "../attempt-finalize";
+import { captureProviderExchange, shouldCaptureProviderBodyForRequest } from "../attempt-finalize";
 import { proxySuccessHeaders, buildUpstreamDispatchContext } from "../upstream";
+import type { AttemptLeaseOwnership } from "../leases";
+import type { ProviderContinuationScope } from "../../../providers/provider-contracts";
 import { resolveStreamFirstChunkTimeoutMs, resolveStreamStallTimeoutMs, resolveUpstreamTimeoutMs } from "../../../config/timeouts";
 import type { ProxyRequestState } from "../../request/state";
 import type { PreparedProxyRequest } from "../../request/preparer";
@@ -81,6 +83,10 @@ export interface StreamingDispatchInput {
   readonly proxySlot: { poolId: string; release: () => void } | undefined;
   readonly networkPoolId: string | undefined;
   readonly providerCapture: ProviderExchangeCapture;
+  /** Ownership of this attempt's account/network-pool release, when one was acquired. */
+  readonly leaseOwnership?: AttemptLeaseOwnership | undefined;
+  /** Caller identity authorizing a provider session held across requests. */
+  readonly continuationScope?: ProviderContinuationScope | undefined;
   /** Hands lease ownership to the returned `Response`'s async lifetime. */
   retainLeases: () => void;
   /** First-token latency in the spread shape `completeAttempt` accepts. */
@@ -151,6 +157,8 @@ export async function dispatchStreamingAttempt(input: StreamingDispatchInput): P
     providerCapture,
     retainLeases,
     ttfbFields,
+    leaseOwnership,
+    continuationScope,
   } = input;
 
   const outboundFetch = deps.networkBindingFactory?.fetch(
@@ -161,7 +169,7 @@ export async function dispatchStreamingAttempt(input: StreamingDispatchInput): P
     ? captureProviderExchange(
         outboundFetch,
         providerCapture,
-        await shouldCaptureProviderBody(deps.db, prepared.authorization.snapshot.tenant_id),
+        await shouldCaptureProviderBodyForRequest(deps.db, prepared.authorization.snapshot.tenant_id, state),
       )
     : undefined;
   const dispatchContext = buildUpstreamDispatchContext({
@@ -174,6 +182,7 @@ export async function dispatchStreamingAttempt(input: StreamingDispatchInput): P
     ...(conversationAffinity ? { conversationAffinity } : {}),
     ...(candidate.user_agent === undefined ? {} : { userAgent: candidate.user_agent }),
     ...(wrappedOutboundFetch ? { outboundFetch: wrappedOutboundFetch } : {}),
+    ...(outboundFetch ? { outboundAttachmentFetch: outboundFetch } : {}),
     ...(deps.networkBindingFactory
       ? {
           outboundWebSocket: deps.networkBindingFactory.webSocket(
@@ -182,6 +191,16 @@ export async function dispatchStreamingAttempt(input: StreamingDispatchInput): P
           ),
         }
       : {}),
+    ...(deps.networkBindingFactory
+      ? {
+          outboundHttp2: deps.networkBindingFactory.http2Bidi(
+            networkPoolId,
+            prepared.authorization.snapshot.tenant_id,
+          ),
+        }
+      : {}),
+    ...(leaseOwnership === undefined ? {} : { leaseOwnership }),
+    ...(continuationScope === undefined ? {} : { continuationScope }),
   });
   // `ProviderAdapter.dispatch` is declared to return a non-nullable
   // `AsyncIterable`, so an adapter that returned `undefined` would be a
@@ -248,6 +267,7 @@ export async function dispatchStreamingAttempt(input: StreamingDispatchInput): P
       providerCapture,
       getIterator: () => iterator,
       ttfbFields,
+      ...(leaseOwnership === undefined ? {} : { leaseOwnership }),
     },
     pipeline,
     {

package/src/transport/dispatch/upstream.ts

@@ -1,5 +1,6 @@
 import type { CanonicalEvent } from "../../protocol/canonical-model";
-import type { ValidatedOutboundFetch, ValidatedOutboundWebSocket } from "../../providers/provider-contracts";
+import type { AttemptLeaseOwnership, ValidatedOutboundFetch, ValidatedOutboundHttp2Bidi, ValidatedOutboundWebSocket } from "../../providers/provider-contracts";
+import type { ProviderContinuationScope } from "../../providers/provider-contracts";
 import { GATEWAY_SECURITY_HEADERS } from "../../security/outbound-headers";
 
 const FORWARDED_REQUEST_HEADERS = new Set([
@@ -41,7 +42,18 @@ export function buildUpstreamDispatchContext(input: {
   readonly requestId?: string;
   readonly userAgent?: string;
   readonly outboundFetch?: ValidatedOutboundFetch;
+  /** Validated attachment egress that must not be wrapped by provider payload capture. */
+  readonly outboundAttachmentFetch?: ValidatedOutboundFetch;
   readonly outboundWebSocket?: ValidatedOutboundWebSocket;
+  /** Validated bidirectional HTTP/2 egress bound to the same selected pool. */
+  readonly outboundHttp2?: ValidatedOutboundHttp2Bidi;
+  /**
+   * Ownership of this attempt's account/network-pool lease; a provider session
+   * that outlives the request takes it over.
+   */
+  readonly leaseOwnership?: AttemptLeaseOwnership;
+  /** Caller identity authorizing a provider session held across requests. */
+  readonly continuationScope?: ProviderContinuationScope;
   /** Stable per-conversation cache affinity (preferred over random ids). */
   readonly conversationAffinity?: string;
   /** Opaque identity shared by retries of one logical gateway request. */
@@ -74,7 +86,13 @@ export function buildUpstreamDispatchContext(input: {
     ...(userAgent ? { user_agent: userAgent } : {}),
     ...(Object.keys(input.headers).length > 0 ? { request_headers: input.headers } : {}),
     ...(outboundFetch ? { outbound_fetch: outboundFetch } : {}),
+    ...(input.outboundAttachmentFetch
+      ? { outbound_attachment_fetch: input.outboundAttachmentFetch }
+      : {}),
     ...(input.outboundWebSocket ? { outbound_websocket: input.outboundWebSocket } : {}),
+    ...(input.outboundHttp2 ? { outbound_http2: input.outboundHttp2 } : {}),
+    ...(input.leaseOwnership ? { lease_ownership: input.leaseOwnership } : {}),
+    ...(input.continuationScope ? { continuation_scope: input.continuationScope } : {}),
     ...(input.conversationAffinity ? { conversation_affinity: input.conversationAffinity } : {}),
     ...(input.requestIdentity ? { request_identity: input.requestIdentity } : {}),
   } as Record<string, unknown>;

package/src/transport/guards/auth-guard.ts

@@ -1,3 +1,4 @@
+import { log } from "../../observability/logger";
 // API-key authentication guard for `/v1/*`: token resolution, scope check,
 // client-router denylist, and the model-abuse ban gate.
 import { Elysia } from "elysia";
@@ -39,7 +40,31 @@ export function createApiKeyAuthenticationMiddleware(deps: {
       const pathname = fastPathname(request.url);
       if (!pathname.startsWith("/v1/")) return;
       const token = requestToken(request.headers);
-      const authorization = await resolveApiKeyAuthorization(deps.db, token);
+      // A database failure here is not "the key is bad". Left to propagate it
+      // surfaced as a 500 whose log line carried the whole statement and its
+      // bound parameters — including the key hash — once per request. Under an
+      // overloaded database that is a credential leak written at request rate.
+      //
+      // It is also the wrong answer: the caller cannot fix it by sending a
+      // different key, so it is a capacity signal, not an auth one.
+      const authorization = await resolveApiKeyAuthorization(deps.db, token).catch((error: unknown) => {
+        // Only the error's identity is logged, never its message: a drizzle
+        // query error carries the full statement and its bound parameters, and
+        // on this path one of those parameters is the key hash.
+        // A sanitized stand-in, not the original: a drizzle query error's
+        // message is the statement plus its bound parameters, and one of those
+        // parameters is the key hash.
+        const safe = new Error("[redacted: credential-store query failed]");
+        safe.name = error instanceof Error ? error.name : "Error";
+        log.error("[auth] key lookup failed; treating as unavailable", safe);
+        throw new GatewayError(
+          "accounts_unavailable",
+          503,
+          "The gateway could not verify this API key because its credential store is unavailable. Retry shortly.",
+          {},
+          "cartethyia",
+        );
+      });
       if (!authorization)
         throw new GatewayError("invalid_request", 401, "This API key is unknown, revoked, or expired. Issue a new key and send it as: Authorization: Bearer <key>.");
       const decision = createAccessDecision({

package/src/transport/guards/body-policy.ts

@@ -17,10 +17,11 @@ export function isProxyRequest(request: Request): boolean {
  * This list must mirror the routes `app.ts` actually mounts. It drives
  * body-read policy — a JSON route rejects a missing or non-JSON content-type
  * with 415, while an unrouted path is not read at all — so an entry with no
- * handler behind it describes a route the gateway does not serve. Two such
- * entries (`/v1/embeddings`, `/v1/audio/speech`) sit outside this list: they
- * advertise a surface that 404s, and the route-table test pins them absent so
- * re-adding one is a deliberate act.
+ * handler behind it describes a route the gateway does not serve. Three such
+ * entries (`/v1/embeddings`, `/v1/audio/transcriptions`, `/v1/audio/speech`)
+ * were listed for a while with nothing mounted — they advertised a surface
+ * that 404d — and the route-table test pinned them absent so re-adding one was
+ * a deliberate act. They are mounted now, as passthrough surfaces.
  *
  * The native service routes (`NATIVE_SERVICE_PATHS` — System One, web search,
  * image and video generation) are included: they read a JSON body through the