@swarmclawai/swarmclaw 1.3.5 → 1.4.0

package/src/lib/server/chat-execution/chat-execution-disabled.test.ts

@@ -1,40 +1,23 @@
 import assert from 'node:assert/strict'
-import fs from 'node:fs'
-import os from 'node:os'
-import path from 'node:path'
-import { spawnSync } from 'node:child_process'
 import test from 'node:test'
+import { runWithTempDataDir as runWithSharedTempDataDir } from '@/lib/server/test-utils/run-with-temp-data-dir'
 
-const repoRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname), '../../..')
-
-function runWithTempDataDir(script: string) {
-  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-chat-disabled-'))
-  try {
-    const result = spawnSync(process.execPath, ['--import', 'tsx', '--input-type=module', '--eval', script], {
-      cwd: repoRoot,
-      env: {
-        ...process.env,
-        DATA_DIR: path.join(tempDir, 'data'),
-        WORKSPACE_DIR: path.join(tempDir, 'workspace'),
-        BROWSER_PROFILES_DIR: path.join(tempDir, 'browser-profiles'),
-      },
-      encoding: 'utf-8',
-    })
-    assert.equal(result.status, 0, result.stderr || result.stdout || 'subprocess failed')
-    const lines = (result.stdout || '')
-      .trim()
-      .split('\n')
-      .map((line) => line.trim())
-      .filter(Boolean)
-    const jsonLine = [...lines].reverse().find((line) => line.startsWith('{'))
-    return JSON.parse(jsonLine || '{}')
-  } finally {
-    fs.rmSync(tempDir, { recursive: true, force: true })
-  }
+function runWithTempDataDir<T = unknown>(script: string): T {
+  return runWithSharedTempDataDir<T>(script, {
+    prefix: 'swarmclaw-chat-disabled-',
+    dataDir: 'data',
+    browserProfilesDir: 'browser-profiles',
+  })
 }
 
 test('executeSessionChatTurn persists a visible error for disabled agents', () => {
-  const output = runWithTempDataDir(`
+  const output = runWithTempDataDir<{
+    error: string | null
+    text: string | null
+    persisted: boolean
+    lastRole: string | null
+    lastText: string | null
+  }>(`
     const storageMod = await import('@/lib/server/storage')
     const storage = storageMod.default || storageMod['module.exports'] || storageMod
     const threadMod = await import('@/lib/server/agents/agent-thread-session')

package/src/lib/server/chat-execution/chat-execution-eval-history.test.ts

@@ -1,40 +1,13 @@
 import assert from 'node:assert/strict'
-import fs from 'node:fs'
-import os from 'node:os'
-import path from 'node:path'
-import { spawnSync } from 'node:child_process'
 import test from 'node:test'
-
-const repoRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname), '../../..')
-
-function runWithTempDataDir(script: string) {
-  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-chat-eval-history-'))
-  try {
-    const result = spawnSync(process.execPath, ['--import', 'tsx', '--input-type=module', '--eval', script], {
-      cwd: repoRoot,
-      env: {
-        ...process.env,
-        DATA_DIR: path.join(tempDir, 'data'),
-        WORKSPACE_DIR: path.join(tempDir, 'workspace'),
-        BROWSER_PROFILES_DIR: path.join(tempDir, 'browser-profiles'),
-      },
-      encoding: 'utf-8',
-    })
-    assert.equal(result.status, 0, result.stderr || result.stdout || 'subprocess failed')
-    const lines = (result.stdout || '')
-      .trim()
-      .split('\n')
-      .map((line) => line.trim())
-      .filter(Boolean)
-    const jsonLine = [...lines].reverse().find((line) => line.startsWith('{'))
-    return JSON.parse(jsonLine || '{}')
-  } finally {
-    fs.rmSync(tempDir, { recursive: true, force: true })
-  }
-}
+import { runWithTempDataDir } from '@/lib/server/test-utils/run-with-temp-data-dir'
 
 test('executeSessionChatTurn persists internal eval user turns for same-thread recall', () => {
-  const output = runWithTempDataDir(`
+  const output = runWithTempDataDir<{
+    recallText: string | null
+    roles: string[]
+    texts: string[]
+  }>(`
     const storageMod = await import('@/lib/server/storage')
     const storage = storageMod.default || storageMod['module.exports'] || storageMod
     const providersMod = await import('@/lib/providers/index')
@@ -103,7 +76,11 @@ test('executeSessionChatTurn persists internal eval user turns for same-thread r
       roles: storedSession.messages.map((entry) => entry.role),
       texts: storedSession.messages.map((entry) => entry.text),
     }))
-  `)
+  `, {
+    prefix: 'swarmclaw-chat-eval-history-',
+    dataDir: 'data',
+    browserProfilesDir: 'browser-profiles',
+  })
 
   assert.match(String(output.recallText || ''), /Sunbird/)
   assert.deepEqual(output.roles, ['user', 'assistant', 'user', 'assistant'])

package/src/lib/server/chat-execution/chat-execution-grounding.test.ts

@@ -1,40 +1,17 @@
 import assert from 'node:assert/strict'
-import fs from 'node:fs'
-import os from 'node:os'
-import path from 'node:path'
-import { spawnSync } from 'node:child_process'
 import test from 'node:test'
-
-const repoRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname), '../../..')
-
-function runWithTempDataDir(script: string) {
-  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-chat-grounding-'))
-  try {
-    const result = spawnSync(process.execPath, ['--import', 'tsx', '--input-type=module', '--eval', script], {
-      cwd: repoRoot,
-      env: {
-        ...process.env,
-        DATA_DIR: path.join(tempDir, 'data'),
-        WORKSPACE_DIR: path.join(tempDir, 'workspace'),
-        BROWSER_PROFILES_DIR: path.join(tempDir, 'browser-profiles'),
-      },
-      encoding: 'utf-8',
-    })
-    assert.equal(result.status, 0, result.stderr || result.stdout || 'subprocess failed')
-    const lines = (result.stdout || '')
-      .trim()
-      .split('\n')
-      .map((line) => line.trim())
-      .filter(Boolean)
-    const jsonLine = [...lines].reverse().find((line) => line.startsWith('{'))
-    return JSON.parse(jsonLine || '{}')
-  } finally {
-    fs.rmSync(tempDir, { recursive: true, force: true })
-  }
-}
+import { runWithTempDataDir } from '@/lib/server/test-utils/run-with-temp-data-dir'
 
 test('executeSessionChatTurn persists citations and retrieval traces on grounded assistant messages', () => {
-  const output = runWithTempDataDir(`
+  const output = runWithTempDataDir<{
+    persisted: boolean
+    resultCitationCount: number
+    resultSelectorStatus: string | null
+    messageCitationCount: number
+    messageTraceHitCount: number
+    messageSelectorStatus: string | null
+    messageSourceTitle: string | null
+  }>(`
     const storageMod = await import('@/lib/server/storage')
     const providersMod = await import('@/lib/providers/index')
     const threadMod = await import('@/lib/server/agents/agent-thread-session')
@@ -115,7 +92,11 @@ test('executeSessionChatTurn persists citations and retrieval traces on grounded
       messageSelectorStatus: lastMessage?.retrievalTrace?.selectorStatus || null,
       messageSourceTitle: lastMessage?.citations?.[0]?.sourceTitle || null,
     }))
-  `)
+  `, {
+    prefix: 'swarmclaw-chat-grounding-',
+    dataDir: 'data',
+    browserProfilesDir: 'browser-profiles',
+  })
 
   assert.equal(output.persisted, true)
   assert.equal(output.resultCitationCount >= 1, true)

package/src/lib/server/chat-execution/chat-execution-session-sync.test.ts

@@ -1,40 +1,24 @@
 import assert from 'node:assert/strict'
-import fs from 'node:fs'
-import os from 'node:os'
-import path from 'node:path'
-import { spawnSync } from 'node:child_process'
 import test from 'node:test'
-
-const repoRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname), '../../..')
-
-function runWithTempDataDir(script: string) {
-  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-chat-session-sync-'))
-  try {
-    const result = spawnSync(process.execPath, ['--import', 'tsx', '--input-type=module', '--eval', script], {
-      cwd: repoRoot,
-      env: {
-        ...process.env,
-        DATA_DIR: path.join(tempDir, 'data'),
-        WORKSPACE_DIR: path.join(tempDir, 'workspace'),
-        BROWSER_PROFILES_DIR: path.join(tempDir, 'browser-profiles'),
-      },
-      encoding: 'utf-8',
-    })
-    assert.equal(result.status, 0, result.stderr || result.stdout || 'subprocess failed')
-    const lines = (result.stdout || '')
-      .trim()
-      .split('\n')
-      .map((line) => line.trim())
-      .filter(Boolean)
-    const jsonLine = [...lines].reverse().find((line) => line.startsWith('{'))
-    return JSON.parse(jsonLine || '{}')
-  } finally {
-    fs.rmSync(tempDir, { recursive: true, force: true })
-  }
+import { runWithTempDataDir as runWithSharedTempDataDir } from '@/lib/server/test-utils/run-with-temp-data-dir'
+
+function runWithTempDataDir<T = unknown>(script: string): T {
+  return runWithSharedTempDataDir<T>(script, {
+    prefix: 'swarmclaw-chat-session-sync-',
+    dataDir: 'data',
+    browserProfilesDir: 'browser-profiles',
+  })
 }
 
 test('executeSessionChatTurn syncs updated agent runtime fields onto its thread session', () => {
-  const output = runWithTempDataDir(`
+  const output = runWithTempDataDir<{
+    provider: string | null
+    model: string | null
+    extensions: string[]
+    heartbeatEnabled: boolean | null
+    heartbeatIntervalSec: number | null
+    connectorContext: Record<string, unknown> | null
+  }>(`
     const storageMod = await import('@/lib/server/storage')
     const storage = storageMod.default || storageMod['module.exports'] || storageMod
     const providersMod = await import('@/lib/providers/index')
@@ -126,7 +110,12 @@ test('executeSessionChatTurn syncs updated agent runtime fields onto its thread
 })
 
 test('executeSessionChatTurn keeps tool-only heartbeats off the visible main-thread history and clears stale connector state', () => {
-  const output = runWithTempDataDir(`
+  const output = runWithTempDataDir<{
+    connectorContext: Record<string, unknown> | null
+    messageCount: number
+    lastMessageText: string | null
+    heartbeatKinds: number
+  }>(`
     const storageMod = await import('@/lib/server/storage')
     const providersMod = await import('@/lib/providers/index')
     const execMod = await import('@/lib/server/chat-execution/chat-execution')
@@ -232,7 +221,11 @@ test('executeSessionChatTurn keeps tool-only heartbeats off the visible main-thr
 })
 
 test('executeSessionChatTurn hides internal main-loop followup output from the visible transcript', () => {
-  const output = runWithTempDataDir(`
+  const output = runWithTempDataDir<{
+    messageCount: number
+    lastMessageText: string | null
+    hasStreamingArtifacts: boolean
+  }>(`
     const storageMod = await import('@/lib/server/storage')
     const providersMod = await import('@/lib/providers/index')
     const execMod = await import('@/lib/server/chat-execution/chat-execution')
@@ -324,7 +317,10 @@ test('executeSessionChatTurn hides internal main-loop followup output from the v
 })
 
 test('executeSessionChatTurn forces external connector sessions onto session-scoped memory', () => {
-  const output = runWithTempDataDir(`
+  const output = runWithTempDataDir<{
+    memoryScopeMode: string | null
+    connectorContext: { isOwnerConversation?: boolean } | null
+  }>(`
     const storageMod = await import('@/lib/server/storage')
     const providersMod = await import('@/lib/providers/index')
     const execMod = await import('@/lib/server/chat-execution/chat-execution')
@@ -418,7 +414,10 @@ test('executeSessionChatTurn forces external connector sessions onto session-sco
 })
 
 test('executeSessionChatTurn applies lifecycle hooks for model resolution and message persistence', () => {
-  const output = runWithTempDataDir(`
+  const output = runWithTempDataDir<{
+    lastMessageText: string
+    marks: string[]
+  }>(`
     const storageMod = await import('@/lib/server/storage')
     const providersMod = await import('@/lib/providers/index')
     const extMod = await import('@/lib/server/extensions')

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

@@ -89,14 +89,19 @@ export async function executeSessionChatTurn(input: ExecuteChatTurnInput): Promi
     return preflight.terminalResult
   }
 
-  const streamResult = await executePreparedChatTurn({
-    input,
-    prepared: preparedTurn,
-    partialPersistence,
-    preflightToolRoutingResult: preflight?.directMemoryResult || null,
-  })
+  let streamResult: Awaited<ReturnType<typeof executePreparedChatTurn>>
+  try {
+    streamResult = await executePreparedChatTurn({
+      input,
+      prepared: preparedTurn,
+      partialPersistence,
+      preflightToolRoutingResult: preflight?.directMemoryResult || null,
+    })
 
-  await partialPersistence.awaitIdle()
+    await partialPersistence.awaitIdle()
+  } finally {
+    partialPersistence.stop()
+  }
 
   if (!streamResult.errorMessage) {
     markProviderSuccess(preparedTurn.providerType, preparedTurn.sessionForRun.credentialId)

package/src/lib/server/extensions.ts

@@ -874,6 +874,17 @@ class ExtensionManager {
     try {
       const parsed = JSON.parse(fs.readFileSync(EXTENSION_FAILURES, 'utf8')) as Record<string, ExtensionFailureRecord>
       if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {}
+      // Prune records older than 7 days
+      const maxAgeMs = 7 * 24 * 60 * 60 * 1000
+      const now = Date.now()
+      let pruned = false
+      for (const key of Object.keys(parsed)) {
+        if (now - (parsed[key].lastFailedAt || 0) > maxAgeMs) {
+          delete parsed[key]
+          pruned = true
+        }
+      }
+      if (pruned) this.writeFailureState(parsed)
       return parsed
     } catch {
       return {}

package/src/lib/server/knowledge-sources.test.ts

@@ -213,3 +213,49 @@ test('runKnowledgeHygieneMaintenance reindexes stale file sources and archives e
   assert.ok(output.recentActionKinds.includes('archive'))
   assert.ok(output.recentActionKinds.includes('reindex') || output.recentActionKinds.includes('sync'))
 })
+
+test('runKnowledgeHygieneMaintenance keeps same-content sources separate when visibility differs', () => {
+  const output = runWithTempDataDir<{
+    globalArchived: boolean
+    agentArchived: boolean
+    agent1Hits: number
+    agent2Hits: number
+  }>(`
+    const knowledgeMod = await import('./src/lib/server/knowledge-sources.ts')
+    const knowledge = knowledgeMod.default || knowledgeMod
+
+    const globalSource = await knowledge.createKnowledgeSource({
+      kind: 'manual',
+      title: 'Global Policy',
+      content: 'identical content',
+      scope: 'global',
+    })
+
+    const agentSource = await knowledge.createKnowledgeSource({
+      kind: 'manual',
+      title: 'Scoped Policy',
+      content: 'identical content',
+      scope: 'agent',
+      agentIds: ['agent-1'],
+    })
+
+    await knowledge.runKnowledgeHygieneMaintenance()
+
+    const globalDetail = await knowledge.getKnowledgeSourceDetail(globalSource.source.id)
+    const agentDetail = await knowledge.getKnowledgeSourceDetail(agentSource.source.id)
+    const agent1Hits = await knowledge.searchKnowledgeHits({ query: 'identical', viewerAgentId: 'agent-1' })
+    const agent2Hits = await knowledge.searchKnowledgeHits({ query: 'identical', viewerAgentId: 'agent-2' })
+
+    console.log(JSON.stringify({
+      globalArchived: !!globalDetail?.source?.archivedAt,
+      agentArchived: !!agentDetail?.source?.archivedAt,
+      agent1Hits: agent1Hits.length,
+      agent2Hits: agent2Hits.length,
+    }))
+  `, { prefix: 'swarmclaw-knowledge-visibility-' })
+
+  assert.equal(output.globalArchived, false)
+  assert.equal(output.agentArchived, false)
+  assert.equal(output.agent1Hits, 2)
+  assert.equal(output.agent2Hits, 1)
+})

package/src/lib/server/knowledge-sources.ts

@@ -1056,6 +1056,38 @@ function sameSourceOrigin(left: KnowledgeSource, right: KnowledgeSource): boolea
   return false
 }
 
+function duplicateOriginFingerprint(source: KnowledgeSource): string {
+  if (source.sourceUrl) return `url:${source.sourceUrl}`
+  if (source.sourcePath) return `path:${source.sourcePath}`
+  return `kind:${source.kind}`
+}
+
+function duplicateGroupKey(source: KnowledgeSource): string | null {
+  if (!source.sourceHash) return null
+  const sortedAgentIds = [...source.agentIds].sort()
+  const sortedTags = [...source.tags].map((tag) => tag.toLowerCase()).sort()
+  return [
+    source.sourceHash,
+    source.kind,
+    source.scope,
+    sortedAgentIds.join(','),
+    sortedTags.join(','),
+    duplicateOriginFingerprint(source),
+  ].join('|')
+}
+
+function collectDuplicateGroups(sources: KnowledgeSource[]): Map<string, KnowledgeSource[]> {
+  const duplicateGroups = new Map<string, KnowledgeSource[]>()
+  for (const source of sources) {
+    const groupKey = duplicateGroupKey(source)
+    if (!groupKey) continue
+    const group = duplicateGroups.get(groupKey) || []
+    group.push(source)
+    duplicateGroups.set(groupKey, group)
+  }
+  return duplicateGroups
+}
+
 function canonicalSourceForGroup(group: KnowledgeSource[]): KnowledgeSource {
   return [...group].sort((left, right) => {
     const archiveDelta = Number(sourceIsExcludedByDefault(left)) - Number(sourceIsExcludedByDefault(right))
@@ -1072,14 +1104,7 @@ function buildHygieneSummary(sources: KnowledgeSource[]): KnowledgeHygieneSummar
   const pushFinding = (finding: KnowledgeHygieneFinding) => {
     if (findings.length < MAX_HYGIENE_FINDINGS) findings.push(finding)
   }
-
-  const duplicateGroups = new Map<string, KnowledgeSource[]>()
-  for (const source of sources) {
-    if (!source.sourceHash) continue
-    const group = duplicateGroups.get(source.sourceHash) || []
-    group.push(source)
-    duplicateGroups.set(source.sourceHash, group)
-  }
+  const duplicateGroups = collectDuplicateGroups(sources)
 
   for (const source of sources) {
     if (sourceIsArchived(source)) {
@@ -1185,14 +1210,7 @@ export async function getKnowledgeHygieneSummary(): Promise<KnowledgeHygieneSumm
 export async function runKnowledgeHygieneMaintenance(): Promise<KnowledgeHygieneSummary> {
   await ensureLegacyKnowledgeBackfill()
   const sources = listStoredSources()
-
-  const duplicateGroups = new Map<string, KnowledgeSource[]>()
-  for (const source of sources) {
-    if (!source.sourceHash) continue
-    const group = duplicateGroups.get(source.sourceHash) || []
-    group.push(source)
-    duplicateGroups.set(source.sourceHash, group)
-  }
+  const duplicateGroups = collectDuplicateGroups(sources)
 
   for (const source of sources) {
     if (sourceIsExcludedByDefault(source)) continue

package/src/lib/server/openclaw/sync.ts

@@ -381,7 +381,7 @@ export function syncExtensionsFromOpenClaw(): { imported: number } {
   const openclawExtensionDir = path.join(config.workspacePath, 'plugins')
   if (!fs.existsSync(openclawExtensionDir)) return { imported: 0 }
 
-  const localExtensionDir = path.join(DATA_DIR, 'plugins')
+  const localExtensionDir = path.join(DATA_DIR, 'extensions')
   ensureDir(localExtensionDir)
 
   const files = fs.readdirSync(openclawExtensionDir).filter((f) => f.endsWith('.js'))
@@ -432,7 +432,7 @@ export function setSharedDeviceToken(token: string): void {
 
 // --- Unified Sync Entry Point ---
 
-export type SyncType = 'memory' | 'workspace' | 'schedules' | 'credentials' | 'plugins'
+export type SyncType = 'memory' | 'workspace' | 'schedules' | 'credentials' | 'extensions'
 
 export interface SyncResult {
   type: SyncType
@@ -467,7 +467,7 @@ export async function runSync(params: {
         case 'credentials':
           results.push({ type, action: 'push', result: pushCredentialsToOpenClaw() })
           break
-        case 'plugins':
+        case 'extensions':
           // Extensions only pull from OpenClaw
           break
       }
@@ -492,7 +492,7 @@ export async function runSync(params: {
         case 'credentials':
           results.push({ type, action: 'pull', result: await pullCredentialsFromOpenClaw() })
           break
-        case 'plugins':
+        case 'extensions':
           results.push({ type, action: 'pull', result: syncExtensionsFromOpenClaw() })
           break
       }

package/src/lib/server/protocols/protocol-a2a-delegate.ts

@@ -0,0 +1,135 @@
+import { genId } from '@/lib/id'
+import { log } from '@/lib/server/logger'
+import { errorMessage } from '@/lib/shared-utils'
+import { upsertTask } from '@/lib/server/tasks/task-repository'
+import { notify } from '@/lib/server/ws-hub'
+import { callA2AAgent } from '@/lib/a2a/client'
+import { loadExternalAgents } from '@/lib/server/storage'
+import { appendProtocolEvent, persistRun } from '@/lib/server/protocols/protocol-agent-turn'
+import { now } from '@/lib/server/protocols/protocol-types'
+import type { ProtocolRunDeps } from '@/lib/server/protocols/protocol-types'
+import type { ProtocolPhaseDefinition, ProtocolRun, ProtocolRunPhaseState } from '@/types/protocol'
+import type { BoardTask } from '@/types/task'
+
+const TAG = 'protocol-a2a-delegate'
+
+/**
+ * Process an a2a_delegate phase: call a remote A2A agent and wait for the result.
+ *
+ * Follows the same pattern as processDispatchDelegationPhase:
+ * 1. Create a BoardTask for tracking (with protocolRunId so wakeProtocolRunFromTaskCompletion fires)
+ * 2. Call the remote agent via HTTP
+ * 3. Set protocol run to 'waiting'
+ * 4. When the HTTP call completes, update the task → wake machinery resumes the run
+ */
+export function processA2ADelegatePhase(
+  run: ProtocolRun,
+  phase: ProtocolPhaseDefinition,
+  deps?: ProtocolRunDeps,
+): ProtocolRun {
+  const config = phase.a2aDelegateConfig
+  if (!config?.taskName || !config?.taskMessage) {
+    appendProtocolEvent(run.id, {
+      type: 'failed',
+      phaseId: phase.id,
+      summary: `a2a_delegate phase "${phase.label}" missing a2aDelegateConfig`,
+    }, deps)
+    return persistRun({
+      ...run,
+      status: 'failed',
+      lastError: `a2a_delegate phase "${phase.label}" missing a2aDelegateConfig`,
+      endedAt: run.endedAt || now(deps),
+      updatedAt: now(deps),
+    })
+  }
+
+  // Resolve target URL
+  let targetUrl = config.targetUrl
+  if (!targetUrl && config.targetExternalAgentId) {
+    const externalAgents = loadExternalAgents()
+    const ea = externalAgents[config.targetExternalAgentId]
+    if (ea?.endpoint) {
+      targetUrl = ea.endpoint
+    }
+  }
+
+  if (!targetUrl) {
+    appendProtocolEvent(run.id, {
+      type: 'failed',
+      phaseId: phase.id,
+      summary: `a2a_delegate phase "${phase.label}" — no target URL resolved`,
+    }, deps)
+    return persistRun({
+      ...run,
+      status: 'failed',
+      lastError: `a2a_delegate phase "${phase.label}" — could not resolve target A2A agent URL`,
+      endedAt: run.endedAt || now(deps),
+      updatedAt: now(deps),
+    })
+  }
+
+  // Create a BoardTask for tracking
+  const taskId = genId()
+  const taskData: BoardTask = {
+    id: taskId,
+    title: `A2A: ${config.taskName}`,
+    description: config.taskMessage,
+    status: 'queued',
+    agentId: run.facilitatorAgentId || run.participantAgentIds?.[0] || '',
+    protocolRunId: run.id,
+    sourceType: 'delegation',
+    externalSource: { source: 'a2a', id: taskId },
+    queuedAt: now(deps),
+    createdAt: now(deps),
+    updatedAt: now(deps),
+  }
+  upsertTask(taskId, taskData)
+  notify('tasks')
+
+  appendProtocolEvent(run.id, {
+    type: 'delegation_dispatched',
+    summary: `Dispatched A2A delegation to ${targetUrl}: ${config.taskName}`,
+    phaseId: phase.id,
+    taskId,
+  }, deps)
+
+  log.info(TAG, `Calling remote A2A agent at ${targetUrl}`, { taskName: config.taskName, taskId })
+
+  // Fire the HTTP call asynchronously — when it completes, update the task
+  // The existing wakeProtocolRunFromTaskCompletion machinery will resume the run
+  const resolvedUrl = targetUrl
+  callA2AAgent(resolvedUrl, 'executeTask', {
+    taskId,
+    taskName: config.taskName,
+    message: config.taskMessage,
+  }, {
+    timeout: config.timeoutMs ?? 300_000,
+    credentialId: config.credentialId,
+  }).then(result => {
+    const resultStr = typeof result === 'string' ? result : JSON.stringify(result)
+    upsertTask(taskId, { ...taskData, status: 'completed', result: resultStr, updatedAt: Date.now(), completedAt: Date.now() })
+    notify('tasks')
+    log.info(TAG, `A2A delegation completed for task ${taskId}`)
+    // Dynamic import to break circular dependency (protocol-step-processors → protocol-a2a-delegate → protocol-run-lifecycle → protocol-step-processors)
+    import('@/lib/server/protocols/protocol-run-lifecycle').then(m => m.wakeProtocolRunFromTaskCompletion(taskId))
+  }).catch(err => {
+    log.error(TAG, `A2A delegation failed for task ${taskId}: ${errorMessage(err)}`)
+    if (config.onFailure === 'advance_with_warning') {
+      upsertTask(taskId, { ...taskData, status: 'completed', result: `A2A delegation failed: ${errorMessage(err)}`, error: errorMessage(err), updatedAt: Date.now(), completedAt: Date.now() })
+    } else {
+      upsertTask(taskId, { ...taskData, status: 'failed', error: errorMessage(err), updatedAt: Date.now() })
+    }
+    notify('tasks')
+    import('@/lib/server/protocols/protocol-run-lifecycle').then(m => m.wakeProtocolRunFromTaskCompletion(taskId))
+  })
+
+  const createdTaskIds = [...(run.createdTaskIds || []), taskId]
+  return persistRun({
+    ...run,
+    status: 'waiting',
+    waitingReason: `Waiting for A2A delegation: ${config.taskName}`,
+    createdTaskIds,
+    phaseState: { ...(run.phaseState || { phaseId: phase.id }), dispatchedTaskId: taskId } as ProtocolRunPhaseState,
+    updatedAt: now(deps),
+  })
+}

package/src/lib/server/protocols/protocol-normalization.ts

@@ -171,6 +171,7 @@ function isDiscussionStepKindLocal(kind: string): boolean {
     'wait',
     'dispatch_task',
     'dispatch_delegation',
+    'a2a_delegate',
   ].includes(kind)
 }
 

package/src/lib/server/protocols/protocol-step-helpers.test.ts

@@ -48,7 +48,7 @@ describe('protocol-step-helpers', () => {
       const kinds = [
         'present', 'collect_independent_inputs', 'round_robin',
         'compare', 'decide', 'summarize', 'emit_tasks', 'wait',
-        'dispatch_task', 'dispatch_delegation',
+        'dispatch_task', 'dispatch_delegation', 'a2a_delegate',
       ]
       for (const kind of kinds) {
         const step = { id: `step-${kind}`, kind, label: kind } as never

package/src/lib/server/protocols/protocol-step-helpers.ts

@@ -58,6 +58,7 @@ export function phaseFromStep(step: ProtocolStepDefinition): ProtocolPhaseDefini
     completionCriteria: step.completionCriteria || null,
     taskConfig: step.taskConfig || null,
     delegationConfig: step.delegationConfig || null,
+    a2aDelegateConfig: step.a2aDelegateConfig || null,
   }
 }
 

package/src/lib/server/protocols/protocol-step-processors.ts

@@ -23,6 +23,7 @@ import type * as ProtocolRunLifecycle from '@/lib/server/protocols/protocol-run-
 import { processForEachStep } from '@/lib/server/protocols/protocol-foreach'
 import { processSubflowStep } from '@/lib/server/protocols/protocol-subflow'
 import { processSwarmStep } from '@/lib/server/protocols/protocol-swarm'
+import { processA2ADelegatePhase } from '@/lib/server/protocols/protocol-a2a-delegate'
 import { findRunStep } from '@/lib/server/protocols/protocol-normalization'
 import {
   appendProtocolEvent,
@@ -708,6 +709,7 @@ export async function stepProtocolRun(run: ProtocolRun, deps?: ProtocolRunDeps):
     if (phase.kind === 'emit_tasks') return processEmitTasksPhase(started, phase, deps)
     if (phase.kind === 'dispatch_task') return processDispatchTaskPhase(started, phase, deps)
     if (phase.kind === 'dispatch_delegation') return processDispatchDelegationPhase(started, phase, deps)
+    if (phase.kind === 'a2a_delegate') return processA2ADelegatePhase(started, phase, deps)
     return processWaitPhase(started, phase, deps)
   }
   if (step.kind === 'branch') return processBranchStep(run, step, deps)