@lota-sdk/core 0.4.13 → 0.4.15

package/src/system-agents/delegated-agent-factory.ts

@@ -5,6 +5,7 @@ import { z } from 'zod'
 
 import type { ToolDefinition } from '../ai/definitions'
 import { aiLogger } from '../config/logger'
+import { ERROR_TAGS } from '../effect/errors'
 import { formatUtcPromptDate, nowDate } from '../utils/date-time'
 import { getErrorMessage } from '../utils/errors'
 import { isRecord } from '../utils/string'
@@ -12,6 +13,7 @@ import { assertSubstantiveAgentResult } from './agent-result'
 
 type AgentProviderOptions = ToolLoopAgentSettings['providerOptions']
 type AgentModel = LanguageModel | (() => LanguageModel)
+type AgentModelWithContext<TContext> = LanguageModel | ((context: TContext) => LanguageModel)
 
 interface DelegatedAgentDefinition {
   id: string
@@ -24,13 +26,26 @@ interface DelegatedAgentDefinition {
   maxSteps?: number
   maxOutputTokens?: number
   temperature?: number
+  runPromise: <A, E>(effect: Effect.Effect<A, E, never>, options?: { signal?: AbortSignal }) => Promise<A>
 }
 
-interface DelegatedAgentDefinitionWithContext<TContext> extends Omit<DelegatedAgentDefinition, 'tools'> {
+type DelegatedAgentRunPromise = <A, E>(
+  effect: Effect.Effect<A, E, never>,
+  options?: { signal?: AbortSignal },
+) => Promise<A>
+
+interface DelegatedAgentDefinitionWithContext<TContext> extends Omit<
+  DelegatedAgentDefinition,
+  'tools' | 'model' | 'runPromise'
+> {
+  model: AgentModelWithContext<TContext>
   createTools: (context: TContext) => ToolSet
+  /** Pull runPromise off the caller's context so each tool invocation carries
+   * its own runtime binding rather than closing over a boot-time one. */
+  getRunPromise: (context: TContext) => DelegatedAgentRunPromise
 }
 
-class DelegatedAgentError extends Schema.TaggedErrorClass<DelegatedAgentError>()('DelegatedAgentError', {
+class DelegatedAgentError extends Schema.TaggedErrorClass<DelegatedAgentError>()(ERROR_TAGS.DelegatedAgentError, {
   stage: Schema.Literals(['generate', 'validate', 'follow-up-generate', 'follow-up-validate']),
   label: Schema.String,
   message: Schema.String,
@@ -49,6 +64,13 @@ function resolveAgentModel(model: AgentModel): LanguageModel {
   return typeof model === 'function' ? model() : model
 }
 
+function resolveAgentModelWithContext<TContext>(
+  model: AgentModelWithContext<TContext>,
+  context: TContext,
+): LanguageModel {
+  return typeof model === 'function' ? (model as (ctx: TContext) => LanguageModel)(context) : model
+}
+
 function buildCurrentDateContext(now = nowDate()): string {
   return [`Today is ${formatUtcPromptDate(now)}.`, 'Use this exact date for any recency reasoning.'].join(' ')
 }
@@ -229,7 +251,7 @@ export function createDelegatedAgentTool(definition: DelegatedAgentDefinition):
         description: definition.description,
         inputSchema: z.object({ task: z.string().min(1) }),
         execute: ({ task }: { task: string }, { abortSignal }) =>
-          Effect.runPromise(
+          definition.runPromise(
             Effect.gen(function* () {
               const agentTools = definition.tools
               const createAgent = () =>
@@ -268,6 +290,7 @@ export function createDelegatedAgentTool(definition: DelegatedAgentDefinition):
                 }),
               }
             }),
+            abortSignal ? { signal: abortSignal } : undefined,
           ),
       }),
   } as const satisfies ToolDefinition<void>
@@ -286,13 +309,13 @@ export function createDelegatedAgentToolWithContext<TContext>(
         description: definition.description,
         inputSchema: z.object({ task: z.string().min(1) }),
         execute: ({ task }: { task: string }, { abortSignal }) =>
-          Effect.runPromise(
+          definition.getRunPromise(context)(
             Effect.gen(function* () {
               const agentTools = definition.createTools(context)
               const createAgent = () =>
                 new ToolLoopAgent({
                   id: definition.id,
-                  model: resolveAgentModel(definition.model),
+                  model: resolveAgentModelWithContext(definition.model, context),
                   ...(definition.providerOptions ? { providerOptions: definition.providerOptions } : {}),
                   ...(definition.headers ? { headers: definition.headers } : {}),
                   instructions: buildDelegatedAgentInstructions(definition.instructions, agentTools),
@@ -304,7 +327,7 @@ export function createDelegatedAgentToolWithContext<TContext>(
                 })
               const synthesize = (prompt: string, abortSignal?: AbortSignal) =>
                 generateText({
-                  model: resolveAgentModel(definition.model),
+                  model: resolveAgentModelWithContext(definition.model, context),
                   ...(definition.providerOptions ? { providerOptions: definition.providerOptions } : {}),
                   ...(definition.headers ? { headers: definition.headers } : {}),
                   system: `${definition.instructions.trim()}\n\nReturn a complete final markdown answer using only the provided research data. Do not call tools.`,
@@ -325,6 +348,7 @@ export function createDelegatedAgentToolWithContext<TContext>(
                 }),
               }
             }),
+            abortSignal ? { signal: abortSignal } : undefined,
           ),
       }),
   } as const satisfies ToolDefinition<TContext>

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

@@ -1,7 +1,7 @@
 import type { CreateHelperToolLoopAgentOptions } from '@lota-sdk/shared'
 import { ToolLoopAgent } from 'ai'
 
-import { aiGatewayChatModel } from '../ai-gateway/ai-gateway'
+import type { AiGatewayModels } from '../ai-gateway/ai-gateway'
 import { buildAiGatewayDirectCacheHeaders } from '../ai-gateway/cache-headers'
 import {
   OPENROUTER_LOW_REASONING_PROVIDER_OPTIONS,
@@ -29,12 +29,13 @@ Set every item.relevance as a string; use empty string when no reason is needed.
 </output>
 </agent-instructions>`
 
-export function createMemoryRerankerAgent(options: CreateHelperToolLoopAgentOptions) {
-  return new ToolLoopAgent({
-    id: 'memory-reranker',
-    model: aiGatewayChatModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
-    headers: buildAiGatewayDirectCacheHeaders('lota-sdk'),
-    providerOptions: OPENROUTER_LOW_REASONING_PROVIDER_OPTIONS,
-    ...resolveHelperAgentOptions(options),
-  })
+export function makeMemoryRerankerAgentFactory(models: AiGatewayModels) {
+  return (options: CreateHelperToolLoopAgentOptions) =>
+    new ToolLoopAgent({
+      id: 'memory-reranker',
+      model: models.chatModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
+      headers: buildAiGatewayDirectCacheHeaders('lota-sdk'),
+      providerOptions: OPENROUTER_LOW_REASONING_PROVIDER_OPTIONS,
+      ...resolveHelperAgentOptions(options),
+    })
 }

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

@@ -1,7 +1,7 @@
 import type { CreateHelperToolLoopAgentOptions } from '@lota-sdk/shared'
 import { ToolLoopAgent } from 'ai'
 
-import { aiGatewayChatModel } from '../ai-gateway/ai-gateway'
+import type { AiGatewayModels } from '../ai-gateway/ai-gateway'
 import { buildAiGatewayDirectCacheHeaders } from '../ai-gateway/cache-headers'
 import {
   OPENROUTER_STRUCTURED_HELPER_MODEL_ID,
@@ -49,12 +49,13 @@ Return only the schema fields with no extra formatting.
 </format>
 </agent-instructions>`
 
-export function createOrgMemoryAgent(options: CreateHelperToolLoopAgentOptions) {
-  return new ToolLoopAgent({
-    id: 'org-memory',
-    model: aiGatewayChatModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
-    headers: buildAiGatewayDirectCacheHeaders('lota-sdk'),
-    providerOptions: OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
-    ...resolveHelperAgentOptions(options),
-  })
+export function makeOrgMemoryAgentFactory(models: AiGatewayModels) {
+  return (options: CreateHelperToolLoopAgentOptions) =>
+    new ToolLoopAgent({
+      id: 'org-memory',
+      model: models.chatModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
+      headers: buildAiGatewayDirectCacheHeaders('lota-sdk'),
+      providerOptions: OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
+      ...resolveHelperAgentOptions(options),
+    })
 }

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

@@ -1,7 +1,7 @@
 import type { CreateHelperToolLoopAgentOptions } from '@lota-sdk/shared'
 import { ToolLoopAgent } from 'ai'
 
-import { aiGatewayChatModel } from '../ai-gateway/ai-gateway'
+import type { AiGatewayModels } from '../ai-gateway/ai-gateway'
 import { buildAiGatewayDirectCacheHeaders } from '../ai-gateway/cache-headers'
 import type { ResolvedAgentConfig } from '../config/agent-defaults'
 import {
@@ -76,18 +76,16 @@ Return only the title text. No quotes, labels, JSON, markdown, or explanation.
 </output>
 </agent-instructions>`
 
-export function createRecentActivityTitleRefinerAgent(
-  agentConfig: ResolvedAgentConfig,
-  options: CreateHelperToolLoopAgentOptions,
-) {
-  return new ToolLoopAgent({
-    id: 'recent-activity-title-refiner',
-    model: aiGatewayChatModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
-    headers: buildAiGatewayDirectCacheHeaders('lota-sdk'),
-    providerOptions: OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
-    ...resolveHelperAgentOptions(options, {
-      instructions: buildRecentActivityTitleRefinerPrompt(agentConfig),
-      maxOutputTokens: RECENT_ACTIVITY_TITLE_MAX_TOKENS,
-    }),
-  })
+export function makeRecentActivityTitleRefinerAgentFactory(models: AiGatewayModels, agentConfig: ResolvedAgentConfig) {
+  return (options: CreateHelperToolLoopAgentOptions) =>
+    new ToolLoopAgent({
+      id: 'recent-activity-title-refiner',
+      model: models.chatModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
+      headers: buildAiGatewayDirectCacheHeaders('lota-sdk'),
+      providerOptions: OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
+      ...resolveHelperAgentOptions(options, {
+        instructions: buildRecentActivityTitleRefinerPrompt(agentConfig),
+        maxOutputTokens: RECENT_ACTIVITY_TITLE_MAX_TOKENS,
+      }),
+    })
 }

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

@@ -1,7 +1,7 @@
 import type { CreateHelperToolLoopAgentOptions } from '@lota-sdk/shared'
 import { ToolLoopAgent } from 'ai'
 
-import { aiGatewayChatModel } from '../ai-gateway/ai-gateway'
+import type { AiGatewayModels } from '../ai-gateway/ai-gateway'
 import { buildAiGatewayDirectCacheHeaders } from '../ai-gateway/cache-headers'
 import {
   OPENROUTER_STRUCTURED_HELPER_MODEL_ID,
@@ -24,15 +24,16 @@ Synthesize an updated workspace profile summary and durable memory facts from co
 </rules>
 </agent-instructions>`
 
-export function createRegularChatMemoryDigestAgent(options: CreateHelperToolLoopAgentOptions) {
-  return new ToolLoopAgent({
-    id: 'regular-chat-memory-digest',
-    model: aiGatewayChatModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
-    headers: buildAiGatewayDirectCacheHeaders('lota-sdk'),
-    providerOptions: OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
-    ...resolveHelperAgentOptions(options, {
-      instructions: regularChatMemoryDigestPrompt,
-      maxOutputTokens: REGULAR_CHAT_MEMORY_DIGEST_MAX_TOKENS,
-    }),
-  })
+export function makeRegularChatMemoryDigestAgentFactory(models: AiGatewayModels) {
+  return (options: CreateHelperToolLoopAgentOptions) =>
+    new ToolLoopAgent({
+      id: 'regular-chat-memory-digest',
+      model: models.chatModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
+      headers: buildAiGatewayDirectCacheHeaders('lota-sdk'),
+      providerOptions: OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
+      ...resolveHelperAgentOptions(options, {
+        instructions: regularChatMemoryDigestPrompt,
+        maxOutputTokens: REGULAR_CHAT_MEMORY_DIGEST_MAX_TOKENS,
+      }),
+    })
 }

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

@@ -2,7 +2,7 @@ import type { CreateHelperToolLoopAgentOptions } from '@lota-sdk/shared'
 import { ToolLoopAgent } from 'ai'
 import { z } from 'zod'
 
-import { aiGatewayChatModel } from '../ai-gateway/ai-gateway'
+import type { AiGatewayModels } from '../ai-gateway/ai-gateway'
 import { buildAiGatewayDirectCacheHeaders } from '../ai-gateway/cache-headers'
 import {
   OPENROUTER_STRUCTURED_HELPER_MODEL_ID,
@@ -42,15 +42,16 @@ export const SkillExtractionOutputSchema = z.object({ candidates: z.array(SkillC
 
 export type SkillCandidate = z.infer<typeof SkillCandidateSchema>
 
-export function createSkillExtractorAgent(options: CreateHelperToolLoopAgentOptions) {
-  return new ToolLoopAgent({
-    id: 'skill-extractor',
-    model: aiGatewayChatModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
-    headers: buildAiGatewayDirectCacheHeaders('lota-sdk'),
-    providerOptions: OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
-    ...resolveHelperAgentOptions(options, {
-      instructions: skillExtractorPrompt,
-      maxOutputTokens: SKILL_EXTRACTOR_MAX_TOKENS,
-    }),
-  })
+export function makeSkillExtractorAgentFactory(models: AiGatewayModels) {
+  return (options: CreateHelperToolLoopAgentOptions) =>
+    new ToolLoopAgent({
+      id: 'skill-extractor',
+      model: models.chatModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
+      headers: buildAiGatewayDirectCacheHeaders('lota-sdk'),
+      providerOptions: OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
+      ...resolveHelperAgentOptions(options, {
+        instructions: skillExtractorPrompt,
+        maxOutputTokens: SKILL_EXTRACTOR_MAX_TOKENS,
+      }),
+    })
 }

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

@@ -2,7 +2,7 @@ import type { CreateHelperToolLoopAgentOptions } from '@lota-sdk/shared'
 import { ToolLoopAgent } from 'ai'
 import { z } from 'zod'
 
-import { aiGatewayChatModel } from '../ai-gateway/ai-gateway'
+import type { AiGatewayModels } from '../ai-gateway/ai-gateway'
 import { buildAiGatewayDirectCacheHeaders } from '../ai-gateway/cache-headers'
 import {
   OPENROUTER_STRUCTURED_HELPER_MODEL_ID,
@@ -66,15 +66,16 @@ export const SkillManagerOutputSchema = z.object({
   mergedSkill: MergedSkillSchema.optional(),
 })
 
-export function createSkillManagerAgent(options: CreateHelperToolLoopAgentOptions) {
-  return new ToolLoopAgent({
-    id: 'skill-manager',
-    model: aiGatewayChatModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
-    headers: buildAiGatewayDirectCacheHeaders('lota-sdk'),
-    providerOptions: OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
-    ...resolveHelperAgentOptions(options, {
-      instructions: skillManagerPrompt,
-      maxOutputTokens: SKILL_MANAGER_MAX_TOKENS,
-    }),
-  })
+export function makeSkillManagerAgentFactory(models: AiGatewayModels) {
+  return (options: CreateHelperToolLoopAgentOptions) =>
+    new ToolLoopAgent({
+      id: 'skill-manager',
+      model: models.chatModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
+      headers: buildAiGatewayDirectCacheHeaders('lota-sdk'),
+      providerOptions: OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
+      ...resolveHelperAgentOptions(options, {
+        instructions: skillManagerPrompt,
+        maxOutputTokens: SKILL_MANAGER_MAX_TOKENS,
+      }),
+    })
 }

package/src/system-agents/thread-router.agent.ts

@@ -2,12 +2,12 @@ import { generateObject } from 'ai'
 import { Effect } from 'effect'
 import { z } from 'zod'
 
-import { aiGatewayChatModel } from '../ai-gateway/ai-gateway'
+import type { AiGatewayModels } from '../ai-gateway/ai-gateway'
 import { buildAiGatewayDirectCacheHeaders } from '../ai-gateway/cache-headers'
 import type { ResolvedAgentConfig } from '../config/agent-defaults'
 import { chatLogger } from '../config/logger'
 import type { ValidationError } from '../effect/errors'
-import { AiGenerationError } from '../effect/errors'
+import { ERROR_TAGS, AiGenerationError } from '../effect/errors'
 import { zodParse } from '../effect/zod'
 
 const TriageResultSchema = z.object({ agentId: z.string(), routingContext: z.string() })
@@ -170,19 +170,19 @@ function toRouterGenerationError(label: 'triage' | 'check', error: unknown): AiG
 
 function generateRouterObjectEffect<TSchema extends z.ZodTypeAny>(params: {
   agentConfig: ResolvedAgentConfig
+  aiGatewayModels: AiGatewayModels
   schema: TSchema
   system: string
   prompt: string
   label: 'triage' | 'check'
 }): Effect.Effect<z.infer<TSchema> | null, never> {
-  const modelId = params.agentConfig.routerModelId ?? 'openrouter/openai/gpt-5.4-nano'
+  const modelId = params.agentConfig.routerModelId ?? 'gpt-5.4-nano'
 
   return Effect.tryPromise({
     try: () =>
       generateObject({
-        model: aiGatewayChatModel(modelId),
+        model: params.aiGatewayModels.chatModel(modelId),
         headers: buildAiGatewayDirectCacheHeaders('lota-sdk'),
-        providerOptions: { openai: { reasoningEffort: 'low' } },
         schema: params.schema,
         system: params.system,
         prompt: params.prompt,
@@ -201,12 +201,12 @@ function generateRouterObjectEffect<TSchema extends z.ZodTypeAny>(params: {
     ),
     Effect.flatMap(({ object }) => zodParse(params.schema, object)),
     Effect.catchTags({
-      AiGenerationError: (error: AiGenerationError) =>
+      [ERROR_TAGS.AiGenerationError]: (error: AiGenerationError) =>
         Effect.sync(() => {
           chatLogger.error`[thread-router] ${params.label} failed: ${error.message}`
           return null
         }),
-      ValidationError: (error: ValidationError) =>
+      [ERROR_TAGS.ValidationError]: (error: ValidationError) =>
         Effect.sync(() => {
           chatLogger.error`[thread-router] ${params.label} failed: ${error.message}`
           return null
@@ -217,6 +217,7 @@ function generateRouterObjectEffect<TSchema extends z.ZodTypeAny>(params: {
 
 export function triageThreadMessage(params: {
   agentConfig: ResolvedAgentConfig
+  aiGatewayModels: AiGatewayModels
   threadTitle: string
   members: readonly string[]
   messageText: string
@@ -254,6 +255,7 @@ export function triageThreadMessage(params: {
 
       const parsed = yield* generateRouterObjectEffect({
         agentConfig: params.agentConfig,
+        aiGatewayModels: params.aiGatewayModels,
         schema: TriageResultSchema,
         system: TRIAGE_SYSTEM_PROMPT,
         prompt,
@@ -280,6 +282,7 @@ export function triageThreadMessage(params: {
 
 export function checkForNextAgent(params: {
   agentConfig: ResolvedAgentConfig
+  aiGatewayModels: AiGatewayModels
   threadTitle: string
   members: readonly string[]
   messageText: string
@@ -323,6 +326,7 @@ export function checkForNextAgent(params: {
 
       const parsed = yield* generateRouterObjectEffect({
         agentConfig: params.agentConfig,
+        aiGatewayModels: params.aiGatewayModels,
         schema: CheckResultObjectSchema,
         system: CHECK_SYSTEM_PROMPT,
         prompt,

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

@@ -1,7 +1,7 @@
 import type { CreateHelperToolLoopAgentOptions } from '@lota-sdk/shared'
 import { ToolLoopAgent } from 'ai'
 
-import { aiGatewayChatModel } from '../ai-gateway/ai-gateway'
+import type { AiGatewayModels } from '../ai-gateway/ai-gateway'
 import { buildAiGatewayDirectCacheHeaders } from '../ai-gateway/cache-headers'
 import {
   OPENROUTER_FAST_REASONING_MODEL_ID,
@@ -30,15 +30,16 @@ Return only the title text. No quotes, no labels, no explanation.
 </output-format>
 </agent-instructions>`
 
-export function createThreadTitleGeneratorAgent(options: CreateHelperToolLoopAgentOptions) {
-  return new ToolLoopAgent({
-    id: 'thread-title-generator',
-    model: aiGatewayChatModel(OPENROUTER_FAST_REASONING_MODEL_ID),
-    headers: buildAiGatewayDirectCacheHeaders('lota-sdk'),
-    providerOptions: OPENROUTER_MINIMAL_REASONING_PROVIDER_OPTIONS,
-    ...resolveHelperAgentOptions(options, {
-      instructions: THREAD_TITLE_GENERATOR_PROMPT,
-      maxOutputTokens: THREAD_TITLE_MAX_TOKENS,
-    }),
-  })
+export function makeThreadTitleGeneratorAgentFactory(models: AiGatewayModels) {
+  return (options: CreateHelperToolLoopAgentOptions) =>
+    new ToolLoopAgent({
+      id: 'thread-title-generator',
+      model: models.chatModel(OPENROUTER_FAST_REASONING_MODEL_ID),
+      headers: buildAiGatewayDirectCacheHeaders('lota-sdk'),
+      providerOptions: OPENROUTER_MINIMAL_REASONING_PROVIDER_OPTIONS,
+      ...resolveHelperAgentOptions(options, {
+        instructions: THREAD_TITLE_GENERATOR_PROMPT,
+        maxOutputTokens: THREAD_TITLE_MAX_TOKENS,
+      }),
+    })
 }

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

@@ -12,6 +12,7 @@ import { toRecord, WEB_TOOL_TIMEOUT_MS } from './web-tool-shared'
 
 export interface FetchWebpageToolContext {
   firecrawl: Firecrawl
+  runPromise: <A, E>(effect: Effect.Effect<A, E, never>, options?: { signal?: AbortSignal }) => Promise<A>
 }
 
 class FetchWebpageToolError extends Schema.TaggedErrorClass<FetchWebpageToolError>()(
@@ -102,7 +103,7 @@ function buildFetchCitations(url: string, document: unknown): WebCitation[] {
 
 export const fetchWebpageTool = {
   name: 'fetchWebpage',
-  create: ({ firecrawl }: FetchWebpageToolContext) =>
+  create: ({ firecrawl, runPromise }: FetchWebpageToolContext) =>
     tool({
       description: 'Retrieve and parse a single webpage.',
       inputSchema: z
@@ -113,18 +114,16 @@ export const fetchWebpageTool = {
           maxAge: z.number().int().min(1).optional(),
         })
         .strict(),
-      execute: ({
-        url,
-        formats,
-        onlyMainContent,
-        maxAge,
-      }: {
-        url: string
-        formats?: z.infer<typeof FormatSchema>[]
-        onlyMainContent?: boolean
-        maxAge?: number
-      }) =>
-        Effect.runPromise(
+      execute: (
+        {
+          url,
+          formats,
+          onlyMainContent,
+          maxAge,
+        }: { url: string; formats?: z.infer<typeof FormatSchema>[]; onlyMainContent?: boolean; maxAge?: number },
+        { abortSignal }: { abortSignal?: AbortSignal } = {},
+      ) =>
+        runPromise(
           Effect.gen(function* () {
             const result = yield* Effect.tryPromise({
               try: () =>
@@ -141,6 +140,7 @@ export const fetchWebpageTool = {
             })
             return { url, document: summarizeDocument(url, result), citations: buildFetchCitations(url, result) }
           }).pipe(Effect.withSpan('tool.fetchWebpage.execute')),
+          abortSignal ? { signal: abortSignal } : undefined,
         ),
     }),
 } as const satisfies ToolDefinition<FetchWebpageToolContext>

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

@@ -18,12 +18,14 @@ export function createMemoryBlockTool({
   threadId,
   agentLabel,
   threadService,
+  runPromise,
   getCurrentBlock,
   onAppend,
 }: {
   threadId: RecordIdRef
   agentLabel: string
   threadService: MemoryBlockThreadService
+  runPromise: <A, E>(effect: Effect.Effect<A, E, never>) => Promise<A>
   getCurrentBlock?: () => string
   onAppend?: (value: string) => void
 }) {
@@ -48,7 +50,7 @@ export function createMemoryBlockTool({
 
       void safeEnqueue(
         () =>
-          Effect.runPromise(
+          runPromise(
             Effect.gen(function* () {
               const updated = yield* threadService.appendMemoryBlock(threadId, prepared.formatted)
               onAppend?.(updated)

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

@@ -21,14 +21,15 @@ export function createPlanApprovalTool(params: {
   threadId: RecordIdRef
   actorId: string
   executionPlanService: PlanApprovalExecutionPlanService
+  runPromise: <A, E>(effect: Effect.Effect<A, E, never>, options?: { signal?: AbortSignal }) => Promise<A>
 }) {
   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: (input) =>
-      Effect.runPromise(
+    execute: (input, { abortSignal }: { abortSignal?: AbortSignal } = {}) =>
+      params.runPromise(
         Effect.gen(function* () {
           switch (input.action) {
             case 'approve': {
@@ -71,6 +72,7 @@ export function createPlanApprovalTool(params: {
             }
           }
         }),
+        abortSignal ? { signal: abortSignal } : undefined,
       ),
   })
 }

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

@@ -3,6 +3,7 @@ import { Schema, Effect } from 'effect'
 import { z } from 'zod'
 
 import type { ToolDefinition } from '../ai/definitions'
+import { ERROR_TAGS } from '../effect/errors'
 import type { makeAttachmentService } from '../services/attachment.service'
 import type { ReadableUploadMetadata } from '../storage/attachment-types'
 
@@ -15,6 +16,7 @@ export interface ReadFilePartsToolContext {
   userId: string
   uploads: ReadableUploadMetadata[]
   attachmentService: ReadFilePartsAttachmentService
+  runPromise: <A, E>(effect: Effect.Effect<A, E, never>, options?: { signal?: AbortSignal }) => Promise<A>
 }
 
 function toUploadSummary(upload: ReadableUploadMetadata) {
@@ -26,7 +28,7 @@ function toUploadSummary(upload: ReadableUploadMetadata) {
   }
 }
 
-class ReadFilePartsError extends Schema.TaggedErrorClass<ReadFilePartsError>()('ReadFilePartsError', {
+class ReadFilePartsError extends Schema.TaggedErrorClass<ReadFilePartsError>()(ERROR_TAGS.ReadFilePartsError, {
   message: Schema.String,
 }) {}
 
@@ -47,15 +49,18 @@ function resolveUploadTargetEffect(params: {
 
 export const readFilePartsTool = {
   name: 'readFileParts',
-  create: ({ orgId, userId, uploads, attachmentService }: ReadFilePartsToolContext) =>
+  create: ({ orgId, userId, uploads, attachmentService, runPromise }: 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: ({ storageKey, part }: { storageKey?: string; part?: number }) =>
-        Effect.runPromise(
+      execute: (
+        { storageKey, part }: { storageKey?: string; part?: number },
+        { abortSignal }: { abortSignal?: AbortSignal } = {},
+      ) =>
+        runPromise(
           Effect.gen(function* () {
             const availableUploads = uploads.map(toUploadSummary)
             const selected = yield* resolveUploadTargetEffect({ uploads, storageKey })
@@ -86,6 +91,7 @@ export const readFilePartsTool = {
 
             return { availableUploads, selectedUpload: toUploadSummary(selected), ...parts }
           }),
+          abortSignal ? { signal: abortSignal } : undefined,
         ),
     }),
 } as const satisfies ToolDefinition<ReadFilePartsToolContext>

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

@@ -24,10 +24,12 @@ export function createRememberMemoryTool({
   orgId,
   agentName,
   memoryService,
+  runPromise,
 }: {
   orgId: RecordIdRef
   agentName: string
   memoryService: RememberMemoryService
+  runPromise: <A, E>(effect: Effect.Effect<A, E, never>) => Promise<A>
 }) {
   return tool({
     description:
@@ -42,7 +44,7 @@ export function createRememberMemoryTool({
       const orgIdString = recordIdToString(orgId, TABLES.ORGANIZATION)
       void safeEnqueue(
         () =>
-          Effect.runPromise(
+          runPromise(
             Effect.gen(function* () {
               const assessment = yield* memoryService.assessMemoryCandidate({ orgId: orgIdString, content: trimmed })
               if (!assessment) {