@lota-sdk/core 0.4.10 → 0.4.12

package/src/system-agents/thread-router.agent.ts

@@ -4,12 +4,7 @@ import { z } from 'zod'
 
 import { aiGatewayChatModel } from '../ai-gateway/ai-gateway'
 import { buildAiGatewayDirectCacheHeaders } from '../ai-gateway/cache-headers'
-import {
-  getAgentDescriptions,
-  getAgentDisplayNames,
-  getAgentShortDisplayNames,
-  getRouterModelId,
-} from '../config/agent-defaults'
+import type { ResolvedAgentConfig } from '../config/agent-defaults'
 import { chatLogger } from '../config/logger'
 import type { ValidationError } from '../effect/errors'
 import { AiGenerationError } from '../effect/errors'
@@ -28,6 +23,7 @@ export type RouterTriageResult = z.infer<typeof TriageResultSchema>
 export type RouterCheckResult = { done: true } | RouterCheckContinueResult
 
 interface RouterDisplayOptions {
+  agentConfig: ResolvedAgentConfig
   displayNamesById?: Partial<Record<string, string>>
   shortDisplayNamesById?: Partial<Record<string, string>>
   routingAliasesByAgentId?: Partial<Record<string, string[]>>
@@ -44,26 +40,26 @@ function readStringArrayOverride(
   return record && Object.hasOwn(record, key) ? record[key] : undefined
 }
 
-function readDisplayName(agentId: string, options?: RouterDisplayOptions): string {
-  const override = readStringOverride(options?.displayNamesById, agentId)
+function readDisplayName(agentId: string, options: RouterDisplayOptions): string {
+  const override = readStringOverride(options.displayNamesById, agentId)
   if (override !== undefined) {
     return override
   }
 
-  return getAgentDisplayNames()[agentId] ?? agentId
+  return options.agentConfig.displayNames[agentId] ?? agentId
 }
 
-function readShortDisplayName(agentId: string, options?: RouterDisplayOptions): string {
-  const override = readStringOverride(options?.shortDisplayNamesById, agentId)
+function readShortDisplayName(agentId: string, options: RouterDisplayOptions): string {
+  const override = readStringOverride(options.shortDisplayNamesById, agentId)
   if (override !== undefined) {
     return override
   }
 
-  return getAgentShortDisplayNames()[agentId] ?? readDisplayName(agentId, options)
+  return options.agentConfig.shortDisplayNames[agentId] ?? readDisplayName(agentId, options)
 }
 
-function buildMembersDescription(members: readonly string[], options?: RouterDisplayOptions): string {
-  const agentDescriptions = getAgentDescriptions()
+function buildMembersDescription(members: readonly string[], options: RouterDisplayOptions): string {
+  const agentDescriptions = options.agentConfig.descriptions
   return members
     .map((id) => {
       const display = readDisplayName(id, options)
@@ -77,7 +73,7 @@ function escapeRegex(value: string): string {
   return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 }
 
-function buildExplicitAgentRoutingContext(agentId: string, options?: RouterDisplayOptions): string {
+function buildExplicitAgentRoutingContext(agentId: string, options: RouterDisplayOptions): string {
   const displayName = readDisplayName(agentId, options)
   return `Respond directly to the part of the user's request explicitly addressed to ${displayName}.`
 }
@@ -85,16 +81,16 @@ function buildExplicitAgentRoutingContext(agentId: string, options?: RouterDispl
 function extractExplicitAgentTargets(
   messageText: string,
   members: readonly string[],
-  options?: RouterDisplayOptions,
+  options: RouterDisplayOptions,
 ): string[] {
   const normalizedMessage = messageText.trim()
   if (!normalizedMessage) return []
 
   const memberSet = new Set(members)
   const aliases = new Map<string, string>()
-  const defaultDisplayNames = options?.displayNamesById === undefined ? getAgentDisplayNames() : undefined
+  const defaultDisplayNames = options.displayNamesById === undefined ? options.agentConfig.displayNames : undefined
   const defaultShortDisplayNames =
-    options?.shortDisplayNamesById === undefined ? getAgentShortDisplayNames() : undefined
+    options.shortDisplayNamesById === undefined ? options.agentConfig.shortDisplayNames : undefined
 
   for (const member of members) {
     for (const rawAlias of [
@@ -103,7 +99,7 @@ function extractExplicitAgentTargets(
       defaultShortDisplayNames?.[member],
       readDisplayName(member, options),
       readShortDisplayName(member, options),
-      ...(readStringArrayOverride(options?.routingAliasesByAgentId, member) ?? []),
+      ...(readStringArrayOverride(options.routingAliasesByAgentId, member) ?? []),
     ]) {
       if (typeof rawAlias !== 'string') continue
       const alias = rawAlias.trim().toLowerCase()
@@ -173,12 +169,13 @@ function toRouterGenerationError(label: 'triage' | 'check', error: unknown): AiG
 }
 
 function generateRouterObjectEffect<TSchema extends z.ZodTypeAny>(params: {
+  agentConfig: ResolvedAgentConfig
   schema: TSchema
   system: string
   prompt: string
   label: 'triage' | 'check'
 }): Effect.Effect<z.infer<TSchema> | null, never> {
-  const modelId = getRouterModelId() ?? 'openrouter/openai/gpt-5.4-nano'
+  const modelId = params.agentConfig.routerModelId ?? 'openrouter/openai/gpt-5.4-nano'
 
   return Effect.tryPromise({
     try: () =>
@@ -219,6 +216,7 @@ function generateRouterObjectEffect<TSchema extends z.ZodTypeAny>(params: {
 }
 
 export function triageThreadMessage(params: {
+  agentConfig: ResolvedAgentConfig
   threadTitle: string
   members: readonly string[]
   messageText: string
@@ -230,6 +228,7 @@ export function triageThreadMessage(params: {
   return Effect.runPromise(
     Effect.gen(function* () {
       const displayOptions: RouterDisplayOptions = {
+        agentConfig: params.agentConfig,
         displayNamesById: params.displayNamesById,
         shortDisplayNamesById: params.shortDisplayNamesById,
         routingAliasesByAgentId: params.routingAliasesByAgentId,
@@ -254,6 +253,7 @@ export function triageThreadMessage(params: {
         .join('\n\n')
 
       const parsed = yield* generateRouterObjectEffect({
+        agentConfig: params.agentConfig,
         schema: TriageResultSchema,
         system: TRIAGE_SYSTEM_PROMPT,
         prompt,
@@ -279,6 +279,7 @@ export function triageThreadMessage(params: {
 }
 
 export function checkForNextAgent(params: {
+  agentConfig: ResolvedAgentConfig
   threadTitle: string
   members: readonly string[]
   messageText: string
@@ -291,6 +292,7 @@ export function checkForNextAgent(params: {
   return Effect.runPromise(
     Effect.gen(function* () {
       const displayOptions: RouterDisplayOptions = {
+        agentConfig: params.agentConfig,
         displayNamesById: params.displayNamesById,
         shortDisplayNamesById: params.shortDisplayNamesById,
         routingAliasesByAgentId: params.routingAliasesByAgentId,
@@ -320,6 +322,7 @@ export function checkForNextAgent(params: {
       ].join('\n\n')
 
       const parsed = yield* generateRouterObjectEffect({
+        agentConfig: params.agentConfig,
         schema: CheckResultObjectSchema,
         system: CHECK_SYSTEM_PROMPT,
         prompt,

package/src/tools/execution-plan.tool.ts

@@ -49,6 +49,8 @@ type ExecutionPlanExecutionPlanService = NoContextService<
 
 type ExecutionPlanToolValidationError = ReturnType<typeof toValidationError>
 
+export type ExecutionPlanToolRunPromise = <A, E>(effect: Effect.Effect<A, E, never>) => Promise<A>
+
 export function createExecutionPlanTool(params: {
   orgId: RecordIdRef
   userId: RecordIdRef
@@ -56,6 +58,7 @@ export function createExecutionPlanTool(params: {
   agentId: string
   executionPlanService: ExecutionPlanExecutionPlanService
   threadService: ExecutionPlanThreadService
+  runPromise: ExecutionPlanToolRunPromise
   onPlanChanged?: () => void
   validateInlinePlan?: (draft: ReturnType<typeof expandAgentPlanDraft>) => void
 }) {
@@ -64,7 +67,7 @@ export function createExecutionPlanTool(params: {
       'Manage execution plans. Actions: create (inline, 1-2 nodes), create-project (dedicated project thread, 3+ nodes), replace (swap active plan), resume (resume interrupted plan), update-node (submit result for a specific node).',
     inputSchema: ExecutionPlanArgsSchema,
     execute: (input) =>
-      Effect.runPromise(
+      params.runPromise(
         Effect.gen(function* () {
           const parsed = yield* parseExecutionPlanArgsEffect(input)
 
@@ -262,13 +265,14 @@ function extractAgentPlanDraftEffect(
 export function createExecutionPlanQueryTool(params: {
   threadId: RecordIdRef
   executionPlanService: Pick<ExecutionPlanExecutionPlanService, 'listActivePlanSummaries' | 'getActivePlanToolResult'>
+  runPromise: ExecutionPlanToolRunPromise
 }) {
   return tool({
     description:
       'Query execution plans. Omit runId to list all active plans. Provide runId to load a specific plan run.',
     inputSchema: ExecutionPlanQueryArgsSchema,
     execute: (input) =>
-      Effect.runPromise(
+      params.runPromise(
         Effect.gen(function* () {
           if (!input.runId) {
             return yield* params.executionPlanService.listActivePlanSummaries(params.threadId)
@@ -291,6 +295,7 @@ export function createSubmitExecutionNodeResultTool(params: {
   threadId: RecordIdRef
   agentId: string
   executionPlanService: Pick<ExecutionPlanExecutionPlanService, 'submitNodeResult'>
+  runPromise: ExecutionPlanToolRunPromise
   onPlanChanged?: () => void
 }) {
   return tool({
@@ -298,7 +303,7 @@ export function createSubmitExecutionNodeResultTool(params: {
       'Submit the result for the currently running execution node. The executor validates outputs, artifacts, and completion checks before advancing the run.',
     inputSchema: SubmitExecutionNodeResultArgsSchema,
     execute: (input) =>
-      Effect.runPromise(
+      params.runPromise(
         Effect.gen(function* () {
           const result = yield* params.executionPlanService.submitNodeResult({
             threadId: params.threadId,

package/src/tools/fetch-webpage.tool.ts

@@ -1,3 +1,4 @@
+import type Firecrawl from '@mendable/firecrawl-js'
 import { tool } from 'ai'
 import { Effect, Schema } from 'effect'
 import { z } from 'zod'
@@ -6,10 +7,13 @@ import type { ToolDefinition } from '../ai/definitions'
 import { withTimeout } from '../utils/async'
 import { nowIsoDateTimeString } from '../utils/date-time'
 import { readStringField, truncateOptionalText } from '../utils/string'
-import { getFirecrawlClient } from './firecrawl-client'
 import type { WebCitation } from './tool-contracts'
 import { toRecord, WEB_TOOL_TIMEOUT_MS } from './web-tool-shared'
 
+export interface FetchWebpageToolContext {
+  firecrawl: Firecrawl
+}
+
 class FetchWebpageToolError extends Schema.TaggedErrorClass<FetchWebpageToolError>()(
   '@lota-sdk/core/FetchWebpageToolError',
   { message: Schema.String, cause: Schema.optional(Schema.Defect) },
@@ -98,7 +102,7 @@ function buildFetchCitations(url: string, document: unknown): WebCitation[] {
 
 export const fetchWebpageTool = {
   name: 'fetchWebpage',
-  create: () =>
+  create: ({ firecrawl }: FetchWebpageToolContext) =>
     tool({
       description: 'Retrieve and parse a single webpage.',
       inputSchema: z
@@ -119,10 +123,8 @@ export const fetchWebpageTool = {
         formats?: z.infer<typeof FormatSchema>[]
         onlyMainContent?: boolean
         maxAge?: number
-      }) => {
-        const firecrawl = getFirecrawlClient()
-
-        return Effect.runPromise(
+      }) =>
+        Effect.runPromise(
           Effect.gen(function* () {
             const result = yield* Effect.tryPromise({
               try: () =>
@@ -139,7 +141,6 @@ export const fetchWebpageTool = {
             })
             return { url, document: summarizeDocument(url, result), citations: buildFetchCitations(url, result) }
           }).pipe(Effect.withSpan('tool.fetchWebpage.execute')),
-        )
-      },
+        ),
     }),
-} as const satisfies ToolDefinition<void>
+} as const satisfies ToolDefinition<FetchWebpageToolContext>

package/src/tools/firecrawl-client.ts

@@ -1,7 +1,6 @@
 import Firecrawl from '@mendable/firecrawl-js'
 import { Context, Effect, Layer } from 'effect'
 
-import { resolveLotaService } from '../effect/runtime'
 import { RuntimeConfigServiceTag } from '../effect/services'
 
 export class FirecrawlTag extends Context.Service<FirecrawlTag, Firecrawl>()('@lota-sdk/core/Firecrawl') {}
@@ -16,17 +15,3 @@ export const FirecrawlLive = Layer.effect(
     })
   }),
 )
-
-let currentFirecrawlClient: Firecrawl | null = null
-
-export function configureFirecrawlClient(client: Firecrawl): void {
-  currentFirecrawlClient = client
-}
-
-export function clearFirecrawlClient(): void {
-  currentFirecrawlClient = null
-}
-
-export function getFirecrawlClient(): Firecrawl {
-  return currentFirecrawlClient ?? resolveLotaService(FirecrawlTag)
-}

package/src/tools/remember-memory.tool.ts

@@ -5,7 +5,6 @@ import { z } from 'zod'
 import type { RecordIdRef } from '../db/record-id'
 import { recordIdToString } from '../db/record-id'
 import { TABLES } from '../db/tables'
-import type { MaybeAwaitableService } from '../effect/awaitable-effect'
 import type { createMemoryService } from '../services/memory/memory.service'
 import { safeEnqueue } from '../utils/async'
 
@@ -16,11 +15,9 @@ const RememberMemoryInputSchema = z
   })
   .strict()
 
-type RememberMemoryService = MaybeAwaitableService<
-  Pick<
-    ReturnType<typeof createMemoryService>,
-    'assessMemoryCandidate' | 'createOrganizationMemory' | 'createAgentMemory'
-  >
+type RememberMemoryService = Pick<
+  ReturnType<typeof createMemoryService>,
+  'assessMemoryCandidate' | 'createOrganizationMemory' | 'createAgentMemory'
 >
 
 export function createRememberMemoryTool({

package/src/tools/research-topic.tool.ts

@@ -1,15 +1,21 @@
+import type Firecrawl from '@mendable/firecrawl-js'
+
 import { aiGatewayChatModel } from '../ai-gateway/ai-gateway'
 import { buildAiGatewayStrictSemanticCacheHeaders } from '../ai-gateway/cache-headers'
 import {
   OPENROUTER_FAST_REASONING_MODEL_ID,
   OPENROUTER_LOW_REASONING_PROVIDER_OPTIONS,
 } from '../config/model-constants'
-import { createDelegatedAgentTool } from '../system-agents/delegated-agent-factory'
+import { createDelegatedAgentToolWithContext } from '../system-agents/delegated-agent-factory'
 import { RESEARCHER_PROMPT } from '../system-agents/researcher.agent'
 import { fetchWebpageTool } from './fetch-webpage.tool'
 import { searchWebTool } from './search-web.tool'
 
-export const researchTopicTool = createDelegatedAgentTool({
+export interface ResearchTopicToolContext {
+  firecrawl: Firecrawl
+}
+
+export const researchTopicTool = createDelegatedAgentToolWithContext<ResearchTopicToolContext>({
   id: 'researchTopic',
   description:
     'Delegate a research task to a dedicated research agent that searches the web, fetches pages, and returns a synthesized markdown report.',
@@ -17,6 +23,9 @@ export const researchTopicTool = createDelegatedAgentTool({
   providerOptions: OPENROUTER_LOW_REASONING_PROVIDER_OPTIONS,
   headers: buildAiGatewayStrictSemanticCacheHeaders('researchTopic'),
   instructions: RESEARCHER_PROMPT,
-  tools: { searchWeb: searchWebTool.create(), fetchWebpage: fetchWebpageTool.create() },
+  createTools: ({ firecrawl }) => ({
+    searchWeb: searchWebTool.create({ firecrawl }),
+    fetchWebpage: fetchWebpageTool.create({ firecrawl }),
+  }),
   maxSteps: 6,
 })

package/src/tools/search-web.tool.ts

@@ -1,3 +1,4 @@
+import type Firecrawl from '@mendable/firecrawl-js'
 import { tool } from 'ai'
 import { Effect, Schema } from 'effect'
 import { z } from 'zod'
@@ -6,10 +7,13 @@ import type { ToolDefinition } from '../ai/definitions'
 import { withTimeout } from '../utils/async'
 import { nowIsoDateTimeString } from '../utils/date-time'
 import { readStringField, truncateOptionalText } from '../utils/string'
-import { getFirecrawlClient } from './firecrawl-client'
 import type { WebCitation } from './tool-contracts'
 import { toRecord, WEB_TOOL_TIMEOUT_MS } from './web-tool-shared'
 
+export interface SearchWebToolContext {
+  firecrawl: Firecrawl
+}
+
 class SearchWebToolError extends Schema.TaggedErrorClass<SearchWebToolError>()('@lota-sdk/core/SearchWebToolError', {
   message: Schema.String,
   cause: Schema.optional(Schema.Defect),
@@ -135,7 +139,7 @@ function buildWebCitations(results: { web?: unknown[]; news?: unknown[]; images?
 
 export const searchWebTool = {
   name: 'searchWeb',
-  create: () =>
+  create: ({ firecrawl }: SearchWebToolContext) =>
     tool({
       description: 'Search the web for real-time information.',
       inputSchema: z
@@ -159,10 +163,8 @@ export const searchWebTool = {
         sources?: ('web' | 'news' | 'images')[]
         location?: string
         tbs?: string
-      }) => {
-        const firecrawl = getFirecrawlClient()
-
-        return Effect.runPromise(
+      }) =>
+        Effect.runPromise(
           Effect.gen(function* () {
             const results = yield* Effect.tryPromise({
               try: () =>
@@ -183,7 +185,6 @@ export const searchWebTool = {
               citations: buildWebCitations(results),
             }
           }).pipe(Effect.withSpan('tool.searchWeb.execute')),
-        )
-      },
+        ),
     }),
-} as const satisfies ToolDefinition<void>
+} as const satisfies ToolDefinition<SearchWebToolContext>

package/src/tools/search.tool.ts

@@ -2,9 +2,9 @@ import { tool } from 'ai'
 import { Effect } from 'effect'
 import { z } from 'zod'
 
+import type { ResolvedAgentConfig } from '../config/agent-defaults'
 import { isAgentName } from '../config/agent-defaults'
 import type { RecordIdRef } from '../db/record-id'
-import type { MaybeAwaitableService } from '../effect/awaitable-effect'
 import type { createMemoryService } from '../services/memory/memory.service'
 import type { makeThreadMessageService } from '../services/thread/thread-message.service'
 
@@ -12,12 +12,11 @@ const CONVERSATION_SEARCH_RESULT_LIMIT = 20
 const MemorySearchInputSchema = z.object({ query: z.string().min(1) }).strict()
 const ConversationSearchInputSchema = z.object({ query: z.string().min(1), type: z.enum(['user', 'agent']) }).strict()
 
-type MemorySearchService = MaybeAwaitableService<
-  Pick<ReturnType<typeof createMemoryService>, 'searchAllMemoriesBatched'>
->
+type MemorySearchService = Pick<ReturnType<typeof createMemoryService>, 'searchAllMemoriesBatched'>
 type ConversationSearchService = Pick<ReturnType<typeof makeThreadMessageService>, 'searchMessagesEffect'>
 
 export function createMemorySearchTool(
+  agentConfig: ResolvedAgentConfig,
   orgIdString: string,
   memoryService: MemorySearchService,
   agentName?: string,
@@ -32,7 +31,7 @@ export function createMemorySearchTool(
           const normalizedQuery = query.trim()
           const retrieval = yield* memoryService.searchAllMemoriesBatched({
             orgId: orgIdString,
-            agentName: isAgentName(agentName) ? agentName : undefined,
+            agentName: isAgentName(agentConfig, agentName) ? agentName : undefined,
             query: normalizedQuery,
             ...(typeof options?.fastMode === 'boolean' ? { fastMode: options.fastMode } : {}),
             ...(typeof options?.allowMultiScopeRerank === 'boolean'