@opengeni/api-router 4.1.0 → 4.1.2-canary.36199476632001

package/src/integrations/personal-github.ts

@@ -48,8 +48,10 @@ import {
 } from "../connection-ownership";
 import {
   integrationBaseUrl,
+  oauthStateFailureReturn,
   oauthStateTtlMs,
   requireIntegrationsStateSecret,
+  workspaceIntegrationsPath,
 } from "./oauth-client";
 
 const PERSONAL_GITHUB_OAUTH_STATE_KIND = "personal_github_oauth";
@@ -536,7 +538,7 @@ export async function completePersonalGitHubOAuthCallback(
     return {
       redirectTo: personalGitHubCallbackReturnUrl(
         returnBaseUrl,
-        state?.returnPath ?? "/integrations",
+        state?.returnPath ?? oauthStateFailureReturn(deps.settings, input.state).returnPath,
         "error",
         { reason: personalGitHubFailureReason(error) },
       ),
@@ -752,7 +754,7 @@ function parseGitHubScopes(raw: string | null): string[] {
 }
 
 function personalGitHubReturnPath(workspaceId: string, raw?: string): string {
-  const fallback = `/workspaces/${workspaceId}/capabilities`;
+  const fallback = workspaceIntegrationsPath(workspaceId);
   if (!raw) return fallback;
   let parsed: URL;
   try {

package/src/integrations/provider-oauth.ts

@@ -54,8 +54,10 @@ import {
 } from "../connection-ownership";
 import {
   integrationBaseUrl,
+  oauthStateFailureReturn,
   oauthStateTtlMs,
   requireIntegrationsStateSecret,
+  workspaceIntegrationsPath,
 } from "./oauth-client";
 
 const PROVIDER_OAUTH_CALLBACK_PATH = "/v1/integrations/provider-oauth/callback";
@@ -109,6 +111,7 @@ type ProviderIdentity = {
 
 type ProviderOAuthFailureReason =
   | "state_invalid"
+  | "state_expired"
   | "state_replayed"
   | "provider_denied"
   | "missing_code"
@@ -202,7 +205,7 @@ export async function startApiIntegrationProviderOAuth(
   const baseUrl = integrationBaseUrl(deps.settings.publicBaseUrl, input.requestUrl);
   const redirectUri = `${baseUrl}${providerOAuthCallbackPath(definition)}`;
   const returnPath = safeReturnPath(
-    input.payload.returnPath ?? `/workspaces/${input.workspaceId}/capabilities`,
+    input.payload.returnPath ?? workspaceIntegrationsPath(input.workspaceId),
   );
   const state = createSignedState(requireIntegrationsStateSecret(deps.settings), {
     accountId: input.accountId,
@@ -517,14 +520,18 @@ export async function completeApiIntegrationProviderOAuth(
     };
   } catch (error) {
     if (exactReturnUrl !== undefined) return { redirectTo: exactReturnUrl, exactReturn: true };
+    const reason = providerOAuthFailureReason(error);
+    // An unreadable state carries no return path; an authentic but aged one
+    // still names its workspace and is reported as expired.
+    const failure = state ? null : oauthStateFailureReturn(deps.settings, input.state);
     return {
       redirectTo: providerOAuthReturnUrl(
         returnBaseUrl,
-        state?.returnPath ?? "/integrations",
+        state?.returnPath ?? failure!.returnPath,
         "error",
         {
           ...(state?.definitionId ? { definitionId: state.definitionId } : {}),
-          reason: providerOAuthFailureReason(error),
+          reason: failure && reason === "state_invalid" ? failure.reason : reason,
         },
       ),
     };

package/src/integrations/slack-bot.ts

@@ -43,11 +43,14 @@ import {
   type FetchLike,
 } from "@opengeni/network";
 import { HTTPException } from "hono/http-exception";
+import sharp from "sharp";
 
 const SLACK_API_BASE = "https://slack.com/api/";
 const SLACK_RESPONSE_MAX_BYTES = 2 * 1024 * 1024;
 const SLACK_FILE_RESPONSE_MAX_BYTES = 4 * 1024 * 1024;
 export const SLACK_REACTION_IMAGE_MAX_BYTES = 4 * 1024 * 1024;
+// Base64 plus MCP metadata must stay below the runtime's 1 MiB model-result cap.
+export const SLACK_MCP_IMAGE_MAX_BYTES = 640 * 1024;
 const SLACK_FILE_CONTENT_PAGE_CHARS = 50_000;
 const SLACK_TIMEOUT_MS = 10_000;
 const MAX_CHANNEL_PAGE = 200;
@@ -991,6 +994,35 @@ export class OpenGeniSlackBotClient {
         "file.content.read",
         input,
       );
+      if (SLACK_REACTION_IMAGE_MIME_TYPES.has(normalizedContentType(file.mimetype))) {
+        if (input.offset !== undefined && input.offset !== 0) {
+          throw new SlackBotProviderError("invalid_file_offset");
+        }
+        // A context file is read only on explicit request. Keep the same
+        // non-shared channel boundary and byte validation as invocation images.
+        await this.requireActiveNonSharedMemberChannel(headers, input.channelId);
+        if (!fileIsSharedToChannel(fileRecord, input.channelId)) {
+          throw new SlackBotProviderError("file_not_shared_to_channel");
+        }
+        if (file.size !== null && (file.size < 1 || file.size > SLACK_REACTION_IMAGE_MAX_BYTES)) {
+          throw new SlackBotProviderError("invalid_file_size");
+        }
+        if (file.size !== null && file.size > SLACK_MCP_IMAGE_MAX_BYTES) {
+          throw new SlackBotProviderError("image_result_too_large");
+        }
+        const image = await this.downloadReactionImage({
+          fileId: file.id,
+          filename: file.name || file.title || file.id,
+          declaredMimeType: normalizedContentType(file.mimetype),
+          declaredSizeBytes: file.size,
+          downloadUrl: privateSlackFileUrl(fileRecord),
+        });
+        if (image.bytes.byteLength > SLACK_MCP_IMAGE_MAX_BYTES) {
+          throw new SlackBotProviderError("image_result_too_large");
+        }
+        await validateSlackMcpImage(image.bytes);
+        return { channel: info, file, image };
+      }
       const embeddedTranscript = embeddedHuddleTranscription(fileRecord, parentFileRecord);
       const { contentType, content } =
         embeddedTranscript ?? (await this.readPrivateFileText(fileRecord, "file.content.read"));
@@ -1718,7 +1750,8 @@ export class OpenGeniSlackBotClient {
         method: "GET",
         headers: {
           ...headers,
-          accept: "text/*, application/json, application/xml, application/xhtml+xml",
+          accept:
+            "image/png, image/jpeg, image/webp, text/*, application/json, application/xml, application/xhtml+xml",
         },
         redirect: "manual",
         signal: AbortSignal.timeout(SLACK_TIMEOUT_MS),
@@ -1921,6 +1954,15 @@ export class OpenGeniSlackBotClient {
   }
 }
 
+/** Full decode guards the model image block against header-only or corrupt files. */
+export async function validateSlackMcpImage(bytes: Uint8Array): Promise<void> {
+  try {
+    await sharp(bytes, { limitInputPixels: 16_000_000, failOn: "error" }).stats();
+  } catch {
+    throw new SlackBotProviderError("invalid_file_content");
+  }
+}
+
 export function createOpenGeniSlackBotClient(
   deps: {
     db: Database;

package/src/integrations/social-oauth.ts

@@ -36,8 +36,10 @@ import { ApiHttpError } from "../http/api-error";
 import { requireConnectOwnerAuthority } from "./connect-authority";
 import {
   integrationBaseUrl,
+  oauthStateFailureReturn,
   oauthStateTtlMs,
   requireIntegrationsStateSecret,
+  workspaceIntegrationsPath,
 } from "./oauth-client";
 
 // Reddit requires a descriptive, stable User-Agent on every request (token
@@ -200,7 +202,9 @@ export async function startSocialOAuth(
   await withOrganizationIntegrationAcquisition(deps.db, context, [provider.id], async () => {});
   const client = socialOAuthClientFor(settings, provider.id);
   const redirectUri = socialOAuthRedirectUri(settings, context.requestUrl);
-  const returnPath = safeReturnPath(context.payload.returnPath ?? "/integrations");
+  const returnPath = safeReturnPath(
+    context.payload.returnPath ?? workspaceIntegrationsPath(context.workspaceId),
+  );
   const scopes = uniqueScopes(context.payload.scopes) ?? provider.defaultScopes;
   const verifier = provider.pkce ? randomBytes(32).toString("base64url") : null;
   // Require the encryption key for every provider (not just PKCE ones) so a
@@ -260,8 +264,9 @@ export async function completeSocialOAuthCallback(
     state = readSocialOAuthState(input.state, settings);
   } catch (error) {
     logSocialOAuthFailure(observability, "state_verify", state, error);
+    const failure = oauthStateFailureReturn(settings, input.state);
     return {
-      redirectTo: callbackReturnPath("/integrations", "error", { reason: "state_invalid" }),
+      redirectTo: callbackReturnPath(failure.returnPath, "error", { reason: failure.reason }),
     };
   }
   if (state.connectAttemptId) return completeSocialConnect(deps, state, input);

package/src/mcp/documents.ts

@@ -1,4 +1,5 @@
 import { searchKnowledgeEntries } from "@opengeni/core";
+import type { Settings } from "@opengeni/config";
 import { KnowledgeEntryListRequest } from "@opengeni/contracts";
 import type { DocumentServices } from "@opengeni/documents";
 import {
@@ -17,7 +18,7 @@ export function buildDocumentsMcpServer(
   accountId: string,
   workspaceId: string,
   documentServices: DocumentServices,
-  options: { knowledge: KnowledgeContext },
+  options: { knowledge: KnowledgeContext; settings?: Settings },
 ): McpServer {
   const context = options.knowledge;
   if (context.accountId !== accountId || context.workspaceId !== workspaceId)
@@ -39,7 +40,13 @@ export function buildDocumentsMcpServer(
         {
           type: "text",
           text: JSON.stringify(
-            await searchKnowledgeEntries(db, context, input, () => documentServices.embedder),
+            await searchKnowledgeEntries(
+              db,
+              context,
+              input,
+              () => documentServices.embedder,
+              options.settings,
+            ),
           ),
         },
       ],

package/src/mcp/files.ts

@@ -9,6 +9,7 @@ import {
 } from "@opengeni/core";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod/v4";
+import { userContentSignedGetUrlOptions } from "../http/user-content";
 
 /** Dedicated file MCP surface. The broad `opengeni` server never registers it. */
 export function buildFilesMcpServer(
@@ -63,7 +64,10 @@ export function buildFilesMcpServer(
         if (file.status !== "ready") {
           throw new Error(`file is ${file.status}`);
         }
-        const signed = await deps.objectStorage.createGetUrl({ key: file.objectKey });
+        const signed = await deps.objectStorage.createGetUrl({
+          key: file.objectKey,
+          ...userContentSignedGetUrlOptions(file.contentType, file.filename),
+        });
         // Principal-facing signed URL issuance is a metadata-only audit
         // fact, awaited before the URL leaves the platform. Never the URL/key.
         await recordAuditEvent(deps.db, {

package/src/mcp/first-party-tool-permissions.ts

@@ -117,6 +117,8 @@ export const FIRST_PARTY_TOOL_AUTHORIZATION = {
   browser_open: { sessionRequired: true, allOf: ["sessions:control"] },
   browser_tabs: { sessionRequired: true, allOf: ["sessions:control"] },
   browser_observe: { sessionRequired: true, allOf: ["sessions:read"] },
+  browser_read: { sessionRequired: true, allOf: ["sessions:read"] },
+  browser_screenshot: { sessionRequired: true, allOf: ["sessions:read"] },
   browser_act: { sessionRequired: true, allOf: ["sessions:control"] },
   browser_clipboard: { sessionRequired: true, allOf: ["sessions:read"] },
   browser_debug: { sessionRequired: true, allOf: ["sessions:read"] },
@@ -152,6 +154,10 @@ export const FIRST_PARTY_TOOL_AUTHORIZATION = {
     sessionRequired: true,
     allOf: ["workspace:read"],
   },
+  custom_mcp_setup_request: {
+    sessionRequired: true,
+    allOf: ["workspace:read"],
+  },
   github_connect_link: { allOf: ["github:use"] },
   github_repositories_list: { allOf: ["github:use"] },
   social_connections_list: { allOf: ["connections:read"] },

package/src/mcp/knowledge-entries.ts

@@ -142,7 +142,14 @@ export function registerKnowledgeEntryTools(
     },
     (input) =>
       run((context) =>
-        prepareKnowledgeSave(deps.db, context, input, () => deps.getDocumentServices().embedder),
+        prepareKnowledgeSave(
+          deps.db,
+          context,
+          input,
+          () => deps.getDocumentServices().embedder,
+          undefined,
+          deps.settings,
+        ),
       ),
   );
   server.registerTool(
@@ -159,7 +166,13 @@ export function registerKnowledgeEntryTools(
     },
     (input) =>
       run((context) =>
-        searchKnowledgeEntries(deps.db, context, input, () => deps.getDocumentServices().embedder),
+        searchKnowledgeEntries(
+          deps.db,
+          context,
+          input,
+          () => deps.getDocumentServices().embedder,
+          deps.settings,
+        ),
       ),
   );
   server.registerTool(

package/src/mcp/server.ts

@@ -187,7 +187,12 @@ import {
   searchCapabilityCatalogItems,
   type ResolvedSessionAuthorization,
 } from "@opengeni/core";
-import { recordWorkspaceUsage, requireLimit, workflowIdForSession } from "@opengeni/core";
+import {
+  recordWorkspaceUsage,
+  requireLimit,
+  resolveScheduledTaskPreflightModel,
+  workflowIdForSession,
+} from "@opengeni/core";
 import type { ApiRouteDeps } from "@opengeni/core";
 import {
   githubBindingStatus,
@@ -307,6 +312,7 @@ import { ensureSessionGroupReady as ensureViewerSessionGroupReady } from "../san
 import {
   createOpenGeniSlackBotClient,
   resolveSlackBotConnectionForTool,
+  type OpenGeniSlackBotClient,
 } from "../integrations/slack-bot";
 import { createFikenClient, resolveFikenConnectionForTool } from "../integrations/fiken";
 import {
@@ -574,6 +580,51 @@ class PolicyMcpServer extends McpServer {
   }
 }
 
+export function slackBotFileContentResult(
+  result: Awaited<ReturnType<OpenGeniSlackBotClient["fileContent"]>>,
+) {
+  if (!("image" in result)) {
+    return {
+      content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+      structuredContent: {
+        kind: "text" as const,
+        fileId: result.file.id,
+        contentType: result.contentType,
+        content: result.content,
+        sizeBytes: null,
+        nextOffset: result.nextOffset,
+      },
+    };
+  }
+  return {
+    structuredContent: {
+      kind: "image" as const,
+      fileId: result.file.id,
+      contentType: result.image.contentType,
+      content: null,
+      sizeBytes: result.image.bytes.byteLength,
+      nextOffset: null,
+    },
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify({
+          channel: result.channel,
+          file: result.file,
+          contentType: result.image.contentType,
+          sizeBytes: result.image.bytes.byteLength,
+          receipt: result.receipt,
+        }),
+      },
+      {
+        type: "image" as const,
+        mimeType: result.image.contentType,
+        data: Buffer.from(result.image.bytes).toString("base64"),
+      },
+    ],
+  };
+}
+
 export function buildOpenGeniMcpServer(
   deps: ApiRouteDeps,
   grant: AccessGrant,
@@ -1598,7 +1649,7 @@ export function buildOpenGeniMcpServer(
             workspaceId: grant.workspaceId,
             action: "agent_run:create",
             quantity: 1,
-            model: task.agentConfig.model ?? deps.settings.openaiModel,
+            model: await resolveScheduledTaskPreflightModel(deps.db, catalogSettings, task),
           });
         }
         const triggerToken = scheduledTaskTriggerToken(triggerId);
@@ -1944,7 +1995,7 @@ function registerSlackBotTools(
     "slack_bot_file_content",
     {
       description:
-        "Read a bounded page of UTF-8 text from a Slack file or canvas shared with a channel where the workspace-shared OpenGeni bot is already a member. For an embedded huddle transcript, also pass the shared canvas file ID as parentFileId so OpenGeni can verify the channel-to-canvas-to-transcript chain. Slack may still restrict a huddle transcript body to participants; that returns huddle_transcript_requires_participant_access. Private Slack URLs and credentials are never returned. Continue with nextOffset when truncated is true.",
+        "Read a bounded page of text or view a PNG, JPEG, or WebP image from a Slack file shared with a channel where the workspace-shared OpenGeni bot is already a member. Use the file ID from thread replies to view images in earlier thread messages. Images are returned as viewable content, only when directly shared to a non-shared channel, up to 640 KiB; offset must be 0. For an embedded huddle transcript, also pass the shared canvas file ID as parentFileId so OpenGeni can verify the channel-to-canvas-to-transcript chain. Slack may still restrict a huddle transcript body to participants; that returns huddle_transcript_requires_participant_access. Private Slack URLs and credentials are never returned. Continue with nextOffset for truncated text.",
       inputSchema: {
         connectionId: z4.string().uuid().optional(),
         channelId: z4.string().min(1).max(64),
@@ -1952,18 +2003,26 @@ function registerSlackBotTools(
         parentFileId: z4.string().min(1).max(64).optional(),
         offset: z4.number().int().min(0).max(4_000_000).optional(),
       },
+      outputSchema: {
+        kind: z4.enum(["text", "image"]),
+        fileId: z4.string(),
+        contentType: z4.string(),
+        content: z4.string().nullable(),
+        sizeBytes: z4.number().int().nullable(),
+        nextOffset: z4.number().int().nullable(),
+      },
+    },
+    async ({ connectionId, channelId, fileId, parentFileId, offset }) => {
+      const result = await (
+        await clientFor(connectionId)
+      ).fileContent({
+        channelId,
+        fileId,
+        ...(parentFileId ? { parentFileId } : {}),
+        ...(offset !== undefined ? { offset } : {}),
+      });
+      return slackBotFileContentResult(result);
     },
-    async ({ connectionId, channelId, fileId, parentFileId, offset }) =>
-      json(
-        await (
-          await clientFor(connectionId)
-        ).fileContent({
-          channelId,
-          fileId,
-          ...(parentFileId ? { parentFileId } : {}),
-          ...(offset !== undefined ? { offset } : {}),
-        }),
-      ),
   );
 
   server.registerTool(
@@ -2521,7 +2580,7 @@ function registerGoalTools(
     "goal_update",
     {
       description:
-        "Propose or apply a semantic goal revision under the session's mutation policy. Retain the standing goal unless explicit user direction or meaningful new evidence justifies the declared refinement, adaptation, or replacement. Every rewrite must use the exact expected objective revision and a concise rationale. Root constraints cannot be changed by an agent. A rewrite is not an execution-progress audit fact; use the optional goal_progress tool when such a fact should be recorded.",
+        "Maintain your operational goal as user direction or meaningful new evidence clarifies the intended outcome. Changes apply directly unless the user explicitly configured review_changes; refinement, adaptation, and replacement are audit classifications, not approval gates under the default policy. Use the exact expected objective revision and a concise rationale. Updating a goal grants no additional authority and cannot change root constraints. Use goal_progress for an execution-progress audit fact rather than a goal rewrite.",
       inputSchema: {
         text: goalText.optional(),
         successCriteria: successCriteriaSchema.nullable().optional(),
@@ -5854,9 +5913,14 @@ function registerCapabilityDiscoveryTools(
   // This is a readiness projection, never credential resolution or a new grant.
   const setupProjections = async (items: CapabilityCatalogItem[]) => {
     const availableServerIds = new Set<string>();
+    const availableFirstPartyTools = new Set<string>();
     const acceptedServerIds = new Set<string>();
     let accountSelectionKnown = false;
-    if (items.some((item) => item.enabled && item.connectionRef)) {
+    if (
+      items.some(
+        (item) => item.enabled && (item.connectionRef || item.surfaceType === "first_party_fiken"),
+      )
+    ) {
       const claims = exactAgentCommandContext(grant, sessionId);
       const attemptCatalog = await getAttemptToolCatalog(deps.db, {
         accountId: grant.accountId,
@@ -5868,7 +5932,11 @@ function registerCapabilityDiscoveryTools(
         attemptCatalog.turnId === claims.callerTurnId &&
         attemptCatalog.executionGeneration === claims.callerExecutionGeneration
       ) {
-        for (const entry of attemptCatalog.entries) availableServerIds.add(entry.identity.serverId);
+        for (const entry of attemptCatalog.entries) {
+          availableServerIds.add(entry.identity.serverId);
+          if (entry.identity.serverId === "opengeni")
+            availableFirstPartyTools.add(entry.identity.toolName);
+        }
         const bindings = await getSessionTurnMcpAccountBindings(
           deps.db,
           grant.workspaceId,
@@ -5890,6 +5958,8 @@ function registerCapabilityDiscoveryTools(
           availableServerIds,
           acceptedServerIds,
           accountSelectionKnown,
+          availableFirstPartyTools,
+          new Set((grant.metadata?.firstPartyMcpTools as string[] | undefined) ?? []),
         ),
       ),
     );
@@ -6015,6 +6085,72 @@ function registerCapabilityDiscoveryTools(
       });
     },
   );
+
+  server.registerTool(
+    "custom_mcp_setup_request",
+    {
+      description:
+        "Show a review card for a remote HTTPS MCP server that is not in the workspace catalog. Use only an endpoint supplied by the user or established by reliable documentation; do not invent a URL. Never include query parameters or secrets in this URL; the human can edit it in the protected setup form. The agent cannot add, enable, or contact the server. Search the catalog first and do not propose an already available integration.",
+      inputSchema: {
+        name: z4.string().trim().min(1).max(256),
+        endpointUrl: z4
+          .string()
+          .url()
+          .max(2048)
+          .refine((url) => {
+            const parsed = new URL(url);
+            return (
+              parsed.protocol === "https:" &&
+              !parsed.username &&
+              !parsed.password &&
+              !parsed.hash &&
+              !parsed.search
+            );
+          }),
+        rationale: z4.string().trim().min(1).max(2000),
+      },
+    },
+    async ({ name, endpointUrl, rationale }) => {
+      await authorize();
+      const current = await catalog();
+      const existing = current.items.find(
+        (item) => item.kind === "mcp" && item.endpointUrl === endpointUrl && !item.stale,
+      );
+      if (existing) {
+        return json({
+          status: "already_in_catalog",
+          capabilityId: existing.id,
+          message: "Use the catalog authorization flow for this server instead.",
+        });
+      }
+      const claims = exactAgentCommandContext(grant, sessionId);
+      const payload = ToolAuthNeededPayload.parse({
+        serverId: "opengeni",
+        toolName: "custom_mcp_setup_request",
+        providerDomain: new URL(endpointUrl).hostname,
+        reason: "missing_connection",
+        setupRequest: { kind: "mcp", name, endpointUrl, rationale },
+      });
+      const appended = await appendAndPublishTurnEventsFenced(
+        deps.db,
+        deps.bus,
+        grant.workspaceId,
+        sessionId,
+        claims.callerTurnId,
+        claims.callerExecutionGeneration,
+        claims.callerAttemptId,
+        [{ type: "tool.auth_needed", payload }],
+      );
+      if (!appended.accepted) {
+        throw new Error("The calling turn was replaced before the setup request committed.");
+      }
+      return json({
+        status: "setup_requested",
+        eventId: appended.events[0]?.id ?? null,
+        message: "The human review card was posted. No server was added or contacted.",
+      });
+    },
+  );
 }
 
 async function capabilitySetupProjection(
@@ -6024,7 +6160,45 @@ async function capabilitySetupProjection(
   availableServerIds: ReadonlySet<string>,
   acceptedServerIds: ReadonlySet<string>,
   accountSelectionKnown: boolean,
+  availableFirstPartyTools: ReadonlySet<string>,
+  selectedFirstPartyTools: ReadonlySet<string>,
 ): Promise<CapabilitySetupProjection> {
+  if (item.surfaceType === "first_party_fiken") {
+    if (!item.enabled || item.metadata.connectionStatus !== "active") {
+      return {
+        status: "authorization_required",
+        action: "connect",
+        detail:
+          item.metadata.connectionStatus === "needs_reauth"
+            ? "The workspace Fiken connection needs reconnection."
+            : "Connect Fiken through the protected setup form.",
+      };
+    }
+    const selected = FIRST_PARTY_MCP_TOOL_NAMES.filter(
+      (name) => name.startsWith("fiken_") && selectedFirstPartyTools.has(name),
+    );
+    if (selected.length === 0) {
+      return {
+        status: "authorization_required",
+        action: "enable",
+        detail:
+          "Fiken is connected, but its tools are not selected for this conversation. Ask the user to add its tools through the setup card, then send a new message.",
+      };
+    }
+    if (selected.some((name) => availableFirstPartyTools.has(name))) {
+      return {
+        status: "ready",
+        action: null,
+        detail: "Fiken is connected and has tools available in this turn.",
+      };
+    }
+    return {
+      status: "unavailable",
+      action: null,
+      detail:
+        "Fiken is connected, but its selected tools are unavailable in this execution. Check tool permissions and setup before retrying; reconnection is not required by this status.",
+    };
+  }
   if (item.id === "api:github-app" || item.surfaceType === "first_party_github") {
     const missing = githubAppMissingSettings(deps.settings);
     if (missing.length > 0) {

package/src/mcp-oauth.ts

@@ -41,7 +41,7 @@ import {
 } from "@opengeni/core";
 import { Hono, type Context } from "hono";
 import { HTTPException } from "hono/http-exception";
-import { trustedRequestSourceAddress } from "./http/request-source";
+import { trustedRequestSourceRateLimitKey, type RequestSourceTrust } from "./http/request-source";
 import {
   prepareWorkspaceToolGateway,
   requireWorkspaceToolGatewayAuthorization,
@@ -126,9 +126,7 @@ export function registerMcpOAuthRoutes(app: Hono, deps: ApiRouteDeps): void {
         clientName: parsed.data.client_name ?? null,
         grantTypes: parsed.data.grant_types,
         responseTypes: ["code"],
-        registrationScopeHash: tokenHash(
-          mcpOAuthRegistrationClientKey(c, deps.settings.mcpOauthTrustedProxyHops),
-        ),
+        registrationScopeHash: tokenHash(mcpOAuthRegistrationClientKey(c, deps.settings)),
       });
     } catch (error) {
       if (error instanceof McpOAuthClientRegistrationRateLimitError) {
@@ -626,8 +624,8 @@ function tokenHash(value: string): string {
   return createHash("sha256").update(value, "utf8").digest("hex");
 }
 
-function mcpOAuthRegistrationClientKey(c: Context, trustedProxyHops: number): string {
-  return `mcp-oauth-registration:${trustedRequestSourceAddress(c, trustedProxyHops)}`;
+function mcpOAuthRegistrationClientKey(c: Context, trust: RequestSourceTrust): string {
+  return `mcp-oauth-registration:${trustedRequestSourceRateLimitKey(c, trust)}`;
 }
 
 function expiresIn(seconds: number): Date {

package/src/model-catalog.ts

@@ -6,9 +6,14 @@ import {
 import {
   ClientModel,
   WorkspaceModelCatalogResponse,
+  type DefaultModelSelection,
   type WorkspaceModelCatalogResponse as WorkspaceModelCatalogResponseType,
 } from "@opengeni/contracts";
-import { resolveWorkspaceModelSelection, type WorkspaceModelSelectionInput } from "@opengeni/core";
+import {
+  resolveWorkspaceModelSelection,
+  type WorkspaceModelSelection,
+  type WorkspaceModelSelectionInput,
+} from "@opengeni/core";
 
 export {
   MODEL_CREDENTIAL_READINESS_OBSERVATION_MAX_AGE_MS,
@@ -81,12 +86,34 @@ export function projectClientModel(model: ConfiguredModel): ClientModel {
  */
 export function buildWorkspaceModelCatalog(
   input: WorkspaceModelSelectionInput,
+  defaults?: WorkspaceModelCatalogDefaults,
 ): WorkspaceModelCatalogResponseType {
-  const models = resolveWorkspaceModelSelection(input).map((selection) => ({
+  return projectWorkspaceModelCatalog(resolveWorkspaceModelSelection(input), defaults);
+}
+
+/** Resolved new-chat defaults published beside the catalog rows. */
+export type WorkspaceModelCatalogDefaults = {
+  defaultSelection: DefaultModelSelection;
+  creditsSelection: DefaultModelSelection | null;
+};
+
+export function projectWorkspaceModelCatalog(
+  selections: readonly WorkspaceModelSelection[],
+  defaults?: WorkspaceModelCatalogDefaults,
+): WorkspaceModelCatalogResponseType {
+  const models = selections.map((selection) => ({
     ...projectClientModel(selection.model),
     credentialReadiness: selection.credentialReadiness,
     policyAllowed: selection.policyAllowed,
     availability: selection.availability,
   }));
-  return WorkspaceModelCatalogResponse.parse({ models });
+  return WorkspaceModelCatalogResponse.parse({
+    models,
+    ...(defaults
+      ? {
+          defaultSelection: defaults.defaultSelection,
+          creditsSelection: defaults.creditsSelection,
+        }
+      : {}),
+  });
 }