@lota-sdk/core 0.1.36 → 0.1.37

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lota-sdk/core",
-  "version": "0.1.36",
+  "version": "0.1.37",
   "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.35",
+    "@lota-sdk/shared": "0.1.37",
     "@mendable/firecrawl-js": "^4.18.0",
     "@surrealdb/node": "^3.0.3",
     "ai": "^6.0.141",

package/src/config/agent-defaults.ts

@@ -12,6 +12,7 @@ function defaultGetAgentRuntimeConfig(): Record<string, never> {
 export let agentDisplayNames: Record<string, string> = {}
 export let agentShortDisplayNames: Record<string, string> = {}
 export let agentDescriptions: Record<string, string> = {}
+export let managerModelId: string | undefined = undefined
 export let agentRoster: readonly string[] = []
 export let leadAgentId = ''
 export let teamConsultParticipants: readonly string[] = []
@@ -38,6 +39,7 @@ export function configureAgents(config: {
   displayNames: Record<string, string>
   shortDisplayNames?: Record<string, string>
   descriptions?: Record<string, string>
+  managerModelId?: string
   teamConsultParticipants: readonly string[]
   getCoreWorkstreamProfile?: (coreType: string) => CoreWorkstreamProfile
 }): void {
@@ -50,6 +52,7 @@ export function configureAgents(config: {
   agentDisplayNames = config.displayNames
   agentShortDisplayNames = config.shortDisplayNames ?? {}
   agentDescriptions = config.descriptions ?? {}
+  managerModelId = config.managerModelId
   teamConsultParticipants = config.teamConsultParticipants
   if (config.getCoreWorkstreamProfile) {
     getCoreWorkstreamProfile = config.getCoreWorkstreamProfile

package/src/config/model-constants.ts

@@ -12,7 +12,6 @@ export {
   OPENROUTER_TEAM_AGENT_MODEL_ID,
   OPENROUTER_WEB_RESEARCH_MODEL_ID,
   OPENROUTER_XHIGH_REASONING_PROVIDER_OPTIONS,
-  OPENROUTER_MANAGER_MODEL_ID,
 } from '@lota-sdk/shared'
 
 // Both aliases point to the same underlying model. Keep the names separate so

package/src/create-runtime.ts

@@ -251,6 +251,7 @@ export async function createLotaRuntime(config: LotaRuntimeConfig): Promise<Lota
       displayNames: agentDisplayNames,
       shortDisplayNames: runtimeConfig.agents.shortDisplayNames,
       descriptions: runtimeConfig.agents.descriptions,
+      managerModelId: runtimeConfig.agents.managerModelId,
       teamConsultParticipants: runtimeConfig.agents.teamConsultParticipants,
       getCoreWorkstreamProfile: runtimeConfig.agents.getCoreWorkstreamProfile,
     })

package/src/runtime/runtime-config.ts

@@ -176,6 +176,7 @@ const agentsConfigSchema = z
     descriptions: z
       .custom<Record<string, string>>(isStringRecord, { error: 'agents.descriptions must be a string record' })
       .optional(),
+    managerModelId: z.string().trim().min(1).optional(),
     teamConsultParticipants: z.array(z.string().trim().min(1)),
     getCoreWorkstreamProfile: z
       .custom<(coreType: string) => CoreWorkstreamProfile>(isFunction, {

package/src/services/global-orchestrator.service.ts

@@ -3,6 +3,7 @@ import type { ConvergenceState, PlanFailureClass } from '@lota-sdk/shared'
 import { serverLogger } from '../config/logger'
 import { recordIdToString } from '../db/record-id'
 import { TABLES } from '../db/tables'
+import { shouldPlanNodeUseVisibleTurn } from '../runtime/execution-plan-visibility'
 
 function classifyDispatchFailure(ownerType: string, error: unknown): PlanFailureClass {
   const errorMessage = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase()
@@ -80,17 +81,48 @@ class GlobalOrchestratorService {
       })
       if (readyNodes.length === 0) break
 
+      // Split into silent (dispatch now) and visible (enqueue heartbeat wake)
+      const silentNodes = readyNodes.filter((nr) => {
+        const ns = nodeSpecs.find((s) => s.nodeId === nr.nodeId)
+        return ns && !shouldPlanNodeUseVisibleTurn(spec, ns)
+      })
+      const visibleNodes = readyNodes.filter((nr) => {
+        const ns = nodeSpecs.find((s) => s.nodeId === nr.nodeId)
+        return ns && shouldPlanNodeUseVisibleTurn(spec, ns)
+      })
+
       // Transition all ready nodes to 'running' BEFORE dispatching
       for (const nodeRun of readyNodes) {
         await planExecutorService.transitionNodeToRunning({ runId: params.runId, nodeId: nodeRun.nodeId })
       }
 
+      // Enqueue heartbeat wakes for visible agent nodes — they need a streaming turn
+      if (visibleNodes.length > 0) {
+        const { enqueuePlanAgentHeartbeatWake } = await import('../queues/plan-agent-heartbeat.queue')
+        const updatedRunForWake = await planRunService.getRunById(params.runId)
+        for (const nodeRun of visibleNodes) {
+          const ns = nodeSpecs.find((s) => s.nodeId === nodeRun.nodeId)
+          if (!ns || ns.owner.executorType !== 'agent') continue
+          await enqueuePlanAgentHeartbeatWake({
+            organizationId: recordIdToString(updatedRunForWake.organizationId, TABLES.ORGANIZATION),
+            workstreamId: recordIdToString(updatedRunForWake.workstreamId, TABLES.WORKSTREAM),
+            runId: recordIdToString(updatedRunForWake.id, TABLES.PLAN_RUN),
+            nodeId: nodeRun.nodeId,
+            agentId: ns.owner.ref,
+            reason: 'graph-full-visible',
+          })
+        }
+      }
+
+      // If no silent nodes to dispatch, break and let heartbeat handle visible ones
+      if (silentNodes.length === 0) break
+
       // Re-fetch run after transitions for accurate state in dispatch context
       const updatedRun = await planRunService.getRunById(params.runId)
 
-      // Dispatch all in parallel with LINEAR mode override (prevents recursion)
+      // Dispatch silent nodes in parallel with LINEAR mode override (prevents recursion)
       const results = await Promise.allSettled(
-        readyNodes.map(async (nodeRun) => {
+        silentNodes.map(async (nodeRun) => {
           const nodeSpecRecord = nodeSpecs.find((ns) => ns.nodeId === nodeRun.nodeId)
           if (!nodeSpecRecord) {
             throw new Error(`Node spec not found for node "${nodeRun.nodeId}".`)
@@ -114,7 +146,7 @@ class GlobalOrchestratorService {
       // Submit results sequentially (each triggers syncRunGraph internally)
       for (let i = 0; i < results.length; i++) {
         const settled = results[i]
-        const nodeRun = readyNodes[i]
+        const nodeRun = silentNodes[i]
         const nodeSpecRecord = nodeSpecs.find((ns) => ns.nodeId === nodeRun.nodeId)
 
         if (settled.status === 'fulfilled') {

package/src/services/plan-agent-query.service.ts

@@ -73,6 +73,34 @@ class PlanAgentQueryService {
 
     for (const run of runs) {
       const spec = await planRunService.getPlanSpecById(run.planSpecId)
+
+      // Graph-full plans can have multiple visible agent nodes running in parallel
+      if (spec.executionMode === 'graph-full') {
+        const [nodeSpecs, nodeRuns] = await Promise.all([
+          planRunService.listNodeSpecs(spec.id),
+          planRunService.listNodeRuns(run.id),
+        ])
+        for (const nodeRun of nodeRuns) {
+          if (!ACTIONABLE_NODE_STATUSES.has(nodeRun.status)) continue
+          const nodeSpec = nodeSpecs.find((ns) => ns.nodeId === nodeRun.nodeId)
+          if (!nodeSpec) continue
+          const visibleTarget = isVisibleAgentNode({ nodeSpec, spec })
+          if (!visibleTarget) continue
+          if (params.agentId && params.agentId !== visibleTarget.agentId) continue
+          actionable.push({
+            organizationId: recordIdToString(run.organizationId, TABLES.ORGANIZATION),
+            workstreamId: recordIdToString(run.workstreamId, TABLES.WORKSTREAM),
+            runId: recordIdToString(run.id, TABLES.PLAN_RUN),
+            nodeId: nodeSpec.nodeId,
+            agentId: visibleTarget.agentId,
+            status: nodeRun.status as 'ready' | 'running',
+            visibility: visibleTarget.visibility,
+          })
+        }
+        continue
+      }
+
+      // Linear plans: only the current node is actionable
       const currentNodeId = run.currentNodeId
       if (!currentNodeId) {
         continue

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

@@ -244,6 +244,7 @@ interface StreamAgentResponseParams {
   stopWhen?: StopCondition<ToolSet> | Array<StopCondition<ToolSet>>
   prepareStep?: PrepareStepFunction<ToolSet>
   abortSignal?: AbortSignal
+  suppressFinish?: boolean
 }
 
 async function streamAgentResponse(
@@ -393,6 +394,15 @@ 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)
       }
     }
@@ -817,6 +827,7 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
             filterTools?: (tools: ToolSet) => ToolSet
             includeExecutionPlanTools?: boolean
             metadataPatch?: NonNullable<MessageMetadata>
+            suppressFinish?: boolean
           }): Promise<ChatMessage> => {
             const visibleTimer = lotaDebugLogger.timer(`visible:${runParams.agentId}`)
             let runMemoryBlock = memoryBlock
@@ -852,6 +863,7 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
               additionalInstructionSections: runParams.additionalInstructionSections,
               includeExecutionPlanTools,
               writer,
+              suppressFinish: runParams.suppressFinish,
             })
 
             visibleTimer.step('stream-agent-response')
@@ -898,8 +910,8 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
               await runVisibleAgent({ agentId: workstream.agentId, mode: 'direct' })
             } else {
               // Multi-agent orchestration for group workstreams
-              const members =
-                workstream.members.length > 0 ? workstream.members : [visibleWorkstreamAgentId ?? defaultLeadAgentId]
+              const wsMembers = (workstream as { members?: string[] }).members ?? []
+              const members = wsMembers.length > 0 ? wsMembers : [visibleWorkstreamAgentId ?? defaultLeadAgentId]
               const fallbackAgentId = coreWorkstreamProfile?.config.agentId ?? defaultLeadAgentId
 
               const recentContext = currentMessages
@@ -914,10 +926,13 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
                 recentContext,
               })
 
-              const runGroupAgent = async (agentId: string, routingContext?: string) => {
+              const runGroupAgent = async (
+                agentId: string,
+                options?: { routingContext?: string; suppressFinish?: boolean },
+              ) => {
                 const additionalSections = [...(coreInstructionSections ?? []), ...hookInstructionSections]
-                if (routingContext) {
-                  additionalSections.push(`<routing-context>\n${routingContext}\n</routing-context>`)
+                if (options?.routingContext) {
+                  additionalSections.push(`<routing-context>\n${options.routingContext}\n</routing-context>`)
                 }
                 // Multi-agent member protocol: be direct, focus on domain
                 additionalSections.push(
@@ -929,16 +944,20 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
                   mode: 'workstreamMode',
                   skills: coreWorkstreamProfile?.skills ? [...coreWorkstreamProfile.skills] : undefined,
                   additionalInstructionSections: additionalSections,
+                  suppressFinish: options?.suppressFinish,
                 })
               }
 
               if (!triageResult) {
-                // No specialist match — fallback to owner (core) or chief (non-core)
+                // No specialist match — fallback to owner (core) or chief (non-core), single agent turn
                 await runGroupAgent(fallbackAgentId)
               } else {
-                // Run first routed agent
+                // Run first routed agent — suppress finish in case more agents follow
                 const respondedAgents: string[] = []
-                let lastResponse = await runGroupAgent(triageResult.agentId, triageResult.routingContext)
+                let lastResponse = await runGroupAgent(triageResult.agentId, {
+                  routingContext: triageResult.routingContext,
+                  suppressFinish: true,
+                })
                 respondedAgents.push(triageResult.agentId)
 
                 // Check if more agents should respond (max 3 total)
@@ -964,7 +983,7 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
                         text: checkResult.routingContext ?? 'Please also provide your perspective on this topic.',
                       },
                     ],
-                    metadata: { hidden: true, createdAt: Date.now() },
+                    metadata: { hidden: true, createdAt: Date.now() } as MessageMetadata,
                   }
                   await workstreamMessageService.upsertMessages({
                     workstreamId: workstreamRef,
@@ -972,9 +991,17 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
                   })
                   currentMessages = upsertChatHistoryMessage(currentMessages, bridgeMessage)
 
-                  lastResponse = await runGroupAgent(checkResult.agentId, checkResult.routingContext)
+                  lastResponse = await runGroupAgent(checkResult.agentId, {
+                    routingContext: checkResult.routingContext,
+                    suppressFinish: true,
+                  })
                   respondedAgents.push(checkResult.agentId)
                 }
+
+                // Write final finish chunk so the client knows the turn is complete
+                if (writer) {
+                  writer.write({ type: 'finish', finishReason: 'stop' } as ChatStreamChunk)
+                }
               }
             }
           }

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

@@ -1,31 +1,32 @@
-import { Output, ToolLoopAgent } from 'ai'
+import { ToolLoopAgent } from 'ai'
 import { z } from 'zod'
 
 import { aiGatewayChatModel } from '../ai-gateway/ai-gateway'
 import { buildAiGatewayDirectCacheHeaders } from '../ai-gateway/cache-headers'
-import { agentDescriptions, agentDisplayNames } from '../config/agent-defaults'
-import { OPENROUTER_MANAGER_MODEL_ID, OPENROUTER_XHIGH_REASONING_PROVIDER_OPTIONS } from '../config/model-constants'
+import { agentDescriptions, agentDisplayNames, managerModelId } from '../config/agent-defaults'
+import {
+  OPENROUTER_FAST_REASONING_MODEL_ID,
+  OPENROUTER_XHIGH_REASONING_PROVIDER_OPTIONS,
+  OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
+} from '../config/model-constants'
 
 // ---------------------------------------------------------------------------
 // Schemas
 // ---------------------------------------------------------------------------
 
-const TriageResultSchema = z.object({
-  agentId: z.string().describe('The agent ID that should respond next'),
-  routingContext: z.string().describe('Brief instruction for the selected agent about what to focus on'),
-})
+const TriageResultSchema = z.object({ agentId: z.string(), routingContext: z.string() })
 
 const CheckResultSchema = z.object({
-  done: z.boolean().describe('true if no more agents need to respond'),
-  agentId: z.string().optional().describe('Next agent ID if done is false'),
-  routingContext: z.string().optional().describe('Brief instruction for the next agent if done is false'),
+  done: z.boolean(),
+  agentId: z.string().optional(),
+  routingContext: z.string().optional(),
 })
 
 export type ManagerTriageResult = z.infer<typeof TriageResultSchema>
 export type ManagerCheckResult = z.infer<typeof CheckResultSchema>
 
 // ---------------------------------------------------------------------------
-// Prompt builders
+// Helpers
 // ---------------------------------------------------------------------------
 
 function buildMembersDescription(members: readonly string[]): string {
@@ -33,53 +34,58 @@ function buildMembersDescription(members: readonly string[]): string {
     .map((id) => {
       const display = agentDisplayNames[id] ?? id
       const desc = agentDescriptions[id] ?? ''
-      return `- **${display}** (id: \`${id}\`): ${desc}`
+      return `- ${display} (id: ${id}): ${desc}`
     })
     .join('\n')
 }
 
-const TRIAGE_SYSTEM_PROMPT = `You are a workstream message router. Your job is to decide which team member should respond to a user message.
+function extractJson(text: string): unknown {
+  const match = text.match(/\{[\s\S]*\}/)
+  if (!match) return null
+  try {
+    return JSON.parse(match[0])
+  } catch {
+    return null
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Prompts
+// ---------------------------------------------------------------------------
+
+const TRIAGE_SYSTEM_PROMPT = `You are a workstream message router. Decide which team member should respond to the user message.
 
-<rules>
-- Pick the single best-fit agent from the members list.
-- Consider the agent's domain expertise against the user's question.
-- If the message is clearly about a specific domain (marketing, tech, product, finance, etc.), route to the domain specialist.
-- If multiple domains are equally relevant, pick the most relevant one — a follow-up check will decide if another agent should also respond.
-- If no specialist clearly matches (general chat, greetings, coordination), respond with an empty agentId to signal fallback.
-- Be decisive. Do not overthink.
-</rules>
+Rules:
+- Pick the single best-fit agent from the members list based on domain expertise.
+- If no specialist clearly matches (general chat, greetings, coordination), respond with agentId "".
+- Be decisive. Reply with ONLY a JSON object, no other text.
 
-<output-format>
-Respond with JSON only: { "agentId": "<agent-id>", "routingContext": "<1-sentence instruction>" }
-If no specialist matches, respond: { "agentId": "", "routingContext": "" }
-</output-format>`
+Format: {"agentId":"<id>","routingContext":"<1-sentence instruction>"}`
 
-const CHECK_SYSTEM_PROMPT = `You are a workstream conversation reviewer. After an agent has responded to a user message, you decide if another team member should also respond.
+const CHECK_SYSTEM_PROMPT = `You decide if another team member should also respond after the previous agent.
 
-<rules>
-- Only add another agent if the user's question has a clearly separate dimension that the previous agent(s) did not cover.
-- Do NOT add agents just for acknowledgement or agreement.
-- Do NOT repeat the same domain. If the CTO already covered tech, don't add another tech perspective.
-- Most messages need only one agent. Multi-agent responses should be the exception, not the rule.
-- Maximum 3 total agent responses per user message.
-</rules>
+Rules:
+- Only add another agent if the user's question has a clearly separate dimension not yet covered.
+- Do NOT add agents for agreement or acknowledgement.
+- Most messages need only one agent. Reply with ONLY a JSON object, no other text.
 
-<output-format>
-Respond with JSON only: { "done": true } or { "done": false, "agentId": "<agent-id>", "routingContext": "<1-sentence instruction>" }
-</output-format>`
+Format: {"done":true} or {"done":false,"agentId":"<id>","routingContext":"<1-sentence>"}`
 
 // ---------------------------------------------------------------------------
 // Agent functions
 // ---------------------------------------------------------------------------
 
-function createManagerAgent(systemPrompt: string, schema: z.ZodSchema) {
+function createManagerAgent(systemPrompt: string) {
+  const modelId = managerModelId ?? OPENROUTER_FAST_REASONING_MODEL_ID
+  const providerOptions = managerModelId
+    ? OPENROUTER_XHIGH_REASONING_PROVIDER_OPTIONS
+    : OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS
   return new ToolLoopAgent({
     id: 'workstream-manager',
-    model: aiGatewayChatModel(OPENROUTER_MANAGER_MODEL_ID),
+    model: aiGatewayChatModel(modelId),
     headers: buildAiGatewayDirectCacheHeaders('workstream-manager'),
-    providerOptions: OPENROUTER_XHIGH_REASONING_PROVIDER_OPTIONS,
+    providerOptions,
     instructions: systemPrompt,
-    output: Output.object({ schema }),
     maxOutputTokens: 256,
   })
 }
@@ -93,23 +99,20 @@ export async function triageWorkstreamMessage(params: {
   const membersDesc = buildMembersDescription(params.members)
   const prompt = [
     `Workstream: "${params.workstreamTitle}"`,
-    `\nMembers:\n${membersDesc}`,
-    params.recentContext ? `\nRecent context:\n${params.recentContext}` : '',
-    `\nUser message: "${params.messageText}"`,
+    `Members:\n${membersDesc}`,
+    params.recentContext ? `Recent context:\n${params.recentContext}` : '',
+    `User message: "${params.messageText}"`,
   ]
     .filter(Boolean)
-    .join('\n')
+    .join('\n\n')
 
-  const agent = createManagerAgent(TRIAGE_SYSTEM_PROMPT, TriageResultSchema)
-  const result = await agent.generate({ messages: [{ role: 'user', content: prompt }], timeout: { totalMs: 15_000 } })
+  const agent = createManagerAgent(TRIAGE_SYSTEM_PROMPT)
+  const result = await agent.generate({ messages: [{ role: 'user', content: prompt }], timeout: { totalMs: 30_000 } })
 
-  const parsed = TriageResultSchema.safeParse(result.output)
+  const json = extractJson(typeof result.text === 'string' ? result.text : '')
+  const parsed = TriageResultSchema.safeParse(json)
   if (!parsed.success) return null
-
-  // Empty agentId = no specialist match, fallback to owner/chief
   if (!parsed.data.agentId) return null
-
-  // Validate agent is in members list
   if (!params.members.includes(parsed.data.agentId)) return null
 
   return parsed.data
@@ -130,24 +133,20 @@ export async function checkForNextAgent(params: {
 
   const prompt = [
     `Workstream: "${params.workstreamTitle}"`,
-    `\nRemaining members:\n${membersDesc}`,
-    `\nAlready responded: ${respondedList}`,
-    `\nUser message: "${params.messageText}"`,
-    `\nLast response summary: "${params.lastResponseSummary}"`,
-  ].join('\n')
+    `Remaining members:\n${membersDesc}`,
+    `Already responded: ${respondedList}`,
+    `User message: "${params.messageText}"`,
+    `Last response summary: "${params.lastResponseSummary}"`,
+  ].join('\n\n')
 
-  const agent = createManagerAgent(CHECK_SYSTEM_PROMPT, CheckResultSchema)
-  const result = await agent.generate({ messages: [{ role: 'user', content: prompt }], timeout: { totalMs: 15_000 } })
+  const agent = createManagerAgent(CHECK_SYSTEM_PROMPT)
+  const result = await agent.generate({ messages: [{ role: 'user', content: prompt }], timeout: { totalMs: 30_000 } })
 
-  const parsed = CheckResultSchema.safeParse(result.output)
+  const json = extractJson(typeof result.text === 'string' ? result.text : '')
+  const parsed = CheckResultSchema.safeParse(json)
   if (!parsed.success) return { done: true }
-
   if (parsed.data.done) return { done: true }
-
-  // Validate next agent is in remaining members
-  if (!parsed.data.agentId || !remainingMembers.includes(parsed.data.agentId)) {
-    return { done: true }
-  }
+  if (!parsed.data.agentId || !remainingMembers.includes(parsed.data.agentId)) return { done: true }
 
   return parsed.data
 }