@tonyclaw/agent-inspector 4.0.1 → 4.0.3

package/src/proxy/identityProxy.ts

@@ -1,1842 +0,0 @@
-import http from "node:http";
-import { Buffer } from "node:buffer";
-import { createHash, timingSafeEqual } from "node:crypto";
-import { isIP } from "node:net";
-import {
-  BROWSER_RUNTIME_JSON_PLACEHOLDER,
-  BROWSER_RUNTIME_SCHEMA_VERSION,
-  type BrowserRuntimeDeployment,
-} from "../lib/browserRuntimeContract";
-import {
-  AGENT_INSPECTOR_BACKEND_HEADER,
-  type BackendImplementation,
-} from "../lib/backendImplementation";
-import {
-  AGENT_INSPECTOR_BASE_PATH_META_NAME,
-  AGENT_INSPECTOR_PUBLIC_BASE_PATH_HEADER,
-  AGENT_INSPECTOR_PUBLIC_ORIGIN_HEADER,
-  AGENT_INSPECTOR_PUBLIC_PORT_HEADER,
-  getConfiguredBasePath,
-  normalizePublicBasePath,
-  stripBasePath,
-  stripBasePathFromRequestPath,
-  withBasePath,
-} from "../lib/basePath";
-import {
-  MANAGED_INSTANCE_CONTROL_PATH,
-  MANAGED_INSTANCE_SHUTDOWN_PATH,
-  MANAGED_INSTANCE_TOKEN_HEADER,
-} from "../lib/managedInstance";
-import { lookupClientByPort } from "./socketTracker";
-import { loadUiAsset } from "./uiAssetServer";
-
-const IDENTITY_HEADERS = {
-  pid: "x-agent-inspector-client-pid",
-  port: "x-agent-inspector-client-port",
-  cwd: "x-agent-inspector-client-cwd",
-  projectFolder: "x-agent-inspector-client-project-folder",
-} as const;
-
-const IDENTITY_HEADER_PREFIX = "x-agent-inspector-";
-const PROXY_TOKEN_HEADER = "x-agent-inspector-proxy-token";
-const CSRF_HEADER = "x-agent-inspector-csrf";
-const FORWARDED_AGENT_HEADER_ALLOWLIST = new Set<string>([CSRF_HEADER]);
-const DEFAULT_MAX_REQUEST_BYTES = 64 * 1024 * 1024;
-const DEFAULT_REQUEST_TIMEOUT_MS = 120_000;
-const ALIAS_CONTROL_MAX_REQUEST_BYTES = 8 * 1024;
-const INSTANCE_API_MAX_REQUEST_BYTES = 64 * 1024;
-const LOCAL_CONTROL_MAX_RESPONSE_BYTES = 1024 * 1024;
-
-export const IDENTITY_PROXY_CONTROL_NAMESPACE = "/.agent-inspector";
-export const IDENTITY_PROXY_ALIAS_CONTROL_PATH = `${IDENTITY_PROXY_CONTROL_NAMESPACE}/base-path-aliases`;
-
-export type BasePathAliasResolution = {
-  effectiveBasePath: string;
-  isAlias: boolean;
-  upstreamPath: string;
-};
-
-export type BasePathAliasMutationResult =
-  | { ok: true; basePath: string }
-  | {
-      ok: false;
-      code: "canonical" | "duplicate" | "invalid" | "not-found" | "overlap" | "reserved";
-      error: string;
-    };
-
-export type BasePathAliasRegistry = {
-  canonicalBasePath: string;
-  add: (basePath: string) => BasePathAliasMutationResult;
-  list: () => readonly string[];
-  remove: (basePath: string) => BasePathAliasMutationResult;
-  resolve: (rawPath: string) => BasePathAliasResolution;
-};
-
-function normalizedAliasCandidate(
-  value: string,
-): { ok: true; basePath: string } | { ok: false; code: "invalid" | "reserved"; error: string } {
-  const normalized = normalizePublicBasePath(value);
-  if (normalized === null) {
-    return {
-      ok: false,
-      code: "invalid",
-      error: "Base Path aliases may contain only URL-safe path segments.",
-    };
-  }
-  if (normalized.length === 0) {
-    return {
-      ok: false,
-      code: "invalid",
-      error: "Base Path aliases must be non-root paths such as /inspector.",
-    };
-  }
-  if (
-    normalized === IDENTITY_PROXY_CONTROL_NAMESPACE ||
-    normalized.startsWith(`${IDENTITY_PROXY_CONTROL_NAMESPACE}/`)
-  ) {
-    return {
-      ok: false,
-      code: "reserved",
-      error: `${normalized} collides with the reserved Agent Inspector control path.`,
-    };
-  }
-  const publicNamespace = ["/api", "/assets", "/proxy", "/session", "/livez", "/readyz"].find(
-    (namespace) => normalized === namespace || normalized.startsWith(`${namespace}/`),
-  );
-  if (publicNamespace !== undefined) {
-    return {
-      ok: false,
-      code: "reserved",
-      error: `${normalized} collides with the reserved ${publicNamespace} public namespace.`,
-    };
-  }
-  return { ok: true, basePath: normalized };
-}
-
-function pathMatchesBasePath(pathname: string, basePath: string): boolean {
-  return pathname === basePath || pathname.startsWith(`${basePath}/`);
-}
-
-function basePathsOverlap(left: string, right: string): boolean {
-  return pathMatchesBasePath(left, right) || pathMatchesBasePath(right, left);
-}
-
-/**
- * Create an in-memory registry owned by one identity ingress. Runtime aliases
- * intentionally disappear when that ingress exits.
- */
-export function createBasePathAliasRegistry(
-  canonicalBasePath: string,
-  initialAliases: readonly string[] = [],
-): BasePathAliasRegistry {
-  const canonical = normalizePublicBasePath(canonicalBasePath) ?? "";
-  const aliases: string[] = [];
-
-  const add = (value: string): BasePathAliasMutationResult => {
-    const candidate = normalizedAliasCandidate(value);
-    if (!candidate.ok) return candidate;
-    if (candidate.basePath === canonical) {
-      return {
-        ok: false,
-        code: "canonical",
-        error: `${candidate.basePath} is already the canonical Base Path.`,
-      };
-    }
-    if (canonical.length > 0 && basePathsOverlap(candidate.basePath, canonical)) {
-      return {
-        ok: false,
-        code: "overlap",
-        error: `${candidate.basePath} overlaps the canonical Base Path ${canonical}.`,
-      };
-    }
-    if (aliases.includes(candidate.basePath)) {
-      return {
-        ok: false,
-        code: "duplicate",
-        error: `${candidate.basePath} is already an active runtime alias.`,
-      };
-    }
-    const overlappingAlias = aliases.find((alias) => basePathsOverlap(candidate.basePath, alias));
-    if (overlappingAlias !== undefined) {
-      return {
-        ok: false,
-        code: "overlap",
-        error: `${candidate.basePath} overlaps the active runtime alias ${overlappingAlias}.`,
-      };
-    }
-    aliases.push(candidate.basePath);
-    aliases.sort((left, right) => right.length - left.length || left.localeCompare(right));
-    return { ok: true, basePath: candidate.basePath };
-  };
-
-  const remove = (value: string): BasePathAliasMutationResult => {
-    const candidate = normalizedAliasCandidate(value);
-    if (!candidate.ok) return candidate;
-    if (candidate.basePath === canonical) {
-      return {
-        ok: false,
-        code: "canonical",
-        error: `${candidate.basePath} is the canonical Base Path and cannot be removed.`,
-      };
-    }
-    const index = aliases.indexOf(candidate.basePath);
-    if (index === -1) {
-      return {
-        ok: false,
-        code: "not-found",
-        error: `${candidate.basePath} is not an active runtime alias.`,
-      };
-    }
-    aliases.splice(index, 1);
-    return { ok: true, basePath: candidate.basePath };
-  };
-
-  const resolve = (rawPath: string): BasePathAliasResolution => {
-    const requestUrl = new URL(rawPath, "http://localhost");
-    const alias = aliases.find((candidate) => pathMatchesBasePath(requestUrl.pathname, candidate));
-    const effectiveBasePath = alias ?? canonical;
-    return {
-      effectiveBasePath,
-      isAlias: alias !== undefined,
-      upstreamPath: stripBasePathFromRequestPath(rawPath, effectiveBasePath),
-    };
-  };
-
-  const registry: BasePathAliasRegistry = {
-    canonicalBasePath: canonical,
-    add,
-    list: () => [...aliases],
-    remove,
-    resolve,
-  };
-  for (const alias of initialAliases) add(alias);
-  return registry;
-}
-
-export function resolveBasePathAliasRequest(
-  registry: BasePathAliasRegistry,
-  rawPath: string,
-): BasePathAliasResolution {
-  return registry.resolve(rawPath);
-}
-
-type IdentityProxyRuntimeState = {
-  acceptingRequests: boolean;
-  activeRequests: number;
-  drainWaiters: Set<() => void>;
-};
-
-const identityProxyRuntimeStates = new WeakMap<http.Server, IdentityProxyRuntimeState>();
-
-const REQUEST_HOP_BY_HOP = new Set([
-  "connection",
-  "keep-alive",
-  "proxy-authenticate",
-  "proxy-authorization",
-  "te",
-  "trailers",
-  "transfer-encoding",
-  "upgrade",
-  "content-length",
-]);
-
-const RESPONSE_HOP_BY_HOP = new Set([
-  "connection",
-  "keep-alive",
-  "proxy-authenticate",
-  "proxy-authorization",
-  "te",
-  "trailers",
-  "transfer-encoding",
-  "upgrade",
-]);
-
-const BASE_SECURITY_HEADERS = {
-  "permissions-policy": "camera=(), microphone=(), geolocation=()",
-  "referrer-policy": "no-referrer",
-  "x-content-type-options": "nosniff",
-  "x-frame-options": "DENY",
-} as const;
-
-const DOCUMENT_CONTENT_SECURITY_POLICY = [
-  "default-src 'self'",
-  "base-uri 'self'",
-  "connect-src 'self'",
-  "font-src 'self' data:",
-  "frame-ancestors 'none'",
-  "img-src 'self' data: blob:",
-  "object-src 'none'",
-  "script-src 'self' 'unsafe-inline'",
-  "style-src 'self' 'unsafe-inline'",
-  "worker-src 'self' blob:",
-].join("; ");
-
-function htmlAttributeEscape(value: string): string {
-  return value
-    .replace(/&/gu, "&amp;")
-    .replace(/"/gu, "&quot;")
-    .replace(/</gu, "&lt;")
-    .replace(/>/gu, "&gt;");
-}
-
-function rewriteRootRelativePublicPath(
-  value: string,
-  effectiveBasePath: string,
-  sourceBasePath: string,
-): string {
-  if (!value.startsWith("/") || value.startsWith("//")) return value;
-  const normalizedEffective = normalizePublicBasePath(effectiveBasePath);
-  const normalizedSource = normalizePublicBasePath(sourceBasePath);
-  if (normalizedEffective === null || normalizedSource === null) return value;
-  const suffixIndex = value.search(/[?#]/u);
-  const pathname = suffixIndex === -1 ? value : value.slice(0, suffixIndex);
-  const suffix = suffixIndex === -1 ? "" : value.slice(suffixIndex);
-  if (normalizedEffective.length > 0 && pathMatchesBasePath(pathname, normalizedEffective)) {
-    return value;
-  }
-  const rootRelativePath =
-    normalizedSource.length > 0 && pathMatchesBasePath(pathname, normalizedSource)
-      ? pathname.slice(normalizedSource.length) || "/"
-      : pathname;
-  const rewritten = withBasePath(rootRelativePath, normalizedEffective);
-  const trailingSlash = pathname.endsWith("/") && !rewritten.endsWith("/") ? "/" : "";
-  return `${rewritten}${trailingSlash}${suffix}`;
-}
-
-function rewriteQuotedAssetPaths(
-  source: string,
-  effectiveBasePath: string,
-  sourceBasePath: string,
-  escape: (value: string, quote: string) => string,
-): string {
-  return source.replace(
-    /(["'])(\/(?:[^"'/]+\/)*assets\/)/gu,
-    (_match: string, quote: string, assetPrefix: string) =>
-      `${quote}${escape(
-        rewriteRootRelativePublicPath(assetPrefix, effectiveBasePath, sourceBasePath),
-        quote,
-      )}`,
-  );
-}
-
-export function rewriteHtmlForBasePath(
-  html: string,
-  basePath: string,
-  sourceBasePath = "",
-): string {
-  const normalized = normalizePublicBasePath(basePath);
-  const normalizedSource = normalizePublicBasePath(sourceBasePath);
-  if (normalized === null || normalizedSource === null) return html;
-  const escaped = htmlAttributeEscape(normalized);
-  const meta = `<meta name="${AGENT_INSPECTOR_BASE_PATH_META_NAME}" content="${escaped}">`;
-  const metaPattern = new RegExp(
-    `<meta\\b[^>]*\\bname\\s*=\\s*("|')${AGENT_INSPECTOR_BASE_PATH_META_NAME}\\1[^>]*>`,
-    "giu",
-  );
-  let replacedMeta = false;
-  const withReplacedMeta = html.replace(metaPattern, () => {
-    if (replacedMeta) return "";
-    replacedMeta = true;
-    return meta;
-  });
-  const withMeta = replacedMeta
-    ? withReplacedMeta
-    : withReplacedMeta.replace(/<head(\s[^>]*)?>/iu, (match) => `${match}${meta}`);
-  const withRewrittenAttributes = withMeta.replace(
-    /\b(href|src|action)=(["'])(\/(?!\/)[^"']*)\2/giu,
-    (_match: string, attribute: string, quote: string, path: string) =>
-      `${attribute}=${quote}${htmlAttributeEscape(
-        rewriteRootRelativePublicPath(path, normalized, normalizedSource),
-      )}${quote}`,
-  );
-  return rewriteQuotedAssetPaths(withRewrittenAttributes, normalized, normalizedSource, (value) =>
-    htmlAttributeEscape(value),
-  );
-}
-
-function javaScriptStringEscape(value: string, quote: string): string {
-  const escaped = value
-    .replace(/\\/gu, "\\\\")
-    .replace(/\r/gu, "\\r")
-    .replace(/\n/gu, "\\n")
-    .replace(/\u2028/gu, "\\u2028")
-    .replace(/\u2029/gu, "\\u2029")
-    .replace(/&/gu, "\\u0026")
-    .replace(/</gu, "\\u003c")
-    .replace(/>/gu, "\\u003e");
-  return quote === "'" ? escaped.replace(/'/gu, "\\'") : escaped.replace(/"/gu, '\\"');
-}
-
-export function rewriteJavaScriptForBasePath(
-  source: string,
-  basePath: string,
-  sourceBasePath = "",
-): string {
-  const normalized = normalizePublicBasePath(basePath);
-  const normalizedSource = normalizePublicBasePath(sourceBasePath);
-  if (normalized === null || normalizedSource === null) return source;
-  const escaped = javaScriptStringEscape(normalized, '"');
-  const withRouterBasePath = source.replace(
-    /\bbasepath:\s*(["'])[^"']*\1/gu,
-    `basepath:"${escaped}"`,
-  );
-  const withDynamicPaths = withRouterBasePath.replace(
-    /return(["'])(\/(?!\/)[^"']*)\1\+([A-Za-z_$][\w$]*)/gu,
-    (_match: string, quote: string, path: string, variable: string) => {
-      const rewritten = rewriteRootRelativePublicPath(path, normalized, normalizedSource);
-      return `return${quote}${javaScriptStringEscape(rewritten, quote)}${quote}+${variable}`;
-    },
-  );
-  return rewriteQuotedAssetPaths(
-    withDynamicPaths,
-    normalized,
-    normalizedSource,
-    javaScriptStringEscape,
-  );
-}
-
-function publicOriginForRequest(req: http.IncomingMessage, options: IdentityProxyOptions): string {
-  if (options.publicOrigin !== undefined) {
-    try {
-      return new URL(options.publicOrigin).origin;
-    } catch {
-      // Invalid explicit values are rejected by the CLI; retain a safe local fallback for embedders.
-    }
-  }
-  return `http://${req.headers.host ?? "localhost"}`;
-}
-
-function browserRuntimeForRequest(
-  req: http.IncomingMessage,
-  options: IdentityProxyOptions,
-  basePath: string,
-): BrowserRuntimeDeployment {
-  const origin = publicOriginForRequest(req, options);
-  const normalized = normalizePublicBasePath(basePath) ?? "";
-  const baseUrl = normalized.length === 0 ? origin : `${origin}${normalized}`;
-  return {
-    schemaVersion: BROWSER_RUNTIME_SCHEMA_VERSION,
-    deploymentMode: "composed",
-    ui: { basePath: normalized.length === 0 ? "/" : normalized },
-    control: { baseUrl },
-    agent: { baseUrl },
-    capabilities: {
-      rest: true,
-      sse: true,
-      proxy: true,
-      mcp: true,
-    },
-  };
-}
-
-function safeInlineJson(value: unknown): string {
-  return JSON.stringify(value)
-    .replace(/&/gu, "\\u0026")
-    .replace(/</gu, "\\u003c")
-    .replace(/>/gu, "\\u003e")
-    .replace(/\u2028/gu, "\\u2028")
-    .replace(/\u2029/gu, "\\u2029");
-}
-
-function injectBrowserRuntime(html: string, runtime: BrowserRuntimeDeployment): string {
-  const runtimeJson = safeInlineJson(runtime);
-  if (html.includes(BROWSER_RUNTIME_JSON_PLACEHOLDER)) {
-    return html.replaceAll(BROWSER_RUNTIME_JSON_PLACEHOLDER, runtimeJson);
-  }
-  const bootstrap = `<script>window.__AGENT_INSPECTOR_RUNTIME__=${runtimeJson};</script>`;
-  return html.replace(/<head(\s[^>]*)?>/iu, (head) => `${head}${bootstrap}`);
-}
-
-async function tryServeUiAsset(
-  req: http.IncomingMessage,
-  res: http.ServerResponse,
-  options: IdentityProxyOptions,
-  pathname: string,
-  basePath: string,
-  sourceBasePath: string,
-): Promise<boolean> {
-  const method = (req.method ?? "GET").toUpperCase();
-  if ((method !== "GET" && method !== "HEAD") || options.uiDirectory === undefined) return false;
-  const asset = await loadUiAsset(options.uiDirectory, pathname);
-  if (asset === null) return false;
-  let body = asset.body;
-  if (asset.document) {
-    const rewritten = rewriteHtmlForBasePath(body.toString("utf8"), basePath, sourceBasePath);
-    body = Buffer.from(
-      injectBrowserRuntime(rewritten, browserRuntimeForRequest(req, options, basePath)),
-      "utf8",
-    );
-  } else if (basePath.length > 0 && asset.contentType.includes("javascript")) {
-    body = Buffer.from(
-      rewriteJavaScriptForBasePath(body.toString("utf8"), basePath, sourceBasePath),
-      "utf8",
-    );
-  }
-  const headers: Record<string, string | number> = {
-    ...BASE_SECURITY_HEADERS,
-    "cache-control": asset.cacheControl,
-    "content-length": body.byteLength,
-    "content-type": asset.contentType,
-  };
-  if (asset.document) headers["content-security-policy"] = DOCUMENT_CONTENT_SECURITY_POLICY;
-  res.writeHead(200, headers);
-  if (method === "HEAD") res.end();
-  else res.end(body);
-  req.resume();
-  return true;
-}
-
-export type IdentityProxyOptions = {
-  /** Backend child implementation supervised behind this protected ingress. */
-  backendImplementation?: BackendImplementation;
-  /** Public port to listen on. Clients point at this. */
-  listenPort: number;
-  /** Interface exposed to clients. Defaults are chosen by the CLI. */
-  listenHost: string;
-  /** Host the upstream TanStack Start server listens on. */
-  upstreamHost: string;
-  /** Port the upstream TanStack Start server listens on. */
-  upstreamPort: number;
-  /** Restrict non-proxy routes for clients outside the local machine. */
-  restrictRemoteControl?: boolean;
-  /** Explicitly expose UI, REST, and MCP to remote peers. */
-  allowRemoteControl?: boolean;
-  /** Optional Bearer token for remote control-plane API clients. */
-  controlToken?: string;
-  /** Dedicated credential for non-loopback model-proxy clients. */
-  proxyToken?: string;
-  /** Temporary compatibility escape hatch for legacy unauthenticated remote proxy clients. */
-  allowUnauthenticatedRemoteProxy?: boolean;
-  /** Additional public hostnames accepted by the ingress Host boundary. */
-  trustedHosts?: readonly string[];
-  /** Exact browser UI origins allowed to call control REST/SSE across origins. */
-  allowedUiOrigins?: readonly string[];
-  /** Independent static UI artifact directory served only by the protected ingress. */
-  uiDirectory?: string;
-  /** Explicit public origin for reverse-proxy deployments; never inferred from forwarded headers. */
-  publicOrigin?: string;
-  /** Maximum declared or streamed request body size. */
-  maxRequestBytes?: number;
-  /** Deadline for receiving and forwarding one request body. */
-  requestTimeoutMs?: number;
-  /** Runtime-scoped additional public Base Path mounts. */
-  aliasRegistry?: BasePathAliasRegistry;
-  /** Private lifecycle identity exposed only to the owning local instance manager. */
-  managedInstance?: ManagedInstanceControlOptions;
-  /** Optional Node-supervisor instance API retained when the selected backend is Rust. */
-  instanceApiHandler?: (request: Request) => Promise<Response>;
-};
-
-export type ManagedInstanceControlOptions = {
-  backend?: BackendImplementation;
-  name: string;
-  instanceId: string;
-  launchId: string;
-  controlToken: string;
-  supervisorPid: number;
-  startedAt: string;
-  publicPort: number;
-  upstreamPort: number;
-  requestShutdown: () => void;
-};
-
-function isLoopbackPeer(address: string | undefined): boolean {
-  if (address === undefined) return false;
-  const normalized = address.toLowerCase();
-  return (
-    normalized === "::1" || normalized.startsWith("127.") || normalized.startsWith("::ffff:127.")
-  );
-}
-
-function bearerToken(authorization: string | undefined): string | null {
-  if (authorization === undefined) return null;
-  const match = /^Bearer\s+(.+)$/i.exec(authorization.trim());
-  return match?.[1] ?? null;
-}
-
-function tokensMatch(received: string | null, expected: string | undefined): boolean {
-  if (received === null || expected === undefined || expected === "") return false;
-  const receivedBuffer = Buffer.from(received);
-  const expectedBuffer = Buffer.from(expected);
-  return (
-    receivedBuffer.byteLength === expectedBuffer.byteLength &&
-    timingSafeEqual(receivedBuffer, expectedBuffer)
-  );
-}
-
-function managedInstanceTokensMatch(received: string | undefined, expected: string): boolean {
-  if (received === undefined || received.length === 0 || expected.length === 0) return false;
-  const receivedDigest = createHash("sha256").update(received).digest();
-  const expectedDigest = createHash("sha256").update(expected).digest();
-  return timingSafeEqual(receivedDigest, expectedDigest);
-}
-
-function firstHeader(value: string | readonly string[] | undefined): string | undefined {
-  return typeof value === "string" ? value : value?.[0];
-}
-
-function normalizedHostname(value: string): string | null {
-  const candidate = value.trim();
-  if (candidate.length === 0) return null;
-  try {
-    return new URL(`http://${candidate}`).hostname.toLowerCase().replace(/^\[|]$/g, "");
-  } catch {
-    return null;
-  }
-}
-
-function isLoopbackHostname(hostname: string): boolean {
-  const normalized = hostname.toLowerCase().replace(/^\[|]$/g, "");
-  if (normalized === "localhost" || normalized === "::1") return true;
-  if (isIP(normalized) !== 4) return false;
-  return normalized.split(".", 1)[0] === "127";
-}
-
-export type UiOriginAllowlist = {
-  origins: readonly string[];
-  rejected: readonly string[];
-};
-
-function parseUrl(value: string): URL | null {
-  try {
-    return new URL(value);
-  } catch {
-    return null;
-  }
-}
-
-export function parseUiOriginAllowlist(value: string | undefined): UiOriginAllowlist {
-  const origins: string[] = [];
-  const rejected: string[] = [];
-  for (const entry of (value ?? "").split(",")) {
-    const candidate = entry.trim();
-    if (candidate.length === 0) continue;
-    const parsed = parseUrl(candidate);
-    const valid =
-      parsed !== null &&
-      (parsed.protocol === "http:" || parsed.protocol === "https:") &&
-      parsed.username.length === 0 &&
-      parsed.password.length === 0 &&
-      parsed.pathname === "/" &&
-      parsed.search.length === 0 &&
-      parsed.hash.length === 0 &&
-      isLoopbackHostname(parsed.hostname.toLowerCase().replace(/^\[|\]$/gu, ""));
-    if (!valid || parsed === null) {
-      rejected.push(candidate);
-      continue;
-    }
-    if (!origins.includes(parsed.origin)) origins.push(parsed.origin);
-  }
-  return { origins, rejected };
-}
-
-function normalizeTrustedPublicOrigin(value: string | undefined): string | null | undefined {
-  if (value === undefined) return undefined;
-  return normalizedRequestOrigin(value.trim());
-}
-
-export function isTrustedIdentityProxyHost(
-  host: string | undefined,
-  options: Pick<IdentityProxyOptions, "listenHost" | "trustedHosts">,
-): boolean {
-  if (host === undefined) return false;
-  const hostname = normalizedHostname(host);
-  if (hostname === null) return false;
-  if (isLoopbackHostname(hostname) || isIP(hostname) !== 0) return true;
-
-  const listenHostname = normalizedHostname(options.listenHost);
-  if (listenHostname !== null && hostname === listenHostname) return true;
-  return (options.trustedHosts ?? []).some(
-    (trustedHost) => normalizedHostname(trustedHost) === hostname,
-  );
-}
-
-function isSafeMethod(method: string | undefined): boolean {
-  const normalized = (method ?? "GET").toUpperCase();
-  return normalized === "GET" || normalized === "HEAD" || normalized === "OPTIONS";
-}
-
-const UI_CORS_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"] as const;
-const UI_CORS_HEADERS = ["authorization", "content-type", "last-event-id", CSRF_HEADER] as const;
-
-function normalizedRequestOrigin(origin: string): string | null {
-  try {
-    const parsed = new URL(origin);
-    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
-    if (parsed.username.length > 0 || parsed.password.length > 0) return null;
-    if (parsed.pathname !== "/" || parsed.search.length > 0 || parsed.hash.length > 0) return null;
-    return parsed.origin;
-  } catch {
-    return null;
-  }
-}
-
-function parsedRequestOrigin(origin: string): URL | null {
-  const normalized = normalizedRequestOrigin(origin);
-  if (normalized === null) return null;
-  return new URL(normalized);
-}
-
-function isSameOrLoopbackAliasOrigin(left: URL, right: URL): boolean {
-  if (left.origin === right.origin) return true;
-  return (
-    left.protocol === right.protocol &&
-    left.port === right.port &&
-    isLoopbackHostname(left.hostname) &&
-    isLoopbackHostname(right.hostname)
-  );
-}
-
-function isSameRequestOrigin(
-  origin: string,
-  host: string | undefined,
-  publicOrigin?: string,
-): boolean {
-  const parsedOrigin = parsedRequestOrigin(origin);
-  if (parsedOrigin === null) return false;
-  const expected = parsedRequestOrigin(publicOrigin ?? `http://${host ?? "localhost"}`);
-  return expected !== null && isSameOrLoopbackAliasOrigin(parsedOrigin, expected);
-}
-
-function matchedUiOrigin(
-  origin: string | undefined,
-  allowedUiOrigins: readonly string[] | undefined,
-): string | null {
-  if (origin === undefined) return null;
-  return (allowedUiOrigins ?? []).find((candidate) => candidate === origin) ?? null;
-}
-
-function isUiControlPath(pathname: string): boolean {
-  if (pathname === "/livez" || pathname === "/readyz") return true;
-  if (pathname === "/api/mcp") return false;
-  return pathname === "/api" || pathname.startsWith("/api/");
-}
-
-function isModelProxyPath(pathname: string): boolean {
-  return pathname === "/proxy" || pathname.startsWith("/proxy/");
-}
-
-function uiCorsHeaders(origin: string | null): Record<string, string> {
-  if (origin === null) return {};
-  return {
-    "access-control-allow-origin": origin,
-    "access-control-expose-headers": "Content-Disposition",
-    vary: "Origin",
-  };
-}
-
-function appendVaryHeader(existing: string | string[] | undefined, name: string): string {
-  const values = (Array.isArray(existing) ? existing.join(",") : (existing ?? ""))
-    .split(",")
-    .map((value) => value.trim())
-    .filter((value) => value.length > 0);
-  if (!values.some((value) => value.toLowerCase() === name.toLowerCase())) values.push(name);
-  return values.join(", ");
-}
-
-function requestedCorsHeaders(value: string | undefined): readonly string[] {
-  return (value ?? "")
-    .split(",")
-    .map((header) => header.trim().toLowerCase())
-    .filter((header) => header.length > 0);
-}
-
-function handleUiCorsPreflight(
-  req: http.IncomingMessage,
-  res: http.ServerResponse,
-  origin: string,
-): void {
-  const requestedMethod = firstHeader(req.headers["access-control-request-method"])?.toUpperCase();
-  const requestedHeaders = requestedCorsHeaders(
-    firstHeader(req.headers["access-control-request-headers"]),
-  );
-  const methodAllowed =
-    requestedMethod !== undefined && UI_CORS_METHODS.some((method) => method === requestedMethod);
-  const headersAllowed = requestedHeaders.every((header) =>
-    UI_CORS_HEADERS.some((allowedHeader) => allowedHeader === header),
-  );
-  if (!methodAllowed || !headersAllowed) {
-    res.writeHead(403, {
-      "content-type": "application/json; charset=utf-8",
-      "cache-control": "no-store",
-      ...uiCorsHeaders(origin),
-    });
-    res.end(JSON.stringify({ error: "CORS preflight is not allowed for this request." }));
-    req.resume();
-    return;
-  }
-  res.writeHead(204, {
-    "cache-control": "no-store",
-    "access-control-allow-origin": origin,
-    "access-control-allow-methods": UI_CORS_METHODS.join(", "),
-    "access-control-allow-headers": UI_CORS_HEADERS.join(", "),
-    "access-control-max-age": "600",
-    vary: "Origin, Access-Control-Request-Method, Access-Control-Request-Headers",
-  });
-  res.end();
-  req.resume();
-}
-
-function isPublicHealthPath(pathname: string): boolean {
-  return pathname === "/livez" || pathname === "/readyz" || pathname === "/api/health";
-}
-
-function isInstanceManagementPath(pathname: string): boolean {
-  return pathname === "/api/instances" || pathname.startsWith("/api/instances/");
-}
-
-function configuredPositiveInteger(value: number | undefined, fallback: number): number {
-  return value !== undefined && Number.isSafeInteger(value) && value > 0 ? value : fallback;
-}
-
-function declaredContentLength(value: string | undefined): number | null {
-  if (value === undefined) return null;
-  if (!/^\d+$/.test(value)) return Number.NaN;
-  const parsed = Number(value);
-  return Number.isSafeInteger(parsed) ? parsed : Number.NaN;
-}
-
-export function isBrowserMutationAllowed(input: {
-  path: string;
-  basePath?: string;
-  method?: string;
-  host?: string;
-  origin?: string;
-  secFetchSite?: string;
-  csrfToken?: string;
-  allowedUiOrigins?: readonly string[];
-  publicOrigin?: string;
-}): boolean {
-  if (isSafeMethod(input.method)) return true;
-  const pathname = stripBasePath(
-    new URL(input.path, "http://localhost").pathname,
-    input.basePath ?? getConfiguredBasePath(process.env),
-  );
-  const fetchSite = input.secFetchSite?.toLowerCase();
-  const browserRequest = input.origin !== undefined || fetchSite !== undefined;
-  if (!browserRequest) return true;
-  const sameOrigin =
-    input.origin !== undefined
-      ? isSameRequestOrigin(input.origin, input.host, input.publicOrigin)
-      : false;
-  if (isModelProxyPath(pathname)) {
-    if (fetchSite !== undefined && fetchSite !== "same-origin" && !sameOrigin) return false;
-    if (input.origin !== undefined && !sameOrigin) {
-      return false;
-    }
-    return input.csrfToken === "1";
-  }
-  const allowedOrigin = matchedUiOrigin(input.origin, input.allowedUiOrigins);
-  if (
-    fetchSite !== undefined &&
-    fetchSite !== "same-origin" &&
-    !sameOrigin &&
-    allowedOrigin === null
-  )
-    return false;
-  if (input.origin !== undefined) {
-    if (!sameOrigin && allowedOrigin === null) {
-      return false;
-    }
-  }
-  return input.csrfToken === "1";
-}
-
-export function isIdentityProxyRequestAllowed(input: {
-  path: string;
-  basePath?: string;
-  remoteAddress?: string;
-  authorization?: string;
-  proxyAuthorization?: string;
-  proxyTokenHeader?: string;
-  options: Pick<
-    IdentityProxyOptions,
-    | "restrictRemoteControl"
-    | "allowRemoteControl"
-    | "controlToken"
-    | "proxyToken"
-    | "allowUnauthenticatedRemoteProxy"
-  >;
-}): boolean {
-  const pathname = stripBasePath(
-    new URL(input.path, "http://localhost").pathname,
-    input.basePath ?? getConfiguredBasePath(process.env),
-  );
-  if (!isLoopbackPeer(input.remoteAddress) && isInstanceManagementPath(pathname)) {
-    return tokensMatch(bearerToken(input.authorization), input.options.controlToken);
-  }
-  if (input.options.restrictRemoteControl !== true) return true;
-  if (input.options.allowRemoteControl === true) return true;
-  if (isLoopbackPeer(input.remoteAddress)) return true;
-
-  if (pathname === "/proxy" || pathname.startsWith("/proxy/")) {
-    if (input.options.allowUnauthenticatedRemoteProxy === true) return true;
-    const proxyCredential = bearerToken(input.proxyAuthorization) ?? input.proxyTokenHeader ?? null;
-    return tokensMatch(proxyCredential, input.options.proxyToken);
-  }
-  if (isPublicHealthPath(pathname)) return true;
-  return tokensMatch(bearerToken(input.authorization), input.options.controlToken);
-}
-
-type AliasControlBodyResult =
-  | { ok: true; body: string }
-  | { ok: false; status: number; error: string };
-
-function readAliasControlBody(req: http.IncomingMessage): Promise<AliasControlBodyResult> {
-  const contentLength = declaredContentLength(req.headers["content-length"]);
-  if (contentLength !== null && (!Number.isFinite(contentLength) || contentLength < 0)) {
-    req.resume();
-    return Promise.resolve({ ok: false, status: 400, error: "Invalid Content-Length header" });
-  }
-  if (contentLength !== null && contentLength > ALIAS_CONTROL_MAX_REQUEST_BYTES) {
-    req.resume();
-    return Promise.resolve({
-      ok: false,
-      status: 413,
-      error: `Alias control body exceeds ${String(ALIAS_CONTROL_MAX_REQUEST_BYTES)} bytes`,
-    });
-  }
-
-  return new Promise((resolve) => {
-    const chunks: Buffer[] = [];
-    let receivedBytes = 0;
-    let settled = false;
-    const finish = (result: AliasControlBodyResult): void => {
-      if (settled) return;
-      settled = true;
-      resolve(result);
-    };
-    req.on("data", (chunk: unknown) => {
-      if (settled) return;
-      const buffer = toBuffer(chunk);
-      receivedBytes += buffer.byteLength;
-      if (receivedBytes > ALIAS_CONTROL_MAX_REQUEST_BYTES) {
-        finish({
-          ok: false,
-          status: 413,
-          error: `Alias control body exceeds ${String(ALIAS_CONTROL_MAX_REQUEST_BYTES)} bytes`,
-        });
-        return;
-      }
-      chunks.push(buffer);
-    });
-    req.on("end", () => {
-      finish({ ok: true, body: Buffer.concat(chunks).toString("utf8") });
-    });
-    req.on("aborted", () => {
-      finish({ ok: false, status: 400, error: "Client aborted alias control request" });
-    });
-    req.on("error", () => {
-      finish({ ok: false, status: 400, error: "Alias control request body failed" });
-    });
-  });
-}
-
-type LocalControlBodyResult =
-  | { ok: true; body: Buffer }
-  | { ok: false; status: number; error: string };
-
-function readLocalControlBody(
-  req: http.IncomingMessage,
-  maxBytes: number,
-  timeoutMs: number,
-): Promise<LocalControlBodyResult> {
-  return new Promise((resolve) => {
-    const chunks: Buffer[] = [];
-    let receivedBytes = 0;
-    let settled = false;
-    const timer = setTimeout(() => {
-      finish({ ok: false, status: 408, error: "Instance request body timed out" });
-      req.resume();
-    }, timeoutMs);
-    const finish = (result: LocalControlBodyResult): void => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      resolve(result);
-    };
-    req.on("data", (chunk: unknown) => {
-      if (settled) return;
-      const buffer = toBuffer(chunk);
-      receivedBytes += buffer.byteLength;
-      if (receivedBytes > maxBytes) {
-        finish({
-          ok: false,
-          status: 413,
-          error: `Instance request body exceeds ${String(maxBytes)} bytes`,
-        });
-        req.resume();
-        return;
-      }
-      chunks.push(buffer);
-    });
-    req.on("end", () => finish({ ok: true, body: Buffer.concat(chunks) }));
-    req.on("aborted", () =>
-      finish({ ok: false, status: 400, error: "Client aborted instance request body" }),
-    );
-    req.on("error", () =>
-      finish({ ok: false, status: 400, error: "Instance request body failed" }),
-    );
-  });
-}
-
-function writeLocalControlError(
-  res: http.ServerResponse,
-  status: number,
-  error: string,
-  allowedUiOrigin: string | null,
-): void {
-  res.writeHead(status, {
-    "content-type": "application/json; charset=utf-8",
-    "cache-control": "no-store",
-    ...uiCorsHeaders(allowedUiOrigin),
-  });
-  res.end(JSON.stringify({ error }));
-}
-
-async function handleLocalInstanceApi(
-  req: http.IncomingMessage,
-  res: http.ServerResponse,
-  handler: (request: Request) => Promise<Response>,
-  upstreamPath: string,
-  requestPublicOrigin: string,
-  allowedUiOrigin: string | null,
-  maxRequestBytes: number,
-  requestTimeoutMs: number,
-): Promise<void> {
-  const body = await readLocalControlBody(
-    req,
-    Math.min(maxRequestBytes, INSTANCE_API_MAX_REQUEST_BYTES),
-    requestTimeoutMs,
-  );
-  if (!body.ok) {
-    writeLocalControlError(res, body.status, body.error, allowedUiOrigin);
-    return;
-  }
-  const method = (req.method ?? "GET").toUpperCase();
-  const headers = new Headers();
-  const contentType = firstHeader(req.headers["content-type"]);
-  if (contentType !== undefined) headers.set("content-type", contentType);
-  const request = new Request(new URL(upstreamPath, requestPublicOrigin), {
-    method,
-    headers,
-    body: method === "GET" || method === "HEAD" ? undefined : body.body.toString("utf8"),
-  });
-  let response: Response;
-  try {
-    response = await handler(request);
-  } catch {
-    writeLocalControlError(res, 503, "Instance supervisor request failed", allowedUiOrigin);
-    return;
-  }
-  const responseBody = Buffer.from(await response.arrayBuffer());
-  if (responseBody.byteLength > LOCAL_CONTROL_MAX_RESPONSE_BYTES) {
-    writeLocalControlError(
-      res,
-      502,
-      "Instance supervisor response exceeded its resource limit",
-      allowedUiOrigin,
-    );
-    return;
-  }
-  const responseHeaders: Record<string, string> = {
-    ...uiCorsHeaders(allowedUiOrigin),
-    "content-length": String(responseBody.byteLength),
-  };
-  response.headers.forEach((value, name) => {
-    const lowerName = name.toLowerCase();
-    if (!REQUEST_HOP_BY_HOP.has(lowerName) && lowerName !== "content-length") {
-      responseHeaders[lowerName] = value;
-    }
-  });
-  responseHeaders["cache-control"] = "no-store";
-  res.writeHead(response.status, responseHeaders);
-  res.end(responseBody);
-}
-
-function isUnknownRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function aliasBasePathFromJson(
-  body: string,
-): { ok: true; basePath: string } | { ok: false; error: string } {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(body);
-  } catch {
-    return { ok: false, error: "Alias control body must be valid JSON." };
-  }
-  if (!isUnknownRecord(parsed) || typeof parsed.basePath !== "string") {
-    return { ok: false, error: 'Alias control body must contain a string "basePath" field.' };
-  }
-  return { ok: true, basePath: parsed.basePath };
-}
-
-function writeAliasControlResponse(
-  res: http.ServerResponse,
-  registry: BasePathAliasRegistry,
-  status: number,
-  result:
-    | { basePath?: string; code?: string; error?: string }
-    | { basePath: string }
-    | undefined = undefined,
-  extraHeaders: Readonly<Record<string, string>> = {},
-): void {
-  res.writeHead(status, {
-    "content-type": "application/json; charset=utf-8",
-    "cache-control": "no-store",
-    ...extraHeaders,
-  });
-  res.end(
-    JSON.stringify({
-      canonicalBasePath: registry.canonicalBasePath,
-      aliases: registry.list(),
-      runtimeScoped: true,
-      ...result,
-    }),
-  );
-}
-
-async function handleAliasControlRequest(
-  req: http.IncomingMessage,
-  res: http.ServerResponse,
-  registry: BasePathAliasRegistry,
-): Promise<void> {
-  if (!isLoopbackPeer(req.socket.remoteAddress)) {
-    req.resume();
-    writeAliasControlResponse(res, registry, 403, {
-      error: "Base Path aliases can only be managed from the local machine.",
-    });
-    return;
-  }
-  if (
-    !isBrowserMutationAllowed({
-      path: req.url ?? IDENTITY_PROXY_ALIAS_CONTROL_PATH,
-      basePath: "",
-      method: req.method,
-      host: req.headers.host,
-      origin: req.headers.origin,
-      secFetchSite: firstHeader(req.headers["sec-fetch-site"]),
-      csrfToken: firstHeader(req.headers[CSRF_HEADER]),
-    })
-  ) {
-    req.resume();
-    writeAliasControlResponse(res, registry, 403, {
-      error: "Browser mutation requires same-origin CSRF proof.",
-    });
-    return;
-  }
-
-  const method = (req.method ?? "GET").toUpperCase();
-  if (method === "GET") {
-    req.resume();
-    writeAliasControlResponse(res, registry, 200);
-    return;
-  }
-  if (method !== "POST" && method !== "DELETE") {
-    req.resume();
-    writeAliasControlResponse(
-      res,
-      registry,
-      405,
-      { error: "Alias control supports GET, POST, and DELETE." },
-      { allow: "GET, POST, DELETE" },
-    );
-    return;
-  }
-
-  const bodyResult = await readAliasControlBody(req);
-  if (!bodyResult.ok) {
-    writeAliasControlResponse(res, registry, bodyResult.status, { error: bodyResult.error });
-    return;
-  }
-  const input = aliasBasePathFromJson(bodyResult.body);
-  if (!input.ok) {
-    writeAliasControlResponse(res, registry, 400, { error: input.error });
-    return;
-  }
-  const mutation =
-    method === "POST" ? registry.add(input.basePath) : registry.remove(input.basePath);
-  if (mutation.ok) {
-    writeAliasControlResponse(res, registry, method === "POST" ? 201 : 200, {
-      basePath: mutation.basePath,
-    });
-    return;
-  }
-  const status =
-    mutation.code === "duplicate" || mutation.code === "overlap"
-      ? 409
-      : mutation.code === "not-found"
-        ? 404
-        : 400;
-  writeAliasControlResponse(res, registry, status, {
-    code: mutation.code,
-    error: mutation.error,
-  });
-}
-
-function writeManagedInstanceControlResponse(
-  res: http.ServerResponse,
-  status: number,
-  body: Readonly<Record<string, unknown>>,
-  extraHeaders: Readonly<Record<string, string>> = {},
-  onFinished: (() => void) | undefined = undefined,
-): void {
-  res.writeHead(status, {
-    "content-type": "application/json; charset=utf-8",
-    "cache-control": "no-store",
-    ...extraHeaders,
-  });
-  res.end(JSON.stringify(body), onFinished);
-}
-
-function handleManagedInstanceControlRequest(
-  req: http.IncomingMessage,
-  res: http.ServerResponse,
-  pathname: string,
-  managedInstance: ManagedInstanceControlOptions | undefined,
-): void {
-  req.resume();
-  if (managedInstance === undefined) {
-    writeManagedInstanceControlResponse(res, 404, { error: "Control endpoint not found" });
-    return;
-  }
-  const authorized = managedInstanceTokensMatch(
-    firstHeader(req.headers[MANAGED_INSTANCE_TOKEN_HEADER]),
-    managedInstance.controlToken,
-  );
-  if (!authorized) {
-    writeManagedInstanceControlResponse(res, 403, { error: "Instance control access denied" });
-    return;
-  }
-
-  const method = (req.method ?? "GET").toUpperCase();
-  if (pathname === MANAGED_INSTANCE_CONTROL_PATH) {
-    if (method !== "GET") {
-      writeManagedInstanceControlResponse(
-        res,
-        405,
-        { error: "Instance identity supports GET only" },
-        { allow: "GET" },
-      );
-      return;
-    }
-    writeManagedInstanceControlResponse(res, 200, {
-      schemaVersion: 1,
-      backend: managedInstance.backend ?? "typescript",
-      name: managedInstance.name,
-      instanceId: managedInstance.instanceId,
-      launchId: managedInstance.launchId,
-      supervisorPid: managedInstance.supervisorPid,
-      startedAt: managedInstance.startedAt,
-      publicPort: managedInstance.publicPort,
-      upstreamPort: managedInstance.upstreamPort,
-    });
-    return;
-  }
-  if (method !== "POST") {
-    writeManagedInstanceControlResponse(
-      res,
-      405,
-      { error: "Instance shutdown supports POST only" },
-      { allow: "POST" },
-    );
-    return;
-  }
-  writeManagedInstanceControlResponse(
-    res,
-    202,
-    { accepted: true, launchId: managedInstance.launchId },
-    {},
-    () => {
-      process.nextTick(managedInstance.requestShutdown);
-    },
-  );
-}
-
-function isIdentityProxyControlPath(pathname: string): boolean {
-  return (
-    pathname === IDENTITY_PROXY_CONTROL_NAMESPACE ||
-    pathname.startsWith(`${IDENTITY_PROXY_CONTROL_NAMESPACE}/`)
-  );
-}
-
-/**
- * Start a tiny native Node HTTP server that:
- *   1. Reads the client connection's source port (`req.socket.remotePort`).
- *   2. Resolves that port to a PID via the OS connection table
- *      (`Get-NetTCPConnection -LocalPort <port>` on Windows,
- *       `ss -tanp state established` on Linux/macOS).
- *   3. Resolves the PID's cwd / project folder.
- *   4. Injects everything as `X-Agent-Inspector-Client-*` headers.
- *   5. Reverse-proxies the request to the upstream inspector (TanStack
- *      Start, which already reads those headers via `getClientInfo`).
- *
- * Why this exists: TanStack Start strips the underlying TCP socket from
- * the fetch-API `Request` before it reaches the proxy handler, so the
- * handler cannot read `socket.remotePort`. Sitting in front of TanStack
- * Start as a native Node server restores the ability to look up the
- * client PID at the socket level — no wrapper script, no client-side
- * changes, no header configuration by the AI tool author.
- *
- * The proxy degrades gracefully when the OS lookup fails (missing
- * permissions, port not found): the request is still forwarded, just
- * without identity headers, so it falls back to the existing
- * best-effort scan inside TanStack Start.
- */
-export function startIdentityProxy(options: IdentityProxyOptions): Promise<http.Server> {
-  const allowedUiOrigins = parseUiOriginAllowlist(options.allowedUiOrigins?.join(","));
-  if (allowedUiOrigins.rejected.length > 0) {
-    return Promise.reject(
-      new Error(
-        `Unsafe UI origins are not accepted: ${allowedUiOrigins.rejected.join(", ")}. Only exact loopback HTTP(S) origins are supported.`,
-      ),
-    );
-  }
-  const publicOrigin = normalizeTrustedPublicOrigin(options.publicOrigin);
-  if (publicOrigin === null) {
-    return Promise.reject(
-      new Error(
-        "publicOrigin must be an exact HTTP(S) origin without credentials, path, or query.",
-      ),
-    );
-  }
-  const effectiveOptions: IdentityProxyOptions = {
-    ...options,
-    allowedUiOrigins: allowedUiOrigins.origins,
-    publicOrigin,
-  };
-  return new Promise((resolve, reject) => {
-    const server = http.createServer();
-    const aliasRegistry =
-      options.aliasRegistry ?? createBasePathAliasRegistry(getConfiguredBasePath(process.env));
-    const runtimeState: IdentityProxyRuntimeState = {
-      acceptingRequests: true,
-      activeRequests: 0,
-      drainWaiters: new Set(),
-    };
-    identityProxyRuntimeStates.set(server, runtimeState);
-    // Eagerly resolve client identity on `connection` — at that point the
-    // socket is fresh and the OS connection table still lists it as
-    // ESTABLISHED. By the time `request` fires (let alone after we finish
-    // reading the body) HTTP/1.0 clients have already closed their side
-    // and the row is in TIME_WAIT with PID 0.
-    server.on("connection", (socket: import("node:net").Socket) => {
-      const remotePort = socket.remotePort;
-      if (remotePort !== undefined && remotePort > 0) {
-        void lookupClientByPort(remotePort).catch(() => null);
-      }
-    });
-    server.on("request", (req, res) => {
-      if (!runtimeState.acceptingRequests) {
-        res.writeHead(503, {
-          "content-type": "application/json; charset=utf-8",
-          "cache-control": "no-store",
-          connection: "close",
-          "retry-after": "5",
-        });
-        res.end(JSON.stringify({ error: "Agent Inspector is shutting down" }));
-        req.resume();
-        return;
-      }
-
-      runtimeState.activeRequests += 1;
-      let released = false;
-      const release = (): void => {
-        if (released) return;
-        released = true;
-        runtimeState.activeRequests = Math.max(0, runtimeState.activeRequests - 1);
-        if (runtimeState.activeRequests !== 0) return;
-        for (const resolveDrain of runtimeState.drainWaiters) resolveDrain();
-        runtimeState.drainWaiters.clear();
-      };
-      res.once("finish", release);
-      res.once("close", release);
-      void handleRequest(req, res, effectiveOptions, aliasRegistry).catch((err: unknown) => {
-        const message = err instanceof Error ? err.message : String(err);
-        if (!res.headersSent) {
-          res.writeHead(502, { "content-type": "text/plain" });
-        }
-        res.end(`Identity proxy error: ${message}`);
-      });
-    });
-    server.once("error", reject);
-    server.listen(options.listenPort, options.listenHost, () => {
-      server.removeListener("error", reject);
-      resolve(server);
-    });
-  });
-}
-
-export function stopIdentityProxyAdmission(server: http.Server): void {
-  const state = identityProxyRuntimeStates.get(server);
-  if (state !== undefined) state.acceptingRequests = false;
-}
-
-export async function waitForIdentityProxyDrain(server: http.Server): Promise<void> {
-  const state = identityProxyRuntimeStates.get(server);
-  if (state === undefined || state.activeRequests === 0) return;
-  await new Promise<void>((resolve) => {
-    state.drainWaiters.add(resolve);
-  });
-}
-
-export async function closeIdentityProxyGracefully(server: http.Server): Promise<void> {
-  stopIdentityProxyAdmission(server);
-  const closed = new Promise<void>((resolve) => {
-    if (!server.listening) {
-      resolve();
-      return;
-    }
-    server.close(() => resolve());
-  });
-  await Promise.all([closed, waitForIdentityProxyDrain(server)]);
-}
-
-export function forceCloseIdentityProxy(server: http.Server): void {
-  stopIdentityProxyAdmission(server);
-  server.closeAllConnections();
-  server.close();
-}
-
-async function handleRequest(
-  req: http.IncomingMessage,
-  res: http.ServerResponse,
-  options: IdentityProxyOptions,
-  aliasRegistry: BasePathAliasRegistry,
-): Promise<void> {
-  const requestUrl = new URL(req.url ?? "/", "http://localhost");
-  if (!isTrustedIdentityProxyHost(req.headers.host, options)) {
-    res.writeHead(400, {
-      "content-type": "application/json; charset=utf-8",
-      "cache-control": "no-store",
-    });
-    res.end(JSON.stringify({ error: "Untrusted Host header" }));
-    req.resume();
-    return;
-  }
-
-  if (requestUrl.pathname === IDENTITY_PROXY_ALIAS_CONTROL_PATH) {
-    await handleAliasControlRequest(req, res, aliasRegistry);
-    return;
-  }
-
-  if (
-    requestUrl.pathname === MANAGED_INSTANCE_CONTROL_PATH ||
-    requestUrl.pathname === MANAGED_INSTANCE_SHUTDOWN_PATH
-  ) {
-    handleManagedInstanceControlRequest(req, res, requestUrl.pathname, options.managedInstance);
-    return;
-  }
-
-  if (isIdentityProxyControlPath(requestUrl.pathname)) {
-    req.resume();
-    writeManagedInstanceControlResponse(res, 404, { error: "Control endpoint not found" });
-    return;
-  }
-
-  const resolution = resolveBasePathAliasRequest(aliasRegistry, req.url ?? "/");
-  const basePath = resolution.effectiveBasePath;
-  const upstreamPath = resolution.upstreamPath;
-  const upstreamPathname = new URL(upstreamPath, "http://localhost").pathname;
-  const requestOrigin = req.headers.origin;
-  const requestPublicOrigin = publicOriginForRequest(req, options);
-  const crossOriginRequest =
-    requestOrigin !== undefined &&
-    !isSameRequestOrigin(requestOrigin, req.headers.host, requestPublicOrigin);
-  const allowedUiOrigin = crossOriginRequest
-    ? matchedUiOrigin(requestOrigin, options.allowedUiOrigins)
-    : null;
-
-  if (crossOriginRequest && isModelProxyPath(upstreamPathname)) {
-    res.writeHead(403, {
-      "content-type": "application/json; charset=utf-8",
-      "cache-control": "no-store",
-    });
-    res.end(
-      JSON.stringify({ error: "Cross-origin browser access to the model proxy is forbidden." }),
-    );
-    req.resume();
-    return;
-  }
-
-  if (crossOriginRequest && upstreamPathname === "/api/mcp") {
-    res.writeHead(403, {
-      "content-type": "application/json; charset=utf-8",
-      "cache-control": "no-store",
-    });
-    res.end(JSON.stringify({ error: "Browser CORS is not enabled for the MCP endpoint." }));
-    req.resume();
-    return;
-  }
-
-  if (crossOriginRequest && isUiControlPath(upstreamPathname)) {
-    if (allowedUiOrigin === null) {
-      res.writeHead(403, {
-        "content-type": "application/json; charset=utf-8",
-        "cache-control": "no-store",
-      });
-      res.end(
-        JSON.stringify({ error: "UI origin is not allowed by this Agent Inspector runtime." }),
-      );
-      req.resume();
-      return;
-    }
-    if ((req.method ?? "GET").toUpperCase() === "OPTIONS") {
-      handleUiCorsPreflight(req, res, allowedUiOrigin);
-      return;
-    }
-  }
-
-  if (basePath.length > 0 && requestUrl.pathname.startsWith("/assets/")) {
-    res.writeHead(307, {
-      location: `${basePath}${requestUrl.pathname}${requestUrl.search}`,
-      "cache-control": "no-store",
-    });
-    res.end();
-    req.resume();
-    return;
-  }
-
-  if (
-    !isBrowserMutationAllowed({
-      path: req.url ?? "/",
-      basePath,
-      method: req.method,
-      host: req.headers.host,
-      origin: req.headers.origin,
-      secFetchSite: firstHeader(req.headers["sec-fetch-site"]),
-      csrfToken: firstHeader(req.headers[CSRF_HEADER]),
-      allowedUiOrigins: options.allowedUiOrigins,
-      publicOrigin: requestPublicOrigin,
-    })
-  ) {
-    res.writeHead(403, {
-      "content-type": "application/json; charset=utf-8",
-      "cache-control": "no-store",
-      ...uiCorsHeaders(allowedUiOrigin),
-    });
-    res.end(JSON.stringify({ error: "Browser mutation requires same-origin CSRF proof" }));
-    req.resume();
-    return;
-  }
-
-  if (
-    !isIdentityProxyRequestAllowed({
-      path: req.url ?? "/",
-      basePath,
-      remoteAddress: req.socket.remoteAddress,
-      authorization: req.headers.authorization,
-      proxyAuthorization: req.headers["proxy-authorization"],
-      proxyTokenHeader: firstHeader(req.headers[PROXY_TOKEN_HEADER]),
-      options,
-    })
-  ) {
-    res.writeHead(403, {
-      "content-type": "application/json; charset=utf-8",
-      "cache-control": "no-store",
-      ...uiCorsHeaders(allowedUiOrigin),
-    });
-    res.end(
-      JSON.stringify({
-        error: "Remote access requires a credential scoped to this endpoint.",
-      }),
-    );
-    req.resume();
-    return;
-  }
-
-  if (
-    await tryServeUiAsset(
-      req,
-      res,
-      options,
-      upstreamPathname,
-      basePath,
-      aliasRegistry.canonicalBasePath,
-    )
-  ) {
-    return;
-  }
-
-  // The connection-time lookup already populated the per-port cache; this
-  // call now hits the cache and returns the result synchronously.
-  const remotePort = req.socket.remotePort;
-  let identity: Awaited<ReturnType<typeof lookupClientByPort>> | null = null;
-  if (remotePort !== undefined && remotePort > 0) {
-    try {
-      identity = await lookupClientByPort(remotePort);
-    } catch {
-      identity = null;
-    }
-  }
-
-  // Validate declared size before any body allocation, then forward the raw
-  // stream with backpressure while enforcing the actual-byte budget below.
-  const maxRequestBytes = configuredPositiveInteger(
-    options.maxRequestBytes,
-    DEFAULT_MAX_REQUEST_BYTES,
-  );
-  const contentLength = declaredContentLength(req.headers["content-length"]);
-  if (contentLength !== null && (!Number.isFinite(contentLength) || contentLength < 0)) {
-    res.writeHead(400, {
-      "content-type": "application/json; charset=utf-8",
-      "cache-control": "no-store",
-      ...uiCorsHeaders(allowedUiOrigin),
-    });
-    res.end(JSON.stringify({ error: "Invalid Content-Length header" }));
-    req.resume();
-    return;
-  }
-  if (contentLength !== null && contentLength > maxRequestBytes) {
-    res.writeHead(413, {
-      "content-type": "application/json; charset=utf-8",
-      "cache-control": "no-store",
-      ...uiCorsHeaders(allowedUiOrigin),
-    });
-    res.end(JSON.stringify({ error: `Request body exceeds ${String(maxRequestBytes)} bytes` }));
-    req.resume();
-    return;
-  }
-
-  const upstreamHeaders: Record<string, string | string[]> = {};
-  for (const [name, value] of Object.entries(req.headers)) {
-    const lowerName = name.toLowerCase();
-    if (REQUEST_HOP_BY_HOP.has(lowerName)) continue;
-    if (
-      basePath.length > 0 &&
-      (lowerName === "accept-encoding" || lowerName === "range" || lowerName === "if-range")
-    )
-      continue;
-    if (
-      lowerName.startsWith(IDENTITY_HEADER_PREFIX) &&
-      !FORWARDED_AGENT_HEADER_ALLOWLIST.has(lowerName)
-    )
-      continue;
-    if (lowerName === "authorization" && !isModelProxyPath(upstreamPathname)) continue;
-    if (value === undefined) continue;
-    upstreamHeaders[name] = value;
-  }
-  upstreamHeaders[AGENT_INSPECTOR_PUBLIC_BASE_PATH_HEADER] = basePath.length === 0 ? "/" : basePath;
-  upstreamHeaders[AGENT_INSPECTOR_PUBLIC_ORIGIN_HEADER] = requestPublicOrigin;
-  const publicPort = req.socket.localPort;
-  if (publicPort !== undefined && publicPort > 0 && publicPort <= 65_535) {
-    upstreamHeaders[AGENT_INSPECTOR_PUBLIC_PORT_HEADER] = String(publicPort);
-  }
-  if (identity !== null && identity.pid !== null) {
-    upstreamHeaders[IDENTITY_HEADERS.pid] = String(identity.pid);
-    if (identity.port !== null) {
-      upstreamHeaders[IDENTITY_HEADERS.port] = String(identity.port);
-    }
-    if (identity.cwd !== null) {
-      upstreamHeaders[IDENTITY_HEADERS.cwd] = identity.cwd;
-    }
-    if (identity.projectFolder !== null) {
-      upstreamHeaders[IDENTITY_HEADERS.projectFolder] = identity.projectFolder;
-    }
-  }
-
-  let terminal = false;
-  const requestTimeoutMs = configuredPositiveInteger(
-    options.requestTimeoutMs,
-    DEFAULT_REQUEST_TIMEOUT_MS,
-  );
-  if (options.instanceApiHandler !== undefined && isInstanceManagementPath(upstreamPathname)) {
-    await handleLocalInstanceApi(
-      req,
-      res,
-      options.instanceApiHandler,
-      upstreamPath,
-      requestPublicOrigin,
-      allowedUiOrigin,
-      maxRequestBytes,
-      requestTimeoutMs,
-    );
-    return;
-  }
-  const proxyReq = http.request(
-    {
-      hostname: options.upstreamHost,
-      port: options.upstreamPort,
-      path: upstreamPath,
-      method: req.method,
-      headers: upstreamHeaders,
-    },
-    (proxyRes) => {
-      if (terminal || res.destroyed) {
-        proxyRes.destroy();
-        return;
-      }
-      const destroyUpstreamResponse = (): void => {
-        proxyRes.destroy();
-        proxyRes.socket.destroy();
-        proxyReq.destroy();
-      };
-      const removeDownstreamListeners = (): void => {
-        res.removeListener("close", destroyUpstreamResponse);
-        res.removeListener("error", destroyUpstreamResponse);
-        req.socket.removeListener("close", destroyUpstreamResponse);
-      };
-      res.once("close", destroyUpstreamResponse);
-      res.once("error", destroyUpstreamResponse);
-      req.socket.once("close", destroyUpstreamResponse);
-      proxyRes.once("end", removeDownstreamListeners);
-      proxyRes.once("close", removeDownstreamListeners);
-      const outHeaders: Record<string, string | string[]> = {};
-      const contentType = firstHeader(proxyRes.headers["content-type"]);
-      const shouldRewriteHtml =
-        basePath.length > 0 && contentType?.toLowerCase().includes("text/html") === true;
-      const shouldRewriteJavaScript =
-        basePath.length > 0 &&
-        (contentType?.toLowerCase().includes("javascript") === true ||
-          upstreamPath.split("?", 1)[0]?.endsWith(".js") === true);
-      const shouldRewriteBody = shouldRewriteHtml || shouldRewriteJavaScript;
-      for (const [name, value] of Object.entries(proxyRes.headers)) {
-        const lowerName = name.toLowerCase();
-        if (RESPONSE_HOP_BY_HOP.has(lowerName)) continue;
-        if (
-          shouldRewriteBody &&
-          (lowerName === "content-length" ||
-            lowerName === "content-range" ||
-            lowerName === "accept-ranges" ||
-            lowerName === "etag" ||
-            lowerName === "last-modified" ||
-            lowerName === "content-md5" ||
-            lowerName === "digest")
-        )
-          continue;
-        if (value === undefined) continue;
-        if (
-          lowerName === "location" &&
-          basePath.length > 0 &&
-          typeof value === "string" &&
-          value.startsWith("/") &&
-          !value.startsWith("//")
-        ) {
-          outHeaders[name] = rewriteRootRelativePublicPath(
-            value,
-            basePath,
-            aliasRegistry.canonicalBasePath,
-          );
-        } else {
-          outHeaders[name] = value;
-        }
-      }
-      for (const [name, value] of Object.entries(BASE_SECURITY_HEADERS)) {
-        outHeaders[name] = value;
-      }
-      outHeaders[AGENT_INSPECTOR_BACKEND_HEADER] = options.backendImplementation ?? "typescript";
-      if (allowedUiOrigin !== null && isUiControlPath(upstreamPathname)) {
-        outHeaders["access-control-allow-origin"] = allowedUiOrigin;
-        outHeaders["access-control-expose-headers"] = "Content-Disposition";
-        outHeaders["vary"] = appendVaryHeader(outHeaders["vary"], "Origin");
-      }
-      if (contentType?.toLowerCase().includes("text/html") === true) {
-        outHeaders["content-security-policy"] = DOCUMENT_CONTENT_SECURITY_POLICY;
-      }
-      const responseStatus =
-        shouldRewriteBody && proxyRes.statusCode === 206 ? 200 : (proxyRes.statusCode ?? 502);
-      res.writeHead(responseStatus, outHeaders);
-      if (shouldRewriteBody) {
-        const chunks: Buffer[] = [];
-        proxyRes.on("data", (chunk: unknown) => {
-          chunks.push(toBuffer(chunk));
-        });
-        proxyRes.on("end", () => {
-          const body = Buffer.concat(chunks).toString("utf8");
-          res.write(
-            shouldRewriteHtml
-              ? rewriteHtmlForBasePath(body, basePath, aliasRegistry.canonicalBasePath)
-              : rewriteJavaScriptForBasePath(body, basePath, aliasRegistry.canonicalBasePath),
-          );
-          res.end();
-        });
-        proxyRes.on("error", () => {
-          if (!res.writableEnded) res.destroy();
-        });
-        return;
-      }
-      proxyRes.pipe(res);
-    },
-  );
-  const deadline = setTimeout(() => {
-    failRequest(408, "Request body deadline exceeded");
-  }, requestTimeoutMs);
-  deadline.unref();
-
-  function clearDeadline(): void {
-    clearTimeout(deadline);
-  }
-
-  function failRequest(status: number, error: string): void {
-    if (terminal) return;
-    terminal = true;
-    clearDeadline();
-    proxyReq.destroy();
-    if (res.headersSent) {
-      res.destroy();
-    } else {
-      res.writeHead(status, {
-        "content-type": "application/json; charset=utf-8",
-        "cache-control": "no-store",
-      });
-      res.end(JSON.stringify({ error }));
-    }
-    req.resume();
-  }
-
-  proxyReq.on("error", (err) => {
-    if (terminal) return;
-    terminal = true;
-    clearDeadline();
-    if (!res.headersSent) {
-      res.writeHead(502, { "content-type": "text/plain" });
-    }
-    res.end(`Upstream error: ${err.message}`);
-  });
-  proxyReq.on("drain", () => req.resume());
-  res.once("close", () => {
-    clearDeadline();
-    proxyReq.destroy();
-  });
-
-  let receivedBytes = 0;
-  req.on("data", (chunk: unknown) => {
-    if (terminal) return;
-    const buffer = toBuffer(chunk);
-    receivedBytes += buffer.byteLength;
-    if (receivedBytes > maxRequestBytes) {
-      failRequest(413, `Request body exceeds ${String(maxRequestBytes)} bytes`);
-      return;
-    }
-    if (buffer.byteLength > 0 && !proxyReq.write(buffer)) req.pause();
-  });
-  req.on("end", () => {
-    if (terminal) return;
-    clearDeadline();
-    proxyReq.end();
-  });
-  req.on("aborted", () => {
-    failRequest(400, "Client aborted request body");
-  });
-  req.on("error", () => {
-    failRequest(400, "Request body stream failed");
-  });
-}
-
-// `Readable` chunks in Node are typed as `any` (they can be Buffer | string
-// depending on the encoding setting). We narrow them via runtime checks.
-function toBuffer(chunk: unknown): Buffer {
-  if (Buffer.isBuffer(chunk)) return chunk;
-  if (typeof chunk === "string") return Buffer.from(chunk);
-  // `for await` over a Node Readable always yields Buffer | string; this
-  // branch is only reachable if a custom stream returns something else
-  // (Uint8Array / ArrayBuffer / etc.). The Buffer constructor accepts an
-  // ArrayBuffer directly; we attempt that first, then fall back to a
-  // best-effort empty buffer so we never throw on an unexpected chunk.
-  if (chunk instanceof ArrayBuffer) return Buffer.from(chunk);
-  if (chunk instanceof Uint8Array)
-    return Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength);
-  return Buffer.alloc(0);
-}