cartethyia 2.7.3 → 2.7.5

package/src/providers/operations/account-reset-service.ts

@@ -27,6 +27,7 @@ import { CLAUDE_CODE_USER_AGENT } from "../integrations/claude/claude-fingerprin
 import { authCredential, codexJwtAccountId, text } from "../quota/quota-contracts";
 import { getCodexVersion } from "./client-versions";
 import { buildCodexUserAgent } from "./cli-platform";
+import { TtlCache } from "../../persistence/ttl-cache";
 
 /** One redeemable (or already-spent) saved reset. */
 export interface ResetCredit {
@@ -62,6 +63,51 @@ const JUNIPER_PROGRAM = "juniper_tide";
 const ORG_ID = /^[A-Za-z0-9_-]{1,128}$/;
 /** Cedar grant ids are short slugs; anything else never reaches the provider. */
 const CEDAR_GRANT_ID = /^[a-z0-9_-]{1,40}$/;
+/** Abort budget for one upstream reset-path request, mirroring quota refresh. */
+const RESET_FETCH_TIMEOUT_MS = 15_000;
+
+/**
+ * Short per-account cache for {@link listAccountResetCredits}.
+ *
+ * The console reads the reset list each time a dialog opens; without a cache
+ * every open hits the upstream live. The TTL is short — the list changes when
+ * a credit is consumed, and `invalidateResetCreditsCache` clears the entry on
+ * a successful redemption — so staleness is bounded to a dialog-refresh
+ * window. Failures (`null`) are deliberately not cached: a discovery error
+ * stays retryable on the next open.
+ */
+const RESET_CREDITS_TTL_MS = 30_000;
+const resetCreditsCache = new TtlCache<ResetCreditList | null>({
+  ttlMs: RESET_CREDITS_TTL_MS,
+  maxEntries: 512,
+});
+
+/**
+ * Reads one account's saved reset credits through the short TTL cache.
+ * Concurrent misses share one upstream discovery via the cache's load-through
+ * deduplication.
+ */
+export async function getCachedResetCredits(
+  providerId: string,
+  accountId: string,
+  load: () => Promise<ResetCreditList | null>,
+): Promise<ResetCreditList | null> {
+  return resetCreditsCache.load(`${providerId}:${accountId}`, load, {
+    namespace: "reset-credits",
+  });
+}
+
+/**
+ * Drops every cached reset-credit entry for one account. Called after a
+ * successful redemption so the dialog does not keep showing a spent credit for
+ * the rest of the TTL.
+ */
+export function invalidateResetCreditsCache(accountId: string): void {
+  const suffix = `:${accountId}`;
+  for (const key of resetCreditsCache.keys()) {
+    if (key.endsWith(suffix)) resetCreditsCache.delete(key);
+  }
+}
 
 export function supportsAccountReset(providerId: string): boolean {
   const norm = providerId.trim().toLowerCase();
@@ -172,7 +218,10 @@ export async function listAccountResetCredits(
     try {
       const res = await fetcher(
         "https://chatgpt.com/backend-api/wham/rate-limit-reset-credits",
-        { headers: codexHeaders(access, accountId, version, false) },
+        {
+          headers: codexHeaders(access, accountId, version, false),
+          signal: AbortSignal.timeout(RESET_FETCH_TIMEOUT_MS),
+        },
       );
       if (!res.ok) return null;
       const payload = (await res.json()) as unknown;
@@ -237,6 +286,7 @@ async function discoverCedar(
   try {
     res = await fetcher("https://api.anthropic.com/api/oauth/usage?cedar_ember=1&skip_spend=1", {
       headers: claudeHeaders(access, false),
+      signal: AbortSignal.timeout(RESET_FETCH_TIMEOUT_MS),
     });
   } catch {
     return "failed";
@@ -343,6 +393,7 @@ async function discoverJuniper(
   try {
     res = await fetcher("https://api.anthropic.com/api/oauth/usage?at_wall=1&skip_spend=1", {
       headers: claudeHeaders(access, false),
+      signal: AbortSignal.timeout(RESET_FETCH_TIMEOUT_MS),
     });
   } catch {
     return null;
@@ -385,6 +436,7 @@ async function resolveClaudeOrg(access: string, fetcher: typeof fetch): Promise<
   try {
     const res = await fetcher("https://api.anthropic.com/api/oauth/profile", {
       headers: claudeHeaders(access, false),
+      signal: AbortSignal.timeout(RESET_FETCH_TIMEOUT_MS),
     });
     if (!res.ok) return null;
     const payload = (await res.json()) as unknown;
@@ -449,6 +501,7 @@ export async function consumeAccountResetCredit(args: {
               redeem_request_id: randomUUID(),
               ...(codexAccountId ? { account_id: codexAccountId } : {}),
             }),
+            signal: AbortSignal.timeout(RESET_FETCH_TIMEOUT_MS),
           },
         );
         const body = (await res.json().catch(() => undefined)) as Record<string, unknown> | undefined;
@@ -528,6 +581,7 @@ export async function consumeAccountResetCredit(args: {
               method: "POST",
               headers: claudeHeaders(access, true),
               body: JSON.stringify(body),
+              signal: AbortSignal.timeout(RESET_FETCH_TIMEOUT_MS),
             },
           );
           const payload = (await res.json().catch(() => undefined)) as
@@ -651,6 +705,9 @@ async function recordResetActivity(
       errorCategory: null,
       createdAt: now,
     });
+    // The redeemed credit is gone; the next dialog open must not serve the
+    // pre-redeem list for the rest of the TTL.
+    invalidateResetCreditsCache(accountId);
     await snapshotInvalidator?.invalidate();
     return;
   }

package/src/providers/operations/cli-platform.ts

@@ -16,6 +16,8 @@
  * Every value below is what the real client would report, taken from each
  * client's own source rather than guessed.
  */
+import { createHash } from "node:crypto";
+import { hostname as osHostname } from "node:os";
 
 /**
  * `os_info` — the crate Codex reads this from — returns the marketing name
@@ -52,9 +54,6 @@ const KIMI_OS_VERSION = "macOS 15.6";
  */
 const KIMI_DEVICE_NAME = "MacBook-Pro.local";
 
-/** Qoder's `cosy-machineos`: "<arch>_<os>". */
-const QODER_MACHINE_OS = "aarch64_macos";
-
 
 /**
  * Cline's `x-platform` / `x-platform-version`.
@@ -128,9 +127,36 @@ export function kimiDeviceName(): string {
   return KIMI_DEVICE_NAME;
 }
 
-/** Qoder's `cosy-machineos`. */
+/**
+ * Qoder's `cosy-machineos`: "<arch>_<os>".
+ *
+ * The desktop IDE builds this from its own runtime
+ * (`V8e = ${process.arch==="arm64"?"aarch64":process.arch==="x64"?"x86_64":process.arch}_${process.platform}`),
+ * so the gateway mirrors that exact mapping instead of a fixed macOS value.
+ */
 export function qoderMachineOs(): string {
-  return QODER_MACHINE_OS;
+  const arch = process.arch === "arm64" ? "aarch64" : process.arch === "x64" ? "x86_64" : process.arch;
+  return `${arch}_${process.platform}`;
+}
+
+/**
+ * Qoder's `cosy-machinehostname`.
+ *
+ * The desktop IDE sends the real machine hostname, normalized to a header-safe
+ * form (`B9i` in the unpacked worker: lowercase, non-ASCII and runs of dashes
+ * collapsed, truncated to 96 chars with a short hash suffix). Mirror the exact
+ * mapping so the value is indistinguishable from the IDE's.
+ */
+export function qoderMachineHostname(): string {
+  const raw = (osHostname() ?? "").trim().toLowerCase();
+  if (!raw) return "";
+  const safe = raw
+    .replace(/[^\x21-\x7e]+/gu, "-")
+    .replace(/-{2,}/gu, "-")
+    .replace(/^-+|-+$/gu, "");
+  if (safe.length <= 96) return safe;
+  const hash = createHash("sha256").update(safe, "utf8").digest("hex").slice(0, 8);
+  return `${safe.slice(0, 96 - 1 - 8)}-${hash}`;
 }
 
 /** Cline's `x-platform`. */

package/src/providers/operations/client-version-resolver.ts

@@ -12,12 +12,11 @@
  * only call the synchronous `get`/`snapshot` accessors and never fetch.
  */
 import { getCachedVersion, resetVersionCacheForTesting } from "./provider-version-cache";
+import type { OutboundFetch } from "../provider-contracts";
+import { composeAbortSignal } from "../authentication/oauth-flow-store";
 
 /** Structural fetch contract for providers that inject lightweight transports. */
-export type ClientVersionFetcher = (
-  input: RequestInfo | URL,
-  init?: RequestInit,
-) => Promise<Response>;
+export type ClientVersionFetcher = OutboundFetch;
 
 /** One ordered upstream probe. Earlier entries win. */
 export interface ClientVersionSource {
@@ -156,10 +155,9 @@ export function createClientVersionResolver(
   }
 
   async function probe(source: ClientVersionSource, fetcher: ClientVersionFetcher, signal?: AbortSignal): Promise<string | null> {
-    const timeoutSignal = AbortSignal.timeout(FETCH_TIMEOUT_MS);
     const response = await fetcher(source.url, {
       headers: { accept: "application/json, text/plain, */*" },
-      signal: signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal,
+      signal: composeAbortSignal(signal, FETCH_TIMEOUT_MS),
     });
     if (!response.ok) return null;
     return (source.extract ?? defaultExtract)(response);

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

@@ -200,7 +200,7 @@ async function githubReleaseVersion(response: Response): Promise<string | null>
  * The discovery source below only supplies the *IDE* version that follows the
  * `KiroIDE` device marker.
  */
-const KIRO_RUNTIME_SDK_VERSION = "1.0.39";
+const KIRO_RUNTIME_SDK_VERSION = "1.0.44";
 
 /**
  * AWS SSO OIDC SDK version stamped into login and token-refresh User-Agents.
@@ -242,7 +242,12 @@ export const VERSION_SOURCES = {
   },
   qoder: {
     key: "qoder",
-    fallback: "1.1.81",
+    // The desktop IDE hardcodes its COSY_VERSION as "1.1.80" (`S9` in the
+    // unpacked worker bundle); the model-server surface sees this value, so
+    // the gateway presents the same build the IDE ships. Discovery (npm
+    // `@qoder-ai/qodercli/latest`) may report a newer CLI, but the CLI and
+    // IDE are different products — the chat surface identity is the IDE's.
+    fallback: "1.1.80",
     sources: [
       {
         url: "https://registry.npmjs.org/@qoder-ai/qodercli/latest",
@@ -254,7 +259,9 @@ export const VERSION_SOURCES = {
     key: "opencode",
     // The v1 package (`opencode-ai`) stopped at 1.18. The v2 line publishes
     // under `@opencode/cli`, and this feed is what its own installer reads.
-    fallback: "2.2.2",
+    // Fallback = the current latest release; raise it whenever the package
+    // moves so a cold process does not present a stale client build.
+    fallback: "2.2.5",
     minVersion: "2.0.0",
     sources: [{ url: "https://opencode.ai/update/api/latest/cli/npm" }],
   },
@@ -628,11 +635,8 @@ 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;
@@ -696,7 +700,6 @@ export const _resetCodeBuddyCnVersionCache = accessor("codebuddyCn").reset;
 
 export const getClaudeCliVersion = accessor("claudeCli").get;
 export const adoptClaudeCliVersion = accessor("claudeCli").adopt;
-export const _resetClaudeCliVersionCache = accessor("claudeCli").reset;
 export const getClaudeSdkVersion = accessor("claudeSdk").get;
 
 export const getKiroVersion = accessor("kiro").get;

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

@@ -59,6 +59,7 @@ export async function seedBundledModels(
           // 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,
+          dialect: definition.dialect ?? null,
           source: "builtin",
           sourceUpdatedAt: now,
           enabled: true,
@@ -88,6 +89,7 @@ export async function seedBundledModels(
       cost: sql`excluded.cost`,
       proOnly: sql`excluded.pro_only`,
       freeTier: sql`excluded.free_tier`,
+      dialect: sql`excluded.dialect`,
       source: sql`'builtin'`,
       sourceUpdatedAt: sql`excluded.source_updated_at`,
     },

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

@@ -20,6 +20,7 @@ import { GATEWAY_USER_AGENT } from "./gateway-user-agent";
 import { isIP } from "node:net";
 import { isAddressAllowed } from "../../network/ssrf";
 import type { SsrfPolicy } from "../../config/network";
+import { BoundedLruMap } from "../../transport/routing/bounded-lru";
 
 /**
  * Revision of the compiled provider catalog, and the last one materialized.
@@ -234,14 +235,20 @@ export async function bundledModelCatalog(
  * 30 s timer, so an ungated re-seed could be pushed onto the next proxy
  * request for a catalog that had not changed. The paths that do change the
  * catalog bump the revision; everything else is a no-op here.
+ *
+ * `precomputedCatalog` supplies the compiled catalog when the caller already
+ * materialized it (the boot path's deferred B-01 resolution), so the seed
+ * shares that walk instead of running a second one. Absent, the walk runs
+ * here as before.
  */
 export async function refreshActiveProviderCatalogs(
   db: CartethyiaDatabase,
   registry: ProviderRegistry,
+  precomputedCatalog?: BundledProviderCatalog,
 ): Promise<void> {
   const revision = currentCatalogRevision();
   if (revision === lastSeededCatalogRevision) return;
-  const catalog = await bundledModelCatalog(registry);
+  const catalog = precomputedCatalog ?? (await bundledModelCatalog(registry));
   await seedBundledModels(db, catalog.modelsByProvider);
   lastSeededCatalogRevision = revision;
 }
@@ -251,8 +258,17 @@ export async function refreshActiveProviderCatalogs(
  * Last successfully applied BYOK config per normalized provider ID.
  * Makes repeated `syncByokProviders` runs cheap: an unchanged row is skipped,
  * while a changed one is re-registered instead of being rejected.
+ *
+ * Bounded (G-04 / B-04): provider IDs are operator-created strings, so an
+ * unbounded map would pin an entry for every retired or deleted custom
+ * provider forever. The LRU bound keeps only the most recently touched
+ * registrations resident; a dropped entry simply re-registers on the next
+ * pass (the fingerprint is a skip-ahead optimization, not correctness).
  */
-const byokRegistrationFingerprints = new Map<string, string>();
+const BYOK_FINGERPRINT_CACHE_MAX_ENTRIES = 1024;
+const byokRegistrationFingerprints = new BoundedLruMap<string, string>(
+  BYOK_FINGERPRINT_CACHE_MAX_ENTRIES,
+);
 
 function byokFingerprint(
   baseUrl: string,
@@ -290,10 +306,10 @@ export async function registerByokProviders(
     try {
       providerId = parseProviderId(row.id);
     } catch {
-      throw new GatewayError("invalid_request", 400, `invalid BYOK provider ID: ${row.id}`);
+      throw new GatewayError("invalid_request", 400, `invalid BYOK provider ID: ${row.id} (request {requestId}). Check the shape of what you sent — then resend 🪞`);
     }
     if (isBundledProviderId(providerId)) {
-      throw new GatewayError("invalid_request", 409, `BYOK provider ID collides with a built-in: ${row.id}`, {
+      throw new GatewayError("invalid_request", 409, `BYOK provider ID collides with a built-in: ${row.id} (request {requestId}). This name's taken — pick another alias ✨`, {
         provider_id: providerId,
       });
     }
@@ -309,14 +325,14 @@ export async function registerByokProviders(
       }
     } catch (error) {
       if (error instanceof GatewayError) throw error;
-      throw new GatewayError("invalid_request", 400, `invalid BYOK base URL for provider ${row.id}`);
+      throw new GatewayError("invalid_request", 400, `invalid BYOK base URL for provider ${row.id} (request {requestId}). Check the shape of what you sent — then resend 🪞`);
     }
     // IP literals are rejected at registration; DNS names are revalidated at dispatch.
     if (isIP(parsedUrl.hostname) !== 0 && !isAddressAllowed(parsedUrl.hostname, ssrfPolicy)) {
       throw new GatewayError(
         "invalid_request",
         400,
-        `BYOK provider ${row.id} host is blocked (private/unsafe address)`,
+        `BYOK provider ${row.id} host is blocked (private/unsafe address) (request {requestId}). All roads blocked — time to find a new route 🗺️`,
       );
     }
     const defaultPort = parsedUrl.protocol === "http:" ? 80 : 443;

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

@@ -9,8 +9,20 @@ import type { OAuthRefreshService, OAuthTokenRefresher } from "../authentication
 import { CredentialResolver, type CredentialAlternative } from "../provider-credential-resolver";
 import { parseProviderId, type CredentialKind } from "../provider-contracts";
 import type { ResolvedCredential } from "../provider-contracts";
-import { record } from "../authentication/oauth-flow-store";
 import { refreshLeadMs } from "./oauth-refresh-lead";
+import { asJsonbRecord } from "../../shared/coerce";
+
+/**
+ * The `auth_state` JSONB column arrives as a POJO from Postgres (drizzle
+ * jsonb) but as a JSON STRING from SQLite (the native column stores text).
+ * The resolver's `record()` helper rejects strings, so a SQLite read dropped
+ * the auth state entirely — Qoder dispatch then saw no userId/machineId and
+ * failed with 401 "missing its user identity". Parse the string form once
+ * here so every backend hands the resolver the same POJO shape.
+ */
+function jsonbRecord(value: unknown): Record<string, unknown> | undefined {
+  return asJsonbRecord(value);
+}
 
 // ── Credential cache ─────────────────────────────────────────────────────────
 /**
@@ -93,6 +105,23 @@ export function invalidateCredentialCache(accountId?: string): void {
   }
 }
 
+/**
+ * Invalidates many accounts' cached credentials in one pass over the cache.
+ *
+ * The batch-delete route deletes several accounts at once; calling the single
+ * variant per id would scan the whole cache once per account. This is one
+ * scan with a suffix set, so the cost is one pass regardless of batch size.
+ */
+export function invalidateCredentialCaches(accountIds: readonly string[]): void {
+  if (accountIds.length === 0) return;
+  const suffixes = new Set(accountIds.map((id) => `:${id}`));
+  for (const key of credCache.keys()) {
+    // Account ids are globally unique and contain no colon, so the trailing
+    // `:${accountId}` segment uniquely identifies the owning account.
+    if (suffixes.has(key.slice(key.lastIndexOf(":")))) credCache.delete(key);
+  }
+}
+
 const resolver = new CredentialResolver();
 
 /** Stored account fields needed by credential resolution and token refresh. */
@@ -229,7 +258,7 @@ export async function resolveCredentialForAccount(
       throw new GatewayError(
         "authentication_failed",
         401,
-        "provider credential cannot be decrypted; re-save the account credential",
+        "provider credential cannot be decrypted (request {requestId}); re-save the account credential. Wrong key, right door — check the credential 🔑",
         {
           providerId: row.providerId,
           accountId: row.id,
@@ -253,7 +282,7 @@ export async function resolveCredentialForAccount(
     }
   }
 
-  const authState = record(row.authState);
+  const authState = jsonbRecord(row.authState);
   const alternative: CredentialAlternative = {
     provider_id: parseProviderId(row.providerId),
     account_id: row.id,
@@ -283,7 +312,7 @@ export async function resolveCredentialForAccount(
   return value;
 }
 
-export async function resolveAccountSecretString(
+async function resolveAccountSecretString(
   db: CartethyiaDatabase,
   providerId: string,
   accountId: string,
@@ -294,7 +323,7 @@ export async function resolveAccountSecretString(
 }
 
 /** Decrypts the stored provider tokens after refreshing an expired OAuth access token. */
-export async function resolveAccountCredentialsForExport(
+async function resolveAccountCredentialsForExport(
   db: CartethyiaDatabase,
   providerId: string,
   accountId: string,
@@ -319,7 +348,7 @@ export async function resolveAccountCredentialsForExport(
       await oauth.refreshService.ensureFreshAccessToken(accountId, refresher);
       account = await loadAccountWithFreshness(db, accountId);
       if (!account) {
-        throw new GatewayError("admission_unavailable", 503, "This provider account no longer exists, so its credential cannot be read. Re-select the account, or point the route at a live one.", {
+        throw new GatewayError("admission_unavailable", 503, "This provider account no longer exists, so its credential cannot be read (request {requestId}). Re-select the account, or point the route at a live one. The account went cold — reconnect or resend 🔌", {
           provider_id: providerId,
           account_id: accountId,
         });

package/src/providers/operations/upstream-deadline.ts

@@ -17,7 +17,7 @@ export function createUpstreamDeadlineLifecycle(
         new GatewayError(
           "deadline_exceeded",
           504,
-          "upstream request deadline exceeded",
+          "upstream request deadline exceeded (request {requestId}). Some things just take longer 🐢",
           {},
           "upstream",
         ),
@@ -52,11 +52,11 @@ export function abortGatewayError(
   const reason = lifecycle.signal.reason ?? requestSignal?.reason;
   if (reason instanceof GatewayError) return reason;
   if (reason instanceof DOMException && reason.name === "TimeoutError")
-    return new GatewayError("deadline_exceeded", 504, "request deadline exceeded", {}, "cartethyia");
+    return new GatewayError("deadline_exceeded", 504, "request deadline exceeded (request {requestId}). Some things just take longer 🐢", {}, "cartethyia");
   const abortLike =
     (error instanceof DOMException && error.name === "AbortError") ||
     (error instanceof Error && error.name === "AbortError");
   if (lifecycle.signal.aborted || requestSignal?.aborted || abortLike)
-    return new GatewayError("transport_closed", 499, "request was cancelled");
+    return new GatewayError("transport_closed", 499, "The request was cancelled (request {requestId}). Send it again whenever ready 🙃");
   return undefined;
 }

package/src/providers/provider-contracts.ts

@@ -42,18 +42,69 @@ export function readCredentialSecret(credential: ResolvedCredential, errorMessag
     throw new GatewayError(
       "authentication_failed",
       401,
-      errorMessage ?? "Provider credential secret is missing or empty",
+      `${errorMessage ?? "Provider credential secret is missing or empty"} (request {requestId}). Wrong key, right door — check the credential 🔑`,
     );
   }
   return raw;
 }
 
-/** Fetch capability that validates DNS answers and redirects before each request. */
-export type ValidatedOutboundFetch = (
+/**
+ * Asserts a credential is of the required kind, throwing a typed rejection
+ * otherwise. Providers disagree on the kind they accept (`oauth` vs
+ * `api_key` vs `scoped_access_token`), and each hand-rolled its own check +
+ * message. This centralizes the common pattern so a mis-bound credential reads
+ * the same everywhere, preserving the existing `invalid_request`/400 wire
+ * contract.
+ */
+export function assertCredentialKind(
+  credential: ResolvedCredential,
+  expected: CredentialKind | readonly CredentialKind[],
+  providerLabel: string,
+): void {
+  const expectedKinds = Array.isArray(expected) ? expected : [expected];
+  if (expectedKinds.includes(credential.credential_kind)) return;
+  throw new GatewayError(
+    "invalid_request",
+    400,
+    `${providerLabel}: ${expectedKinds.join(" or ")} credential required (got credential_kind=${credential.credential_kind}) (request {requestId}). Wrong key, right door — check the credential 🔑`,
+    { expected_credential_kind: expectedKinds },
+  );
+}
+
+/**
+ * Asserts a candidate's wire family is one of the ones the provider serves,
+ * throwing `capability_unsupported` otherwise. Every provider hand-rolled this
+ * guard with the same shape; this centralizes the pattern so a mis-routed
+ * candidate reads the same everywhere.
+ */
+export function assertWireFamily(
+  candidate: ProviderDispatchTarget,
+  allowed: WireFamily | readonly WireFamily[],
+  providerLabel: string,
+): void {
+  const allowedFamilies = Array.isArray(allowed) ? allowed : [allowed];
+  if (allowedFamilies.includes(candidate.wire_family)) return;
+  throw new GatewayError(
+    "capability_unsupported",
+    400,
+    `${providerLabel} supports ${allowedFamilies.join("/")} only, got ${candidate.wire_family} (request {requestId}). Know your tools — this one just isn't in the box 🧰`,
+    { expected_wire_families: allowedFamilies, got_wire_family: candidate.wire_family },
+  );
+}
+
+/**
+ * Minimal fetch surface accepted by provider adapters, collectors, and
+ * discovery paths. One canonical shape shared across modules that plug a
+ * transport into a provider boundary.
+ */
+export type OutboundFetch = (
   input: RequestInfo | URL,
   init?: RequestInit,
 ) => Promise<Response>;
 
+/** Fetch capability that validates DNS answers and redirects before each request. */
+export type ValidatedOutboundFetch = OutboundFetch;
+
 /** Provider WebSocket session over validated WSS egress. */
 export interface ProviderWebSocketSession {
   send(message: string): void;
@@ -217,6 +268,8 @@ export interface ProviderDispatchTarget {
   readonly endpoint_path: string;
   readonly output_limit?: number | null;
   readonly capabilities: Readonly<Record<string, boolean>>;
+  /** Explicit wire dialect (from `models.dialect`), when set. Absent = resolver fallback. */
+  readonly dialect?: string;
 }
 
 /** Provider adapter boundary: canonical request/events in, no public HTTP routes. */
@@ -228,11 +281,13 @@ export interface ProviderAdapter {
     context: ProviderDispatchContext,
   ): AsyncIterable<CanonicalEvent>;
   /**
-   * Optional native-protocol capability. A provider whose catalog serves a
-   * non-`llm` service kind (System One) implements the matching method; the
-   * native route handler looks it up and dispatches the caller's opaque body
-   * through it. The body is forwarded untouched — the method only adds the
-   * provider's auth/identity headers and posts it to `endpoint_path`.
+   * Optional native-protocol capability for the public `POST /v1/systemone`
+   * route (the dispatch leg of the System One service, alongside the probing
+   * leg served by the discovery/probing-service). A provider whose catalog
+   * serves a non-`llm` service kind (System One) implements the matching
+   * method; the native route handler looks it up and dispatches the caller's
+   * opaque body through it. The body is forwarded untouched — the method only
+   * adds the provider's auth/identity headers and posts it to `endpoint_path`.
    *
    * An adapter without this method is simply not eligible for the route, which
    * is why it is optional rather than a required no-op.
@@ -352,7 +407,7 @@ export interface WebSearchOutcome {
 function normalizeProviderSlug(id: string): string {
   const trimmed = id.trim().toLowerCase();
   if (!/^[a-z][a-z0-9-]{0,63}$/.test(trimmed)) {
-    throw new GatewayError("invalid_request", 400, "Provider ID must be a lowercase slug");
+    throw new GatewayError("invalid_request", 400, "Provider ID must be a lowercase slug (request {requestId}). Check the shape of what you sent — then resend 🪞");
   }
   return trimmed;
 }
@@ -379,7 +434,7 @@ export function parseCustomProviderId(value: string): CustomProviderId {
     throw new GatewayError(
       "slug_reserved",
       409,
-      "The provider ID is reserved for a builtin provider",
+      "The provider ID is reserved for a builtin provider (request {requestId}). This name's taken — pick another alias ✨",
       { provider_id: normalized },
     );
   }

package/src/providers/provider-credential-resolver.ts

@@ -68,7 +68,7 @@ export class CredentialResolver {
     throw new GatewayError(
       "invalid_request",
       401,
-      "No usable upstream credential is configured for the selected provider",
+      "No usable upstream credential is configured for the selected provider (request {requestId}). Wrong key, right door — check the credential 🔑",
       { provider_id: providerId },
     );
   }

package/src/providers/provider-metadata.ts

@@ -115,10 +115,12 @@ const RAW_BUNDLED_PROVIDER_METADATA = [
   },
   {
     // Kiro frames its own conversation ledger over an AWS EventStream wire and
-    // has no chat-shaped endpoint to route through.
+    // has no chat-shaped endpoint to route through. Generation is the Kiro
+    // runtime service (`https://runtime.{region}.kiro.dev`), not the legacy
+    // `q.{region}.amazonaws.com` AWS surface.
     id: "kiro",
     displayName: "Kiro",
-    baseUrl: "https://q.us-east-1.amazonaws.com",
+    baseUrl: "https://runtime.us-east-1.kiro.dev",
     bespokeWire: true,
     hasAdapterUserAgent: true,
     defaultSkipProxy: true,
@@ -276,6 +278,19 @@ const RAW_BUNDLED_PROVIDER_METADATA = [
     baseUrl: "https://api.z.ai/api/coding/paas/v4",
     credentialUrl: "https://chat.z.ai",
   },
+  {
+    // The ZCode Start Plan is the free plan minted by the referral flow. The
+    // endpoint refuses bare Anthropic traffic ("3012 request has been blocked
+    // due to unusual activity"); the integration adds the ZCode identity
+    // headers and the system/date/cache-control dress in-process.
+    id: "zcode-start",
+    displayName: "ZCode Start",
+    baseUrl: "https://zcode.z.ai/api/v1/zcode-plan/anthropic",
+    wireFamilyDefault: "messages",
+    hasAdapterUserAgent: true,
+    credentialUrl: "https://zcode.z.ai",
+    credentialHint: "Use the ZCode login JWT, not a Z.AI access token or Coding Plan API key.",
+  },
   {
     // Factory Droid's LLM proxy. The base URL is the global residency host; an
     // EU account resolves to `api.eu.factory.ai` from the region recorded in