cartethyia 2.7.9 → 2.8.1

package/src/providers/integrations/zcode-start-plan/provider.ts

@@ -1,16 +1,41 @@
 /**
- * ZCode Start Plan uses the client's three-block Messages prompt fingerprint.
- * Caller instructions remain inside the third block; a fourth block is refused.
- * The bundled prompt/version pair is kept together to preserve upstream bytes.
- * Reference provenance and bounded live acceptance evidence: provider guide.
+ * ZCode Start Plan provider integration.
+ *
+ * The plan lane is an Anthropic Messages endpoint that only accepts the
+ * dressed ZCode client request (see `dress`): the gateway content-inspects the
+ * `system` field and refuses a request without the exact three-block identity
+ * fingerprint with `405 {code:3012}`. The credential is a ZCode login JWT —
+ * pasted, or minted by the sign-in flow (`oauth.ts`).
+ *
+ * Wire facts mirrored from the donor gateway (verified live 2026-10-30):
+ * - `anthropic-beta: mid-conversation-system-2026-04-07` rides every request.
+ * - `metadata.user_id` is a JSON string `{"device_id","account_uuid","session_id"}`
+ *   the gateway reads for attribution; it lives in the body, not a header.
+ * - The LLM identity face carries per-request correlation ids: `x-session-id`,
+ *   `x-request-id`, `x-zcode-trace-id`, `x-query-id`, `x-zcode-query-source`.
+ * - Errors inside an HTTP 200 response come as a `{code,msg,logid}` envelope
+ *   (`1113` grant spent, `3009` model concurrency, `3012` identity gate) and
+ *   are mapped through the shared `classifyUpstreamError`.
  */
 import { randomUUID } from "node:crypto";
 import { release as osRelease } from "node:os";
 
-import type { ApiKeyProviderSpec } from "../../configured-provider";
 import { defineModel } from "../../provider-model-definition";
 import type { ModelDefinition } from "../../provider-model-definition";
 import { getOrCreateInstallId } from "../shared/install-id";
+import { resolveInboundSessionId } from "../../operations/session-resolution";
+import { assertCredentialKind, assertWireFamily } from "../../provider-contracts";
+import type { ProviderAdapter, ProviderDispatchContext, ProviderDispatchTarget } from "../../provider-contracts";
+import { GatewayError } from "../../../protocol/gateway-error";
+import { applyParamQuirks } from "../../../protocol/translation/quirks";
+import { buildClaudeMessagesRequest, filterClaudeCustomHeaders } from "../shared/claude-messages";
+import { mapClaudeHttpError } from "../../../protocol/messages-errors";
+import { isRecord } from "../../../protocol/codecs";
+import { classifyUpstreamError, upstreamErrorIdentifier, upstreamMessageAsIs } from "../../../transport/failure-policy";
+import { parseClaudeSseStream, claudeResponseToEvents } from "../../../protocol/response/messages";
+import { createUpstreamDeadlineLifecycle } from "../../operations/upstream-deadline";
+import type { CanonicalEvent, CanonicalRequest } from "../../../protocol/canonical-model";
+import { parseJwt } from "../../authentication/jwt-validator";
 import prompt from "./zcode_prompt.json";
 
 const CLI_PREFIX: string = prompt.cliPrefix;
@@ -21,8 +46,18 @@ export const ZCODE_START_PLAN_PROVIDER_ID = "zcode-start" as const;
 export const ZCODE_START_PLAN_ENDPOINT_PATH = "/v1/messages" as const;
 export const ZCODE_START_PLAN_BASE_URL = "https://zcode.z.ai/api/v1/zcode-plan/anthropic" as const;
 
-/** Client version the plan endpoint expects in the identity headers. */
+/**
+ * Client version the plan endpoint expects in the identity headers. This is
+ * kept in step with the bundled prompt asset (`zcode_prompt.json`, 3.14.5):
+ * the gateway content-inspects the system blocks, and a version/prompt split
+ * (e.g. 3.16.3 headers over 3.14.5 blocks) risks the 3012 identity gate. Bump
+ * both together only after re-capturing the live blocks and re-verifying.
+ */
 const APP_VERSION = "3.14.5";
+/** Anthropic beta the desktop client sends on the plan lane (captured live). */
+const ANTHROPIC_BETA = "mid-conversation-system-2026-04-07";
+/** The plan gateway enforces a serial per-account in-flight limit; 8192 is the desktop default. */
+const DEFAULT_MAX_TOKENS = 8192;
 
 type Loose = Record<string, unknown>;
 type TextBlock = { type: "text"; text: string; cache_control?: { type: "ephemeral" } };
@@ -40,26 +75,47 @@ function environmentBlock(provider: string, model: string): string {
     .replace("{model}", model);
 }
 
+/** The account uuid carried by the plan JWT, for metadata attribution. */
+function jwtUserId(credential: { secret?: Uint8Array | undefined } | undefined): string {
+  if (!credential?.secret || credential.secret.length === 0) return "";
+  try {
+    const token = new TextDecoder().decode(credential.secret);
+    const parsed = parseJwt(token);
+    const userId = parsed?.payload?.["user_id"];
+    return typeof userId === "string" ? userId : "";
+  } catch {
+    return "";
+  }
+}
+
 /** Identity headers every dispatch carries; the adapter adds Authorization. */
-async function identityHeaders(): Promise<Record<string, string>> {
+async function identityHeaders(context: ProviderDispatchContext): Promise<Record<string, string>> {
+  const sessionId = resolveInboundSessionId(context) ?? `session_${randomUUID().replace(/-/g, "").slice(0, 32)}`;
+  const requestId = randomUUID();
+  const traceId = randomUUID();
+  const queryId = `01a1${requestId.slice(4).replace(/-/g, "").slice(0, 28)}`;
+  const deviceMid = await getOrCreateInstallId("zcode-start-plan");
   return {
     "user-agent": `ZCode/${APP_VERSION} ai-sdk/anthropic/3.0.81`,
     "http-referer": "https://zcode.z.ai",
-    "x-title": "Z Code@cli",
+    "x-title": "Z Code@electron",
     "x-zcode-app-version": APP_VERSION,
     "x-zcode-agent": "glm",
     "x-release-channel": "production",
     "x-client-language": "en-US",
     "x-client-timezone": "Asia/Jakarta",
-    "x-platform": "linux",
+    "x-platform": "linux-x64",
     "x-os-category": "linux",
     "x-os-version": osRelease(),
-    "x-request-id": randomUUID(),
+    "x-request-id": requestId,
+    "x-query-id": queryId,
+    "x-zcode-trace-id": traceId,
     "x-zcode-session-type": "main",
-    "x-zcode-trace-id": randomUUID(),
-    // Keep the persisted install-id filename stable across the provider-ID rename.
-    "x-device-mid": await getOrCreateInstallId("zcode-start-plan"),
+    "x-zcode-query-source": "main_turn",
+    "x-session-id": sessionId,
+    "x-device-mid": deviceMid,
     "anthropic-version": "2023-06-01",
+    "anthropic-beta": ANTHROPIC_BETA,
   };
 }
 
@@ -119,13 +175,160 @@ export const ZCODE_START_PLAN_MODELS: readonly ModelDefinition[] = [
   }),
 ];
 
-/** Start Plan adapter spec: direct upstream, prompt fingerprint, no sidecar. */
-export const ZCODE_START_PLAN_SPEC: ApiKeyProviderSpec = {
-  provider_id: ZCODE_START_PLAN_PROVIDER_ID,
-  base_url: ZCODE_START_PLAN_BASE_URL,
-  endpoint_paths_by_wire_family: { messages: ZCODE_START_PLAN_ENDPOINT_PATH },
-  buildExtraHeaders: () => identityHeaders(),
-  prePayload: (payload) => {
-    dress(payload as Loose);
-  },
-};
+/** True when the body is the ZCode `{code,msg,logid}` business-error envelope. */
+function isZcodeEnvelopeError(body: Record<string, unknown>): boolean {
+  if (body["success"] === false) return true;
+  const code = body["code"];
+  return code !== undefined && ![0, 200, "0", "200"].includes(code as string | number);
+}
+
+/**
+ * Plan-lane Messages adapter. Unlike the plain Anthropic adapter it must (a)
+ * dress the three-block system fingerprint, (b) inject `metadata.user_id`, and
+ * (c) treat a `{code,msg}` envelope inside an HTTP 200 as a refusal — the
+ * gateway reports business errors on success statuses.
+ */
+export class ZcodeStartPlanAdapter implements ProviderAdapter {
+  readonly provider_id = ZCODE_START_PLAN_PROVIDER_ID;
+  private readonly fetchFn: typeof fetch;
+  private readonly baseUrl: string;
+
+  constructor(fetchImpl?: typeof fetch, baseUrl?: string) {
+    this.fetchFn = fetchImpl ?? globalThis.fetch;
+    this.baseUrl = (baseUrl ?? ZCODE_START_PLAN_BASE_URL).replace(/\/+$/, "");
+  }
+
+  async *dispatch(
+    request: CanonicalRequest,
+    candidate: ProviderDispatchTarget,
+    context: ProviderDispatchContext,
+  ): AsyncIterable<CanonicalEvent> {
+    if (candidate.wire_family !== "messages") {
+      assertWireFamily(candidate, "messages", "zcode-start messages leg");
+    }
+    if (context.credential.credential_kind !== "api_key") {
+      assertCredentialKind(context.credential, "api_key", "zcode-start");
+    }
+    if (context.credential.secret === undefined || context.credential.secret.length === 0) {
+      throw new GatewayError(
+        "invalid_request",
+        400,
+        "zcode-start: plan JWT is missing a secret value (request {requestId}). Wrong key, right door — check the credential 🔑",
+      );
+    }
+    const planJwt = new TextDecoder().decode(context.credential.secret);
+    const sessionId = resolveInboundSessionId(context, request) ?? `session_${randomUUID().replace(/-/g, "").slice(0, 32)}`;
+    const deviceMid = await getOrCreateInstallId("zcode-start-plan");
+    const accountUuid = jwtUserId(context.credential);
+    const customHeaders = filterClaudeCustomHeaders({
+      ...context.credential.custom_headers,
+    });
+    const outbound = buildClaudeMessagesRequest({
+      request: applyParamQuirks(request, candidate.provider_id),
+      authHeader: "bearer",
+      credential: { secret: planJwt, customHeaders },
+      baseUrl: this.baseUrl,
+      endpointPath: candidate.endpoint_path,
+      mutatePayload: (payload) => {
+        dress(payload);
+        const metadata = (isRecord(payload["metadata"]) ? payload["metadata"] : {}) as Loose;
+        metadata["user_id"] = JSON.stringify({
+          device_id: deviceMid,
+          account_uuid: accountUuid,
+          session_id: sessionId,
+        });
+        payload.metadata = metadata;
+        if (payload["max_tokens"] == null) payload["max_tokens"] = DEFAULT_MAX_TOKENS;
+        return payload;
+      },
+    });
+    Object.assign(outbound.headers, await identityHeaders(context));
+
+    const outboundFetch = context.outbound_fetch ?? this.fetchFn;
+    const lifecycle = createUpstreamDeadlineLifecycle(context);
+    let response: Response;
+    try {
+      response = await outboundFetch(outbound.url, {
+        method: "POST",
+        headers: outbound.headers,
+        body: outbound.body,
+        signal: lifecycle.signal,
+      });
+    } catch (error: unknown) {
+      lifecycle.release();
+      if (error instanceof GatewayError) throw error;
+      throw new GatewayError(
+        "transport_unavailable",
+        502,
+        `zcode-start upstream fetch failed: ${(error as Error)?.message ?? String(error)}`,
+        {},
+        "network",
+      );
+    }
+    lifecycle.release();
+
+    if (!response.ok) {
+      const bodyText = await response.text().catch(() => "");
+      throw mapClaudeHttpError(response.status, bodyText, response.headers);
+    }
+    const contentType = response.headers.get("content-type") ?? "";
+    if (contentType.toLowerCase().includes("text/event-stream") || request.stream) {
+      if (response.body === null) {
+        throw new GatewayError(
+          "platform_unavailable",
+          502,
+          "zcode-start returned no stream body (request {requestId}). The upstream came back empty-handed — retry 🌙",
+          {},
+          "upstream",
+        );
+      }
+      yield* parseClaudeSseStream(response.body, context.abort_signal, false);
+      return;
+    }
+    const bodyText = await response.text().catch(() => "");
+    let json: unknown;
+    try {
+      json = JSON.parse(bodyText) as unknown;
+    } catch {
+      const upstreamText = upstreamMessageAsIs(bodyText, "");
+      throw new GatewayError(
+        "platform_unavailable",
+        502,
+        upstreamText.message || "zcode-start response is not valid JSON (request {requestId}). The upstream came back empty-handed — retry 🌙",
+        { raw: bodyText.slice(0, 4096) },
+        "upstream",
+      );
+    }
+    if (!isRecord(json)) {
+      throw new GatewayError(
+        "platform_unavailable",
+        502,
+        "zcode-start response must be an object (request {requestId}). The upstream came back empty-handed — retry 🌙",
+        {},
+        "upstream",
+      );
+    }
+    if (isZcodeEnvelopeError(json)) {
+      const identifier = upstreamErrorIdentifier(json);
+      const classification = classifyUpstreamError(undefined, identifier);
+      const upstreamText = upstreamMessageAsIs(json, "");
+      throw new GatewayError(
+        classification.code,
+        classification.status,
+        upstreamText.message || "zcode-start reported an upstream error",
+        {
+          providerId: this.provider_id,
+          ...(identifier === undefined ? {} : { providerCode: identifier }),
+          ...(upstreamText.hadUpstreamText ? { upstreamMessageAsIs: true } : {}),
+          raw: bodyText.slice(0, 4096),
+        },
+        classification.origin,
+      );
+    }
+    yield* claudeResponseToEvents(json, request, false);
+  }
+}
+
+export function createZcodeStartPlanAdapter(fetchImpl?: typeof fetch): ProviderAdapter {
+  return new ZcodeStartPlanAdapter(fetchImpl);
+}

package/src/providers/integrations/zcode-start-plan/quota.ts

@@ -1,9 +1,23 @@
+import { createHash } from "node:crypto";
 import { asCoercedNumber, asRecord, asTrimmedString } from "../../../shared/coerce";
 import type { FetchLike, ProviderQuotaResult, ProviderQuotaWindow } from "../../quota/quota-contracts";
 
 const BALANCE_URL = "https://zcode.z.ai/api/v1/zcode-plan/billing/balance?app_version=3.16.3";
-const DEVICE_MID = "9f1b0d4e-3c2a-4e7b-9f1d-6a2c8b5e0d31";
 const APP_VERSION = "3.16.3";
+const PLATFORM = "linux-x64";
+
+/**
+ * Stable per-account device mid. The gateway validates `X-Device-Mid` as a
+ * UUID (billing answers `3001 parameter error` without it) and attributes
+ * usage to it; a hardcoded shared UUID would lump every account into one
+ * billing identity. Derivation matches the gift-claim device id, so quota and
+ * claim present the same device per account.
+ */
+function deviceMid(accountId: string): string {
+  const hash = createHash("sha256").update(`zcode-device\0${accountId}`).digest("hex");
+  const variant = ((parseInt(hash[16] as string, 16) & 3) | 8).toString(16);
+  return `${hash.slice(0, 8)}-${hash.slice(8, 12)}-4${hash.slice(13, 16)}-${variant}${hash.slice(17, 20)}-${hash.slice(20, 32)}`;
+}
 
 function instant(value: unknown): string | null {
   const seconds = asCoercedNumber(value);
@@ -57,16 +71,19 @@ function samePlan(bucket: Record<string, unknown>, plan: Record<string, unknown>
 export async function fetchZcodeStartPlanQuota(
   credential: string,
   fetcher: FetchLike,
+  context?: { accountId?: string },
 ): Promise<ProviderQuotaResult> {
   const source = "zcode-start";
   try {
+    const accountId = context?.accountId ?? credential.trim();
     const response = await fetcher(BALANCE_URL, {
       headers: {
         authorization: `Bearer ${credential}`,
         accept: "application/json",
-        "x-device-mid": DEVICE_MID,
+        "x-device-mid": deviceMid(accountId),
         "x-zcode-app-version": APP_VERSION,
         "x-client-language": "en-US",
+        "x-platform": PLATFORM,
       },
       signal: AbortSignal.timeout(15_000),
     });

package/src/providers/integrations/zro/zro.ts

@@ -0,0 +1,205 @@
+// Zro provider integration — TypeScript, Zro (moonmath).
+//
+// Zro exposes three wire formats: OpenAI Chat (`/v1/chat/completions`),
+// OpenAI Responses (`/v1/responses`), and Anthropic Messages
+// (`/v1/messages`). Claude Code talks to it through the Messages wire with a
+// plain `Authorization: Bearer sk-...` key (no `x-api-key`, no CLI
+// fingerprint) — verified live 2026-11-09 that the Anthropic envelope +
+// bearer auth answers 200, and that the full Claude Code header set
+// (`anthropic-version`, Stainless identity, official user-agent) is accepted
+// but not required. Every model is served over Messages in this integration,
+// matching how the provider's own Claude Code docs route traffic.
+//
+// Quota: Zro publishes no billing/quota endpoint (all probe guesses 404).
+// The entitlement surface is `GET /v1/models` itself — a key only sees the
+// models it is allowed to call (verified: a key with 3 models got 403
+// `user_model_access_denied` for a 4th), and an invalid key answers 401 there.
+// The quota collector probes that same `/v1/models` surface, and model
+// discovery owns the entitlement truth.
+
+import { assertCredentialKind, assertWireFamily } from "../../provider-contracts";
+import type { ProviderAdapter, ProviderDispatchContext, ProviderDispatchTarget } from "../../provider-contracts";
+import type { ModelDefinition } from "../../provider-model-definition";
+import { defineModel } from "../../provider-model-definition";
+import type { ProviderModelDiscovery } from "../../discovery/discovery-types";
+import type { FetchLike, ProviderQuotaResult } from "../../quota/quota-contracts";
+import type { CanonicalEvent, CanonicalRequest } from "../../../protocol/canonical-model";
+import { GatewayError } from "../../../protocol/gateway-error";
+import { applyParamQuirks } from "../../../protocol/translation/quirks";
+import { buildClaudeMessagesRequest, filterClaudeCustomHeaders } from "../shared/claude-messages";
+import { sendClaudeMessagesRequest } from "../../../protocol/upstream/send-claude-messages";
+
+export const ZRO_PROVIDER_ID = "zro" as const;
+export const ZRO_BASE_URL = "https://zro.moonmath.ai";
+
+/**
+ * Offline fallback for the models this key is entitled to, used when the live
+ * `/v1/models` read fails or returns nothing. The three rows are exactly the
+ * reachable set of the probe key (each also carries a `zro/` alias on the
+ * wire); a live read may show more or fewer and replaces this seed entirely.
+ */
+const ZRO_MODELS_RAW: readonly {
+  id: string;
+  contextLimit: number;
+  outputLimit: number;
+}[] = [
+  { id: "deepseek-v4-flash-0731", contextLimit: 1_048_576, outputLimit: 64_000 },
+  { id: "deepseek-v4.1-flash", contextLimit: 1_048_576, outputLimit: 64_000 },
+] as const;
+
+export const ZRO_MODELS: readonly ModelDefinition[] = ZRO_MODELS_RAW.map((row) =>
+  defineModel({
+    id: row.id,
+    providerId: ZRO_PROVIDER_ID,
+    wireFamily: "messages",
+    // The Messages wire root is `/v1/messages` on Zro's host, not the
+    // family-conventional `/messages` path `defineModel` would otherwise pick.
+    endpoint: "/v1/messages",
+    ctx: row.contextLimit,
+    out: row.outputLimit,
+    vision: false,
+    reasoning: true,
+    toolCall: true,
+    // The reachable rows are the free-limited allowance this key can call; the
+    // dashboard groups them under "Free models (auto)".
+    freeTier: true,
+  }),
+);
+
+/**
+ * Zro model discovery. The live `/v1/models` list is the *entitlement*
+ * surface: it returns only the models a key may call (verified live
+ * 2026-11-09 — a key with 3 models got 403 for a 4th; the public `/models`
+ * catalog without the `/v1` prefix lists everything, including models the key
+ * is refused). The `/v1` prefix is therefore mandatory. Each row appears
+ * twice on the wire (bare id + `zro/` alias); the alias is folded onto the
+ * bare id. Every listed row is forced onto the Messages wire, mirroring the
+ * offline catalog.
+ */
+export function zroModelDiscovery(): () => Promise<ProviderModelDiscovery> {
+  return async () => async (input) => {
+    // dynamic-import: cycle-break — model discovery is only imported at call time,
+    // so a provider that never runs discovery never pays for the OpenAI discovery graph.
+    const { fetchOpenAICompatibleModels } = await import("../../discovery/openai-model-discovery");
+    const base = input.baseUrl.replace(/\/+$/, "");
+    const models = await fetchOpenAICompatibleModels({
+      // `/v1` is the entitlement surface; the bare `/models` path is the
+      // public full catalog and would advertise models the key cannot call.
+      baseUrl: `${base}/v1`,
+      providerId: ZRO_PROVIDER_ID,
+      headers: { authorization: `Bearer ${input.credential}` },
+      ...(input.fetcher ? { fetcher: input.fetcher } : {}),
+    });
+    const source: readonly ModelDefinition[] =
+      models === null || models.length === 0 ? ZRO_MODELS : models;
+    const byId = new Map<string, ModelDefinition>();
+    for (const model of source) {
+      const raw = model.modelId;
+      const bare = raw.toLowerCase().startsWith("zro/") ? raw.slice("zro/".length) : raw;
+      byId.set(bare, { ...model, modelId: bare });
+    }
+    return [...byId.values()].map((model) => ({
+      ...model,
+      wireFamily: "messages" as const,
+      endpointPath: "/v1/messages",
+      // The `/v1/models` list is by definition the set this key may call on
+      // the free-limited allowance, so every discovered row is free-tier.
+      freeTier: true,
+    }));
+  };
+}
+
+/**
+ * Messages-wire adapter. Same Claude pipeline as the plain Anthropic adapter,
+ * but Zro authenticates with a Bearer key instead of `x-api-key` — the same
+ * shape as InferHub's Claude leg.
+ */
+export class ZroMessagesAdapter implements ProviderAdapter {
+  readonly provider_id = ZRO_PROVIDER_ID;
+  private readonly fetchFn: typeof fetch;
+  private readonly baseUrl: string;
+
+  constructor(fetchImpl?: typeof fetch, baseUrl?: string) {
+    this.fetchFn = fetchImpl ?? globalThis.fetch;
+    this.baseUrl = (baseUrl ?? ZRO_BASE_URL).replace(/\/+$/, "");
+  }
+
+  async *dispatch(
+    request: CanonicalRequest,
+    candidate: ProviderDispatchTarget,
+    context: ProviderDispatchContext,
+  ): AsyncIterable<CanonicalEvent> {
+    if (candidate.wire_family !== "messages") {
+      assertWireFamily(candidate, "messages", "zro messages leg");
+    }
+    if (context.credential.credential_kind !== "api_key") {
+      assertCredentialKind(context.credential, "api_key", "zro");
+    }
+    if (context.credential.secret === undefined || context.credential.secret.length === 0) {
+      throw new GatewayError(
+        "invalid_request",
+        400,
+        "zro: API key is missing a secret value (request {requestId}). Wrong key, right door — check the key 🔑",
+      );
+    }
+    const apiKey = new TextDecoder().decode(context.credential.secret);
+    const customHeaders = filterClaudeCustomHeaders({
+      ...context.credential.custom_headers,
+    });
+    const outbound = buildClaudeMessagesRequest({
+      request: applyParamQuirks(request, candidate.provider_id),
+      authHeader: "bearer",
+      credential: { secret: apiKey, customHeaders },
+      baseUrl: this.baseUrl,
+      endpointPath: candidate.endpoint_path,
+    });
+    yield* sendClaudeMessagesRequest(
+      outbound.url,
+      outbound.headers,
+      outbound.body,
+      context,
+      request,
+      this.fetchFn,
+    );
+  }
+}
+
+export function createZroAdapter(fetchImpl?: typeof fetch): ProviderAdapter {
+  return new ZroMessagesAdapter(fetchImpl);
+}
+
+/**
+ * Zro quota collector. Zro publishes no billing/quota endpoint; the
+ * entitlement surface is `GET /v1/models` — a key only sees the models it may
+ * call, and an invalid key answers 401/403 (verified live 2026-11-09). The
+ * bare `/models` path is the public full catalog and does NOT authenticate, so
+ * the `/v1` prefix is mandatory here.
+ */
+export async function fetchZroQuota(
+  credential: string,
+  fetcher: FetchLike,
+): Promise<ProviderQuotaResult> {
+  const fetchFn = fetcher ?? globalThis.fetch;
+  let response: Response;
+  try {
+    response = await fetchFn(`${ZRO_BASE_URL}/v1/models`, {
+      headers: { accept: "application/json", authorization: `Bearer ${credential.trim()}` },
+      signal: AbortSignal.timeout(15_000),
+    });
+  } catch (error) {
+    return {
+      source: ZRO_PROVIDER_ID,
+      plan: null,
+      windows: [],
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+  if (response.status === 401 || response.status === 403) {
+    return { source: ZRO_PROVIDER_ID, plan: null, windows: [], error: "API key is invalid or revoked." };
+  }
+  if (!response.ok) {
+    return { source: ZRO_PROVIDER_ID, plan: null, windows: [], error: `Connectivity check failed: HTTP ${response.status}.` };
+  }
+  await response.text().catch(() => "");
+  return { source: ZRO_PROVIDER_ID, plan: "limited", windows: [], error: null };
+}