@poolzin/pool-bot 2026.3.11 → 2026.3.14

package/docs/refactor/plugin-development-guide.md

@@ -0,0 +1,281 @@
+# Plugin Development Guide
+
+Complete guide for creating PoolBot plugins using the template scaffold.
+
+## Quick Start
+
+### 1. Create from Template
+
+Copy the template to a new plugin directory:
+
+```bash
+cp -r extensions/template extensions/my-plugin
+cd extensions/my-plugin
+```
+
+### 2. Update Package Info
+
+Edit `package.json`:
+
+```json
+{
+  "name": "@poolzin/my-plugin",
+  "version": "2026.3.12",
+  "description": "My custom PoolBot plugin"
+}
+```
+
+### 3. Update Plugin Manifest
+
+Edit `poolbot.plugin.json`:
+
+```json
+{
+  "id": "my-plugin",
+  "name": "My Plugin",
+  "description": "What my plugin does.",
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "apiKey": {
+        "type": "string",
+        "description": "API key for external service"
+      }
+    }
+  }
+}
+```
+
+### 4. Implement Plugin
+
+Edit `index.ts`:
+
+```typescript
+import type { PoolBotPluginApi } from "../../src/plugins/types.js";
+import type { AgentToolResult } from "@mariozechner/pi-agent-core";
+
+export default function register(api: PoolBotPluginApi) {
+  // Register tools, providers, channels, or hooks
+  api.registerTool({
+    label: "My Tool",
+    name: "my_tool",
+    description: "Does something useful",
+    parameters: {
+      type: "object",
+      properties: {
+        input: { type: "string" }
+      },
+      required: ["input"]
+    },
+    async execute(_toolCallId, params): Promise<AgentToolResult<unknown>> {
+      const { input } = params as { input: string };
+      return {
+        content: [{ type: "text", text: `Processed: ${input}` }],
+        details: { input }
+      };
+    }
+  });
+}
+```
+
+### 5. Test Locally
+
+```bash
+# Build
+pnpm build
+
+# Lint
+pnpm lint
+
+# Run PoolBot with plugin
+pnpm dev
+```
+
+### 6. Publish (Optional)
+
+```bash
+cd extensions/my-plugin
+npm publish --access public
+```
+
+## Plugin Structure
+
+```
+extensions/my-plugin/
+├── package.json          # npm manifest
+├── poolbot.plugin.json   # Plugin manifest (required)
+├── index.ts              # Entry point (root level)
+└── README.md             # Documentation
+```
+
+## Extension Types
+
+### Tools
+
+Add capabilities that agents can use:
+
+```typescript
+api.registerTool({
+  label: "Weather",
+  name: "weather_lookup",
+  description: "Get current weather for a location",
+  parameters: {
+    type: "object",
+    properties: {
+      city: { type: "string" }
+    },
+    required: ["city"]
+  },
+  async execute(_toolCallId, params): Promise<AgentToolResult<unknown>> {
+    const { city } = params as { city: string };
+    // Call weather API
+    return {
+      content: [{ type: "text", text: `Weather in ${city}: ...` }],
+      details: { city, temperature: 72 }
+    };
+  }
+});
+```
+
+### Providers
+
+Add custom LLM model providers:
+
+```typescript
+api.registerProvider({
+  id: "my-provider",
+  name: "My Provider",
+  // ... provider config
+});
+```
+
+### Channels
+
+Add messaging channel integrations:
+
+```typescript
+api.registerChannel({
+  id: "my-channel",
+  name: "My Channel",
+  // ... channel implementation
+});
+```
+
+### Hooks
+
+Intercept lifecycle events:
+
+```typescript
+api.on("before_model_resolve", async (ctx) => {
+  // Modify context before model selection
+});
+```
+
+## Configuration Schema
+
+The `configSchema` in `poolbot.plugin.json` defines user-configurable settings:
+
+```json
+{
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "apiKey": {
+        "type": "string",
+        "description": "API authentication key"
+      },
+      "endpoint": {
+        "type": "string",
+        "default": "https://api.example.com",
+        "description": "API endpoint URL"
+      },
+      "timeout": {
+        "type": "number",
+        "default": 5000,
+        "description": "Request timeout in milliseconds"
+      }
+    },
+    "required": ["apiKey"]
+  }
+}
+```
+
+Access config in your plugin:
+
+```typescript
+export default function register(api: PoolBotPluginApi) {
+  const config = api.pluginConfig as { apiKey: string; endpoint?: string };
+  const endpoint = config.endpoint ?? "https://api.example.com";
+  // Use config.apiKey...
+}
+```
+
+## Testing Your Plugin
+
+### Local Testing
+
+1. Place plugin in `extensions/my-plugin/`
+2. Ensure `poolbot.extensions` in root `package.json` includes the path
+3. Run `pnpm build` and `pnpm dev`
+4. Test with `poolbot doctor` to verify loading
+
+### Test Plugin Available
+
+Use the published test plugin as a reference:
+
+```bash
+npm install @poolzin/test-plugin
+```
+
+This plugin provides:
+- `test_echo` - Echo tool for validation
+- `test_validate` - Plugin status checker
+
+## Troubleshooting
+
+### "plugin manifest not found"
+
+- Check if `poolbot.plugin.json` exists in plugin root
+- Verify JSON is valid
+
+### "extension entry escapes package directory"
+
+- Entry point in `package.json` must use relative path: `"./index.ts"`
+- File must be inside plugin directory
+
+### TypeScript Errors
+
+- Use `import type { PoolBotPluginApi } from "../../src/plugins/types.js"`
+- Note the capital `B` in `PoolBotPluginApi`
+- Tool `label` property is required
+- Tool `execute` must return `Promise<AgentToolResult<unknown>>`
+
+### Tool Not Appearing
+
+- Verify tool has `label`, `name`, `description`, `parameters`, and `execute`
+- Check that `parameters` follows JSON Schema format
+- Ensure `execute` returns correct `AgentToolResult` structure
+
+## Best Practices
+
+1. **Use TypeScript** - Full type safety for better DX
+2. **Add Labels** - Every tool needs a `label` for display
+3. **Validate Input** - Check parameters before processing
+4. **Return Proper Results** - Use `AgentToolResult` structure
+5. **Document Config** - Describe all config options in schema
+6. **Handle Errors** - Throw descriptive errors for invalid input
+7. **Test Thoroughly** - Test with `poolbot doctor` before publishing
+
+## Examples
+
+See working examples in the repository:
+
+- `extensions/template/` - Minimal starter template
+- `extensions/test-plugin/` - Working example with tools
+- `extensions/lobster/` - Complex plugin with multiple features
+- `extensions/llm-task/` - Provider plugin example
+
+## References
+
+- [Plugin SDK Documentation](plugin-sdk.md)
+- [Test Plugin on npm](https://www.npmjs.com/package/@poolzin/test-plugin)

package/extensions/agency-agents/README.md

@@ -0,0 +1,301 @@
+# Agency Agents Extension for PoolBot
+
+AI specialist agents for software engineering tasks. Register domain-specific agents (Frontend, Backend, DevOps, etc.) and orchestrate complex multi-agent workflows with collaboration, messaging, and review capabilities.
+
+## Features
+
+- **Specialist Agents**: Pre-configured agents for different engineering domains
+- **Task Management**: Create, assign, and track tasks with dependencies
+- **Multi-Agent Collaboration**: Form teams with lead agents and participants
+- **Workflow Orchestration**: Define step-by-step workflows with dependencies
+- **Agent Messaging**: Inter-agent communication for coordination
+- **Code Review**: Structured review process with approval workflows
+- **System Prompts**: Auto-generated prompts for LLM integration
+
+## Installation
+
+```bash
+# Install as PoolBot extension
+poolbot extension install @poolbot/agency-agents
+
+# Or manual installation
+cd extensions/agency-agents
+pnpm install
+pnpm build
+```
+
+## Configuration
+
+```json
+{
+  "agencyAgents": {
+    "agents": [
+      {
+        "name": "FrontendDev",
+        "description": "Frontend development specialist",
+        "category": "engineering",
+        "color": "#3b82f6",
+        "content": "Expert in React, Vue, and modern CSS...",
+        "capabilities": ["react", "vue", "css", "typescript"],
+        "tools": ["code_editor", "browser", "git"]
+      },
+      {
+        "name": "BackendDev",
+        "description": "Backend development specialist",
+        "category": "engineering",
+        "color": "#10b981",
+        "content": "Expert in Node.js, Python, and databases...",
+        "capabilities": ["nodejs", "python", "postgresql", "redis"],
+        "tools": ["code_editor", "database", "api_tester"]
+      }
+    ]
+  }
+}
+```
+
+## Usage
+
+### Initialize Service
+
+```typescript
+import { AgencyAgentsService } from '@poolbot/agency-agents'
+
+const service = new AgencyAgentsService(config)
+```
+
+### Register Agents
+
+```typescript
+service.registerAgent({
+  name: 'DevOpsEngineer',
+  description: 'DevOps and infrastructure specialist',
+  category: 'engineering',
+  color: '#f59e0b',
+  content: 'Expert in Docker, Kubernetes, and CI/CD...',
+  capabilities: ['docker', 'kubernetes', 'terraform', 'aws'],
+  tools: ['terminal', 'docker', 'kubectl']
+})
+```
+
+### Task Management
+
+```typescript
+// Create a task
+const task = service.createTask(
+  'FrontendDev',
+  'Build login page component',
+  'Create a responsive login form with email and password fields'
+)
+
+// Update task status
+service.updateTaskStatus(task.id, 'in_progress')
+service.updateTaskStatus(task.id, 'completed', 'Login component built successfully')
+
+// Get task details
+const taskDetails = service.getTask(task.id)
+
+// List all tasks
+const allTasks = service.listTasks()
+
+// Filter by agent or status
+const frontendTasks = service.listTasks('FrontendDev')
+const pendingTasks = service.listTasks(undefined, 'pending')
+```
+
+### Agent Collaboration
+
+```typescript
+// Create a collaboration
+const collab = service.createCollaboration(
+  'E-commerce Feature',
+  'Build shopping cart functionality',
+  'FrontendDev',
+  ['BackendDev', 'UXDesigner']
+)
+
+// Add tasks to collaboration
+const task1 = service.createTask('FrontendDev', 'Build cart UI', undefined, collab.id)
+const task2 = service.createTask('BackendDev', 'Build cart API', undefined, collab.id)
+
+// Update collaboration status
+service.updateCollaborationStatus(collab.id, 'active')
+
+// List collaborations
+const activeCollabs = service.listCollaborations('active')
+```
+
+### Agent Messaging
+
+```typescript
+// Send message between agents
+service.sendMessage(
+  'FrontendDev',
+  'BackendDev',
+  collab.id,
+  'What is the API endpoint for adding items to cart?',
+  'request'
+)
+
+// Get messages for collaboration
+const messages = service.getMessagesForCollaboration(collab.id)
+```
+
+### Code Review
+
+```typescript
+// Create a review
+service.createReview(
+  task.id,
+  'SeniorDev',
+  'FrontendDev',
+  'Code looks good but needs error handling',
+  'changes_requested',
+  ['Add try-catch block', 'Validate input parameters']
+)
+
+// Approve review
+service.approveReview(review.id)
+
+// Get reviews for task
+const reviews = service.getReviewsForTask(task.id)
+```
+
+### Workflow Orchestration
+
+```typescript
+// Create a workflow
+const workflow = service.createWorkflow(
+  'Feature Development',
+  'Complete feature development workflow',
+  'engineering'
+)
+
+// Add steps
+const step1 = service.addWorkflowStep(
+  workflow.id,
+  'Design API',
+  'Design the API endpoints',
+  'BackendDev',
+  'Create OpenAPI spec',
+  []
+)
+
+const step2 = service.addWorkflowStep(
+  workflow.id,
+  'Implement API',
+  'Build the backend API',
+  'BackendDev',
+  'Implement endpoints',
+  [step1.id]
+)
+
+// Execute workflow
+await service.executeWorkflow(workflow.id)
+```
+
+### System Prompt Generation
+
+```typescript
+// Generate system prompt for agent
+const prompt = service.generateSystemPrompt('FrontendDev')
+console.log(prompt)
+// Output: "You are FrontendDev, a Frontend development specialist..."
+```
+
+## Data Types
+
+### AgencyAgent
+
+```typescript
+interface AgencyAgent {
+  name: string
+  description: string
+  color?: string
+  category: string
+  content: string
+  capabilities: string[]
+  tools?: string[]
+}
+```
+
+### AgentTask
+
+```typescript
+interface AgentTask {
+  id: string
+  agentName: string
+  task: string
+  context?: string
+  status: 'pending' | 'in_progress' | 'completed' | 'failed' | 'reviewing'
+  output?: string
+  createdAt: Date
+  updatedAt: Date
+  parentTaskId?: string
+  subtasks?: string[]
+  dependencies?: string[]
+}
+```
+
+### AgentCollaboration
+
+```typescript
+interface AgentCollaboration {
+  id: string
+  name: string
+  description: string
+  leadAgent: string
+  participatingAgents: string[]
+  tasks: AgentTask[]
+  status: 'planning' | 'active' | 'completed' | 'paused'
+  createdAt: Date
+  updatedAt: Date
+}
+```
+
+## Testing
+
+```bash
+# Run all tests
+pnpm test
+
+# Watch mode
+pnpm test:watch
+
+# Coverage
+pnpm test:coverage
+```
+
+## API Reference
+
+### AgencyAgentsService
+
+| Method | Description |
+|--------|-------------|
+| `registerAgent(agent)` | Register a new agent |
+| `unregisterAgent(name)` | Remove an agent |
+| `getAgent(name)` | Get agent by name |
+| `listAgents()` | List all registered agents |
+| `findAgentsByCapability(cap)` | Find agents by capability |
+| `matchAgentToTask(task)` | Find best agent for task |
+| `createTask(agent, task, context, parentId)` | Create a task |
+| `getTask(id)` | Get task by ID |
+| `updateTaskStatus(id, status, output)` | Update task status |
+| `listTasks(agent?, status?)` | List tasks with filters |
+| `createCollaboration(name, desc, lead, participants)` | Create collaboration |
+| `getCollaboration(id)` | Get collaboration by ID |
+| `updateCollaborationStatus(id, status)` | Update collaboration status |
+| `listCollaborations(status?)` | List collaborations |
+| `sendMessage(from, to, collabId, content, type)` | Send agent message |
+| `getMessagesForCollaboration(id)` | Get collaboration messages |
+| `createReview(taskId, reviewer, reviewee, feedback, status, suggestions?)` | Create review |
+| `approveReview(id)` | Approve a review |
+| `getReviewsForTask(id)` | Get reviews for task |
+| `createWorkflow(name, desc, category)` | Create workflow |
+| `addWorkflowStep(flowId, name, desc, agent, task, deps)` | Add workflow step |
+| `executeWorkflow(id)` | Execute workflow |
+| `generateSystemPrompt(agentName)` | Generate system prompt |
+| `getStatistics()` | Get service statistics |
+
+## License
+
+MIT