@lota-sdk/core 0.1.20 → 0.1.22

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

@@ -6,10 +6,19 @@ import {
   ConsultSpecialistArgsSchema,
   dataPartsSchemas,
   messageMetadataSchema,
+  PlanNodeResultSubmissionSchema,
+  SUBMIT_PLAN_TURN_RESULT_TOOL_NAME,
   toTimestamp,
   withMessageCreatedAt,
 } from '@lota-sdk/shared'
-import type { ChatMessage, MessageMetadata } from '@lota-sdk/shared'
+import type {
+  ChatMessage,
+  MessageMetadata,
+  PlanArtifactSubmission,
+  PlanNodeHandoffContext,
+  PlanNodeRunRecord,
+  PlanNodeSpecRecord,
+} from '@lota-sdk/shared'
 import { convertToModelMessages, readUIMessageStream, stepCountIs, tool as createTool, validateUIMessages } from 'ai'
 import type { PrepareStepFunction, StopCondition, ToolLoopAgent, ToolSet, UIMessageStreamWriter } from 'ai'
 import type { z } from 'zod'
@@ -36,6 +45,10 @@ import { enqueueRegularChatMemoryDigest } from '../queues/regular-chat-memory-di
 import { enqueueSkillExtraction } from '../queues/skill-extraction.queue'
 import { enqueueWorkstreamTitleGeneration } from '../queues/workstream-title-generation.queue'
 import { buildAgentPromptContext } from '../runtime/agent-prompt-context'
+import {
+  OWNERSHIP_DISPATCH_BLOCKED_TOOL_NAMES,
+  buildCompletionCheckStructuredOutputHints,
+} from '../runtime/agent-runtime-policy'
 import {
   buildSpecialistTaskMessage,
   createAgentMessageMetadata,
@@ -85,7 +98,7 @@ import { memoryService } from './memory.service'
 import { planRunService } from './plan-run.service'
 import { recentActivityService } from './recent-activity.service'
 import { workstreamMessageService } from './workstream-message.service'
-import { workstreamService } from './workstream.service'
+import { ActiveWorkstreamRunConflictError, workstreamService } from './workstream.service'
 
 type ChatStreamChunk = Parameters<UIMessageStreamWriter<ChatMessage>['write']>[0]
 
@@ -183,6 +196,190 @@ function optionalInstructionSection(value: unknown): string[] | undefined {
   return section ? [section] : undefined
 }
 
+export interface PlanTurnUpstreamHandoff {
+  nodeId: string
+  label: string
+  ownerRef: string
+  ownerType: PlanNodeSpecRecord['owner']['executorType']
+  handoffContext: PlanNodeHandoffContext
+}
+
+export interface WorkstreamPlanTurnContext {
+  runId: string
+  nodeId: string
+  planTitle: string
+  nodeSpec: PlanNodeSpecRecord
+  nodeRun: PlanNodeRunRecord
+  resolvedInput: Record<string, unknown>
+  inputArtifacts: PlanArtifactSubmission[]
+  upstreamHandoffs: PlanTurnUpstreamHandoff[]
+}
+
+function buildPlanTurnExecutionSection(planTurn: WorkstreamPlanTurnContext): string {
+  const payload = {
+    runId: planTurn.runId,
+    planTitle: planTurn.planTitle,
+    node: {
+      id: planTurn.nodeSpec.nodeId,
+      label: planTurn.nodeSpec.label,
+      owner: planTurn.nodeSpec.owner,
+      objective: planTurn.nodeSpec.objective,
+      instructions: planTurn.nodeSpec.instructions,
+      outputSchemaRef: planTurn.nodeSpec.outputSchemaRef ?? null,
+      deliverables: planTurn.nodeSpec.deliverables,
+      successCriteria: planTurn.nodeSpec.successCriteria,
+      completionChecks: planTurn.nodeSpec.completionChecks,
+      toolPolicy: planTurn.nodeSpec.toolPolicy,
+      contextPolicy: planTurn.nodeSpec.contextPolicy,
+    },
+    resolvedInput: planTurn.resolvedInput,
+    inputArtifacts: planTurn.inputArtifacts,
+  }
+
+  return [
+    '<plan-turn-execution>',
+    'The runtime has activated a visible execution-plan node inside this workstream.',
+    `Complete node "${planTurn.nodeSpec.label}" for plan "${planTurn.planTitle}".`,
+    'Use only the node contract, resolved input, input artifacts, and upstream handoff context provided here.',
+    'Do not ask the user for more input and do not rely on unstated external context.',
+    'Do not submit placeholders, partial work, or speculative outputs.',
+    'Before submitting, satisfy every required deliverable, success criterion, and completion check for this node.',
+    'Deliverables must use the exact artifact names and kinds declared in the node contract.',
+    'If a deliverable declares schemaRef, include the same schemaRef and a payload that satisfies that schema.',
+    'If outputSchemaRef is declared, structuredOutput must satisfy that schema before you submit.',
+    `When finished, call ${SUBMIT_PLAN_TURN_RESULT_TOOL_NAME} exactly once.`,
+    'Always include durable handoffContext for downstream nodes when you submit the final result.',
+    'Do not ask the user for confirmation and do not create or replace execution plans in this turn.',
+    JSON.stringify(payload, null, 2),
+    '</plan-turn-execution>',
+  ].join('\n')
+}
+
+function describePlanTurnDeliverable(deliverable: PlanNodeSpecRecord['deliverables'][number]): string {
+  return [
+    `- ${deliverable.name}`,
+    `kind=${deliverable.kind}`,
+    deliverable.required ? 'required' : 'optional',
+    deliverable.schemaRef ? `schemaRef=${deliverable.schemaRef}` : undefined,
+    deliverable.description ? `description=${deliverable.description}` : undefined,
+  ]
+    .filter(Boolean)
+    .join(' | ')
+}
+
+function describePlanTurnCompletionCheck(check: PlanNodeSpecRecord['completionChecks'][number]): string {
+  return [
+    `- ${check.description}`,
+    `type=${check.type}`,
+    check.blocking ? 'blocking' : 'warning',
+    Object.keys(check.config).length > 0 ? `config=${JSON.stringify(check.config)}` : undefined,
+  ]
+    .filter(Boolean)
+    .join(' | ')
+}
+
+function buildPlanTurnResultContractSection(planTurn: WorkstreamPlanTurnContext): string {
+  const requiredDeliverables = planTurn.nodeSpec.deliverables.filter((deliverable) => deliverable.required)
+  const completionCheckOutputHints = buildCompletionCheckStructuredOutputHints(planTurn.nodeSpec)
+  const deliverableLines =
+    planTurn.nodeSpec.deliverables.length > 0
+      ? planTurn.nodeSpec.deliverables.map(describePlanTurnDeliverable)
+      : ['- none']
+  const completionCheckLines =
+    planTurn.nodeSpec.completionChecks.length > 0
+      ? planTurn.nodeSpec.completionChecks.map(describePlanTurnCompletionCheck)
+      : ['- none']
+
+  return [
+    '<plan-turn-result-contract>',
+    `Call ${SUBMIT_PLAN_TURN_RESULT_TOOL_NAME} exactly once with a result object that passes node validation.`,
+    'Validation is strict. Missing required artifacts, schema mismatches, or failed completion checks will fail the node run.',
+    `Required artifacts: ${requiredDeliverables.length > 0 ? requiredDeliverables.map((deliverable) => deliverable.name).join(', ') : 'none'}`,
+    `Structured output: ${
+      planTurn.nodeSpec.outputSchemaRef
+        ? `required and must match schema "${planTurn.nodeSpec.outputSchemaRef}"`
+        : 'optional unless needed by a completion check'
+    }`,
+    'Deliverables:',
+    ...deliverableLines,
+    'Completion checks:',
+    ...completionCheckLines,
+    ...(completionCheckOutputHints.length > 0
+      ? ['Structured output fields required by completion checks:', ...completionCheckOutputHints]
+      : []),
+    'Include notes with a concise completion summary grounded in the submitted artifacts and structuredOutput.',
+    'Always include handoffContext for downstream execution with a durable summary, key decisions, open questions, risks, recommendations, and references when relevant.',
+    '</plan-turn-result-contract>',
+  ].join('\n')
+}
+
+function buildPlanTurnSubmitToolDescription(planTurn: WorkstreamPlanTurnContext): string {
+  const requiredArtifacts =
+    planTurn.nodeSpec.deliverables
+      .filter((deliverable) => deliverable.required)
+      .map((deliverable) => `${deliverable.name} (${deliverable.kind})`)
+      .join(', ') || 'none'
+
+  return [
+    'Submit the final result for the active plan-triggered node turn.',
+    'Call this exactly once when the node output is complete.',
+    `Required artifacts: ${requiredArtifacts}.`,
+    `Structured output: ${
+      planTurn.nodeSpec.outputSchemaRef ? `must satisfy ${planTurn.nodeSpec.outputSchemaRef}` : 'optional'
+    }.`,
+    'Do not submit partial results. Include durable handoffContext for downstream nodes.',
+  ].join(' ')
+}
+
+function buildPlanTurnPromptMessage(planTurn: WorkstreamPlanTurnContext): ChatMessage {
+  return {
+    id: Bun.randomUUIDv7(),
+    role: 'user',
+    parts: [
+      {
+        type: 'text',
+        text: `Execute the active plan node "${planTurn.nodeSpec.label}" now and submit the result with ${SUBMIT_PLAN_TURN_RESULT_TOOL_NAME}.`,
+      },
+    ],
+    metadata: { trigger: 'plan-turn', planRunId: planTurn.runId, planNodeId: planTurn.nodeId, createdAt: Date.now() },
+  }
+}
+
+function buildUpstreamHandoffSection(upstreamHandoffs: PlanTurnUpstreamHandoff[]): string | undefined {
+  if (upstreamHandoffs.length === 0) {
+    return undefined
+  }
+
+  return [
+    '<upstream-handoff>',
+    JSON.stringify(
+      upstreamHandoffs.map((handoff) => ({
+        nodeId: handoff.nodeId,
+        label: handoff.label,
+        ownerRef: handoff.ownerRef,
+        ownerType: handoff.ownerType,
+        handoffContext: handoff.handoffContext,
+      })),
+      null,
+      2,
+    ),
+    '</upstream-handoff>',
+  ].join('\n')
+}
+
+function applyPlanTurnToolPolicy(tools: ToolSet, nodeSpec: PlanNodeSpecRecord): ToolSet {
+  const blockedToolNames = new Set([...OWNERSHIP_DISPATCH_BLOCKED_TOOL_NAMES, ...nodeSpec.toolPolicy.deny])
+  const allowList = nodeSpec.toolPolicy.allow.length > 0 ? new Set(nodeSpec.toolPolicy.allow) : null
+
+  return Object.fromEntries(
+    Object.entries(tools).filter(
+      ([toolName]) =>
+        !blockedToolNames.has(toolName) &&
+        (toolName === SUBMIT_PLAN_TURN_RESULT_TOOL_NAME || allowList === null || allowList.has(toolName)),
+    ),
+  )
+}
+
 export interface WorkstreamTurnParams {
   workstream: NormalizedWorkstream
   workstreamRef: RecordIdRef
@@ -207,6 +404,17 @@ export interface WorkstreamApprovalContinuationParams {
   streamId?: string
 }
 
+export interface WorkstreamPlanTurnParams {
+  workstream: NormalizedWorkstream
+  workstreamRef: RecordIdRef
+  orgRef: RecordIdRef
+  userRef: RecordIdRef
+  userName?: string | null
+  planTurn: WorkstreamPlanTurnContext
+  abortSignal?: AbortSignal
+  streamId?: string
+}
+
 type WorkstreamRunCoreParams = {
   workstream: NormalizedWorkstream
   workstreamRef: RecordIdRef
@@ -220,6 +428,7 @@ type WorkstreamRunCoreParams = {
   | { kind: 'userTurn'; inputMessage: ChatMessage; skipInputMessagePersistence?: boolean }
   | { kind: 'approvalContinuation'; approvalMessages: ChatMessage[] }
   | { kind: 'nativeToolApprovalTurn'; approvalMessages: ChatMessage[] }
+  | { kind: 'planTurn'; planTurn: WorkstreamPlanTurnContext }
 )
 
 interface PreparedWorkstreamTurn {
@@ -617,7 +826,8 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
   let inputMessage: ChatMessage | undefined
   const shouldPersistInputMessage = params.kind === 'userTurn' ? params.skipInputMessagePersistence !== true : false
   const shouldProcessPostRunSideEffects =
-    params.kind === 'approvalContinuation' || params.kind === 'nativeToolApprovalTurn' || shouldPersistInputMessage
+    params.kind !== 'planTurn' &&
+    (params.kind === 'approvalContinuation' || params.kind === 'nativeToolApprovalTurn' || shouldPersistInputMessage)
   if (params.kind === 'userTurn') {
     inputMessage = hydrateMessageFileUrls(withMessageCreatedAt(params.inputMessage, Date.now()))
     if (inputMessage.role !== 'user') {
@@ -638,7 +848,10 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
 
   const workstreamRecord = await waitForWorkstreamCompactionIfNeeded(workstreamRef)
   timer.step('compaction-gate')
-  if (toOptionalTrimmedString(workstreamRecord.activeRunId)) {
+  if (
+    (await workstreamService.hasActiveRunLease(workstreamRef)) ||
+    toOptionalTrimmedString(workstreamRecord.activeRunId)
+  ) {
     const clearedStaleRun = await workstreamService.clearStaleActiveRunIfMissingFromRegistry(workstreamRef)
     if (!clearedStaleRun) {
       throw new WorkstreamTurnError('A chat run is already active.', 409)
@@ -713,10 +926,17 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
   const originalMessages = userMessage ? upsertChatHistoryMessage(liveHistory, userMessage) : liveHistory
   let allAssistantMessages: ChatMessage[] = []
   const referenceUserMessage =
-    params.kind === 'userTurn' && !shouldPersistInputMessage
-      ? [...liveHistory].reverse().find((m) => m.role === 'user')
-      : (userMessage ?? [...liveHistory].reverse().find((m) => m.role === 'user'))
-  const messageText = referenceUserMessage ? extractMessageText(referenceUserMessage).trim() : ''
+    params.kind === 'planTurn'
+      ? undefined
+      : params.kind === 'userTurn' && !shouldPersistInputMessage
+        ? [...liveHistory].reverse().find((m) => m.role === 'user')
+        : (userMessage ?? [...liveHistory].reverse().find((m) => m.role === 'user'))
+  const messageText =
+    params.kind === 'planTurn'
+      ? `${params.planTurn.nodeSpec.label}\n${params.planTurn.nodeSpec.objective}\n${params.planTurn.nodeSpec.instructions}`
+      : referenceUserMessage
+        ? extractMessageText(referenceUserMessage).trim()
+        : ''
 
   if (
     params.kind === 'userTurn' &&
@@ -975,9 +1195,17 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
             },
           })
 
-          const commitAssistantResponse = async (response: ChatMessage, agentId: string, agentName: string) => {
+          const commitAssistantResponse = async (
+            response: ChatMessage,
+            agentId: string,
+            agentName: string,
+            metadataPatch?: NonNullable<MessageMetadata>,
+          ) => {
             const committed = withMessageCreatedAt(
-              { ...response, metadata: { ...response.metadata, ...buildAgentMetadataPatch(agentId, agentName) } },
+              {
+                ...response,
+                metadata: { ...response.metadata, ...buildAgentMetadataPatch(agentId, agentName), ...metadataPatch },
+              },
               Date.now(),
             )
 
@@ -1017,11 +1245,15 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
             additionalInstructionSections?: string[]
             extraMessages?: ChatMessage[]
             extraTools?: ToolSet
+            filterTools?: (tools: ToolSet) => ToolSet
+            includeExecutionPlanTools?: boolean
+            metadataPatch?: NonNullable<MessageMetadata>
           }): Promise<ChatMessage> => {
             const visibleTimer = lotaDebugLogger.timer(`visible:${runParams.agentId}`)
             let runMemoryBlock = memoryBlock
-            const includeExecutionPlanTools = runParams.mode !== 'fixedWorkstreamMode' && !onboardingActive
-            const tools: ToolSet = {
+            const includeExecutionPlanTools =
+              runParams.includeExecutionPlanTools ?? (runParams.mode !== 'fixedWorkstreamMode' && !onboardingActive)
+            const rawTools: ToolSet = {
               ...((await buildAgentTools({
                 agentId: runParams.agentId,
                 orgId: orgRef,
@@ -1049,6 +1281,7 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
               ...toolProviders,
               ...runParams.extraTools,
             }
+            const tools = runParams.filterTools ? runParams.filterTools(rawTools) : rawTools
             visibleTimer.step('build-agent-tools')
             streamCtx.memoryBlock = memoryBlock
             const responseMessage = await streamAgentResponse(streamCtx, {
@@ -1069,6 +1302,7 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
               responseMessage,
               runParams.agentId,
               agentDisplayNames[runParams.agentId] ?? runParams.agentId,
+              runParams.metadataPatch,
             )
           }
 
@@ -1078,181 +1312,214 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
             return { inputMessageId: referenceUserMessage?.id, assistantMessages: [] }
           }
 
-          const consultSpecialistTool = createTool({
-            description: 'Consult one specialist teammate for domain-specific guidance before replying to the user.',
-            inputSchema: ConsultSpecialistArgsSchema,
-            execute: async function* (
-              { agentId, task }: z.infer<typeof ConsultSpecialistArgsSchema>,
-              { abortSignal: toolAbortSignal }: { abortSignal?: AbortSignal },
-            ) {
-              let specialistMemoryBlock = memoryBlock
-              const specialistTaskMessage = buildSpecialistTaskMessage({ agentId, task })
-              const specialistTools = await buildAgentTools({
-                agentId,
-                orgId: orgRef,
-                userId: userRef,
-                userName: userName ?? 'there',
-                workstreamId: workstreamRef,
-                orgIdString,
-                workstreamMode: workstream.mode,
-                mode: 'fixedWorkstreamMode',
-                linearInstalled,
-                onboardingActive,
-                githubInstalled,
-                provideRepoTool: indexedRepoContext.provideRepoTool,
-                defaultRepoSections: indexedRepoContext.defaultSectionsByAgent[agentId],
-                memoryBlock: specialistMemoryBlock,
-                onAppendMemoryBlock: (value: string) => {
-                  specialistMemoryBlock = value
-                },
-                availableUploads: listReadableUploads([specialistTaskMessage]),
-                includeExecutionPlanTools: false,
-                context: buildContextResult,
-              })
-
-              const [
-                specialistExecutionPlanInstructionSections,
-                specialistPreSeededMemories,
-                specialistWorkstreamState,
-                specialistLearnedSkills,
-              ] = await Promise.all([
-                getExecutionPlanInstructionSections(),
-                getPreSeededMemoriesSection(agentId),
-                getWorkstreamStateSection(),
-                getLearnedSkillsSection(agentId),
-              ])
-              const specialistConfig = getAgentRuntimeConfig({
-                agentId,
-                workstreamMode: workstream.mode,
-                mode: 'fixedWorkstreamMode',
-                onboardingActive,
-                linearInstalled,
-                systemWorkspaceDetails: promptContext.systemWorkspaceDetails,
-                preSeededMemoriesSection: specialistPreSeededMemories,
-                retrievedKnowledgeSection,
-                workstreamMemoryBlock: specialistMemoryBlock,
-                workstreamStateSection: specialistWorkstreamState,
-                learnedSkillsSection: specialistLearnedSkills,
-                additionalInstructionSections: mergeInstructionSections(
-                  specialistExecutionPlanInstructionSections,
-                  coreInstructionSections,
-                  hookInstructionSections,
-                ),
-                context: buildContextResult,
-              }) as Record<string, unknown>
-              const observer = createObserver(agentId)
-              const agent = createAgent[specialistConfig.id as string]({
-                mode: 'fixedWorkstreamMode',
-                tools: { ...(specialistTools as ToolSet), ...toolProviders },
-                extraInstructions: specialistConfig.extraInstructions,
-                stopWhen: [stepCountIs(specialistConfig.maxSteps as number)],
-              }) as ToolLoopAgent<never, ToolSet>
-              const modelMessages = await convertToModelMessages(buildRunInputMessages([specialistTaskMessage]), {
-                ignoreIncompleteToolCalls: true,
-              })
-              const specialistAbortSignal = toolAbortSignal ?? runAbort.signal
-              let result: unknown
-              try {
-                result = await observer.run(() =>
-                  agent.stream({ messages: modelMessages, abortSignal: specialistAbortSignal }),
-                )
-              } catch (error) {
-                if (specialistAbortSignal.aborted) {
-                  observer.recordAbort(error)
-                } else {
-                  observer.recordError(error)
-                }
-                throw error
-              }
-              if (!hasUIMessageStream(result)) {
-                throw new Error(`Specialist ${agentId} did not expose a UI message stream.`)
-              }
-
-              let finalMessage: ChatMessage | null = null
-              for await (const message of readUIMessageStream<ChatMessage>({
-                stream: result.toUIMessageStream({
-                  generateMessageId: () => Bun.randomUUIDv7(),
-                  sendReasoning: true,
-                  sendSources: true,
-                  sendStart: false,
-                  sendFinish: false,
-                  messageMetadata: createAgentMessageMetadata({
-                    agentId,
-                    agentName: specialistConfig.displayName as string,
-                  }),
-                }) as ReadableStream<never>,
-              })) {
-                finalMessage = withMessageCreatedAt(message, Date.now())
-                yield finalMessage
-              }
-
-              if (!finalMessage) {
-                throw new Error(`Specialist ${agentId} did not produce a response message.`)
-              }
-
-              for (const toolError of collectToolOutputErrors({ responseMessage: finalMessage })) {
-                aiLogger.warn`Tool execution failed (agent=${agentId}, tool=${toolError.toolName}, toolCallId=${toolError.toolCallId}): ${toolError.errorText}`
-              }
-
-              memoryBlock = specialistMemoryBlock
-              return finalMessage
-            },
-            toModelOutput: ({ output }) => {
-              const result = getChatMessageFromToolOutput(output)
-              const agentName =
-                typeof result?.metadata?.agentName === 'string' && result.metadata.agentName.trim().length > 0
-                  ? result.metadata.agentName.trim()
-                  : 'Specialist'
-              const summary = result ? extractMessageText(result).trim() : ''
-              return {
-                type: 'text',
-                value: summary ? `${agentName}: ${summary}` : `${agentName} completed the requested task.`,
-              }
-            },
-          })
+          if (params.kind === 'planTurn') {
+            const planTurn = params.planTurn
+            const submitPlanTurnNodeResultTool = createTool({
+              description: buildPlanTurnSubmitToolDescription(planTurn),
+              inputSchema: PlanNodeResultSubmissionSchema,
+              execute: async (result) =>
+                await executionPlanService.submitPlanTurnResult({
+                  workstreamId: workstreamRef,
+                  runId: planTurn.runId,
+                  nodeId: planTurn.nodeId,
+                  emittedBy: planTurn.nodeSpec.owner.ref,
+                  input: result,
+                }),
+            })
 
-          const teamThinkTool =
-            workstream.mode === 'group' && !onboardingActive
-              ? createTeamThinkTool({
-                  historyMessages: currentMessages,
-                  latestUserMessageId: referenceUserMessageId,
+            await runVisibleAgent({
+              agentId: planTurn.nodeSpec.owner.ref,
+              mode: workstream.mode === 'direct' ? 'direct' : 'workstreamMode',
+              additionalInstructionSections: mergeInstructionSections(
+                [buildPlanTurnExecutionSection(planTurn), buildPlanTurnResultContractSection(planTurn)],
+                optionalInstructionSection(buildUpstreamHandoffSection(planTurn.upstreamHandoffs)),
+              ),
+              extraMessages: [buildPlanTurnPromptMessage(planTurn)],
+              includeExecutionPlanTools: false,
+              extraTools: { [SUBMIT_PLAN_TURN_RESULT_TOOL_NAME]: submitPlanTurnNodeResultTool },
+              filterTools: (tools) => applyPlanTurnToolPolicy(tools, planTurn.nodeSpec),
+              metadataPatch: { trigger: 'plan-turn', planRunId: planTurn.runId, planNodeId: planTurn.nodeId },
+            })
+          } else {
+            const consultSpecialistTool = createTool({
+              description: 'Consult one specialist teammate for domain-specific guidance before replying to the user.',
+              inputSchema: ConsultSpecialistArgsSchema,
+              execute: async function* (
+                { agentId, task }: z.infer<typeof ConsultSpecialistArgsSchema>,
+                { abortSignal: toolAbortSignal }: { abortSignal?: AbortSignal },
+              ) {
+                let specialistMemoryBlock = memoryBlock
+                const specialistTaskMessage = buildSpecialistTaskMessage({ agentId, task })
+                const specialistTools = await buildAgentTools({
+                  agentId,
                   orgId: orgRef,
                   userId: userRef,
+                  userName: userName ?? 'there',
                   workstreamId: workstreamRef,
+                  orgIdString,
+                  workstreamMode: workstream.mode,
+                  mode: 'fixedWorkstreamMode',
+                  linearInstalled,
+                  onboardingActive,
                   githubInstalled,
-                  availableUploads: listReadableUploads(),
                   provideRepoTool: indexedRepoContext.provideRepoTool,
-                  defaultRepoSectionsByAgent: indexedRepoContext.defaultSectionsByAgent as never,
+                  defaultRepoSections: indexedRepoContext.defaultSectionsByAgent[agentId],
+                  memoryBlock: specialistMemoryBlock,
+                  onAppendMemoryBlock: (value: string) => {
+                    specialistMemoryBlock = value
+                  },
+                  availableUploads: listReadableUploads([specialistTaskMessage]),
+                  includeExecutionPlanTools: false,
+                  context: buildContextResult,
+                })
+
+                const [
+                  specialistExecutionPlanInstructionSections,
+                  specialistPreSeededMemories,
+                  specialistWorkstreamState,
+                  specialistLearnedSkills,
+                ] = await Promise.all([
+                  getExecutionPlanInstructionSections(),
+                  getPreSeededMemoriesSection(agentId),
+                  getWorkstreamStateSection(),
+                  getLearnedSkillsSection(agentId),
+                ])
+                const specialistConfig = getAgentRuntimeConfig({
+                  agentId,
+                  workstreamMode: workstream.mode,
+                  mode: 'fixedWorkstreamMode',
+                  onboardingActive,
+                  linearInstalled,
                   systemWorkspaceDetails: promptContext.systemWorkspaceDetails,
-                  getPreSeededMemoriesSection,
+                  preSeededMemoriesSection: specialistPreSeededMemories,
                   retrievedKnowledgeSection,
+                  workstreamMemoryBlock: specialistMemoryBlock,
+                  workstreamStateSection: specialistWorkstreamState,
+                  learnedSkillsSection: specialistLearnedSkills,
                   additionalInstructionSections: mergeInstructionSections(
+                    specialistExecutionPlanInstructionSections,
                     coreInstructionSections,
                     hookInstructionSections,
                   ),
-                  getAdditionalInstructionSections: getExecutionPlanInstructionSections,
                   context: buildContextResult,
-                  toolProviders,
-                  abortSignal: runAbort.signal,
+                }) as Record<string, unknown>
+                const observer = createObserver(agentId)
+                const agent = createAgent[specialistConfig.id as string]({
+                  mode: 'fixedWorkstreamMode',
+                  tools: { ...(specialistTools as ToolSet), ...toolProviders },
+                  extraInstructions: specialistConfig.extraInstructions,
+                  stopWhen: [stepCountIs(specialistConfig.maxSteps as number)],
+                }) as ToolLoopAgent<never, ToolSet>
+                const modelMessages = await convertToModelMessages(buildRunInputMessages([specialistTaskMessage]), {
+                  ignoreIncompleteToolCalls: true,
                 })
-              : null
+                const specialistAbortSignal = toolAbortSignal ?? runAbort.signal
+                let result: unknown
+                try {
+                  result = await observer.run(() =>
+                    agent.stream({ messages: modelMessages, abortSignal: specialistAbortSignal }),
+                  )
+                } catch (error) {
+                  if (specialistAbortSignal.aborted) {
+                    observer.recordAbort(error)
+                  } else {
+                    observer.recordError(error)
+                  }
+                  throw error
+                }
+                if (!hasUIMessageStream(result)) {
+                  throw new Error(`Specialist ${agentId} did not expose a UI message stream.`)
+                }
 
-          if (workstream.mode === 'direct') {
-            if (!workstream.agentId) {
-              throw new WorkstreamTurnError('Direct workstreams require an assigned agent.', 400)
-            }
-            await runVisibleAgent({ agentId: workstream.agentId, mode: 'direct' })
-          } else {
-            await runVisibleAgent({
-              agentId: visibleWorkstreamAgentId ?? defaultLeadAgentId,
-              mode: 'workstreamMode',
-              skills: coreWorkstreamProfile?.skills ? [...coreWorkstreamProfile.skills] : undefined,
-              additionalInstructionSections: mergeInstructionSections(coreInstructionSections, hookInstructionSections),
-              extraTools: {
-                [CONSULT_SPECIALIST_TOOL_NAME]: consultSpecialistTool,
-                ...(teamThinkTool ? { [CONSULT_TEAM_TOOL_NAME]: teamThinkTool } : {}),
+                let finalMessage: ChatMessage | null = null
+                for await (const message of readUIMessageStream<ChatMessage>({
+                  stream: result.toUIMessageStream({
+                    generateMessageId: () => Bun.randomUUIDv7(),
+                    sendReasoning: true,
+                    sendSources: true,
+                    sendStart: false,
+                    sendFinish: false,
+                    messageMetadata: createAgentMessageMetadata({
+                      agentId,
+                      agentName: specialistConfig.displayName as string,
+                    }),
+                  }) as ReadableStream<never>,
+                })) {
+                  finalMessage = withMessageCreatedAt(message, Date.now())
+                  yield finalMessage
+                }
+
+                if (!finalMessage) {
+                  throw new Error(`Specialist ${agentId} did not produce a response message.`)
+                }
+
+                for (const toolError of collectToolOutputErrors({ responseMessage: finalMessage })) {
+                  aiLogger.warn`Tool execution failed (agent=${agentId}, tool=${toolError.toolName}, toolCallId=${toolError.toolCallId}): ${toolError.errorText}`
+                }
+
+                memoryBlock = specialistMemoryBlock
+                return finalMessage
+              },
+              toModelOutput: ({ output }) => {
+                const result = getChatMessageFromToolOutput(output)
+                const agentName =
+                  typeof result?.metadata?.agentName === 'string' && result.metadata.agentName.trim().length > 0
+                    ? result.metadata.agentName.trim()
+                    : 'Specialist'
+                const summary = result ? extractMessageText(result).trim() : ''
+                return {
+                  type: 'text',
+                  value: summary ? `${agentName}: ${summary}` : `${agentName} completed the requested task.`,
+                }
               },
             })
+
+            const teamThinkTool =
+              workstream.mode === 'group' && !onboardingActive
+                ? createTeamThinkTool({
+                    historyMessages: currentMessages,
+                    latestUserMessageId: referenceUserMessageId,
+                    orgId: orgRef,
+                    userId: userRef,
+                    workstreamId: workstreamRef,
+                    githubInstalled,
+                    availableUploads: listReadableUploads(),
+                    provideRepoTool: indexedRepoContext.provideRepoTool,
+                    defaultRepoSectionsByAgent: indexedRepoContext.defaultSectionsByAgent as never,
+                    systemWorkspaceDetails: promptContext.systemWorkspaceDetails,
+                    getPreSeededMemoriesSection,
+                    retrievedKnowledgeSection,
+                    additionalInstructionSections: mergeInstructionSections(
+                      coreInstructionSections,
+                      hookInstructionSections,
+                    ),
+                    getAdditionalInstructionSections: getExecutionPlanInstructionSections,
+                    context: buildContextResult,
+                    toolProviders,
+                    abortSignal: runAbort.signal,
+                  })
+                : null
+
+            if (workstream.mode === 'direct') {
+              if (!workstream.agentId) {
+                throw new WorkstreamTurnError('Direct workstreams require an assigned agent.', 400)
+              }
+              await runVisibleAgent({ agentId: workstream.agentId, mode: 'direct' })
+            } else {
+              await runVisibleAgent({
+                agentId: visibleWorkstreamAgentId ?? defaultLeadAgentId,
+                mode: 'workstreamMode',
+                skills: coreWorkstreamProfile?.skills ? [...coreWorkstreamProfile.skills] : undefined,
+                additionalInstructionSections: mergeInstructionSections(
+                  coreInstructionSections,
+                  hookInstructionSections,
+                ),
+                extraTools: {
+                  [CONSULT_SPECIALIST_TOOL_NAME]: consultSpecialistTool,
+                  ...(teamThinkTool ? { [CONSULT_TEAM_TOOL_NAME]: teamThinkTool } : {}),
+                },
+              })
+            }
           }
         } finally {
           try {
@@ -1312,7 +1579,7 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
               })
             }
 
-            if (allAssistantMessages.length > 0) {
+            if (allAssistantMessages.length > 0 && params.kind !== 'planTurn') {
               await turnHooks.afterTurn?.({
                 workstream,
                 workstreamRef,
@@ -1333,12 +1600,21 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
         }
       }
 
-      const runResult = await executeRun()
-      if (runResult) {
-        return runResult
-      }
+      try {
+        return await workstreamService.withActiveRunLease(workstreamRef, async () => {
+          const runResult = await executeRun()
+          if (runResult) {
+            return runResult
+          }
 
-      return { inputMessageId: referenceUserMessage?.id, assistantMessages: [...allAssistantMessages] }
+          return { inputMessageId: referenceUserMessage?.id, assistantMessages: [...allAssistantMessages] }
+        })
+      } catch (error) {
+        if (error instanceof ActiveWorkstreamRunConflictError) {
+          throw new WorkstreamTurnError(error.message, 409)
+        }
+        throw error
+      }
     },
   }
 }