@swarmclawai/swarmclaw 1.2.3 → 1.2.5

package/src/lib/server/chat-execution/stream-continuation.ts

@@ -8,7 +8,7 @@
 import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
-import type { MessageToolEvent } from '@/types'
+import type { Message, MessageToolEvent } from '@/types'
 import { extractSuggestions } from '@/lib/server/suggestions'
 import { isSuccessfulMemoryMutationToolEvent } from '@/lib/server/chat-execution/memory-mutation-tools'
 import type { MessageClassification } from '@/lib/server/chat-execution/message-classifier'
@@ -108,7 +108,7 @@ function looksLikeIncompleteDeliverableResponse(text: string): boolean {
 }
 
 function hasRecentDeliverableContext(
-  history: Array<{ role?: string; text?: string }> | undefined,
+  history: Message[] | undefined,
   userMessage: string,
 ): boolean {
   if (!Array.isArray(history) || history.length === 0) return false
@@ -116,7 +116,7 @@ function hasRecentDeliverableContext(
   if (!trimmed || trimmed.length > 160) return false
   return history
     .slice(-8)
-    .some((entry) => entry.role === 'user' && looksLikeOpenEndedDeliverableTask((entry.text || '').trim()))
+    .some((entry) => entry.role === 'user' && entry.semantics?.isDeliverableTask === true)
 }
 
 const ARTIFACT_PATH_EXT_RE = /\.(?:md|txt|html?|json|csv|ya?ml|xml|pdf|png|jpe?g|webp|gif|svg|zip|ts|tsx|js|jsx|mjs|cjs|py|sql|sh)$/i
@@ -245,7 +245,7 @@ export function shouldForceExternalExecutionFollowthrough(params: {
   toolEvents: MessageToolEvent[]
   classification?: MessageClassification | null
 }): boolean {
-  const isTransactional = params.classification ? params.classification.walletIntent === 'transactional' : looksLikeBoundedExternalExecutionTask(params.userMessage)
+  const isTransactional = params.classification?.walletIntent === 'transactional'
   if (!isTransactional) return false
   if (!params.hasToolCalls || params.toolEvents.length < 4) return false
   if (hasStateChangingWalletEvidence(params.toolEvents)) return false
@@ -266,7 +266,7 @@ export function shouldForceExternalExecutionKickoffFollowthrough(params: {
   toolEvents: MessageToolEvent[]
   classification?: MessageClassification | null
 }): boolean {
-  const isTransactional = params.classification ? params.classification.walletIntent === 'transactional' : looksLikeBoundedExternalExecutionTask(params.userMessage)
+  const isTransactional = params.classification?.walletIntent === 'transactional'
   if (!isTransactional) return false
   if (params.hasToolCalls || params.toolEvents.length > 0) return false
 
@@ -289,11 +289,11 @@ export function shouldForceDeliverableFollowthrough(params: {
   hasToolCalls: boolean
   toolEvents: MessageToolEvent[]
   cwd?: string
-  history?: Array<{ role?: string; text?: string }>
+  history?: Message[]
   classification?: MessageClassification | null
 }): boolean {
   const recentDeliverableContext = hasRecentDeliverableContext(params.history, params.userMessage)
-  const isDeliverable = params.classification ? params.classification.isDeliverableTask : looksLikeOpenEndedDeliverableTask(params.userMessage)
+  const isDeliverable = params.classification?.isDeliverableTask === true
   const deliverableIntent = isDeliverable || recentDeliverableContext
   const requestedArtifacts = getRequestedArtifactStatus({
     userMessage: params.userMessage,
@@ -744,6 +744,9 @@ export function buildContinuationPrompt(params: {
   cwd?: string
   frequencyLimitedToolName?: string
   sessionExtensions?: string[]
+  isCoordinatorAgent?: boolean
+  recommendedDelegateName?: string | null
+  delegationRationale?: string | null
 }): string | null {
   switch (params.type) {
     case 'memory_write_followthrough':
@@ -819,12 +822,24 @@ export function buildContinuationPrompt(params: {
       ].filter(Boolean).join('\n')
 
     case 'coordinator_delegation_nudge':
-      return [
-        'IMPORTANT: You have specialist workers available but you have been doing substantial work directly with tools.',
-        'You MUST delegate the remaining work via `spawn_subagent` to the appropriate specialist worker NOW.',
-        'As a coordinator, your job is to orchestrate — not to do the work yourself. Direct tool use is only for quick lookups and validation.',
-        'Review the workers listed in your system prompt and delegate immediately.',
-      ].join('\n')
+      return params.isCoordinatorAgent
+        ? [
+            'IMPORTANT: You have specialist workers available but you have been doing substantial work directly with tools.',
+            params.recommendedDelegateName
+              ? `Delegate the remaining execution via \`spawn_subagent\` to ${params.recommendedDelegateName} now.`
+              : 'You MUST delegate the remaining work via `spawn_subagent` to the appropriate specialist worker NOW.',
+            'As a coordinator, your job is to orchestrate — not to do the work yourself. Direct tool use is only for quick lookups and validation.',
+            params.delegationRationale ? `Reason: ${params.delegationRationale}.` : '',
+            'Review the workers listed in your system prompt and delegate immediately.',
+          ].filter(Boolean).join('\n')
+        : [
+            'You have delegation available and a teammate is a materially better fit for the remaining work.',
+            params.recommendedDelegateName
+              ? `Use \`spawn_subagent\` to hand the execution to ${params.recommendedDelegateName} now.`
+              : 'Use `spawn_subagent` to hand the execution to the best-fit teammate now.',
+            params.delegationRationale ? `Reason: ${params.delegationRationale}.` : '',
+            'Keep your direct tool use to reconnaissance, validation, or synthesis unless delegation is blocked.',
+          ].filter(Boolean).join('\n')
 
     case 'loop_recovery': {
       const freqTool = params.frequencyLimitedToolName

package/src/lib/server/chatrooms/chatroom-agent-signals.ts

@@ -1,5 +1,5 @@
 import type { Chatroom, Agent } from '@/types'
-import { loadChatrooms, saveChatrooms } from '@/lib/server/storage'
+import { patchChatroom } from '@/lib/server/chatrooms/chatroom-repository'
 import { notify } from '@/lib/server/ws-hub'
 
 /**
@@ -35,25 +35,33 @@ export function isImplicitlyMentioned(text: string, agent: Agent): boolean {
  * Useful for acknowledging tasks or agreeing with teammates.
  */
 export function addAgentReaction(chatroomId: string, messageId: string, agentId: string, emoji: string) {
-  const chatrooms = loadChatrooms()
-  const chatroom = chatrooms[chatroomId] as Chatroom | undefined
-  if (!chatroom) return
+  const updated = patchChatroom(chatroomId, (current) => {
+    const chatroom = current as Chatroom | null
+    if (!chatroom) return null
+    const message = chatroom.messages.find(m => m.id === messageId)
+    if (!message) return chatroom
+    if (message.reactions.some(r => r.reactorId === agentId && r.emoji === emoji)) return chatroom
 
-  const message = chatroom.messages.find(m => m.id === messageId)
-  if (!message) return
-
-  // Prevent duplicate reactions from the same agent
-  if (message.reactions.some(r => r.reactorId === agentId && r.emoji === emoji)) return
-
-  message.reactions.push({
-    emoji,
-    reactorId: agentId,
-    time: Date.now()
+    return {
+      ...chatroom,
+      messages: chatroom.messages.map((entry) => (
+        entry.id !== messageId
+          ? entry
+          : {
+              ...entry,
+              reactions: [
+                ...entry.reactions,
+                {
+                  emoji,
+                  reactorId: agentId,
+                  time: Date.now(),
+                },
+              ],
+            }
+      )),
+    }
   })
-
-  chatrooms[chatroomId] = chatroom
-  saveChatrooms(chatrooms)
-  notify(`chatroom:${chatroomId}`)
+  if (updated) notify(`chatroom:${chatroomId}`)
 }
 
 /**

package/src/lib/server/chatrooms/chatroom-helpers.ts

@@ -1,14 +1,18 @@
 import fs from 'fs'
 import os from 'os'
 import path from 'path'
-import { loadSettings, loadSkills, loadCredentials, decryptKey, loadSessions, saveSessions } from '@/lib/server/storage'
 import { buildCurrentDateTimePromptContext } from '@/lib/server/prompt-runtime-context'
 import { buildIdentityContinuityContext } from '@/lib/server/identity-continuity'
 import { genId } from '@/lib/id'
 import { WORKSPACE_DIR } from '@/lib/server/data-dir'
 import { applyResolvedRoute, resolvePrimaryAgentRoute } from '@/lib/server/agents/agent-runtime-config'
+import { loadCredential, decryptKey } from '@/lib/server/credentials/credential-repository'
 import { resolveProviderApiEndpoint, resolveProviderCredentialId } from '@/lib/server/provider-endpoint'
+import { loadSettings } from '@/lib/server/settings/settings-repository'
 import { buildRuntimeSkillPromptBlocks, resolveRuntimeSkills } from '@/lib/server/skills/runtime-skill-resolver'
+import { loadSkills } from '@/lib/server/skills/skill-repository'
+import { loadSession, patchSession, saveSession } from '@/lib/server/sessions/session-repository'
+import { appendMessage } from '@/lib/server/messages/message-repository'
 import type { Chatroom, ChatroomMember, Agent, Session, Message, ChatroomMessage } from '@/types'
 import { getEnabledCapabilityIds, getEnabledToolIds } from '@/lib/capability-selection'
 
@@ -16,8 +20,7 @@ import { getEnabledCapabilityIds, getEnabledToolIds } from '@/lib/capability-sel
 export function resolveApiKey(credentialId: string | null | undefined): string | null {
   const resolvedCredentialId = resolveProviderCredentialId({ credentialId })
   if (!resolvedCredentialId) return null
-  const creds = loadCredentials()
-  const cred = creds[resolvedCredentialId]
+  const cred = loadCredential(resolvedCredentialId)
   if (!cred?.encryptedKey) return null
   try { return decryptKey(cred.encryptedKey) } catch { return null }
 }
@@ -136,6 +139,7 @@ export function parseMentions(
 
   // Check if the only explicit matches are the sender — if so, treat as "no explicit mentions"
   const senderId = opts?.senderId
+  const explicitSelfMentioned = senderId ? mentioned.includes(senderId) : false
   const explicitNonSelf = senderId ? mentioned.filter((id) => id !== senderId) : mentioned
 
   // 2. Reply-based implicit mention
@@ -158,8 +162,9 @@ export function parseMentions(
     }
   }
 
-  // Remove self from final list when senderId is provided
-  return senderId ? mentioned.filter((mid) => mid !== senderId) : mentioned
+  // Preserve explicit self-mentions so agents can intentionally address themselves.
+  if (!senderId || explicitSelfMentioned) return mentioned
+  return mentioned.filter((mid) => mid !== senderId)
 }
 
 export function resolveReplyTargetAgentId(
@@ -312,9 +317,8 @@ export function ensureSyntheticSession(agent: Agent, chatroomId: string): Sessio
   const roomWorkspace = resolveChatroomWorkspaceDir(chatroomId)
   fs.mkdirSync(roomWorkspace, { recursive: true })
   const sessionId = resolveSyntheticSessionId(chatroomId, agent.id)
-  const sessions = loadSessions()
   const now = Date.now()
-  const existing = sessions[sessionId]
+  const existing = loadSession(sessionId)
   const session: Session = existing
     ? applyResolvedRoute({
         ...existing,
@@ -348,8 +352,7 @@ export function ensureSyntheticSession(agent: Agent, chatroomId: string): Sessio
   }
   if (session.codexThreadId === undefined) session.codexThreadId = null
   if (session.opencodeSessionId === undefined) session.opencodeSessionId = null
-  sessions[sessionId] = session
-  saveSessions(sessions)
+  saveSession(sessionId, session)
   return session
 }
 
@@ -360,18 +363,16 @@ export function appendSyntheticSessionMessage(
 ): void {
   const trimmed = String(text || '').trim()
   if (!trimmed) return
-  const sessions = loadSessions()
-  const session = sessions[sessionId]
-  if (!session) return
-  if (!Array.isArray(session.messages)) session.messages = []
-  session.messages.push({
+  const timestamp = Date.now()
+  appendMessage(sessionId, {
     role,
     text: trimmed,
-    time: Date.now(),
+    time: timestamp,
+  })
+  patchSession(sessionId, (current) => {
+    if (!current) return null
+    return { ...current, lastActiveAt: timestamp }
   })
-  session.lastActiveAt = Date.now()
-  sessions[sessionId] = session
-  saveSessions(sessions)
 }
 
 /** Build agent's system prompt including skills and identity context */

package/src/lib/server/chatrooms/chatroom-repository.ts

@@ -1,10 +1,13 @@
 import type { Chatroom } from '@/types'
 
 import {
+  deleteStoredItem,
   loadChatroom as loadStoredChatroom,
   loadChatrooms as loadStoredChatrooms,
+  patchStoredItem,
   saveChatrooms as saveStoredChatrooms,
   upsertChatroom as upsertStoredChatroom,
+  upsertStoredItems,
 } from '@/lib/server/storage'
 import { createRecordRepository } from '@/lib/server/persistence/repository-utils'
 
@@ -20,13 +23,26 @@ export const chatroomRepository = createRecordRepository<Chatroom>(
     upsert(id, value) {
       upsertStoredChatroom(id, value as Chatroom)
     },
+    upsertMany(entries) {
+      upsertStoredItems('chatrooms', entries as Array<[string, Chatroom]>)
+    },
+    patch(id, updater) {
+      return patchStoredItem('chatrooms', id, updater as (current: Chatroom | null) => Chatroom | null) as Chatroom | null
+    },
     replace(data) {
       saveStoredChatrooms(data)
     },
+    delete(id) {
+      deleteStoredItem('chatrooms', id)
+    },
   },
 )
 
 export const loadChatrooms = () => chatroomRepository.list()
 export const loadChatroom = (id: string) => chatroomRepository.get(id)
+export const loadChatroomMany = (ids: string[]) => chatroomRepository.getMany(ids)
 export const saveChatrooms = (items: Record<string, Chatroom | Record<string, unknown>>) => chatroomRepository.replace(items as Record<string, Chatroom>)
 export const upsertChatroom = (id: string, value: Chatroom | Record<string, unknown>) => chatroomRepository.upsert(id, value as Chatroom)
+export const upsertChatrooms = (entries: Array<[string, Chatroom | Record<string, unknown>]>) => chatroomRepository.upsertMany(entries as Array<[string, Chatroom]>)
+export const patchChatroom = (id: string, updater: (current: Chatroom | null) => Chatroom | null) => chatroomRepository.patch(id, updater)
+export const deleteChatroom = (id: string) => chatroomRepository.delete(id)

package/src/lib/server/chatrooms/chatroom-routing.test.ts

@@ -0,0 +1,96 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import type { Agent, Chatroom } from '@/types'
+import {
+  ensureChatroomRoutingGuidance,
+  selectChatroomRecipients,
+  synthesizeRoutingGuidanceFromRules,
+} from './chatroom-routing'
+
+const agents: Record<string, Agent> = {
+  ops: {
+    id: 'ops',
+    name: 'Ops',
+    description: 'Handles deploys and infrastructure',
+    provider: 'openai',
+    model: 'gpt-test',
+    systemPrompt: '',
+    capabilities: ['deploy', 'infrastructure'],
+  },
+  design: {
+    id: 'design',
+    name: 'Design',
+    description: 'Handles design critique and UI polish',
+    provider: 'openai',
+    model: 'gpt-test',
+    systemPrompt: '',
+    capabilities: ['design', 'ui'],
+  },
+}
+
+function makeChatroom(overrides: Partial<Chatroom> = {}): Chatroom {
+  return {
+    id: 'room-1',
+    name: 'Test Room',
+    description: 'General routing test room',
+    agentIds: ['ops', 'design'],
+    messages: [],
+    createdAt: 1,
+    updatedAt: 1,
+    ...overrides,
+  }
+}
+
+test('synthesizes guidance from legacy routing rules and migrates the chatroom', () => {
+  const chatroom = makeChatroom({
+    routingRules: [
+      { id: 'rule-1', type: 'keyword', keywords: ['deploy', 'release'], agentId: 'ops', priority: 1 },
+      { id: 'rule-2', type: 'capability', pattern: 'design review', agentId: 'design', priority: 2 },
+    ],
+  })
+
+  const guidance = synthesizeRoutingGuidanceFromRules(chatroom.routingRules, agents)
+  assert.match(String(guidance || ''), /deploy/i)
+  assert.match(String(guidance || ''), /Design/i)
+
+  const changed = ensureChatroomRoutingGuidance(chatroom, agents)
+  assert.equal(changed, true)
+  assert.equal(typeof chatroom.routingGuidance, 'string')
+  assert.equal(chatroom.routingRules, undefined)
+})
+
+test('selects only member ids returned by the selector model', async () => {
+  const chatroom = makeChatroom({
+    routingGuidance: 'Route deployment incidents to Ops. Prefer Design for UI critique.',
+  })
+
+  const selected = await selectChatroomRecipients({
+    text: 'Please diagnose the failed deployment.',
+    chatroom,
+    agentsById: agents,
+  }, {
+    generateText: async () => '{"agentIds":["ops","non-member","ops"]}',
+  })
+
+  assert.deepEqual(selected, ['ops'])
+})
+
+test('fails open to no inferred mentions when there is no guidance or the selector output is invalid', async () => {
+  const unguided = await selectChatroomRecipients({
+    text: 'Anyone here?',
+    chatroom: makeChatroom(),
+    agentsById: agents,
+  }, {
+    generateText: async () => '{"agentIds":["ops"]}',
+  })
+  assert.deepEqual(unguided, [])
+
+  const invalid = await selectChatroomRecipients({
+    text: 'Please review the new layout.',
+    chatroom: makeChatroom({ routingGuidance: 'Prefer Design for UI review.' }),
+    agentsById: agents,
+  }, {
+    generateText: async () => 'not-json',
+  })
+  assert.deepEqual(invalid, [])
+})

package/src/lib/server/chatrooms/chatroom-routing.ts

@@ -1,66 +1,220 @@
-import type { ChatroomRoutingRule, Agent } from '@/types'
-import { matchesCapabilities } from '@/lib/server/agents/capability-match'
+import { HumanMessage } from '@langchain/core/messages'
+import type { Agent, Chatroom, ChatroomRoutingRule } from '@/types'
+import { buildLLM } from '@/lib/server/build-llm'
+import { log } from '@/lib/server/logger'
 
-/**
- * Evaluate routing rules against inbound message text.
- *
- * Rules are evaluated in priority order (lower number = higher priority).
- * First match wins — returns the matched agentIds.
- *
- * - 'keyword' rules: case-insensitive substring match against `keywords[]`,
- *   or regex match against `pattern`.
- * - 'capability' rules: match `pattern` against each agent's `capabilities[]`.
- */
-export function evaluateRoutingRules(
-  text: string,
-  rules: ChatroomRoutingRule[],
-  agents: Agent[],
-): string[] {
-  if (!rules.length) return []
+const TAG = 'chatroom-routing'
+const SELECTOR_TIMEOUT_MS = 4_000
 
-  const sorted = [...rules].sort((a, b) => a.priority - b.priority)
-  const lowerText = text.toLowerCase()
+interface ChatroomRecipientSelection {
+  agentIds: string[]
+}
 
-  for (const rule of sorted) {
-    if (rule.type === 'keyword') {
-      let matched = false
+function normalizeGuidance(value: string | null | undefined): string | null {
+  const trimmed = typeof value === 'string' ? value.trim() : ''
+  return trimmed || null
+}
 
-      // Check keywords (case-insensitive substring)
-      if (rule.keywords?.length) {
-        matched = rule.keywords.some((kw) => lowerText.includes(kw.toLowerCase()))
+function extractFirstJsonObject(text: string): string | null {
+  const source = String(text || '').trim()
+  if (!source) return null
+  let start = -1
+  let depth = 0
+  let inString = false
+  let escaped = false
+  for (let index = 0; index < source.length; index += 1) {
+    const char = source[index]
+    if (start === -1) {
+      if (char === '{') {
+        start = index
+        depth = 1
       }
+      continue
+    }
+    if (inString) {
+      if (escaped) escaped = false
+      else if (char === '\\') escaped = true
+      else if (char === '"') inString = false
+      continue
+    }
+    if (char === '"') {
+      inString = true
+      continue
+    }
+    if (char === '{') depth += 1
+    else if (char === '}') depth -= 1
+    if (depth === 0) return source.slice(start, index + 1)
+  }
+  return null
+}
 
-      // Check pattern (regex)
-      if (!matched && rule.pattern) {
-        try {
-          const re = new RegExp(rule.pattern, 'i')
-          matched = re.test(text)
-        } catch {
-          // Invalid regex — skip
-        }
-      }
+function extractModelText(content: unknown): string {
+  if (typeof content === 'string') return content
+  if (!Array.isArray(content)) return ''
+  return content
+    .map((part) => (part && typeof part === 'object' && 'text' in part && typeof part.text === 'string') ? part.text : '')
+    .join('')
+}
 
-      if (matched) return [rule.agentId]
+function parseRecipientSelection(text: string, allowedAgentIds: Set<string>): string[] {
+  const jsonText = extractFirstJsonObject(text)
+  if (!jsonText) return []
+  try {
+    const parsed = JSON.parse(jsonText) as Partial<ChatroomRecipientSelection>
+    if (!Array.isArray(parsed.agentIds)) return []
+    const seen = new Set<string>()
+    const selected: string[] = []
+    for (const value of parsed.agentIds) {
+      if (typeof value !== 'string') continue
+      const agentId = value.trim()
+      if (!agentId || !allowedAgentIds.has(agentId) || seen.has(agentId)) continue
+      seen.add(agentId)
+      selected.push(agentId)
     }
+    return selected
+  } catch {
+    return []
+  }
+}
+
+function formatLegacyRule(rule: ChatroomRoutingRule, agentsById: Record<string, Agent | undefined>): string | null {
+  const agentName = agentsById[rule.agentId]?.name || rule.agentId
+  if (rule.type === 'keyword') {
+    const parts = [
+      Array.isArray(rule.keywords) && rule.keywords.length > 0
+        ? `topics or phrases like ${rule.keywords.map((keyword) => `"${keyword}"`).join(', ')}`
+        : null,
+      rule.pattern ? `messages matching ${JSON.stringify(rule.pattern)}` : null,
+    ].filter(Boolean)
+    if (parts.length === 0) return null
+    return `Priority ${rule.priority}: route ${parts.join(' or ')} to ${agentName}.`
+  }
+  if (!rule.pattern) return null
+  return `Priority ${rule.priority}: prefer ${agentName} when the request best fits capability area ${JSON.stringify(rule.pattern)}.`
+}
+
+export function synthesizeRoutingGuidanceFromRules(
+  rules: ChatroomRoutingRule[] | null | undefined,
+  agentsById: Record<string, Agent | undefined>,
+): string | null {
+  if (!Array.isArray(rules) || rules.length === 0) return null
+  const lines = rules
+    .slice()
+    .sort((a, b) => a.priority - b.priority)
+    .map((rule) => formatLegacyRule(rule, agentsById))
+    .filter((line): line is string => typeof line === 'string' && line.trim().length > 0)
+  if (lines.length === 0) return null
+  return [
+    'Legacy routing guidance synthesized from older routing rules. Earlier priorities take precedence when multiple agents could fit.',
+    ...lines,
+  ].join('\n')
+}
 
-    if (rule.type === 'capability') {
-      if (!rule.pattern) continue
-      const patternLower = rule.pattern.toLowerCase()
+export function resolveChatroomRoutingGuidance(
+  chatroom: Chatroom,
+  agentsById: Record<string, Agent | undefined>,
+): string | null {
+  return normalizeGuidance(chatroom.routingGuidance)
+    || synthesizeRoutingGuidanceFromRules(chatroom.routingRules, agentsById)
+}
 
-      // Check if the specific agent has a matching capability
-      const agent = agents.find((a) => a.id === rule.agentId)
-      if (agent && matchesCapabilities(agent.capabilities, [rule.pattern])) {
-        // Only match if the message text is relevant to the capability
-        // Use the pattern as a keyword match against the message text too
-        try {
-          const re = new RegExp(rule.pattern, 'i')
-          if (re.test(text)) return [rule.agentId]
-        } catch {
-          if (lowerText.includes(patternLower)) return [rule.agentId]
-        }
+export function ensureChatroomRoutingGuidance(
+  chatroom: Chatroom,
+  agentsById: Record<string, Agent | undefined>,
+): boolean {
+  const guidance = resolveChatroomRoutingGuidance(chatroom, agentsById)
+  const nextGuidance = normalizeGuidance(guidance)
+  const hadRules = Array.isArray(chatroom.routingRules) && chatroom.routingRules.length > 0
+  const guidanceChanged = nextGuidance !== normalizeGuidance(chatroom.routingGuidance)
+  if (!guidanceChanged && !hadRules) return false
+  chatroom.routingGuidance = nextGuidance
+  delete chatroom.routingRules
+  return guidanceChanged || hadRules
+}
+
+function buildRecipientSelectionPrompt(params: {
+  text: string
+  chatroom: Chatroom
+  guidance: string
+  members: Array<{
+    id: string
+    name: string
+    description: string
+    capabilities: string[]
+  }>
+}): string {
+  return [
+    'Choose which chatroom members should receive the latest message.',
+    'Return JSON only.',
+    'Use only agent IDs from the provided member list.',
+    'Prefer the smallest relevant set. Return an empty array when no routing guidance clearly applies.',
+    'Respect explicit routing guidance over generic capability overlap.',
+    '',
+    'Output shape:',
+    '{"agentIds":["agent-id-1","agent-id-2"]}',
+    '',
+    `Chatroom description: ${JSON.stringify(params.chatroom.description || '')}`,
+    `Routing guidance: ${JSON.stringify(params.guidance)}`,
+    `Latest message: ${JSON.stringify(params.text)}`,
+    'Members:',
+    JSON.stringify(params.members),
+  ].join('\n')
+}
+
+export async function selectChatroomRecipients(
+  params: {
+    text: string
+    chatroom: Chatroom
+    agentsById: Record<string, Agent | undefined>
+  },
+  hooks?: {
+    generateText?: (prompt: string) => Promise<string>
+  },
+): Promise<string[]> {
+  const guidance = resolveChatroomRoutingGuidance(params.chatroom, params.agentsById)
+  if (!guidance) return []
+
+  const members = params.chatroom.agentIds
+    .map((agentId) => {
+      const agent = params.agentsById[agentId]
+      if (!agent) return null
+      return {
+        id: agent.id,
+        name: agent.name,
+        description: agent.description || '',
+        capabilities: Array.isArray(agent.capabilities) ? agent.capabilities.slice(0, 12) : [],
       }
-    }
-  }
+    })
+    .filter((member): member is NonNullable<typeof member> => member !== null)
+  if (members.length === 0) return []
+
+  const prompt = buildRecipientSelectionPrompt({
+    text: params.text,
+    chatroom: params.chatroom,
+    guidance,
+    members,
+  })
+  const allowedAgentIds = new Set(members.map((member) => member.id))
 
-  return []
+  try {
+    const responseText = await Promise.race([
+      hooks?.generateText
+        ? hooks.generateText(prompt)
+        : (async () => {
+            const { llm } = await buildLLM()
+            const response = await llm.invoke([new HumanMessage(prompt)])
+            return extractModelText(response.content)
+          })(),
+      new Promise<never>((_, reject) => {
+        setTimeout(() => reject(new Error('chatroom-recipient-selector-timeout')), SELECTOR_TIMEOUT_MS)
+      }),
+    ])
+    return parseRecipientSelection(responseText, allowedAgentIds)
+  } catch (error: unknown) {
+    log.warn(TAG, 'Failed to select chatroom recipients from routing guidance', {
+      error: error instanceof Error ? error.message : 'unknown',
+      chatroomId: params.chatroom.id,
+    })
+    return []
+  }
 }