Fix #815: deduplicate SessionConnector::watch() emissions with debouncing

.agents/README.md

@@ -0,0 +1,56 @@
+# Custom Agents
+
+Create specialized agent workflows that coordinate multiple AI agents to tackle complex engineering tasks. Instead of a single agent trying to handle everything, you can orchestrate teams of focused specialists that work together.
+
+## Getting Started
+
+1. **Edit an existing agent**: Start with `my-custom-agent.ts` and modify it for your needs
+2. **Test your agent**: Run `codebuff --agent your-agent-name`
+3. **Publish your agent**: Run `codebuff publish your-agent-name`
+
+## Need Help?
+
+- For detailed documentation, see [agent-guide.md](./agent-guide.md).
+- For examples, check the `examples/` directory.
+- Join our [Discord community](https://codebuff.com/discord) and ask your questions!
+
+## Context Window Management
+
+### Why Agent Workflows?
+
+Modern software projects are complex ecosystems with thousands of files, multiple frameworks, intricate dependencies, and domain-specific requirements. A single AI agent trying to understand and modify such systems faces fundamental limitations—not just in knowledge, but in the sheer volume of information it can process at once.
+
+### The Solution: Focused Context Windows
+
+Agent workflows elegantly solve this by breaking large tasks into focused sub-problems. When working with large codebases (100k+ lines), each specialist agent receives only the narrow context it needs—a security agent sees only auth code, not UI components—keeping the context for each agent manageable while ensuring comprehensive coverage.
+
+### Why Not Just Mimic Human Roles?
+
+This is about efficient AI context management, not recreating a human department. Simply creating a "frontend-developer" agent misses the point. AI agents don't have human constraints like context-switching or meetings. Their power comes from hyper-specialization, allowing them to process a narrow domain more deeply than a human could, then coordinating seamlessly with other specialists.
+
+## Agent workflows in action
+
+Here's an example of a `git-committer` agent that creates good commit messages:
+
+```typescript
+export default {
+  id: 'git-committer',
+  displayName: 'Git Committer',
+  model: 'openai/gpt-5-nano',
+  toolNames: ['read_files', 'run_terminal_command', 'end_turn'],
+
+  instructionsPrompt:
+    'You create meaningful git commits by analyzing changes, reading relevant files for context, and crafting clear commit messages that explain the "why" behind changes.',
+
+  async *handleSteps() {
+    // Analyze what changed
+    yield { tool: 'run_terminal_command', command: 'git diff' }
+    yield { tool: 'run_terminal_command', command: 'git log --oneline -5' }
+
+    // Stage files and create commit with good message
+    yield 'STEP_ALL'
+  },
+}
+```
+
+This agent systematically analyzes changes, reads relevant files for context, then creates commits with clear, meaningful messages that explain the "why" behind changes.

.agents/examples/01-basic-diff-reviewer.ts

@@ -0,0 +1,17 @@
+import type { AgentDefinition } from '../types/agent-definition'
+
+const definition: AgentDefinition = {
+  id: 'basic-diff-reviewer',
+  displayName: 'Basic Diff Reviewer',
+  model: 'anthropic/claude-4-sonnet-20250522',
+  toolNames: ['read_files', 'run_terminal_command'],
+
+  spawnerPrompt: 'Spawn when you need to review code changes in the git diff',
+
+  instructionsPrompt: `Execute the following steps:
+1. Run git diff
+2. Read the files that have changed
+3. Review the changes and suggest improvements`,
+}
+
+export default definition

.agents/examples/02-intermediate-git-committer.ts

@@ -0,0 +1,78 @@
+import type {
+  AgentDefinition,
+  AgentStepContext,
+  ToolCall,
+} from '../types/agent-definition'
+
+const definition: AgentDefinition = {
+  id: 'git-committer',
+  displayName: 'Intermediate Git Committer',
+  model: 'anthropic/claude-4-sonnet-20250522',
+  toolNames: ['read_files', 'run_terminal_command', 'add_message', 'end_turn'],
+
+  inputSchema: {
+    prompt: {
+      type: 'string',
+      description: 'What changes to commit',
+    },
+  },
+
+  spawnerPrompt:
+    'Spawn when you need to commit code changes to git with an appropriate commit message',
+
+  systemPrompt:
+    'You are an expert software developer. Your job is to create a git commit with a really good commit message.',
+
+  instructionsPrompt:
+    'Follow the steps to create a good commit: analyze changes with git diff and git log, read relevant files for context, stage appropriate files, analyze changes, and create a commit with proper formatting.',
+
+  handleSteps: function* ({ agentState, prompt, params }: AgentStepContext) {
+    // Step 1: Run git diff and git log to analyze changes.
+    yield {
+      toolName: 'run_terminal_command',
+      input: {
+        command: 'git diff',
+        process_type: 'SYNC',
+        timeout_seconds: 30,
+      },
+    } satisfies ToolCall
+
+    yield {
+      toolName: 'run_terminal_command',
+      input: {
+        command: 'git log --oneline -10',
+        process_type: 'SYNC',
+        timeout_seconds: 30,
+      },
+    } satisfies ToolCall
+
+    // Step 2: Put words in AI's mouth so it will read files next.
+    yield {
+      toolName: 'add_message',
+      input: {
+        role: 'assistant',
+        content:
+          "I've analyzed the git diff and recent commit history. Now I'll read any relevant files to better understand the context of these changes.",
+      },
+      includeToolCall: false,
+    } satisfies ToolCall
+
+    // Step 3: Let AI generate a step to decide which files to read.
+    yield 'STEP'
+
+    // Step 4: Put words in AI's mouth to analyze the changes and create a commit.
+    yield {
+      toolName: 'add_message',
+      input: {
+        role: 'assistant',
+        content:
+          "Now I'll analyze the changes and create a commit with a good commit message.",
+      },
+      includeToolCall: false,
+    } satisfies ToolCall
+
+    yield 'STEP_ALL'
+  },
+}
+
+export default definition

.agents/examples/03-advanced-file-explorer.ts

@@ -0,0 +1,73 @@
+import type { AgentDefinition, ToolCall } from '../types/agent-definition'
+
+const definition: AgentDefinition = {
+  id: 'advanced-file-explorer',
+  displayName: 'Dora the File Explorer',
+  model: 'openai/gpt-5',
+
+  spawnerPrompt:
+    'Spawns multiple file picker agents in parallel to comprehensively explore the codebase from different perspectives',
+
+  includeMessageHistory: false,
+  toolNames: ['spawn_agents', 'set_output'],
+  spawnableAgents: [`codebuff/file-picker@0.0.1`],
+
+  inputSchema: {
+    prompt: {
+      description: 'What you need to accomplish by exploring the codebase',
+      type: 'string',
+    },
+    params: {
+      type: 'object',
+      properties: {
+        prompts: {
+          description:
+            'List of 1-4 different parts of the codebase that could be useful to explore',
+          type: 'array',
+          items: {
+            type: 'string',
+          },
+        },
+      },
+      required: ['prompts'],
+      additionalProperties: false,
+    },
+  },
+  outputMode: 'structured_output',
+  outputSchema: {
+    type: 'object',
+    properties: {
+      results: {
+        type: 'string',
+        description: 'The results of the file exploration',
+      },
+    },
+    required: ['results'],
+    additionalProperties: false,
+  },
+
+  handleSteps: function* ({ prompt, params }) {
+    const prompts: string[] = params?.prompts ?? []
+    const filePickerPrompts = prompts.map(
+        (focusPrompt) =>
+          `Based on the overall goal "${prompt}", find files related to this specific area: ${focusPrompt}`,
+      ),
+      { toolResult: spawnResult } = yield {
+        toolName: 'spawn_agents',
+        input: {
+          agents: filePickerPrompts.map((promptText) => ({
+            agent_type: 'codebuff/file-picker@0.0.1',
+            prompt: promptText,
+          })),
+        },
+      } satisfies ToolCall
+    yield {
+      toolName: 'set_output',
+      input: {
+        results: spawnResult,
+      },
+    } satisfies ToolCall
+  },
+}
+
+export default definition

.agents/my-custom-agent.ts

@@ -0,0 +1,43 @@
+/*
+ *  EDIT ME to create your own agent!
+ *
+ *  Change any field below, and consult the AgentDefinition type for information on all fields and their purpose.
+ *
+ *  Run your agent with:
+ *  > codebuff --agent git-committer
+ *
+ *  Or, run codebuff normally, and use the '@' menu to mention your agent, and codebuff will spawn it for you.
+ *
+ *  Finally, you can publish your agent with 'codebuff publish your-custom-agent' so users from around the world can run it.
+ */
+
+import type { AgentDefinition } from './types/agent-definition'
+
+const definition: AgentDefinition = {
+  id: 'my-custom-agent',
+  displayName: 'My Custom Agent',
+
+  model: 'anthropic/claude-4-sonnet-20250522',
+  spawnableAgents: ['file-explorer'],
+
+  // Check out .agents/types/tools.ts for more information on the tools you can include.
+  toolNames: ['run_terminal_command', 'read_files', 'spawn_agents'],
+
+  spawnerPrompt: 'Spawn when you need to review code changes in the git diff',
+
+  instructionsPrompt: `Review the code changes and suggest improvements.
+Execute the following steps:
+1. Run git diff
+2. Spawn a file explorer to find all relevant files
+3. Read any relevant files
+4. Review the changes and suggest improvements`,
+
+  // Add more fields here to customize your agent further:
+  // - system prompt
+  // - input/output schema
+  // - handleSteps
+
+  // Check out the examples in .agents/examples for more ideas!
+}
+
+export default definition