@lota-sdk/core 0.4.8 → 0.4.9

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

@@ -13,17 +13,24 @@ import {
 } from '@lota-sdk/shared'
 import type { CreateProjectWithPlanResultData, ExecutionPlanArgs } from '@lota-sdk/shared'
 import { tool } from 'ai'
+import { Effect } from 'effect'
 
+import { serverLogger } from '../config/logger'
 import type { RecordIdRef } from '../db/record-id'
 import { recordIdToString } from '../db/record-id'
 import { TABLES } from '../db/tables'
-import { executionPlanService } from '../services/execution-plan.service'
-import { threadService } from '../services/thread.service'
+import { BadRequestError, ConflictError, ForbiddenError } from '../effect/errors'
+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<typeof threadService, 'createThread' | 'deleteThread' | 'getThread'>
+type ExecutionPlanThreadService = Pick<
+  ReturnType<typeof makeThreadService>,
+  'createThread' | 'deleteThread' | 'getThread'
+>
 
 type ExecutionPlanExecutionPlanService = Pick<
-  typeof executionPlanService,
+  ReturnType<typeof makeExecutionPlanService>,
   | 'createPlan'
   | 'replacePlan'
   | 'resumeRun'
@@ -38,207 +45,259 @@ export function createExecutionPlanTool(params: {
   userId: RecordIdRef
   threadId: RecordIdRef
   agentId: string
-  executionPlanService?: ExecutionPlanExecutionPlanService
-  threadService?: ExecutionPlanThreadService
+  executionPlanService: ExecutionPlanExecutionPlanService
+  threadService: ExecutionPlanThreadService
   onPlanChanged?: () => void
   validateInlinePlan?: (draft: ReturnType<typeof expandAgentPlanDraft>) => void
 }) {
-  const resolvedEpService = params.executionPlanService ?? executionPlanService
-  const resolvedWsService = params.threadService ?? threadService
-
   return tool({
     description:
       '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: async (input) => {
-      const parsed = parseExecutionPlanArgs(input)
-      let result: unknown
-
-      switch (parsed.action) {
-        case 'create': {
-          const draft = extractAgentPlanDraft(parsed)
-          params.validateInlinePlan?.(draft)
-          const targetThreadId = parsed.targetThreadId ?? params.threadId
-          const isCrossThreadTarget =
-            recordIdToString(targetThreadId, TABLES.THREAD) !== recordIdToString(params.threadId, TABLES.THREAD)
-          result = await resolvedEpService.createPlan({
-            organizationId: params.orgId,
-            threadId: targetThreadId,
-            ...(isCrossThreadTarget ? { sourceThreadId: params.threadId } : {}),
-            leadAgentId: params.agentId,
-            createdByAgentId: params.agentId,
-            requireApproval: parsed.requireApproval ?? isCrossThreadTarget,
-            input: draft,
-          })
-          break
-        }
-
-        case 'create-project': {
-          const draft = extractAgentPlanDraft(parsed)
-          const targetThread = parsed.targetThreadId
-            ? await resolvedWsService.getThread(parsed.targetThreadId)
-            : await (() => {
-                if (!parsed.projectTitle) {
-                  throw new Error('projectTitle is required when action is "create-project".')
+    execute: (input) =>
+      Effect.runPromise(
+        Effect.gen(function* () {
+          const parsed = yield* parseExecutionPlanArgsEffect(input)
+
+          switch (parsed.action) {
+            case 'create': {
+              const draft = yield* extractAgentPlanDraftEffect(parsed)
+              params.validateInlinePlan?.(draft)
+              const targetThreadId = parsed.targetThreadId ?? params.threadId
+              const isCrossThreadTarget =
+                recordIdToString(targetThreadId, TABLES.THREAD) !== recordIdToString(params.threadId, TABLES.THREAD)
+              const result = yield* params.executionPlanService.createPlan({
+                organizationId: params.orgId,
+                threadId: targetThreadId,
+                ...(isCrossThreadTarget ? { sourceThreadId: params.threadId } : {}),
+                leadAgentId: params.agentId,
+                createdByAgentId: params.agentId,
+                requireApproval: parsed.requireApproval ?? isCrossThreadTarget,
+                input: draft,
+              })
+              params.onPlanChanged?.()
+              return result
+            }
+
+            case 'create-project': {
+              const draft = yield* extractAgentPlanDraftEffect(parsed)
+              let createdThreadId: string | null = null
+
+              const cleanupLeakedThread = (threadId: string) =>
+                params.threadService.deleteThread(threadId).pipe(
+                  Effect.catch((cleanupError: unknown) =>
+                    Effect.sync(() => {
+                      serverLogger.warn`Failed to clean up leaked execution-plan project thread ${threadId}: ${cleanupError}`
+                    }),
+                  ),
+                )
+
+              const projectEffect = Effect.gen(function* () {
+                const projectTitle = parsed.projectTitle
+                const targetThreadId = parsed.targetThreadId
+                const targetThread = targetThreadId
+                  ? yield* params.threadService.getThread(targetThreadId)
+                  : yield* (() => {
+                      if (!projectTitle) {
+                        return new BadRequestError({
+                          message: 'projectTitle is required when action is "create-project".',
+                        })
+                      }
+
+                      return params.threadService.createThread({
+                        userId: params.userId,
+                        organizationId: params.orgId,
+                        title: projectTitle,
+                        type: 'group',
+                      })
+                    })()
+
+                if (!parsed.targetThreadId) {
+                  createdThreadId = targetThread.id
+                }
+
+                if (targetThread.organizationId !== recordIdToString(params.orgId, TABLES.ORGANIZATION)) {
+                  return yield* new ForbiddenError({ message: 'Target thread belongs to a different organization.' })
+                }
+                if (targetThread.userId !== recordIdToString(params.userId, TABLES.USER)) {
+                  return yield* new ForbiddenError({ message: 'Target thread belongs to a different user.' })
+                }
+
+                const existingPlans = yield* params.executionPlanService.getActivePlansForThread(targetThread.id)
+                if (targetThread.type !== 'thread' && existingPlans.length > 0) {
+                  return yield* new ConflictError({
+                    message:
+                      'This thread already has an active execution plan. Use action "replace" or target a core thread.',
+                  })
                 }
 
-                return resolvedWsService.createThread({
-                  userId: params.userId,
+                const created = yield* params.executionPlanService.createPlan({
                   organizationId: params.orgId,
-                  title: parsed.projectTitle,
-                  type: 'group',
+                  threadId: targetThread.id,
+                  sourceThreadId: params.threadId,
+                  leadAgentId: params.agentId,
+                  createdByAgentId: params.agentId,
+                  requireApproval: parsed.requireApproval ?? true,
+                  input: draft,
                 })
-              })()
-
-          if (targetThread.organizationId !== recordIdToString(params.orgId, TABLES.ORGANIZATION)) {
-            throw new Error('Target thread belongs to a different organization.')
-          }
-          if (targetThread.userId !== recordIdToString(params.userId, TABLES.USER)) {
-            throw new Error('Target thread belongs to a different user.')
-          }
 
-          const existingPlans = await resolvedEpService.getActivePlansForThread(targetThread.id)
-          if (targetThread.type !== 'thread' && existingPlans.length > 0) {
-            throw new Error(
-              'This thread already has an active execution plan. Use action "replace" or target a core thread.',
-            )
-          }
+                const result = {
+                  ...created,
+                  runId: created.plan?.runId ?? '',
+                  threadId: targetThread.id,
+                  threadTitle: targetThread.title,
+                  createdThread: createdThreadId !== null,
+                } satisfies CreateProjectWithPlanResultData
+                params.onPlanChanged?.()
+                return result
+              }).pipe(Effect.tapError(() => (createdThreadId ? cleanupLeakedThread(createdThreadId) : Effect.void)))
 
-          const createdThread = !parsed.targetThreadId
-          try {
-            const created = await resolvedEpService.createPlan({
-              organizationId: params.orgId,
-              threadId: targetThread.id,
-              sourceThreadId: params.threadId,
-              leadAgentId: params.agentId,
-              createdByAgentId: params.agentId,
-              requireApproval: parsed.requireApproval ?? true,
-              input: draft,
-            })
-            result = {
-              ...created,
-              runId: created.plan?.runId ?? '',
-              threadId: targetThread.id,
-              threadTitle: targetThread.title,
-              createdThread,
-            } satisfies CreateProjectWithPlanResultData
-          } catch (error) {
-            if (createdThread) {
-              await resolvedWsService.deleteThread(targetThread.id).catch(() => {})
+              return yield* projectEffect
             }
-            throw error
-          }
-          break
-        }
-
-        case 'replace': {
-          const draft = extractAgentPlanDraft(parsed)
-          result = await resolvedEpService.replacePlan({
-            organizationId: params.orgId,
-            threadId: params.threadId,
-            leadAgentId: params.agentId,
-            createdByAgentId: params.agentId,
-            input: { runId: parsed.runId, reason: parsed.reason, requireApproval: parsed.requireApproval, ...draft },
-          })
-          break
-        }
 
-        case 'resume':
-          result = await resolvedEpService.resumeRun({
-            threadId: params.threadId,
-            emittedBy: params.agentId,
-            input: { runId: parsed.runId },
-          })
-          break
+            case 'replace': {
+              const draft = yield* extractAgentPlanDraftEffect(parsed)
+              const result = yield* params.executionPlanService.replacePlan({
+                organizationId: params.orgId,
+                threadId: params.threadId,
+                leadAgentId: params.agentId,
+                createdByAgentId: params.agentId,
+                input: {
+                  runId: parsed.runId,
+                  reason: parsed.reason,
+                  requireApproval: parsed.requireApproval,
+                  ...draft,
+                },
+              })
+              params.onPlanChanged?.()
+              return result
+            }
 
-        case 'update-node':
-          result = await resolvedEpService.submitNodeResult({
-            threadId: params.threadId,
-            emittedBy: params.agentId,
-            input: {
-              runId: parsed.runId,
-              nodeId: parsed.node.id,
-              notes: parsed.node.latestNotes,
-              artifacts: parsed.node.deliverables ?? [],
-            },
-          })
-          break
-      }
+            case 'resume': {
+              const result = yield* params.executionPlanService.resumeRun({
+                threadId: params.threadId,
+                emittedBy: params.agentId,
+                input: { runId: parsed.runId },
+              })
+              params.onPlanChanged?.()
+              return result
+            }
 
-      params.onPlanChanged?.()
-      return result
-    },
+            case 'update-node': {
+              const result = yield* params.executionPlanService.submitNodeResult({
+                threadId: params.threadId,
+                emittedBy: params.agentId,
+                input: {
+                  runId: parsed.runId,
+                  nodeId: parsed.node.id,
+                  notes: parsed.node.latestNotes,
+                  artifacts: parsed.node.deliverables ?? [],
+                },
+              })
+              params.onPlanChanged?.()
+              return result
+            }
+          }
+        }),
+      ),
   })
 }
 
-function parseExecutionPlanArgs(input: unknown): ExecutionPlanArgs {
-  const parsed = ExecutionPlanArgsSchema.parse(input)
-
-  switch (parsed.action) {
-    case 'create':
-      return ExecutionPlanCreateArgsSchema.parse(parsed)
-    case 'create-project':
-      return ExecutionPlanCreateProjectArgsSchema.parse(parsed)
-    case 'replace':
-      return ExecutionPlanReplaceArgsSchema.parse(parsed)
-    case 'resume':
-      return ExecutionPlanResumeArgsSchema.parse(parsed)
-    case 'update-node':
-      return ExecutionPlanUpdateNodeArgsSchema.parse(parsed)
-  }
+function parseExecutionPlanArgsEffect(input: unknown) {
+  return Effect.gen(function* () {
+    const parsedArgs = ExecutionPlanArgsSchema.safeParse(input)
+    if (!parsedArgs.success) {
+      return yield* toValidationError(parsedArgs.error, 'Invalid execution plan tool input')
+    }
+    const parsed = parsedArgs.data
+
+    const parseAction = <T>(result: { success: true; data: T } | { success: false; error: unknown }) =>
+      result.success
+        ? Effect.succeed(result.data)
+        : Effect.fail(toValidationError(result.error, 'Invalid execution plan action input'))
+
+    switch (parsed.action) {
+      case 'create':
+        return yield* parseAction(ExecutionPlanCreateArgsSchema.safeParse(parsed))
+      case 'create-project':
+        return yield* parseAction(ExecutionPlanCreateProjectArgsSchema.safeParse(parsed))
+      case 'replace':
+        return yield* parseAction(ExecutionPlanReplaceArgsSchema.safeParse(parsed))
+      case 'resume':
+        return yield* parseAction(ExecutionPlanResumeArgsSchema.safeParse(parsed))
+      case 'update-node':
+        return yield* parseAction(ExecutionPlanUpdateNodeArgsSchema.safeParse(parsed))
+    }
+  })
 }
 
-function extractAgentPlanDraft(input: Extract<ExecutionPlanArgs, { action: 'create' | 'create-project' | 'replace' }>) {
-  return expandAgentPlanDraft(
-    AgentPlanDraftSchema.parse({
+function extractAgentPlanDraftEffect(
+  input: Extract<ExecutionPlanArgs, { action: 'create' | 'create-project' | 'replace' }>,
+) {
+  return Effect.gen(function* () {
+    const parsedDraft = AgentPlanDraftSchema.safeParse({
       title: input.title,
       objective: input.objective,
       nodes: input.nodes,
       edges: input.edges,
-    }),
-  )
+    })
+    if (!parsedDraft.success) {
+      return yield* toValidationError(parsedDraft.error, 'Invalid execution plan draft')
+    }
+    return expandAgentPlanDraft(parsedDraft.data)
+  })
 }
 
-export function createExecutionPlanQueryTool(params: { threadId: RecordIdRef }) {
+export function createExecutionPlanQueryTool(params: {
+  threadId: RecordIdRef
+  executionPlanService: Pick<ExecutionPlanExecutionPlanService, 'listActivePlanSummaries' | 'getActivePlanToolResult'>
+}) {
   return tool({
     description:
       'Query execution plans. Omit runId to list all active plans. Provide runId to load a specific plan run.',
     inputSchema: ExecutionPlanQueryArgsSchema,
-    execute: async (input) => {
-      if (!input.runId) {
-        return await executionPlanService.listActivePlanSummaries(params.threadId)
-      }
-      return await executionPlanService.getActivePlanToolResult({
-        threadId: params.threadId,
-        runId: input.runId,
-        includeEvents: input.includeEvents,
-        includeArtifacts: input.includeArtifacts,
-        includeApprovals: input.includeApprovals,
-        includeCheckpoints: input.includeCheckpoints,
-        includeValidationIssues: input.includeValidationIssues,
-      })
-    },
+    execute: (input) =>
+      Effect.runPromise(
+        Effect.gen(function* () {
+          if (!input.runId) {
+            return yield* params.executionPlanService.listActivePlanSummaries(params.threadId)
+          }
+          return yield* params.executionPlanService.getActivePlanToolResult({
+            threadId: params.threadId,
+            runId: input.runId,
+            includeEvents: input.includeEvents,
+            includeArtifacts: input.includeArtifacts,
+            includeApprovals: input.includeApprovals,
+            includeCheckpoints: input.includeCheckpoints,
+            includeValidationIssues: input.includeValidationIssues,
+          })
+        }),
+      ),
   })
 }
 
 export function createSubmitExecutionNodeResultTool(params: {
   threadId: RecordIdRef
   agentId: string
+  executionPlanService: Pick<ExecutionPlanExecutionPlanService, 'submitNodeResult'>
   onPlanChanged?: () => void
 }) {
   return tool({
     description:
       'Submit the result for the currently running execution node. The executor validates outputs, artifacts, and completion checks before advancing the run.',
     inputSchema: SubmitExecutionNodeResultArgsSchema,
-    execute: async (input) => {
-      const result = await executionPlanService.submitNodeResult({
-        threadId: params.threadId,
-        emittedBy: params.agentId,
-        input,
-      })
-      params.onPlanChanged?.()
-      return result
-    },
+    execute: (input) =>
+      Effect.runPromise(
+        Effect.gen(function* () {
+          const result = yield* params.executionPlanService.submitNodeResult({
+            threadId: params.threadId,
+            emittedBy: params.agentId,
+            input,
+          })
+          params.onPlanChanged?.()
+          return result
+        }),
+      ),
     toModelOutput: ({ output }) => {
       const result = getLatestExecutionPlanResult(output)
       const summary = result?.message?.trim()

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

@@ -1,24 +1,21 @@
 import { tool } from 'ai'
+import { Effect } 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'
 
-const TOOL_TIMEOUT_MS = 30_000
 const FormatSchema = z.enum(['markdown', 'html', 'rawHtml', 'links', 'images', 'screenshot', 'summary'])
 const MAX_MARKDOWN_CHARS = 6_000
 const MAX_SUMMARY_CHARS = 1_200
 const MAX_LINKS = 25
 const MAX_IMAGES = 10
 
-function toRecord(value: unknown): Record<string, unknown> | null {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) return null
-  return value as Record<string, unknown>
-}
-
 function readStringList(record: Record<string, unknown>, key: string, maxItems: number): string[] {
   const value = record[key]
   if (!Array.isArray(value)) return []
@@ -91,7 +88,7 @@ function buildFetchCitations(url: string, document: unknown): WebCitation[] {
     }
   }
 
-  return [{ source: 'web', sourceId, retrievedAt: new Date().toISOString() }]
+  return [{ source: 'web', sourceId, retrievedAt: nowIsoDateTimeString() }]
 }
 
 export const fetchWebpageTool = {
@@ -107,7 +104,7 @@ export const fetchWebpageTool = {
           maxAge: z.number().int().min(1).optional(),
         })
         .strict(),
-      execute: async ({
+      execute: ({
         url,
         formats,
         onlyMainContent,
@@ -118,17 +115,24 @@ export const fetchWebpageTool = {
         onlyMainContent?: boolean
         maxAge?: number
       }) => {
-        const result = await withTimeout(
-          getFirecrawlClient().scrape(url, {
-            formats: formats?.length ? formats : ['markdown'],
-            onlyMainContent: onlyMainContent ?? true,
-            maxAge,
+        const firecrawl = getFirecrawlClient()
+
+        return 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',
+              ),
+            )
+            return { url, document: summarizeDocument(url, result), citations: buildFetchCitations(url, result) }
           }),
-          TOOL_TIMEOUT_MS,
-          'Webpage fetch',
         )
-
-        return { url, document: summarizeDocument(url, result), citations: buildFetchCitations(url, result) }
       },
     }),
 } as const satisfies ToolDefinition<void>

package/src/tools/firecrawl-client.ts

@@ -1,12 +1,22 @@
 import Firecrawl from '@mendable/firecrawl-js'
+import { Context, Effect, Layer } from 'effect'
 
-import { getRuntimeConfig } from '../runtime/runtime-config'
+import { getCurrentRuntime } from '../effect/runtime-ref'
+import { RuntimeConfigServiceTag } from '../effect/services'
 
-let _firecrawlClient: Firecrawl | undefined
+export class FirecrawlTag extends Context.Service<FirecrawlTag, Firecrawl>()('Firecrawl') {}
+
+export const FirecrawlLive = Layer.effect(
+  FirecrawlTag,
+  Effect.gen(function* () {
+    const config = yield* RuntimeConfigServiceTag
+    return new Firecrawl({
+      apiKey: config.firecrawl.apiKey,
+      ...(config.firecrawl.apiBaseUrl ? { apiUrl: config.firecrawl.apiBaseUrl } : {}),
+    })
+  }),
+)
 
 export function getFirecrawlClient(): Firecrawl {
-  if (!_firecrawlClient) {
-    _firecrawlClient = new Firecrawl({ apiKey: getRuntimeConfig().firecrawl.apiKey })
-  }
-  return _firecrawlClient
+  return getCurrentRuntime().runSync(Effect.service(FirecrawlTag))
 }

package/src/tools/index.ts

@@ -1,5 +1,6 @@
 export * from './execution-plan.tool'
 export * from './fetch-webpage.tool'
+export * from './firecrawl-client'
 export * from './memory-block.tool'
 export * from './plan-approval.tool'
 export * from './read-file-parts.tool'

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

@@ -1,4 +1,5 @@
 import { tool } from 'ai'
+import { Effect } from 'effect'
 import { z } from 'zod'
 
 import type { RecordIdRef } from '../db/record-id'
@@ -7,18 +8,22 @@ import {
   normalizeMemoryBlockEntry,
   prepareMemoryBlockAppend,
   validateMemoryBlockEntry,
-} from '../runtime/memory-block'
-import { threadService } from '../services/thread.service'
+} from '../runtime/memory/memory-block'
+import type { makeThreadService } from '../services/thread/thread.service'
 import { safeEnqueue } from '../utils/async'
 
+type MemoryBlockThreadService = Pick<ReturnType<typeof makeThreadService>, 'appendMemoryBlock'>
+
 export function createMemoryBlockTool({
   threadId,
   agentLabel,
+  threadService,
   getCurrentBlock,
   onAppend,
 }: {
   threadId: RecordIdRef
   agentLabel: string
+  threadService: MemoryBlockThreadService
   getCurrentBlock?: () => string
   onAppend?: (value: string) => void
 }) {
@@ -42,10 +47,13 @@ export function createMemoryBlockTool({
       onAppend?.(prepared.optimisticBlock)
 
       void safeEnqueue(
-        async () => {
-          const updated = await threadService.appendMemoryBlock(threadId, prepared.formatted)
-          onAppend?.(updated)
-        },
+        () =>
+          Effect.runPromise(
+            Effect.gen(function* () {
+              const updated = yield* threadService.appendMemoryBlock(threadId, prepared.formatted)
+              onAppend?.(updated)
+            }),
+          ),
         { operationName: 'append memory block entry', logPrefix: 'Background memoryBlockAppend task failed' },
       )