@lota-sdk/core 0.4.7 → 0.4.9

package/src/runtime/runtime-config.ts

@@ -1,10 +1,15 @@
 import type { ToolSet } from 'ai'
+import { Config, ConfigProvider, Effect, Option, Redacted } from 'effect'
 import { z } from 'zod'
 
 import type { CoreThreadProfile } from '../config/agent-defaults'
 import type { AgentFactory, AgentRuntimeConfigProvider, AgentToolBuilder } from '../config/agent-types'
+import { DEFAULT_AI_GATEWAY_URL } from '../config/constants'
+import { OPENROUTER_FAST_RERANK_MODEL_ID } from '../config/model-constants'
 import type { LotaThreadConfig, ThreadBootstrapWelcomeConfig } from '../config/thread-defaults'
 import type { RecordIdRef } from '../db/record-id'
+import { getCurrentRuntime } from '../effect/runtime-ref'
+import { RuntimeConfigServiceTag } from '../effect/services'
 import type { NotificationService } from '../services/notification.service'
 import { isRecord } from '../utils/string'
 import type { GraphDesigner } from './graph-designer'
@@ -13,6 +18,11 @@ import type { LotaRuntimeAdapters, LotaRuntimeTurnHooks } from './runtime-extens
 import type { LotaRuntimeWorkerExtensions } from './runtime-worker-registry'
 
 const logLevelValues = ['trace', 'debug', 'info', 'warning', 'error', 'fatal'] as const
+const nonEmptyStringSchema = z.string().trim().min(1)
+const stringRecordSchema = z.record(z.string(), z.string())
+function objectRecordSchema<T extends object>() {
+  return z.custom<T>(isRecord)
+}
 
 function isStringOrUrl(value: unknown): value is string | URL {
   return typeof value === 'string' || value instanceof URL
@@ -22,26 +32,14 @@ function isFunction(value: unknown): value is (...args: unknown[]) => unknown {
   return typeof value === 'function'
 }
 
-function isStringRecord(value: unknown): value is Record<string, string> {
-  return isRecord(value) && Object.values(value).every((entry) => typeof entry === 'string')
+function isToolSet(value: unknown): value is ToolSet {
+  return isRecord(value)
 }
 
 function isAgentFactoryRegistry(value: unknown): value is AgentFactory {
   return isRecord(value) && Object.values(value).every((entry) => typeof entry === 'function')
 }
 
-function isPluginRuntimeRecord(value: unknown): value is Record<string, LotaPlugin> {
-  return isRecord(value)
-}
-
-function isSystemExecutorRecord(value: unknown): value is Record<string, SystemNodeExecutor> {
-  return isRecord(value)
-}
-
-function isToolProviderRecord(value: unknown): value is Record<string, unknown> {
-  return isRecord(value)
-}
-
 function isNotificationService(value: unknown): value is NotificationService {
   return isRecord(value) && isFunction(value.notify) && isFunction(value.remind) && isFunction(value.escalate)
 }
@@ -145,7 +143,7 @@ function isSocialChatConfig(value: unknown): value is LotaRuntimeSocialChatConfi
 }
 
 const threadBootstrapWelcomeConfigSchema = z.object({
-  defaultAgentId: z.string().trim().min(1),
+  defaultAgentId: nonEmptyStringSchema,
   buildMessageText: z.custom<ThreadBootstrapWelcomeConfig['buildMessageText']>(isFunction, {
     error: 'onboardingWelcome.buildMessageText must be a function',
   }),
@@ -155,9 +153,9 @@ const threadConfigSchema = z
   .object({
     bootstrap: z
       .object({
-        onboardingDefaultAgents: z.array(z.string().trim().min(1)).optional(),
-        completedDefaultAgents: z.array(z.string().trim().min(1)).optional(),
-        threadTypesAfterOnboarding: z.array(z.string().trim().min(1)).optional(),
+        onboardingDefaultAgents: z.array(nonEmptyStringSchema).optional(),
+        completedDefaultAgents: z.array(nonEmptyStringSchema).optional(),
+        threadTypesAfterOnboarding: z.array(nonEmptyStringSchema).optional(),
         ensureDefaultGroupOnCompleted: z.boolean().optional(),
         onboardingWelcome: threadBootstrapWelcomeConfigSchema.optional(),
       })
@@ -168,19 +166,13 @@ const threadConfigSchema = z
 
 const agentsConfigSchema = z
   .object({
-    roster: z.array(z.string().trim().min(1)).min(1),
-    leadAgentId: z.string().trim().min(1),
-    displayNames: z.custom<Record<string, string>>(isStringRecord, {
-      error: 'agents.displayNames must be a string record',
-    }),
-    shortDisplayNames: z
-      .custom<Record<string, string>>(isStringRecord, { error: 'agents.shortDisplayNames must be a string record' })
-      .optional(),
-    descriptions: z
-      .custom<Record<string, string>>(isStringRecord, { error: 'agents.descriptions must be a string record' })
-      .optional(),
-    routerModelId: z.string().trim().min(1).optional(),
-    teamConsultParticipants: z.array(z.string().trim().min(1)),
+    roster: z.array(nonEmptyStringSchema).min(1),
+    leadAgentId: nonEmptyStringSchema,
+    displayNames: stringRecordSchema,
+    shortDisplayNames: stringRecordSchema.optional(),
+    descriptions: stringRecordSchema.optional(),
+    routerModelId: nonEmptyStringSchema.optional(),
+    teamConsultParticipants: z.array(nonEmptyStringSchema),
     getCoreThreadProfile: z
       .custom<(coreType: string) => CoreThreadProfile>(isFunction, {
         error: 'agents.getCoreThreadProfile must be a function',
@@ -216,25 +208,30 @@ const agentsConfigSchema = z
     }
   })
 
+export const MemoryRerankerStrategySchema = z.enum(['helper-model', 'rerank'])
+export type MemoryRerankerStrategy = z.infer<typeof MemoryRerankerStrategySchema>
+
 export const LotaRuntimeConfigSchema = z.object({
   database: z.object({
-    url: z.string().trim().min(1),
-    namespace: z.string().trim().min(1),
-    username: z.string().trim().min(1),
-    password: z.string().trim().min(1),
+    url: nonEmptyStringSchema,
+    namespace: nonEmptyStringSchema,
+    username: nonEmptyStringSchema,
+    password: nonEmptyStringSchema,
   }),
-  redis: z.object({ url: z.string().trim().min(1) }),
+  redis: z.object({ url: nonEmptyStringSchema }),
   aiGateway: z.object({
-    url: z.string().trim().min(1),
-    key: z.string().trim().min(1),
-    embeddingModel: z.string().trim().min(1).default('openai/text-embedding-3-small'),
+    url: nonEmptyStringSchema,
+    key: nonEmptyStringSchema,
+    embeddingModel: nonEmptyStringSchema.default('openai/text-embedding-3-small'),
+    openRouterApiKey: nonEmptyStringSchema.optional(),
+    maxConcurrency: z.coerce.number().int().positive().default(8),
   }),
   s3: z.object({
-    endpoint: z.string().trim().min(1),
-    bucket: z.string().trim().min(1),
-    region: z.string().trim().min(1).default('garage'),
-    accessKeyId: z.string().trim().min(1),
-    secretAccessKey: z.string().trim().min(1),
+    endpoint: nonEmptyStringSchema,
+    bucket: nonEmptyStringSchema,
+    region: nonEmptyStringSchema.default('garage'),
+    accessKeyId: nonEmptyStringSchema,
+    secretAccessKey: nonEmptyStringSchema,
     attachmentUrlExpiresIn: z.coerce.number().positive().default(1800),
   }),
   firecrawl: z.object({
@@ -250,20 +247,36 @@ export const LotaRuntimeConfigSchema = z.object({
     .object({
       searchK: z.coerce.number().int().positive().default(6),
       embeddingCacheTtlSeconds: z.coerce.number().int().positive().default(7200),
+      rerankerStrategy: MemoryRerankerStrategySchema.default('rerank'),
+      rerankerModelId: z.string().trim().min(1).default(OPENROUTER_FAST_RERANK_MODEL_ID),
     })
-    .default({ searchK: 6, embeddingCacheTtlSeconds: 7200 }),
+    .default({
+      searchK: 6,
+      embeddingCacheTtlSeconds: 7200,
+      rerankerStrategy: 'rerank',
+      rerankerModelId: OPENROUTER_FAST_RERANK_MODEL_ID,
+    }),
   threads: threadConfigSchema.default({}),
   agents: agentsConfigSchema,
-  toolProviders: z.custom<Record<string, unknown>>(isToolProviderRecord).optional(),
+  toolProviders: z.custom<ToolSet>(isToolSet, { error: 'toolProviders must be a tool registry object' }).optional(),
   extraSchemaFiles: z.array(z.custom<string | URL>(isStringOrUrl)).optional(),
   extraWorkers: z.custom<LotaRuntimeWorkerExtensions>(isWorkerExtensionRecord).optional(),
-  pluginRuntime: z.custom<Record<string, LotaPlugin>>(isPluginRuntimeRecord).optional(),
-  systemExecutors: z.custom<Record<string, SystemNodeExecutor>>(isSystemExecutorRecord).optional(),
+  pluginRuntime: objectRecordSchema<Record<string, LotaPlugin>>().optional(),
+  systemExecutors: objectRecordSchema<Record<string, SystemNodeExecutor>>().optional(),
   notificationService: z.custom<NotificationService>(isNotificationService).optional(),
-  runtimeAdapters: z.custom<LotaRuntimeAdapters>(isRecord).optional(),
-  turnHooks: z.custom<LotaRuntimeTurnHooks>(isRecord).optional(),
+  runtimeAdapters: objectRecordSchema<LotaRuntimeAdapters>().optional(),
+  turnHooks: objectRecordSchema<LotaRuntimeTurnHooks>().optional(),
   graphDesigner: z.custom<GraphDesigner>(isGraphDesigner).optional(),
   socialChat: z.custom<LotaRuntimeSocialChatConfig>(isSocialChatConfig).optional(),
+  observability: z
+    .object({
+      otlpBaseUrl: nonEmptyStringSchema.optional(),
+      otlpHeaders: stringRecordSchema.optional(),
+      serviceName: nonEmptyStringSchema.default('lota-sdk'),
+      serviceVersion: nonEmptyStringSchema.optional(),
+      devToolsUrl: nonEmptyStringSchema.optional(),
+    })
+    .default({ serviceName: 'lota-sdk' }),
 })
 
 export type LotaRuntimeConfig = z.input<typeof LotaRuntimeConfigSchema>
@@ -288,6 +301,8 @@ export const LOTA_RUNTIME_ENV_KEYS = Object.freeze([
   'AI_GATEWAY_URL',
   'AI_GATEWAY_KEY',
   'AI_EMBEDDING_MODEL',
+  'OPENROUTER_API_KEY',
+  'AI_GATEWAY_MAX_CONCURRENCY',
   'S3_ENDPOINT',
   'S3_BUCKET',
   'S3_REGION',
@@ -298,28 +313,117 @@ export const LOTA_RUNTIME_ENV_KEYS = Object.freeze([
   'FIRECRAWL_API_BASE_URL',
   'LOG_LEVEL',
   'MEMORY_SEARCH_K',
+  'MEMORY_RERANKER_STRATEGY',
+  'MEMORY_RERANKER_MODEL_ID',
+  'OTLP_BASE_URL',
+  'OTLP_SERVICE_NAME',
+  'OTLP_SERVICE_VERSION',
+  'DEVTOOLS_URL',
 ])
 
-let runtimeConfig: ResolvedLotaRuntimeConfig | null = null
-
 export function parseLotaRuntimeConfig(config: LotaRuntimeConfig): ResolvedLotaRuntimeConfig {
   return LotaRuntimeConfigSchema.parse(config)
 }
 
-export function configureRuntimeConfig(config: ResolvedLotaRuntimeConfig): void {
-  runtimeConfig = config
+export function parseWorkerBootstrapEnv(env: Record<string, string | undefined>): WorkerBootstrapEnv {
+  return WORKER_BOOTSTRAP_ENV_SCHEMA.parse(env)
 }
 
-export function getRuntimeConfig(): ResolvedLotaRuntimeConfig {
-  if (!runtimeConfig) {
-    throw new Error('Lota runtime config not configured. Call createLotaRuntime() first.')
-  }
+const runtimeEnvironmentConfig = Config.all({
+  surrealdbUrl: Config.string('SURREALDB_URL'),
+  surrealdbNamespace: Config.string('SURREALDB_NAMESPACE'),
+  surrealdbUser: Config.string('SURREALDB_USER'),
+  surrealdbPassword: Config.redacted('SURREALDB_PASSWORD'),
+  redisUrl: Config.string('REDIS_URL'),
+  aiGatewayUrl: Config.string('AI_GATEWAY_URL').pipe(Config.withDefault(DEFAULT_AI_GATEWAY_URL)),
+  aiGatewayKey: Config.redacted('AI_GATEWAY_KEY'),
+  aiEmbeddingModel: Config.string('AI_EMBEDDING_MODEL').pipe(Config.withDefault('openai/text-embedding-3-small')),
+  openRouterApiKey: Config.redacted('OPENROUTER_API_KEY').pipe(Config.option),
+  aiGatewayMaxConcurrency: Config.number('AI_GATEWAY_MAX_CONCURRENCY').pipe(Config.withDefault(8)),
+  s3Endpoint: Config.string('S3_ENDPOINT'),
+  s3Bucket: Config.string('S3_BUCKET'),
+  s3Region: Config.string('S3_REGION').pipe(Config.withDefault('garage')),
+  s3AccessKeyId: Config.redacted('S3_ACCESS_KEY_ID'),
+  s3SecretAccessKey: Config.redacted('S3_SECRET_ACCESS_KEY'),
+  attachmentUrlExpiresIn: Config.number('ATTACHMENT_URL_EXPIRES_IN').pipe(Config.withDefault(1800)),
+  firecrawlApiKey: Config.redacted('FIRECRAWL_API_KEY'),
+  firecrawlApiBaseUrl: Config.string('FIRECRAWL_API_BASE_URL').pipe(Config.option),
+  logLevel: Config.string('LOG_LEVEL').pipe(Config.withDefault('info')),
+  memorySearchK: Config.number('MEMORY_SEARCH_K').pipe(Config.withDefault(6)),
+  memoryRerankerStrategy: Config.string('MEMORY_RERANKER_STRATEGY').pipe(Config.withDefault('rerank')),
+  memoryRerankerModelId: Config.string('MEMORY_RERANKER_MODEL_ID').pipe(
+    Config.withDefault(OPENROUTER_FAST_RERANK_MODEL_ID),
+  ),
+  otlpBaseUrl: Config.string('OTLP_BASE_URL').pipe(Config.option),
+  otlpServiceName: Config.string('OTLP_SERVICE_NAME').pipe(Config.withDefault('lota-sdk')),
+  otlpServiceVersion: Config.string('OTLP_SERVICE_VERSION').pipe(Config.option),
+  devToolsUrl: Config.string('DEVTOOLS_URL').pipe(Config.option),
+})
 
-  return runtimeConfig
+export type LotaRuntimeEnvironmentOverrides = Omit<
+  LotaRuntimeConfig,
+  'database' | 'redis' | 'aiGateway' | 's3' | 'firecrawl' | 'logging' | 'memory'
+> & { logging?: LotaRuntimeConfig['logging']; memory?: LotaRuntimeConfig['memory'] }
+
+export function loadLotaRuntimeConfigFromEnv(
+  overrides: LotaRuntimeEnvironmentOverrides,
+  options: { configProvider?: ConfigProvider.ConfigProvider } = {},
+) {
+  return runtimeEnvironmentConfig
+    .parse(options.configProvider ?? ConfigProvider.fromEnv())
+    .pipe(
+      Effect.map((env) =>
+        parseLotaRuntimeConfig({
+          ...overrides,
+          database: {
+            url: env.surrealdbUrl,
+            namespace: env.surrealdbNamespace,
+            username: env.surrealdbUser,
+            password: Redacted.value(env.surrealdbPassword),
+          },
+          redis: { url: env.redisUrl },
+          aiGateway: {
+            url: env.aiGatewayUrl,
+            key: Redacted.value(env.aiGatewayKey),
+            embeddingModel: env.aiEmbeddingModel,
+            maxConcurrency: env.aiGatewayMaxConcurrency,
+            ...(Option.isSome(env.openRouterApiKey)
+              ? { openRouterApiKey: Redacted.value(env.openRouterApiKey.value) }
+              : {}),
+          },
+          s3: {
+            endpoint: env.s3Endpoint,
+            bucket: env.s3Bucket,
+            region: env.s3Region,
+            accessKeyId: Redacted.value(env.s3AccessKeyId),
+            secretAccessKey: Redacted.value(env.s3SecretAccessKey),
+            attachmentUrlExpiresIn: env.attachmentUrlExpiresIn,
+          },
+          firecrawl: {
+            apiKey: Redacted.value(env.firecrawlApiKey),
+            ...(Option.isSome(env.firecrawlApiBaseUrl) ? { apiBaseUrl: env.firecrawlApiBaseUrl.value } : {}),
+          },
+          logging: overrides.logging ?? { level: env.logLevel as (typeof logLevelValues)[number] },
+          memory: {
+            searchK: env.memorySearchK,
+            rerankerStrategy: env.memoryRerankerStrategy as MemoryRerankerStrategy,
+            rerankerModelId: env.memoryRerankerModelId,
+            ...overrides.memory,
+          },
+          observability: {
+            serviceName: env.otlpServiceName,
+            ...(Option.isSome(env.otlpBaseUrl) ? { otlpBaseUrl: env.otlpBaseUrl.value } : {}),
+            ...(Option.isSome(env.otlpServiceVersion) ? { serviceVersion: env.otlpServiceVersion.value } : {}),
+            ...(Option.isSome(env.devToolsUrl) ? { devToolsUrl: env.devToolsUrl.value } : {}),
+            ...overrides.observability,
+          },
+        }),
+      ),
+    )
 }
 
-export function parseWorkerBootstrapEnv(env: Record<string, string | undefined>): WorkerBootstrapEnv {
-  return WORKER_BOOTSTRAP_ENV_SCHEMA.parse(env)
+export function getRuntimeConfig(): ResolvedLotaRuntimeConfig {
+  return getCurrentRuntime().runSync(Effect.service(RuntimeConfigServiceTag))
 }
 
 export type { LotaThreadConfig }

package/src/runtime/runtime-extensions.ts

@@ -6,8 +6,17 @@ import type {
   PlanSpecRecord,
 } from '@lota-sdk/shared'
 import type { ToolSet } from 'ai'
+import { Effect } from 'effect'
+import type { Context } from 'effect'
 
 import type { RecordIdRef } from '../db/record-id'
+import { getCurrentRuntime } from '../effect/runtime-ref'
+import {
+  RuntimeAdaptersServiceTag,
+  RuntimeWorkerExtensionsServiceTag,
+  ToolProvidersServiceTag,
+  TurnHooksServiceTag,
+} from '../effect/services'
 import type { ReadableUploadMetadata } from '../storage/attachment-types'
 import type { LotaRuntimeWorkerExtensions } from './runtime-worker-registry'
 
@@ -193,54 +202,32 @@ export interface LotaRuntimeAdapters {
   withWorkspaceMemoryLock?: <T>(workspaceId: string, fn: () => Promise<T>) => Promise<T>
 }
 
-interface RuntimeExtensionsState {
-  adapters: LotaRuntimeAdapters
-  turnHooks: LotaRuntimeTurnHooks
-  toolProviders: ToolSet
-  extraWorkers: LotaRuntimeWorkerExtensions
-}
-
-const EMPTY_TOOLS = {} as ToolSet
-
-let runtimeExtensionsState: RuntimeExtensionsState = {
-  adapters: {},
-  turnHooks: {},
-  toolProviders: EMPTY_TOOLS,
-  extraWorkers: {},
-}
-
-export function configureRuntimeExtensions(params: {
-  adapters?: LotaRuntimeAdapters
-  turnHooks?: LotaRuntimeTurnHooks
-  toolProviders?: ToolSet
-  extraWorkers?: LotaRuntimeWorkerExtensions
-}): void {
-  runtimeExtensionsState = {
-    adapters: params.adapters ?? {},
-    turnHooks: params.turnHooks ?? {},
-    toolProviders: params.toolProviders ?? EMPTY_TOOLS,
-    extraWorkers: params.extraWorkers ?? {},
-  }
+function resolveFromRuntime<I, T>(tag: Context.Key<I, T>): T {
+  return getCurrentRuntime().runSync(Effect.service(tag))
 }
 
 export function getRuntimeAdapters(): LotaRuntimeAdapters {
-  return runtimeExtensionsState.adapters
+  return resolveFromRuntime(RuntimeAdaptersServiceTag)
 }
 
 export function getTurnHooks(): LotaRuntimeTurnHooks {
-  return runtimeExtensionsState.turnHooks
+  return resolveFromRuntime(TurnHooksServiceTag)
 }
 
 export function getToolProviders(): ToolSet {
-  return runtimeExtensionsState.toolProviders
+  return resolveFromRuntime(ToolProvidersServiceTag)
 }
 
 export function getConfiguredPluginDatabaseConnector(): (() => Promise<void>) | undefined {
-  return runtimeExtensionsState.adapters.connectPluginDatabases
+  return getRuntimeAdapters().connectPluginDatabases
+}
+
+export function getExtraWorkers(): LotaRuntimeWorkerExtensions {
+  return resolveFromRuntime(RuntimeWorkerExtensionsServiceTag)
 }
 
-export async function withConfiguredWorkspaceMemoryLock<T>(workspaceId: string, fn: () => Promise<T>): Promise<T> {
-  const adapter = runtimeExtensionsState.adapters.withWorkspaceMemoryLock
+export function withConfiguredWorkspaceMemoryLock<T>(workspaceId: string, fn: () => Promise<T>): Promise<T> {
+  const adapter = getRuntimeAdapters().withWorkspaceMemoryLock
   if (!adapter) {
     return fn()
   }

package/src/runtime/social-chat/social-chat-agent-runner.ts

@@ -0,0 +1,157 @@
+import { stepCountIs } from 'ai'
+import type { ToolSet } from 'ai'
+import { Schema, Effect } from 'effect'
+
+import { getAgentRuntimeConfig, getResolvedAgentFactoryConfig } from '../../config/agent-defaults'
+import { aiLogger } from '../../config/logger'
+
+interface ExecutableToolDefinition {
+  execute: (...args: unknown[]) => Promise<unknown>
+}
+
+class SocialChatAgentRunnerError extends Schema.TaggedErrorClass<SocialChatAgentRunnerError>()(
+  'SocialChatAgentRunnerError',
+  { message: Schema.String, cause: Schema.optional(Schema.Defect) },
+) {}
+
+const SOCIAL_CHAT_RETRIEVAL_TOOL_NAMES = [
+  'memorySearch',
+  'conversationSearch',
+  'queryKnowledge',
+  'researchTopic',
+  'searchWeb',
+  'fetchWebpage',
+  'inspectWebsite',
+] as const
+
+export function withLoggedSocialToolSet(
+  tools: ToolSet,
+  params: { agentId: string; channelId: string; threadId: string; executedToolNames: string[] },
+): ToolSet {
+  return Object.fromEntries(
+    Object.entries(tools).map(([toolName, toolDefinition]) => {
+      if (
+        typeof toolDefinition !== 'object' ||
+        !('execute' in toolDefinition) ||
+        typeof toolDefinition.execute !== 'function'
+      ) {
+        return [toolName, toolDefinition]
+      }
+
+      const executableTool = toolDefinition as typeof toolDefinition & ExecutableToolDefinition
+      return [
+        toolName,
+        {
+          ...toolDefinition,
+          execute: (...args: unknown[]): Promise<unknown> =>
+            Effect.runPromise(
+              Effect.gen(function* () {
+                aiLogger.info`Slack social-chat tool start: agentId=${params.agentId}, tool=${toolName}, channelId=${params.channelId}, threadId=${params.threadId}`
+                const result: unknown = yield* Effect.tryPromise({
+                  try: () => executableTool.execute(...args),
+                  catch: (error: unknown) => new SocialChatAgentRunnerError({ message: String(error), cause: error }),
+                })
+                params.executedToolNames.push(toolName)
+                aiLogger.info`Slack social-chat tool finish: agentId=${params.agentId}, tool=${toolName}, channelId=${params.channelId}, threadId=${params.threadId}`
+                return result
+              }).pipe(
+                Effect.tapError((error) =>
+                  Effect.sync(() => {
+                    aiLogger.warn`Slack social-chat tool failed: agentId=${params.agentId}, tool=${toolName}, channelId=${params.channelId}, threadId=${params.threadId}, error=${error}`
+                  }),
+                ),
+              ),
+            ),
+        },
+      ]
+    }),
+  )
+}
+
+function runSocialAgentTurnEffect(params: {
+  agentId: string
+  mode: 'fixedThreadMode' | 'threadMode'
+  threadType: 'group'
+  onboardingActive: boolean
+  linearInstalled: boolean
+  systemWorkspaceDetails?: string
+  preSeededMemoriesSection?: string
+  retrievedKnowledgeSection?: string
+  learnedSkillsSection?: string
+  userMessageText?: string
+  additionalInstructionSections?: string[]
+  prompt: string
+  tools: ToolSet
+  abortSignal: AbortSignal
+}): Effect.Effect<{ text: string; displayName: string }, SocialChatAgentRunnerError> {
+  return Effect.gen(function* () {
+    const runtimeConfig = getAgentRuntimeConfig({
+      agentId: params.agentId,
+      threadType: params.threadType,
+      mode: params.mode,
+      onboardingActive: params.onboardingActive,
+      linearInstalled: params.linearInstalled,
+      systemWorkspaceDetails: params.systemWorkspaceDetails,
+      preSeededMemoriesSection: params.preSeededMemoriesSection,
+      retrievedKnowledgeSection: params.retrievedKnowledgeSection,
+      learnedSkillsSection: params.learnedSkillsSection,
+      userMessageText: params.userMessageText,
+      ruleOptions: {
+        includeMemr3Rule: SOCIAL_CHAT_RETRIEVAL_TOOL_NAMES.some((toolName) => toolName in params.tools),
+        includeDomainReasoningFallbackRule: params.agentId === 'cpo' || params.agentId === 'mentor',
+      },
+      additionalInstructionSections: params.additionalInstructionSections,
+    })
+
+    const agentFactoryEntry = getResolvedAgentFactoryConfig().createAgent[runtimeConfig.id]
+    if (typeof agentFactoryEntry !== 'function') {
+      return yield* new SocialChatAgentRunnerError({
+        message: `Social chat agent factory is not configured for ${runtimeConfig.id}`,
+      })
+    }
+    const agentFactory = agentFactoryEntry
+
+    const agent = agentFactory({
+      mode: params.mode,
+      tools: params.tools,
+      extraInstructions: runtimeConfig.extraInstructions,
+      stopWhen: [stepCountIs(runtimeConfig.maxSteps)],
+    })
+    const response = yield* Effect.promise(() =>
+      agent.generate({ prompt: params.prompt, abortSignal: params.abortSignal }),
+    )
+    const text = response.text.trim()
+    if (!text) {
+      return yield* new SocialChatAgentRunnerError({
+        message: `Social chat agent ${params.agentId} returned an empty response.`,
+      })
+    }
+
+    return {
+      text,
+      displayName:
+        typeof runtimeConfig.displayName === 'string' && runtimeConfig.displayName.trim()
+          ? runtimeConfig.displayName.trim()
+          : params.agentId,
+    }
+  })
+}
+
+export function runSocialAgentTurn(params: {
+  agentId: string
+  mode: 'fixedThreadMode' | 'threadMode'
+  threadType: 'group'
+  onboardingActive: boolean
+  linearInstalled: boolean
+  systemWorkspaceDetails?: string
+  preSeededMemoriesSection?: string
+  retrievedKnowledgeSection?: string
+  learnedSkillsSection?: string
+  userMessageText?: string
+  additionalInstructionSections?: string[]
+  prompt: string
+  tools: ToolSet
+  abortSignal: AbortSignal
+}): Promise<{ text: string; displayName: string }> {
+  return Effect.runPromise(runSocialAgentTurnEffect(params))
+}

package/src/runtime/{social-chat-history.ts → social-chat/social-chat-history.ts}

@@ -1,8 +1,18 @@
 import { stripSlackToolExecutionNoticeMarkdown } from '@lota-sdk/shared'
 import type { Message, Thread } from 'chat'
+import { Schema, Effect } from 'effect'
 
-import type { SocialChatHistoryMessage } from '../services/social-chat-history.service'
-import { toHistoryMessages, toOptionalTrimmedString } from './thread-chat-helpers'
+import type {
+  SocialChatHistoryMessage,
+  SocialChatHistoryMetadata,
+  SocialChatHistoryPart,
+} from '../../services/social-chat-history.service'
+import { toHistoryMessages, toOptionalTrimmedString } from '../thread-chat-helpers'
+
+class SocialChatHistoryError extends Schema.TaggedErrorClass<SocialChatHistoryError>()('SocialChatHistoryError', {
+  message: Schema.String,
+  cause: Schema.optional(Schema.Defect),
+}) {}
 
 export function readSlackAuthorName(message: Message): string | undefined {
   return (
@@ -14,13 +24,9 @@ export function readSlackAuthorName(message: Message): string | undefined {
 }
 
 export function buildSocialChatThreadTranscript(
-  messages: Array<{
-    role: 'user' | 'assistant'
-    parts: Array<Record<string, unknown>>
-    metadata?: Record<string, unknown>
-  }>,
+  messages: ReadonlyArray<Pick<SocialChatHistoryMessage, 'role' | 'parts' | 'metadata'>>,
 ): string {
-  const historyMessages = toHistoryMessages(messages)
+  const historyMessages = toHistoryMessages([...messages])
   if (historyMessages.length === 0) return 'No prior thread history.'
 
   return historyMessages
@@ -58,11 +64,11 @@ export function normalizeSocialHistoryMessage(params: {
     mediaType: attachment.mimeType ?? 'application/octet-stream',
     sizeBytes: typeof attachment.size === 'number' ? attachment.size : null,
     storageKey: attachment.url ?? 'external',
-  }))
+  })) satisfies SocialChatHistoryPart[]
   const parts = [...(text ? [{ type: 'text', text }] : []), ...fileParts]
   if (parts.length === 0) return null
 
-  const metadata: Record<string, unknown> = {
+  const metadata: SocialChatHistoryMetadata = {
     platform: 'slack',
     channelId: params.channelId,
     threadId: params.message.threadId,
@@ -97,14 +103,30 @@ export function normalizeSocialHistoryMessage(params: {
   }
 }
 
-export async function collectThreadMessages(thread: Thread, incomingMessage: Message): Promise<Message[]> {
-  try {
-    const messages: Message[] = []
-    for await (const message of thread.allMessages) {
-      messages.push(message)
-    }
-    return messages.length > 0 ? messages : [incomingMessage]
-  } catch {
-    return thread.recentMessages.length > 0 ? [...thread.recentMessages] : [incomingMessage]
-  }
+export function collectThreadMessages(thread: Thread, incomingMessage: Message): Promise<Message[]> {
+  return Effect.runPromise(
+    Effect.catch(
+      Effect.gen(function* () {
+        const collected: Message[] = []
+        const iterator = thread.allMessages[Symbol.asyncIterator]()
+
+        for (;;) {
+          const next = yield* Effect.tryPromise({
+            try: () => iterator.next(),
+            catch: (error: unknown) =>
+              new SocialChatHistoryError({ message: 'Failed to read thread messages', cause: error }),
+          })
+          if (next.done) break
+          collected.push(next.value)
+        }
+
+        return collected.length > 0
+          ? collected
+          : thread.recentMessages.length > 0
+            ? [...thread.recentMessages]
+            : [incomingMessage]
+      }),
+      () => Effect.succeed(thread.recentMessages.length > 0 ? [...thread.recentMessages] : [incomingMessage]),
+    ),
+  )
 }