@swarmclawai/swarmclaw 1.2.3 → 1.2.5

package/src/lib/server/agents/agent-thread-session.ts

@@ -2,9 +2,10 @@ import { genId } from '@/lib/id'
 import type { Agent, Session } from '@/types'
 import { applyResolvedRoute, resolvePrimaryAgentRoute } from '@/lib/server/agents/agent-runtime-config'
 import { isAgentDisabled } from '@/lib/server/agents/agent-availability'
+import { loadAgent, loadAgents, upsertAgent } from '@/lib/server/agents/agent-repository'
 import { WORKSPACE_DIR } from '@/lib/server/data-dir'
-import { loadAgents, loadSession, loadSessions, upsertAgent, upsertStoredItem } from '@/lib/server/storage'
 import { getEnabledCapabilitySelection } from '@/lib/capability-selection'
+import { loadSession, loadSessions, upsertSession } from '@/lib/server/sessions/session-repository'
 
 function buildEmptyDelegateResumeIds(): NonNullable<Session['delegateResumeIds']> {
   return {
@@ -108,7 +109,7 @@ function shouldHealAgentCredentialId(agent: Agent, session: Session): boolean {
 }
 
 export function ensureAgentThreadSession(agentId: string, user = 'default', preloadedAgent?: Agent): Session | null {
-  const agent = preloadedAgent ?? (loadAgents()[agentId] as Agent | undefined)
+  const agent = preloadedAgent ?? loadAgent(agentId) ?? (loadAgents()[agentId] as Agent | undefined)
   if (!agent) return null
 
   const now = Date.now()
@@ -124,7 +125,7 @@ export function ensureAgentThreadSession(agentId: string, user = 'default', prel
         agent.updatedAt = now
         upsertAgent(agentId, agent)
       }
-      upsertStoredItem('sessions', existingId, session)
+      upsertSession(existingId, session)
       return session
     }
     // Session was deleted — fall through to legacy search / creation
@@ -147,7 +148,7 @@ export function ensureAgentThreadSession(agentId: string, user = 'default', prel
     }
     agent.updatedAt = now
     upsertAgent(agentId, agent)
-    upsertStoredItem('sessions', legacySession.id, session)
+    upsertSession(legacySession.id, session)
     return session
   }
 
@@ -158,7 +159,7 @@ export function ensureAgentThreadSession(agentId: string, user = 'default', prel
   if (shouldHealAgentCredentialId(agent, session)) {
     agent.credentialId = session.credentialId ?? null
   }
-  upsertStoredItem('sessions', sessionId, session)
+  upsertSession(sessionId, session)
 
   agent.threadSessionId = sessionId
   agent.updatedAt = now

package/src/lib/server/agents/autonomy-contract.ts

@@ -1,4 +1,5 @@
 import type { GoalContract } from '@/types'
+import { cleanText } from '@/lib/server/text-normalization'
 
 const PLAN_LINE_RE = /\[MAIN_LOOP_PLAN\]\s*(\{[^\n]*\})/i
 const REVIEW_LINE_RE = /\[MAIN_LOOP_REVIEW\]\s*(\{[^\n]*\})/i
@@ -15,10 +16,6 @@ export interface MainLoopReviewMeta {
   needs_replan?: boolean
 }
 
-function cleanText(value: string, max = 400): string {
-  return (value || '').replace(/\s+/g, ' ').trim().slice(0, max)
-}
-
 function uniqueStrings(input: string[]): string[] {
   const seen = new Set<string>()
   const out: string[] = []

package/src/lib/server/agents/delegation-advisory.test.ts

@@ -0,0 +1,206 @@
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { after, before, describe, it } from 'node:test'
+import type { Agent } from '@/types'
+import type { MessageClassification } from '@/lib/server/chat-execution/message-classifier'
+
+const originalEnv = {
+  DATA_DIR: process.env.DATA_DIR,
+  WORKSPACE_DIR: process.env.WORKSPACE_DIR,
+  SWARMCLAW_BUILD_MODE: process.env.SWARMCLAW_BUILD_MODE,
+}
+
+let tempDir = ''
+let advisory: typeof import('@/lib/server/agents/delegation-advisory')
+let storage: typeof import('@/lib/server/storage')
+
+before(async () => {
+  tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-delegation-advisory-'))
+  process.env.DATA_DIR = path.join(tempDir, 'data')
+  process.env.WORKSPACE_DIR = path.join(tempDir, 'workspace')
+  process.env.SWARMCLAW_BUILD_MODE = '1'
+  fs.mkdirSync(process.env.DATA_DIR, { recursive: true })
+  fs.mkdirSync(process.env.WORKSPACE_DIR, { recursive: true })
+
+  advisory = await import('@/lib/server/agents/delegation-advisory')
+  storage = await import('@/lib/server/storage')
+})
+
+after(() => {
+  if (originalEnv.DATA_DIR === undefined) delete process.env.DATA_DIR
+  else process.env.DATA_DIR = originalEnv.DATA_DIR
+  if (originalEnv.WORKSPACE_DIR === undefined) delete process.env.WORKSPACE_DIR
+  else process.env.WORKSPACE_DIR = originalEnv.WORKSPACE_DIR
+  if (originalEnv.SWARMCLAW_BUILD_MODE === undefined) delete process.env.SWARMCLAW_BUILD_MODE
+  else process.env.SWARMCLAW_BUILD_MODE = originalEnv.SWARMCLAW_BUILD_MODE
+  fs.rmSync(tempDir, { recursive: true, force: true })
+})
+
+function makeAgent(params: Partial<Agent> & Pick<Agent, 'id' | 'name'>): Agent {
+  const now = Date.now()
+  return {
+    id: params.id,
+    name: params.name,
+    role: params.role || 'worker',
+    description: params.description || '',
+    systemPrompt: params.systemPrompt || '',
+    provider: params.provider || 'openai',
+    model: params.model || 'gpt-test',
+    capabilities: params.capabilities || [],
+    delegationEnabled: params.delegationEnabled ?? false,
+    delegationTargetMode: params.delegationTargetMode || 'all',
+    delegationTargetAgentIds: params.delegationTargetAgentIds || [],
+    createdAt: params.createdAt || now,
+    updatedAt: params.updatedAt || now,
+  } as Agent
+}
+
+function makeClassification(overrides: Partial<MessageClassification>): MessageClassification {
+  return {
+    taskIntent: 'general',
+    isDeliverableTask: false,
+    isBroadGoal: false,
+    walletIntent: 'none',
+    hasHumanSignals: false,
+    hasSignificantEvent: false,
+    isResearchSynthesis: false,
+    workType: 'general',
+    wantsScreenshots: false,
+    wantsOutboundDelivery: false,
+    wantsVoiceDelivery: false,
+    explicitToolRequests: [],
+    confidence: 0.9,
+    ...overrides,
+  }
+}
+
+function saveAgents(agents: Agent[]): Record<string, Agent> {
+  const record = Object.fromEntries(agents.map((agent) => [agent.id, agent]))
+  storage.saveAgents(record)
+  storage.saveTasks({})
+  storage.saveSessions({})
+  return record
+}
+
+describe('delegation-advisory', () => {
+  it('prefers a builder over a coordinator for coding work', () => {
+    const agents = saveAgents([
+      makeAgent({
+        id: 'ceo',
+        name: 'CEO',
+        role: 'coordinator',
+        capabilities: ['coordination', 'delegation', 'operations'],
+        delegationEnabled: true,
+      }),
+      makeAgent({
+        id: 'builder',
+        name: 'Builder',
+        role: 'worker',
+        capabilities: ['coding', 'implementation', 'debugging'],
+      }),
+      makeAgent({
+        id: 'writer',
+        name: 'Writer',
+        role: 'worker',
+        capabilities: ['writing', 'editing'],
+      }),
+    ])
+
+    const profile = advisory.buildDelegationTaskProfile({
+      classification: makeClassification({
+        isDeliverableTask: true,
+        workType: 'coding',
+      }),
+    })
+    const result = advisory.resolveDelegationAdvisory({
+      currentAgent: agents.ceo,
+      agents,
+      profile,
+      delegationTargetMode: 'all',
+      delegationTargetAgentIds: [],
+    })
+
+    assert.equal(result.shouldDelegate, true)
+    assert.equal(result.style, 'managerial')
+    assert.equal(result.recommended?.agentId, 'builder')
+    assert.match(advisory.formatDelegationRationale(result.recommended), /coding/i)
+  })
+
+  it('prefers a researcher for research work', () => {
+    const agents = saveAgents([
+      makeAgent({
+        id: 'ceo',
+        name: 'CEO',
+        role: 'coordinator',
+        capabilities: ['coordination', 'delegation', 'operations'],
+        delegationEnabled: true,
+      }),
+      makeAgent({
+        id: 'builder',
+        name: 'Builder',
+        role: 'worker',
+        capabilities: ['coding', 'implementation', 'debugging'],
+      }),
+      makeAgent({
+        id: 'researcher',
+        name: 'Researcher',
+        role: 'worker',
+        capabilities: ['research', 'analysis', 'summarization'],
+      }),
+    ])
+
+    const profile = advisory.buildDelegationTaskProfile({
+      classification: makeClassification({
+        isResearchSynthesis: true,
+        workType: 'research',
+      }),
+    })
+    const result = advisory.resolveDelegationAdvisory({
+      currentAgent: agents.ceo,
+      agents,
+      profile,
+      delegationTargetMode: 'all',
+      delegationTargetAgentIds: [],
+    })
+
+    assert.equal(result.shouldDelegate, true)
+    assert.equal(result.recommended?.agentId, 'researcher')
+  })
+
+  it('does not advise delegation when self is already as capable as peers', () => {
+    const agents = saveAgents([
+      makeAgent({
+        id: 'builder-a',
+        name: 'Builder A',
+        role: 'worker',
+        capabilities: ['coding', 'implementation', 'debugging'],
+        delegationEnabled: true,
+      }),
+      makeAgent({
+        id: 'builder-b',
+        name: 'Builder B',
+        role: 'worker',
+        capabilities: ['coding', 'implementation', 'debugging'],
+      }),
+    ])
+
+    const profile = advisory.buildDelegationTaskProfile({
+      classification: makeClassification({
+        isDeliverableTask: true,
+        workType: 'coding',
+      }),
+    })
+    const result = advisory.resolveDelegationAdvisory({
+      currentAgent: agents['builder-a'],
+      agents,
+      profile,
+      delegationTargetMode: 'all',
+      delegationTargetAgentIds: [],
+    })
+
+    assert.equal(result.recommended?.agentId, 'builder-b')
+    assert.equal(result.shouldDelegate, false)
+  })
+})

package/src/lib/server/agents/delegation-advisory.ts

@@ -0,0 +1,251 @@
+import type { Agent } from '@/types'
+import type { MessageClassification } from '@/lib/server/chat-execution/message-classifier'
+import { capabilityMatchScore } from '@/lib/server/agents/capability-match'
+import { getAgentDirectory, type AgentDirectoryEntry } from '@/lib/server/agents/agent-registry'
+
+export type DelegationWorkType =
+  | 'coding'
+  | 'research'
+  | 'writing'
+  | 'review'
+  | 'operations'
+  | 'general'
+
+export interface DelegationTaskProfile {
+  workType: DelegationWorkType
+  requiredCapabilities: string[]
+  substantial: boolean
+}
+
+export interface DelegationCandidateFit {
+  agentId: string
+  agentName: string
+  score: number
+  availability: 'idle' | 'working' | 'unknown'
+  matchedCapabilities: string[]
+  reasons: string[]
+}
+
+export interface DelegationAdvisory {
+  profile: DelegationTaskProfile
+  current: DelegationCandidateFit | null
+  recommended: DelegationCandidateFit | null
+  shouldDelegate: boolean
+  style: 'managerial' | 'advisory'
+}
+
+const WORK_TYPE_CAPABILITIES: Record<DelegationWorkType, string[]> = {
+  coding: ['coding', 'implementation', 'debugging'],
+  research: ['research', 'analysis', 'summarization'],
+  writing: ['writing', 'messaging', 'structuring', 'editing'],
+  review: ['review', 'testing', 'risk assessment'],
+  operations: ['coordination', 'delegation', 'operations'],
+  general: [],
+}
+
+function normalizeCapabilityList(value: string[] | undefined | null): string[] {
+  if (!Array.isArray(value)) return []
+  const seen = new Set<string>()
+  const out: string[] = []
+  for (const entry of value) {
+    const trimmed = typeof entry === 'string' ? entry.trim() : ''
+    const key = trimmed.toLowerCase()
+    if (!trimmed || seen.has(key)) continue
+    seen.add(key)
+    out.push(trimmed)
+  }
+  return out
+}
+
+function normalizeWorkType(value: unknown): DelegationWorkType {
+  if (
+    value === 'coding'
+    || value === 'research'
+    || value === 'writing'
+    || value === 'review'
+    || value === 'operations'
+  ) {
+    return value
+  }
+  return 'general'
+}
+
+function matchedCapabilities(agentCapabilities: string[] | undefined, requiredCapabilities: string[]): string[] {
+  if (!requiredCapabilities.length || !Array.isArray(agentCapabilities) || !agentCapabilities.length) return []
+  const agentSet = new Set(agentCapabilities.map((entry) => entry.toLowerCase()))
+  return requiredCapabilities.filter((entry) => agentSet.has(entry.toLowerCase()))
+}
+
+function roleAdjustment(agent: Agent, profile: DelegationTaskProfile): number {
+  const role = agent.role === 'coordinator' ? 'coordinator' : 'worker'
+  if (profile.workType === 'operations') {
+    return role === 'coordinator' ? 0.28 : -0.04
+  }
+  if (profile.workType === 'general') {
+    return role === 'coordinator' ? -0.03 : 0
+  }
+  return role === 'coordinator' ? -0.18 : 0.16
+}
+
+function selfExecutionPenalty(agent: Agent, profile: DelegationTaskProfile, isSelf: boolean): number {
+  if (!isSelf) return 0
+  if (agent.role !== 'coordinator') return 0
+  if (!profile.substantial) return 0
+  if (profile.workType === 'operations') return 0
+  return -0.42
+}
+
+function availabilityAdjustment(
+  availability: DelegationCandidateFit['availability'],
+  isSelf: boolean,
+  directoryEntry?: AgentDirectoryEntry,
+): number {
+  if (availability === 'idle') return 0.08
+  if (availability === 'working') {
+    // The current live chat session should not count as a self-load penalty.
+    if (isSelf && !directoryEntry?.statusDetail) return 0.08
+    return -0.08
+  }
+  return 0
+}
+
+function buildAvailabilityMap(): Map<string, AgentDirectoryEntry> {
+  return new Map(getAgentDirectory().map((entry) => [entry.id, entry]))
+}
+
+function buildCandidateFit(
+  agent: Agent,
+  profile: DelegationTaskProfile,
+  directory: Map<string, AgentDirectoryEntry>,
+  isSelf = false,
+): DelegationCandidateFit {
+  const directoryEntry = directory.get(agent.id)
+  const availability = directoryEntry?.status || 'unknown'
+  const matched = matchedCapabilities(agent.capabilities, profile.requiredCapabilities)
+  const capabilityScore = profile.requiredCapabilities.length > 0
+    ? capabilityMatchScore(agent.capabilities, profile.requiredCapabilities) * 1.45
+    : 0
+  const score = capabilityScore
+    + roleAdjustment(agent, profile)
+    + availabilityAdjustment(availability, isSelf, directoryEntry)
+    + selfExecutionPenalty(agent, profile, isSelf)
+
+  const reasons: string[] = []
+  if (matched.length > 0) reasons.push(`capability match: ${matched.join(', ')}`)
+  if (profile.workType === 'operations' && agent.role === 'coordinator') reasons.push('coordinator role fits operations work')
+  if (profile.workType !== 'operations' && profile.workType !== 'general' && agent.role !== 'coordinator') reasons.push('worker role fits execution-heavy work')
+  if (availability === 'idle') reasons.push('currently idle')
+  if (availability === 'working' && directoryEntry?.statusDetail) reasons.push(directoryEntry.statusDetail)
+  if (isSelf && selfExecutionPenalty(agent, profile, true) < 0) reasons.push('coordinator should prefer orchestration over direct execution')
+
+  return {
+    agentId: agent.id,
+    agentName: agent.name,
+    score,
+    availability,
+    matchedCapabilities: matched,
+    reasons,
+  }
+}
+
+function isAllowedDelegateTarget(
+  agentId: string,
+  opts?: { delegationTargetMode?: 'all' | 'selected'; delegationTargetAgentIds?: string[] },
+): boolean {
+  if (opts?.delegationTargetMode !== 'selected') return true
+  const allowed = new Set(normalizeCapabilityList(opts.delegationTargetAgentIds))
+  return allowed.size === 0 || allowed.has(agentId)
+}
+
+export function resolveDelegationWorkType(
+  classification: MessageClassification | null | undefined,
+): DelegationWorkType {
+  return normalizeWorkType(classification?.workType)
+}
+
+export function buildDelegationTaskProfile(params: {
+  classification?: MessageClassification | null
+  workType?: DelegationWorkType | null
+  requiredCapabilities?: string[] | null
+}): DelegationTaskProfile {
+  const workType = params.workType
+    ? normalizeWorkType(params.workType)
+    : resolveDelegationWorkType(params.classification)
+  const explicitRequirements = normalizeCapabilityList(params.requiredCapabilities)
+  const requiredCapabilities = explicitRequirements.length > 0
+    ? explicitRequirements
+    : WORK_TYPE_CAPABILITIES[workType]
+  const substantial = explicitRequirements.length > 0
+    || Boolean(params.classification?.isBroadGoal)
+    || Boolean(params.classification?.isDeliverableTask)
+    || Boolean(params.classification?.isResearchSynthesis)
+    || workType !== 'general'
+  return {
+    workType,
+    requiredCapabilities,
+    substantial,
+  }
+}
+
+export function resolveBestDelegateTarget(params: {
+  currentAgentId?: string | null
+  agents: Record<string, Agent>
+  profile: DelegationTaskProfile
+  delegationTargetMode?: 'all' | 'selected'
+  delegationTargetAgentIds?: string[]
+}): DelegationCandidateFit | null {
+  const directory = buildAvailabilityMap()
+  const candidates = Object.values(params.agents)
+    .filter((agent) => agent.id !== params.currentAgentId)
+    .filter((agent) => !agent.disabled && !agent.trashedAt)
+    .filter((agent) => isAllowedDelegateTarget(agent.id, params))
+    .map((agent) => buildCandidateFit(agent, params.profile, directory))
+    .sort((left, right) => {
+      if (right.score !== left.score) return right.score - left.score
+      return left.agentName.localeCompare(right.agentName)
+    })
+  return candidates[0] || null
+}
+
+export function resolveDelegationAdvisory(params: {
+  currentAgent: Agent | null | undefined
+  agents: Record<string, Agent>
+  profile: DelegationTaskProfile
+  delegationTargetMode?: 'all' | 'selected'
+  delegationTargetAgentIds?: string[]
+}): DelegationAdvisory {
+  const directory = buildAvailabilityMap()
+  const current = params.currentAgent && !params.currentAgent.disabled && !params.currentAgent.trashedAt
+    ? buildCandidateFit(params.currentAgent, params.profile, directory, true)
+    : null
+  const recommended = resolveBestDelegateTarget({
+    currentAgentId: params.currentAgent?.id || null,
+    agents: params.agents,
+    profile: params.profile,
+    delegationTargetMode: params.delegationTargetMode,
+    delegationTargetAgentIds: params.delegationTargetAgentIds,
+  })
+  const currentScore = current?.score ?? 0
+  const recommendedScore = recommended?.score ?? Number.NEGATIVE_INFINITY
+  const shouldDelegate = Boolean(
+    params.profile.substantial
+    && recommended
+    && recommendedScore >= currentScore + 0.3
+    && recommendedScore >= 0.25,
+  )
+  const style = params.currentAgent?.role === 'coordinator' && params.profile.workType !== 'operations'
+    ? 'managerial'
+    : 'advisory'
+  return {
+    profile: params.profile,
+    current,
+    recommended,
+    shouldDelegate,
+    style,
+  }
+}
+
+export function formatDelegationRationale(candidate: DelegationCandidateFit | null | undefined): string {
+  if (!candidate || candidate.reasons.length === 0) return 'better fit for this work'
+  return candidate.reasons.slice(0, 2).join('; ')
+}