@poolzin/pool-bot 2026.3.9 → 2026.3.10

package/docs/features/discord-components-v2.md

@@ -0,0 +1,277 @@
+# Discord Components V2
+
+Pool Bot supports Discord's Components V2 system for building rich, interactive messages. This feature uses the `@buape/carbon` library to provide a declarative API for creating containers, sections, buttons, selects, media galleries, and modals.
+
+## Overview
+
+Components V2 messages are structured using a `blocks`-based layout system wrapped in a container. Unlike traditional Discord embeds, Components V2 supports:
+
+- **Containers** with accent colors and spoiler support
+- **Text blocks** with markdown support
+- **Sections** with thumbnails or accessory buttons
+- **Separators** with configurable spacing
+- **Action rows** with buttons and select menus
+- **Media galleries** for image grids
+- **File attachments** with spoiler support
+- **Modals** for form-based interactions
+
+## Using Components
+
+Components are defined in the `components` field when sending messages via the `message` tool.
+
+### Basic Structure
+
+```json
+{
+  "text": "Optional top-level text",
+  "container": {
+    "accentColor": "#3498db",
+    "spoiler": false
+  },
+  "blocks": [
+    { "type": "text", "text": "Hello from Components V2!" },
+    { "type": "separator", "spacing": "large", "divider": true }
+  ],
+  "reusable": false
+}
+```
+
+## Block Types
+
+### Text Block
+
+Display simple text content with full markdown support.
+
+```json
+{ "type": "text", "text": "**Bold** and *italic* text with [links](https://example.com)" }
+```
+
+### Section Block
+
+Group related content with an optional thumbnail or button accessory.
+
+```json
+{
+  "type": "section",
+  "text": "Main content text",
+  "accessory": {
+    "type": "thumbnail",
+    "url": "https://example.com/image.png"
+  }
+}
+```
+
+With a button accessory:
+
+```json
+{
+  "type": "section",
+  "texts": ["Line 1", "Line 2", "Line 3"],
+  "accessory": {
+    "type": "button",
+    "button": {
+      "label": "Click me",
+      "style": "primary"
+    }
+  }
+}
+```
+
+**Limits:** Up to 3 text displays per section.
+
+### Separator Block
+
+Add visual spacing between blocks.
+
+```json
+{ "type": "separator", "spacing": "large", "divider": true }
+```
+
+**Spacing options:** `"small"`, `"large"`, `1`, `2`
+
+### Actions Block
+
+Contains interactive elements: buttons or select menus.
+
+#### Buttons
+
+```json
+{
+  "type": "actions",
+  "buttons": [
+    { "label": "Confirm", "style": "success" },
+    { "label": "Cancel", "style": "danger" },
+    { "label": "Info", "style": "secondary" },
+    { "label": "Visit", "style": "link", "url": "https://example.com" }
+  ]
+}
+```
+
+**Button styles:** `primary`, `secondary`, `success`, `danger`, `link`
+
+**Limits:** Up to 5 buttons per action row.
+
+#### Select Menus
+
+```json
+{
+  "type": "actions",
+  "select": {
+    "type": "string",
+    "placeholder": "Choose an option",
+    "options": [
+      { "label": "Option 1", "value": "opt1", "description": "First option" },
+      { "label": "Option 2", "value": "opt2" }
+    ]
+  }
+}
+```
+
+**Select types:** `string`, `user`, `role`, `mentionable`, `channel`
+
+### Media Gallery Block
+
+Display a grid of images.
+
+```json
+{
+  "type": "media-gallery",
+  "items": [
+    { "url": "https://example.com/photo1.jpg", "description": "Photo 1" },
+    { "url": "https://example.com/photo2.jpg", "spoiler": true }
+  ]
+}
+```
+
+### File Block
+
+Reference an uploaded file attachment.
+
+```json
+{
+  "type": "file",
+  "file": "attachment://document.pdf",
+  "spoiler": false
+}
+```
+
+## Modals
+
+Create form-based interactions that open when users click a trigger button.
+
+```json
+{
+  "text": "Click below to open the form",
+  "modal": {
+    "title": "Feedback Form",
+    "triggerLabel": "Open Feedback",
+    "triggerStyle": "primary",
+    "fields": [
+      {
+        "type": "text",
+        "name": "name",
+        "label": "Your Name",
+        "placeholder": "Enter your name",
+        "required": true,
+        "style": "short"
+      },
+      {
+        "type": "text",
+        "name": "feedback",
+        "label": "Feedback",
+        "placeholder": "Share your thoughts...",
+        "style": "paragraph",
+        "maxLength": 1000
+      },
+      {
+        "type": "select",
+        "name": "rating",
+        "label": "Rating",
+        "options": [
+          { "label": "Excellent", "value": "5" },
+          { "label": "Good", "value": "4" },
+          { "label": "Fair", "value": "3" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Modal Field Types
+
+| Type | Description |
+|------|-------------|
+| `text` | Single-line or paragraph text input |
+| `checkbox` | Multiple-choice checkbox group |
+| `radio` | Single-choice radio group |
+| `select` | Dropdown select menu |
+| `role-select` | Discord role selector |
+| `user-select` | Discord user selector |
+
+**Limits:** Maximum 5 fields per modal.
+
+## Complete Example
+
+```json
+{
+  "components": {
+    "container": {
+      "accentColor": "#5865F2"
+    },
+    "blocks": [
+      {
+        "type": "section",
+        "text": "## Welcome to Pool Bot!",
+        "accessory": {
+          "type": "thumbnail",
+          "url": "https://cdn.discordapp.com/avatars/..."
+        }
+      },
+      { "type": "separator", "spacing": "small" },
+      {
+        "type": "text",
+        "text": "Choose an action below to get started."
+      },
+      {
+        "type": "actions",
+        "buttons": [
+          { "label": "Get Started", "style": "success" },
+          { "label": "Documentation", "style": "link", "url": "https://docs.molt.bot" },
+          { "label": "Support", "style": "secondary" }
+        ]
+      }
+    ],
+    "modal": {
+      "title": "Contact Support",
+      "triggerLabel": "Contact Us",
+      "triggerStyle": "primary",
+      "fields": [
+        {
+          "type": "text",
+          "name": "issue",
+          "label": "Describe your issue",
+          "style": "paragraph",
+          "required": true
+        }
+      ]
+    }
+  }
+}
+```
+
+## Component Persistence
+
+Set `reusable: true` to allow components to be used across multiple interactions. By default, components are single-use.
+
+## Technical Details
+
+- Components are built using `@buape/carbon` library
+- Custom IDs use `occomp:` prefix for components and `ocmodal:` for modals
+- Messages with Components V2 automatically receive the `IsComponentsV2` flag
+- Component interactions are handled by the Discord gateway and routed to the appropriate agent session
+
+## Related
+
+- [Discord Gateway](/gateway/overview) - How component interactions are processed
+- [Message Tool](/features/message-tool) - General message sending capabilities

package/docs/features/swarm.md

@@ -0,0 +1,100 @@
+# Agent Swarm
+
+Pool Bot supports **Agent Swarms** - coordinated groups of agents that work together on complex tasks through distributed task allocation and specialized capabilities.
+
+## Overview
+
+An agent swarm consists of:
+- **Orchestrator**: The main agent that coordinates task distribution
+- **Members**: Individual agents with specific capabilities
+- **Tasks**: Work items assigned to agents based on strategy
+- **Strategy**: Algorithm for task distribution
+
+## Commands
+
+### List Swarms
+
+```bash
+poolbot swarm list
+```
+
+Shows all active swarms with member and task counts.
+
+### View Swarm Status
+
+```bash
+poolbot swarm status
+poolbot swarm status --id <swarm-id>
+```
+
+Displays a detailed dashboard showing:
+- Swarm statistics (members, tasks, completion rate)
+- Member status table with capabilities
+- Task queue with priorities and assignments
+- Visual status indicators
+
+### Create a Swarm
+
+```bash
+poolbot swarm create --name "My Swarm" \
+  --description "Team coordination swarm" \
+  --strategy capability_match \
+  --orchestrator main
+```
+
+**Options:**
+- `--name` (required): Swarm name
+- `--description`: Optional description
+- `--strategy`: Task distribution strategy (see below)
+- `--orchestrator`: Orchestrator agent ID (default: "main")
+
+## Task Distribution Strategies
+
+| Strategy | Description |
+|----------|-------------|
+| `round_robin` | Cycles through agents evenly |
+| `least_busy` | Assigns to agent with fewest active tasks |
+| `capability_match` | Matches tasks to agent capabilities (default) |
+| `priority_queue` | Processes highest priority tasks first |
+
+## Status Indicators
+
+### Member Status
+- `◌ idle` - Agent ready for work
+- `▶ working` - Agent processing task
+- `✖ error` - Agent encountered error
+- `⊘ offline` - Agent unavailable
+
+### Task Status
+- `○ pending` - Waiting for assignment
+- `◎ assigned` - Assigned to agent
+- `◐ in_progress` - Being processed
+- `● completed` - Finished successfully
+- `✖ failed` - Failed with error
+
+## JSON Output
+
+All commands support `--json` for programmatic use:
+
+```bash
+poolbot swarm status --json
+poolbot swarm list --json
+poolbot swarm create --name "Test" --json
+```
+
+## Gateway RPC Methods
+
+Swarm functionality is exposed via gateway RPC:
+
+- `swarm.list` - List all swarms
+- `swarm.status` - Get swarm details
+- `swarm.create` - Create new swarm
+
+## Architecture
+
+The swarm system consists of:
+- **SwarmService** (`src/swarm/service.ts`) - Core business logic
+- **Gateway Handlers** (`src/gateway/server-methods/swarm.ts`) - RPC endpoints
+- **CLI Commands** (`src/cli/swarm-cli/`) - User interface
+
+Swarm state is currently stored in-memory (persistent storage planned for future releases).

package/docs/features/telemetry.md

@@ -0,0 +1,284 @@
+# OpenTelemetry Observability
+
+Pool Bot includes built-in OpenTelemetry (OTel) observability for monitoring gateway performance, tracing requests, and collecting metrics.
+
+## Overview
+
+The telemetry system provides:
+
+- **Distributed Tracing**: Track request flows through the gateway
+- **Metrics Collection**: Counters, histograms, and gauges for performance monitoring
+- **Multiple Exporters**: Console, in-memory (for CLI), or OTLP (for production)
+- **Runtime Configuration**: Enable/disable via config without restarts
+
+## Configuration
+
+Enable telemetry in your Pool Bot config:
+
+```bash
+poolbot config set diagnostics.otel.enabled true
+poolbot config set diagnostics.otel.endpoint http://localhost:4318/v1/traces
+poolbot config set diagnostics.otel.serviceName poolbot-gateway
+poolbot config set diagnostics.otel.traces true
+poolbot config set diagnostics.otel.metrics true
+poolbot config set diagnostics.otel.sampleRate 1.0
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | boolean | `false` | Master switch for telemetry |
+| `endpoint` | string | - | OTLP endpoint URL (e.g., `http://localhost:4318`) |
+| `protocol` | string | `http/protobuf` | Protocol: `http/protobuf` or `grpc` |
+| `headers` | object | - | Custom headers for OTLP requests |
+| `serviceName` | string | `poolbot` | Service name in traces/metrics |
+| `traces` | boolean | `true` | Enable trace collection |
+| `metrics` | boolean | `true` | Enable metrics collection |
+| `sampleRate` | number | `1.0` | Trace sampling rate (0.0-1.0) |
+| `flushIntervalMs` | number | `60000` | Metrics export interval |
+
+## CLI Commands
+
+### Status Dashboard
+
+View telemetry status and configuration:
+
+```bash
+poolbot telemetry status
+```
+
+Displays:
+- Service initialization state
+- Exporter type and endpoint
+- Tracing/metrics configuration
+- Current metrics snapshot
+
+### Metrics Dashboard
+
+View collected metrics:
+
+```bash
+poolbot telemetry metrics
+```
+
+Shows:
+- Gateway request counts and latency
+- WebSocket connection metrics
+- Cron job execution stats
+- Custom application metrics
+
+Use `--json` for machine-readable output:
+
+```bash
+poolbot telemetry metrics --json
+```
+
+## Instrumentation
+
+### Gateway Instrumentation
+
+The gateway automatically instruments:
+
+- HTTP request duration and counts
+- WebSocket connection lifecycle
+- RPC method calls
+- Channel operations
+
+### Cron Instrumentation
+
+Cron jobs are instrumented with:
+
+- Job execution duration
+- Success/failure counts
+- Schedule adherence metrics
+
+### Custom Instrumentation
+
+Add custom metrics in your code:
+
+```typescript
+import { withInstrumentation, recordCounter, recordHistogram } from "../telemetry/instrumentation.js";
+
+// Wrap a function with tracing
+const result = await withInstrumentation("my-operation", async (span) => {
+  span.setAttribute("custom.attribute", "value");
+  return await doWork();
+});
+
+// Record a counter
+recordCounter("poolbot.mycomponent.events", 1, { event_type: "created" });
+
+// Record a histogram value
+recordHistogram("poolbot.mycomponent.duration", durationMs);
+```
+
+## Exporters
+
+### Console Exporter
+
+Outputs traces and metrics to stdout (useful for debugging):
+
+```bash
+poolbot config set diagnostics.otel.enabled true
+# No endpoint = console exporter
+```
+
+### OTLP Exporter
+
+Send to any OTLP-compatible backend:
+
+```bash
+poolbot config set diagnostics.otel.enabled true
+poolbot config set diagnostics.otel.endpoint http://jaeger:4318
+```
+
+Compatible with:
+- [Jaeger](https://www.jaegertracing.io/)
+- [Tempo](https://grafana.com/oss/tempo/)
+- [Honeycomb](https://www.honeycomb.io/)
+- [Datadog](https://www.datadoghq.com/)
+- Any OTLP-compliant collector
+
+### In-Memory Exporter
+
+Used internally by the CLI for displaying metrics without external dependencies.
+
+## Architecture
+
+The telemetry system consists of:
+
+1. **TelemetryService** (`src/telemetry/service.ts`): Core SDK initialization and lifecycle
+2. **Instrumentation Helpers** (`src/telemetry/instrumentation.ts`): High-level APIs for tracing and metrics
+3. **Gateway Instrumentation** (`src/telemetry/gateway-instrumentation.ts`): Gateway-specific metrics
+4. **Cron Instrumentation** (`src/telemetry/cron-instrumentation.ts`): Cron job metrics
+  5. **RPC Handlers** (`src/gateway/server-methods/telemetry.ts`): CLI-to-gateway communication
+  6. **Alert Engine** (`src/telemetry/alert-engine.ts`): Intelligent alerting with configurable rules
+
+## Alerting
+
+Pool Bot includes an intelligent alert system that monitors telemetry data and notifies you when issues are detected.
+
+### Built-in Alert Rules
+
+| Rule | Condition | Severity | Description |
+|------|-----------|----------|-------------|
+| `cron-job-failures` | >3 failures in 5min | error | Cron job execution failures |
+| `cron-job-slow` | >60s execution | warn | Cron jobs running slowly |
+| `cron-job-stuck` | >5min execution | error | Cron jobs stuck/frozen |
+| `security-scan-failures` | >0 failures | error | Security scan failures |
+| `hexstrike-api-latency` | >5s response | warn | HexStrike API slow |
+| `swarm-task-failures` | >3 failures in 5min | error | Swarm task failures |
+| `gateway-memory-high` | >512MB usage | warn | High memory usage |
+| `gateway-memory-critical` | >1GB usage | error | Critical memory usage |
+| `gateway-cpu-high` | >80% CPU | warn | High CPU usage |
+
+### Alert Configuration
+
+Configure alerts via config:
+
+```bash
+# Enable alerts
+poolbot config set alerts.enabled true
+
+# Configure notification channels
+poolbot config set alerts.channels.webhook.url https://hooks.slack.com/services/...
+poolbot config set alerts.channels.announce true  # Use configured announce channel
+```
+
+### Custom Alert Rules
+
+Add custom rules programmatically:
+
+```typescript
+import { alertEngine } from "../telemetry/alert-engine.js";
+
+// Add custom rule
+alertEngine.addRule({
+  id: "my-custom-alert",
+  name: "Custom Metric Alert",
+  metric: "poolbot.mycomponent.errors",
+  condition: { type: "threshold", operator: ">", value: 10 },
+  windowMs: 60000,  // 1 minute window
+  severity: "error",
+  channels: ["webhook"]
+});
+```
+
+### Alert Channels
+
+- **Webhook**: POST alert payload to configured URL
+- **Announce**: Send to configured announce channel (Discord, Slack, etc.)
+- **Console**: Log to stderr (always enabled)
+
+### Alert Payload
+
+```json
+{
+  "ruleId": "cron-job-failures",
+  "ruleName": "Cron Job Failures",
+  "severity": "error",
+  "message": "Alert: Cron Job Failures - 5 failures in 5 minutes",
+  "timestamp": "2026-03-10T12:00:00Z",
+  "data": { "failures": 5, "window": "5m" }
+}
+```
+
+## Troubleshooting
+
+### Telemetry not initializing
+
+Check logs for:
+```
+[telemetry] service started
+```
+
+If missing, verify:
+- `diagnostics.otel.enabled` is `true`
+- Config was saved: `poolbot config get diagnostics.otel`
+
+### No metrics appearing
+
+For OTLP export:
+- Verify endpoint URL is correct
+- Check network connectivity: `curl -v $OTEL_ENDPOINT`
+- Review collector logs for rejected spans
+
+### High memory usage
+
+- Reduce `sampleRate` (e.g., `0.1` for 10% sampling)
+- Lower `flushIntervalMs` to export more frequently
+- Disable unused instrumentation: `diagnostics.otel.metrics: false`
+
+## Examples
+
+### Basic Setup with Jaeger
+
+```bash
+# Start Jaeger
+docker run -d --name jaeger \
+  -p 16686:16686 \
+  -p 4318:4318 \
+  jaegertracing/all-in-one:latest
+
+# Configure Pool Bot
+poolbot config set diagnostics.otel.enabled true
+poolbot config set diagnostics.otel.endpoint http://localhost:4318/v1/traces
+poolbot config set diagnostics.otel.serviceName poolbot-dev
+
+# Restart gateway
+poolbot gateway restart
+
+# View traces at http://localhost:16686
+```
+
+### Debugging with Console Output
+
+```bash
+poolbot config set diagnostics.otel.enabled true
+poolbot config set diagnostics.otel.traces true
+poolbot config set diagnostics.otel.metrics false  # Reduce noise
+
+# Watch telemetry output
+poolbot gateway run 2>&1 | grep -E "\[telemetry\]|Span|Metric"
+```