@lota-sdk/core 0.4.8 → 0.4.10

package/src/redis/redis-lease-lock.ts

@@ -1,7 +1,8 @@
-import { setTimeout as delay } from 'node:timers/promises'
-
+import { Clock, Deferred, Duration, Effect, Random, Schedule } from 'effect'
 import type IORedis from 'ioredis'
 
+import { LockAcquisitionError, LockLostError, RedisError } from '../effect/errors'
+import { RedisServiceTag } from '../effect/services'
 import { getErrorMessage } from '../utils/errors'
 
 interface RedisLeaseLockLogger {
@@ -10,8 +11,8 @@ interface RedisLeaseLockLogger {
   warn?: (message: string) => void
 }
 
-interface RedisLeaseLockOptions {
-  redis: IORedis
+export interface RedisLeaseLockOptions {
+  redis?: IORedis
   lockKey: string
   lockTtlMs: number
   retryDelayMs?: number
@@ -47,144 +48,222 @@ function log(logger: RedisLeaseLockLogger | undefined, level: keyof RedisLeaseLo
   }
 }
 
-async function acquireLeaseLock(
-  options: Required<Pick<RedisLeaseLockOptions, 'retryDelayMs' | 'waitLogIntervalMs' | 'maxWaitMs'>> &
-    RedisLeaseLockOptions & { lockValue: string; label: string },
-): Promise<void> {
-  const waitStart = Date.now()
-  let lastWaitLogAt = waitStart
-
-  for (;;) {
-    const result = await options.redis.set(options.lockKey, options.lockValue, 'PX', options.lockTtlMs, 'NX')
-
-    if (result === 'OK') {
-      return
-    }
+function toRedisError(error: unknown, message: string): RedisError {
+  return new RedisError({ message: `${message}: ${getErrorMessage(error)}`, cause: error })
+}
 
-    const now = Date.now()
-    const waitedMs = now - waitStart
-    if (waitedMs >= options.maxWaitMs) {
-      throw new Error(`Timed out waiting for ${options.label} (${options.lockKey}) waitedMs=${waitedMs}`)
-    }
+function getNormalizedOptions(options: RedisLeaseLockOptions) {
+  const normalizedLockTtlMs = Math.max(1_000, Math.trunc(options.lockTtlMs))
+  const requestedRefreshIntervalMs = options.refreshIntervalMs ?? Math.floor(normalizedLockTtlMs / 3)
+  const normalizedRefreshIntervalMs = Math.min(
+    Math.max(250, Math.trunc(requestedRefreshIntervalMs)),
+    Math.max(250, normalizedLockTtlMs - 250),
+  )
 
-    if (now - lastWaitLogAt >= options.waitLogIntervalMs) {
-      log(options.logger, 'info', `Waiting for ${options.label} (${options.lockKey}) waitedMs=${waitedMs}`)
-      lastWaitLogAt = now
-    }
+  return {
+    ...options,
+    lockKey: options.lockKey.trim(),
+    lockTtlMs: normalizedLockTtlMs,
+    retryDelayMs: options.retryDelayMs ?? 500,
+    refreshIntervalMs: normalizedRefreshIntervalMs,
+    waitLogIntervalMs: options.waitLogIntervalMs ?? 30_000,
+    maxWaitMs: options.maxWaitMs ?? 45_000,
+    acquiredWaitInfoThresholdMs: options.acquiredWaitInfoThresholdMs ?? 1_000,
+    heldInfoThresholdMs: options.heldInfoThresholdMs ?? 5_000,
+    label: options.label ?? 'redis lease lock',
+  }
+}
 
-    await delay(options.retryDelayMs)
+function resolveRedisConnection(options: RedisLeaseLockOptions): Effect.Effect<IORedis, RedisError, RedisServiceTag> {
+  if (options.redis) {
+    return Effect.succeed(options.redis)
   }
+
+  return Effect.gen(function* () {
+    const redisService = yield* RedisServiceTag
+    return redisService.getConnection()
+  })
 }
 
-async function refreshLeaseLock(options: RedisLeaseLockOptions & { lockValue: string; label: string }): Promise<void> {
-  const refreshed = await options.redis.eval(
-    REFRESH_LOCK_SCRIPT,
-    1,
-    options.lockKey,
-    options.lockValue,
-    options.lockTtlMs.toString(),
-  )
+function acquireLock(
+  redis: IORedis,
+  options: ReturnType<typeof getNormalizedOptions>,
+  lockValue: string,
+): Effect.Effect<void, LockAcquisitionError | RedisError> {
+  return Effect.gen(function* () {
+    const waitStart = yield* Clock.currentTimeMillis
+    let lastWaitLogAt = waitStart
 
-  const refreshedCount = typeof refreshed === 'number' ? refreshed : Number(refreshed)
-  if (refreshedCount === 1) return
-  throw new Error(`${options.label} refresh was rejected for key ${options.lockKey}`)
+    const tryOnce = Effect.gen(function* () {
+      const result = yield* Effect.tryPromise({
+        try: () => redis.set(options.lockKey, lockValue, 'PX', options.lockTtlMs, 'NX'),
+        catch: (error) => toRedisError(error, `Failed to acquire ${options.label} (${options.lockKey})`),
+      })
+
+      if (result === 'OK') {
+        return
+      }
+
+      const now = yield* Clock.currentTimeMillis
+      const waitedMs = now - waitStart
+      if (now - lastWaitLogAt >= options.waitLogIntervalMs) {
+        log(options.logger, 'info', `Waiting for ${options.label} (${options.lockKey}) waitedMs=${waitedMs}`)
+        lastWaitLogAt = now
+      }
+
+      return yield* new LockAcquisitionError({ lockKey: options.lockKey, maxWaitMs: options.maxWaitMs })
+    })
+
+    return yield* Effect.retry(tryOnce, {
+      times: Math.max(0, Math.ceil(options.maxWaitMs / options.retryDelayMs) - 1),
+      schedule: Schedule.fixed(Duration.millis(options.retryDelayMs)),
+    }).pipe(
+      Effect.asVoid,
+      Effect.catchTag('LockAcquisitionError', () =>
+        Effect.fail(new LockAcquisitionError({ lockKey: options.lockKey, maxWaitMs: options.maxWaitMs })),
+      ),
+    )
+  })
 }
 
-async function releaseLeaseLock(options: RedisLeaseLockOptions & { lockValue: string }): Promise<void> {
-  await options.redis.eval(RELEASE_LOCK_SCRIPT, 1, options.lockKey, options.lockValue)
+function refreshLock(
+  redis: IORedis,
+  options: ReturnType<typeof getNormalizedOptions>,
+  lockValue: string,
+): Effect.Effect<void, LockLostError | RedisError> {
+  return Effect.tryPromise({
+    try: () => redis.eval(REFRESH_LOCK_SCRIPT, 1, options.lockKey, lockValue, options.lockTtlMs.toString()),
+    catch: (error) => toRedisError(error, `Failed to refresh ${options.label} (${options.lockKey})`),
+  }).pipe(
+    Effect.flatMap((refreshed) => {
+      const refreshedCount = typeof refreshed === 'number' ? refreshed : Number(refreshed)
+      if (refreshedCount === 1) {
+        return Effect.void
+      }
+      return Effect.fail(new LockLostError({ lockKey: options.lockKey }))
+    }),
+  )
 }
 
-export class LeaseLockLostError extends Error {
-  constructor(message: string) {
-    super(message)
-    this.name = 'LeaseLockLostError'
-  }
+function releaseLock(
+  redis: IORedis,
+  options: ReturnType<typeof getNormalizedOptions>,
+  lockValue: string,
+): Effect.Effect<void, RedisError> {
+  return Effect.asVoid(
+    Effect.tryPromise({
+      try: () => redis.eval(RELEASE_LOCK_SCRIPT, 1, options.lockKey, lockValue),
+      catch: (error) => toRedisError(error, `Failed to release ${options.label} (${options.lockKey})`),
+    }),
+  )
 }
 
-function startLeaseLockRefreshLoop(
-  options: Required<Pick<RedisLeaseLockOptions, 'refreshIntervalMs'>> &
-    RedisLeaseLockOptions & { lockValue: string; label: string },
-  ac: AbortController,
-): () => void {
-  let stopped = false
-
-  const timer = setInterval(() => {
-    if (stopped) return
-    void refreshLeaseLock(options).catch((error: unknown) => {
-      stopped = true
-      clearInterval(timer)
-      const message = `Failed to refresh ${options.label} (${options.lockKey}): ${getErrorMessage(error)}`
-      log(options.logger, 'warn', message)
-      if (!ac.signal.aborted) {
-        ac.abort(new LeaseLockLostError(message))
-      }
-    })
-  }, options.refreshIntervalMs)
+function startRefreshFiber(
+  redis: IORedis,
+  options: ReturnType<typeof getNormalizedOptions>,
+  lockValue: string,
+  abortController: AbortController,
+  lockLost: Deferred.Deferred<never, LockLostError | RedisError>,
+) {
+  const handleLockLoss = (error: LockLostError | RedisError) =>
+    Deferred.fail(lockLost, error).pipe(
+      Effect.andThen(
+        Effect.sync(() => {
+          const message =
+            error._tag === 'LockLostError'
+              ? `${options.label} refresh was rejected for key ${options.lockKey}`
+              : error.message
 
-  timer.unref()
+          log(options.logger, 'warn', message)
+          if (!abortController.signal.aborted) {
+            abortController.abort(error)
+          }
+        }),
+      ),
+      Effect.andThen(Effect.fail(error)),
+    )
 
-  return () => {
-    stopped = true
-    clearInterval(timer)
-  }
+  const refreshProgram = Effect.gen(function* () {
+    for (;;) {
+      yield* Effect.sleep(Duration.millis(options.refreshIntervalMs))
+
+      yield* refreshLock(redis, options, lockValue).pipe(
+        Effect.catchTag('LockLostError', handleLockLoss),
+        Effect.catchTag('RedisError', handleLockLoss),
+      )
+    }
+  })
+
+  return Effect.forkScoped(refreshProgram).pipe(Effect.asVoid)
 }
 
-export async function withRedisLeaseLock<T>(
+export function withLeaseLock<A, E, R>(
+  options: RedisLeaseLockOptions & { redis: IORedis },
+  fn: (signal: AbortSignal) => Effect.Effect<A, E, R>,
+): Effect.Effect<A, E | LockAcquisitionError | LockLostError | RedisError, R>
+export function withLeaseLock<A, E, R>(
   options: RedisLeaseLockOptions,
-  fn: (signal: AbortSignal) => Promise<T>,
-): Promise<T> {
-  const lockKey = options.lockKey.trim()
-  if (!lockKey) {
-    throw new Error('Redis lease lock requires a non-empty lock key')
-  }
+  fn: (signal: AbortSignal) => Effect.Effect<A, E, R>,
+): Effect.Effect<A, E | LockAcquisitionError | LockLostError | RedisError, RedisServiceTag | R> {
+  const normalized = getNormalizedOptions(options)
 
-  const retryDelayMs = options.retryDelayMs ?? 500
-  const refreshIntervalMs = options.refreshIntervalMs ?? 30_000
-  const waitLogIntervalMs = options.waitLogIntervalMs ?? 30_000
-  const maxWaitMs = options.maxWaitMs ?? 45_000
-  const acquiredWaitInfoThresholdMs = options.acquiredWaitInfoThresholdMs ?? 1_000
-  const heldInfoThresholdMs = options.heldInfoThresholdMs ?? 5_000
-  const label = options.label ?? 'redis lease lock'
-
-  const lockValue = crypto.randomUUID()
-  const waitStart = Date.now()
-  await acquireLeaseLock({ ...options, lockKey, lockValue, label, retryDelayMs, waitLogIntervalMs, maxWaitMs })
-  const waitedMs = Date.now() - waitStart
-  if (waitedMs >= acquiredWaitInfoThresholdMs) {
-    log(options.logger, 'info', `Acquired ${label} (${lockKey}) after waiting waitedMs=${waitedMs}`)
-  }
+  return Effect.gen(function* () {
+    if (!normalized.lockKey) {
+      return yield* new LockAcquisitionError({ lockKey: '', maxWaitMs: normalized.maxWaitMs })
+    }
 
-  const ac = new AbortController()
-  const stopRefreshLoop = startLeaseLockRefreshLoop({ ...options, lockKey, lockValue, label, refreshIntervalMs }, ac)
-  const holdStart = Date.now()
+    const redis = yield* resolveRedisConnection(options)
+    const lockValue = yield* Random.nextUUIDv4
+    const waitStart = yield* Clock.currentTimeMillis
 
-  try {
-    const abortPromise = new Promise<never>((_, reject) => {
-      if (ac.signal.aborted) {
-        reject(ac.signal.reason as Error)
-        return
-      }
-      ac.signal.addEventListener(
-        'abort',
-        () => {
-          reject(ac.signal.reason as Error)
-        },
-        { once: true },
+    yield* acquireLock(redis, normalized, lockValue)
+
+    const waitedMs = (yield* Clock.currentTimeMillis) - waitStart
+    if (waitedMs >= normalized.acquiredWaitInfoThresholdMs) {
+      log(
+        normalized.logger,
+        'info',
+        `Acquired ${normalized.label} (${normalized.lockKey}) after waiting waitedMs=${waitedMs}`,
       )
-    })
-    return await Promise.race([fn(ac.signal), abortPromise])
-  } finally {
-    stopRefreshLoop()
-    const heldMs = Date.now() - holdStart
-    if (!ac.signal.aborted) {
-      await releaseLeaseLock({ ...options, lockKey, lockValue }).catch((error: unknown) => {
-        log(options.logger, 'warn', `Failed to release ${label} (${lockKey}): ${getErrorMessage(error)}`)
-      })
-    }
-    if (heldMs >= heldInfoThresholdMs) {
-      log(options.logger, 'info', `Released ${label} (${lockKey}) heldMs=${heldMs}`)
-    } else {
-      log(options.logger, 'debug', `Released ${label} (${lockKey}) heldMs=${heldMs}`)
     }
-  }
+
+    const abortController = new AbortController()
+    const holdStart = yield* Clock.currentTimeMillis
+    const lockLost = yield* Deferred.make<never, LockLostError | RedisError>()
+
+    const cleanup = Effect.sync(() => {
+      if (!abortController.signal.aborted) {
+        abortController.abort()
+      }
+    }).pipe(
+      Effect.andThen(
+        releaseLock(redis, normalized, lockValue).pipe(
+          Effect.catch((error) =>
+            Effect.sync(() => {
+              log(normalized.logger, 'warn', error.message)
+            }),
+          ),
+        ),
+      ),
+      Effect.andThen(
+        Effect.gen(function* () {
+          const heldMs = (yield* Clock.currentTimeMillis) - holdStart
+          if (heldMs >= normalized.heldInfoThresholdMs) {
+            log(normalized.logger, 'info', `Released ${normalized.label} (${normalized.lockKey}) heldMs=${heldMs}`)
+            return
+          }
+
+          log(normalized.logger, 'debug', `Released ${normalized.label} (${normalized.lockKey}) heldMs=${heldMs}`)
+        }),
+      ),
+      Effect.ignore,
+    )
+
+    return yield* Effect.scoped(
+      startRefreshFiber(redis, normalized, lockValue, abortController, lockLost).pipe(
+        Effect.andThen(fn(abortController.signal).pipe(Effect.raceFirst(Deferred.await(lockLost)))),
+        Effect.ensuring(cleanup),
+      ),
+    )
+  })
 }

package/src/redis/runtime-connection.ts

@@ -0,0 +1,20 @@
+import type IORedis from 'ioredis'
+
+import { resolveLotaService } from '../effect/runtime'
+import { RedisServiceTag } from '../effect/services'
+import type { RedisConnectionManager } from './connection'
+
+let currentRedisManager: RedisConnectionManager | null = null
+
+export function configureRuntimeRedisManager(redisManager: RedisConnectionManager): void {
+  currentRedisManager = redisManager
+}
+
+export function clearRuntimeRedisManager(): void {
+  currentRedisManager = null
+}
+
+export function getRuntimeRedisConnection(): IORedis {
+  const redis = currentRedisManager ?? resolveLotaService(RedisServiceTag)
+  return redis.getConnection()
+}

package/src/redis/stream-context.ts

@@ -1,28 +1,13 @@
+import { Context, Schema, Effect, Fiber, Layer, Queue, Stream } from 'effect'
 import type { Redis } from 'ioredis'
 import type { Publisher, Subscriber } from 'resumable-stream/ioredis'
 import { createResumableStreamContext } from 'resumable-stream/ioredis'
 
-import { getRedisConnection } from './connection-accessor'
+import { serverLogger } from '../config/logger'
+import { RedisServiceTag } from '../effect/services'
+import type { RedisConnectionManager } from './connection'
 
-function toSubscriber(client: Redis): Subscriber {
-  const handlers = new Map<string, (message: string) => void>()
-  const messageListener = (channel: string, message: string) => {
-    handlers.get(channel)?.(message)
-  }
-  return {
-    connect: () => Promise.resolve(),
-    subscribe: async (channel, callback) => {
-      if (handlers.size === 0) client.on('message', messageListener)
-      handlers.set(channel, callback)
-      await client.subscribe(channel)
-    },
-    unsubscribe: async (channel) => {
-      handlers.delete(channel)
-      if (handlers.size === 0) client.removeListener('message', messageListener)
-      return client.unsubscribe(channel)
-    },
-  }
-}
+const SUBSCRIBER_QUEUE_CAPACITY = 1024
 
 function toPublisher(client: Redis): Publisher {
   return {
@@ -34,35 +19,96 @@ function toPublisher(client: Redis): Publisher {
   }
 }
 
-let sharedSubscriber: { client: Redis; subscriber: Subscriber } | undefined
+type SharedSubscriberEvent = { readonly channel: string; readonly message: string }
+
+class SharedSubscriberCloseError extends Schema.TaggedErrorClass<SharedSubscriberCloseError>()(
+  'SharedSubscriberCloseError',
+  { message: Schema.String, cause: Schema.optional(Schema.Defect) },
+) {}
+
+export class SharedThreadStreamSubscriberTag extends Context.Service<
+  SharedThreadStreamSubscriberTag,
+  { readonly subscriber: Subscriber }
+>()('@lota-sdk/core/SharedThreadStreamSubscriber') {}
 
-function getSharedSubscriber(): Subscriber {
-  if (!sharedSubscriber) {
+export const SharedThreadStreamSubscriberLive = Layer.effect(
+  SharedThreadStreamSubscriberTag,
+  Effect.gen(function* () {
+    const redisManager = yield* RedisServiceTag
     // Disable enableReadyCheck — the ready check sends INFO which is rejected
     // on connections in subscribe mode, causing unhandled ioredis error events.
-    const client = getRedisConnection().duplicate({ enableReadyCheck: false })
-    client.on('error', () => {}) // prevent [ioredis] Unhandled error event logs
-    sharedSubscriber = { client, subscriber: toSubscriber(client) }
-  }
-  return sharedSubscriber.subscriber
-}
+    const client = redisManager.getConnection().duplicate({ enableReadyCheck: false })
+    client.on('error', (error: unknown) => {
+      serverLogger.warn('Redis subscriber error', { cause: error })
+    })
 
-export async function closeSharedSubscriber(): Promise<void> {
-  if (!sharedSubscriber) return
-  const { client } = sharedSubscriber
-  sharedSubscriber = undefined
-  try {
-    await client.quit()
-  } catch {
-    client.disconnect()
-  }
-}
+    const events = yield* Queue.bounded<SharedSubscriberEvent>(SUBSCRIBER_QUEUE_CAPACITY)
+    const handlers = new Map<string, (message: string) => void>()
+
+    const dispatchFiber = yield* Effect.forkScoped(
+      Stream.fromQueue(events).pipe(
+        Stream.runForEach((event) =>
+          Effect.sync(() => {
+            handlers.get(event.channel)?.(event.message)
+          }),
+        ),
+      ),
+    )
+
+    const messageListener = (channel: string, message: string) => {
+      // Synchronous bounded enqueue — drops (returns false) when consumer is slow,
+      // surfacing back-pressure instead of growing memory unbounded.
+      const accepted = Queue.offerUnsafe(events, { channel, message })
+      if (!accepted) {
+        serverLogger.warn('Redis subscriber queue full, dropping message', { channel })
+      }
+    }
+    client.on('message', messageListener)
+
+    const subscribe = (channel: string, callback: (message: string) => void): Promise<void> => {
+      handlers.set(channel, callback)
+      return client.subscribe(channel).then(() => undefined)
+    }
+
+    const unsubscribe = (channel: string): Promise<void> => {
+      handlers.delete(channel)
+      return client.unsubscribe(channel).then(() => undefined)
+    }
+
+    const subscriber: Subscriber = {
+      connect: () => Promise.resolve(),
+      subscribe: (channel, callback) => subscribe(channel, callback),
+      unsubscribe: (channel) => unsubscribe(channel),
+    }
+
+    yield* Effect.addFinalizer(() =>
+      Effect.gen(function* () {
+        handlers.clear()
+        client.removeListener('message', messageListener)
+        yield* Fiber.interrupt(dispatchFiber)
+        yield* Queue.shutdown(events)
+        yield* Effect.tryPromise({
+          try: () => client.quit(),
+          catch: (cause) =>
+            new SharedSubscriberCloseError({ message: 'Failed to quit shared stream subscriber.', cause }),
+        }).pipe(
+          Effect.catch(() =>
+            Effect.sync(() => {
+              client.disconnect()
+            }),
+          ),
+        )
+      }),
+    )
+
+    return { subscriber }
+  }),
+)
 
-export function createThreadResumableContext() {
-  const redis = getRedisConnection()
-  return createResumableStreamContext({
-    waitUntil: null,
-    subscriber: getSharedSubscriber(),
-    publisher: toPublisher(redis),
-  })
+export function createThreadResumableContext(
+  redisManager: Pick<RedisConnectionManager, 'getConnection'>,
+  subscriber: Subscriber,
+) {
+  const redis = redisManager.getConnection()
+  return createResumableStreamContext({ waitUntil: null, subscriber, publisher: toPublisher(redis) })
 }

package/src/runtime/agent-identity-overrides.ts

@@ -1,4 +1,4 @@
-import { agentDisplayNames } from '../config/agent-defaults'
+import { getAgentDisplayNames } from '../config/agent-defaults'
 import { asRecord, readOptionalString } from './thread-chat-helpers'
 
 interface RuntimeAgentIdentityOverrides {
@@ -58,5 +58,5 @@ export function resolveRuntimeAgentDisplayName(overrides: RuntimeAgentIdentityOv
     return override
   }
 
-  return agentDisplayNames[agentId] ?? agentId
+  return getAgentDisplayNames()[agentId] ?? agentId
 }

package/src/runtime/agent-runtime-policy.ts

@@ -1,4 +1,5 @@
 import type {
+  ChatMode,
   ExecutionMode,
   OwnershipDispatchContext,
   PlanArtifactSubmission,
@@ -8,7 +9,6 @@ import type {
 
 import { getLeadAgentId } from '../config/agent-defaults'
 import { resolveOnboardingOwnerAgentId } from '../config/thread-defaults'
-import type { ChatMode } from './agent-types'
 export interface AgentRuntimeConfig<TAgent extends string> {
   id: TAgent
   displayName: string
@@ -162,10 +162,13 @@ export function buildThreadAgentToolPolicy<TAgent extends string, TSkill extends
   linearInstalled: boolean
   githubInstalled: boolean
   provideRepoTool: boolean
+  leadAgentId?: TAgent
+  onboardingOwnerAgentId?: TAgent
   getAgentSkills: (agentId: TAgent, mode: ChatMode) => TSkill[]
 }): AgentToolPolicy<TSkill> {
   const resolvedMode = params.mode ?? toChatMode(params.threadType)
-  const onboardingOwnerAgentId = resolveOnboardingOwnerAgentId(getLeadAgentId()) as TAgent
+  const leadAgentId = params.leadAgentId ?? (getLeadAgentId() as TAgent)
+  const onboardingOwnerAgentId = params.onboardingOwnerAgentId ?? (resolveOnboardingOwnerAgentId(leadAgentId) as TAgent)
   const skills = resolveActiveAgentSkills({
     agentId: params.agentId,
     threadType: params.threadType,

package/src/runtime/agent-stream-helpers.ts

@@ -1,7 +1,9 @@
 import type { ChatMessage } from '@lota-sdk/shared'
 import type { LanguageModelUsage, UIMessageStreamOptions } from 'ai'
+import { Duration, Effect, Exit, Scope } from 'effect'
 
-import { agentDisplayNames, getLeadAgentDisplayName } from '../config/agent-defaults'
+import { getAgentDisplayNames, getLeadAgentDisplayName } from '../config/agent-defaults'
+import { nowEpochMillis } from '../utils/date-time'
 import { readRecord as _readRecord } from '../utils/string'
 
 export function readFiniteNumber(value: unknown): number | undefined {
@@ -32,7 +34,7 @@ export function createAgentMessageMetadata(params: {
 }): NonNullable<UIMessageStreamOptions<ChatMessage>['messageMetadata']> {
   return ({ part }) => {
     if (part.type === 'start') {
-      return { agentId: params.agentId, agentName: params.agentName, createdAt: Date.now() }
+      return { agentId: params.agentId, agentName: params.agentName, createdAt: nowEpochMillis() }
     }
 
     if (part.type === 'finish') {
@@ -100,13 +102,24 @@ export function createServerRunAbortController(externalAbortSignal?: AbortSignal
 export function createTimedAbortSignal(parentSignal: AbortSignal, timeoutMs: number) {
   const controller = new AbortController()
   let didTimeout = false
+  let disposed = false
   const abortFromParent = () => {
     controller.abort((parentSignal as AbortSignal & { reason?: unknown }).reason)
   }
-  const timeoutId = setTimeout(() => {
-    didTimeout = true
-    controller.abort(new Error(`Timed out after ${timeoutMs}ms`))
-  }, timeoutMs)
+
+  // Own a scope so the timeout fiber is cleaned up via Scope.close() on dispose,
+  // matching Effect v4 best practices (forkScoped + scope-bound finalizers).
+  const scope = Scope.makeUnsafe()
+  const timeoutEffect = Effect.sleep(Duration.millis(timeoutMs)).pipe(
+    Effect.andThen(
+      Effect.sync(() => {
+        if (disposed || controller.signal.aborted) return
+        didTimeout = true
+        controller.abort(new Error(`Timed out after ${timeoutMs}ms`))
+      }),
+    ),
+  )
+  Effect.runFork(Scope.provide(Effect.forkScoped(timeoutEffect), scope))
 
   if (parentSignal.aborted) {
     abortFromParent()
@@ -118,14 +131,16 @@ export function createTimedAbortSignal(parentSignal: AbortSignal, timeoutMs: num
     signal: controller.signal,
     didTimeout: () => didTimeout,
     dispose: () => {
-      clearTimeout(timeoutId)
+      if (disposed) return
+      disposed = true
       parentSignal.removeEventListener('abort', abortFromParent)
+      void Effect.runPromise(Scope.close(scope, Exit.void).pipe(Effect.catchCause(() => Effect.void)))
     },
   }
 }
 
 export function buildSpecialistTaskMessage(params: { agentId: string; task: string }): ChatMessage {
-  const displayName = agentDisplayNames[params.agentId] ?? params.agentId
+  const displayName = getAgentDisplayNames()[params.agentId] ?? params.agentId
   const leadAgentDisplayName = getLeadAgentDisplayName()
   return {
     id: Bun.randomUUIDv7(),
@@ -133,6 +148,6 @@ export function buildSpecialistTaskMessage(params: { agentId: string; task: stri
     parts: [
       { type: 'text', text: [`${leadAgentDisplayName} request for ${displayName}:`, params.task.trim()].join('\n') },
     ],
-    metadata: { createdAt: Date.now() },
+    metadata: { createdAt: nowEpochMillis() },
   }
 }