@lota-sdk/core 0.1.47 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lota-sdk/core",
-  "version": "0.1.47",
+  "version": "0.2.0",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -32,7 +32,7 @@
     "@chat-adapter/slack": "^4.23.0",
     "@chat-adapter/state-ioredis": "^4.23.0",
     "@logtape/logtape": "^2.0.5",
-    "@lota-sdk/shared": "0.1.47",
+    "@lota-sdk/shared": "0.2.0",
     "@mendable/firecrawl-js": "^4.18.0",
     "@surrealdb/node": "^3.0.3",
     "ai": "^6.0.141",

package/src/runtime/agent-stream-helpers.ts

@@ -50,22 +50,38 @@ export function createAgentMessageMetadata(params: {
   }
 }
 
-export function createServerRunAbortController(externalAbortSignal?: AbortSignal) {
+function toExternalAbortSignals(externalAbortSignal?: AbortSignal | readonly AbortSignal[]): AbortSignal[] {
+  if (!externalAbortSignal) return []
+
+  const signals = Array.isArray(externalAbortSignal) ? externalAbortSignal : [externalAbortSignal]
+  return [...new Set<AbortSignal>(signals)]
+}
+
+export function createServerRunAbortController(externalAbortSignal?: AbortSignal | readonly AbortSignal[]) {
   const controller = new AbortController()
   const abort = (reason?: unknown) => {
     if (controller.signal.aborted) return
     controller.abort(reason ?? new DOMException('Run stopped by user.', 'AbortError'))
   }
 
-  const abortFromExternal = () => {
-    abort((externalAbortSignal as (AbortSignal & { reason?: unknown }) | undefined)?.reason)
-  }
+  const externalSignals = toExternalAbortSignals(externalAbortSignal)
+  const listeners = externalSignals.map((signal) => {
+    const abortFromExternal = () => {
+      abort((signal as AbortSignal & { reason?: unknown }).reason)
+    }
 
-  if (externalAbortSignal) {
-    if (externalAbortSignal.aborted) {
+    if (signal.aborted) {
       abortFromExternal()
     } else {
-      externalAbortSignal.addEventListener('abort', abortFromExternal, { once: true })
+      signal.addEventListener('abort', abortFromExternal, { once: true })
+    }
+
+    return { signal, abortFromExternal }
+  })
+
+  if (controller.signal.aborted) {
+    for (const { signal, abortFromExternal } of listeners) {
+      signal.removeEventListener('abort', abortFromExternal)
     }
   }
 
@@ -74,8 +90,9 @@ export function createServerRunAbortController(externalAbortSignal?: AbortSignal
     signal: controller.signal,
     abort,
     dispose: () => {
-      if (!externalAbortSignal) return
-      externalAbortSignal.removeEventListener('abort', abortFromExternal)
+      for (const { signal, abortFromExternal } of listeners) {
+        signal.removeEventListener('abort', abortFromExternal)
+      }
     },
   }
 }

package/src/runtime/execution-plan.ts

@@ -4,10 +4,11 @@ type ExecutionPlanPromptSummary = Pick<SerializableExecutionPlan, 'runId' | 'tit
 
 const EXECUTION_PLAN_AGENT_PROTOCOL_PROMPT = `<execution-plan-protocol>
 - Create execution plans for multi-step work. Review existing plans before creating new ones.
+- The active execution runs in <execution-plan-state> are a summary inventory only. They list runId and title, not node-level state.
 - The runtime executor owns lifecycle truth. Do not claim node completion until the executor confirms.
-- Work only on active/ready nodes assigned to you. Stop at human gates.
+- Do not invent or restate run/node lifecycle details that are not present in the prompt or tool results.
 - During plan-triggered turns, use the dedicated result-submission tool. Include handoffContext.
-- Treat the active execution runs in <execution-plan-state> as authoritative. Do not mutate run or node status in prose.
+- Treat the active execution runs in <execution-plan-state> as authoritative for whether a plan already exists.
 - If contracts or criteria materially change, replace the plan.
 </execution-plan-protocol>`
 

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

@@ -734,10 +734,16 @@ 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)),
+        )
+        if (runAbort.signal.aborted) {
+          throw runAbort.signal.reason ?? new DOMException('The operation was aborted.', 'AbortError')
+        }
         // 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)
@@ -746,6 +752,11 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
         runTimer.step('set-active-run+stream')
 
         try {
+          const throwIfRunAborted = () => {
+            if (!runAbort.signal.aborted) return
+            throw runAbort.signal.reason ?? new DOMException('The operation was aborted.', 'AbortError')
+          }
+
           const buildAgentMetadataPatch = (agentId: string, agentName: string): NonNullable<MessageMetadata> => ({
             agentId,
             agentName,
@@ -768,6 +779,8 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
             agentName: string,
             metadataPatch?: NonNullable<MessageMetadata>,
           ) => {
+            throwIfRunAborted()
+
             const committed = withMessageCreatedAt(
               {
                 ...response,
@@ -779,6 +792,7 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
             await workstreamMessageService.upsertMessages({ workstreamId: workstreamRef, messages: [committed] })
             currentMessages = upsertChatHistoryMessage(currentMessages, committed)
             allAssistantMessages = upsertChatHistoryMessage(allAssistantMessages, committed)
+            throwIfRunAborted()
 
             return committed
           }
@@ -840,6 +854,7 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
             const tools = runParams.filterTools ? runParams.filterTools(rawTools) : rawTools
             visibleTimer.step('build-agent-tools')
             streamCtx.memoryBlock = memoryBlock
+            throwIfRunAborted()
             const responseMessage = await streamAgentResponse(streamCtx, {
               agentId: runParams.agentId,
               mode: runParams.mode,
@@ -899,6 +914,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
+              throwIfRunAborted()
               writeMultiAgentEvent(writer, { phase: 'routing', note: 'Routing this turn to the right agent.' })
 
               const recentContext = currentMessages
@@ -912,6 +928,7 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
                 messageText,
                 recentContext,
               })
+              throwIfRunAborted()
 
               const runGroupAgent = async (
                 agentId: string,
@@ -938,6 +955,7 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
               if (!triageResult) {
                 // No specialist match — fallback to owner (core) or chief (non-core), single visible turn.
                 await runGroupAgent(fallbackAgentId)
+                throwIfRunAborted()
                 writeMultiAgentEvent(writer, { phase: 'complete' })
               } else {
                 const respondedAgents: string[] = []
@@ -945,6 +963,7 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
                   routingContext: triageResult.routingContext,
                 })
                 respondedAgents.push(triageResult.agentId)
+                throwIfRunAborted()
 
                 // Follow-up specialists run headless, persist their own messages,
                 // and are surfaced by transient events plus cache refresh.
@@ -957,6 +976,7 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
                     respondedAgents,
                     lastResponseSummary: lastResponseText,
                   })
+                  throwIfRunAborted()
 
                   if (checkResult.done || !checkResult.agentId) break
 
@@ -979,17 +999,20 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
                     ],
                     metadata: { hidden: true, createdAt: Date.now() } as MessageMetadata,
                   }
+                  throwIfRunAborted()
                   await workstreamMessageService.upsertMessages({
                     workstreamId: workstreamRef,
                     messages: [bridgeMessage],
                   })
                   currentMessages = upsertChatHistoryMessage(currentMessages, bridgeMessage)
+                  throwIfRunAborted()
 
                   lastResponse = await runGroupAgent(checkResult.agentId, {
                     routingContext: checkResult.routingContext,
                     headless: true,
                   })
                   respondedAgents.push(checkResult.agentId)
+                  throwIfRunAborted()
                   writeMultiAgentEvent(writer, {
                     phase: 'agent-message-persisted',
                     agentId: checkResult.agentId,
@@ -998,6 +1021,7 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
                   })
                 }
 
+                throwIfRunAborted()
                 writeMultiAgentEvent(writer, { phase: 'complete' })
               }
             }
@@ -1093,8 +1117,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/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 }