@opengeni/api-router 0.12.1 → 0.12.5

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   createApp
-} from "./chunk-S2N4252E.js";
+} from "./chunk-3BHOMOSD.js";
 
 // src/index.ts
 import {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/api-router",
-  "version": "0.12.1",
+  "version": "0.12.5",
   "description": "OpenGeni HTTP surface: the Hono adapter/router (createApp), routes, MCP HTTP transport, and HTTP access adapters over @opengeni/core. An engine-distribution surface — its runtime closure includes engine-internal packages.",
   "license": "Apache-2.0",
   "repository": {
@@ -44,17 +44,17 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@opengeni/agent-proto": "^0.3.0",
     "@opengeni/codex": "^0.2.7",
-    "@opengeni/config": "^0.7.8",
-    "@opengeni/contracts": "^0.20.1",
-    "@opengeni/core": "^0.12.1",
-    "@opengeni/db": "^0.13.1",
-    "@opengeni/documents": "^0.2.38",
-    "@opengeni/events": "^0.3.29",
-    "@opengeni/github": "^0.3.20",
+    "@opengeni/config": "^0.7.10",
+    "@opengeni/contracts": "^0.21.0",
+    "@opengeni/core": "^0.12.5",
+    "@opengeni/db": "^0.13.4",
+    "@opengeni/documents": "^0.2.41",
+    "@opengeni/events": "^0.3.32",
+    "@opengeni/github": "^0.3.22",
     "@opengeni/network": "^0.1.1",
     "@opengeni/observability": "^0.3.0",
-    "@opengeni/runtime": "^0.13.12",
-    "@opengeni/storage": "^0.2.32",
+    "@opengeni/runtime": "^0.14.0",
+    "@opengeni/storage": "^0.2.34",
     "@temporalio/client": "^1.17.0",
     "better-auth": "^1.6.14",
     "hono": "^4.12.18",

package/src/app.ts

@@ -3,6 +3,7 @@ import {
   configuredAllowedModels,
   configuredAllowedReasoningEfforts,
   configuredModels,
+  withCodexCatalogProvider,
 } from "@opengeni/config";
 import {
   ClientConfig,
@@ -322,18 +323,21 @@ export function createApp(deps: AppDependencies): Hono {
 
   app.get("/v1/config/client", (c) => {
     c.header("cache-control", "no-store");
+    const catalogSettings = deps.settings.codexSubscriptionEnabled
+      ? withCodexCatalogProvider(deps.settings)
+      : deps.settings;
     return c.json(
       ClientConfig.parse({
         deploymentRevision: deps.settings.deploymentRevision,
         apiContractRevision: OPENGENI_API_CONTRACT_REVISION,
         ...(deps.settings.serverVersion ? { serverVersion: deps.settings.serverVersion } : {}),
-        defaultModel: canonicalizeConfiguredModelId(deps.settings, deps.settings.openaiModel),
-        allowedModels: configuredAllowedModels(deps.settings),
+        defaultModel: canonicalizeConfiguredModelId(catalogSettings, catalogSettings.openaiModel),
+        allowedModels: configuredAllowedModels(catalogSettings),
         // Provider-grouped model list for the picker. configuredModels() carries the
         // union of the built-in allow-list and every registry provider's models, in
         // selection order (default model first); project each to the client-safe
         // ClientModel shape (ConfiguredModel.providerId → ClientModel.provider).
-        models: configuredModels(deps.settings).map(projectClientModel),
+        models: configuredModels(catalogSettings).map(projectClientModel),
         defaultReasoningEffort: deps.settings.openaiReasoningEffort,
         allowedReasoningEfforts: configuredAllowedReasoningEfforts(deps.settings),
         mcpServers: deps.settings.mcpServers.map((server) => ({
@@ -957,8 +961,8 @@ const routeLabelPatterns: Array<{ pattern: RegExp; label: string }> = [
     label: "/v1/workspaces/:workspaceId/connections/oauth/start",
   },
   {
-    pattern: /^\/v1\/workspaces\/[^/]+\/connections\/slack-bot$/,
-    label: "/v1/workspaces/:workspaceId/connections/slack-bot",
+    pattern: /^\/v1\/workspaces\/[^/]+\/connections\/slack-bot\/install$/,
+    label: "/v1/workspaces/:workspaceId/connections/slack-bot/install",
   },
   {
     pattern: /^\/v1\/workspaces\/[^/]+\/connections\/[^/]+$/,
@@ -973,6 +977,10 @@ const routeLabelPatterns: Array<{ pattern: RegExp; label: string }> = [
     pattern: /^\/v1\/integrations\/oauth\/client-metadata\.json$/,
     label: "/v1/integrations/oauth/client-metadata.json",
   },
+  {
+    pattern: /^\/v1\/integrations\/slack\/callback$/,
+    label: "/v1/integrations/slack/callback",
+  },
   {
     pattern: /^\/v1\/enrollments\/device\/start$/,
     label: "/v1/enrollments/device/start",

package/src/http/auth.ts

@@ -49,7 +49,8 @@ function isAuthExempt(c: Context, settings: Settings): boolean {
   }
   if (
     path === "/v1/integrations/oauth/callback" ||
-    path === "/v1/integrations/oauth/client-metadata.json"
+    path === "/v1/integrations/oauth/client-metadata.json" ||
+    path === "/v1/integrations/slack/callback"
   ) {
     return true;
   }

package/src/integrations/oauth-client.ts

@@ -3,7 +3,7 @@ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import { parseIntegrationsOauthClientsJson, type Settings } from "@opengeni/config";
 import { OAuthStartResponse, type OAuthStartRequest } from "@opengeni/contracts";
-import { requireEnvironmentEncryption } from "@opengeni/core";
+import { hasPermission, requireEnvironmentEncryption } from "@opengeni/core";
 import type { Observability } from "@opengeni/observability";
 import {
   consumeIntegrationOAuthStateNonce,
@@ -11,6 +11,7 @@ import {
   decryptEnvironmentValue,
   encryptEnvironmentValue,
   getConnectionMetadata,
+  getWorkspaceGrant,
   listConnectionsMetadata,
   loadIntegrationOAuthClient,
   normalizeBearerScheme,
@@ -33,6 +34,8 @@ import { HTTPException } from "hono/http-exception";
 import { canonicalProviderDomain } from "./provider-domain";
 
 export const oauthStateTtlMs = 10 * 60 * 1000;
+export const OFFICIAL_SLACK_MCP_URL = "https://mcp.slack.com/mcp";
+const SLACK_OAUTH_ORIGIN = "https://slack.com";
 export { OAUTH_MAX_RESPONSE_BYTES } from "@opengeni/network";
 
 type OAuthClientDeps = {
@@ -139,9 +142,12 @@ export async function startMcpOAuth(
 ): Promise<OAuthStartResponse> {
   const { db, settings } = deps;
   const mcpUrl = canonicalMcpResource(context.payload.mcpUrl ?? context.payload.resource);
-  const providerDomain = canonicalProviderDomain(
-    context.payload.providerDomain ?? new URL(mcpUrl).hostname,
-  );
+  const officialSlackResource = mcpUrl === OFFICIAL_SLACK_MCP_URL;
+  const providerDomain = officialSlackResource
+    ? "slack.com"
+    : canonicalProviderDomain(context.payload.providerDomain ?? new URL(mcpUrl).hostname);
+  const personalSlack = officialSlackResource || providerDomain === "slack.com";
+  assertPersonalSlackOAuthStart(settings, context.payload, mcpUrl, personalSlack);
   const returnPath = safeReturnPath(context.payload.returnPath ?? "/integrations");
   const baseUrl = integrationBaseUrl(settings.publicBaseUrl, context.requestUrl);
   const redirectUri = `${baseUrl}/v1/integrations/oauth/callback`;
@@ -157,6 +163,9 @@ export async function startMcpOAuth(
   }
 
   const discovery = await discoverMcpOAuth(mcpUrl, settings);
+  if (personalSlack && !isLocalTestEnvironment(settings.environment)) {
+    assertSlackAuthorizationServer(discovery.as);
+  }
   const resource = discovery.prm.resource ? canonicalOAuthResource(discovery.prm.resource) : mcpUrl;
   const verifier = randomPkceVerifier();
   const authorizeScopes = chooseAuthorizeScopes(
@@ -230,6 +239,7 @@ export async function completeMcpOAuthCallback(
   }
   try {
     state = readOAuthState(input.state, settings);
+    await requireOAuthCallbackGrant(db, state);
     if (!input.code) {
       return {
         redirectTo: callbackReturnPath(state.returnPath, "error", { reason: "missing_code" }),
@@ -287,6 +297,7 @@ export async function completeMcpOAuthCallback(
       ...(verification.tools ? { mcpTools: verification.tools } : {}),
     };
     const credentialEncrypted = encryptEnvironmentValue(key, JSON.stringify(credential));
+    await requireOAuthCallbackGrant(db, state);
     const connection = await runCallbackStage("persist", "persist_failed", () =>
       state.connectionId
         ? updateConnection(db, {
@@ -294,6 +305,7 @@ export async function completeMcpOAuthCallback(
             connectionId: state.connectionId,
             visibleToSubjectId: state.subjectId,
             expectedVersion: state.connectionVersion,
+            subjectId: state.subjectId,
             providerDomain: state.providerDomain,
             kind: "oauth2",
             status: "active",
@@ -306,7 +318,7 @@ export async function completeMcpOAuthCallback(
         : createConnection(db, {
             accountId: state.accountId,
             workspaceId: state.workspaceId,
-            subjectId: null,
+            subjectId: state.subjectId,
             providerDomain: state.providerDomain,
             kind: "oauth2",
             credentialEncrypted,
@@ -356,6 +368,56 @@ export function requireIntegrationsStateSecret(settings: Settings): string {
   return secret;
 }
 
+async function requireOAuthCallbackGrant(db: Database, state: OAuthStatePayload): Promise<void> {
+  const grant = await getWorkspaceGrant(db, state.subjectId, state.workspaceId);
+  if (
+    !grant ||
+    grant.accountId !== state.accountId ||
+    !hasPermission(grant.permissions, "connections:write")
+  ) {
+    throw new HTTPException(403, {
+      message: "OAuth subject no longer has permission to write this workspace connection",
+    });
+  }
+}
+
+function assertPersonalSlackOAuthStart(
+  settings: Settings,
+  payload: OAuthStartRequest,
+  mcpUrl: string,
+  personalSlack: boolean,
+): void {
+  if (!personalSlack) return;
+  if (payload.oauthClient) {
+    throw new HTTPException(422, {
+      message: "Slack OAuth client credentials are deployment-managed",
+    });
+  }
+  if (payload.providerDomain && canonicalProviderDomain(payload.providerDomain) !== "slack.com") {
+    throw new HTTPException(422, { message: "Slack provider identity does not match slack.com" });
+  }
+  if (!isLocalTestEnvironment(settings.environment) && mcpUrl !== OFFICIAL_SLACK_MCP_URL) {
+    throw new HTTPException(422, {
+      message: `personal Slack OAuth must use ${OFFICIAL_SLACK_MCP_URL}`,
+    });
+  }
+  if (!settings.slackClientId?.trim() || !settings.slackClientSecret?.trim()) {
+    throw new HTTPException(503, {
+      message:
+        "personal Slack OAuth requires OPENGENI_SLACK_CLIENT_ID and OPENGENI_SLACK_CLIENT_SECRET",
+    });
+  }
+}
+
+export function assertSlackAuthorizationServer(as: AuthorizationServerMetadata): void {
+  const urls = [as.issuer, as.authorizationServer, as.authorizationEndpoint, as.tokenEndpoint];
+  if (urls.some((value) => new URL(value).origin !== SLACK_OAUTH_ORIGIN)) {
+    throw new HTTPException(422, {
+      message: "Slack MCP authorization metadata did not remain bound to slack.com",
+    });
+  }
+}
+
 async function discoverMcpOAuth(
   resource: string,
   settings: Settings,
@@ -656,6 +718,18 @@ function operatorClientEntryFor(
   settings: Settings,
   candidates: string[],
 ): ReturnType<typeof parseIntegrationsOauthClientsJson>[string] | null {
+  const normalizedCandidates = new Set(candidates.map(normalizedIssuerKey));
+  if (
+    normalizedCandidates.has(SLACK_OAUTH_ORIGIN) &&
+    settings.slackClientId?.trim() &&
+    settings.slackClientSecret?.trim()
+  ) {
+    return {
+      clientId: settings.slackClientId.trim(),
+      clientSecret: settings.slackClientSecret.trim(),
+      tokenEndpointAuthMethod: "client_secret_post",
+    };
+  }
   const configured = parseIntegrationsOauthClientsJson(settings.integrationsOauthClientsJson);
   const exactKeys = uniqueStrings(
     candidates.flatMap((candidate) => [candidate, normalizedIssuerKey(candidate)]),
@@ -666,7 +740,6 @@ function operatorClientEntryFor(
       return entry;
     }
   }
-  const normalizedCandidates = new Set(candidates.map(normalizedIssuerKey));
   for (const [key, entry] of Object.entries(configured)) {
     if (normalizedCandidates.has(normalizedIssuerKey(key))) {
       return entry;
@@ -743,13 +816,23 @@ async function existingOAuthConnectionForStart(
   },
 ) {
   if (input.connectionId) {
-    return await getConnectionMetadata(db, input.workspaceId, input.connectionId, input.subjectId);
+    const connection = await getConnectionMetadata(
+      db,
+      input.workspaceId,
+      input.connectionId,
+      input.subjectId,
+    );
+    return connection?.subjectId === input.subjectId &&
+      connection.kind === "oauth2" &&
+      connection.providerDomain === input.providerDomain
+      ? connection
+      : null;
   }
   const visible = await listConnectionsMetadata(db, input.workspaceId, input.subjectId);
   return (
     visible.find(
       (connection) =>
-        connection.subjectId === null &&
+        connection.subjectId === input.subjectId &&
         connection.kind === "oauth2" &&
         connection.status === "active" &&
         connection.providerDomain === input.providerDomain,
@@ -836,6 +919,9 @@ function readOAuthState(state: string, settings: Settings): OAuthStatePayload {
   };
   const connectionId = stringValue(payload.connectionId);
   const connectionVersion = numberValue(payload.connectionVersion);
+  if (Boolean(connectionId) !== Boolean(connectionVersion)) {
+    throw new HTTPException(400, { message: "invalid OAuth reconnect state" });
+  }
   return {
     ...parsed,
     ...(connectionId ? { connectionId } : {}),

package/src/integrations/slack-bot.ts

@@ -22,6 +22,7 @@ import {
   getSession,
   recordAuditEvent,
   releaseSlackBotPostOperationClaim,
+  setConnectionStatus,
   type Database,
 } from "@opengeni/db";
 import { readResponseJsonBounded, type FetchLike } from "@opengeni/network";
@@ -43,6 +44,55 @@ export type VerifiedOpenGeniSlackBot = {
   metadata: OpenGeniSlackBotConnectionMetadata;
 };
 
+export async function exchangeOpenGeniSlackAuthorizationCode(
+  input: {
+    code: string;
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+  },
+  fetchImpl: FetchLike = fetch,
+): Promise<string> {
+  const body = new URLSearchParams({
+    code: input.code,
+    client_id: input.clientId,
+    client_secret: input.clientSecret,
+    redirect_uri: input.redirectUri,
+  });
+  let response: Response;
+  try {
+    response = await fetchImpl(`${SLACK_API_BASE}oauth.v2.access`, {
+      method: "POST",
+      headers: {
+        accept: "application/json",
+        "content-type": "application/x-www-form-urlencoded",
+      },
+      body: body.toString(),
+      redirect: "error",
+      signal: AbortSignal.timeout(SLACK_TIMEOUT_MS),
+    });
+  } catch {
+    throw new HTTPException(502, { message: "Slack installation token exchange failed" });
+  }
+  if (!response.ok) {
+    throw new HTTPException(502, { message: "Slack installation token exchange failed" });
+  }
+  const payload = await readResponseJsonBounded<unknown>(
+    response,
+    SLACK_RESPONSE_MAX_BYTES,
+    "Slack OAuth response",
+  );
+  const record = slackRecord(payload);
+  if (!record || record.ok !== true) {
+    throw new SlackBotProviderError(slackString(record?.error) || "oauth_exchange_failed");
+  }
+  const accessToken = slackString(record.access_token);
+  if (!accessToken?.startsWith("xoxb-")) {
+    throw new HTTPException(502, { message: "Slack installation did not return a bot token" });
+  }
+  return accessToken;
+}
+
 export type SlackBotReceipt = {
   credentialRole: typeof OPENGENI_SLACK_BOT_CREDENTIAL_ROLE;
   credentialLabel: typeof OPENGENI_SLACK_BOT_CREDENTIAL_LABEL;
@@ -70,6 +120,30 @@ export class SlackBotProviderError extends Error {
   }
 }
 
+const SLACK_CREDENTIAL_REJECTION_CODES = new Set([
+  "account_inactive",
+  "invalid_auth",
+  "not_authed",
+  "token_expired",
+  "token_revoked",
+]);
+
+function slackCredentialRejected(error: unknown): error is SlackBotProviderError {
+  return error instanceof SlackBotProviderError && SLACK_CREDENTIAL_REJECTION_CODES.has(error.code);
+}
+
+export type SlackBotCredentialVerificationFailureReason = "scope_mismatch" | "identity_mismatch";
+
+export class SlackBotCredentialVerificationError extends HTTPException {
+  constructor(
+    readonly failureReason: SlackBotCredentialVerificationFailureReason,
+    message: string,
+  ) {
+    super(422, { message });
+    this.name = "SlackBotCredentialVerificationError";
+  }
+}
+
 /**
  * Validates a write-only xoxb credential before it can enter encrypted storage.
  * Slack does not expose the app's display_information name to this scope set;
@@ -95,14 +169,18 @@ export async function verifyOpenGeniSlackBotCredential(
   });
   const user = slackRecord(userResponse.payload.user);
   if (!user || user.is_bot !== true || user.deleted === true) {
-    throw new HTTPException(422, { message: "Slack credential must identify an active bot user" });
+    throw new SlackBotCredentialVerificationError(
+      "identity_mismatch",
+      "Slack credential must identify an active bot user",
+    );
   }
   const profile = slackRecord(user.profile);
   const displayName = slackString(profile?.display_name) || slackString(profile?.real_name);
   if (displayName !== "OpenGeni") {
-    throw new HTTPException(422, {
-      message: 'Slack bot display name must be exactly "OpenGeni"',
-    });
+    throw new SlackBotCredentialVerificationError(
+      "identity_mismatch",
+      'Slack bot display name must be exactly "OpenGeni"',
+    );
   }
 
   return {
@@ -355,7 +433,18 @@ export class OpenGeniSlackBotClient {
     method: string,
     params: Record<string, string>,
   ): Promise<SlackPayload> {
-    return (await slackApiFetchWithHeaders(this.fetchImpl, method, headers, params)).payload;
+    try {
+      return (await slackApiFetchWithHeaders(this.fetchImpl, method, headers, params)).payload;
+    } catch (error) {
+      if (slackCredentialRejected(error)) {
+        await setConnectionStatus(this.db, this.context.workspaceId, "needs_reauth", error.code, {
+          id: this.connection.id,
+          version: this.connection.version,
+          subjectId: null,
+        }).catch(() => false);
+      }
+      throw error;
+    }
   }
 
   private async withAudit<T extends Record<string, unknown>>(
@@ -561,15 +650,19 @@ function assertExactOpenGeniSlackBotScopes(grantedScopes: string[]): void {
       ...(forbidden.length ? [`forbidden: ${forbidden.join(", ")}`] : []),
       ...(unsupported.length ? [`unsupported: ${unsupported.join(", ")}`] : []),
     ];
-    throw new HTTPException(422, {
-      message: `Slack bot scopes must exactly match the OpenGeni manifest (${facts.join("; ")})`,
-    });
+    throw new SlackBotCredentialVerificationError(
+      "scope_mismatch",
+      `Slack bot scopes must exactly match the OpenGeni manifest (${facts.join("; ")})`,
+    );
   }
 }
 
 function parseGrantedScopes(header: string | null): string[] {
   if (!header) {
-    throw new HTTPException(422, { message: "Slack did not report granted bot scopes" });
+    throw new SlackBotCredentialVerificationError(
+      "scope_mismatch",
+      "Slack did not report granted bot scopes",
+    );
   }
   return [
     ...new Set(

package/src/mcp/server.ts

@@ -776,6 +776,26 @@ function registerToolspaceProxyTools(server: McpServer, surface: ToolspaceMcpSur
   if (!surface) {
     return;
   }
+  // McpServer installs its tools/list handler lazily on the first registered
+  // tool. A legitimate empty Toolspace surface (no selected proxyable servers,
+  // no active turn, or all optional upstreams unavailable) must therefore seed
+  // and disable one invisible tool; otherwise `ogtool list` receives JSON-RPC
+  // "Method not found" instead of the valid `{ tools: [] }` response.
+  if (surface.tools.length === 0) {
+    server
+      .registerTool(
+        "__opengeni_empty_toolspace_surface__",
+        {
+          description: "Internal disabled placeholder for an empty Toolspace surface.",
+          inputSchema: z4.object({}),
+        },
+        async () => ({
+          content: [{ type: "text" as const, text: '{"unavailable":true}' }],
+        }),
+      )
+      .disable();
+    return;
+  }
   for (const tool of surface.tools) {
     server.registerTool(
       tool.name,

package/src/mcp/toolspace.ts

@@ -367,7 +367,13 @@ async function resolveToolListing(input: {
       sessionId,
       rootSessionId,
       turn: activeTurn,
-    }).catch(() => null);
+    }).catch((error) => {
+      deps.observability?.warn("toolspace upstream connection failed", {
+        serverId,
+        ...toolspaceErrorAttributes(error),
+      });
+      return null;
+    });
     if (!connection) {
       aggregateBudget.replace(serverId, []);
       return;
@@ -375,7 +381,13 @@ async function resolveToolListing(input: {
     try {
       const listed = await connection.client
         .listTools(undefined, toolspaceRequestOptions(config))
-        .catch(() => ({ tools: [] }));
+        .catch((error) => {
+          deps.observability?.warn("toolspace upstream tool list failed", {
+            serverId,
+            ...toolspaceErrorAttributes(error),
+          });
+          return { tools: [] };
+        });
       let boundedTools: readonly McpTool[];
       try {
         boundedTools = assertMcpToolListWithinBounds(listed.tools as McpTool[]) as McpTool[];
@@ -494,7 +506,18 @@ async function connectToolspaceServer(input: {
   rootSessionId: string;
   turn: SessionTurn;
 }): Promise<ConnectedToolspaceServer> {
-  const guardedFetch = guardedMcpFetch(input.deps.settings, undiciFetch);
+  // npm Undici's dispatcher transport is not reliable under Bun. The worker's
+  // model-visible MCP path already uses Bun's native fetch while retaining the
+  // same pre-request destination-policy check; Toolspace must do the same or an
+  // embedded Bun API can expose a server to the model while silently dropping
+  // that exact server from `ogtool list`.
+  const useBunNativeFetch = !!process.versions.bun;
+  const mcpFetchImpl: FetchLike = useBunNativeFetch
+    ? globalThis.fetch.bind(globalThis)
+    : undiciFetch;
+  const guardedFetch = guardedMcpFetch(input.deps.settings, mcpFetchImpl, {
+    ...(useBunNativeFetch ? { pinResolvedDestination: false } : {}),
+  });
   const baseFetch: FetchLike = input.config.connectionRef
     ? connectionBrokerFetch(guardedFetch, input)
     : guardedFetch;
@@ -730,6 +753,24 @@ function toolspaceAuditSummary(value: unknown): {
   };
 }
 
+function toolspaceErrorAttributes(error: unknown): {
+  errorClass: string;
+  errorCode?: string;
+  errorMessage?: string;
+} {
+  if (!(error instanceof Error)) {
+    return { errorClass: typeof error };
+  }
+  const code = (error as Error & { code?: unknown }).code;
+  return {
+    errorClass: error.name,
+    ...(typeof code === "string" ? { errorCode: code } : {}),
+    ...(error.message
+      ? { errorMessage: error.message.replaceAll(/[\r\n]+/gu, " ").slice(0, 512) }
+      : {}),
+  };
+}
+
 type ToolspaceReservation =
   | { status: "ok"; turn: SessionTurn }
   | { status: "no_active_turn" }
@@ -844,8 +885,17 @@ export function connectionBrokerFetch(
   if (!connectionRef) {
     return baseFetch;
   }
-  const resolveCredential = input.deps.connectionCredentials?.mcpCredentials
-    ? buildHostConnectionTokenResolver(input.deps.connectionCredentials.mcpCredentials, {
+  const credentialSubjectId =
+    input.turn.initiator.kind === "subject" ? input.turn.initiator.subjectId : undefined;
+  if (connectionRef.subjectScope === "subject" && !credentialSubjectId) {
+    throw new Error(
+      `subject-owned connection for MCP server ${input.config.id} requires a human turn initiator`,
+    );
+  }
+  const hostCredentialPort = input.deps.connectionCredentials?.mcpCredentials;
+  const resolverSubjectId = hostCredentialPort ? input.grant.subjectId : credentialSubjectId;
+  const resolveCredential = hostCredentialPort
+    ? buildHostConnectionTokenResolver(hostCredentialPort, {
         accountId: input.grant.accountId,
         workspaceId: input.grant.workspaceId,
         sessionId: input.sessionId,
@@ -868,7 +918,7 @@ export function connectionBrokerFetch(
       destinationUrl,
       forceRefresh: false,
       ...(request.toolName ? { toolName: request.toolName } : {}),
-      subjectId: input.grant.subjectId,
+      ...(resolverSubjectId ? { subjectId: resolverSubjectId } : {}),
     });
     if (first.status === "auth_needed") {
       return await authNeededFetchResponse(input, request, first);
@@ -886,7 +936,7 @@ export function connectionBrokerFetch(
         destinationUrl,
         forceRefresh: true,
         ...(request.toolName ? { toolName: request.toolName } : {}),
-        subjectId: input.grant.subjectId,
+        ...(resolverSubjectId ? { subjectId: resolverSubjectId } : {}),
       });
       if (refreshed.status === "auth_needed") {
         return await authNeededFetchResponse(input, request, refreshed);