@swarmclawai/swarmclaw 0.9.4 → 0.9.5

package/README.md

@@ -729,15 +729,15 @@ On `v*` tags, GitHub Actions will:
 2. Create a GitHub Release
 3. Build and publish Docker images to `ghcr.io/swarmclawai/swarmclaw` (`:vX.Y.Z`, `:latest`, `:sha-*`)
 
-#### v0.9.4 Release Readiness Notes
+#### v0.9.5 Release Readiness Notes
 
-Before shipping `v0.9.4`, confirm the following user-facing changes are reflected in docs:
+Before shipping `v0.9.5`, confirm the following user-facing changes are reflected in docs:
 
-1. Skills docs explain that local skills are discoverable by default, while `skillIds` now mean pinned always-on skills for an agent.
-2. Runtime-skill docs mention executable skill metadata, on-demand selection, and the `use_skill` / `manage_skills` flow instead of implying every discovered skill is inlined into the prompt.
-3. Connector/heartbeat docs mention that routable connector state is kept on direct connector sessions only, sender quiet-boundary memories are enforced before reply generation, and tool-only heartbeats no longer pollute visible main-thread history.
-4. Site and README install/version strings are updated to `v0.9.4`, including pinned install snippets, release notes index text, and sidebar/footer labels.
-5. The release tag, npm package version, and generated GitHub release install snippet all agree on the non-prefixed npm version (`0.9.4`) versus the git tag (`v0.9.4`).
+1. Plugin/runtime docs mention the new typed lifecycle hooks: `beforePromptBuild`, `beforeToolCall`, `beforeModelResolve`, `llmInput`, `llmOutput`, `toolResultPersist`, `beforeMessageWrite`, plus session and subagent lifecycle hooks.
+2. Connector/memory docs explain that quiet-boundary memories are matched by identifiers and agent aliases, with explicit boundary metadata support, rather than relying on hardcoded person-name fallbacks.
+3. Skills docs still explain that local skills are discoverable by default, pinned skills stay always-on, and `use_skill` is the runtime path for selection/loading/dispatch.
+4. Site and README install/version strings are updated to `v0.9.5`, including release notes index text and any pinned install snippets.
+5. The release tag, npm package version, and generated GitHub release install snippet all agree on the non-prefixed npm version (`0.9.5`) versus the git tag (`v0.9.5`).
 
 ## CLI
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "0.9.4",
+  "version": "0.9.5",
   "description": "Self-hosted AI agent orchestration dashboard — manage LLM providers, orchestrate agent swarms, schedule tasks, and bridge agents to chat platforms.",
   "license": "MIT",
   "publishConfig": {

package/src/lib/server/agents/subagent-runtime.test.ts

@@ -15,6 +15,10 @@ let runtime: typeof import('@/lib/server/agents/subagent-runtime')
 let lineage: typeof import('@/lib/server/agents/subagent-lineage')
 let delegationJobs: typeof import('@/lib/server/agents/delegation-jobs')
 let storage: typeof import('@/lib/server/storage')
+let pluginManager: {
+  registerBuiltin: (id: string, plugin: Record<string, unknown>) => void
+}
+let providers: Record<string, unknown>
 
 before(async () => {
   tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-subagent-runtime-'))
@@ -26,6 +30,9 @@ before(async () => {
   delegationJobs = await import('@/lib/server/agents/delegation-jobs')
   lineage = await import('@/lib/server/agents/subagent-lineage')
   runtime = await import('@/lib/server/agents/subagent-runtime')
+  pluginManager = (await import('@/lib/server/plugins')).getPluginManager()
+  const providersMod = await import('@/lib/providers/index')
+  providers = providersMod.PROVIDERS
 })
 
 after(() => {
@@ -57,9 +64,9 @@ describe('subagent-runtime', () => {
   })
 
   describe('spawnSubagent', () => {
-    it('throws for unknown agent', () => {
+    it('throws for unknown agent', async () => {
       lineage._clearLineage()
-      assert.throws(
+      await assert.rejects(
         () => runtime.spawnSubagent(
           { agentId: 'nonexistent', message: 'hello' },
           { cwd: tempDir },
@@ -68,7 +75,7 @@ describe('subagent-runtime', () => {
       )
     })
 
-    it('throws when max depth is exceeded', () => {
+    it('throws when max depth is exceeded', async () => {
       lineage._clearLineage()
       seedAgent('depth-agent', 'Depth Agent')
 
@@ -80,7 +87,7 @@ describe('subagent-runtime', () => {
       sessions['depth-s3'] = { id: 'depth-s3', parentSessionId: 'depth-s2', cwd: tempDir }
       storage.saveSessions(sessions)
 
-      assert.throws(
+      await assert.rejects(
         () => runtime.spawnSubagent(
           { agentId: 'depth-agent', message: 'too deep' },
           { sessionId: 'depth-s3', cwd: tempDir },
@@ -89,13 +96,13 @@ describe('subagent-runtime', () => {
       )
     })
 
-    it('creates session, lineage node, and delegation job', () => {
+    it('creates session, lineage node, and delegation job', async () => {
       lineage._clearLineage()
       seedAgent('spawn-agent', 'Spawn Agent')
 
-      let handle: ReturnType<typeof runtime.spawnSubagent> | null = null
+      let handle: Awaited<ReturnType<typeof runtime.spawnSubagent>> | null = null
       try {
-        handle = runtime.spawnSubagent(
+        handle = await runtime.spawnSubagent(
           { agentId: 'spawn-agent', message: 'test task', waitForCompletion: false },
           { sessionId: undefined, cwd: tempDir },
         )
@@ -132,7 +139,7 @@ describe('subagent-runtime', () => {
       }
     })
 
-    it('tracks parent-child lineage correctly', () => {
+    it('tracks parent-child lineage correctly', async () => {
       lineage._clearLineage()
       seedAgent('parent-agent', 'Parent')
       seedAgent('child-agent', 'Child')
@@ -155,9 +162,9 @@ describe('subagent-runtime', () => {
         task: 'Parent task',
       })
 
-      let handle: ReturnType<typeof runtime.spawnSubagent> | null = null
+      let handle: Awaited<ReturnType<typeof runtime.spawnSubagent>> | null = null
       try {
-        handle = runtime.spawnSubagent(
+        handle = await runtime.spawnSubagent(
           { agentId: 'child-agent', message: 'child task', waitForCompletion: false },
           { sessionId: 'parent-session', cwd: tempDir },
         )
@@ -184,6 +191,82 @@ describe('subagent-runtime', () => {
         assert.equal(ancestors[0].sessionId, 'parent-session')
       }
     })
+
+    it('fires subagent lifecycle hooks through the native runtime', async () => {
+      lineage._clearLineage()
+      seedAgent('parent-hook-agent', 'Parent Hook Agent', ['subagent_lifecycle_test'])
+      seedAgent('child-hook-agent', 'Child Hook Agent')
+
+      const marks: string[] = []
+      pluginManager.registerBuiltin('subagent_lifecycle_test', {
+        name: 'Subagent Lifecycle Test',
+        hooks: {
+          subagentSpawning: ({ agentId }) => {
+            marks.push(`spawning:${agentId}`)
+            return { status: 'ok' }
+          },
+          subagentSpawned: ({ childSessionId }) => {
+            marks.push(`spawned:${childSessionId}`)
+          },
+          subagentEnded: ({ status }) => {
+            marks.push(`ended:${status}`)
+          },
+          sessionEnd: ({ reason }) => {
+            marks.push(`session_end:${reason}`)
+          },
+        },
+      })
+
+      providers['subagent-test-provider'] = {
+        id: 'subagent-test-provider',
+        name: 'Subagent Test Provider',
+        models: ['unit'],
+        requiresApiKey: false,
+        requiresEndpoint: false,
+        handler: {
+          async streamChat() {
+            return 'subagent finished'
+          },
+        },
+      }
+
+      const agents = storage.loadAgents()
+      agents['child-hook-agent'] = {
+        id: 'child-hook-agent',
+        name: 'Child Hook Agent',
+        provider: 'subagent-test-provider',
+        model: 'unit',
+        systemPrompt: 'Child runtime test',
+      }
+      storage.saveAgents(agents)
+
+      const sessions = storage.loadSessions()
+      sessions['hook-parent-session'] = {
+        id: 'hook-parent-session',
+        cwd: tempDir,
+        parentSessionId: null,
+        agentId: 'parent-hook-agent',
+        provider: 'subagent-test-provider',
+        model: 'unit',
+        plugins: ['subagent_lifecycle_test'],
+        messages: [],
+        createdAt: Date.now(),
+        lastActiveAt: Date.now(),
+      }
+      storage.saveSessions(sessions)
+
+      const handle = await runtime.spawnSubagent(
+        { agentId: 'child-hook-agent', message: 'finish the task', waitForCompletion: false },
+        { sessionId: 'hook-parent-session', cwd: tempDir },
+      )
+      const result = await handle.promise
+
+      assert.equal(result.status, 'completed')
+      assert.equal(marks.includes('spawning:child-hook-agent'), true)
+      assert.equal(marks.some((mark) => mark.startsWith('spawned:')), true)
+      assert.equal(marks.includes('ended:completed'), true)
+      assert.equal(marks.includes('session_end:completed'), true)
+    })
   })
 
   describe('mergePlugins', () => {
@@ -230,7 +313,7 @@ describe('subagent-runtime', () => {
   })
 
   describe('plugin inheritance in spawnSubagent', () => {
-    it('child session inherits parent plugins merged with agent plugins', () => {
+    it('child session inherits parent plugins merged with agent plugins', async () => {
       lineage._clearLineage()
       seedAgent('inherit-agent', 'Inherit Agent', ['shell', 'memory'])
 
@@ -244,9 +327,9 @@ describe('subagent-runtime', () => {
       }
       storage.saveSessions(sessions)
 
-      let handle: ReturnType<typeof runtime.spawnSubagent> | null = null
+      let handle: Awaited<ReturnType<typeof runtime.spawnSubagent>> | null = null
       try {
-        handle = runtime.spawnSubagent(
+        handle = await runtime.spawnSubagent(
           { agentId: 'inherit-agent', message: 'test inheritance', waitForCompletion: false },
           { sessionId: 'inherit-parent', cwd: tempDir },
         )
@@ -265,7 +348,7 @@ describe('subagent-runtime', () => {
       }
     })
 
-    it('child session does not inherit when inheritPlugins is false', () => {
+    it('child session does not inherit when inheritPlugins is false', async () => {
       lineage._clearLineage()
       seedAgent('no-inherit-agent', 'No Inherit Agent', ['shell'])
 
@@ -278,9 +361,9 @@ describe('subagent-runtime', () => {
       }
       storage.saveSessions(sessions)
 
-      let handle: ReturnType<typeof runtime.spawnSubagent> | null = null
+      let handle: Awaited<ReturnType<typeof runtime.spawnSubagent>> | null = null
       try {
-        handle = runtime.spawnSubagent(
+        handle = await runtime.spawnSubagent(
           { agentId: 'no-inherit-agent', message: 'no inherit', inheritPlugins: false, waitForCompletion: false },
           { sessionId: 'no-inherit-parent', cwd: tempDir },
         )

package/src/lib/server/agents/subagent-runtime.ts

@@ -13,6 +13,7 @@ import { enqueueSessionRun, type EnqueueSessionRunResult } from '@/lib/server/ru
 import { loadRuntimeSettings } from '@/lib/server/runtime/runtime-settings'
 import { applyResolvedRoute, resolvePrimaryAgentRoute } from '@/lib/server/agents/agent-runtime-config'
 import { resolveSubagentBrowserProfileId } from '@/lib/server/session-tools/subagent'
+import { getPluginManager } from '@/lib/server/plugins'
 import {
   appendDelegationCheckpoint,
   completeDelegationJob,
@@ -179,7 +180,14 @@ export function getSessionDepth(
 export function spawnSubagent(
   input: SpawnSubagentInput,
   context: SubagentContext,
-): SubagentHandle {
+): Promise<SubagentHandle> {
+  return spawnSubagentImpl(input, context)
+}
+
+async function spawnSubagentImpl(
+  input: SpawnSubagentInput,
+  context: SubagentContext,
+): Promise<SubagentHandle> {
   const runtime = loadRuntimeSettings()
   const maxDepth = runtime.delegationMaxDepth || DEFAULT_DELEGATION_MAX_DEPTH
   const agents = loadAgents()
@@ -195,6 +203,28 @@ export function spawnSubagent(
   if (depth >= maxDepth) {
     throw new Error(`Max subagent depth (${maxDepth}) reached.`)
   }
+  const parent = context.sessionId ? sessions[context.sessionId] : null
+  const parentPlugins = (
+    Array.isArray(parent?.plugins) ? parent.plugins
+    : Array.isArray(parent?.tools) ? parent.tools
+    : []
+  ) as string[]
+  const pluginManager = getPluginManager()
+  const spawningResult = await pluginManager.runSubagentSpawning(
+    {
+      parentSessionId: context.sessionId || null,
+      agentId: input.agentId,
+      agentName: agent.name,
+      message: input.message,
+      cwd: input.cwd || context.cwd,
+      mode: 'run',
+      threadRequested: false,
+    },
+    { enabledIds: parentPlugins },
+  )
+  if (spawningResult.status === 'error') {
+    throw new Error(spawningResult.error || 'Subagent spawn blocked by plugin hook')
+  }
 
   // 1. Create delegation job
   const job = createDelegationJob({
@@ -209,7 +239,6 @@ export function spawnSubagent(
   // 2. Create child session
   const sid = genId()
   const now = Date.now()
-  const parent = context.sessionId ? sessions[context.sessionId] : null
   const browserProfileId = resolveSubagentBrowserProfileId(
     parent,
     sid,
@@ -276,6 +305,19 @@ export function spawnSubagent(
     mode: 'followup',
     executionGroupKey: input.executionGroupKey,
   })
+  await pluginManager.runHook(
+    'subagentSpawned',
+    {
+      parentSessionId: context.sessionId || null,
+      childSessionId: sid,
+      agentId: agent.id,
+      agentName: agent.name,
+      runId: run.runId,
+      mode: 'run',
+      threadRequested: false,
+    },
+    { enabledIds: parentPlugins },
+  )
 
   // 8. Register runtime handle for cancellation
   registerDelegationRuntime(job.id, {
@@ -290,33 +332,87 @@ export function spawnSubagent(
 
   // 9. Build result promise
   const resultPromise = run.promise
-    .then((result): SubagentResult => {
+    .then(async (result): Promise<SubagentResult> => {
       const latest = getDelegationJob(job.id)
       const node = getLineageNode(lineageNode.id)
+      let subagentResult: SubagentResult
       if (latest?.status === 'cancelled' || node?.status === 'cancelled') {
-        return buildResult(job.id, sid, lineageNode, agent, 'cancelled', null, null)
+        subagentResult = buildResult(job.id, sid, lineageNode, agent, 'cancelled', null, null)
+      } else {
+        const responseText = (result.text || '').slice(0, 32_000)
+        completeLineageNode(lineageNode.id, responseText.slice(0, 1000))
+        appendDelegationCheckpoint(job.id, 'Child session completed', 'completed')
+        completeDelegationJob(job.id, responseText, { childSessionId: sid })
+
+        subagentResult = buildResult(job.id, sid, lineageNode, agent, 'completed', responseText, null)
       }
-
-      const responseText = (result.text || '').slice(0, 32_000)
-      completeLineageNode(lineageNode.id, responseText.slice(0, 1000))
-      appendDelegationCheckpoint(job.id, 'Child session completed', 'completed')
-      completeDelegationJob(job.id, responseText, { childSessionId: sid })
-
-      return buildResult(job.id, sid, lineageNode, agent, 'completed', responseText, null)
+      await pluginManager.runHook(
+        'subagentEnded',
+        {
+          parentSessionId: context.sessionId || null,
+          childSessionId: sid,
+          agentId: agent.id,
+          agentName: agent.name,
+          status: subagentResult.status,
+          response: subagentResult.response,
+          error: subagentResult.error,
+          durationMs: subagentResult.durationMs,
+        },
+        { enabledIds: parentPlugins },
+      )
+      await pluginManager.runHook(
+        'sessionEnd',
+        {
+          sessionId: sid,
+          session: loadSessions()[sid] || null,
+          messageCount: Array.isArray(loadSessions()[sid]?.messages) ? loadSessions()[sid].messages.length : 0,
+          durationMs: subagentResult.durationMs,
+          reason: subagentResult.status,
+        },
+        { enabledIds: parentPlugins },
+      )
+      return subagentResult
     })
-    .catch((err: unknown): SubagentResult => {
+    .catch(async (err: unknown): Promise<SubagentResult> => {
       const message = errorMessage(err)
       const latest = getDelegationJob(job.id)
       const node = getLineageNode(lineageNode.id)
+      let subagentResult: SubagentResult
       if (latest?.status === 'cancelled' || node?.status === 'cancelled') {
-        return buildResult(job.id, sid, lineageNode, agent, 'cancelled', null, null)
-      }
+        subagentResult = buildResult(job.id, sid, lineageNode, agent, 'cancelled', null, null)
+      } else {
+        failLineageNode(lineageNode.id, message)
+        appendDelegationCheckpoint(job.id, `Child session failed: ${message}`, 'failed')
+        failDelegationJob(job.id, message, { childSessionId: sid })
 
-      failLineageNode(lineageNode.id, message)
-      appendDelegationCheckpoint(job.id, `Child session failed: ${message}`, 'failed')
-      failDelegationJob(job.id, message, { childSessionId: sid })
-
-      return buildResult(job.id, sid, lineageNode, agent, 'failed', null, message)
+        subagentResult = buildResult(job.id, sid, lineageNode, agent, 'failed', null, message)
+      }
+      await pluginManager.runHook(
+        'subagentEnded',
+        {
+          parentSessionId: context.sessionId || null,
+          childSessionId: sid,
+          agentId: agent.id,
+          agentName: agent.name,
+          status: subagentResult.status,
+          response: subagentResult.response,
+          error: subagentResult.error,
+          durationMs: subagentResult.durationMs,
+        },
+        { enabledIds: parentPlugins },
+      )
+      await pluginManager.runHook(
+        'sessionEnd',
+        {
+          sessionId: sid,
+          session: loadSessions()[sid] || null,
+          messageCount: Array.isArray(loadSessions()[sid]?.messages) ? loadSessions()[sid].messages.length : 0,
+          durationMs: subagentResult.durationMs,
+          reason: subagentResult.status,
+        },
+        { enabledIds: parentPlugins },
+      )
+      return subagentResult
     })
 
   const handle: SubagentHandle = {

package/src/lib/server/agents/subagent-swarm.ts

@@ -169,10 +169,10 @@ function notifySwarmChanged() {
  *
  *   const aggregate = await swarm.allSettled
  */
-export function spawnSwarm(
+export async function spawnSwarm(
   input: BatchSpawnInput,
   context: SubagentContext,
-): SwarmHandle {
+): Promise<SwarmHandle> {
   const swarmId = genId(10)
   const createdAt = Date.now()
   const members: SwarmMember[] = []
@@ -190,7 +190,7 @@ export function spawnSwarm(
   for (let i = 0; i < input.tasks.length; i++) {
     const task = input.tasks[i]
     try {
-      const handle = spawnSubagent(
+      const handle = await spawnSubagent(
         {
           agentId: task.agentId,
           message: task.message,

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

@@ -230,3 +230,115 @@ test('executeSessionChatTurn keeps tool-only heartbeats off the visible main-thr
   assert.equal(output.lastMessageText, 'seed user message')
   assert.equal(output.heartbeatKinds, 0)
 })
+
+test('executeSessionChatTurn applies lifecycle hooks for model resolution and message persistence', () => {
+  const output = runWithTempDataDir(`
+    const storageMod = await import('@/lib/server/storage')
+    const providersMod = await import('@/lib/providers/index')
+    const pluginsMod = await import('@/lib/server/plugins')
+    const execMod = await import('@/lib/server/chat-execution/chat-execution')
+    const storage = storageMod.default || storageMod['module.exports'] || storageMod
+    const executeSessionChatTurn = execMod.executeSessionChatTurn
+      || execMod.default?.executeSessionChatTurn
+      || execMod['module.exports']?.executeSessionChatTurn
+    const providers = providersMod.PROVIDERS
+      || providersMod.default?.PROVIDERS
+      || providersMod['module.exports']?.PROVIDERS
+    const pluginManager = pluginsMod.getPluginManager
+      ? pluginsMod.getPluginManager()
+      : pluginsMod.default?.getPluginManager?.()
+
+    const lifecycleMarks = []
+    pluginManager.registerBuiltin('lifecycle_hooks_test', {
+      name: 'Lifecycle Hooks Test',
+      hooks: {
+        beforeModelResolve: () => ({
+          providerOverride: 'claude-cli',
+          modelOverride: 'resolved-model',
+        }),
+        beforeMessageWrite: ({ message, phase }) => {
+          lifecycleMarks.push(phase || 'unknown')
+          return {
+            message: {
+              ...message,
+              text: message.role === 'assistant' ? message.text + ' [stored]' : message.text,
+            },
+          }
+        },
+        sessionStart: () => {
+          lifecycleMarks.push('session_start')
+        },
+      },
+    })
+
+    providers['claude-cli'] = {
+      id: 'claude-cli',
+      name: 'Resolved Provider',
+      models: ['resolved-model'],
+      requiresApiKey: false,
+      requiresEndpoint: false,
+      handler: {
+        async streamChat(opts) {
+          lifecycleMarks.push('provider:' + opts.session.provider + ':' + opts.session.model)
+          return 'resolved response'
+        },
+      },
+    }
+
+    const now = Date.now()
+    storage.saveAgents({
+      lifecycle: {
+        id: 'lifecycle',
+        name: 'Lifecycle Agent',
+        description: 'Lifecycle hook integration test',
+        provider: 'openai',
+        model: 'seed-model',
+        credentialId: null,
+        apiEndpoint: null,
+        fallbackCredentialIds: [],
+        disabled: false,
+        heartbeatEnabled: false,
+        heartbeatIntervalSec: null,
+        plugins: ['lifecycle_hooks_test'],
+        createdAt: now,
+        updatedAt: now,
+      },
+    })
+    storage.saveSessions({
+      lifecycle_session: {
+        id: 'lifecycle_session',
+        name: 'Lifecycle Session',
+        cwd: process.env.WORKSPACE_DIR,
+        user: 'default',
+        provider: 'openai',
+        model: 'seed-model',
+        claudeSessionId: null,
+        messages: [],
+        createdAt: now,
+        lastActiveAt: now,
+        sessionType: 'human',
+        agentId: 'lifecycle',
+        plugins: ['lifecycle_hooks_test'],
+      },
+    })
+
+    await executeSessionChatTurn({
+      sessionId: 'lifecycle_session',
+      message: 'hello lifecycle',
+      runId: 'run-lifecycle-hooks',
+    })
+
+    const persisted = storage.loadSession('lifecycle_session')
+    console.log(JSON.stringify({
+      lastMessageText: persisted?.messages?.at(-1)?.text || null,
+      marks: lifecycleMarks,
+    }))
+  `)
+
+  assert.equal(output.lastMessageText.startsWith('resolved response'), true)
+  assert.equal(output.lastMessageText.endsWith('[stored]'), true)
+  assert.equal(output.marks.includes('session_start'), true)
+  assert.equal(output.marks.includes('provider:claude-cli:resolved-model'), true)
+  assert.equal(output.marks.includes('user'), true)
+  assert.equal(output.marks.includes('assistant_final'), true)
+})