cartethyia 2.7.7 → 2.7.9

package/src/providers/integrations/devin/protocol/framing.ts

@@ -0,0 +1,124 @@
+/**
+ * Devin (Codeium Cascade) Connect framing.
+ *
+ * Connect protocol over HTTP/1.1: a request body is a single frame
+ * `[flags 1 byte][length 4 bytes BE][payload]`; the response is a stream of
+ * the same frames. Flags: 0x01 = payload gzip-compressed, 0x02 = end-of-
+ * stream (trailer JSON). Ported from oh-my-pi / opencode-devin-provider
+ * (MIT) and adapted to Cartethyia.
+ */
+
+import { randomBytes } from "node:crypto";
+import { gzipSync, gunzipSync } from "node:zlib";
+
+export const CONNECT_COMPRESSED_FLAG = 0x01;
+export const CONNECT_END_STREAM_FLAG = 0x02;
+
+/** Cap on one frame payload, guarding against a hostile length prefix. */
+export const MAX_CONNECT_FRAME_PAYLOAD = 16 * 1024 * 1024;
+
+/** Request bodies at or above this size are gzip-compressed. */
+export const MIN_COMPRESSED_BODY_BYTES = 1024;
+
+export class ConnectFrameError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ConnectFrameError";
+  }
+}
+
+export interface ConnectFrame {
+  readonly flags: number;
+  readonly payload: Uint8Array;
+  readonly compressed: boolean;
+}
+
+/** Encodes one payload into a Connect frame, compressing when `compress` is set. */
+export function encodeFrame(payload: Uint8Array, compress: boolean): Buffer {
+  const useCompression = compress && payload.byteLength >= MIN_COMPRESSED_BODY_BYTES;
+  const body = useCompression ? gzipSync(payload) : Buffer.from(payload);
+  const flags = useCompression ? CONNECT_COMPRESSED_FLAG : 0;
+  const header = Buffer.alloc(5);
+  header[0] = flags;
+  header.writeUInt32BE(body.length, 1);
+  return Buffer.concat([header, body]);
+}
+
+/** Decodes one frame from a buffer containing exactly one frame. */
+export function decodeFrame(buf: Buffer): ConnectFrame {
+  if (buf.length < 5) {
+    throw new ConnectFrameError(`frame shorter than 5-byte header (${buf.length})`);
+  }
+  const flags = buf[0]!;
+  const length = buf.readUInt32BE(1);
+  if (length > MAX_CONNECT_FRAME_PAYLOAD) {
+    throw new ConnectFrameError(`frame payload ${length} exceeds ${MAX_CONNECT_FRAME_PAYLOAD} cap`);
+  }
+  const payload = buf.subarray(5, 5 + length);
+  return {
+    flags,
+    payload,
+    compressed: (flags & CONNECT_COMPRESSED_FLAG) !== 0,
+  };
+}
+
+/** Decompresses a frame payload if its compressed flag is set. */
+export function deframe(payload: Uint8Array, compressed: boolean): Buffer {
+  return compressed ? gunzipSync(payload) : Buffer.from(payload);
+}
+
+/**
+ * Incremental frame reader over a byte stream. Consumes as many complete
+ * frames as the input holds; a trailing partial frame is buffered until more
+ * bytes arrive.
+ */
+export class ConnectFrameDecoder {
+  #buffer = Buffer.alloc(0);
+
+  push(chunk: Uint8Array): ConnectFrame[] {
+    this.#buffer = this.#buffer.length === 0 ? Buffer.from(chunk) : Buffer.concat([this.#buffer, chunk]);
+    const frames: ConnectFrame[] = [];
+    for (;;) {
+      if (this.#buffer.length < 5) break;
+      const length = this.#buffer.readUInt32BE(1);
+      if (length > MAX_CONNECT_FRAME_PAYLOAD) {
+        throw new ConnectFrameError(`frame payload ${length} exceeds ${MAX_CONNECT_FRAME_PAYLOAD} cap`);
+      }
+      if (this.#buffer.length < 5 + length) break;
+      frames.push(decodeFrame(this.#buffer.subarray(0, 5 + length)));
+      this.#buffer = this.#buffer.subarray(5 + length);
+    }
+    return frames;
+  }
+
+  /** True when a partial frame is buffered (stream ended mid-frame). */
+  get hasPartial(): boolean {
+    return this.#buffer.length > 0;
+  }
+}
+
+/** Parses the Connect end-of-stream trailer JSON: `{error:{code,message}}`. */
+export interface ConnectTrailer {
+  readonly error?: { readonly code?: string; readonly message?: string };
+  readonly details?: unknown;
+}
+
+export function parseTrailer(payload: Uint8Array): ConnectTrailer {
+  const text = new TextDecoder().decode(payload).trim();
+  if (!text) return {};
+  try {
+    const parsed = JSON.parse(text) as ConnectTrailer;
+    return parsed;
+  } catch {
+    return {};
+  }
+}
+
+/** Deterministic random UUID for execution ids (avoids importing node crypto in browser-safe paths). */
+export function newExecutionId(): string {
+  const bytes = randomBytes(16);
+  bytes[6] = (bytes[6]! & 0x0f) | 0x40;
+  bytes[8] = (bytes[8]! & 0x3f) | 0x80;
+  const hex = bytes.toString("hex");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

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

@@ -555,7 +555,7 @@ class FactoryDroidAdapter implements ProviderAdapter {
       yield {
         type: "content_delta",
         sequence_number: seq++,
-        content: { kind: "reasoning", payload: null, summary: output.thought },
+        content: { kind: "reasoning", payload: null, summary: output.thought, ...(output.thoughtSignature ? { signature: output.thoughtSignature } : {}) },
       } as CanonicalEvent;
     }
     if (output.text) {
@@ -606,7 +606,7 @@ class FactoryDroidAdapter implements ProviderAdapter {
         yield {
           type: "content_delta",
           sequence_number: seq++,
-          content: { kind: "reasoning", payload: null, summary: output.thought },
+          content: { kind: "reasoning", payload: null, summary: output.thought, ...(output.thoughtSignature ? { signature: output.thoughtSignature } : {}) },
         } as CanonicalEvent;
       }
       if (output.text) {

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();