cartethyia 2.5.4 → 2.5.6

package/src/console/providers/oauth/routes.ts

@@ -102,8 +102,7 @@ export class DrizzleOAuthAccountStore implements OAuthAccountStore {
               lastErrorAt: null,
               lastRecoveredAt: null,
               // A fresh login supplies a refresh token, so the account returns
-              // to normal OAuth refresh handling — a static-token flag set on
-              // the previous (refresh-less) credential no longer applies.
+              // to normal OAuth refresh handling and is not a static token.
               staticToken: false,
               // Only what this login reported: a flow that learned no profile or
               // region leaves the stored configuration alone rather than blanking it.
@@ -164,16 +163,13 @@ export class DrizzleOAuthAccountStore implements OAuthAccountStore {
  * and device-code start/poll — driven by whichever `OAuthLoginClient` is
  * registered for a given provider id.
  *
- * > **Koreksi.** An earlier comment here read "Cartethyia hosts the callback
- * > itself (it's a server process, not a local CLI), so there is no
- * > loopback-listener/port-selection problem." That was wrong, and it is the
- * > premise that produced the bug. The redirect URIs these clients advertise
- * > are loopback (`localhost:1455`, `127.0.0.1:54549`, …), which name the
- * > machine the *operator's browser* is on — not this process. Advertising one
- * > without binding the port leaves the code in the browser's address bar, so
- * > every browser login needed the redirect pasted back by hand. The gateway
- * > is a server process, but it is not *the* server the redirect arrives at;
- * > `callback-listener.ts` is what makes those the same endpoint.
+ * The redirect URIs these clients advertise are loopback (`localhost:1455`,
+ * `127.0.0.1:54549`, …), which name the machine the *operator's browser* is on
+ * — not this process. Advertising one without binding the port leaves the code
+ * in the browser's address bar, so every browser login needs the redirect
+ * pasted back by hand. The gateway is a server process, but it is not *the*
+ * server the redirect arrives at; `callback-listener.ts` is what makes those
+ * the same endpoint.
  */
 export interface PersistedOAuthAccount {
   readonly accountId: string;

package/src/console/quota/account-quota-tenant.ts

@@ -354,12 +354,12 @@ export function registerAccountQuotaTenantRoutes(
       const accounts = rows.map((row) => {
         const entry =
           row.tenantId === null ? globalCache.get(row.id) : ownedCache.get(row.id);
-        // No background refresh is enqueued here. Opening the page used to
-        // enqueue one for every account whose cached value had aged out, so a
-        // single page open hit every provider's quota endpoint at once — and
-        // because the page also polled, the operator saw that fan-out as "the
-        // page refreshes everything when I open it". The periodic sweep owns
-        // freshness; this route renders what is cached.
+        // No background refresh is enqueued here: enqueuing one for every
+        // account whose cached value had aged out means a single page open hits
+        // every provider's quota endpoint at once — and because the page also
+        // polls, the operator sees that fan-out as "the page refreshes
+        // everything when I open it". The periodic sweep owns freshness; this
+        // route renders what is cached.
         //
         // `refreshing` still counts accounts with no cached value, so the client
         // can show them as pending while the sweep fills them.

package/src/console/quota/quota-view.ts

@@ -154,7 +154,7 @@ export function toQuotaAccountHealth(row: {
     cooldownUntil: row.cooldownUntil ? row.cooldownUntil.toISOString() : null,
     // Only deadlines still in force are returned: the sweep prunes the column
     // on a timer, so a raw read can carry an entry that has already elapsed and
-    // would render as a cooldown that no longer applies.
+    // would render as a cooldown that is not in force.
     modelCooldowns: liveModelCooldowns(row.modelCooldowns),
   };
 }

package/src/console/remote-support/contracts.ts

@@ -0,0 +1,61 @@
+/**
+ * Remote-support tunnel contracts.
+ *
+ * A tunnel publishes the loopback gateway to a public or tailnet address. This
+ * module owns the vocabulary (which tool, which states, what a status reports)
+ * and is deliberately free of Elysia and Node imports so the dashboard can
+ * import the same shape without dragging a server runtime into the browser
+ * bundle.
+ */
+
+/** The two supported publishers. Both must already be installed. */
+export const REMOTE_SUPPORT_TOOLS = ["cloudflared", "tailscale"] as const;
+
+export type RemoteSupportTool = (typeof REMOTE_SUPPORT_TOOLS)[number];
+
+/**
+ * Why a tunnel cannot start. `not_installed` is the common one: this product
+ * never installs third-party binaries, so a missing `cloudflared` or
+ * `tailscale` is reported for the operator to install, never downloaded.
+ */
+export type RemoteSupportBlocker =
+  | "not_installed"
+  | "unsupported_platform"
+  | "launch_failed";
+
+export interface RemoteSupportStatus {
+  /** Which publisher is up, or `null` when neither is. */
+  readonly active: RemoteSupportTool | null;
+  /** The published base URL, present once the publisher reported one. */
+  readonly url: string | null;
+  /** Set when a start was refused, with the operator-facing reason. */
+  readonly blocker: RemoteSupportBlocker | null;
+  /** Operator-facing detail for `blocker`, e.g. the install hint. */
+  readonly message: string | null;
+  /** Local port the tunnel forwards to. */
+  readonly port: number;
+  /** Which publishers are installed on this host. Cached so the UI doesn't poll. */
+  readonly installed: Readonly<Record<RemoteSupportTool, boolean>>;
+}
+
+export interface RemoteSupportStartRequest {
+  readonly tool: RemoteSupportTool;
+  /** Defaults to the gateway's own port when omitted. */
+  readonly port?: number;
+}
+
+export interface RemoteSupportStartResponse extends RemoteSupportStatus {
+  readonly started: boolean;
+}
+
+/** Human-readable install guidance, keyed by tool. Never an installer. */
+export const REMOTE_SUPPORT_INSTALL_HINT: Readonly<Record<RemoteSupportTool, string>> = {
+  cloudflared:
+    "cloudflared is not installed. Install it yourself (winget install Cloudflare.cloudflared) and try again.",
+  tailscale:
+    "tailscale is not installed. Install it yourself (winget install Tailscale.Tailscale), run `tailscale up` once, then try again.",
+};
+
+export function isRemoteSupportTool(value: unknown): value is RemoteSupportTool {
+  return typeof value === "string" && (REMOTE_SUPPORT_TOOLS as readonly string[]).includes(value);
+}

package/src/console/remote-support/routes.ts

@@ -0,0 +1,65 @@
+/**
+ * Remote-support HTTP surface.
+ *
+ * Three routes over one external launcher script: read the current tunnel,
+ * start one, stop one. Every mutating route needs `dashboard:write` because it
+ * runs a process on the host running the gateway.
+ *
+ * The start response never contains a secret and never performs an install; it
+ * reports `not_installed` with guidance when the publisher is missing.
+ */
+import { Elysia, t } from "elysia";
+import type { ConsoleAccessResolver } from "../auth/access";
+import { consoleErrorHandler, requireTenantScope } from "../shared/errors";
+import { REMOTE_SUPPORT_TOOLS } from "./contracts";
+import type { RemoteSupportService } from "./service";
+
+export interface RemoteSupportRoutesConfig {
+  readonly accessResolver: ConsoleAccessResolver;
+  readonly service: RemoteSupportService;
+}
+
+const toolSchema = t.Union([
+  t.Literal(REMOTE_SUPPORT_TOOLS[0]),
+  t.Literal(REMOTE_SUPPORT_TOOLS[1]),
+]);
+
+const startBody = t.Object({
+  tool: toolSchema,
+  port: t.Optional(t.Number()),
+});
+
+const stopBody = t.Object({
+  tool: t.Optional(toolSchema),
+});
+
+/**
+ * The return type is inferred rather than annotated as `Elysia`: `.error()`
+ * widens the instance type with its handler's response envelope, so the
+ * annotated base type no longer matches the chained result.
+ */
+export function createRemoteSupportRoutes(config: RemoteSupportRoutesConfig) {
+  return new Elysia()
+    .error(consoleErrorHandler("Remote support failed"))
+    .get("/remote-support/status", async ({ request }) => {
+      requireTenantScope(config.accessResolver(request), "dashboard:read");
+      return await config.service.status();
+    })
+    .post(
+      "/remote-support/start",
+      { body: startBody },
+      async ({ request, body }) => {
+        requireTenantScope(config.accessResolver(request), "dashboard:write");
+        const status = await config.service.start(body.tool, body.port);
+        return { started: status.active !== null, ...status };
+      },
+    )
+    .post(
+      "/remote-support/stop",
+      { body: stopBody },
+      async ({ request, body }) => {
+        requireTenantScope(config.accessResolver(request), "dashboard:write");
+        return await config.service.stop(body.tool);
+      },
+    );
+}

package/src/console/remote-support/service.ts

@@ -0,0 +1,207 @@
+/**
+ * Remote-support tunnel service.
+ *
+ * The tunnel is launched by an external script rather than by spawning
+ * `cloudflared`/`tailscale` directly, for one reason that matters: the script
+ * hands the publisher to the OS session, so the tunnel is not a child of this
+ * gateway. A gateway restart, a hot reload, or a Ctrl-C in the owning terminal
+ * therefore cannot kill an operator's live remote-support session.
+ *
+ * This service never installs anything. A missing binary is reported as a
+ * blocker with install guidance; downloading a third-party agent on the
+ * operator's behalf is out of scope.
+ */
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { PACKAGE_ROOT } from "../../config/package-paths";
+import {
+  REMOTE_SUPPORT_INSTALL_HINT,
+  type RemoteSupportBlocker,
+  type RemoteSupportStatus,
+  type RemoteSupportTool,
+} from "./contracts";
+
+/** How long the launcher may take to report a URL before we stop waiting. */
+const LAUNCH_TIMEOUT_MS = 40_000;
+
+/** Cached install detection so we don't spawn `where` on every status poll. */
+const installedCache = new Map<RemoteSupportTool, boolean>();
+
+export interface RemoteSupportServiceConfig {
+  /** Defaults to the gateway's configured port. */
+  readonly port: number;
+  /** Overridable for tests; defaults to the package root. */
+  readonly scriptDir?: string;
+}
+
+interface CommandResult {
+  readonly status: number;
+  readonly stdout: string;
+}
+
+function scriptPath(config: RemoteSupportServiceConfig, name: string): string {
+  const dir = config.scriptDir ?? join(PACKAGE_ROOT, "scripts");
+  return join(dir, name);
+}
+
+function runScript(
+  config: RemoteSupportServiceConfig,
+  args: readonly string[],
+): Promise<CommandResult> {
+  const { promise, resolve, reject } = Promise.withResolvers<CommandResult>();
+  const isWindows = process.platform === "win32";
+  // Windows cannot spawn a `.cmd` directly — `spawn` rejects it with EINVAL
+  // because a batch file is not an executable image. It has to be handed to
+  // `cmd.exe /c`, which is also what lets the batch call `exit /b 3` and have
+  // that code reach us as the child's status.
+  const command = isWindows ? "cmd.exe" : "powershell";
+  const fileName = isWindows ? "remote-support.cmd" : "remote-support.ps1";
+  const file = scriptPath(config, fileName);
+  const spawnArgs = isWindows
+    ? ["/d", "/s", "/c", file, ...args]
+    : ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", file, ...args];
+  const child = spawn(command, spawnArgs, {
+    stdio: ["ignore", "pipe", "pipe"],
+    windowsHide: true,
+  });
+  let stdout = "";
+  let stderr = "";
+  child.stdout.setEncoding("utf8");
+  child.stderr.setEncoding("utf8");
+  child.stdout.on("data", (chunk: string) => {
+    stdout += chunk;
+  });
+  child.stderr.on("data", (chunk: string) => {
+    stderr += chunk;
+  });
+  const timer = setTimeout(() => child.kill(), LAUNCH_TIMEOUT_MS);
+  child.on("error", reject);
+  child.on("close", (status) => {
+    clearTimeout(timer);
+    resolve({ status: status ?? 1, stdout: `${stdout}${stderr}`.trim() });
+  });
+  return promise;
+}
+
+/**
+ * `where`/`which` lookup, mirroring what the script does itself so the route
+ * can answer `not_installed` with a clear message instead of a generic failure.
+ */
+function toolAvailable(tool: RemoteSupportTool): Promise<boolean> {
+  const cached = installedCache.get(tool);
+  if (cached !== undefined) return Promise.resolve(cached);
+  const { promise, resolve } = Promise.withResolvers<boolean>();
+  const command = process.platform === "win32" ? "where" : "which";
+  const child = spawn(command, [tool], { stdio: "ignore", windowsHide: true });
+  child.on("error", () => {
+    installedCache.set(tool, false);
+    resolve(false);
+  });
+  child.on("close", (status) => {
+    const ok = status === 0;
+    installedCache.set(tool, ok);
+    resolve(ok);
+  });
+  return promise;
+}
+
+export interface RemoteSupportService {
+  status(): Promise<RemoteSupportStatus>;
+  start(tool: RemoteSupportTool, port?: number): Promise<RemoteSupportStatus>;
+  stop(tool?: RemoteSupportTool): Promise<RemoteSupportStatus>;
+}
+
+export function createRemoteSupportService(config: RemoteSupportServiceConfig): RemoteSupportService {
+  const port = config.port;
+
+  /**
+   * Install state for both publishers, cached per process.
+   *
+   * Every status carries it so the card can show "not installed" without the
+   * browser probing on its own — but the probe is `where`/`which`, which is a
+   * process spawn, so it is memoised here rather than run on each poll.
+   */
+  async function detectInstalled(): Promise<Readonly<Record<RemoteSupportTool, boolean>>> {
+    return {
+      cloudflared: await toolAvailable("cloudflared"),
+      tailscale: await toolAvailable("tailscale"),
+    } as const;
+  }
+
+  async function readStatus(blocker: RemoteSupportBlocker | null = null, message: string | null = null): Promise<RemoteSupportStatus> {
+    const result = await runScript(config, ["status"]);
+    const text = result.stdout;
+    const active: RemoteSupportTool | null = text.includes("cloudflared running")
+      ? "cloudflared"
+      : text.includes("tailscale running")
+        ? "tailscale"
+        : null;
+    let url: string | null = null;
+    if (active !== null) {
+      const urlResult = await runScript(config, ["url"]);
+      const candidate = urlResult.stdout.trim().split(/\s+/).find((line) => line.startsWith("https://"));
+      url = candidate ?? null;
+    }
+    const installed = await detectInstalled();
+    return { active, url, blocker, message, port, installed };
+  }
+
+  return {
+    async status() {
+      return await readStatus();
+    },
+
+    async start(tool, requestedPort) {
+      if (process.platform !== "win32") {
+        return {
+          active: null,
+          url: null,
+          blocker: "unsupported_platform",
+          message: "Remote support is currently scripted for Windows hosts only.",
+          port,
+          installed: { cloudflared: false, tailscale: false },
+        };
+      }
+      const launcher = scriptPath(config, "remote-support.cmd");
+      if (!existsSync(launcher)) {
+        return {
+          active: null,
+          url: null,
+          blocker: "launch_failed",
+          message: `Launcher not found: ${launcher}`,
+          port,
+          installed: await detectInstalled(),
+        };
+      }
+      if (!(await toolAvailable(tool))) {
+        return {
+          active: null,
+          url: null,
+          blocker: "not_installed",
+          message: REMOTE_SUPPORT_INSTALL_HINT[tool],
+          port,
+          installed: await detectInstalled(),
+        };
+      }
+      const target = requestedPort ?? port;
+      const result = await runScript(config, ["start", tool, String(target)]);
+      if (result.status !== 0 && !result.stdout.includes("started")) {
+        return {
+          active: null,
+          url: null,
+          blocker: "launch_failed",
+          message: result.stdout || `Failed to start ${tool}.`,
+          port,
+          installed: await detectInstalled(),
+        };
+      }
+      return await readStatus();
+    },
+
+    async stop(tool) {
+      await runScript(config, tool === undefined ? ["stop"] : ["stop", tool]);
+      return await readStatus();
+    },
+  };
+}

package/src/console/response-compression.ts

@@ -18,9 +18,6 @@
  * only". A path test can, and it lives inside `gzipResponse` — the one place
  * that runs on every request.
  *
- * Consequence: `/v1/models` was previously compressed as a side effect of
- * that `hoc` propagation. It deliberately is not now.
- *
  * ## Why this is scoped to the console, not the proxy
  *
  * `/v1/*` is deliberately excluded, for two independent reasons:

package/src/console/routing/pools/probe-result.ts

@@ -51,8 +51,9 @@ export function classifyPoolConnectError(
   error: unknown,
   latencyMs: number,
 ): HealthCheckResult | undefined {
-  // The agent throws a typed refusal carrying the status, so this no longer
-  // re-parses the message text (which a wording change would silently break).
+  // The agent throws a typed refusal carrying the status, so this reads the
+  // status rather than re-parsing message text (which a wording change would
+  // silently break).
   if (!(error instanceof ProxyConnectRefusalError)) return undefined;
   if (error.statusCode !== 402 && error.statusCode !== 407) return undefined;
   return classifyPoolProbeResponse(poolId, { ok: false, status: error.statusCode }, latencyMs);