linkedin-automation-cli 1.0.0

package/docs/superpowers/plans/2026-03-14-page-agent-plan.md

@@ -0,0 +1,1598 @@
+# Page Agent Implementation Plan
+
+> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Implement DOM-text based LinkedIn automation using Claude API, replacing selector-based approach with LLM-powered agent for connect and message commands.
+
+**Architecture:** Extract semantic DOM representation from LinkedIn pages, send to Claude API for action planning, execute actions via Playwright. Uses accessibility-first extraction with element IDs mapped to bounding boxes for clicking.
+
+**Tech Stack:** TypeScript, Playwright, Claude API (via Dashscope), Zod for validation
+
+---
+
+## File Structure
+
+```
+src/
+├── agent/
+│   ├── index.ts              # Public exports
+│   ├── types.ts              # Core type definitions
+│   ├── dom-extractor.ts      # DOM to structured text extraction
+│   ├── claude-client.ts      # Claude API client via Dashscope
+│   ├── action-executor.ts    # Execute action plans with Playwright
+│   ├── page-agent.ts         # Main orchestrator
+│   └── prompts.ts            # LLM prompt templates
+├── cli/
+│   └── agent-commands.ts     # New CLI commands
+└── linkedin/
+    └── (existing - keep for reference)
+```
+
+---
+
+## Chunk 1: Types and Interfaces
+
+**Purpose:** Define all TypeScript interfaces and types for the agent system.
+
+**Files:**
+- Create: `src/agent/types.ts`
+
+---
+
+### Task 1: Define DOM Types
+
+- [ ] **Step 1: Write types for DOM representation**
+
+Create `src/agent/types.ts`:
+
+```typescript
+/**
+ * Bounding box for an element on the page
+ */
+export interface BoundingBox {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * Represents a single DOM element extracted from the page
+ */
+export interface DOMElement {
+  /** Unique identifier assigned during extraction */
+  id: string;
+  /** HTML tag name */
+  tag: string;
+  /** ARIA role if present */
+  role?: string;
+  /** ARIA label if present */
+  ariaLabel?: string;
+  /** Visible text content */
+  text: string;
+  /** Element type for interactive elements */
+  type?: 'button' | 'link' | 'input' | 'textarea' | 'select' | 'checkbox';
+  /** Current value (for form inputs) */
+  value?: string;
+  /** Whether element is visible */
+  visible: boolean;
+  /** Whether element is enabled */
+  enabled: boolean;
+  /** Bounding box for click coordinates */
+  bbox: BoundingBox;
+}
+
+/**
+ * Complete DOM representation of a page
+ */
+export interface DOMRepresentation {
+  /** Current URL */
+  url: string;
+  /** Page title */
+  title: string;
+  /** All extracted elements */
+  elements: DOMElement[];
+  /** Extracted status/info from the page */
+  metadata: PageMetadata;
+}
+
+/**
+ * Metadata extracted from LinkedIn pages
+ */
+export interface PageMetadata {
+  /** Type of page */
+  pageType: 'profile' | 'messaging' | 'feed' | 'other';
+  /** Profile name (if on profile page) */
+  profileName?: string;
+  /** Profile headline/title (if on profile page) */
+  profileTitle?: string;
+  /** Connection status with profile owner */
+  connectionState?: 'connected' | 'pending' | 'not_connected' | 'unknown';
+  /** Any error or status messages visible */
+  statusMessages: string[];
+}
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add src/agent/types.ts
+git commit -m "feat(agent): add DOM representation types"
+```
+
+---
+
+### Task 2: Define Action Types
+
+- [ ] **Step 1: Add action type definitions to types.ts**
+
+Add to `src/agent/types.ts`:
+
+```typescript
+/**
+ * Click action - click an element by ID
+ */
+export interface ClickAction {
+  type: 'click';
+  elementId: string;
+  description: string;
+}
+
+/**
+ * Type action - enter text into an input
+ */
+export interface TypeAction {
+  type: 'type';
+  elementId: string;
+  text: string;
+  description: string;
+}
+
+/**
+ * Wait action - pause execution
+ */
+export interface WaitAction {
+  type: 'wait';
+  durationMs: number;
+  description: string;
+}
+
+/**
+ * Navigate action - go to a URL
+ */
+export interface NavigateAction {
+  type: 'navigate';
+  url: string;
+  description: string;
+}
+
+/**
+ * Union type of all possible actions
+ */
+export type Action = ClickAction | TypeAction | WaitAction | NavigateAction;
+
+/**
+ * Complete action plan from LLM
+ */
+export interface ActionPlan {
+  /** Reasoning for the plan */
+  reasoning: string;
+  /** Expected outcome after executing */
+  expectedOutcome: string;
+  /** Actions to execute */
+  actions: Action[];
+  /** Current status */
+  status: 'in_progress' | 'completed' | 'error';
+  /** Error message if status is error */
+  error?: string;
+}
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add src/agent/types.ts
+git commit -m "feat(agent): add action type definitions"
+```
+
+---
+
+### Task 3: Define Client and Task Types
+
+- [ ] **Step 1: Add remaining type definitions**
+
+Add to `src/agent/types.ts`:
+
+```typescript
+/**
+ * Configuration for Claude API client
+ */
+export interface ClaudeClientConfig {
+  /** API key for Dashscope */
+  apiKey: string;
+  /** Base URL for API */
+  baseUrl: string;
+  /** Model to use */
+  model: string;
+}
+
+/**
+ * Context for action planning
+ */
+export interface ActionContext {
+  /** Previous actions taken */
+  previousActions: ExecutedAction[];
+  /** User's goal */
+  goal: string;
+  /** Number of retries so far */
+  retryCount: number;
+}
+
+/**
+ * Record of an executed action
+ */
+export interface ExecutedAction {
+  action: Action;
+  success: boolean;
+  timestamp: number;
+  error?: string;
+}
+
+/**
+ * Task for the agent to execute
+ */
+export interface Task {
+  /** What the user wants to accomplish */
+  goal: string;
+  /** Target LinkedIn profile URL (for connect/message tasks) */
+  profileUrl?: string;
+  /** Note to include (for connection requests) */
+  note?: string;
+  /** Message to send (for messaging) */
+  message?: string;
+}
+
+/**
+ * Result of executing a task
+ */
+export interface TaskResult {
+  success: boolean;
+  message: string;
+  actionsTaken: Action[];
+  finalUrl?: string;
+}
+
+/**
+ * Connection-specific result
+ */
+export interface ConnectionResult extends TaskResult {
+  sent: boolean;
+  pending: boolean;
+  alreadyConnected?: boolean;
+}
+
+/**
+ * Message-specific result
+ */
+export interface MessageResult extends TaskResult {
+  sent: boolean;
+}
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add src/agent/types.ts
+git commit -m "feat(agent): add client and task type definitions"
+```
+
+---
+
+## Chunk 2: DOM Extractor
+
+**Purpose:** Extract semantic DOM representation from LinkedIn pages using Playwright.
+
+**Files:**
+- Create: `src/agent/dom-extractor.ts`
+- Test: `src/agent/dom-extractor.test.ts`
+
+---
+
+### Task 4: Create DOM Extractor Core
+
+- [ ] **Step 1: Write the failing test**
+
+Create `src/agent/dom-extractor.test.ts`:
+
+```typescript
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { DOMExtractor } from './dom-extractor';
+import type { Page } from 'playwright';
+
+describe('DOMExtractor', () => {
+  let extractor: DOMExtractor;
+  let mockPage: Partial<Page>;
+
+  beforeEach(() => {
+    extractor = new DOMExtractor();
+    mockPage = {
+      url: vi.fn().mockReturnValue('https://www.linkedin.com/in/test'),
+      title: vi.fn().mockResolvedValue('Test User | LinkedIn'),
+      evaluate: vi.fn().mockResolvedValue({
+        elements: [
+          {
+            id: 'elem-1',
+            tag: 'button',
+            role: 'button',
+            ariaLabel: 'Connect',
+            text: 'Connect',
+            type: 'button',
+            visible: true,
+            enabled: true,
+            bbox: { x: 100, y: 200, width: 80, height: 40 },
+          },
+        ],
+        metadata: {
+          pageType: 'profile',
+          profileName: 'Test User',
+          connectionState: 'not_connected',
+          statusMessages: [],
+        },
+      }),
+    };
+  });
+
+  it('should extract DOM representation from page', async () => {
+    const dom = await extractor.extract(mockPage as Page);
+
+    expect(dom.url).toBe('https://www.linkedin.com/in/test');
+    expect(dom.title).toBe('Test User | LinkedIn');
+    expect(dom.elements).toHaveLength(1);
+    expect(dom.elements[0].text).toBe('Connect');
+    expect(dom.metadata.pageType).toBe('profile');
+  });
+
+  it('should generate unique IDs for elements', async () => {
+    const dom = await extractor.extract(mockPage as Page);
+
+    expect(dom.elements[0].id).toBeDefined();
+    expect(typeof dom.elements[0].id).toBe('string');
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+```bash
+npm test src/agent/dom-extractor.test.ts
+```
+
+Expected: FAIL with "Cannot find module './dom-extractor'"
+
+- [ ] **Step 3: Implement DOM extractor**
+
+Create `src/agent/dom-extractor.ts`:
+
+```typescript
+import type { Page } from 'playwright';
+import type { DOMRepresentation, DOMElement, PageMetadata } from './types';
+
+/**
+ * Extracts semantic DOM representation from a LinkedIn page.
+ * Uses Playwright's evaluate to extract clean, structured data.
+ */
+export class DOMExtractor {
+  /**
+   * Extract DOM representation from the current page
+   */
+  async extract(page: Page): Promise<DOMRepresentation> {
+    const url = page.url();
+    const title = await page.title();
+
+    // Extract elements and metadata via page.evaluate
+    const result = await page.evaluate(() => {
+      const elements: Array<{
+        tag: string;
+        role?: string;
+        ariaLabel?: string;
+        text: string;
+        type?: string;
+        visible: boolean;
+        enabled: boolean;
+        bbox: { x: number; y: number; width: number; height: number };
+      }> = [];
+
+      // Helper to check visibility
+      const isVisible = (el: Element): boolean => {
+        const style = window.getComputedStyle(el);
+        return (
+          style.display !== 'none' &&
+          style.visibility !== 'hidden' &&
+          style.opacity !== '0' &&
+          el.getBoundingClientRect().width > 0 &&
+          el.getBoundingClientRect().height > 0
+        );
+      };
+
+      // Extract interactive elements
+      const interactiveSelectors = [
+        'button',
+        'a[href]',
+        'input',
+        'textarea',
+        'select',
+        '[role="button"]',
+        '[role="link"]',
+        '[role="textbox"]',
+      ];
+
+      interactiveSelectors.forEach((selector) => {
+        document.querySelectorAll(selector).forEach((el, index) => {
+          const htmlEl = el as HTMLElement;
+          const rect = el.getBoundingClientRect();
+
+          if (!isVisible(el)) return;
+
+          const text = el.textContent?.trim() || '';
+          const ariaLabel =
+            el.getAttribute('aria-label') ||
+            el.getAttribute('title') ||
+            '';
+
+          // Determine element type
+          let type: string | undefined;
+          const tag = el.tagName.toLowerCase();
+          if (tag === 'button' || el.getAttribute('role') === 'button') {
+            type = 'button';
+          } else if (tag === 'a' || el.getAttribute('role') === 'link') {
+            type = 'link';
+          } else if (tag === 'input') {
+            type = el.getAttribute('type') || 'input';
+          } else if (tag === 'textarea') {
+            type = 'textarea';
+          }
+
+          elements.push({
+            tag,
+            role: el.getAttribute('role') || undefined,
+            ariaLabel: ariaLabel || undefined,
+            text: text.slice(0, 200), // Limit text length
+            type,
+            visible: true,
+            enabled: !htmlEl.disabled,
+            bbox: {
+              x: Math.round(rect.x),
+              y: Math.round(rect.y),
+              width: Math.round(rect.width),
+              height: Math.round(rect.height),
+            },
+          });
+        });
+      });
+
+      // Extract metadata
+      const metadata: PageMetadata = {
+        pageType: 'other',
+        statusMessages: [],
+      };
+
+      // Detect page type
+      if (window.location.pathname.includes('/in/')) {
+        metadata.pageType = 'profile';
+
+        // Try to find profile name
+        const nameEl =
+          document.querySelector('h1') ||
+          document.querySelector('[data-testid="profile-name"]');
+        if (nameEl) {
+          metadata.profileName = nameEl.textContent?.trim();
+        }
+
+        // Detect connection state
+        const bodyText = document.body.innerText;
+        if (bodyText.includes('Pending')) {
+          metadata.connectionState = 'pending';
+        } else if (
+          bodyText.includes('Message') &&
+          !bodyText.includes('Connect')
+        ) {
+          metadata.connectionState = 'connected';
+        } else if (bodyText.includes('Connect')) {
+          metadata.connectionState = 'not_connected';
+        }
+      } else if (window.location.pathname.includes('/messaging/')) {
+        metadata.pageType = 'messaging';
+      }
+
+      return { elements, metadata };
+    });
+
+    // Assign unique IDs to elements
+    const elementsWithIds: DOMElement[] = result.elements.map((el, index) => ({
+      ...el,
+      id: this.generateElementId(el, index),
+    }));
+
+    return {
+      url,
+      title,
+      elements: elementsWithIds,
+      metadata: result.metadata,
+    };
+  }
+
+  /**
+   * Generate a unique ID for an element
+   */
+  private generateElementId(
+    el: { tag: string; ariaLabel?: string; text: string },
+    index: number
+  ): string {
+    const label = el.ariaLabel || el.text.slice(0, 20);
+    const hash = `${el.tag}-${label}-${index}`
+      .replace(/[^a-zA-Z0-9-]/g, '-')
+      .toLowerCase();
+    return `elem-${hash}`;
+  }
+}
+```
+
+- [ ] **Step 4: Run tests**
+
+```bash
+npm test src/agent/dom-extractor.test.ts
+```
+
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/agent/dom-extractor.ts src/agent/dom-extractor.test.ts
+git commit -m "feat(agent): implement DOM extractor"
+```
+
+---
+
+## Chunk 3: Claude API Client
+
+**Purpose:** Client for Dashscope Claude API.
+
+**Files:**
+- Create: `src/agent/claude-client.ts`
+- Test: `src/agent/claude-client.test.ts`
+
+---
+
+### Task 5: Create Claude Client
+
+- [ ] **Step 1: Write the failing test**
+
+Create `src/agent/claude-client.test.ts`:
+
+```typescript
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { ClaudeClient } from './claude-client';
+import type { DOMRepresentation, ActionContext } from './types';
+
+describe('ClaudeClient', () => {
+  let client: ClaudeClient;
+
+  beforeEach(() => {
+    client = new ClaudeClient({
+      apiKey: 'test-key',
+      baseUrl: 'https://test.example.com',
+      model: 'qwen3.5-plus',
+    });
+
+    // Mock fetch
+    global.fetch = vi.fn();
+  });
+
+  it('should generate action plan from DOM', async () => {
+    const mockResponse = {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify({
+            reasoning: 'Need to click Connect button',
+            expectedOutcome: 'Connection modal opens',
+            actions: [
+              { type: 'click', elementId: 'elem-button-connect', description: 'Click Connect' },
+            ],
+            status: 'in_progress',
+          }),
+        },
+      ],
+    };
+
+    vi.mocked(fetch).mockResolvedValueOnce({
+      ok: true,
+      json: async () => mockResponse,
+    } as Response);
+
+    const dom: DOMRepresentation = {
+      url: 'https://linkedin.com/in/test',
+      title: 'Test | LinkedIn',
+      elements: [
+        {
+          id: 'elem-button-connect',
+          tag: 'button',
+          text: 'Connect',
+          type: 'button',
+          visible: true,
+          enabled: true,
+          bbox: { x: 100, y: 200, width: 80, height: 40 },
+        },
+      ],
+      metadata: {
+        pageType: 'profile',
+        connectionState: 'not_connected',
+        statusMessages: [],
+      },
+    };
+
+    const context: ActionContext = {
+      goal: 'Send connection request',
+      previousActions: [],
+      retryCount: 0,
+    };
+
+    const plan = await client.generateActionPlan(dom, context);
+
+    expect(plan.reasoning).toBe('Need to click Connect button');
+    expect(plan.actions).toHaveLength(1);
+    expect(plan.actions[0].type).toBe('click');
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+```bash
+npm test src/agent/claude-client.test.ts
+```
+
+Expected: FAIL with "Cannot find module"
+
+- [ ] **Step 3: Implement Claude client**
+
+Create `src/agent/claude-client.ts`:
+
+```typescript
+import type { DOMRepresentation, ActionPlan, ActionContext, ClaudeClientConfig } from './types';
+
+export class ClaudeClient {
+  private config: ClaudeClientConfig;
+
+  constructor(config: ClaudeClientConfig) {
+    this.config = config;
+  }
+
+  /**
+   * Generate an action plan based on current DOM state
+   */
+  async generateActionPlan(
+    dom: DOMRepresentation,
+    context: ActionContext
+  ): Promise<ActionPlan> {
+    const messages = this.buildMessages(dom, context);
+
+    const response = await fetch(`${this.config.baseUrl}/messages`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${this.config.apiKey}`,
+      },
+      body: JSON.stringify({
+        model: this.config.model,
+        max_tokens: 4096,
+        messages,
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Claude API error: ${response.status} - ${error}`);
+    }
+
+    const result = await response.json();
+    const content = result.content?.[0]?.text;
+
+    if (!content) {
+      throw new Error('Empty response from Claude API');
+    }
+
+    return this.parseActionPlan(content);
+  }
+
+  /**
+   * Build messages for the API call
+   */
+  private buildMessages(dom: DOMRepresentation, context: ActionContext): Array<{ role: string; content: string }> {
+    const systemPrompt = `You are a web automation agent that controls LinkedIn through a browser.
+You receive a DOM representation of the current page and must decide the next action(s) to achieve the user's goal.
+
+Rules:
+1. Respond ONLY with a JSON action plan
+2. Each action must reference an element by its ID from the DOM
+3. Include brief reasoning for your decision
+4. If the goal is already achieved, return empty actions with status "completed"
+5. If stuck or error, explain why and suggest recovery with status "error"
+
+Available actions:
+- click: Click an element (requires elementId)
+- type: Type text into an input (requires elementId, text)
+- wait: Wait for page to stabilize (requires durationMs in milliseconds)
+- navigate: Go to a URL (requires url)
+
+Response format:
+{
+  "reasoning": "brief explanation",
+  "expectedOutcome": "what should happen",
+  "actions": [
+    { "type": "click", "elementId": "elem-xxx", "description": "what this does" }
+  ],
+  "status": "in_progress" | "completed" | "error",
+  "error": "error message if status is error"
+}`;
+
+    const domJson = JSON.stringify(dom, null, 2);
+    const previousActionsText =
+      context.previousActions.length > 0
+        ? `\nPrevious actions taken:\n${context.previousActions
+            .map((a) => `- ${a.action.type}: ${a.action.description} (${a.success ? 'success' : 'failed'})`)
+            .join('\n')}`
+        : '';
+
+    const userPrompt = `Goal: ${context.goal}
+
+Current page DOM:
+\`\`\`json
+${domJson}
+\`\`\`
+${previousActionsText}
+
+What action(s) should be taken next?`;
+
+    return [
+      { role: 'system', content: systemPrompt },
+      { role: 'user', content: userPrompt },
+    ];
+  }
+
+  /**
+   * Parse the LLM response into an ActionPlan
+   */
+  private parseActionPlan(content: string): ActionPlan {
+    try {
+      // Try to extract JSON from the response
+      const jsonMatch = content.match(/\{[\s\S]*\}/);
+      if (!jsonMatch) {
+        throw new Error('No JSON found in response');
+      }
+
+      const parsed = JSON.parse(jsonMatch[0]);
+
+      // Validate required fields
+      if (!parsed.reasoning || !Array.isArray(parsed.actions)) {
+        throw new Error('Invalid action plan structure');
+      }
+
+      return {
+        reasoning: parsed.reasoning,
+        expectedOutcome: parsed.expectedOutcome || '',
+        actions: parsed.actions,
+        status: parsed.status || 'in_progress',
+        error: parsed.error,
+      };
+    } catch (error) {
+      return {
+        reasoning: 'Failed to parse LLM response',
+        expectedOutcome: 'None',
+        actions: [],
+        status: 'error',
+        error: `Parse error: ${error instanceof Error ? error.message : 'unknown'}`,
+      };
+    }
+  }
+}
+```
+
+- [ ] **Step 4: Run tests**
+
+```bash
+npm test src/agent/claude-client.test.ts
+```
+
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/agent/claude-client.ts src/agent/claude-client.test.ts
+git commit -m "feat(agent): implement Claude API client"
+```
+
+---
+
+## Chunk 4: Action Executor
+
+**Purpose:** Execute action plans using Playwright.
+
+**Files:**
+- Create: `src/agent/action-executor.ts`
+- Test: `src/agent/action-executor.test.ts`
+
+---
+
+### Task 6: Create Action Executor
+
+- [ ] **Step 1: Write the failing test**
+
+Create `src/agent/action-executor.test.ts`:
+
+```typescript
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { ActionExecutor } from './action-executor';
+import type { Page } from 'playwright';
+import type { DOMRepresentation, Action } from './types';
+
+describe('ActionExecutor', () => {
+  let executor: ActionExecutor;
+  let mockPage: Partial<Page>;
+  let mockDom: DOMRepresentation;
+
+  beforeEach(() => {
+    mockPage = {
+      click: vi.fn().mockResolvedValue(undefined),
+      fill: vi.fn().mockResolvedValue(undefined),
+      waitForTimeout: vi.fn().mockResolvedValue(undefined),
+      goto: vi.fn().mockResolvedValue(undefined),
+    };
+
+    mockDom = {
+      url: 'https://linkedin.com/in/test',
+      title: 'Test | LinkedIn',
+      elements: [
+        {
+          id: 'elem-1',
+          tag: 'button',
+          text: 'Connect',
+          type: 'button',
+          visible: true,
+          enabled: true,
+          bbox: { x: 100, y: 200, width: 80, height: 40 },
+        },
+      ],
+      metadata: {
+        pageType: 'profile',
+        statusMessages: [],
+      },
+    };
+
+    executor = new ActionExecutor(mockPage as Page, mockDom);
+  });
+
+  it('should execute click action', async () => {
+    const action: Action = {
+      type: 'click',
+      elementId: 'elem-1',
+      description: 'Click Connect button',
+    };
+
+    const result = await executor.execute(action);
+
+    expect(result.success).toBe(true);
+    expect(mockPage.click).toHaveBeenCalledWith(140, 220); // center of bbox
+  });
+
+  it('should return error for unknown element', async () => {
+    const action: Action = {
+      type: 'click',
+      elementId: 'unknown',
+      description: 'Click unknown',
+    };
+
+    const result = await executor.execute(action);
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('not found');
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+```bash
+npm test src/agent/action-executor.test.ts
+```
+
+Expected: FAIL
+
+- [ ] **Step 3: Implement action executor**
+
+Create `src/agent/action-executor.ts`:
+
+```typescript
+import type { Page } from 'playwright';
+import type { Action, DOMRepresentation, ExecutedAction } from './types';
+
+export interface ExecutionResult {
+  success: boolean;
+  error?: string;
+}
+
+export class ActionExecutor {
+  private page: Page;
+  private dom: DOMRepresentation;
+
+  constructor(page: Page, dom: DOMRepresentation) {
+    this.page = page;
+    this.dom = dom;
+  }
+
+  /**
+   * Execute a single action
+   */
+  async execute(action: Action): Promise<ExecutionResult> {
+    try {
+      switch (action.type) {
+        case 'click':
+          return await this.executeClick(action.elementId);
+        case 'type':
+          return await this.executeType(action.elementId, action.text);
+        case 'wait':
+          return await this.executeWait(action.durationMs);
+        case 'navigate':
+          return await this.executeNavigate(action.url);
+        default:
+          return { success: false, error: `Unknown action type: ${(action as any).type}` };
+      }
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error',
+      };
+    }
+  }
+
+  /**
+   * Execute a click on an element by ID
+   */
+  private async executeClick(elementId: string): Promise<ExecutionResult> {
+    const element = this.dom.elements.find((el) => el.id === elementId);
+
+    if (!element) {
+      return { success: false, error: `Element ${elementId} not found in DOM` };
+    }
+
+    // Calculate center of bounding box
+    const centerX = element.bbox.x + element.bbox.width / 2;
+    const centerY = element.bbox.y + element.bbox.height / 2;
+
+    // Use Playwright's mouse click at coordinates
+    await this.page.mouse.click(centerX, centerY);
+
+    return { success: true };
+  }
+
+  /**
+   * Execute typing into an input element
+   */
+  private async executeType(elementId: string, text: string): Promise<ExecutionResult> {
+    const element = this.dom.elements.find((el) => el.id === elementId);
+
+    if (!element) {
+      return { success: false, error: `Element ${elementId} not found in DOM` };
+    }
+
+    // Click first to focus
+    const clickResult = await this.executeClick(elementId);
+    if (!clickResult.success) {
+      return clickResult;
+    }
+
+    // Wait a bit for focus
+    await this.page.waitForTimeout(100);
+
+    // Type the text
+    await this.page.keyboard.type(text);
+
+    return { success: true };
+  }
+
+  /**
+   * Execute wait action
+   */
+  private async executeWait(durationMs: number): Promise<ExecutionResult> {
+    await this.page.waitForTimeout(durationMs);
+    return { success: true };
+  }
+
+  /**
+   * Execute navigation
+   */
+  private async executeNavigate(url: string): Promise<ExecutionResult> {
+    await this.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
+    return { success: true };
+  }
+
+  /**
+   * Execute multiple actions in sequence
+   */
+  async executeAll(actions: Action[]): Promise<ExecutedAction[]> {
+    const executed: ExecutedAction[] = [];
+
+    for (const action of actions) {
+      console.log(`Executing: ${action.description}`);
+      const result = await this.execute(action);
+
+      executed.push({
+        action,
+        success: result.success,
+        timestamp: Date.now(),
+        error: result.error,
+      });
+
+      if (!result.success) {
+        console.error(`Action failed: ${result.error}`);
+        break;
+      }
+
+      // Small delay between actions
+      await this.page.waitForTimeout(500);
+    }
+
+    return executed;
+  }
+}
+```
+
+- [ ] **Step 4: Run tests**
+
+```bash
+npm test src/agent/action-executor.test.ts
+```
+
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/agent/action-executor.ts src/agent/action-executor.test.ts
+git commit -m "feat(agent): implement action executor"
+```
+
+---
+
+## Chunk 5: Page Agent Orchestrator
+
+**Purpose:** Main orchestrator that combines all components.
+
+**Files:**
+- Create: `src/agent/page-agent.ts`
+
+---
+
+### Task 7: Create Page Agent
+
+- [ ] **Step 1: Implement Page Agent**
+
+Create `src/agent/page-agent.ts`:
+
+```typescript
+import type { Page } from 'playwright';
+import { DOMExtractor } from './dom-extractor';
+import { ClaudeClient } from './claude-client';
+import { ActionExecutor } from './action-executor';
+import type {
+  Task,
+  TaskResult,
+  ConnectionResult,
+  MessageResult,
+  ActionContext,
+  ExecutedAction,
+  ClaudeClientConfig,
+} from './types';
+
+export interface PageAgentOptions {
+  claudeConfig: ClaudeClientConfig;
+  maxRetries?: number;
+  debug?: boolean;
+}
+
+export class PageAgent {
+  private domExtractor: DOMExtractor;
+  private claudeClient: ClaudeClient;
+  private options: PageAgentOptions;
+
+  constructor(options: PageAgentOptions) {
+    this.domExtractor = new DOMExtractor();
+    this.claudeClient = new ClaudeClient(options.claudeConfig);
+    this.options = {
+      maxRetries: 3,
+      debug: false,
+      ...options,
+    };
+  }
+
+  /**
+   * Execute a task on a LinkedIn page
+   */
+  async execute(task: Task, page: Page): Promise<TaskResult> {
+    const goal = this.buildGoal(task);
+    const actions: ExecutedAction[] = [];
+    let retryCount = 0;
+
+    while (retryCount < this.options.maxRetries!) {
+      // Extract current DOM state
+      const dom = await this.domExtractor.extract(page);
+
+      if (this.options.debug) {
+        console.log('Extracted DOM:', JSON.stringify(dom, null, 2));
+      }
+
+      // Build context
+      const context: ActionContext = {
+        goal,
+        previousActions: actions,
+        retryCount,
+      };
+
+      // Get action plan from Claude
+      let plan;
+      try {
+        plan = await this.claudeClient.generateActionPlan(dom, context);
+      } catch (error) {
+        return {
+          success: false,
+          message: `Failed to get action plan: ${error instanceof Error ? error.message : 'unknown'}`,
+          actionsTaken: actions.map((a) => a.action),
+        };
+      }
+
+      if (this.options.debug) {
+        console.log('Action plan:', plan);
+      }
+
+      // Check if completed
+      if (plan.status === 'completed') {
+        return {
+          success: true,
+          message: plan.reasoning || 'Task completed',
+          actionsTaken: actions.map((a) => a.action),
+          finalUrl: page.url(),
+        };
+      }
+
+      // Check for error
+      if (plan.status === 'error') {
+        return {
+          success: false,
+          message: plan.error || 'Unknown error',
+          actionsTaken: actions.map((a) => a.action),
+        };
+      }
+
+      // Execute actions
+      const executor = new ActionExecutor(page, dom);
+      const executed = await executor.executeAll(plan.actions);
+      actions.push(...executed);
+
+      // Check if any action failed
+      const failedAction = executed.find((e) => !e.success);
+      if (failedAction) {
+        retryCount++;
+        if (retryCount >= this.options.maxRetries!) {
+          return {
+            success: false,
+            message: `Failed after ${retryCount} retries: ${failedAction.error}`,
+            actionsTaken: actions.map((a) => a.action),
+          };
+        }
+        // Wait before retry
+        await page.waitForTimeout(2000);
+      }
+
+      // Wait for page to stabilize
+      await page.waitForTimeout(1000);
+    }
+
+    return {
+      success: false,
+      message: `Exceeded maximum retries (${this.options.maxRetries})`,
+      actionsTaken: actions.map((a) => a.action),
+    };
+  }
+
+  /**
+   * Send connection request to a profile
+   */
+  async connect(profileUrl: string, note: string | undefined, page: Page): Promise<ConnectionResult> {
+    // Navigate to profile first
+    await page.goto(profileUrl, { waitUntil: 'domcontentloaded', timeout: 30000 });
+    await page.waitForTimeout(3000);
+
+    const task: Task = {
+      goal: note
+        ? `Send connection request with note: "${note}"`
+        : 'Send connection request',
+      profileUrl,
+      note,
+    };
+
+    const result = await this.execute(task, page);
+
+    // Check final state
+    const dom = await this.domExtractor.extract(page);
+
+    return {
+      ...result,
+      sent: result.success && dom.metadata.connectionState === 'pending',
+      pending: dom.metadata.connectionState === 'pending',
+      alreadyConnected: dom.metadata.connectionState === 'connected',
+    };
+  }
+
+  /**
+   * Send message to a profile
+   */
+  async sendMessage(profileUrl: string, message: string, page: Page): Promise<MessageResult> {
+    // Navigate to profile first
+    await page.goto(profileUrl, { waitUntil: 'domcontentloaded', timeout: 30000 });
+    await page.waitForTimeout(3000);
+
+    const task: Task = {
+      goal: `Send message: "${message}"`,
+      profileUrl,
+      message,
+    };
+
+    const result = await this.execute(task, page);
+
+    return {
+      ...result,
+      sent: result.success,
+    };
+  }
+
+  /**
+   * Build natural language goal from task
+   */
+  private buildGoal(task: Task): string {
+    if (task.goal) {
+      return task.goal;
+    }
+    if (task.note) {
+      return `Send connection request to ${task.profileUrl} with note: "${task.note}"`;
+    }
+    if (task.message) {
+      return `Send message to ${task.profileUrl}: "${task.message}"`;
+    }
+    return 'Complete task on LinkedIn';
+  }
+}
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add src/agent/page-agent.ts
+git commit -m "feat(agent): implement page agent orchestrator"
+```
+
+---
+
+## Chunk 6: Module Exports
+
+**Purpose:** Export public API from agent module.
+
+**Files:**
+- Create: `src/agent/index.ts`
+
+---
+
+### Task 8: Create Module Index
+
+- [ ] **Step 1: Create index.ts**
+
+Create `src/agent/index.ts`:
+
+```typescript
+// Types
+export type {
+  Action,
+  ActionContext,
+  ActionPlan,
+  BoundingBox,
+  ClaudeClientConfig,
+  ClickAction,
+  ConnectionResult,
+  DOMElement,
+  DOMRepresentation,
+  ExecutedAction,
+  MessageResult,
+  NavigateAction,
+  PageMetadata,
+  Task,
+  TaskResult,
+  TypeAction,
+  WaitAction,
+} from './types';
+
+// Classes
+export { DOMExtractor } from './dom-extractor';
+export { ClaudeClient } from './claude-client';
+export { ActionExecutor } from './action-executor';
+export { PageAgent } from './page-agent';
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add src/agent/index.ts
+git commit -m "feat(agent): add module exports"
+```
+
+---
+
+## Chunk 7: CLI Commands
+
+**Purpose:** Add CLI commands for the agent.
+
+**Files:**
+- Create: `src/cli/agent-commands.ts`
+- Modify: `src/cli/index.ts` (add export)
+- Modify: `src/index.ts` (register commands)
+
+---
+
+### Task 9: Create Agent CLI Commands
+
+- [ ] **Step 1: Create agent commands**
+
+Create `src/cli/agent-commands.ts`:
+
+```typescript
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { PageAgent } from '../agent';
+import { createBrowser } from '../core/browser';
+import { getConfig } from '../core/config';
+
+export function registerAgentCommands(program: Command): void {
+  const agentCmd = program
+    .command('agent')
+    .description('AI-powered LinkedIn automation using DOM-text agent');
+
+  // Connect command
+  agentCmd
+    .command('connect <url>')
+    .description('Send connection request using AI agent')
+    .option('--note <text>', 'Personal note to include')
+    .option('--profile <name>', 'Browser profile to use')
+    .option('--debug', 'Enable debug output')
+    .action(async (url, options) => {
+      const config = getConfig();
+      const apiKey = process.env.DASHSCOPE_API_KEY;
+
+      if (!apiKey) {
+        console.error(chalk.red('Error: DASHSCOPE_API_KEY environment variable not set'));
+        console.log('Set it with: export DASHSCOPE_API_KEY=your_key');
+        process.exit(1);
+      }
+
+      console.log(chalk.blue('Starting browser...'));
+      const browser = await createBrowser({
+        headless: config.get().headless,
+        debug: options.debug,
+      });
+
+      try {
+        const agent = new PageAgent({
+          claudeConfig: {
+            apiKey,
+            baseUrl: process.env.DASHSCOPE_BASE_URL || 'https://coding.dashscope.aliyuncs.com/apps/anthropic/v1',
+            model: process.env.DASHSCOPE_MODEL || 'qwen3.5-plus',
+          },
+          debug: options.debug,
+        });
+
+        console.log(chalk.blue(`Navigating to ${url}...`));
+        const page = browser.getPage()!;
+
+        const result = await agent.connect(url, options.note, page);
+
+        if (result.success) {
+          console.log(chalk.green('✓ Connection request sent successfully'));
+          if (result.alreadyConnected) {
+            console.log(chalk.yellow('Note: Already connected with this person'));
+          }
+        } else {
+          console.error(chalk.red(`✗ Failed: ${result.message}`));
+          process.exit(1);
+        }
+      } finally {
+        await browser.close();
+      }
+    });
+
+  // Message command
+  agentCmd
+    .command('message <url>')
+    .description('Send message using AI agent')
+    .requiredOption('--message <text>', 'Message to send')
+    .option('--profile <name>', 'Browser profile to use')
+    .option('--debug', 'Enable debug output')
+    .action(async (url, options) => {
+      const config = getConfig();
+      const apiKey = process.env.DASHSCOPE_API_KEY;
+
+      if (!apiKey) {
+        console.error(chalk.red('Error: DASHSCOPE_API_KEY environment variable not set'));
+        console.log('Set it with: export DASHSCOPE_API_KEY=your_key');
+        process.exit(1);
+      }
+
+      console.log(chalk.blue('Starting browser...'));
+      const browser = await createBrowser({
+        headless: config.get().headless,
+        debug: options.debug,
+      });
+
+      try {
+        const agent = new PageAgent({
+          claudeConfig: {
+            apiKey,
+            baseUrl: process.env.DASHSCOPE_BASE_URL || 'https://coding.dashscope.aliyuncs.com/apps/anthropic/v1',
+            model: process.env.DASHSCOPE_MODEL || 'qwen3.5-plus',
+          },
+          debug: options.debug,
+        });
+
+        console.log(chalk.blue(`Navigating to ${url}...`));
+        const page = browser.getPage()!;
+
+        const result = await agent.sendMessage(url, options.message, page);
+
+        if (result.success) {
+          console.log(chalk.green('✓ Message sent successfully'));
+        } else {
+          console.error(chalk.red(`✗ Failed: ${result.message}`));
+          process.exit(1);
+        }
+      } finally {
+        await browser.close();
+      }
+    });
+}
+```
+
+- [ ] **Step 2: Update CLI index**
+
+Modify `src/cli/index.ts` to add export:
+
+```typescript
+export { registerAuthCommands } from './auth';
+export { registerMessageCommands } from './messages';
+export { registerReplyCommands } from './reply';
+export { registerConnectionCommands } from './connections';
+export { registerAgentCommands } from './agent-commands';
+```
+
+- [ ] **Step 3: Register commands in main entry**
+
+Modify `src/index.ts` to add:
+
+```typescript
+import {
+  registerAuthCommands,
+  registerMessageCommands,
+  registerReplyCommands,
+  registerConnectionCommands,
+  registerAgentCommands,
+} from './cli';
+
+// ... existing code ...
+
+// Register command groups
+registerAuthCommands(program);
+registerMessageCommands(program);
+registerReplyCommands(program);
+registerConnectionCommands(program);
+registerAgentCommands(program);  // Add this line
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/cli/agent-commands.ts src/cli/index.ts src/index.ts
+git commit -m "feat(cli): add agent commands for connect and message"
+```
+
+---
+
+## Chunk 8: Environment Configuration
+
+**Purpose:** Document environment variables.
+
+**Files:**
+- Create: `.env.example`
+
+---
+
+### Task 10: Create Environment Example
+
+- [ ] **Step 1: Create .env.example**
+
+Create `.env.example`:
+
+```bash
+# Dashscope Claude API Configuration
+# Get your API key from: https://dashscope.aliyun.com/
+DASHSCOPE_API_KEY=your_key_here
+DASHSCOPE_BASE_URL=https://coding.dashscope.aliyuncs.com/apps/anthropic/v1
+DASHSCOPE_MODEL=qwen3.5-plus
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add .env.example
+git commit -m "docs: add environment configuration example"
+```
+
+---
+
+## Final Steps
+
+### Task 11: Build and Test
+
+- [ ] **Step 1: Build the project**
+
+```bash
+npm run build
+```
+
+Expected: Build completes without errors
+
+- [ ] **Step 2: Run all tests**
+
+```bash
+npm test
+```
+
+Expected: All tests pass
+
+- [ ] **Step 3: Final commit**
+
+```bash
+git commit -m "feat: complete Page Agent integration"
+```
+
+---
+
+## Usage Instructions
+
+After implementation, users can:
+
+```bash
+# Set up environment
+export DASHSCOPE_API_KEY=your_key
+
+# Send connection request
+linkedin agent connect https://www.linkedin.com/in/alice --note "Hi Alice!"
+
+# Send message
+linkedin agent message https://www.linkedin.com/in/alice --message "Thanks for connecting!"
+
+# Debug mode
+linkedin agent connect https://www.linkedin.com/in/alice --debug
+```
+
+---
+
+## Implementation Complete
+
+Plan complete and saved to `docs/superpowers/plans/2026-03-14-page-agent-plan.md`. Ready to execute?