@lota-sdk/core 0.4.8 → 0.4.10

package/src/runtime/team-consultation/team-consultation-orchestrator.ts

@@ -0,0 +1,433 @@
+import { ConsultTeamArgsSchema, withMessageCreatedAt } from '@lota-sdk/shared'
+import type { ChatMessage, ConsultTeamResultData } from '@lota-sdk/shared'
+import { convertToModelMessages, tool as createTool } from 'ai'
+import { Schema, Deferred, Effect, Exit, Fiber, Queue, Ref, Scope } from 'effect'
+
+import { getAgentDisplayNames, getTeamConsultParticipants } from '../../config/agent-defaults'
+import { nowEpochMillis } from '../../utils/date-time'
+import { createTimedAbortSignal } from '../agent-stream-helpers'
+import { buildModelInputMessagesWithUploadMetadata, buildReadableUploadMetadataText } from '../chat-attachments'
+import type { ReadableUploadMetadataLike } from '../chat-attachments'
+import type { RepoSectionName } from '../indexed-repositories-policy'
+import { extractMessageText } from '../thread-chat-helpers'
+import { buildTeamConsultationFailureMessage } from './team-consultation-prompts'
+
+export type DefaultRepoSections = RepoSectionName[]
+const TEAM_CONSULTATION_TIMEOUT_MS = 90_000
+
+class TeamConsultationError extends Schema.TaggedErrorClass<TeamConsultationError>()('TeamConsultationError', {
+  message: Schema.String,
+  cause: Schema.optional(Schema.Defect),
+}) {}
+
+function buildSnapshot(responses: ConsultTeamResultData['responses']): ConsultTeamResultData {
+  return { responses: responses.map((response) => ({ ...response })) }
+}
+
+function getConsultTeamOutput(output: unknown): ConsultTeamResultData | undefined {
+  if (output && typeof output === 'object' && Array.isArray((output as { responses?: unknown }).responses)) {
+    return output as ConsultTeamResultData
+  }
+
+  if (Array.isArray(output)) {
+    for (let index = output.length - 1; index >= 0; index -= 1) {
+      const candidate = getConsultTeamOutput(output[index])
+      if (candidate) return candidate
+    }
+  }
+
+  return undefined
+}
+
+function findLastUserMessage(
+  messages: ChatMessage[],
+  predicate: (message: ChatMessage) => boolean,
+): ChatMessage | null {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index]
+    if (predicate(message)) {
+      return message
+    }
+  }
+
+  return null
+}
+
+function selectTeamConsultationContextMessages(messages: ChatMessage[], latestUserMessageId: string): ChatMessage[] {
+  const latestUserMessage =
+    findLastUserMessage(messages, (message) => message.id === latestUserMessageId && message.role === 'user') ??
+    findLastUserMessage(messages, (message) => message.role === 'user')
+
+  return latestUserMessage ? [latestUserMessage] : []
+}
+
+interface ParticipantObserver {
+  run<T>(fn: () => T | Promise<T>): Promise<T>
+  recordError?: (error: unknown) => void
+  recordAbort?: (error: unknown) => void
+}
+
+export interface TeamConsultationParticipantRunner {
+  buildParticipantAgent(
+    agentId: string,
+    params: {
+      task: string
+      systemWorkspaceDetails?: string
+      preSeededMemoriesSection?: string
+      retrievedKnowledgeSection?: string
+    },
+  ): Promise<{
+    agent: {
+      generate(params: Record<string, unknown>): Promise<{ text: string }>
+      stream(
+        params: Record<string, unknown>,
+      ): Promise<{
+        consumeStream(): unknown
+        toUIMessageStream(options: Record<string, unknown>): ReadableStream<unknown>
+      }>
+    }
+    observer: ParticipantObserver
+  }>
+}
+
+export interface CreateConsultTeamToolParams {
+  historyMessages: ChatMessage[]
+  latestUserMessageId: string
+  availableUploads: ReadableUploadMetadataLike[]
+  defaultRepoSectionsByAgent: Record<string, DefaultRepoSections | undefined>
+  systemWorkspaceDetails?: string
+  getPreSeededMemoriesSection: (agentId: string) => Promise<string | undefined>
+  retrievedKnowledgeSection?: string
+  displayNamesById?: Partial<Record<string, string>>
+  abortSignal: AbortSignal
+  participantRunner: TeamConsultationParticipantRunner
+  onReadError?: (agentId: string, error: unknown) => void
+}
+
+/** Sentinel pushed into the snapshot queue to signal that all workers are done. */
+const DONE = Symbol('done')
+
+type ConsultTeamSnapshotItem = ConsultTeamResultData | typeof DONE
+
+interface ConsultTeamStreamResources {
+  snapshotQueue: Queue.Queue<ConsultTeamSnapshotItem>
+  workerFiber: Fiber.Fiber<unknown, unknown>
+}
+
+function createConsultTeamStreamResources(params: {
+  task: string
+  uploadMetadataText: string
+  teamConsultParticipants: readonly string[]
+  resolveDisplayName: (agentId: string) => string
+  historyMessages: ChatMessage[]
+  latestUserMessageId: string
+  availableUploads: ReadableUploadMetadataLike[]
+  systemWorkspaceDetails?: string
+  getPreSeededMemoriesSection: (agentId: string) => Promise<string | undefined>
+  retrievedKnowledgeSection?: string
+  abortSignal: AbortSignal
+  participantRunner: TeamConsultationParticipantRunner
+  onReadError?: (agentId: string, error: unknown) => void
+}): Effect.Effect<ConsultTeamStreamResources, TeamConsultationError> {
+  return Effect.gen(function* () {
+    const initialResponses: ConsultTeamResultData['responses'] = params.teamConsultParticipants.map((agentId) => ({
+      agentId,
+      agentName: params.resolveDisplayName(agentId),
+      status: 'running',
+    }))
+
+    const snapshotQueue = yield* Queue.bounded<ConsultTeamSnapshotItem>(params.teamConsultParticipants.length + 2)
+    const responsesRef = yield* Ref.make([...initialResponses])
+
+    const pushSnapshot = Effect.flatMap(Ref.get(responsesRef), (current) =>
+      Queue.offer(snapshotQueue, buildSnapshot(current)),
+    )
+
+    const runParticipantEffect = (agentId: string, index: number) => {
+      const agentName = params.resolveDisplayName(agentId)
+      const timedAbort = createTimedAbortSignal(params.abortSignal, TEAM_CONSULTATION_TIMEOUT_MS)
+      const toTeamConsultationError = (message: string, cause?: unknown) =>
+        new TeamConsultationError({ message, cause })
+
+      const generateAndRecord = Effect.gen(function* () {
+        const preSeededMemoriesSection = yield* Effect.tryPromise({
+          try: () => params.getPreSeededMemoriesSection(agentId),
+          catch: (error) => toTeamConsultationError(`Failed to load pre-seeded memories for ${agentName}.`, error),
+        })
+
+        const { agent, observer } = yield* Effect.tryPromise({
+          try: () =>
+            params.participantRunner.buildParticipantAgent(agentId, {
+              task: params.task,
+              systemWorkspaceDetails: params.systemWorkspaceDetails,
+              preSeededMemoriesSection,
+              retrievedKnowledgeSection: params.retrievedKnowledgeSection,
+            }),
+          catch: (error) => toTeamConsultationError(`Failed to build team participant agent for ${agentName}.`, error),
+        })
+
+        const modelMessages = yield* Effect.tryPromise({
+          try: () =>
+            convertToModelMessages(
+              buildModelInputMessagesWithUploadMetadata({
+                messages: selectTeamConsultationContextMessages(params.historyMessages, params.latestUserMessageId),
+                latestUserMessageId: params.latestUserMessageId,
+                uploadMetadataText: params.uploadMetadataText,
+              }),
+              { ignoreIncompleteToolCalls: true },
+            ),
+          catch: (error) => toTeamConsultationError(`Failed to build model messages for ${agentName}.`, error),
+        })
+
+        const result = yield* Effect.tryPromise({
+          try: () =>
+            observer.run(() =>
+              agent.generate({
+                messages: modelMessages,
+                abortSignal: timedAbort.signal,
+                timeout: TEAM_CONSULTATION_TIMEOUT_MS,
+              }),
+            ),
+          catch: (error) => {
+            if (params.abortSignal.aborted || timedAbort.signal.aborted) {
+              observer.recordAbort?.(error)
+            } else {
+              observer.recordError?.(error)
+            }
+            return toTeamConsultationError(`Team participant ${agentName} failed.`, error)
+          },
+        })
+
+        const responseText = result.text.trim()
+        if (!responseText) {
+          return yield* new TeamConsultationError({
+            message: `Team participant ${agentName} did not produce a response.`,
+          })
+        }
+
+        const message = withMessageCreatedAt(
+          {
+            id: Bun.randomUUIDv7(),
+            role: 'assistant',
+            parts: [{ type: 'text', text: responseText }],
+            metadata: { agentId, agentName },
+          } satisfies ChatMessage,
+          nowEpochMillis(),
+        )
+
+        yield* Ref.update(responsesRef, (prev) => {
+          const next = [...prev]
+          next[index] = {
+            agentId,
+            agentName,
+            status: 'complete',
+            summary: extractMessageText(message).trim() || undefined,
+            message,
+          }
+          return next
+        })
+        yield* pushSnapshot
+      })
+
+      return generateAndRecord.pipe(
+        Effect.catch((error) => {
+          // Parent abort is fatal — re-fail so structured concurrency interrupts siblings.
+          if (params.abortSignal.aborted) {
+            return Effect.fail(error)
+          }
+
+          return Ref.update(responsesRef, (prev) => {
+            const next = [...prev]
+            next[index] = {
+              agentId,
+              agentName,
+              status: 'error',
+              error: buildTeamConsultationFailureMessage(
+                agentName,
+                TEAM_CONSULTATION_TIMEOUT_MS,
+                timedAbort.didTimeout(),
+                error,
+              ),
+            }
+            return next
+          }).pipe(Effect.andThen(pushSnapshot))
+        }),
+        Effect.ensuring(Effect.sync(() => timedAbort.dispose())),
+      )
+    }
+
+    const workersEffect = Effect.forEach(
+      params.teamConsultParticipants,
+      (agentId, index) => runParticipantEffect(agentId, index),
+      { concurrency: 'unbounded' },
+    ).pipe(Effect.ensuring(Queue.offer(snapshotQueue, DONE)))
+
+    yield* pushSnapshot
+    const workerFiber = yield* Effect.forkChild(workersEffect)
+
+    return { snapshotQueue, workerFiber }
+  })
+}
+
+class ConsultTeamSnapshotIterable implements AsyncIterableIterator<ConsultTeamResultData> {
+  private readonly scope: Scope.Closeable
+  private readonly resourcesDeferred: Deferred.Deferred<ConsultTeamStreamResources, TeamConsultationError>
+  private readonly buildEffect: Effect.Effect<ConsultTeamStreamResources, TeamConsultationError>
+  private initStarted = false
+  private closed = false
+  private completed = false
+
+  constructor(params: CreateConsultTeamToolParams, task: string) {
+    const teamConsultParticipants = getTeamConsultParticipants()
+    const uploadMetadataText = buildReadableUploadMetadataText(params.availableUploads)
+    const agentDisplayNames = getAgentDisplayNames()
+    const resolveDisplayName = (agentId: string) => {
+      if (params.displayNamesById && Object.hasOwn(params.displayNamesById, agentId)) {
+        const override = params.displayNamesById[agentId]
+        if (override !== undefined) {
+          return override
+        }
+      }
+
+      return agentDisplayNames[agentId] ?? agentId
+    }
+
+    this.scope = Scope.makeUnsafe()
+    this.resourcesDeferred = Deferred.makeUnsafe<ConsultTeamStreamResources, TeamConsultationError>()
+    this.buildEffect = createConsultTeamStreamResources({
+      task,
+      uploadMetadataText,
+      teamConsultParticipants,
+      resolveDisplayName,
+      historyMessages: params.historyMessages,
+      latestUserMessageId: params.latestUserMessageId,
+      availableUploads: params.availableUploads,
+      systemWorkspaceDetails: params.systemWorkspaceDetails,
+      getPreSeededMemoriesSection: params.getPreSeededMemoriesSection,
+      retrievedKnowledgeSection: params.retrievedKnowledgeSection,
+      abortSignal: params.abortSignal,
+      participantRunner: params.participantRunner,
+      onReadError: params.onReadError,
+    })
+  }
+
+  /**
+   * Acquire-release: on first call, build the stream resources and register
+   * cleanup as a finalizer in the iterable's scope. Subsequent calls await the
+   * cached `Deferred`. If init fails, no finalizer is registered, so closing
+   * the scope is a no-op for the leaked-resource path.
+   */
+  private acquireResourcesEffect(): Effect.Effect<ConsultTeamStreamResources, TeamConsultationError> {
+    if (this.initStarted) {
+      return Deferred.await(this.resourcesDeferred)
+    }
+    this.initStarted = true
+
+    const acquire = Effect.acquireRelease(this.buildEffect, ({ snapshotQueue, workerFiber }) =>
+      Fiber.interrupt(workerFiber).pipe(Effect.andThen(Queue.shutdown(snapshotQueue))),
+    ).pipe(Scope.provide(this.scope))
+
+    return acquire.pipe(
+      Effect.exit,
+      Effect.flatMap((exit) =>
+        Deferred.done(this.resourcesDeferred, exit).pipe(Effect.andThen(Deferred.await(this.resourcesDeferred))),
+      ),
+    )
+  }
+
+  /** Close the scope idempotently. Runs cleanup finalizers iff init succeeded. */
+  private closeScopeEffect(): Effect.Effect<void, never> {
+    return Scope.close(this.scope, Exit.void).pipe(Effect.catchCause(() => Effect.void))
+  }
+
+  [Symbol.asyncIterator](): AsyncIterableIterator<ConsultTeamResultData> {
+    return this
+  }
+
+  next(): Promise<IteratorResult<ConsultTeamResultData>> {
+    if (this.closed) {
+      return Promise.resolve({ done: true, value: undefined as never })
+    }
+
+    return Effect.runPromise(
+      Effect.gen(
+        function* (this: ConsultTeamSnapshotIterable) {
+          const { snapshotQueue } = yield* this.acquireResourcesEffect()
+
+          if (this.completed) {
+            return { done: true, value: undefined as never }
+          }
+
+          const item = yield* Queue.take(snapshotQueue)
+          if (item === DONE) {
+            this.completed = true
+            this.closed = true
+            yield* this.closeScopeEffect()
+            return { done: true, value: undefined as never }
+          }
+
+          return { done: false, value: item }
+        }.bind(this),
+      ).pipe(
+        Effect.tapCause(() =>
+          Effect.sync(() => {
+            this.closed = true
+          }).pipe(Effect.andThen(this.closeScopeEffect())),
+        ),
+      ),
+    )
+  }
+
+  return(): Promise<IteratorResult<ConsultTeamResultData>> {
+    this.closed = true
+    return Effect.runPromise(this.closeScopeEffect().pipe(Effect.as({ done: true, value: undefined as never })))
+  }
+
+  throw(error: unknown): Promise<never> {
+    this.closed = true
+    return Effect.runPromise(this.closeScopeEffect().pipe(Effect.andThen(Effect.fail(error as never))))
+  }
+}
+
+export function createConsultTeamTool(params: CreateConsultTeamToolParams) {
+  const teamConsultParticipants = getTeamConsultParticipants()
+  const agentDisplayNames = getAgentDisplayNames()
+  const resolveDisplayName = (agentId: string) => {
+    if (params.displayNamesById && Object.hasOwn(params.displayNamesById, agentId)) {
+      const override = params.displayNamesById[agentId]
+      if (override !== undefined) {
+        return override
+      }
+    }
+
+    return agentDisplayNames[agentId] ?? agentId
+  }
+  const participantNames = teamConsultParticipants
+    .map((agentId) => resolveDisplayName(agentId))
+    .filter((value) => value.trim().length > 0)
+  const participantSummary =
+    participantNames.length > 0 ? participantNames.join(', ') : 'the configured specialist participants'
+
+  return createTool({
+    description: `Consult the specialist team in parallel before replying. Use this when the answer benefits from structured input across ${participantSummary}.`,
+    inputSchema: ConsultTeamArgsSchema,
+    execute: ({ task }) => new ConsultTeamSnapshotIterable(params, task),
+    toModelOutput: ({ output }) => {
+      const result = getConsultTeamOutput(output)
+      const summaryLines =
+        result?.responses
+          .map((response) => {
+            const summary =
+              typeof response.error === 'string' && response.error.trim().length > 0
+                ? response.error.trim()
+                : typeof response.summary === 'string' && response.summary.trim().length > 0
+                  ? response.summary.trim()
+                  : 'No response.'
+            return `${response.agentName}: ${summary}`
+          })
+          .join('\n') ?? 'Team consultation completed.'
+
+      return { type: 'text', value: summaryLines }
+    },
+  })
+}

package/src/runtime/{team-consultation-prompts.ts → team-consultation/team-consultation-prompts.ts}

@@ -1,7 +1,11 @@
-import { agentDisplayNames, getLeadAgentDisplayName } from '../config/agent-defaults'
+import { getAgentDisplayNames, getLeadAgentDisplayName } from '../../config/agent-defaults'
+
+function resolveDisplayName(agentId: string): string {
+  return getAgentDisplayNames()[agentId] ?? agentId
+}
 
 export function buildTeamConsultationResponseGuard(params: { agentId: string; task: string }) {
-  const agentName = agentDisplayNames[params.agentId] ?? params.agentId
+  const agentName = resolveDisplayName(params.agentId)
   const leadAgentDisplayName = getLeadAgentDisplayName()
   const mentorConstraint =
     params.agentId === 'mentor'

package/src/runtime/thread-chat-helpers.ts

@@ -1,7 +1,7 @@
 import { toTimestamp } from '@lota-sdk/shared'
 import type { ChatMessage } from '@lota-sdk/shared'
 
-import { agentDisplayNames, resolveAgentNameAlias } from '../config/agent-defaults'
+import { getAgentDisplayNames, resolveAgentNameAlias } from '../config/agent-defaults'
 import type { ChatMessageLike, ReadableUploadMetadataLike } from './chat-types'
 
 export interface ThreadHistoryMessage {
@@ -35,7 +35,7 @@ function getAgentName(message: ChatMessageLike): string | undefined {
   const value = (metadata as Record<string, unknown>).agentName
   if (typeof value !== 'string' || !value.trim()) return undefined
   const resolvedAgentName = resolveAgentNameAlias(value)
-  return resolvedAgentName ? (agentDisplayNames[resolvedAgentName] ?? value.trim()) : value.trim()
+  return resolvedAgentName ? (getAgentDisplayNames()[resolvedAgentName] ?? value.trim()) : value.trim()
 }
 
 export function extractMessageText(message: ChatMessageLike): string {

package/src/runtime/thread-plan-turn.ts

@@ -1,6 +1,7 @@
 import { SUBMIT_PLAN_TURN_RESULT_TOOL_NAME, withMessageCreatedAt } from '@lota-sdk/shared'
 import type { ChatMessage, PlanArtifactSubmission, PlanNodeRunRecord, PlanNodeSpecRecord } from '@lota-sdk/shared'
 
+import { nowEpochMillis } from '../utils/date-time'
 import { buildCompletionCheckStructuredOutputHints } from './agent-runtime-policy'
 import { mergeInstructionSections } from './instruction-sections'
 
@@ -125,6 +126,6 @@ export function buildPlanTurnPromptMessage(planTurn: ThreadPlanTurnContext): Cha
       ],
       metadata: { trigger: 'plan-turn', planRunId: planTurn.runId, planNodeId: planTurn.nodeId },
     },
-    Date.now(),
+    nowEpochMillis(),
   )
 }