@lota-sdk/core 0.4.9 → 0.4.10

package/src/services/graph-full-routing.ts

@@ -12,11 +12,14 @@ import { Effect } from 'effect'
 import { serverLogger } from '../config/logger'
 import { recordIdToString } from '../db/record-id'
 import { TABLES } from '../db/tables'
-import { BadRequestError } from '../effect/errors'
+import { BadRequestError, ServiceError } from '../effect/errors'
+import { makeEffectTryPromiseWithMessage } from '../effect/helpers'
 import { shouldPlanNodeUseVisibleTurn } from '../runtime/execution-plan-visibility'
 import type { makePlanExecutorService } from './plan/plan-executor.service'
 import type { makePlanRunService } from './plan/plan-run.service'
 
+const tryGraphFullPromise = makeEffectTryPromiseWithMessage((message, cause) => new ServiceError({ message, cause }))
+
 function classifyDispatchFailure(ownerType: string, error: unknown): PlanFailureClass {
   const errorMessage = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase()
   if (errorMessage.includes('timeout')) return 'timeout_exceeded'
@@ -30,19 +33,19 @@ function formatDispatchError(error: unknown): string {
 
 const STABLE_RUN_STATUSES = new Set(['pending-approval', 'awaiting-human', 'blocked', 'failed', 'completed', 'aborted'])
 
-interface GraphFullRoutingDeps {
+interface GraphFullRoutingDeps<E = never> {
   dispatchReadyNode(params: {
     run: PlanRunRecord
     nodeSpecRecord: PlanNodeSpecRecord
     nodeRun: PlanNodeRunRecord
     spec: PlanSpecRecord
     executionModeOverride?: ExecutionMode
-  }): Effect.Effect<PlanNodeResultSubmission, unknown>
+  }): Effect.Effect<PlanNodeResultSubmission, E, never>
   planExecutorService: ReturnType<typeof makePlanExecutorService>
   planRunService: ReturnType<typeof makePlanRunService>
 }
 
-export function routeGraphFullEffect(params: { threadId: string; runId: string }, deps: GraphFullRoutingDeps) {
+export function routeGraphFullEffect<E>(params: { threadId: string; runId: string }, deps: GraphFullRoutingDeps<E>) {
   return Effect.gen(function* () {
     const MAX_ROUNDS = 32
     const STRUCTURAL_TYPES = new Set(['switch', 'join', 'deliberation-fork'])
@@ -75,15 +78,17 @@ export function routeGraphFullEffect(params: { threadId: string; runId: string }
       yield* Effect.forEach(
         readyNodes,
         (nodeRun) =>
-          Effect.tryPromise(() =>
-            deps.planExecutorService.transitionNodeToRunning({ runId: params.runId, nodeId: nodeRun.nodeId }),
+          tryGraphFullPromise(
+            () => deps.planExecutorService.transitionNodeToRunning({ runId: params.runId, nodeId: nodeRun.nodeId }),
+            'Failed to transition plan node to running.',
           ),
         { concurrency: 'unbounded' },
       )
 
       if (visibleNodes.length > 0) {
-        const { enqueuePlanAgentHeartbeatWake } = yield* Effect.tryPromise(
+        const { enqueuePlanAgentHeartbeatWake } = yield* tryGraphFullPromise(
           () => import('../queues/plan-agent-heartbeat.queue'),
+          'Failed to load plan agent heartbeat queue module.',
         )
         const updatedRunForWake = yield* deps.planRunService.getRunById(params.runId)
         yield* Effect.forEach(
@@ -95,15 +100,17 @@ export function routeGraphFullEffect(params: { threadId: string; runId: string }
                 return
               }
 
-              yield* Effect.tryPromise(() =>
-                enqueuePlanAgentHeartbeatWake({
-                  organizationId: recordIdToString(updatedRunForWake.organizationId, TABLES.ORGANIZATION),
-                  threadId: recordIdToString(updatedRunForWake.threadId, TABLES.THREAD),
-                  runId: recordIdToString(updatedRunForWake.id, TABLES.PLAN_RUN),
-                  nodeId: nodeRun.nodeId,
-                  agentId: ns.owner.ref,
-                  reason: 'graph-full-visible',
-                }),
+              yield* tryGraphFullPromise(
+                () =>
+                  enqueuePlanAgentHeartbeatWake({
+                    organizationId: recordIdToString(updatedRunForWake.organizationId, TABLES.ORGANIZATION),
+                    threadId: recordIdToString(updatedRunForWake.threadId, TABLES.THREAD),
+                    runId: recordIdToString(updatedRunForWake.id, TABLES.PLAN_RUN),
+                    nodeId: nodeRun.nodeId,
+                    agentId: ns.owner.ref,
+                    reason: 'graph-full-visible',
+                  }),
+                'Failed to enqueue plan agent heartbeat wake.',
               )
             }),
           { concurrency: 'unbounded' },
@@ -150,26 +157,30 @@ export function routeGraphFullEffect(params: { threadId: string; runId: string }
         const nodeSpecRecord = nodeSpecs.find((ns) => ns.nodeId === nodeRun.nodeId)
 
         if (settled.status === 'fulfilled') {
-          yield* Effect.tryPromise(() =>
-            deps.planExecutorService.submitNodeResult({
-              threadId,
-              runId,
-              nodeId: settled.value.nodeId,
-              emittedBy: settled.value.ownerRef,
-              result: settled.value.result,
-            }),
+          yield* tryGraphFullPromise(
+            () =>
+              deps.planExecutorService.submitNodeResult({
+                threadId,
+                runId,
+                nodeId: settled.value.nodeId,
+                emittedBy: settled.value.ownerRef,
+                result: settled.value.result,
+              }),
+            'Failed to submit plan node result.',
           )
         } else {
           serverLogger.warn`routeGraphFull: dispatch failed for node "${nodeRun.nodeId}": ${settled.reason}`
-          yield* Effect.tryPromise(() =>
-            deps.planExecutorService.blockNodeOnDispatchFailure({
-              threadId,
-              runId,
-              nodeId: nodeRun.nodeId,
-              emittedBy: nodeSpecRecord?.owner.ref ?? 'unknown',
-              message: formatDispatchError(settled.reason),
-              failureClass: classifyDispatchFailure(nodeSpecRecord?.owner.executorType ?? 'agent', settled.reason),
-            }),
+          yield* tryGraphFullPromise(
+            () =>
+              deps.planExecutorService.blockNodeOnDispatchFailure({
+                threadId,
+                runId,
+                nodeId: nodeRun.nodeId,
+                emittedBy: nodeSpecRecord?.owner.ref ?? 'unknown',
+                message: formatDispatchError(settled.reason),
+                failureClass: classifyDispatchFailure(nodeSpecRecord?.owner.executorType ?? 'agent', settled.reason),
+              }),
+            'Failed to block plan node on dispatch failure.',
           )
         }
       }

package/src/services/index.ts

@@ -3,6 +3,7 @@ export * from './agent-activity.service'
 export * from './artifact.service'
 export * from './attachment.service'
 export * from './autonomous-job.service'
+export * from './background-work.service'
 export * from './document-chunk.service'
 export * from './execution-plan/execution-plan.service'
 export * from './institutional-memory.service'

package/src/services/institutional-memory.service.ts

@@ -11,6 +11,7 @@ import { BoundQuery } from 'surrealdb'
 import { ensureRecordId } from '../db/record-id'
 import type { SurrealDBService } from '../db/service'
 import { TABLES } from '../db/tables'
+import { makeEffectTryPromiseWithMessage } from '../effect/helpers'
 import { DatabaseServiceTag } from '../effect/services'
 import { unsafeDateFrom } from '../utils/date-time'
 import type { makePlanRunService } from './plan/plan-run.service'
@@ -26,25 +27,15 @@ class InstitutionalMemoryServiceError extends Schema.TaggedErrorClass<Institutio
   { message: Schema.String, cause: Schema.Defect },
 ) {}
 
+const effectTryInstitutionalMemoryPromise = makeEffectTryPromiseWithMessage(
+  (message, cause) => new InstitutionalMemoryServiceError({ message, cause }),
+)
+
 function tryInstitutionalMemoryPromise<A>(
   message: string,
-  thunk: () => PromiseLike<A> | Effect.Effect<A, unknown>,
+  evaluate: () => PromiseLike<A> | Effect.Effect<A, unknown>,
 ): Effect.Effect<A, InstitutionalMemoryServiceError> {
-  return Effect.suspend(() => {
-    try {
-      const value = thunk()
-      if (Effect.isEffect(value)) {
-        return value.pipe(Effect.mapError((cause) => new InstitutionalMemoryServiceError({ message, cause })))
-      }
-
-      return Effect.tryPromise({
-        try: () => Promise.resolve(value),
-        catch: (cause) => new InstitutionalMemoryServiceError({ message, cause }),
-      })
-    } catch (cause) {
-      return Effect.fail(new InstitutionalMemoryServiceError({ message, cause }))
-    }
-  })
+  return effectTryInstitutionalMemoryPromise(evaluate, message)
 }
 
 export function makeInstitutionalMemoryService(deps: InstitutionalMemoryDeps) {
@@ -230,7 +221,7 @@ export function makeInstitutionalMemoryService(deps: InstitutionalMemoryDeps) {
 export class InstitutionalMemoryServiceTag extends Context.Service<
   InstitutionalMemoryServiceTag,
   ReturnType<typeof makeInstitutionalMemoryService>
->()('InstitutionalMemoryService') {}
+>()('@lota-sdk/core/InstitutionalMemoryService') {}
 
 export const InstitutionalMemoryServiceLive = Layer.effect(
   InstitutionalMemoryServiceTag,

package/src/services/learned-skill.service.ts

@@ -8,10 +8,12 @@ import { serverLogger } from '../config/logger'
 import { ensureRecordId, recordIdToString } from '../db/record-id'
 import type { SurrealDBService } from '../db/service'
 import { TABLES } from '../db/tables'
+import { makeEffectTryPromiseWithMessage } from '../effect/helpers'
 import { DatabaseServiceTag, RuntimeConfigServiceTag } from '../effect/services'
 import { ProviderEmbeddings } from '../embeddings/provider'
 import { sha256HexFromParts } from '../utils/crypto'
 import { nowDate } from '../utils/date-time'
+import { BackgroundWorkService } from './background-work.service'
 
 const PROMOTION_MIN_USES = 5
 const PROMOTION_MIN_SUCCESS_RATE = 0.6
@@ -64,25 +66,15 @@ class LearnedSkillNotFoundError extends Schema.TaggedErrorClass<LearnedSkillNotF
   { message: Schema.String },
 ) {}
 
+const effectTryLearnedSkillPromise = makeEffectTryPromiseWithMessage(
+  (message, cause) => new LearnedSkillServiceError({ message, cause }),
+)
+
 function tryLearnedSkillPromise<A>(
   message: string,
-  thunk: () => PromiseLike<A> | Effect.Effect<A, unknown>,
+  evaluate: () => PromiseLike<A> | Effect.Effect<A, unknown>,
 ): Effect.Effect<A, LearnedSkillServiceError> {
-  return Effect.suspend(() => {
-    try {
-      const value = thunk()
-      if (Effect.isEffect(value)) {
-        return value.pipe(Effect.mapError((cause) => new LearnedSkillServiceError({ message, cause })))
-      }
-
-      return Effect.tryPromise({
-        try: () => Promise.resolve(value),
-        catch: (cause) => new LearnedSkillServiceError({ message, cause }),
-      })
-    } catch (cause) {
-      return Effect.fail(new LearnedSkillServiceError({ message, cause }))
-    }
-  })
+  return effectTryLearnedSkillPromise(evaluate, message)
 }
 
 interface CreateLearnedSkillInput {
@@ -126,6 +118,7 @@ export function makeLearnedSkillService(
   db: SurrealDBService,
   options: { embeddingModel: string; openRouterApiKey?: string },
   skillExistsCache: Cache.Cache<string, boolean, LearnedSkillServiceError>,
+  background: Context.Service.Shape<typeof BackgroundWorkService>,
 ) {
   const embeddings = new ProviderEmbeddings({
     modelId: options.embeddingModel,
@@ -265,30 +258,33 @@ export function makeLearnedSkillService(
         }),
       ),
     ).pipe(Effect.withSpan('LearnedSkillService.queryNearestSkills'))
-    return rows.map((row) => SearchResultRowSchema.parse(row)).filter((row) => row.similarity >= 0.3)
+    const parsedRows = yield* Effect.try({
+      try: () => rows.map((row) => SearchResultRowSchema.parse(row)),
+      catch: (cause) =>
+        new LearnedSkillServiceError({ message: 'Failed to parse learned skill search results.', cause }),
+    })
+    return parsedRows.filter((row) => row.similarity >= 0.3)
   })
 
   const retrieveForTurn = Effect.fn('LearnedSkillService.retrieveForTurn')(function* (params: RetrieveForTurnParams) {
     const results = yield* searchForTurn(params)
     if (results.length === 0) return undefined
 
-    const currentContext = yield* Effect.context<never>()
-    yield* Effect.sync(() => {
-      void Effect.runForkWith(currentContext)(
-        Effect.forEach(
-          results,
-          (result) =>
-            recordUsage(result.id).pipe(
-              Effect.tapError((error) =>
-                Effect.sync(() => {
-                  serverLogger.warn`Failed to record learned skill usage for ${result.id}: ${error}`
-                }),
-              ),
+    yield* background.run(
+      Effect.forEach(
+        results,
+        (result) =>
+          recordUsage(result.id).pipe(
+            Effect.tapError((error) =>
+              Effect.sync(() => {
+                serverLogger.warn`Failed to record learned skill usage for ${result.id}: ${error}`
+              }),
             ),
-          { discard: true },
-        ),
-      )
-    })
+          ),
+        { discard: true },
+      ),
+      'learned-skill.recordUsage',
+    )
 
     const section = renderLearnedSkillInstructions(
       results.map((row) => ({ name: row.name, instructions: row.instructions })),
@@ -365,7 +361,12 @@ export function makeLearnedSkillService(
       const rows = yield* tryLearnedSkillPromise('Failed to query most similar learned skill.', () =>
         db.query<unknown>(new BoundQuery(sql, { organizationId: orgRef, embedding: descEmbedding })),
       )
-      return rows.length === 0 ? null : LearnedSkillRowSchema.parse(rows[0])
+      if (rows.length === 0) return null
+      return yield* Effect.try({
+        try: () => LearnedSkillRowSchema.parse(rows[0]),
+        catch: (cause) =>
+          new LearnedSkillServiceError({ message: 'Failed to parse most similar learned skill row.', cause }),
+      })
     })
 
   const listForOrg = (orgId: string) =>
@@ -450,13 +451,14 @@ export function makeLearnedSkillService(
 export class LearnedSkillServiceTag extends Context.Service<
   LearnedSkillServiceTag,
   ReturnType<typeof makeLearnedSkillService>
->()('LearnedSkillService') {}
+>()('@lota-sdk/core/LearnedSkillService') {}
 
 export const LearnedSkillServiceLive = Layer.effect(
   LearnedSkillServiceTag,
   Effect.gen(function* () {
     const db = yield* DatabaseServiceTag
     const runtimeConfig = yield* RuntimeConfigServiceTag
+    const background = yield* BackgroundWorkService
     const skillExistsCache = yield* Cache.make({
       lookup: (key: string) =>
         Effect.gen(function* () {
@@ -486,6 +488,7 @@ export const LearnedSkillServiceLive = Layer.effect(
         openRouterApiKey: runtimeConfig.aiGateway.openRouterApiKey,
       },
       skillExistsCache,
+      background,
     )
   }),
 )

package/src/services/memory/memory-errors.ts

@@ -0,0 +1,27 @@
+import { Effect, Schema } from 'effect'
+
+export class MemoryServiceError extends Schema.TaggedErrorClass<MemoryServiceError>()('MemoryServiceError', {
+  message: Schema.String,
+  cause: Schema.Defect,
+}) {}
+
+export function tryMemoryPromise<A, E, R = never>(
+  message: string,
+  thunk: () => PromiseLike<A> | Effect.Effect<A, E, R>,
+): Effect.Effect<A, MemoryServiceError, R> {
+  return Effect.suspend(() => {
+    try {
+      const value = thunk()
+      if (Effect.isEffect(value)) {
+        return value.pipe(Effect.mapError((cause) => new MemoryServiceError({ message, cause })))
+      }
+
+      return Effect.tryPromise({
+        try: () => Promise.resolve(value),
+        catch: (cause) => new MemoryServiceError({ message, cause }),
+      })
+    } catch (cause) {
+      return Effect.fail(new MemoryServiceError({ message, cause }))
+    }
+  })
+}

package/src/services/memory/memory-org-memory.ts

@@ -1,3 +1,4 @@
+import type { Context } from 'effect'
 import { Cache, Duration, Effect } from 'effect'
 
 import { aiLogger } from '../../config/logger'
@@ -7,6 +8,7 @@ import type { HelperModelRuntime } from '../../runtime/helper-model'
 import { ORG_SCOPE_PREFIX, scopeId } from '../../runtime/memory/memory-scope'
 import type { ResolvedLotaRuntimeConfig } from '../../runtime/runtime-config'
 import { createOrgMemoryAgent, ORG_MEMORY_PROMPT } from '../../system-agents/memory.agent'
+import type { BackgroundWorkService } from '../background-work.service'
 
 const MAX_ORG_MEMORY_CLIENTS = 128
 
@@ -14,6 +16,7 @@ interface OrgMemoryDeps {
   db: SurrealDBService
   runtimeConfig: ResolvedLotaRuntimeConfig
   helperModelRuntime: HelperModelRuntime
+  background: Context.Service.Shape<typeof BackgroundWorkService>
 }
 
 export type OrgMemoryCache = Cache.Cache<string, Memory>
@@ -24,7 +27,12 @@ export function makeOrgMemoryCache(deps: OrgMemoryDeps) {
       Effect.sync(() => {
         aiLogger.debug`Memory client created and cached for ${cacheKey}`
         return new Memory(
-          { db: deps.db, runtimeConfig: deps.runtimeConfig, helperModelRuntime: deps.helperModelRuntime },
+          {
+            db: deps.db,
+            runtimeConfig: deps.runtimeConfig,
+            helperModelRuntime: deps.helperModelRuntime,
+            background: deps.background,
+          },
           { createAgent: createOrgMemoryAgent },
           { customPrompt: ORG_MEMORY_PROMPT },
         )
@@ -34,6 +42,9 @@ export function makeOrgMemoryCache(deps: OrgMemoryDeps) {
   })
 }
 
-export function getOrgMemory(cache: OrgMemoryCache, orgId: string): Effect.Effect<Memory> {
-  return Cache.get(cache, scopeId(ORG_SCOPE_PREFIX, orgId))
+export function getOrgMemory(cache: OrgMemoryCache, orgId: string) {
+  return Effect.gen(function* () {
+    const key = yield* scopeId(ORG_SCOPE_PREFIX, orgId)
+    return yield* Cache.get(cache, key)
+  })
 }

package/src/services/memory/memory-preseeded.ts

@@ -1,6 +1,8 @@
 import { Effect } from 'effect'
 
+import type { Memory } from '../../db/memory'
 import type { MemoryRecord } from '../../db/memory-types'
+import type { MemoryScopeError } from '../../runtime/memory/memory-scope'
 import { ORG_SCOPE_PREFIX, agentScopeId, scopeId } from '../../runtime/memory/memory-scope'
 import { compactWhitespace, truncateText } from '../../utils/string'
 import type { OrgMemoryCache } from './memory-org-memory'
@@ -10,6 +12,7 @@ const PRESEEDED_MEMORY_LIMIT = 5
 const PRESEEDED_MEMORY_MAX_CHARS = 300
 const PRESEEDED_MIN_IMPORTANCE = 0.7
 const PRESEEDED_MEMORY_DURABILITY: MemoryRecord['durability'] = 'core'
+type PreSeededMemoryError = Effect.Error<ReturnType<Memory['listTopMemories']>> | MemoryScopeError
 
 function normalizePreSeededMemoryText(value: string): string {
   return truncateText(compactWhitespace(value), PRESEEDED_MEMORY_MAX_CHARS)
@@ -30,13 +33,16 @@ export function getTopMemoriesSection(params: {
   orgId: string
   agentName?: string
   limit?: number
-}): Effect.Effect<string | undefined, unknown> {
+}): Effect.Effect<string | undefined, PreSeededMemoryError, never> {
   return Effect.gen(function* () {
     const orgMemory = yield* getOrgMemory(params.orgMemoryCache, params.orgId)
-    const orgScopeId = scopeId(ORG_SCOPE_PREFIX, params.orgId)
+    const orgScopeId = yield* scopeId(ORG_SCOPE_PREFIX, params.orgId)
     const requestedLimit = params.limit ?? PRESEEDED_MEMORY_LIMIT
     const limit = Math.max(1, Math.min(requestedLimit, PRESEEDED_MEMORY_LIMIT))
 
+    const agentScopedId =
+      params.agentName && params.agentName.trim() ? yield* agentScopeId(params.orgId, params.agentName) : undefined
+
     const [orgTopMemories, agentTopMemories] = yield* Effect.all([
       orgMemory.listTopMemories({
         scopeId: orgScopeId,
@@ -45,9 +51,9 @@ export function getTopMemoriesSection(params: {
         durability: PRESEEDED_MEMORY_DURABILITY,
         minImportance: PRESEEDED_MIN_IMPORTANCE,
       }),
-      params.agentName && params.agentName.trim()
+      agentScopedId
         ? orgMemory.listTopMemories({
-            scopeId: agentScopeId(params.orgId, params.agentName),
+            scopeId: agentScopedId,
             limit,
             memoryType: 'fact',
             durability: PRESEEDED_MEMORY_DURABILITY,

package/src/services/memory/memory-utils.ts

@@ -1,5 +1,6 @@
+import { VECTOR_SEARCH_OVERFETCH_MULTIPLIER } from '@lota-sdk/shared'
+
 import { MEMORY } from '../../config/constants'
-import { VECTOR_SEARCH_OVERFETCH_MULTIPLIER } from '../../config/search'
 import type { MemorySearchResult } from '../../db/memory-types'
 import { compactWhitespace, truncateText } from '../../utils/string'
 import type { MemoryRerankOutput } from './memory-rerank'