cartethyia 2.4.5 → 2.5.0

package/scripts/cli/ui/background.ts

@@ -0,0 +1,110 @@
+import { spawn } from "node:child_process";
+import { readFileSync, unlinkSync } from "node:fs";
+import { PACKAGE_ROOT, resolvePackagePath } from "../../../src/config/package-paths";
+
+/** Opens a URL in the operator's default browser, ignoring a missing handler. */
+export function openUrl(url: string): Promise<void> {
+  const command = process.platform === "win32"
+    ? "explorer.exe"
+    : process.platform === "darwin"
+      ? "open"
+      : "xdg-open";
+  const child = Bun.spawn([command, url], {
+    stdin: "ignore",
+    stdout: "ignore",
+    stderr: "ignore",
+  });
+  return child.exited.then(() => undefined);
+}
+
+/**
+ * Starts a detached process and resolves once it reports readiness.
+ *
+ * The child owns no stdio, so a signal file is the only channel that survives
+ * the parent. Without it the caller prints "running in the background" for a
+ * child that may already have died — which is exactly what a port clash looks
+ * like, because the child's own startup probe fails while the parent's gateway
+ * still holds the port.
+ *
+ * Resolves with the URL the child reported. Rejects with the child's message
+ * when it reports failure, or with a timeout if it never reports at all.
+ */
+export function launchBackgroundWithStatus(
+  args: readonly string[],
+  options: { readonly signalPath: string; readonly timeoutMs?: number } = { signalPath: "" },
+): Promise<string> {
+  return new Promise<string>((resolve, reject) => {
+    const signalPath = options.signalPath;
+    const deadline = Date.now() + (options.timeoutMs ?? 60_000);
+    let settled = false;
+    const finish = (error: Error | null, url?: string): void => {
+      if (settled) return;
+      settled = true;
+      clearInterval(timer);
+      try {
+        unlinkSync(signalPath);
+      } catch {}
+      if (error) reject(error);
+      else resolve(url ?? "");
+    };
+
+    const env = { ...process.env, CARTETHYIA_TRAY_STARTUP_SIGNAL: signalPath };
+    spawnBackground(args, env);
+
+    const timer = setInterval(() => {
+      if (settled) return;
+      let raw: string;
+      try {
+        raw = readFileSync(signalPath, "utf8");
+      } catch {
+        if (Date.now() >= deadline) finish(new Error("the background process did not report startup within the deadline"));
+        return;
+      }
+      try {
+        const signal = JSON.parse(raw) as { status?: string; url?: string; message?: string };
+        if (signal.status === "ready" && typeof signal.url === "string") finish(null, signal.url);
+        else if (signal.status === "failed") finish(new Error(signal.message ?? "the background process failed to start"));
+      } catch {
+        // A partially written file is read again on the next tick.
+      }
+    }, 150);
+    timer.unref?.();
+  });
+}
+
+/**
+ * Starts a Bun process that owns no console window.
+ *
+ * On Windows, spawning the child directly is not enough: a console-subsystem
+ * child of a window-less parent allocates a new console, and when the parent is
+ * inside Windows Terminal the tab is already on screen before any flag can take
+ * effect — measured: `detached: true` plus `windowsHide: true` still produced a
+ * Windows Terminal window titled with the bun path. `wscript.exe` is a
+ * GUI-subsystem host, so it never allocates a console, and a child launched
+ * from it with window style 0 inherits that. The VBS is that launcher.
+ *
+ * Elsewhere `detached` is enough and the helper is not used.
+ */
+export function launchBackground(args: readonly string[]): void {
+  spawnBackground(args, process.env);
+}
+
+function spawnBackground(args: readonly string[], env: NodeJS.ProcessEnv): void {
+  if (process.platform !== "win32") {
+    const child = spawn(process.execPath, [...args], {
+      cwd: PACKAGE_ROOT,
+      detached: true,
+      stdio: "ignore",
+      env,
+    });
+    child.unref();
+    return;
+  }
+  const launcher = resolvePackagePath("scripts", "cli", "tray", "hidden-window.vbs");
+  const child = spawn(
+    "wscript.exe",
+    ["//nologo", launcher, process.execPath, ...args],
+    { cwd: PACKAGE_ROOT, detached: true, stdio: "ignore", windowsHide: true, env },
+  );
+  child.unref();
+}

package/src/boot/app.ts

@@ -34,14 +34,21 @@ import {
 import { createResponsesCompactHandler } from "../transport/dispatch/responses-compact";
 import { createSystemoneHandler } from "../transport/dispatch/systemone";
 import { createWebsearchHandler } from "../transport/dispatch/websearch";
-import { createImageGenerationHandler, createVideoGenerationHandler } from "../transport/dispatch/generation";
+import {
+  createAudioSpeechHandler,
+  createAudioTranscriptionHandler,
+  createEmbeddingHandler,
+  createImageGenerationHandler,
+  createVideoGenerationHandler,
+} from "../transport/dispatch/generation";
 import { createTokenCountHandler } from "../transport/dispatch/token-count";
 
 import { createTransportPipeline } from "../transport/guards/pipeline";
 import { createDrainHandler, isLoopbackPeer, tokenMatches } from "../transport/drain-endpoint";
 import { createConsoleAccountResetHandler } from "../console/auth/account-reset";
+import { resetConsoleAuthState } from "../console/auth/account-reset-store";
 import { createBackupExportHandler } from "../console/backup/export-endpoint";
-import { consoleUsers, tenants } from "../persistence/schema";
+import { tenants } from "../persistence/schema";
 import { PublicModelCatalogStore, type AllowedModelEntry } from "../console/providers/catalog/public-model-store";
 import type { IpAbuseProtectionService } from "../security/abuse";
 import type { ReadinessCheckResult } from "../persistence/readiness";
@@ -196,7 +203,9 @@ export function createGatewayApp(deps: GatewayAppDeps) {
   const peerAddresses = new WeakMap<Request, string>();
   const serveDashboard = async ({ request }: { request: Request }): Promise<Response> => {
     const pathname = fastPathname(request.url);
-    const result = await staticHandler(pathname);
+    // The client's `accept-encoding` is what decides whether a precompressed
+    // `.gz` sibling can be served instead of the plain asset.
+    const result = await staticHandler(pathname, request.headers.get("accept-encoding"));
     return new Response(result.body ? (result.body as unknown as BodyInit) : null, {
       status: result.status,
       headers: result.headers,
@@ -512,6 +521,13 @@ export function createGatewayApp(deps: GatewayAppDeps) {
     // Mounted with no model behind it on purpose: the surface exists so it can
     // be finished when an upstream is known, rather than 404ing like a typo.
     const handleVideoGeneration = createVideoGenerationHandler(generationDeps);
+    // Passthrough surfaces: routed and accounted for, but never interpreted.
+    // No bundled adapter implements embeddings or audio, and inventing a wire
+    // for them would be a guess; what these need to be useful is the route, the
+    // pipeline, and a compatible upstream behind it.
+    const handleEmbedding = createEmbeddingHandler(generationDeps);
+    const handleAudioTranscription = createAudioTranscriptionHandler(generationDeps);
+    const handleAudioSpeech = createAudioSpeechHandler(generationDeps);
     // Shares the generation dependency bundle: same pipeline, and a count is
     // neither chat-shaped nor generation-shaped, so it needs exactly the same
     // routing, leasing, and accounting surface.
@@ -533,6 +549,9 @@ export function createGatewayApp(deps: GatewayAppDeps) {
         routes.post("/search", handleWebsearch);
         routes.post("/images/generations", handleImageGeneration);
         routes.post("/videos/generations", handleVideoGeneration);
+        routes.post("/embeddings", handleEmbedding);
+        routes.post("/audio/transcriptions", handleAudioTranscription);
+        routes.post("/audio/speech", handleAudioSpeech);
         routes.get("/models", handleModelsList);
         routes.get("/models/info", handleModelsDetail);
         routes.get("/models/*", handleModelsDetail);
@@ -580,10 +599,7 @@ export function createGatewayApp(deps: GatewayAppDeps) {
         createConsoleAccountResetHandler({
           token: deps.drainToken,
           resolvePeerAddress: (request) => peerAddresses.get(request) ?? null,
-          resetConsoleAccount: async () => {
-            const users = await deps.db.delete(consoleUsers);
-            return users.rowCount ?? 0;
-          },
+          resetConsoleAccount: () => resetConsoleAuthState(deps.db),
         }),
       );
     }

package/src/boot/dependencies.ts

@@ -7,6 +7,7 @@ import type { RedisClient } from "../persistence/redis";
 import {
   bundledModelCatalog,
   liveProviderUpstreamHosts,
+  markCatalogSeeded,
   refreshActiveProviderCatalogs,
   registerByokProviders,
   retireUnbundledProviders,
@@ -31,6 +32,9 @@ import { RedisAdmissionCounterStore } from "../security/admission/redis-store";
 import { sweepLeases } from "../security/admission/lease-sweep";
 import { DrizzleApiKeyStore } from "../persistence/stores/api-key-store";
 import { UsageFlushBuffer } from "../persistence/usage-flush";
+import { setPendingUsageSource } from "../security/api-key-auth";
+import { HealthEventFlushBuffer, setHealthEventBuffer } from "../persistence/health-event-flush";
+import { subscribePeerSettingsRevisions } from "../persistence/settings-revision";
 import { deleteExpiredSessions } from "../console/auth/session-service";
 import { InMemoryIpAbuseStore, IpAbuseProtectionService, RedisIpAbuseStore } from "../security/abuse";
 import {
@@ -61,6 +65,7 @@ import {
 } from "../workers/buddy-growth-tasks";
 import { createAccountSecretResolver } from "../providers/operations/provider-credential-service";
 import { quotaCacheSize } from "../console/quota/cache";
+import { modelCatalogCacheSize } from "../providers/operations/model-catalog-cache";
 import { preferencesReaderFor } from "../persistence/tenant-preferences";
 import { sweepExpiredCooldowns } from "../providers/operations/account-health-service";
 import { DrizzleTelemetryStore } from "../persistence/stores/telemetry-store";
@@ -109,6 +114,7 @@ export interface ProductionDeps {
   poolSelector: NetworkPoolSelector;
   telemetryBuffer: TelemetryBatchBuffer;
   usageFlush: UsageFlushBuffer;
+  healthEventFlush: HealthEventFlushBuffer;
   trustedProxyBoundary: TrustedProxyBoundary;
   providerRegistry: ProviderRegistry;
   resolveOAuthRefresher: (providerId: string) => Promise<OAuthTokenRefresher | undefined>;
@@ -130,7 +136,9 @@ const OAUTH_REFRESH_INTER_ITEM_DELAY_MS = 1_500;
  * Client identities are refreshed out of band so provider dispatch never waits
  * on npm/provider version endpoints. Resolver TTLs deduplicate the sources.
  */
-const CLIENT_VERSION_MONITOR_INTERVAL_MS = 15 * 60_000;
+// Matched to the resolver's own 30 min cache TTL: at 15 min every second pass
+// was a pure cache read that could not discover anything new.
+const CLIENT_VERSION_MONITOR_INTERVAL_MS = 30 * 60_000;
 const CLIENT_VERSION_INITIAL_DELAY_MS = 10_000;
 
 export async function buildProductionDeps(): Promise<ProductionDeps> {
@@ -166,6 +174,9 @@ export async function buildProductionDeps(): Promise<ProductionDeps> {
   await measureStartupPhase("bundled-model-seed", () =>
     seedBundledModels(db, bundledCatalog.modelsByProvider),
   );
+  // The boot seed above is unconditional, so record it: the snapshot builder's
+  // first rebuild would otherwise re-seed an identical catalog.
+  markCatalogSeeded();
   const snapshotService = new InMemoryRouteSnapshotService(
     createDatabaseSnapshotBuilder(db, () => refreshActiveProviderCatalogs(db, registry)),
   );
@@ -197,7 +208,21 @@ export async function buildProductionDeps(): Promise<ProductionDeps> {
     }
     return [...totals].map(([accountId, inflight]) => ({ accountId, inflight }));
   };
+  // Peer processes' settings mutations arrive here. Subscribed once for the
+  // process: the revision counter is process-global, and the handler only
+  // moves it forward.
+  subscribePeerSettingsRevisions();
   const usageFlush = new UsageFlushBuffer(db);
+  // Auth reads lifetime usage to seed the admission counter. The persisted
+  // value lags by up to one flush interval, so hand it the in-flight deltas
+  // too — otherwise the seed is systematically under what has actually been
+  // spent, worst exactly when the key is busiest.
+  setPendingUsageSource((apiKeyId) => usageFlush.pendingFor(apiKeyId));
+  // Health audit rows are append-only and read by nobody in dispatch, so they
+  // no longer land inside the request. The status write they accompany stays
+  // synchronous — routing reads it.
+  const healthEventFlush = new HealthEventFlushBuffer(db);
+  setHealthEventBuffer(healthEventFlush);
   const admissionStore = redis
     ? new RedisAdmissionCounterStore(redis)
     : new InMemoryAdmissionCounterStore();
@@ -280,7 +305,11 @@ export async function buildProductionDeps(): Promise<ProductionDeps> {
   });
   scheduledTasks.register({
     name: "console-session-sweep",
-    intervalMs: 60 * 60_000,
+    // Sessions live 48 h, so an hourly sweep deleted nothing 47 times out of
+    // 48 — each pass a full scan of the session table for rows that cannot yet
+    // be expired. Half the session lifetime is the point where a pass can
+    // actually find work, and still leaves a full grace period after it.
+    intervalMs: 12 * 60 * 60_000,
     run: () => deleteExpiredSessions(db),
   });
   scheduledTasks.register({
@@ -309,6 +338,7 @@ export async function buildProductionDeps(): Promise<ProductionDeps> {
     routingRoundRobinEntries: () => routingEngine.roundRobinEntries(),
     ipAbuseKeys: () => (ipStore instanceof InMemoryIpAbuseStore ? ipStore.keyCount() : 0),
     quotaCacheEntries: () => quotaCacheSize(),
+    modelCatalogEntries: () => modelCatalogCacheSize(),
     // Late-bound via bindInFlight once the request state store exists.
     inFlight: () => 0,
   });
@@ -322,7 +352,11 @@ export async function buildProductionDeps(): Promise<ProductionDeps> {
   });
   scheduledTasks.register({
     name: "pool-agent-sweep",
-    intervalMs: 60_000,
+    // `resolveAgent` already self-sweeps every 30 s, so a 1 min timer added a
+    // second pass that almost always found nothing to release. 5 min is well
+    // inside the idle timeout this exists to enforce, and outside the path
+    // that already runs.
+    intervalMs: 5 * 60_000,
     run: () => poolAgentResolver.sweepIdleAgents(),
   });
   const oauthRefreshService = new OAuthRefreshService(db);
@@ -338,7 +372,12 @@ export async function buildProductionDeps(): Promise<ProductionDeps> {
   // credential — no upstream call — so it runs often and cheaply.
   scheduledTasks.register({
     name: "account-enrichment-sweep",
-    intervalMs: 30_000,
+    // Converges via `identity_checked_at`: once every stored credential has
+    // been parsed, the listing query returns nothing — and a 30 s timer kept
+    // running that empty query forever, two million times a year. 10 min is
+    // still instant for the case that matters (a batch import, where the label
+    // and email show up on the next tick) and costs nothing when idle.
+    intervalMs: 10 * 60_000,
     run: () => accountIdentitySweep({ db }),
   });
   scheduledTasks.register({
@@ -434,9 +473,11 @@ export async function buildProductionDeps(): Promise<ProductionDeps> {
   // an account unhealthy — a growth endpoint that 404s is a display miss, not a
   // dispatch failure.
   //
-  // Hourly, not minute-cadenced: each claim is once per account per day, and a
-  // task that ticks every minute would spend its whole budget re-reading the
-  // day marker.
+  // Daily, not hourly: each claim is once per account per day and is
+  // ledger-guarded, so at an hourly cadence 23 of every 24 passes were a full
+  // scan of active accounts plus a ledger read per account that resolved to
+  // nothing. Once a day is the shortest interval where a pass can still find
+  // work, which is the only reason to run at all.
   const buddyTaskDeps = {
     db,
     resolveCredential: quotaResolveCredential,
@@ -447,37 +488,37 @@ export async function buildProductionDeps(): Promise<ProductionDeps> {
   };
   scheduledTasks.register({
     name: "buddy-streak",
-    intervalMs: 60 * 60_000,
+    intervalMs: 24 * 60 * 60_000,
     initialDelayMs: 5 * 60_000,
     run: () => buddyStreakTask(buddyTaskDeps),
   });
   scheduledTasks.register({
     name: "buddy-redeem",
-    intervalMs: 60 * 60_000,
+    intervalMs: 24 * 60 * 60_000,
     initialDelayMs: 8 * 60_000,
     run: () => buddyRedeemTask(buddyTaskDeps),
   });
   scheduledTasks.register({
     name: "buddy-lottery",
-    intervalMs: 60 * 60_000,
+    intervalMs: 24 * 60 * 60_000,
     initialDelayMs: 11 * 60_000,
     run: () => buddyLotteryTask(buddyTaskDeps),
   });
   scheduledTasks.register({
     name: "buddy-travel",
-    intervalMs: 60 * 60_000,
+    intervalMs: 24 * 60 * 60_000,
     initialDelayMs: 14 * 60_000,
     run: () => buddyTravelTask(buddyTaskDeps),
   });
   scheduledTasks.register({
     name: "buddy-adopt",
-    intervalMs: 60 * 60_000,
+    intervalMs: 24 * 60 * 60_000,
     initialDelayMs: 17 * 60_000,
     run: () => buddyAdoptTask(buddyTaskDeps),
   });
   scheduledTasks.register({
     name: "buddy-trial",
-    intervalMs: 6 * 60 * 60_000,
+    intervalMs: 24 * 60 * 60_000,
     initialDelayMs: 20 * 60_000,
     run: () => buddyTrialTask(buddyTaskDeps),
   });
@@ -525,6 +566,7 @@ export async function buildProductionDeps(): Promise<ProductionDeps> {
     poolAgentResolver,
     telemetryBuffer,
     usageFlush,
+    healthEventFlush,
     poolSelector,
     admissionService,
     trustedProxyBoundary: resolveTrustedProxyBoundary(),

package/src/boot/elysia-typebox-bridge.ts

@@ -0,0 +1,37 @@
+/**
+ * Wires Elysia's TypeBox bridge statically, for a source-run process.
+ *
+ * Elysia reaches TypeBox through a lazy `require("typebox/schema")` that
+ * resolves to a partial namespace outside a bundler. The bridge supplies all
+ * five namespaces explicitly so the lookup never has to happen.
+ *
+ * This is necessary but **not sufficient** for `NODE_ENV=production`: it does
+ * not stop the eager validator branch from reading
+ * `this.tb.buildResult.external`, which is still absent on a source run. That
+ * half is owned by `resolveElysiaPrecompile()`, which turns precompilation off
+ * for a source run. Keep both — wiring the bridge without the precompile guard
+ * still crashes, and the guard without the bridge leaves the lazy require in
+ * place for anything else that needs it.
+ *
+ * Keep this import first in `main.ts` so it runs before any module builds a
+ * route.
+ */
+import { setupTypebox } from "elysia";
+import * as typeboxType from "typebox";
+import * as typeboxCompile from "typebox/compile";
+import * as typeboxSchema from "typebox/schema";
+import * as typeboxSystem from "typebox/system";
+import * as typeboxValue from "typebox/value";
+
+setupTypebox({
+  typebox: {
+    // The type side (`type` + `system`) and the value side (`value` + `schema`
+    // + `compile`) must both be complete; Elysia rejects a partial set because
+    // a half-wired bridge fails later with a less obvious error.
+    type: typeboxType,
+    system: typeboxSystem,
+    value: typeboxValue,
+    schema: typeboxSchema,
+    compile: typeboxCompile,
+  },
+});

package/src/boot/lifecycle.ts

@@ -220,12 +220,14 @@ export async function bootstrap(): Promise<CartethyiaBoot> {
         flushTelemetry: async () => {
           await deps.telemetryBuffer.flush();
           await deps.usageFlush.flush();
+          await deps.healthEventFlush.flush();
         },
         closePools: async () => {
           await boot.server?.stop();
           await deps.scheduledTasks.stop();
           await deps.telemetryBuffer.stop({ flush: true });
           await deps.usageFlush.stop({ flush: true });
+          await deps.healthEventFlush.stop();
           await Promise.allSettled([
             closeDb(),
             closeRedis(),