CDP Agent

https://github.com/yosefhayim/cdp-agent
Admin
CDP Agent is an autonomous coding agent that uses Chrome DevTools Protocol to connect to Gemini and...
Tokens:8,769
Snippets:69
Trust Score:4
Update:7 months ago
Show doc for...
Tokens:
Raw
### Install and Run CDP-Agent

Source: https://github.com/yosefhayim/cdp-agent/blob/main/README.md

Instructions for setting up the project environment using Bun and executing the agent with a specific task prompt.

```bash
git clone https://github.com/YosefHayim/CDP-Agent.git
cd CDP-Agent
bun install
bun run start -- --prompt "Add a README to this project"
```

--------------------------------

### CDP Agent Configuration File Example

Source: https://context7.com/yosefhayim/cdp-agent/llms.txt

An example of the optional JSON configuration file (`.cdp-agent.config.json`) used to customize the CDP Agent's behavior. Settings include CDP port, iteration limits, timeouts, and directory paths.

```json
{
  "cdpPort": 9222,
  "maxIterations": 50,
  "maxParseFailures": 3,
  "shellTimeout": 120000,
  "fileReadMaxSize": 102400,
  "stabilityThreshold": 3,
  "stabilityPollingInterval": 500,
  "workingDirectory": ".",
  "sessionDir": ".cdp-agent-sessions",
  "verbose": false
}
```

--------------------------------

### CLI Usage Examples

Source: https://github.com/yosefhayim/cdp-agent/blob/main/README.md

Common command-line interface patterns for managing agent tasks, checking connections, and resuming previous sessions.

```bash
bun run start -- --prompt "Fix the lint errors in src/"
bun run start -- --check-connection
bun run start -- --list-sessions
bun run start -- --resume <session-id>
```

--------------------------------

### Standard Git Commit Message Format

Source: https://github.com/yosefhayim/cdp-agent/blob/main/docs/PROJECT_RULES.md

Defines the conventional commit message format used in the project. It specifies the structure including type, scope, description, and optional body/footer, along with a list of valid commit types and examples.

```bash
<type>(<scope>): <description> (#task-id)

[optional body]

[optional footer]

```

```bash
# Feature
feat(auth): add OAuth2 login with Google (#1.2)

# Bug fix
fix(api): handle null response in user service (#2.1)

# Refactor
refactor(components): extract Card base component (#3.4)

Extracted common card styling into reusable Card component.
Updated UserCard and ProductCard to use new base.

BREAKING CHANGE: Card now requires 'variant' prop

```

--------------------------------

### Run CDP Agent CLI Commands

Source: https://context7.com/yosefhayim/cdp-agent/llms.txt

Demonstrates various command-line interface commands for running the CDP Agent, including launching Chrome, checking connections, managing sessions, and setting options like verbose logging and custom ports.

```bash
# Run a simple task
bun run start -- --prompt "Add unit tests for the utils module"

# Auto-launch Chrome with remote debugging enabled
bun run start -- --launch-chrome --prompt "Fix the lint errors in src/"

# Check CDP connection status
bun run start -- --check-connection

# List all saved sessions
bun run start -- --list-sessions

# Resume a previous session by ID
bun run start -- --resume lx7f2k9

# Run with verbose logging and custom working directory
bun run start -- --prompt "Refactor auth module" --working-dir /path/to/project --verbose

# Use custom CDP port
bun run start -- --cdp-port 9223 --prompt "Add README documentation"
```

--------------------------------

### Implement search_directory Tool in TypeScript

Source: https://context7.com/yosefhayim/cdp-agent/llms.txt

Shows how to use the `search_directory` tool in TypeScript for finding files within a project. It supports glob patterns, automatically respects `.gitignore`, and allows searching within specific subdirectories.

```typescript
import { createSearchDirectoryTool } from './tools/search-directory.js';

const searchDir = createSearchDirectoryTool('/path/to/project');

// Find all TypeScript files
const tsFiles = await searchDir.execute({ pattern: '**/*.ts' });
// Returns: { success: true, output: "src/index.ts\nsrc/utils.ts\n[5 file(s) found]" }

// Search in specific subdirectory
const components = await searchDir.execute({
  pattern: '**/*.tsx',
  path: 'src/components'
});
// Returns: { success: true, output: "src/components/Button.tsx\n..." }

// Find config files
const configs = await searchDir.execute({ pattern: '*.config.{js,ts,json}' });
// Returns: { success: true, output: "tsconfig.json\nbiome.json\n[2 file(s) found]" }
```

--------------------------------

### CSS Modules Styling Conventions for Semantics

Source: https://github.com/yosefhayim/cdp-agent/blob/main/docs/PROJECT_RULES.md

Best practices for using CSS Modules, advocating for semantic class names over presentational ones to ensure maintainability and adaptability to design changes. It demonstrates importing styles and applying them to elements.

```tsx
// DO: Use semantic class names
import styles from './Button.module.css';
<button className={styles.primary}>

// DON'T: Use presentational names
<button className={styles.blueButton}>  // What if design changes?
```

--------------------------------

### Launch Chrome for Debugging

Source: https://github.com/yosefhayim/cdp-agent/blob/main/README.md

Platform-specific commands to launch the Google Chrome browser with the required remote debugging port enabled for CDP communication.

```bash
# macOS
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222

# Linux
google-chrome --remote-debugging-port=9222

# Windows
"C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe" --remote-debugging-port=9222
```

--------------------------------

### Implement read_file Tool in TypeScript

Source: https://context7.com/yosefhayim/cdp-agent/llms.txt

Demonstrates the creation and usage of the `read_file` tool in TypeScript. This tool reads file contents with line numbers, enforces security by restricting access to the working directory, and handles large files by truncating them.

```typescript
import { createReadFileTool } from './tools/read-file.js';

const readFile = createReadFileTool('/path/to/project', 102400);

// Read a TypeScript file
const result = await readFile.execute({ path: 'src/index.ts' });
// Returns: { success: true, output: "1: import {...}\n2: export function..." }

// Attempt to read outside working directory (blocked)
const blocked = await readFile.execute({ path: '../../../etc/passwd' });
// Returns: { success: false, error: 'Path is outside the working directory' }

// Read large file (truncated at limit)
const large = await readFile.execute({ path: 'data/large-file.json' });
// Returns: { success: true, output: "1: {...}\n[TRUNCATED at 102400 bytes]" }
```

--------------------------------

### Launch Chrome for Automation

Source: https://context7.com/yosefhayim/cdp-agent/llms.txt

Utility to launch a Chrome instance with remote debugging enabled. It handles platform-specific paths and ensures the browser is ready for CDP interactions.

```typescript
import { launchChrome, getChromePath } from './browser/launch.js';

const chromePath = getChromePath();
await launchChrome(9222, true);
```

--------------------------------

### Execute shell commands with shell tool

Source: https://context7.com/yosefhayim/cdp-agent/llms.txt

The shell tool provides a wrapper for executing system commands with configurable timeouts. It captures stdout, stderr, and exit codes, providing a structured interface for tasks like linting, testing, and Git operations.

```typescript
import { createShellTool } from './tools/shell.js';

const shell = createShellTool('/path/to/project', 120000);

// Run TypeScript compilation check
const typecheck = await shell.execute({ command: 'bun run tsc --noEmit' });

// Run tests
const tests = await shell.execute({ command: 'bun test' });
```

--------------------------------

### Test Service Functionality with TypeScript

Source: https://github.com/yosefhayim/cdp-agent/blob/main/docs/PROJECT_RULES.md

This snippet demonstrates how to test service functions using TypeScript and Vitest. It includes mocking database interactions and testing for successful operations and error handling, specifically for findById and create operations.

```typescript
// Location: src/services/__tests__/{{domain}}.service.test.ts

import { describe, it, expect, vi, beforeEach } from 'vitest';
import { {{domain}}Service } from '../{{domain}}.service';
import { db } from '@/lib/database';
import { NotFoundError } from '@/lib/errors';

// Mock database
vi.mock('@/lib/database', () => ({
  db: {
    {{entity}}: {
      findMany: vi.fn(),
      findUnique: vi.fn(),
      create: vi.fn(),
      update: vi.fn(),
      delete: vi.fn(),
    },
  },
}));

describe('{{domain}}Service', () => {
  beforeEach(() => {
    vi.clearAllMocks();
  });

  describe('findById', () => {
    it('returns {{entity}} when found', async () => {
      const mock{{Entity}} = { id: '1', name: 'Test' };
      vi.mocked(db.{{entity}}.findUnique).mockResolvedValue(mock{{Entity}});

      const result = await {{domain}}Service.findById('1');

      expect(result).toEqual(mock{{Entity}});
      expect(db.{{entity}}.findUnique).toHaveBeenCalledWith({ where: { id: '1' } });
    });

    it('throws NotFoundError when not found', async () => {
      vi.mocked(db.{{entity}}.findUnique).mockResolvedValue(null);

      await expect({{domain}}Service.findById('999'))
        .rejects
        .toThrow(NotFoundError);
    });
  });

  describe('create', () => {
    it('creates and returns new {{entity}}', async () => {
      const input = { name: 'New {{Entity}}' };
      const created = { id: '1', ...input };
      vi.mocked(db.{{entity}}.create).mockResolvedValue(created);

      const result = await {{domain}}Service.create(input);

      expect(result).toEqual(created);
      expect(db.{{entity}}.create).toHaveBeenCalledWith({ data: input });
    });
  });
});

```

--------------------------------

### Apply file edits and create files with edit_file tool

Source: https://context7.com/yosefhayim/cdp-agent/llms.txt

The edit_file tool allows for atomic file modifications using unified diffs or direct content writes. It validates context before applying patches and returns success status with metadata about the changes.

```typescript
import { createEditFileTool } from './tools/edit-file.js';

const editFile = createEditFileTool('/path/to/project');

// Apply a unified diff to modify existing file
const patchResult = await editFile.execute({
  path: 'src/utils.ts',
  diff: `--- a/src/utils.ts
+++ b/src/utils.ts
@@ -1,3 +1,4 @@
 import { join } from 'path';
+import { existsSync } from 'fs';

 export function resolvePath(p: string) {`
});

// Create a new file (non-diff content writes directly)
const newFile = await editFile.execute({
  path: 'src/constants.ts',
  diff: `export const API_VERSION = '1.0.0';
export const MAX_RETRIES = 3;`
});
```

--------------------------------

### DO: Check Authentication at Route/Page Level in TypeScript

Source: https://github.com/yosefhayim/cdp-agent/blob/main/docs/PROJECT_RULES.md

Shows the best practice for handling authentication checks by performing them at the route or page level to protect entire sections of the application, preventing unauthorized access early.

```typescript
// DO: Check auth at route/page level
export default async function ProtectedPage() {
  const session = await auth();
  if (!session) redirect('/login');
  // ...
}

```

--------------------------------

### Implement Data Fetching with TanStack Query

Source: https://github.com/yosefhayim/cdp-agent/blob/main/docs/PROJECT_RULES.md

A template for creating reusable React Query hooks. It demonstrates centralized query key management and standard CRUD patterns including invalidation logic for data consistency.

```typescript
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';

export const entityKeys = {
  all: ['entities'] as const,
  lists: () => [...entityKeys.all, 'list'] as const,
  list: (filters: string) => [...entityKeys.lists(), filters] as const,
  details: () => [...entityKeys.all, 'detail'] as const,
  detail: (id: string) => [...entityKeys.details(), id] as const,
};

export function useEntities(filters?: any) {
  return useQuery({
    queryKey: entityKeys.list(JSON.stringify(filters)),
    queryFn: () => api.getAll(filters),
  });
}

export function useCreateEntity() {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: (input: any) => api.create(input),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: entityKeys.lists() });
    },
  });
}
```

--------------------------------

### Test React Components with Testing Library

Source: https://github.com/yosefhayim/cdp-agent/blob/main/docs/PROJECT_RULES.md

A boilerplate for component unit testing using Vitest and React Testing Library. It covers rendering, user interactions, state management, and edge case handling.

```typescript
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { MyComponent } from './MyComponent';

describe('MyComponent', () => {
  const renderComponent = (props = {}) => render(<MyComponent {...props} />);

  it('renders correctly', () => {
    renderComponent();
    expect(screen.getByRole('button')).toBeInTheDocument();
  });

  it('calls onClick when clicked', async () => {
    const user = userEvent.setup();
    const handleClick = vi.fn();
    renderComponent({ onClick: handleClick });
    await user.click(screen.getByRole('button'));
    expect(handleClick).toHaveBeenCalledTimes(1);
  });
});
```

--------------------------------

### Interact with Gemini interface via GeminiProtocol

Source: https://context7.com/yosefhayim/cdp-agent/llms.txt

GeminiProtocol automates interactions with the Gemini web interface. It supports text injection, message submission, and response extraction, including logic to detect completion via UI stability signals.

```typescript
import { GeminiProtocol } from './browser/protocol.js';

// Inject text into the Gemini input
await GeminiProtocol.injectText(page, 'Explain this code: function add(a, b) { return a + b; }');

// Submit the message
await GeminiProtocol.submitMessage(page);

// Wait for response to complete
const completed = await GeminiProtocol.waitForCompletion(page, {
  stabilityThreshold: 3,
  stabilityPollingInterval: 500,
  shellTimeout: 120000
});
```

--------------------------------

### DO: Use Controlled Forms with Validation in TypeScript

Source: https://github.com/yosefhayim/cdp-agent/blob/main/docs/PROJECT_RULES.md

Illustrates the recommended approach for handling forms in TypeScript, emphasizing the use of controlled components and integrating validation, likely with a library like Zod.

```typescript
// DO: Use controlled forms with validation
const form = useForm<FormData>({
  resolver: zodResolver(formSchema),
  defaultValues: { name: '', email: '' },
});

```

--------------------------------

### Orchestrate ReAct Loop with cdp-agent

Source: https://context7.com/yosefhayim/cdp-agent/llms.txt

The ReActLoop class manages the reasoning-acting-observing cycle. It requires a session manager, tool definitions, and a protocol handler to execute tasks and handle state transitions.

```typescript
import { ReActLoop } from './engine/react-loop.js';
import { GeminiProtocol } from './browser/protocol.js';
import { parseResponse } from './engine/parser.js';
import { SessionManager } from './session/manager.js';

const tools = new Map<string, Tool>();
tools.set('read_file', createReadFileTool(config.workingDirectory, config.fileReadMaxSize));
tools.set('search_directory', createSearchDirectoryTool(config.workingDirectory));
tools.set('edit_file', createEditFileTool(config.workingDirectory));
tools.set('shell', createShellTool(config.workingDirectory, config.shellTimeout));

const sessionManager = new SessionManager('.cdp-agent-sessions');
const loop = new ReActLoop(page, GeminiProtocol, parseResponse, sessionManager, tools, config);

const result = await loop.run('Add input validation to the login form', 'session-123');

if (result.success) {
  console.log('Task completed:', result.finalResponse);
} else {
  console.log('Task failed:', result.reason);
}
```

--------------------------------

### Parse Gemini LLM Responses

Source: https://context7.com/yosefhayim/cdp-agent/llms.txt

The response parser extracts structured tool calls and completion signals from free-form text. It identifies reasoning, specific tool execution requests, and task status signals.

```typescript
import { parseResponse } from './engine/parser.js';

const toolResponse = parseResponse(`
THOUGHT: I need to read the main file.

```json
{
  "tool": "read_file",
  "args": { "path": "src/index.ts" }
}
```
`);

const completeResponse = parseResponse(`
TASK_COMPLETE: Added input validation.
`);

console.log(toolResponse.toolCalls);
console.log(completeResponse.signals.taskComplete);
```

--------------------------------

### React Component Structure with Hooks and Effects

Source: https://github.com/yosefhayim/cdp-agent/blob/main/docs/PROJECT_RULES.md

A standard React component pattern demonstrating the order of hooks, effects, event handlers, and rendering. It includes type definitions and utility imports for a clean structure. Assumes React and a utility for class name merging.

```tsx
// {{PROJECT_NAME}} Standard Component Pattern

import { useState, useEffect } from 'react';
import { cn } from '@/lib/utils';
import type { {{ComponentName}}Props } from './types';

/**
 * @description Brief description of component purpose
 * @example
 * <{{ComponentName}} prop="value" />
 */
export function {{ComponentName}}({
  className,
  children,
  ...props
}: {{ComponentName}}Props) {
  // 1. Hooks first (state, refs, custom hooks)
  const [state, setState] = useState(initialValue);

  // 2. Effects second
  useEffect(() => {
    // Side effects here
  }, [dependencies]);

  // 3. Event handlers third
  const handleAction = () => {
    // Handler logic
  };

  // 4. Render last
  return (
    <div className={cn('base-styles', className)} {...props}>
      {children}
    </div>
  );
}
```

--------------------------------

### TailwindCSS Styling Conventions for Consistency

Source: https://github.com/yosefhayim/cdp-agent/blob/main/docs/PROJECT_RULES.md

Guidelines for using TailwindCSS effectively, emphasizing consistent spacing, design system colors, and extracting repeated patterns into variables. It also highlights anti-patterns like using arbitrary values without justification and mixing styling approaches.

```tsx
// DO: Use consistent spacing scale
<div className="p-4 m-2 gap-4">  // 4 = 1rem = 16px

// DO: Use design system colors
<button className="bg-primary text-primary-foreground hover:bg-primary/90">

// DO: Extract repeated patterns to variables
const cardStyles = "rounded-lg border bg-card p-6 shadow-sm";
const buttonBase = "inline-flex items-center justify-center rounded-md text-sm font-medium";

// DON'T: Use arbitrary values without documented reason
<div className="p-[13px]">  // Why 13px specifically?

// DON'T: Mix styling approaches
<div className="p-4" style={{ margin: '8px' }}>  // Pick one approach
```

--------------------------------

### Implement Next.js API Route Pattern

Source: https://github.com/yosefhayim/cdp-agent/blob/main/docs/PROJECT_RULES.md

Provides a template for Next.js App Router API endpoints. It handles authentication, request parsing, service invocation, and standardized error responses.

```typescript
import { NextRequest, NextResponse } from 'next/server';
import { {{domain}}Service } from '@/services/{{domain}}.service';
import { handleApiError } from '@/lib/api-utils';
import { auth } from '@/lib/auth';

export async function GET(request: NextRequest) {
  try {
    const session = await auth();
    if (!session) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
    const { searchParams } = new URL(request.url);
    const filters = Object.fromEntries(searchParams);
    const data = await {{domain}}Service.findAll(filters);
    return NextResponse.json({ data });
  } catch (error) {
    return handleApiError(error);
  }
}

export async function POST(request: NextRequest) {
  try {
    const session = await auth();
    if (!session) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
    const body = await request.json();
    const data = await {{domain}}Service.create(body);
    return NextResponse.json({ data }, { status: 201 });
  } catch (error) {
    return handleApiError(error);
  }
}
```

--------------------------------

### Git Branch Naming Convention

Source: https://github.com/yosefhayim/cdp-agent/blob/main/docs/PROJECT_RULES.md

Outlines the standard format for naming Git branches within the project. The convention follows a pattern of type, task ID, and a short description to ensure clarity and consistency.

```bash
<type>/<task-id>-<short-description>

Examples:
feat/1.2-oauth-login
fix/2.1-null-response
refactor/3.4-card-component

```

--------------------------------

### DON'T: Check Authentication in Individual Components in TypeScript

Source: https://github.com/yosefhayim/cdp-agent/blob/main/docs/PROJECT_RULES.md

Highlights an anti-pattern where authentication checks are performed within individual components, which can lead to layout shifts and a less secure user experience by briefly exposing protected content.

```typescript
// DON'T: Check auth in individual components
function UserProfile() {
  const session = useSession();
  if (!session) return null; // This causes layout shift
  // ...
}

```

--------------------------------

### DON'T: Mix Controlled and Uncontrolled Inputs in TypeScript

Source: https://github.com/yosefhayim/cdp-agent/blob/main/docs/PROJECT_RULES.md

Demonstrates an anti-pattern in form handling where controlled and uncontrolled input elements are mixed, which can lead to state management issues and unpredictable behavior.

```typescript
// DON'T: Mix controlled and uncontrolled inputs
<input ref={inputRef} value={value} onChange={handleChange} />

```

--------------------------------

### Manage Tasks with MCP Tools

Source: https://github.com/yosefhayim/cdp-agent/blob/main/CLAUDE.md

A collection of MCP tool definitions used for task management within the Claude Code environment. These functions allow developers to view, update, and decompose tasks directly through the AI interface.

```javascript
// Task Management
get_tasks          // View all tasks
next_task          // Get next task to work on
get_task           // Show specific task details
set_task_status    // Mark task complete

// Task Operations
expand_task        // Break down into subtasks
update_subtask     // Log implementation notes
add_task           // Create new task
```

--------------------------------

### Implement Service Layer Pattern in TypeScript

Source: https://github.com/yosefhayim/cdp-agent/blob/main/docs/PROJECT_RULES.md

Defines a standardized service layer for CRUD operations using Prisma. It leverages Zod schemas for validation and custom error classes for robust exception handling.

```typescript
import { db } from '@/lib/database';
import { {{Entity}}CreateSchema, {{Entity}}UpdateSchema } from '@/schemas';
import { NotFoundError, ValidationError } from '@/lib/errors';
import type { {{Entity}}, Create{{Entity}}Input, Update{{Entity}}Input } from '@/types';

export const {{domain}}Service = {
  async findAll(filters?: {{Entity}}Filters): Promise<{{Entity}}[]> {
    return db.{{entity}}.findMany({
      where: filters,
      orderBy: { createdAt: 'desc' },
    });
  },

  async findById(id: string): Promise<{{Entity}}> {
    const result = await db.{{entity}}.findUnique({ where: { id } });
    if (!result) {
      throw new NotFoundError(`{{Entity}} with id ${id} not found`);
    }
    return result;
  },

  async create(input: Create{{Entity}}Input): Promise<{{Entity}}> {
    const validated = {{Entity}}CreateSchema.parse(input);
    return db.{{entity}}.create({ data: validated });
  },

  async update(id: string, input: Update{{Entity}}Input): Promise<{{Entity}}> {
    await this.findById(id);
    const validated = {{Entity}}UpdateSchema.parse(input);
    return db.{{entity}}.update({ where: { id }, data: validated });
  },

  async delete(id: string): Promise<void> {
    await this.findById(id);
    await db.{{entity}}.delete({ where: { id } });
  },
};
```

--------------------------------

### Manage Persistent Sessions

Source: https://context7.com/yosefhayim/cdp-agent/llms.txt

The SessionManager handles atomic persistence of agent states to JSON files. This allows for task interruption, resumption, and listing of historical sessions.

```typescript
import { SessionManager } from './session/manager.js';

const sessionManager = new SessionManager('.cdp-agent-sessions');

await sessionManager.save({
  id: 'abc123',
  prompt: 'Refactor the auth module',
  steps: [{
    thought: 'First, I need to find the auth files',
    action: { tool: 'search_directory', args: { pattern: '**/auth*.ts' } },
    observation: { success: true, output: 'src/auth/login.ts' },
    timestamp: Date.now()
  }],
  config: { maxIterations: 50 },
  createdAt: '2024-01-15T10:00:00Z',
  lastStepAt: '2024-01-15T10:05:00Z'
});

const sessions = await sessionManager.list();
const session = await sessionManager.load('abc123');
```

--------------------------------

### Handle API Errors with TypeScript

Source: https://github.com/yosefhayim/cdp-agent/blob/main/docs/PROJECT_RULES.md

A centralized utility function to standardize API error responses in Next.js. It handles specific AppError instances, Zod validation errors, and provides a fallback for unexpected server errors to prevent information leakage.

```typescript
import { NextResponse } from 'next/server';
import { AppError } from './errors';
import { ZodError } from 'zod';

export function handleApiError(error: unknown) {
  console.error('API Error:', error);

  if (error instanceof AppError) {
    return NextResponse.json(
      { 
        error: { 
          code: error.code, 
          message: error.message,
          details: error.details 
        } 
      },
      { status: error.statusCode }
    );
  }

  if (error instanceof ZodError) {
    return NextResponse.json(
      { 
        error: { 
          code: 'VALIDATION_ERROR', 
          message: 'Invalid request data',
          details: error.flatten() 
        } 
      },
      { status: 400 }
    );
  }

  return NextResponse.json(
    { 
      error: { 
        code: 'INTERNAL_ERROR', 
        message: 'An unexpected error occurred' 
      } 
    },
    { status: 500 }
  );
}
```

--------------------------------

### Manage BrowserBridge connection

Source: https://context7.com/yosefhayim/cdp-agent/llms.txt

BrowserBridge handles the lifecycle of the Chrome DevTools Protocol connection. It facilitates discovery of the WebSocket endpoint and provides access to the Puppeteer page object for browser automation.

```typescript
import { BrowserBridge } from './browser/index.js';
import { loadConfig } from './config/loader.js';

const config = loadConfig({ port: 9222, verbose: true });
const bridge = new BrowserBridge(config);

// Connect to existing Chrome instance
await bridge.connect();

// Get the Puppeteer page object for the Gemini tab
const connection = bridge.getConnection();
const page = connection.page;
```

--------------------------------

### Define Custom Error Classes

Source: https://github.com/yosefhayim/cdp-agent/blob/main/docs/PROJECT_RULES.md

Establishes a hierarchy of custom error classes extending a base AppError. This ensures consistent error reporting across the application with appropriate HTTP status codes.

```typescript
export class AppError extends Error {
  constructor(
    message: string,
    public code: string,
    public statusCode: number = 500,
    public details?: unknown
  ) {
    super(message);
    this.name = 'AppError';
  }
}

export class NotFoundError extends AppError {
  constructor(message: string) {
    super(message, 'NOT_FOUND', 404);
    this.name = 'NotFoundError';
  }
}

export class ValidationError extends AppError {
  constructor(message: string, details?: unknown) {
    super(message, 'VALIDATION_ERROR', 400, details);
    this.name = 'ValidationError';
  }
}
```
Tokens:
Raw