@lota-sdk/core 0.1.5

package/src/runtime/plugin-types.ts

@@ -0,0 +1,10 @@
+export interface LotaPluginContributions {
+  envKeys: readonly string[]
+  schemaFiles: readonly (string | URL)[]
+}
+
+export interface LotaPlugin<TServices = unknown, TTools = unknown> {
+  services: TServices
+  tools?: TTools
+  contributions: LotaPluginContributions
+}

package/src/runtime/retrieval-adapters.ts

@@ -0,0 +1,25 @@
+interface ScopedRetrievalTask<TCandidate> {
+  scopeTag: string
+  retrieve: () => Promise<TCandidate[]>
+}
+
+interface ScopedRetrievalResult<TCandidate> {
+  scopeTag: string
+  candidates: TCandidate[]
+}
+
+export async function executeScopedRetrieval<TCandidate>(
+  tasks: ScopedRetrievalTask<TCandidate>[],
+): Promise<ScopedRetrievalResult<TCandidate>[]> {
+  return await Promise.all(tasks.map(async (task) => ({ scopeTag: task.scopeTag, candidates: await task.retrieve() })))
+}
+
+export function countScopedRetrievalCandidates<TCandidate>(scoped: ScopedRetrievalResult<TCandidate>[]): number {
+  return scoped.reduce((sum, entry) => sum + entry.candidates.length, 0)
+}
+
+export function scopedRetrievalToMap<TCandidate>(
+  scoped: ScopedRetrievalResult<TCandidate>[],
+): Map<string, TCandidate[]> {
+  return new Map(scoped.map((entry) => [entry.scopeTag, entry.candidates]))
+}

package/src/runtime/retrieval-pipeline.ts

@@ -0,0 +1,3 @@
+export function resolveCandidateLimit(params: { limit: number; multiplier: number; minimum: number }): number {
+  return Math.max(params.limit * params.multiplier, params.minimum)
+}

package/src/runtime/runtime-extensions.ts

@@ -0,0 +1,154 @@
+import type { ToolSet } from 'ai'
+
+import type { RecordIdRef } from '../db/record-id'
+import type { ReadableUploadMetadata } from '../services/attachment.service'
+
+export interface LotaRuntimeBackgroundCursor {
+  createdAt: Date
+  id: string
+}
+
+export type LotaRuntimeBackgroundCursorKind = 'regular-chat-digest' | 'skill-extraction'
+
+export interface LotaRuntimeWorkspaceLifecycleState {
+  bootstrapActive: boolean
+  bootstrapCompletedAt?: Date | null
+}
+
+export interface LotaRuntimeWorkspaceProjectionState {
+  workspaceName: string
+  summaryBlock?: string
+  structuredProfile?: Record<string, unknown>
+}
+
+export interface LotaRuntimeProfileProjection {
+  summaryBlock?: string
+  structuredPatch?: Record<string, unknown>
+}
+
+export interface LotaRuntimeWorkspaceProvider {
+  getWorkspace(workspaceId: RecordIdRef): Promise<Record<string, unknown>>
+  getLifecycleState?(
+    workspace: Record<string, unknown>,
+  ): Promise<LotaRuntimeWorkspaceLifecycleState> | LotaRuntimeWorkspaceLifecycleState
+  readProfileProjectionState?(
+    workspace: Record<string, unknown>,
+  ): Promise<LotaRuntimeWorkspaceProjectionState | void> | LotaRuntimeWorkspaceProjectionState | void
+  buildPromptSummary?(workspaceId: RecordIdRef): Promise<string | undefined>
+  listRecentDomainEvents?(workspaceId: RecordIdRef, limit?: number): Promise<Array<Record<string, unknown>>>
+  hasActiveKnowledgeSources?(workspaceId: string): Promise<boolean>
+  buildRetrievedKnowledgeSection?(params: {
+    workspaceId: string
+    userId: string
+    query: string
+  }): Promise<string | undefined>
+  applyProfileProjection?(workspaceId: RecordIdRef, projection: LotaRuntimeProfileProjection): Promise<void>
+  getBackgroundCursor?(
+    kind: LotaRuntimeBackgroundCursorKind,
+    workspaceId: RecordIdRef,
+  ): Promise<LotaRuntimeBackgroundCursor | null>
+  setBackgroundCursor?(
+    kind: LotaRuntimeBackgroundCursorKind,
+    workspaceId: RecordIdRef,
+    cursor: LotaRuntimeBackgroundCursor,
+  ): Promise<void>
+}
+
+export interface LotaRuntimeIndexedRepositoriesContext {
+  provideRepoTool: boolean
+  defaultSectionsByAgent: Record<string, string[]>
+  dataSourceContextByAgent?: Record<string, string>
+  context?: string
+}
+
+export interface LotaRuntimeTeamThinkToolsParams {
+  agentId: string
+  workspaceId: RecordIdRef
+  userId: RecordIdRef
+  workspaceIdString: string
+  workstreamId: RecordIdRef
+  githubInstalled: boolean
+  provideRepoTool: boolean
+  availableUploads: ReadableUploadMetadata[]
+  defaultRepoSections?: string[]
+  context?: unknown
+  toolProviders?: ToolSet
+}
+
+export interface LotaRuntimeTurnHooks {
+  buildContext?: (params: Record<string, unknown>) => Promise<Record<string, unknown> | void>
+  afterTurn?: (params: Record<string, unknown>) => Promise<void>
+  resolveAgent?: (params: Record<string, unknown>) => Promise<Record<string, unknown> | void>
+  buildExtraInstructionSections?: (params: Record<string, unknown>) => Promise<string[] | void>
+}
+
+export interface LotaRuntimeAdapters {
+  services?: { workspaceProvider?: LotaRuntimeWorkspaceProvider }
+  workstream?: {
+    buildIndexedRepositoriesContext?: (workspaceId: string) => Promise<LotaRuntimeIndexedRepositoriesContext>
+    buildTeamThinkAgentTools?: (params: LotaRuntimeTeamThinkToolsParams) => Promise<{ tools: ToolSet }>
+  }
+  queues?: {
+    enqueuePostChatOrgAction?: (job: Record<string, unknown>) => Promise<void> | void
+    enqueueOnboardingRepoIndexFollowUp?: (job: Record<string, unknown>) => Promise<void> | void
+  }
+  workers?: {
+    connectPluginDatabases?: () => Promise<void>
+    withWorkspaceMemoryLock?: <T>(workspaceId: string, fn: () => Promise<T>) => Promise<T>
+  }
+}
+
+interface RuntimeExtensionsState {
+  adapters: LotaRuntimeAdapters
+  turnHooks: LotaRuntimeTurnHooks
+  toolProviders: ToolSet
+  extraWorkers: Record<string, unknown>
+}
+
+const EMPTY_TOOLS = {} as ToolSet
+
+let runtimeExtensionsState: RuntimeExtensionsState = {
+  adapters: {},
+  turnHooks: {},
+  toolProviders: EMPTY_TOOLS,
+  extraWorkers: {},
+}
+
+export function configureRuntimeExtensions(params?: {
+  adapters?: LotaRuntimeAdapters
+  turnHooks?: LotaRuntimeTurnHooks
+  toolProviders?: ToolSet
+  extraWorkers?: Record<string, unknown>
+}): void {
+  runtimeExtensionsState = {
+    adapters: params?.adapters ?? {},
+    turnHooks: params?.turnHooks ?? {},
+    toolProviders: params?.toolProviders ?? EMPTY_TOOLS,
+    extraWorkers: params?.extraWorkers ?? {},
+  }
+}
+
+export function getRuntimeAdapters(): LotaRuntimeAdapters {
+  return runtimeExtensionsState.adapters
+}
+
+export function getTurnHooks(): LotaRuntimeTurnHooks {
+  return runtimeExtensionsState.turnHooks
+}
+
+export function getToolProviders(): ToolSet {
+  return runtimeExtensionsState.toolProviders
+}
+
+export function getConfiguredPluginDatabaseConnector(): (() => Promise<void>) | undefined {
+  return runtimeExtensionsState.adapters.workers?.connectPluginDatabases
+}
+
+export async function withConfiguredWorkspaceMemoryLock<T>(workspaceId: string, fn: () => Promise<T>): Promise<T> {
+  const adapter = runtimeExtensionsState.adapters.workers?.withWorkspaceMemoryLock
+  if (!adapter) {
+    return await fn()
+  }
+
+  return await adapter(workspaceId, fn)
+}

package/src/runtime/skill-extraction-policy.ts

@@ -0,0 +1,3 @@
+export function shouldEnqueueSkillExtraction(params: { onboardingActive: boolean }): boolean {
+  return !params.onboardingActive
+}

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

@@ -0,0 +1,245 @@
+import { withMessageCreatedAt } from '@lota-sdk/shared/runtime/chat-message-metadata'
+import type { ChatMessage } from '@lota-sdk/shared/schemas/chat-message'
+import { ConsultTeamArgsSchema } from '@lota-sdk/shared/schemas/tools'
+import type { ConsultTeamResultData } from '@lota-sdk/shared/schemas/tools'
+import { convertToModelMessages, readUIMessageStream, tool as createTool } from 'ai'
+
+import { agentDisplayNames, teamConsultParticipants } from '../config/agent-defaults'
+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 { buildTeamConsultationFailureMessage } from './team-consultation-prompts'
+import { extractMessageText } from './workstream-chat-helpers'
+import type { ReasoningProfileName } from './workstream-routing-policy'
+
+export type DefaultRepoSections = RepoSectionName[]
+const TEAM_CONSULTATION_TIMEOUT_MS = 90_000
+
+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
+}
+
+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
+      reasoningProfile: ReasoningProfileName
+      systemWorkspaceDetails?: string
+      preSeededMemoriesSection?: string
+      retrievedKnowledgeSection?: string
+    },
+  ): Promise<{
+    agent: {
+      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>
+  reasoningProfile: 'fast' | 'standard' | 'deep'
+  systemWorkspaceDetails?: string
+  getPreSeededMemoriesSection: (agentId: string) => Promise<string | undefined>
+  retrievedKnowledgeSection?: string
+  abortSignal: AbortSignal
+  participantRunner: TeamConsultationParticipantRunner
+  onReadError?: (agentId: string, error: unknown) => void
+}
+
+export function createConsultTeamTool(params: CreateConsultTeamToolParams) {
+  return createTool({
+    description:
+      'Consult the specialist team in parallel before replying. Use this when the answer benefits from structured executive input across product, engineering, finance, marketing, strategy, and mentorship.',
+    inputSchema: ConsultTeamArgsSchema,
+    execute: async function* ({ task }) {
+      const uploadMetadataText = buildReadableUploadMetadataText(params.availableUploads)
+      const responses: ConsultTeamResultData['responses'] = teamConsultParticipants.map((agentId) => ({
+        agentId,
+        agentName: agentDisplayNames[agentId] ?? agentId,
+        status: 'running',
+      }))
+      const queue: ConsultTeamResultData[] = []
+      let wake: (() => void) | undefined
+      let completedWorkers = 0
+      let fatalError: unknown
+
+      const pushSnapshot = () => {
+        queue.push(buildSnapshot(responses))
+        wake?.()
+        wake = undefined
+      }
+
+      const workerPromises = teamConsultParticipants.map(async (agentId, index) => {
+        const agentName = agentDisplayNames[agentId] ?? agentId
+        const timedAbort = createTimedAbortSignal(params.abortSignal, TEAM_CONSULTATION_TIMEOUT_MS)
+        let latestMessage: ChatMessage | null = null
+
+        try {
+          const { agent, observer } = await params.participantRunner.buildParticipantAgent(agentId, {
+            task,
+            reasoningProfile: params.reasoningProfile,
+            systemWorkspaceDetails: params.systemWorkspaceDetails,
+            preSeededMemoriesSection: await params.getPreSeededMemoriesSection(agentId),
+            retrievedKnowledgeSection: params.retrievedKnowledgeSection,
+          })
+          const modelMessages = await convertToModelMessages(
+            buildModelInputMessagesWithUploadMetadata({
+              messages: params.historyMessages,
+              latestUserMessageId: params.latestUserMessageId,
+              uploadMetadataText,
+            }),
+            { ignoreIncompleteToolCalls: true },
+          )
+
+          let result: Awaited<ReturnType<typeof agent.stream>>
+          try {
+            result = await observer.run(() => agent.stream({ messages: modelMessages, abortSignal: timedAbort.signal }))
+          } catch (error) {
+            if (params.abortSignal.aborted || timedAbort.signal.aborted) {
+              observer.recordAbort?.(error)
+            } else {
+              observer.recordError?.(error)
+            }
+            throw error
+          }
+
+          for await (const message of readUIMessageStream<ChatMessage>({
+            stream: result.toUIMessageStream({
+              generateMessageId: () => Bun.randomUUIDv7(),
+              sendReasoning: true,
+              sendSources: true,
+              sendStart: false,
+              sendFinish: false,
+            }) as ReadableStream<never>,
+            onError: (error) => {
+              params.onReadError?.(agentId, error)
+            },
+          })) {
+            latestMessage = withMessageCreatedAt(message)
+            responses[index] = {
+              agentId,
+              agentName,
+              status: 'running',
+              summary: extractMessageText(latestMessage).trim() || undefined,
+              message: latestMessage,
+            }
+            pushSnapshot()
+          }
+
+          if (!latestMessage) {
+            throw new Error(`Team participant ${agentId} did not produce a response.`)
+          }
+
+          responses[index] = {
+            agentId,
+            agentName,
+            status: 'complete',
+            summary: extractMessageText(latestMessage).trim() || undefined,
+            message: latestMessage,
+          }
+          pushSnapshot()
+        } catch (error) {
+          if (params.abortSignal.aborted) {
+            fatalError = error
+            wake?.()
+            wake = undefined
+            return
+          }
+
+          responses[index] = {
+            agentId,
+            agentName,
+            status: 'error',
+            summary: latestMessage ? extractMessageText(latestMessage).trim() || undefined : undefined,
+            error: buildTeamConsultationFailureMessage(
+              agentName,
+              TEAM_CONSULTATION_TIMEOUT_MS,
+              timedAbort.didTimeout(),
+              error,
+            ),
+            ...(latestMessage ? { message: latestMessage } : {}),
+          }
+          pushSnapshot()
+        } finally {
+          timedAbort.dispose()
+          completedWorkers += 1
+          wake?.()
+          wake = undefined
+        }
+      })
+
+      pushSnapshot()
+
+      while (queue.length > 0 || completedWorkers < teamConsultParticipants.length) {
+        if (fatalError) {
+          await Promise.allSettled(workerPromises)
+          throw fatalError
+        }
+
+        if (queue.length === 0) {
+          await new Promise<void>((resolve) => {
+            wake = resolve
+          })
+          continue
+        }
+
+        const snapshot = queue.shift()
+        if (snapshot) {
+          yield snapshot
+        }
+      }
+
+      await Promise.all(workerPromises)
+      return buildSnapshot(responses)
+    },
+    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

@@ -0,0 +1,32 @@
+import { agentDisplayNames } from '../config/agent-defaults'
+
+export function buildTeamConsultationResponseGuard(params: { agentId: string; task: string }) {
+  const agentName = agentDisplayNames[params.agentId] ?? params.agentId
+  return [
+    '<team-consultation-agent-protocol>',
+    '- You are participating in a structured internal team consultation led by Chief of Staff.',
+    `- Your role for this response is ${agentName}.`,
+    '- Use markdown when it helps clarity.',
+    '- Make the recommendation, explain key tradeoffs, and note the next decision.',
+    '',
+    '<team-consultation-task>',
+    params.task.trim(),
+    '</team-consultation-task>',
+    '</team-consultation-agent-protocol>',
+  ].join('\n')
+}
+
+export function buildTeamConsultationFailureMessage(
+  agentName: string,
+  timeoutMs: number,
+  didTimeout: boolean,
+  error: unknown,
+): string {
+  if (didTimeout) {
+    return `${agentName} timed out after ${Math.ceil(timeoutMs / 1000)} seconds.`
+  }
+  if (error instanceof Error && error.message.trim().length > 0) {
+    return `${agentName} failed: ${error.message.trim()}`
+  }
+  return `${agentName} failed to complete the team consultation response.`
+}

package/src/runtime/title-helpers.ts

@@ -0,0 +1,12 @@
+const TITLE_WORD_LIMIT = 5
+
+export function limitTitleWords(text: string): string {
+  const words = text.replace(/\s+/g, ' ').trim().split(' ').filter(Boolean)
+  return words.slice(0, TITLE_WORD_LIMIT).join(' ')
+}
+
+export function deriveTitle(text: string): string {
+  const trimmed = text.replace(/\s+/g, ' ').trim()
+  if (trimmed.length <= 60) return trimmed
+  return `${trimmed.slice(0, 57)}...`
+}

package/src/runtime/turn-lifecycle.ts

@@ -0,0 +1,28 @@
+import type { ChatMessage } from '@lota-sdk/shared/schemas/chat-message'
+
+export async function finalizeTurnRun(params: {
+  serverRunId: string
+  getEntity: () => Promise<{ lastCompactedMessageId?: string | null; chatSummary?: string | null }>
+  getUncompactedMessages: (cursor?: string) => Promise<ChatMessage[]>
+  assessCompaction: (summaryText: string, messages: ChatMessage[]) => { shouldCompact: boolean }
+  enqueueCompaction: () => Promise<void>
+  unregisterRun: (runId: string) => void
+  clearActiveRunId: (runId: string) => Promise<void>
+  disposeAbort: () => void
+}): Promise<void> {
+  try {
+    const entity = await params.getEntity()
+    const cursor = typeof entity.lastCompactedMessageId === 'string' ? entity.lastCompactedMessageId : undefined
+    const uncompactedMessages = await params.getUncompactedMessages(cursor)
+    const summaryText = typeof entity.chatSummary === 'string' ? entity.chatSummary : ''
+    const { shouldCompact } = params.assessCompaction(summaryText, uncompactedMessages)
+
+    if (shouldCompact) {
+      await params.enqueueCompaction()
+    }
+  } finally {
+    params.unregisterRun(params.serverRunId)
+    await params.clearActiveRunId(params.serverRunId)
+    params.disposeAbort()
+  }
+}