@bitkyc08/opencodex 2.65.0 → 2.66.0

package/src/server/hub-usage.ts

@@ -3,7 +3,7 @@ import { MAX_HUB_USAGE_BYTES, parseHubUsage } from "../remote/hub-usage";
 import { parseRange, parseUsageSurface, USAGE_RANGES, USAGE_SURFACES } from "../usage/summary";
 import { parseUsageTimeWindow } from "../usage/time-range";
 import { getFilteredUsageAggregate } from "./management/usage-aggregate-cache";
-import { isAllowedRequestOrigin, resolveDataPlaneAdmissionSecret, withCors, type RequestPolicyView } from "./auth-cors";
+import { isAllowedRequestOrigin, resolveDataPlaneAdmissionSecret, withCors, type DataPlaneAdmissionOptions, type RequestPolicyView } from "./auth-cors";
 
 /** Read only the ledger rows belonging to an explicitly authenticated configured key. */
 export async function handleHubUsage(req: Request, config: OcxConfig, policy: RequestPolicyView): Promise<Response> {
@@ -12,7 +12,8 @@ export async function handleHubUsage(req: Request, config: OcxConfig, policy: Re
   }), req, policy);
   const error = (code: string, message: string, status: number) => reply({ error: { code, message } }, status);
   const token = req.headers.get("x-opencodex-api-key") ?? "";
-  const admission = resolveDataPlaneAdmissionSecret(token, config);
+  const options: DataPlaneAdmissionOptions = { linkIngress: policy.linkIngress?.allowedKeyIds };
+  const admission = resolveDataPlaneAdmissionSecret(token, config, "dedicated", options);
   if (admission?.kind !== "configured") return error("hub_usage_unauthorized", "A configured client data key is required", 401);
   if (!isAllowedRequestOrigin(req, policy)) return error("origin_rejected", "Cross-origin request blocked", 403);
   if (config.runtimeRole !== "hub") return error("hub_usage_not_a_hub", "Usage is served here only by a hub", 404);
@@ -38,7 +39,7 @@ export async function handleHubUsage(req: Request, config: OcxConfig, policy: Re
     const aggregate = await getFilteredUsageAggregate({
       apiKeyId: keyId, provider: query.get("provider"), model: query.get("model"),
     }, window);
-    const current = resolveDataPlaneAdmissionSecret(token, config);
+    const current = resolveDataPlaneAdmissionSecret(token, config, "dedicated", options);
     if (current?.kind !== "configured" || current.keyId !== keyId) {
       return error("hub_usage_unauthorized", "The client key changed during the read", 401);
     }

package/src/server/index/link-listener.ts

@@ -0,0 +1,195 @@
+import type { Server } from "bun";
+import {
+  emptyLinkStore,
+  readLinkStore,
+  type LinkStore,
+  writeLinkStore,
+} from "../../link/store";
+import { linkStorePath } from "../../link/paths";
+import { linkRouteAllowed } from "../../link/routes";
+
+export const LINK_INGRESS_HOSTNAME = "opencodex-link.invalid";
+
+export interface LinkListenerStartContext<T> {
+  dispatch: (req: Request, server: Server<T>) => Promise<Response>;
+  maxRequestBodySize: number;
+}
+
+export interface LinkListenerDeps {
+  storePath?: string;
+  readStore?: (path: string) => LinkStore;
+  writeStore?: (path: string, store: LinkStore) => void;
+  serve?: (options: Parameters<typeof Bun.serve>[0]) => Server<unknown>;
+  warn?: (message: string) => void;
+}
+
+export type LinkListenerStatus = {
+  state: "off" | "listening" | "failed";
+  port: number | null;
+  reason: string | null;
+};
+
+export interface LinkListenerLifecycle<T> {
+  ownsListener(server: Server<T>): boolean;
+  start(ctx: LinkListenerStartContext<T>): void;
+  ensureStarted(): Promise<void>;
+  linkAdmissionKeyIds(): ReadonlySet<string>;
+  onAuthenticatedCatalog(listener: (apiKeyId: string) => void): () => void;
+  notifyAuthenticatedCatalog(apiKeyId: string): void;
+  status(): LinkListenerStatus;
+  close(): Promise<void>;
+  stop(): Promise<void>;
+}
+
+export { linkRouteAllowed } from "../../link/routes";
+
+function closeWithoutAwait<T>(server: Server<T>): void {
+  try { void server.stop(true).catch(() => {}); } catch { /* preserve the bind failure */ }
+}
+
+export function createLinkListenerLifecycle<T>(deps: LinkListenerDeps = {}): LinkListenerLifecycle<T> {
+  const storePath = deps.storePath ?? linkStorePath();
+  const readStore = deps.readStore ?? readLinkStore;
+  const writeStore = deps.writeStore ?? writeLinkStore;
+  const serve = deps.serve ?? (options => Bun.serve(options));
+  const warn = deps.warn ?? ((message: string) => console.warn(message));
+  let listener: Server<T> | null = null;
+  let startContext: LinkListenerStartContext<T> | undefined;
+  let ensureFlight: Promise<void> | undefined;
+  let closeFlight: Promise<void> | undefined;
+  let stopped = false;
+  const authenticatedCatalogListeners = new Set<(apiKeyId: string) => void>();
+  let lifecycleStatus: LinkListenerStatus = { state: "off", port: null, reason: null };
+
+  const setStatus = (state: LinkListenerStatus["state"], port: number | null, reason: string | null): void => {
+    lifecycleStatus = { state, port, reason };
+  };
+
+  const reportFailure = (operation: string, error: unknown, reason: string): void => {
+    setStatus("failed", null, reason);
+    warn(`⚠ hub-link listener ${operation} failed: ${error instanceof Error ? error.message : String(error)}`);
+  };
+
+  const readStoreForAdmission = (): LinkStore => {
+    try { return readStore(storePath); } catch { return emptyLinkStore(); }
+  };
+
+  const bindIfNeeded = (): void => {
+    if (stopped || listener || !startContext) return;
+    let store: LinkStore;
+    try {
+      store = readStore(storePath);
+    } catch (error) {
+      reportFailure("store read", error, "bind");
+      return;
+    }
+    if (store.links.length === 0) {
+      setStatus("off", null, null);
+      return;
+    }
+    const requestedPort = store.listenerPort ?? 0;
+    let bound: Server<unknown>;
+    try {
+      bound = serve({
+        hostname: "127.0.0.1",
+        port: requestedPort,
+        maxRequestBodySize: startContext.maxRequestBodySize,
+        fetch: (req: Request, server: Server<unknown>) => startContext!.dispatch(req, server as Server<T>),
+      } as Parameters<typeof Bun.serve>[0]);
+    } catch (error) {
+      reportFailure("bind", error, "bind");
+      return;
+    }
+    if (stopped) {
+      closeWithoutAwait(bound);
+      return;
+    }
+    if (store.listenerPort === null) {
+      const port = bound.port;
+      if (!port || port === 0) {
+        closeWithoutAwait(bound);
+        reportFailure("bind", new Error("Bun did not report a concrete listener port"), "bind");
+        return;
+      }
+      try {
+        const current = readStore(storePath);
+        if (current.listenerPort !== null && current.listenerPort !== port) {
+          // Another writer fixed a different port while this bind ran. Tunnels target the stored
+          // port, so serving on this one would strand them: give it up and let the next
+          // ensureStarted() bind the stored port.
+          closeWithoutAwait(bound);
+          reportFailure("listenerPort persistence", new Error(`stored port ${current.listenerPort} differs from bound port ${port}`), "persist");
+          return;
+        }
+        writeStore(storePath, { ...current, listenerPort: port });
+      } catch (error) {
+        closeWithoutAwait(bound);
+        reportFailure("listenerPort persistence", error, "persist");
+        return;
+      }
+    }
+    listener = bound as Server<T>;
+    setStatus("listening", bound.port ?? (requestedPort > 0 ? requestedPort : null), null);
+  };
+
+  const ensureStarted = (): Promise<void> => {
+    if (stopped) return Promise.resolve();
+    if (ensureFlight) return ensureFlight;
+    const flight = (async () => {
+      if (closeFlight) await closeFlight;
+      if (stopped) return;
+      bindIfNeeded();
+    })();
+    ensureFlight = flight.finally(() => {
+      if (ensureFlight === sharedFlight) ensureFlight = undefined;
+    });
+    const sharedFlight = ensureFlight;
+    return sharedFlight;
+  };
+
+  const close = (): Promise<void> => {
+    if (closeFlight) return closeFlight;
+    const flight = (async () => {
+      if (ensureFlight) await ensureFlight;
+      const current = listener;
+      listener = null;
+      if (current) await current.stop(true);
+      // Closing is the caller saying "no links now": an earlier bind or persist failure no
+      // longer describes anything, so the status reads off either way.
+      setStatus("off", null, null);
+    })();
+    closeFlight = flight.finally(() => {
+      closeFlight = undefined;
+    });
+    return closeFlight;
+  };
+
+  return {
+    ownsListener: server => listener !== null && listener === server,
+    start(ctx) {
+      startContext = ctx;
+      bindIfNeeded();
+    },
+    ensureStarted,
+    linkAdmissionKeyIds() {
+      return new Set(readStoreForAdmission().links.map(link => link.apiKeyId));
+    },
+    onAuthenticatedCatalog(listener) {
+      authenticatedCatalogListeners.add(listener);
+      return () => { authenticatedCatalogListeners.delete(listener); };
+    },
+    notifyAuthenticatedCatalog(apiKeyId) {
+      for (const listener of authenticatedCatalogListeners) listener(apiKeyId);
+    },
+    status() {
+      return { ...lifecycleStatus };
+    },
+    close,
+    async stop() {
+      stopped = true;
+      await close();
+      startContext = undefined;
+      setStatus("off", null, null);
+    },
+  };
+}

package/src/server/index/optional-listeners.ts

@@ -0,0 +1,115 @@
+import type { Server } from "bun";
+import type { OcxConfig } from "../../types";
+import {
+  createClaudeInterceptLifecycle,
+  type ClaudeInterceptLifecycle,
+} from "./claude-intercept-lifecycle";
+import {
+  createLinkListenerLifecycle,
+  linkRouteAllowed,
+  type LinkListenerDeps,
+  type LinkListenerLifecycle,
+  type LinkListenerStatus,
+} from "./link-listener";
+import { createLinkSupervisor, type LinkSupervisor } from "../../link/supervisor";
+import { saveConfigPreservingClaudeCode } from "../../config/live-reconcile";
+import { reconcileLiveStateStores } from "../../lib/state-store-registrations";
+export { LINK_INGRESS_HOSTNAME } from "./link-listener";
+import type { ServerIngress } from "./serve-options";
+
+export interface OptionalListenerStartContext<T> {
+  config: OcxConfig;
+  publicPort: number;
+  requestedPort?: number;
+  maxRequestBodySize: number;
+  dispatch: (req: Request, server: Server<T>) => Promise<Response>;
+}
+
+export interface OptionalListenerSet<T> {
+  ingressOf(server: Server<T>): ServerIngress | undefined;
+  linkRouteAllowed(url: URL, req: Request): boolean;
+  linkAdmissionKeyIds(): ReadonlySet<string>;
+  onAuthenticatedCatalog(listener: (apiKeyId: string) => void): () => void;
+  notifyAuthenticatedCatalog(apiKeyId: string): void;
+  status(): LinkListenerStatus;
+  linkStatus(): LinkListenerStatus;
+  linkSupervisor(): LinkSupervisor;
+  start(ctx: OptionalListenerStartContext<T>): void;
+  ensureStarted(): Promise<void>;
+  close(): Promise<void>;
+  registerSupervisorStop(stop: () => Promise<void>): () => void;
+  stop(): Promise<void>;
+}
+
+export function createOptionalListenerSet<T>(linkDeps: LinkListenerDeps = {}): OptionalListenerSet<T> {
+  const claudeIntercept: ClaudeInterceptLifecycle<T> = createClaudeInterceptLifecycle<T>();
+  const linkListener: LinkListenerLifecycle<T> = createLinkListenerLifecycle<T>(linkDeps);
+  let activeConfig: OcxConfig | undefined;
+  const supervisor = createLinkSupervisor({
+    apiKeys: () => activeConfig?.apiKeys ?? [],
+    revokeApiKey: id => {
+      if (!activeConfig) return false;
+      const before = activeConfig.apiKeys ?? [];
+      if (!before.some(key => key.id === id)) return false;
+      activeConfig.apiKeys = before.filter(key => key.id !== id);
+      try {
+        saveConfigPreservingClaudeCode(activeConfig);
+        reconcileLiveStateStores();
+      } catch (error) {
+        activeConfig.apiKeys = before;
+        throw error;
+      }
+      return true;
+    },
+  });
+  let unregisterSupervisorAdmission: (() => void) | undefined;
+  let supervisorStop: (() => Promise<void>) | undefined;
+
+  return {
+    ingressOf(server) {
+      if (linkListener.ownsListener(server)) return "hub-link";
+      if (claudeIntercept.ownsListener(server)) return "claude-intercept";
+      return undefined;
+    },
+    linkRouteAllowed,
+    linkAdmissionKeyIds: () => linkListener.linkAdmissionKeyIds(),
+    onAuthenticatedCatalog: listener => linkListener.onAuthenticatedCatalog(listener),
+    notifyAuthenticatedCatalog: apiKeyId => linkListener.notifyAuthenticatedCatalog(apiKeyId),
+    status: () => linkListener.status(),
+    linkStatus: () => linkListener.status(),
+    linkSupervisor: () => supervisor,
+    start(ctx) {
+      activeConfig = ctx.config;
+      linkListener.start({ dispatch: ctx.dispatch, maxRequestBodySize: ctx.maxRequestBodySize });
+      unregisterSupervisorAdmission ??= linkListener.onAuthenticatedCatalog(apiKeyId => supervisor.notifyAuthenticatedRequest?.(apiKeyId));
+      supervisor.start();
+      supervisorStop = () => supervisor.stop();
+      claudeIntercept.start({
+        config: ctx.config,
+        publicPort: ctx.publicPort,
+        requestedPort: ctx.requestedPort,
+        maxRequestBodySize: ctx.maxRequestBodySize,
+        dispatch: ctx.dispatch,
+      });
+    },
+    ensureStarted: () => linkListener.ensureStarted(),
+    close: () => linkListener.close(),
+    registerSupervisorStop(stop) {
+      supervisorStop = stop;
+      return () => {
+        if (supervisorStop === stop) supervisorStop = undefined;
+      };
+    },
+    async stop() {
+      let failure: unknown;
+      if (supervisorStop) {
+        try { await supervisorStop(); } catch (error) { failure = error; }
+      }
+      try { await linkListener.stop(); } catch (error) { failure ??= error; }
+      try { await claudeIntercept.stop(); } catch (error) { failure ??= error; }
+      unregisterSupervisorAdmission?.();
+      unregisterSupervisorAdmission = undefined;
+      if (failure) throw failure;
+    },
+  };
+}

package/src/server/index/serve-options.ts

@@ -93,6 +93,7 @@ import {
   isAllowedRequestOrigin,
   isAllowedManagementOrigin,
   isApiAuthRequired,
+  isLoopbackHostname,
   jsonResponse,
   admissionFields,
   resolveApiAuth,
@@ -101,6 +102,7 @@ import {
   withCors,
   withManagementCors,
 } from "../auth-cors";
+import { managementSessionIssuance } from "../management-auth";
 import { resolveAdmissionModelScope, routeAllowedByScope } from "../admission-model-scope";
 import {
   disableResponsesRequestTimeout,
@@ -199,7 +201,12 @@ import { readyProtocolMetadata } from "../../remote/protocol";
 import { modelCapabilityFields } from "../models-capabilities";
 import { createWebsocketHandler } from "./websocket-handler";
 
-export type ServerIngress = "public" | "unauthenticated-loopback" | "hub-management" | "claude-intercept";
+export type ServerIngress = "public" | "unauthenticated-loopback" | "hub-management" | "claude-intercept" | "hub-link";
+
+export function trustedLoopbackForIngress(ingress: ServerIngress, hostname: string): boolean {
+  return ingress === "unauthenticated-loopback"
+    || (ingress === "public" && isLoopbackHostname(hostname));
+}
 
 /**
  * Routes the Claude intercept TLS listener may reach. Everything else on that socket is relayed
@@ -219,6 +226,9 @@ export interface ServeOptionsContext {
   ingressForServer: (requestServer: Server<WsData>) => ServerIngress;
   loopbackRouteAllowed: (url: URL, req: Request) => boolean;
   managementIngressRouteAllowed: (url: URL, req: Request) => boolean;
+  linkRouteAllowed: (url: URL, req: Request) => boolean;
+  onAuthenticatedCatalog: (apiKeyId: string) => void;
+  linkPolicy: () => RequestPolicyView;
   packageTreeChangedResponse: (
     req: Request,
     policy: RequestPolicyView,
@@ -261,6 +271,8 @@ export function createServeOptions(ctx: ServeOptionsContext) {
     ingressForServer,
     loopbackRouteAllowed,
     managementIngressRouteAllowed,
+    linkRouteAllowed, onAuthenticatedCatalog,
+    linkPolicy,
     packageTreeChangedResponse,
     serverBusyResponse,
     runAdmittedHttpTurn,
@@ -293,6 +305,8 @@ export function createServeOptions(ctx: ServeOptionsContext) {
       maxRequestBodySize: inboundBodyLimitBytes,
       async fetch(req: Request, requestServer: Server<WsData>): Promise<Response> {
       const ingress = ingressForServer(requestServer);
+      const requestUrl = codexCompatibleUrl(req.url);
+      const linkPolicyView = ingress === "hub-link" ? linkPolicy() : undefined;
       // The unauthenticated loopback listener (#1102) serves a fixed allowlist and nothing
       // else. Rejecting here, before any handler runs, is what keeps the surface from growing
       // silently when a route is added below.
@@ -303,6 +317,13 @@ export function createServeOptions(ctx: ServeOptionsContext) {
           loopbackPolicy(),
         );
       }
+      if (ingress === "hub-link" && !linkRouteAllowed(requestUrl, req)) {
+        return withCors(
+          formatErrorResponse(404, "not_found", `Unknown endpoint: ${req.method} ${new URL(req.url).pathname}`),
+          req,
+          linkPolicyView!,
+        );
+      }
       // Tailscale Serve terminates only on this separately bound loopback socket. Reject before
       // dispatch so no data, readiness, health, WebSocket, or unknown-static handler can run.
       if (ingress === "hub-management" && !managementIngressRouteAllowed(codexCompatibleUrl(req.url), req)) {
@@ -327,10 +348,20 @@ export function createServeOptions(ctx: ServeOptionsContext) {
       // The Claude intercept listener is loopback by construction (the CONNECT proxy binds
       // 127.0.0.1 and the request was rewritten onto a loopback origin), and its callers carry
       // Anthropic credentials, not opencodex admission tokens — so it takes the loopback view too.
-      const policy: RequestPolicyView = ingress === "unauthenticated-loopback" || ingress === "claude-intercept"
-        ? loopbackPolicy()
-        : config;
-      const url = codexCompatibleUrl(req.url);
+      const policy: RequestPolicyView = ingress === "hub-link"
+        ? linkPolicyView!
+        : ingress === "unauthenticated-loopback" || ingress === "claude-intercept"
+          ? loopbackPolicy()
+          : config;
+      if (ingress === "hub-link") {
+        const admission = resolveApiAuth(req, policy);
+        if (!admission) return withCors(formatErrorResponse(401, "authentication_error", "opencodex API key required"), req, policy);
+        if (requestUrl.pathname === "/v1/catalog" && requestUrl.search === ""
+          && (req.method === "GET" || req.method === "HEAD")
+          && admission.kind === "configured") onAuthenticatedCatalog(admission.keyId);
+      }
+      const url = requestUrl;
+      const admissionOptions = { linkIngress: policy.linkIngress?.allowedKeyIds };
       markActivity(`${req.method} ${url.pathname}`);
 
       // Readiness is exact-GET on the literal /readyz path. Compare the DECODED
@@ -660,7 +691,10 @@ export function createServeOptions(ctx: ServeOptionsContext) {
             }), req, config);
           }
         }
-        const mgmtResponse = await handleManagementAPI(req, url, config, requestManagementApiDeps, principal, managementSessionControl);
+        const mgmtResponse = await handleManagementAPI(req, url, config, requestManagementApiDeps, principal, managementSessionControl, {
+          trustedLoopback: trustedLoopbackForIngress(ingress, config.hostname ?? "127.0.0.1"),
+          guiSessionIssuance: managementSessionIssuance(req, managementAuth),
+        });
         if (mgmtResponse) return withManagementCors(mgmtResponse, req, config);
         return withManagementCors(formatErrorResponse(404, "not_found", `Unknown endpoint: ${req.method} ${url.pathname}`), req, config);
       }
@@ -1545,7 +1579,7 @@ export function createServeOptions(ctx: ServeOptionsContext) {
       if (url.pathname === "/v1/audio/transcriptions" && req.method === "POST") {
         disableResponsesRequestTimeout(req, requestServer);
         if (isDraining()) return drainingResponse(req, policy);
-        const admission = resolveAudioAdmission(req.headers, config);
+        const admission = resolveAudioAdmission(req.headers, config, admissionOptions);
         if (!admission) return withCors(formatErrorResponse(401, "authentication_error", "opencodex API key required"), req, policy);
         if (!isAllowedRequestOrigin(req, policy)) {
           return withCors(formatErrorResponse(403, "origin_rejected", "cross-origin audio request blocked"), req, policy);
@@ -1576,7 +1610,7 @@ export function createServeOptions(ctx: ServeOptionsContext) {
         if (isDraining()) {
           return drainingResponse(req, policy);
         }
-        const audioClient = resolveAudioClient(req, config);
+        const audioClient = resolveAudioClient(req, config, false, admissionOptions);
         if (audioClient instanceof Response) return withCors(audioClient, req, policy);
         const admission = audioClient?.admission ?? resolveApiAuth(req, policy);
         if (!admission) return withCors(formatErrorResponse(401, "authentication_error", "opencodex API key required"), req, policy);
@@ -1620,7 +1654,7 @@ export function createServeOptions(ctx: ServeOptionsContext) {
         if (isDraining()) {
           return drainingResponse(req, policy);
         }
-        const audioClient = resolveAudioClient(req, config, dictationSocket);
+        const audioClient = resolveAudioClient(req, config, dictationSocket, admissionOptions);
         if (audioClient instanceof Response) return withCors(audioClient, req, policy);
         if (!audioClient && liveSidebandTarget && "callId" in liveSidebandTarget
           && liveSidebandTarget.callId.startsWith(EXTERNAL_CALL_PREFIX)) {
@@ -1868,7 +1902,7 @@ export function createServeOptions(ctx: ServeOptionsContext) {
         undefined,
         guiSessionCandidate ?? undefined,
         config.runtimeRole ?? "standalone",
-        isApiAuthRequired(config),
+        isApiAuthRequired(policy),
       );
       if (guiFile) return guiFile;
       if (url.pathname === "/" && req.method === "GET") {

package/src/server/index.ts

@@ -196,7 +196,7 @@ import {
 } from "../lib/local-management-attestation";
 import { createReadinessGate, type ReadinessGate } from "./readiness";
 import { createServeOptions, type ServerIngress } from "./index/serve-options";
-import { createClaudeInterceptLifecycle } from "./index/claude-intercept-lifecycle";
+import { createOptionalListenerSet, LINK_INGRESS_HOSTNAME } from "./index/optional-listeners";
 import { createPackageTreeIntegrityGuardForServer } from "./index/package-tree-guard";
 import { inspectStartupOwnership, resolveInboundBodyLimitWithWarning, setStartupCacheInvalidationWrite, warnAgentTaskRecoveryStartup, warnPlaintextV2AgentMessagesStartup, type StartServerDeps } from "./index/startup-warnings";
 import { acquireSpendLedgerServerLifecycle, recordFailedStartRollback, type SpendLedgerServerLifecycle } from "./index/spend-ledger-lifecycle";
@@ -623,15 +623,17 @@ function startServerWithSpendLedgerOwner(port: number | undefined, deps: StartSe
   let server: Server<WsData>;
   let loopbackServer: Server<WsData> | null = null;
   let managementIngressServer: Server<WsData> | null = null;
-  const claudeIntercept = createClaudeInterceptLifecycle<WsData>();
+  const optionalListeners = createOptionalListenerSet<WsData>();
   const inboundBodyLimitBytes = resolveInboundBodyLimitWithWarning(config);
 
   function ingressForServer(requestServer: Server<WsData>): ServerIngress {
+    const optionalIngress = optionalListeners.ingressOf(requestServer);
+    if (optionalIngress !== undefined) return optionalIngress;
     if (requestServer === loopbackServer) return "unauthenticated-loopback";
     if (requestServer === managementIngressServer) return "hub-management";
-    if (claudeIntercept.ownsListener(requestServer)) return "claude-intercept";
     return "public";
   }
+  const linkPolicy = (): RequestPolicyView => requestPolicyView(config, LINK_INGRESS_HOSTNAME, { allowedKeyIds: optionalListeners.linkAdmissionKeyIds() });
   let backgroundLifecycle: ReturnType<typeof acquireServerBackgroundLifecycle> | null = null;
   let unregisterQuotaAutoRefresh: (() => void) | null = null;
   let remoteWorkspaceStopping = false;
@@ -639,7 +641,7 @@ function startServerWithSpendLedgerOwner(port: number | undefined, deps: StartSe
   const managementApiDeps: ManagementApiDeps = {
     ...deps.managementApi,
     remoteWorkspaceStopping: () => remoteWorkspaceStopping,
-    onRemoteWorkspaceShutdown: shutdown => { remoteWorkspaceShutdown = shutdown; },
+    onRemoteWorkspaceShutdown: shutdown => { remoteWorkspaceShutdown = shutdown; }, linkSupervisor: () => optionalListeners.linkSupervisor(), linkListener: () => optionalListeners,
   };
   let workspaceRuntimeFlight: Promise<typeof import("../remote-control/workspace-runtime")> | undefined;
   const loadRemoteWorkspaceRuntime = () => {
@@ -666,6 +668,7 @@ function startServerWithSpendLedgerOwner(port: number | undefined, deps: StartSe
       ingressForServer,
       loopbackRouteAllowed,
       managementIngressRouteAllowed,
+      linkRouteAllowed: optionalListeners.linkRouteAllowed, linkPolicy, onAuthenticatedCatalog: optionalListeners.notifyAuthenticatedCatalog,
       packageTreeChangedResponse,
       serverBusyResponse,
       runAdmittedHttpTurn,
@@ -731,10 +734,8 @@ function startServerWithSpendLedgerOwner(port: number | undefined, deps: StartSe
         throw new AuxiliaryListenerBindError("hub.managementIngress", managementIngressPort, "127.0.0.1", error);
       }
     }
-    claudeIntercept.start({
-      config, publicPort: server.port ?? listenPort, requestedPort: listenPort, maxRequestBodySize: inboundBodyLimitBytes,
-      dispatch: (req, requestServer) => serveOptions.fetch(req, requestServer),
-    });
+    optionalListeners.start({ config, publicPort: server.port ?? listenPort, requestedPort: listenPort,
+      maxRequestBodySize: inboundBodyLimitBytes, dispatch: (req, requestServer) => serveOptions.fetch(req, requestServer) });
   } catch (error) {
     unregisterQuotaAutoRefresh?.();
     userCostOverlayReconciler?.stop();
@@ -772,7 +773,7 @@ function startServerWithSpendLedgerOwner(port: number | undefined, deps: StartSe
           ...(managementIngressRef
             ? [() => managementIngressRef.stop(closeActiveConnections)]
             : []),
-          () => claudeIntercept.stop(),
+          () => optionalListeners.stop(),
           async () => { await remoteWorkspaceShutdown?.(); },
           async () => {
             try {

package/src/server/inference/attempt.ts

@@ -0,0 +1,51 @@
+import type { OcxUsage } from "../../types";
+import type { PersistedUsageAttempt } from "../../usage/log";
+import {
+  beginRequestAttempt,
+  finishRequestAttempt,
+  sealRequestAttemptIdentity,
+  type RequestLogContext,
+} from "../request-log";
+
+export interface InferenceAttemptTarget {
+  provider: string;
+  model: string;
+  adapter: string;
+}
+
+export interface InferenceAttempt {
+  readonly attempt: PersistedUsageAttempt;
+  /** Epoch ms the attempt became active; the duration `finish` records is measured from it. */
+  readonly startedAt: number;
+  /** Stamp the attempt's provider/adapter identity and, before its first send, its account. */
+  seal(accountLabel?: string): void;
+  /** Close the attempt row with its status and duration; `usage` overrides the attempt's own. */
+  finish(status: number, usage?: OcxUsage): PersistedUsageAttempt;
+}
+
+/**
+ * Open one physical attempt on `logCtx`: the next ordinal, the active attempt and its start
+ * time, and the attempt appended to the request's list, in that order. The attempt is the row
+ * the final request log finishes; `finish` exists for owners that close it themselves.
+ */
+export function beginInferenceAttempt(
+  logCtx: RequestLogContext,
+  target: InferenceAttemptTarget,
+): InferenceAttempt {
+  const attempt = beginRequestAttempt(
+    (logCtx.attempts?.length ?? 0) + 1,
+    target.provider,
+    target.model,
+    target.adapter,
+  );
+  logCtx.activeAttempt = attempt;
+  const startedAt = Date.now();
+  logCtx.activeAttemptStartedAt = startedAt;
+  (logCtx.attempts ??= []).push(attempt);
+  return {
+    attempt,
+    startedAt,
+    seal: accountLabel => sealRequestAttemptIdentity(attempt, target.provider, target.adapter, accountLabel),
+    finish: (status, usage) => finishRequestAttempt(attempt, status, Date.now() - startedAt, usage),
+  };
+}