@lota-sdk/core 0.4.8 → 0.4.10

package/src/services/agent-executor.service.ts

@@ -9,12 +9,18 @@ import type {
 } from '@lota-sdk/shared'
 import { PlanNodeResultSubmissionSchema, WriteIntentSchema } from '@lota-sdk/shared'
 import { stepCountIs, tool } from 'ai'
-import type { ToolLoopAgent, ToolSet } from 'ai'
+import type { ToolSet } from 'ai'
+import { Context, Schema, Effect, Layer } from 'effect'
 
-import { agentRoster, buildAgentTools, createAgent, getAgentRuntimeConfig } from '../config/agent-defaults'
+import { getAgentRoster, getAgentRuntimeConfig, getResolvedAgentFactoryConfig } from '../config/agent-defaults'
 import { ensureRecordId } from '../db/record-id'
-import { databaseService } from '../db/service'
+import type { SurrealDBService } from '../db/service'
 import { TABLES } from '../db/tables'
+import { BadRequestError, NotFoundError } from '../effect/errors'
+import { makeEffectTryPromiseWithOperation } from '../effect/helpers'
+import { runPromise } from '../effect/runtime'
+import { DatabaseServiceTag } from '../effect/services'
+import { toValidationError } from '../effect/zod'
 import {
   OWNERSHIP_DISPATCH_BLOCKED_TOOL_NAMES,
   buildCompletionCheckStructuredOutputHints,
@@ -22,13 +28,24 @@ import {
   buildOwnershipDispatchResponseGuard,
 } from '../runtime/agent-runtime-policy'
 import { mergeInstructionSections } from '../runtime/instruction-sections'
-import { buildIndexedRepositoriesContext, getPluginService } from '../runtime/plugin-resolution'
+import {
+  buildIndexedRepositoriesContext,
+  getGithubInstallationForOrganization,
+  getLinearInstallationByOrgId,
+} from '../runtime/plugin-resolution'
 import { getTurnHooks } from '../runtime/runtime-extensions'
-import { asRecord, readInstructionSections, readOptionalString } from '../runtime/thread-chat-helpers'
-import { nodeWorkspaceService } from './node-workspace.service'
-import type { PlanValidationIssueInput } from './plan-validator.service'
-import { ThreadSchema } from './thread.types'
-import { writeIntentValidatorService } from './write-intent-validator.service'
+import { readInstructionSections, readOptionalString } from '../runtime/thread-chat-helpers'
+import { nowDate } from '../utils/date-time'
+import type { makeNodeWorkspaceService } from './node-workspace.service'
+import { NodeWorkspaceServiceTag } from './node-workspace.service'
+import type { PlanValidationIssueInput } from './plan/plan-validator.service'
+import { ThreadSchema } from './thread/thread.types'
+import type { makeWriteIntentValidatorService } from './write-intent-validator.service'
+import { WriteIntentValidatorServiceTag } from './write-intent-validator.service'
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
 
 function applyToolPolicy(tools: ToolSet, nodeSpec: PlanNodeSpec): ToolSet {
   const blockedToolNames = new Set([...OWNERSHIP_DISPATCH_BLOCKED_TOOL_NAMES, ...nodeSpec.toolPolicy.deny])
@@ -74,79 +91,151 @@ export function buildWriteIntentDispatchPrompt(nodeSpec: PlanNodeSpec): string {
 
 const MAX_SELF_CORRECTION_RETRIES = 3
 
-class AgentExecutorService {
-  validateOwner(agentId: string, nodeId: string): PlanValidationIssueInput[] {
-    if (!agentRoster.includes(agentId)) {
-      return [
-        {
-          severity: 'blocking',
-          code: 'agent_executor_missing',
-          message: `Node "${nodeId}" references unknown agent executor "${agentId}".`,
-          nodeId,
-          detail: { agentId },
-        },
-      ]
-    }
-
-    return []
+function validateOwner(agentId: string, nodeId: string): PlanValidationIssueInput[] {
+  if (!getAgentRoster().includes(agentId)) {
+    return [
+      {
+        severity: 'blocking',
+        code: 'agent_executor_missing',
+        message: `Node "${nodeId}" references unknown agent executor "${agentId}".`,
+        nodeId,
+        detail: { agentId },
+      },
+    ]
   }
 
-  async executeNode(params: {
+  return []
+}
+
+class AgentExecutorError extends Schema.TaggedErrorClass<AgentExecutorError>()('AgentExecutorError', {
+  operation: Schema.String,
+  message: Schema.String,
+  cause: Schema.Defect,
+}) {}
+
+const tryAgentExecutorPromise = makeEffectTryPromiseWithOperation(
+  (operation, message, cause) => new AgentExecutorError({ operation, message, cause }),
+)
+const tryAgentExecutorTask = <A>(
+  operation: string,
+  message: string,
+  task: () => PromiseLike<A>,
+): Effect.Effect<A, AgentExecutorError> =>
+  Effect.tryPromise({ try: task, catch: (cause) => new AgentExecutorError({ operation, message, cause }) })
+
+function isAgentExecutorOwner(
+  owner: PlanNodeSpec['owner'],
+): owner is Extract<PlanNodeSpec['owner'], { executorType: 'agent' }> {
+  return owner.executorType === 'agent'
+}
+
+function buildWriteIntentTool(params: {
+  nodeSpec: PlanNodeSpec
+  workspace: ReturnType<ReturnType<typeof makeNodeWorkspaceService>['initialize']>
+  writeIntentValidatorService: ReturnType<typeof makeWriteIntentValidatorService>
+  stageWrite: (intent: WriteIntent) => Effect.Effect<void, BadRequestError>
+}) {
+  return tool({
+    description:
+      'Write a validated artifact or structured output field. Call this for each deliverable. If validation fails, correct your payload and try again.',
+    inputSchema: WriteIntentSchema,
+    execute: (intent: WriteIntent) =>
+      runPromise(
+        Effect.gen(function* () {
+          const correctionCount = params.workspace.sys.correctionCounts.get(intent.targetPath) ?? 0
+
+          const validation = params.writeIntentValidatorService.validate({
+            intent,
+            nodeSpec: params.nodeSpec,
+            schemaRegistry: params.workspace.ctx.schemaRegistry,
+            existingDeliverables: params.workspace.deliverables,
+          })
+
+          if (validation.issues.length > 0) {
+            if (correctionCount >= MAX_SELF_CORRECTION_RETRIES) {
+              return yield* new BadRequestError({
+                message: `Write validation failed for "${intent.targetPath}" after ${MAX_SELF_CORRECTION_RETRIES} retries: ${validation.issues.map((i) => i.message).join(', ')}`,
+              })
+            }
+            params.workspace.sys.correctionCounts.set(intent.targetPath, correctionCount + 1)
+            params.workspace.sys.writeLog.push({
+              targetPath: intent.targetPath,
+              action: intent.action,
+              timestamp: nowDate(),
+              result: 'rejected',
+            })
+            return {
+              status: 'validation_failed',
+              error: { targetPath: intent.targetPath, action: intent.action, issues: validation.issues },
+              hint: `Correct and re-emit. Attempt ${correctionCount + 1}/${MAX_SELF_CORRECTION_RETRIES}.`,
+            }
+          }
+
+          yield* params.stageWrite(intent)
+          return { status: 'accepted', message: `Write to "${intent.targetPath}" validated and staged.` }
+        }),
+      ),
+  })
+}
+
+function createExecuteNode(deps: AgentExecutorDeps) {
+  return Effect.fn('AgentExecutor.executeNode')(function* (params: {
     nodeSpec: PlanNodeSpec
     resolvedInput: Record<string, unknown>
     inputArtifacts: PlanArtifactSubmission[]
     context: OwnershipDispatchContext
     executionMode?: ExecutionMode
     schemaRegistry?: PlanSchemaRegistry
-  }): Promise<PlanNodeResult> {
-    if (params.nodeSpec.owner.executorType !== 'agent') {
-      throw new Error(`AgentExecutor cannot execute owner type "${params.nodeSpec.owner.executorType}".`)
+  }) {
+    const owner = params.nodeSpec.owner
+    if (!isAgentExecutorOwner(owner)) {
+      return yield* new BadRequestError({ message: `AgentExecutor cannot execute owner type "${owner.executorType}".` })
     }
 
-    const agentId = params.nodeSpec.owner.ref
-    if (!agentRoster.includes(agentId)) {
-      throw new Error(`Agent executor "${agentId}" is not registered.`)
+    const agentId = owner.ref
+    if (!getAgentRoster().includes(agentId)) {
+      return yield* new BadRequestError({ message: `Agent executor "${agentId}" is not registered.` })
     }
 
-    const thread = await databaseService.findOne(
-      TABLES.THREAD,
-      { id: ensureRecordId(params.context.threadId, TABLES.THREAD) },
-      ThreadSchema,
-    )
+    const thread = yield* tryAgentExecutorPromise('load-thread', 'Failed to load dispatched thread.', () =>
+      deps.db.findOne(TABLES.THREAD, { id: ensureRecordId(params.context.threadId, TABLES.THREAD) }, ThreadSchema),
+    ).pipe(Effect.withSpan('AgentExecutor.loadThread'))
     if (!thread) {
-      throw new Error(`Thread ${params.context.threadId} not found for dispatched execution.`)
+      return yield* new NotFoundError({
+        resource: TABLES.THREAD,
+        message: `Thread ${params.context.threadId} not found for dispatched execution.`,
+      })
     }
 
     const organizationRef = ensureRecordId(params.context.organizationId, TABLES.ORGANIZATION)
     const threadRef = ensureRecordId(params.context.threadId, TABLES.THREAD)
     const userRefSource = params.context.userId ?? thread.userId
     if (!userRefSource) {
-      throw new Error(`Thread ${params.context.threadId} is missing a user context for dispatched execution.`)
+      return yield* new BadRequestError({
+        message: `Thread ${params.context.threadId} is missing a user context for dispatched execution.`,
+      })
     }
     const userRef = ensureRecordId(userRefSource, TABLES.USER)
     const userName = params.context.userName ?? 'User'
-    const getLinearInstallationByOrgId = getPluginService([
-      'linear',
-      'services',
-      'linearService',
-      'getInstallationByOrgId',
-    ])
-    const getGithubInstallationForOrganization = getPluginService([
-      'github',
-      'services',
-      'githubService',
-      'getInstallationForOrganization',
-    ])
-    const [linearInstallation, githubInstallation, indexedRepoContext] = await Promise.all([
-      getLinearInstallationByOrgId ? getLinearInstallationByOrgId(organizationRef) : Promise.resolve(null),
-      getGithubInstallationForOrganization
-        ? getGithubInstallationForOrganization(params.context.organizationId)
-        : Promise.resolve(null),
-      buildIndexedRepositoriesContext(params.context.organizationId),
-    ])
+    const { linearInstallation, githubInstallation, indexedRepoContext } = yield* Effect.all({
+      linearInstallation: tryAgentExecutorTask(
+        'get-linear-installation',
+        `Failed to load Linear installation for org ${params.context.organizationId}.`,
+        () => getLinearInstallationByOrgId(organizationRef),
+      ),
+      githubInstallation: tryAgentExecutorTask(
+        'get-github-installation',
+        `Failed to load GitHub installation for org ${params.context.organizationId}.`,
+        () => getGithubInstallationForOrganization(params.context.organizationId),
+      ),
+      indexedRepoContext: tryAgentExecutorTask(
+        'build-indexed-repositories-context',
+        `Failed to build indexed repository context for org ${params.context.organizationId}.`,
+        () => buildIndexedRepositoriesContext(params.context.organizationId),
+      ),
+    }).pipe(Effect.withSpan('AgentExecutor.loadInstallations'))
 
     const mode = params.executionMode ?? 'linear'
-
     const dispatchMode = thread.type === 'group' ? 'fixedThreadMode' : 'direct'
     const dispatchInstructionSections = [
       buildOwnershipDispatchContextSection({
@@ -156,23 +245,30 @@ class AgentExecutorService {
         upstreamHandoffs: params.context.upstreamHandoffs,
       }),
     ]
+
     const turnHooks = getTurnHooks()
-    const agentResolution = asRecord(
-      await turnHooks.resolveAgent?.({
-        agentId,
-        mode: dispatchMode,
-        thread,
-        threadRef,
-        orgRef: organizationRef,
-        userRef,
-        userName,
-        onboardingActive: false,
-        linearInstalled: Boolean(linearInstallation),
-        githubInstalled: Boolean(githubInstallation),
-        additionalInstructionSections: dispatchInstructionSections,
-        context: null,
-      }),
+    const agentResolutionValue = yield* tryAgentExecutorPromise(
+      'resolve-agent',
+      `Failed to resolve agent "${agentId}" for dispatched execution.`,
+      () =>
+        Promise.resolve(
+          turnHooks.resolveAgent?.({
+            agentId,
+            mode: dispatchMode,
+            thread,
+            threadRef,
+            orgRef: organizationRef,
+            userRef,
+            userName,
+            onboardingActive: false,
+            linearInstalled: Boolean(linearInstallation),
+            githubInstalled: Boolean(githubInstallation),
+            additionalInstructionSections: dispatchInstructionSections,
+            context: null,
+          }),
+        ),
     )
+    const agentResolution = isRecord(agentResolutionValue) ? agentResolutionValue : null
     const resolvedAgentId = readOptionalString(agentResolution?.agentId) ?? agentId
     const runtimeConfig = getAgentRuntimeConfig({
       agentId: resolvedAgentId,
@@ -185,32 +281,40 @@ class AgentExecutorService {
         readInstructionSections(agentResolution?.additionalInstructionSections),
       ),
       responseGuardSection: buildOwnershipDispatchResponseGuard({ node: params.nodeSpec, executionMode: mode }),
-    }) as Record<string, unknown>
+    })
 
-    const rawTools = (await buildAgentTools({
-      agentId: resolvedAgentId,
-      orgId: organizationRef,
-      userId: userRef,
-      userName,
-      threadId: threadRef,
-      orgIdString: params.context.organizationId,
-      threadType: thread.type,
-      mode: dispatchMode,
-      linearInstalled: Boolean(linearInstallation),
-      onboardingActive: false,
-      githubInstalled: Boolean(githubInstallation),
-      provideRepoTool: indexedRepoContext.provideRepoTool,
-      defaultRepoSections: indexedRepoContext.defaultSectionsByAgent[resolvedAgentId],
-      memoryBlock: '',
-      onAppendMemoryBlock: () => undefined,
-      availableUploads: [],
-      includeExecutionPlanTools: false,
-    })) as ToolSet
+    const agentFactoryConfig = getResolvedAgentFactoryConfig()
+    const rawTools = yield* tryAgentExecutorPromise(
+      'build-agent-tools',
+      `Failed to build agent tools for "${resolvedAgentId}".`,
+      () =>
+        Promise.resolve(
+          agentFactoryConfig.buildAgentTools({
+            agentId: resolvedAgentId,
+            orgId: organizationRef,
+            userId: userRef,
+            userName,
+            threadId: threadRef,
+            orgIdString: params.context.organizationId,
+            threadType: thread.type,
+            mode: dispatchMode,
+            linearInstalled: Boolean(linearInstallation),
+            onboardingActive: false,
+            githubInstalled: Boolean(githubInstallation),
+            provideRepoTool: indexedRepoContext.provideRepoTool,
+            defaultRepoSections: indexedRepoContext.defaultSectionsByAgent[resolvedAgentId],
+            memoryBlock: '',
+            onAppendMemoryBlock: () => undefined,
+            availableUploads: [],
+            includeExecutionPlanTools: false,
+          }),
+        ),
+    )
     const tools = applyToolPolicy(rawTools, params.nodeSpec)
 
-    const agentFactory = createAgent[resolvedAgentId] as ((...args: unknown[]) => unknown) | undefined
+    const agentFactory = agentFactoryConfig.createAgent[resolvedAgentId]
     if (!agentFactory) {
-      throw new Error(`Agent factory "${resolvedAgentId}" is not registered.`)
+      return yield* new BadRequestError({ message: `Agent factory "${resolvedAgentId}" is not registered.` })
     }
 
     const maxSteps = typeof runtimeConfig.maxSteps === 'number' ? runtimeConfig.maxSteps : 8
@@ -223,67 +327,40 @@ class AgentExecutorService {
           typeof runtimeConfig.extraInstructions === 'string' ? runtimeConfig.extraInstructions : undefined,
         maxRetries: 1,
         stopWhen: [stepCountIs(maxSteps)],
-      }) as ToolLoopAgent<never, ToolSet>
+      })
 
-      const result = await agent.generate({ prompt: buildDispatchPrompt(params.nodeSpec) })
+      const result = yield* tryAgentExecutorPromise(
+        'generate-agent-dispatch',
+        `Agent "${resolvedAgentId}" failed to generate a dispatch result.`,
+        () => agent.generate({ prompt: buildDispatchPrompt(params.nodeSpec) }),
+      ).pipe(Effect.withSpan('AgentExecutor.generateLinearDispatch'))
       const outputCandidate = PlanNodeResultSubmissionSchema.safeParse(result.output)
       if (outputCandidate.success) {
         return outputCandidate.data
       }
 
-      throw new Error(`Agent executor "${agentId}" returned an invalid node result.`)
+      return yield* toValidationError(
+        outputCandidate.error,
+        `Agent executor "${agentId}" returned an invalid node result`,
+      )
     }
 
-    // --- Graph-lite / Graph-full path ---
-
-    const workspace = nodeWorkspaceService.initialize({
+    const workspace = deps.nodeWorkspaceService.initialize({
       nodeSpec: params.nodeSpec,
       resolvedInput: params.resolvedInput,
       inputArtifacts: params.inputArtifacts,
       schemaRegistry: params.schemaRegistry ?? {},
     })
 
-    const writeIntentTool = tool({
-      description:
-        'Write a validated artifact or structured output field. Call this for each deliverable. If validation fails, correct your payload and try again.',
-      inputSchema: WriteIntentSchema,
-      execute: async (intent: WriteIntent) => {
-        const correctionCount = workspace.sys.correctionCounts.get(intent.targetPath) ?? 0
-
-        const validation = writeIntentValidatorService.validate({
-          intent,
-          nodeSpec: params.nodeSpec,
-          schemaRegistry: workspace.ctx.schemaRegistry,
-          existingDeliverables: workspace.deliverables,
-        })
-
-        if (validation.issues.length > 0) {
-          if (correctionCount >= MAX_SELF_CORRECTION_RETRIES) {
-            throw new Error(
-              `Write validation failed for "${intent.targetPath}" after ${MAX_SELF_CORRECTION_RETRIES} retries: ${validation.issues.map((i) => i.message).join(', ')}`,
-            )
-          }
-          workspace.sys.correctionCounts.set(intent.targetPath, correctionCount + 1)
-          workspace.sys.writeLog.push({
-            targetPath: intent.targetPath,
-            action: intent.action,
-            timestamp: new Date(),
-            result: 'rejected',
-          })
-          return {
-            status: 'validation_failed',
-            error: { targetPath: intent.targetPath, action: intent.action, issues: validation.issues },
-            hint: `Correct and re-emit. Attempt ${correctionCount + 1}/${MAX_SELF_CORRECTION_RETRIES}.`,
-          }
-        }
-
-        nodeWorkspaceService.stageWrite(workspace, intent, 'validated')
-        return { status: 'accepted', message: `Write to "${intent.targetPath}" validated and staged.` }
-      },
-    })
-
-    const graphTools = { ...tools, writeIntent: writeIntentTool }
-
+    const graphTools = {
+      ...tools,
+      writeIntent: buildWriteIntentTool({
+        nodeSpec: params.nodeSpec,
+        workspace,
+        writeIntentValidatorService: deps.writeIntentValidatorService,
+        stageWrite: (intent) => deps.nodeWorkspaceService.stageWrite(workspace, intent, 'validated'),
+      }),
+    }
     const agent = agentFactory({
       mode: dispatchMode,
       tools: graphTools,
@@ -291,11 +368,15 @@ class AgentExecutorService {
         typeof runtimeConfig.extraInstructions === 'string' ? runtimeConfig.extraInstructions : undefined,
       maxRetries: 1,
       stopWhen: [stepCountIs(maxSteps)],
-    }) as ToolLoopAgent<never, ToolSet>
+    })
 
-    await agent.generate({ prompt: buildWriteIntentDispatchPrompt(params.nodeSpec) })
+    yield* tryAgentExecutorPromise(
+      'generate-write-intent-dispatch',
+      `Agent "${resolvedAgentId}" failed to generate a write-intent dispatch result.`,
+      () => agent.generate({ prompt: buildWriteIntentDispatchPrompt(params.nodeSpec) }),
+    ).pipe(Effect.withSpan('AgentExecutor.generateWriteIntentDispatch'))
 
-    const finalResult = nodeWorkspaceService.finalize(workspace)
+    const finalResult = yield* deps.nodeWorkspaceService.finalize(workspace)
 
     if (!finalResult.isComplete) {
       const result: PlanNodeResult = {
@@ -303,7 +384,7 @@ class AgentExecutorService {
         artifacts: finalResult.artifacts,
         notes: 'Execution incomplete: missing required deliverables or validation failures.',
       }
-      nodeWorkspaceService.cleanup(workspace)
+      deps.nodeWorkspaceService.cleanup(workspace)
       return result
     }
 
@@ -313,9 +394,32 @@ class AgentExecutorService {
       notes: finalResult.notes,
     }
 
-    nodeWorkspaceService.cleanup(workspace)
+    deps.nodeWorkspaceService.cleanup(workspace)
     return result
-  }
+  })
+}
+
+interface AgentExecutorDeps {
+  db: SurrealDBService
+  nodeWorkspaceService: ReturnType<typeof makeNodeWorkspaceService>
+  writeIntentValidatorService: ReturnType<typeof makeWriteIntentValidatorService>
+}
+
+export function makeAgentExecutorService(deps: AgentExecutorDeps) {
+  return { validateOwner, executeNode: createExecuteNode(deps) }
 }
 
-export const agentExecutorService = new AgentExecutorService()
+export class AgentExecutorServiceTag extends Context.Service<
+  AgentExecutorServiceTag,
+  ReturnType<typeof makeAgentExecutorService>
+>()('@lota-sdk/core/AgentExecutorService') {}
+
+export const AgentExecutorServiceLive = Layer.effect(
+  AgentExecutorServiceTag,
+  Effect.gen(function* () {
+    const db = yield* DatabaseServiceTag
+    const nodeWorkspaceService = yield* NodeWorkspaceServiceTag
+    const writeIntentValidatorService = yield* WriteIntentValidatorServiceTag
+    return makeAgentExecutorService({ db, nodeWorkspaceService, writeIntentValidatorService })
+  }),
+)