@lota-sdk/core 0.1.5

package/src/bifrost/bifrost.ts

@@ -0,0 +1,256 @@
+import { createOpenAI } from '@ai-sdk/openai'
+import { wrapLanguageModel } from 'ai'
+import type { LanguageModelMiddleware } from 'ai'
+
+import { isRecord, readString } from '../utils/string'
+
+type BifrostExtraParams = Record<string, unknown>
+type BifrostChatResponse = { body?: unknown }
+type BifrostTransformParamsOptions = Parameters<NonNullable<LanguageModelMiddleware['transformParams']>>[0]
+type WrapStreamOptions = Parameters<NonNullable<LanguageModelMiddleware['wrapStream']>>[0]
+type BifrostCallOptions = WrapStreamOptions['params']
+type BifrostGenerateResult = Awaited<ReturnType<WrapStreamOptions['doGenerate']>>
+type BifrostStreamResult = Awaited<ReturnType<WrapStreamOptions['doStream']>>
+type BifrostGeneratedContent = BifrostGenerateResult['content'][number]
+type BifrostStreamPart = BifrostStreamResult['stream'] extends ReadableStream<infer T> ? T : never
+
+const OPENROUTER_RESPONSE_HEALING_EXTRA_PARAMS = {
+  plugins: [{ id: 'response-healing' }],
+} as const satisfies BifrostExtraParams
+
+function readRequiredGatewayEnv(name: 'AI_GATEWAY_KEY' | 'AI_GATEWAY_URL'): string {
+  const value = process.env[name]?.trim()
+  if (value) return value
+  throw new Error(`[bifrost] Missing ${name}.`)
+}
+
+function readReasoningDetailsText(value: unknown): string | null {
+  if (!Array.isArray(value)) return null
+
+  const textParts = value
+    .map((item) => (isRecord(item) ? readString(item.text) : null))
+    .filter((item): item is string => item !== null)
+
+  if (textParts.length === 0) return null
+
+  return textParts.join('\n\n')
+}
+
+function readBifrostChatReasoningText(message: Record<string, unknown>): string | null {
+  return (
+    readString(message.reasoning) ??
+    readString(message.reasoning_content) ??
+    readReasoningDetailsText(message.reasoning_details)
+  )
+}
+
+export function extractBifrostChatReasoningText(responseBody: unknown): string | null {
+  if (!isRecord(responseBody) || !Array.isArray(responseBody.choices)) return null
+
+  for (const choice of responseBody.choices) {
+    if (!isRecord(choice) || !isRecord(choice.message)) continue
+
+    const reasoningText = readBifrostChatReasoningText(choice.message)
+    if (reasoningText) return reasoningText
+  }
+
+  return null
+}
+
+export function extractBifrostChatReasoningDeltaText(rawChunk: unknown): string | null {
+  if (!isRecord(rawChunk) || !Array.isArray(rawChunk.choices)) return null
+
+  for (const choice of rawChunk.choices) {
+    if (!isRecord(choice) || !isRecord(choice.delta)) continue
+
+    const reasoningText = readBifrostChatReasoningText(choice.delta)
+    if (reasoningText) return reasoningText
+  }
+
+  return null
+}
+
+export function injectBifrostChatReasoningContent(
+  content: readonly BifrostGeneratedContent[],
+  response?: BifrostChatResponse,
+): BifrostGeneratedContent[] {
+  if (content.some((part) => part.type === 'reasoning')) {
+    return [...content]
+  }
+
+  const reasoningText = extractBifrostChatReasoningText(response?.body)
+  if (!reasoningText) return [...content]
+
+  return [{ type: 'reasoning', text: reasoningText }, ...content]
+}
+
+function isReasoningEnabled(params: BifrostCallOptions): boolean {
+  if (!isRecord(params.providerOptions) || !isRecord(params.providerOptions.openai)) return false
+
+  const openaiOptions = params.providerOptions.openai
+  if (openaiOptions.forceReasoning === true) return true
+  if (typeof openaiOptions.reasoningSummary === 'string' && openaiOptions.reasoningSummary.length > 0) return true
+  return typeof openaiOptions.reasoningEffort === 'string' && openaiOptions.reasoningEffort !== 'none'
+}
+
+function shouldCloseInjectedReasoning(chunk: BifrostStreamPart): boolean {
+  return chunk.type !== 'stream-start' && chunk.type !== 'response-metadata' && chunk.type !== 'raw'
+}
+
+export function injectBifrostChatReasoningStream(
+  stream: ReadableStream<BifrostStreamPart>,
+): ReadableStream<BifrostStreamPart> {
+  const reasoningId = 'bifrost-reasoning-0'
+  let reasoningOpen = false
+  let reasoningClosed = false
+
+  return stream.pipeThrough(
+    new TransformStream<BifrostStreamPart, BifrostStreamPart>({
+      transform(chunk, controller) {
+        const closeReasoning = () => {
+          if (!reasoningOpen || reasoningClosed) return
+
+          controller.enqueue({ type: 'reasoning-end', id: reasoningId } as BifrostStreamPart)
+          reasoningClosed = true
+        }
+
+        if (chunk.type === 'raw') {
+          const reasoningDelta = reasoningClosed ? null : extractBifrostChatReasoningDeltaText(chunk.rawValue)
+          controller.enqueue(chunk)
+
+          if (reasoningDelta) {
+            if (!reasoningOpen) {
+              controller.enqueue({ type: 'reasoning-start', id: reasoningId } as BifrostStreamPart)
+              reasoningOpen = true
+            }
+
+            controller.enqueue({ type: 'reasoning-delta', id: reasoningId, delta: reasoningDelta } as BifrostStreamPart)
+          }
+          return
+        }
+
+        if (shouldCloseInjectedReasoning(chunk)) {
+          closeReasoning()
+        }
+
+        controller.enqueue(chunk)
+      },
+      flush(controller) {
+        if (!reasoningOpen || reasoningClosed) return
+        controller.enqueue({ type: 'reasoning-end', id: reasoningId } as BifrostStreamPart)
+      },
+    }),
+  )
+}
+
+function addBifrostReasoningRawChunks(
+  params: BifrostCallOptions,
+  type: BifrostTransformParamsOptions['type'],
+): BifrostCallOptions {
+  if (type !== 'stream' || !isReasoningEnabled(params) || params.includeRawChunks === true) {
+    return params
+  }
+
+  return { ...params, includeRawChunks: true }
+}
+
+export function injectBifrostExtraParamsRequestBody(
+  body: BodyInit | null | undefined,
+  extraParams: BifrostExtraParams,
+): BodyInit | null | undefined {
+  if (typeof body !== 'string') return body
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(body)
+  } catch {
+    return body
+  }
+
+  if (!isRecord(parsed)) return body
+
+  const mergedExtraParams = isRecord(parsed.extra_params)
+    ? { ...parsed.extra_params, ...extraParams }
+    : { ...extraParams }
+
+  return JSON.stringify({ ...parsed, extra_params: mergedExtraParams })
+}
+
+function createBifrostFetchWithExtraParams(extraParams: BifrostExtraParams): typeof fetch {
+  const fetchWithExtraParams = (input: RequestInfo | URL, init?: RequestInit | BunFetchRequestInit) =>
+    globalThis.fetch(input, { ...init, body: injectBifrostExtraParamsRequestBody(init?.body, extraParams) })
+
+  return Object.assign(fetchWithExtraParams, { preconnect: globalThis.fetch.preconnect.bind(globalThis.fetch) })
+}
+
+function createBifrostProvider(extraParams?: BifrostExtraParams) {
+  const apiKey = readRequiredGatewayEnv('AI_GATEWAY_KEY')
+  if (!apiKey.startsWith('sk-bf-')) {
+    throw new Error('[bifrost] AI_GATEWAY_KEY must use the Bifrost virtual-key format (sk-bf-*).')
+  }
+
+  return createOpenAI({
+    baseURL: readRequiredGatewayEnv('AI_GATEWAY_URL'),
+    apiKey,
+    headers: { 'x-bf-vk': apiKey, ...(extraParams ? { 'x-bf-passthrough-extra-params': 'true' } : {}) },
+    ...(extraParams ? { fetch: createBifrostFetchWithExtraParams(extraParams) } : {}),
+  })
+}
+
+let provider: ReturnType<typeof createOpenAI> | null = null
+let openRouterResponseHealingProvider: ReturnType<typeof createOpenAI> | null = null
+
+export function getBifrostProvider() {
+  if (provider) return provider
+
+  provider = createBifrostProvider()
+
+  return provider
+}
+
+export function getBifrostOpenRouterResponseHealingProvider() {
+  if (openRouterResponseHealingProvider) return openRouterResponseHealingProvider
+
+  openRouterResponseHealingProvider = createBifrostProvider(OPENROUTER_RESPONSE_HEALING_EXTRA_PARAMS)
+
+  return openRouterResponseHealingProvider
+}
+
+export function bifrostModel(modelId: string) {
+  return getBifrostProvider()(modelId)
+}
+
+export function bifrostOpenRouterResponseHealingModel(modelId: string) {
+  return getBifrostOpenRouterResponseHealingProvider()(modelId)
+}
+
+export function bifrostChatModel(modelId: string) {
+  return wrapLanguageModel({
+    model: getBifrostProvider().chat(modelId),
+    middleware: {
+      specificationVersion: 'v3',
+      transformParams: async ({ params, type }) => addBifrostReasoningRawChunks(params, type),
+      wrapGenerate: async ({ doGenerate }) => {
+        const result = await doGenerate()
+
+        return {
+          ...result,
+          content: injectBifrostChatReasoningContent(
+            result.content,
+            result.response as BifrostChatResponse | undefined,
+          ),
+        }
+      },
+      wrapStream: async ({ doStream, params }) => {
+        const result = await doStream()
+        if (!isReasoningEnabled(params)) return result
+
+        return { ...result, stream: injectBifrostChatReasoningStream(result.stream) }
+      },
+    },
+  })
+}
+
+export function bifrostEmbeddingModel(modelId: string) {
+  return getBifrostProvider().embeddingModel(modelId)
+}

package/src/config/agent-defaults.ts

@@ -0,0 +1,99 @@
+type LotaAgentFactoryRegistry = Record<string, (...args: unknown[]) => unknown>
+
+// Agent configuration — these are defaults that consumers override via createLotaRuntime config
+export let agentDisplayNames: Record<string, string> = {}
+export let agentShortDisplayNames: Record<string, string> = {}
+export let agentRoster: readonly string[] = []
+export let teamConsultParticipants: readonly string[] = []
+
+export interface CoreWorkstreamProfile {
+  config: { coreType: string; agentId: string; title: string }
+  tools: readonly string[]
+  skills: readonly string[]
+  instructions: string
+}
+
+export let getCoreWorkstreamProfile: (coreType: string) => CoreWorkstreamProfile = (_coreType) => ({
+  config: { coreType: _coreType, agentId: '', title: '' },
+  tools: [],
+  skills: [],
+  instructions: '',
+})
+
+export function configureAgents(config: {
+  roster: readonly string[]
+  displayNames: Record<string, string>
+  shortDisplayNames?: Record<string, string>
+  teamConsultParticipants: readonly string[]
+  getCoreWorkstreamProfile?: (coreType: string) => CoreWorkstreamProfile
+}): void {
+  agentRoster = config.roster
+  agentDisplayNames = config.displayNames
+  agentShortDisplayNames = config.shortDisplayNames ?? {}
+  teamConsultParticipants = config.teamConsultParticipants
+  if (config.getCoreWorkstreamProfile) {
+    getCoreWorkstreamProfile = config.getCoreWorkstreamProfile
+  }
+}
+
+export function isAgentName(value: unknown): boolean {
+  return typeof value === 'string' && new Set(agentRoster).has(value)
+}
+
+export function resolveAgentNameAlias(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined
+  const lowered = value.trim().toLowerCase()
+  const aliasMap = new Map<string, string>()
+  for (const agent of agentRoster) {
+    aliasMap.set(agent.toLowerCase(), agent)
+    const displayName = agentDisplayNames[agent]
+    if (displayName) aliasMap.set(displayName.toLowerCase(), agent)
+    const shortName = agentShortDisplayNames[agent]
+    if (shortName) aliasMap.set(shortName.toLowerCase(), agent)
+  }
+  return aliasMap.get(lowered)
+}
+
+export let createAgent: LotaAgentFactoryRegistry = {}
+
+export let buildAgentTools: (...args: unknown[]) => unknown = () => ({})
+export let getAgentRuntimeConfig: (...args: unknown[]) => unknown = () => ({})
+export let pluginRuntime: unknown = undefined
+
+export function configureAgentFactory(config: {
+  createAgent: LotaAgentFactoryRegistry
+  buildAgentTools?: (...args: unknown[]) => unknown
+  getAgentRuntimeConfig?: (...args: unknown[]) => unknown
+  pluginRuntime?: unknown
+}): void {
+  createAgent = config.createAgent
+  if (config.buildAgentTools) buildAgentTools = config.buildAgentTools
+  if (config.getAgentRuntimeConfig) getAgentRuntimeConfig = config.getAgentRuntimeConfig
+  if (config.pluginRuntime !== undefined) pluginRuntime = config.pluginRuntime
+}
+
+const AGENT_MENTION_REGEX = /(^|[^\w])@([a-z][a-z0-9_-]*)\b/gi
+
+export interface AgentMentionMatch {
+  agent: string
+  mention: string
+  index: number
+  length: number
+}
+
+export function extractAgentMentions(message: string): AgentMentionMatch[] {
+  const matches: AgentMentionMatch[] = []
+  if (!message.trim()) return matches
+
+  const regex = new RegExp(AGENT_MENTION_REGEX)
+  for (const rawMatch of message.matchAll(regex)) {
+    const prefix = rawMatch[1] ?? ''
+    const rawAgent = (rawMatch[2] ?? '').toLowerCase()
+    if (!isAgentName(rawAgent)) continue
+
+    const index = rawMatch.index + prefix.length
+    matches.push({ agent: rawAgent, mention: `@${rawAgent}`, index, length: rawAgent.length + 1 })
+  }
+
+  return matches
+}

package/src/config/constants.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod'
+
+// ============================================================================
+// Memory System Constants
+// ============================================================================
+
+export const MEMORY = {
+  /** Default number of memory candidates to fetch */
+  DEFAULT_CANDIDATE_LIMIT: 12,
+  /** Maximum KNN limit for safety */
+  MAX_KNN_LIMIT: 100,
+} as const
+
+// ============================================================================
+// Validation Helpers
+// ============================================================================
+
+/**
+ * Validates that a value is a safe integer for KNN queries
+ * Throws if validation fails
+ */
+export function validateKnnLimit(limit: unknown): number {
+  return z.number().int().positive().max(MEMORY.MAX_KNN_LIMIT).parse(limit)
+}
+
+/**
+ * Creates a KNN query string with validated limit
+ * Example: createKnnQuery(10) returns "<|10|>"
+ */
+export function createKnnQuery(limit: unknown): string {
+  const validatedLimit = validateKnnLimit(limit)
+  return `<|${validatedLimit}|>`
+}

package/src/config/env-shapes.ts

@@ -0,0 +1,122 @@
+import type { ZodTypeAny } from 'zod'
+import { z } from 'zod'
+
+const logLevelValues = ['trace', 'debug', 'info', 'warning', 'error', 'fatal'] as const
+
+export const nodeServerEnvShape = {
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+  PORT: z.coerce.number().default(3000),
+  MAIN_CLIENT_URL: z.string().min(1).default('http://localhost:5173'),
+} as const satisfies Record<string, ZodTypeAny>
+
+export const surrealDbEnvShape = {
+  SURREALDB_URL: z.string().min(1, 'SurrealDB URL is required'),
+  SURREALDB_USER: z.string().min(1, 'SurrealDB user is required'),
+  SURREALDB_PASSWORD: z.string().min(1, 'SurrealDB password is required'),
+  SURREALDB_NAMESPACE: z.string().min(1, 'SurrealDB namespace is required'),
+  SURREALDB_DATABASE: z.string().min(1, 'SurrealDB database is required'),
+} as const satisfies Record<string, ZodTypeAny>
+
+export const betterAuthEnvShape = {
+  BETTER_AUTH_SECRET: z.string().min(32, 'Better Auth secret must be at least 32 characters long'),
+} as const satisfies Record<string, ZodTypeAny>
+
+export const serverUrlEnvShape = { SERVER_URL: z.string().min(1, 'Server URL is required') } as const satisfies Record<
+  string,
+  ZodTypeAny
+>
+
+export const aiGatewayEnvShape = {
+  AI_GATEWAY_URL: z.string().url('AI gateway URL is required'),
+  AI_GATEWAY_KEY: z.string().min(1, 'AI gateway key is required'),
+  AI_GATEWAY_ADMIN: z.string().min(1).optional(),
+  AI_GATEWAY_PASS: z.string().min(1).optional(),
+  AI_EMBEDDING_MODEL: z.string().default('openai/text-embedding-3-small'),
+} as const satisfies Record<string, ZodTypeAny>
+
+export const firecrawlEnvShape = {
+  FIRECRAWL_API_KEY: z
+    .string()
+    .min(1, 'Firecrawl API key is required')
+    .refine((value) => value.startsWith('fc-'), 'Firecrawl API key must start with fc-')
+    .refine((value) => value !== 'dev-fire-key', 'Firecrawl API key placeholder is not allowed'),
+  FIRECRAWL_API_BASE_URL: z.string().url().optional(),
+} as const satisfies Record<string, ZodTypeAny>
+
+export const memorySearchEnvShape = {
+  MEMORY_SEARCH_K: z.coerce.number().int().positive().default(6),
+} as const satisfies Record<string, ZodTypeAny>
+
+export const redisEnvShape = { REDIS_URL: z.string().min(1, 'Redis URL is required') } as const satisfies Record<
+  string,
+  ZodTypeAny
+>
+
+export const s3StorageEnvShape = {
+  S3_ENDPOINT: z.string().min(1, 'S3 endpoint is required'),
+  S3_BUCKET: z.string().min(1, 'S3 bucket is required'),
+  S3_REGION: z.string().default('garage'),
+  S3_ACCESS_KEY_ID: z.string().min(1, 'S3 access key is required'),
+  S3_SECRET_ACCESS_KEY: z.string().min(1, 'S3 secret access key is required'),
+  ATTACHMENT_URL_EXPIRES_IN: z.coerce.number().positive('Attachment URL expiry must be positive').default(1800),
+} as const satisfies Record<string, ZodTypeAny>
+
+export const loggingEnvShape = { LOG_LEVEL: z.enum(logLevelValues).default('info') } as const satisfies Record<
+  string,
+  ZodTypeAny
+>
+
+export const githubAppEnvShape = {
+  GITHUB_APP_ID: z.string().optional(),
+  GITHUB_PRIVATE_KEY: z.string().optional(),
+  GITHUB_APP_SLUG: z.string().optional(),
+} as const satisfies Record<string, ZodTypeAny>
+
+export const linearOauthEnvShape = {
+  LINEAR_CLIENT_ID: z.string().optional(),
+  LINEAR_CLIENT_SECRET: z.string().optional(),
+  LINEAR_REDIRECT_URI: z.string().optional(),
+} as const satisfies Record<string, ZodTypeAny>
+
+export const marketingStudioEnvShape = {
+  MARKETING_STUDIO_BASE_URL: z.string().url().optional(),
+  MARKETING_STUDIO_ADMIN_API_KEY: z.string().min(1).optional(),
+  MARKETING_STUDIO_WEBHOOK_SIGNING_SECRET: z.string().min(1).optional(),
+} as const satisfies Record<string, ZodTypeAny>
+
+export function envKeys<TShape extends Record<string, ZodTypeAny>>(shape: TShape) {
+  return Object.freeze(Object.keys(shape)) as readonly Extract<keyof TShape, string>[]
+}
+
+const lotaSdkEnvSchema = z.object({
+  ...aiGatewayEnvShape,
+  ...memorySearchEnvShape,
+  ...redisEnvShape,
+  ...loggingEnvShape,
+  ...s3StorageEnvShape,
+  ...firecrawlEnvShape,
+})
+
+export const lotaSdkEnvKeys = Object.freeze([
+  ...envKeys(aiGatewayEnvShape),
+  ...envKeys(memorySearchEnvShape),
+  ...envKeys(redisEnvShape),
+  ...envKeys(loggingEnvShape),
+  ...envKeys(s3StorageEnvShape),
+  ...envKeys(firecrawlEnvShape),
+]) as readonly string[]
+
+type LotaSdkEnv = z.infer<typeof lotaSdkEnvSchema>
+
+let _env: LotaSdkEnv | undefined
+
+export function setEnv(value: LotaSdkEnv): void {
+  _env = value
+}
+
+export const env: LotaSdkEnv = new Proxy({} as LotaSdkEnv, {
+  get(_target, prop: string) {
+    if (!_env) throw new Error(`lota-sdk env not configured. Call setEnv() before accessing env.${prop}`)
+    return (_env as Record<string, unknown>)[prop]
+  },
+})

package/src/config/logger.ts

@@ -0,0 +1,29 @@
+import type { LogLevel } from '@logtape/logtape'
+import { configure, getAnsiColorFormatter, getConsoleSink, getLogger as getLogTapeLogger } from '@logtape/logtape'
+
+export async function configureLotaLogger(logLevel: LogLevel): Promise<void> {
+  const formatter = getAnsiColorFormatter({ level: 'FULL' })
+
+  await configure({
+    reset: true,
+    sinks: { console: getConsoleSink({ formatter }) },
+    loggers: [
+      { category: ['logtape', 'meta'], lowestLevel: 'warning', sinks: ['console'] },
+      { category: ['server'], lowestLevel: logLevel, sinks: ['console'] },
+      { category: ['lota-sdk'], lowestLevel: logLevel, sinks: ['console'] },
+      { category: ['hono'], lowestLevel: logLevel, sinks: ['console'] },
+    ],
+  })
+}
+
+export function getLogger(category: readonly string[]) {
+  return getLogTapeLogger([...category])
+}
+
+export async function configureLogger(logLevel?: LogLevel): Promise<void> {
+  await configureLotaLogger(logLevel ?? 'info')
+}
+
+export const serverLogger = getLogger(['lota-sdk'])
+export const chatLogger = getLogger(['lota-sdk', 'chat'])
+export const aiLogger = getLogger(['lota-sdk', 'ai'])

package/src/config/model-constants.ts

@@ -0,0 +1,31 @@
+export const OPENAI_REASONING_MODEL_ID = 'openai/gpt-5.4' as const
+
+export const OPENROUTER_TEAM_AGENT_MODEL_ID = 'openrouter/google/gemini-3.1-pro-preview' as const
+export const OPENROUTER_STRUCTURED_HELPER_MODEL_ID = 'openrouter/google/gemini-3-flash-preview:exacto' as const
+export const OPENROUTER_DELEGATED_REASONING_MODEL_ID = 'openrouter/google/gemini-3-flash-preview:exacto' as const
+export const OPENROUTER_WEB_RESEARCH_MODEL_ID = 'openrouter/stepfun/step-3.5-flash' as const
+export const OPENROUTER_ARTIFACT_GENERATOR_MODEL_ID = 'openrouter/qwen/qwen3.5-flash-02-23' as const
+export const OPENROUTER_REPO_INDEXER_MODEL_ID = 'openrouter/qwen/qwen3.5-flash-02-23:nitro' as const
+export const OPENROUTER_CODE_ANALYSIS_MODEL_ID = 'openrouter/xiaomi/mimo-v2-flash' as const
+export const OPENROUTER_FAST_REASONING_MODEL_ID = 'openrouter/openai/gpt-oss-120b:nitro' as const
+export const OPENROUTER_STRUCTURED_REASONING_MODEL_ID = 'openrouter/openai/gpt-oss-120b:exacto' as const
+
+export const OPENAI_HIGH_REASONING_PROVIDER_OPTIONS = {
+  openai: { forceReasoning: true, reasoningEffort: 'high', reasoningSummary: 'auto' },
+} as const
+
+export const OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS = {
+  openai: { forceReasoning: true, reasoningEffort: 'high', reasoningSummary: 'auto' },
+} as const
+
+export const OPENROUTER_XHIGH_REASONING_PROVIDER_OPTIONS = {
+  openai: { forceReasoning: true, reasoningEffort: 'xhigh', reasoningSummary: 'auto' },
+} as const
+
+export const OPENROUTER_LOW_REASONING_PROVIDER_OPTIONS = {
+  openai: { forceReasoning: true, reasoningEffort: 'low', reasoningSummary: 'auto' },
+} as const
+
+export const OPENROUTER_MINIMAL_REASONING_PROVIDER_OPTIONS = {
+  openai: { forceReasoning: true, reasoningEffort: 'minimal', reasoningSummary: 'auto' },
+} as const

package/src/config/search.ts

@@ -0,0 +1,17 @@
+/**
+ * Search-related constants for vector search and hybrid search
+ */
+
+/**
+ * Multiplier for vector search fetch limit.
+ * We fetch more candidates than needed (limit * multiplier) to allow for:
+ * - RRF (Reciprocal Rank Fusion) re-ranking
+ * - Hybrid search combining vector + full-text results
+ * - Filtering out low-quality matches before returning final results
+ */
+export const VECTOR_SEARCH_OVERFETCH_MULTIPLIER = 2
+
+/**
+ * Default limit for memory search queries
+ */
+export const DEFAULT_MEMORY_SEARCH_LIMIT = 10

package/src/config/workstream-defaults.ts

@@ -0,0 +1,68 @@
+export interface WorkstreamBootstrapWelcomeConfig {
+  directAgentId: string
+  buildMessageText: (params: { userName?: string | null }) => string
+}
+
+export interface LotaWorkstreamBootstrapConfig {
+  onboardingDirectAgents?: readonly string[]
+  completedDirectAgents?: readonly string[]
+  coreTypesAfterOnboarding?: readonly string[]
+  ensureDefaultGroupOnCompleted?: boolean
+  onboardingWelcome?: WorkstreamBootstrapWelcomeConfig
+}
+
+export interface LotaWorkstreamConfig {
+  bootstrap?: LotaWorkstreamBootstrapConfig
+}
+
+interface ResolvedWorkstreamBootstrapConfig {
+  onboardingDirectAgents: readonly string[]
+  completedDirectAgents: readonly string[]
+  coreTypesAfterOnboarding: readonly string[]
+  ensureDefaultGroupOnCompleted: boolean
+  onboardingWelcome?: WorkstreamBootstrapWelcomeConfig
+}
+
+const DEFAULT_WORKSTREAM_BOOTSTRAP_CONFIG: ResolvedWorkstreamBootstrapConfig = {
+  onboardingDirectAgents: [],
+  completedDirectAgents: [],
+  coreTypesAfterOnboarding: [],
+  ensureDefaultGroupOnCompleted: true,
+}
+
+let resolvedWorkstreamBootstrapConfig: ResolvedWorkstreamBootstrapConfig = DEFAULT_WORKSTREAM_BOOTSTRAP_CONFIG
+
+function withDedupedStrings(values: readonly string[]): string[] {
+  const seen = new Set<string>()
+  const deduped: string[] = []
+
+  for (const value of values) {
+    const normalized = value.trim()
+    if (!normalized || seen.has(normalized)) continue
+    seen.add(normalized)
+    deduped.push(normalized)
+  }
+
+  return deduped
+}
+
+export function configureWorkstreams(params: { agentRoster: readonly string[]; config?: LotaWorkstreamConfig }): void {
+  const bootstrap = params.config?.bootstrap
+  const onboardingWelcome = bootstrap?.onboardingWelcome
+  const onboardingDirectAgents = withDedupedStrings([
+    ...(bootstrap?.onboardingDirectAgents ?? params.agentRoster),
+    ...(onboardingWelcome ? [onboardingWelcome.directAgentId] : []),
+  ])
+
+  resolvedWorkstreamBootstrapConfig = {
+    onboardingDirectAgents,
+    completedDirectAgents: withDedupedStrings(bootstrap?.completedDirectAgents ?? params.agentRoster),
+    coreTypesAfterOnboarding: withDedupedStrings(bootstrap?.coreTypesAfterOnboarding ?? []),
+    ensureDefaultGroupOnCompleted: bootstrap?.ensureDefaultGroupOnCompleted ?? true,
+    ...(onboardingWelcome ? { onboardingWelcome } : {}),
+  }
+}
+
+export function getWorkstreamBootstrapConfig(): ResolvedWorkstreamBootstrapConfig {
+  return resolvedWorkstreamBootstrapConfig
+}