@lota-sdk/core 0.4.9 → 0.4.10

package/src/storage/attachment-storage.service.ts

@@ -107,11 +107,14 @@ export function makeAttachmentStorageService(config: ResolvedLotaRuntimeConfig)
     storageKey: string
     orgId: string
     userId: string
-  }): void {
+  }): Effect.Effect<void, ForbiddenError> {
     const storagePrefix = buildUploadStoragePrefix({ orgId, userId })
     if (!storageKey.startsWith(storagePrefix)) {
-      throw new ForbiddenError({ message: 'Upload does not belong to the current organization/user scope.' })
+      return Effect.fail(
+        new ForbiddenError({ message: 'Upload does not belong to the current organization/user scope.' }),
+      )
     }
+    return Effect.void
   }
 
   function writeOrganizationDocumentEffect({
@@ -284,7 +287,7 @@ export function makeAttachmentStorageService(config: ResolvedLotaRuntimeConfig)
     pagesPerPart?: number
   }) {
     return Effect.gen(function* () {
-      assertUploadOwnership({ storageKey: upload.storageKey, orgId, userId })
+      yield* assertUploadOwnership({ storageKey: upload.storageKey, orgId, userId })
 
       const parsed = yield* extractStoredAttachmentPagesEffect({
         storageKey: upload.storageKey,
@@ -437,7 +440,7 @@ export function makeAttachmentStorageService(config: ResolvedLotaRuntimeConfig)
 export class AttachmentStorageServiceTag extends Context.Service<
   AttachmentStorageServiceTag,
   ReturnType<typeof makeAttachmentStorageService>
->()('AttachmentStorageService') {}
+>()('@lota-sdk/core/AttachmentStorageService') {}
 
 export const AttachmentStorageServiceLive = Layer.effect(
   AttachmentStorageServiceTag,

package/src/storage/generated-document-storage.service.ts

@@ -86,7 +86,7 @@ export function makeGeneratedDocumentStorageService(config: ResolvedLotaRuntimeC
 export class GeneratedDocumentStorageServiceTag extends Context.Service<
   GeneratedDocumentStorageServiceTag,
   ReturnType<typeof makeGeneratedDocumentStorageService>
->()('GeneratedDocumentStorageService') {}
+>()('@lota-sdk/core/GeneratedDocumentStorageService') {}
 
 export const GeneratedDocumentStorageServiceLive = Layer.effect(
   GeneratedDocumentStorageServiceTag,

package/src/system-agents/context-compaction.agent.ts

@@ -1,3 +1,4 @@
+import type { CreateHelperToolLoopAgentOptions } from '@lota-sdk/shared'
 import { ToolLoopAgent } from 'ai'
 
 import { aiGatewayChatModel } from '../ai-gateway/ai-gateway'
@@ -6,7 +7,6 @@ import {
   OPENROUTER_STRUCTURED_HELPER_MODEL_ID,
   OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
 } from '../config/model-constants'
-import type { CreateHelperToolLoopAgentOptions } from '../runtime/agent-types'
 import { resolveHelperAgentOptions } from './helper-agent-options'
 
 const CONTEXT_COMPACTION_PROMPT = `<agent-instructions>

package/src/system-agents/helper-agent-options.ts

@@ -1,4 +1,4 @@
-import type { CreateHelperToolLoopAgentOptions } from '../runtime/agent-types'
+import type { CreateHelperToolLoopAgentOptions } from '@lota-sdk/shared'
 
 interface HelperAgentOptionOverrides {
   instructions?: string

package/src/system-agents/memory-reranker.agent.ts

@@ -1,3 +1,4 @@
+import type { CreateHelperToolLoopAgentOptions } from '@lota-sdk/shared'
 import { ToolLoopAgent } from 'ai'
 
 import { aiGatewayChatModel } from '../ai-gateway/ai-gateway'
@@ -6,7 +7,6 @@ import {
   OPENROUTER_LOW_REASONING_PROVIDER_OPTIONS,
   OPENROUTER_STRUCTURED_HELPER_MODEL_ID,
 } from '../config/model-constants'
-import type { CreateHelperToolLoopAgentOptions } from '../runtime/agent-types'
 import { resolveHelperAgentOptions } from './helper-agent-options'
 
 export const MEMORY_RERANKER_PROMPT = `<agent-instructions>

package/src/system-agents/memory.agent.ts

@@ -1,3 +1,4 @@
+import type { CreateHelperToolLoopAgentOptions } from '@lota-sdk/shared'
 import { ToolLoopAgent } from 'ai'
 
 import { aiGatewayChatModel } from '../ai-gateway/ai-gateway'
@@ -6,7 +7,6 @@ import {
   OPENROUTER_STRUCTURED_HELPER_MODEL_ID,
   OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
 } from '../config/model-constants'
-import type { CreateHelperToolLoopAgentOptions } from '../runtime/agent-types'
 import { resolveHelperAgentOptions } from './helper-agent-options'
 
 export const ORG_MEMORY_PROMPT = `<agent-instructions>

package/src/system-agents/recent-activity-title-refiner.agent.ts

@@ -1,3 +1,4 @@
+import type { CreateHelperToolLoopAgentOptions } from '@lota-sdk/shared'
 import { ToolLoopAgent } from 'ai'
 
 import { aiGatewayChatModel } from '../ai-gateway/ai-gateway'
@@ -7,7 +8,6 @@ import {
   OPENROUTER_STRUCTURED_HELPER_MODEL_ID,
   OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
 } from '../config/model-constants'
-import type { CreateHelperToolLoopAgentOptions } from '../runtime/agent-types'
 import { resolveHelperAgentOptions } from './helper-agent-options'
 
 const RECENT_ACTIVITY_TITLE_MAX_TOKENS = 256

package/src/system-agents/regular-chat-memory-digest.agent.ts

@@ -1,3 +1,4 @@
+import type { CreateHelperToolLoopAgentOptions } from '@lota-sdk/shared'
 import { ToolLoopAgent } from 'ai'
 
 import { aiGatewayChatModel } from '../ai-gateway/ai-gateway'
@@ -6,7 +7,6 @@ import {
   OPENROUTER_STRUCTURED_HELPER_MODEL_ID,
   OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
 } from '../config/model-constants'
-import type { CreateHelperToolLoopAgentOptions } from '../runtime/agent-types'
 import { resolveHelperAgentOptions } from './helper-agent-options'
 
 const REGULAR_CHAT_MEMORY_DIGEST_MAX_TOKENS = 8_192

package/src/system-agents/skill-extractor.agent.ts

@@ -1,3 +1,4 @@
+import type { CreateHelperToolLoopAgentOptions } from '@lota-sdk/shared'
 import { ToolLoopAgent } from 'ai'
 import { z } from 'zod'
 
@@ -7,7 +8,6 @@ import {
   OPENROUTER_STRUCTURED_HELPER_MODEL_ID,
   OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
 } from '../config/model-constants'
-import type { CreateHelperToolLoopAgentOptions } from '../runtime/agent-types'
 import { resolveHelperAgentOptions } from './helper-agent-options'
 
 const SKILL_EXTRACTOR_MAX_TOKENS = 8_192

package/src/system-agents/skill-manager.agent.ts

@@ -1,3 +1,4 @@
+import type { CreateHelperToolLoopAgentOptions } from '@lota-sdk/shared'
 import { ToolLoopAgent } from 'ai'
 import { z } from 'zod'
 
@@ -7,7 +8,6 @@ import {
   OPENROUTER_STRUCTURED_HELPER_MODEL_ID,
   OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
 } from '../config/model-constants'
-import type { CreateHelperToolLoopAgentOptions } from '../runtime/agent-types'
 import { resolveHelperAgentOptions } from './helper-agent-options'
 
 const SKILL_MANAGER_MAX_TOKENS = 4_096

package/src/system-agents/title-generator.agent.ts

@@ -1,3 +1,4 @@
+import type { CreateHelperToolLoopAgentOptions } from '@lota-sdk/shared'
 import { ToolLoopAgent } from 'ai'
 
 import { aiGatewayChatModel } from '../ai-gateway/ai-gateway'
@@ -6,7 +7,6 @@ import {
   OPENROUTER_FAST_REASONING_MODEL_ID,
   OPENROUTER_MINIMAL_REASONING_PROVIDER_OPTIONS,
 } from '../config/model-constants'
-import type { CreateHelperToolLoopAgentOptions } from '../runtime/agent-types'
 import { resolveHelperAgentOptions } from './helper-agent-options'
 
 const THREAD_TITLE_MAX_TOKENS = 512

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

@@ -24,22 +24,31 @@ 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<
-  ReturnType<typeof makeThreadService>,
-  'createThread' | 'deleteThread' | 'getThread'
+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 ExecutionPlanThreadService = NoContextService<
+  Pick<ReturnType<typeof makeThreadService>, 'createThread' | 'deleteThread' | 'getThread'>
 >
 
-type ExecutionPlanExecutionPlanService = Pick<
-  ReturnType<typeof makeExecutionPlanService>,
-  | 'createPlan'
-  | 'replacePlan'
-  | 'resumeRun'
-  | 'submitNodeResult'
-  | 'listActivePlanSummaries'
-  | 'getActivePlanToolResult'
-  | 'getActivePlansForThread'
+type ExecutionPlanExecutionPlanService = NoContextService<
+  Pick<
+    ReturnType<typeof makeExecutionPlanService>,
+    | 'createPlan'
+    | 'replacePlan'
+    | 'resumeRun'
+    | 'submitNodeResult'
+    | 'listActivePlanSummaries'
+    | 'getActivePlanToolResult'
+    | 'getActivePlansForThread'
+  >
 >
 
+type ExecutionPlanToolValidationError = ReturnType<typeof toValidationError>
+
 export function createExecutionPlanTool(params: {
   orgId: RecordIdRef
   userId: RecordIdRef
@@ -198,12 +207,14 @@ export function createExecutionPlanTool(params: {
               return result
             }
           }
-        }),
+        }).pipe(Effect.withSpan('tool.executionPlan.execute')),
       ),
   })
 }
 
-function parseExecutionPlanArgsEffect(input: unknown) {
+function parseExecutionPlanArgsEffect(
+  input: unknown,
+): Effect.Effect<ExecutionPlanArgs, ExecutionPlanToolValidationError> {
   return Effect.gen(function* () {
     const parsedArgs = ExecutionPlanArgsSchema.safeParse(input)
     if (!parsedArgs.success) {
@@ -233,7 +244,7 @@ function parseExecutionPlanArgsEffect(input: unknown) {
 
 function extractAgentPlanDraftEffect(
   input: Extract<ExecutionPlanArgs, { action: 'create' | 'create-project' | 'replace' }>,
-) {
+): Effect.Effect<ReturnType<typeof expandAgentPlanDraft>, ExecutionPlanToolValidationError> {
   return Effect.gen(function* () {
     const parsedDraft = AgentPlanDraftSchema.safeParse({
       title: input.title,
@@ -271,7 +282,7 @@ export function createExecutionPlanQueryTool(params: {
             includeCheckpoints: input.includeCheckpoints,
             includeValidationIssues: input.includeValidationIssues,
           })
-        }),
+        }).pipe(Effect.withSpan('tool.executionPlanQuery.execute')),
       ),
   })
 }
@@ -296,7 +307,7 @@ export function createSubmitExecutionNodeResultTool(params: {
           })
           params.onPlanChanged?.()
           return result
-        }),
+        }).pipe(Effect.withSpan('tool.submitExecutionNodeResult.execute')),
       ),
     toModelOutput: ({ output }) => {
       const result = getLatestExecutionPlanResult(output)

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

@@ -1,5 +1,5 @@
 import { tool } from 'ai'
-import { Effect } from 'effect'
+import { Effect, Schema } from 'effect'
 import { z } from 'zod'
 
 import type { ToolDefinition } from '../ai/definitions'
@@ -10,6 +10,11 @@ import { getFirecrawlClient } from './firecrawl-client'
 import type { WebCitation } from './tool-contracts'
 import { toRecord, WEB_TOOL_TIMEOUT_MS } from './web-tool-shared'
 
+class FetchWebpageToolError extends Schema.TaggedErrorClass<FetchWebpageToolError>()(
+  '@lota-sdk/core/FetchWebpageToolError',
+  { message: Schema.String, cause: Schema.optional(Schema.Defect) },
+) {}
+
 const FormatSchema = z.enum(['markdown', 'html', 'rawHtml', 'links', 'images', 'screenshot', 'summary'])
 const MAX_MARKDOWN_CHARS = 6_000
 const MAX_SUMMARY_CHARS = 1_200
@@ -119,19 +124,21 @@ export const fetchWebpageTool = {
 
         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',
-              ),
-            )
+            const result = yield* Effect.tryPromise({
+              try: () =>
+                withTimeout(
+                  firecrawl.scrape(url, {
+                    formats: formats?.length ? formats : ['markdown'],
+                    onlyMainContent: onlyMainContent ?? true,
+                    maxAge,
+                  }),
+                  WEB_TOOL_TIMEOUT_MS,
+                  'Webpage fetch',
+                ),
+              catch: (cause) => new FetchWebpageToolError({ message: `Webpage fetch failed for ${url}.`, cause }),
+            })
             return { url, document: summarizeDocument(url, result), citations: buildFetchCitations(url, result) }
-          }),
+          }).pipe(Effect.withSpan('tool.fetchWebpage.execute')),
         )
       },
     }),

package/src/tools/firecrawl-client.ts

@@ -1,10 +1,10 @@
 import Firecrawl from '@mendable/firecrawl-js'
 import { Context, Effect, Layer } from 'effect'
 
-import { getCurrentRuntime } from '../effect/runtime-ref'
+import { resolveLotaService } from '../effect/runtime'
 import { RuntimeConfigServiceTag } from '../effect/services'
 
-export class FirecrawlTag extends Context.Service<FirecrawlTag, Firecrawl>()('Firecrawl') {}
+export class FirecrawlTag extends Context.Service<FirecrawlTag, Firecrawl>()('@lota-sdk/core/Firecrawl') {}
 
 export const FirecrawlLive = Layer.effect(
   FirecrawlTag,
@@ -17,6 +17,16 @@ export const FirecrawlLive = Layer.effect(
   }),
 )
 
+let currentFirecrawlClient: Firecrawl | null = null
+
+export function configureFirecrawlClient(client: Firecrawl): void {
+  currentFirecrawlClient = client
+}
+
+export function clearFirecrawlClient(): void {
+  currentFirecrawlClient = null
+}
+
 export function getFirecrawlClient(): Firecrawl {
-  return getCurrentRuntime().runSync(Effect.service(FirecrawlTag))
+  return currentFirecrawlClient ?? resolveLotaService(FirecrawlTag)
 }

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

@@ -6,7 +6,15 @@ import type { RecordIdRef } from '../db/record-id'
 import type { makeExecutionPlanService } from '../services/execution-plan/execution-plan.service'
 import { toToolPlanSummary } from '../services/plan/plan-run-data'
 
-type PlanApprovalExecutionPlanService = Pick<ReturnType<typeof makeExecutionPlanService>, '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

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

@@ -1,5 +1,5 @@
 import { tool } from 'ai'
-import { Effect } from 'effect'
+import { Effect, Schema } from 'effect'
 import { z } from 'zod'
 
 import type { ToolDefinition } from '../ai/definitions'
@@ -10,6 +10,11 @@ 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 SourceSchema = z.enum(['web', 'news', 'images'])
 const MAX_RESULTS_PER_SOURCE = 4
 const MAX_SNIPPET_CHARS = 320
@@ -159,13 +164,15 @@ export const searchWebTool = {
 
         return Effect.runPromise(
           Effect.gen(function* () {
-            const results = yield* Effect.tryPromise(() =>
-              withTimeout(
-                firecrawl.search(query, { limit, sources, location, tbs }),
-                WEB_TOOL_TIMEOUT_MS,
-                'Web search',
-              ),
-            )
+            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: {
@@ -175,7 +182,7 @@ export const searchWebTool = {
               },
               citations: buildWebCitations(results),
             }
-          }),
+          }).pipe(Effect.withSpan('tool.searchWeb.execute')),
         )
       },
     }),

package/src/tools/team-think.tool.ts

@@ -161,7 +161,7 @@ export function createTeamThinkTool(params: {
               aiLogger.error`Team-think participant failed (${agentId}): ${error}`
             },
             recordAbort: (error: unknown) => {
-              aiLogger.info`Team-think participant aborted (${agentId}): ${
+              aiLogger.debug`Team-think participant aborted (${agentId}): ${
                 error instanceof Error ? error.message : String(error)
               }`
             },
@@ -170,7 +170,7 @@ export function createTeamThinkTool(params: {
             agent: agent as Awaited<ReturnType<TeamConsultationParticipantRunner['buildParticipantAgent']>>['agent'],
             observer,
           }
-        }),
+        }).pipe(Effect.withSpan('tool.teamThink.buildParticipantAgent')),
       )
     },
   }

package/src/utils/async.ts

@@ -1,24 +1,33 @@
-import { Schema, Duration, Effect } from 'effect'
+import { Cause, Duration, Effect, Exit, Schema } from 'effect'
 
 import { serverLogger } from '../config/logger'
 import { TimeoutError } from '../effect/errors'
-import { getErrorMessage } from './errors'
+import { getErrorMessage, toError } from './errors'
 
 class TimedOperationError extends Schema.TaggedErrorClass<TimedOperationError>()('TimedOperationError', {
   operation: Schema.String,
   cause: Schema.Defect,
 }) {}
 
+function isTimedOperationError(error: unknown): error is TimedOperationError {
+  return typeof error === 'object' && error !== null && '_tag' in error && error._tag === 'TimedOperationError'
+}
+
 export function withTimeout<T>(promise: Promise<T>, ms: number, operation: string): Promise<T> {
   return Effect.runPromise(
     Effect.tryPromise({ try: () => promise, catch: (cause) => new TimedOperationError({ operation, cause }) }).pipe(
       Effect.timeout(Duration.millis(ms)),
       Effect.catchTag('TimeoutError', () => Effect.fail(new TimeoutError({ operation, ms }))),
-      Effect.catchTag('TimedOperationError', (error) =>
-        Effect.fail(error.cause instanceof Error ? error.cause : new Error(String(error.cause))),
-      ),
+      Effect.exit,
     ),
-  )
+  ).then((exit) => {
+    if (Exit.isSuccess(exit)) {
+      return exit.value
+    }
+
+    const error = Cause.squash(exit.cause)
+    throw isTimedOperationError(error) ? toError(error.cause) : error
+  })
 }
 
 export function createSafeEnqueue(logger: { warn: (message: string) => void }) {

package/src/utils/errors.ts

@@ -1,5 +1,5 @@
 export { getErrorMessage } from '@lota-sdk/shared'
-import { Match } from 'effect'
+import { Data, Match } from 'effect'
 
 import type { EffectError, ValidationIssue } from '../effect/errors'
 import { BaseServicePersistenceError, isEffectError } from '../effect/errors'
@@ -19,18 +19,16 @@ export interface AppErrorResponse {
   body: { error: { code: string; message: string } }
 }
 
-export type AppErrorLike = Error & { code: string; statusCode: number; toResponse?: () => AppErrorResponse }
+export type AppErrorLike = Error & { code: string; statusCode: number; toResponse?: () => unknown }
 
-export class AppError extends Error {
+export class AppError extends Data.Error<{
+  readonly message: string
   readonly code: string
   readonly statusCode: number
-
+}> {
   constructor(message: string, code: string, statusCode: number) {
-    super(message)
+    super({ message, code, statusCode })
     this.name = new.target.name
-    this.code = code
-    this.statusCode = statusCode
-    Object.setPrototypeOf(this, new.target.prototype)
   }
 
   toResponse(): AppErrorResponse {
@@ -99,16 +97,30 @@ export function isAppErrorLike(error: unknown): error is AppErrorLike {
   return typeof candidate.code === 'string' && typeof candidate.statusCode === 'number'
 }
 
+function isAppErrorResponse(value: unknown): value is AppErrorResponse {
+  if (typeof value !== 'object' || value === null) {
+    return false
+  }
+
+  const candidate = value as {
+    status?: unknown
+    body?: { error?: { code?: unknown; message?: unknown } | null } | null
+  }
+  return (
+    typeof candidate.status === 'number' &&
+    typeof candidate.body === 'object' &&
+    candidate.body !== null &&
+    typeof candidate.body.error === 'object' &&
+    candidate.body.error !== null &&
+    typeof candidate.body.error.code === 'string' &&
+    typeof candidate.body.error.message === 'string'
+  )
+}
+
 export function toAppErrorResponse(error: AppErrorLike): AppErrorResponse {
   if (typeof error.toResponse === 'function') {
     const response = error.toResponse()
-    if (
-      response &&
-      typeof response === 'object' &&
-      typeof response.status === 'number' &&
-      response.body &&
-      typeof response.body === 'object'
-    ) {
+    if (isAppErrorResponse(response)) {
       return response
     }
   }