cartethyia 2.4.5 → 2.5.0

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;

package/src/providers/provider-metadata.ts

@@ -1,4 +1,6 @@
-import type { ServiceKind, WireFamily } from "../protocol/canonical-model";
+import { SERVICE_KINDS, type ServiceKind, type WireFamily } from "../protocol/canonical-model";
+import { QODER_CHAT_PATH, QODER_REALMS } from "./integrations/qoder/qoder-realm";
+import { TRAE_CHAT_PATH, TRAE_REALMS } from "./integrations/trae/trae-realm";
 
 /** OpenAI-compatible wire overrides persisted for bundled and BYOK providers. */
 export interface CompatibilityProfile {
@@ -110,6 +112,17 @@ const RAW_BUNDLED_PROVIDER_METADATA = [
     credentialUrl: "https://kiro.dev",
     credentialHint: "Sign in with Google or GitHub in the browser, or use the device-code login with an Identity Center organization, then paste a Kiro API key if you prefer. Prompt caching is not reliably working for Kiro: the upstream recomputes the prompt on every turn, so cached-token savings should not be expected.",
   },
+  {
+    id: "cursor",
+    displayName: "Cursor",
+    baseUrl: "https://api2.cursor.sh",
+    wireFamilyDefault: "chat",
+    requiresAccount: true,
+    bespokeWire: true,
+    hasAdapterUserAgent: true,
+    credentialUrl: "https://cursor.com",
+    credentialHint: "Sign in with Cursor or import a Cursor API key.",
+  },
   { id: "kimi", displayName: "Kimi Code", baseUrl: "https://api.kimi.com/coding", credentialUrl: "https://platform.moonshot.ai/console/api-keys" },
   { id: "opencode", displayName: "OpenCode Free", baseUrl: "https://opencode.ai", requiresAccount: false, ipScopedRateLimit: true, hasAdapterUserAgent: true },
   { id: "opencode-zen", displayName: "OpenCode Zen", baseUrl: "https://opencode.ai", hasAdapterUserAgent: true, credentialUrl: "https://opencode.ai/auth" },
@@ -281,7 +294,23 @@ const RAW_BUNDLED_PROVIDER_METADATA = [
     baseUrl: "https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
     credentialUrl: "https://bailian.console.aliyun.com/",
   },
-  { id: "hermes", displayName: "Nous Research", baseUrl: "https://inference-api.nousresearch.com/v1", credentialUrl: "https://portal.nousresearch.com" },
+  // Egress pool traffic is refused here: the origin sits behind Cloudflare,
+  // which answers the pool's addresses with `403 Attention Required!` while the
+  // same request from the host answers 200. The credential is a per-account API
+  // key, so rotating the egress address buys nothing and only invites the
+  // challenge — the same reason InferHub and Cline skip the pool.
+  {
+    id: "hermes",
+    displayName: "Nous Research",
+    baseUrl: "https://inference-api.nousresearch.com/v1",
+    credentialUrl: "https://portal.nousresearch.com",
+    defaultSkipProxy: true,
+    // The adapter stamps its own identity (`hermes-agent/<version>`), which it
+    // also needs: Cloudflare in front of the origin refuses a request with no
+    // User-Agent. Letting the operator overwrite it would let them break the
+    // provider, so the console locks the control.
+    hasAdapterUserAgent: true,
+  },
   { id: "bai", displayName: "B.AI", baseUrl: "https://api.b.ai/v1", credentialUrl: "https://b.ai" },
   { id: "inferhub", displayName: "InferHub", baseUrl: "https://api.inferhub.dev/v1", defaultSkipProxy: true },
   { id: "aihubmix", displayName: "AiHubMix", baseUrl: "https://aihubmix.com/v1", credentialUrl: "https://aihubmix.com/token" },
@@ -308,14 +337,47 @@ const RAW_BUNDLED_PROVIDER_METADATA = [
     // (`x-command-code-version`, `x-cli-environment`, `x-session-id`) and never
     // reads the route User-Agent, so the Routing Strategy panel must not offer
     // a custom User-Agent for it — the field would be silently ignored.
+    //
+    // The base is the Provider API origin, not `/alpha/generate`. Command Code
+    // serves three wires from `/provider/v1` — `/chat/completions`,
+    // `/responses` and `/messages` — and `/alpha/generate` is the CLI's own
+    // NDJSON surface. Pointing the base at one endpoint made the other two
+    // unroutable, which is why every `claude-*` id (served on `/messages`
+    // only) could not be dispatched at all.
     id: "commandcode",
     displayName: "Command Code",
-    baseUrl: "https://api.commandcode.ai/alpha/generate",
+    baseUrl: "https://api.commandcode.ai/provider/v1",
     hasAdapterUserAgent: true,
     credentialUrl: "https://commandcode.ai/studio",
     credentialHint: "Use the API key from the Command Code CLI, or create one in the studio.",
   },
   { id: "qoder", displayName: "Qoder", baseUrl: "https://api2.qoder.sh/algo/api/v2/service/pro/sse/agent_chat_generation?FetchKeys=llm_model_result&AgentId=agent_common&Encode=1", hasAdapterUserAgent: true, credentialUrl: "https://qoder.com/account/integrations", credentialHint: "Paste a Personal Access Token (pt-...) from the Qoder integrations page, or sign in with your Qoder account." },
+  // A separate provider, not a region flag on `qoder`: the China deployment has
+  // its own gateway host, OAuth client id, and model roster, and a CN account
+  // dispatched to the global host is refused rather than degraded.
+  //
+  // The base is built from the realm table rather than restated, so the host
+  // the console shows and the host the adapter dials cannot disagree.
+  {
+    id: "qodercn",
+    displayName: "Qoder CN",
+    baseUrl: `${QODER_REALMS.cn.gateway}${QODER_CHAT_PATH}`,
+    hasAdapterUserAgent: true,
+    credentialUrl: `${QODER_REALMS.cn.website}/account/integrations`,
+    credentialHint: "Paste a Personal Access Token (pt-...) from the Qoder CN integrations page, or sign in with your Qoder China account.",
+  },
+  { id: "trae", displayName: "Trae", baseUrl: `${TRAE_REALMS.intl.core}${TRAE_CHAT_PATH}`, hasAdapterUserAgent: true, credentialUrl: "https://www.trae.ai/", credentialHint: "Paste a Trae account export (accessToken + refreshToken) or the raw access token from an international Trae account." },
+  // A separate provider, not a region flag on `trae`: the China deployment has
+  // its own core host, authorization scheme, and model roster, and a CN account
+  // dispatched to the intl host is refused rather than degraded.
+  {
+    id: "traecn",
+    displayName: "Trae CN",
+    baseUrl: `${TRAE_REALMS.cn.core}${TRAE_CHAT_PATH}`,
+    hasAdapterUserAgent: true,
+    credentialUrl: "https://www.trae.com.cn/",
+    credentialHint: "Paste a Trae CN account export (accessToken + refreshToken) or the raw access token from a Trae China account.",
+  },
   { id: "ollamacloud", displayName: "Ollama Cloud", baseUrl: "https://ollama.com/v1", credentialUrl: "https://ollama.com/settings/keys" },
   { id: "gemini", displayName: "Google Gemini", baseUrl: "https://generativelanguage.googleapis.com/v1beta", serviceKinds: ["llm", "websearch", "imageGeneration"], credentialUrl: "https://aistudio.google.com/app/apikey" },
   { id: "xiaomipg", displayName: "Xiaomi MiMo (PAYG)", baseUrl: "https://api.xiaomimimo.com/v1", credentialUrl: "https://platform.xiaomimimo.com" },
@@ -508,8 +570,8 @@ export function providerDisplayName(providerId: string): string {
  * A bundled provider gets exactly what its manifest declares. A custom/BYOK
  * provider has no manifest row, and this is where its capability comes from:
  * `llm` alone is read as "every media surface this gateway knows", so a
- * third-party provider can serve image and video generation without the
- * gateway having to be taught its id.
+ * third-party provider can serve image, video, embeddings, and audio without
+ * the gateway having to be taught its id.
  *
  * That widening is deliberate rather than a default of `["llm"]`, because a
  * BYOK provider points at an operator-chosen base URL — the operator already
@@ -517,6 +579,16 @@ export function providerDisplayName(providerId: string): string {
  * out of the generation routes no matter what its upstream actually answers.
  * The upstream still decides: a request for a capability the remote does not
  * have comes back as that remote's own error, not a gateway-side refusal.
+ *
+ * A custom provider is read as able to serve **every** kind, taken straight
+ * from `SERVICE_KINDS` rather than a second list that can drift from it. A
+ * surface added to the tuple is reachable by custom providers immediately, and
+ * one that is not there cannot be served by anyone.
+ *
+ * `systemone` and `websearch` are included even though a base URL alone rarely
+ * answers them: the upstream still decides, and an operator who points a custom
+ * provider at a host that does speak those shapes should not be blocked by the
+ * gateway guessing it will not.
  */
 export function providerServiceKinds(providerId: string): readonly ServiceKind[] {
   const declared = BUNDLED_PROVIDER_METADATA.find((candidate) => candidate.id === providerId)
@@ -524,7 +596,7 @@ export function providerServiceKinds(providerId: string): readonly ServiceKind[]
   // Bundled providers are explicit: they say which surfaces they serve, and a
   // bundled provider without the declaration serves LLM only.
   if (declared !== undefined) return declared;
-  return ["llm", "imageGeneration", "videoGeneration"];
+  return SERVICE_KINDS;
 }