elsabro 2.2.0 → 3.7.0

package/references/prompt-management.md

@@ -0,0 +1,292 @@
+# Prompt Management System (v3.3)
+
+Sistema de gestión de prompts con templates, versionado, variables, y optimización A/B.
+
+## Arquitectura
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                      PROMPT MANAGEMENT SYSTEM                            │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                    PROMPT REGISTRY                               │    │
+│  │  ┌─────────────────────────────────────────────────────────┐    │    │
+│  │  │                 Template Library                         │    │    │
+│  │  │  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐    │    │    │
+│  │  │  │ explore │  │ analyze │  │implement│  │ review  │    │    │    │
+│  │  │  │  v2.1   │  │  v1.3   │  │  v3.0   │  │  v2.0   │    │    │    │
+│  │  │  └─────────┘  └─────────┘  └─────────┘  └─────────┘    │    │    │
+│  │  └─────────────────────────────────────────────────────────┘    │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+│                                    │                                     │
+│                                    ▼                                     │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                    TEMPLATE ENGINE                               │    │
+│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │    │
+│  │  │  Variables  │  │ Conditionals│  │   Loops     │              │    │
+│  │  │  {{var}}    │  │  {{#if}}    │  │  {{#each}}  │              │    │
+│  │  └─────────────┘  └─────────────┘  └─────────────┘              │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+│                                    │                                     │
+│                                    ▼                                     │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                    A/B TESTING & OPTIMIZATION                    │    │
+│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │    │
+│  │  │ Experiments │  │  Metrics    │  │  Analysis   │              │    │
+│  │  │  A vs B     │  │  tracking   │  │  & Winner   │              │    │
+│  │  └─────────────┘  └─────────────┘  └─────────────┘              │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+│                                                                          │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## PromptRegistry API
+
+```typescript
+interface PromptTemplate {
+  id: string;
+  name: string;
+  version: string;
+  description: string;
+  category: string;
+  template: string;
+  variables: TemplateVariable[];
+  settings: { model?: string; temperature?: number; maxTokens?: number };
+}
+
+class PromptRegistry {
+  // Register new template
+  register(template: PromptTemplate): PromptTemplate;
+
+  // Get template (latest version by default)
+  get(name: string, version?: string): PromptTemplate | undefined;
+
+  // List all templates
+  list(options?: { category?: string }): PromptTemplate[];
+
+  // List versions for template
+  listVersions(name: string): string[];
+
+  // Create alias
+  alias(alias: string, name: string): void;
+
+  // Export/Import templates
+  export(): PromptRegistryExport;
+  import(data: PromptRegistryExport): number;
+}
+```
+
+---
+
+## TemplateEngine
+
+Renderizado de templates con variables, condicionales y loops.
+
+### Sintaxis
+
+| Sintaxis | Descripción | Ejemplo |
+|----------|-------------|---------|
+| `{{variable}}` | Variable simple | `{{name}}` |
+| `{{object.property}}` | Acceso a propiedades | `{{user.email}}` |
+| `{{#if condition}}...{{/if}}` | Condicional | `{{#if hasError}}Error{{/if}}` |
+| `{{#each items}}...{{/each}}` | Loop | `{{#each files}}{{this}}{{/each}}` |
+| `{{helper arg}}` | Helper | `{{uppercase name}}` |
+
+### Helpers Disponibles
+
+| Helper | Descripción | Ejemplo |
+|--------|-------------|---------|
+| `uppercase` | Mayúsculas | `{{uppercase text}}` |
+| `lowercase` | Minúsculas | `{{lowercase text}}` |
+| `capitalize` | Capitalizar | `{{capitalize word}}` |
+| `trim` | Eliminar espacios | `{{trim input}}` |
+| `length` | Longitud de array | `{{length items}}` |
+| `join` | Unir array | `{{join items ", "}}` |
+| `json` | Formatear JSON | `{{json object}}` |
+| `date` | Formatear fecha | `{{date now "date"}}` |
+| `default` | Valor por defecto | `{{default value "N/A"}}` |
+| `truncate` | Truncar texto | `{{truncate text 100}}` |
+
+### Ejemplo de Uso
+
+```typescript
+const engine = new TemplateEngine();
+
+const template = `
+You are {{role}}. Your task is to {{task}}.
+
+{{#if context}}
+Context: {{context}}
+{{/if}}
+
+{{#each requirements}}
+- {{this}}
+{{/each}}
+`;
+
+const result = engine.render(template, {
+  role: 'code reviewer',
+  task: 'review the changes',
+  context: 'PR #123',
+  requirements: ['Check security', 'Verify tests']
+});
+```
+
+---
+
+## PromptOptimizer (A/B Testing)
+
+### Crear Experimento
+
+```typescript
+const optimizer = new PromptOptimizer(registry);
+
+const experiment = optimizer.createExperiment({
+  name: 'Review prompt optimization',
+  promptName: 'review',
+  variants: [
+    { id: 'control', name: 'Control', version: '1.0.0' },
+    { id: 'variant_a', name: 'More structured', version: '1.1.0' }
+  ],
+  traffic: [50, 50],  // 50/50 split
+  metrics: ['success_rate', 'quality_score']
+});
+
+optimizer.startExperiment(experiment.id);
+```
+
+### Obtener Variante
+
+```typescript
+// Get variant for request (based on traffic allocation)
+const variant = optimizer.getVariant(experimentId);
+const template = registry.get(promptName, variant.version);
+```
+
+### Registrar Resultado
+
+```typescript
+optimizer.recordResult(experimentId, variantId, {
+  success_rate: 1,
+  quality_score: 85
+});
+```
+
+### Analizar Resultados
+
+```typescript
+const analysis = optimizer.analyzeExperiment(experimentId);
+// {
+//   winner: 'variant_a',
+//   confidence: 0.95,
+//   recommendation: 'Promote variant_a (12.5% improvement)'
+// }
+```
+
+---
+
+## Templates Predefinidos
+
+### explore (v1.0.0)
+```
+You are an expert code explorer. Your task is to understand and map the codebase.
+
+## Task
+{{task}}
+
+## Focus Areas
+{{#each focusAreas}}
+- {{this}}
+{{/each}}
+
+## Output Requirements
+Provide a structured analysis including:
+1. File structure overview
+2. Key components identified
+3. Dependencies and relationships
+```
+
+### implement (v1.0.0)
+```
+You are an expert software engineer. Implement the following feature.
+
+## Feature
+{{feature}}
+
+## Requirements
+{{#each requirements}}
+- {{this}}
+{{/each}}
+
+## Technical Context
+- Language: {{language}}
+- Framework: {{framework}}
+```
+
+### review (v1.0.0)
+```
+You are a senior code reviewer. Review the following code changes.
+
+## Code to Review
+{{code}}
+
+## Review Criteria
+1. Correctness
+2. Security
+3. Performance
+4. Maintainability
+5. Testing
+
+Provide: Summary, Issues, Suggestions, Approval status
+```
+
+---
+
+## Comandos
+
+```bash
+/elsabro:prompt list                    # Listar templates
+/elsabro:prompt show explore            # Ver template
+/elsabro:prompt versions explore        # Ver versiones
+/elsabro:prompt create                  # Crear nuevo template
+/elsabro:prompt test explore            # Probar template
+/elsabro:prompt experiment create       # Crear A/B test
+/elsabro:prompt experiment status       # Ver experimentos
+```
+
+---
+
+## Configuración
+
+```json
+{
+  "promptManagement": {
+    "enabled": true,
+    "registry": {
+      "loadBuiltins": true,
+      "customPath": ".elsabro/prompts"
+    },
+    "engine": {
+      "strictMode": false,
+      "escapeHtml": false
+    },
+    "experiments": {
+      "minSampleSize": 30,
+      "defaultMetrics": ["success_rate", "quality_score"]
+    }
+  }
+}
+```
+
+---
+
+## Changelog
+
+- **v3.3.0**: Initial Prompt Management System
+  - PromptRegistry with versioning
+  - TemplateEngine with Handlebars-like syntax
+  - PromptOptimizer for A/B testing
+  - Built-in templates

package/references/sandbox-execution.md

@@ -0,0 +1,303 @@
+# Sandbox Execution System (v3.2)
+
+Sistema de ejecución aislada para código generado por agentes en entornos seguros y reproducibles.
+
+## Arquitectura
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                      SANDBOX EXECUTION LAYER                             │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                    SANDBOX MANAGER                               │    │
+│  │  ┌─────────────────────────────────────────────────────────┐    │    │
+│  │  │              Execution Request Queue                     │    │    │
+│  │  │  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐    │    │    │
+│  │  │  │ pending │→ │ running │→ │completed│  │ failed  │    │    │    │
+│  │  │  └─────────┘  └─────────┘  └─────────┘  └─────────┘    │    │    │
+│  │  └─────────────────────────────────────────────────────────┘    │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+│                                    │                                     │
+│                                    ▼                                     │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                    SANDBOX PROVIDERS                             │    │
+│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │    │
+│  │  │   Docker    │  │     E2B     │  │ Firecracker │              │    │
+│  │  │  Container  │  │   Sandbox   │  │   microVM   │              │    │
+│  │  │  (default)  │  │   (cloud)   │  │  (fastest)  │              │    │
+│  │  └─────────────┘  └─────────────┘  └─────────────┘              │    │
+│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │    │
+│  │  │   Process   │  │    WASM     │  │   Remote    │              │    │
+│  │  │  (unsafe)   │  │  (limited)  │  │   (custom)  │              │    │
+│  │  └─────────────┘  └─────────────┘  └─────────────┘              │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+│                                    │                                     │
+│                                    ▼                                     │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                   RESOURCE CONTROLS                              │    │
+│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐        │    │
+│  │  │   CPU    │  │  Memory  │  │   Disk   │  │ Network  │        │    │
+│  │  │  limits  │  │  limits  │  │  limits  │  │  policy  │        │    │
+│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘        │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+│                                                                          │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## SandboxManager API
+
+```typescript
+interface SandboxConfig {
+  provider: 'docker' | 'e2b' | 'firecracker' | 'process' | 'wasm' | 'remote';
+  image?: string;
+  environment?: Record<string, string>;
+  workdir?: string;
+  timeout?: number;
+  resources?: ResourceLimits;
+  network?: NetworkPolicy;
+  mounts?: Mount[];
+  capabilities?: string[];
+}
+
+interface ResourceLimits {
+  cpu?: { cores?: number; percent?: number };
+  memory?: { limitMb?: number; reservationMb?: number };
+  disk?: { limitMb?: number; readOnly?: boolean };
+  pids?: number;
+}
+
+interface ExecutionResult {
+  id: string;
+  status: 'completed' | 'failed' | 'timeout' | 'killed';
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  duration_ms: number;
+  resources: ResourceUsage;
+  artifacts?: Artifact[];
+}
+
+class SandboxManager {
+  // Run code in isolated sandbox
+  async run(code: string, language: string, config?: Partial<SandboxConfig>): Promise<ExecutionResult>;
+
+  // Run file in sandbox
+  async runFile(filePath: string, language: string, config?: Partial<SandboxConfig>): Promise<ExecutionResult>;
+
+  // Run with dependencies installed first
+  async runWithDeps(code: string, language: string, deps: string[], config?: Partial<SandboxConfig>): Promise<ExecutionResult>;
+
+  // Create interactive REPL session
+  async createSession(language: string, config?: Partial<SandboxConfig>): Promise<SandboxSession>;
+
+  // Kill running execution
+  async kill(executionId: string): Promise<void>;
+
+  // List active executions
+  listActive(): SandboxExecution[];
+
+  // Get provider status
+  async getProviderStatus(): Promise<ProviderStatus[]>;
+}
+```
+
+---
+
+## Providers
+
+### DockerProvider (Default)
+
+```typescript
+class DockerProvider implements SandboxProvider {
+  name = 'docker';
+  supportedLanguages = ['python', 'javascript', 'typescript', 'ruby', 'go', 'rust', 'java'];
+
+  async create(config: SandboxConfig): Promise<DockerSandbox> {
+    const container = await this.docker.createContainer({
+      Image: config.image || this.getDefaultImage(config.language),
+      HostConfig: {
+        Memory: (config.resources?.memory?.limitMb || 512) * 1024 * 1024,
+        NanoCpus: (config.resources?.cpu?.cores || 1) * 1e9,
+        PidsLimit: config.resources?.pids || 100,
+        NetworkMode: config.network?.enabled ? 'bridge' : 'none',
+        CapDrop: ['ALL'],
+        SecurityOpt: ['no-new-privileges']
+      }
+    });
+    return new DockerSandbox(container, config);
+  }
+
+  private getDefaultImage(language: string): string {
+    const images: Record<string, string> = {
+      'python': 'python:3.11-slim',
+      'javascript': 'node:20-slim',
+      'typescript': 'node:20-slim',
+      'ruby': 'ruby:3.2-slim',
+      'go': 'golang:1.21-alpine',
+      'rust': 'rust:1.75-slim',
+      'java': 'openjdk:21-slim'
+    };
+    return images[language] || 'ubuntu:22.04';
+  }
+}
+```
+
+### E2BProvider (Cloud)
+
+```typescript
+class E2BProvider implements SandboxProvider {
+  name = 'e2b';
+  supportedLanguages = ['python', 'javascript', 'typescript'];
+
+  async create(config: SandboxConfig): Promise<E2BSandbox> {
+    const sandbox = await this.client.sandboxes.create({
+      template: this.getTemplate(config.language),
+      envVars: config.environment
+    });
+    return new E2BSandbox(sandbox, config);
+  }
+}
+```
+
+### ProcessProvider (Local, Unsafe)
+
+```typescript
+class ProcessProvider implements SandboxProvider {
+  name = 'process';
+  supportedLanguages = ['python', 'javascript', 'typescript', 'ruby', 'bash'];
+
+  async create(config: SandboxConfig): Promise<ProcessSandbox> {
+    // Warning: This provider runs code without isolation
+    console.warn('ProcessProvider: Running without sandboxing. Use only for trusted code.');
+    return new ProcessSandbox(config);
+  }
+}
+```
+
+---
+
+## Interactive Sessions
+
+```typescript
+class SandboxSession {
+  private sandbox: Sandbox;
+  private history: string[] = [];
+
+  // Execute single line/statement in REPL
+  async evaluate(input: string): Promise<string> {
+    this.history.push(input);
+    const result = await this.sandbox.run(input);
+    return result.stdout;
+  }
+
+  // Get command history
+  getHistory(): string[] {
+    return [...this.history];
+  }
+
+  // Reset session state
+  async reset(): Promise<void> {
+    this.history = [];
+  }
+
+  // Close session
+  async close(): Promise<void> {
+    await this.sandbox.cleanup();
+  }
+}
+```
+
+---
+
+## Integración con Agentes
+
+```typescript
+class CodeRunnerAgent {
+  private sandboxManager: SandboxManager;
+
+  async runCode(task: AgentTask): Promise<AgentResult> {
+    const { code, language, dependencies } = task.input;
+
+    // Run in sandbox
+    const result = dependencies?.length
+      ? await this.sandboxManager.runWithDeps(code, language, dependencies)
+      : await this.sandboxManager.run(code, language);
+
+    if (result.status === 'completed') {
+      return { success: true, output: result.stdout, artifacts: result.artifacts };
+    }
+
+    return {
+      success: false,
+      error: result.stderr,
+      suggestion: this.analyzeError(result.stderr, language)
+    };
+  }
+}
+```
+
+---
+
+## Configuración
+
+```json
+{
+  "sandbox": {
+    "enabled": true,
+    "defaultProvider": "docker",
+    "defaultTimeout": 30000,
+    "defaultResources": {
+      "cpu": { "cores": 1 },
+      "memory": { "limitMb": 512 },
+      "disk": { "limitMb": 1024 },
+      "pids": 100
+    },
+    "defaultNetwork": { "enabled": false },
+    "providers": {
+      "docker": { "enabled": true, "socketPath": "/var/run/docker.sock" },
+      "e2b": { "enabled": false, "apiKey": null },
+      "process": { "enabled": true }
+    },
+    "languageDefaults": {
+      "python": { "image": "python:3.11-slim", "timeout": 60000 },
+      "javascript": { "image": "node:20-slim", "timeout": 30000 }
+    }
+  }
+}
+```
+
+---
+
+## Seguridad
+
+### Checklist de Seguridad
+
+- [ ] **Network disabled by default**
+- [ ] **Resource limits enforced** (CPU, memory, disk, PIDs)
+- [ ] **Read-only filesystem** cuando sea posible
+- [ ] **No capabilities** (dropped ALL by default)
+- [ ] **No new privileges** (SecurityOpt enabled)
+- [ ] **Timeout enforced** (kill after timeout)
+- [ ] **Temp directories cleaned** (always cleanup)
+- [ ] **No secrets exposed** (environment sanitized)
+
+### Amenazas Mitigadas
+
+| Amenaza | Mitigación |
+|---------|------------|
+| Fork bomb | PID limit |
+| Memory exhaustion | Memory limit |
+| Disk fill | Disk limit |
+| Network exfiltration | Network disabled |
+| Privilege escalation | No capabilities |
+| Host file access | No mounts by default |
+| Infinite loop | Timeout kill |
+
+---
+
+## Changelog
+
+- **v3.2.0**: Initial Sandbox Execution implementation