fix: small prompt fixes

2026-05-13 21:42:08 +00:00 · 2026-04-04 13:22:01 +02:00
parent a1a59a610a
commit 9820566567
4 changed files with 720 additions and 9 deletions
--- a/_docs/IMPROVEMENTS.md
+++ b/_docs/IMPROVEMENTS.md
@@ -0,0 +1,711 @@
+# ManBot AI Platform - Proposed Improvements
+
+## Overview
+This document outlines comprehensive improvements for the ManBot AI platform based on architectural analysis, code quality assessment, and performance considerations.
+
+## Project Analysis Summary
+
+ManBot is a sophisticated multi-process AI platform with type-safe IPC and capability-graph execution. It demonstrates excellent architectural foundation with room for refinement in type safety, performance optimization, and developer experience.
+
+### Current Strengths
+- **Multi-agent pipeline**: Well-structured Planner → Task Memory → Executor → Critic flow
+- **Type-safe IPC**: Zod-validated envelopes with JSONL communication
+- **Capability graph**: DAG-based execution with parallel processing
+- **Modular design**: Clear separation between adapters, agents, services, and shared utilities
+- **Local-first approach**: No cloud dependencies for core AI functionality
+- **Comprehensive feature set**: File processing, reminders, RAG, monitoring dashboard
+
+### Key Metrics from Analysis
+- **Test coverage**: 17 test files covering core functionality
+- **Type safety concerns**: 396+ instances of `any/unknown` types
+- **Import complexity**: 126+ relative imports using `../` patterns
+- **Async usage**: 727+ async/await patterns for optimization opportunities
+- **Error handling**: 66+ try/catch/throw patterns across services
+
+---
+
+## Proposed Improvements
+
+### 1. Code Organization & Maintainability
+
+#### 1.1 Type Safety Improvements
+**Priority**: High
+**Impact**: Code reliability and developer experience
+
+**Current Issues:**
+- 396+ matches for `any/unknown` types across 41 files
+- Missing type definitions in protocol schemas
+- Inconsistent error type handling
+
+**Proposed Actions:**
+```typescript
+// Replace any types with proper interfaces
+// Before
+const data: any = response.data;
+
+// After
+interface ApiResponse<T> {
+  data: T;
+  status: number;
+  message?: string;
+}
+const data: ApiResponse<ExpectedType> = response.data;
+```
+
+**Implementation Steps:**
+1. Audit all `any` types in `src/shared/protocol.ts`
+2. Create comprehensive interfaces for all API responses
+3. Add generic type parameters for reusable components
+4. Implement strict error type hierarchy
+
+#### 1.2 Import Path Optimization
+**Priority**: High
+**Impact**: Code maintainability and refactoring
+
+**Current Issues:**
+- 126+ relative imports using `../` patterns
+- Deep import paths making refactoring difficult
+- Inconsistent import organization
+
+**Proposed Actions:**
+```typescript
+// tsconfig.json additions
+{
+  "compilerOptions": {
+    "paths": {
+      "@shared/*": ["src/shared/*"],
+      "@agents/*": ["src/agents/*"],
+      "@services/*": ["src/services/*"],
+      "@adapters/*": ["src/adapters/*"]
+    }
+  }
+}
+
+// Replace relative imports
+// Before
+import { Envelope } from "../shared/protocol.js";
+import { BaseProcess } from "../shared/base-process.js";
+
+// After
+import { Envelope } from "@shared/protocol.js";
+import { BaseProcess } from "@shared/base-process.js";
+```
+
+**Implementation Steps:**
+1. Configure path mapping in `tsconfig.json`
+2. Create barrel exports in major directories
+3. Systematically replace relative imports
+4. Update build configuration
+
+#### 1.3 Error Handling Standardization
+**Priority**: Medium
+**Impact**: Debugging and user experience
+
+**Current Issues:**
+- Inconsistent error types across services
+- Missing error context in some cases
+- No centralized error handling patterns
+
+**Proposed Actions:**
+```typescript
+// Create centralized error types
+export class ManBotError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly service: string,
+    public readonly context?: Record<string, unknown>
+  ) {
+    super(message);
+    this.name = 'ManBotError';
+  }
+}
+
+// Service-specific error classes
+export class LemonadeError extends ManBotError {
+  constructor(message: string, context?: Record<string, unknown>) {
+    super(message, 'LEMONADE_ERROR', 'lemonade-adapter', context);
+  }
+}
+```
+
+---
+
+### 2. Performance Optimizations
+
+#### 2.1 Browser Service Enhancement
+**Priority**: Medium
+**Impact**: Web scraping performance and resource usage
+
+**Current Issues:**
+- Each request spawns new browser instance (100-200MB per instance)
+- No connection pooling for multiple requests
+- Potential memory leaks with browser contexts
+
+**Proposed Actions:**
+```typescript
+// Browser connection pool
+class BrowserPool {
+  private browsers: Browser[] = [];
+  private maxBrowsers = 3;
+  private requestQueue: Array<{
+    url: string;
+    resolve: (result: any) => void;
+    reject: (error: Error) => void;
+  }> = [];
+
+  async executeRequest(url: string): Promise<any> {
+    return new Promise((resolve, reject) => {
+      this.requestQueue.push({ url, resolve, reject });
+      this.processQueue();
+    });
+  }
+
+  private async processQueue() {
+    if (this.requestQueue.length === 0) return;
+    
+    const browser = await this.getAvailableBrowser();
+    const request = this.requestQueue.shift();
+    
+    if (request) {
+      this.executeWithBrowser(browser, request);
+    }
+  }
+}
+```
+
+#### 2.2 Model Management Optimization
+**Priority**: Medium
+**Impact**: AI model response times and resource utilization
+
+**Current Issues:**
+- Cold start delays for large models
+- No intelligent preloading based on usage patterns
+- Fixed keep-alive durations regardless of usage
+
+**Proposed Actions:**
+```typescript
+// Smart model manager
+class SmartModelManager {
+  private usagePatterns = new Map<string, {
+    lastUsed: Date;
+    frequency: number;
+    avgResponseTime: number;
+  }>();
+
+  predictModelUsage(modelName: string): number {
+    const pattern = this.usagePatterns.get(modelName);
+    if (!pattern) return 0;
+    
+    const hoursSinceLastUse = (Date.now() - pattern.lastUsed.getTime()) / (1000 * 60 * 60);
+    const frequencyScore = pattern.frequency / 24; // requests per hour
+    const recencyScore = Math.max(0, 1 - hoursSinceLastUse / 24);
+    
+    return frequencyScore * recencyScore;
+  }
+
+  optimizeKeepAlive(modelName: string): string {
+    const prediction = this.predictModelUsage(modelName);
+    if (prediction > 0.5) return "2h";
+    if (prediction > 0.2) return "30m";
+    return "10m";
+  }
+}
+```
+
+#### 2.3 Async Pattern Optimization
+**Priority**: Medium
+**Impact**: System responsiveness and throughput
+
+**Current Issues:**
+- 727+ async/await patterns that could be optimized
+- Some sequential operations that could be parallelized
+- Missing Promise.all optimizations
+
+**Proposed Actions:**
+```typescript
+// Before: Sequential operations
+async function processFiles(files: string[]) {
+  const results = [];
+  for (const file of files) {
+    const result = await processFile(file);
+    results.push(result);
+  }
+  return results;
+}
+
+// After: Parallel operations with batching
+async function processFiles(files: string[], batchSize = 5) {
+  const results = [];
+  for (let i = 0; i < files.length; i += batchSize) {
+    const batch = files.slice(i, i + batchSize);
+    const batchResults = await Promise.all(
+      batch.map(file => processFile(file))
+    );
+    results.push(...batchResults);
+  }
+  return results;
+}
+```
+
+---
+
+### 3. Security & Dependencies
+
+#### 3.1 Dependency Security Audit
+**Priority**: High
+**Impact**: Security posture and vulnerability management
+
+**Proposed Actions:**
+```bash
+# Security audit commands
+npm audit --audit-level moderate
+npm audit fix
+npm update
+
+# Add to package.json scripts
+{
+  "scripts": {
+    "security:audit": "npm audit --audit-level moderate",
+    "security:check": "npm outdated",
+    "security:fix": "npm audit fix && npm update"
+  }
+}
+```
+
+**Implementation Steps:**
+1. Run comprehensive dependency audit
+2. Update vulnerable packages
+3. Implement automated security scanning in CI/CD
+4. Create dependency update policy
+
+#### 3.2 Environment Configuration Validation
+**Priority**: Medium
+**Impact**: Runtime reliability and deployment safety
+
+**Proposed Actions:**
+```typescript
+// Runtime configuration validation
+import { z } from "zod";
+
+const configSchema = z.object({
+  telegram: z.object({
+    botToken: z.string().min(1, "Telegram bot token is required"),
+    allowedUserIds: z.string().optional(),
+  }),
+  lemonade: z.object({
+    baseUrl: z.string().url("Invalid Lemonade base URL"),
+    timeout: z.number().min(1000, "Timeout must be at least 1 second"),
+  }),
+  rag: z.object({
+    embedModel: z.string().min(1),
+    dbPath: z.string().min(1),
+    embeddingDimensions: z.number().positive(),
+  }),
+});
+
+export function validateConfig(config: unknown) {
+  return configSchema.parse(config);
+}
+```
+
+#### 3.3 Input Sanitization Enhancement
+**Priority**: Medium
+**Impact**: Security and data integrity
+
+**Proposed Actions:**
+```typescript
+// Input sanitization utilities
+class InputSanitizer {
+  static sanitizeString(input: unknown, maxLength = 10000): string {
+    if (typeof input !== 'string') {
+      throw new Error('Input must be a string');
+    }
+    
+    return input
+      .trim()
+      .slice(0, maxLength)
+      .replace(/[<>]/g, ''); // Basic HTML tag removal
+  }
+
+  static sanitizeFilePath(path: unknown): string {
+    const cleanPath = this.sanitizeString(path, 255);
+    // Prevent path traversal
+    return cleanPath.replace(/\.\./g, '').replace(/^\//, '');
+  }
+
+  static validateTelegramUserId(userId: unknown): number {
+    const id = Number(userId);
+    if (!Number.isInteger(id) || id <= 0) {
+      throw new Error('Invalid Telegram user ID');
+    }
+    return id;
+  }
+}
+```
+
+---
+
+### 4. Testing & Quality Assurance
+
+#### 4.1 End-to-End Testing Framework
+**Priority**: Medium
+**Impact**: System reliability and regression prevention
+
+**Proposed Actions:**
+```typescript
+// E2E test framework
+class E2ETestSuite {
+  async testCompleteWorkflow(userInput: string) {
+    // 1. Send message to Telegram adapter
+    const response = await this.sendTelegramMessage(userInput);
+    
+    // 2. Verify task creation
+    const task = await this.waitForTaskCreation();
+    expect(task.goal).toContain(userInput);
+    
+    // 3. Monitor execution pipeline
+    const execution = await this.monitorExecution(task.id);
+    expect(execution.status).toBe('completed');
+    
+    // 4. Verify response delivery
+    const finalResponse = await this.waitForTelegramResponse();
+    expect(finalResponse).toBeDefined();
+  }
+}
+```
+
+#### 4.2 Performance Benchmarking
+**Priority**: Medium
+**Impact**: Performance regression detection
+
+**Proposed Actions:**
+```typescript
+// Performance benchmarks
+describe('Performance Benchmarks', () => {
+  it('should process simple task within 5 seconds', async () => {
+    const start = Date.now();
+    await processSimpleTask('Hello world');
+    const duration = Date.now() - start;
+    expect(duration).toBeLessThan(5000);
+  });
+
+  it('should handle concurrent requests efficiently', async () => {
+    const requests = Array(10).fill(null).map(() => 
+      processSimpleTask('Concurrent test')
+    );
+    
+    const start = Date.now();
+    await Promise.all(requests);
+    const duration = Date.now() - start;
+    
+    // Should be significantly faster than sequential processing
+    expect(duration).toBeLessThan(15000);
+  });
+});
+```
+
+#### 4.3 Coverage Analysis Integration
+**Priority**: Low
+**Impact**: Code quality visibility
+
+**Proposed Actions:**
+```json
+// package.json additions
+{
+  "scripts": {
+    "test:coverage": "vitest run --coverage",
+    "test:coverage:report": "vitest run --coverage && open coverage/index.html",
+    "test:watch:coverage": "vitest --coverage --watch"
+  }
+}
+```
+
+---
+
+### 5. Architecture Enhancements
+
+#### 5.1 Service Discovery System
+**Priority**: Low
+**Impact**: System flexibility and scalability
+
+**Proposed Actions:**
+```typescript
+// Service discovery registry
+class ServiceRegistry {
+  private services = new Map<string, ServiceInfo>();
+
+  register(service: ServiceInfo) {
+    this.services.set(service.name, service);
+    this.announceService(service);
+  }
+
+  discover(serviceName: string): ServiceInfo | null {
+    return this.services.get(serviceName) || null;
+  }
+
+  private announceService(service: ServiceInfo) {
+    // Announce service availability to other components
+    this.broadcast('service:registered', service);
+  }
+}
+
+interface ServiceInfo {
+  name: string;
+  version: string;
+  endpoint: string;
+  capabilities: string[];
+  healthCheck: () => Promise<boolean>;
+}
+```
+
+#### 5.2 Circuit Breaker Pattern
+**Priority**: Low
+**Impact**: System resilience and fault tolerance
+
+**Proposed Actions:**
+```typescript
+// Circuit breaker implementation
+class CircuitBreaker {
+  private failures = 0;
+  private state: 'CLOSED' | 'OPEN' | 'HALF_OPEN' = 'CLOSED';
+  private lastFailureTime = 0;
+
+  async execute<T>(operation: () => Promise<T>): Promise<T> {
+    if (this.state === 'OPEN') {
+      if (Date.now() - this.lastFailureTime > this.timeout) {
+        this.state = 'HALF_OPEN';
+      } else {
+        throw new Error('Circuit breaker is OPEN');
+      }
+    }
+
+    try {
+      const result = await operation();
+      this.onSuccess();
+      return result;
+    } catch (error) {
+      this.onFailure();
+      throw error;
+    }
+  }
+
+  private onSuccess() {
+    this.failures = 0;
+    this.state = 'CLOSED';
+  }
+
+  private onFailure() {
+    this.failures++;
+    this.lastFailureTime = Date.now();
+    
+    if (this.failures >= this.threshold) {
+      this.state = 'OPEN';
+    }
+  }
+}
+```
+
+#### 5.3 Metrics Collection System
+**Priority**: Low
+**Impact**: Operational visibility and performance monitoring
+
+**Proposed Actions:**
+```typescript
+// Metrics collection
+class MetricsCollector {
+  private metrics = new Map<string, Metric>();
+
+  increment(name: string, value = 1, tags?: Record<string, string>) {
+    const metric = this.getOrCreateMetric(name, 'counter');
+    metric.value += value;
+    metric.tags = tags;
+  }
+
+  histogram(name: string, value: number, tags?: Record<string, string>) {
+    const metric = this.getOrCreateMetric(name, 'histogram');
+    metric.values.push(value);
+    metric.tags = tags;
+  }
+
+  gauge(name: string, value: number, tags?: Record<string, string>) {
+    const metric = this.getOrCreateMetric(name, 'gauge');
+    metric.value = value;
+    metric.tags = tags;
+  }
+
+  getMetrics(): MetricSnapshot[] {
+    return Array.from(this.metrics.values()).map(metric => ({
+      ...metric,
+      timestamp: Date.now(),
+    }));
+  }
+}
+```
+
+---
+
+### 6. Developer Experience Improvements
+
+#### 6.1 Development Server with Hot Reload
+**Priority**: Low
+**Impact**: Development productivity
+
+**Proposed Actions:**
+```typescript
+// Development server
+class DevServer {
+  private watchers: Array<() => void> = [];
+
+  start() {
+    // Watch TypeScript files
+    this.watch('src/**/*.ts', () => {
+      this.rebuild();
+      this.restartServices();
+    });
+
+    // Watch configuration files
+    this.watch('config.json', () => {
+      this.reloadConfig();
+    });
+  }
+
+  private async rebuild() {
+    console.log('🔨 Rebuilding...');
+    await this.run('npm run build');
+    console.log('✅ Build complete');
+  }
+
+  private async restartServices() {
+    console.log('🔄 Restarting services...');
+    // Restart only changed services
+  }
+}
+```
+
+#### 6.2 Enhanced Debugging Tools
+**Priority**: Low
+**Impact**: Debugging efficiency
+
+**Proposed Actions:**
+```typescript
+// Debugging utilities
+class DebugTools {
+  static async traceMessageFlow(messageId: string) {
+    const trace = await this.collectTrace(messageId);
+    console.table(trace);
+  }
+
+  static async inspectService(serviceName: string) {
+    const status = await this.getServiceStatus(serviceName);
+    const metrics = await this.getServiceMetrics(serviceName);
+    
+    return { status, metrics };
+  }
+
+  static async simulateFailure(serviceName: string, errorType: string) {
+    // Controlled failure simulation for testing
+  }
+}
+```
+
+#### 6.3 CLI Management Commands
+**Priority**: Low
+**Impact**: Operational efficiency
+
+**Proposed Actions:**
+```bash
+# CLI commands to implement
+manbot start              # Start all services
+manbot stop               # Stop all services
+manbot status             # Show service status
+manbot logs [service]     # Show service logs
+manbot config validate    # Validate configuration
+manbot config show        # Show current configuration
+manbot test e2e          # Run end-to-end tests
+manbot benchmark         # Run performance benchmarks
+```
+
+---
+
+## Implementation Roadmap
+
+### Phase 1: High Priority (1-2 weeks)
+1. **Type Safety Improvements**
+   - Audit and replace `any` types
+   - Create comprehensive interfaces
+   - Implement strict error types
+
+2. **Import Path Optimization**
+   - Configure path mapping
+   - Create barrel exports
+   - Replace relative imports
+
+3. **Security Audit**
+   - Run dependency audit
+   - Update vulnerable packages
+   - Implement security scanning
+
+### Phase 2: Medium Priority (2-4 weeks)
+1. **Performance Optimizations**
+   - Browser service pooling
+   - Smart model management
+   - Async pattern optimization
+
+2. **Testing Enhancement**
+   - E2E testing framework
+   - Performance benchmarks
+   - Coverage analysis
+
+3. **Error Handling Standardization**
+   - Centralized error types
+   - Consistent error patterns
+   - Enhanced error context
+
+### Phase 3: Low Priority (4-8 weeks)
+1. **Architecture Enhancements**
+   - Service discovery
+   - Circuit breakers
+   - Metrics collection
+
+2. **Developer Experience**
+   - Development server
+   - Debugging tools
+   - CLI commands
+
+3. **Documentation & Maintenance**
+   - API documentation
+   - Architecture diagrams
+   - Maintenance guides
+
+---
+
+## Success Metrics
+
+### Code Quality Metrics
+- **Type Safety**: Reduce `any` usage by 90%
+- **Import Complexity**: Reduce relative imports by 80%
+- **Test Coverage**: Achieve 85%+ coverage
+- **Error Handling**: Standardize error patterns across all services
+
+### Performance Metrics
+- **Response Time**: 20% improvement in average task completion
+- **Memory Usage**: 30% reduction in browser service memory
+- **Concurrency**: Handle 10x more concurrent requests
+- **Uptime**: 99.9% service availability
+
+### Developer Experience Metrics
+- **Setup Time**: Reduce new developer setup to <15 minutes
+- **Debug Time**: 50% reduction in debugging time
+- **Build Time**: <5 second incremental builds
+- **Documentation**: 100% API coverage
+
+---
+
+## Conclusion
+
+The ManBot platform demonstrates excellent architectural foundation with sophisticated multi-agent capabilities. The proposed improvements focus on enhancing type safety, performance optimization, security hardening, and developer experience while maintaining the platform's core strengths.
+
+Implementing these improvements incrementally will ensure continued platform evolution while maintaining system stability and reliability. The phased approach allows for careful testing and validation of each enhancement before full deployment.
+
+The improvements outlined in this document provide a clear roadmap for elevating ManBot from a functional prototype to a production-ready, enterprise-grade AI platform.
--- a/src/agents/prompts/planner.ts
+++ b/src/agents/prompts/planner.ts
@@ -35,7 +35,7 @@ Before using raw tools, scan <available_skills>.
 - Manual "shell" or "http" chains are a last resort when no skill fits.

 ## 2. TOOL CONSTRAINTS
-The "tool-host" service supports ONLY these 3 names in the "tool" field:
+The "tool-host" service supports ONLY these 4 names in the "tool" field:
 - **"shell"**: For ALL terminal commands. (Example: \`"tool": "shell", "arguments": { "command": "cat file.txt" }\`)
 - **"http_get"**: For rendering a specific URL (Playwright).
 - **"http_search"**: For finding information on the web.
--- a/src/agents/prompts/telegram-html.ts
+++ b/src/agents/prompts/telegram-html.ts
@@ -7,9 +7,9 @@
 export const TELEGRAM_HTML_FORMAT_INSTRUCTION = `## TELEGRAM HTML FORMATTING RULES:
 You MUST format your output using Telegram-supported HTML tags. Do NOT use Markdown syntax.

-1. **No Markdown**: Do NOT use *, **, _, ~~, \`, #, or any Markdown syntax. Use HTML tags only.
-2. **No Tables**: HTML tables are not supported by Telegram. Use structured bullet points (•) or bold lists.
-3. **Supported HTML tags**:
+1. NO Markdown: Do NOT use *, **, _, ~~, \`, #, or any Markdown syntax. Use HTML tags only.
+2. NO Tables: HTML tables are not supported by Telegram. Use structured bullet points (•) or bold lists.
+3. Supported HTML tags:
   - Bold: <b>text</b>
   - Italic: <i>text</i>
   - Underline: <u>text</u>
@@ -21,8 +21,8 @@ You MUST format your output using Telegram-supported HTML tags. Do NOT use Markd
   - Block quote: <blockquote>quote</blockquote>
   - Expandable Block quote (for long quotes): <blockquote expandable>quote</blockquote>
   - Code block with language: <pre><code class="language-python">code</code></pre>
-4. **Special characters**: The characters <, > and & must be replaced with &lt;, &gt; and &amp; respectively when used as literals (not as part of HTML tags).
-5. **Line breaks**: Use regular line breaks (newlines). Do NOT use <br> tags.`;
+4. Special characters: The characters <, > and & must be replaced with &lt;, &gt; and &amp; respectively when used as literals (not as part of HTML tags).
+5. Line breaks: Use regular line breaks (newlines). Do NOT use <br> tags.`;

 /**
 * Default system prompt for LLM calls that need Telegram HTML formatting
--- a/src/services/skill-manager.ts
+++ b/src/services/skill-manager.ts
@@ -40,12 +40,12 @@ export class SkillManager {
                            const lines = content.split("\n").filter(l => l.trim() !== "");
                            const firstLine = lines[0]?.trim();
                            if (!firstLine) continue;
-                            
+
                            let description = firstLine;
                            if (firstLine.toLowerCase().startsWith("description:")) {
                                description = firstLine.substring("description:".length).trim();
                            }
-                            
+
                            if (description) {
                                skills.push({
                                    name: entry.name,
@@ -76,7 +76,7 @@ export class SkillManager {

        try {
            const content = readFileSync(skillPath, "utf-8");
-            return `${content}\n\n## OUTPUT FORMATTING\n${TELEGRAM_HTML_FORMAT_INSTRUCTION}\n\nYou MUST format your final response using only the Telegram HTML tags listed above. Never use Markdown (replace will allowed HTML tags).`;
+            return `${content}\n\n## OUTPUT FORMATTING\nYou MUST format your final response using only the Telegram HTML tags listed above. Never use Markdown (replace will allowed HTML tags).\n\n${TELEGRAM_HTML_FORMAT_INSTRUCTION}`;
        } catch (err) {
            console.error(`Failed to load skill prompt for ${name}:`, err);
            return null;