cartethyia 2.8.0 → 2.8.1

package/src/providers/integrations/deepai/deepai-catalog.ts

@@ -0,0 +1,149 @@
+// DeepAI model catalog + discovery.
+//
+// All 22 rows below were fetched live from `GET /deepai_code/models` on
+// 2026-11-11 (see `documentation/research/deepai/2026-11-11-deepai-code-live-wire-verification.md`).
+// The 11 zero-Theos rows carry the daily free-tier allowance (`freeTier: true`
+// + `free: true` — they bill zero and do not draw from the balance). The
+// metered rows keep their `theosPerRequest` price as a per-request cost
+// estimate for the operator.
+//
+// Wire routing: every row is a chat-wire model except `gpt-6-astra`, which the
+// upstream serves only on `/responses` (verified live: it answers 400
+// `model_not_found` on `/chat/completions`, and the rest answer 400 on
+// `/responses`).
+import type { ModelDefinition } from "../../provider-model-definition";
+import { defineModel } from "../../provider-model-definition";
+import {
+  DEEPAI_CHAT_PATH,
+  DEEPAI_HEADER_INSTANCE,
+  DEEPAI_HEADER_THEOS,
+  DEEPAI_LANE_VERSION,
+  DEEPAI_MODELS_PATH,
+  DEEPAI_RESPONSES_PATH,
+  deepAIInstanceId,
+} from "./deepai-common";
+
+interface DeepAIRosterRow {
+  readonly id: string;
+  readonly name: string;
+  readonly reasoning: boolean;
+  readonly vision: boolean;
+  readonly ctx: number;
+  readonly out: number;
+  readonly theosPerRequest: number;
+  readonly responsesWire?: boolean;
+}
+
+const DEEPAI_ROSTER: readonly DeepAIRosterRow[] = [
+  { id: "glm-5.3-flash", name: "GLM 5.3 Flash", reasoning: true, vision: true, ctx: 1_048_576, out: 131_072, theosPerRequest: 0 },
+  { id: "deepseek-v4.1-flash", name: "DeepSeek V4.1 Flash 1017", reasoning: true, vision: true, ctx: 1_048_576, out: 131_072, theosPerRequest: 0 },
+  { id: "mimo-2.6-flash", name: "MiMo 2.6 Flash", reasoning: true, vision: true, ctx: 1_048_576, out: 131_072, theosPerRequest: 0 },
+  { id: "qwen-3.8-flash", name: "Qwen 3.8 Flash", reasoning: true, vision: true, ctx: 991_000, out: 128_000, theosPerRequest: 0 },
+  { id: "minimax-m3.1-flash", name: "MiniMax M3.1 Flash", reasoning: true, vision: true, ctx: 1_048_576, out: 131_072, theosPerRequest: 0 },
+  { id: "solar-mini-4", name: "Solar Mini 4", reasoning: true, vision: false, ctx: 524_288, out: 131_072, theosPerRequest: 0 },
+  { id: "gpt-6-luna", name: "GPT-6 Luna", reasoning: true, vision: true, ctx: 1_048_576, out: 128_000, theosPerRequest: 0 },
+  { id: "mimo-2.6-pro", name: "MiMo 2.6 Pro", reasoning: true, vision: true, ctx: 1_048_576, out: 131_072, theosPerRequest: 0 },
+  { id: "crouton-alpha", name: "Crouton Alpha", reasoning: true, vision: true, ctx: 1_048_576, out: 131_072, theosPerRequest: 0 },
+  { id: "glyph-cluster", name: "Glyph Cluster", reasoning: true, vision: false, ctx: 256_000, out: 131_072, theosPerRequest: 0 },
+  { id: "deepai-cyber", name: "DeepAI Cyber", reasoning: true, vision: false, ctx: 1_048_576, out: 131_072, theosPerRequest: 0 },
+  { id: "minimax-m3", name: "MiniMax M3", reasoning: true, vision: false, ctx: 512_000, out: 131_000, theosPerRequest: 2 },
+  { id: "gpt-6.1-sol", name: "GPT-6.1 Sol", reasoning: true, vision: true, ctx: 1_048_576, out: 128_000, theosPerRequest: 10 },
+  { id: "gemini-4-argon", name: "Gemini 4 Argon", reasoning: true, vision: true, ctx: 1_048_576, out: 131_072, theosPerRequest: 10 },
+  { id: "glm-5.3", name: "GLM 5.3", reasoning: true, vision: false, ctx: 1_048_576, out: 131_072, theosPerRequest: 3 },
+  { id: "kimi-k3", name: "Kimi K3", reasoning: true, vision: true, ctx: 1_048_576, out: 131_072, theosPerRequest: 3 },
+  { id: "muse-spark-1.3", name: "Muse Spark 1.3", reasoning: true, vision: true, ctx: 1_048_576, out: 131_072, theosPerRequest: 6 },
+  { id: "claude-opus-5-5", name: "Claude Opus 5.5", reasoning: true, vision: true, ctx: 1_000_000, out: 64_000, theosPerRequest: 15 },
+  { id: "muse-wonder", name: "Muse Wonder", reasoning: true, vision: true, ctx: 1_048_576, out: 131_072, theosPerRequest: 15 },
+  { id: "qwen-3.8-max-prime", name: "Qwen 3.8 Max Prime", reasoning: true, vision: true, ctx: 1_000_000, out: 131_072, theosPerRequest: 15 },
+  { id: "claude-fable-5-2", name: "Claude Fable 5.2", reasoning: true, vision: true, ctx: 1_000_000, out: 64_000, theosPerRequest: 20 },
+  { id: "gpt-6-astra", name: "GPT-6 Astra", reasoning: true, vision: true, ctx: 1_048_576, out: 128_000, theosPerRequest: 50, responsesWire: true },
+];
+
+function rowToModel(row: DeepAIRosterRow): ModelDefinition {
+  const free = row.theosPerRequest === 0;
+  return defineModel({
+    id: row.id,
+    providerId: "deepai",
+    wireFamily: row.responsesWire === true ? "responses" : "chat",
+    endpoint: row.responsesWire === true ? DEEPAI_RESPONSES_PATH : DEEPAI_CHAT_PATH,
+    ctx: row.ctx,
+    out: row.out,
+    vision: row.vision,
+    reasoning: row.reasoning,
+    toolCall: true,
+    ...(free ? { free: true, freeTier: true } : {}),
+  });
+}
+
+/** Static roster — the live-verified free tier plus metered rows. */
+export const DEEPAI_DEFAULT_MODELS: readonly ModelDefinition[] =
+  DEEPAI_ROSTER.map(rowToModel);
+
+/** Live `/deepai_code/models` listing. */
+export async function discoverDeepAIModels(options: {
+  readonly baseUrl: string;
+  readonly fetcher?: typeof fetch;
+}): Promise<readonly ModelDefinition[] | null> {
+  const fetcher = options.fetcher ?? fetch;
+  const url = `${options.baseUrl.replace(/\/+$/, "")}${DEEPAI_MODELS_PATH}`;
+  try {
+    const response = await fetcher(url, {
+      headers: {
+        accept: "application/json",
+        // The catalog is lane-aware: the 22-row roster only comes back with the
+        // lane headers (verified live 2026-11-11 — bare GET returns a smaller
+        // 9-row default roster).
+        [DEEPAI_HEADER_THEOS]: DEEPAI_LANE_VERSION,
+        [DEEPAI_HEADER_INSTANCE]: deepAIInstanceId(),
+      },
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!response.ok) return null;
+    const payload = (await response.json()) as unknown;
+    const list = payload !== null && typeof payload === "object" && Array.isArray((payload as { models?: unknown }).models)
+      ? ((payload as { models: unknown }).models as readonly Record<string, unknown>[])
+      : null;
+    if (list === null || list.length === 0) return null;
+    const rows: DeepAIRosterRow[] = [];
+    for (const entry of list) {
+      const id = typeof entry.id === "string" && entry.id.trim() ? entry.id.trim() : null;
+      if (id === null) continue;
+      // `theosPerRequest` arrives as a string ("0", "2", "50") or a number.
+      const theosNumber = parseTheosAmount(entry.theosPerRequest);
+      const input = entry.input;
+      const hasImage = Array.isArray(input) && input.some((m) => m === "image");
+      rows.push({
+        id,
+        name: typeof entry.name === "string" ? entry.name : id,
+        reasoning: entry.reasoning === true,
+        vision: hasImage,
+        ctx: positiveInt(entry.contextWindow) ?? positiveInt(entry.context_window) ?? 1_048_576,
+        out: positiveInt(entry.maxTokens) ?? positiveInt(entry.max_completion_tokens) ?? 131_072,
+        theosPerRequest: theosNumber,
+        responsesWire: entry.api === "openai-responses",
+      });
+    }
+    if (rows.length === 0) return null;
+    return rows.map(rowToModel);
+  } catch {
+    return null;
+  }
+}
+
+function positiveInt(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : null;
+}
+
+/** Parses `theosPerRequest` — a numeric string ("0"/"50") or a number. */
+function parseTheosAmount(value: unknown): number {
+  if (typeof value === "number" && Number.isFinite(value)) return Math.max(0, value);
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (/^\d+(?:\.\d+)?$/.test(trimmed)) {
+      const n = Number(trimmed);
+      if (Number.isFinite(n)) return Math.max(0, n);
+    }
+  }
+  // Absent / unparseable means the server did not meter it → free.
+  return 0;
+}

package/src/providers/integrations/deepai/deepai-common.ts

@@ -0,0 +1,145 @@
+// DeepAI shared wire helpers.
+//
+// Wire facts reconstructed from the DeepAI Code 0.3.35 bundle and verified
+// live 2026-11-11 (see `documentation/research/deepai/`):
+//
+//   - Model base is `https://api.deepai.org/deepai_code`; the sign-in flow
+//     (`/deepai_code/desktop_auth/`) returns an opaque `api_key`.
+//   - Every model call carries:
+//       `X-DeepAI-Code-Theos: 4`   (lane version)
+//       `X-DeepAI-Code-Instance`     (16 random bytes hex, per process)
+//       `X-DeepAI-Code-Machine`      (sha256hex of the machine id)
+//       `Api-Key: <api_key>`         (the credential; NOT a Bearer)
+//   - The machine header is a digest of a platform identifier (SMBIOS UUID /
+//     MachineGuid / `/etc/machine-id`); the raw identifier never leaves the
+//     machine. The grant is bound to the account, not the machine, so a
+//     missing/mangled machine header is tolerated (verified live).
+import { randomBytes } from "node:crypto";
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { readFileSync } from "node:fs";
+
+export const DEEPAI_PROVIDER_ID = "deepai" as const;
+export const DEEPAI_API_ORIGIN = "https://api.deepai.org";
+export const DEEPAI_MODEL_BASE = `${DEEPAI_API_ORIGIN}/deepai_code`;
+
+export const DEEPAI_LANE_VERSION = "4";
+export const DEEPAI_HEADER_THEOS = "X-DeepAI-Code-Theos";
+export const DEEPAI_HEADER_INSTANCE = "X-DeepAI-Code-Instance";
+export const DEEPAI_HEADER_MACHINE = "X-DeepAI-Code-Machine";
+export const DEEPAI_HEADER_API_KEY = "Api-Key";
+
+export const DEEPAI_CHAT_PATH = "/deepai_code/chat/completions";
+export const DEEPAI_RESPONSES_PATH = "/deepai_code/responses";
+export const DEEPAI_MODELS_PATH = "/deepai_code/models";
+export const DEEPAI_THEOS_PATH = "/deepai_code/theos";
+export const DEEPAI_USAGE_SUMMARY_PATH = "/get_usage_summary";
+export const DEEPAI_SIGNIN_PATH = "/deepai_code/desktop_auth/";
+export const DEEPAI_EXCHANGE_PATH = "/deepai_code/desktop_auth/exchange/";
+
+const UUID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+const SMBIOS_PLACEHOLDERS = new Set([
+  "00000000-0000-0000-0000-000000000000",
+  "ffffffff-ffff-ffff-ffff-ffffffffffff",
+  "03000200-0400-0500-0006-000700080009",
+]);
+
+function run(file: string, args: readonly string[]): Promise<string> {
+  return new Promise((resolve) => {
+    execFile(
+      file,
+      [...args],
+      { encoding: "utf8", timeout: 10_000, windowsHide: true },
+      (error, stdout) => resolve(error ? "" : stdout),
+    );
+  });
+}
+
+function parseSmbiosUUID(output: string): string | null {
+  const uuid = UUID_RE.exec(output)?.[0]?.toLowerCase() ?? null;
+  return uuid && !SMBIOS_PLACEHOLDERS.has(uuid) ? uuid : null;
+}
+
+function parseMachineGuid(regQuery: string): string | null {
+  const match = /MachineGuid\s+REG_SZ\s+(\S+)/.exec(regQuery);
+  return match?.[1] && UUID_RE.test(match[1]) ? match[1].toLowerCase() : null;
+}
+
+function parseLinuxMachineId(file: string): string | null {
+  const id = file.trim().toLowerCase();
+  return /^[0-9a-f]{32}$/.test(id) && !/^0+$/.test(id) ? id : null;
+}
+
+function detectMachineId(): Promise<string | null> {
+  try {
+    if (process.platform === "win32") {
+      return (async () => {
+        const smbios = await run("powershell", [
+          "-NoProfile",
+          "-NonInteractive",
+          "-Command",
+          "(Get-CimInstance Win32_ComputerSystemProduct).UUID",
+        ]);
+        const uuid = parseSmbiosUUID(smbios);
+        if (uuid) return uuid;
+        const guid = await run("reg", [
+          "query",
+          "HKLM\\SOFTWARE\\Microsoft\\Cryptography",
+          "/v",
+          "MachineGuid",
+        ]);
+        return parseMachineGuid(guid);
+      })();
+    }
+    if (process.platform === "darwin") {
+      return (async () => {
+        const ioreg = await run("ioreg", ["-rd1", "-c", "IOPlatformExpertDevice"]);
+        const match = /"IOPlatformUUID"\s*=\s*"([^"]+)"/.exec(ioreg);
+        return match?.[1] && UUID_RE.test(match[1]) ? match[1].toLowerCase() : null;
+      })();
+    }
+    for (const path of ["/etc/machine-id", "/var/lib/dbus/machine-id"]) {
+      try {
+        const id = parseLinuxMachineId(readFileSync(path, "utf8"));
+        if (id) return Promise.resolve(id);
+      } catch {
+        // try the next path
+      }
+    }
+    return Promise.resolve(null);
+  } catch {
+    return Promise.resolve(null);
+  }
+}
+
+let machineDigestPromise: Promise<string | null> | undefined;
+
+/** sha256hex(machineId), computed once per process; null when unreadable. */
+export function deepAIMachineDigest(): Promise<string | null> {
+  machineDigestPromise ??= detectMachineId().then(
+    (raw) => (raw === null ? null : createHash("sha256").update(raw).digest("hex")),
+  );
+  return machineDigestPromise;
+}
+
+/** Fresh per-process instance id (16 random bytes hex). */
+export function deepAIInstanceId(): string {
+  return randomBytes(16).toString("hex");
+}
+
+/**
+ * Baseline DeepAI headers shared by every model API call. `apiKey` is the
+ * account credential (the sign-in `api_key`); omit it for unauthenticated
+ * reads (model catalog).
+ */
+export async function deepAIBaseHeaders(apiKey?: string): Promise<Record<string, string>> {
+  const headers: Record<string, string> = {
+    "content-type": "application/json",
+    [DEEPAI_HEADER_THEOS]: DEEPAI_LANE_VERSION,
+    [DEEPAI_HEADER_INSTANCE]: deepAIInstanceId(),
+  };
+  const machine = await deepAIMachineDigest();
+  if (machine !== null) headers[DEEPAI_HEADER_MACHINE] = machine;
+  if (apiKey !== undefined && apiKey.length > 0) headers[DEEPAI_HEADER_API_KEY] = apiKey;
+  return headers;
+}

package/src/providers/integrations/deepai/deepai-oauth.ts

@@ -0,0 +1,129 @@
+// DeepAI browser login client.
+//
+// DeepAI's desktop sign-in is a loopback flow: the app builds
+// `https://api.deepai.org/deepai_code/desktop_auth/?state=<state>&port=<port>`,
+// the operator signs in in the browser, and the server redirects to
+// `http://127.0.0.1:<port>/callback?code=<code>&state=<state>`. The code is
+// then exchanged at `/deepai_code/desktop_auth/exchange/` for an opaque
+// `api_key`. There is no PKCE verifier and no refresh token — the key is
+// long-lived and the flow is re-run when needed.
+//
+// Verified live 2026-11-11: the exchange answers 200 with
+// `{ api_key, username, is_pro }`, and the api_key authenticates the model
+// API via the `Api-Key` header (a Bearer or `x-api-key` spelling is rejected
+// with 401).
+import { randomBytes } from "node:crypto";
+import { OAuthClient } from "../../authentication/oauth-client";
+import type {
+  OAuthAuthorizeRequest,
+  OAuthCodeExchangeContext,
+  OAuthExchangeResult,
+  OAuthImportInput,
+} from "../../authentication/oauth-flow-store";
+import {
+  DEEPAI_API_ORIGIN,
+  DEEPAI_EXCHANGE_PATH,
+  DEEPAI_THEOS_PATH,
+  deepAIBaseHeaders,
+} from "./deepai-common";
+
+const DEEPAI_LOGIN_TTL_MS = 365 * 24 * 60 * 60 * 1000;
+
+function loopbackPortFromRedirectUri(redirectUri: string): number {
+  const url = new URL(redirectUri);
+  const port = Number(url.port);
+  if (!Number.isInteger(port) || port <= 0 || port > 65_535) {
+    throw new Error("deepai: redirect URI names an invalid loopback port");
+  }
+  return port;
+}
+
+export class DeepAIOAuthClient extends OAuthClient {
+  override readonly supportsDeviceCode = false;
+  override readonly supportsBrowserCode = true;
+  override readonly providerLabel = "deepai";
+  override readonly clientId = "";
+  override readonly tokenUrl = "";
+  override readonly scopes = "";
+
+  /**
+   * DeepAI's hosted sign-in validates the state as 32 hex characters; the
+   * shared base64url state (which can contain `-`/`_`) is rejected with
+   * "Invalid desktop sign-in request".
+   */
+  override generateState(): string {
+    return randomBytes(16).toString("hex");
+  }
+
+  /** DeepAI's hosted sign-in URL, carrying the loopback port + state. */
+  override buildAuthorizeUrl(request: OAuthAuthorizeRequest): string {
+    const port = loopbackPortFromRedirectUri(request.redirectUri);
+    const signIn = new URL(DEEPAI_EXCHANGE_PATH.replace("/desktop_auth/exchange/", "/desktop_auth/"), DEEPAI_API_ORIGIN);
+    signIn.search = "";
+    signIn.searchParams.set("state", request.state);
+    signIn.searchParams.set("port", String(port));
+    return signIn.toString();
+  }
+
+  /** Exchanges the callback code for the DeepAI api_key. */
+  override async exchangeCode(
+    code: string,
+    _codeVerifier: string,
+    _redirectUri: string,
+    _state?: string,
+    _context?: OAuthCodeExchangeContext,
+  ): Promise<OAuthExchangeResult> {
+    const response = await this.fetchFn(new URL(DEEPAI_EXCHANGE_PATH, DEEPAI_API_ORIGIN), {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json" },
+      body: JSON.stringify({ code }),
+    });
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      throw new Error(`deepai sign-in exchange failed: HTTP ${response.status} ${text.slice(0, 300)}`);
+    }
+    return this.parseExchangeBody(await response.json());
+  }
+
+  /** Accepts a pasted DeepAI api_key, validated against `/theos`. */
+  async importCredential(input: OAuthImportInput): Promise<OAuthExchangeResult> {
+    const apiKey = input.credential.trim();
+    if (!apiKey) throw new Error("deepai: pasted API key is empty");
+    const headers = await deepAIBaseHeaders(apiKey);
+    const response = await this.fetchFn(new URL(DEEPAI_THEOS_PATH, DEEPAI_API_ORIGIN), {
+      method: "GET",
+      headers,
+    });
+    if (!response.ok) {
+      throw new Error(
+        `deepai: API key validation failed (HTTP ${response.status}) — paste a key minted by the DeepAI sign-in flow`,
+      );
+    }
+    return {
+      access: apiKey,
+      refresh: apiKey,
+      expiresAt: new Date(Date.now() + DEEPAI_LOGIN_TTL_MS),
+      accountLabel: input.accountLabel || "deepai",
+      auth_state: { via: "import" },
+    };
+  }
+
+  private parseExchangeBody(body: unknown): OAuthExchangeResult {
+    const record = body !== null && typeof body === "object" ? (body as Record<string, unknown>) : null;
+    const apiKey = typeof record?.api_key === "string" ? record.api_key.trim() : "";
+    if (!apiKey || /[\r\n]/.test(apiKey)) {
+      throw new Error("deepai: sign-in response did not carry a valid api_key");
+    }
+    const username = typeof record?.username === "string" ? record.username : "";
+    return {
+      access: apiKey,
+      refresh: apiKey,
+      expiresAt: new Date(Date.now() + DEEPAI_LOGIN_TTL_MS),
+      ...(username ? { accountLabel: username, accountName: username } : {}),
+      auth_state: { is_pro: record?.is_pro === true },
+    };
+  }
+}
+
+/** Shared DeepAI browser-login client instance (registry-facing). */
+export const deepAIOAuthClient = new DeepAIOAuthClient();

package/src/providers/integrations/deepai/deepai-quota.ts

@@ -0,0 +1,97 @@
+// DeepAI quota collector.
+//
+// Reads the account's DeepAI allowance from `GET /deepai_code/theos`
+// (`balance`/`granted`/`refresh_at`), which is the daily free-tier grant. The
+// entitlement surface (`/get_usage_summary`, `is_pro`) is probed second to
+// distinguish a free vs pro account. Both calls require the `Api-Key` header
+// (not Bearer).
+import type {
+  FetchLike,
+  ProviderQuotaResult,
+  ProviderQuotaWindow,
+} from "../../quota/quota-contracts";
+import { cleanError, number, percentWindow, text } from "../../quota/quota-contracts";
+import type { QuotaCollectionContext } from "../../quota/quota-support";
+import {
+  DEEPAI_API_ORIGIN,
+  DEEPAI_THEOS_PATH,
+  DEEPAI_USAGE_SUMMARY_PATH,
+  deepAIBaseHeaders,
+} from "./deepai-common";
+
+const LABEL = "DeepAI";
+
+async function readJson(
+  url: string,
+  headers: Record<string, string>,
+  fetcher: FetchLike,
+): Promise<Record<string, unknown> | null> {
+  try {
+    const res = await fetcher(url, {
+      method: "GET",
+      headers,
+      signal: AbortSignal.timeout(15_000),
+    });
+    if (!res.ok) return null;
+    const parsed = (await res.json()) as unknown;
+    return parsed !== null && typeof parsed === "object" ? (parsed as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Reads the DeepAI allowance and returns a normalized result.
+ *
+ * The Daily Theos window is pooled (the balance funds model calls) with the
+ * daily grant as the ceiling and the account's `refresh_at` as the reset. The
+ * plan is `free` when the allowance is enabled, `pro` when `is_pro` reads
+ * true from the usage summary.
+ */
+export async function fetchDeepAIQuota(
+  credential: string,
+  fetcher: FetchLike,
+  _context?: QuotaCollectionContext,
+): Promise<ProviderQuotaResult> {
+  try {
+    const apiKey = text(credential);
+    if (!apiKey) {
+      return { source: LABEL, plan: null, windows: [], error: "DeepAI credential missing" };
+    }
+    const headers = await deepAIBaseHeaders(apiKey);
+    const theos = await readJson(`${DEEPAI_API_ORIGIN}${DEEPAI_THEOS_PATH}`, headers, fetcher);
+    if (!theos) {
+      return { source: LABEL, plan: null, windows: [], error: "DeepAI /theos endpoint unavailable" };
+    }
+
+    const windows: ProviderQuotaWindow[] = [];
+    const enabled = theos.enabled === true;
+    const granted = number(theos.granted);
+    const balance = number(theos.balance);
+    if (enabled && granted !== null && granted > 0) {
+      const used = balance === null ? null : Math.max(0, granted - balance);
+      const resetsAt =
+        typeof theos.refresh_at === "string" && Number.isFinite(Date.parse(theos.refresh_at))
+          ? new Date(theos.refresh_at).toISOString()
+          : null;
+      windows.push(
+        percentWindow(
+          "theos_daily",
+          "Daily Theos",
+          used === null ? null : (used / granted) * 100,
+          resetsAt,
+          used,
+          granted,
+          "pooled",
+        ),
+      );
+    }
+
+    const summary = await readJson(`${DEEPAI_API_ORIGIN}${DEEPAI_USAGE_SUMMARY_PATH}`, headers, fetcher);
+    const isPro = summary?.is_pro === true;
+    const plan = enabled ? (isPro ? "pro" : "free") : null;
+    return { source: LABEL, plan, windows, error: null };
+  } catch (error) {
+    return { source: LABEL, plan: null, windows: [], error: cleanError(error) };
+  }
+}

package/src/providers/integrations/deepai/provider.ts

@@ -0,0 +1,42 @@
+// DeepAI provider — TypeScript, DeepAI Code model API, Free Limited.
+//
+// DeepAI Code's model API (`https://api.deepai.org/deepai_code`) is served
+// with a non-Bearer credential: the sign-in flow returns an opaque `api_key`
+// that travels in the `Api-Key` header (a Bearer or `x-api-key` spelling is
+// rejected with 401 — verified live 2026-11-11). Every model call also needs
+// the lane headers (`X-DeepAI-Code-Theos` / `-Instance` / `-Machine`), which
+// the adapter stamps per dispatch. The daily free allowance is 50 Theos and
+// the 11 zero-Theos models draw nothing from it.
+//
+// Verified live 2026-11-11 (evidence: `documentation/research/deepai/`):
+//   - `GET /deepai_code/models` → 200, 22 rows (unauthenticated).
+//   - `POST /deepai_code/chat/completions` → 200 stream + non-stream with
+//     lane headers + `Api-Key`.
+//   - `POST /deepai_code/responses` → 200 SSE for `gpt-6-astra` only.
+//   - `GET /deepai_code/theos` → 200 allowance (balance/granted/refresh).
+import type { ApiKeyProviderSpec } from "../../configured-provider";
+import {
+  DEEPAI_API_ORIGIN,
+  DEEPAI_CHAT_PATH,
+  DEEPAI_RESPONSES_PATH,
+  deepAIBaseHeaders,
+} from "./deepai-common";
+import type { ProviderDispatchContext } from "../../provider-contracts";
+
+export const DEEPAI_SPEC: ApiKeyProviderSpec = {
+  provider_id: "deepai",
+  base_url: DEEPAI_API_ORIGIN,
+  endpoint_paths_by_wire_family: {
+    chat: DEEPAI_CHAT_PATH,
+    responses: DEEPAI_RESPONSES_PATH,
+  },
+  // The credential is not a bearer: sending `Authorization` would be wrong
+  // (and the upstream rejects a stray bearer). `buildExtraHeaders` stamps the
+  // `Api-Key` + lane headers instead.
+  credential_forwarding: "never",
+  buildExtraHeaders: async (context: ProviderDispatchContext) => {
+    const secret = context.credential.secret;
+    const apiKey = secret === undefined || secret.length === 0 ? "" : new TextDecoder().decode(secret);
+    return deepAIBaseHeaders(apiKey);
+  },
+};

package/src/providers/integrations/devin/devin-auth.ts

@@ -137,6 +137,13 @@ export async function resolveDevinAccountLabel(
 
 const DEVIN_AUTHORIZE_URL = "https://app.devin.ai/auth/cli/continue";
 const DEVIN_TOKEN_URL = "https://api.devin.ai/auth/cli/token";
+// Devin's authorization server only accepts this exact loopback redirect; a
+// public-origin redirect is refused with "Invalid redirect URI". The browser
+// opens it on the operator's own machine (the loopback listener belongs to the
+// desktop flow), so the gateway cannot intercept it — the operator pastes the
+// resulting URL back into the modal. On a server, the browser will show
+// "can't be reached" for 127.0.0.1: that is expected; the address bar still
+// carries the `code` to paste.
 const DEVIN_BROWSER_REDIRECT_URI = "http://127.0.0.1:59653/callback";
 
 export const devinOAuthClient: OAuthLoginClient = {

package/src/providers/integrations/factory/factory-oauth.ts

@@ -30,6 +30,7 @@ import type {
 import {
   decodeJwtPayload,
   nonEmptyTrimmedString,
+  oauthAccountIdentity,
   readJsonResponse,
   record,
 } from "../../authentication/oauth-flow-store";
@@ -104,9 +105,11 @@ function buildEnvelope(
     // cause; failing upstream would surface as an opaque 401.
     throw new Error("Factory Droid token carries no organization claim; sign in again");
   }
-  const email = nonEmptyTrimmedString(claims?.["email"]);
-  const subject = nonEmptyTrimmedString(claims?.["sub"]);
-  const label = accountLabel ?? email ?? subject;
+  const responseIdentity = oauthAccountIdentity(payload);
+  const email = nonEmptyTrimmedString(claims?.["email"]) ?? responseIdentity.accountEmail;
+  const accountName = responseIdentity.accountName ?? nonEmptyTrimmedString(claims?.["name"]);
+  const subject = nonEmptyTrimmedString(claims?.["sub"]) ?? nonEmptyTrimmedString(record(payload["user"])?.["id"]);
+  const label = accountLabel ?? email ?? accountName ?? subject;
   const envelope: FactoryDroidEnvelope = { accessToken, orgId };
   const result: OAuthExchangeResult = {
     access: encodeFactoryDroidCredential(envelope),
@@ -117,12 +120,15 @@ function buildEnvelope(
     refresh: nonEmptyTrimmedString(payload["refresh_token"]) ?? accessToken,
     expiresAt: expiryFromClaims(claims),
     ...(label === undefined ? {} : { accountLabel: label }),
+    ...(email === undefined ? {} : { accountEmail: email }),
+    ...(accountName === undefined ? {} : { accountName }),
   };
   return {
     result,
     authState: {
       orgId,
       ...(email === undefined ? {} : { email }),
+      ...(accountName === undefined ? {} : { accountName }),
       ...(subject === undefined ? {} : { userId: subject }),
     },
   };
@@ -139,7 +145,7 @@ export class FactoryOAuthClient extends OAuthDeviceFlow {
   protected override readonly scopes = "";
 
   override async startDeviceAuth(
-    _context?: OAuthDeviceFlowContext,
+    context?: OAuthDeviceFlowContext,
   ): Promise<OAuthDeviceStartResult> {
     return this.startGenericDeviceAuth({
       tokenUrl: FACTORY_DROID_TOKEN_URL,
@@ -147,7 +153,7 @@ export class FactoryOAuthClient extends OAuthDeviceFlow {
       clientId: FACTORY_DROID_CLIENT_ID,
       formHeaders: WORKOS_HEADERS,
       startParams: { user_agent: "cartethyia" },
-    });
+    }, context);
   }
 
   /**
@@ -159,14 +165,14 @@ export class FactoryOAuthClient extends OAuthDeviceFlow {
    */
   override async pollDeviceAuth(
     deviceAuthId: string,
-    _context?: OAuthDeviceFlowContext,
+    context?: OAuthDeviceFlowContext,
   ): Promise<OAuthDevicePollResult> {
     return this.pollGenericDeviceAuth(deviceAuthId, {
       tokenUrl: FACTORY_DROID_TOKEN_URL,
       deviceAuthUrl: FACTORY_DROID_DEVICE_AUTH_URL,
       clientId: FACTORY_DROID_CLIENT_ID,
       formHeaders: { ...WORKOS_HEADERS, "content-type": "application/x-www-form-urlencoded" },
-    });
+    }, context);
   }
 
   protected override afterDeviceTokenExchange(
@@ -200,6 +206,9 @@ export class FactoryOAuthClient extends OAuthDeviceFlow {
       refresh: refreshToken,
       expiresAt: result.expiresAt,
       auth_state: authState,
+      ...(result.accountEmail === undefined ? {} : { accountEmail: result.accountEmail }),
+      ...(result.accountName === undefined ? {} : { accountName: result.accountName }),
+      ...(result.accountLabel === undefined ? {} : { accountLabel: result.accountLabel }),
     };
   }
 }