cartethyia 2.4.6 → 2.5.0

package/src/providers/operations/client-versions.ts

@@ -25,11 +25,65 @@ async function qoderVersion(response: Response): Promise<string | null> {
   }
 }
 
+/**
+ * Newest Trae IDE version from the official changelog.
+ *
+ * Trae publishes no npm package and no release API, so the changelog is the
+ * only machine-readable source of the current client version. It matters
+ * upstream: intl `llm_raw_chat` answers `4015` unless the request carries the
+ * *current* client version, so a stale pin is an outage, not a cosmetic drift.
+ *
+ * The page embeds its content as JSON, and its newest entry is the first dated
+ * heading — not the highest semver, because this vendor's hotfix line numbers
+ * past its feature line (3.5.104 shipped after 3.5.97). Taking `max(semver)`
+ * would report an old build as current, so this walks the document in order and
+ * returns the first version following a dated release heading.
+ */
+async function traeVersion(response: Response): Promise<string | null> {
+  try {
+    const text = await response.text();
+    const heading =
+      /"insert":"((?:January|February|March|April|May|June|July|August|September|October|November|December)\s+\d{1,2},\s*\d{4}\s*\([^)]*\))\\n"/g;
+    for (const match of text.matchAll(heading)) {
+      const window = text.slice(match.index ?? 0, (match.index ?? 0) + 900);
+      const found = window.match(/TraeCode\s+v?(\d+\.\d+\.\d+)|v?(\d+\.\d+\.\d+)\s+is\s+released/i);
+      const version = found?.[1] ?? found?.[2];
+      if (version && isSemverish(version)) return version.trim();
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
 async function clineClientVersion(response: Response): Promise<string | null> {
   const data = (await response.json()) as { version?: unknown };
   return isSemverish(data.version) ? data.version.trim() : null;
 }
 
+/**
+ * Newest Cursor build from the official download API, as the IDE's own header
+ * spells it.
+ *
+ * Cursor's `x-cursor-client-version` is not the IDE semver on its own: the wire
+ * value is `cli-<version>-<sha7>` (observed live as `cli-2026.10.19-6bbf2c4`).
+ * The download API is the only source that returns both halves — `version` and
+ * `commitSha` — so they are joined here rather than guessed. A semver alone
+ * would be a different identity than the one the IDE sends.
+ */
+async function cursorVersion(response: Response): Promise<string | null> {
+  try {
+    const data = (await response.json()) as { version?: unknown; commitSha?: unknown };
+    const version = data.version;
+    if (!isSemverish(version)) return null;
+    const sha = typeof data.commitSha === "string" ? data.commitSha.trim() : "";
+    const short = sha.length >= 7 ? sha.slice(0, 7) : "";
+    return short.length > 0 ? `cli-${version.trim()}-${short}` : version.trim();
+  } catch {
+    return null;
+  }
+}
+
 async function clineSdkVersion(response: Response): Promise<string | null> {
   const data = (await response.json()) as {
     version?: unknown;
@@ -177,7 +231,7 @@ export const VERSION_SOURCES = {
   },
   qoder: {
     key: "qoder",
-    fallback: "1.1.73",
+    fallback: "1.1.74",
     sources: [
       {
         url: "https://registry.npmjs.org/@qoder-ai/qodercli/latest",
@@ -222,6 +276,11 @@ export const VERSION_SOURCES = {
     fallback: "0.0.95",
     sources: [{ url: "https://registry.npmjs.org/@cline/sdk/latest", extract: clineSdkVersion }],
   },
+  clineCli: {
+    key: "cline-cli",
+    fallback: "3.0.73",
+    sources: [{ url: "https://registry.npmjs.org/cline/latest", extract: clineSdkVersion }],
+  },
   codex: {
     key: "codex",
     fallback: "0.163.0",
@@ -257,7 +316,7 @@ export const VERSION_SOURCES = {
   },
   workbuddyCli: {
     key: "workbuddy",
-    fallback: "2.168.2",
+    fallback: "2.169.0",
     sources: [
       { url: "https://registry.npmjs.org/@tencent-ai/codebuddy-code/latest" },
       { url: "https://registry.npmmirror.com/@tencent-ai/codebuddy-code/latest" },
@@ -284,7 +343,7 @@ export const VERSION_SOURCES = {
   },
   codebuddy: {
     key: "codebuddy",
-    fallback: "2.168.2",
+    fallback: "2.169.0",
     sources: [
       { url: "https://registry.npmjs.org/@tencent-ai/codebuddy-code/latest" },
       { url: "https://registry.npmmirror.com/@tencent-ai/codebuddy-code/latest" },
@@ -342,6 +401,46 @@ export const VERSION_SOURCES = {
     fallback: "1.4.10-R6427.1",
     sources: [{ url: "https://api.meta.ai/muse-code/channels/muse-stable" }],
   },
+  trae: {
+    key: "trae",
+    // Fallback = the donor's last observed client version. Discovery replaces
+    // it within one monitor tick; it is only what a cold process sends before
+    // the first successful fetch.
+    fallback: "3.6.2",
+    sources: [
+      {
+        url: "https://docs.trae.ai/ide/changelog?_lang=en",
+        extract: traeVersion,
+      },
+    ],
+  },
+  cursor: {
+    key: "cursor",
+    // Fallback = the last observed wire version. Discovery replaces it within
+    // one monitor tick; it is only what a cold process sends before the first
+    // successful fetch.
+    fallback: "cli-2026.10.19-6bbf2c4",
+    sources: [
+      {
+        url: "https://cursor.com/api/download?platform=win32-x64-user&releaseTrack=stable",
+        extract: cursorVersion,
+      },
+    ],
+  },
+  hermes: {
+    key: "hermes",
+    // Hermes DOES publish a semver: the GitHub release tag is `v0.22.2`. The
+    // comment this replaced claimed no semver existed and pinned a date tag
+    // (`v2026.9.24`) as the version — a tag, not a release, and not the
+    // identity the client sends.
+    fallback: "0.22.2",
+    sources: [
+      {
+        url: "https://api.github.com/repos/NousResearch/hermes-agent/releases/latest",
+        extract: githubReleaseVersion,
+      },
+    ],
+  },
   zcode: {
     key: "zcode",
     fallback: "3.14.3",
@@ -357,11 +456,15 @@ export const VERSION_SOURCES = {
 const resolvers = {
   antigravity: createClientVersionResolver({ ...VERSION_SOURCES.antigravity, client: "antigravity" }),
   qoder: createClientVersionResolver({ ...VERSION_SOURCES.qoder, client: "qoder" }),
+  hermes: createClientVersionResolver({ ...VERSION_SOURCES.hermes, client: "hermes" }),
+  trae: createClientVersionResolver({ ...VERSION_SOURCES.trae, client: "trae" }),
+  cursor: createClientVersionResolver({ ...VERSION_SOURCES.cursor, client: "cursor" }),
   opencode: createClientVersionResolver({ ...VERSION_SOURCES.opencode, client: "opencode" }),
   commandcode: createClientVersionResolver({ ...VERSION_SOURCES.commandcode, client: "command-code" }),
   grok: createClientVersionResolver({ ...VERSION_SOURCES.grok, client: "grok" }),
   clineClient: createClientVersionResolver({ ...VERSION_SOURCES.clineClient, client: "cline" }),
   clineSdk: createClientVersionResolver({ ...VERSION_SOURCES.clineSdk, client: "cline-sdk" }),
+  clineCli: createClientVersionResolver({ ...VERSION_SOURCES.clineCli, client: "cline-cli" }),
   codex: createClientVersionResolver({ ...VERSION_SOURCES.codex, client: "codex" }),
   workbuddyClient: createClientVersionResolver({ ...VERSION_SOURCES.workbuddyClient, client: "workbuddy" }),
   workbuddyCnClient: createClientVersionResolver({ ...VERSION_SOURCES.workbuddyCnClient, client: "workbuddy-cn" }),
@@ -384,9 +487,16 @@ const PROVIDER_VERSION_RESOLVERS: Readonly<Record<string, ClientVersionResolver>
   opencode: resolvers.opencode,
   "opencode-zen": resolvers.opencode,
   "opencode-go": resolvers.opencode,
-  cline: resolvers.clineClient,
+  // The identity this provider is dispatched under is the CLI's, so the route
+  // identity reports the CLI version. `clineClient` (the VS Code extension
+  // manifest) is no longer the client this provider claims to be.
+  cline: resolvers.clineCli,
   codex: resolvers.codex,
   qoder: resolvers.qoder,
+  hermes: resolvers.hermes,
+  trae: resolvers.trae,
+  traecn: resolvers.trae,
+  cursor: resolvers.cursor,
   commandcode: resolvers.commandcode,
   workbuddy: resolvers.workbuddyClient,
   workbuddycn: resolvers.workbuddyCnClient,
@@ -484,6 +594,8 @@ function accessor<K extends keyof typeof resolvers>(name: K): {
 }
 
 export const getQoderVersion = accessor("qoder").get;
+export const getHermesVersion = accessor("hermes").get;
+export const getTraeVersion = accessor("trae").get;
 export const getAntigravityVersion = accessor("antigravity").get;
 
 export const getOpenCodeVersion = accessor("opencode").get;
@@ -503,8 +615,10 @@ export function buildGrokAuthUserAgent(version = getGrokVersion()): string {
 
 export const getClineClientVersion = accessor("clineClient").get;
 export const getClineSdkVersion = accessor("clineSdk").get;
+export const getClineCliVersion = accessor("clineCli").get;
 export const _resetClineClientVersionCache = accessor("clineClient").reset;
 export const _resetClineSdkVersionCache = accessor("clineSdk").reset;
+export const _resetClineCliVersionCache = accessor("clineCli").reset;
 
 export const getCodexVersion = accessor("codex").get;
 
@@ -513,9 +627,16 @@ export const getWorkBuddyCnClientVersion = accessor("workbuddyCnClient").get;
 export const getWorkBuddyCliVersion = accessor("workbuddyCli").get;
 
 export function buildWorkBuddyUserAgent(
+  identity = "WB",
   clientVersion = getWorkBuddyClientVersion(),
   cliVersion = getWorkBuddyCliVersion(),
 ): string {
+  // 1:1 with codebuddy2api. The CLI profile is `CLI/<v> CodeBuddy/<v>` and the
+  // WorkBuddy profile is `WorkBuddy/<wb> WorkBuddy AI/<wb> CLI/<cli>`, which
+  // sends NO SDK headers — two separate profiles, not one string with a switch.
+  // Whether SDK headers ride along is decided by `workbuddyHeaders`, not here, so
+  // this builder only decides the UA text.
+  if (identity === "CLI") return `CLI/${cliVersion} CodeBuddy/${cliVersion}`;
   return `WorkBuddy/${clientVersion} WorkBuddy AI/${clientVersion} CLI/${cliVersion}`;
 }
 
@@ -529,7 +650,7 @@ export const getCodeBuddyCnVersion = accessor("codebuddyCn").get;
  * The CodeBuddy User-Agent.
  *
  * Both identities share the CLI *package* version, which is why `codebuddy`
- * (the npm `@tencent-ai/codebuddy-code` pin, `2.168.2` — the value both
+ * (the npm `@tencent-ai/codebuddy-code` pin, `2.169.0` — the value both
  * references use for CLI) is the version for each. `codebuddyCn` is the CN
  * *desktop* build (`4.12.2.…`), and using it here produced
  * `CLI/4.12.2.41207131 CodeBuddy/4.12.2.41207131` — a CLI claiming a desktop
@@ -538,8 +659,14 @@ export const getCodeBuddyCnVersion = accessor("codebuddyCn").get;
 export function buildCodeBuddyUserAgent(
   identity: "IDE" | "CLI",
   version = getCodeBuddyVersion(),
+  cnVersion = getCodeBuddyCnVersion(),
 ): string {
-  return `${identity}/${version} CodeBuddy/${version}`;
+  // 1:1 with codebuddy2api's identity_headers(): the CLI profile uses ONE version
+  // (the npm CLI package pin) for both halves, and the IDE profile uses the other
+  // product's version. This previously always used `version`, so "CLI" produced
+  // `CLI/<ide> CodeBuddy/<ide>` — a CLI claiming the desktop build.
+  const resolved = identity === "CLI" ? cnVersion : version;
+  return `${identity}/${resolved} CodeBuddy/${resolved}`;
 }
 
 export const _resetCodeBuddyVersionCache = accessor("codebuddy").reset;

package/src/providers/operations/provider-catalog-seeder.ts

@@ -1,86 +1,95 @@
-/** Durable materialization of bundled provider model metadata. */
-import { and, eq, sql } from "drizzle-orm";
-import type { CartethyiaDatabase } from "../../persistence/db-handle";
-import { models } from "../../persistence/schema";
-import type { ModelDefinition } from "../provider-model-definition";
-
-/** Persists compiled provider model metadata and reconciles drifted capability flags. */
-export async function seedBundledModels(
-  db: CartethyiaDatabase,
-  builtinModels: ReadonlyMap<string, readonly ModelDefinition[]>,
-): Promise<void> {
-  for (const [providerId, definitions] of builtinModels) {
-    if (definitions.length === 0) continue;
-    // Drop builtin rows the current catalog no longer declares, including rows
-    // whose model id is still present but whose endpoint path drifted (e.g. a
-    // provider that moved from `/chat/completions` to `/v2/chat/completions`).
-    // The unique key is (provider, model, endpoint), so a changed endpoint
-    // would otherwise insert a second row and leave the stale route behind —
-    // the model list would then show duplicates and probes could hit the dead
-    // path. Composite `NOT IN` keeps exactly the (model, endpoint) pairs the
-    // catalog owns.
-    const pairs = definitions.map(
-      (definition) => sql`(${definition.modelId}, ${definition.endpointPath})`,
-    );
-    await db
-      .delete(models)
-      .where(
-        and(
-          eq(models.providerId, providerId),
-          eq(models.source, "builtin"),
-          sql`(${models.modelId}, ${models.endpointPath}) NOT IN (${sql.join(pairs, sql`, `)})`,
-        ),
-      );
-  }
-  const now = new Date();
-  const seen = new Set<string>();
-  const rows = [...builtinModels.entries()].flatMap(([providerId, definitions]) =>
-    definitions.flatMap((definition) => {
-      const key = `${providerId}\u0000${definition.modelId}\u0000${definition.endpointPath}`;
-      if (seen.has(key)) return [];
-      seen.add(key);
-      return [
-        {
-          providerId,
-          modelId: definition.modelId,
-          wireFamily: definition.wireFamily,
-          serviceKind: definition.serviceKind ?? "llm",
-          endpointPath: definition.endpointPath,
-          contextLimit: definition.contextLimit,
-          outputLimit: definition.outputLimit,
-          modalities: definition.modalities,
-          reasoning: definition.reasoning,
-          toolCall: definition.toolCall,
-          cost: definition.cost,
-          source: "builtin",
-          sourceUpdatedAt: now,
-          enabled: true,
-        },
-      ];
-    }),
-  );
-  if (rows.length === 0) return;
-  // Reconcile static metadata on conflict rather than skipping: capability
-  // flags (toolCall/reasoning/webSearch), wire family, limits, and cost can
-  // drift on a pre-existing row (e.g. a discovery seeded `tool_call=false`
-  // before the static catalog was corrected). `source` is forced back to
-  // `builtin`: a fetch upsert may have flipped a builtin row to `discovered`,
-  // and the static catalog owns these ids. `enabled` is operator-owned and
-  // must never be reset here.
-  await db.insert(models).values(rows).onConflictDoUpdate({
-    target: [models.providerId, models.modelId, models.endpointPath],
-    set: {
-      wireFamily: sql`excluded.wire_family`,
-      serviceKind: sql`excluded.service_kind`,
-      endpointPath: sql`excluded.endpoint_path`,
-      contextLimit: sql`excluded.context_limit`,
-      outputLimit: sql`excluded.output_limit`,
-      modalities: sql`excluded.modalities`,
-      reasoning: sql`excluded.reasoning`,
-      toolCall: sql`excluded.tool_call`,
-      cost: sql`excluded.cost`,
-      source: sql`'builtin'`,
-      sourceUpdatedAt: sql`excluded.source_updated_at`,
-    },
-  });
-}
+/** Durable materialization of bundled provider model metadata. */
+import { and, eq, sql } from "drizzle-orm";
+import type { CartethyiaDatabase } from "../../persistence/db-handle";
+import { models } from "../../persistence/schema";
+import type { ModelDefinition } from "../provider-model-definition";
+
+/** Persists compiled provider model metadata and reconciles drifted capability flags. */
+export async function seedBundledModels(
+  db: CartethyiaDatabase,
+  builtinModels: ReadonlyMap<string, readonly ModelDefinition[]>,
+): Promise<void> {
+  for (const [providerId, definitions] of builtinModels) {
+    if (definitions.length === 0) continue;
+    // Drop builtin rows the current catalog no longer declares, including rows
+    // whose model id is still present but whose endpoint path drifted (e.g. a
+    // provider that moved from `/chat/completions` to `/v2/chat/completions`).
+    // The unique key is (provider, model, endpoint), so a changed endpoint
+    // would otherwise insert a second row and leave the stale route behind —
+    // the model list would then show duplicates and probes could hit the dead
+    // path. Composite `NOT IN` keeps exactly the (model, endpoint) pairs the
+    // catalog owns.
+    const pairs = definitions.map(
+      (definition) => sql`(${definition.modelId}, ${definition.endpointPath})`,
+    );
+    await db
+      .delete(models)
+      .where(
+        and(
+          eq(models.providerId, providerId),
+          eq(models.source, "builtin"),
+          sql`(${models.modelId}, ${models.endpointPath}) NOT IN (${sql.join(pairs, sql`, `)})`,
+        ),
+      );
+  }
+  const now = new Date();
+  const seen = new Set<string>();
+  const rows = [...builtinModels.entries()].flatMap(([providerId, definitions]) =>
+    definitions.flatMap((definition) => {
+      const key = `${providerId}\u0000${definition.modelId}\u0000${definition.endpointPath}`;
+      if (seen.has(key)) return [];
+      seen.add(key);
+      return [
+        {
+          providerId,
+          modelId: definition.modelId,
+          wireFamily: definition.wireFamily,
+          serviceKind: definition.serviceKind ?? "llm",
+          endpointPath: definition.endpointPath,
+          contextLimit: definition.contextLimit,
+          outputLimit: definition.outputLimit,
+          modalities: definition.modalities,
+          reasoning: definition.reasoning,
+          toolCall: definition.toolCall,
+          cost: definition.cost,
+          // A static row either knows it is refused on a free plan or says
+          // nothing. Never coerced to false: the column is three-valued, and
+          // "nobody established it" is not the same claim as "served on free".
+          proOnly: definition.proOnly ?? null,
+          // Same three-valued rule for the inverse: the provider's directory
+          // states the tier, so the flag is carried rather than derived.
+          freeTier: definition.freeTier ?? null,
+          source: "builtin",
+          sourceUpdatedAt: now,
+          enabled: true,
+        },
+      ];
+    }),
+  );
+  if (rows.length === 0) return;
+  // Reconcile static metadata on conflict rather than skipping: capability
+  // flags (toolCall/reasoning/webSearch), wire family, limits, and cost can
+  // drift on a pre-existing row (e.g. a discovery seeded `tool_call=false`
+  // before the static catalog was corrected). `source` is forced back to
+  // `builtin`: a fetch upsert may have flipped a builtin row to `discovered`,
+  // and the static catalog owns these ids. `enabled` is operator-owned and
+  // must never be reset here.
+  await db.insert(models).values(rows).onConflictDoUpdate({
+    target: [models.providerId, models.modelId, models.endpointPath],
+    set: {
+      wireFamily: sql`excluded.wire_family`,
+      serviceKind: sql`excluded.service_kind`,
+      endpointPath: sql`excluded.endpoint_path`,
+      contextLimit: sql`excluded.context_limit`,
+      outputLimit: sql`excluded.output_limit`,
+      modalities: sql`excluded.modalities`,
+      reasoning: sql`excluded.reasoning`,
+      toolCall: sql`excluded.tool_call`,
+      cost: sql`excluded.cost`,
+      proOnly: sql`excluded.pro_only`,
+      freeTier: sql`excluded.free_tier`,
+      source: sql`'builtin'`,
+      sourceUpdatedAt: sql`excluded.source_updated_at`,
+    },
+  });
+}

package/src/providers/operations/provider-credential-service.ts

@@ -29,8 +29,31 @@ const CRED_CACHE_MAX_ENTRIES = 2_000;
 interface CredCacheEntry {
   readonly at: number;
   readonly value: ResolvedCredential;
+  /**
+   * When this entry must stop being served, or `undefined` for "the default
+   * TTL applies".
+   *
+   * Per-entry rather than global because a credential's usable lifetime is a
+   * property of the credential: an OAuth token with 30 minutes left can be
+   * served for the full window, one with 20 seconds left for almost none of
+   * it. Storing the bound on the entry lets both share one cache.
+   */
+  readonly expiresAt?: number;
 }
 
+/**
+ * Margin kept between a cached OAuth token's expiry and the moment the cache
+ * stops serving it.
+ *
+ * The old rule refused to cache OAuth at all unless the token outlived the
+ * whole 5 s window, which meant every attempt paid a SELECT + AES-GCM decrypt
+ * for every OAuth account — the largest remaining per-request DB read. Caching
+ * against the token's own expiry is the same safety with a fraction of the
+ * reads. The margin covers clock skew between this process and the issuer, and
+ * the time a request already in flight may hold the value.
+ */
+const CRED_CACHE_EXPIRY_MARGIN_MS = 30_000;
+
 const credCache = new Map<string, CredCacheEntry>();
 
 /**
@@ -159,9 +182,14 @@ export async function resolveCredentialForAccount(
   // the cached value would contain a soon-to-expire secret.
   const now = Date.now();
   const cached = credCache.get(credCacheKey(providerId, accountId));
-  if (cached && now - cached.at < CRED_CACHE_TTL_MS) {
-    const kind = (cached.value as { credential_kind?: string }).credential_kind;
-    if (kind !== "oauth") return cached.value;
+  if (cached) {
+    // Two independent bounds: the cache window (rotation freshness) and, for a
+    // credential whose usable life was known, the moment that life ends. The
+    // shorter one wins, so a token about to expire is never served past it and
+    // no credential is served stale for longer than the window.
+    const withinWindow = now - cached.at < CRED_CACHE_TTL_MS;
+    const withinLife = cached.expiresAt === undefined || now < cached.expiresAt;
+    if (withinWindow && withinLife) return cached.value;
   }
 
   const parsedProviderId = parseProviderId(providerId);
@@ -208,11 +236,22 @@ export async function resolveCredentialForAccount(
     ...(authState === undefined ? {} : { auth_state: authState }),
   };
   const value = resolver.resolve(parsedProviderId, [alternative]).credential;
-  // Cache non-OAuth credentials unconditionally; OAuth only when far from expiry.
+  // Every credential is cached; an OAuth token with a known expiry simply gets
+  // a shorter bound. Refusing to cache OAuth was the safe-looking choice that
+  // cost a SELECT + decrypt per attempt, and it was stricter than necessary:
+  // the risk is serving an expired token, which a TTL tied to that token
+  // expiry prevents as completely as not caching does.
   const isOAuth = row.credentialKind === "oauth";
-  const safeToCache = !isOAuth || (dueAt !== undefined && dueAt > now + CRED_CACHE_TTL_MS);
-  if (safeToCache) {
-    credCache.set(credCacheKey(providerId, accountId), { at: now, value });
+  const lifeBound =
+    isOAuth && dueAt !== undefined ? dueAt - CRED_CACHE_EXPIRY_MARGIN_MS : undefined;
+  // A token already inside the margin must not be cached at all — its bound
+  // would be in the past, so the entry would be dead on arrival.
+  if (lifeBound === undefined || lifeBound > now) {
+    credCache.set(credCacheKey(providerId, accountId), {
+      at: now,
+      value,
+      ...(lifeBound === undefined ? {} : { expiresAt: lifeBound }),
+    });
     evictCredCacheOldest();
   }
   return value;

package/src/providers/provider-contracts.ts

@@ -5,6 +5,7 @@
 import type { CanonicalEvent, CanonicalRequest, WireFamily } from "../protocol/canonical-model";
 import { GatewayError } from "../protocol/gateway-error";
 import { BUNDLED_PROVIDER_METADATA, type BundledProviderId } from "./provider-metadata";
+import type { ValidatedOutboundHttp2Bidi } from "../network/http2-bidi";
 
 /** Closed union of every shipped provider ID. */
 export const BUNDLED_PROVIDER_IDS = BUNDLED_PROVIDER_METADATA.map((definition) => definition.id) as readonly BundledProviderId[];
@@ -67,14 +68,76 @@ export type ValidatedOutboundWebSocket = (
   signal: AbortSignal,
 ) => Promise<ProviderWebSocketSession>;
 
+/**
+ * Validated bidirectional HTTP/2 egress, bound to the same selected network
+ * pool as `outbound_fetch`.
+ *
+ * A Connect-RPC bidi Run is neither a `fetch` (the request body never ends)
+ * nor a WebSocket (different protocol), so it gets its own capability — and it
+ * goes through the same binding factory as every other egress, which is what
+ * keeps SSRF validation, DNS pinning, and pool byte attribution intact. A
+ * provider adapter receives this closure and never dials a socket itself.
+ */
+/**
+ * The dialer contract handed to a provider adapter.
+ *
+ * Declared in `network/http2-bidi.ts` — the transport owns the contract — and
+ * re-exported here so provider code keeps one import site.
+ */
+export type { ValidatedOutboundHttp2Bidi };
+
+/**
+ * A provider session that outlives the HTTP request that created it.
+ *
+ * Cursor's Run stays open between the client's separate HTTP requests: the
+ * first request returns a tool call and the next submits that tool's result on
+ * the *same* upstream Run. The account and network-pool slot that Run holds
+ * must therefore stay held too, while the request-scoped accounting for the
+ * first HTTP request is already settled. Ownership is transferred here so the
+ * release is idempotent and belongs to exactly one owner.
+ */
+export interface AttemptLeaseOwnership {
+  /**
+   * Hands the selected account/network-pool lease to a provider session that
+   * outlives this request. Returns the release to call exactly once when the
+   * session terminates; returns `undefined` when there was nothing to transfer
+   * (a credential-less or pool-less route), which is not an error.
+   *
+   * Idempotent: a second call returns `undefined` and releases nothing.
+   */
+  transferToProviderSession(): (() => void) | undefined;
+}
+
+/**
+ * Identity that authorizes a later request to continue a provider session the
+ * gateway is already holding.
+ *
+ * Cursor's tool loop spans two client HTTP requests on one upstream Run, so the
+ * Run — and the account lease it holds — outlives the request that opened it. A
+ * later request may only claim the Run by presenting the same tenant, API key,
+ * provider, and account, all recorded server-side when the Run was created. A
+ * call id alone is never sufficient: it is unguessable but it is still just a
+ * string a client could carry into another key's request.
+ */
+export interface ProviderContinuationScope {
+  readonly tenantId: string;
+  readonly apiKeyId: string;
+  readonly providerId: string;
+  readonly providerAccountId: string;
+}
+
 /** Context passed from routing to a provider adapter. */
 export interface ProviderDispatchContext {
   readonly credential: ResolvedCredential;
   readonly deadline: number;
   readonly abort_signal: AbortSignal;
   readonly outbound_fetch?: ValidatedOutboundFetch | undefined;
+  /** Validated image/attachment egress; deliberately excluded from payload capture. */
+  readonly outbound_attachment_fetch?: ValidatedOutboundFetch | undefined;
   /** Validated WSS egress bound to the same selected network pool as HTTP. */
   readonly outbound_websocket?: ValidatedOutboundWebSocket | undefined;
+  /** Validated bidirectional HTTP/2 egress bound to the same selected network pool. */
+  readonly outbound_http2?: ValidatedOutboundHttp2Bidi | undefined;
   /** Built-in API-key route-selected fallback User-Agent; custom providers leave this unset. */
   readonly user_agent?: string | undefined;
   /** Gateway request id, stable across provider retries for one logical request. */
@@ -85,6 +148,19 @@ export interface ProviderDispatchContext {
   readonly conversation_affinity?: string | undefined;
   /** Opaque identity shared by retries of one logical gateway request. */
   readonly request_identity?: object | undefined;
+  /**
+   * Ownership of this attempt's account/network-pool lease. Present only when
+   * the route holds a lease; a provider session that outlives the request
+   * (Cursor's Run) takes it over so the slot is not released while the Run is
+   * live, and not released twice when it ends.
+   */
+  readonly lease_ownership?: AttemptLeaseOwnership | undefined;
+  /**
+   * Identity of the caller, for a provider session that outlives this request.
+   * Absent when the route cannot scope a continuation, in which case a session
+   * must not be held open across requests at all.
+   */
+  readonly continuation_scope?: ProviderContinuationScope | undefined;
 }
 
 const USER_AGENT_HEADER_NAME = /^user-agent$/i;