cartethyia 2.7.8 → 2.7.9

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

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

@@ -0,0 +1,35 @@
+// Free-pi realm constants.
+//
+// A single deployment with no regional variants: the backend base URL is the
+// same for everyone (FREEPI_BASE_URL defaults to https://api.freepi.ai). The
+// chat wire is OpenAI-completions (`/v1/chat/completions`), and the credential
+// is a JWT issued by the backend (device flow or guest), sent as
+// `Authorization: Bearer <jwt>`.
+
+/** Default backend base URL, matching FREEPI_BASE_URL. */
+export const FREEPI_BASE_URL = "https://api.freepi.ai";
+
+/** Chat completions path, relative to the base URL (OpenAI-completions). */
+export const FREEPI_CHAT_PATH = "/v1/chat/completions";
+
+/** Ad fetch/impression paths, relative to the base URL. */
+export const FREEPI_AD_NEXT_PATH = "/ads/next";
+export const FREEPI_AD_IMPRESSION_PATH = "/ads/impression";
+
+/** Client version the gateway reports via `x-client-version`. */
+export const FREEPI_CLI_VERSION = "0.6.14";
+
+/** Consent version shipped in 0.6.14. */
+export const FREEPI_CONSENT_VERSION = "4";
+
+/** Provider id used by the registry. */
+export const FREEPI_PROVIDER_ID = "freepi";
+
+/** Static roster fallback; the live `/client-version` catalog replaces it. */
+export const FREEPI_DEFAULT_MODEL = "deepseek/deepseek-v4-flash";
+
+/** Context window the provider reports for every model (the client hardcodes 200k). */
+export const FREEPI_CONTEXT_WINDOW = 200_000;
+
+/** Maximum output tokens the client requests (hardcoded in the bundle). */
+export const FREEPI_MAX_OUTPUT_TOKENS = 8192;

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

@@ -0,0 +1,292 @@
+// Free-pi adapter.
+//
+// OpenAI-completions wire with a JWT bearer. The model catalog is
+// server-driven (`GET /client-version`); dispatch posts to
+// `/v1/chat/completions` and translates the OpenAI-style SSE stream into
+// canonical events.
+
+import { randomUUID } from "node:crypto";
+import type {
+  CanonicalEvent,
+  CanonicalRequest,
+  CanonicalMessage,
+  CanonicalStopReason,
+} from "../../../protocol/canonical-model";
+import { GatewayError } from "../../../protocol/gateway-error";
+import {
+  assertWireFamily,
+  readCredentialSecret,
+  type ProviderAdapter,
+  type ProviderDispatchContext,
+  type ProviderDispatchTarget,
+  type ProviderId,
+} from "../../provider-contracts";
+import { mapUpstreamHttpError } from "../../../transport/failure-policy";
+import { abortGatewayError, createUpstreamDeadlineLifecycle } from "../../operations/upstream-deadline";
+import { resolvePromptCacheKey } from "../../operations/session-resolution";
+import { usageFromProvider } from "../../provider-usage";
+import { buildFreepiChatBody, parseFreepiSse, throwFreepiUpstreamError } from "./freepi-protocol";
+import { buildFreepiHeaders } from "./freepi-headers";
+import {
+  FREEPI_AD_IMPRESSION_PATH,
+  FREEPI_AD_NEXT_PATH,
+  FREEPI_BASE_URL,
+  FREEPI_CHAT_PATH,
+  FREEPI_PROVIDER_ID,
+} from "./freepi-realm";
+
+const STOP_REASONS: Readonly<Record<string, CanonicalStopReason>> = {
+  stop: "stop",
+  length: "length",
+  tool_calls: "tool_use",
+  function_call: "tool_use",
+};
+
+interface FreepiAdapterOptions {
+  readonly providerId?: string;
+  readonly fetch?: typeof fetch;
+}
+
+export class FreepiAdapter implements ProviderAdapter {
+  readonly provider_id: ProviderId;
+  private readonly fetchFn: typeof fetch;
+  /**
+   * One stable ad-registered session id per account credential, so repeated
+   * chats reuse a session the upstream knows has shown ads. The session must
+   * exist for the chat wire: without it the server answers `ads_required`
+   * ("Ads aren't showing for this account, so free completions are paused").
+   */
+  #sessionByCredential = new Map<string, string>();
+
+  constructor(options: FreepiAdapterOptions = {}) {
+    this.provider_id = (options.providerId ?? FREEPI_PROVIDER_ID) as ProviderId;
+    this.fetchFn = options.fetch ?? globalThis.fetch;
+  }
+
+  /**
+   * Ensures a session id exists for this credential and that the session has
+   * registered at least one ad impression (banner + inline). The upstream
+   * refuses the chat wire with `ads_required` until a session has shown ads,
+   * so the first call per credential pays the two ad-registration requests.
+   *
+   * Returns the session id to send as `x-session-id`. Falls back to a fresh
+   * random id when registration fails — a broken ad surface must not block
+   * chat entirely, and the error is caught upstream anyway.
+   */
+  async #ensureSession(secret: string, outboundFetch: typeof fetch): Promise<string> {
+    const existing = this.#sessionByCredential.get(secret);
+    if (existing !== undefined) return existing;
+    const sessionId = randomUUID();
+    try {
+      for (const slot of ["banner", "inline"] as const) {
+        const next = await outboundFetch(new URL(`${FREEPI_AD_NEXT_PATH}?slot=${slot}`, FREEPI_BASE_URL), {
+          method: "GET",
+          headers: buildFreepiHeaders(secret, false, sessionId),
+          signal: AbortSignal.timeout(15_000),
+        });
+        if (!next.ok || next.status === 204) continue;
+        const ad = (await next.json()) as Record<string, unknown>;
+        const adId = ad["ad_id"];
+        const clickToken = ad["click_token"];
+        if (typeof adId !== "string" || typeof clickToken !== "string") continue;
+        await outboundFetch(new URL(FREEPI_AD_IMPRESSION_PATH, FREEPI_BASE_URL), {
+          method: "POST",
+          headers: buildFreepiHeaders(secret, false, sessionId),
+          body: JSON.stringify({ ad_id: adId, click_token: clickToken, imp_fired: true }),
+          signal: AbortSignal.timeout(15_000),
+        });
+      }
+    } catch {
+      // The ad surface is best-effort; chat may still work or fail upstream.
+    }
+    this.#sessionByCredential.set(secret, sessionId);
+    return sessionId;
+  }
+
+  async *dispatch(
+    request: CanonicalRequest,
+    candidate: ProviderDispatchTarget,
+    context: ProviderDispatchContext,
+  ): AsyncIterable<CanonicalEvent> {
+    if (candidate.wire_family !== "chat") {
+      assertWireFamily(candidate, "chat", "freepi");
+    }
+    const secret = readCredentialSecret(context.credential, "Free-pi credential is required");
+    const modelId = candidate.model_id || request.model;
+    const lifecycle = createUpstreamDeadlineLifecycle(context);
+    const outboundFetch =
+      (context.outbound_fetch as unknown as typeof fetch | undefined) ?? this.fetchFn;
+
+    const body = buildFreepiChatBody(modelId, request, candidate.output_limit ?? undefined);
+
+    const sessionKey = resolvePromptCacheKey(request, context);
+    const cacheSessionKey = sessionKey === undefined ? undefined : `${modelId}:${sessionKey}`;
+
+    const sessionId = await this.#ensureSession(secret, outboundFetch);
+    const headers = buildFreepiHeaders(secret, true, sessionId);
+    const url = `${FREEPI_BASE_URL}${FREEPI_CHAT_PATH}`;
+
+    try {
+      const response = await outboundFetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+        signal: lifecycle.signal,
+      });
+      if (!response.ok) throw await mapUpstreamHttpError(response, this.provider_id);
+      if (!response.body) {
+        throw new GatewayError("platform_unavailable", 502, "Free-pi returned empty body (request {requestId}). The upstream came back empty-handed — retry 🌙", {}, "upstream");
+      }
+      lifecycle.release();
+      yield* this.#events(
+        response.body as ReadableStream<Uint8Array>,
+        lifecycle.signal,
+        request.model,
+        cacheSessionKey,
+        request.messages,
+      );
+    } catch (err: unknown) {
+      const abortError = abortGatewayError(lifecycle, err, context.abort_signal);
+      if (abortError) throw abortError;
+      throw err;
+    } finally {
+      lifecycle.release();
+    }
+  }
+
+  async *#events(
+    body: ReadableStream<Uint8Array>,
+    _signal: AbortSignal,
+    requestModel: string,
+    sessionId?: string,
+    _messages?: readonly CanonicalMessage[],
+  ): AsyncIterable<CanonicalEvent> {
+    let seq = 1;
+    yield { type: "response_start", sequence_number: seq++, model: requestModel } as CanonicalEvent;
+    let stopReason: CanonicalStopReason = "stop";
+    let usage: Record<string, unknown> | undefined;
+    const toolCallIds = new Map<string, string>();
+    const announced = new Set<string>();
+
+    for await (const frame of parseFreepiSse(body)) {
+      if (frame.event === "done") {
+        const data = frame.data as { finish_reason?: unknown };
+        if (typeof data.finish_reason === "string") {
+          stopReason = STOP_REASONS[data.finish_reason] ?? "stop";
+        }
+        continue;
+      }
+      if (typeof frame.data !== "object" || frame.data === null) continue;
+      const record = frame.data as Record<string, unknown>;
+
+      // Upstream error payloads can be HTTP 200 `{"error":{...}}`.
+      if (record["error"] !== undefined && typeof record["error"] === "object") {
+        const nested = record["error"] as Record<string, unknown>;
+        throwFreepiUpstreamError(nested["code"], nested["message"]);
+      }
+      if (record["code"] !== undefined) {
+        throwFreepiUpstreamError(record["code"], record["message"]);
+      }
+
+      const choices = Array.isArray(record["choices"]) ? (record["choices"] as Record<string, unknown>[]) : [];
+      const choice = choices[0];
+      if (!choice) continue;
+      const delta = choice["delta"] as Record<string, unknown> | undefined;
+      if (!delta) continue;
+
+      const text = delta["content"];
+      if (typeof text === "string" && text.length > 0) {
+        yield {
+          type: "content_delta",
+          sequence_number: seq++,
+          content: { kind: "text", text },
+        } as CanonicalEvent;
+      }
+      const reasoning = delta["reasoning_content"];
+      if (typeof reasoning === "string" && reasoning.length > 0) {
+        yield {
+          type: "content_delta",
+          sequence_number: seq++,
+          content: { kind: "reasoning", payload: null, summary: reasoning },
+        } as CanonicalEvent;
+      }
+      yield* this.#toolCallDeltas(delta["tool_calls"], announced, toolCallIds, () => seq++);
+      if (typeof choice["finish_reason"] === "string" && choice["finish_reason"] !== null) {
+        stopReason = STOP_REASONS[String(choice["finish_reason"])] ?? "stop";
+      }
+      const u = record["usage"];
+      if (typeof u === "object" && u !== null) usage = u as Record<string, unknown>;
+    }
+
+    const assessed = usage === undefined ? undefined : usageFromProvider(usage);
+    if (assessed !== undefined) {
+      yield { type: "usage", sequence_number: seq++, usage: assessed } as unknown as CanonicalEvent;
+    }
+    yield {
+      type: "terminal",
+      sequence_number: seq,
+      state: "complete",
+      stop_reason: stopReason,
+      ...(assessed === undefined ? {} : { usage: assessed }),
+      ...(sessionId !== undefined ? { prompt_cache_key: sessionId } : {}),
+    } as unknown as CanonicalEvent;
+  }
+
+  /**
+   * Emits canonical tool-call deltas from one OpenAI `tool_calls` array.
+   *
+   * The upstream spreads one call over many frames: the first carries id and
+   * name, the middle ones carry `arguments` as successive JSON fragments with
+   * an empty id, and the last repeats the id with no arguments. Grouping by
+   * `index` ties them together — the id is absent exactly when the arguments
+   * are present, so keying on id would drop every fragment.
+   */
+  async *#toolCallDeltas(
+    raw: unknown,
+    announced: Set<string>,
+    toolCallIds: Map<string, string>,
+    nextSeq: () => number,
+  ): AsyncIterable<CanonicalEvent> {
+    if (!Array.isArray(raw)) return;
+    for (const entry of raw) {
+      if (typeof entry !== "object" || entry === null) continue;
+      const call = entry as Record<string, unknown>;
+      const fn = call["function"];
+      const fnRecord = typeof fn === "object" && fn !== null ? (fn as Record<string, unknown>) : undefined;
+      const name = typeof fnRecord?.["name"] === "string" ? (fnRecord["name"] as string) : undefined;
+      const args = typeof fnRecord?.["arguments"] === "string" ? (fnRecord["arguments"] as string) : "";
+      const declaredId = typeof call["id"] === "string" ? call["id"] : "";
+      const index = typeof call["index"] === "number" ? call["index"] : 0;
+      const slot = `idx:${index}`;
+
+      if (declaredId.length > 0) {
+        toolCallIds.set(slot, declaredId);
+        if (announced.has(declaredId)) continue;
+        announced.add(declaredId);
+        yield {
+          type: "tool_call_delta",
+          sequence_number: nextSeq(),
+          call_id: declaredId,
+          name: name ?? "",
+          arguments_delta: "",
+        } as CanonicalEvent;
+        if (args.length === 0) continue;
+      }
+
+      if (args.length === 0) continue;
+      const id = toolCallIds.get(slot);
+      if (id === undefined) continue;
+      yield {
+        type: "tool_call_delta",
+        sequence_number: nextSeq(),
+        call_id: id,
+        arguments_delta: args,
+      } as CanonicalEvent;
+    }
+  }
+}
+
+/** Adapter for the international free-pi deployment. */
+export function createFreepiAdapter(options: FreepiAdapterOptions = {}): ProviderAdapter {
+  return new FreepiAdapter({ ...options, providerId: FREEPI_PROVIDER_ID });
+}