cartethyia 2.4.6 → 2.5.1

package/migrations/full-postgres/0018_add_accounts_quota_plan.sql

@@ -0,0 +1,18 @@
+-- The plan the provider reports for this account, last seen by a quota read.
+--
+-- Routing needs it because some upstreams gate models on it. CodeBuddy
+-- refuses a set of models on a free plan with `11158 "model [X] is not allowed
+-- for user type [personal_free_user]"`, and nothing in its model directory
+-- predicts which — only the account's own plan does. Without a persisted plan
+-- the router cannot tell a pro account from a free one and would keep sending
+-- pro-only traffic to an account that is certain to be refused.
+--
+-- Persisted rather than read from the quota cache: the cache is a 900 second
+-- in-process TTL and empty on a cold start, so an account's plan would be
+-- unknown exactly when a freshly booted process makes its first decisions.
+-- The row is the only place that survives a restart.
+--
+-- Nullable: most providers report no plan at all, and an account whose plan
+-- was never read must say so rather than inventing one.
+ALTER TABLE "provider_accounts"
+  ADD COLUMN IF NOT EXISTS "quota_plan" text;

package/migrations/full-postgres/0019_add_models_free_tier.sql

@@ -0,0 +1,15 @@
+-- Whether the provider publishes this model as free.
+--
+-- Qoder states `is_free` per row in its own model directory, so the tier is a
+-- fact the provider reports rather than something we have to infer. That is the
+-- opposite of `pro_only`, which exists because CodeBuddy publishes nothing that
+-- predicts plan access and only the refusal itself is a signal.
+--
+-- Nullable three-valued on purpose, matching `pro_only`: `true` is free,
+-- `false` is billed, and `NULL` is "the provider did not state it". Qoder omits
+-- the field entirely for several rows, and collapsing that absence into `false`
+-- would assert a measured fact for models nobody measured. Absence must also
+-- stay distinct from `false` on the surface, or a row that simply predates this
+-- column would render as a billed model.
+ALTER TABLE "models"
+  ADD COLUMN IF NOT EXISTS "free_tier" boolean;

package/migrations/lite-sqlite3/0015_add_payload_stages.sql

@@ -0,0 +1,18 @@
+-- Which payload stages were captured for a request, as a bitmask.
+--
+-- The detail drawer shows four panels (client request, provider request,
+-- provider response, client response), and the Usage list shows one icon per
+-- panel. Reading the frame to learn which stages exist costs an inflate per
+-- row, so the writer records presence here at capture time and the list reads
+-- it with the indexed row it already fetches.
+--
+-- Bit 0 (1) = request_body, bit 1 (2) = provider_request_body,
+-- bit 2 (4) = provider_response_body, bit 3 (8) = client_response_body.
+-- `response_body` is the legacy alias of the client response and is not
+-- tracked: it never names a stage the other four do not.
+--
+-- Nullable with no default: NULL means the row predates this column, and the
+-- list renders every icon greyed — an old row never observed presence, so
+-- inventing it would be a claim.
+ALTER TABLE "telemetry_payloads"
+  ADD COLUMN "stages" integer;

package/migrations/lite-sqlite3/0016_add_share_link_slug.sql

@@ -0,0 +1,20 @@
+-- The public slug a share page is reachable at, held in the clear.
+--
+-- `token_encrypted` is the bearer token under the deployment's encryption key,
+-- so a link cannot be re-displayed after that key changes — which is exactly
+-- what happens when a backup is restored onto a fresh deployment. A share page
+-- then dies on arrival even though the backup carried its row.
+--
+-- The slug is the half of the link that is not a secret: it names the page in
+-- the URL and is looked up by index. Holding it in the clear means a restore
+-- keeps every share page reachable under the same address, independent of the
+-- encryption key.
+--
+-- Nullable with no default: rows written before this column have no slug, and
+-- inventing one would publish an address the page never had.
+ALTER TABLE "share_links"
+  ADD COLUMN "slug" text;
+
+CREATE UNIQUE INDEX "share_links_slug_uidx"
+  ON "share_links" ("slug")
+  WHERE "slug" IS NOT NULL;

package/migrations/lite-sqlite3/0017_add_models_pro_only.sql

@@ -0,0 +1,18 @@
+-- Whether the upstream refuses this model on a free plan.
+--
+-- CodeBuddy is why this is a column and not a derived rule. Its console
+-- directory publishes no field that predicts access: `credits` and `vendor`
+-- were both measured against real dispatches and neither correlates — one model
+-- billed at `x1.62` is served on a free account while one billed at `x0.14` is
+-- refused. The only signal is the refusal itself, `11158 "model [X] is not
+-- allowed for user type [personal_free_user]"`, so the answer has to be
+-- recorded per model rather than computed from the catalog.
+--
+-- Nullable three-valued on purpose. `true` is refused on a free plan and
+-- `false` is served there; `NULL` is "nobody established it", which is the
+-- state of every model on every provider that publishes nothing about plan
+-- access. Collapsing that into `false` would assert, for thousands of rows, a
+-- fact nobody measured — and would make a pro-only row that predates this
+-- column indistinguishable from a genuinely free one.
+ALTER TABLE "models"
+  ADD COLUMN "pro_only" boolean;

package/migrations/lite-sqlite3/0018_add_accounts_quota_plan.sql

@@ -0,0 +1,18 @@
+-- The plan the provider reports for this account, last seen by a quota read.
+--
+-- Routing needs it because some upstreams gate models on it. CodeBuddy
+-- refuses a set of models on a free plan with `11158 "model [X] is not allowed
+-- for user type [personal_free_user]"`, and nothing in its model directory
+-- predicts which — only the account's own plan does. Without a persisted plan
+-- the router cannot tell a pro account from a free one and would keep sending
+-- pro-only traffic to an account that is certain to be refused.
+--
+-- Persisted rather than read from the quota cache: the cache is a 900 second
+-- in-process TTL and empty on a cold start, so an account's plan would be
+-- unknown exactly when a freshly booted process makes its first decisions.
+-- The row is the only place that survives a restart.
+--
+-- Nullable: most providers report no plan at all, and an account whose plan
+-- was never read must say so rather than inventing one.
+ALTER TABLE "provider_accounts"
+  ADD COLUMN "quota_plan" text;

package/migrations/lite-sqlite3/0019_add_models_free_tier.sql

@@ -0,0 +1,15 @@
+-- Whether the provider publishes this model as free.
+--
+-- Qoder states `is_free` per row in its own model directory, so the tier is a
+-- fact the provider reports rather than something we have to infer. That is the
+-- opposite of `pro_only`, which exists because CodeBuddy publishes nothing that
+-- predicts plan access and only the refusal itself is a signal.
+--
+-- Nullable three-valued on purpose, matching `pro_only`: `true` is free,
+-- `false` is billed, and `NULL` is "the provider did not state it". Qoder omits
+-- the field entirely for several rows, and collapsing that absence into `false`
+-- would assert a measured fact for models nobody measured. Absence must also
+-- stay distinct from `false` on the surface, or a row that simply predates this
+-- column would render as a billed model.
+ALTER TABLE "models"
+  ADD COLUMN "free_tier" boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cartethyia",
-  "version": "2.4.6",
+  "version": "2.5.1",
   "description": "A powerful, self-hosted reverse proxy for OpenAI- and Anthropic-compatible AI clients, powered by native Bun and Elysia. It serves both protocols from a single server, routes every model across any configured provider, and translates requests and responses in real time — streaming and prompt caching included. Underneath it runs a full delivery engine: per-account health tracking, quota and cooldown enforcement, automatic failover across pools and providers, usage accounting, and telemetry. Point OpenCode, Cline, Claude Code, Codex, or any compatible client at Cartethyia and it keeps its native protocol while the gateway absorbs every provider-specific difference behind it. Runs on embedded SQLite or external PostgreSQL with optional Redis coordination, ships as a global CLI with a system-tray console, and needs only Bun 1.4+ alongside Node.js/npm.",
   "license": "GPL-3.0-only",
   "type": "module",
@@ -45,7 +45,7 @@
     "build": "bun run scripts/binary/build.ts",
     "prepack": "bun run dashboard:build",
     "setup": "bun run scripts/cli/command/setup.ts",
-    "start": "bun run scripts/binary/start.ts",
+    "start": "bun run scripts/cli/main.ts start",
     "doctor": "bun run scripts/cli/command/doctor.ts",
     "probe:egress": "bun run scripts/operations/probe-egress.ts",
     "restart": "bun run scripts/binary/restart.ts",
@@ -78,6 +78,7 @@
     "pg": "8.23.0",
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
+    "protobufjs": "^7.6.5",
     "socks-proxy-agent": "^10.1.0",
     "systray2": "2.1.4",
     "typebox": "1.3.27",

package/scripts/cli/command/console-menu.ts

@@ -1,4 +1,7 @@
 import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
 import { isNewerRelease } from "../../../src/console/updates/version-compare";
 import { resolvePackagePath } from "../../../src/config/package-paths";
 import { resolvePort } from "../../../src/config/runtime";
@@ -7,7 +10,7 @@ import { startGateway } from "../gateway/spawn";
 import { stopGateway } from "../gateway/stop";
 import { ENV_PATH, readEnvFile } from "../support/env";
 import { readInstalledVersion, readLatestPublishedVersion } from "../support/version";
-import { launchBackground, openUrl } from "../ui/background";
+import { launchBackgroundWithStatus, openUrl } from "../ui/background";
 import { chooseFromMenu, confirmByTyping, confirmStep } from "../ui/prompt";
 import { renderWordmark } from "../ui/wordmark";
 import { exportBackup, resetConsoleAccount } from "./admin";
@@ -185,20 +188,36 @@ export async function startMenu(): Promise<void> {
         return;
       },
       async () => {
-        // Start a detached `tray` process that owns the gateway from scratch,
-        // then drain this one so the new process can claim the port. This is
-        // the pattern 9router uses and it is simpler than handing a live
-        // gateway between processes: the tray is a normal first-class run, not
-        // an adopted orphan, so Exit and update behave the same whether the
-        // gateway was started here or from `carte --tray`.
-        console.log("Starting the tray in the background…");
-        launchBackground(["run", resolvePackagePath("scripts", "cli", "main.ts"), "tray"]);
+        // Drain first, then start the tray.
+        //
+        // The tray's own startup probe refuses to boot when the port is busy,
+        // so starting it before this process has let go made it fail with
+        // "already running on port" every time — while the menu still printed
+        // that everything was running, because a detached child with no stdio
+        // cannot report anything back. Releasing the port first is the fix, and
+        // waiting on the child's signal is what stops the menu from claiming
+        // success for a child that died.
+        console.log("Stopping the gateway to free the port…");
         running = false;
         stopping = true;
         handedOff = true;
         await shutDown();
-        console.log(`Cartethyia is running in the background at ${dashboardUrl}.`);
-        console.log("The tray icon owns it; use Exit there to stop it.");
+        console.log("Starting the tray in the background…");
+        const signalPath = join(tmpdir(), `cartethyia-tray-menu-${process.pid}-${randomUUID()}.json`);
+        try {
+          const url = await launchBackgroundWithStatus(
+            ["run", resolvePackagePath("scripts", "cli", "main.ts"), "tray"],
+            { signalPath },
+          );
+          console.log(`Cartethyia is running in the background at ${url || dashboardUrl}.`);
+          console.log("The tray icon owns it; use Exit there to stop it.");
+        } catch (error) {
+          handedOff = false;
+          console.error(
+            `Could not hand off to the tray: ${error instanceof Error ? error.message : "unknown error"}`,
+          );
+          console.error("Cartethyia is stopped. Start it again from this menu.");
+        }
       },
       async () => {
         running = false;

package/scripts/cli/command/start.ts

@@ -1,13 +1,77 @@
-import { ensureDrainToken } from "../gateway/drain-token";
-
-/**
- * Runs the gateway in the foreground, in this process.
- *
- * A foreground run still needs a drain token on disk: the gateway registers
- * `/admin/drain` only when one is set, and "Hide to tray" hands this run to a
- * tray that drains it through that route.
- */
-export async function startForeground(): Promise<void> {
-  process.env.CARTETHYIA_DRAIN_TOKEN ??= ensureDrainToken();
-  await import("../../../src/main");
-}
+import { resolvePort } from "../../../src/config/runtime";
+import { ensureDrainToken } from "../gateway/drain-token";
+import { clearInstanceLock, pidAlive, readInstanceLock, writeInstanceLock } from "../gateway/instance-lock";
+
+/**
+ * Runs the gateway in the foreground, in this process.
+ *
+ * A foreground run still needs a drain token on disk: the gateway registers
+ * `/admin/drain` only when one is set, and "Hide to tray" hands this run to a
+ * tray that drains it through that route.
+ *
+ * Unlike the menu and tray paths this one does not spawn a child, so the
+ * port-busy check has to happen here too — otherwise a stale gateway makes a
+ * plain `cartethyia start` fail from inside `src/main` with a message that says
+ * nothing about what to do.
+ */
+export async function startForeground(): Promise<void> {
+  const token = ensureDrainToken();
+  process.env.CARTETHYIA_DRAIN_TOKEN ??= token;
+  const port = resolvePort();
+  const blocker = await inspectPortHolder(port, token);
+  if (blocker !== null) throw new Error(blocker);
+  writeInstanceLock(port, process.pid, token);
+  await import("../../../src/main");
+}
+
+/**
+ * What to tell the operator when the port is already taken, or `null` when the
+ * port is free (or was freed).
+ *
+ * Same rule as the spawned path: only ever stop a gateway that proves it is
+ * this install's own. A drain request is token-gated, so a 401 means another
+ * Cartethyia install and anything else is not a gateway at all — neither may be
+ * touched, and both are reported instead.
+ */
+async function inspectPortHolder(port: number, token: string): Promise<string | null> {
+  const up = await fetch(`http://127.0.0.1:${port}/health`, {
+    signal: AbortSignal.timeout(1_000),
+  }).catch(() => null);
+  if (up === null) {
+    // Port is free. Drop a stale marker from a crashed run so the next start
+    // does not read a dead pid as a live gateway.
+    const lock = readInstanceLock();
+    if (lock !== null && lock.port === port && !pidAlive(lock.pid)) clearInstanceLock();
+    return null;
+  }
+  const response = await fetch(`http://127.0.0.1:${port}/admin/drain`, {
+    method: "POST",
+    headers: { "x-drain-token": token },
+    signal: AbortSignal.timeout(3_000),
+  }).catch(() => null);
+  if (response === null) {
+    return `Port ${port} is busy and nothing there answers a drain request. Stop whatever holds it, or set a different PORT.`;
+  }
+  if (response.status === 401) {
+    return `Another Cartethyia gateway is already running on port ${port} under a different install. Stop it from its own terminal or tray — this install will not stop a gateway it does not own.`;
+  }
+  if (response.status === 403) {
+    return `Port ${port} refused a drain from loopback. Stop what holds it, then start again.`;
+  }
+  if (response.status !== 202) {
+    return `Port ${port} is busy and refused to drain (HTTP ${response.status}). Stop it manually, then start again.`;
+  }
+  // Drain accepted; wait for the port to actually close.
+  const deadline = Date.now() + 30_000;
+  while (Date.now() < deadline) {
+    const stillUp = await fetch(`http://127.0.0.1:${port}/health`, {
+      signal: AbortSignal.timeout(500),
+    }).catch(() => null);
+    if (stillUp === null) {
+      clearInstanceLock();
+      return null;
+    }
+    await Bun.sleep(200);
+  }
+  return `The gateway on port ${port} accepted a drain but did not release the port within 30 seconds. Stop it manually, then start again.`;
+}

package/scripts/cli/command/tray.ts

@@ -17,7 +17,29 @@ import { printUpdateInstructions } from "./update";
  * an empty console tab open for the tray's whole lifetime, and that window is
  * owned by Windows Terminal — not by this process, so it cannot be found and
  * hidden from inside.
+ *
+ * The gateway it starts is detached, which is what makes the health poll below
+ * necessary — see {@link TRAY_HEALTH_POLL_MS}.
  */
+
+/**
+ * How often the tray asks whether the gateway is still answering.
+ *
+ * 10 s: often enough that an operator who stops the gateway by hand sees the
+ * icon go away, and far below the cost of a request. A detached gateway can no
+ * longer be waited on, so this poll is the only signal left.
+ */
+const TRAY_HEALTH_POLL_MS = 10_000;
+
+/**
+ * Consecutive misses to forgive before a dead gateway closes the tray.
+ *
+ * One refusal is not a stopped gateway — a probe can lose a race with startup
+ * or a slow request — and closing the icon on one would make startup feel
+ * random.
+ */
+const TRAY_HEALTH_MISSES_BEFORE_CLOSE = 3;
+
 export async function startTray(): Promise<void> {
   const port = resolvePort();
   const drainToken = ensureDrainToken();
@@ -137,7 +159,13 @@ export async function startTray(): Promise<void> {
 
   try {
     await tray.ready();
-    gateway = await startGateway(port, drainToken);
+    // Detached, unlike every other caller: the gateway must outlive this
+    // process. Attached, it dies with the tray — and the tray dies with the
+    // terminal that launched it, so closing that terminal took the gateway
+    // down too and "Hide to tray" left nothing serving. `stopGateway` drains
+    // over HTTP before it ever reaches for `kill()`, so detaching costs the
+    // exit path nothing: the tray can still stop the gateway on Exit.
+    gateway = await startGateway(port, drainToken, { detached: true });
     // The launcher that spawned this tray is blocked on a signal file: it
     // cannot read our stdio, because the tray is detached. Without this write
     // it waits out its 60 s deadline and reports a failure for a tray that is
@@ -146,17 +174,28 @@ export async function startTray(): Promise<void> {
     console.log(`Cartethyia is running at ${dashboardUrl}`);
     void refreshVersion();
 
+    let misses = 0;
+    // A detached child's `exited` never settles on Windows, so the old
+    // `await current.exited` would have parked here forever and the tray would
+    // never notice the gateway going away. Poll its health endpoint instead:
+    // that answers for a process we no longer own, which is the whole point of
+    // detaching it. The probe is the same one startup used, so a gateway that
+    // is up reads as up regardless of who spawned it.
     while (!closing) {
-      const current: Bun.Subprocess | null = gateway;
-      if (!current) {
-        await Bun.sleep(100);
+      await Bun.sleep(TRAY_HEALTH_POLL_MS);
+      if (closing || gateway === null) continue;
+      const alive = await fetch(`http://127.0.0.1:${port}/health`, {
+        signal: AbortSignal.timeout(2_000),
+      }).then((response) => response.ok).catch(() => false);
+      if (alive) {
+        misses = 0;
         continue;
       }
-      const code = await current.exited;
-      if (gateway !== current || closing) continue;
+      misses += 1;
+      if (misses < TRAY_HEALTH_MISSES_BEFORE_CLOSE) continue;
       gateway = null;
-      console.error(`Cartethyia exited with code ${code}.`);
-      await close(code ?? 1);
+      console.error("Cartethyia stopped answering; the tray is closing.");
+      await close(1);
     }
   } catch (error) {
     await close(1);

package/scripts/cli/command/update.ts

@@ -8,7 +8,7 @@
  * the same shape 9router uses.
  */
 export function updateCommand(): string {
-  return "npm install --global cartethyia@latest --prefer-online";
+  return "npm install -g cartethyia@latest --prefer-online";
 }
 
 /** Prints the "run this now" block after Cartethyia has stopped. */

package/scripts/cli/gateway/instance-lock.ts

@@ -0,0 +1,105 @@
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * A marker that one gateway owns this install's port.
+ *
+ * The port probe alone cannot tell a healthy gateway from a stranger's process:
+ * something answering on 12800 is not necessarily ours, so a start that found
+ * the port busy either failed outright or — worse — would have to guess before
+ * stopping anything. The lock names the PID and the token it was written with,
+ * which is what makes "is this our gateway?" answerable without guessing.
+ *
+ * It is advisory, not an OS lock: a stale file from a crashed process is the
+ * normal case this exists to recover from, so presence alone never blocks a
+ * start. Liveness is decided by probing the port, and identity by the token.
+ */
+export interface InstanceLock {
+  readonly pid: number;
+  readonly port: number;
+  /** Fingerprint of the drain token, never the token itself. */
+  readonly tokenFingerprint: string;
+  readonly startedAt: string;
+}
+
+const LOCK_FILE = "instance.json";
+
+function lockPath(): string | null {
+  const configDir = process.env.CARTETHYIA_CONFIG_DIR;
+  return configDir ? join(configDir, LOCK_FILE) : null;
+}
+
+/** A short, non-reversible fingerprint so the token itself is never written. */
+export function fingerprint(token: string): string {
+  let hash = 0;
+  for (let i = 0; i < token.length; i += 1) {
+    hash = (hash * 31 + token.charCodeAt(i)) | 0;
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+
+export function writeInstanceLock(port: number, pid: number, token: string): void {
+  const path = lockPath();
+  if (path === null) return;
+  const lock: InstanceLock = {
+    pid,
+    port,
+    tokenFingerprint: fingerprint(token),
+    startedAt: new Date().toISOString(),
+  };
+  try {
+    writeFileSync(path, JSON.stringify(lock), { encoding: "utf8", mode: 0o600 });
+  } catch {
+    // A read-only config directory costs the marker, not the run.
+  }
+}
+
+export function readInstanceLock(): InstanceLock | null {
+  const path = lockPath();
+  if (path === null || !existsSync(path)) return null;
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+    if (
+      parsed !== null &&
+      typeof parsed === "object" &&
+      "pid" in parsed &&
+      typeof parsed.pid === "number" &&
+      "port" in parsed &&
+      typeof parsed.port === "number" &&
+      "tokenFingerprint" in parsed &&
+      typeof parsed.tokenFingerprint === "string"
+    ) {
+      const startedAt = "startedAt" in parsed && typeof parsed.startedAt === "string" ? parsed.startedAt : "";
+      return {
+        pid: parsed.pid,
+        port: parsed.port,
+        tokenFingerprint: parsed.tokenFingerprint,
+        startedAt,
+      };
+    }
+  } catch {
+    // A corrupt marker reads as none.
+  }
+  return null;
+}
+
+export function clearInstanceLock(): void {
+  const path = lockPath();
+  if (path === null) return;
+  try {
+    unlinkSync(path);
+  } catch {
+    // Already gone, or the directory is read-only.
+  }
+}
+
+/** Whether a process id is alive. `0` is never a real pid. */
+export function pidAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}