@lota-sdk/core 0.4.9 → 0.4.10

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

@@ -17,6 +17,7 @@ import { ensureRecordId } from '../db/record-id'
 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'
@@ -112,27 +113,15 @@ class AgentExecutorError extends Schema.TaggedErrorClass<AgentExecutorError>()('
   cause: Schema.Defect,
 }) {}
 
-function tryAgentExecutorPromise<A>(
+const tryAgentExecutorPromise = makeEffectTryPromiseWithOperation(
+  (operation, message, cause) => new AgentExecutorError({ operation, message, cause }),
+)
+const tryAgentExecutorTask = <A>(
   operation: string,
   message: string,
-  thunk: () => PromiseLike<A> | A | Effect.Effect<A, unknown, never>,
-): Effect.Effect<A, AgentExecutorError> {
-  return Effect.suspend(() => {
-    try {
-      const value = thunk()
-      if (Effect.isEffect(value)) {
-        return value.pipe(Effect.mapError((cause) => new AgentExecutorError({ operation, message, cause })))
-      }
-
-      return Effect.tryPromise({
-        try: () => Promise.resolve(value),
-        catch: (cause) => new AgentExecutorError({ operation, message, cause }),
-      })
-    } catch (cause) {
-      return Effect.fail(new AgentExecutorError({ operation, message, cause }))
-    }
-  })
-}
+  task: () => PromiseLike<A>,
+): Effect.Effect<A, AgentExecutorError> =>
+  Effect.tryPromise({ try: task, catch: (cause) => new AgentExecutorError({ operation, message, cause }) })
 
 function isAgentExecutorOwner(
   owner: PlanNodeSpec['owner'],
@@ -190,7 +179,7 @@ function buildWriteIntentTool(params: {
 }
 
 function createExecuteNode(deps: AgentExecutorDeps) {
-  return function executeNode(params: {
+  return Effect.fn('AgentExecutor.executeNode')(function* (params: {
     nodeSpec: PlanNodeSpec
     resolvedInput: Record<string, unknown>
     inputArtifacts: PlanArtifactSubmission[]
@@ -198,70 +187,70 @@ function createExecuteNode(deps: AgentExecutorDeps) {
     executionMode?: ExecutionMode
     schemaRegistry?: PlanSchemaRegistry
   }) {
-    return Effect.gen(function* () {
-      const owner = params.nodeSpec.owner
-      if (!isAgentExecutorOwner(owner)) {
-        return yield* new BadRequestError({
-          message: `AgentExecutor cannot execute owner type "${owner.executorType}".`,
-        })
-      }
+    const owner = params.nodeSpec.owner
+    if (!isAgentExecutorOwner(owner)) {
+      return yield* new BadRequestError({ message: `AgentExecutor cannot execute owner type "${owner.executorType}".` })
+    }
 
-      const agentId = owner.ref
-      if (!getAgentRoster().includes(agentId)) {
-        return yield* new BadRequestError({ message: `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 = yield* tryAgentExecutorPromise('load-thread', 'Failed to load dispatched thread.', () =>
-        deps.db.findOne(TABLES.THREAD, { id: ensureRecordId(params.context.threadId, TABLES.THREAD) }, ThreadSchema),
-      )
-      if (!thread) {
-        return yield* new NotFoundError({
-          resource: TABLES.THREAD,
-          message: `Thread ${params.context.threadId} not found for dispatched execution.`,
-        })
-      }
+    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) {
+      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) {
-        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 [linearInstallation, githubInstallation, indexedRepoContext] = yield* Effect.all([
-        tryAgentExecutorPromise(
-          'get-linear-installation',
-          `Failed to load Linear installation for org ${params.context.organizationId}.`,
-          () => getLinearInstallationByOrgId(organizationRef),
-        ),
-        tryAgentExecutorPromise(
-          'get-github-installation',
-          `Failed to load GitHub installation for org ${params.context.organizationId}.`,
-          () => getGithubInstallationForOrganization(params.context.organizationId),
-        ),
-        tryAgentExecutorPromise(
-          'build-indexed-repositories-context',
-          `Failed to build indexed repository context for org ${params.context.organizationId}.`,
-          () => buildIndexedRepositoriesContext(params.context.organizationId),
-        ),
-      ])
-
-      const mode = params.executionMode ?? 'linear'
-      const dispatchMode = thread.type === 'group' ? 'fixedThreadMode' : 'direct'
-      const dispatchInstructionSections = [
-        buildOwnershipDispatchContextSection({
-          node: params.nodeSpec,
-          resolvedInput: params.resolvedInput,
-          inputArtifacts: params.inputArtifacts,
-          upstreamHandoffs: params.context.upstreamHandoffs,
-        }),
-      ]
+    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) {
+      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 { 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({
+        node: params.nodeSpec,
+        resolvedInput: params.resolvedInput,
+        inputArtifacts: params.inputArtifacts,
+        upstreamHandoffs: params.context.upstreamHandoffs,
+      }),
+    ]
 
-      const turnHooks = getTurnHooks()
-      const agentResolutionValue = yield* Effect.tryPromise(() =>
+    const turnHooks = getTurnHooks()
+    const agentResolutionValue = yield* tryAgentExecutorPromise(
+      'resolve-agent',
+      `Failed to resolve agent "${agentId}" for dispatched execution.`,
+      () =>
         Promise.resolve(
           turnHooks.resolveAgent?.({
             agentId,
@@ -278,133 +267,136 @@ function createExecuteNode(deps: AgentExecutorDeps) {
             context: null,
           }),
         ),
-      )
-      const agentResolution = isRecord(agentResolutionValue) ? agentResolutionValue : null
-      const resolvedAgentId = readOptionalString(agentResolution?.agentId) ?? agentId
-      const runtimeConfig = getAgentRuntimeConfig({
-        agentId: resolvedAgentId,
-        threadType: thread.type,
-        mode: dispatchMode,
-        onboardingActive: false,
-        linearInstalled: Boolean(linearInstallation),
-        additionalInstructionSections: mergeInstructionSections(
-          dispatchInstructionSections,
-          readInstructionSections(agentResolution?.additionalInstructionSections),
-        ),
-        responseGuardSection: buildOwnershipDispatchResponseGuard({ node: params.nodeSpec, executionMode: mode }),
-      })
-
-      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 agentResolution = isRecord(agentResolutionValue) ? agentResolutionValue : null
+    const resolvedAgentId = readOptionalString(agentResolution?.agentId) ?? agentId
+    const runtimeConfig = getAgentRuntimeConfig({
+      agentId: resolvedAgentId,
+      threadType: thread.type,
+      mode: dispatchMode,
+      onboardingActive: false,
+      linearInstalled: Boolean(linearInstallation),
+      additionalInstructionSections: mergeInstructionSections(
+        dispatchInstructionSections,
+        readInstructionSections(agentResolution?.additionalInstructionSections),
+      ),
+      responseGuardSection: buildOwnershipDispatchResponseGuard({ node: params.nodeSpec, executionMode: mode }),
+    })
 
-      const agentFactory = agentFactoryConfig.createAgent[resolvedAgentId]
-      if (!agentFactory) {
-        return yield* new BadRequestError({ message: `Agent factory "${resolvedAgentId}" is not registered.` })
-      }
+    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 maxSteps = typeof runtimeConfig.maxSteps === 'number' ? runtimeConfig.maxSteps : 8
-
-      if (mode === 'linear') {
-        const agent = agentFactory({
-          mode: dispatchMode,
-          tools,
-          extraInstructions:
-            typeof runtimeConfig.extraInstructions === 'string' ? runtimeConfig.extraInstructions : undefined,
-          maxRetries: 1,
-          stopWhen: [stepCountIs(maxSteps)],
-        })
-
-        const result = yield* tryAgentExecutorPromise(
-          'generate-agent-dispatch',
-          `Agent "${resolvedAgentId}" failed to generate a dispatch result.`,
-          () => agent.generate({ prompt: buildDispatchPrompt(params.nodeSpec) }),
-        )
-        const outputCandidate = PlanNodeResultSubmissionSchema.safeParse(result.output)
-        if (outputCandidate.success) {
-          return outputCandidate.data
-        }
-
-        return yield* toValidationError(
-          outputCandidate.error,
-          `Agent executor "${agentId}" returned an invalid node result`,
-        )
-      }
+    const agentFactory = agentFactoryConfig.createAgent[resolvedAgentId]
+    if (!agentFactory) {
+      return yield* new BadRequestError({ message: `Agent factory "${resolvedAgentId}" is not registered.` })
+    }
 
-      const workspace = deps.nodeWorkspaceService.initialize({
-        nodeSpec: params.nodeSpec,
-        resolvedInput: params.resolvedInput,
-        inputArtifacts: params.inputArtifacts,
-        schemaRegistry: params.schemaRegistry ?? {},
-      })
+    const maxSteps = typeof runtimeConfig.maxSteps === 'number' ? runtimeConfig.maxSteps : 8
 
-      const graphTools = {
-        ...tools,
-        writeIntent: buildWriteIntentTool({
-          nodeSpec: params.nodeSpec,
-          workspace,
-          writeIntentValidatorService: deps.writeIntentValidatorService,
-          stageWrite: (intent) => deps.nodeWorkspaceService.stageWrite(workspace, intent, 'validated'),
-        }),
-      }
+    if (mode === 'linear') {
       const agent = agentFactory({
         mode: dispatchMode,
-        tools: graphTools,
+        tools,
         extraInstructions:
           typeof runtimeConfig.extraInstructions === 'string' ? runtimeConfig.extraInstructions : undefined,
         maxRetries: 1,
         stopWhen: [stepCountIs(maxSteps)],
       })
 
-      yield* Effect.tryPromise(() => agent.generate({ prompt: buildWriteIntentDispatchPrompt(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
+      }
+
+      return yield* toValidationError(
+        outputCandidate.error,
+        `Agent executor "${agentId}" returned an invalid node result`,
+      )
+    }
 
-      const finalResult = yield* deps.nodeWorkspaceService.finalize(workspace)
+    const workspace = deps.nodeWorkspaceService.initialize({
+      nodeSpec: params.nodeSpec,
+      resolvedInput: params.resolvedInput,
+      inputArtifacts: params.inputArtifacts,
+      schemaRegistry: params.schemaRegistry ?? {},
+    })
 
-      if (!finalResult.isComplete) {
-        const result: PlanNodeResult = {
-          structuredOutput: finalResult.structuredOutput,
-          artifacts: finalResult.artifacts,
-          notes: 'Execution incomplete: missing required deliverables or validation failures.',
-        }
-        deps.nodeWorkspaceService.cleanup(workspace)
-        return result
-      }
+    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,
+      extraInstructions:
+        typeof runtimeConfig.extraInstructions === 'string' ? runtimeConfig.extraInstructions : undefined,
+      maxRetries: 1,
+      stopWhen: [stepCountIs(maxSteps)],
+    })
+
+    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 = yield* deps.nodeWorkspaceService.finalize(workspace)
+
+    if (!finalResult.isComplete) {
       const result: PlanNodeResult = {
         structuredOutput: finalResult.structuredOutput,
         artifacts: finalResult.artifacts,
-        notes: finalResult.notes,
+        notes: 'Execution incomplete: missing required deliverables or validation failures.',
       }
-
       deps.nodeWorkspaceService.cleanup(workspace)
       return result
-    })
-  }
+    }
+
+    const result: PlanNodeResult = {
+      structuredOutput: finalResult.structuredOutput,
+      artifacts: finalResult.artifacts,
+      notes: finalResult.notes,
+    }
+
+    deps.nodeWorkspaceService.cleanup(workspace)
+    return result
+  })
 }
 
 interface AgentExecutorDeps {
@@ -420,7 +412,7 @@ export function makeAgentExecutorService(deps: AgentExecutorDeps) {
 export class AgentExecutorServiceTag extends Context.Service<
   AgentExecutorServiceTag,
   ReturnType<typeof makeAgentExecutorService>
->()('AgentExecutorService') {}
+>()('@lota-sdk/core/AgentExecutorService') {}
 
 export const AgentExecutorServiceLive = Layer.effect(
   AgentExecutorServiceTag,

package/src/services/artifact.service.ts

@@ -15,7 +15,7 @@ import type { SurrealDBService, DatabaseTransaction } from '../db/service'
 import { TABLES } from '../db/tables'
 import { ConfigurationError, DatabaseError, NotFoundError } from '../effect/errors'
 import { DatabaseServiceTag } from '../effect/services'
-import { toValidationError } from '../effect/zod'
+import { toValidationError, zodParse } from '../effect/zod'
 import type { makeGeneratedDocumentStorageService } from '../storage/generated-document-storage.service'
 import { GeneratedDocumentStorageServiceTag } from '../storage/generated-document-storage.service'
 import { sha256Hex } from '../utils/crypto'
@@ -180,7 +180,7 @@ export function makeArtifactService(deps: ArtifactServiceDeps) {
         },
       })
 
-      return ArtifactRecordSchema.array().parse(records)
+      return yield* zodParse(ArtifactRecordSchema.array(), records)
     })
 
   const publishArtifactInTransactionEffect = (
@@ -247,7 +247,7 @@ export function makeArtifactService(deps: ArtifactServiceDeps) {
         })
       }
 
-      const created = ArtifactRecordSchema.parse(createdRecord)
+      const created = yield* zodParse(ArtifactRecordSchema, createdRecord)
 
       const previousActive = existing.find((record) => record.status === 'active')
       if (previousActive) {
@@ -392,7 +392,12 @@ export function makeArtifactService(deps: ArtifactServiceDeps) {
         listBacklinksEffect(artifact),
       ])
 
-      return GetArtifactResultSchema.parse({ artifact, content, versions: versions.map(toVersionSummary), backlinks })
+      return yield* zodParse(GetArtifactResultSchema, {
+        artifact,
+        content,
+        versions: versions.map(toVersionSummary),
+        backlinks,
+      })
     })
 
   const listBacklinksEffect = (artifact: Pick<ArtifactRecord, 'id' | 'organizationId'>) =>
@@ -439,7 +444,7 @@ export function makeArtifactService(deps: ArtifactServiceDeps) {
 }
 
 export class ArtifactServiceTag extends Context.Service<ArtifactServiceTag, ReturnType<typeof makeArtifactService>>()(
-  'ArtifactService',
+  '@lota-sdk/core/ArtifactService',
 ) {}
 
 export const ArtifactServiceLive = Layer.effect(

package/src/services/attachment.service.ts

@@ -67,6 +67,10 @@ export function makeAttachmentService(attachmentStorage: ReturnType<typeof makeA
       return runPromise(attachmentStorage.extractStoredAttachmentText({ storageKey, name, contentType }))
     },
 
+    extractStoredAttachmentTextEffect(params: { storageKey: string; name: string; contentType: string }) {
+      return attachmentStorage.extractStoredAttachmentText(params)
+    },
+
     extractStoredAttachmentPages({
       storageKey,
       name,
@@ -79,6 +83,10 @@ export function makeAttachmentService(attachmentStorage: ReturnType<typeof makeA
       return runPromise(attachmentStorage.extractStoredAttachmentPages({ storageKey, name, contentType }))
     },
 
+    extractStoredAttachmentPagesEffect(params: { storageKey: string; name: string; contentType: string }) {
+      return attachmentStorage.extractStoredAttachmentPages(params)
+    },
+
     readFilePartsFromUpload({
       upload,
       orgId,
@@ -129,6 +137,28 @@ export function makeAttachmentService(attachmentStorage: ReturnType<typeof makeA
       )
     },
 
+    writeOrganizationDocumentEffect({
+      orgId,
+      namespace,
+      relativePath,
+      content,
+      contentType,
+    }: {
+      orgId: RecordIdRef
+      namespace: string
+      relativePath: string
+      content: string
+      contentType: string
+    }) {
+      return attachmentStorage.writeOrganizationDocument({
+        orgId: toOrgId(orgId),
+        namespace,
+        relativePath,
+        content,
+        contentType,
+      })
+    },
+
     uploadOrganizationDocument({
       file,
       orgId,
@@ -156,13 +186,17 @@ export function makeAttachmentService(attachmentStorage: ReturnType<typeof makeA
         attachmentStorage.uploadThreadAttachment({ file, orgId: toOrgId(orgId), userId: toUserId(userId) }),
       )
     },
+
+    uploadThreadAttachmentEffect({ file, orgId, userId }: { file: File; orgId: RecordIdRef; userId: RecordIdRef }) {
+      return attachmentStorage.uploadThreadAttachment({ file, orgId: toOrgId(orgId), userId: toUserId(userId) })
+    },
   }
 }
 
 export class AttachmentServiceTag extends Context.Service<
   AttachmentServiceTag,
   ReturnType<typeof makeAttachmentService>
->()('AttachmentService') {}
+>()('@lota-sdk/core/AttachmentService') {}
 
 export const AttachmentServiceLive = Layer.effect(
   AttachmentServiceTag,