Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
32.3 KB
Raw Blame
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
import type { CallToolResult, Tool } from "@modelcontextprotocol/sdk/types.js";
import {
  CONNECT_MCP_APP_HOST_CAPABILITY,
  CONNECT_MCP_APP_HOST_CAPABILITY_HEADER,
  connectMcpAppHostName,
  findOmniRushConnectMcpAppHostServer,
  readOmniRushConnectMcpAppHostAuthorization,
  readOmniRushConnectMcpAppHostCatalog,
  refreshOmniRushConnectMcpAppHostCatalog,
} from "./connect-mcp-server-catalog.js";
import type { ServerConfig } from "./types.js";
import {
  assertLocalManagedMcpUrl,
  createLocalManagedMcpGuardedFetch,
  LocalManagedMcpPrivateUrlError,
} from "./local-managed-mcp-url-guard.js";
import { diagnoseMcpToolDenies, listMcpFromRuntimeSnapshot } from "./mcp.js";
import { readEffectiveRuntimeOpencodeConfig } from "./runtime-opencode-config-store.js";

async function listMcp(serverConfig: ServerConfig, workspaceId: string, workspaceRoot: string) {
  // Account-scoped gateways live in the engine-global runtime layer. Resolve
  // Apps against the same effective configuration that produced the tool call.
  return listMcpFromRuntimeSnapshot(workspaceRoot, await readEffectiveRuntimeOpencodeConfig(serverConfig, workspaceId));
}

const MCP_APP_EXTENSION = "io.modelcontextprotocol/ui";
const MCP_APP_MIME_TYPE = "text/html;profile=mcp-app";
const MCP_PROTOCOL_VERSION = "2025-06-18";
const MAX_TOOL_PAGES = 32;
const MAX_TOOLS = 2_048;
const MAX_RESOURCE_BYTES = 768 * 1024;
const MAX_RESULT_BYTES = 1024 * 1024;
/** Same cap Den applies to provider-declared error excerpts before relaying them. */
const MAX_PROVIDER_ERROR_CHARS = 512;

type McpAppCsp = {
  connectDomains: string[];
  resourceDomains: string[];
  frameDomains: string[];
  baseUriDomains: string[];
};

export type McpAppResource = {
  serverName: string;
  toolName: string;
  resourceUri: string;
  html: string;
  csp: McpAppCsp;
  prefersBorder: boolean;
};

export type ConnectMcpAppLaunchReference = {
  connectionId: string;
  toolName: string;
  resourceUri: string;
};

export type SameServerMcpAppLaunchReference = {
  toolName: string;
  resourceUri: string;
};

export class McpAppHostError extends Error {
  constructor(
    readonly code: string,
    message: string,
  ) {
    super(message);
    this.name = "McpAppHostError";
  }
}

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

/**
 * A bounded, single-line excerpt of a provider's error text. Providers already
 * return arbitrary tool *results* to the same callers, so relaying their
 * rejection is not a new disclosure, but the text is untrusted: strip control
 * characters and cap its length before it becomes an API error message.
 */
function providerErrorExcerpt(error: unknown): string | null {
  if (!(error instanceof Error) || !error.message) return null;
  const sanitized = error.message
    .replace(/[\u0000-\u001F\u007F-\u009F]/g, " ")
    .replace(/\s+/g, " ")
    .trim();
  if (!sanitized) return null;
  return sanitized.length > MAX_PROVIDER_ERROR_CHARS ? `${sanitized.slice(0, MAX_PROVIDER_ERROR_CHARS)}…` : sanitized;
}

function stringHeaders(value: unknown): Record<string, string> {
  if (!isRecord(value)) return {};
  return Object.fromEntries(
    Object.entries(value).filter((entry): entry is [string, string] => typeof entry[1] === "string"),
  );
}

export function projectedMcpToolName(serverName: string, toolName: string): string {
  const sanitize = (value: string) => value.replace(/[^a-zA-Z0-9_-]/g, "_");
  return `${sanitize(serverName)}_${sanitize(toolName)}`;
}

export function toolUiResourceUri(tool: Partial<Tool>): string | null {
  const meta = isRecord(tool._meta) ? tool._meta : {};
  const ui = isRecord(meta.ui) ? meta.ui : {};
  const nested = typeof ui.resourceUri === "string" ? ui.resourceUri : null;
  const legacy = typeof meta["ui/resourceUri"] === "string" ? meta["ui/resourceUri"] : null;
  const uri = nested ?? legacy;
  if (!uri) return null;
  if (!uri.startsWith("ui://")) throw new McpAppHostError("invalid_resource_uri", "MCP App resource URI must use ui://.");
  return uri;
}

function safeDomain(value: unknown): string | null {
  if (typeof value !== "string" || value.length > 2048) return null;
  try {
    const url = new URL(value);
    if (url.username || url.password || url.pathname !== "/" || url.search || url.hash) return null;
    if (url.protocol === "https:") return url.origin;
    if (url.protocol === "http:" && isLoopbackHostname(url.hostname)) return url.origin;
  } catch {
    return null;
  }
  return null;
}

function isLoopbackHostname(hostname: string): boolean {
  return hostname === "127.0.0.1" || hostname === "localhost" || hostname === "[::1]";
}

function domainList(value: unknown): string[] {
  if (!Array.isArray(value) || value.length > 16) {
    if (value === undefined) return [];
    throw new McpAppHostError("invalid_resource_csp", "MCP App CSP domain lists must contain at most 16 origins.");
  }
  const domains = value.map(safeDomain);
  if (domains.some((domain) => domain === null)) {
    throw new McpAppHostError("invalid_resource_csp", "MCP App CSP domains must be HTTPS origins (or loopback HTTP origins).");
  }
  return Array.from(new Set(domains as string[]));
}

function resourcePresentationMeta(value: unknown): { csp: McpAppCsp; prefersBorder: boolean } {
  const meta = isRecord(value) ? value : {};
  const ui = isRecord(meta.ui) ? meta.ui : {};
  const csp = isRecord(ui.csp) ? ui.csp : {};
  const permissions = isRecord(ui.permissions) ? ui.permissions : {};
  if (Object.keys(permissions).length > 0 || ui.domain !== undefined) {
    throw new McpAppHostError(
      "unsupported_resource_permissions",
      "This OmniRush.ai host slice does not grant device permissions or dedicated sandbox origins.",
    );
  }
  return {
    csp: {
      connectDomains: domainList(csp.connectDomains),
      resourceDomains: domainList(csp.resourceDomains),
      frameDomains: domainList(csp.frameDomains),
      baseUriDomains: domainList(csp.baseUriDomains),
    },
    prefersBorder: ui.prefersBorder !== false,
  };
}

function remoteUrl(config: Record<string, unknown>): URL | null {
  if (config.enabled === false || typeof config.url !== "string") return null;
  try {
    const url = new URL(config.url);
    if (url.username || url.password) return null;
    return url.protocol === "https:" || (url.protocol === "http:" && isLoopbackHostname(url.hostname)) ? url : null;
  } catch {
    return null;
  }
}

function clientOptions() {
  return {
    capabilities: {
      extensions: {
        [MCP_APP_EXTENSION]: { mimeTypes: [MCP_APP_MIME_TYPE] },
      },
    },
  };
}

async function withRemoteClient<T>(
  config: Record<string, unknown>,
  run: (client: Client) => Promise<T>,
): Promise<T> {
  const url = remoteUrl(config);
  if (!url) throw new McpAppHostError("unsupported_transport", "MCP Apps currently require a configured remote HTTP MCP server.");
  try {
    await assertLocalManagedMcpUrl(url.toString());
  } catch (error) {
    if (error instanceof LocalManagedMcpPrivateUrlError) {
      throw new McpAppHostError("unsafe_server_url", error.message);
    }
    throw error;
  }
  const guardedFetch = createLocalManagedMcpGuardedFetch();
  const requestInit = {
    headers: stringHeaders(config.headers),
  };
  const attempts = [
    () => new StreamableHTTPClientTransport(url, { requestInit, fetch: guardedFetch }),
    () => new SSEClientTransport(url, { requestInit, fetch: guardedFetch }),
  ];
  let lastError: unknown;
  for (const createTransport of attempts) {
    const client = new Client({ name: "omnirush-mcp-app-host", version: "1.0.0" }, clientOptions());
    let connected = false;
    try {
      await client.connect(createTransport());
      connected = true;
      return await run(client);
    } catch (error) {
      if (connected) throw error;
      lastError = error;
    } finally {
      await client.close().catch(() => undefined);
    }
  }
  throw new McpAppHostError(
    "mcp_unreachable",
    lastError instanceof Error ? lastError.message : "The MCP server could not be reached.",
  );
}

async function listTools(client: Client): Promise<Tool[]> {
  const tools: Tool[] = [];
  let cursor: string | undefined;
  for (let page = 0; page < MAX_TOOL_PAGES; page += 1) {
    const listed = await client.listTools(cursor ? { cursor } : undefined);
    tools.push(...listed.tools);
    if (tools.length > MAX_TOOLS) {
      throw new McpAppHostError("tool_catalog_too_large", "The MCP tool catalog exceeds the host limit.");
    }
    if (!listed.nextCursor) return tools;
    cursor = listed.nextCursor;
  }
  throw new McpAppHostError("tool_catalog_too_large", "MCP tool pagination exceeded the host limit.");
}

function toolVisibility(tool: Partial<Tool>, audience: "model" | "app"): boolean {
  const meta = isRecord(tool._meta) ? tool._meta : {};
  const ui = isRecord(meta.ui) ? meta.ui : {};
  if (ui.visibility === undefined) return true;
  return Array.isArray(ui.visibility)
    && ui.visibility.every((entry) => entry === "model" || entry === "app")
    && ui.visibility.includes(audience);
}

function strictBase64Bytes(value: string): Uint8Array {
  if (value.length > Math.ceil(MAX_RESOURCE_BYTES / 3) * 4) {
    throw new McpAppHostError("resource_too_large", "The MCP App resource exceeds the 768 KiB host limit.");
  }
  if (value.length % 4 !== 0 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)) {
    throw new McpAppHostError("invalid_resource", "The MCP App resource blob is not valid base64.");
  }
  return Buffer.from(value, "base64");
}

function decodeResourceHtml(content: { text?: string; blob?: string }): { html: string; bytes: number } {
  if (typeof content.text === "string" && content.blob === undefined) {
    const bytes = new TextEncoder().encode(content.text).byteLength;
    return { html: content.text, bytes };
  }
  if (typeof content.blob === "string" && content.text === undefined) {
    const bytes = strictBase64Bytes(content.blob);
    try {
      return { html: new TextDecoder("utf-8", { fatal: true }).decode(bytes), bytes: bytes.byteLength };
    } catch {
      throw new McpAppHostError("invalid_resource", "The MCP App resource blob is not valid UTF-8 HTML.");
    }
  }
  throw new McpAppHostError("invalid_resource", "The MCP App resource must contain exactly one of text or blob HTML.");
}

async function privateConnectMcpConfig(input: {
  serverConfig: ServerConfig;
  workspaceId: string;
  connectionId?: string;
  serverName?: string;
}): Promise<{ serverName: string; config: Record<string, unknown> } | null> {
  let descriptor = await findOmniRushConnectMcpAppHostServer(
    input.serverConfig,
    input.workspaceId,
    { connectionId: input.connectionId, serverName: input.serverName },
  );
  if (!descriptor) {
    const refreshed = await refreshOmniRushConnectMcpAppHostCatalog(input.serverConfig, input.workspaceId);
    if (refreshed.status === "synced") {
      descriptor = await findOmniRushConnectMcpAppHostServer(
        input.serverConfig,
        input.workspaceId,
        { connectionId: input.connectionId, serverName: input.serverName },
      );
    }
  }
  if (!descriptor) return null;
  const appHostAuthorization = await readOmniRushConnectMcpAppHostAuthorization(
    input.serverConfig,
    input.workspaceId,
    descriptor.url,
  );
  if (!appHostAuthorization) return null;
  return {
    serverName: connectMcpAppHostName(descriptor.connectionId),
    config: {
      type: "remote",
      url: descriptor.url,
      enabled: true,
      headers: {
        Authorization: appHostAuthorization,
        [CONNECT_MCP_APP_HOST_CAPABILITY_HEADER]: CONNECT_MCP_APP_HOST_CAPABILITY,
      },
    },
  };
}

function findHtmlResource(
  resourceUri: string,
  result: Awaited<ReturnType<Client["readResource"]>>,
): { html: string; meta: unknown } {
  const candidates = result.contents.filter((content) => content.uri === resourceUri);
  if (candidates.length !== 1) {
    throw new McpAppHostError("invalid_resource", "The MCP App resource must return exactly one matching HTML resource.");
  }
  const content = candidates[0];
  if (!content) throw new McpAppHostError("invalid_resource", "The MCP App resource did not return HTML content.");
  if (content.mimeType?.toLowerCase() !== MCP_APP_MIME_TYPE) {
    throw new McpAppHostError("invalid_resource_mime", `MCP App resources must use ${MCP_APP_MIME_TYPE}.`);
  }
  const decoded = decodeResourceHtml(content);
  if (decoded.bytes > MAX_RESOURCE_BYTES) {
    throw new McpAppHostError("resource_too_large", "The MCP App resource exceeds the 768 KiB host limit.");
  }
  return { html: decoded.html, meta: content._meta };
}

export type McpAppCatalogApp = {
  serverName: string;
  /** Present for Connect app-host apps: launch them through this connection reference. */
  connectionId?: string;
  toolName: string;
  projectedToolName: string;
  resourceUri: string;
  title: string | null;
  description: string | null;
  /** True when the launch tool declares required input, so a host cannot start it with empty arguments. */
  requiresInput: boolean;
  /** True when calling the launch tool needs user approval (not explicitly read-only, or destructive). */
  requiresApproval: boolean;
};

export type McpAppCatalogServer = {
  serverName: string;
  /** Human-readable provider name for Connect app-host servers. */
  displayName?: string;
  connectionId?: string;
  reachable: boolean;
  error?: string;
  apps: McpAppCatalogApp[];
};

function toolRequiresInput(tool: Tool): boolean {
  const schema: unknown = tool.inputSchema;
  if (!isRecord(schema)) return false;
  return Array.isArray(schema.required) && schema.required.length > 0;
}

/** The single approval rule: `callMcpAppTool` enforces it, the catalog reports it. */
function toolRequiresApproval(tool: Tool): boolean {
  return tool.annotations?.readOnlyHint !== true || tool.annotations?.destructiveHint === true;
}

/** Per-server budget for catalog probes so one slow server cannot starve the rest. */
const CATALOG_PROBE_TIMEOUT_MS = 10_000;

async function withCatalogProbeTimeout<T>(work: Promise<T>): Promise<T> {
  let timer: ReturnType<typeof setTimeout> | undefined;
  try {
    return await Promise.race([
      work,
      new Promise<never>((_, reject) => {
        timer = setTimeout(
          () => reject(new Error("The MCP server did not respond in time.")),
          CATALOG_PROBE_TIMEOUT_MS,
        );
      }),
    ]);
  } finally {
    if (timer !== undefined) clearTimeout(timer);
    work.catch(() => undefined);
  }
}

async function catalogAppsFromClient(client: Client, options: {
  serverName: string;
  workspaceRoot: string;
  connectionId?: string;
  /** Cold launches resolve by projected tool name, which needs model visibility. */
  requireModelVisibility: boolean;
}): Promise<McpAppCatalogApp[]> {
  const catalog: McpAppCatalogApp[] = [];
  for (const tool of await listTools(client)) {
    if (options.requireModelVisibility && !toolVisibility(tool, "model")) continue;
    if (!toolVisibility(tool, "app")) continue;
    let resourceUri: string | null;
    try {
      resourceUri = toolUiResourceUri(tool);
    } catch {
      continue;
    }
    if (!resourceUri) continue;
    const projectedToolName = projectedMcpToolName(options.serverName, tool.name);
    if ((await diagnoseMcpToolDenies(options.workspaceRoot, options.serverName, [projectedToolName])).length > 0) continue;
    catalog.push({
      serverName: options.serverName,
      ...(options.connectionId ? { connectionId: options.connectionId } : {}),
      toolName: tool.name,
      projectedToolName,
      resourceUri,
      title: toolDisplayTitle(tool),
      description: typeof tool.description === "string" ? tool.description : null,
      requiresInput: toolRequiresInput(tool),
      requiresApproval: toolRequiresApproval(tool),
    });
  }
  return catalog;
}

function toolDisplayTitle(tool: Tool): string | null {
  if (typeof tool.title === "string" && tool.title.trim()) return tool.title;
  const annotationTitle = tool.annotations?.title;
  return typeof annotationTitle === "string" && annotationTitle.trim() ? annotationTitle : null;
}

/**
 * Enumerates every MCP App a host surface can launch cold: tools on configured
 * remote MCP servers that advertise a standard UI resource binding, stay
 * visible to both the model (resolution) and apps (tool calls), and are not
 * denied by the workspace tool policy. Unreachable servers are reported, not
 * fatal, so the catalog doubles as a live connection probe.
 */
export async function listMcpAppCatalog(input: {
  serverConfig: ServerConfig;
  workspaceId: string;
  workspaceRoot: string;
}): Promise<McpAppCatalogServer[]> {
  const configured = await listMcp(input.serverConfig, input.workspaceId, input.workspaceRoot);
  // Connect app-host providers: org connections surfaced through the Cloud
  // capability gateway. Their catalog and authorization live in the private
  // app-host store, not the workspace MCP config, and their launches resolve
  // through a connection reference (app audience only).
  let connectCatalog = await readOmniRushConnectMcpAppHostCatalog(input.serverConfig, input.workspaceId);
  if (connectCatalog.servers.length === 0) {
    const refreshed = await refreshOmniRushConnectMcpAppHostCatalog(input.serverConfig, input.workspaceId);
    if (refreshed.status === "synced") {
      connectCatalog = await readOmniRushConnectMcpAppHostCatalog(input.serverConfig, input.workspaceId);
    }
  }
  // A Connect host can also appear in the workspace MCP config under the same
  // name; the provider section owns it (its entries carry the connection
  // reference launches need), so the workspace copy is skipped.
  const connectHostNames = new Set(
    connectCatalog.servers.map((descriptor) => connectMcpAppHostName(descriptor.connectionId)),
  );

  const configuredEntries = configured
    .filter((item) => item.config.enabled !== false && remoteUrl(item.config) && !connectHostNames.has(item.name))
    .map(async (item): Promise<McpAppCatalogServer> => {
      try {
        const apps = await withCatalogProbeTimeout(withRemoteClient(item.config, (client) =>
          // Cold dashboard launches resolve by projected tool name (model
          // audience) and execute through the app-mediated call path, so a
          // listed app must stay visible to both.
          catalogAppsFromClient(client, {
            serverName: item.name,
            workspaceRoot: input.workspaceRoot,
            requireModelVisibility: true,
          })));
        return { serverName: item.name, reachable: true, apps };
      } catch (error) {
        return {
          serverName: item.name,
          reachable: false,
          error: error instanceof Error ? error.message : "The MCP server could not be reached.",
          apps: [],
        };
      }
    });

  const connectEntries = connectCatalog.servers.map(async (descriptor): Promise<McpAppCatalogServer> => {
    const hostName = connectMcpAppHostName(descriptor.connectionId);
    const base = {
      serverName: hostName,
      displayName: descriptor.name,
      connectionId: descriptor.connectionId,
    };
    const authorization = await readOmniRushConnectMcpAppHostAuthorization(
      input.serverConfig,
      input.workspaceId,
      descriptor.url,
    );
    if (!authorization) {
      return {
        ...base,
        reachable: false,
        error: "The Connect MCP provider is not authorized for this workspace.",
        apps: [],
      };
    }
    const config: Record<string, unknown> = {
      type: "remote",
      url: descriptor.url,
      enabled: true,
      headers: {
        Authorization: authorization,
        [CONNECT_MCP_APP_HOST_CAPABILITY_HEADER]: CONNECT_MCP_APP_HOST_CAPABILITY,
      },
    };
    try {
      const apps = await withCatalogProbeTimeout(withRemoteClient(config, (client) =>
        catalogAppsFromClient(client, {
          serverName: hostName,
          workspaceRoot: input.workspaceRoot,
          connectionId: descriptor.connectionId,
          requireModelVisibility: false,
        })));
      return { ...base, reachable: true, apps };
    } catch (error) {
      return {
        ...base,
        reachable: false,
        error: error instanceof Error ? error.message : "The Connect MCP provider could not be reached.",
        apps: [],
      };
    }
  });

  // Servers are independent probes: run them concurrently so catalog latency
  // is the slowest single server, not the sum of every connection attempt.
  return Promise.all([...configuredEntries, ...connectEntries]);
}

export async function resolveMcpAppResource(input: {
  serverConfig: ServerConfig;
  workspaceId: string;
  workspaceRoot: string;
  projectedToolName: string;
}): Promise<McpAppResource | null> {
  if (!/^[a-zA-Z0-9_-]{1,256}$/.test(input.projectedToolName)) {
    throw new McpAppHostError("invalid_tool_name", "Projected MCP tool name is invalid.");
  }
  const configured = await listMcp(input.serverConfig, input.workspaceId, input.workspaceRoot);
  const candidates = configured.filter((item) => (
    item.config.enabled !== false
    && input.projectedToolName.startsWith(`${item.name.replace(/[^a-zA-Z0-9_-]/g, "_")}_`)
  ));
  const matches: McpAppResource[] = [];
  const resolutionErrors: McpAppHostError[] = [];
  for (const item of candidates) {
    if (!remoteUrl(item.config)) continue;
    const match = await withRemoteClient(item.config, async (client) => {
      const tool = (await listTools(client)).find((candidate) => (
        projectedMcpToolName(item.name, candidate.name) === input.projectedToolName
      ));
      if (!tool) return null;
      if (!toolVisibility(tool, "model")) return null;
      const resourceUri = toolUiResourceUri(tool);
      if (!resourceUri) return null;
      if ((await diagnoseMcpToolDenies(input.workspaceRoot, item.name, [input.projectedToolName])).length > 0) {
        throw new McpAppHostError("tool_denied", "This MCP App tool is denied by the workspace tool policy.");
      }
      const read = await client.readResource({ uri: resourceUri }).catch(() => {
        throw new McpAppHostError(
          "resource_read_failed",
          "The current MCP App tool definition advertises a resource that resources/read could not load.",
        );
      });
      const resource = findHtmlResource(resourceUri, read);
      const presentation = resourcePresentationMeta(resource.meta);
      return {
        serverName: item.name,
        toolName: tool.name,
        resourceUri,
        html: resource.html,
        ...presentation,
      } satisfies McpAppResource;
    }).catch((error) => {
      if (error instanceof McpAppHostError && error.code !== "mcp_unreachable") throw error;
      resolutionErrors.push(error instanceof McpAppHostError
        ? error
        : new McpAppHostError("mcp_app_resolution_failed", "The MCP App resource could not be resolved."));
      return null;
    });
    if (match) matches.push(match);
  }
  if (matches.length > 1) {
    throw new McpAppHostError("ambiguous_tool", "More than one configured MCP App matches this projected tool name.");
  }
  if (matches.length === 0 && resolutionErrors[0]) throw resolutionErrors[0];
  return matches[0] ?? null;
}

/**
 * Resolves a capability-gateway launch back to the exact native Connect MCP
 * tool. The gateway reference is only a routing hint: the local host derives
 * the managed server name, re-lists the provider tool, and requires its live
 * UI binding to match before reading or executing any resource.
 */
export async function resolveConnectMcpAppResource(input: {
  serverConfig: ServerConfig;
  workspaceId: string;
  workspaceRoot: string;
  launch: ConnectMcpAppLaunchReference;
}): Promise<McpAppResource> {
  if (!/^[a-zA-Z0-9_-]{1,160}$/.test(input.launch.connectionId)) {
    throw new McpAppHostError("invalid_launch_reference", "The MCP App connection reference is invalid.");
  }
  if (!/^[^\s]{1,256}$/.test(input.launch.toolName)) {
    throw new McpAppHostError("invalid_launch_reference", "The MCP App tool reference is invalid.");
  }
  if (!input.launch.resourceUri.startsWith("ui://") || input.launch.resourceUri.length > 2_048) {
    throw new McpAppHostError("invalid_resource_uri", "MCP App resource URI must use ui://.");
  }

  const item = await privateConnectMcpConfig({
    serverConfig: input.serverConfig,
    workspaceId: input.workspaceId,
    connectionId: input.launch.connectionId,
  });
  if (!item || !remoteUrl(item.config)) {
    throw new McpAppHostError("server_unavailable", "The originating Connect MCP server is not available to this workspace.");
  }
  const { serverName } = item;

  return await withRemoteClient(item.config, async (client) => {
    const tool = (await listTools(client)).find((candidate) => candidate.name === input.launch.toolName);
    if (!tool) {
      throw new McpAppHostError("tool_not_found", "The originating MCP App tool is no longer advertised.");
    }
    if (!toolVisibility(tool, "app")) {
      throw new McpAppHostError("tool_not_visible", "The originating MCP App tool is not visible to apps.");
    }
    const resourceUri = toolUiResourceUri(tool);
    if (resourceUri !== input.launch.resourceUri) {
      throw new McpAppHostError("tool_resource_mismatch", "The originating MCP App tool now advertises a different resource.");
    }
    const projectedName = projectedMcpToolName(serverName, tool.name);
    if ((await diagnoseMcpToolDenies(input.workspaceRoot, serverName, [projectedName])).length > 0) {
      throw new McpAppHostError("tool_denied", "This MCP App tool is denied by the workspace tool policy.");
    }
    const read = await client.readResource({ uri: resourceUri }).catch(() => {
      throw new McpAppHostError(
        "resource_read_failed",
        "The current MCP App tool definition advertises a resource that resources/read could not load.",
      );
    });
    const resource = findHtmlResource(resourceUri, read);
    const presentation = resourcePresentationMeta(resource.meta);
    return {
      serverName,
      toolName: tool.name,
      resourceUri,
      html: resource.html,
      ...presentation,
    };
  });
}

/** Resolve an indirect launch against the same MCP server that owns the
 * model-visible capability gateway tool. The target launch tool stays
 * app-visible, but its standard UI binding and resource are revalidated live.
 */
export async function resolveSameServerMcpAppResource(input: {
  serverConfig: ServerConfig;
  workspaceId: string;
  workspaceRoot: string;
  projectedToolName: string;
  launch: SameServerMcpAppLaunchReference;
}): Promise<McpAppResource> {
  if (!/^[a-zA-Z0-9_-]{1,256}$/.test(input.projectedToolName)) {
    throw new McpAppHostError("invalid_tool_name", "Projected MCP tool name is invalid.");
  }
  if (!/^[^\s]{1,256}$/.test(input.launch.toolName)) {
    throw new McpAppHostError("invalid_launch_reference", "The MCP App tool reference is invalid.");
  }
  if (!input.launch.resourceUri.startsWith("ui://") || input.launch.resourceUri.length > 2_048) {
    throw new McpAppHostError("invalid_resource_uri", "MCP App resource URI must use ui://.");
  }

  const configured = await listMcp(input.serverConfig, input.workspaceId, input.workspaceRoot);
  const candidates = configured.filter((item) => (
    item.config.enabled !== false
    && remoteUrl(item.config)
    && input.projectedToolName.startsWith(`${item.name.replace(/[^a-zA-Z0-9_-]/g, "_")}_`)
  ));
  const matches: McpAppResource[] = [];
  for (const item of candidates) {
    const match = await withRemoteClient(item.config, async (client) => {
      const tools = await listTools(client);
      const gatewayTool = tools.find((tool) => projectedMcpToolName(item.name, tool.name) === input.projectedToolName);
      if (!gatewayTool || !toolVisibility(gatewayTool, "model")) return null;
      const launchTool = tools.find((tool) => tool.name === input.launch.toolName);
      if (!launchTool) throw new McpAppHostError("tool_not_found", "The same-server MCP App tool is no longer advertised.");
      if (!toolVisibility(launchTool, "app")) {
        throw new McpAppHostError("tool_not_visible", "The same-server MCP App tool is not visible to apps.");
      }
      const resourceUri = toolUiResourceUri(launchTool);
      if (resourceUri !== input.launch.resourceUri) {
        throw new McpAppHostError("tool_resource_mismatch", "The same-server MCP App tool now advertises a different resource.");
      }
      const projectedLaunchName = projectedMcpToolName(item.name, launchTool.name);
      if ((await diagnoseMcpToolDenies(input.workspaceRoot, item.name, [projectedLaunchName])).length > 0) {
        throw new McpAppHostError("tool_denied", "This MCP App tool is denied by the workspace tool policy.");
      }
      const read = await client.readResource({ uri: resourceUri }).catch(() => {
        throw new McpAppHostError("resource_read_failed", "The MCP App resource could not be loaded from its same-server provider.");
      });
      const resource = findHtmlResource(resourceUri, read);
      return {
        serverName: item.name,
        toolName: launchTool.name,
        resourceUri,
        html: resource.html,
        ...resourcePresentationMeta(resource.meta),
      } satisfies McpAppResource;
    });
    if (match) matches.push(match);
  }
  if (matches.length > 1) {
    throw new McpAppHostError("ambiguous_tool", "More than one configured MCP server matches this capability gateway launch.");
  }
  if (!matches[0]) throw new McpAppHostError("server_unavailable", "The MCP server that produced this App launch is unavailable.");
  return matches[0];
}

export async function callMcpAppTool(input: {
  serverConfig: ServerConfig;
  workspaceId: string;
  workspaceRoot: string;
  serverName: string;
  name: string;
  resourceUri?: string;
  arguments?: Record<string, unknown>;
  approved?: boolean;
}): Promise<CallToolResult> {
  const privateItem = await privateConnectMcpConfig({
    serverConfig: input.serverConfig,
    workspaceId: input.workspaceId,
    serverName: input.serverName,
  });
  const configured = privateItem ? [] : await listMcp(input.serverConfig, input.workspaceId, input.workspaceRoot);
  const item = privateItem ?? configured.find((candidate) => candidate.name === input.serverName);
  if (!item || item.config.enabled === false) {
    throw new McpAppHostError("server_unavailable", "The originating MCP server is not available to this workspace.");
  }
  return await withRemoteClient(item.config, async (client) => {
    const tool = (await listTools(client)).find((candidate) => candidate.name === input.name);
    if (!tool) throw new McpAppHostError("tool_not_found", "The requested same-server MCP tool was not found.");
    if (!toolVisibility(tool, "app")) {
      throw new McpAppHostError("tool_not_visible", "The requested MCP tool is not visible to apps.");
    }
    const boundResourceUri = toolUiResourceUri(tool);
    if (boundResourceUri && boundResourceUri !== input.resourceUri) {
      throw new McpAppHostError(
        "tool_resource_mismatch",
        "The requested MCP tool is bound to a different MCP App resource.",
      );
    }
    const projectedName = projectedMcpToolName(input.serverName, tool.name);
    if ((await diagnoseMcpToolDenies(input.workspaceRoot, input.serverName, [projectedName])).length > 0) {
      throw new McpAppHostError("tool_denied", "This same-server MCP tool is denied by the workspace tool policy.");
    }
    if (toolRequiresApproval(tool) && !input.approved) {
      throw new McpAppHostError(
        "tool_requires_approval",
        "This MCP App tool requires user approval before OmniRush.ai can call it.",
      );
    }
    // A provider that rejects the call (for example JSON-RPC -32602 for a
    // missing required argument) must reach the member as that rejection,
    // not as an unhandled 500 "Unexpected server error". The text is
    // provider-controlled: bound it the same way Den bounds provider excerpts.
    const result = await client.callTool({ name: input.name, arguments: input.arguments ?? {} }).catch((error: unknown) => {
      throw new McpAppHostError("tool_call_failed", providerErrorExcerpt(error) ?? "The MCP App tool call failed.");
    });
    if (new TextEncoder().encode(JSON.stringify(result)).byteLength > MAX_RESULT_BYTES) {
      throw new McpAppHostError("result_too_large", "The MCP App tool result exceeds the 1 MiB host limit.");
    }
    return result as CallToolResult;
  });
}

export const mcpAppHostProtocol = {
  extension: MCP_APP_EXTENSION,
  mimeType: MCP_APP_MIME_TYPE,
  protocolVersion: MCP_PROTOCOL_VERSION,
};