@poolzin/pool-bot 2026.3.6 → 2026.3.9

package/docs/INTEGRATION_PLAN.md

@@ -0,0 +1,475 @@
+# PoolBot Integration Plan: External Projects
+
+**Status**: Draft  
+**Date**: 2025-01-09  
+**Goal**: Make PoolBot complete and independent by integrating capabilities from Page Agent, HexStrike AI, and xyOps
+
+---
+
+## Executive Summary
+
+This plan outlines the integration of three external projects into PoolBot to create a comprehensive, self-sufficient automation platform:
+
+1. **Page Agent** → Enhanced browser automation with natural language control
+2. **HexStrike AI** → Security/penetration testing capabilities (150+ security tools)
+3. **xyOps** → Workflow automation, scheduling, and infrastructure monitoring
+
+**Integration Strategy**: Gateway Node protocol for external processes + Plugin extensions for deep integration
+
+---
+
+## 1. Architecture Overview
+
+### Current PoolBot Extension Points
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     PoolBot Core                            │
+├─────────────┬─────────────┬─────────────┬───────────────────┤
+│   Agents    │   Gateway   │    ACP      │     Plugins       │
+│  (skills)   │  (WebSocket)│  (WebSocket)│  (lifecycle hooks)│
+└──────┬──────┴──────┬──────┴──────┬──────┴─────────┬─────────┘
+       │             │             │                │
+       ▼             ▼             ▼                ▼
+┌──────────────┐ ┌─────────┐ ┌──────────┐ ┌──────────────────┐
+│  Subagents   │ │  Nodes  │ │  IDE/CLI │ │  Extensions/     │
+│  (isolated)  │ │(external│ │  clients │ │  Skills          │
+│              │ │processes)│ │          │ │                  │
+└──────────────┘ └─────────┘ └──────────┘ └──────────────────┘
+```
+
+### Integration Approach by Project
+
+| Project | Integration Method | Rationale |
+|---------|-------------------|-----------|
+| **Page Agent** | Gateway Node + Browser Extension | External Node.js process, needs browser control |
+| **HexStrike AI** | Gateway Node (Python) | Python-based, 150+ tools, MCP protocol already used |
+| **xyOps** | Plugin Extension + Gateway Node | Node.js-based, can be deeply integrated |
+
+---
+
+## 2. Page Agent Integration
+
+### 2.1 Overview
+- **Source**: Alibaba's Page Agent (GUI agent for web automation)
+- **Language**: TypeScript/JavaScript
+- **Key Feature**: Natural language control of web pages via DOM manipulation
+- **Current PoolBot Overlap**: `src/browser/`, `src/cli/browser-cli.ts`
+
+### 2.2 Integration Design
+
+```typescript
+// Gateway Node registration
+interface PageAgentNode {
+  capabilities: ['tools.browser.*', 'tools.page.*'];
+  tools: {
+    'browser.navigate': { url: string };
+    'browser.click': { selector: string };
+    'browser.type': { selector: string, text: string };
+    'browser.extract': { selector: string };
+    'page.agent': { instruction: string }; // Natural language
+  };
+}
+```
+
+### 2.3 Implementation Plan
+
+**Phase 1: Gateway Node Wrapper** (Week 1)
+```
+extensions/page-agent-gateway/
+├── src/
+│   ├── node.ts           # Gateway Node WebSocket client
+│   ├── page-agent-bridge.ts  # Adapts Page Agent to PoolBot tools
+│   └── index.ts
+├── package.json
+└── README.md
+```
+
+**Phase 2: Browser Extension Integration** (Week 2)
+- Extend existing `src/browser/` CDP proxy
+- Add Page Agent's DOM-based interaction layer
+- Support multi-page workflows via Chrome extension
+
+**Phase 3: Natural Language Interface** (Week 3)
+```typescript
+// New tool: page.agent
+{
+  name: 'page.agent',
+  description: 'Control web pages using natural language',
+  parameters: {
+    instruction: 'string', // e.g., "Find the pricing page and extract all plans"
+    url: 'string?',
+  }
+}
+```
+
+### 2.4 Value Add
+- Natural language browser control (vs. manual DOM selectors)
+- Multi-page workflow support
+- No screenshot/OCR latency (text-based DOM)
+
+---
+
+## 3. HexStrike AI Integration
+
+### 3.1 Overview
+- **Source**: HexStrike AI (Cybersecurity MCP platform)
+- **Language**: Python
+- **Key Features**: 150+ security tools, 12+ AI agents, autonomous pentesting
+- **Protocol**: FastMCP (Model Context Protocol)
+
+### 3.2 Integration Design
+
+```python
+# HexStrike as Gateway Node (Python)
+class HexStrikeNode:
+    capabilities = ["tools.security.*", "tools.pentest.*"]
+    
+    tools = {
+        "security.scan": {"target": "string", "tools": "string[]"},
+        "security.nmap": {"target": "string", "ports": "string?"},
+        "security.nuclei": {"target": "string", "templates": "string[]?"},
+        "pentest.ctf": {"challenge": "string", "hints": "boolean?"},
+        "pentest.bugbounty": {"target": "string", "scope": "string"},
+    }
+```
+
+### 3.3 Implementation Plan
+
+**Phase 1: MCP-to-Gateway Bridge** (Week 1-2)
+```
+extensions/hexstrike-gateway/
+├── python/
+│   ├── hexstrike_node.py    # FastMCP server + WebSocket client
+│   ├── tool_adapter.py      # Maps HexStrike tools to PoolBot
+│   └── requirements.txt
+├── src/
+│   └── index.ts             # TypeScript type definitions
+└── README.md
+```
+
+**Phase 2: Security Agent** (Week 3)
+```typescript
+// New agent type: security
+{
+  type: 'security',
+  skills: ['hexstrike.pentest', 'hexstrike.scan'],
+  systemPrompt: 'You are a security analyst...',
+}
+```
+
+**Phase 3: Report Integration** (Week 4)
+- Auto-generate security reports
+- Integration with PoolBot's canvas/document system
+- CVE intelligence dashboard
+
+### 3.4 Value Add
+- 150+ security tools accessible via natural language
+- Autonomous penetration testing
+- CTF solver and bug bounty assistance
+- Security reporting integrated with PoolBot workflows
+
+---
+
+## 4. xyOps Integration
+
+### 4.1 Overview
+- **Source**: xyOps (Job scheduling and workflow automation)
+- **Language**: Node.js/TypeScript
+- **Key Features**: Visual workflow editor, monitoring, incident response
+- **License**: BSD (permissive)
+
+### 4.2 Integration Design
+
+```typescript
+// Dual integration: Plugin + Gateway Node
+
+// As Plugin (deep integration)
+interface XyOpsPlugin {
+  onLoad(): void;
+  registerWorkflowEngine(): void;
+  registerScheduler(): void;
+}
+
+// As Gateway Node (external process support)
+interface XyOpsNode {
+  capabilities: ['tools.workflow.*', 'tools.schedule.*', 'tools.monitor.*'];
+  tools: {
+    'workflow.create': { name: string, steps: Step[] };
+    'workflow.run': { id: string, inputs: Record<string, any> };
+    'schedule.cron': { expression: string, workflow: string };
+    'monitor.check': { target: string, interval: number };
+  };
+}
+```
+
+### 4.3 Implementation Plan
+
+**Phase 1: Plugin Foundation** (Week 1-2)
+```
+extensions/xyops/
+├── src/
+│   ├── plugin.ts            # PoolBot plugin lifecycle
+│   ├── workflow/
+│   │   ├── engine.ts        # xyOps workflow engine
+│   │   └── visual-editor.ts # React-based editor
+│   ├── scheduler/
+│   │   └── cron.ts          # Job scheduling
+│   └── monitoring/
+│       └── health-check.ts  # Service monitoring
+├── package.json
+└── README.md
+```
+
+**Phase 2: Gateway Node** (Week 3)
+- Enable external xyOps instances to connect
+- Distributed workflow execution
+- Cross-instance job delegation
+
+**Phase 3: PoolBot Native Integration** (Week 4)
+```typescript
+// New CLI commands
+poolbot workflow create --from-prompt "Every day at 9am, check website health"
+poolbot workflow list
+poolbot workflow run <id>
+poolbot schedule add --workflow <id> --cron "0 9 * * *"
+
+// Agent integration
+{
+  type: 'workflow',
+  skills: ['xyops.create', 'xyops.schedule'],
+}
+```
+
+### 4.4 Value Add
+- Visual workflow builder for non-technical users
+- Scheduled automation (cron-like)
+- Infrastructure monitoring and alerting
+- Incident response with ticketing
+
+---
+
+## 5. Unified Integration Architecture
+
+### 5.1 Common Gateway Node Protocol
+
+All three projects connect via the same Gateway Node protocol:
+
+```typescript
+// src/gateway/nodes/external-node.ts
+interface ExternalNodeConfig {
+  id: string;
+  type: 'page-agent' | 'hexstrike' | 'xyops' | 'custom';
+  endpoint: string;           // WebSocket URL
+  auth: { token: string };
+  capabilities: string[];     // e.g., ['tools.browser.*']
+  healthCheck: { interval: number };
+}
+
+// PoolBot manages node lifecycle
+class NodeManager {
+  async registerNode(config: ExternalNodeConfig): Promise<Node>;
+  async proxyToolCall(nodeId: string, tool: string, params: any): Promise<any>;
+  async monitorHealth(nodeId: string): Promise<HealthStatus>;
+}
+```
+
+### 5.2 Skill Registration
+
+Each integration registers skills that agents can use:
+
+```typescript
+// Skills are automatically registered from Gateway Nodes
+interface NodeSkill {
+  name: string;           // e.g., 'browser.agent'
+  nodeId: string;         // Source node
+  description: string;
+  parameters: JSONSchema;
+}
+
+// Agents can use these skills transparently
+agent.execute({
+  skill: 'browser.agent',
+  params: { instruction: 'Find pricing' }
+});
+```
+
+### 5.3 Security Model
+
+```typescript
+interface NodeSecurity {
+  // Sandboxed execution
+  sandbox: {
+    enabled: boolean;
+    allowedOperations: string[];
+    blockedOperations: string[];
+  };
+  
+  // Capability-based access
+  capabilities: {
+    tools: string[];      // Which tools can be called
+    channels: string[];   // Which channels can access
+    rateLimit: number;    // Calls per minute
+  };
+  
+  // Audit logging
+  audit: {
+    logAllCalls: boolean;
+    retentionDays: number;
+  };
+}
+```
+
+---
+
+## 6. Implementation Roadmap
+
+### Phase 1: Foundation (Weeks 1-2)
+- [ ] Create `extensions/` structure for all three projects
+- [ ] Implement common Gateway Node protocol improvements
+- [ ] Set up build/test infrastructure for extensions
+- [ ] Create Node.js Gateway Node SDK
+
+### Phase 2: Page Agent (Weeks 3-4)
+- [ ] Gateway Node wrapper for Page Agent
+- [ ] Browser extension integration
+- [ ] Natural language tool registration
+- [ ] Documentation and examples
+
+### Phase 3: HexStrike AI (Weeks 5-7)
+- [ ] Python Gateway Node SDK
+- [ ] MCP-to-Gateway adapter
+- [ ] Security agent type
+- [ ] Tool categorization (scan, pentest, ctf, etc.)
+
+### Phase 4: xyOps (Weeks 8-10)
+- [ ] Plugin foundation
+- [ ] Workflow engine integration
+- [ ] Visual editor (React)
+- [ ] Scheduler and monitoring
+
+### Phase 5: Unification (Weeks 11-12)
+- [ ] Unified CLI (`poolbot mods` enhancements)
+- [ ] Cross-project workflows
+- [ ] Documentation and tutorials
+- [ ] Performance optimization
+
+---
+
+## 7. Technical Specifications
+
+### 7.1 Gateway Node Protocol
+
+```typescript
+// WebSocket message format
+interface NodeMessage {
+  id: string;
+  type: 'register' | 'tool_call' | 'tool_result' | 'heartbeat' | 'error';
+  payload: unknown;
+}
+
+// Registration
+interface RegisterPayload {
+  nodeId: string;
+  capabilities: string[];
+  tools: ToolDefinition[];
+  metadata: {
+    name: string;
+    version: string;
+    description: string;
+  };
+}
+
+// Tool call
+interface ToolCallPayload {
+  callId: string;
+  tool: string;
+  parameters: Record<string, unknown>;
+  context: {
+    channelId?: string;
+    agentId?: string;
+    userId?: string;
+  };
+}
+```
+
+### 7.2 File Structure
+
+```
+extensions/
+├── page-agent-gateway/      # Page Agent integration
+│   ├── src/
+│   ├── package.json
+│   └── README.md
+├── hexstrike-gateway/       # HexStrike AI integration
+│   ├── python/
+│   ├── src/
+│   └── README.md
+├── xyops/                   # xyOps integration
+│   ├── src/
+│   ├── package.json
+│   └── README.md
+└── node-sdk/                # Shared Node.js SDK
+    ├── src/
+    └── package.json
+```
+
+### 7.3 Configuration
+
+```yaml
+# poolbot.yaml
+mods:
+  page-agent:
+    enabled: true
+    endpoint: ws://localhost:3001
+    auth:
+      token: ${PAGE_AGENT_TOKEN}
+    
+  hexstrike:
+    enabled: true
+    endpoint: ws://localhost:3002
+    auth:
+      token: ${HEXSTRIKE_TOKEN}
+    
+  xyops:
+    enabled: true
+    mode: plugin  # or 'gateway' for external instance
+    endpoint: ws://localhost:3003
+```
+
+---
+
+## 8. Risk Assessment
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| Python dependency (HexStrike) | Medium | Containerize, optional dependency |
+| Browser extension security | High | Sandboxed execution, CSP |
+| Performance overhead | Medium | Lazy loading, caching |
+| Maintenance burden | Medium | Clear ownership, automated tests |
+| Breaking changes in upstream | Low | Pin versions, abstraction layer |
+
+---
+
+## 9. Success Metrics
+
+- [ ] All 3 projects integrated as Gateway Nodes
+- [ ] 150+ security tools accessible via natural language
+- [ ] Visual workflow editor functional
+- [ ] Browser automation with natural language
+- [ ] Zero breaking changes to existing PoolBot
+- [ ] Documentation complete
+- [ ] Performance: <100ms tool call overhead
+
+---
+
+## 10. Next Steps
+
+1. **Review this plan** with stakeholders
+2. **Create GitHub issues** for each phase
+3. **Set up development branches** for each integration
+4. **Begin Phase 1** (Foundation) implementation
+
+---
+
+**Questions?** See `docs/skills/SKILL.md` for the skills system that enables this integration.

package/docs/INTEGRATION_SUMMARY.md

@@ -0,0 +1,215 @@
+# PoolBot Integration Summary
+
+**Date**: 2025-01-09  
+**Status**: Planning Complete ✅  
+**Next Phase**: Implementation Ready
+
+---
+
+## What We've Accomplished
+
+### Phase 1: Core Skills System ✅
+
+Built a complete modular skill management system in `src/skills/`:
+
+| Component | Purpose | Status |
+|-----------|---------|--------|
+| `types.ts` | Type definitions (agentskills.io compatible) | ✅ Complete |
+| `parser.ts` | SKILL.md parser with YAML frontmatter | ✅ Complete |
+| `registry.ts` | Skills registry with EventEmitter | ✅ Complete |
+| `loader.ts` | Progressive disclosure loader | ✅ Complete |
+| `security.ts` | Security scanner | ✅ Complete |
+| `commands.ts` | CLI commands (`poolbot mods`) | ✅ Complete |
+| `index.ts` | Public API exports | ✅ Complete |
+| `index.test.ts` | 52 comprehensive tests | ✅ All passing |
+
+**Build Status**: ✅ Passes  
+**Test Status**: ✅ 52/52 passing
+
+---
+
+## External Project Analysis
+
+### 1. Page Agent (Alibaba)
+- **Language**: TypeScript/JavaScript
+- **Key Feature**: Natural language browser automation
+- **Integration**: Gateway Node (WebSocket)
+- **Duration**: 2 weeks
+- **Plan**: `docs/integrations/PAGE_AGENT_PLAN.md`
+
+### 2. HexStrike AI
+- **Language**: Python
+- **Key Feature**: 150+ security tools, pentesting, CTF
+- **Integration**: Gateway Node (Python SDK + WebSocket)
+- **Duration**: 3 weeks
+- **Plan**: `docs/integrations/HEXSTRIKE_PLAN.md`
+
+### 3. xyOps
+- **Language**: Node.js/TypeScript
+- **Key Feature**: Workflow automation, scheduling, monitoring
+- **Integration**: Plugin Extension + Gateway Node
+- **Duration**: 3 weeks
+- **Plan**: `docs/integrations/XYOPS_PLAN.md`
+
+---
+
+## Integration Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     PoolBot Core                            │
+├─────────────────────────────────────────────────────────────┤
+│  Skills System (NEW)                                        │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
+│  │   Parser     │  │   Registry   │  │   Loader     │       │
+│  └──────────────┘  └──────────────┘  └──────────────┘       │
+├─────────────────────────────────────────────────────────────┤
+│  Gateway Server (WebSocket JSON-RPC)                        │
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │              Node Manager                           │    │
+│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐          │    │
+│  │  │Page Agent│  │HexStrike │  │  xyOps   │          │    │
+│  │  │  Node    │  │  Node    │  │  Node    │          │    │
+│  │  └──────────┘  └──────────┘  └──────────┘          │    │
+│  └─────────────────────────────────────────────────────┘    │
+├─────────────────────────────────────────────────────────────┤
+│  Plugin Extensions                                          │
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │  xyOps Plugin (Workflow, Schedule, Monitor)         │    │
+│  └─────────────────────────────────────────────────────┘    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Key Design Decisions
+
+### 1. Gateway Node Protocol
+All three projects connect via a unified WebSocket JSON-RPC protocol:
+- **Registration**: Nodes register capabilities and tools
+- **Tool Calls**: PoolBot proxies tool calls to nodes
+- **Health Monitoring**: Automatic node health checks
+- **Security**: Token-based auth, capability scoping
+
+### 2. Dual Integration Modes
+- **Gateway Node**: For external processes (Python, separate instances)
+- **Plugin Extension**: For deep PoolBot integration (Node.js)
+
+### 3. Skill Registration
+Tools from Gateway Nodes automatically register as PoolBot skills:
+```typescript
+// Agent can use external tools transparently
+agent.execute({
+  skill: 'security.nmap',  // From HexStrike
+  params: { target: '192.168.1.1' }
+});
+```
+
+---
+
+## Implementation Roadmap
+
+### Phase 1: Foundation (Weeks 1-2)
+- [ ] Create `extensions/` structure
+- [ ] Implement Node.js Gateway Node SDK
+- [ ] Implement Python Gateway Node SDK
+- [ ] Set up build/test infrastructure
+
+### Phase 2: Page Agent (Weeks 3-4)
+- [ ] Gateway Node wrapper
+- [ ] Browser extension integration
+- [ ] Natural language tool registration
+- [ ] Documentation
+
+### Phase 3: HexStrike AI (Weeks 5-7)
+- [ ] Python Gateway Node SDK
+- [ ] MCP-to-Gateway adapter
+- [ ] Security agent type
+- [ ] Tool categorization
+
+### Phase 4: xyOps (Weeks 8-10)
+- [ ] Plugin foundation
+- [ ] Workflow engine
+- [ ] Visual editor
+- [ ] Scheduler and monitoring
+
+### Phase 5: Unification (Weeks 11-12)
+- [ ] Unified CLI
+- [ ] Cross-project workflows
+- [ ] Documentation
+- [ ] Performance optimization
+
+---
+
+## Value Proposition
+
+After integration, PoolBot will have:
+
+| Capability | Source | Use Case |
+|------------|--------|----------|
+| **Natural Language Browser Control** | Page Agent | Web automation without selectors |
+| **150+ Security Tools** | HexStrike AI | Pentesting, vulnerability scanning |
+| **CTF Solver** | HexStrike AI | Capture The Flag challenges |
+| **Bug Bounty Automation** | HexStrike AI | Automated security hunting |
+| **Visual Workflow Builder** | xyOps | No-code automation |
+| **Scheduled Jobs** | xyOps | Cron-like task scheduling |
+| **Infrastructure Monitoring** | xyOps | Health checks, alerting |
+
+---
+
+## Success Metrics
+
+- [ ] All 3 projects integrated as Gateway Nodes
+- [ ] 150+ security tools accessible via natural language
+- [ ] Visual workflow editor functional
+- [ ] Browser automation with natural language
+- [ ] Zero breaking changes to existing PoolBot
+- [ ] <100ms tool call overhead
+- [ ] Documentation complete
+
+---
+
+## Next Steps
+
+1. **Review Plans**: Review the detailed plans in `docs/integrations/`
+2. **Create GitHub Issues**: Break down into trackable issues
+3. **Start Phase 1**: Begin with Foundation (Node SDKs)
+4. **Set up Branches**: `feat/page-agent`, `feat/hexstrike`, `feat/xyops`
+
+---
+
+## Documents Created
+
+| Document | Purpose |
+|----------|---------|
+| `docs/INTEGRATION_PLAN.md` | Overall integration strategy |
+| `docs/integrations/PAGE_AGENT_PLAN.md` | Page Agent implementation |
+| `docs/integrations/HEXSTRIKE_PLAN.md` | HexStrike AI implementation |
+| `docs/integrations/XYOPS_PLAN.md` | xyOps implementation |
+| `docs/skills/SKILL.md` | Skills system documentation |
+
+---
+
+## Limitations Identified
+
+1. **Python Dependency**: HexStrike requires Python runtime
+   - **Mitigation**: Docker containerization, optional dependency
+
+2. **Browser Extension Security**: Page Agent needs browser access
+   - **Mitigation**: Sandboxed execution, URL allowlists
+
+3. **Performance**: External process communication adds latency
+   - **Mitigation**: Connection pooling, caching, local mode for plugins
+
+---
+
+## Questions for Stakeholders
+
+1. **Priority**: Which integration should we start with?
+2. **Resources**: Do we need additional developers for Python SDK?
+3. **Scope**: Should we implement all 3 or start with 1-2?
+4. **Timeline**: Is the 12-week timeline acceptable?
+
+---
+
+**Ready to proceed with implementation! 🚀**