@lota-sdk/core 0.4.8 → 0.4.10

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

@@ -1,66 +1,76 @@
 import { PlanApprovalArgsSchema, PlanApprovalToolResultDataSchema } from '@lota-sdk/shared'
 import { tool } from 'ai'
+import { Effect } from 'effect'
 
 import type { RecordIdRef } from '../db/record-id'
-import { executionPlanService } from '../services/execution-plan.service'
-import { toToolPlanSummary } from '../services/plan-run-data'
+import type { makeExecutionPlanService } from '../services/execution-plan/execution-plan.service'
+import { toToolPlanSummary } from '../services/plan/plan-run-data'
 
-type PlanApprovalExecutionPlanService = Pick<typeof executionPlanService, '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
   threadId: RecordIdRef
   actorId: string
-  executionPlanService?: PlanApprovalExecutionPlanService
+  executionPlanService: PlanApprovalExecutionPlanService
 }) {
-  const resolvedExecutionPlanService = params.executionPlanService ?? executionPlanService
-
   return tool({
     description:
       'Approve, reject, or request changes to a plan that is pending approval. Use approve to start execution, reject to abort it, or modify to request a revised plan.',
     inputSchema: PlanApprovalArgsSchema,
     outputSchema: PlanApprovalToolResultDataSchema,
-    execute: async (input) => {
-      switch (input.action) {
-        case 'approve': {
-          const plan = await resolvedExecutionPlanService.approvePlan({
-            organizationId: params.orgId,
-            threadId: params.threadId,
-            runId: input.runId,
-            emittedBy: params.actorId,
-          })
-          const toolPlan = toToolPlanSummary(plan)
-          return {
-            action: 'approved',
-            message: `Approved execution plan "${plan.title}" and started it.`,
-            hasPlan: true,
-            status: toolPlan.status,
-            plan: toolPlan,
-          }
-        }
-        case 'reject':
-        case 'modify': {
-          const plan = await resolvedExecutionPlanService.rejectPlan({
-            organizationId: params.orgId,
-            threadId: params.threadId,
-            runId: input.runId,
-            emittedBy: params.actorId,
-            reason: input.reason,
-            resolution: input.action === 'modify' ? 'changes-requested' : 'rejected',
-          })
-          const toolPlan = toToolPlanSummary(plan)
-          return {
-            action: input.action === 'modify' ? 'changes-requested' : 'rejected',
-            message:
-              input.action === 'modify'
-                ? `Requested changes for execution plan "${plan.title}".`
-                : `Rejected execution plan "${plan.title}".`,
-            hasPlan: true,
-            status: toolPlan.status,
-            plan: toolPlan,
+    execute: (input) =>
+      Effect.runPromise(
+        Effect.gen(function* () {
+          switch (input.action) {
+            case 'approve': {
+              const plan = yield* params.executionPlanService.approvePlan({
+                organizationId: params.orgId,
+                threadId: params.threadId,
+                runId: input.runId,
+                emittedBy: params.actorId,
+              })
+              const toolPlan = toToolPlanSummary(plan)
+              return {
+                action: 'approved',
+                message: `Approved execution plan "${plan.title}" and started it.`,
+                hasPlan: true,
+                status: toolPlan.status,
+                plan: toolPlan,
+              }
+            }
+            case 'reject':
+            case 'modify': {
+              const plan = yield* params.executionPlanService.rejectPlan({
+                organizationId: params.orgId,
+                threadId: params.threadId,
+                runId: input.runId,
+                emittedBy: params.actorId,
+                reason: input.reason,
+                resolution: input.action === 'modify' ? 'changes-requested' : 'rejected',
+              })
+              const toolPlan = toToolPlanSummary(plan)
+              return {
+                action: input.action === 'modify' ? 'changes-requested' : 'rejected',
+                message:
+                  input.action === 'modify'
+                    ? `Requested changes for execution plan "${plan.title}".`
+                    : `Rejected execution plan "${plan.title}".`,
+                hasPlan: true,
+                status: toolPlan.status,
+                plan: toolPlan,
+              }
+            }
           }
-        }
-      }
-    },
+        }),
+      ),
   })
 }

package/src/tools/read-file-parts.tool.ts

@@ -1,16 +1,20 @@
 import { tool } from 'ai'
+import { Schema, Effect } from 'effect'
 import { z } from 'zod'
 
 import type { ToolDefinition } from '../ai/definitions'
-import { attachmentStorageService } from '../storage/attachment-storage.service'
+import type { makeAttachmentService } from '../services/attachment.service'
 import type { ReadableUploadMetadata } from '../storage/attachment-types'
 
 const PAGES_PER_PART = 25
 
+type ReadFilePartsAttachmentService = Pick<ReturnType<typeof makeAttachmentService>, 'readFilePartsFromUpload'>
+
 export interface ReadFilePartsToolContext {
   orgId: string
   userId: string
   uploads: ReadableUploadMetadata[]
+  attachmentService: ReadFilePartsAttachmentService
 }
 
 function toUploadSummary(upload: ReadableUploadMetadata) {
@@ -22,59 +26,66 @@ function toUploadSummary(upload: ReadableUploadMetadata) {
   }
 }
 
-function resolveUploadTarget(params: {
+class ReadFilePartsError extends Schema.TaggedErrorClass<ReadFilePartsError>()('ReadFilePartsError', {
+  message: Schema.String,
+}) {}
+
+function resolveUploadTargetEffect(params: {
   uploads: ReadableUploadMetadata[]
   storageKey?: string
-}): ReadableUploadMetadata | null {
+}): Effect.Effect<ReadableUploadMetadata | null, ReadFilePartsError> {
   const normalizedStorageKey = params.storageKey?.trim()
   const byStorageKey = normalizedStorageKey
     ? params.uploads.find((upload) => upload.storageKey === normalizedStorageKey)
     : null
   if (normalizedStorageKey !== undefined && !byStorageKey) {
-    throw new Error(`No upload found for storageKey "${normalizedStorageKey}".`)
+    return Effect.fail(new ReadFilePartsError({ message: `No upload found for storageKey "${normalizedStorageKey}".` }))
   }
 
-  return byStorageKey ?? null
+  return Effect.succeed(byStorageKey ?? null)
 }
 
 export const readFilePartsTool = {
   name: 'readFileParts',
-  create: ({ orgId, userId, uploads }: ReadFilePartsToolContext) =>
+  create: ({ orgId, userId, uploads, attachmentService }: ReadFilePartsToolContext) =>
     tool({
       description:
         'Read uploaded file content by part. Call with no args to list uploads metadata, then call with storageKey and part (25 pages per part).',
       inputSchema: z
         .object({ storageKey: z.string().trim().min(1).optional(), part: z.number().int().positive().default(1) })
         .strict(),
-      execute: async ({ storageKey, part }: { storageKey?: string; part?: number }) => {
-        const availableUploads = uploads.map(toUploadSummary)
-        const selected = resolveUploadTarget({ uploads, storageKey })
+      execute: ({ storageKey, part }: { storageKey?: string; part?: number }) =>
+        Effect.runPromise(
+          Effect.gen(function* () {
+            const availableUploads = uploads.map(toUploadSummary)
+            const selected = yield* resolveUploadTargetEffect({ uploads, storageKey })
 
-        if (!selected) {
-          return {
-            pagesPerPart: PAGES_PER_PART,
-            currentPart: 1,
-            hasNextPart: false,
-            totalParts: 0,
-            data: [],
-            availableUploads,
-            selectedUpload: null,
-            message:
-              uploads.length === 0
-                ? 'No uploaded files are available in this conversation.'
-                : 'Select an upload via storageKey, then provide part (25 pages per part).',
-          }
-        }
+            if (!selected) {
+              return {
+                pagesPerPart: PAGES_PER_PART,
+                currentPart: 1,
+                hasNextPart: false,
+                totalParts: 0,
+                data: [],
+                availableUploads,
+                selectedUpload: null,
+                message:
+                  uploads.length === 0
+                    ? 'No uploaded files are available in this conversation.'
+                    : 'Select an upload via storageKey, then provide part (25 pages per part).',
+              }
+            }
 
-        const parts = await attachmentStorageService.readFilePartsFromUpload({
-          upload: selected,
-          orgId,
-          userId,
-          part,
-          pagesPerPart: PAGES_PER_PART,
-        })
+            const parts = yield* attachmentService.readFilePartsFromUpload({
+              upload: selected,
+              orgId,
+              userId,
+              part,
+              pagesPerPart: PAGES_PER_PART,
+            })
 
-        return { availableUploads, selectedUpload: toUploadSummary(selected), ...parts }
-      },
+            return { availableUploads, selectedUpload: toUploadSummary(selected), ...parts }
+          }),
+        ),
     }),
 } as const satisfies ToolDefinition<ReadFilePartsToolContext>

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

@@ -1,10 +1,12 @@
 import { tool } from 'ai'
+import { Effect } from 'effect'
 import { z } from 'zod'
 
 import type { RecordIdRef } from '../db/record-id'
 import { recordIdToString } from '../db/record-id'
 import { TABLES } from '../db/tables'
-import { memoryService } from '../services/memory.service'
+import type { MaybeAwaitableService } from '../effect/awaitable-effect'
+import type { createMemoryService } from '../services/memory/memory.service'
 import { safeEnqueue } from '../utils/async'
 
 const RememberMemoryInputSchema = z
@@ -14,7 +16,22 @@ const RememberMemoryInputSchema = z
   })
   .strict()
 
-export function createRememberMemoryTool({ orgId, agentName }: { orgId: RecordIdRef; agentName: string }) {
+type RememberMemoryService = MaybeAwaitableService<
+  Pick<
+    ReturnType<typeof createMemoryService>,
+    'assessMemoryCandidate' | 'createOrganizationMemory' | 'createAgentMemory'
+  >
+>
+
+export function createRememberMemoryTool({
+  orgId,
+  agentName,
+  memoryService,
+}: {
+  orgId: RecordIdRef
+  agentName: string
+  memoryService: RememberMemoryService
+}) {
   return tool({
     description:
       'Save a durable memory. Importance is scored automatically from memory significance. Use targetScope="agent" for role-specific memory, or targetScope="global" for organization-wide memory.',
@@ -27,52 +44,55 @@ export function createRememberMemoryTool({ orgId, agentName }: { orgId: RecordId
 
       const orgIdString = recordIdToString(orgId, TABLES.ORGANIZATION)
       void safeEnqueue(
-        async () => {
-          const assessment = await memoryService.assessMemoryCandidate({ orgId: orgIdString, content: trimmed })
-          if (!assessment) {
-            return
-          }
-          if (assessment.classification === 'transient' && assessment.durability === 'ephemeral') {
-            return
-          }
+        () =>
+          Effect.runPromise(
+            Effect.gen(function* () {
+              const assessment = yield* memoryService.assessMemoryCandidate({ orgId: orgIdString, content: trimmed })
+              if (!assessment) {
+                return
+              }
+              if (assessment.classification === 'transient' && assessment.durability === 'ephemeral') {
+                return
+              }
 
-          const importance = Math.round(assessment.importance * 100) / 100
+              const importance = Math.round(assessment.importance * 100) / 100
 
-          if (targetScope === 'global') {
-            await memoryService.createOrganizationMemory({
-              orgId: orgIdString,
-              content: trimmed,
-              memoryType: 'fact',
-              importance,
-              metadata: {
-                source: 'agent_tool',
-                agentName,
-                memoryScope: 'global',
-                importanceSource: 'extraction_assessed',
-                durability: assessment.durability,
-                classification: assessment.classification,
-                rationale: assessment.rationale,
-              },
-            })
-            return
-          }
+              if (targetScope === 'global') {
+                yield* memoryService.createOrganizationMemory({
+                  orgId: orgIdString,
+                  content: trimmed,
+                  memoryType: 'fact',
+                  importance,
+                  metadata: {
+                    source: 'agent_tool',
+                    agentName,
+                    memoryScope: 'global',
+                    importanceSource: 'extraction_assessed',
+                    durability: assessment.durability,
+                    classification: assessment.classification,
+                    rationale: assessment.rationale,
+                  },
+                })
+                return
+              }
 
-          await memoryService.createAgentMemory({
-            orgId: orgIdString,
-            agentName,
-            content: trimmed,
-            memoryType: 'fact',
-            importance,
-            metadata: {
-              source: 'agent_tool',
-              memoryScope: 'agent',
-              importanceSource: 'extraction_assessed',
-              durability: assessment.durability,
-              classification: assessment.classification,
-              rationale: assessment.rationale,
-            },
-          })
-        },
+              yield* memoryService.createAgentMemory({
+                orgId: orgIdString,
+                agentName,
+                content: trimmed,
+                memoryType: 'fact',
+                importance,
+                metadata: {
+                  source: 'agent_tool',
+                  memoryScope: 'agent',
+                  importanceSource: 'extraction_assessed',
+                  durability: assessment.durability,
+                  classification: assessment.classification,
+                  rationale: assessment.rationale,
+                },
+              })
+            }),
+          ),
         { operationName: `remember memory (${targetScope})`, logPrefix: 'Background memoryRemember task failed' },
       )
 

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

@@ -1,22 +1,24 @@
 import { tool } from 'ai'
+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'
+
+class SearchWebToolError extends Schema.TaggedErrorClass<SearchWebToolError>()('@lota-sdk/core/SearchWebToolError', {
+  message: Schema.String,
+  cause: Schema.optional(Schema.Defect),
+}) {}
 
-const TOOL_TIMEOUT_MS = 30_000
 const SourceSchema = z.enum(['web', 'news', 'images'])
 const MAX_RESULTS_PER_SOURCE = 4
 const MAX_SNIPPET_CHARS = 320
 
-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 readMetadata(item: unknown): Record<string, unknown> {
   const record = toRecord(item)
   if (!record) return {}
@@ -112,7 +114,7 @@ function extractUrlFromSearchItem(item: unknown): string | undefined {
 function buildWebCitations(results: { web?: unknown[]; news?: unknown[]; images?: unknown[] }): WebCitation[] {
   const seen = new Set<string>()
   const citations: WebCitation[] = []
-  const retrievedAt = new Date().toISOString()
+  const retrievedAt = nowIsoDateTimeString()
 
   const append = (items: unknown[] | undefined) => {
     if (!items) return
@@ -145,7 +147,7 @@ export const searchWebTool = {
           tbs: z.string().optional(),
         })
         .strict(),
-      execute: async ({
+      execute: ({
         query,
         limit,
         sources,
@@ -158,21 +160,30 @@ export const searchWebTool = {
         location?: string
         tbs?: string
       }) => {
-        const results = await withTimeout(
-          getFirecrawlClient().search(query, { limit, sources, location, tbs }),
-          TOOL_TIMEOUT_MS,
-          'Web search',
+        const firecrawl = getFirecrawlClient()
+
+        return Effect.runPromise(
+          Effect.gen(function* () {
+            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: {
+                web: summarizeSearchItems(results.web),
+                news: summarizeSearchItems(results.news),
+                images: summarizeSearchItems(results.images),
+              },
+              citations: buildWebCitations(results),
+            }
+          }).pipe(Effect.withSpan('tool.searchWeb.execute')),
         )
-
-        return {
-          query,
-          results: {
-            web: summarizeSearchItems(results.web),
-            news: summarizeSearchItems(results.news),
-            images: summarizeSearchItems(results.images),
-          },
-          citations: buildWebCitations(results),
-        }
       },
     }),
 } as const satisfies ToolDefinition<void>

package/src/tools/search.tool.ts

@@ -1,55 +1,67 @@
 import { tool } from 'ai'
+import { Effect } from 'effect'
 import { z } from 'zod'
 
 import { isAgentName } from '../config/agent-defaults'
 import type { RecordIdRef } from '../db/record-id'
-import { memoryService } from '../services/memory.service'
-import { threadMessageService } from '../services/thread-message.service'
+import type { MaybeAwaitableService } from '../effect/awaitable-effect'
+import type { createMemoryService } from '../services/memory/memory.service'
+import type { makeThreadMessageService } from '../services/thread/thread-message.service'
 
 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 ConversationSearchService = Pick<ReturnType<typeof makeThreadMessageService>, 'searchMessagesEffect'>
+
 export function createMemorySearchTool(
   orgIdString: string,
+  memoryService: MemorySearchService,
   agentName?: string,
   options?: { fastMode?: boolean; allowMultiScopeRerank?: boolean },
 ) {
   return tool({
     description: 'Search organization and agent memories relevant to a query.',
     inputSchema: MemorySearchInputSchema,
-    execute: async ({ query }: z.infer<typeof MemorySearchInputSchema>) => {
-      const normalizedQuery = query.trim()
-      const retrieval = await memoryService.searchAllMemoriesBatched({
-        orgId: orgIdString,
-        agentName: isAgentName(agentName) ? agentName : undefined,
-        query: normalizedQuery,
-        ...(typeof options?.fastMode === 'boolean' ? { fastMode: options.fastMode } : {}),
-        ...(typeof options?.allowMultiScopeRerank === 'boolean'
-          ? { allowMultiScopeRerank: options.allowMultiScopeRerank }
-          : {}),
-      })
-      const reminder = `Remember: you searched for "${normalizedQuery}". Use the highest-relevance retrieved lines above to answer.`
-
-      return { query: normalizedQuery, retrieval, reminder }
-    },
+    execute: ({ query }: z.infer<typeof MemorySearchInputSchema>) =>
+      Effect.runPromise(
+        Effect.gen(function* () {
+          const normalizedQuery = query.trim()
+          const retrieval = yield* memoryService.searchAllMemoriesBatched({
+            orgId: orgIdString,
+            agentName: isAgentName(agentName) ? agentName : undefined,
+            query: normalizedQuery,
+            ...(typeof options?.fastMode === 'boolean' ? { fastMode: options.fastMode } : {}),
+            ...(typeof options?.allowMultiScopeRerank === 'boolean'
+              ? { allowMultiScopeRerank: options.allowMultiScopeRerank }
+              : {}),
+          })
+          const reminder = `Remember: you searched for "${normalizedQuery}". Use the highest-relevance retrieved lines above to answer.`
+          return { query: normalizedQuery, retrieval, reminder }
+        }),
+      ),
   })
 }
 
-export function createConversationSearchTool(threadId: RecordIdRef) {
+export function createConversationSearchTool(threadId: RecordIdRef, threadMessageService: ConversationSearchService) {
   return tool({
     description: 'Search prior chat messages by role and query text.',
     inputSchema: ConversationSearchInputSchema,
-    execute: async ({ query, type }: z.infer<typeof ConversationSearchInputSchema>) => {
-      const normalizedQuery = query.trim()
-      const results = await threadMessageService.searchMessages({
-        threadId,
-        role: type === 'user' ? 'user' : 'assistant',
-        query: normalizedQuery,
-        limit: CONVERSATION_SEARCH_RESULT_LIMIT,
-      })
-
-      return { query: normalizedQuery, type, count: results.length, results }
-    },
+    execute: ({ query, type }: z.infer<typeof ConversationSearchInputSchema>) =>
+      Effect.runPromise(
+        Effect.gen(function* () {
+          const normalizedQuery = query.trim()
+          const results = yield* threadMessageService.searchMessagesEffect({
+            threadId,
+            role: type === 'user' ? 'user' : 'assistant',
+            query: normalizedQuery,
+            limit: CONVERSATION_SEARCH_RESULT_LIMIT,
+          })
+          return { query: normalizedQuery, type, count: results.length, results }
+        }),
+      ),
   })
 }