cartethyia 2.7.9 → 2.8.1

package/src/providers/integrations/cursor/protocol/messages.ts

@@ -25,28 +25,7 @@
  */
 
 import protobuf from "protobufjs"
-
-// ── Helper: create a root and add a Type with fields ──
-
-type FieldDef = { id: number; name: string; type: string; repeated?: boolean }
-type OneofDef = { name: string; fields: string[] }
-
-function addType(
-  root: protobuf.Root,
-  name: string,
-  fields: FieldDef[],
-  oneofs?: OneofDef[],
-): protobuf.Type {
-  const t = new protobuf.Type(name)
-  for (const f of fields) {
-    t.add(new protobuf.Field(f.name, f.id, f.type, f.repeated ? "repeated" : undefined))
-  }
-  for (const o of oneofs ?? []) {
-    t.add(new protobuf.OneOf(o.name, o.fields))
-  }
-  root.add(t)
-  return t
-}
+import { addType } from "./protobuf-schema"
 
 // ── Utility messages ──
 
@@ -1809,8 +1788,8 @@ export function createMessageTypes(): protobuf.Root {
   ])
 
   addType(root, "CancelAction", [
-    // Cursor CLI CancelAction field #1 is the interruption reason, not an id.
-    { id: 1, name: "reason", type: "string" },
+    // `agent.proto` declares CancelAction empty (oneof presence is the signal);
+    // the reason travels on the stream, not in the message.
   ])
 
   // Deferred answers for an AskQuestion the client already replied to with
@@ -1922,8 +1901,24 @@ export function createMessageTypes(): protobuf.Root {
     { id: 8, name: "turns", type: "ConversationTurn", repeated: true },
   ])
 
+  // `agent.proto` ModelDetails.thinking_details — empty in the current build;
+  // declared for wire-shape completeness.
+  addType(root, "ThinkingDetails", [])
+
+  // `agent.proto` AgentRunRequest.skill_options (deprecated upstream; kept for
+  // wire-shape completeness).
+  addType(root, "SkillOptions", [
+    { id: 1, name: "skill_descriptors", type: "SkillDescriptor", repeated: true },
+  ])
+
   addType(root, "ModelDetails", [
     { id: 1, name: "model_id", type: "string" },
+    { id: 2, name: "thinking_details", type: "ThinkingDetails" },
+    { id: 3, name: "display_model_id", type: "string" },
+    { id: 4, name: "display_name", type: "string" },
+    { id: 5, name: "display_name_short", type: "string" },
+    { id: 6, name: "aliases", type: "string", repeated: true },
+    { id: 7, name: "max_mode", type: "bool" },
   ])
 
   addType(root, "McpTools", [
@@ -1933,15 +1928,13 @@ export function createMessageTypes(): protobuf.Root {
   addType(root, "AgentRunRequest", [
     { id: 1, name: "conversation_state", type: "bytes" },
     { id: 2, name: "action", type: "ConversationAction" },
+    { id: 3, name: "model_details", type: "ModelDetails" },
     { id: 4, name: "mcp_tools", type: "McpTools" },
     { id: 5, name: "conversation_id", type: "string" },
+    { id: 6, name: "mcp_file_system_options", type: "McpFileSystemOptions" },
+    { id: 7, name: "skill_options", type: "SkillOptions" },
     { id: 8, name: "custom_system_prompt", type: "string" },
     { id: 9, name: "requested_model", type: "RequestedModel" },
-    { id: 10, name: "unknown_flag", type: "uint32" },
-    { id: 12, name: "field_12", type: "uint32" },
-    { id: 14, name: "selected_subagent_models", type: "RequestedModel", repeated: true },
-    { id: 16, name: "conversation_group_id", type: "string" },
-    { id: 25, name: "run_id", type: "string" },
   ])
 
   // ── Client heartbeat ──

package/src/providers/integrations/cursor/protocol/protobuf-schema.ts

@@ -0,0 +1,37 @@
+/**
+ * Shared protobufjs schema-builder helpers.
+ *
+ * Extracted verbatim from the vendored protocol modules that each carried the
+ * same implementation: `cursor/protocol/messages.ts` (vendored from
+ * `cursor-opencode-provider`, MIT) and `devin/protocol/devin-proto.ts`
+ * (vendored from `oh-my-pi`, MIT). The original license texts remain in those
+ * files; this module exists so future schema additions have one place to fix.
+ */
+
+import protobuf from "protobufjs";
+
+export type FieldDef = { id: number; name: string; type: string; repeated?: boolean };
+export type OneofDef = { name: string; fields: string[] };
+
+/** Create a root Type with fields and optional oneofs, and register it. */
+export function addType(
+  root: protobuf.Root,
+  name: string,
+  fields: FieldDef[],
+  oneofs?: OneofDef[],
+): protobuf.Type {
+  const t = new protobuf.Type(name);
+  for (const f of fields) {
+    t.add(new protobuf.Field(f.name, f.id, f.type, f.repeated ? "repeated" : undefined));
+  }
+  for (const o of oneofs ?? []) {
+    t.add(new protobuf.OneOf(o.name, o.fields));
+  }
+  root.add(t);
+  return t;
+}
+
+/** Register an enum on the root. */
+export function addEnum(root: protobuf.Root, name: string, values: Record<string, number>): void {
+  root.add(new protobuf.Enum(name, values));
+}

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) };
+  }
+}