@lota-sdk/core 0.4.9 → 0.4.11

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

@@ -24,22 +24,33 @@ import { toValidationError } from '../effect/zod'
 import type { makeExecutionPlanService } from '../services/execution-plan/execution-plan.service'
 import type { makeThreadService } from '../services/thread/thread.service'
 
-type ExecutionPlanThreadService = Pick<
-  ReturnType<typeof makeThreadService>,
-  'createThread' | 'deleteThread' | 'getThread'
+type NoContextService<TService> = {
+  [K in keyof TService]: TService[K] extends (...args: infer TArgs) => Effect.Effect<infer A, infer E, unknown>
+    ? (...args: TArgs) => Effect.Effect<A, E, never>
+    : TService[K]
+}
+
+type ExecutionPlanThreadService = NoContextService<
+  Pick<ReturnType<typeof makeThreadService>, 'createThread' | 'deleteThread' | 'getThread'>
 >
 
-type ExecutionPlanExecutionPlanService = Pick<
-  ReturnType<typeof makeExecutionPlanService>,
-  | 'createPlan'
-  | 'replacePlan'
-  | 'resumeRun'
-  | 'submitNodeResult'
-  | 'listActivePlanSummaries'
-  | 'getActivePlanToolResult'
-  | 'getActivePlansForThread'
+type ExecutionPlanExecutionPlanService = NoContextService<
+  Pick<
+    ReturnType<typeof makeExecutionPlanService>,
+    | 'createPlan'
+    | 'replacePlan'
+    | 'resumeRun'
+    | 'submitNodeResult'
+    | 'listActivePlanSummaries'
+    | 'getActivePlanToolResult'
+    | 'getActivePlansForThread'
+  >
 >
 
+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
@@ -47,6 +58,7 @@ export function createExecutionPlanTool(params: {
   agentId: string
   executionPlanService: ExecutionPlanExecutionPlanService
   threadService: ExecutionPlanThreadService
+  runPromise: ExecutionPlanToolRunPromise
   onPlanChanged?: () => void
   validateInlinePlan?: (draft: ReturnType<typeof expandAgentPlanDraft>) => void
 }) {
@@ -55,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)
 
@@ -198,12 +210,14 @@ export function createExecutionPlanTool(params: {
               return result
             }
           }
-        }),
+        }).pipe(Effect.withSpan('tool.executionPlan.execute')),
       ),
   })
 }
 
-function parseExecutionPlanArgsEffect(input: unknown) {
+function parseExecutionPlanArgsEffect(
+  input: unknown,
+): Effect.Effect<ExecutionPlanArgs, ExecutionPlanToolValidationError> {
   return Effect.gen(function* () {
     const parsedArgs = ExecutionPlanArgsSchema.safeParse(input)
     if (!parsedArgs.success) {
@@ -233,7 +247,7 @@ function parseExecutionPlanArgsEffect(input: unknown) {
 
 function extractAgentPlanDraftEffect(
   input: Extract<ExecutionPlanArgs, { action: 'create' | 'create-project' | 'replace' }>,
-) {
+): Effect.Effect<ReturnType<typeof expandAgentPlanDraft>, ExecutionPlanToolValidationError> {
   return Effect.gen(function* () {
     const parsedDraft = AgentPlanDraftSchema.safeParse({
       title: input.title,
@@ -251,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)
@@ -271,7 +286,7 @@ export function createExecutionPlanQueryTool(params: {
             includeCheckpoints: input.includeCheckpoints,
             includeValidationIssues: input.includeValidationIssues,
           })
-        }),
+        }).pipe(Effect.withSpan('tool.executionPlanQuery.execute')),
       ),
   })
 }
@@ -280,6 +295,7 @@ export function createSubmitExecutionNodeResultTool(params: {
   threadId: RecordIdRef
   agentId: string
   executionPlanService: Pick<ExecutionPlanExecutionPlanService, 'submitNodeResult'>
+  runPromise: ExecutionPlanToolRunPromise
   onPlanChanged?: () => void
 }) {
   return tool({
@@ -287,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,
@@ -296,7 +312,7 @@ export function createSubmitExecutionNodeResultTool(params: {
           })
           params.onPlanChanged?.()
           return result
-        }),
+        }).pipe(Effect.withSpan('tool.submitExecutionNodeResult.execute')),
       ),
     toModelOutput: ({ output }) => {
       const result = getLatestExecutionPlanResult(output)

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

@@ -1,15 +1,24 @@
+import type Firecrawl from '@mendable/firecrawl-js'
 import { tool } from 'ai'
-import { Effect } from 'effect'
+import { Effect, Schema } from 'effect'
 import { z } from 'zod'
 
 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) },
+) {}
+
 const FormatSchema = z.enum(['markdown', 'html', 'rawHtml', 'links', 'images', 'screenshot', 'summary'])
 const MAX_MARKDOWN_CHARS = 6_000
 const MAX_SUMMARY_CHARS = 1_200
@@ -93,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
@@ -114,25 +123,24 @@ 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(() =>
-              withTimeout(
-                firecrawl.scrape(url, {
-                  formats: formats?.length ? formats : ['markdown'],
-                  onlyMainContent: onlyMainContent ?? true,
-                  maxAge,
-                }),
-                WEB_TOOL_TIMEOUT_MS,
-                'Webpage fetch',
-              ),
-            )
+            const result = yield* Effect.tryPromise({
+              try: () =>
+                withTimeout(
+                  firecrawl.scrape(url, {
+                    formats: formats?.length ? formats : ['markdown'],
+                    onlyMainContent: onlyMainContent ?? true,
+                    maxAge,
+                  }),
+                  WEB_TOOL_TIMEOUT_MS,
+                  'Webpage fetch',
+                ),
+              catch: (cause) => new FetchWebpageToolError({ message: `Webpage fetch failed for ${url}.`, cause }),
+            })
             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,10 +1,9 @@
 import Firecrawl from '@mendable/firecrawl-js'
 import { Context, Effect, Layer } from 'effect'
 
-import { getCurrentRuntime } from '../effect/runtime-ref'
 import { RuntimeConfigServiceTag } from '../effect/services'
 
-export class FirecrawlTag extends Context.Service<FirecrawlTag, Firecrawl>()('Firecrawl') {}
+export class FirecrawlTag extends Context.Service<FirecrawlTag, Firecrawl>()('@lota-sdk/core/Firecrawl') {}
 
 export const FirecrawlLive = Layer.effect(
   FirecrawlTag,
@@ -16,7 +15,3 @@ export const FirecrawlLive = Layer.effect(
     })
   }),
 )
-
-export function getFirecrawlClient(): Firecrawl {
-  return getCurrentRuntime().runSync(Effect.service(FirecrawlTag))
-}

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

@@ -6,7 +6,15 @@ import type { RecordIdRef } from '../db/record-id'
 import type { makeExecutionPlanService } from '../services/execution-plan/execution-plan.service'
 import { toToolPlanSummary } from '../services/plan/plan-run-data'
 
-type PlanApprovalExecutionPlanService = Pick<ReturnType<typeof makeExecutionPlanService>, 'approvePlan' | 'rejectPlan'>
+type NoContextService<TService> = {
+  [K in keyof TService]: TService[K] extends (...args: infer TArgs) => Effect.Effect<infer A, infer E, unknown>
+    ? (...args: TArgs) => Effect.Effect<A, E, never>
+    : TService[K]
+}
+
+type PlanApprovalExecutionPlanService = NoContextService<
+  Pick<ReturnType<typeof makeExecutionPlanService>, 'approvePlan' | 'rejectPlan'>
+>
 
 export function createPlanApprovalTool(params: {
   orgId: RecordIdRef

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,15 +1,24 @@
+import type Firecrawl from '@mendable/firecrawl-js'
 import { tool } from 'ai'
-import { Effect } from 'effect'
+import { Effect, Schema } from 'effect'
 import { z } from 'zod'
 
 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),
+}) {}
+
 const SourceSchema = z.enum(['web', 'news', 'images'])
 const MAX_RESULTS_PER_SOURCE = 4
 const MAX_SNIPPET_CHARS = 320
@@ -130,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
@@ -154,18 +163,18 @@ 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(() =>
-              withTimeout(
-                firecrawl.search(query, { limit, sources, location, tbs }),
-                WEB_TOOL_TIMEOUT_MS,
-                'Web search',
-              ),
-            )
+            const results = yield* Effect.tryPromise({
+              try: () =>
+                withTimeout(
+                  firecrawl.search(query, { limit, sources, location, tbs }),
+                  WEB_TOOL_TIMEOUT_MS,
+                  'Web search',
+                ),
+              catch: (cause) => new SearchWebToolError({ message: 'Web search request failed.', cause }),
+            })
             return {
               query,
               results: {
@@ -175,8 +184,7 @@ 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'