@fatagnus/codebuff 1.0.3 → 1.0.4

package/README.md

@@ -347,6 +347,49 @@ export async function multiTurnConversation(
 }
 ```
 
+### Subagent Spawning in Convex
+
+The Convex runtime supports spawning subagents using the `spawn_agents` tool. To use this feature:
+
+1. Define your agents with `spawnableAgents` arrays
+2. Include all agent definitions in `agentDefinitions`
+
+```typescript
+import { ConvexCodebuffClient } from '@fatagnus/codebuff/convex'
+import type { AgentDefinition } from '@fatagnus/codebuff/convex'
+
+const helperAgent: AgentDefinition = {
+  id: 'helper',
+  displayName: 'Helper Agent',
+  systemPrompt: 'You are a helpful assistant that answers questions.',
+  toolNames: ['read_files', 'end_turn'],
+}
+
+const orchestratorAgent: AgentDefinition = {
+  id: 'orchestrator',
+  displayName: 'Orchestrator',
+  systemPrompt: 'You coordinate tasks by spawning helper agents.',
+  toolNames: ['spawn_agents', 'read_files', 'end_turn'],
+  spawnableAgents: ['helper'], // Can spawn the helper agent
+}
+
+const client = new ConvexCodebuffClient({
+  apiKey,
+  projectFiles: myFiles,
+  agentDefinitions: [helperAgent, orchestratorAgent],
+})
+
+const result = await client.run({
+  agent: orchestratorAgent,
+  prompt: 'Analyze this codebase by spawning helpers for each file.',
+})
+```
+
+**Subagent limitations in Convex:**
+- Maximum nesting depth of 5 levels
+- Subagents can only be spawned from `agentDefinitions` (no database lookups)
+- Subagents run in parallel using `Promise.allSettled`
+
 ### Convex Limitations
 
 When running in Convex, the following tools are **not available** (they will throw `ConvexUnsupportedToolError`):
@@ -385,7 +428,7 @@ const client = new ConvexCodebuffClient({
 - **`agentDefinitions`** (array, optional): Custom agent definitions
 - **`maxAgentSteps`** (number, optional): Max steps before stopping (recommended: 10-20 for Convex timeout limits)
 - **`handleEvent`** (function, optional): Event callback for streaming
-- **`handleStreamChunk`** (function, optional): Chunk callback for real-time updates
+- **`handleStreamChunk`** (function, optional): Chunk callback for real-time updates. Receives text chunks and subagent events (`subagent_start`, `subagent_chunk`, `subagent_finish`)
 - **`overrideTools`** (object, optional): Custom tool implementations
 - **`customToolDefinitions`** (array, optional): Custom tool definitions