@tonyclaw/agent-inspector 3.0.44 → 3.0.46

package/src/lib/alertContract.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { JsonValueSchema } from "../contracts";
+import { JsonValueSchema, LogIdSchema } from "../contracts";
 
 export const AlertSeveritySchema = z.enum(["critical", "warning", "notice"]);
 export const AlertStatusSchema = z.enum(["open"]);
@@ -35,7 +35,7 @@ export const AlertSchema = z.object({
   count: z.number().int().positive(),
   firstSeenAt: z.string(),
   lastSeenAt: z.string(),
-  logIds: z.array(z.number().int().positive()),
+  logIds: z.array(LogIdSchema),
   sessionIds: z.array(z.string()),
   runIds: z.array(z.string()),
   groupIds: z.array(z.string()),

package/src/lib/apiClient.ts

@@ -1,6 +1,6 @@
 /* eslint-disable functional/no-throw-statements */
 import { z } from "zod";
-import { withBasePath } from "./basePath";
+import { buildControlRuntimeUrl, resolveBrowserRuntimeForDocument } from "./browserRuntimeResolver";
 
 const ApiErrorSchema = z.object({
   error: z.string(),
@@ -8,10 +8,22 @@ const ApiErrorSchema = z.object({
 
 const MUTATION_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
 
-function withInspectorBasePath(input: RequestInfo | URL): RequestInfo | URL {
+function withInspectorControlSurface(input: RequestInfo | URL): RequestInfo | URL {
   if (typeof input !== "string") return input;
-  if (!input.startsWith("/") || input.startsWith("//")) return input;
-  return withBasePath(input);
+  if (!input.startsWith("/")) return input;
+  if (input.startsWith("//")) {
+    throw new TypeError("Protocol-relative API URLs are not allowed.");
+  }
+
+  const runtime = resolveBrowserRuntimeForDocument();
+  if (!runtime.ok) {
+    throw new Error(`Browser runtime is unavailable: ${runtime.issues.join("; ")}`);
+  }
+  const url = buildControlRuntimeUrl(runtime.runtime, input);
+  if (url === null) {
+    throw new TypeError(`Invalid logical control path: ${input}`);
+  }
+  return url;
 }
 
 export function withBrowserMutationProof(init?: RequestInit): RequestInit | undefined {
@@ -50,6 +62,17 @@ export async function readApiError(response: Response, fallback: string): Promis
   }
 }
 
+/**
+ * Fetch through the browser runtime's control surface while retaining the
+ * mutation proof required by the protected ingress.
+ */
+export async function fetchControl(
+  input: RequestInfo | URL,
+  init?: RequestInit,
+): Promise<Response> {
+  return await fetch(withInspectorControlSurface(input), withBrowserMutationProof(init));
+}
+
 /**
  * Fetch a JSON resource and validate its successful response.
  */
@@ -59,7 +82,7 @@ export async function fetchJson<T>(
   init?: RequestInit,
   errorFallback?: (response: Response) => string,
 ): Promise<T> {
-  const response = await fetch(withInspectorBasePath(input), withBrowserMutationProof(init));
+  const response = await fetchControl(input, init);
   if (!response.ok) {
     const fallback = errorFallback?.(response) ?? `Request failed with status ${response.status}`;
     throw new Error(await readApiError(response, fallback));
@@ -107,8 +130,8 @@ export async function fetchWithTimeout(
   }
 
   try {
-    return await fetch(withInspectorBasePath(input), {
-      ...withBrowserMutationProof(init),
+    return await fetchControl(input, {
+      ...init,
       signal: controller.signal,
     });
   } catch (error) {

package/src/lib/apiFormat.ts

@@ -0,0 +1,29 @@
+import type { ApiFormat } from "../contracts/log";
+
+type KnownApiFormat = Exclude<ApiFormat, "unknown">;
+
+/**
+ * Request paths whose protocol is part of the public Agent Inspector contract.
+ *
+ * Keep this module browser-safe: both the proxy registry and the UI's log
+ * presentation use the same path classifier without importing proxy startup
+ * registrations or provider implementations.
+ */
+export const API_FORMAT_PATH_ENTRIES: ReadonlyArray<
+  readonly [path: string, format: KnownApiFormat]
+> = [
+  ["/v1/messages", "anthropic"],
+  ["/v1/chat/completions", "openai"],
+  ["/chat/completions", "openai"],
+  ["/v1/responses", "openai"],
+  ["/responses", "openai"],
+];
+
+/** Resolve an API format from its authoritative request path. */
+export function apiFormatForPath(path: string): ApiFormat {
+  const requestPath = path.split("?")[0] ?? "";
+  for (const [knownPath, format] of API_FORMAT_PATH_ENTRIES) {
+    if (requestPath === knownPath) return format;
+  }
+  return "unknown";
+}

package/src/lib/basePath.ts

@@ -4,6 +4,9 @@ export const AGENT_INSPECTOR_BASE_PATH_ENV = "AGENT_INSPECTOR_BASE_PATH";
 export const AGENT_INSPECTOR_INTERNAL_STRIPPED_BASE_PATH_ENV =
   "AGENT_INSPECTOR_INTERNAL_STRIPPED_BASE_PATH";
 export const AGENT_INSPECTOR_BASE_PATH_META_NAME = "agent-inspector-base-path";
+export const AGENT_INSPECTOR_PUBLIC_BASE_PATH_HEADER = "x-agent-inspector-public-base-path";
+export const AGENT_INSPECTOR_PUBLIC_PORT_HEADER = "x-agent-inspector-public-port";
+export const AGENT_INSPECTOR_PUBLIC_ORIGIN_HEADER = "x-agent-inspector-public-origin";
 export const DEFAULT_AGENT_INSPECTOR_BASE_PATH = "/inspector";
 
 type BasePathEnv = Readonly<Record<string, string | undefined>>;
@@ -12,6 +15,24 @@ function trimSlashes(value: string): string {
   return value.replace(/^\/+/u, "").replace(/\/+$/u, "");
 }
 
+const SAFE_PUBLIC_BASE_PATH_PATTERN = /^\/[A-Za-z0-9._~-]+(?:\/[A-Za-z0-9._~-]+)*$/u;
+
+/**
+ * Normalize a public mount path only when every segment is safe to reuse in
+ * URLs, HTML attributes, JavaScript bootstrap data, and ingress routing.
+ * Root is represented internally as the empty string.
+ */
+export function normalizePublicBasePath(value: string | undefined): string | null {
+  const trimmed = value?.trim() ?? "";
+  if (trimmed.length === 0 || trimmed === "/") return "";
+  if (!trimmed.startsWith("/") || trimmed.startsWith("//")) return null;
+
+  const normalized = normalizeBasePath(trimmed);
+  if (!SAFE_PUBLIC_BASE_PATH_PATTERN.test(normalized)) return null;
+  if (normalized.split("/").some((segment) => segment === "." || segment === "..")) return null;
+  return normalized;
+}
+
 export function normalizeBasePath(value: string | undefined): string {
   const trimmed = value?.trim();
   if (trimmed === undefined || trimmed.length === 0 || trimmed === "/") return "";
@@ -35,13 +56,16 @@ function readProcessBasePath(): string | undefined {
 }
 
 export function getConfiguredBasePath(env?: BasePathEnv): string {
-  return normalizeBasePath(
-    env?.[AGENT_INSPECTOR_BASE_PATH_ENV] ??
-      readProcessBasePath() ??
-      readDocumentBasePath() ??
-      import.meta.env?.BASE_URL ??
-      DEFAULT_AGENT_INSPECTOR_BASE_PATH,
-  );
+  const configured =
+    env !== undefined
+      ? (env[AGENT_INSPECTOR_BASE_PATH_ENV] ?? DEFAULT_AGENT_INSPECTOR_BASE_PATH)
+      : (readProcessBasePath() ??
+        readDocumentBasePath() ??
+        import.meta.env?.BASE_URL ??
+        DEFAULT_AGENT_INSPECTOR_BASE_PATH);
+  const normalized = normalizePublicBasePath(configured);
+  if (normalized !== null) return normalized;
+  return normalizePublicBasePath(DEFAULT_AGENT_INSPECTOR_BASE_PATH) ?? "";
 }
 
 export function getRouterBasePath(env?: BasePathEnv): string {

package/src/lib/browserRuntimeContract.ts

@@ -0,0 +1,124 @@
+import { z } from "zod";
+import { normalizePublicBasePath } from "./basePath";
+
+export const BROWSER_RUNTIME_SCHEMA_VERSION = 1;
+export const BROWSER_RUNTIME_JSON_PLACEHOLDER = "__AGENT_INSPECTOR_RUNTIME_JSON__";
+
+function parseAbsoluteUrl(value: string): URL | null {
+  try {
+    return new URL(value);
+  } catch {
+    return null;
+  }
+}
+
+function hasUnsafePathSegment(pathname: string): boolean {
+  return pathname
+    .split("/")
+    .some((segment) => segment === "." || segment === ".." || /%(?:2e|2f|5c)/iu.test(segment));
+}
+
+function hasControlCharacter(value: string): boolean {
+  return [...value].some((character) => {
+    const code = character.charCodeAt(0);
+    return code < 32 || code === 127;
+  });
+}
+
+export function normalizeBrowserRuntimeBasePath(value: string): string | null {
+  const trimmed = value.trim();
+  if (trimmed.length === 0) return null;
+  const normalized = normalizePublicBasePath(trimmed);
+  if (normalized === null) return null;
+  return normalized.length === 0 ? "/" : normalized;
+}
+
+export function normalizeBrowserRuntimeBaseUrl(value: string): string | null {
+  if (
+    value.trim() !== value ||
+    value.includes("\\") ||
+    hasControlCharacter(value) ||
+    hasUnsafePathSegment(value)
+  ) {
+    return null;
+  }
+
+  const parsed = parseAbsoluteUrl(value);
+  if (parsed === null) return null;
+
+  switch (parsed.protocol) {
+    case "http:":
+    case "https:":
+      break;
+    default:
+      return null;
+  }
+
+  if (
+    parsed.username.length > 0 ||
+    parsed.password.length > 0 ||
+    parsed.search.length > 0 ||
+    parsed.hash.length > 0 ||
+    hasUnsafePathSegment(parsed.pathname)
+  ) {
+    return null;
+  }
+
+  const basePath = normalizeBrowserRuntimeBasePath(parsed.pathname);
+  if (basePath === null) return null;
+  return basePath === "/" ? parsed.origin : `${parsed.origin}${basePath}`;
+}
+
+export const BrowserRuntimeBasePathSchema = z
+  .string()
+  .min(1)
+  .max(2_048)
+  .refine(
+    (value) => normalizeBrowserRuntimeBasePath(value) !== null,
+    "UI Base Path must be an absolute path without query, hash, backslash, or traversal",
+  )
+  .transform((value) => normalizeBrowserRuntimeBasePath(value) ?? value);
+
+export const BrowserRuntimeBaseUrlSchema = z
+  .string()
+  .min(1)
+  .max(2_048)
+  .refine(
+    (value) => normalizeBrowserRuntimeBaseUrl(value) !== null,
+    "Runtime Base URL must be an HTTP(S) URL without credentials, query, hash, or traversal",
+  )
+  .transform((value) => normalizeBrowserRuntimeBaseUrl(value) ?? value);
+
+export const BrowserRuntimeCapabilitiesSchema = z
+  .object({
+    rest: z.boolean(),
+    sse: z.boolean(),
+    proxy: z.boolean(),
+    mcp: z.boolean(),
+  })
+  .strict();
+
+export const BrowserRuntimeDeploymentSchema = z
+  .object({
+    schemaVersion: z.literal(BROWSER_RUNTIME_SCHEMA_VERSION),
+    deploymentMode: z.enum(["composed", "backend-only", "separated"]),
+    ui: z
+      .object({
+        basePath: BrowserRuntimeBasePathSchema,
+      })
+      .strict(),
+    control: z
+      .object({
+        baseUrl: BrowserRuntimeBaseUrlSchema,
+      })
+      .strict(),
+    agent: z
+      .object({
+        baseUrl: BrowserRuntimeBaseUrlSchema,
+      })
+      .strict(),
+    capabilities: BrowserRuntimeCapabilitiesSchema,
+  })
+  .strict();
+
+export type BrowserRuntimeDeployment = z.infer<typeof BrowserRuntimeDeploymentSchema>;

package/src/lib/browserRuntimeResolver.ts

@@ -0,0 +1,244 @@
+import { getConfiguredBasePath } from "./basePath";
+import {
+  BROWSER_RUNTIME_SCHEMA_VERSION,
+  BrowserRuntimeDeploymentSchema,
+  normalizeBrowserRuntimeBasePath,
+  normalizeBrowserRuntimeBaseUrl,
+  type BrowserRuntimeDeployment,
+} from "./browserRuntimeContract";
+
+export const AGENT_INSPECTOR_INJECTED_RUNTIME_GLOBAL = "__AGENT_INSPECTOR_RUNTIME__";
+export const AGENT_INSPECTOR_OPERATOR_RUNTIME_GLOBAL = "__AGENT_INSPECTOR_RUNTIME_CONFIG__";
+export const AGENT_INSPECTOR_RUNTIME_DISCOVERED_EVENT = "agent-inspector:runtime-discovered";
+
+export type BrowserRuntimeSource = "injected" | "operator" | "discovered" | "composed-fallback";
+
+export type BrowserRuntimeComposedFallback = {
+  origin: string;
+  uiBasePath: string;
+};
+
+export type BrowserRuntimeSources = {
+  injected?: unknown;
+  operator?: unknown;
+  composedFallback?: BrowserRuntimeComposedFallback;
+};
+
+export type BrowserRuntimeResolution =
+  | {
+      ok: true;
+      source: BrowserRuntimeSource;
+      runtime: BrowserRuntimeDeployment;
+    }
+  | {
+      ok: false;
+      source: BrowserRuntimeSource | "none";
+      code: "invalid" | "missing";
+      issues: readonly string[];
+    };
+
+let discoveredRuntimeForDocument: BrowserRuntimeDeployment | null = null;
+
+function readGlobalValue(name: string): unknown {
+  const descriptor = Object.getOwnPropertyDescriptor(globalThis, name);
+  const value: unknown = descriptor?.value;
+  if (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Object.keys(value).length === 0
+  ) {
+    return undefined;
+  }
+  return value;
+}
+
+export function readBrowserRuntimeSources(): Pick<BrowserRuntimeSources, "injected" | "operator"> {
+  return {
+    injected: readGlobalValue(AGENT_INSPECTOR_INJECTED_RUNTIME_GLOBAL),
+    operator: readGlobalValue(AGENT_INSPECTOR_OPERATOR_RUNTIME_GLOBAL),
+  };
+}
+
+function formatIssues(error: {
+  issues: readonly { path: PropertyKey[]; message: string }[];
+}): string[] {
+  return error.issues.map((issue) => {
+    const path = issue.path.map(String).join(".");
+    return path.length === 0 ? issue.message : `${path}: ${issue.message}`;
+  });
+}
+
+function validateRuntime(source: BrowserRuntimeSource, value: unknown): BrowserRuntimeResolution {
+  const parsed = BrowserRuntimeDeploymentSchema.safeParse(value);
+  if (parsed.success) {
+    return { ok: true, source, runtime: parsed.data };
+  }
+  return {
+    ok: false,
+    source,
+    code: "invalid",
+    issues: formatIssues(parsed.error),
+  };
+}
+
+function fallbackRuntime(fallback: BrowserRuntimeComposedFallback): unknown {
+  const normalizedOrigin = normalizeBrowserRuntimeBaseUrl(fallback.origin);
+  const normalizedBasePath = normalizeBrowserRuntimeBasePath(
+    fallback.uiBasePath.length === 0 ? "/" : fallback.uiBasePath,
+  );
+  if (
+    normalizedOrigin === null ||
+    normalizedBasePath === null ||
+    normalizedOrigin !== new URL(normalizedOrigin).origin
+  ) {
+    return null;
+  }
+
+  const baseUrl =
+    normalizedBasePath === "/" ? normalizedOrigin : `${normalizedOrigin}${normalizedBasePath}`;
+  return {
+    schemaVersion: BROWSER_RUNTIME_SCHEMA_VERSION,
+    deploymentMode: "composed",
+    ui: { basePath: normalizedBasePath },
+    control: { baseUrl },
+    agent: { baseUrl },
+    capabilities: {
+      rest: true,
+      sse: true,
+      proxy: true,
+      mcp: true,
+    },
+  };
+}
+
+export function resolveBrowserRuntime(sources: BrowserRuntimeSources): BrowserRuntimeResolution {
+  if (sources.injected !== undefined) {
+    return validateRuntime("injected", sources.injected);
+  }
+  if (sources.operator !== undefined) {
+    return validateRuntime("operator", sources.operator);
+  }
+  if (sources.composedFallback !== undefined) {
+    return validateRuntime("composed-fallback", fallbackRuntime(sources.composedFallback));
+  }
+  return {
+    ok: false,
+    source: "none",
+    code: "missing",
+    issues: ["No injected, operator, or explicit composed runtime configuration is available."],
+  };
+}
+
+function configuredBrowserRuntimeForDocument(): BrowserRuntimeResolution | null {
+  const sources = readBrowserRuntimeSources();
+  if (sources.injected !== undefined || sources.operator !== undefined) {
+    return resolveBrowserRuntime(sources);
+  }
+  return null;
+}
+
+export function acceptBrowserRuntimeDiscovery(
+  expectedFallback: BrowserRuntimeDeployment,
+  value: unknown,
+): BrowserRuntimeResolution {
+  const discovered = validateRuntime("discovered", value);
+  if (!discovered.ok) return discovered;
+  if (
+    discovered.runtime.control.baseUrl !== expectedFallback.control.baseUrl ||
+    discovered.runtime.ui.basePath !== expectedFallback.ui.basePath
+  ) {
+    return {
+      ok: false,
+      source: "discovered",
+      code: "invalid",
+      issues: ["Backend discovery does not match the same-origin fallback control surface."],
+    };
+  }
+  discoveredRuntimeForDocument = discovered.runtime;
+  if (typeof globalThis.dispatchEvent === "function" && typeof globalThis.Event === "function") {
+    globalThis.dispatchEvent(new Event(AGENT_INSPECTOR_RUNTIME_DISCOVERED_EVENT));
+  }
+  return discovered;
+}
+
+export function resolveVerifiedBrowserRuntimeForDocument(): BrowserRuntimeResolution {
+  const configured = configuredBrowserRuntimeForDocument();
+  if (configured !== null) return configured;
+  if (discoveredRuntimeForDocument !== null) {
+    return validateRuntime("discovered", discoveredRuntimeForDocument);
+  }
+  return {
+    ok: false,
+    source: "none",
+    code: "missing",
+    issues: ["The same-origin backend discovery response has not been validated."],
+  };
+}
+
+export function resolveBrowserRuntimeForDocument(): BrowserRuntimeResolution {
+  const configured = configuredBrowserRuntimeForDocument();
+  if (configured !== null) return configured;
+  if (discoveredRuntimeForDocument !== null) {
+    return validateRuntime("discovered", discoveredRuntimeForDocument);
+  }
+  if (typeof globalThis.location === "undefined") return resolveBrowserRuntime({});
+  return resolveBrowserRuntime({
+    composedFallback: {
+      origin: globalThis.location.origin,
+      uiBasePath: getConfiguredBasePath(),
+    },
+  });
+}
+
+function hasControlCharacter(value: string): boolean {
+  return [...value].some((character) => {
+    const code = character.charCodeAt(0);
+    return code < 32 || code === 127;
+  });
+}
+
+function normalizeLogicalRuntimePath(value: string): string | null {
+  if (
+    value.trim() !== value ||
+    !value.startsWith("/") ||
+    value.startsWith("//") ||
+    value.includes("#") ||
+    value.includes("\\") ||
+    hasControlCharacter(value)
+  ) {
+    return null;
+  }
+
+  const queryIndex = value.indexOf("?");
+  const pathname = queryIndex < 0 ? value : value.slice(0, queryIndex);
+  const segments = pathname.split("/");
+  if (
+    segments.some(
+      (segment) => segment === "." || segment === ".." || /%(?:2e|2f|5c)/iu.test(segment),
+    )
+  ) {
+    return null;
+  }
+  return value === "/" ? "" : value;
+}
+
+function buildRuntimeUrl(baseUrl: string, logicalPath: string): string | null {
+  const path = normalizeLogicalRuntimePath(logicalPath);
+  if (path === null) return null;
+  return `${baseUrl}${path}`;
+}
+
+export function buildControlRuntimeUrl(
+  runtime: BrowserRuntimeDeployment,
+  logicalPath: string,
+): string | null {
+  return buildRuntimeUrl(runtime.control.baseUrl, logicalPath);
+}
+
+export function buildAgentRuntimeUrl(
+  runtime: BrowserRuntimeDeployment,
+  logicalPath: string,
+): string | null {
+  return buildRuntimeUrl(runtime.agent.baseUrl, logicalPath);
+}

package/src/{proxy → lib}/claudeCodeStrip.ts

@@ -1,3 +1,5 @@
+import { isPlainRecord, safeGetOwnProperty } from "./objectUtils";
+
 /**
  * Claude Code (and similar Anthropic SDK-based clients) prepend a synthetic
  * text block to the `system` array that looks like an HTTP header:
@@ -9,9 +11,8 @@
  * changes on every request, which kills prefix-cache hit rates and wastes
  * input tokens.
  *
- * This module detects the marker and returns a rewritten body with the
- * block removed. It is opt-in (see constants.ts) so the proxy remains a
- * transparent pass-through by default.
+ * This browser-safe module contains only the pure request transformation so
+ * the proxy and UI preview can share it without coupling the UI to the proxy.
  */
 
 const BILLING_HEADER_PREFIX = "x-anthropic-billing-header:";
@@ -33,8 +34,6 @@ export function isClaudeCodeBillingHeaderBlock(text: string): boolean {
   return trimmed.toLowerCase().startsWith(BILLING_HEADER_PREFIX);
 }
 
-import { safeGetOwnProperty, isPlainRecord } from "../lib/objectUtils";
-
 function isObjectWithSystem(value: unknown): value is { system?: unknown[] } {
   if (!isPlainRecord(value)) return false;
   return Object.prototype.hasOwnProperty.call(value, "system");
@@ -53,8 +52,8 @@ function isBillingHeaderTextBlock(block: unknown): boolean {
  * Inspects the request body and, if it is an Anthropic-format request whose
  * `system` array contains one or more Claude Code billing-header text blocks,
  * returns a new body with those blocks removed. The original string is
- * returned unchanged (by reference equality on the result) when no edit is
- * needed so callers can avoid re-serializing.
+ * returned unchanged when no edit is needed so callers can avoid
+ * re-serializing.
  */
 export function stripClaudeCodeBillingHeader(rawBody: string): StripResult {
   let parsed: unknown;

package/src/lib/codingAgentEndpoints.ts

@@ -0,0 +1,54 @@
+import { appendBasePathToOrigin } from "./basePath";
+import type { BrowserRuntimeDeployment } from "./browserRuntimeContract";
+import {
+  AGENT_INSPECTOR_RUNTIME_DISCOVERED_EVENT,
+  buildAgentRuntimeUrl,
+  resolveVerifiedBrowserRuntimeForDocument,
+} from "./browserRuntimeResolver";
+
+export type CodingAgentEndpoints = {
+  proxy: string;
+  openAiV1: string;
+  mcp: string;
+};
+
+/** Derive the public protocol endpoints shown to coding agents from one Inspector origin. */
+export function deriveCodingAgentEndpoints(origin: string, basePath: string): CodingAgentEndpoints {
+  return {
+    proxy: appendBasePathToOrigin(origin, "/proxy", basePath),
+    openAiV1: appendBasePathToOrigin(origin, "/proxy/v1", basePath),
+    mcp: appendBasePathToOrigin(origin, "/api/mcp", basePath),
+  };
+}
+
+/** Derive copyable Coding Agent endpoints exclusively from the agent-facing runtime surface. */
+export function deriveCodingAgentEndpointsFromRuntime(
+  runtime: BrowserRuntimeDeployment,
+): CodingAgentEndpoints | null {
+  const proxy = buildAgentRuntimeUrl(runtime, "/proxy");
+  const openAiV1 = buildAgentRuntimeUrl(runtime, "/proxy/v1");
+  const mcp = buildAgentRuntimeUrl(runtime, "/api/mcp");
+  if (proxy === null || openAiV1 === null || mcp === null) return null;
+  return { proxy, openAiV1, mcp };
+}
+
+export function resolveCodingAgentEndpointsForDocument(): CodingAgentEndpoints | null {
+  const runtime = resolveVerifiedBrowserRuntimeForDocument();
+  if (!runtime.ok) return null;
+  return deriveCodingAgentEndpointsFromRuntime(runtime.runtime);
+}
+
+export function subscribeCodingAgentEndpoints(
+  listener: (endpoints: CodingAgentEndpoints | null) => void,
+): () => void {
+  const update = (): void => listener(resolveCodingAgentEndpointsForDocument());
+  update();
+  if (
+    typeof globalThis.addEventListener !== "function" ||
+    typeof globalThis.removeEventListener !== "function"
+  ) {
+    return () => undefined;
+  }
+  globalThis.addEventListener(AGENT_INSPECTOR_RUNTIME_DISCOVERED_EVENT, update);
+  return () => globalThis.removeEventListener(AGENT_INSPECTOR_RUNTIME_DISCOVERED_EVENT, update);
+}