@opengeni/core 4.0.1 → 4.0.3-canary.36199476632001

package/src/default-session-model.ts

@@ -0,0 +1,467 @@
+import {
+  canonicalizeConfiguredModelId,
+  type ConfiguredModel,
+  type Settings,
+} from "@opengeni/config";
+import {
+  resolveWorkspaceSessionDefaults,
+  type DefaultModelSelection,
+  type ReasoningEffort,
+  type ScheduledTask,
+  type WorkspaceSessionDefaults,
+  type XaiProviderAccountAuthoritySnapshotV1,
+} from "@opengeni/contracts";
+import {
+  getScheduledTaskXaiProviderAccountAuthoritySnapshot,
+  getSession,
+  getWorkspace,
+  getWorkspaceConnectionModelRestrictions,
+  getWorkspaceModelPolicy,
+  listOrganizationModelProviderCustomModelsForWorkspace,
+  listWorkspaceGatewayCustomModels,
+  listWorkspaceOpenRouterCustomModels,
+  organizationModelProviderConnectionActiveForWorkspace,
+  workspaceCodexSubscriptionActive,
+  workspaceOpenRouterConnectionActive,
+  workspaceVercelAiGatewayConnectionActive,
+  organizationHoldsCredits,
+  workspaceXaiSubscriptionActive,
+  workspaceXaiSubscriptionActiveForAuthority,
+  XaiAuthorityPoolInactiveError,
+  type ConnectionModelRestrictions,
+  type Database,
+} from "@opengeni/db";
+import {
+  resolveWorkspaceModelSelection,
+  type WorkspaceModelSelection,
+  type WorkspaceModelSelectionInput,
+} from "./model-catalog";
+
+const REASONING_EFFORT_ORDER: readonly ReasoningEffort[] = [
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+];
+
+function supportedReasoningEfforts(model: ConfiguredModel): ReasoningEffort[] {
+  const efforts = model.capabilities.reasoning.efforts;
+  return REASONING_EFFORT_ORDER.filter((effort) => efforts.includes(effort));
+}
+
+/** The model's own default effort, matching the web picker's choice. */
+export function defaultReasoningEffortForConfiguredModel(
+  model: ConfiguredModel,
+  fallback: ReasoningEffort,
+): ReasoningEffort {
+  const options = supportedReasoningEfforts(model);
+  if (options.length === 0) return fallback;
+  const configured = model.capabilities.reasoning.defaultEffort;
+  if (configured && options.includes(configured)) return configured;
+  return options[0]!;
+}
+
+/** The highest supported effort at or below `preferred`. */
+export function clampReasoningEffortForConfiguredModel(
+  model: ConfiguredModel,
+  preferred: ReasoningEffort,
+  fallback: ReasoningEffort,
+): ReasoningEffort {
+  const options = supportedReasoningEfforts(model);
+  if (options.length === 0) return fallback;
+  if (options.includes(preferred)) return preferred;
+  const ceiling = REASONING_EFFORT_ORDER.indexOf(preferred);
+  const below = options.filter((effort) => REASONING_EFFORT_ORDER.indexOf(effort) <= ceiling);
+  return below.at(-1) ?? defaultReasoningEffortForConfiguredModel(model, fallback);
+}
+
+function findSelection(
+  selections: readonly WorkspaceModelSelection[],
+  modelId: string,
+): WorkspaceModelSelection | undefined {
+  return (
+    selections.find((selection) => selection.model.id === modelId) ??
+    selections.find((selection) => selection.model.aliases.includes(modelId))
+  );
+}
+
+export type DefaultSessionModelInput = {
+  /** Catalog-resolved settings: `openaiModel` is the deployment default. */
+  settings: Settings;
+  /** This workspace's selection, in operator catalog order. */
+  selections: readonly WorkspaceModelSelection[];
+  workspaceDefaults: WorkspaceSessionDefaults | null;
+  /**
+   * True while the organization holds a positive OpenGeni credit balance from
+   * any source, the verified-signup trial grant included (see
+   * `organizationHoldsCredits`).
+   */
+  creditsAvailable: boolean;
+};
+
+function creditsCandidate(
+  input: Pick<DefaultSessionModelInput, "settings" | "selections">,
+): DefaultModelSelection | null {
+  const fallbackEffort = input.settings.openaiReasoningEffort;
+  const deployment = findSelection(input.selections, input.settings.openaiModel);
+  if (deployment?.availability.selectable && deployment.model.cost === "credits") return null;
+  const configured = findSelection(input.selections, input.settings.creditsDefaultModel);
+  if (configured?.availability.selectable && configured.model.cost === "credits") {
+    return {
+      model: configured.model.id,
+      reasoningEffort: clampReasoningEffortForConfiguredModel(
+        configured.model,
+        input.settings.creditsDefaultReasoningEffort,
+        fallbackEffort,
+      ),
+      source: "credits",
+    };
+  }
+  const first = input.selections.find(
+    (selection) => selection.availability.selectable && selection.model.cost === "credits",
+  );
+  return first
+    ? {
+        model: first.model.id,
+        reasoningEffort: defaultReasoningEffortForConfiguredModel(first.model, fallbackEffort),
+        source: "credits",
+      }
+    : null;
+}
+
+/**
+ * Default model policy for a new chat or scheduled task that names no model.
+ *
+ * Precedence, first match wins:
+ *
+ * 1. `workspace`: the saved workspace default (`settings.sessionDefaults`)
+ *    while it is selectable in this workspace, its saved effort clamped to
+ *    what the model supports today.
+ * 2. `subscription`: the first selectable connected-subscription model
+ *    (ChatGPT/Codex, then SuperGrok) in operator catalog order. The
+ *    deployment default wins inside this step when it is itself a selectable
+ *    subscription model.
+ * 3. `credits`: while the organization holds a positive OpenGeni credit
+ *    balance (a purchase, a grant, or the verified-signup trial grant), the
+ *    configured credits default (`OPENGENI_CREDITS_DEFAULT_MODEL`, effort
+ *    clamped to what the model supports), or the first selectable
+ *    credits-billed model when that one is not selectable. Skipped when the
+ *    deployment default is already a selectable credits-billed model, so an
+ *    operator's paid default is never replaced.
+ * 4. `deployment`: the deployment default with the deployment reasoning effort.
+ *
+ * An explicit model on the request, the scheduled task, or the person's
+ * new-chat draft is never passed through this function.
+ */
+export function selectDefaultSessionModel(input: DefaultSessionModelInput): DefaultModelSelection {
+  const fallbackEffort = input.settings.openaiReasoningEffort;
+  if (input.workspaceDefaults) {
+    const saved = findSelection(input.selections, input.workspaceDefaults.model);
+    if (saved?.availability.selectable) {
+      return {
+        model: saved.model.id,
+        reasoningEffort: clampReasoningEffortForConfiguredModel(
+          saved.model,
+          input.workspaceDefaults.reasoningEffort,
+          fallbackEffort,
+        ),
+        source: "workspace",
+      };
+    }
+  }
+  const deployment = findSelection(input.selections, input.settings.openaiModel);
+  const subscription =
+    deployment?.availability.selectable && deployment.model.cost === "subscription"
+      ? deployment
+      : input.selections.find(
+          (selection) =>
+            selection.availability.selectable && selection.model.cost === "subscription",
+        );
+  if (subscription) {
+    return {
+      model: subscription.model.id,
+      reasoningEffort: defaultReasoningEffortForConfiguredModel(subscription.model, fallbackEffort),
+      source: "subscription",
+    };
+  }
+  if (input.creditsAvailable) {
+    const credits = creditsCandidate(input);
+    if (credits) return credits;
+  }
+  return {
+    model:
+      deployment?.model.id ??
+      canonicalizeConfiguredModelId(input.settings, input.settings.openaiModel),
+    reasoningEffort: fallbackEffort,
+    source: "deployment",
+  };
+}
+
+/**
+ * The default this workspace would use while its organization holds a
+ * positive OpenGeni credit balance. Null when the deployment does not bill
+ * credits.
+ */
+export function creditsDefaultSessionModel(input: {
+  settings: Settings;
+  selections: readonly WorkspaceModelSelection[];
+  workspaceSettings: unknown;
+}): DefaultModelSelection | null {
+  if (input.settings.billingMode !== "stripe") return null;
+  return selectDefaultSessionModel({
+    settings: input.settings,
+    selections: input.selections,
+    workspaceDefaults: resolveWorkspaceSessionDefaults(input.workspaceSettings),
+    creditsAvailable: true,
+  });
+}
+
+/**
+ * Resolve the default for an already-loaded workspace selection. The credit
+ * ledger is read only when it can change the answer.
+ */
+export async function resolveDefaultSessionModelForSelections(
+  db: Database,
+  input: {
+    settings: Settings;
+    accountId: string;
+    workspaceSettings: unknown;
+    selections: readonly WorkspaceModelSelection[];
+  },
+): Promise<DefaultModelSelection> {
+  const decision = {
+    settings: input.settings,
+    selections: input.selections,
+    workspaceDefaults: resolveWorkspaceSessionDefaults(input.workspaceSettings),
+  };
+  const withoutCredits = selectDefaultSessionModel({ ...decision, creditsAvailable: false });
+  if (
+    withoutCredits.source !== "deployment" ||
+    input.settings.billingMode !== "stripe" ||
+    creditsCandidate(decision) === null
+  ) {
+    return withoutCredits;
+  }
+  return (await organizationHoldsCredits(db, input.accountId))
+    ? selectDefaultSessionModel({ ...decision, creditsAvailable: true })
+    : withoutCredits;
+}
+
+export type WorkspaceModelSelectionContext = {
+  accountId: string;
+  workspaceId: string;
+  /**
+   * The subject whose connected-subscription authority applies: the
+   * authenticated caller for direct creates, or a scheduled task's immutable
+   * execution owner. Never another member.
+   */
+  subjectId: string;
+  /**
+   * An already-frozen SuperGrok authority (a scheduled task's snapshot).
+   * Omitted means the subject's current acceptance authority, exactly as a
+   * direct Send resolves it.
+   */
+  xaiAuthoritySnapshot?: XaiProviderAccountAuthoritySnapshotV1 | undefined;
+};
+
+/**
+ * Connection restrictions and SuperGrok readiness for the subject. With a
+ * frozen authority (a scheduled task's snapshot), a user pool that no longer
+ * resolves (disconnected, reconnected under a new authority generation, or its
+ * owner left) means SuperGrok is not ready: no SuperGrok model is selectable,
+ * and resolution falls through to credits or the deployment default instead of
+ * failing the occurrence. The frozen authority is never swapped for the
+ * subject's current one; the SuperGrok restriction is closed outright, while
+ * the other providers' restrictions do not depend on SuperGrok authority.
+ */
+async function connectionRestrictionsAndXaiReadiness(
+  db: Database,
+  settings: Settings,
+  context: WorkspaceModelSelectionContext,
+): Promise<{ restrictions: ConnectionModelRestrictions; xaiSubscriptionActive: boolean }> {
+  const { workspaceId, subjectId, xaiAuthoritySnapshot } = context;
+  if (!xaiAuthoritySnapshot) {
+    const [restrictions, xaiSubscriptionActive] = await Promise.all([
+      getWorkspaceConnectionModelRestrictions(db, workspaceId, subjectId),
+      workspaceXaiSubscriptionActive(db, settings, workspaceId, subjectId),
+    ]);
+    return { restrictions, xaiSubscriptionActive };
+  }
+  const frozen = await Promise.allSettled([
+    getWorkspaceConnectionModelRestrictions(db, workspaceId, subjectId, xaiAuthoritySnapshot),
+    workspaceXaiSubscriptionActiveForAuthority(db, settings, {
+      workspaceId,
+      subjectId,
+      authoritySnapshot: xaiAuthoritySnapshot,
+    }),
+  ]);
+  const [restrictions, readiness] = frozen;
+  if (restrictions.status === "fulfilled" && readiness.status === "fulfilled") {
+    return { restrictions: restrictions.value, xaiSubscriptionActive: readiness.value };
+  }
+  for (const result of frozen) {
+    if (result.status === "rejected" && !(result.reason instanceof XaiAuthorityPoolInactiveError)) {
+      throw result.reason;
+    }
+  }
+  const current = await getWorkspaceConnectionModelRestrictions(db, workspaceId, subjectId);
+  return {
+    restrictions: { ...current, "supergrok/": [] },
+    xaiSubscriptionActive: false,
+  };
+}
+
+/** Load the same inputs the workspace model catalog route evaluates. */
+export async function loadWorkspaceModelSelectionInput(
+  db: Database,
+  settings: Settings,
+  context: WorkspaceModelSelectionContext,
+): Promise<WorkspaceModelSelectionInput> {
+  const { accountId, workspaceId } = context;
+  const [
+    { restrictions: connectionModelRestrictions, xaiSubscriptionActive },
+    policy,
+    codexSubscriptionActive,
+    workspaceGatewayConnectionActive,
+    workspaceGatewayCustomModels,
+    openRouterConnectionActive,
+    workspaceOpenRouterCustomModels,
+    organizationGatewayConnectionActive,
+    organizationOpenRouterConnectionActive,
+    organizationGatewayCustomModels,
+    organizationOpenRouterCustomModels,
+  ] = await Promise.all([
+    connectionRestrictionsAndXaiReadiness(db, settings, context),
+    getWorkspaceModelPolicy(db, workspaceId),
+    workspaceCodexSubscriptionActive(db, settings, workspaceId),
+    workspaceVercelAiGatewayConnectionActive(db, workspaceId),
+    listWorkspaceGatewayCustomModels(db, { accountId, workspaceId }),
+    workspaceOpenRouterConnectionActive(db, workspaceId),
+    listWorkspaceOpenRouterCustomModels(db, { accountId, workspaceId }),
+    organizationModelProviderConnectionActiveForWorkspace(db, {
+      accountId,
+      workspaceId,
+      providerKind: "vercel_gateway",
+    }),
+    organizationModelProviderConnectionActiveForWorkspace(db, {
+      accountId,
+      workspaceId,
+      providerKind: "openrouter",
+    }),
+    listOrganizationModelProviderCustomModelsForWorkspace(db, {
+      accountId,
+      workspaceId,
+      providerKind: "vercel_gateway",
+    }),
+    listOrganizationModelProviderCustomModelsForWorkspace(db, {
+      accountId,
+      workspaceId,
+      providerKind: "openrouter",
+    }),
+  ]);
+  return {
+    connectionModelRestrictions,
+    settings,
+    policy,
+    codexSubscriptionActive,
+    xaiSubscriptionActive,
+    workspaceGatewayConnectionActive,
+    workspaceGatewayCustomModels,
+    workspaceOpenRouterConnectionActive: openRouterConnectionActive,
+    workspaceOpenRouterCustomModels,
+    organizationGatewayConnectionActive,
+    organizationOpenRouterConnectionActive,
+    organizationGatewayCustomModels,
+    organizationOpenRouterCustomModels,
+  };
+}
+
+/**
+ * Server-side default for new work that names no model: API and Slack session
+ * creates, new-chat drafts that follow the default, and scheduled-task
+ * occurrences. The result is resolved once and then frozen by the accepted
+ * session or occurrence like any other model choice.
+ */
+export async function resolveDefaultSessionModel(
+  db: Database,
+  settings: Settings,
+  context: WorkspaceModelSelectionContext & { workspaceSettings?: unknown },
+): Promise<DefaultModelSelection> {
+  const [selectionInput, workspaceSettings] = await Promise.all([
+    loadWorkspaceModelSelectionInput(db, settings, context),
+    context.workspaceSettings !== undefined
+      ? Promise.resolve(context.workspaceSettings)
+      : getWorkspace(db, context.workspaceId).then((workspace) => workspace?.settings ?? {}),
+  ]);
+  return await resolveDefaultSessionModelForSelections(db, {
+    settings,
+    accountId: context.accountId,
+    workspaceSettings,
+    selections: resolveWorkspaceModelSelection(selectionInput),
+  });
+}
+
+/**
+ * The default a scheduled occurrence uses when its task names no model and the
+ * occurrence creates its own session: resolved under the task's immutable
+ * execution owner (or its creator for a workspace/service task) and the task's
+ * frozen SuperGrok authority, never another member's. The worker stamps the
+ * result onto the accepted execution, so retries and recovery replay it; the
+ * API's manual-trigger limit check uses the same resolution so it gates the
+ * model that will run.
+ */
+export async function resolveScheduledTaskDefaultModel(
+  db: Database,
+  settings: Settings,
+  task: Pick<ScheduledTask, "id" | "accountId" | "workspaceId" | "ownerSubjectId" | "createdBy">,
+): Promise<DefaultModelSelection> {
+  return await resolveDefaultSessionModel(db, settings, {
+    accountId: task.accountId,
+    workspaceId: task.workspaceId,
+    subjectId: task.ownerSubjectId ?? task.createdBy.subjectId,
+    xaiAuthoritySnapshot: await getScheduledTaskXaiProviderAccountAuthoritySnapshot(
+      db,
+      task.workspaceId,
+      task.id,
+    ),
+  });
+}
+
+/**
+ * The model a manual trigger's limit pre-check evaluates, matching what the
+ * occurrence will run: the task's explicit model, else the target or reusable
+ * session's model when that session exists, else the resolved scheduled
+ * default. The worker still resolves authoritatively at dispatch.
+ */
+export async function resolveScheduledTaskPreflightModel(
+  db: Database,
+  settings: Settings,
+  task: Pick<
+    ScheduledTask,
+    | "id"
+    | "accountId"
+    | "workspaceId"
+    | "ownerSubjectId"
+    | "createdBy"
+    | "agentConfig"
+    | "runMode"
+    | "targetSessionId"
+    | "reusableSessionId"
+  >,
+): Promise<string> {
+  if (task.agentConfig.model) return task.agentConfig.model;
+  const targetSessionId =
+    task.runMode === "existing_session"
+      ? task.targetSessionId
+      : task.runMode === "reusable_session"
+        ? task.reusableSessionId
+        : null;
+  if (targetSessionId) {
+    const session = await getSession(db, task.workspaceId, targetSessionId);
+    if (session) return session.model;
+  }
+  return (await resolveScheduledTaskDefaultModel(db, settings, task)).model;
+}

package/src/domain/capabilities.ts

@@ -4,6 +4,7 @@ import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import { isDeepStrictEqual } from "node:util";
 import { withLockedCapabilityInstallation } from "@opengeni/db/capability-reconciliation";
 import { environmentsEncryptionKeyBytes, type Settings } from "@opengeni/config";
+import { pinnedFetch } from "@opengeni/network";
 import {
   CapabilityCatalogItem,
   capabilityCatalogItemIsTrustedForExposure,
@@ -344,7 +345,12 @@ export async function prepareCapabilityEnable(input: EnableCapabilityInput) {
       ...installationMetadata,
       ...(connectionRef && !headers
         ? authDeferredMcpConnectivity()
-        : await validateMcpCapabilityConnection(item, input.probeMcpServer, headers ?? undefined)),
+        : await validateMcpCapabilityConnection(
+            item,
+            input.probeMcpServer,
+            headers ?? undefined,
+            input.settings,
+          )),
     };
     if (connectionRef) {
       installationConfig.connectionRef = connectionRef;
@@ -669,6 +675,7 @@ export type McpCapabilityProbeInput = {
   url: string;
   timeoutMs: number;
   headers?: Record<string, string>;
+  settings?: Settings;
 };
 
 export type McpCapabilityProbeResult = {
@@ -683,6 +690,7 @@ export async function validateMcpCapabilityConnection(
   item: CapabilityCatalogItem,
   probe: McpCapabilityProbe = probeStreamableHttpMcpServer,
   headers?: Record<string, string>,
+  settings?: Settings,
 ): Promise<Record<string, unknown>> {
   if (item.kind !== "mcp") {
     return {};
@@ -699,6 +707,7 @@ export async function validateMcpCapabilityConnection(
       url: item.endpointUrl,
       timeoutMs: mcpCapabilityProbeTimeoutMs,
       ...(headers ? { headers } : {}),
+      ...(settings ? { settings } : {}),
     });
     return {
       mcpConnectivity: {
@@ -717,6 +726,8 @@ export async function validateMcpCapabilityConnection(
 async function probeStreamableHttpMcpServer(
   input: McpCapabilityProbeInput,
 ): Promise<McpCapabilityProbeResult> {
+  const settings = input.settings;
+  if (!settings) throw new Error("Network policy is unavailable for MCP validation");
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), input.timeoutMs);
   const client = new Client(
@@ -729,6 +740,11 @@ async function probeStreamableHttpMcpServer(
         signal: controller.signal,
         ...(input.headers ? { headers: input.headers } : {}),
       },
+      fetch: (url, init) =>
+        pinnedFetch(url, init, settings, {
+          label: "MCP capability probe",
+          requireHttpsOutsideLocalTest: true,
+        }),
     });
     await client.connect(transport as unknown as Transport, {
       timeout: input.timeoutMs,
@@ -1314,6 +1330,7 @@ function fikenCatalogItem(fikenConnections: ConnectionMetadata[]): CapabilityCat
     metadata: {
       connectorMode: "first_party_fiken",
       ownership: "workspace",
+      connectionStatus: fikenConnection?.status ?? null,
       // Derived from the contracts catalog so a new fiken_* tool cannot be
       // registered without also appearing on the capability tile.
       firstPartyMcpTools: FIRST_PARTY_MCP_TOOL_NAMES.filter((name) => name.startsWith("fiken_")),
@@ -1563,6 +1580,11 @@ export function applyCapabilityEnablement(
   item: CapabilityCatalogItem,
   installation: CapabilityInstallation | undefined,
 ): CapabilityCatalogItem {
+  if (item.surfaceType === "first_party_fiken") {
+    // Fiken is an API item with connection-derived state, not a generic API
+    // installation. Preserve that state before the non-MCP fallback below.
+    return { ...item, connectionRef: null };
+  }
   if (item.kind === "skill" || item.kind === "api" || item.kind === "plugin") {
     return { ...item, enabled: false, enabledReason: null, connectionRef: null };
   }
@@ -1572,12 +1594,6 @@ export function applyCapabilityEnablement(
     // publishes a personal connection UUID or collapses many accounts to one.
     return { ...item, connectionRef: null };
   }
-  if (item.surfaceType === "first_party_fiken") {
-    // Fiken connector state is derived from the authoritative workspace
-    // connection row while the catalog is built; browseable never means an
-    // account is already connected.
-    return { ...item, connectionRef: null };
-  }
   if (item.surfaceType === "codex_apps") {
     // Unlike ordinary built-ins, Apps availability is derived from the exact
     // active workspace designation above. Do not overwrite it with the

package/src/domain/knowledge-preparation.test.ts

@@ -221,6 +221,31 @@ test("published and pending searches reuse one query embedding", async () => {
   expect(calls).toBe(1);
 });
 
+test("a keyword fallback in the first view never retries an unfunded provider in the review view", async () => {
+  const searches: Array<{ mode: string | undefined; settingsProvided: boolean }> = [];
+  await prepareKnowledgeSave(
+    db,
+    context,
+    { query: "Acme renewal" },
+    () => {
+      throw new Error("An unfunded provider was called");
+    },
+    {
+      list: async () => ({ entries: [], nextCursor: null }),
+      get: async () => null,
+      search: async (_db, _context, request, _embedder, settings) => {
+        searches.push({ mode: request.mode, settingsProvided: !!settings });
+        return { entries: [], nextCursor: null, searchMode: "keyword" };
+      },
+    },
+    { documentEmbeddingProvider: "openai", documentEmbeddingBillingMode: "credits" } as never,
+  );
+  expect(searches).toEqual([
+    { mode: "keyword", settingsProvided: false },
+    { mode: "keyword", settingsProvided: false },
+  ]);
+});
+
 test("catalog rechecks current metadata after a collection changes", async () => {
   const old = group("Old name");
   const current = {

package/src/domain/knowledge-preparation.ts

@@ -9,6 +9,8 @@ import {
   type KnowledgeContext,
 } from "@opengeni/db";
 import type { DocumentEmbedder } from "@opengeni/documents";
+import type { Settings } from "@opengeni/config";
+import { paidDocumentEmbedding } from "../billing/limits";
 import { searchKnowledgeEntries } from "./knowledge-search";
 
 const defaults = {
@@ -29,6 +31,7 @@ export async function prepareKnowledgeSave(
   input: KnowledgeSavePreparationRequest,
   embedder: () => DocumentEmbedder,
   services = defaults,
+  settings?: Settings,
 ): Promise<KnowledgeSavePreparationResponse> {
   const request = KnowledgeSavePreparationRequest.parse(input);
   if (context.actor.kind !== "agent" && !(context.actor.kind === "human" && context.actor.review)) {
@@ -56,20 +59,38 @@ export async function prepareKnowledgeSave(
   };
   // Search is independent of collection placement and always includes the
   // separate unapproved view. No authoring policy or write is invoked here.
-  const matches = {
-    published: await services.search(
-      db,
-      context,
-      { query: request.query, limit: request.limit, view: "published" },
-      sharedEmbedder,
-    ),
-    needs_review: await services.search(
-      db,
-      context,
-      { query: request.query, limit: request.limit, view: "needs_review" },
-      sharedEmbedder,
-    ),
-  };
+  // Preparation returns BOTH views plus a catalog. A charge on the first
+  // semantic search would precede the second view and catalog; any later
+  // failure would leave no deliverable preparation result. Paid mode uses
+  // keyword discovery until a single-operation settlement seam exists.
+  const paid = settings != null && paidDocumentEmbedding(settings);
+  const published = await services.search(
+    db,
+    context,
+    {
+      query: request.query,
+      limit: request.limit,
+      view: "published",
+      ...(paid ? { mode: "keyword" as const } : {}),
+    },
+    sharedEmbedder,
+    paid ? undefined : settings,
+  );
+  // Reuse the first request's provider result (and charge). If it fell back
+  // to keyword because funding or the provider was unavailable, do not retry
+  // an unfunded embedding request in the second review view.
+  const needsReview = await services.search(
+    db,
+    context,
+    {
+      query: request.query,
+      limit: request.limit,
+      view: "needs_review",
+      ...(published.searchMode === "keyword" ? { mode: "keyword" as const } : {}),
+    },
+    sharedEmbedder,
+  );
+  const matches = { published, needs_review: needsReview };
   for (const view of ["published", "needs_review"] as const) {
     if (request.collectionCursors && request.collectionCursors[view] === null) continue;
     let cursor = request.collectionCursors?.[view] ?? undefined;