@poolzin/pool-bot 2026.3.9 → 2026.3.11

package/docs/integrations/INTEGRATION_PLAN.md

@@ -1,424 +1,744 @@
-# PoolBot Integration Architecture Plan
+# PoolBot Integration Plan: Page Agent, HexStrike AI, and xyOps
 
 ## Executive Summary
 
-This document outlines the integration strategy for three external projects into PoolBot to create a "complete and independent" AI agent platform:
+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.
 
-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
+## Projects Overview
 
-## Current PoolBot Architecture Analysis
+### 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
 
-| 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 |
+| 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 Integration Patterns
+### Key Architectural Decisions
 
-```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;
-}
+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
 
-// Pattern 2: Gateway Method Proxy
-interface ServiceProxyHandler {
-  method: string;           // e.g., "pageagent.navigate"
-  handler: GatewayRequestHandler;
-  serviceConfig: ServiceConfig;
-}
+## Integration Architecture
 
-// 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>;
-}
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              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)      │                │
+│         └─────────────────┘ └──────────┘ └─────────────────┘                │
+└─────────────────────────────────────────────────────────────────────────────┘
 ```
 
-## Integration Architecture
+## Detailed Integration Plans
+
+---
+
+## 1. Page Agent Integration
 
-### 1. Page Agent Integration (Browser Enhancement)
+### 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.
 
-**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 Strategy
 
-**Integration Approach**: **Browser Route Extension**
+#### Option A: Browser Driver Plugin (Recommended)
+Implement Page Agent as an alternative browser driver alongside Playwright.
 
+**Files to Create:**
 ```
-┌─────────────────────────────────────────────────────────────┐
-│                    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/*) │
-                    └─────────────────┘
+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
 ```
 
-**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
+**Key Components:**
 
-**Agent Tools Generated**:
+1. **Driver Implementation** (`driver.ts`)
 ```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> }
+// 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
 {
-  name: "browser_multi_page_task",
-  description: "Execute task across multiple pages",
-  parameters: { steps: Array<{action: string, target: string}> }
+  "dependencies": {
+    "@page-agent/core": "^1.x",
+    "@page-agent/page-controller": "^1.x",
+    "poolbot": "workspace:*"
+  }
 }
 ```
 
-### 2. HexStrike AI Integration (Security Platform)
+---
+
+## 2. HexStrike AI Integration
 
-**Rationale**: HexStrike provides 150+ security tools and 12+ AI agents. Integration adds:
-- Penetration testing capabilities
-- CTF solving
-- Bug bounty automation
-- CVE intelligence
-- Compliance scanning
+### 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 Approach**: **MCP Client + Virtual Node**
+### 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:**
 ```
-┌─────────────────────────────────────────────────────────────┐
-│                  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  │
-                    └─────────────────┘
+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
 ```
 
-**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)
+**Key Components:**
 
-**Agent Tools Generated** (sample from 150+ tools):
+1. **MCP Client** (`mcp-client.ts`)
 ```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[] }
+// 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
 {
-  name: "security_solve_ctf",
-  description: "Solve CTF challenge using AI agent",
-  parameters: { challenge_type: string, description: string }
+  "dependencies": {
+    "@anthropic-ai/mcp": "^1.x",
+    "poolbot": "workspace:*"
+  },
+  "optionalDependencies": {
+    "python-bridge": "^1.x"  // For direct Python integration
+  }
 }
 ```
 
-### 3. xyOps Integration (Workflow Automation)
+### 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)
+
+---
 
-**Rationale**: xyOps adds job scheduling, workflow automation, and monitoring. Integration provides:
-- Scheduled agent tasks
-- Visual workflow editor
-- Incident response automation
-- Server monitoring integration
+## 3. xyOps Integration
 
-**Integration Approach**: **Plugin + Gateway Methods**
+### 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:**
 ```
-┌─────────────────────────────────────────────────────────────┐
-│                  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   │
-                    └─────────────────┘
+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
 ```
 
-**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
+**Key Components:**
 
-**Agent Tools Generated**:
+1. **API Client** (`client.ts`)
 ```typescript
-{
-  name: "workflow_create",
-  description: "Create automated workflow",
-  parameters: { name: string, triggers: Trigger[], actions: Action[] }
+// 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>;
 }
-{
-  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 }
+```
+
+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
 {
-  name: "workflow_incident_response",
-  description: "Execute incident response playbook",
-  parameters: { incident_type: string, severity: string }
+  "dependencies": {
+    "xyops": "^1.x",  // If published to npm
+    "node-cron": "^3.x",
+    "poolbot": "workspace:*"
+  }
 }
 ```
 
-## Unified Integration Layer
+---
 
-### New Core Module: `src/integrations/`
+## Cross-Cutting Concerns
 
-```
-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
+### 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
 ```
 
-### Service Registry
+### 2. Shared Configuration
 
-```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;
-}
+All integrations use PoolBot's config system:
 
-class IntegrationServiceRegistry extends EventEmitter {
-  register(service: ExternalService): void;
-  unregister(serviceId: string): void;
-  get(serviceId: string): ExternalService | undefined;
-  listByType(type: string): ExternalService[];
-  getAllTools(): AnyAgentTool[];
+```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}"
+    }
+  }
 }
 ```
 
-### 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
+### 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
+  });
+});
 ```
 
-## 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
+### 4. Shared Skills
 
-## Security Considerations
+Cross-project skills that combine capabilities:
 
-### Sandboxing
-- HexStrike tools run in isolated Python subprocess
-- Network access restricted to configured endpoints
-- File system access limited to temp directories
+```markdown
+---
+id: automated-security-audit
+name: Automated Security Audit
+version: 1.0.0
+capabilities:
+  - browser
+  - security
+  - workflow
+---
 
-### Tool Permissions
-```typescript
-interface ToolPermissionPolicy {
-  service: string;
-  toolPattern: string;  // glob pattern
-  allowed: boolean;
-  requireApproval: boolean;
-  rateLimit?: number;
-}
+# 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
 ```
 
-### Audit Logging
-- All external service calls logged
-- Tool invocations tracked with session correlation
-- Security tool results encrypted at rest
+---
+
+## 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 |
 
-## 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 Assessment
 
-## Risk Mitigation
+| 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 |
 
-| 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.
+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
+```
 
-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
+### No Changes Required
+- Core agent system
+- Gateway server
+- ACP protocol
+- Existing plugin system
+- Memory/embeddings system
+- Browser system (Playwright driver)