@larkup/workspace-server 0.0.0-stage → 0.2.0

package/src/lib/chat/media-source-routing.ts

@@ -0,0 +1,100 @@
+import { buildQueryTermMatchers, countMatchesIn } from './retrieval-ranking';
+
+export type RoutableMediaAsset = {
+  id: string;
+  fileName: string;
+  originalUrl?: string;
+  processingStatus: string;
+  activeVideoKnowledgeRevisionId?: string;
+  type: string;
+  documentIds: string[];
+};
+
+/** Select a title only when it has a clear lexical lead over every other source. */
+export function clearlyTitleMatchedMediaAsset<T extends RoutableMediaAsset>(
+  query: string,
+  assets: readonly T[],
+): T | undefined {
+  const matchers = buildQueryTermMatchers(query);
+  if (matchers.length === 0) return undefined;
+  const ranked = assets
+    .map((asset) => ({ asset, matches: countMatchesIn(matchers, asset.fileName) }))
+    .filter(({ matches }) => matches >= Math.min(2, matchers.length))
+    .sort((left, right) => right.matches - left.matches);
+  if (ranked.length === 0) return undefined;
+  if (ranked.length > 1 && ranked[0].matches === ranked[1].matches) return undefined;
+  return ranked[0].asset;
+}
+
+/**
+ * Before ordinary retrieval runs, media may become authoritative only when
+ * the question explicitly names it. A sole video is a safe fallback after a
+ * retrieval miss, but it must never pre-empt a document or tabular hit.
+ */
+export function explicitlySelectedMediaAsset<T extends RoutableMediaAsset>(
+  query: string,
+  assets: readonly T[],
+): T | undefined {
+  return clearlyTitleMatchedMediaAsset(query, assets);
+}
+
+/**
+ * Detect an explicitly named source that exists but is outside the Assistant
+ * source scope. A generic single-source fallback must not silently replace it
+ * with an unrelated enabled recording.
+ */
+export function clearlyUnavailableTitleMatchedMediaAsset<T extends RoutableMediaAsset>(
+  query: string,
+  availableAssets: readonly T[],
+  allAssets: readonly T[],
+): T | undefined {
+  const matched = clearlyTitleMatchedMediaAsset(query, allAssets);
+  if (!matched) return undefined;
+  return availableAssets.some((asset) => asset.id === matched.id) ? undefined : matched;
+}
+
+/**
+ * A conversation carries a source selection as structured state. Once a
+ * source is selected, do not reinterpret ordinary user prose in an attempt
+ * to switch it: that is language- and genre-dependent, and can silently send
+ * a precise question to a different recording. A source switch must be
+ * represented by a new selected source in the conversation.
+ */
+export function shouldKeepActiveMediaSource<T extends RoutableMediaAsset>(
+  _query: string,
+  activeAsset: T,
+  availableAssets: readonly T[],
+) {
+  return availableAssets.some((asset) => asset.id === activeAsset.id);
+}
+
+/** A conversational follow-up stays on its active source and skips global reranking. */
+export function activeMediaFollowUpResult(
+  query: string,
+  asset: RoutableMediaAsset,
+  indexedContext?: string,
+) {
+  const context = indexedContext?.trim();
+  return {
+    query,
+    hits: [
+      {
+        title: asset.fileName,
+        url: `/api/media/${encodeURIComponent(asset.id)}`,
+        score: 1,
+        text: context ?? '',
+        ...(context ? { context } : {}),
+        metadata: {
+          mediaAssetId: asset.id,
+          mediaType: asset.type,
+          fileName: asset.fileName,
+        },
+      },
+    ],
+    videoEvidence: {
+      mediaAssetId: asset.id,
+      fileName: asset.fileName,
+      retrievalFallback: 'active-conversation-media-source' as const,
+    },
+  };
+}

package/src/lib/chat/message-input.ts

@@ -0,0 +1,48 @@
+type IncomingMessage = Record<string, unknown> & {
+  id?: unknown;
+  role?: unknown;
+  parts?: unknown;
+  content?: unknown;
+};
+
+/** Accept UI messages and the common curl-friendly `{ role, content }` shape. */
+export function normalizeIncomingMessages(value: unknown) {
+  if (!Array.isArray(value)) return [];
+
+  return value.flatMap((candidate, index) => {
+    if (!candidate || typeof candidate !== 'object') return [];
+    const message = candidate as IncomingMessage;
+    if (!['user', 'assistant', 'system'].includes(String(message.role ?? ''))) return [];
+
+    const suppliedParts = Array.isArray(message.parts)
+      ? message.parts.filter(
+          (part): part is Record<string, unknown> =>
+            Boolean(part) && typeof part === 'object' && typeof (part as any).type === 'string',
+        )
+      : [];
+    const contentParts = Array.isArray(message.content)
+      ? message.content.filter(
+          (part): part is Record<string, unknown> =>
+            Boolean(part) && typeof part === 'object' && typeof (part as any).type === 'string',
+        )
+      : [];
+    const parts =
+      suppliedParts.length > 0
+        ? suppliedParts
+        : contentParts.length > 0
+          ? contentParts
+          : typeof message.content === 'string' && message.content.trim()
+            ? [{ type: 'text', text: message.content }]
+            : [];
+    if (parts.length === 0) return [];
+
+    return [
+      {
+        ...message,
+        id: typeof message.id === 'string' && message.id.trim() ? message.id : `incoming-${index}`,
+        role: message.role as 'user' | 'assistant' | 'system',
+        parts,
+      },
+    ];
+  });
+}

package/src/lib/chat/model-provider.ts

@@ -0,0 +1,157 @@
+import { createAnthropic } from '@ai-sdk/anthropic';
+import { createCohere } from '@ai-sdk/cohere';
+import { createDeepSeek } from '@ai-sdk/deepseek';
+import { createGateway } from '@ai-sdk/gateway';
+import { createGoogleGenerativeAI } from '@ai-sdk/google';
+import { createMistral } from '@ai-sdk/mistral';
+import { createOpenAI } from '@ai-sdk/openai';
+import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
+import {
+  getDefaultChatModel,
+  getDefaultVisionModel,
+  normalizeNativeChatModelId,
+  toChatDescriptor,
+} from '@larkup/core/chat-models/registry';
+import type { GatewayModel } from '@larkup/core/models-cache';
+import type { CustomModelConfig, RagConfig } from '@larkup/core/types';
+
+const FALLBACK_CHAT_MODELS: Record<string, string> = {
+  openai: 'openai/gpt-4o-mini',
+  anthropic: 'anthropic/claude-3-5-sonnet-latest',
+  google: 'google/gemini-3.6-flash',
+  cohere: 'cohere/command-r-plus',
+  mistral: 'mistral/mistral-large-latest',
+  deepseek: 'deepseek/deepseek-chat',
+};
+
+export interface ResolvedChatModel {
+  provider: string;
+  modelId: string;
+  apiKey?: string;
+}
+
+export interface ResolveChatModelOptions {
+  requiredTag?: string;
+}
+
+/**
+ * Resolve an LLM from persisted settings. The configured provider is
+ * authoritative: a gateway key must never be passed to a model vendor SDK.
+ */
+export function resolveConfiguredChatModel(
+  config: RagConfig,
+  availableModels: GatewayModel[] = [],
+  options: ResolveChatModelOptions = {},
+): ResolvedChatModel {
+  const provider = config.chatProvider || config.embeddingProvider || 'openai';
+  let modelId = config.chatModelId?.trim();
+
+  if (!modelId && provider === 'custom' && config.customChatModels?.[0]) {
+    modelId = `custom:${config.customChatModels[0].modelName}`;
+  }
+
+  if (!modelId && availableModels.length > 0) {
+    const requiredTag = options.requiredTag;
+    const taggedModels = requiredTag
+      ? availableModels.filter((model) => model.tags?.includes(requiredTag))
+      : availableModels;
+    const candidates = taggedModels.length > 0 ? taggedModels : availableModels;
+    modelId = getDefaultChatModel(candidates.map(toChatDescriptor), provider)?.id;
+  }
+
+  if (!modelId && provider === 'vercel_ai_gateway') {
+    throw new Error('No gateway model is available. Choose a chat model before processing media.');
+  }
+
+  modelId = normalizeNativeChatModelId(provider, modelId);
+  modelId ||= FALLBACK_CHAT_MODELS[provider] || FALLBACK_CHAT_MODELS.openai;
+
+  return {
+    provider,
+    modelId,
+    apiKey: config.chatApiKey || config.embeddingApiKey || undefined,
+  };
+}
+
+/**
+ * Resolve the workspace-wide vision-language model. Image-capable tools share
+ * this setting so they do not accidentally run on a text-only chat model.
+ */
+export function resolveConfiguredVisionModel(
+  config: RagConfig,
+  availableModels: GatewayModel[] = [],
+): ResolvedChatModel {
+  const provider =
+    config.visionProvider || config.chatProvider || config.embeddingProvider || 'openai';
+  let modelId = config.visionModelId?.trim();
+  const customModels = config.customVisionModels ?? [];
+
+  if (!modelId && provider === 'custom' && customModels[0]) {
+    modelId = `custom:${customModels[0].modelName}`;
+  }
+
+  if (!modelId) {
+    modelId = getDefaultVisionModel(availableModels.map(toChatDescriptor), provider)?.id;
+  }
+
+  if (!modelId) {
+    throw new Error(
+      `No vision-capable model is available for ${provider}. Configure a Vision Model in Settings → AI Models.`,
+    );
+  }
+
+  const chatProvider = config.chatProvider || config.embeddingProvider;
+  const apiKey =
+    config.visionApiKey ||
+    (provider === chatProvider ? config.chatApiKey : undefined) ||
+    (provider === config.embeddingProvider ? config.embeddingApiKey : undefined);
+
+  return { provider, modelId: normalizeNativeChatModelId(provider, modelId)!, apiKey };
+}
+
+export function createChatModel(
+  provider: string,
+  modelId: string,
+  apiKey?: string,
+  customChatModels: CustomModelConfig[] = [],
+): ReturnType<ReturnType<typeof createOpenAI>> {
+  if (modelId.startsWith('custom:')) {
+    const customName = modelId.slice('custom:'.length);
+    const custom = customChatModels.find((candidate) => candidate.modelName === customName);
+    if (!custom) {
+      throw new Error(`Custom chat model "${customName}" is not configured.`);
+    }
+
+    const customProvider = createOpenAICompatible({
+      name: 'custom_chat_provider',
+      baseURL: custom.baseUrl,
+      apiKey: custom.apiKey || apiKey || undefined,
+    });
+    return customProvider(custom.modelName);
+  }
+
+  const modelName = modelId.includes('/') ? modelId.split('/').slice(1).join('/') : modelId;
+
+  switch (provider) {
+    case 'google':
+      return createGoogleGenerativeAI({ apiKey })(modelName);
+    case 'cohere':
+      return createCohere({ apiKey })(modelName);
+    case 'mistral':
+      return createMistral({ apiKey })(modelName);
+    case 'deepseek':
+      return createDeepSeek({ apiKey })(modelName);
+    case 'anthropic':
+      return createAnthropic({ apiKey })(modelName);
+    case 'openai':
+      return createOpenAI({ apiKey })(modelName);
+    case 'vercel_ai_gateway':
+      // Gateway model IDs retain their vendor prefix (for example,
+      // "openai/gpt-4o-mini") because routing happens at the gateway.
+      return createGateway({ apiKey })(modelId);
+    case 'custom':
+      throw new Error('Choose a configured custom chat model before processing media.');
+    default:
+      throw new Error(`Unsupported chat provider "${provider}".`);
+  }
+}

package/src/lib/chat/response-style.ts

@@ -0,0 +1,3 @@
+export const PERSONALIZED_RESPONSE_STYLE = `
+Speak as a personalized assistant that already knows the user's context. Never mention or imply documents, files, stored data, a knowledge base, search, retrieval, sources, indexing, or tool calls. Do not start with phrases such as "Based on", "According to", "I found", "Your document says", or "The search results show". Start with the answer naturally and directly.
+`;

package/src/lib/chat/retrieval-ranking.ts

@@ -0,0 +1,126 @@
+const STOP_WORDS = new Set([
+  'a',
+  'an',
+  'and',
+  'are',
+  'be',
+  'by',
+  'do',
+  'for',
+  'from',
+  'how',
+  'i',
+  'in',
+  'is',
+  'it',
+  'list',
+  'me',
+  'of',
+  'on',
+  'or',
+  'show',
+  'tell',
+  'that',
+  'the',
+  'this',
+  'to',
+  'under',
+  'was',
+  'what',
+  'when',
+  'which',
+  'who',
+  'with',
+]);
+
+export function searchTerms(text: string): string[] {
+  return [
+    ...new Set(
+      text
+        .toLocaleLowerCase()
+        .match(/[\p{L}\p{N}_-]+/gu)
+        ?.filter((term) => term.length > 1 && !STOP_WORDS.has(term)) ?? [],
+    ),
+  ];
+}
+
+// A plain substring check turns a short query term into a false hit inside
+// any longer word that happens to contain it as a fragment -- "day" inside
+// "Tuesday", "color" inside "Colored" -- which systematically favors long,
+// generic documents over a short, genuinely on-topic one. Word-boundary
+// matching (Unicode-aware, so non-Latin scripts aren't broken) keeps the
+// coverage signal tied to the term actually appearing as its own word --
+// tolerating a trailing plural/possessive suffix (view/views, routine/
+// routines) so a strict boundary doesn't overcorrect into missing ordinary
+// inflection, which "day"/"color" above are not instances of.
+function termMatcher(term: string): RegExp {
+  const escaped = term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`(?<![\\p{L}\\p{N}])${escaped}(?:'s|es|s)?(?![\\p{L}\\p{N}])`, 'u');
+}
+
+export interface QueryTermMatcher {
+  term: string;
+  regex: RegExp;
+}
+
+/**
+ * Extracts a query's significant terms and compiles their matchers once, so
+ * a caller scanning many candidates (e.g. every document's title) doesn't
+ * redo term extraction and regex compilation on every single one of them.
+ */
+export function buildQueryTermMatchers(query: string): QueryTermMatcher[] {
+  return searchTerms(query).map((term) => ({ term, regex: termMatcher(term) }));
+}
+
+/** How many of a precomputed set of query-term matchers appear (word-boundary
+ * aware) in `text`. */
+export function countMatchesIn(matchers: QueryTermMatcher[], text: string): number {
+  if (matchers.length === 0) return 0;
+  const normalized = text.toLocaleLowerCase();
+  return matchers.filter(({ regex }) => regex.test(normalized)).length;
+}
+
+/**
+ * How many of the query's significant terms appear (word-boundary aware) in
+ * `title`. Exposed so a candidate-pool builder can pull in a document whose
+ * title is an obvious match for the query even when pure vector similarity
+ * placed it outside the retrieved pool entirely -- reranking can only
+ * reorder what's already in the pool, it can't recover a document that
+ * never made it in. Scanning many titles for the same query should use
+ * `buildQueryTermMatchers` once and call `countMatchesIn` per title instead
+ * of this convenience wrapper, which redoes both on every call.
+ */
+export function countTitleTermMatches(query: string, title: string): number {
+  return countMatchesIn(buildQueryTermMatchers(query), title);
+}
+
+/** Merge semantic recall with exact terminology from names, labels, and IDs. */
+export function rankKnowledgeHits<T extends { text?: string; title?: string; metadata?: any }>(
+  query: string,
+  hits: T[],
+): T[] {
+  const matchers = buildQueryTermMatchers(query);
+  if (matchers.length === 0 || hits.length < 2) return hits;
+
+  const phrase = query.trim().toLocaleLowerCase().replace(/\s+/g, ' ');
+  return hits
+    .map((hit, denseRank) => {
+      const searchable = [
+        hit.title,
+        hit.text,
+        hit.metadata?.description,
+        hit.metadata?.originalFile,
+      ]
+        .filter((value): value is string => typeof value === 'string')
+        .join(' ')
+        .toLocaleLowerCase();
+      const coverage = countMatchesIn(matchers, searchable) / matchers.length;
+      const title = hit.title?.toLocaleLowerCase();
+      const titleMatches = title ? countMatchesIn(matchers, title) : 0;
+      const phraseBonus = phrase.length > 3 && searchable.includes(phrase) ? 0.2 : 0;
+      const score = 0.35 / (denseRank + 1) + coverage + titleMatches * 0.08 + phraseBonus;
+      return { hit, score, denseRank };
+    })
+    .sort((left, right) => right.score - left.score || left.denseRank - right.denseRank)
+    .map(({ hit }) => hit);
+}

package/src/lib/chat/retrieval-routing.ts

@@ -0,0 +1,221 @@
+function isMatchResultQuestion(text: string): boolean {
+  return (
+    /\b(?:who\s+won|winner|final\s+score|scoreline|match\s+result|what(?:'s|\s+is|\s+was)?\s+the\s+score)\b[\s\S]{0,120}\b(?:match|game|fixture|final|vs?\.?|versus)\b/i.test(
+      text,
+    ) ||
+    /\b(?:match|game|fixture|final|vs?\.?|versus)\b[\s\S]{0,120}\b(?:who\s+won|winner|final\s+score|scoreline|result|score)\b/i.test(
+      text,
+    )
+  );
+}
+
+// Up to two words (an adjective, a participle, a compound modifier) between
+// a determiner/possessive and the noun it governs -- "my test video", "this
+// uploaded recording", "the indexed sales report". A bare `\s+` between the
+// two required a direct adjacency that real phrasing rarely uses.
+const GAP = '(?:\\s+\\w+){0,2}\\s+';
+const MY_FAVORITE_RE = new RegExp(
+  `\\b(my|our)${GAP}(favo(?:u)?rite|preference|choice|answer|name|result|score|winner)\\b`,
+  'i',
+);
+const THIS_VIDEO_RE = new RegExp(
+  `\\b(?:this|that|the)${GAP}(?:match|video|episode|recording|diagram|chart|image|page|section)\\b`,
+  'i',
+);
+const MY_UPLOAD_RE = new RegExp(
+  `\\b(my|our)${GAP}(document|file|data|image|picture|diagram|video|audio|upload|corpus|knowledge|database|db|pdf|report|spreadsheet|presentation)\\b`,
+  'i',
+);
+const THE_DOCUMENT_RE = new RegExp(
+  `\\b(the|this|that)${GAP}(document|file|diagram|image|picture|upload|pdf|report)\\b`,
+  'i',
+);
+
+export function requiresKnowledgeBaseSearch(text: string): boolean {
+  const normalized = text.trim();
+  if (/^(hi|hello|hey|thanks|thank you|ok|sure|yes|no|please|help)\b/i.test(normalized)) {
+    return false;
+  }
+
+  return (
+    MY_FAVORITE_RE.test(normalized) ||
+    /\b(?:what|which|who|where|when|how)\b[\s\S]{0,80}\b(my|our)\b/i.test(normalized) ||
+    THIS_VIDEO_RE.test(normalized) ||
+    /\b(?:shown|listed|named|counted|under)\b[\s\S]{0,80}\b(?:image|diagram|chart|pdf|document|page|section|resources)\b/i.test(
+      normalized,
+    ) ||
+    MY_UPLOAD_RE.test(normalized) ||
+    /\b(?:search|check|query)\s+(?:the\s+)?(?:knowledge base|corpus|database|db)\b/i.test(
+      normalized,
+    ) ||
+    THE_DOCUMENT_RE.test(normalized) ||
+    // A named match is commonly a question about an indexed recording. The
+    // user does not need to repeat "my video" for every follow-up question.
+    isMatchResultQuestion(normalized) ||
+    /\b(uploaded?|indexed|scraped|knowledge base|corpus)\b/i.test(normalized) ||
+    /\bshow\s+me\b/i.test(normalized)
+  );
+}
+
+type ChatMessageWithToolParts = {
+  role?: string;
+  parts?: unknown;
+  toolInvocations?: unknown;
+};
+
+function resultHasHits(result: unknown): boolean {
+  if (typeof result === 'string') {
+    try {
+      return resultHasHits(JSON.parse(result));
+    } catch {
+      return false;
+    }
+  }
+  if (
+    typeof result === 'object' &&
+    result !== null &&
+    (result as { type?: string }).type === 'json' &&
+    'value' in result
+  ) {
+    return resultHasHits((result as { value?: unknown }).value);
+  }
+  return (
+    typeof result === 'object' &&
+    result !== null &&
+    Array.isArray((result as { hits?: unknown }).hits) &&
+    (result as { hits: unknown[] }).hits.length > 0
+  );
+}
+
+/**
+ * A follow-up may safely reuse evidence that is still in the conversation.
+ * Do not reuse an empty search: a new, more specific wording can surface a
+ * relevant chunk on the next attempt.
+ */
+export function hasPriorKnowledgeBaseEvidence(messages: ChatMessageWithToolParts[]): boolean {
+  return messages.some((message) => {
+    if (message.role !== 'assistant') return false;
+    const parts = Array.isArray(message.parts) ? message.parts : [];
+    const toolPartsContainHits = parts.some((part: any) => {
+      if (part?.type === 'tool-invocation') {
+        return (
+          part.toolInvocation?.toolName === 'searchKnowledgeBase' &&
+          resultHasHits(part.toolInvocation?.result)
+        );
+      }
+      return part?.type === 'tool-searchKnowledgeBase' && resultHasHits(part.output ?? part.result);
+    });
+    if (toolPartsContainHits) return true;
+
+    const invocations = Array.isArray(message.toolInvocations) ? message.toolInvocations : [];
+    return invocations.some(
+      (invocation: any) =>
+        invocation?.toolName === 'searchKnowledgeBase' && resultHasHits(invocation?.result),
+    );
+  });
+}
+
+function extractMessageText(message: ChatMessageWithToolParts): string {
+  const anyM = message as any;
+  if (typeof anyM.content === 'string') return anyM.content;
+  const parts = Array.isArray(anyM.parts)
+    ? anyM.parts
+    : Array.isArray(anyM.content)
+      ? anyM.content
+      : [];
+  return parts
+    .filter((p: any) => p.type === 'text' && typeof p.text === 'string')
+    .map((p: any) => p.text)
+    .join(' ');
+}
+
+/**
+ * Keep retrieval efficient for natural continuations such as "what about it?"
+ * while treating every new standalone question as a fresh lookup.
+ */
+export function isLikelyKnowledgeFollowUp(
+  text: string,
+  messages?: ChatMessageWithToolParts[],
+): boolean {
+  const normalized = text.trim().toLowerCase();
+  if (!normalized) return false;
+
+  const hasFollowUpKeywords =
+    /^(?:and|also|then|so)\b/.test(normalized) ||
+    /^(?:tell me more|continue|go on|can you (?:explain|elaborate|clarify))\b/.test(normalized) ||
+    /\b(?:it|this|that|they|them|those|these|its|their)\b/.test(normalized);
+
+  if (hasFollowUpKeywords) return true;
+
+  if (messages && messages.length > 0) {
+    const userMessages = messages.filter((m) => m.role === 'user');
+    if (userMessages.length >= 2) {
+      const prevUserText = extractMessageText(userMessages[userMessages.length - 2]);
+      if (prevUserText.trim().toLowerCase() === normalized) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+export function canReuseKnowledgeBaseEvidence(
+  text: string,
+  messages: ChatMessageWithToolParts[],
+): boolean {
+  return isLikelyKnowledgeFollowUp(text, messages) && hasPriorKnowledgeBaseEvidence(messages);
+}
+
+/** The chat workspace is intentionally a retrieval-only experience. */
+export function requiresCurrentWebSearch(text: string): boolean {
+  void text;
+  return false;
+}
+
+/** Only the first retrieval is forced. The other source remains available for
+ * exactly one recovery attempt; subsequent steps are reserved for analysis and
+ * the final answer. */
+export function retrievalToolsForStep<ToolName extends string>(options: {
+  stepNumber: number;
+  forceKnowledgeBaseSearch: boolean;
+  forceWebSearch: boolean;
+  toolNames: readonly ToolName[];
+  /** Reserve this and every later step for the model's final answer. */
+  finalAnswerStep?: number;
+}):
+  | {
+      toolChoice?: { type: 'tool'; toolName: ToolName } | 'none';
+      activeTools?: ToolName[];
+    }
+  | undefined {
+  const { stepNumber, forceKnowledgeBaseSearch, forceWebSearch, toolNames, finalAnswerStep } =
+    options;
+  const without = (...blocked: string[]) => toolNames.filter((name) => !blocked.includes(name));
+
+  if (stepNumber === 0 && forceKnowledgeBaseSearch) {
+    return {
+      toolChoice: { type: 'tool', toolName: 'searchKnowledgeBase' as ToolName },
+      activeTools: ['searchKnowledgeBase' as ToolName],
+    };
+  }
+  if (stepNumber === 0 && forceWebSearch) return { activeTools: without('webSearch') };
+  if (stepNumber === 0) {
+    // If not forced, do not expose searchKnowledgeBase for ordinary conversation.
+    return { activeTools: without('webSearch', 'searchKnowledgeBase') };
+  }
+  if (forceKnowledgeBaseSearch) {
+    if (finalAnswerStep !== undefined && stepNumber >= finalAnswerStep) {
+      // A stale toolChoice of 'auto' left over from the top-level streamText
+      // config paired with zero active tools produced a degenerate
+      // near-empty completion (observed live: 1 output token, no text) --
+      // be explicit that no tool call is available for this step.
+      return { toolChoice: 'none', activeTools: [] };
+    }
+    return { activeTools: without('searchKnowledgeBase', 'webSearch') };
+  }
+  if (stepNumber === 1 && forceWebSearch) {
+    return { activeTools: without('webSearch') };
+  }
+  return { activeTools: without('webSearch', 'searchKnowledgeBase') };
+}