@lota-sdk/core 0.4.9 → 0.4.10

package/src/runtime/runtime-lifecycle.ts

@@ -0,0 +1,124 @@
+/**
+ * Plugin database connect/disconnect helpers and runtime disconnect assembly.
+ *
+ * The plugin connect/disconnect helpers run inside the supplied
+ * `ManagedRuntime` so spans, logging, and layer context stay consistent with
+ * the rest of the SDK runtime. `createRuntimeDisconnect` instead drives the
+ * shutdown sequence through the caller-supplied `runPromiseWithCurrentContext`
+ * (currently `Effect.runPromiseWith(Context.empty())`), which intentionally
+ * does not preserve the SDK runtime context — by then the runtime is being
+ * torn down.
+ */
+
+import type { ManagedRuntime } from 'effect'
+import { Effect } from 'effect'
+
+import { effectTryPromise } from '../effect/helpers'
+import type { LotaPlugin } from './plugin-types'
+
+// 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>
+
+function getPluginLifecycleServices(plugin: LotaPlugin): Record<string, unknown> {
+  return plugin.services
+}
+
+/**
+ * Build a plugin database connector that iterates the configured plugins and
+ * calls each `services.connectDatabase()` once, tracking completion in
+ * `connectedPluginDatabases` so repeated calls are idempotent.
+ */
+export function createPluginDatabaseConnector(
+  managedRuntime: SdkManagedRuntime,
+  pluginRuntime: Record<string, LotaPlugin>,
+  connectedPluginDatabases: Set<string>,
+): () => Promise<void> {
+  return () =>
+    managedRuntime.runPromise(
+      Effect.gen(function* () {
+        for (const [pluginName, plugin] of Object.entries(pluginRuntime)) {
+          if (connectedPluginDatabases.has(pluginName)) {
+            continue
+          }
+
+          const services = getPluginLifecycleServices(plugin)
+          const connectDatabase = Reflect.get(services, 'connectDatabase')
+          if (typeof connectDatabase !== 'function') {
+            continue
+          }
+
+          const connectDatabaseFn = connectDatabase as (this: typeof services) => Promise<void>
+          yield* effectTryPromise(() => connectDatabaseFn.call(services))
+          connectedPluginDatabases.add(pluginName)
+        }
+      }),
+    )
+}
+
+/**
+ * Build a plugin database disconnector. Clears `connectedPluginDatabases`
+ * entries regardless of whether the plugin provides a `disconnectDatabase`
+ * hook, so the set stays in sync with actual connection state.
+ */
+export function createPluginDatabaseDisconnector(
+  managedRuntime: SdkManagedRuntime,
+  pluginRuntime: Record<string, LotaPlugin>,
+  connectedPluginDatabases: Set<string>,
+): () => Promise<void> {
+  return () =>
+    managedRuntime.runPromise(
+      Effect.gen(function* () {
+        for (const [pluginName, plugin] of Object.entries(pluginRuntime)) {
+          if (!connectedPluginDatabases.has(pluginName)) {
+            continue
+          }
+
+          const services = getPluginLifecycleServices(plugin)
+          const disconnectDatabase = Reflect.get(services, 'disconnectDatabase')
+          if (typeof disconnectDatabase !== 'function') {
+            connectedPluginDatabases.delete(pluginName)
+            continue
+          }
+
+          const disconnectDatabaseFn = disconnectDatabase as (this: typeof services) => Promise<void>
+          yield* effectTryPromise(() => disconnectDatabaseFn.call(services))
+          connectedPluginDatabases.delete(pluginName)
+        }
+      }),
+    )
+}
+
+interface CreateDisconnectInput {
+  managedRuntime: SdkManagedRuntime
+  runPromiseWithCurrentContext: <A, E>(effect: Effect.Effect<A, E, never>) => Promise<A>
+  socialChatShutdown: () => Promise<void>
+  disconnectPluginDatabases: () => Promise<void>
+  onFinalize: () => void
+}
+
+/**
+ * Compose the runtime `disconnect()` function. The returned function is
+ * idempotent: the first call starts the shutdown sequence, subsequent calls
+ * return the same in-flight promise.
+ */
+export function createRuntimeDisconnect(input: CreateDisconnectInput): () => Promise<void> {
+  const { managedRuntime, runPromiseWithCurrentContext, socialChatShutdown, disconnectPluginDatabases, onFinalize } =
+    input
+
+  let disconnectPromise: Promise<void> | null = null
+
+  return () => {
+    if (disconnectPromise) {
+      return disconnectPromise
+    }
+
+    disconnectPromise = runPromiseWithCurrentContext(
+      Effect.gen(function* () {
+        yield* Effect.ignore(effectTryPromise(() => socialChatShutdown()))
+        yield* Effect.ignore(effectTryPromise(() => disconnectPluginDatabases()))
+        yield* effectTryPromise(() => managedRuntime.dispose())
+      }).pipe(Effect.ensuring(Effect.sync(onFinalize))),
+    )
+    return disconnectPromise
+  }
+}

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

@@ -46,13 +46,13 @@ export function withLoggedSocialToolSet(
           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}`
+                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.info`Slack social-chat tool finish: agentId=${params.agentId}, tool=${toolName}, channelId=${params.channelId}, threadId=${params.threadId}`
+                aiLogger.debug`Slack social-chat tool finish: agentId=${params.agentId}, tool=${toolName}, channelId=${params.channelId}, threadId=${params.threadId}`
                 return result
               }).pipe(
                 Effect.tapError((error) =>
@@ -117,9 +117,11 @@ function runSocialAgentTurnEffect(params: {
       extraInstructions: runtimeConfig.extraInstructions,
       stopWhen: [stepCountIs(runtimeConfig.maxSteps)],
     })
-    const response = yield* Effect.promise(() =>
-      agent.generate({ prompt: params.prompt, abortSignal: params.abortSignal }),
-    )
+    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({

package/src/runtime/social-chat/social-chat-history.ts

@@ -2,6 +2,7 @@ import { stripSlackToolExecutionNoticeMarkdown } from '@lota-sdk/shared'
 import type { Message, Thread } from 'chat'
 import { Schema, Effect } from 'effect'
 
+import { iterateEffect } from '../../effect/helpers'
 import type {
   SocialChatHistoryMessage,
   SocialChatHistoryMetadata,
@@ -107,21 +108,29 @@ export function collectThreadMessages(thread: Thread, incomingMessage: 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)
-        }
+        const collected = yield* iterateEffect<{ messages: Message[]; done: boolean }, SocialChatHistoryError, never>(
+          { messages: [], done: false },
+          {
+            while: (state) => !state.done,
+            body: (state) =>
+              Effect.tryPromise({
+                try: () => iterator.next(),
+                catch: (error: unknown) =>
+                  new SocialChatHistoryError({ message: 'Failed to read thread messages', cause: error }),
+              }).pipe(
+                Effect.map((next) =>
+                  next.done
+                    ? { messages: state.messages, done: true }
+                    : { messages: [...state.messages, next.value], done: false },
+                ),
+              ),
+          },
+        )
 
-        return collected.length > 0
-          ? collected
+        return collected.messages.length > 0
+          ? collected.messages
           : thread.recentMessages.length > 0
             ? [...thread.recentMessages]
             : [incomingMessage]