@lota-sdk/core 0.4.8 → 0.4.10

package/src/runtime/runtime-services.ts

@@ -0,0 +1,386 @@
+/**
+ * Eagerly resolves the full SDK service surface against a live ManagedRuntime.
+ *
+ * The previous implementation used per-property `get` Proxies that re-resolved
+ * each tag on every access. This module resolves every tag exactly once when
+ * the runtime starts and returns a plain object whose shape matches the
+ * `LotaRuntime['services']` + `LotaRuntime['lota']` contracts byte-for-byte.
+ */
+
+import type { ChatMessage } from '@lota-sdk/shared'
+import type { Context, ManagedRuntime } from 'effect'
+import { Effect } from 'effect'
+
+import { ensureRecordId } from '../db/record-id'
+import type { SurrealDBService } from '../db/service'
+import { TABLES } from '../db/tables'
+import type { AwaitableService, AwaitableValue } from '../effect/awaitable-effect'
+import { toAwaitableService } from '../effect/awaitable-effect'
+import { BadRequestError, NotFoundError } from '../effect/errors'
+import { effectTryPromise } from '../effect/helpers'
+import type { RedisConnectionManager } from '../redis/connection'
+import type { SharedThreadStreamSubscriberTag } from '../redis/stream-context'
+import { AgentActivityServiceTag } from '../services/agent-activity.service'
+import { ArtifactServiceTag } from '../services/artifact.service'
+import { AttachmentServiceTag } from '../services/attachment.service'
+import { AutonomousJobServiceTag } from '../services/autonomous-job.service'
+import { ContextCompactionServiceTag } from '../services/context-compaction.service'
+import { DocumentChunkServiceTag } from '../services/document-chunk.service'
+import { ExecutionPlanServiceTag } from '../services/execution-plan/execution-plan.service'
+import { MemoryServiceTag } from '../services/memory/memory.service'
+import { RerankServiceTag } from '../services/memory/rerank.service'
+import { MutatingApprovalServiceTag } from '../services/mutating-approval.service'
+import { OrganizationMemberServiceTag } from '../services/organization-member.service'
+import { OrganizationServiceTag } from '../services/organization.service'
+import { PlanAgentHeartbeatServiceTag } from '../services/plan/plan-agent-heartbeat.service'
+import { PlanAgentQueryServiceTag } from '../services/plan/plan-agent-query.service'
+import { PlanCoordinationServiceTag } from '../services/plan/plan-coordination.service'
+import { PlanCycleServiceTag } from '../services/plan/plan-cycle.service'
+import { PlanDeadlineServiceTag } from '../services/plan/plan-deadline.service'
+import { PlanExecutorServiceTag } from '../services/plan/plan-executor.service'
+import { PlanRunServiceTag } from '../services/plan/plan-run.service'
+import { PlanSchedulerServiceTag } from '../services/plan/plan-scheduler.service'
+import { PlanTemplateServiceTag } from '../services/plan/plan-template.service'
+import { RecentActivityTitleServiceTag } from '../services/recent-activity-title.service'
+import { RecentActivityServiceTag } from '../services/recent-activity.service'
+import type { makeSocialChatHistoryService } from '../services/social-chat-history.service'
+import { ThreadMessageServiceTag } from '../services/thread/thread-message.service'
+import { ThreadTitleServiceTag } from '../services/thread/thread-title.service'
+import { isApprovalContinuationRequest as isApprovalContinuationRequestFn } from '../services/thread/thread-turn'
+import type {
+  createThreadApprovalContinuationStream,
+  createThreadNativeToolApprovalStream,
+  createThreadTurnStream,
+  runThreadTurnInBackground,
+  ThreadTurnServiceTag,
+  triggerPlanNodeTurn,
+} from '../services/thread/thread-turn'
+import { ThreadServiceTag } from '../services/thread/thread.service'
+import { UserServiceTag } from '../services/user.service'
+import { GeneratedDocumentStorageServiceTag } from '../storage/generated-document-storage.service'
+import { routeThreadChatMessages } from './chat-request-routing'
+
+// eslint-disable-next-line typescript-eslint/no-explicit-any -- ManagedRuntime is contravariant in R; `any` is the only valid wildcard
+type SdkManagedRuntime = ManagedRuntime.ManagedRuntime<any, any>
+
+// ── Type helpers (shared with create-runtime.ts's public interface) ──
+type Svc<T extends { readonly Service: unknown }> = T['Service']
+type HostSvc<T extends { readonly Service: object }> = AwaitableService<T['Service']>
+
+export type AwaitableThreadService = HostSvc<typeof ThreadServiceTag> &
+  Pick<Svc<typeof ThreadServiceTag>, 'withActiveRunLease'>
+export type AwaitableDocumentChunkService = HostSvc<typeof DocumentChunkServiceTag> &
+  Pick<Svc<typeof DocumentChunkServiceTag>, 'syncVersionedChunks'>
+
+export type ArchiveSdkThread = (
+  threadId: Parameters<Svc<typeof ThreadServiceTag>['updateStatus']>[0],
+  status?: 'archived',
+) => ReturnType<Svc<typeof ThreadServiceTag>['updateStatus']>
+
+export type UnarchiveSdkThread = (
+  threadId: Parameters<Svc<typeof ThreadServiceTag>['updateStatus']>[0],
+  status?: 'active',
+) => ReturnType<Svc<typeof ThreadServiceTag>['updateStatus']>
+
+export interface LotaRuntimeServices {
+  database: SurrealDBService
+  redis: RedisConnectionManager
+  closeRedisConnection: () => Promise<void>
+  agentActivityService: HostSvc<typeof AgentActivityServiceTag>
+  artifactService: HostSvc<typeof ArtifactServiceTag>
+  attachmentService: HostSvc<typeof AttachmentServiceTag>
+  autonomousJobService: HostSvc<typeof AutonomousJobServiceTag>
+  contextCompactionService: HostSvc<typeof ContextCompactionServiceTag>
+  documentChunkService: AwaitableDocumentChunkService
+  generatedDocumentStorageService: HostSvc<typeof GeneratedDocumentStorageServiceTag>
+  memoryService: HostSvc<typeof MemoryServiceTag>
+  rerankService: HostSvc<typeof RerankServiceTag>
+  verifyMutatingApproval: HostSvc<typeof MutatingApprovalServiceTag>
+  organizationService: HostSvc<typeof OrganizationServiceTag>
+  organizationMemberService: HostSvc<typeof OrganizationMemberServiceTag>
+  userService: HostSvc<typeof UserServiceTag>
+  recentActivityService: HostSvc<typeof RecentActivityServiceTag>
+  recentActivityTitleService: HostSvc<typeof RecentActivityTitleServiceTag>
+  socialChatHistoryService: ReturnType<typeof makeSocialChatHistoryService>
+  executionPlanService: HostSvc<typeof ExecutionPlanServiceTag>
+  planDeadlineService: HostSvc<typeof PlanDeadlineServiceTag>
+  planExecutorService: HostSvc<typeof PlanExecutorServiceTag>
+  planRunService: HostSvc<typeof PlanRunServiceTag>
+  planTemplateService: HostSvc<typeof PlanTemplateServiceTag>
+  planCoordinationService: HostSvc<typeof PlanCoordinationServiceTag>
+  planSchedulerService: HostSvc<typeof PlanSchedulerServiceTag>
+  planAgentHeartbeatService: HostSvc<typeof PlanAgentHeartbeatServiceTag>
+  planAgentQueryService: HostSvc<typeof PlanAgentQueryServiceTag>
+  planCycleService: HostSvc<typeof PlanCycleServiceTag>
+  threadMessageService: HostSvc<typeof ThreadMessageServiceTag>
+  threadService: AwaitableThreadService
+  threadTitleService: HostSvc<typeof ThreadTitleServiceTag>
+  createThreadApprovalContinuationStream: typeof createThreadApprovalContinuationStream
+  createThreadNativeToolApprovalStream: typeof createThreadNativeToolApprovalStream
+  createThreadTurnStream: typeof createThreadTurnStream
+  isApprovalContinuationRequest: typeof isApprovalContinuationRequestFn
+  runThreadTurnInBackground: typeof runThreadTurnInBackground
+  triggerPlanNodeTurn: typeof triggerPlanNodeTurn
+}
+
+export interface LotaRuntimeLota {
+  organizations: {
+    create: AwaitableValue<Svc<typeof OrganizationServiceTag>['createOrganization']>
+    upsert: AwaitableValue<Svc<typeof OrganizationServiceTag>['upsertOrganization']>
+    get: AwaitableValue<Svc<typeof OrganizationServiceTag>['getOrganization']>
+    list: AwaitableValue<Svc<typeof OrganizationServiceTag>['listOrganizations']>
+    update: AwaitableValue<Svc<typeof OrganizationServiceTag>['updateOrganization']>
+    delete: AwaitableValue<Svc<typeof OrganizationServiceTag>['deleteOrganization']>
+  }
+  users: {
+    upsert: AwaitableValue<Svc<typeof UserServiceTag>['upsertUser']>
+    get: AwaitableValue<Svc<typeof UserServiceTag>['getUser']>
+    list: AwaitableValue<Svc<typeof UserServiceTag>['listUsers']>
+    update: AwaitableValue<Svc<typeof UserServiceTag>['updateUser']>
+    delete: AwaitableValue<Svc<typeof UserServiceTag>['deleteUser']>
+  }
+  memberships: {
+    add: AwaitableValue<Svc<typeof OrganizationMemberServiceTag>['addMembership']>
+    listForOrganization: AwaitableValue<Svc<typeof OrganizationMemberServiceTag>['listMembershipsForOrganization']>
+    listForUser: AwaitableValue<Svc<typeof OrganizationMemberServiceTag>['listMembershipsForUser']>
+    remove: AwaitableValue<Svc<typeof OrganizationMemberServiceTag>['removeMembership']>
+    isMember: AwaitableValue<Svc<typeof OrganizationMemberServiceTag>['isMember']>
+  }
+  threads: {
+    create: AwaitableValue<Svc<typeof ThreadServiceTag>['createThread']>
+    list: AwaitableValue<Svc<typeof ThreadServiceTag>['listThreads']>
+    get: AwaitableValue<Svc<typeof ThreadServiceTag>['getThread']>
+    update: AwaitableValue<Svc<typeof ThreadServiceTag>['updateTitle']>
+    archive: AwaitableValue<ArchiveSdkThread>
+    unarchive: AwaitableValue<UnarchiveSdkThread>
+    delete: AwaitableValue<Svc<typeof ThreadServiceTag>['deleteThread']>
+    stop: AwaitableValue<Svc<typeof ThreadServiceTag>['stopActiveRun']>
+    listMessages: AwaitableValue<Svc<typeof ThreadMessageServiceTag>['listMessageHistoryPage']>
+    getMessage: (params: { threadId: string; messageId: string }) => Promise<ChatMessage>
+    sendMessage: (params: {
+      threadId: string
+      organizationId: string
+      userId: string
+      userName: string
+      messages: Parameters<typeof routeThreadChatMessages>[0]
+    }) => Promise<Awaited<ReturnType<typeof createThreadTurnStream>>>
+    continueApproval: (params: {
+      threadId: string
+      organizationId: string
+      userId: string
+      userName: string
+      messages: Parameters<typeof routeThreadChatMessages>[0]
+    }) => Promise<Awaited<ReturnType<typeof createThreadApprovalContinuationStream>>>
+    uploadAttachment: AwaitableValue<Svc<typeof AttachmentServiceTag>['uploadThreadAttachment']>
+  }
+}
+
+interface BuildRuntimeServiceSurfaceInput {
+  managedRuntime: SdkManagedRuntime
+  db: SurrealDBService
+  redisManager: RedisConnectionManager
+  sharedSubscriber: Svc<typeof SharedThreadStreamSubscriberTag>
+  threadTurnService: Svc<typeof ThreadTurnServiceTag>
+  socialChatHistoryService: ReturnType<typeof makeSocialChatHistoryService>
+}
+
+interface RuntimeServiceSurface {
+  services: LotaRuntimeServices
+  lota: LotaRuntimeLota
+}
+
+/**
+ * Eagerly resolve the full service surface exactly once.
+ *
+ * All Effect-returning service methods are wrapped with `toAwaitableService`,
+ * which means callers can `await` them directly while they stay discoverable
+ * as Effects for composition.
+ */
+export function buildRuntimeServiceSurface(input: BuildRuntimeServiceSurfaceInput): RuntimeServiceSurface {
+  const { managedRuntime, db, redisManager, threadTurnService, socialChatHistoryService } = input
+  const runPromise = <A, E>(effect: Effect.Effect<A, E>): Promise<A> => managedRuntime.runPromise(effect)
+
+  const resolveRaw = <I, T>(tag: Context.Key<I, T>): T => managedRuntime.runSync(Effect.service(tag))
+  const resolveOnce = <I, T extends object>(tag: Context.Key<I, T>): AwaitableService<T> =>
+    toAwaitableService(resolveRaw(tag), { runPromise: (effect) => managedRuntime.runPromise(effect) })
+
+  // ── Resolve every tag eagerly. Each binding is a plain value from here. ──
+  const agentActivityService = resolveOnce(AgentActivityServiceTag)
+  const artifactService = resolveOnce(ArtifactServiceTag)
+  const attachmentService = resolveOnce(AttachmentServiceTag)
+  const autonomousJobService = resolveOnce(AutonomousJobServiceTag)
+  const contextCompactionService = resolveOnce(ContextCompactionServiceTag)
+  const documentChunkService = resolveOnce(DocumentChunkServiceTag) as AwaitableDocumentChunkService
+  const generatedDocumentStorageService = resolveOnce(GeneratedDocumentStorageServiceTag)
+  const memoryService = resolveOnce(MemoryServiceTag)
+  const rerankService = resolveOnce(RerankServiceTag)
+  const verifyMutatingApproval = resolveOnce(MutatingApprovalServiceTag)
+  const organizationService = resolveOnce(OrganizationServiceTag)
+  const organizationMemberService = resolveOnce(OrganizationMemberServiceTag)
+  const userService = resolveOnce(UserServiceTag)
+  const recentActivityService = resolveOnce(RecentActivityServiceTag)
+  const recentActivityTitleService = resolveOnce(RecentActivityTitleServiceTag)
+  const executionPlanService = resolveOnce(ExecutionPlanServiceTag)
+  const planDeadlineService = resolveOnce(PlanDeadlineServiceTag)
+  const planExecutorService = resolveOnce(PlanExecutorServiceTag)
+  const planRunService = resolveOnce(PlanRunServiceTag)
+  const planTemplateService = resolveOnce(PlanTemplateServiceTag)
+  const planCoordinationService = resolveOnce(PlanCoordinationServiceTag)
+  const planSchedulerService = resolveOnce(PlanSchedulerServiceTag)
+  const planAgentHeartbeatService = resolveOnce(PlanAgentHeartbeatServiceTag)
+  const planAgentQueryService = resolveOnce(PlanAgentQueryServiceTag)
+  const planCycleService = resolveOnce(PlanCycleServiceTag)
+  const threadMessageService = resolveOnce(ThreadMessageServiceTag)
+  const threadService = resolveOnce(ThreadServiceTag) as AwaitableThreadService
+  const threadTitleService = resolveOnce(ThreadTitleServiceTag)
+
+  // ── Resolve the raw service instances once for inline Effect composition ──
+  // `toAwaitableService` (used above) erases Effect return types so callers
+  // can `await` directly. The `getMessage`/`sendMessage`/`continueApproval`
+  // wrappers below need the raw Effect-returning signatures so they can
+  // `yield*` service methods inside their `Effect.gen` blocks.
+  const threadMessageServiceRaw = resolveRaw(ThreadMessageServiceTag)
+  const threadServiceRaw = resolveRaw(ThreadServiceTag)
+
+  const services: LotaRuntimeServices = {
+    database: db,
+    redis: redisManager,
+    closeRedisConnection: () => runPromise(effectTryPromise(() => redisManager.closeConnection())),
+    agentActivityService,
+    artifactService,
+    attachmentService,
+    autonomousJobService,
+    contextCompactionService,
+    documentChunkService,
+    generatedDocumentStorageService,
+    memoryService,
+    rerankService,
+    verifyMutatingApproval,
+    organizationService,
+    organizationMemberService,
+    userService,
+    recentActivityService,
+    recentActivityTitleService,
+    socialChatHistoryService,
+    executionPlanService,
+    planDeadlineService,
+    planExecutorService,
+    planRunService,
+    planTemplateService,
+    planCoordinationService,
+    planSchedulerService,
+    planAgentHeartbeatService,
+    planAgentQueryService,
+    planCycleService,
+    threadMessageService,
+    threadService,
+    threadTitleService,
+    createThreadApprovalContinuationStream: (...args) =>
+      runPromise(threadTurnService.createThreadApprovalContinuationStream(...args)),
+    createThreadNativeToolApprovalStream: (...args) =>
+      runPromise(threadTurnService.createThreadNativeToolApprovalStream(...args)),
+    createThreadTurnStream: (...args) => runPromise(threadTurnService.createThreadTurnStream(...args)),
+    isApprovalContinuationRequest: isApprovalContinuationRequestFn,
+    runThreadTurnInBackground: (...args) => runPromise(threadTurnService.runThreadTurnInBackground(...args)),
+    triggerPlanNodeTurn: (...args) => runPromise(threadTurnService.triggerPlanNodeTurn(...args)),
+  }
+
+  const lota: LotaRuntimeLota = {
+    organizations: {
+      create: (...args) => organizationService.createOrganization(...args),
+      upsert: (...args) => organizationService.upsertOrganization(...args),
+      get: (...args) => organizationService.getOrganization(...args),
+      list: (...args) => organizationService.listOrganizations(...args),
+      update: (...args) => organizationService.updateOrganization(...args),
+      delete: (...args) => organizationService.deleteOrganization(...args),
+    },
+    users: {
+      upsert: (...args) => userService.upsertUser(...args),
+      get: (...args) => userService.getUser(...args),
+      list: (...args) => userService.listUsers(...args),
+      update: (...args) => userService.updateUser(...args),
+      delete: (...args) => userService.deleteUser(...args),
+    },
+    memberships: {
+      add: (...args) => organizationMemberService.addMembership(...args),
+      listForOrganization: (...args) => organizationMemberService.listMembershipsForOrganization(...args),
+      listForUser: (...args) => organizationMemberService.listMembershipsForUser(...args),
+      remove: (...args) => organizationMemberService.removeMembership(...args),
+      isMember: (...args) => organizationMemberService.isMember(...args),
+    },
+    threads: {
+      create: (...args) => threadService.createThread(...args),
+      list: (...args) => threadService.listThreads(...args),
+      get: (...args) => threadService.getThread(...args),
+      update: (...args) => threadService.updateTitle(...args),
+      archive: (threadId, status = 'archived') => threadService.updateStatus(threadId, status),
+      unarchive: (threadId, status = 'active') => threadService.updateStatus(threadId, status),
+      delete: (...args) => threadService.deleteThread(...args),
+      stop: (...args) => threadService.stopActiveRun(...args),
+      listMessages: (...args) => threadMessageService.listMessageHistoryPage(...args),
+      getMessage: ({ threadId, messageId }) =>
+        runPromise(
+          Effect.gen(function* () {
+            const messages = yield* threadMessageServiceRaw.listMessages(ensureRecordId(threadId, TABLES.THREAD))
+            const message = messages.find((candidate: ChatMessage) => candidate.id === messageId)
+            if (!message) {
+              return yield* new NotFoundError({
+                resource: 'Thread message',
+                id: messageId,
+                message: `Thread message not found: ${messageId}`,
+              })
+            }
+            return message
+          }),
+        ),
+      sendMessage: ({ threadId, organizationId, userId, userName, messages }) =>
+        runPromise(
+          Effect.gen(function* () {
+            const threadRef = ensureRecordId(threadId, TABLES.THREAD)
+            const thread = yield* threadServiceRaw.getThread(threadRef)
+            const routed = routeThreadChatMessages(messages)
+            if (routed.kind !== 'turn') {
+              return yield* new BadRequestError({
+                message: routed.kind === 'invalid' ? routed.message : 'Expected a user turn payload.',
+              })
+            }
+
+            return yield* threadTurnService.createThreadTurnStream({
+              thread,
+              threadRef,
+              orgRef: ensureRecordId(organizationId, TABLES.ORGANIZATION),
+              userRef: ensureRecordId(userId, TABLES.USER),
+              userName,
+              inputMessage: routed.inputMessage,
+            })
+          }),
+        ),
+      continueApproval: ({ threadId, organizationId, userId, userName, messages }) =>
+        runPromise(
+          Effect.gen(function* () {
+            const threadRef = ensureRecordId(threadId, TABLES.THREAD)
+            const thread = yield* threadServiceRaw.getThread(threadRef)
+            const routed = routeThreadChatMessages(messages)
+            if (routed.kind !== 'approval-continuation') {
+              return yield* new BadRequestError({
+                message:
+                  routed.kind === 'invalid' ? routed.message : 'Expected approval continuation messages payload.',
+              })
+            }
+
+            return yield* threadTurnService.createThreadApprovalContinuationStream({
+              thread,
+              threadRef,
+              orgRef: ensureRecordId(organizationId, TABLES.ORGANIZATION),
+              userRef: ensureRecordId(userId, TABLES.USER),
+              userName,
+              approvalMessages: routed.approvalMessages,
+            })
+          }),
+        ),
+      uploadAttachment: (...args) => attachmentService.uploadThreadAttachment(...args),
+    },
+  }
+
+  return { services, lota }
+}

package/src/runtime/runtime-token.ts

@@ -0,0 +1,47 @@
+/**
+ * Single-slot runtime token. `createLotaRuntime()` claims the slot on success
+ * and releases it on disconnect, enforcing the "one runtime per process"
+ * invariant. Kept as a small, typed module so the guard is trivially testable
+ * and stays out of the main entrypoint.
+ */
+
+import { Effect } from 'effect'
+
+import { ConfigurationError } from '../effect/errors'
+
+let activeToken: symbol | null = null
+
+function buildConflictError(): ConfigurationError {
+  return new ConfigurationError({
+    message: 'createLotaRuntime() is process-scoped. Disconnect the active runtime before creating another one.',
+  })
+}
+
+/**
+ * Claim the process-wide runtime slot. Fails with `ConfigurationError` if it
+ * is already held. Preferred inside `Effect.gen` so the failure is expressed
+ * through the typed error channel instead of a thrown value.
+ */
+export function acquireRuntimeTokenEffect(): Effect.Effect<symbol, ConfigurationError> {
+  return Effect.suspend(() => {
+    if (activeToken) {
+      return Effect.fail(buildConflictError())
+    }
+
+    const token = Symbol('lota-runtime')
+    activeToken = token
+    return Effect.succeed(token)
+  })
+}
+
+/** Release the slot only if the caller holds the current token. */
+export function releaseRuntimeToken(token: symbol): void {
+  if (activeToken === token) {
+    activeToken = null
+  }
+}
+
+/** Diagnostic: whether a runtime is currently active in this process. */
+export function isRuntimeTokenActive(): boolean {
+  return activeToken !== null
+}

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

@@ -0,0 +1,159 @@
+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.debug`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.debug`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.tryPromise({
+      try: () => agent.generate({ prompt: params.prompt, abortSignal: params.abortSignal }),
+      catch: (cause) =>
+        new SocialChatAgentRunnerError({ message: `Social chat agent ${params.agentId} generate() failed.`, cause }),
+    })
+    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))
+}