@poolzin/pool-bot 2026.3.6 → 2026.3.9

package/docs/integrations/INTEGRATION_PLAN.md

@@ -0,0 +1,424 @@
+# PoolBot Integration Architecture Plan
+
+## Executive Summary
+
+This document outlines the integration strategy for three external projects into PoolBot to create a "complete and independent" AI agent platform:
+
+1. **Page Agent** (Alibaba) - GUI browser automation via text-based DOM manipulation
+2. **HexStrike AI** - MCP-based cybersecurity platform with 150+ security tools
+3. **xyOps** - Job scheduling, workflow automation, and monitoring platform
+
+## Current PoolBot Architecture Analysis
+
+### Existing Systems
+
+| System | Location | Capabilities | Integration Point |
+|--------|----------|--------------|-------------------|
+| **Skills System** | `src/skills/` | Modular skill loading, progressive disclosure, security scanning | New skill type: `external-service` |
+| **Plugin System** | `src/plugins/` | Tools, hooks, HTTP handlers, CLI commands, gateway methods | Plugin adapters for external services |
+| **Browser Automation** | `src/browser/` | Playwright-based browser control, Chrome extension relay, agent routes | Extend with Page Agent's text-based DOM approach |
+| **Node Registry** | `src/gateway/node-registry.ts` | Distributed node management, command invocation | External services as "virtual nodes" |
+| **Gateway Methods** | `src/gateway/server-methods/` | RPC-style API endpoints | New methods for external service proxy |
+| **Agent Tools** | `src/agents/tools/` | LLM-callable tools | Auto-generated tools from external services |
+| **Context Engine** | `src/context-engine/` | Legacy + Summarizing implementations | No changes needed |
+| **Memory/Embeddings** | `src/memory/` | Sophisticated embedding system | No changes needed |
+
+### Key Integration Patterns
+
+```typescript
+// Pattern 1: External Service as Virtual Node
+interface ExternalServiceNode {
+  nodeId: string;           // e.g., "page-agent", "hexstrike-ai"
+  serviceType: string;      // "browser", "security", "workflow"
+  commands: string[];       // Available commands
+  caps: string[];          // Capabilities
+  connection: ServiceConnection;
+}
+
+// Pattern 2: Gateway Method Proxy
+interface ServiceProxyHandler {
+  method: string;           // e.g., "pageagent.navigate"
+  handler: GatewayRequestHandler;
+  serviceConfig: ServiceConfig;
+}
+
+// Pattern 3: Auto-Generated Agent Tools
+type ServiceToolGenerator = (
+  serviceSchema: ServiceSchema
+) => AnyAgentTool[];
+
+// Pattern 4: Plugin Adapter
+interface ExternalServicePlugin {
+  id: string;
+  serviceType: string;
+  register: (api: PoolBotPluginApi) => void;
+  activate: (api: PoolBotPluginApi) => Promise<void>;
+}
+```
+
+## Integration Architecture
+
+### 1. Page Agent Integration (Browser Enhancement)
+
+**Rationale**: Page Agent's text-based DOM manipulation complements PoolBot's existing screenshot-based browser automation. It provides:
+- Lower latency (no image encoding/decoding)
+- Better for structured data extraction
+- Multi-page task support via Chrome extension
+
+**Integration Approach**: **Browser Route Extension**
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    PoolBot Browser System                    │
+├─────────────────────────────────────────────────────────────┤
+│  Existing Routes    │    New Page Agent Routes               │
+│  ─────────────────  │    ─────────────────────               │
+│  GET  /tabs         │    POST /pageagent/navigate            │
+│  POST /tabs/open    │    POST /pageagent/act                 │
+│  POST /agent/snapshot│   POST /pageagent/extract             │
+│  POST /agent/act    │    POST /pageagent/scroll              │
+│  ...                │    WebSocket /pageagent/session        │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+                    ┌─────────────────┐
+                    │  Page Agent Core │
+                    │  (@page-agent/*) │
+                    └─────────────────┘
+```
+
+**Implementation**:
+- New file: `src/browser/routes/page-agent.ts`
+- Extends existing browser route dispatcher
+- Uses Page Agent's npm packages: `@page-agent/core`, `@page-agent/page-controller`
+- Adds new agent contract methods for text-based interaction
+
+**Agent Tools Generated**:
+```typescript
+{
+  name: "browser_navigate_text",
+  description: "Navigate to URL using text-based DOM approach",
+  parameters: { url: string, waitFor?: string }
+}
+{
+  name: "browser_extract_data",
+  description: "Extract structured data from page using selectors",
+  parameters: { selectors: Record<string, string> }
+}
+{
+  name: "browser_multi_page_task",
+  description: "Execute task across multiple pages",
+  parameters: { steps: Array<{action: string, target: string}> }
+}
+```
+
+### 2. HexStrike AI Integration (Security Platform)
+
+**Rationale**: HexStrike provides 150+ security tools and 12+ AI agents. Integration adds:
+- Penetration testing capabilities
+- CTF solving
+- Bug bounty automation
+- CVE intelligence
+- Compliance scanning
+
+**Integration Approach**: **MCP Client + Virtual Node**
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                  PoolBot Gateway System                      │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │
+│  │  Node Registry│◄───│ HexStrike    │    │  Other Nodes │  │
+│  │               │    │ MCP Client   │    │              │  │
+│  └───────┬───────┘    └──────────────┘    └──────────────┘  │
+│          │                                                  │
+│          ▼                                                  │
+│  ┌──────────────┐                                          │
+│  │ Gateway Methods                                          │
+│  │ ─────────────                                            │
+│  │ hexstrike.scan                                           │
+│  │ hexstrike.exploit                                        │
+│  │ hexstrike.ctf.solve                                      │
+│  │ hexstrike.cve.lookup                                     │
+│  └──────────────┘                                          │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              │ HTTP/MCP
+                              ▼
+                    ┌─────────────────┐
+                    │  HexStrike AI    │
+                    │  Flask API:8888  │
+                    │  FastMCP Server  │
+                    └─────────────────┘
+```
+
+**Implementation**:
+- New file: `src/gateway/server-methods/hexstrike.ts`
+- MCP client wrapper: `src/integrations/mcp/client.ts`
+- Service discovery from HexStrike's OpenAPI spec
+- Python process management (HexStrike requires Python backend)
+
+**Agent Tools Generated** (sample from 150+ tools):
+```typescript
+{
+  name: "security_scan_port",
+  description: "Scan ports using nmap",
+  parameters: { target: string, ports?: string }
+}
+{
+  name: "security_scan_vulnerability",
+  description: "Run vulnerability scan using nuclei",
+  parameters: { target: string, templates?: string[] }
+}
+{
+  name: "security_test_sql_injection",
+  description: "Test for SQL injection using sqlmap",
+  parameters: { url: string, parameters?: string[] }
+}
+{
+  name: "security_solve_ctf",
+  description: "Solve CTF challenge using AI agent",
+  parameters: { challenge_type: string, description: string }
+}
+```
+
+### 3. xyOps Integration (Workflow Automation)
+
+**Rationale**: xyOps adds job scheduling, workflow automation, and monitoring. Integration provides:
+- Scheduled agent tasks
+- Visual workflow editor
+- Incident response automation
+- Server monitoring integration
+
+**Integration Approach**: **Plugin + Gateway Methods**
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                  PoolBot Workflow System                     │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │
+│  │  Cron System │◄───│ xyOps        │───►│ Job Queue    │  │
+│  │              │    │ Integration  │    │              │  │
+│  └──────────────┘    └──────────────┘    └──────────────┘  │
+│                              │                              │
+│                              ▼                              │
+│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │
+│  │ Workflow     │    │ xyOps API    │    │ Monitoring   │  │
+│  │ Definitions  │◄───│ Client       │───►│ Alerts       │  │
+│  └──────────────┘    └──────────────┘    └──────────────┘  │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              │ HTTP/WebSocket
+                              ▼
+                    ┌─────────────────┐
+                    │  xyOps Server    │
+                    │  Node.js API     │
+                    │  MongoDB/Redis   │
+                    └─────────────────┘
+```
+
+**Implementation**:
+- New plugin: `extensions/xyops/` or `src/integrations/xyops/`
+- Gateway methods: `src/gateway/server-methods/xyops.ts`
+- Workflow definition format compatible with xyOps
+- Bidirectional event streaming
+
+**Agent Tools Generated**:
+```typescript
+{
+  name: "workflow_create",
+  description: "Create automated workflow",
+  parameters: { name: string, triggers: Trigger[], actions: Action[] }
+}
+{
+  name: "workflow_schedule",
+  description: "Schedule recurring agent task",
+  parameters: { cron: string, prompt: string, agentId?: string }
+}
+{
+  name: "workflow_monitor",
+  description: "Monitor system and alert on conditions",
+  parameters: { metric: string, threshold: number, alertChannel: string }
+}
+{
+  name: "workflow_incident_response",
+  description: "Execute incident response playbook",
+  parameters: { incident_type: string, severity: string }
+}
+```
+
+## Unified Integration Layer
+
+### New Core Module: `src/integrations/`
+
+```
+src/integrations/
+├── common/
+│   ├── types.ts              # Shared integration types
+│   ├── service-registry.ts   # External service registry
+│   ├── connection-manager.ts # Connection lifecycle management
+│   └── tool-generator.ts     # Auto-generate agent tools from schemas
+├── page-agent/
+│   ├── index.ts
+│   ├── routes.ts
+│   ├── client.ts
+│   └── tools.ts
+├── hexstrike/
+│   ├── index.ts
+│   ├── mcp-client.ts
+│   ├── gateway-methods.ts
+│   ├── tool-adapter.ts
+│   └── process-manager.ts    # Python process management
+├── xyops/
+│   ├── index.ts
+│   ├── client.ts
+│   ├── gateway-methods.ts
+│   ├── workflow-sync.ts
+│   └── plugin.ts
+└── index.ts
+```
+
+### Service Registry
+
+```typescript
+// src/integrations/common/service-registry.ts
+interface ExternalService {
+  id: string;
+  name: string;
+  type: 'browser' | 'security' | 'workflow' | 'custom';
+  status: 'disconnected' | 'connecting' | 'connected' | 'error';
+  capabilities: string[];
+  tools: AnyAgentTool[];
+  gatewayMethods: string[];
+  config: ServiceConfig;
+}
+
+class IntegrationServiceRegistry extends EventEmitter {
+  register(service: ExternalService): void;
+  unregister(serviceId: string): void;
+  get(serviceId: string): ExternalService | undefined;
+  listByType(type: string): ExternalService[];
+  getAllTools(): AnyAgentTool[];
+}
+```
+
+### Configuration Schema
+
+```yaml
+# poolbot.yaml additions
+integrations:
+  page-agent:
+    enabled: true
+    mode: "embedded"  # or "external" for standalone
+    chromeExtension: true
+    defaultProfile: "default"
+    
+  hexstrike:
+    enabled: true
+    mode: "managed"   # PoolBot manages Python process
+    # mode: "external" # Connect to existing instance
+    apiUrl: "http://localhost:8888"
+    mcpEndpoint: "/mcp"
+    tools:
+      allowlist: []     # empty = all allowed
+      denylist: []      # blocked tools
+      
+  xyops:
+    enabled: true
+    apiUrl: "http://localhost:3000"
+    wsUrl: "ws://localhost:3000/ws"
+    syncWorkflows: true
+    bidirectionalEvents: true
+```
+
+## Implementation Phases
+
+### Phase 1: Foundation (Week 1)
+- [ ] Create `src/integrations/` module structure
+- [ ] Implement `IntegrationServiceRegistry`
+- [ ] Add configuration schema and validation
+- [ ] Create common connection manager
+- [ ] Add integration status to `poolbot status`
+
+### Phase 2: Page Agent Integration (Week 2)
+- [ ] Install Page Agent npm packages
+- [ ] Create browser route extensions
+- [ ] Implement text-based DOM agent tools
+- [ ] Add Chrome extension relay integration
+- [ ] Tests and documentation
+
+### Phase 3: HexStrike Integration (Week 3-4)
+- [ ] Implement MCP client wrapper
+- [ ] Create Python process manager
+- [ ] Auto-generate tools from HexStrike schema
+- [ ] Add security-specific gateway methods
+- [ ] Implement tool allowlist/denylist
+- [ ] Tests and documentation
+
+### Phase 4: xyOps Integration (Week 5)
+- [ ] Create xyOps API client
+- [ ] Implement workflow sync
+- [ ] Add bidirectional event streaming
+- [ ] Create workflow agent tools
+- [ ] Tests and documentation
+
+### Phase 5: Polish (Week 6)
+- [ ] Unified CLI commands: `poolbot integrations`
+- [ ] Status dashboard for all integrations
+- [ ] Documentation and examples
+- [ ] Performance optimization
+- [ ] Final testing
+
+## Security Considerations
+
+### Sandboxing
+- HexStrike tools run in isolated Python subprocess
+- Network access restricted to configured endpoints
+- File system access limited to temp directories
+
+### Tool Permissions
+```typescript
+interface ToolPermissionPolicy {
+  service: string;
+  toolPattern: string;  // glob pattern
+  allowed: boolean;
+  requireApproval: boolean;
+  rateLimit?: number;
+}
+```
+
+### Audit Logging
+- All external service calls logged
+- Tool invocations tracked with session correlation
+- Security tool results encrypted at rest
+
+## Benefits
+
+1. **Completeness**: PoolBot becomes a full-stack AI agent platform
+2. **Independence**: Self-hosted, no external API dependencies
+3. **Extensibility**: New integrations follow established patterns
+4. **Maintainability**: Clean separation of concerns
+5. **Performance**: Local execution where possible
+
+## Risk Mitigation
+
+| Risk | Mitigation |
+|------|------------|
+| Python dependency for HexStrike | Optional integration, clear error messages |
+| Security tool misuse | Tool allowlist, approval workflows, audit logging |
+| Performance overhead | Lazy loading, connection pooling, caching |
+| Maintenance burden | Clean interfaces, automated tests, documentation |
+
+## Conclusion
+
+This integration architecture leverages PoolBot's existing plugin system, gateway methods, and node registry to seamlessly incorporate external capabilities. The modular design ensures each integration is optional, well-isolated, and follows established patterns.
+
+The result is a "complete and independent" AI agent platform that can:
+- Browse and interact with web pages (Page Agent)
+- Perform security assessments (HexStrike)
+- Automate workflows and schedules (xyOps)
+- All while maintaining PoolBot's core philosophy of local-first, privacy-respecting AI