@tonyclaw/agent-inspector 3.0.45 → 3.0.47

package/src/cli/rustBackendPackage.ts

@@ -0,0 +1,450 @@
+import { spawnSync } from "node:child_process";
+import { Buffer } from "node:buffer";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+
+export const RUST_BACKEND_IDENTITY_FLAG = "--agent-inspector-package-identity";
+export const RUST_BACKEND_CLI_PROTOCOL = "agent-inspector-cli-backend-v1";
+export const RUST_BACKEND_IDENTITY_TIMEOUT_MS = 2_000;
+
+export type RustBackendLibc = "glibc" | "musl" | "unknown" | "not-applicable";
+
+export type RustBackendTarget = {
+  packageName: string;
+  target: string;
+  binary: string;
+  os: "win32" | "linux" | "darwin";
+  cpu: "x64" | "arm64";
+  libc: "glibc" | null;
+};
+
+export type RustBackendPackageErrorCode =
+  | "binary_invalid"
+  | "binary_missing"
+  | "hash_mismatch"
+  | "identity_failed"
+  | "identity_mismatch"
+  | "manifest_invalid"
+  | "package_invalid"
+  | "package_missing"
+  | "target_mismatch"
+  | "unsupported_platform"
+  | "version_mismatch";
+
+export type RustBackendPackageError = {
+  code: RustBackendPackageErrorCode;
+  message: string;
+};
+
+export type RustBackendPackageResolution =
+  | {
+      kind: "success";
+      value: {
+        command: string;
+        args: readonly string[];
+        packageName: string;
+        packageVersion: string;
+        target: string;
+        sha256: string;
+      };
+    }
+  | { kind: "error"; error: RustBackendPackageError };
+
+export type RustBackendTargetResolution =
+  | { kind: "success"; value: RustBackendTarget }
+  | { kind: "error"; error: RustBackendPackageError };
+
+const RustBackendIdentitySchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    name: z.literal("agent-inspector-backend"),
+    packageVersion: z.string().min(1),
+    target: z.string().min(1),
+    binary: z.string().min(1),
+    cliProtocol: z.literal(RUST_BACKEND_CLI_PROTOCOL),
+    productionReady: z.literal(true),
+    capabilities: z
+      .object({
+        nodeProtectedIngress: z.literal(true),
+        basePath: z.literal(true),
+        namedInstances: z.literal(true),
+        gracefulShutdown: z.literal(true),
+      })
+      .strict(),
+  })
+  .strict();
+
+export type RustBackendIdentity = z.infer<typeof RustBackendIdentitySchema>;
+
+const RustBackendPackageJsonSchema = z
+  .object({
+    name: z.string().min(1),
+    version: z.string().min(1),
+    os: z.array(z.string()).min(1),
+    cpu: z.array(z.string()).min(1),
+    libc: z.array(z.string()).optional(),
+    agentInspectorRustBackend: z
+      .object({
+        schemaVersion: z.literal(1),
+        target: z.string().min(1),
+        binary: z.string().min(1),
+        manifest: z.string().min(1),
+        identityFlag: z.literal(RUST_BACKEND_IDENTITY_FLAG),
+        cliProtocol: z.literal(RUST_BACKEND_CLI_PROTOCOL),
+      })
+      .strict(),
+  })
+  .passthrough();
+
+const RustBackendBinaryManifestSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    packageName: z.string().min(1),
+    packageVersion: z.string().min(1),
+    target: z.string().min(1),
+    binary: z.string().min(1),
+    sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+    identity: RustBackendIdentitySchema,
+  })
+  .strict();
+
+type IdentityProbeResult =
+  | { kind: "success"; value: RustBackendIdentity }
+  | { kind: "error"; message: string };
+
+export type ResolveRustBackendPackageOptions = {
+  rootVersion: string;
+  platform?: string;
+  arch?: string;
+  libc?: RustBackendLibc;
+  resolvePackageJson?: (specifier: string) => string;
+  identityProbe?: (binaryPath: string, identityFlag: string) => IdentityProbeResult;
+};
+
+function packageFailure(
+  code: RustBackendPackageErrorCode,
+  message: string,
+): RustBackendPackageResolution {
+  return { kind: "error", error: { code, message } };
+}
+
+function targetFailure(message: string): RustBackendTargetResolution {
+  return { kind: "error", error: { code: "unsupported_platform", message } };
+}
+
+function detectLinuxLibc(): RustBackendLibc {
+  if (process.platform !== "linux") return "not-applicable";
+  const report = process.report.getReport();
+  const header = objectProperty(report, "header");
+  const glibcVersion = objectProperty(header, "glibcVersionRuntime");
+  if (typeof glibcVersion === "string" && glibcVersion.length > 0) {
+    return "glibc";
+  }
+  const sharedObjects = objectProperty(report, "sharedObjects");
+  return Array.isArray(sharedObjects) &&
+    sharedObjects.some((path) => typeof path === "string" && path.toLowerCase().includes("musl"))
+    ? "musl"
+    : "unknown";
+}
+
+function objectProperty(value: unknown, name: string): unknown {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+  return Object.getOwnPropertyDescriptor(value, name)?.value;
+}
+
+export function resolveRustBackendTarget(
+  platform: string = process.platform,
+  arch: string = process.arch,
+  libc: RustBackendLibc = platform === "linux" ? detectLinuxLibc() : "not-applicable",
+): RustBackendTargetResolution {
+  switch (platform) {
+    case "win32":
+      return arch === "x64"
+        ? {
+            kind: "success",
+            value: {
+              packageName: "@tonyclaw/agent-inspector-backend-win32-x64-msvc",
+              target: "x86_64-pc-windows-msvc",
+              binary: "bin/agent-inspector-backend.exe",
+              os: "win32",
+              cpu: "x64",
+              libc: null,
+            },
+          }
+        : targetFailure(`Rust backend packages do not support Windows ${arch}.`);
+    case "linux":
+      if (arch !== "x64")
+        return targetFailure(`Rust backend packages do not support Linux ${arch}.`);
+      if (libc !== "glibc") {
+        return targetFailure(
+          `The Linux Rust backend package requires glibc; detected ${libc}. No binary was started.`,
+        );
+      }
+      return {
+        kind: "success",
+        value: {
+          packageName: "@tonyclaw/agent-inspector-backend-linux-x64-gnu",
+          target: "x86_64-unknown-linux-gnu",
+          binary: "bin/agent-inspector-backend",
+          os: "linux",
+          cpu: "x64",
+          libc: "glibc",
+        },
+      };
+    case "darwin":
+      return arch === "arm64"
+        ? {
+            kind: "success",
+            value: {
+              packageName: "@tonyclaw/agent-inspector-backend-darwin-arm64",
+              target: "aarch64-apple-darwin",
+              binary: "bin/agent-inspector-backend",
+              os: "darwin",
+              cpu: "arm64",
+              libc: null,
+            },
+          }
+        : targetFailure(`Rust backend packages do not support macOS ${arch}.`);
+    default:
+      return targetFailure(`Rust backend packages do not support ${platform} ${arch}.`);
+  }
+}
+
+function readJson(path: string): { kind: "success"; value: unknown } | { kind: "error" } {
+  try {
+    const value: unknown = JSON.parse(readFileSync(path, "utf8"));
+    return { kind: "success", value };
+  } catch {
+    return { kind: "error" };
+  }
+}
+
+function isConfinedPath(root: string, candidate: string): boolean {
+  const child = relative(root, candidate);
+  return child.length > 0 && !child.startsWith("..") && !isAbsolute(child);
+}
+
+function identitiesMatch(left: RustBackendIdentity, right: RustBackendIdentity): boolean {
+  return (
+    left.schemaVersion === right.schemaVersion &&
+    left.name === right.name &&
+    left.packageVersion === right.packageVersion &&
+    left.target === right.target &&
+    left.binary === right.binary &&
+    left.cliProtocol === right.cliProtocol &&
+    left.productionReady === right.productionReady &&
+    left.capabilities.nodeProtectedIngress === right.capabilities.nodeProtectedIngress &&
+    left.capabilities.basePath === right.capabilities.basePath &&
+    left.capabilities.namedInstances === right.capabilities.namedInstances &&
+    left.capabilities.gracefulShutdown === right.capabilities.gracefulShutdown
+  );
+}
+
+function probeBinaryIdentity(binaryPath: string, identityFlag: string): IdentityProbeResult {
+  const result = spawnSync(binaryPath, [identityFlag], {
+    encoding: "utf8",
+    windowsHide: true,
+    timeout: RUST_BACKEND_IDENTITY_TIMEOUT_MS,
+    maxBuffer: 64 * 1024,
+  });
+  if (result.error !== undefined) {
+    return { kind: "error", message: result.error.message };
+  }
+  if (result.status !== 0) {
+    return {
+      kind: "error",
+      message: `identity command exited with status ${String(result.status)}`,
+    };
+  }
+  let raw: unknown;
+  try {
+    raw = JSON.parse(result.stdout);
+  } catch {
+    return { kind: "error", message: "identity command did not return JSON" };
+  }
+  const parsed = RustBackendIdentitySchema.safeParse(raw);
+  return parsed.success
+    ? { kind: "success", value: parsed.data }
+    : { kind: "error", message: "identity command returned an unsupported contract" };
+}
+
+const packageRequire = createRequire(import.meta.url);
+
+function defaultResolvePackageJson(specifier: string): string {
+  try {
+    return packageRequire.resolve(specifier);
+  } catch {
+    const suffix = "/package.json";
+    const packageName = specifier.endsWith(suffix) ? specifier.slice(0, -suffix.length) : "";
+    const directoryName = packageName.split("/").at(-1);
+    if (directoryName !== undefined && directoryName.length > 0) {
+      const localPackageJson = resolve(
+        dirname(fileURLToPath(import.meta.url)),
+        "../packages",
+        directoryName,
+        "package.json",
+      );
+      if (existsSync(localPackageJson)) return localPackageJson;
+    }
+    return packageRequire.resolve(specifier);
+  }
+}
+
+export function resolveRustBackendPackage(
+  options: ResolveRustBackendPackageOptions,
+): RustBackendPackageResolution {
+  const target = resolveRustBackendTarget(options.platform, options.arch, options.libc);
+  if (target.kind === "error") return { kind: "error", error: target.error };
+
+  const packageJsonSpecifier = `${target.value.packageName}/package.json`;
+  let packageJsonPath: string;
+  try {
+    packageJsonPath = (options.resolvePackageJson ?? defaultResolvePackageJson)(
+      packageJsonSpecifier,
+    );
+  } catch {
+    return packageFailure(
+      "package_missing",
+      `Rust backend ${target.value.target} was requested, but optional package ${target.value.packageName}@${options.rootVersion} is not installed. Reinstall without omitting optional dependencies; no TypeScript fallback was used.`,
+    );
+  }
+
+  const rawPackage = readJson(packageJsonPath);
+  if (rawPackage.kind === "error") {
+    return packageFailure("package_invalid", `Cannot read ${packageJsonSpecifier}.`);
+  }
+  const packageJson = RustBackendPackageJsonSchema.safeParse(rawPackage.value);
+  if (!packageJson.success) {
+    return packageFailure(
+      "package_invalid",
+      `Package ${target.value.packageName} does not contain the Rust backend package contract.`,
+    );
+  }
+  if (
+    packageJson.data.name !== target.value.packageName ||
+    packageJson.data.version !== options.rootVersion
+  ) {
+    return packageFailure(
+      "version_mismatch",
+      `Rust backend package must exactly match @tonyclaw/agent-inspector@${options.rootVersion}; found ${packageJson.data.name}@${packageJson.data.version}.`,
+    );
+  }
+
+  const metadata = packageJson.data.agentInspectorRustBackend;
+  const expectedLibc = target.value.libc === null ? undefined : [target.value.libc];
+  if (
+    metadata.target !== target.value.target ||
+    metadata.binary !== target.value.binary ||
+    metadata.manifest !== "binary-manifest.json" ||
+    packageJson.data.os.length !== 1 ||
+    packageJson.data.os[0] !== target.value.os ||
+    packageJson.data.cpu.length !== 1 ||
+    packageJson.data.cpu[0] !== target.value.cpu ||
+    JSON.stringify(packageJson.data.libc) !== JSON.stringify(expectedLibc)
+  ) {
+    return packageFailure(
+      "target_mismatch",
+      `Package ${target.value.packageName} does not match target ${target.value.target}.`,
+    );
+  }
+
+  const packageRoot = dirname(packageJsonPath);
+  const manifestPath = resolve(packageRoot, metadata.manifest);
+  const binaryPath = resolve(packageRoot, metadata.binary);
+  if (!isConfinedPath(packageRoot, manifestPath) || !isConfinedPath(packageRoot, binaryPath)) {
+    return packageFailure(
+      "package_invalid",
+      `Package ${target.value.packageName} contains an unsafe artifact path.`,
+    );
+  }
+
+  const rawManifest = readJson(manifestPath);
+  if (rawManifest.kind === "error") {
+    return packageFailure(
+      "manifest_invalid",
+      `Rust backend package ${target.value.packageName} is incomplete: binary-manifest.json is missing or invalid.`,
+    );
+  }
+  const manifest = RustBackendBinaryManifestSchema.safeParse(rawManifest.value);
+  if (!manifest.success) {
+    return packageFailure(
+      "manifest_invalid",
+      `Rust backend package ${target.value.packageName} has an invalid target manifest.`,
+    );
+  }
+  if (
+    manifest.data.packageName !== target.value.packageName ||
+    manifest.data.packageVersion !== options.rootVersion ||
+    manifest.data.identity.packageVersion !== options.rootVersion
+  ) {
+    return packageFailure(
+      "version_mismatch",
+      `Rust backend manifest must exactly match @tonyclaw/agent-inspector@${options.rootVersion}.`,
+    );
+  }
+  if (
+    manifest.data.target !== target.value.target ||
+    manifest.data.binary !== target.value.binary ||
+    manifest.data.identity.target !== target.value.target ||
+    manifest.data.identity.binary !== target.value.binary
+  ) {
+    return packageFailure(
+      "target_mismatch",
+      `Rust backend manifest identity does not match target ${target.value.target}.`,
+    );
+  }
+
+  let binaryBytes: Buffer;
+  try {
+    const stats = statSync(binaryPath);
+    if (!stats.isFile()) {
+      return packageFailure("binary_invalid", `Rust backend artifact is not a regular file.`);
+    }
+    if (target.value.os !== "win32" && (stats.mode & 0o111) === 0) {
+      return packageFailure("binary_invalid", `Rust backend artifact is not executable.`);
+    }
+    binaryBytes = readFileSync(binaryPath);
+  } catch {
+    return packageFailure(
+      "binary_missing",
+      `Rust backend binary ${target.value.binary} is missing from ${target.value.packageName}.`,
+    );
+  }
+  const sha256 = createHash("sha256").update(binaryBytes).digest("hex");
+  if (sha256 !== manifest.data.sha256) {
+    return packageFailure(
+      "hash_mismatch",
+      `Rust backend binary integrity check failed for ${target.value.packageName}; no binary was started.`,
+    );
+  }
+
+  const probed = (options.identityProbe ?? probeBinaryIdentity)(binaryPath, metadata.identityFlag);
+  if (probed.kind === "error") {
+    return packageFailure(
+      "identity_failed",
+      `Rust backend binary did not pass the production identity gate: ${probed.message}. No TypeScript fallback was used.`,
+    );
+  }
+  if (!identitiesMatch(probed.value, manifest.data.identity)) {
+    return packageFailure(
+      "identity_mismatch",
+      `Rust backend binary identity differs from its signed package manifest; no binary was started.`,
+    );
+  }
+
+  return {
+    kind: "success",
+    value: {
+      command: binaryPath,
+      args: [],
+      packageName: target.value.packageName,
+      packageVersion: options.rootVersion,
+      target: target.value.target,
+      sha256,
+    },
+  };
+}

package/src/cli/templates/codex-skill-onboard.ts

@@ -11,8 +11,14 @@ export type CodexSkillOnboardContext = {
   readonly version: string;
   /** The default proxy port (mirrors `DEFAULT_PORT` in `src/cli.ts`). */
   readonly port: number;
-  /** Public UI base URL, including the configured base path. */
+  /** Public backend control/agent Base URL, including the configured Base Path. */
   readonly baseUrl: string;
+  /** Optional composed or standalone UI URL. Undefined preserves the legacy composed default. */
+  readonly uiUrl?: string | null;
+  /** REST/SSE Base URL. Falls back to baseUrl for compatibility. */
+  readonly controlBaseUrl?: string;
+  /** Proxy/MCP Base URL. Falls back to baseUrl for compatibility. */
+  readonly agentBaseUrl?: string;
   /** MCP config key selected by onboarding. */
   readonly mcpName?: string;
   /** Selected onboarding target type. */
@@ -33,16 +39,20 @@ export const REQUIRED_CODEX_PHASE_HEADINGS = [
 ] as const;
 
 export function renderCodexSkillOnboard(ctx: CodexSkillOnboardContext): string {
-  const { version, baseUrl } = ctx;
+  const { version } = ctx;
+  const controlBaseUrl = ctx.controlBaseUrl ?? ctx.baseUrl;
+  const agentBaseUrl = ctx.agentBaseUrl ?? ctx.baseUrl;
+  const uiUrl = ctx.uiUrl === undefined ? ctx.baseUrl : ctx.uiUrl;
   const mcpName = ctx.mcpName ?? "agent-inspector";
   const targetKind = ctx.targetKind ?? "default";
   const targetArguments = ctx.onboardTargetArguments ?? "";
   const instanceName = ctx.instanceName ?? null;
-  const healthUrl = `${baseUrl}/api/health`;
-  const configUrl = `${baseUrl}/api/config`;
-  const anthropicProxyUrl = `${baseUrl}/proxy`;
-  const openAiProxyUrl = `${baseUrl}/proxy/v1`;
-  const mcpUrl = `${baseUrl}/api/mcp`;
+  const healthUrl = `${controlBaseUrl}/api/health`;
+  const runtimeUrl = `${controlBaseUrl}/api/runtime`;
+  const configUrl = `${controlBaseUrl}/api/config`;
+  const anthropicProxyUrl = `${agentBaseUrl}/proxy`;
+  const openAiProxyUrl = `${agentBaseUrl}/proxy/v1`;
+  const mcpUrl = `${agentBaseUrl}/api/mcp`;
   const mcpTomlKey = /^[A-Za-z0-9_-]+$/u.test(mcpName) ? mcpName : JSON.stringify(mcpName);
   const statusCommand = `agent-inspector onboard --status${targetArguments}`;
   const refreshCommand = `agent-inspector onboard --force${targetArguments}`;
@@ -50,7 +60,7 @@ export function renderCodexSkillOnboard(ctx: CodexSkillOnboardContext): string {
     targetKind === "instance" && instanceName !== null
       ? `agent-inspector instance start ${instanceName}`
       : targetKind === "base-url"
-        ? `# Explicit target ${baseUrl}: do not start a replacement local runtime.`
+        ? `# Explicit control target ${controlBaseUrl}: do not start a replacement local runtime.`
         : "agent-inspector --mode simple --background --no-open";
   const fullModeCommand =
     targetKind === "instance" && instanceName !== null
@@ -60,8 +70,14 @@ export function renderCodexSkillOnboard(ctx: CodexSkillOnboardContext): string {
         : "agent-inspector --mode full --force-restart";
   const startExplanation =
     targetKind === "base-url"
-      ? `The selected Inspector target is the explicit Base URL \`${baseUrl}\`. Do not start the default local runtime as a substitute; verify the selected target and ask its operator for help if it is unavailable.`
-      : `Start or reuse the selected Agent Inspector runtime before wiring MCP. Prefer the installed binary so Windows users get the branded runtime in Task Manager. Use \`${fullModeCommand}\` only when the user needs raw headers, raw response, or SSE chunks.`;
+      ? `The selected Inspector target uses control Base URL \`${controlBaseUrl}\` and agent Base URL \`${agentBaseUrl}\`. Do not start the default local runtime as a substitute; verify the selected target and ask its operator for help if it is unavailable.`
+      : `Start or reuse the selected Agent Inspector backend before wiring MCP. The default command composes a UI, while backend-only named instances retain proxy, REST, health, and MCP without UI files. Prefer the installed binary so Windows users get the branded runtime in Task Manager. Use \`${fullModeCommand}\` only when the user needs raw headers, raw response, or SSE chunks.`;
+  const selectedUi =
+    uiUrl === null ? "not supplied (do not infer one from a backend URL)" : `\`${uiUrl}\``;
+  const providerTestUiGuidance =
+    uiUrl === null
+      ? `No UI URL was supplied. Do not open \`${controlBaseUrl}\` or \`${agentBaseUrl}\` as a page; use the MCP Provider Test tools and log/session resources, or ask the operator for a standalone UI URL.`
+      : `The operator supplied the explicit composed or standalone UI URL \`${uiUrl}\`. Use that URL for browser steps; do not substitute the control or agent Base URL.`;
   return `---
 name: agent-inspector-onboard
 description: Guide Codex users through connecting Agent Inspector v${version} as a local MCP server.
@@ -74,7 +90,13 @@ metadata:
 
 Use this skill when the user wants to set up Agent Inspector inside Codex, connect the Agent Inspector MCP server, inspect captured model traffic from Codex, or turn Inspector sessions into reviewable knowledge candidates.
 
-Agent Inspector runs a local web UI, proxy, REST API, and MCP endpoint on the same port. The default MCP endpoint is:
+The selected deployment has these explicit surfaces:
+
+- UI URL: ${selectedUi}
+- Control Base URL: \`${controlBaseUrl}\`
+- Agent Base URL: \`${agentBaseUrl}\`
+
+Composed mode may use one URL for all three, but backend-only mode and separately hosted UI deployments do not require UI and backend to share a process, origin, or port. The selected MCP endpoint is:
 
 \`\`\`text
 ${mcpUrl}
@@ -92,6 +114,8 @@ Do not configure both transports in the same MCP client, or the client may show
 
 Keep this setup local and explicit. Agent Inspector MCP tools can read captured requests and provider configuration, so only wire it into trusted local Codex environments.
 
+The backend publishes token-free runtime discovery at \`${runtimeUrl}\`. Treat \`backend-only\` as healthy when REST, proxy, and MCP capabilities are present.
+
 Agent Inspector starts in **Simple mode** by default. Keep Simple mode for everyday capture: requests, responses, tools, timing, and token usage stay available without retaining heavier raw headers, raw response, or detailed SSE chunk artifacts. Use **Full mode** only when the user is debugging provider headers, raw response payloads, or SSE stream details.
 
 ---
@@ -134,12 +158,14 @@ ${startExplanation}
 \`\`\`powershell
 ${startCommand}
 Invoke-RestMethod -Uri "${healthUrl}" -TimeoutSec 3
+Invoke-RestMethod -Uri "${runtimeUrl}" -TimeoutSec 3 | Select-Object deploymentMode, capabilities
 Invoke-RestMethod -Uri "${configUrl}" -TimeoutSec 3 | Select-Object captureMode
 \`\`\`
 
 \`\`\`bash
 ${startCommand}
 curl -fsS "${healthUrl}"
+curl -fsS "${runtimeUrl}"
 curl -fsS "${configUrl}" | grep -o '"captureMode":"[^"]*"'
 \`\`\`
 
@@ -183,7 +209,7 @@ When editing:
 - Keep existing \`mcp_servers.*\`, \`projects.*\`, profiles, sandbox, approval, and model settings intact.
 - Remove any duplicate Inspector MCP entry that points to the same \`/api/mcp\` endpoint or runs the same \`agent-inspector-mcp stdio\` bridge under another name.
 - Do not write provider API keys into Codex config.
-- Do not expose Agent Inspector MCP beyond localhost.
+- Do not expose a raw Inspector listener to untrusted networks. For remote use, require the operator's authenticated same-origin gateway and keep control credentials in environment variables rather than generated config.
 
 ---
 
@@ -264,14 +290,18 @@ Inspector, \`localhost\` points at the tool's own environment. Replace \`localho
 address reachable from that environment, then verify the network/firewall path before debugging
 provider credentials.
 
-For a Provider Test memory probe, run a provider test in the Agent Inspector UI:
+For a Provider Test memory probe, first read \`${runtimeUrl}\`. ${providerTestUiGuidance}
 
-1. Open \`${baseUrl}\`.
+When an explicit UI URL is available:
+
+1. Open the supplied UI URL.
 2. Go to Settings -> Providers.
 3. Add or edit a Provider.
 4. Run Test.
 5. Check the \`provider-test\` session.
 
+If discovery reports \`backend-only\`, do not fail onboarding. A separately hosted UI may still exist only when its URL was explicitly supplied; otherwise use the MCP Provider Test tools and log/session resources. Proxy, REST, health, and MCP remain fully usable without UI files.
+
 Then ask Codex:
 
 \`\`\`text