@poolzin/pool-bot 2026.3.11 → 2026.3.13

package/CHANGELOG.md

@@ -1,3 +1,37 @@
+## v2026.3.13 (2026-03-13)
+
+### Features
+- **Plugin Development Guide:** comprehensive documentation at `docs/refactor/plugin-development-guide.md`
+  - Quick start tutorial from template
+  - Extension types (tools, providers, channels, hooks)
+  - Configuration schema examples
+  - Troubleshooting common errors
+
+### Fixes
+- **Plugin Template:** renamed `mavalie` → `template` with proper structure
+  - Fixed entry point path (`./index.ts` instead of `./src/index.ts`)
+  - Added required `poolbot.plugin.json` manifest
+  - Updated all metadata (id, name, description)
+  - Added `label` property to tool examples (required field)
+- **Missing Manifests:** added `poolbot.plugin.json` to `mcp-server` and `hexstrike-bridge`
+  - Fixes "plugin manifest not found" doctor errors
+  - Fixes "extension entry escapes package directory" errors
+
+---
+
+## v2026.3.12 (2026-03-12)
+
+### Fixes
+- **Plugin Template:** renamed `mavalie` → `template` with proper structure
+  - Fixed entry point path (`./index.ts` instead of `./src/index.ts`)
+  - Added required `poolbot.plugin.json` manifest
+  - Updated all metadata (id, name, description)
+- **Missing Manifests:** added `poolbot.plugin.json` to `mcp-server` and `hexstrike-bridge`
+  - Fixes "plugin manifest not found" doctor errors
+  - Fixes "extension entry escapes package directory" errors
+
+---
+
 ## v2026.3.11 (2026-03-11)
 
 ### Features

package/dist/.buildstamp

@@ -1 +1 @@
-1773140740628
+1773200810931

package/dist/build-info.json

@@ -1,5 +1,5 @@
 {
-  "version": "2026.3.11",
-  "commit": "e464b86a7613500e5f85a0ea9dcf1f3ebdb25745",
-  "builtAt": "2026-03-11T01:05:20.779Z"
+  "version": "2026.3.13",
+  "commit": "772f27d4ab21d89af08b22c846efea9a20f86f83",
+  "builtAt": "2026-03-11T03:51:28.829Z"
 }

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/hexstrike-bridge/package.json

@@ -5,7 +5,7 @@
   "description": "HexStrike AI security tools bridge for PoolBot - integrates 150+ security scanners",
   "poolbot": {
     "extensions": [
-      "./src/index.ts"
+      "./index.ts"
     ]
   },
   "dependencies": {

package/extensions/hexstrike-bridge/poolbot.plugin.json

@@ -0,0 +1,23 @@
+{
+  "id": "hexstrike-bridge",
+  "name": "HexStrike Security Bridge",
+  "description": "Integrates HexStrike AI security tools (150+ scanners).",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "baseUrl": {
+        "type": "string",
+        "default": "http://localhost:8888"
+      },
+      "timeoutMs": {
+        "type": "number",
+        "default": 300000
+      },
+      "maxConcurrentScans": {
+        "type": "number",
+        "default": 3
+      }
+    }
+  }
+}

package/extensions/mcp-server/poolbot.plugin.json

@@ -0,0 +1,10 @@
+{
+  "id": "mcp-server",
+  "name": "MCP Server",
+  "description": "MCP (Model Context Protocol) server - exposes PoolBot tools via MCP protocol.",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/extensions/template/README.md

@@ -0,0 +1,101 @@
+# Template Plugin for PoolBot
+
+Starter template for creating custom PoolBot plugins.
+
+## Structure
+
+```
+extensions/template/
+├── package.json          # npm manifest
+├── poolbot.plugin.json   # Plugin manifest (required)
+├── index.ts              # Entry point (root level)
+└── README.md             # Documentation
+```
+
+## Installation
+
+The plugin loads automatically when:
+- Directory is in `extensions/template/`
+- `package.json` has `poolbot.extensions` configured
+- `poolbot.plugin.json` exists in plugin root
+
+## Configuration
+
+The plugin uses an empty schema (`configSchema` with `additionalProperties: false`), meaning no initial configuration is required.
+
+To add settings, update `poolbot.plugin.json`:
+
+```json
+{
+  "id": "template",
+  "name": "Template",
+  "description": "My custom PoolBot plugin.",
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "apiKey": { "type": "string" },
+      "endpoint": { "type": "string", "default": "https://api.example.com" }
+    }
+  }
+}
+```
+
+## Development
+
+### Extension Types
+
+PoolBot supports 4 extension types via `PoolBotPluginApi`:
+
+1. **Tool** - Add agent tools (`api.registerTool()`)
+2. **Provider** - Add custom LLM models (`api.registerProvider()`)
+3. **Channel** - Add messaging channels (`api.registerChannel()`)
+4. **Hook** - Intercept lifecycle events (`api.registerHook()`)
+
+### Example: Registering a Tool
+
+```typescript
+import type { PoolBotPluginApi } from "../../src/plugins/types.js";
+import type { AgentToolResult } from "@mariozechner/pi-agent-core";
+
+export default function register(api: PoolBotPluginApi) {
+  api.registerTool({
+    label: "My Search",           // Display name for the tool
+    name: "my_search",            // Tool identifier (snake_case)
+    description: "Search using custom API",
+    parameters: {
+      type: "object",
+      properties: {
+        query: { type: "string" }
+      },
+      required: ["query"]
+    },
+    async execute(_toolCallId, params): Promise<AgentToolResult<unknown>> {
+      const { query } = params as { query: string };
+      // Implementation here
+      return {
+        content: [{ type: "text", text: JSON.stringify({ results: [] }) }],
+        details: { query }
+      };
+    }
+  });
+}
+```
+
+## 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`
+
+## References
+
+- [Plugin SDK Documentation](../../docs/refactor/plugin-sdk.md)
+- [Example Plugins](../lobster/, ../llm-task/, etc.)

package/extensions/template/index.ts

@@ -0,0 +1,38 @@
+import type { PoolBotPluginApi } from "../../src/plugins/types.js";
+
+/**
+ * Template Plugin for PoolBot
+ *
+ * Starter template for creating custom PoolBot plugins.
+ * This plugin can be expanded with custom tools, providers, channels, or hooks.
+ */
+
+export default function register(_api: PoolBotPluginApi) {
+  // Plugin registered successfully
+  // TODO: Add here:
+  // - Tools (agent tools)
+  // - Providers (custom LLM models)
+  // - Channels (messaging integrations)
+  // - Hooks (lifecycle events)
+
+  // Example: Register a simple tool
+  // api.registerTool({
+  //   label: "My Tool",           // Display name
+  //   name: "my_tool",            // Tool identifier (snake_case)
+  //   description: "Does something",
+  //   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: `Result: ${input}` }],
+  //       details: { input }
+  //     };
+  //   }
+  // });
+}

package/extensions/template/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@poolbot/template",
+  "version": "2026.3.12",
+  "type": "module",
+  "description": "Template plugin for PoolBot - starter template for custom integrations",
+  "poolbot": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "poolbot": "workspace:*"
+  }
+}

package/extensions/template/poolbot.plugin.json

@@ -0,0 +1,10 @@
+{
+  "id": "template",
+  "name": "Template",
+  "description": "Starter template plugin for PoolBot custom integrations.",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poolzin/pool-bot",
-  "version": "2026.3.11",
+  "version": "2026.3.13",
   "description": "🎱 Pool Bot - AI assistant with PLCODE integrations",
   "keywords": [],
   "license": "MIT",

package/extensions/mavalie/README.md

@@ -1,97 +0,0 @@
-# Mavalie Plugin for PoolBot
-
-Plugin template válido para PoolBot.
-
-## Estrutura
-
-```
-extensions/mavalie/
-├── package.json          # Manifest do plugin
-├── src/
-│   └── index.ts         # Entry point
-└── README.md            # Esta documentação
-```
-
-## Instalação
-
-1. **Build do plugin:**
-   ```bash
-   cd extensions/mavalie
-   npm install
-   npm run build  # ou pnpm build
-   ```
-
-2. **Ativação no PoolBot:**
-   O plugin é carregado automaticamente pelo PoolBot quando:
-   - O diretório está em `extensions/mavalie/`
-   - O `package.json` tem a seção `poolbot.extensions` configurada
-   - O entry point (`dist/index.js`) existe
-
-## Configuração
-
-O plugin usa `emptyPluginConfigSchema()`, ou seja, não requer configuração.
-
-Para adicionar configurações, substitua por:
-
-```typescript
-import { z } from "zod";
-
-const configSchema = z.object({
-  apiKey: z.string().optional(),
-  endpoint: z.string().url().default("https://api.mavalie.com"),
-});
-```
-
-## Desenvolvimento
-
-### Padrões de Plugin
-
-O PoolBot suporta 4 tipos de extensões:
-
-1. **Provider** - Adiciona novos modelos LLM
-2. **Channel** - Adiciona canais de comunicação (Discord, Slack, etc)
-3. **Tool** - Adiciona ferramentas para agentes
-4. **Hook** - Intercepta eventos do ciclo de vida
-
-### Exemplo: Registrando um Provider
-
-```typescript
-api.registerProvider({
-  id: "mavalie",
-  label: "Mavalie AI",
-  auth: [{
-    id: "api-key",
-    kind: "apiKey",
-    run: async (ctx) => {
-      const key = await ctx.prompter.password({
-        message: "Mavalie API Key:"
-      });
-      return {
-        profiles: [{
-          profileId: "mavalie:default",
-          credential: { type: "apiKey", key: String(key) }
-        }]
-      };
-    }
-  }]
-});
-```
-
-## Troubleshooting
-
-### "plugin manifest not found"
-- Verifique se `package.json` existe e tem `poolbot.extensions`
-- Verifique se o caminho em `extensions` aponta para o arquivo correto
-
-### "extension entry escapes package directory"
-- O entry point deve estar dentro do diretório do plugin
-- Use `./dist/index.js` (não `./src/index.ts` para produção)
-
-### Erros de TypeScript "Cannot find module 'poolbot/plugin-sdk'"
-- Normal durante desenvolvimento - o alias só resolve após build
-- O build do PoolBot principal resolve essas dependências
-
-## Referências
-
-- [Plugin SDK Documentation](../../docs/refactor/plugin-sdk.md)
-- [Exemplos de Plugins](../discord/, ../slack/, etc.)

package/extensions/mavalie/package.json

@@ -1,15 +0,0 @@
-{
-  "name": "@poolbot/mavalie",
-  "version": "2026.3.11",
-  "type": "module",
-  "description": "Mavalie plugin for PoolBot - custom integration",
-  "poolbot": {
-    "extensions": [
-      "./src/index.ts"
-    ]
-  },
-  "dependencies": {},
-  "devDependencies": {
-    "poolbot": "workspace:*"
-  }
-}

package/extensions/mavalie/src/index.ts

@@ -1,62 +0,0 @@
-import { emptyPluginConfigSchema } from "poolbot/plugin-sdk";
-
-/**
- * Mavalie Plugin for PoolBot
- * 
- * Template mínimo válido de plugin para PoolBot.
- * Este plugin registra um provider customizado que pode ser expandido
- * conforme necessidades específicas.
- */
-
-const mavaliePlugin = {
-  id: "mavalie",
-  name: "Mavalie",
-  description: "Custom Mavalie integration for PoolBot",
-  configSchema: emptyPluginConfigSchema(),
-  
-  register(api) {
-    // Log de registro do plugin
-    api.runtime?.log?.("Mavalie plugin registered");
-    
-    // TODO: Adicione aqui o registro de:
-    // - Providers (modelos customizados)
-    // - Canais (integrações de mensageria)
-    // - Ferramentas (tools para agentes)
-    // - Hooks (eventos do ciclo de vida)
-    
-    // Exemplo de registro de provider (descomente e adapte):
-    /*
-    api.registerProvider({
-      id: "mavalie",
-      label: "Mavalie Provider",
-      docsPath: "/providers/models",
-      auth: [
-        {
-          id: "api-key",
-          label: "API Key",
-          kind: "apiKey",
-          run: async (ctx) => {
-            const key = await ctx.prompter.password({
-              message: "Enter your Mavalie API key:",
-            });
-            return {
-              profiles: [
-                {
-                  profileId: "mavalie:default",
-                  credential: {
-                    type: "apiKey",
-                    provider: "mavalie",
-                    key: String(key),
-                  },
-                },
-              ],
-            };
-          },
-        },
-      ],
-    });
-    */
-  },
-};
-
-export default mavaliePlugin;