cartethyia 2.7.8 → 2.8.0

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

@@ -0,0 +1,60 @@
+// Free-pi model roster.
+//
+// The live roster is server-driven: `GET /client-version` returns the full
+// model list (`models[]`, with `section` and `tier`). The static roster here
+// is only the fallback when that call fails, mirroring the Trae pattern. All
+// rows use the chat completions wire.
+//
+// Capability/funding facts (from the live 2026-11-08 sweep on a GitHub
+// account): the four "Free Unlimited" rows (particle, deepseek-v4.1-flash,
+// glm-5.3-flash, deepseek-v4-flash) stream for everyone; everything else is
+// either premium (billed from the allowance) or defense (section "defense").
+// Context is 200k and output 8k per the client bundle; these are the client's
+// own claims, not upstream model truth.
+
+import { defineModel, type ModelDefinition } from "../../provider-model-definition";
+import {
+  FREEPI_CHAT_PATH,
+  FREEPI_CONTEXT_WINDOW,
+  FREEPI_MAX_OUTPUT_TOKENS,
+  FREEPI_PROVIDER_ID,
+} from "./freepi-realm";
+
+interface FreepiRow {
+  readonly id: string;
+  readonly displayName: string;
+  readonly free?: boolean;
+  readonly proOnly?: boolean;
+}
+
+const FREEPI_ROWS: readonly FreepiRow[] = [
+  // Only the "Free Unlimited" rows ship in the static roster: they are the
+  // ones the live sweep confirmed stream for every account type (guest +
+  // GitHub). Paid/defense rows are left to live discovery, which keeps the
+  // whole catalog; the fallback must never advertise a model the account
+  // cannot serve.
+  { id: "deepseek-v4.1-flash", displayName: "DeepSeek V4.1 Flash", free: true },
+  { id: "glm-5.3-flash", displayName: "GLM 5.3 Flash", free: true },
+  { id: "particle", displayName: "Particle · Free Unlimited", free: true },
+];
+
+export const FREEPI_MODELS: readonly ModelDefinition[] = FREEPI_ROWS.map((row) =>
+  defineModel({
+    id: row.id,
+    providerId: FREEPI_PROVIDER_ID,
+    wireFamily: "chat",
+    endpoint: FREEPI_CHAT_PATH,
+    ctx: FREEPI_CONTEXT_WINDOW,
+    out: FREEPI_MAX_OUTPUT_TOKENS,
+    // No vision/audio/document claims: the upstream `/client-version` catalog
+    // publishes only id/name/section/tier, and the live sweep verified text
+    // completions but no other modality. Everything streamed reasoning
+    // content, and the agent wire carries tools, so reasoning + toolCall are
+    // the only declared capabilities.
+    vision: false,
+    reasoning: true,
+    toolCall: true,
+    ...(row.free ? { free: true, freeTier: true } : {}),
+    ...(row.proOnly ? { proOnly: true } : {}),
+  }),
+);

package/src/providers/integrations/freepi/freepi-discovery.ts

@@ -0,0 +1,82 @@
+// Free-pi live model discovery.
+//
+// `GET /client-version` (Bearer) returns the full model catalog:
+// `models[]` with `{id, name, section?, tier?}` plus `fusion`, `model`, and
+// `notice`. Discovery parses that into `ModelDefinition` rows. The static
+// roster remains the fallback when the live call fails (mirrors the Trae
+// pattern).
+//
+// Normalization:
+//   - The CLI's default id is `deepseek/deepseek-v4-flash`, while the catalog
+//     lists the bare `deepseek-v4-flash`. They are one model; discovery maps
+//     the bare id onto the default id so a single row survives (no duplicate,
+//     no ambiguous pair inside the provider).
+//   - Every discovered row is kept as-is (no free/pro filtering); the static
+//     roster is the fallback and carries only the free rows.
+//   - No vision/audio/document claims: the catalog publishes only
+//     id/name/section/tier, and the live sweep verified text completions only.
+
+import { defineModel, type ModelDefinition } from "../../provider-model-definition";
+import {
+  FREEPI_CHAT_PATH,
+  FREEPI_CLI_VERSION,
+  FREEPI_CONTEXT_WINDOW,
+  FREEPI_DEFAULT_MODEL,
+  FREEPI_MAX_OUTPUT_TOKENS,
+  FREEPI_PROVIDER_ID,
+} from "./freepi-realm";
+
+/** Catalog id → canonical roster id for one model. */
+const CATALOG_ID_REMAP: Readonly<Record<string, string>> = {
+  "deepseek-v4-flash": FREEPI_DEFAULT_MODEL,
+};
+
+/** Fetches the live model catalog. */
+export async function discoverFreepiModels(input: {
+  readonly token: string;
+  readonly fetcher: typeof fetch;
+  readonly signal?: AbortSignal;
+  readonly providerId?: string;
+}): Promise<readonly ModelDefinition[]> {
+  const url = new URL("/client-version", "https://api.freepi.ai");
+  const response = await input.fetcher(url, {
+    method: "GET",
+    headers: {
+      authorization: `Bearer ${input.token}`,
+      accept: "application/json",
+      "x-client-version": FREEPI_CLI_VERSION,
+    },
+    ...(input.signal ? { signal: input.signal } : {}),
+  });
+  if (!response.ok) return [];
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = (await response.json()) as Record<string, unknown>;
+  } catch {
+    return [];
+  }
+  const rows = Array.isArray(parsed["models"]) ? (parsed["models"] as Record<string, unknown>[]) : [];
+  const seen = new Set<string>();
+  const out: ModelDefinition[] = [];
+  for (const row of rows) {
+    const rawId = String(row["id"] ?? "").trim();
+    if (!rawId) continue;
+    const id = CATALOG_ID_REMAP[rawId] ?? rawId;
+    if (seen.has(id)) continue;
+    seen.add(id);
+    out.push(
+      defineModel({
+        id,
+        providerId: input.providerId ?? FREEPI_PROVIDER_ID,
+        wireFamily: "chat",
+        endpoint: FREEPI_CHAT_PATH,
+        ctx: FREEPI_CONTEXT_WINDOW,
+        out: FREEPI_MAX_OUTPUT_TOKENS,
+        vision: false,
+        reasoning: true,
+        toolCall: true,
+      }),
+    );
+  }
+  return out;
+}

package/src/providers/integrations/freepi/freepi-headers.ts

@@ -0,0 +1,21 @@
+// Free-pi request headers.
+//
+// The client sends `Authorization: Bearer <jwt>` plus `x-client-version` (the
+// CLI version) on the chat wire, and uses `application/json`. There is no
+// device fingerprint — the JWT is the whole identity.
+
+import { FREEPI_CLI_VERSION } from "./freepi-realm";
+
+/** Builds the header set for one free-pi request. */
+export function buildFreepiHeaders(jwt: string, stream = false, sessionId?: string): Record<string, string> {
+  const headers: Record<string, string> = {
+    authorization: `Bearer ${jwt}`,
+    "content-type": "application/json",
+    accept: stream ? "text/event-stream" : "application/json",
+    "x-client-version": FREEPI_CLI_VERSION,
+  };
+  if (sessionId !== undefined && sessionId.length > 0) {
+    headers["x-session-id"] = sessionId;
+  }
+  return headers;
+}

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

@@ -0,0 +1,142 @@
+// Free-pi credential login (device flow) and refresh.
+//
+// The backend has no standard OAuth token endpoint; the device flow is:
+//
+//   1. POST /auth/github/device   -> { session_id, user_code, verification_uri, interval }
+//   2. POST /auth/consent          -> { session_id, consent_version: "4" }
+//   3. POST /auth/token (poll)     -> pending / { token }
+//
+// The issued token is a JWT used as `Authorization: Bearer` on every data-plane
+// call. There is no refresh token: the JWT is long-lived (the CLI just re-runs
+// the flow). Pasting a raw JWT is supported via `importCredential`.
+
+import { OAuthClient } from "../../authentication/oauth-client";
+import { decodeJwtPayload } from "../../authentication/oauth-flow-store";
+import type {
+  OAuthDeviceStartResult,
+  OAuthDevicePollResult,
+  OAuthDeviceFlowContext,
+  OAuthExchangeResult,
+  OAuthImportInput,
+} from "../../authentication/oauth-flow-store";
+
+const FREEPI_DEVICE_START_PATH = "/auth/github/device";
+const FREEPI_CONSENT_PATH = "/auth/consent";
+const FREEPI_TOKEN_PATH = "/auth/token";
+const FREEPI_BASE_URL = "https://api.freepi.ai";
+const FREEPI_CONSENT_VERSION = "4";
+
+export class FreepiOAuthClient extends OAuthClient {
+  readonly supportsDeviceCode = true;
+  readonly supportsBrowserCode = false;
+  protected readonly providerLabel = "free-pi";
+  protected readonly clientId = "";
+  protected readonly tokenUrl = "";
+  protected readonly scopes = "";
+
+  async startDeviceAuth(): Promise<OAuthDeviceStartResult> {
+    const res = await this.fetchFn(new URL(FREEPI_DEVICE_START_PATH, FREEPI_BASE_URL), {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json" },
+      body: JSON.stringify({}),
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(`free-pi device flow start failed: HTTP ${res.status} ${text.slice(0, 300)}`);
+    }
+    const body = (await res.json()) as Record<string, unknown>;
+    const sessionId = String(body["session_id"] ?? "");
+    // The upstream requires consent before the token poll answers: without it,
+    // `/auth/token` returns 403 `consent_required`. Submit it once here so
+    // the device flow is complete before the dashboard starts polling.
+    if (sessionId) {
+      try {
+        await this.fetchFn(new URL(FREEPI_CONSENT_PATH, FREEPI_BASE_URL), {
+          method: "POST",
+          headers: { "content-type": "application/json", accept: "application/json" },
+          body: JSON.stringify({ session_id: sessionId, consent_version: FREEPI_CONSENT_VERSION }),
+        });
+      } catch {
+        // Consent failure is non-fatal at start; the poll will surface it.
+      }
+    }
+    return {
+      verificationUri: String(body["verification_uri"] ?? ""),
+      userCode: String(body["user_code"] ?? ""),
+      deviceAuthId: sessionId,
+      intervalSeconds: Number(body["interval"] ?? 5),
+      expiresInSeconds: Number(body["expires_in"] ?? 900),
+      providerState: JSON.stringify({ session_id: sessionId }),
+    };
+  }
+
+  async pollDeviceAuth(deviceAuthId: string, _context?: OAuthDeviceFlowContext): Promise<OAuthDevicePollResult> {
+    let providerState: Record<string, unknown> = {};
+    try {
+      providerState = JSON.parse(_context?.providerState ?? "{}") as Record<string, unknown>;
+    } catch {
+      /* ignore */
+    }
+    const sessionId = String(providerState["session_id"] ?? deviceAuthId);
+    const res = await this.fetchFn(new URL(FREEPI_TOKEN_PATH, FREEPI_BASE_URL), {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json" },
+      body: JSON.stringify({ session_id: sessionId }),
+    });
+    if (!res.ok) {
+      return { status: "failed", reason: `token poll failed: HTTP ${res.status}` };
+    }
+    const body = (await res.json()) as Record<string, unknown>;
+    if (typeof body["token"] === "string" && (body["token"] as string).length > 0) {
+      const token = body["token"] as string;
+      // The free-pi JWT carries the GitHub user identity (`sub` = GitHub user
+      // id, `email` when the account has one). Resolving it keeps one account
+      // per GitHub user — without it every device login minted the same
+      // generic label and the second account replaced the first (the identity
+      // fingerprint collided on the static label).
+      const claims = decodeJwtPayload(token);
+      const userId = typeof claims?.["sub"] === "string" ? claims["sub"] : undefined;
+      const email = typeof claims?.["email"] === "string" ? (claims["email"] as string).trim() : "";
+      const label = email.length > 0 ? email : userId ? `freepi-${userId}` : "freepi-device";
+      return {
+        status: "complete",
+        result: {
+          access: token,
+          refresh: "",
+          expiresAt: new Date(Date.now() + 30 * 24 * 3600 * 1000),
+          accountLabel: label,
+          // The upstream identity the token resolved, stored beside the token
+          // so a later login of the same GitHub user lands on the same row
+          // (and a *different* user on a different row).
+          ...(userId || email
+            ? { auth_state: { ...(userId ? { freepi_user_id: userId } : {}), ...(email ? { email } : {}) } }
+            : {}),
+        },
+      };
+    }
+    if (body["code"] === "consent_required") {
+      return { status: "failed", reason: "consent_required" };
+    }
+    return { status: "pending" };
+  }
+
+  async importCredential(input: OAuthImportInput): Promise<OAuthExchangeResult> {
+    const token = input.credential.trim();
+    if (!token) throw new Error("free-pi: a JWT credential is required");
+    const claims = decodeJwtPayload(token);
+    const userId = typeof claims?.["sub"] === "string" ? claims["sub"] : undefined;
+    const email = typeof claims?.["email"] === "string" ? (claims["email"] as string).trim() : "";
+    const label = email.length > 0 ? email : userId ? `freepi-${userId}` : input.accountLabel ?? "freepi-jwt";
+    return {
+      access: token,
+      refresh: "",
+      expiresAt: new Date(Date.now() + 30 * 24 * 3600 * 1000),
+      accountLabel: label,
+      ...(userId || email
+        ? { auth_state: { ...(userId ? { freepi_user_id: userId } : {}), ...(email ? { email } : {}) } }
+        : {}),
+    };
+  }
+}
+
+export const freepiOAuthClient = new FreepiOAuthClient();

package/src/providers/integrations/freepi/freepi-protocol.ts

@@ -0,0 +1,242 @@
+// Free-pi wire protocol: request body and SSE translation.
+//
+// The wire is OpenAI-completions (`/v1/chat/completions`) with a JWT bearer.
+// Streaming returns OpenAI-style SSE: `data:` JSON chunks (no `event:` name),
+// terminated by `[DONE]`. Errors come as HTTP status + JSON
+// `{code, message, error: {code, message}}`.
+//
+// The client (0.6.14) sends `model` (the catalog id), `messages`, `stream`,
+// and optionally `max_tokens`; the upstream resolves the catalog id to the
+// real model and echoes it in each chunk (`choices[0].delta.model`).
+
+import type { CanonicalRequest, ContentPart } from "../../../protocol/canonical-model";
+import { GatewayError } from "../../../protocol/gateway-error";
+
+/** Upstream chat body (OpenAI-completions shape). */
+export interface FreepiChatBody {
+  readonly model: string;
+  readonly messages: readonly FreepiMessage[];
+  readonly stream: boolean;
+  readonly max_tokens?: number;
+  readonly temperature?: number;
+  readonly top_p?: number;
+  readonly tools?: readonly FreepiToolDeclaration[];
+}
+
+export interface FreepiMessage {
+  readonly role: "system" | "user" | "assistant" | "tool";
+  readonly content: string;
+  readonly tool_call_id?: string;
+  readonly tool_calls?: readonly FreepiToolCall[];
+}
+
+export interface FreepiToolDeclaration {
+  readonly type: "function";
+  readonly function: {
+    readonly name: string;
+    readonly description?: string;
+    readonly parameters: unknown;
+  };
+}
+
+export interface FreepiToolCall {
+  readonly id: string;
+  readonly type: "function";
+  readonly function: { readonly name: string; readonly arguments: string };
+}
+
+function textOf(part: ContentPart): string {
+  return part.kind === "text" ? part.text : "";
+}
+
+function toolArguments(args: unknown): string {
+  if (typeof args === "string") return args;
+  try {
+    return JSON.stringify(args ?? {});
+  } catch {
+    return "{}";
+  }
+}
+
+function toolResultText(content: readonly ContentPart[] | string): string {
+  if (typeof content === "string") return content;
+  return content
+    .map((part) => (part.kind === "text" ? part.text : ""))
+    .filter((text) => text.length > 0)
+    .join("\n");
+}
+
+/** Builds the upstream chat body from a canonical request. */
+export function buildFreepiChatBody(
+  modelId: string,
+  request: CanonicalRequest,
+  maxOutputTokens?: number,
+): FreepiChatBody {
+  const messages: FreepiMessage[] = [];
+  const systemParts: string[] = [];
+  for (const part of request.system ?? []) {
+    const text = textOf(part);
+    if (text.length > 0) systemParts.push(text);
+  }
+  for (const part of request.instructions ?? []) {
+    const text = textOf(part);
+    if (text.length > 0) systemParts.push(text);
+  }
+  if (systemParts.length > 0) {
+    messages.push({ role: "system", content: systemParts.join("\n\n") });
+  }
+
+  for (const message of request.messages) {
+    if (message.role === "system" || message.role === "developer") {
+      const text = message.content.map(textOf).filter((t) => t.length > 0).join("\n\n");
+      if (text.length > 0) systemParts.push(text);
+      continue;
+    }
+    const parts: string[] = [];
+    const toolCalls: FreepiToolCall[] = [];
+    let toolResult: { callId: string; text: string } | undefined;
+    for (const part of message.content) {
+      if (part.kind === "toolCall") {
+        toolCalls.push({
+          id: part.call_id,
+          type: "function",
+          function: { name: part.name, arguments: toolArguments(part.arguments) },
+        });
+        continue;
+      }
+      if (part.kind === "toolResult") {
+        toolResult = { callId: part.call_id, text: toolResultText(part.content) };
+        continue;
+      }
+      const text = textOf(part);
+      if (text.length > 0) parts.push(text);
+    }
+    if (toolResult !== undefined) {
+      messages.push({ role: "tool", content: toolResult.text, tool_call_id: toolResult.callId });
+      continue;
+    }
+    if (parts.length === 0 && toolCalls.length === 0) continue;
+    messages.push({
+      role: message.role === "assistant" ? "assistant" : "user",
+      content: parts.join("\n"),
+      ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : {}),
+    });
+  }
+
+  const body: FreepiChatBody = {
+    model: modelId,
+    messages,
+    stream: request.stream,
+  };
+  const extra: Record<string, unknown> = {};
+  if (maxOutputTokens !== undefined && Number.isFinite(maxOutputTokens) && maxOutputTokens > 0) {
+    extra["max_tokens"] = Math.min(maxOutputTokens, 8192);
+  }
+  const controls = request.generation_controls;
+  if (typeof controls.temperature === "number" && Number.isFinite(controls.temperature)) {
+    extra["temperature"] = controls.temperature;
+  }
+  if (typeof controls.top_p === "number" && Number.isFinite(controls.top_p)) {
+    extra["top_p"] = controls.top_p;
+  }
+  const tools = request.tools;
+  if (tools !== undefined && tools.length > 0) {
+    extra["tools"] = tools.map((tool) => ({
+      type: "function",
+      function: {
+        name: tool.name,
+        ...(tool.description ? { description: tool.description } : {}),
+        parameters: tool.jsonSchema,
+      },
+    }));
+  }
+  return { ...body, ...extra } as FreepiChatBody;
+}
+
+/** One parsed SSE frame. */
+export interface FreepiSseFrame {
+  readonly event: string;
+  readonly data: unknown;
+}
+
+/** Parses an SSE byte stream into frames (OpenAI-style, `data:` only). */
+export async function* parseFreepiSse(
+  body: ReadableStream<Uint8Array>,
+): AsyncIterable<FreepiSseFrame> {
+  const decoder = new TextDecoder();
+  const reader = body.getReader();
+  let buffer = "";
+  let data: string[] = [];
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let newline = buffer.indexOf("\n");
+      while (newline >= 0) {
+        const line = buffer.slice(0, newline).replace(/\r$/, "");
+        buffer = buffer.slice(newline + 1);
+        if (line === "") {
+          if (data.length > 0) {
+            const payload = data.join("\n");
+            data = [];
+            if (payload.trim() === "[DONE]") {
+              yield { event: "done", data: { finish_reason: "stop" } };
+            } else {
+              let parsed: unknown = payload;
+              try {
+                parsed = JSON.parse(payload);
+              } catch {
+                parsed = payload;
+              }
+              yield { event: "message", data: parsed };
+            }
+          }
+        } else if (line.startsWith(":")) {
+          continue;
+        } else if (line.startsWith("data")) {
+          let value = line.slice(4);
+          if (value.startsWith(" ")) value = value.slice(1);
+          data.push(value);
+        }
+        newline = buffer.indexOf("\n");
+      }
+    }
+    if (data.length > 0) {
+      const payload = data.join("\n");
+      if (payload.trim() === "[DONE]") {
+        yield { event: "done", data: { finish_reason: "stop" } };
+      } else {
+        let parsed: unknown = payload;
+        try {
+          parsed = JSON.parse(payload);
+        } catch {
+          parsed = payload;
+        }
+        yield { event: "message", data: parsed };
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+/** Maps upstream error JSON (code/message/error nested) to a GatewayError. */
+export function throwFreepiUpstreamError(code: unknown, message: unknown): never {
+  const msg = typeof message === "string" && message.trim() ? message : "free-pi upstream error";
+  const codeStr = code === undefined ? undefined : String(code);
+  // Entitlement/plan walls the gateway classifies as policy rejection (403):
+  // the account is not allowed to use this model/credential type, which is
+  // not a transient rate limit (quota_exceeded = 429).
+  if (codeStr === "guest_unavailable" || codeStr === "model_requires_credits") {
+    throw new GatewayError("policy_rejected", 403, `${msg} (request {requestId}). The free-pi account cannot serve this — check credits or sign in. 💸`, { upstream_code: codeStr }, "upstream");
+  }
+  // Server-side model unavailability → platform unavailable (503).
+  if (codeStr === "model_at_capacity" || codeStr === "model_unavailable") {
+    throw new GatewayError("platform_unavailable", 503, `${msg} (request {requestId}). Upstream has this model hard-down right now. 🔄`, { upstream_code: codeStr }, "upstream");
+  }
+  if (codeStr === "upstream_error") {
+    throw new GatewayError("platform_unavailable", 502, `${msg} (request {requestId}). The upstream model host errored. 🌙`, { upstream_code: codeStr }, "upstream");
+  }
+  throw new GatewayError("platform_unavailable", 502, `${msg} (request {requestId}). The free-pi upstream refused the request. 🌙`, { upstream_code: codeStr }, "upstream");
+}

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

@@ -0,0 +1,126 @@
+// Free-pi quota collector.
+//
+// Reads `GET /me` (Bearer) — the backend's account/allowance surface. The
+// response carries the USD budget (`cap_usd_today`, `remaining_usd_today`),
+// credit counts (`allowance_credits`, `remaining_credits_today`,
+// `bonus_wallet_credits`, `premium_credits`, …), a `refill_at` reset time, and
+// a usage lane (`standard`/`fallback`/`wait`). Never throws: a failed read
+// returns a null-result so the router treats it as unknown rather than dead.
+
+import type { FetchLike, ProviderQuotaResult, ProviderQuotaWindow } from "../../quota/quota-contracts";
+import { cleanError, percentWindow, text } from "../../quota/quota-contracts";
+import type { QuotaCollectionContext } from "../../quota/quota-support";
+import { buildFreepiHeaders } from "./freepi-headers";
+import { FREEPI_BASE_URL } from "./freepi-realm";
+
+function readMe(baseUrl: string, credential: string, fetcher: FetchLike): Promise<Record<string, unknown> | null> {
+  return fetcher(new URL("/me", baseUrl), {
+    method: "GET",
+    headers: buildFreepiHeaders(credential),
+    signal: AbortSignal.timeout(15_000),
+  })
+    .then(async (res) => {
+      if (!res.ok) return null;
+      try {
+        return (await res.json()) as Record<string, unknown>;
+      } catch {
+        return null;
+      }
+    })
+    .catch(() => null);
+}
+
+/** Reads the account quota and returns a normalized result. */
+export async function fetchFreepiQuota(
+  credential: string,
+  fetcher: FetchLike,
+  _context?: QuotaCollectionContext,
+): Promise<ProviderQuotaResult> {
+  try {
+    const me = await readMe(FREEPI_BASE_URL, credential, fetcher);
+    if (!me) {
+      return {
+        source: "freepi",
+        plan: null,
+        windows: [],
+        error: "free-pi /me unavailable",
+      };
+    }
+    const plan = me["tier"] === undefined ? null : text(me["tier"]);
+    const windows: ProviderQuotaWindow[] = [];
+
+    const capUsd = me["cap_usd_today"];
+    const remainingUsd = me["remaining_usd_today"];
+    const refillAt = me["refill_at"];
+    if (typeof capUsd === "number" && typeof remainingUsd === "number") {
+      const limit = capUsd as number;
+      const remaining = remainingUsd as number;
+      windows.push(
+        percentWindow(
+          "usd_daily",
+          "Daily USD budget",
+          remaining,
+          refillAt === undefined ? null : text(refillAt),
+          limit - remaining,
+          limit,
+          "pooled",
+        ),
+      );
+    }
+
+    const allowance = me["allowance_credits"];
+    const remainingCredits = me["remaining_credits_today"];
+    if (typeof allowance === "number" && typeof remainingCredits === "number") {
+      const limit = allowance as number;
+      const remaining = remainingCredits as number;
+      windows.push(
+        percentWindow(
+          "credits_daily",
+          "Daily credits",
+          remaining,
+          refillAt === undefined ? null : text(refillAt),
+          limit - remaining,
+          limit,
+          "pooled",
+        ),
+      );
+    }
+
+    const bonus = me["bonus_wallet_credits"];
+    if (typeof bonus === "number") {
+      windows.push({
+        kind: "bonus_credits",
+        label: "Bonus credits",
+        accounting: "pooled",
+        usedPercent: null,
+        remainingPercent: null,
+        resetsAt: null,
+        remaining: bonus as number,
+      });
+    }
+
+    const premium = me["premium_credits"];
+    if (typeof premium === "number") {
+      windows.push({
+        kind: "premium_credits",
+        label: "Premium credits",
+        accounting: "pooled",
+        usedPercent: null,
+        remainingPercent: null,
+        resetsAt: null,
+        remaining: premium as number,
+      });
+    }
+
+    const handle = me["handle"];
+    return {
+      source: "freepi",
+      plan,
+      windows,
+      error: null,
+      ...(typeof handle === "string" && handle.trim() ? { accountLabel: handle } : {}),
+    };
+  } catch (error) {
+    return { source: "freepi", plan: null, windows: [], error: cleanError(error) };
+  }
+}