@poolzin/pool-bot 2026.3.7 → 2026.3.10

package/docs/integrations/INTEGRATION_PLAN.md

@@ -0,0 +1,744 @@
+# PoolBot Integration Plan: Page Agent, HexStrike AI, and xyOps
+
+## Executive Summary
+
+This document outlines a professional integration strategy for three external projects into PoolBot to create a **complete and independent** AI-powered automation platform. The integration follows PoolBot's existing plugin architecture, maintains backward compatibility, and adds significant new capabilities.
+
+## Projects Overview
+
+### 1. Page Agent (Alibaba Research)
+- **Type**: Browser automation agent
+- **Language**: TypeScript/JavaScript
+- **Key Features**: Text-based DOM manipulation, multi-page workflows, Chrome extension
+- **Integration Value**: Enhanced browser automation beyond current Playwright-based system
+
+### 2. HexStrike AI
+- **Type**: Cybersecurity platform
+- **Language**: Python (FastMCP server)
+- **Key Features**: 150+ security tools, 12+ AI agents, autonomous pentesting
+- **Integration Value**: Security scanning, penetration testing, vulnerability assessment
+
+### 3. xyOps
+- **Type**: Workflow automation & monitoring
+- **Language**: Node.js
+- **Key Features**: Visual workflow editor, job scheduling, alerting, incident response
+- **Integration Value**: Infrastructure automation, monitoring, incident management
+
+## PoolBot Architecture Analysis
+
+### Existing Systems
+
+| Component | Current Implementation | Integration Point |
+|-----------|----------------------|-------------------|
+| **Browser** | Playwright-based (`src/browser/`) | Page Agent as alternative driver |
+| **Plugins** | Full plugin system (`src/plugins/`) | All 3 projects as plugins |
+| **ACP** | Agent Communication Protocol (`src/acp/`) | Extend for external tool servers |
+| **MCP** | Partial via mcporter (`src/memory/qmd-manager.ts`) | Full MCP client support |
+| **Skills** | New skill system (`src/skills/`) | Project-specific skills |
+| **Gateway** | WebSocket gateway (`src/gateway/`) | Route external requests |
+| **CLI** | Comprehensive CLI (`src/cli/`) | New commands for integrations |
+
+### Key Architectural Decisions
+
+1. **Plugin-First Approach**: All integrations implemented as PoolBot plugins
+2. **MCP Bridge**: HexStrike AI exposed via MCP protocol
+3. **Skill Wrappers**: Each project wrapped in PoolBot skill format
+4. **No Core Changes**: Additive only - no modifications to existing code
+
+## Integration Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              PoolBot Core                                    │
+├─────────────────────────────────────────────────────────────────────────────┤
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
+│  │   Skills    │  │   Plugins   │  │    ACP      │  │       Gateway       │ │
+│  │   System    │  │   System    │  │   Protocol  │  │      Server         │ │
+│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘ │
+│         │                │                │                    │            │
+│         └────────────────┴────────────────┴────────────────────┘            │
+│                                    │                                        │
+│                         Integration Layer                                   │
+│                    ┌───────────────┼───────────────┐                        │
+│                    ▼               ▼               ▼                        │
+│         ┌─────────────────┐ ┌──────────┐ ┌─────────────────┐                │
+│         │  Page Agent     │ │ HexStrike│ │     xyOps       │                │
+│         │  Plugin         │ │ AI Plugin│ │    Plugin       │                │
+│         │                 │ │          │ │                 │                │
+│         │ • Browser driver│ │• MCP     │ │• Workflow       │                │
+│         │ • DOM agent     │ │  client  │ │  scheduler      │                │
+│         │ • Multi-page    │ │• Security│ │• Monitoring     │                │
+│         │   workflows     │ │  tools   │ │• Alerting       │                │
+│         └────────┬────────┘ └────┬─────┘ └────────┬────────┘                │
+│                  │               │                │                         │
+│                  ▼               ▼                ▼                         │
+│         ┌─────────────────┐ ┌──────────┐ ┌─────────────────┐                │
+│         │ Page Agent Core │ │HexStrike │ │   xyOps Core    │                │
+│         │ (npm package)   │ │Server    │ │  (Node.js)      │                │
+│         └─────────────────┘ └──────────┘ └─────────────────┘                │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Detailed Integration Plans
+
+---
+
+## 1. Page Agent Integration
+
+### Overview
+Page Agent provides text-based browser automation with natural language understanding. Unlike PoolBot's current Playwright-based browser which requires precise selectors, Page Agent uses AI to understand and interact with web pages semantically.
+
+### Integration Strategy
+
+#### Option A: Browser Driver Plugin (Recommended)
+Implement Page Agent as an alternative browser driver alongside Playwright.
+
+**Files to Create:**
+```
+extensions/page-agent/
+├── package.json
+├── poolbot.plugin.json
+├── src/
+│   ├── index.ts              # Plugin entry point
+│   ├── driver.ts             # Page Agent driver implementation
+│   ├── tools.ts              # Agent tools for browser control
+│   ├── skills/
+│   │   ├── browser-control.md
+│   │   ├── form-filling.md
+│   │   └── data-extraction.md
+│   └── types.ts
+├── README.md
+└── tsconfig.json
+```
+
+**Key Components:**
+
+1. **Driver Implementation** (`driver.ts`)
+```typescript
+// Wraps @page-agent/core for PoolBot integration
+export class PageAgentDriver implements BrowserDriver {
+  private agent: PageAgentCore;
+  
+  async navigate(url: string): Promise<void>;
+  async act(instruction: string): Promise<ActionResult>;
+  async extract(query: string): Promise<ExtractResult>;
+  async observe(): Promise<PageObservation>;
+}
+```
+
+2. **Agent Tools** (`tools.ts`)
+```typescript
+// Tools registered with PoolBot agent system
+export const pageAgentTools: AnyAgentTool[] = [
+  {
+    name: "browser_navigate",
+    description: "Navigate to a URL using natural language understanding",
+    parameters: z.object({ url: z.string(), goal: z.string().optional() }),
+    execute: async ({ url, goal }) => { /* ... */ }
+  },
+  {
+    name: "browser_act",
+    description: "Perform an action on the current page (click, type, scroll)",
+    parameters: z.object({ instruction: z.string() }),
+    execute: async ({ instruction }) => { /* ... */ }
+  },
+  {
+    name: "browser_extract",
+    description: "Extract data from the page using natural language query",
+    parameters: z.object({ query: z.string() }),
+    execute: async ({ query }) => { /* ... */ }
+  }
+];
+```
+
+3. **Skills** (in `skills/`)
+   - `browser-control.md`: Core browser navigation and control
+   - `form-filling.md`: Intelligent form detection and filling
+   - `data-extraction.md`: Structured data extraction from web pages
+
+#### Option B: Standalone Service
+Run Page Agent as a separate service that PoolBot communicates with via HTTP.
+
+**Pros:**
+- Isolated from PoolBot process
+- Can use different Node.js version if needed
+- Easier to update independently
+
+**Cons:**
+- Additional service management overhead
+- Network latency
+- More complex deployment
+
+### Implementation Phases
+
+#### Phase 1: Basic Integration (Week 1-2)
+- [ ] Create plugin structure
+- [ ] Implement basic driver wrapper
+- [ ] Add 3 core tools (navigate, act, extract)
+- [ ] Create 1 skill (browser-control)
+- [ ] Write tests
+
+#### Phase 2: Advanced Features (Week 3-4)
+- [ ] Multi-page workflow support
+- [ ] Chrome extension integration
+- [ ] Session persistence
+- [ ] Additional skills (form-filling, data-extraction)
+- [ ] Documentation
+
+#### Phase 3: Optimization (Week 5-6)
+- [ ] Performance tuning
+- [ ] Error recovery
+- [ ] Integration with existing PoolBot browser profiles
+- [ ] CLI commands for Page Agent management
+
+### Dependencies
+```json
+{
+  "dependencies": {
+    "@page-agent/core": "^1.x",
+    "@page-agent/page-controller": "^1.x",
+    "poolbot": "workspace:*"
+  }
+}
+```
+
+---
+
+## 2. HexStrike AI Integration
+
+### Overview
+HexStrike AI is a Python-based cybersecurity platform with 150+ tools and 12+ AI agents. It uses FastMCP protocol for AI agent communication, making it ideal for integration via PoolBot's MCP support.
+
+### Integration Strategy
+
+#### MCP Client Bridge (Recommended)
+Expose HexStrike AI as an MCP server that PoolBot can communicate with.
+
+**Architecture:**
+```
+PoolBot → MCP Client → HexStrike AI Server → Security Tools
+```
+
+**Files to Create:**
+```
+extensions/hexstrike-ai/
+├── package.json
+├── poolbot.plugin.json
+├── src/
+│   ├── index.ts              # Plugin entry point
+│   ├── mcp-client.ts         # MCP client implementation
+│   ├── tools.ts              # Security tool wrappers
+│   ├── skills/
+│   │   ├── reconnaissance.md
+│   │   ├── vulnerability-scanning.md
+│   │   ├── penetration-testing.md
+│   │   └── ctf-solving.md
+│   └── types.ts
+├── python-bridge/            # Optional: Python bridge for direct integration
+│   ├── bridge.py
+│   └── requirements.txt
+├── README.md
+└── tsconfig.json
+```
+
+**Key Components:**
+
+1. **MCP Client** (`mcp-client.ts`)
+```typescript
+// Communicates with HexStrike AI FastMCP server
+export class HexStrikeMcpClient {
+  private serverUrl: string;
+  private tools: Map<string, McpTool>;
+  
+  async connect(): Promise<void>;
+  async listTools(): Promise<McpTool[]>;
+  async callTool(name: string, params: unknown): Promise<ToolResult>;
+  async scanTarget(target: string, scanType: ScanType): Promise<ScanResult>;
+}
+```
+
+2. **Security Tools** (`tools.ts`)
+```typescript
+// High-level security tools for PoolBot agents
+export const hexstrikeTools: AnyAgentTool[] = [
+  {
+    name: "security_scan",
+    description: "Perform security scan on a target",
+    parameters: z.object({ 
+      target: z.string(), 
+      scanType: z.enum(["port", "vulnerability", "web", "full"])
+    }),
+    execute: async ({ target, scanType }) => { /* ... */ }
+  },
+  {
+    name: "pentest_agent",
+    description: "Deploy AI pentesting agent for autonomous security testing",
+    parameters: z.object({ 
+      target: z.string(),
+      scope: z.string(),
+      duration: z.number().optional()
+    }),
+    execute: async ({ target, scope, duration }) => { /* ... */ }
+  },
+  {
+    name: "cve_lookup",
+    description: "Look up CVE information and available exploits",
+    parameters: z.object({ cveId: z.string() }),
+    execute: async ({ cveId }) => { /* ... */ }
+  },
+  {
+    name: "exploit_generate",
+    description: "Generate exploit code for a vulnerability",
+    parameters: z.object({ 
+      vulnerability: z.string(),
+      target: z.string()
+    }),
+    execute: async ({ vulnerability, target }) => { /* ... */ }
+  }
+];
+```
+
+3. **Skills** (in `skills/`)
+   - `reconnaissance.md`: Network and target reconnaissance
+   - `vulnerability-scanning.md`: Automated vulnerability assessment
+   - `penetration-testing.md`: Ethical hacking and pentesting workflows
+   - `ctf-solving.md`: Capture The Flag automation
+
+#### Alternative: Direct Python Bridge
+For deeper integration, create a Python bridge that runs HexStrike AI tools directly.
+
+**Pros:**
+- No separate server needed
+- Lower latency
+- Direct access to all tools
+
+**Cons:**
+- Python dependency management
+- Process isolation concerns
+- More complex error handling
+
+### Implementation Phases
+
+#### Phase 1: MCP Integration (Week 1-2)
+- [ ] Create MCP client for HexStrike AI
+- [ ] Implement tool discovery
+- [ ] Add 4 core security tools
+- [ ] Create 2 skills (reconnaissance, vulnerability-scanning)
+- [ ] Configuration management
+
+#### Phase 2: Advanced Features (Week 3-4)
+- [ ] Autonomous pentesting agent integration
+- [ ] CTF solver integration
+- [ ] Report generation
+- [ ] Additional skills (pentesting, ctf-solving)
+- [ ] Security-focused CLI commands
+
+#### Phase 3: Hardening (Week 5-6)
+- [ ] Security scanning of integration itself
+- [ ] Permission system for security tools
+- [ ] Audit logging
+- [ ] Documentation and usage guidelines
+
+### Dependencies
+```json
+{
+  "dependencies": {
+    "@anthropic-ai/mcp": "^1.x",
+    "poolbot": "workspace:*"
+  },
+  "optionalDependencies": {
+    "python-bridge": "^1.x"  // For direct Python integration
+  }
+}
+```
+
+### Security Considerations
+- All security tools require explicit user authorization
+- Audit logging for all security operations
+- Scope limitations to prevent unauthorized scanning
+- Safe defaults (dry-run mode for destructive operations)
+
+---
+
+## 3. xyOps Integration
+
+### Overview
+xyOps is a Node.js-based workflow automation, job scheduling, and monitoring platform. It provides visual workflow editing, alerting, and incident response capabilities.
+
+### Integration Strategy
+
+#### Plugin + Service Integration (Recommended)
+Implement xyOps as a PoolBot plugin that can optionally integrate with a running xyOps instance.
+
+**Files to Create:**
+```
+extensions/xyops/
+├── package.json
+├── poolbot.plugin.json
+├── src/
+│   ├── index.ts              # Plugin entry
+│   ├── client.ts             # xyOps API client
+│   ├── scheduler.ts          # Job scheduling integration
+│   ├── workflows.ts          # Workflow management
+│   ├── monitoring.ts         # Monitoring integration
+│   ├── tools.ts              # Agent tools
+│   ├── skills/
+│   │   ├── workflow-automation.md
+│   │   ├── job-scheduling.md
+│   │   ├── monitoring.md
+│   │   └── incident-response.md
+│   └── types.ts
+├── embedded-server/          # Optional: embedded xyOps server
+│   └── index.ts
+├── README.md
+└── tsconfig.json
+```
+
+**Key Components:**
+
+1. **API Client** (`client.ts`)
+```typescript
+// Client for xyOps REST API
+export class XyOpsClient {
+  private baseUrl: string;
+  private apiKey: string;
+  
+  async createWorkflow(definition: WorkflowDefinition): Promise<Workflow>;
+  async scheduleJob(job: JobDefinition): Promise<ScheduledJob>;
+  async getMetrics(): Promise<SystemMetrics>;
+  async createAlert(rule: AlertRule): Promise<Alert>;
+  async createTicket(incident: Incident): Promise<Ticket>;
+}
+```
+
+2. **Scheduler Integration** (`scheduler.ts`)
+```typescript
+// Integrates with PoolBot's cron system
+export class XyOpsScheduler {
+  async scheduleAgentTask(
+    task: string,
+    schedule: CronExpression,
+    params: unknown
+  ): Promise<ScheduledTask>;
+  
+  async listScheduledTasks(): Promise<ScheduledTask[]>;
+  async cancelTask(taskId: string): Promise<void>;
+}
+```
+
+3. **Agent Tools** (`tools.ts`)
+```typescript
+// Workflow and automation tools
+export const xyopsTools: AnyAgentTool[] = [
+  {
+    name: "workflow_create",
+    description: "Create a new automated workflow",
+    parameters: z.object({
+      name: z.string(),
+      steps: z.array(z.object({
+        action: z.string(),
+        params: z.record(z.unknown())
+      })),
+      triggers: z.array(z.string()).optional()
+    }),
+    execute: async ({ name, steps, triggers }) => { /* ... */ }
+  },
+  {
+    name: "job_schedule",
+    description: "Schedule a recurring job",
+    parameters: z.object({
+      name: z.string(),
+      schedule: z.string(),  // Cron expression
+      task: z.string(),
+      params: z.record(z.unknown()).optional()
+    }),
+    execute: async ({ name, schedule, task, params }) => { /* ... */ }
+  },
+  {
+    name: "monitor_setup",
+    description: "Set up monitoring for a service or metric",
+    parameters: z.object({
+      target: z.string(),
+      metric: z.string(),
+      threshold: z.number(),
+      alertChannel: z.string()
+    }),
+    execute: async ({ target, metric, threshold, alertChannel }) => { /* ... */ }
+  },
+  {
+    name: "incident_create",
+    description: "Create an incident ticket",
+    parameters: z.object({
+      title: z.string(),
+      description: z.string(),
+      severity: z.enum(["low", "medium", "high", "critical"]),
+      assignee: z.string().optional()
+    }),
+    execute: async ({ title, description, severity, assignee }) => { /* ... */ }
+  }
+];
+```
+
+4. **Skills** (in `skills/`)
+   - `workflow-automation.md`: Creating and managing automated workflows
+   - `job-scheduling.md`: Cron jobs and scheduled tasks
+   - `monitoring.md`: System and service monitoring
+   - `incident-response.md`: Incident management and ticketing
+
+#### Embedded Server Option
+xyOps can also be embedded as a service within PoolBot:
+
+```typescript
+// In embedded-server/index.ts
+export function startEmbeddedXyOps(config: XyOpsConfig): Promise<XyOpsServer>;
+```
+
+### Implementation Phases
+
+#### Phase 1: API Integration (Week 1-2)
+- [ ] Create xyOps API client
+- [ ] Implement workflow CRUD operations
+- [ ] Add 4 core tools (workflow_create, job_schedule, monitor_setup, incident_create)
+- [ ] Create 2 skills (workflow-automation, job-scheduling)
+- [ ] Configuration management
+
+#### Phase 2: Embedded Features (Week 3-4)
+- [ ] Optional embedded xyOps server
+- [ ] Integration with PoolBot's cron system
+- [ ] Monitoring dashboard
+- [ ] Additional skills (monitoring, incident-response)
+- [ ] CLI commands for workflow management
+
+#### Phase 3: Advanced Automation (Week 5-6)
+- [ ] Visual workflow editor integration
+- [ ] AI-generated workflows
+- [ ] Cross-system automation (trigger actions in other integrations)
+- [ ] Advanced monitoring and alerting
+
+### Dependencies
+```json
+{
+  "dependencies": {
+    "xyops": "^1.x",  // If published to npm
+    "node-cron": "^3.x",
+    "poolbot": "workspace:*"
+  }
+}
+```
+
+---
+
+## Cross-Cutting Concerns
+
+### 1. Unified CLI Experience
+
+New CLI commands for managing integrations:
+
+```bash
+# Page Agent
+poolbot browser agent <url> "find the login button and click it"
+poolbot browser extract <url> "get all product prices"
+
+# HexStrike AI
+poolbot security scan <target> --type=full
+poolbot security pentest <target> --scope=web
+poolbot security cve CVE-2024-XXXX
+
+# xyOps
+poolbot workflow create --name="Daily Backup" --from-file=backup.yaml
+poolbot workflow run <workflow-id>
+poolbot schedule create --cron="0 2 * * *" --task="backup"
+poolbot monitor status
+```
+
+### 2. Shared Configuration
+
+All integrations use PoolBot's config system:
+
+```json
+{
+  "integrations": {
+    "pageAgent": {
+      "enabled": true,
+      "driver": "page-agent",
+      "config": {
+        "model": "gpt-4",
+        "maxActions": 50
+      }
+    },
+    "hexstrike": {
+      "enabled": true,
+      "serverUrl": "http://localhost:8888",
+      "apiKey": "${HEXSTRIKE_API_KEY}",
+      "allowedTargets": ["*.internal.company.com"]
+    },
+    "xyops": {
+      "enabled": true,
+      "serverUrl": "http://localhost:3000",
+      "embedded": false,
+      "webhookSecret": "${XYOPS_WEBHOOK_SECRET}"
+    }
+  }
+}
+```
+
+### 3. Event Integration
+
+Integrations can emit and listen to events:
+
+```typescript
+// Example: xyOps workflow triggers Page Agent action
+plugin.on("workflow:step:execute", async (event) => {
+  if (event.step.type === "browser_action") {
+    const result = await pageAgent.execute(event.step.instruction);
+    return { result };
+  }
+});
+
+// Example: HexStrike finding triggers xyOps incident
+plugin.on("security:finding:critical", async (event) => {
+  await xyops.createIncident({
+    title: `Critical vulnerability found: ${event.cve}`,
+    severity: "critical",
+    description: event.details
+  });
+});
+```
+
+### 4. Shared Skills
+
+Cross-project skills that combine capabilities:
+
+```markdown
+---
+id: automated-security-audit
+name: Automated Security Audit
+version: 1.0.0
+capabilities:
+  - browser
+  - security
+  - workflow
+---
+
+# Automated Security Audit
+
+Perform comprehensive security audits combining browser automation,
+vulnerability scanning, and automated reporting.
+
+## Workflow
+
+1. Use Page Agent to navigate and map the target application
+2. Use HexStrike AI to scan for vulnerabilities
+3. Use xyOps to schedule recurring scans
+4. Generate and deliver audit reports
+```
+
+---
+
+## Implementation Timeline
+
+### Phase 1: Foundation (Weeks 1-2)
+- [ ] Set up plugin development infrastructure
+- [ ] Implement MCP client improvements for HexStrike
+- [ ] Create shared integration utilities
+- [ ] Begin Page Agent basic integration
+
+### Phase 2: Core Integrations (Weeks 3-6)
+- [ ] Complete Page Agent integration
+- [ ] Complete HexStrike AI integration
+- [ ] Begin xyOps integration
+- [ ] Write comprehensive tests
+
+### Phase 3: Advanced Features (Weeks 7-10)
+- [ ] Complete xyOps integration
+- [ ] Implement cross-integration features
+- [ ] Add CLI commands
+- [ ] Create documentation
+
+### Phase 4: Polish & Release (Weeks 11-12)
+- [ ] Performance optimization
+- [ ] Security audit
+- [ ] User documentation
+- [ ] Release candidate
+
+---
+
+## Success Metrics
+
+| Metric | Target |
+|--------|--------|
+| Page Agent tool coverage | 90% of core features |
+| HexStrike AI tool coverage | 80% of security tools |
+| xyOps API coverage | 100% of core APIs |
+| Test coverage | >70% for each integration |
+| Documentation completeness | 100% of public APIs |
+| CLI command coverage | All major features |
+
+---
+
+## Risk Assessment
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| Page Agent API changes | Medium | Medium | Version pinning, abstraction layer |
+| HexStrike Python deps | Medium | High | Containerization, optional integration |
+| xyOps breaking changes | Low | Medium | API versioning, client abstraction |
+| Security tool misuse | Low | High | Permission system, audit logging |
+| Performance degradation | Medium | Medium | Lazy loading, caching, profiling |
+
+---
+
+## Conclusion
+
+This integration plan provides a roadmap for making PoolBot a complete and independent AI automation platform. By leveraging the existing plugin architecture and following PoolBot's design principles, these integrations will:
+
+1. **Enhance capabilities** without breaking existing functionality
+2. **Maintain independence** through optional, modular integrations
+3. **Follow best practices** for security, testing, and documentation
+4. **Enable new use cases** across browser automation, security, and infrastructure
+
+The phased approach allows for incremental delivery and user feedback, ensuring each integration meets production quality standards before moving to the next phase.
+
+---
+
+## Appendix: File Locations
+
+### New Files
+```
+extensions/page-agent/
+  (see structure above)
+
+extensions/hexstrike-ai/
+  (see structure above)
+
+extensions/xyops/
+  (see structure above)
+
+src/skills/integrations/
+  ├── page-agent/
+  │   └── *.md
+  ├── hexstrike/
+  │   └── *.md
+  └── xyops/
+      └── *.md
+```
+
+### Modified Files (minimal)
+```
+src/plugins/manifest.ts
+  - Add integration metadata fields
+
+src/config/schema.ts
+  - Add integration config sections
+
+src/cli/index.ts
+  - Register new CLI commands
+```
+
+### No Changes Required
+- Core agent system
+- Gateway server
+- ACP protocol
+- Existing plugin system
+- Memory/embeddings system
+- Browser system (Playwright driver)