@lota-sdk/core 0.4.11 → 0.4.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lota-sdk/core",
-  "version": "0.4.11",
+  "version": "0.4.13",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -31,10 +31,10 @@
     "@ai-sdk/openai": "^3.0.53",
     "@chat-adapter/slack": "^4.26.0",
     "@chat-adapter/state-ioredis": "^4.26.0",
-    "@lota-sdk/shared": "0.4.11",
+    "@lota-sdk/shared": "0.4.13",
     "@mendable/firecrawl-js": "^4.18.3",
     "@surrealdb/node": "^3.0.3",
-    "ai": "^6.0.167",
+    "ai": "^6.0.168",
     "bullmq": "^5.74.1",
     "chat": "^4.26.0",
     "effect": "^4.0.0-beta.50",

package/src/ai-gateway/ai-gateway.ts

@@ -595,6 +595,52 @@ export function extractAiGatewayChatReasoningDeltaText(rawChunk: unknown): strin
   return null
 }
 
+function findAiGatewayChatReasoningOverlap(previousReasoningText: string, nextReasoningText: string): number {
+  const maxOverlap = Math.min(previousReasoningText.length, nextReasoningText.length)
+
+  for (let overlapLength = maxOverlap; overlapLength > 0; overlapLength -= 1) {
+    if (previousReasoningText.slice(-overlapLength) === nextReasoningText.slice(0, overlapLength)) {
+      return overlapLength
+    }
+  }
+
+  return 0
+}
+
+function deriveAiGatewayChatReasoningDeltaText(params: { previousReasoningText: string; rawChunk: unknown }): {
+  delta: string | null
+  nextReasoningText: string
+} {
+  const extractedText = extractAiGatewayChatReasoningDeltaText(params.rawChunk)
+  if (!extractedText) {
+    return { delta: null, nextReasoningText: params.previousReasoningText }
+  }
+
+  if (params.previousReasoningText.length === 0) {
+    return { delta: extractedText, nextReasoningText: extractedText }
+  }
+
+  if (extractedText === params.previousReasoningText) {
+    return { delta: null, nextReasoningText: params.previousReasoningText }
+  }
+
+  if (extractedText.startsWith(params.previousReasoningText)) {
+    const delta = extractedText.slice(params.previousReasoningText.length)
+    return { delta: delta.length > 0 ? delta : null, nextReasoningText: extractedText }
+  }
+
+  const overlapLength = findAiGatewayChatReasoningOverlap(params.previousReasoningText, extractedText)
+  if (overlapLength > 0) {
+    const delta = extractedText.slice(overlapLength)
+    return { delta: delta.length > 0 ? delta : null, nextReasoningText: `${params.previousReasoningText}${delta}` }
+  }
+
+  // Some providers emit true deltas, others resend the full reasoning-so-far.
+  // If the chunk is not a prefix extension, treat it as a standalone delta and
+  // append it to the accumulated reasoning text.
+  return { delta: extractedText, nextReasoningText: `${params.previousReasoningText}${extractedText}` }
+}
+
 export function injectAiGatewayChatReasoningContent(
   content: readonly AiGatewayGeneratedContent[],
   response?: AiGatewayChatResponse,
@@ -786,6 +832,8 @@ export function injectAiGatewayChatReasoningStream(
   const reasoningId = 'ai-gateway-reasoning-0'
   let reasoningOpen = false
   let reasoningClosed = false
+  let reasoningText = ''
+  let nativeReasoningSeen = false
 
   return stream.pipeThrough(
     new TransformStream<AiGatewayStreamPart, AiGatewayStreamPart>({
@@ -797,11 +845,25 @@ export function injectAiGatewayChatReasoningStream(
           reasoningClosed = true
         }
 
+        if (chunk.type === 'reasoning-start' || chunk.type === 'reasoning-delta' || chunk.type === 'reasoning-end') {
+          nativeReasoningSeen = true
+          closeReasoning()
+          controller.enqueue(chunk)
+          return
+        }
+
         if (chunk.type === 'raw') {
-          const reasoningDelta = reasoningClosed ? null : extractAiGatewayChatReasoningDeltaText(chunk.rawValue)
+          const reasoningDeltaState =
+            reasoningClosed || nativeReasoningSeen
+              ? null
+              : deriveAiGatewayChatReasoningDeltaText({
+                  previousReasoningText: reasoningText,
+                  rawChunk: chunk.rawValue,
+                })
           controller.enqueue(chunk)
 
-          if (reasoningDelta) {
+          if (reasoningDeltaState?.delta) {
+            reasoningText = reasoningDeltaState.nextReasoningText
             if (!reasoningOpen) {
               controller.enqueue({ type: 'reasoning-start', id: reasoningId } satisfies AiGatewayStreamPart)
               reasoningOpen = true
@@ -810,7 +872,7 @@ export function injectAiGatewayChatReasoningStream(
             controller.enqueue({
               type: 'reasoning-delta',
               id: reasoningId,
-              delta: reasoningDelta,
+              delta: reasoningDeltaState.delta,
             } satisfies AiGatewayStreamPart)
           }
           return

package/src/config/model-constants.ts

@@ -1,5 +1,6 @@
 export {
   AI_GATEWAY_REASONING_SUMMARY_LEVEL,
+  OPENROUTER_GEMINI_PRO_MODEL_ID,
   OPENAI_HIGH_REASONING_PROVIDER_OPTIONS,
   OPENAI_REASONING_MODEL_ID,
   OPENROUTER_FAST_RERANK_MODEL_ID,

package/src/runtime/index.ts

@@ -13,6 +13,7 @@ export * from './instruction-sections'
 export * from './memory/memory-block'
 export * from './memory/memory-digest-policy'
 export * from './memory/memory-scope'
+export * from './live-turn-trace'
 export * from './llm-content'
 export * from './plugin-resolution'
 export * from './plugin-types'

package/src/runtime/live-turn-trace.ts

@@ -0,0 +1,301 @@
+import type { AgentActivityData, ThinkingStepData } from '@lota-sdk/shared'
+import type { UIMessage, UIMessageStreamWriter } from 'ai'
+
+type StreamChunk<TMessage extends UIMessage> = Parameters<UIMessageStreamWriter<TMessage>['write']>[0]
+
+interface ReasoningBlockState {
+  pendingChunk: string
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : null
+}
+
+function readString(value: unknown): string | null {
+  return typeof value === 'string' && value.length > 0 ? value : null
+}
+
+function normalizeWhitespace(value: string): string {
+  return value.replace(/\s+/g, ' ').trim()
+}
+
+function clipThinkingTitle(value: string): string {
+  if (value.length <= 120) return value
+  return `${value.slice(0, 117).trimEnd()}...`
+}
+
+function normalizeThinkingTitle(value: string): string {
+  return clipThinkingTitle(normalizeWhitespace(value))
+}
+
+function sanitizeReasoningText(value: string): string {
+  return value.replace(/\[REDACTED\]/gi, '').replace(/\r\n/g, '\n')
+}
+
+function stripMarkdownTitleDecorators(line: string): string {
+  let value = line.trim()
+  value = value.replace(/^#{1,6}\s+/, '')
+  value = value.replace(/^\*\*(.+?)\*\*[:.]?$/, '$1')
+  value = value.replace(/^__(.+?)__[:.]?$/, '$1')
+  value = value.replace(/^`(.+?)`[:.]?$/, '$1')
+  value = value.replace(/[:\s]+$/, '')
+  return value.trim()
+}
+
+function readHeadingTitle(line: string): string | null {
+  const trimmed = line.trim()
+  if (/^#{1,6}\s+/.test(trimmed)) {
+    return stripMarkdownTitleDecorators(trimmed)
+  }
+  if (/^\*\*.+\*\*[:.]?$/.test(trimmed) || /^__.+__[:.]?$/.test(trimmed) || /^`.+`[:.]?$/.test(trimmed)) {
+    return stripMarkdownTitleDecorators(trimmed)
+  }
+  if (trimmed.length <= 90 && /^[A-Z0-9].*:\s*$/.test(trimmed)) {
+    return stripMarkdownTitleDecorators(trimmed)
+  }
+  return null
+}
+
+export function extractThinkingTitlesFromReasoning(params: { text: string; isFinal?: boolean }): string[] {
+  const cleaned = sanitizeReasoningText(params.text).trim()
+  if (cleaned.length === 0) return []
+
+  const chunks = cleaned
+    .split(/\n{2,}/)
+    .map((chunk) => chunk.trim())
+    .filter((chunk) => chunk.length > 0)
+
+  const titles: string[] = []
+
+  for (const chunk of chunks) {
+    const firstLine = chunk
+      .split('\n')
+      .find((line) => line.trim().length > 0)
+      ?.trim()
+    if (!firstLine) continue
+
+    const headingTitle = readHeadingTitle(firstLine)
+    if (headingTitle) {
+      titles.push(normalizeThinkingTitle(headingTitle))
+    }
+  }
+
+  return titles.filter((title) => title.length > 0)
+}
+
+function splitReasoningChunks(text: string, isFinal: boolean): { completedChunks: string[]; pendingChunk: string } {
+  const parts = text.split(/\n{2,}/)
+  if (isFinal) {
+    return { completedChunks: parts.map((part) => part.trim()).filter((part) => part.length > 0), pendingChunk: '' }
+  }
+
+  const completedChunks = parts
+    .slice(0, -1)
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0)
+  const pendingChunk = parts.at(-1)?.trimStart() ?? ''
+  return { completedChunks, pendingChunk }
+}
+
+function readChunkType<TMessage extends UIMessage>(chunk: StreamChunk<TMessage>): string | null {
+  return readString(asRecord(chunk)?.type)
+}
+
+function readChunkToolCallId<TMessage extends UIMessage>(chunk: StreamChunk<TMessage>): string | null {
+  const record = asRecord(chunk)
+  return readString(record?.toolCallId) ?? readString(record?.id)
+}
+
+function readChunkToolName<TMessage extends UIMessage>(chunk: StreamChunk<TMessage>): string | null {
+  return readString(asRecord(chunk)?.toolName)
+}
+
+function readChunkReasoningId<TMessage extends UIMessage>(chunk: StreamChunk<TMessage>): string | null {
+  return readString(asRecord(chunk)?.id)
+}
+
+function readChunkReasoningDelta<TMessage extends UIMessage>(chunk: StreamChunk<TMessage>): string | null {
+  return readString(asRecord(chunk)?.delta)
+}
+
+function readChunkErrorText<TMessage extends UIMessage>(chunk: StreamChunk<TMessage>): string | null {
+  const record = asRecord(chunk)
+  return readString(record?.errorText) ?? readString(record?.error)
+}
+
+export function createLiveTurnTraceStreamObserver<TMessage extends UIMessage>(params: {
+  traceId: string
+  writer: UIMessageStreamWriter<TMessage>
+  agentId?: string
+  agentName?: string
+}) {
+  const toolNamesByCallId = new Map<string, string>()
+  const startedToolIds = new Set<string>()
+  const completedToolIds = new Set<string>()
+  const reasoningBlocks = new Map<string, ReasoningBlockState>()
+  const emittedThinkingTitles = new Set<string>()
+  let activeThinkingStep: ThinkingStepData | null = null
+  let nextThinkingStepIndex = 0
+
+  const writeActivity = (data: AgentActivityData) => {
+    const chunk = {
+      type: 'data-agent-activity',
+      id: `agent-activity:${data.activityId}`,
+      data,
+      transient: true,
+    } as unknown as StreamChunk<TMessage>
+    params.writer.write(chunk)
+  }
+
+  const writeThinkingStep = (data: ThinkingStepData) => {
+    const chunk = {
+      type: 'data-thinking-step',
+      id: `thinking-step:${data.stepId}`,
+      data,
+      transient: true,
+    } as unknown as StreamChunk<TMessage>
+    params.writer.write(chunk)
+  }
+
+  const markThinkingStepDone = () => {
+    if (!activeThinkingStep) return
+    if (activeThinkingStep.status === 'done') return
+    activeThinkingStep = { ...activeThinkingStep, status: 'done' }
+    writeThinkingStep(activeThinkingStep)
+  }
+
+  const emitThinkingTitles = (titles: string[]) => {
+    for (const title of titles) {
+      const normalizedTitle = title.toLocaleLowerCase()
+      if (emittedThinkingTitles.has(normalizedTitle)) continue
+
+      markThinkingStepDone()
+
+      const nextStep: ThinkingStepData = {
+        traceId: params.traceId,
+        stepId: `${params.traceId}:thinking:${nextThinkingStepIndex}`,
+        index: nextThinkingStepIndex,
+        title,
+        status: 'streaming',
+      }
+      nextThinkingStepIndex += 1
+      emittedThinkingTitles.add(normalizedTitle)
+      activeThinkingStep = nextStep
+      writeThinkingStep(nextStep)
+    }
+  }
+
+  const emitToolPhase = (
+    phase: AgentActivityData['phase'],
+    toolCallId: string,
+    toolName: string,
+    errorText?: string,
+  ) => {
+    writeActivity({
+      traceId: params.traceId,
+      activityId: toolCallId,
+      kind: 'tool',
+      toolName,
+      toolCallId,
+      ...(params.agentId ? { agentId: params.agentId } : {}),
+      ...(params.agentName ? { agentName: params.agentName } : {}),
+      phase,
+      ...(errorText ? { errorText } : {}),
+    })
+  }
+
+  const startTool = (toolCallId: string, toolName: string) => {
+    if (!toolNamesByCallId.has(toolCallId)) {
+      toolNamesByCallId.set(toolCallId, toolName)
+    }
+    if (startedToolIds.has(toolCallId) || completedToolIds.has(toolCallId)) return
+    startedToolIds.add(toolCallId)
+    emitToolPhase('started', toolCallId, toolName)
+  }
+
+  const completeTool = (toolCallId: string, phase: 'completed' | 'failed', errorText?: string) => {
+    const toolName = toolNamesByCallId.get(toolCallId)
+    if (!toolName || completedToolIds.has(toolCallId)) return
+    completedToolIds.add(toolCallId)
+    emitToolPhase(phase, toolCallId, toolName, errorText)
+  }
+
+  const processReasoningText = (reasoningId: string, delta: string, isFinal: boolean) => {
+    const state = reasoningBlocks.get(reasoningId) ?? { pendingChunk: '' }
+    const nextBuffer = state.pendingChunk + sanitizeReasoningText(delta)
+    const { completedChunks, pendingChunk } = splitReasoningChunks(nextBuffer, isFinal)
+
+    for (const completedChunk of completedChunks) {
+      emitThinkingTitles(extractThinkingTitlesFromReasoning({ text: completedChunk, isFinal: true }))
+    }
+
+    if (!isFinal && pendingChunk.length > 0) {
+      emitThinkingTitles(extractThinkingTitlesFromReasoning({ text: pendingChunk, isFinal: false }))
+    }
+
+    if (isFinal) {
+      reasoningBlocks.delete(reasoningId)
+      return
+    }
+
+    reasoningBlocks.set(reasoningId, { pendingChunk })
+  }
+
+  return {
+    observeChunk(chunk: StreamChunk<TMessage>): void {
+      const chunkType = readChunkType(chunk)
+      if (!chunkType) return
+
+      switch (chunkType) {
+        case 'reasoning-delta': {
+          const reasoningId = readChunkReasoningId(chunk)
+          const delta = readChunkReasoningDelta(chunk)
+          if (!reasoningId || delta === null) return
+
+          processReasoningText(reasoningId, delta, false)
+          return
+        }
+
+        case 'reasoning-end': {
+          const reasoningId = readChunkReasoningId(chunk)
+          if (!reasoningId) return
+          processReasoningText(reasoningId, '', true)
+          markThinkingStepDone()
+          return
+        }
+
+        case 'tool-input-start':
+        case 'tool-input-available':
+        case 'tool-call': {
+          const toolCallId = readChunkToolCallId(chunk)
+          const toolName = readChunkToolName(chunk)
+          if (!toolCallId || !toolName) return
+          startTool(toolCallId, toolName)
+          return
+        }
+
+        case 'tool-output-available': {
+          const toolCallId = readChunkToolCallId(chunk)
+          if (!toolCallId) return
+          completeTool(toolCallId, 'completed')
+          return
+        }
+
+        case 'tool-output-error':
+        case 'tool-error': {
+          const toolCallId = readChunkToolCallId(chunk)
+          if (!toolCallId) return
+          completeTool(toolCallId, 'failed', readChunkErrorText(chunk) ?? undefined)
+          return
+        }
+
+        default:
+          return
+      }
+    },
+
+    finish(): void {
+      markThinkingStepDone()
+    },
+  }
+}

package/src/runtime/runtime-services.ts

@@ -52,6 +52,7 @@ import type {
   createThreadApprovalContinuationStream,
   createThreadNativeToolApprovalStream,
   createThreadTurnStream,
+  launchBackgroundThreadWork,
   runThreadTurnInBackground,
   ThreadTurnServiceTag,
   triggerPlanNodeTurn,
@@ -136,6 +137,7 @@ export interface LotaRuntimeServices {
   createThreadNativeToolApprovalStream: typeof createThreadNativeToolApprovalStream
   createThreadTurnStream: typeof createThreadTurnStream
   isApprovalContinuationRequest: typeof isApprovalContinuationRequestFn
+  launchBackgroundThreadWork: typeof launchBackgroundThreadWork
   runThreadTurnInBackground: typeof runThreadTurnInBackground
   triggerPlanNodeTurn: typeof triggerPlanNodeTurn
 }
@@ -350,6 +352,7 @@ export function buildRuntimeServiceSurface(input: BuildRuntimeServiceSurfaceInpu
     createThreadNativeToolApprovalStream: (...args) => threadTurnService.createThreadNativeToolApprovalStream(...args),
     createThreadTurnStream: (...args) => threadTurnService.createThreadTurnStream(...args),
     isApprovalContinuationRequest: isApprovalContinuationRequestFn,
+    launchBackgroundThreadWork: (...args) => threadTurnService.launchBackgroundThreadWork(...args),
     runThreadTurnInBackground: (...args) => threadTurnService.runThreadTurnInBackground(...args),
     triggerPlanNodeTurn: (...args) => threadTurnService.triggerPlanNodeTurn(...args),
   }

package/src/services/thread/thread-turn-preparation.service.ts

@@ -993,27 +993,9 @@ const prepareThreadRunCoreEffect = Effect.fn('ThreadTurnPreparation.prepareThrea
           ).pipe(Effect.withSpan('ThreadTurnPreparation.runPostTurnSideEffects'))
         }
 
-        if (allAssistantMessages.length > 0 && params.kind !== 'planTurn') {
-          const afterTurn = turnHooks.afterTurn
-          if (afterTurn) {
-            yield* effectTryPromise(
-              () =>
-                afterTurn({
-                  thread,
-                  threadRef,
-                  orgRef,
-                  userRef,
-                  userName,
-                  onboardingActive,
-                  referenceUserMessage,
-                  assistantMessages: allAssistantMessages,
-                  latestThreadRecord,
-                  context: buildContextResult,
-                }),
-              'Failed to run afterTurn hook.',
-            ).pipe(Effect.withSpan('ThreadTurnPreparation.afterTurnHook'))
-          }
-        }
+        yield* Effect.sync(() => {
+          launchAfterTurnHook(latestThreadRecord)
+        })
       }).pipe(
         Effect.catch((postRunError) =>
           Effect.sync(() => {
@@ -1034,6 +1016,48 @@ const prepareThreadRunCoreEffect = Effect.fn('ThreadTurnPreparation.prepareThrea
     assistantMessages: [...allAssistantMessages],
   })
 
+  const launchAfterTurnHook = (latestThreadRecord: typeof threadRecord) => {
+    if (allAssistantMessages.length === 0 || params.kind === 'planTurn') {
+      return
+    }
+
+    const afterTurn = turnHooks.afterTurn
+    if (!afterTurn) {
+      return
+    }
+
+    // `afterTurn` is host-owned follow-up work. Launch it detached so the
+    // streamed turn closes after persistence/finalization instead of waiting on
+    // onboarding/map side effects in the request path.
+    void runPromiseWithCurrentContext(
+      effectTryPromise(
+        () =>
+          afterTurn({
+            thread,
+            threadRef,
+            orgRef,
+            userRef,
+            userName,
+            onboardingActive,
+            referenceUserMessage,
+            assistantMessages: allAssistantMessages,
+            latestThreadRecord,
+            context: buildContextResult,
+          }),
+        'Failed to run afterTurn hook.',
+      ).pipe(
+        Effect.withSpan('ThreadTurnPreparation.afterTurnHook'),
+        Effect.catch((error) =>
+          Effect.sync(() => {
+            aiLogger.error`Thread afterTurn hook failed: ${error}`
+          }),
+        ),
+      ),
+    ).catch((error) => {
+      aiLogger.error`Thread afterTurn hook scheduling failed: ${error}`
+    })
+  }
+
   const run = (writer?: UIMessageStreamWriter<ChatMessage>) => {
     const serverRunId = Bun.randomUUIDv7()
 

package/src/services/thread/thread-turn-streaming.ts

@@ -14,6 +14,7 @@ import {
 } from '../../runtime/agent-identity-overrides'
 import { createAgentMessageMetadata } from '../../runtime/agent-stream-helpers'
 import { mergeInstructionSections } from '../../runtime/instruction-sections'
+import { createLiveTurnTraceStreamObserver } from '../../runtime/live-turn-trace'
 import type { LotaRuntimeTurnHooks } from '../../runtime/runtime-extensions'
 import {
   asRecord,
@@ -277,6 +278,7 @@ const streamAgentResponseEffect = Effect.fn('ThreadTurnStreaming.streamAgentResp
     prepareStep: (agentResolution?.prepareStep as PrepareStepFunction<ToolSet> | undefined) ?? streamParams.prepareStep,
   })
   const agentAbortSignal = streamParams.abortSignal ?? ctx.runAbortSignal
+  const resolvedAgentName = resolveRuntimeAgentDisplayName(agentConfig, agentIdentityOverrides, resolvedAgentId)
 
   const generateFallback = (cause: ThreadTurnStreamingError) =>
     effectTryPromise(
@@ -291,6 +293,34 @@ const streamAgentResponseEffect = Effect.fn('ThreadTurnStreaming.streamAgentResp
       Effect.flatMap((result) => buildFallbackResponseMessage(result as ToolLoopGenerateResult)),
     )
 
+  const generateWithoutUiStream = effectTryPromise(
+    () => streamParams.observer.run(() => agent.generate({ messages: modelMessages, abortSignal: agentAbortSignal })),
+    `Agent generate failed for ${resolvedAgentId}.`,
+  ).pipe(
+    Effect.tapError((error) =>
+      Effect.sync(() => {
+        if (agentAbortSignal.aborted) {
+          streamParams.observer.recordAbort(error)
+          return
+        }
+
+        streamParams.observer.recordError(error)
+      }),
+    ),
+    Effect.withSpan('ThreadTurnStreaming.startAgentGenerate'),
+    Effect.flatMap((result) => buildFallbackResponseMessage(result as ToolLoopGenerateResult)),
+  )
+
+  if (!streamParams.writer) {
+    const generatedResponse = yield* generateWithoutUiStream
+
+    for (const toolError of collectToolOutputErrors({ responseMessage: generatedResponse })) {
+      aiLogger.error`Tool execution failed (agent=${resolvedAgentId}, tool=${toolError.toolName}, toolCallId=${toolError.toolCallId}): ${toolError.errorText}`
+    }
+
+    return generatedResponse
+  }
+
   const result = yield* effectTryPromise(
     () => streamParams.observer.run(() => agent.stream({ messages: modelMessages, abortSignal: agentAbortSignal })),
     `Agent stream failed for ${resolvedAgentId}.`,
@@ -320,14 +350,19 @@ const streamAgentResponseEffect = Effect.fn('ThreadTurnStreaming.streamAgentResp
     originalMessages: streamParams.messages,
     sendReasoning: true,
     sendSources: true,
-    messageMetadata: createAgentMessageMetadata({
-      agentId: resolvedAgentId,
-      agentName: resolveRuntimeAgentDisplayName(agentConfig, agentIdentityOverrides, resolvedAgentId),
-    }),
+    messageMetadata: createAgentMessageMetadata({ agentId: resolvedAgentId, agentName: resolvedAgentName }),
     onFinish: ({ responseMessage: finishedResponseMessage }: { responseMessage: ChatMessage }) => {
       resolveFinishedStream(withMessageCreatedAt(finishedResponseMessage, nowEpochMillis()))
     },
   }) as ReadableStream<ChatStreamChunk>
+  const liveTurnTrace = streamParams.writer
+    ? createLiveTurnTraceStreamObserver({
+        traceId: `trace:${Bun.randomUUIDv7()}`,
+        writer: streamParams.writer,
+        agentId: resolvedAgentId,
+        agentName: resolvedAgentName,
+      })
+    : null
   const streamStartedAt = performance.now()
   const firstVisibleOutputRecorded = yield* Ref.make(false)
   const firstTextTokenRecorded = yield* Ref.make(false)
@@ -361,6 +396,7 @@ const streamAgentResponseEffect = Effect.fn('ThreadTurnStreaming.streamAgentResp
         if (streamParams.writer) {
           yield* Effect.sync(() => {
             streamParams.writer?.write(value)
+            liveTurnTrace?.observeChunk(value)
           })
         }
       }),
@@ -371,6 +407,7 @@ const streamAgentResponseEffect = Effect.fn('ThreadTurnStreaming.streamAgentResp
     ),
     Effect.catchTag('ThreadTurnStreamingError', generateFallback),
   )
+  liveTurnTrace?.finish()
 
   for (const toolError of collectToolOutputErrors({ responseMessage: streamedResponse })) {
     aiLogger.error`Tool execution failed (agent=${resolvedAgentId}, tool=${toolError.toolName}, toolCallId=${toolError.toolCallId}): ${toolError.errorText}`

package/src/services/thread/thread-turn.ts

@@ -5,34 +5,68 @@ import { Context, Schema, Effect, Layer } from 'effect'
 import type { ResolvedAgentConfig } from '../../config/agent-defaults'
 import { ensureRecordId, recordIdToString } from '../../db/record-id'
 import { TABLES } from '../../db/tables'
-import { BadRequestError } from '../../effect/errors'
+import { BadRequestError, ForbiddenError } from '../../effect/errors'
 import { AgentConfigServiceTag } from '../../effect/services'
 import { hasApprovalRespondedParts, isApprovalContinuationRequest } from '../../runtime/approval-continuation'
 import { shouldPlanNodeUseVisibleTurn } from '../../runtime/execution-plan-visibility'
 import { wrapResponseWithKeepalive } from '../../utils/sse-keepalive'
+import { BackgroundWorkService } from '../background-work.service'
 import type { makePlanExecutorService } from '../plan/plan-executor.service'
 import { PlanExecutorServiceTag } from '../plan/plan-executor.service'
 import type { makePlanRunService } from '../plan/plan-run.service'
 import { PlanRunServiceTag } from '../plan/plan-run.service'
 import type { makeUserService } from '../user.service'
 import { UserServiceTag } from '../user.service'
+import type { makeThreadMessageService } from './thread-message.service'
+import { ThreadMessageServiceTag } from './thread-message.service'
 import type {
   PreparedThreadTurnResult,
   ThreadApprovalContinuationParams,
-  ThreadPlanTurnParams,
   ThreadTurnParams,
+  ThreadPlanTurnParams,
   makeThreadTurnPreparationService,
 } from './thread-turn-preparation.service'
 import { ThreadTurnPreparationServiceTag } from './thread-turn-preparation.service'
 import { buildThreadTurnSpanAttributes, compactSpanAttributes } from './thread-turn-tracing'
 import type { makeThreadService } from './thread.service'
 import { ThreadServiceTag } from './thread.service'
+import type { NormalizedThread } from './thread.types'
 
 export { hasApprovalRespondedParts, isApprovalContinuationRequest }
 export { wrapResponseWithKeepalive }
 export type { PreparedThreadTurnResult }
 export type { ThreadPlanTurnParams }
 
+export interface BackgroundThreadLaunchMessage {
+  parts: ChatMessage['parts']
+  metadata?: ChatMessage['metadata']
+}
+
+export interface LaunchBackgroundThreadWorkParams {
+  sourceThreadId: Parameters<typeof ensureRecordId>[0]
+  orgRef: Parameters<typeof ensureRecordId>[0]
+  userRef: Parameters<typeof ensureRecordId>[0]
+  userName?: string | null
+  targetThreadId?: Parameters<typeof ensureRecordId>[0]
+  projectTitle?: string
+  targetAgentId?: string
+  handoff: BackgroundThreadLaunchMessage
+  input: BackgroundThreadLaunchMessage
+  abortSignal?: AbortSignal
+  streamId?: string
+}
+
+export interface LaunchBackgroundThreadWorkResult {
+  launched: boolean
+  threadId: string
+  threadTitle: string
+  sourceThreadId: string
+  targetAgentId?: string
+  handoffMessageId: string
+  createdThread: boolean
+  message: string
+}
+
 class ThreadTurnServiceError extends Schema.TaggedErrorClass<ThreadTurnServiceError>()('ThreadTurnServiceError', {
   message: Schema.String,
   cause: Schema.optional(Schema.Defect),
@@ -40,9 +74,12 @@ class ThreadTurnServiceError extends Schema.TaggedErrorClass<ThreadTurnServiceEr
 
 interface ThreadTurnDeps {
   agentConfig: ResolvedAgentConfig
+  background: Context.Service.Shape<typeof BackgroundWorkService>
   planExecutor: ReturnType<typeof makePlanExecutorService>
   planRun: ReturnType<typeof makePlanRunService>
+  provideCurrentContext: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, never>
   thread: ReturnType<typeof makeThreadService>
+  threadMessage: ReturnType<typeof makeThreadMessageService>
   threadTurnPreparation: ReturnType<typeof makeThreadTurnPreparationService>
   user: ReturnType<typeof makeUserService>
 }
@@ -172,6 +209,129 @@ function runThreadTurnInBackgroundWith(deps: ThreadTurnDeps, params: ThreadTurnP
   )
 }
 
+function buildBackgroundLaunchMessage(params: { createdThread: boolean; threadTitle: string }) {
+  return params.createdThread
+    ? `Background work launched in "${params.threadTitle}".`
+    : `Background work launched in existing thread "${params.threadTitle}".`
+}
+
+const launchBackgroundThreadWorkEffect = Effect.fn('ThreadTurn.launchBackgroundThreadWork')(function* (
+  deps: ThreadTurnDeps,
+  params: LaunchBackgroundThreadWorkParams,
+) {
+  const orgIdString = recordIdToString(params.orgRef, TABLES.ORGANIZATION)
+  const userIdString = recordIdToString(params.userRef, TABLES.USER)
+  const sourceThreadId = recordIdToString(params.sourceThreadId, TABLES.THREAD)
+
+  const resolveTargetThread = (): Effect.Effect<
+    { thread: NormalizedThread; createdThread: boolean },
+    BadRequestError | ForbiddenError | ThreadTurnServiceError
+  > =>
+    Effect.gen(function* () {
+      if (params.targetThreadId) {
+        const existingThread = yield* deps.thread
+          .getThread(params.targetThreadId)
+          .pipe(
+            Effect.mapError((cause) => new ThreadTurnServiceError({ message: 'Failed to load target thread.', cause })),
+          )
+        if (existingThread.organizationId !== orgIdString) {
+          return yield* new ForbiddenError({ message: 'Target thread belongs to a different organization.' })
+        }
+        if (existingThread.userId !== userIdString) {
+          return yield* new ForbiddenError({ message: 'Target thread belongs to a different user.' })
+        }
+        if (existingThread.status !== 'active') {
+          return yield* new BadRequestError({ message: 'Target thread must be active.' })
+        }
+        return { thread: existingThread, createdThread: false }
+      }
+
+      const projectTitle = params.projectTitle?.trim()
+      if (!projectTitle) {
+        return yield* new BadRequestError({
+          message: 'projectTitle is required when launching background work without targetThreadId.',
+        })
+      }
+
+      const createdThread = yield* deps.thread
+        .createThread({ userId: params.userRef, organizationId: params.orgRef, title: projectTitle, type: 'group' })
+        .pipe(
+          Effect.mapError((cause) => new ThreadTurnServiceError({ message: 'Failed to create target thread.', cause })),
+        )
+      return { thread: createdThread, createdThread: true }
+    })
+
+  let createdThreadId: string | null = null
+  const cleanupCreatedThread = () =>
+    createdThreadId ? deps.thread.deleteThread(createdThreadId).pipe(Effect.catch(() => Effect.void)) : Effect.void
+
+  return yield* Effect.gen(function* () {
+    const { thread: targetThread, createdThread } = yield* resolveTargetThread()
+    if (createdThread) {
+      createdThreadId = targetThread.id
+    }
+
+    const handoffMessage = yield* deps.threadMessage.addAgentMessage({
+      messageId: { tb: TABLES.THREAD_MESSAGE, id: Bun.randomUUIDv7() },
+      threadId: ensureRecordId(targetThread.id, TABLES.THREAD),
+      parts: params.handoff.parts,
+      metadata: params.handoff.metadata,
+    })
+
+    yield* deps.background.run(
+      deps.provideCurrentContext(
+        runThreadTurnInBackgroundWith(deps, {
+          thread: targetThread,
+          threadRef: ensureRecordId(targetThread.id, TABLES.THREAD),
+          orgRef: params.orgRef,
+          userRef: params.userRef,
+          userName: params.userName,
+          agentIdOverride: params.targetAgentId,
+          inputMessage: {
+            id: Bun.randomUUIDv7(),
+            role: 'user',
+            parts: params.input.parts,
+            metadata: params.input.metadata,
+          },
+          skipInputMessagePersistence: true,
+          abortSignal: params.abortSignal,
+          streamId: params.streamId,
+        }),
+      ),
+      'thread.launchBackgroundThreadWork',
+    )
+
+    return {
+      launched: true,
+      threadId: targetThread.id,
+      threadTitle: targetThread.title,
+      sourceThreadId,
+      ...(params.targetAgentId ? { targetAgentId: params.targetAgentId } : {}),
+      handoffMessageId: handoffMessage.id,
+      createdThread,
+      message: buildBackgroundLaunchMessage({ createdThread, threadTitle: targetThread.title }),
+    } satisfies LaunchBackgroundThreadWorkResult
+  }).pipe(Effect.catch((error) => cleanupCreatedThread().pipe(Effect.andThen(Effect.fail(error)))))
+})
+
+function launchBackgroundThreadWorkWith(deps: ThreadTurnDeps, params: LaunchBackgroundThreadWorkParams) {
+  return launchBackgroundThreadWorkEffect(deps, params).pipe(
+    Effect.annotateSpans(
+      compactSpanAttributes({
+        ...buildThreadTurnSpanAttributes({
+          threadRef: params.sourceThreadId,
+          orgRef: params.orgRef,
+          userRef: params.userRef,
+          kind: 'background-launch',
+          streamId: params.streamId,
+          agentId: params.targetAgentId,
+        }),
+        targetThreadId: params.targetThreadId ? recordIdToString(params.targetThreadId, TABLES.THREAD) : undefined,
+      }),
+    ),
+  )
+}
+
 const triggerPlanNodeTurnEffect = Effect.fn('ThreadTurn.triggerPlanNodeTurn')(function* (
   deps: ThreadTurnDeps,
   params: { runId: string; nodeId: string; abortSignal?: AbortSignal; streamId?: string },
@@ -291,6 +451,9 @@ export function makeThreadTurnService(deps: ThreadTurnDeps) {
     createThreadTurnStream(params: ThreadTurnParams) {
       return createThreadTurnStreamWith(deps, params)
     },
+    launchBackgroundThreadWork(params: LaunchBackgroundThreadWorkParams) {
+      return launchBackgroundThreadWorkWith(deps, params)
+    },
     runThreadTurnInBackground(params: ThreadTurnParams) {
       return runThreadTurnInBackgroundWith(deps, params)
     },
@@ -308,13 +471,28 @@ export class ThreadTurnServiceTag extends Context.Service<
 export const ThreadTurnServiceLive = Layer.effect(
   ThreadTurnServiceTag,
   Effect.gen(function* () {
+    const currentContext = yield* Effect.context()
+    const provideCurrentContext = <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, never> =>
+      effect.pipe(Effect.provide(currentContext)) as Effect.Effect<A, E, never>
     const agentConfig = yield* AgentConfigServiceTag
+    const background = yield* BackgroundWorkService
     const planExecutor = yield* PlanExecutorServiceTag
     const planRun = yield* PlanRunServiceTag
     const thread = yield* ThreadServiceTag
+    const threadMessage = yield* ThreadMessageServiceTag
     const threadTurnPreparation = yield* ThreadTurnPreparationServiceTag
     const user = yield* UserServiceTag
-    return makeThreadTurnService({ agentConfig, planExecutor, planRun, thread, threadTurnPreparation, user })
+    return makeThreadTurnService({
+      agentConfig,
+      background,
+      planExecutor,
+      planRun,
+      provideCurrentContext,
+      thread,
+      threadMessage,
+      threadTurnPreparation,
+      user,
+    })
   }),
 )
 
@@ -339,6 +517,13 @@ export const createThreadTurnStream = Effect.fn('ThreadTurn.createThreadTurnStre
   return yield* threadTurnService.createThreadTurnStream(params)
 })
 
+export const launchBackgroundThreadWork = Effect.fn('ThreadTurn.launchBackgroundThreadWork')(function* (
+  params: LaunchBackgroundThreadWorkParams,
+) {
+  const threadTurnService = yield* ThreadTurnServiceTag
+  return yield* threadTurnService.launchBackgroundThreadWork(params)
+})
+
 export const runThreadTurnInBackground = Effect.fn('ThreadTurn.runThreadTurnInBackground')(function* (
   params: ThreadTurnParams,
 ) {