@poolzin/pool-bot 2026.3.21 → 2026.3.23

package/docs/improvements/USAGE-GUIDE.md

@@ -0,0 +1,359 @@
+# Pool Bot Improvements - Usage Guide
+
+## Overview
+
+This guide documents the professional improvements implemented in Pool Bot, providing usage examples and integration points.
+
+---
+
+## Table of Contents
+
+1. [Event Deduplication](#1-event-deduplication)
+2. [Run Tracker](#2-run-tracker)
+3. [Command Analyzer](#3-command-analyzer)
+4. [Browser Profile Manager](#4-browser-profile-manager)
+
+---
+
+## 1. Event Deduplication
+
+**Location:** `src/gateway/event-deduplication.ts`
+
+**Purpose:** Prevent duplicate event processing within a configurable time window.
+
+### Basic Usage
+
+```typescript
+import { EventDeduplicator, generateEventId } from './gateway/event-deduplication';
+
+// Create deduplicator with 5 second TTL
+const dedup = new EventDeduplicator({ ttlMs: 5000 });
+
+// In event handler
+function handleEvent(event: Event) {
+  const eventId = generateEventId({
+    type: event.type,
+    sessionId: event.sessionId,
+    payload: event.payload
+  });
+  
+  if (dedup.isDuplicate(eventId)) {
+    console.log(`Skipping duplicate event ${eventId}`);
+    return;
+  }
+  
+  // Process event
+  processEvent(event);
+}
+```
+
+### Advanced Configuration
+
+```typescript
+const dedup = new EventDeduplicator({
+  ttlMs: 10000,        // 10 second TTL
+  maxSize: 5000,       // Max 5000 events in memory
+  autoCleanup: true    // Auto cleanup expired events
+});
+
+// Get statistics
+const stats = dedup.getStats();
+console.log(`Total events: ${stats.totalEvents}`);
+console.log(`Duplicates: ${stats.duplicates}`);
+
+// Manual cleanup
+const removed = dedup.cleanup();
+console.log(`Removed ${removed} expired events`);
+```
+
+### Use Cases
+
+- **Gateway event processing:** Prevent duplicate WebSocket events
+- **Retry handling:** Avoid processing retried events multiple times
+- **Race condition prevention:** Handle concurrent event submissions
+
+---
+
+## 2. Run Tracker
+
+**Location:** `src/gateway/run-tracker.ts`
+
+**Purpose:** Track active agent runs with AbortController support for cancellation.
+
+### Basic Usage
+
+```typescript
+import { RunTracker, generateRunId } from './gateway/run-tracker';
+
+const tracker = new RunTracker();
+
+// Start a new run
+const run = tracker.startRun(generateRunId(), {
+  sessionKey: 'session-123',
+  model: 'gpt-4'
+});
+
+// Stream data
+await tracker.writeToRun(run.runId, {
+  type: 'chunk',
+  data: 'response chunk'
+});
+
+// Complete on success
+await tracker.completeRun(run.runId, {
+  outputTokens: 150,
+  inputTokens: 50
+});
+
+// Or abort on cancel
+await tracker.abortRun(run.runId, 'User cancelled');
+```
+
+### Error Handling
+
+```typescript
+try {
+  const run = tracker.startRun(runId, { sessionKey, model });
+  
+  // Process...
+  await tracker.writeToRun(runId, chunk);
+  
+  await tracker.completeRun(runId);
+} catch (error) {
+  await tracker.failRun(runId, error);
+}
+```
+
+### Session Grouping
+
+```typescript
+// Get all runs for a session
+const sessionRuns = tracker.getRunsBySession('session-123');
+
+// Get statistics
+const stats = tracker.getStats();
+console.log(`Active runs: ${stats.activeRuns}`);
+console.log(`Completed: ${stats.completedRuns}`);
+console.log(`Average duration: ${stats.averageDuration}ms`);
+```
+
+### Use Cases
+
+- **Agent loop tracking:** Monitor active LLM runs
+- **Resource cleanup:** Prevent memory leaks from abandoned runs
+- **User cancellation:** Support clean abort of long operations
+- **Observability:** Track run duration and success rates
+
+---
+
+## 3. Command Analyzer
+
+**Location:** `src/infra/security/command-analyzer.ts`
+
+**Purpose:** Analyze commands for security risks before execution.
+
+### Basic Usage
+
+```typescript
+import { CommandAnalyzer } from './infra/security/command-analyzer';
+
+const analyzer = new CommandAnalyzer();
+
+// Analyze command
+const analysis = analyzer.analyze(command, args);
+
+if (analysis.blockedReason) {
+  throw new SecurityError(analysis.blockedReason);
+}
+
+if (analysis.requiresApproval) {
+  const approved = await requestApproval(analysis);
+  if (!approved) {
+    throw new Error('Command not approved');
+  }
+}
+
+// Execute command
+await execute(command, args);
+```
+
+### Risk Levels
+
+```typescript
+// Low risk - safe to execute
+const safe = analyzer.analyze('ls', ['-la']);
+// riskLevel: 'low', requiresApproval: false
+
+// Medium risk - requires approval
+const medium = analyzer.analyze('kill', ['-9', '1234']);
+// riskLevel: 'medium', requiresApproval: true
+
+// High risk - shell wrapper detected
+const high = analyzer.analyze('bash', ['-c', 'rm -rf /']);
+// riskLevel: 'high', requiresApproval: true
+
+// Critical - blocked
+const critical = analyzer.analyze('rm', ['-rf', '/']);
+// riskLevel: 'critical', blockedReason: 'Recursive/force delete'
+```
+
+### Path Sanitization
+
+```typescript
+import { PathSanitizer } from './infra/security/command-analyzer';
+
+const sanitizer = new PathSanitizer('/workspace');
+
+// Sanitize path
+const safePath = sanitizer.sanitize('./file.txt');
+// Returns: '/workspace/file.txt'
+
+// Block traversal
+try {
+  sanitizer.sanitize('../etc/passwd');
+} catch (error) {
+  console.error('Path traversal blocked');
+}
+
+// Sanitize arguments
+const safeArgs = sanitizer.sanitizeArguments(['./file.txt', 'arg2']);
+```
+
+### Integration with Node Invoke
+
+The Command Analyzer is already integrated in `src/gateway/server-methods/nodes.ts`:
+
+```typescript
+// In node.invoke handler
+const analysis = commandAnalyzer.analyze(command, []);
+
+if (analysis.blockedReason) {
+  context.logGateway.warn(
+    `node.invoke blocked command=${command} reason=${analysis.blockedReason}`
+  );
+  respond(false, undefined, errorShape(...));
+  return;
+}
+```
+
+### Use Cases
+
+- **Node command execution:** Security check before running commands on devices
+- **Shell command validation:** Prevent dangerous command execution
+- **Injection prevention:** Detect command injection attempts
+- **Audit logging:** Log risky command attempts
+
+---
+
+## 4. Browser Profile Manager
+
+**Location:** `src/browser/chrome-mcp.ts` (integrated)
+
+**Purpose:** Manage multiple Chrome profiles with isolated user data.
+
+### Basic Usage
+
+```typescript
+import { registerBrowserProfile, getBrowserProfile } from './browser/chrome-mcp';
+
+// Register a profile
+registerBrowserProfile({
+  name: 'profile-1',
+  userDataDir: '/tmp/chrome-profile-1',
+  preferences: {
+    'download.default_directory': '/tmp/downloads'
+  }
+});
+
+// Get profile
+const profile = getBrowserProfile('profile-1');
+
+// List all profiles
+const profiles = listBrowserProfiles();
+```
+
+### Multiple Profiles
+
+```typescript
+// Register multiple isolated profiles
+registerBrowserProfile({
+  name: 'work',
+  userDataDir: '/tmp/chrome-work',
+  proxy: {
+    host: 'proxy.example.com',
+    port: 8080
+  }
+});
+
+registerBrowserProfile({
+  name: 'personal',
+  userDataDir: '/tmp/chrome-personal'
+});
+
+// Each profile has isolated:
+// - Cookies
+// - LocalStorage
+// - Extensions
+// - Preferences
+```
+
+### Use Cases
+
+- **Multi-account automation:** Separate browser sessions for different accounts
+- **Testing:** Isolated browser environments for testing
+- **Privacy:** Separate work/personal browsing contexts
+- **Proxy per profile:** Different network contexts per profile
+
+---
+
+## Testing
+
+All components include comprehensive test suites:
+
+```bash
+# Run tests
+pnpm test src/gateway/event-deduplication.test.ts
+pnpm test src/gateway/run-tracker.test.ts
+pnpm test src/infra/security/command-analyzer.test.ts
+```
+
+### Test Coverage
+
+- **Event Deduplication:** 15+ tests
+- **Run Tracker:** 20+ tests
+- **Command Analyzer:** 30+ tests
+
+---
+
+## Performance
+
+| Component | Memory | CPU | Latency |
+|-----------|--------|-----|---------|
+| Event Dedup | ~100KB | <1ms | <1ms |
+| Run Tracker | ~50KB/run | <1ms | <1ms |
+| Command Analyzer | ~50KB | <1ms | <1ms |
+| Browser Profiles | ~1MB/profile | <5ms | <10ms |
+
+---
+
+## Best Practices
+
+1. **Always check OpenClaw first** - Don't duplicate existing functionality
+2. **Integrate, don't duplicate** - New code should be used, not isolated
+3. **Test thoroughly** - Target 70%+ coverage
+4. **Document usage** - Provide clear examples
+5. **Monitor performance** - Track memory and latency impact
+
+---
+
+## Support
+
+For issues or questions:
+- Check existing documentation in `docs/`
+- Review test files for usage examples
+- Open GitHub issue with reproduction steps
+
+---
+
+**Last Updated:** March 2026
+**Version:** 1.0