@opengeni/core 0.28.1 → 1.0.0

package/src/domain/knowledge-search.ts

@@ -0,0 +1,256 @@
+import { KnowledgeEntryListRequest, type KnowledgeEntryListResponse } from "@opengeni/contracts";
+import type { Settings } from "@opengeni/config";
+import {
+  applyCreditDebitAfterUse,
+  checkWorkspaceAllowance,
+  creditDebitAttributionForTurn,
+  getBillingBalance,
+  listKnowledgeEntries,
+  recordUsageEvent,
+  sumUsageQuantity,
+  withKnowledgeQueryAccountLock,
+  type Database,
+  type KnowledgeContext,
+  type CreditDebitAttribution,
+} from "@opengeni/db";
+import type { DocumentEmbedder } from "@opengeni/documents";
+import type { z } from "zod";
+import { documentEmbeddingCostMicros, paidDocumentEmbedding } from "../billing/limits";
+
+// Safety ceilings, not a commercial tariff. Paid queries have no durable
+// reusable vector cache, so each bounded request consumes the provider once.
+const MAX_PAID_QUERY_BYTES = 4096;
+const MAX_PAID_QUERY_MICROS = 1000;
+const MAX_PAID_QUERY_BYTES_PER_MINUTE = 64 * 1024;
+const MAX_PAID_QUERY_BYTES_PER_MONTH = 8 * 1024 * 1024;
+const MAX_PAID_QUERY_MICROS_PER_MINUTE = 10_000;
+const MAX_PAID_QUERY_MICROS_PER_MONTH = 1_000_000;
+
+export class KnowledgeVectorFundingError extends Error {
+  readonly code = "knowledge_vector_funding_required";
+  constructor() {
+    super("Knowledge vector search needs Opengeni credits; keyword search remains available.");
+    this.name = "KnowledgeVectorFundingError";
+  }
+}
+
+export class KnowledgeVectorQueryRejectedError extends Error {
+  constructor(
+    public readonly code: "pagination_unavailable" | "query_limit" | "quota",
+    message: string,
+  ) {
+    super(message);
+    this.name = "KnowledgeVectorQueryRejectedError";
+  }
+}
+
+/** Shared search path for HTTP and both first-party retrieval servers. */
+export async function searchKnowledgeEntries(
+  db: Database,
+  context: KnowledgeContext,
+  input: z.input<typeof KnowledgeEntryListRequest>,
+  embedder: () => DocumentEmbedder,
+  settings?: Settings,
+): Promise<KnowledgeEntryListResponse> {
+  const request = KnowledgeEntryListRequest.parse(input);
+  // Copy trusted actor fields before any provider/lock await. Request lifetime
+  // mutation cannot replace the initiating identity between admission/debit.
+  const billingActor = { ...context.actor };
+  let paidAttribution: CreditDebitAttribution =
+    billingActor.kind === "human"
+      ? { kind: "human", initiatingHumanSubjectId: billingActor.subjectId }
+      : billingActor.kind === "service"
+        ? { kind: "service" }
+        : { kind: "unknown" };
+  if (!request.query || request.mode === "keyword") {
+    return {
+      ...(await listKnowledgeEntries(db, context, request)),
+      searchMode: "keyword" as const,
+    };
+  }
+  // Hybrid queries are natural language, not a conjunction of every synonym.
+  // Keep lexical recall useful when embeddings or vector indexing are unavailable.
+  // Explicit keyword syntax and keyword-mode queries retain their exact semantics.
+  const lexicalQuery =
+    /^[\p{L}\p{N}\s]+$/u.test(request.query) && !/\bOR\b/i.test(request.query)
+      ? [...new Set(request.query.trim().split(/\s+/u))].map((term) => `"${term}"`).join(" OR ")
+      : request.query;
+  const lexicalRequest = KnowledgeEntryListRequest.safeParse({ ...request, query: lexicalQuery });
+  const retrievalRequest =
+    request.mode === "hybrid" && lexicalRequest.success ? lexicalRequest.data : request;
+  const keywordFallback = async (
+    queryDb: Database,
+    error: unknown,
+    fallbackReason: "awaiting_funding" | "quota" | "provider_unavailable" | "query_limit",
+  ) => {
+    if (request.mode === "vector") throw error;
+    return {
+      ...(await listKnowledgeEntries(queryDb, context, { ...retrievalRequest, mode: "keyword" })),
+      searchMode: "keyword" as const,
+      fallbackReason,
+    };
+  };
+  const bytes = Buffer.byteLength(request.query, "utf8");
+  const paidSettings = settings && paidDocumentEmbedding(settings) ? settings : undefined;
+  // Paid cursors would re-embed and re-charge on each page. Until a durable
+  // vector cache exists, require explicit keyword mode to paginate instead.
+  if (paidSettings && request.cursor)
+    throw new KnowledgeVectorQueryRejectedError(
+      "pagination_unavailable",
+      "Paid semantic Knowledge pagination is unavailable; use keyword mode",
+    );
+  const cost = paidSettings ? documentEmbeddingCostMicros(paidSettings, bytes) : 0;
+  if (paidSettings && (bytes > MAX_PAID_QUERY_BYTES || cost > MAX_PAID_QUERY_MICROS))
+    return keywordFallback(
+      db,
+      new KnowledgeVectorQueryRejectedError(
+        "query_limit",
+        "Paid Knowledge query exceeds the per-request limit",
+      ),
+      "query_limit",
+    );
+
+  const retrieveThenSettle = async (queryDb: Database) => {
+    let embedding: { model: string; values: number[] };
+    try {
+      const provider = embedder();
+      const values = await provider.embedQuery(request.query!);
+      if (
+        values.length !== provider.dimensions ||
+        values.some((value) => !Number.isFinite(value)) ||
+        !values.some((value) => value !== 0)
+      )
+        throw new Error("Knowledge query embedding is unavailable");
+      embedding = { model: provider.model, values };
+    } catch (error) {
+      // Only provider failure may fall back. Retrieval and settlement errors
+      // after use surface; they never masquerade as a successful keyword hit.
+      return keywordFallback(queryDb, error, "provider_unavailable");
+    }
+    // Read before billing, in the same transaction for the paid mode. Failure
+    // here leaves no customer charge and no vector result to return.
+    const found = await listKnowledgeEntries(queryDb, context, retrievalRequest, embedding);
+    if (settings) {
+      const usageId = crypto.randomUUID();
+      await recordUsageEvent(queryDb, {
+        accountId: context.accountId,
+        workspaceId: context.workspaceId,
+        eventType: "document.query_embedding_bytes",
+        quantity: bytes,
+        unit: "byte",
+        sourceResourceType: "knowledge_query",
+        sourceResourceId: usageId,
+        idempotencyKey: `knowledge.query_bytes:${usageId}`,
+      });
+      if (paidSettings && cost > 0)
+        await recordUsageEvent(queryDb, {
+          accountId: context.accountId,
+          workspaceId: context.workspaceId,
+          eventType: "document.query_embedding_cost",
+          quantity: cost,
+          unit: "micro_usd",
+          sourceResourceType: "knowledge_query",
+          sourceResourceId: usageId,
+          idempotencyKey: `knowledge.query_cost:${usageId}`,
+          // Durable receipt inserted before the debit in this same transaction.
+          // The service is the writer, not an inferred causal human.
+          initiator: { kind: "service", subjectId: "worker:knowledge-query" },
+          initiatorContext: { creditDebitAttribution: paidAttribution },
+        });
+      if (paidSettings && cost > 0)
+        await applyCreditDebitAfterUse(queryDb, {
+          accountId: context.accountId,
+          workspaceId: context.workspaceId,
+          type: "document_embedding_debit",
+          amountMicros: cost,
+          sourceType: "knowledge_query",
+          sourceId: usageId,
+          idempotencyKey: `knowledge.query_embedding:${usageId}`,
+          metadata: {
+            model: embedding.model,
+            bytes,
+            // This context is constructed by the trusted HTTP/MCP host, never
+            // from request input. The ledger resolves the immutable exact turn;
+            // an API key's subject (or a session creator) is not a human.
+            ...(billingActor.kind === "agent"
+              ? { turnId: billingActor.turnId }
+              : billingActor.kind === "human"
+                ? { initiatingHumanSubjectId: billingActor.subjectId }
+                : {}),
+          },
+        });
+    }
+    return { ...found, searchMode: request.mode };
+  };
+  if (!paidSettings) return retrieveThenSettle(db);
+  // Serialize paid queries across all workspaces of the account before
+  // checking balance. This is an execution fence, not a credit reservation.
+  return withKnowledgeQueryAccountLock(
+    db,
+    context.accountId,
+    context.workspaceId,
+    async (lockedDb) => {
+      const balance = await getBillingBalance(lockedDb, context.accountId);
+      if (balance.balanceMicros <= 0)
+        return keywordFallback(lockedDb, new KnowledgeVectorFundingError(), "awaiting_funding");
+      const attribution =
+        billingActor.kind === "agent"
+          ? await creditDebitAttributionForTurn(lockedDb, {
+              accountId: context.accountId,
+              workspaceId: context.workspaceId,
+              turnId: billingActor.turnId,
+            })
+          : null;
+      if (attribution) paidAttribution = attribution;
+      const refusal = await checkWorkspaceAllowance(lockedDb, {
+        accountId: context.accountId,
+        workspaceId: context.workspaceId,
+        subjectId:
+          billingActor.kind === "human"
+            ? billingActor.subjectId
+            : attribution?.kind === "turn"
+              ? attribution.initiatingHumanSubjectId
+              : null,
+      });
+      if (refusal)
+        return keywordFallback(
+          lockedDb,
+          Object.assign(new Error(refusal.message), refusal),
+          "quota",
+        );
+      const now = new Date();
+      const minuteBytes = await sumUsageQuantity(lockedDb, {
+        accountId: context.accountId,
+        eventType: "document.query_embedding_bytes",
+        since: new Date(now.getTime() - 60_000),
+      });
+      const monthBytes = await sumUsageQuantity(lockedDb, {
+        accountId: context.accountId,
+        eventType: "document.query_embedding_bytes",
+        since: new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1)),
+      });
+      const minuteMicros = await sumUsageQuantity(lockedDb, {
+        accountId: context.accountId,
+        eventType: "document.query_embedding_cost",
+        since: new Date(now.getTime() - 60_000),
+      });
+      const monthMicros = await sumUsageQuantity(lockedDb, {
+        accountId: context.accountId,
+        eventType: "document.query_embedding_cost",
+        since: new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1)),
+      });
+      if (
+        minuteBytes + bytes > MAX_PAID_QUERY_BYTES_PER_MINUTE ||
+        monthBytes + bytes > MAX_PAID_QUERY_BYTES_PER_MONTH ||
+        minuteMicros + cost > MAX_PAID_QUERY_MICROS_PER_MINUTE ||
+        monthMicros + cost > MAX_PAID_QUERY_MICROS_PER_MONTH
+      )
+        return keywordFallback(
+          lockedDb,
+          new KnowledgeVectorQueryRejectedError("quota", "Paid Knowledge query rate limit reached"),
+          "quota",
+        );
+      return retrieveThenSettle(lockedDb);
+    },
+  );
+}

package/src/domain/knowledge.ts

@@ -0,0 +1,133 @@
+import type { AccessGrant, KnowledgeEntryScope, Permission } from "@opengeni/contracts";
+import type { KnowledgeContext } from "@opengeni/db";
+import { hasPermission, type AccessGrantAuthorization } from "../access";
+import { requireLiveAgentAttemptAuthorization } from "../session-authorization";
+import type { ApiRouteDeps } from "../dependencies";
+import { HTTPException } from "hono/http-exception";
+
+/** A delegated MCP gateway can retrieve shared Knowledge. Its subject label
+ * does not establish personal ownership or human review authority. */
+export async function knowledgeContextForGateway(
+  deps: Pick<ApiRouteDeps, "db">,
+  grant: AccessGrant,
+): Promise<KnowledgeContext> {
+  if (!hasPermission(grant.permissions, "documents:search"))
+    throw new HTTPException(403, { message: "Missing permission: documents:search" });
+  if (grant.principalKind === "agent_attempt") {
+    const sessionId = grant.metadata?.sessionId;
+    if (typeof sessionId !== "string")
+      throw new HTTPException(403, { message: "Knowledge attempt unavailable" });
+    const attempt = await requireLiveAgentAttemptAuthorization(deps.db, grant, sessionId);
+    return {
+      accountId: grant.accountId,
+      workspaceId: grant.workspaceId,
+      actor: {
+        kind: "agent",
+        sessionId: attempt.callerSessionId,
+        turnId: attempt.turnId,
+        attemptId: attempt.attemptId,
+        executionGeneration: attempt.executionGeneration,
+      },
+    };
+  }
+  return {
+    accountId: grant.accountId,
+    workspaceId: grant.workspaceId,
+    actor: {
+      kind: "service",
+      principalKind: "mcp_gateway",
+      subjectId: grant.subjectId,
+      writeScopes: [],
+      review: false,
+      settingsScopes: [],
+    },
+  };
+}
+
+/** One host boundary for HTTP, SDK-through-HTTP and first-party Knowledge tools. */
+export async function knowledgeContextForAccess(
+  deps: Pick<ApiRouteDeps, "db">,
+  access: AccessGrantAuthorization,
+  permission: Permission,
+): Promise<KnowledgeContext> {
+  const { grant } = access;
+  if (!hasPermission(grant.permissions, permission)) {
+    throw new HTTPException(403, { message: `Missing permission: ${permission}` });
+  }
+  if (grant.principalKind === "agent_attempt") {
+    const sessionId = grant.metadata?.sessionId;
+    if (typeof sessionId !== "string")
+      throw new HTTPException(403, { message: "Knowledge attempt unavailable" });
+    const attempt = await requireLiveAgentAttemptAuthorization(deps.db, grant, sessionId);
+    return {
+      accountId: grant.accountId,
+      workspaceId: grant.workspaceId,
+      actor: {
+        kind: "agent",
+        sessionId: attempt.callerSessionId,
+        turnId: attempt.turnId,
+        attemptId: attempt.attemptId,
+        executionGeneration: attempt.executionGeneration,
+      },
+    };
+  }
+  if (
+    grant.principalKind === "service" ||
+    grant.principalKind === "api_key" ||
+    grant.principalKind === "configured_key"
+  ) {
+    const writeScopes: Array<"workspace" | "organization"> = hasPermission(
+      grant.permissions,
+      "documents:manage",
+    )
+      ? ["workspace"]
+      : [];
+    if (writeScopes.length && access.accountGrant?.permissions.includes("account:admin"))
+      writeScopes.push("organization");
+    return {
+      accountId: grant.accountId,
+      workspaceId: grant.workspaceId,
+      actor: {
+        kind: "service",
+        principalKind: grant.principalKind,
+        subjectId: grant.subjectId,
+        writeScopes,
+        review: false,
+        settingsScopes: [],
+      },
+    };
+  }
+  if (
+    grant.principalKind !== "human_session" ||
+    !access.contextIntegrity ||
+    access.authenticatedSubjectId !== grant.subjectId ||
+    grant.serviceInitiator ||
+    grant.serviceInitiatorContext ||
+    grant.metadata?.attemptId !== undefined ||
+    grant.metadata?.turnId !== undefined
+  ) {
+    throw new HTTPException(403, {
+      message: "Knowledge management requires an authenticated human or agent attempt",
+    });
+  }
+  const canWrite = hasPermission(grant.permissions, "documents:manage");
+  const writeScopes: KnowledgeEntryScope[] = canWrite ? ["workspace", "personal"] : [];
+  // Organization authority does not follow from the workspace-admin wildcard.
+  if (canWrite && access.accountGrant?.permissions.includes("account:admin"))
+    writeScopes.push("organization");
+  return {
+    accountId: grant.accountId,
+    workspaceId: grant.workspaceId,
+    actor: {
+      kind: "human",
+      principalKind: "human_session",
+      subjectId: access.authenticatedSubjectId,
+      writeScopes,
+      review: canWrite,
+      settingsScopes: [
+        "personal",
+        ...(hasPermission(grant.permissions, "workspace:admin") ? ["workspace" as const] : []),
+      ],
+    },
+  };
+}

package/src/domain/mcp-account-bindings.ts

@@ -0,0 +1,171 @@
+import { connectionAccountIdentityLabel } from "@opengeni/contracts/connection-account-label";
+import { createHash } from "node:crypto";
+import type { McpServerConfig } from "@opengeni/config";
+import {
+  McpConnectionAccountBindings,
+  type ConnectionMetadata,
+  type McpConnectionAccountBinding,
+  type McpConnectionAccountSelection,
+  type McpPersonalConnectionDelegation,
+} from "@opengeni/contracts";
+import { ConnectionAccountSelectionError } from "./connection-account-selection-error";
+
+/** Account routes are stable across retries, but are never parsed to discover
+ * authority. The canonical server is retained separately in the binding. */
+export function mcpAccountRouteId(serverId: string, connectionId: string): string {
+  return `account-${createHash("sha256")
+    .update(JSON.stringify([serverId, connectionId]))
+    .digest("hex")}`;
+}
+
+function accountLabel(connection: ConnectionMetadata): string {
+  const identity = connectionAccountIdentityLabel(
+    connection.metadata,
+    `${connection.providerDomain} account ${connection.id.slice(0, 8)}`,
+  );
+  const scope = connection.subjectId === null ? "This workspace" : "Only me";
+  return `${identity} · ${scope}`;
+}
+
+function canonicalResource(value: string): string {
+  try {
+    const url = new URL(value);
+    url.hash = "";
+    url.pathname = url.pathname.replace(/\/+$/u, "") || "/";
+    return url.toString();
+  } catch {
+    return value.trim();
+  }
+}
+
+/** Pure admission projection over an already authorized inventory. Explicit
+ * pairs narrow one connector; omission attaches all eligible accounts. */
+export function mcpAccountBindingsFromVisibleConnections(input: {
+  accountId: string;
+  workspaceId: string;
+  subjectId: string | null;
+  servers: McpServerConfig[];
+  connections: ConnectionMetadata[];
+  selections?: McpConnectionAccountSelection[];
+  /** The complete accepted set, including an explicitly empty set. */
+  selectionsFrozen?: boolean;
+}): McpConnectionAccountBinding[] {
+  const remaining = new Set(
+    (input.selections ?? []).map((selection) =>
+      JSON.stringify([selection.serverId, selection.connectionId]),
+    ),
+  );
+  const bindings: McpConnectionAccountBinding[] = [];
+  for (const server of input.servers) {
+    const ref = server.connectionRef;
+    if (!ref || ref.authoritySource === "host") continue;
+    // A selector becomes an exact reference at acceptance; do not persist a
+    // selection directive beside the frozen connection UUID.
+    const { accountSelection: _accountSelection, ...exactRef } = ref;
+    const selections = (input.selections ?? []).filter(
+      (selection) => selection.serverId === server.id,
+    );
+    const selectedIds = new Set(selections.map((selection) => selection.connectionId));
+    for (const connection of input.connections) {
+      if (
+        connection.accountId !== input.accountId ||
+        connection.status !== "active" ||
+        connection.providerDomain.toLowerCase() !== ref.providerDomain.toLowerCase() ||
+        (ref.kind && connection.kind !== ref.kind) ||
+        (ref.connectionId !== undefined && ref.connectionId !== connection.id) ||
+        (ref.resource &&
+          (typeof connection.metadata.resource !== "string" ||
+            canonicalResource(connection.metadata.resource) !== canonicalResource(ref.resource))) ||
+        ((input.selectionsFrozen || selectedIds.size > 0) && !selectedIds.has(connection.id))
+      )
+        continue;
+      const personal = connection.subjectId !== null;
+      if (
+        personal
+          ? !input.subjectId || connection.subjectId !== input.subjectId || !connection.authorityId
+          : connection.workspaceId !== input.workspaceId
+      )
+        continue;
+      remaining.delete(JSON.stringify([server.id, connection.id]));
+      bindings.push({
+        serverId: mcpAccountRouteId(server.id, connection.id),
+        canonicalServerId: server.id,
+        connectionId: connection.id,
+        originWorkspaceId: connection.workspaceId,
+        subjectScope: personal ? "subject" : "workspace",
+        ownerSubjectId: connection.subjectId,
+        accountLabel: accountLabel(connection),
+        providerDomain: connection.providerDomain,
+        kind: connection.kind,
+        connectionRef: {
+          ...exactRef,
+          connectionId: connection.id,
+          providerDomain: connection.providerDomain,
+          kind: connection.kind,
+          subjectScope: personal ? "subject" : "workspace",
+        },
+        ...(connection.connectionAuthorityGeneration
+          ? { connectionAuthorityGeneration: connection.connectionAuthorityGeneration }
+          : {}),
+      });
+    }
+  }
+  if (remaining.size > 0) {
+    throw new ConnectionAccountSelectionError(
+      "An attached connector account is unavailable. Review its connection settings.",
+      {
+        version: 1,
+        reason: "selected_account_unavailable",
+        accounts: (input.selections ?? [])
+          .filter((selection) =>
+            remaining.has(JSON.stringify([selection.serverId, selection.connectionId])),
+          )
+          .map((selection) => {
+            const server = input.servers.find((candidate) => candidate.id === selection.serverId);
+            // Only inspect the caller's already-authorized inventory. Never look
+            // up an unavailable account globally merely to improve an error.
+            const connection = input.connections.find(
+              (candidate) => candidate.id === selection.connectionId,
+            );
+            return {
+              serverId: selection.serverId,
+              connectionId: selection.connectionId,
+              reason:
+                !server?.connectionRef || server.connectionRef.authoritySource === "host"
+                  ? ("connector_unavailable" as const)
+                  : !connection
+                    ? ("account_not_visible" as const)
+                    : connection.status !== "active"
+                      ? ("account_inactive" as const)
+                      : ("account_mismatch" as const),
+            };
+          }),
+      },
+    );
+  }
+  return McpConnectionAccountBindings.parse(
+    bindings.sort((left, right) => left.serverId.localeCompare(right.serverId)),
+  );
+}
+
+/** Workspace accounts never acquire a fabricated personal owner/delegation. */
+export function personalDelegationsForAccountBindings(
+  bindings: McpConnectionAccountBinding[],
+): McpPersonalConnectionDelegation[] {
+  return bindings.flatMap((binding) =>
+    binding.subjectScope === "subject" && binding.ownerSubjectId
+      ? [
+          {
+            serverId: binding.serverId,
+            canonicalServerId: binding.canonicalServerId,
+            connectionId: binding.connectionId,
+            originWorkspaceId: binding.originWorkspaceId,
+            ownerSubjectId: binding.ownerSubjectId,
+            providerDomain: binding.providerDomain,
+            kind: binding.kind,
+            connectionType: "mcp" as const,
+          },
+        ]
+      : [],
+  );
+}

package/src/domain/mcp-account-routes.ts

@@ -0,0 +1,121 @@
+import type { Settings } from "@opengeni/config";
+import type { McpConnectionAccountBinding, ToolRef } from "@opengeni/contracts";
+import type { ApiIntegrationRuntime } from "@opengeni/db";
+
+/** Expand only after canonical tool-policy admission. Aliases are execution
+ * identities, never an alternate way to gain admission to a connector. */
+export function expandMcpAccountRoutes(input: {
+  settings: Settings;
+  tools: ToolRef[];
+  bindings: readonly McpConnectionAccountBinding[] | null | undefined;
+}): { settings: Settings; tools: ToolRef[]; accountLabels: ReadonlyMap<string, string> } {
+  // Only historical work has no binding snapshot. A present empty snapshot is
+  // an explicit lack of account authority, never a request for current defaults.
+  if (input.bindings == null) {
+    return { settings: input.settings, tools: input.tools, accountLabels: new Map() };
+  }
+  const configured = new Map(input.settings.mcpServers.map((server) => [server.id, server]));
+  const byCanonical = new Map<string, McpConnectionAccountBinding[]>();
+  const routes = new Set<string>();
+  const accounts = new Set<string>();
+  for (const binding of input.bindings) {
+    const account = JSON.stringify([binding.canonicalServerId, binding.connectionId]);
+    if (
+      routes.has(binding.serverId) ||
+      accounts.has(account) ||
+      configured.has(binding.serverId) ||
+      (binding.subjectScope === "subject") !== (binding.ownerSubjectId !== null) ||
+      binding.connectionRef.authoritySource === "host" ||
+      binding.connectionRef.connectionId !== binding.connectionId ||
+      binding.connectionRef.subjectScope !== binding.subjectScope ||
+      binding.connectionRef.providerDomain !== binding.providerDomain ||
+      binding.connectionRef.kind !== binding.kind
+    ) {
+      throw new Error("Invalid accepted MCP account route");
+    }
+    routes.add(binding.serverId);
+    accounts.add(account);
+    const siblings = byCanonical.get(binding.canonicalServerId) ?? [];
+    siblings.push(binding);
+    byCanonical.set(binding.canonicalServerId, siblings);
+  }
+  const servers: Settings["mcpServers"] = [];
+  const tools: ToolRef[] = [];
+  const accountLabels = new Map<string, string>();
+  for (const tool of input.tools) {
+    const bindings = byCanonical.get(tool.id);
+    if (!bindings) {
+      if (!configured.get(tool.id)?.connectionRef) tools.push(tool);
+      continue;
+    }
+    const canonical = configured.get(tool.id);
+    if (!canonical?.connectionRef) {
+      throw new Error("Accepted MCP account route has no canonical connection configuration");
+    }
+    for (const binding of bindings) {
+      if (
+        canonical.connectionRef.authoritySource === "host" ||
+        canonical.connectionRef.providerDomain !== binding.providerDomain ||
+        (canonical.connectionRef.kind && canonical.connectionRef.kind !== binding.kind)
+      ) {
+        throw new Error("Accepted MCP account route does not match canonical provider");
+      }
+      // Static headers can belong to the formerly selected account. Credentials
+      // for account-qualified routes come exclusively from the native resolver.
+      const { headers: _headers, ...config } = canonical;
+      const label = `${canonical.name ?? canonical.id} — ${binding.subjectScope === "subject" ? "Personal" : "Workspace"}: ${binding.accountLabel}`;
+      servers.push({
+        ...config,
+        id: binding.serverId,
+        name: label,
+        connectionRef: structuredClone(binding.connectionRef),
+      });
+      tools.push({ ...tool, id: binding.serverId });
+      accountLabels.set(binding.serverId, label);
+    }
+  }
+  return {
+    settings: {
+      ...input.settings,
+      mcpServers: [
+        ...input.settings.mcpServers.filter((server) => !server.connectionRef),
+        ...servers,
+      ],
+    },
+    tools,
+    accountLabels,
+  };
+}
+
+/** Each adapter closes over its own immutable credential ref and authority
+ * generation. Sharing a provider transport never shares a credential resolver. */
+export function expandApiIntegrationAccountRoutes(input: {
+  integrations: readonly ApiIntegrationRuntime[];
+  bindings: readonly McpConnectionAccountBinding[] | null | undefined;
+  tools: readonly ToolRef[];
+}): ApiIntegrationRuntime[] {
+  const selected = new Set(input.tools.map((tool) => tool.id));
+  if (input.bindings == null)
+    return input.integrations.filter((item) => selected.has(item.serverId));
+  const acceptedBindings = input.bindings;
+  return input.integrations.flatMap((integration) => {
+    const bindings = acceptedBindings.filter(
+      (binding) => binding.canonicalServerId === integration.serverId,
+    );
+    if (bindings.length === 0)
+      return !integration.connectionRef && selected.has(integration.serverId) ? [integration] : [];
+    return bindings
+      .filter((binding) => selected.has(binding.serverId))
+      .map((binding) => {
+        if (binding.connectionAuthorityGeneration === undefined) {
+          throw new Error("Accepted API integration account route has no authority generation");
+        }
+        return {
+          ...integration,
+          serverId: binding.serverId,
+          connectionRef: structuredClone(binding.connectionRef),
+          connectionAuthorityGeneration: binding.connectionAuthorityGeneration,
+        };
+      });
+  });
+}