@poolzin/pool-bot 2026.3.9 → 2026.3.11

package/docs/models/provider-infrastructure.md

@@ -0,0 +1,400 @@
+# Provider Infrastructure
+
+PoolBot includes resilient provider infrastructure for LLM integrations, featuring token pools for multi-key setups and automatic failover between providers.
+
+## Overview
+
+The provider infrastructure provides:
+
+- **Token Pools** - Distribute load across multiple API keys
+- **Rate Limit Handling** - Automatic retry and fallback on rate limits
+- **Automatic Failover** - Seamless switching between providers
+- **Request Monitoring** - Tracking for debugging and optimization
+
+## Architecture
+
+```
+User Request
+    │
+    ▼
+┌─────────────────────────────────────┐
+│      Provider Resolution            │
+│  ┌──────────┬──────────┬─────────┐  │
+│  │ Provider │ Provider │Provider │  │
+│  │   A      │    B     │   C     │  │
+│  │ [Key 1]  │ [Key 1]  │ [Key 1] │  │
+│  │ [Key 2]  │          │         │  │
+│  └────┬─────┴────┬─────┴────┬────┘  │
+│       │          │          │       │
+│       └──────────┼──────────┘       │
+│                  ▼                   │
+│         ┌─────────────┐              │
+│         │Rate Limit / │              │
+│         │  Failover   │              │
+│         │  Handling   │              │
+│         └──────┬──────┘              │
+└────────────────┼─────────────────────┘
+                 ▼
+               Provider
+```
+
+## Token Pools
+
+For high-volume deployments, configure multiple API keys:
+
+### Basic Token Pool
+
+```json
+{
+  "models": {
+    "providers": {
+      "openai": {
+        "baseUrl": "https://api.openai.com/v1",
+        "tokens": [
+          { "key": "${OPENAI_API_KEY_1}" },
+          { "key": "${OPENAI_API_KEY_2}" }
+        ]
+      }
+    }
+  }
+}
+```
+
+### Weighted Distribution
+
+Control traffic distribution across keys:
+
+```json
+{
+  "models": {
+    "providers": {
+      "openai": {
+        "tokens": [
+          { "key": "${OPENAI_KEY_1}", "weight": 60 },
+          { "key": "${OPENAI_KEY_2}", "weight": 40 }
+        ]
+      }
+    }
+  }
+}
+```
+
+### Priority Tiers
+
+Use priority for primary/backup key organization:
+
+```json
+{
+  "models": {
+    "providers": {
+      "openai": {
+        "tokens": [
+          { "key": "${OPENAI_KEY_1}", "priority": 1, "weight": 50 },
+          { "key": "${OPENAI_KEY_2}", "priority": 1, "weight": 50 },
+          { "key": "${OPENAI_KEY_3}", "priority": 2, "weight": 100 }
+        ]
+      }
+    }
+  }
+}
+```
+
+Keys with lower priority numbers are tried first.
+
+## Rate Limit Handling
+
+PoolBot automatically handles rate limits:
+
+### Automatic Retry
+
+When a rate limit (429) is encountered:
+1. Mark the key as rate-limited with cooldown
+2. Try the next available key in the pool
+3. Apply exponential backoff for retries
+
+### Error Classification
+
+PoolBot classifies provider errors:
+
+| Error Type | Handling |
+|------------|----------|
+| `rate_limit` | Retry with next key, exponential backoff |
+| `context_overflow` | Fail fast, suggest smaller context |
+| `auth_error` | Mark key as invalid, try next |
+| `server_error` | Retry with backoff |
+| `timeout` | Retry with next key |
+
+### Cooldown Management
+
+Failed keys enter cooldown with exponential backoff:
+
+```
+Attempt 1: 1 second cooldown
+Attempt 2: 2 seconds
+Attempt 3: 4 seconds
+Attempt 4: 8 seconds
+...
+Maximum: 5 minutes
+```
+
+## Failover
+
+### Provider-Level Failover
+
+Configure fallback providers at the agent level:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": {
+        "provider": "openai/gpt-4o",
+        "fallback": [
+          "anthropic/claude-sonnet-4",
+          "google/gemini-1.5-pro"
+        ]
+      }
+    }
+  }
+}
+```
+
+### Failover Triggers
+
+Failover occurs on:
+- Rate limit (429)
+- Server error (5xx)
+- Timeout
+- Authentication error (401/403)
+- Context overflow (when primary can't handle the request)
+
+### Failover Behavior
+
+1. Try primary provider with all available keys
+2. If all keys exhausted, try fallback providers in order
+3. Return best available response or aggregate error
+
+## Request Monitoring
+
+### Profile Tracking
+
+PoolBot tracks usage per auth profile:
+
+```typescript
+{
+  profileId: "openai-key-1",
+  requestsCount: 15432,
+  lastUsedAt: 1709823456789,
+  cooldownUntil: 0,
+  failureCount: 2
+}
+```
+
+### Ring Buffer
+
+Recent requests are tracked for debugging:
+
+```json
+{
+  "models": {
+    "monitoring": {
+      "ringBufferSize": 1000
+    }
+  }
+}
+```
+
+## Configuration Reference
+
+### Provider Configuration
+
+```json
+{
+  "models": {
+    "providers": {
+      "openai": {
+        "baseUrl": "https://api.openai.com/v1",
+        "apiKey": "${OPENAI_API_KEY}",
+        "tokens": [
+          {
+            "key": "sk-...",
+            "weight": 50,
+            "priority": 1
+          }
+        ]
+      },
+      "anthropic": {
+        "baseUrl": "https://api.anthropic.com",
+        "apiKey": "${ANTHROPIC_API_KEY}"
+      },
+      "google": {
+        "baseUrl": "https://generativelanguage.googleapis.com",
+        "apiKey": "${GEMINI_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+### Agent Model Configuration
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": {
+        "provider": "openai/gpt-4o",
+        "fallback": [
+          "anthropic/claude-sonnet-4",
+          "google/gemini-1.5-pro"
+        ],
+        "temperature": 0.7,
+        "maxTokens": 4096
+      }
+    }
+  }
+}
+```
+
+## Best Practices
+
+### Production Setup
+
+```json
+{
+  "models": {
+    "providers": {
+      "openai": {
+        "tokens": [
+          { "key": "${OPENAI_KEY_1}", "weight": 50 },
+          { "key": "${OPENAI_KEY_2}", "weight": 50 }
+        ]
+      },
+      "anthropic": {
+        "apiKey": "${ANTHROPIC_KEY}"
+      }
+    }
+  },
+  "agents": {
+    "defaults": {
+      "model": {
+        "provider": "openai/gpt-4o",
+        "fallback": ["anthropic/claude-sonnet-4"]
+      }
+    }
+  }
+}
+```
+
+### Cost Optimization
+
+Use cheaper models as fallbacks:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": {
+        "provider": "openai/gpt-4o",
+        "fallback": [
+          "openai/gpt-4o-mini",
+          "google/gemini-1.5-flash"
+        ]
+      }
+    }
+  }
+}
+```
+
+### High Availability
+
+Configure multiple providers:
+
+```json
+{
+  "models": {
+    "providers": {
+      "openai": { "apiKey": "${OPENAI_KEY}" },
+      "anthropic": { "apiKey": "${ANTHROPIC_KEY}" },
+      "google": { "apiKey": "${GEMINI_KEY}" }
+    }
+  },
+  "agents": {
+    "defaults": {
+      "model": {
+        "provider": "openai/gpt-4o",
+        "fallback": [
+          "anthropic/claude-sonnet-4",
+          "google/gemini-1.5-pro"
+        ]
+      }
+    }
+  }
+}
+```
+
+## Troubleshooting
+
+### Rate Limit Errors
+
+1. Add more API keys to the token pool
+2. Check if keys are properly configured
+3. Review request patterns for spikes
+4. Consider adding fallback providers
+
+### High Latency
+
+1. Check provider status pages
+2. Review token pool distribution
+3. Consider regional providers
+4. Enable request monitoring to identify bottlenecks
+
+### Failover Not Working
+
+1. Verify fallback providers are configured
+2. Check provider credentials are valid
+3. Review gateway logs for error details
+4. Test providers individually
+
+### Authentication Errors
+
+1. Verify API keys are correct
+2. Check key hasn't expired
+3. Ensure environment variables are set
+4. Review key permissions/scopes
+
+## Monitoring
+
+### Gateway Status
+
+Check provider status:
+
+```bash
+poolbot status --deep
+```
+
+### Model List
+
+List configured providers and models:
+
+```bash
+poolbot models list
+```
+
+### Live Testing
+
+Test providers with live requests:
+
+```bash
+# Test specific provider
+poolbot models list --live --provider openai
+
+# Test all providers
+poolbot models list --live
+```
+
+## See Also
+
+- [Model Configuration](./configuration.md)
+- [Agent Configuration](../agents/configuration.md)
+- [Gateway Operations](../gateway/operations.md)

package/docs/security/exec-approvals.md

@@ -0,0 +1,294 @@
+# Exec Approvals
+
+PoolBot's **Exec Approval System** provides security guardrails for executing commands on host systems. It prevents unauthorized command execution while maintaining usability through configurable allowlists.
+
+## Overview
+
+When agents attempt to execute system commands (via `exec` tool), PoolBot can require explicit approval before execution. This protects against:
+
+- Accidental data loss
+- Malicious command injection
+- Unintended system modifications
+
+## How It Works
+
+```
+Agent requests command ──► PoolBot analyzes ──► Check allowlist
+                                                  │
+                        ◄────────── Execute ◄─────┤ (if allowed)
+                        (approval required) ◄─────┘ (if not in allowlist)
+```
+
+## Configuration
+
+Exec approvals are configured per-agent in `~/.poolbot/exec-approvals.json`:
+
+```json
+{
+  "version": 1,
+  "defaults": {
+    "security": "allowlist",
+    "ask": "on-miss",
+    "askFallback": "deny",
+    "autoAllowSkills": false
+  },
+  "agents": {
+    "main": {
+      "security": "allowlist",
+      "ask": "on-miss",
+      "allowlist": [
+        { "id": "uuid-1", "pattern": "git status", "lastUsedAt": 1709823456789 },
+        { "id": "uuid-2", "pattern": "ls -la", "lastUsedAt": 1709823459999 }
+      ]
+    }
+  }
+}
+```
+
+### Security Levels
+
+| Level | Description |
+|-------|-------------|
+| `deny` | All commands blocked |
+| `allowlist` | Only allowlisted commands permitted |
+| `full` | All commands permitted (use with caution) |
+
+### Ask Modes
+
+| Mode | Description |
+|------|-------------|
+| `always` | Always request approval |
+| `on-miss` | Request approval only if not in allowlist |
+| `off` | Never request approval |
+
+## Approval Workflow
+
+### 1. Command Request
+
+Agent attempts to run a command through the `exec` tool.
+
+### 2. Analysis
+
+PoolBot analyzes the command:
+- Resolves the binary path
+- Checks against allowlist patterns
+- Determines if approval is required
+
+### 3. Approval Request
+
+If approval is needed, PoolBot sends a request via Unix domain socket to the gateway:
+
+```typescript
+{
+  id: "req-uuid",
+  request: {
+    command: "npm install",
+    cwd: "/workspace/project",
+    host: "sandbox",
+    security: "allowlist",
+    ask: "on-miss",
+    agentId: "main"
+  },
+  createdAtMs: 1709823456789,
+  expiresAtMs: 1709823576789
+}
+```
+
+### 4. User Decision
+
+The user can respond with:
+- `allow-once` - Approve this execution only
+- `allow-always` - Add to allowlist and approve
+- `deny` - Reject the command
+
+## Allowlist Management
+
+### Pattern Matching
+
+Allowlist entries support pattern matching:
+
+```json
+{
+  "pattern": "git *"
+}
+```
+
+This matches:
+- `git status`
+- `git log`
+- `git commit -m "message"`
+
+### Automatic Updates
+
+When you approve with "always", PoolBot automatically:
+1. Adds the pattern to the allowlist
+2. Records metadata (last used, resolved path)
+3. Persists to `~/.poolbot/exec-approvals.json`
+
+## Per-Agent Configuration
+
+Different agents can have different security policies:
+
+```json
+{
+  "agents": {
+    "main": {
+      "security": "allowlist",
+      "ask": "on-miss"
+    },
+    "unsafe-agent": {
+      "security": "deny"
+    },
+    "trusted-agent": {
+      "security": "allowlist",
+      "ask": "off",
+      "autoAllowSkills": true
+    }
+  }
+}
+```
+
+## Integration with Tools
+
+### Default Configuration
+
+When using the `exec` tool, the agent's exec approval settings are applied:
+
+```typescript
+// The tool inherits settings from exec-approvals.json
+const result = await exec({
+  command: "npm install",
+  cwd: "/workspace/project"
+});
+```
+
+### Sandbox Mode
+
+Exec approvals work with sandbox mode for additional isolation:
+
+```json
+{
+  "tools": {
+    "exec": {
+      "host": "sandbox",
+      "sandbox": {
+        "image": "node:20-alpine"
+      }
+    }
+  }
+}
+```
+
+## File Location
+
+Exec approvals are stored at:
+
+```
+~/.poolbot/exec-approvals.json
+```
+
+The file has strict permissions (0o600) and contains:
+- Version number
+- Socket configuration for gateway communication
+- Default settings
+- Per-agent configurations and allowlists
+
+## Socket Communication
+
+The CLI and gateway communicate via Unix domain socket:
+
+```
+~/.poolbot/exec-approvals.sock
+```
+
+This enables:
+- Real-time approval requests
+- Secure cross-process communication
+- Token-based authentication
+
+## Best Practices
+
+### Development Environment
+
+```json
+{
+  "defaults": {
+    "security": "allowlist",
+    "ask": "on-miss"
+  },
+  "agents": {
+    "main": {
+      "allowlist": [
+        { "pattern": "git *" },
+        { "pattern": "npm *" },
+        { "pattern": "ls *" },
+        { "pattern": "cat *" }
+      ]
+    }
+  }
+}
+```
+
+### Production Environment
+
+```json
+{
+  "defaults": {
+    "security": "allowlist",
+    "ask": "always"
+  }
+}
+```
+
+### CI/CD Environment
+
+```json
+{
+  "agents": {
+    "ci-agent": {
+      "security": "full",
+      "ask": "off"
+    }
+  }
+}
+```
+
+## Troubleshooting
+
+### Approval Not Received
+
+1. Check gateway is running: `poolbot status`
+2. Verify socket exists: `ls -la ~/.poolbot/exec-approvals.sock`
+3. Check file permissions on `~/.poolbot/exec-approvals.json`
+
+### Commands Blocked Unexpectedly
+
+1. Review allowlist patterns
+2. Check agent-specific settings
+3. Verify `security` level is not set to `deny`
+
+### Socket Errors
+
+If the socket is corrupted or inaccessible:
+
+```bash
+# Remove the socket file
+rm ~/.poolbot/exec-approvals.sock
+
+# Restart the gateway
+poolbot gateway restart
+```
+
+## Security Considerations
+
+- The allowlist file contains sensitive patterns - keep permissions strict (0o600)
+- Socket communication is local-only
+- Tokens are auto-generated and rotated
+- Pattern matching is case-insensitive
+- Resolved binary paths are tracked for auditing
+
+## See Also
+
+- [Security Overview](../security/overview.md)
+- [Sandbox Mode](../security/sandbox.md)
+- [Agent Configuration](../agents/configuration.md)

package/extensions/bluebubbles/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poolbot/bluebubbles",
-  "version": "2026.3.4",
+  "version": "2026.3.11",
   "type": "module",
   "description": "Poolbot BlueBubbles channel plugin",
   "poolbot": {

package/extensions/copilot-proxy/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poolbot/copilot-proxy",
-  "version": "2026.3.4",
+  "version": "2026.3.11",
   "type": "module",
   "description": "Poolbot Copilot Proxy provider plugin",
   "poolbot": {

package/extensions/diagnostics-otel/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poolbot/diagnostics-otel",
-  "version": "2026.3.4",
+  "version": "2026.3.11",
   "type": "module",
   "description": "Poolbot diagnostics OpenTelemetry exporter",
   "poolbot": {

package/extensions/discord/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poolbot/discord",
-  "version": "2026.3.4",
+  "version": "2026.3.11",
   "type": "module",
   "description": "Poolbot Discord channel plugin",
   "poolbot": {