@lota-sdk/core 0.1.46 → 0.1.48

package/src/runtime/execution-plan.ts

@@ -1,5 +1,7 @@
 import type { SerializableExecutionPlan } from '@lota-sdk/shared'
 
+type ExecutionPlanPromptSummary = Pick<SerializableExecutionPlan, 'runId' | 'title'>
+
 const EXECUTION_PLAN_AGENT_PROTOCOL_PROMPT = `<execution-plan-protocol>
 - Create execution plans for multi-step work. Review existing plans before creating new ones.
 - The runtime executor owns lifecycle truth. Do not claim node completion until the executor confirms.
@@ -9,10 +11,14 @@ const EXECUTION_PLAN_AGENT_PROTOCOL_PROMPT = `<execution-plan-protocol>
 - If contracts or criteria materially change, replace the plan.
 </execution-plan-protocol>`
 
+function toExecutionPlanPromptSummaries(plans: SerializableExecutionPlan[]): ExecutionPlanPromptSummary[] {
+  return plans.map(({ runId, title }) => ({ runId, title }))
+}
+
 function formatExecutionPlansForPrompt(plans: SerializableExecutionPlan[]): string | undefined {
   if (plans.length === 0) return undefined
 
-  const payload = { activePlans: plans, planCount: plans.length }
+  const payload = { activePlans: toExecutionPlanPromptSummaries(plans), planCount: plans.length }
 
   return ['<execution-plan-state>', JSON.stringify(payload, null, 2), '</execution-plan-state>'].join('\n')
 }

package/src/runtime/index.ts

@@ -25,15 +25,3 @@ export * from './team-consultation-orchestrator'
 export * from './team-consultation-prompts'
 export * from './turn-lifecycle'
 export * from './workstream-chat-helpers'
-export {
-  WorkstreamStateSchema,
-  type WorkstreamState,
-  type WorkstreamStateDelta,
-  StructuredWorkstreamStateDeltaSchema,
-  type StructuredWorkstreamStateDelta,
-  createEmptyStructuredWorkstreamStateDelta,
-  parseStructuredWorkstreamStateDelta,
-  StructuredCompactionOutputSchema,
-  type CompactionOutput,
-  createEmptyWorkstreamState,
-} from './workstream-state'

package/src/runtime/post-turn-side-effects.ts

@@ -28,7 +28,6 @@ import { workstreamService } from '../services/workstream.service'
 import type { NormalizedWorkstream, WorkstreamRecord } from '../services/workstream.types'
 import { safeEnqueue } from '../utils/async'
 import { toIsoDateTimeString } from '../utils/date-time'
-import type { WorkstreamState } from './workstream-state'
 
 function buildRecentActivityChatDeepLink(params: {
   workstream: NormalizedWorkstream
@@ -77,7 +76,6 @@ interface PostTurnSideEffectsParams {
   visibleWorkstreamAgentId: string | null | undefined
   defaultLeadAgentId: string
   latestWorkstreamRecord: WorkstreamRecord
-  latestPersistedState: WorkstreamState | null
   isUserTurn: boolean
 }
 
@@ -87,7 +85,6 @@ export async function runPostTurnSideEffects(params: PostTurnSideEffectsParams):
   const agentMessages = buildAgentHistoryMessages(params.allAssistantMessages)
   const historyMessagesForMemory = appendPersistedWorkstreamContextToHistoryMessages(toHistoryMessages(recentHistory), {
     compactionSummary: params.latestWorkstreamRecord.compactionSummary,
-    persistedState: params.latestPersistedState,
   })
 
   const userMessageText = params.referenceUserMessage ? extractMessageText(params.referenceUserMessage).trim() : ''

package/src/runtime/runtime-extensions.ts

@@ -132,7 +132,6 @@ export interface AfterTurnParams {
   referenceUserMessage: unknown
   assistantMessages: unknown[]
   latestWorkstreamRecord: unknown
-  latestPersistedState: unknown
   context: Record<string, unknown> | null
   [key: string]: unknown
 }

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

@@ -88,7 +88,7 @@ export function buildAgentHistoryMessages(messages: ChatMessageLike[]): Array<{
 
 export function appendPersistedWorkstreamContextToHistoryMessages(
   historyMessages: WorkstreamHistoryMessage[],
-  params: { compactionSummary?: string | null; persistedState?: unknown },
+  params: { compactionSummary?: string | null },
 ): WorkstreamHistoryMessage[] {
   const nextHistoryMessages = [...historyMessages]
   const compactionSummary = typeof params.compactionSummary === 'string' ? params.compactionSummary.trim() : ''
@@ -96,13 +96,6 @@ export function appendPersistedWorkstreamContextToHistoryMessages(
     nextHistoryMessages.push({ role: 'agent', content: `Compacted chat summary:\n${compactionSummary}` })
   }
 
-  if (params.persistedState !== null && params.persistedState !== undefined) {
-    nextHistoryMessages.push({
-      role: 'agent',
-      content: `Structured workstream state:\n${JSON.stringify(params.persistedState)}`,
-    })
-  }
-
   return nextHistoryMessages
 }
 

package/src/services/context-compaction.service.ts

@@ -7,10 +7,8 @@ import { databaseService } from '../db/service'
 import { TABLES } from '../db/tables'
 import { getRedisConnection } from '../redis/connection-accessor'
 import { withRedisLeaseLock } from '../redis/redis-lease-lock'
-import { parseWorkstreamState, toStateFieldsUpdated } from '../runtime/context-compaction'
 import { CONTEXT_WINDOW_TOKENS, WORKSTREAM_RAW_TAIL_MESSAGES } from '../runtime/context-compaction-constants'
-import type { WorkstreamState } from '../runtime/workstream-state'
-import { compactMemoryBlockSummary, contextCompactionRuntime } from './context-compaction-runtime.singleton'
+import { contextCompactionRuntime, compactMemoryBlockSummary } from './context-compaction-runtime.singleton'
 import { workstreamMessageService } from './workstream-message.service'
 import { WorkstreamSchema } from './workstream.types'
 
@@ -24,8 +22,6 @@ interface PersistedCompactionMetrics {
   compactedMessageCount: number
   remainingMessageCount: number
   estimatedTokens: number
-  stateFieldsUpdated: string[]
-  conflictsDetected: number
 }
 
 class ContextCompactionService {
@@ -33,10 +29,6 @@ class ContextCompactionService {
     return contextCompactionRuntime.createSummaryMessage(summaryText)
   }
 
-  formatWorkstreamStateForPrompt(state: WorkstreamState | null | undefined) {
-    return contextCompactionRuntime.formatWorkstreamStateForPrompt(state)
-  }
-
   estimateThreshold(contextSize = CONTEXT_WINDOW_TOKENS): number {
     return contextCompactionRuntime.estimateThreshold(contextSize)
   }
@@ -48,7 +40,7 @@ class ContextCompactionService {
   async compactWorkstreamHistory(params: {
     workstreamId: RecordIdRef
     contextSize?: number
-  }): Promise<{ compacted: boolean; state: WorkstreamState | null }> {
+  }): Promise<{ compacted: boolean }> {
     const entityId = recordIdToString(params.workstreamId, TABLES.WORKSTREAM)
 
     return withRedisLeaseLock(
@@ -69,7 +61,6 @@ class ContextCompactionService {
           throw new Error(`Workstream not found for compaction: ${entityId}`)
         }
 
-        const currentState = parseWorkstreamState(workstream.state)
         const liveMessages = await workstreamMessageService.listMessagesAfterCursor(
           params.workstreamId,
           typeof workstream.lastCompactedMessageId === 'string' ? workstream.lastCompactedMessageId : undefined,
@@ -80,11 +71,10 @@ class ContextCompactionService {
           liveMessages,
           tailMessageCount: WORKSTREAM_RAW_TAIL_MESSAGES,
           contextSize: params.contextSize,
-          existingState: currentState,
         })
 
         if (!result.compacted || !result.lastCompactedMessageId) {
-          return { compacted: false, state: currentState }
+          return { compacted: false }
         }
 
         if (result.compactedMessages.length > 0) {
@@ -97,11 +87,7 @@ class ContextCompactionService {
         await databaseService.update(
           TABLES.WORKSTREAM,
           params.workstreamId,
-          {
-            compactionSummary: result.summaryText,
-            lastCompactedMessageId: result.lastCompactedMessageId,
-            state: result.state,
-          },
+          { compactionSummary: result.summaryText, lastCompactedMessageId: result.lastCompactedMessageId },
           WorkstreamSchema,
         )
 
@@ -115,11 +101,9 @@ class ContextCompactionService {
           compactedMessageCount: result.compactedMessageCount,
           remainingMessageCount: result.remainingMessageCount,
           estimatedTokens: result.estimatedTokens,
-          stateFieldsUpdated: toStateFieldsUpdated(result.stateDelta),
-          conflictsDetected: result.stateDelta.conflicts?.length ?? 0,
         })
 
-        return { compacted: true, state: result.state }
+        return { compacted: true }
       },
     )
   }

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

@@ -34,7 +34,6 @@ import { hasApprovalRespondedParts } from '../runtime/approval-continuation'
 import { buildModelInputMessagesWithUploadMetadata, buildReadableUploadMetadataText } from '../runtime/chat-attachments'
 import { hasMessageContent } from '../runtime/chat-message'
 import { waitForCompactionIfNeeded } from '../runtime/chat-run-orchestration'
-import { parseWorkstreamState } from '../runtime/context-compaction'
 import { CONTEXT_WINDOW_TOKENS } from '../runtime/context-compaction-constants'
 import { createExecutionPlanInstructionSectionCache } from '../runtime/execution-plan'
 import { mergeInstructionSections } from '../runtime/instruction-sections'
@@ -55,7 +54,6 @@ import {
   buildPlanTurnSubmitToolDescription,
 } from '../runtime/workstream-plan-turn'
 import type { WorkstreamPlanTurnContext } from '../runtime/workstream-plan-turn'
-import type { WorkstreamState } from '../runtime/workstream-state'
 import { assembleWorkstreamTurnContext } from '../runtime/workstream-turn-context'
 import { chatRunRegistry } from '../services/chat-run-registry.service'
 import type { NormalizedWorkstream, WorkstreamRecord } from '../services/workstream.types'
@@ -88,15 +86,6 @@ function hasUIMessageStream(value: unknown): value is UIMessageStreamResult {
 
 const PRESEEDED_MEMORY_LOOKUP_LIMIT = 3
 
-function stripExecutionPlanFieldsFromWorkstreamState(
-  state: WorkstreamState | null | undefined,
-  hasExecutionPlan: boolean,
-): WorkstreamState | null | undefined {
-  if (!state || !hasExecutionPlan) return state
-
-  return { ...state, currentPlan: null, tasks: [], artifacts: [] }
-}
-
 async function waitForWorkstreamCompactionIfNeeded(workstreamId: RecordIdRef): Promise<WorkstreamRecord> {
   return waitForCompactionIfNeeded({
     entityId: recordIdToString(workstreamId, TABLES.WORKSTREAM),
@@ -121,6 +110,26 @@ function optionalInstructionSection(value: unknown): string[] | undefined {
   return section ? [section] : undefined
 }
 
+function writeMultiAgentEvent(
+  writer: UIMessageStreamWriter<ChatMessage> | undefined,
+  event: {
+    phase: 'routing' | 'waiting-for-agent' | 'agent-message-persisted' | 'complete'
+    agentId?: string
+    agentName?: string
+    messageId?: string
+    note?: string
+  },
+): void {
+  if (!writer) return
+
+  writer.write({
+    type: 'data-multi-agent-event',
+    id: `multi-agent-${Bun.randomUUIDv7()}`,
+    data: event,
+    transient: true,
+  } as unknown as ChatStreamChunk)
+}
+
 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
@@ -219,7 +228,6 @@ interface StreamAgentResponseContext {
   buildContextResult: Record<string, unknown> | null
   getExecutionPlanInstructionSections: () => Promise<string[] | undefined>
   getPreSeededMemoriesSection: (agentId: string) => Promise<string | undefined>
-  getWorkstreamStateSection: () => Promise<string | undefined>
   getLearnedSkillsSection: (agentId: string, queryText?: string) => Promise<string | undefined>
   promptContext: { systemWorkspaceDetails?: string }
   retrievedKnowledgeSection: string | undefined
@@ -245,7 +253,6 @@ interface StreamAgentResponseParams {
   stopWhen?: StopCondition<ToolSet> | Array<StopCondition<ToolSet>>
   prepareStep?: PrepareStepFunction<ToolSet>
   abortSignal?: AbortSignal
-  suppressFinish?: boolean
 }
 
 async function streamAgentResponse(
@@ -278,12 +285,11 @@ async function streamAgentResponse(
   const resolvedAgentId = readOptionalString(agentResolution?.agentId) ?? streamParams.agentId
   const latestUserMessage = [...streamParams.messages].reverse().find((message) => message.role === 'user')
   const latestUserMessageText = latestUserMessage ? extractMessageText(latestUserMessage).trim() : undefined
-  const [preSeededMemoriesSection, workstreamStateSection, learnedSkillsSection] = await Promise.all([
+  const [preSeededMemoriesSection, learnedSkillsSection] = await Promise.all([
     ctx.getPreSeededMemoriesSection(resolvedAgentId),
-    ctx.getWorkstreamStateSection(),
     ctx.getLearnedSkillsSection(resolvedAgentId, latestUserMessageText),
   ])
-  agentTimer.step('parallel-fetch(memories+state+skills)')
+  agentTimer.step('parallel-fetch(memories+skills)')
   const toolNames = new Set(Object.keys(streamParams.tools))
   const hasRetrievalTools = [
     'memorySearch',
@@ -308,7 +314,6 @@ async function streamAgentResponse(
     preSeededMemoriesSection,
     retrievedKnowledgeSection: ctx.retrievedKnowledgeSection,
     workstreamMemoryBlock: ctx.memoryBlock,
-    workstreamStateSection,
     learnedSkillsSection,
     userMessageText: latestUserMessageText,
     ruleOptions: { includeMemr3Rule: hasRetrievalTools, includeDomainReasoningFallbackRule: hasDomainRoutingSkills },
@@ -395,15 +400,6 @@ async function streamAgentResponse(
         firstChunkLogged = true
       }
       if (streamParams.writer) {
-        if (
-          streamParams.suppressFinish &&
-          typeof value === 'object' &&
-          value !== null &&
-          'type' in value &&
-          (value as { type: string }).type === 'finish'
-        ) {
-          continue
-        }
         streamParams.writer.write(value)
       }
     }
@@ -497,7 +493,6 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
     timer.step('persist-approval-message')
   }
 
-  const initialWorkstreamState = parseWorkstreamState(workstreamRecord.state)
   const persistedCompactionCursor = toOptionalTrimmedString(workstreamRecord.lastCompactedMessageId) ?? undefined
   const persistedLiveHistoryPromise = workstreamMessageService.listMessagesAfterCursor(
     workstreamRef,
@@ -630,7 +625,6 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
   } = assembledContext
 
   let memoryBlock = workstreamService.formatMemoryBlockForPrompt(workstreamRecord)
-  let workstreamState = initialWorkstreamState
   const executionPlanInstructionSectionCache = createExecutionPlanInstructionSectionCache({
     disabled: false,
     loadPlans: async () => {
@@ -638,18 +632,11 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
       return Promise.all(runs.map((run) => planRunService.toSerializablePlan(run, { slim: true })))
     },
   })
-  const getExecutionPlans = async () => await executionPlanInstructionSectionCache.getPlans()
   const getExecutionPlanInstructionSections = async (): Promise<string[] | undefined> =>
     await executionPlanInstructionSectionCache.getSections()
   const invalidateExecutionPlanInstructionSections = () => {
     executionPlanInstructionSectionCache.invalidate()
   }
-  const getWorkstreamStateSection = async (): Promise<string | undefined> => {
-    const executionPlans = await getExecutionPlans()
-    return contextCompactionRuntime.formatWorkstreamStateForPrompt(
-      stripExecutionPlanFieldsFromWorkstreamState(workstreamState, executionPlans.length > 0),
-    )
-  }
   if (userMessage) {
     const appliedHumanInput = await executionPlanService.applyHumanInputFromUserMessage({
       workstreamId: workstreamRef,
@@ -747,10 +734,13 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
   return {
     originalMessages,
     run: async (writer?: UIMessageStreamWriter<ChatMessage>) => {
-      const executeRun = async (): Promise<PreparedWorkstreamTurnResult | void> => {
+      const executeRun = async (leaseAbortSignal?: AbortSignal): Promise<PreparedWorkstreamTurnResult | void> => {
         const runTimer = lotaDebugLogger.timer('run')
         const serverRunId = Bun.randomUUIDv7()
-        const runAbort = createServerRunAbortController(params.abortSignal)
+        const runAbortSignals = leaseAbortSignal ? [params.abortSignal, leaseAbortSignal] : [params.abortSignal]
+        const runAbort = createServerRunAbortController(
+          runAbortSignals.filter((signal): signal is AbortSignal => Boolean(signal)),
+        )
         // Plan turns run without the chat lease — don't claim the active run slot.
         if (params.kind !== 'planTurn') {
           await workstreamService.setActiveTurn(workstreamRef, serverRunId, params.streamId ?? null)
@@ -809,7 +799,6 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
             buildContextResult,
             getExecutionPlanInstructionSections,
             getPreSeededMemoriesSection,
-            getWorkstreamStateSection,
             getLearnedSkillsSection,
             promptContext,
             retrievedKnowledgeSection,
@@ -828,7 +817,7 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
             filterTools?: (tools: ToolSet) => ToolSet
             includeExecutionPlanTools?: boolean
             metadataPatch?: NonNullable<MessageMetadata>
-            suppressFinish?: boolean
+            headless?: boolean
           }): Promise<ChatMessage> => {
             const visibleTimer = lotaDebugLogger.timer(`visible:${runParams.agentId}`)
             let runMemoryBlock = memoryBlock
@@ -863,8 +852,7 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
               skills: runParams.skills,
               additionalInstructionSections: runParams.additionalInstructionSections,
               includeExecutionPlanTools,
-              writer,
-              suppressFinish: runParams.suppressFinish,
+              writer: runParams.headless ? undefined : writer,
             })
 
             visibleTimer.step('stream-agent-response')
@@ -914,6 +902,7 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
               const wsMembers = (workstream as { members?: string[] }).members ?? []
               const members = wsMembers.length > 0 ? wsMembers : [...agentRoster]
               const fallbackAgentId = coreWorkstreamProfile?.config.agentId ?? defaultLeadAgentId
+              writeMultiAgentEvent(writer, { phase: 'routing', note: 'Routing this turn to the right agent.' })
 
               const recentContext = currentMessages
                 .slice(-6)
@@ -929,7 +918,7 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
 
               const runGroupAgent = async (
                 agentId: string,
-                options?: { routingContext?: string; suppressFinish?: boolean },
+                options?: { routingContext?: string; headless?: boolean },
               ) => {
                 const additionalSections = [...(coreInstructionSections ?? []), ...hookInstructionSections]
                 if (options?.routingContext) {
@@ -945,22 +934,23 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
                   mode: 'workstreamMode',
                   skills: coreWorkstreamProfile?.skills ? [...coreWorkstreamProfile.skills] : undefined,
                   additionalInstructionSections: additionalSections,
-                  suppressFinish: options?.suppressFinish,
+                  headless: options?.headless,
                 })
               }
 
               if (!triageResult) {
-                // No specialist match — fallback to owner (core) or chief (non-core), single agent turn
+                // No specialist match — fallback to owner (core) or chief (non-core), single visible turn.
                 await runGroupAgent(fallbackAgentId)
+                writeMultiAgentEvent(writer, { phase: 'complete' })
               } else {
-                // Run first routed agent — let finish flow naturally so the stream resets between agents
                 const respondedAgents: string[] = []
                 let lastResponse = await runGroupAgent(triageResult.agentId, {
                   routingContext: triageResult.routingContext,
                 })
                 respondedAgents.push(triageResult.agentId)
 
-                // Check if more agents should respond (max 3 total)
+                // Follow-up specialists run headless, persist their own messages,
+                // and are surfaced by transient events plus cache refresh.
                 while (respondedAgents.length < 3) {
                   const lastResponseText = extractMessageText(lastResponse).slice(0, 500)
                   const checkResult = await checkForNextAgent({
@@ -973,6 +963,13 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
 
                   if (checkResult.done || !checkResult.agentId) break
 
+                  writeMultiAgentEvent(writer, {
+                    phase: 'waiting-for-agent',
+                    agentId: checkResult.agentId,
+                    agentName: agentDisplayNames[checkResult.agentId] ?? checkResult.agentId,
+                    note: checkResult.routingContext,
+                  })
+
                   // Insert hidden bridge message between agent turns
                   const bridgeMessage: ChatMessage = {
                     id: Bun.randomUUIDv7(),
@@ -993,16 +990,24 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
 
                   lastResponse = await runGroupAgent(checkResult.agentId, {
                     routingContext: checkResult.routingContext,
+                    headless: true,
                   })
                   respondedAgents.push(checkResult.agentId)
+                  writeMultiAgentEvent(writer, {
+                    phase: 'agent-message-persisted',
+                    agentId: checkResult.agentId,
+                    agentName: agentDisplayNames[checkResult.agentId] ?? checkResult.agentId,
+                    messageId: lastResponse.id,
+                  })
                 }
+
+                writeMultiAgentEvent(writer, { phase: 'complete' })
               }
             }
           }
         } finally {
           try {
             const latestWorkstreamRecord = await workstreamService.getById(workstreamRef)
-            const latestPersistedState = parseWorkstreamState(latestWorkstreamRecord.state)
 
             await finalizeTurnRun({
               serverRunId,
@@ -1056,7 +1061,6 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
                 visibleWorkstreamAgentId,
                 defaultLeadAgentId,
                 latestWorkstreamRecord,
-                latestPersistedState,
                 isUserTurn: params.kind === 'userTurn',
               })
             }
@@ -1072,7 +1076,6 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
                 referenceUserMessage,
                 assistantMessages: allAssistantMessages,
                 latestWorkstreamRecord,
-                latestPersistedState,
                 context: buildContextResult,
               })
             }
@@ -1093,8 +1096,8 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
       }
 
       try {
-        return await workstreamService.withActiveRunLease(workstreamRef, async () => {
-          const runResult = await executeRun()
+        return await workstreamService.withActiveRunLease(workstreamRef, async (leaseAbortSignal) => {
+          const runResult = await executeRun(leaseAbortSignal)
           if (runResult) {
             return runResult
           }

package/src/system-agents/context-compaction.agent.ts

@@ -10,30 +10,24 @@ import type { CreateHelperToolLoopAgentOptions } from '../runtime/agent-types'
 import { resolveHelperAgentOptions } from './helper-agent-options'
 
 const CONTEXT_COMPACTION_PROMPT = `<agent-instructions>
-You are a **Context Compacter** that produces both:
-1) a dense but shorter summary of prior context
-2) a structured state delta for durable execution continuity
+You are a **Context Compacter** that produces one dense replacement summary of prior context.
 
 <task>
 Compress historical context while preserving execution-critical details.
-When provided with existing state, update only changed fields.
 </task>
 
 <rules>
 - Preserve concrete decisions, constraints, assumptions, plans, open questions, and unresolved risks.
 - Preserve action ownership, specialist consultations, and the latest working direction.
-- Preserve provenance by attaching \`sourceMessageIds\` only from the provided message IDs.
 - Keep identifiers, numbers, dates, and proper nouns when present.
 - Remove filler and repetition.
 - Do not invent details.
-- If uncertain, prefer an empty array or null over guessing.
+- If uncertain, omit the detail rather than guessing.
 </rules>
 
 <output-format>
-The caller enforces a structured output schema.
-Return valid data for:
-- summary: concise text summary
-- stateDelta: include every field; use empty arrays for unchanged list fields, null for unchanged nullable fields, and \`currentPlan.action\` to signal \`unchanged\`, \`clear\`, or \`set\`
+The caller enforces a structured output schema with exactly one field:
+- summary: concise replacement summary
 </output-format>
 </agent-instructions>`
 

package/src/system-agents/workstream-router.agent.ts

@@ -3,7 +3,13 @@ import { z } from 'zod'
 
 import { aiGatewayChatModel } from '../ai-gateway/ai-gateway'
 import { buildAiGatewayDirectCacheHeaders } from '../ai-gateway/cache-headers'
-import { agentDescriptions, agentDisplayNames, routerModelId } from '../config/agent-defaults'
+import {
+  agentDescriptions,
+  agentDisplayNames,
+  agentShortDisplayNames,
+  resolveAgentNameAlias,
+  routerModelId,
+} from '../config/agent-defaults'
 
 // ---------------------------------------------------------------------------
 // Schemas
@@ -34,6 +40,60 @@ function buildMembersDescription(members: readonly string[]): string {
     .join('\n')
 }
 
+function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+function buildExplicitAgentRoutingContext(agentId: string): string {
+  const displayName = agentDisplayNames[agentId] ?? agentId
+  return `Respond directly to the part of the user's request explicitly addressed to ${displayName}.`
+}
+
+function extractExplicitAgentTargets(messageText: string, members: readonly string[]): string[] {
+  const normalizedMessage = messageText.trim()
+  if (!normalizedMessage) return []
+
+  const memberSet = new Set(members)
+  const aliases = new Map<string, string>()
+
+  for (const member of members) {
+    for (const rawAlias of [member, agentDisplayNames[member], agentShortDisplayNames[member]]) {
+      if (typeof rawAlias !== 'string') continue
+      const alias = rawAlias.trim().toLowerCase()
+      if (!alias) continue
+      aliases.set(alias, member)
+    }
+  }
+
+  if (aliases.size === 0) return []
+
+  const orderedAliases = [...aliases.keys()].sort((left, right) => right.length - left.length)
+  const matches: Array<{ agentId: string; index: number }> = []
+  const directAddressRegex = new RegExp(
+    `(^|[^\\w@])(?<alias>${orderedAliases.map(escapeRegex).join('|')})(?=\\s*(?::|\\-|—))`,
+    'gi',
+  )
+
+  for (const match of normalizedMessage.matchAll(directAddressRegex)) {
+    const alias = match.groups?.alias
+    const agentId = alias ? resolveAgentNameAlias(alias) : undefined
+    if (!agentId || !memberSet.has(agentId)) continue
+
+    const prefix = match[1]
+    const index = match.index + prefix.length
+    matches.push({ agentId, index })
+  }
+
+  const seenAgents = new Set<string>()
+  return matches
+    .sort((left, right) => left.index - right.index)
+    .flatMap(({ agentId }) => {
+      if (seenAgents.has(agentId)) return []
+      seenAgents.add(agentId)
+      return [agentId]
+    })
+}
+
 function extractJson(text: string): unknown {
   const match = text.match(/\{[\s\S]*\}/)
   if (!match) return null
@@ -53,7 +113,13 @@ function extractResultText(result: { text?: string; reasoning?: unknown }): stri
   if (typeof reasoning === 'string') return reasoning
   if (Array.isArray(reasoning)) {
     return reasoning
-      .map((r) => (typeof r === 'string' ? r : typeof r === 'object' && r && 'text' in r ? String(r.text) : ''))
+      .map((r) => {
+        if (typeof r === 'string') return r
+        if (typeof r !== 'object' || r === null || !('text' in r)) return ''
+
+        const text = (r as { text?: unknown }).text
+        return typeof text === 'string' ? text : ''
+      })
       .join('')
   }
   return ''
@@ -112,6 +178,12 @@ export async function triageWorkstreamMessage(params: {
   messageText: string
   recentContext?: string
 }): Promise<RouterTriageResult | null> {
+  const explicitTargets = extractExplicitAgentTargets(params.messageText, params.members)
+  const firstExplicitTarget = explicitTargets[0]
+  if (firstExplicitTarget) {
+    return { agentId: firstExplicitTarget, routingContext: buildExplicitAgentRoutingContext(firstExplicitTarget) }
+  }
+
   const membersDesc = buildMembersDescription(params.members)
   const prompt = [
     `Workstream: "${params.workstreamTitle}"`,
@@ -159,6 +231,16 @@ export async function checkForNextAgent(params: {
   respondedAgents: string[]
   lastResponseSummary: string
 }): Promise<RouterCheckResult> {
+  const explicitTargets = extractExplicitAgentTargets(params.messageText, params.members)
+  const nextExplicitTarget = explicitTargets.find((agentId) => !params.respondedAgents.includes(agentId))
+  if (nextExplicitTarget) {
+    return {
+      done: false,
+      agentId: nextExplicitTarget,
+      routingContext: buildExplicitAgentRoutingContext(nextExplicitTarget),
+    }
+  }
+
   const remainingMembers = params.members.filter((id) => !params.respondedAgents.includes(id))
   if (remainingMembers.length === 0) return { done: true }