@bluefly/openstandardagents 0.5.1 → 0.5.3

package/dist/adapters/gitlab/package-generator.js

@@ -1,2400 +0,0 @@
-/**
- * GitLab Duo Package Generator
- * Orchestrates complete GitLab Duo agent package generation from OSSA manifests
- *
- * Extends BasePackageGenerator for shared npm package logic
- *
- * Generates complete directory structure (30+ files):
- * {agent-name}-gitlab-duo/
- * ├── .gitlab/duo/
- * │   ├── flows/main.yaml, error.yaml, monitor.yaml, governance.yaml
- * │   ├── agents/{name}.yaml
- * │   ├── triggers/mention.yaml, assign.yaml, assign_reviewer.yaml,
- * │   │          schedule.yaml, pipeline.yaml, webhook.yaml, file_pattern.yaml
- * │   ├── routers/conditional.yaml, multi-agent.yaml
- * │   ├── mcp-config.yaml
- * │   ├── mcp-config.json
- * │   ├── custom-tools.json
- * │   └── AGENTS.md
- * ├── src/
- * ├── Dockerfile
- * ├── package.json
- * ├── README.md
- * ├── DEPLOYMENT.md
- * └── agent.ossa.yaml
- */
-import * as fs from 'fs/promises';
-import * as path from 'path';
-import YAML from 'yaml';
-import { BasePackageGenerator } from '../npm/package-generator.js';
-import { GitLabDuoFlowGenerator } from './flow-generator.js';
-import { ExternalAgentGenerator } from './external-agent-generator.js';
-import { GitLabDuoTriggerGenerator } from './trigger-generator.js';
-import { GitLabDuoRouterGenerator } from './router-generator.js';
-export class GitLabDuoPackageGenerator extends BasePackageGenerator {
-    flowGenerator;
-    externalAgentGenerator;
-    triggerGenerator;
-    routerGenerator;
-    constructor() {
-        super();
-        this.flowGenerator = new GitLabDuoFlowGenerator();
-        this.externalAgentGenerator = new ExternalAgentGenerator();
-        this.triggerGenerator = new GitLabDuoTriggerGenerator();
-        this.routerGenerator = new GitLabDuoRouterGenerator();
-    }
-    /**
-     * Generate complete GitLab Duo agent package
-     */
-    async generate(manifest, options) {
-        const errors = [];
-        try {
-            // Validate manifest
-            const validation = this.validateManifest(manifest);
-            if (!validation.valid) {
-                return {
-                    success: false,
-                    errors: validation.errors,
-                };
-            }
-            const agentName = this.getAgentName(manifest);
-            const packagePath = path.join(options.outputDir, `${agentName}-gitlab-duo`);
-            // Check if package already exists
-            if (!options.overwrite) {
-                try {
-                    await fs.access(packagePath);
-                    return {
-                        success: false,
-                        errors: [
-                            `Package directory already exists: ${packagePath}. Use overwrite option to replace.`,
-                        ],
-                    };
-                }
-                catch {
-                    // Directory doesn't exist, continue
-                }
-            }
-            // Generate all files
-            const files = await this.generateAllFiles(manifest, options);
-            // Create directory structure and write files
-            const generatedFiles = await this.writeFiles(packagePath, files);
-            return {
-                success: true,
-                packagePath,
-                generatedFiles,
-            };
-        }
-        catch (error) {
-            errors.push(error instanceof Error ? error.message : String(error));
-            return {
-                success: false,
-                errors,
-            };
-        }
-    }
-    /**
-     * Validate manifest before generation
-     */
-    validateManifest(manifest) {
-        const errors = [];
-        if (!manifest.metadata?.name) {
-            errors.push('Manifest must have metadata.name');
-        }
-        if (!manifest.spec) {
-            errors.push('Manifest must have spec section');
-        }
-        if (!manifest.spec?.role) {
-            errors.push('Manifest must have spec.role');
-        }
-        return {
-            valid: errors.length === 0,
-            errors,
-        };
-    }
-    /**
-     * Get sanitized agent name from manifest
-     * Overrides base class to support legacy manifest.agent.name fallback
-     */
-    getAgentName(manifest) {
-        const name = manifest.metadata?.name || manifest.agent?.name || 'agent';
-        return this.sanitizePackageName(name);
-    }
-    /**
-     * Generate all package files
-     *
-     * Generates a comprehensive GitLab Duo agent package:
-     * - 4 flows (main, error, monitor, governance)
-     * - 7 triggers (mention, assign, assign_reviewer, schedule, pipeline, webhook, file_pattern)
-     * - 2 routers (conditional, multi-agent)
-     * - 1 MCP config YAML
-     * - Agent definition, tools, documentation, and deployment files
-     */
-    async generateAllFiles(manifest, options) {
-        const files = [];
-        const agentName = this.getAgentName(manifest);
-        // ── Flows (4 files) ──────────────────────────────────────
-        const flowFiles = this.flowGenerator.generateAllFlowFiles(manifest);
-        for (const [fileName, content] of flowFiles.entries()) {
-            files.push({
-                path: `.gitlab/duo/flows/${fileName}`,
-                content,
-            });
-        }
-        // ── External Agent YAML ──────────────────────────────────
-        const externalAgentResult = this.externalAgentGenerator.generate(manifest);
-        if (externalAgentResult.success && externalAgentResult.yaml) {
-            files.push({
-                path: `.gitlab/duo/agents/${agentName}.yaml`,
-                content: externalAgentResult.yaml,
-            });
-        }
-        // ── Triggers (7 files - all types) ───────────────────────
-        const triggerFiles = this.triggerGenerator.generateAllTriggerFiles(manifest);
-        for (const [fileName, content] of triggerFiles.entries()) {
-            files.push({
-                path: `.gitlab/duo/triggers/${fileName}`,
-                content,
-            });
-        }
-        // ── Routers (2 files) ────────────────────────────────────
-        const routerFiles = this.routerGenerator.generateAllRouterFiles(manifest);
-        for (const [fileName, content] of routerFiles.entries()) {
-            files.push({
-                path: `.gitlab/duo/routers/${fileName}`,
-                content,
-            });
-        }
-        // ── MCP Configuration (YAML) ─────────────────────────────
-        files.push({
-            path: `.gitlab/duo/mcp-config.yaml`,
-            content: this.generateMCPConfigYAML(manifest),
-        });
-        // ── MCP Configuration (JSON - for tooling compatibility) ─
-        files.push({
-            path: `.gitlab/duo/mcp-config.json`,
-            content: this.generateMCPConfig(manifest),
-        });
-        // ── Custom Tools Definition ──────────────────────────────
-        files.push({
-            path: `.gitlab/duo/custom-tools.json`,
-            content: this.generateCustomTools(manifest),
-        });
-        // ── AGENTS.md ────────────────────────────────────────────
-        files.push({
-            path: `.gitlab/duo/AGENTS.md`,
-            content: this.generateAgentsMd(manifest),
-        });
-        // ── OSSA manifest ────────────────────────────────────────
-        files.push({
-            path: 'agent.ossa.yaml',
-            content: this.generateOssaManifest(manifest),
-        });
-        // ── Documentation ────────────────────────────────────────
-        files.push({
-            path: 'README.md',
-            content: this.generateReadme(manifest),
-        });
-        files.push({
-            path: 'DEPLOYMENT.md',
-            content: this.generateDeploymentGuide(manifest),
-        });
-        files.push({
-            path: 'SECURITY.md',
-            content: this.generateSecurityGuide(manifest),
-        });
-        files.push({
-            path: 'MONITORING.md',
-            content: this.generateMonitoringGuide(manifest),
-        });
-        files.push({
-            path: 'TROUBLESHOOTING.md',
-            content: this.generateTroubleshootingGuide(manifest),
-        });
-        files.push({
-            path: 'FAQ.md',
-            content: this.generateFAQ(manifest),
-        });
-        files.push({
-            path: 'ARCHITECTURE.md',
-            content: this.generateArchitecture(manifest),
-        });
-        files.push({
-            path: 'API.md',
-            content: this.generateAPIDocumentation(manifest),
-        });
-        // ── package.json ─────────────────────────────────────────
-        files.push({
-            path: 'package.json',
-            content: this.generatePackageJsonForManifest(manifest),
-        });
-        // ── Dockerfile (if enabled) ──────────────────────────────
-        if (options.includeDocker !== false) {
-            files.push({
-                path: 'Dockerfile',
-                content: this.generateDockerfile(manifest),
-            });
-        }
-        // ── Source templates (if enabled) ────────────────────────
-        if (options.includeSourceTemplates) {
-            files.push(...this.generateSourceTemplates(manifest));
-        }
-        // ── CI/CD configuration (if enabled) ─────────────────────
-        if (options.includeCI) {
-            files.push({
-                path: '.gitlab-ci.yml',
-                content: this.generateGitLabCI(manifest),
-            });
-        }
-        // ── .gitignore ───────────────────────────────────────────
-        files.push({
-            path: '.gitignore',
-            content: this.generateGitignore(),
-        });
-        return files;
-    }
-    /**
-     * Write files to disk
-     */
-    async writeFiles(packagePath, files) {
-        const generatedPaths = [];
-        for (const file of files) {
-            const filePath = path.join(packagePath, file.path);
-            const dir = path.dirname(filePath);
-            // Create directory
-            await fs.mkdir(dir, { recursive: true });
-            // Write file
-            await fs.writeFile(filePath, file.content, 'utf8');
-            generatedPaths.push(file.path);
-        }
-        return generatedPaths;
-    }
-    /**
-     * Generate AGENTS.md file
-     */
-    generateAgentsMd(manifest) {
-        const agentName = manifest.metadata?.name || 'Agent';
-        const description = manifest.metadata?.description || '';
-        const role = manifest.spec?.role || '';
-        const lines = [];
-        lines.push(`# ${agentName}`);
-        lines.push('');
-        lines.push(description);
-        lines.push('');
-        lines.push('## Role');
-        lines.push('');
-        lines.push(role);
-        lines.push('');
-        // Add capabilities section
-        const tools = manifest.spec?.tools || [];
-        if (tools.length > 0) {
-            lines.push('## Capabilities');
-            lines.push('');
-            lines.push('This agent has access to the following tools:');
-            lines.push('');
-            for (const tool of tools) {
-                const toolObj = tool;
-                lines.push(`- **${toolObj.name || toolObj.type}**: ${toolObj.description || 'No description'}`);
-            }
-            lines.push('');
-        }
-        // Add usage section
-        lines.push('## Usage');
-        lines.push('');
-        lines.push('### Trigger Agent');
-        lines.push('');
-        lines.push('```bash');
-        lines.push(`glab duo agent trigger ${this.getAgentName(manifest)}`);
-        lines.push('```');
-        lines.push('');
-        // Add configuration section
-        lines.push('## Configuration');
-        lines.push('');
-        lines.push('### Environment Variables');
-        lines.push('');
-        const externalAgentResult = this.externalAgentGenerator.generate(manifest);
-        if (externalAgentResult.success && externalAgentResult.config) {
-            for (const variable of externalAgentResult.config.variables) {
-                lines.push(`- \`${variable}\``);
-            }
-        }
-        lines.push('');
-        // Add LLM configuration
-        const llm = manifest.spec?.llm;
-        if (llm) {
-            lines.push('### LLM Configuration');
-            lines.push('');
-            const llmConfig = llm;
-            lines.push(`- **Provider**: ${llmConfig.provider || 'Not specified'}`);
-            lines.push(`- **Model**: ${llmConfig.model || 'Not specified'}`);
-            if (llmConfig.temperature !== undefined) {
-                lines.push(`- **Temperature**: ${llmConfig.temperature}`);
-            }
-            if (llmConfig.maxTokens) {
-                lines.push(`- **Max Tokens**: ${llmConfig.maxTokens}`);
-            }
-            lines.push('');
-        }
-        // Add deployment section
-        lines.push('## Deployment');
-        lines.push('');
-        lines.push('See [DEPLOYMENT.md](../../../DEPLOYMENT.md) for detailed deployment instructions.');
-        lines.push('');
-        // Add documentation link
-        lines.push('## Documentation');
-        lines.push('');
-        lines.push('- [GitLab Duo Documentation](https://docs.gitlab.com/ee/user/gitlab_duo/)');
-        lines.push('- [OSSA Specification](https://github.com/bluefly-io/ossa)');
-        lines.push('');
-        return lines.join('\n');
-    }
-    /**
-     * Generate OSSA manifest YAML
-     */
-    generateOssaManifest(manifest) {
-        return JSON.stringify(manifest, null, 2);
-    }
-    /**
-     * Generate README.md
-     */
-    generateReadme(manifest) {
-        const agentName = manifest.metadata?.name || 'Agent';
-        const description = manifest.metadata?.description || '';
-        const version = manifest.metadata?.version || '1.0.0';
-        const lines = [];
-        lines.push(`# ${agentName}`);
-        lines.push('');
-        lines.push(`> ${description}`);
-        lines.push('');
-        lines.push(`**Version**: ${version}`);
-        lines.push('');
-        lines.push('## Overview');
-        lines.push('');
-        lines.push('This is a GitLab Duo agent generated from an OSSA manifest. It integrates with GitLab Duo AI Gateway and can be deployed as a Flow or External Agent.');
-        lines.push('');
-        lines.push('## Quick Start');
-        lines.push('');
-        lines.push('### Prerequisites');
-        lines.push('');
-        lines.push('- GitLab account with Duo access');
-        lines.push('- `glab` CLI installed');
-        lines.push('- Docker (for local testing)');
-        lines.push('');
-        lines.push('### Install Dependencies');
-        lines.push('');
-        lines.push('```bash');
-        lines.push('npm install');
-        lines.push('```');
-        lines.push('');
-        lines.push('### Build');
-        lines.push('');
-        lines.push('```bash');
-        lines.push('npm run build');
-        lines.push('```');
-        lines.push('');
-        lines.push('### Deploy');
-        lines.push('');
-        lines.push('See [DEPLOYMENT.md](./DEPLOYMENT.md) for deployment instructions.');
-        lines.push('');
-        lines.push('## Directory Structure');
-        lines.push('');
-        lines.push('```');
-        lines.push('.gitlab/duo/');
-        lines.push('  flows/');
-        lines.push('    main.yaml                   # Primary agent flow');
-        lines.push('    error.yaml                  # Error handling with retry logic');
-        lines.push('    monitor.yaml                # Monitoring and observability');
-        lines.push('    governance.yaml             # Compliance and policy checks');
-        lines.push(`  agents/${this.getAgentName(manifest)}.yaml    # External Agent configuration`);
-        lines.push('  triggers/');
-        lines.push('    mention.yaml                # @agent mention triggers');
-        lines.push('    assign.yaml                 # Issue/MR assignment triggers');
-        lines.push('    assign_reviewer.yaml        # MR reviewer assignment triggers');
-        lines.push('    schedule.yaml               # Cron-based scheduled triggers');
-        lines.push('    pipeline.yaml               # CI/CD pipeline triggers');
-        lines.push('    webhook.yaml                # External webhook triggers');
-        lines.push('    file_pattern.yaml           # File change pattern triggers');
-        lines.push('  routers/');
-        lines.push('    conditional.yaml            # Conditional routing logic');
-        lines.push('    multi-agent.yaml            # Multi-agent orchestration');
-        lines.push('  mcp-config.yaml               # MCP server configuration (YAML)');
-        lines.push('  mcp-config.json               # MCP server configuration (JSON)');
-        lines.push('  custom-tools.json             # Custom tool definitions');
-        lines.push('  AGENTS.md                     # Agent documentation');
-        lines.push('src/                            # Source code');
-        lines.push('agent.ossa.yaml                 # OSSA manifest');
-        lines.push('package.json                    # Node.js dependencies');
-        lines.push('Dockerfile                      # Container image');
-        lines.push('```');
-        lines.push('');
-        lines.push('## Documentation');
-        lines.push('');
-        lines.push('- [AGENTS.md](./.gitlab/duo/AGENTS.md) - Agent capabilities and usage');
-        lines.push('- [DEPLOYMENT.md](./DEPLOYMENT.md) - Deployment guide');
-        lines.push('- [GitLab Duo Documentation](https://docs.gitlab.com/ee/user/gitlab_duo/)');
-        lines.push('');
-        lines.push('## License');
-        lines.push('');
-        lines.push(manifest.metadata?.license || 'MIT');
-        lines.push('');
-        return lines.join('\n');
-    }
-    /**
-     * Generate DEPLOYMENT.md
-     */
-    generateDeploymentGuide(manifest) {
-        const agentName = this.getAgentName(manifest);
-        const lines = [];
-        lines.push('# Deployment Guide');
-        lines.push('');
-        lines.push(`This guide explains how to deploy the **${manifest.metadata?.name || 'Agent'}** to GitLab Duo.`);
-        lines.push('');
-        lines.push('## Deployment Options');
-        lines.push('');
-        lines.push('This agent supports two deployment modes:');
-        lines.push('');
-        lines.push('1. **Flow Agent** - Runs within GitLab Duo infrastructure (recommended)');
-        lines.push('2. **External Agent** - Runs in your GitLab CI/CD pipeline');
-        lines.push('');
-        lines.push('## Option 1: Flow Agent (Recommended)');
-        lines.push('');
-        lines.push('### Register Flow');
-        lines.push('');
-        lines.push('```bash');
-        lines.push(`glab duo flow register .gitlab/duo/flows/${agentName}.yaml`);
-        lines.push('```');
-        lines.push('');
-        lines.push('### Test Flow');
-        lines.push('');
-        lines.push('```bash');
-        lines.push(`glab duo flow test ${agentName}`);
-        lines.push('```');
-        lines.push('');
-        lines.push('### Deploy Flow');
-        lines.push('');
-        lines.push('```bash');
-        lines.push(`glab duo flow deploy ${agentName}`);
-        lines.push('```');
-        lines.push('');
-        lines.push('## Option 2: External Agent');
-        lines.push('');
-        lines.push('### Build Container Image');
-        lines.push('');
-        lines.push('```bash');
-        lines.push('docker build -t registry.gitlab.com/<namespace>/<project>/<agent>:latest .');
-        lines.push('docker push registry.gitlab.com/<namespace>/<project>/<agent>:latest');
-        lines.push('```');
-        lines.push('');
-        lines.push('### Register External Agent');
-        lines.push('');
-        lines.push('```bash');
-        lines.push(`glab duo agent register external .gitlab/duo/agents/${agentName}.yaml`);
-        lines.push('```');
-        lines.push('');
-        lines.push('### Test External Agent');
-        lines.push('');
-        lines.push('```bash');
-        lines.push(`glab duo agent test ${agentName}`);
-        lines.push('```');
-        lines.push('');
-        lines.push('## Environment Variables');
-        lines.push('');
-        lines.push('Required environment variables:');
-        lines.push('');
-        const externalAgentResult = this.externalAgentGenerator.generate(manifest);
-        if (externalAgentResult.success && externalAgentResult.config) {
-            for (const variable of externalAgentResult.config.variables) {
-                lines.push(`- \`${variable}\``);
-            }
-        }
-        lines.push('');
-        lines.push('Set these in your GitLab project:');
-        lines.push('');
-        lines.push('```bash');
-        lines.push('glab variable set GITLAB_TOKEN <your-token>');
-        lines.push('glab variable set AI_GATEWAY_TOKEN <gateway-token>');
-        lines.push('```');
-        lines.push('');
-        lines.push('## Monitoring');
-        lines.push('');
-        lines.push('### View Agent Logs');
-        lines.push('');
-        lines.push('```bash');
-        lines.push(`glab duo agent logs ${agentName}`);
-        lines.push('```');
-        lines.push('');
-        lines.push('### Check Agent Status');
-        lines.push('');
-        lines.push('```bash');
-        lines.push(`glab duo agent status ${agentName}`);
-        lines.push('```');
-        lines.push('');
-        lines.push('## Troubleshooting');
-        lines.push('');
-        lines.push('### Agent Not Responding');
-        lines.push('');
-        lines.push('1. Check agent logs for errors');
-        lines.push('2. Verify environment variables are set correctly');
-        lines.push('3. Ensure AI Gateway token is valid');
-        lines.push('');
-        lines.push('### Authentication Errors');
-        lines.push('');
-        lines.push('1. Verify `GITLAB_TOKEN` has correct permissions');
-        lines.push('2. Check token expiration');
-        lines.push('3. Ensure token has `api` and `read_repository` scopes');
-        lines.push('');
-        lines.push('## Documentation');
-        lines.push('');
-        lines.push('- [GitLab Duo Flows](https://docs.gitlab.com/ee/user/gitlab_duo/flows.html)');
-        lines.push('- [GitLab Duo External Agents](https://docs.gitlab.com/ee/user/gitlab_duo/external_agents.html)');
-        lines.push('- [AI Gateway Documentation](https://docs.gitlab.com/ee/architecture/blueprints/ai_gateway/)');
-        lines.push('');
-        return lines.join('\n');
-    }
-    /**
-     * Generate package.json
-     */
-    /**
-     * Generate GitLab Duo package.json
-     * Uses base class generatePackageJson with GitLab-specific configuration
-     */
-    generatePackageJsonForManifest(manifest) {
-        return super.generatePackageJson({
-            scope: '@gitlab-duo',
-            name: this.getAgentName(manifest),
-            version: this.getAgentVersion(manifest),
-            description: this.getAgentDescription(manifest),
-            type: 'module',
-            main: './dist/index.js',
-            types: './dist/index.d.ts',
-            scripts: {
-                build: 'tsc',
-                dev: 'tsc --watch',
-                test: 'node --test',
-                lint: 'eslint src/',
-                'lint:fix': 'eslint src/ --fix',
-                clean: 'rm -rf dist/',
-            },
-            dependencies: {
-                '@gitlab/duo': '^0.1.0',
-                '@gitbeaker/rest': '^41.0.0',
-            },
-            devDependencies: {
-                '@types/node': '^22.0.0',
-                typescript: '^5.7.0',
-                eslint: '^9.0.0',
-            },
-            engines: {
-                node: '>=22.0.0',
-            },
-            keywords: ['gitlab-duo', 'ai-agent', 'ossa'],
-            author: this.getAgentAuthor(manifest),
-            license: this.getAgentLicense(manifest),
-        });
-    }
-    /**
-     * Generate Dockerfile
-     */
-    generateDockerfile(manifest) {
-        const lines = [];
-        // Determine base image
-        const externalAgentResult = this.externalAgentGenerator.generate(manifest);
-        const baseImage = externalAgentResult.config?.image || 'node:22-slim';
-        lines.push(`FROM ${baseImage}`);
-        lines.push('');
-        lines.push('WORKDIR /app');
-        lines.push('');
-        if (baseImage.startsWith('node:')) {
-            lines.push('# Install dependencies');
-            lines.push('COPY package*.json ./');
-            lines.push('RUN npm ci --only=production');
-            lines.push('');
-            lines.push('# Copy source');
-            lines.push('COPY . .');
-            lines.push('');
-            lines.push('# Build');
-            lines.push('RUN npm run build');
-            lines.push('');
-            lines.push('# Run');
-            lines.push('CMD ["node", "dist/index.js"]');
-        }
-        else if (baseImage.startsWith('python:')) {
-            lines.push('# Install dependencies');
-            lines.push('COPY requirements.txt ./');
-            lines.push('RUN pip install --no-cache-dir -r requirements.txt');
-            lines.push('');
-            lines.push('# Copy source');
-            lines.push('COPY . .');
-            lines.push('');
-            lines.push('# Run');
-            lines.push('CMD ["python", "main.py"]');
-        }
-        else {
-            lines.push('# Copy source');
-            lines.push('COPY . .');
-            lines.push('');
-            lines.push('# Run');
-            lines.push('CMD ["./run.sh"]');
-        }
-        return lines.join('\n');
-    }
-    /**
-     * Generate source templates
-     */
-    generateSourceTemplates(manifest) {
-        const files = [];
-        // Generate index.ts
-        files.push({
-            path: 'src/index.ts',
-            content: this.generateIndexTemplate(manifest),
-        });
-        // Generate agent.ts
-        files.push({
-            path: 'src/agent.ts',
-            content: this.generateAgentTemplate(manifest),
-        });
-        // Generate tsconfig.json
-        files.push({
-            path: 'tsconfig.json',
-            content: this.generateTsConfig(),
-        });
-        return files;
-    }
-    /**
-     * Generate index.ts template
-     */
-    generateIndexTemplate(manifest) {
-        const lines = [];
-        lines.push('/**');
-        lines.push(` * ${manifest.metadata?.name || 'Agent'}`);
-        lines.push(` * ${manifest.metadata?.description || ''}`);
-        lines.push(' */');
-        lines.push('');
-        lines.push("import { Agent } from './agent.js';");
-        lines.push('');
-        lines.push('const agent = new Agent();');
-        lines.push('');
-        lines.push('// Start agent');
-        lines.push('agent.start().catch((error) => {');
-        lines.push('  console.error("Agent failed to start:", error);');
-        lines.push('  process.exit(1);');
-        lines.push('});');
-        lines.push('');
-        return lines.join('\n');
-    }
-    /**
-     * Generate agent.ts template
-     */
-    generateAgentTemplate(manifest) {
-        const role = manifest.spec?.role || 'You are a helpful AI assistant';
-        const lines = [];
-        lines.push('/**');
-        lines.push(' * Agent implementation');
-        lines.push(' */');
-        lines.push('');
-        lines.push('export class Agent {');
-        lines.push('  private role: string;');
-        lines.push('');
-        lines.push('  constructor() {');
-        lines.push(`    this.role = \`${role}\`;`);
-        lines.push('  }');
-        lines.push('');
-        lines.push('  async start(): Promise<void> {');
-        lines.push('    console.log("Agent starting...");');
-        lines.push('    console.log("Role:", this.role);');
-        lines.push('');
-        lines.push('    // Get input from environment');
-        lines.push('    const input = process.env.AI_FLOW_INPUT || "Hello";');
-        lines.push('');
-        lines.push('    // Process input');
-        lines.push('    const response = await this.process(input);');
-        lines.push('');
-        lines.push('    // Output response');
-        lines.push('    console.log("Response:", response);');
-        lines.push('  }');
-        lines.push('');
-        lines.push('  async process(input: string): Promise<string> {');
-        lines.push('    return `Processed: ${input}`;');
-        lines.push('  }');
-        lines.push('}');
-        lines.push('');
-        return lines.join('\n');
-    }
-    /**
-     * Generate tsconfig.json
-     */
-    /**
-     * Generate TypeScript configuration
-     * Uses base class implementation
-     */
-    generateTsConfig() {
-        return super.generateTsConfig();
-    }
-    /**
-     * Generate GitLab CI configuration
-     */
-    generateGitLabCI(manifest) {
-        const agentName = this.getAgentName(manifest);
-        const lines = [];
-        lines.push('# GitLab CI/CD Configuration');
-        lines.push(`# Agent: ${manifest.metadata?.name || 'Agent'}`);
-        lines.push('');
-        lines.push('stages:');
-        lines.push('  - build');
-        lines.push('  - test');
-        lines.push('  - deploy');
-        lines.push('');
-        lines.push('build:');
-        lines.push('  stage: build');
-        lines.push('  image: node:22-slim');
-        lines.push('  script:');
-        lines.push('    - npm ci');
-        lines.push('    - npm run build');
-        lines.push('  artifacts:');
-        lines.push('    paths:');
-        lines.push('      - dist/');
-        lines.push('');
-        lines.push('test:');
-        lines.push('  stage: test');
-        lines.push('  image: node:22-slim');
-        lines.push('  script:');
-        lines.push('    - npm ci');
-        lines.push('    - npm test');
-        lines.push('');
-        lines.push('deploy:');
-        lines.push('  stage: deploy');
-        lines.push('  image: node:22-slim');
-        lines.push('  script:');
-        lines.push('    - npm ci');
-        lines.push('    - npm run build');
-        lines.push(`    - glab duo flow deploy ${agentName}`);
-        lines.push('  only:');
-        lines.push('    - main');
-        lines.push('');
-        return lines.join('\n');
-    }
-    /**
-     * Generate .gitignore
-     * Uses base class implementation
-     */
-    generateGitignore() {
-        return super.generateGitignore();
-    }
-    /**
-     * Generate MCP Configuration
-     */
-    generateMCPConfig(manifest) {
-        const spec = manifest.spec;
-        const tools = spec.tools || [];
-        const mcpServers = {};
-        // Map OSSA tools to MCP servers
-        for (const tool of tools) {
-            const toolName = tool.name || tool.type || 'unknown';
-            if (toolName.includes('gitlab')) {
-                mcpServers['gitlab'] = {
-                    command: 'npx',
-                    args: ['-y', '@modelcontextprotocol/server-gitlab'],
-                    env: {
-                        GITLAB_TOKEN: '${GITLAB_TOKEN}',
-                        GITLAB_URL: 'https://gitlab.com',
-                    },
-                };
-            }
-            else if (toolName.includes('file') ||
-                toolName.includes('read') ||
-                toolName.includes('write')) {
-                mcpServers['filesystem'] = {
-                    command: 'npx',
-                    args: ['-y', '@modelcontextprotocol/server-filesystem', '/workspace'],
-                };
-            }
-            else if (toolName.includes('search')) {
-                mcpServers['ripgrep'] = {
-                    command: 'npx',
-                    args: ['-y', '@modelcontextprotocol/server-ripgrep', '/workspace'],
-                };
-            }
-        }
-        // Always include memory server
-        mcpServers['memory'] = {
-            command: 'npx',
-            args: ['-y', '@modelcontextprotocol/server-memory'],
-        };
-        const config = {
-            mcpServers,
-            version: '1.0.0',
-            description: `MCP configuration for ${manifest.metadata?.name || 'agent'}`,
-        };
-        return JSON.stringify(config, null, 2);
-    }
-    /**
-     * Generate MCP Configuration as YAML.
-     * Provides a structured, human-readable MCP server configuration
-     * with detailed comments for each server and its purpose.
-     */
-    generateMCPConfigYAML(manifest) {
-        const spec = manifest.spec;
-        const tools = spec.tools || [];
-        const agentName = manifest.metadata?.name || 'agent';
-        const mcpServers = {};
-        // Map OSSA tools to MCP servers
-        for (const tool of tools) {
-            const toolName = tool.name || tool.type || 'unknown';
-            if (toolName.includes('gitlab')) {
-                mcpServers['gitlab'] = {
-                    description: 'GitLab API operations (issues, MRs, comments, repository files)',
-                    command: 'npx',
-                    args: ['-y', '@modelcontextprotocol/server-gitlab'],
-                    env: {
-                        GITLAB_TOKEN: '${GITLAB_TOKEN}',
-                        GITLAB_URL: '${GITLAB_URL:-https://gitlab.com}',
-                    },
-                    capabilities: [
-                        'issues',
-                        'merge_requests',
-                        'comments',
-                        'repository_files',
-                        'pipelines',
-                    ],
-                };
-            }
-            else if (toolName.includes('file') ||
-                toolName.includes('read') ||
-                toolName.includes('write')) {
-                mcpServers['filesystem'] = {
-                    description: 'File system operations (read, write, list, search)',
-                    command: 'npx',
-                    args: ['-y', '@modelcontextprotocol/server-filesystem', '/workspace'],
-                    capabilities: [
-                        'read_file',
-                        'create_file_with_contents',
-                        'update_file',
-                        'list_dir',
-                    ],
-                };
-            }
-            else if (toolName.includes('search')) {
-                mcpServers['ripgrep'] = {
-                    description: 'Code search using ripgrep for fast file content searching',
-                    command: 'npx',
-                    args: ['-y', '@modelcontextprotocol/server-ripgrep', '/workspace'],
-                    capabilities: ['search_files', 'regex_search'],
-                };
-            }
-        }
-        // Always include memory server
-        mcpServers['memory'] = {
-            description: 'Persistent memory across agent sessions for context retention',
-            command: 'npx',
-            args: ['-y', '@modelcontextprotocol/server-memory'],
-            capabilities: ['store', 'retrieve', 'delete', 'list_memories'],
-        };
-        // Always include fetch server for external data
-        mcpServers['fetch'] = {
-            description: 'HTTP fetch for retrieving external documentation and API data',
-            command: 'npx',
-            args: ['-y', '@modelcontextprotocol/server-fetch'],
-            capabilities: ['fetch_url', 'parse_html', 'extract_text'],
-        };
-        const config = {
-            version: 'v1',
-            agent_name: agentName,
-            description: `MCP server configuration for ${agentName}. Defines the external tool servers that the agent can use during execution.`,
-            servers: mcpServers,
-            settings: {
-                startup_timeout_seconds: 30,
-                request_timeout_seconds: 60,
-                max_concurrent_servers: 5,
-                restart_on_failure: true,
-                log_level: 'info',
-            },
-            security: {
-                allowed_hosts: ['gitlab.com', '*.gitlab.com', 'ai-gateway.gitlab.com'],
-                deny_shell_execution: true,
-                max_file_size_bytes: 10_485_760,
-                workspace_root: '/workspace',
-            },
-        };
-        return YAML.stringify(config, { indent: 2, lineWidth: 0 });
-    }
-    /**
-     * Generate Custom Tools Definition
-     */
-    generateCustomTools(manifest) {
-        const spec = manifest.spec;
-        const tools = spec.tools || [];
-        const customTools = tools.map((tool) => ({
-            name: tool.name || 'custom_tool',
-            description: tool.description || 'Custom tool implementation',
-            input_schema: {
-                type: 'object',
-                properties: tool.parameters || {},
-                required: Object.keys(tool.parameters || {}),
-            },
-        }));
-        const config = {
-            tools: customTools,
-            version: '1.0.0',
-        };
-        return JSON.stringify(config, null, 2);
-    }
-    /**
-     * Generate SECURITY.md
-     */
-    generateSecurityGuide(manifest) {
-        const agentName = manifest.metadata?.name || 'Agent';
-        const lines = [];
-        lines.push(`# Security Guide: ${agentName}`);
-        lines.push('');
-        lines.push('## Overview');
-        lines.push('');
-        lines.push('This document outlines security considerations, best practices, and procedures for deploying and operating this GitLab Duo agent.');
-        lines.push('');
-        lines.push('## Authentication & Authorization');
-        lines.push('');
-        lines.push('### GitLab Token Management');
-        lines.push('');
-        lines.push('**Required Scopes:**');
-        lines.push('- `api` - Full API access');
-        lines.push('- `read_repository` - Read repository data');
-        lines.push('- `write_repository` - Write repository data (if agent modifies files)');
-        lines.push('');
-        lines.push('**Token Storage:**');
-        lines.push('- Store tokens as GitLab CI/CD variables (masked)');
-        lines.push('- Use environment-specific tokens (dev/staging/prod)');
-        lines.push('- Rotate tokens every 90 days');
-        lines.push('');
-        lines.push('```bash');
-        lines.push('# Set token as masked variable');
-        lines.push('glab variable set GITLAB_TOKEN <token> --masked');
-        lines.push('```');
-        lines.push('');
-        lines.push('### AI Gateway Token');
-        lines.push('');
-        lines.push('- Never commit AI Gateway tokens to repository');
-        lines.push('- Use GitLab CI/CD variables with `protected` flag');
-        lines.push('- Limit token scope to specific agent');
-        lines.push('');
-        lines.push('## Access Controls');
-        lines.push('');
-        lines.push('### Trigger Permissions');
-        lines.push('');
-        lines.push('Ensure triggers have appropriate permissions:');
-        lines.push('');
-        lines.push('- **@mentions**: Minimum `Reporter` role');
-        lines.push('- **Assignments**: Minimum `Developer` role');
-        lines.push('- **Webhooks**: Token-based authentication required');
-        lines.push('- **Scheduled**: Runs as project bot account');
-        lines.push('');
-        lines.push('### Tool Access');
-        lines.push('');
-        lines.push('Restrict tool capabilities based on environment:');
-        lines.push('');
-        lines.push('- **Read-only tools**: `read_file`, `list_dir`, `search_files`');
-        lines.push('- **Write tools**: `create_file`, `update_file` (production only)');
-        lines.push('- **Shell execution**: Disabled by default, enable with caution');
-        lines.push('');
-        lines.push('## Data Protection');
-        lines.push('');
-        lines.push('### Sensitive Data Handling');
-        lines.push('');
-        lines.push('- Never log sensitive data (tokens, passwords, API keys)');
-        lines.push('- Redact sensitive patterns in output');
-        lines.push("- Use GitLab's built-in secret detection");
-        lines.push('');
-        lines.push('### Data Retention');
-        lines.push('');
-        lines.push('- Agent logs retained for 30 days');
-        lines.push('- Conversation history cleared after session');
-        lines.push('- PII redacted before storage');
-        lines.push('');
-        lines.push('## Network Security');
-        lines.push('');
-        lines.push('### Outbound Connections');
-        lines.push('');
-        lines.push('Agent makes connections to:');
-        lines.push('');
-        lines.push('- `gitlab.com` (API)');
-        lines.push('- `ai-gateway.gitlab.com` (AI Gateway)');
-        lines.push('- MCP servers (as configured)');
-        lines.push('');
-        lines.push('### Inbound Webhooks');
-        lines.push('');
-        lines.push('If webhook triggers enabled:');
-        lines.push('');
-        lines.push('- Validate webhook signatures');
-        lines.push('- Rate limit webhook endpoints');
-        lines.push('- Use HTTPS only');
-        lines.push('');
-        lines.push('## Vulnerability Management');
-        lines.push('');
-        lines.push('### Dependency Scanning');
-        lines.push('');
-        lines.push('```bash');
-        lines.push('# Run dependency audit');
-        lines.push('npm audit');
-        lines.push('');
-        lines.push('# Fix vulnerabilities');
-        lines.push('npm audit fix');
-        lines.push('```');
-        lines.push('');
-        lines.push('### Container Security');
-        lines.push('');
-        lines.push('- Use minimal base images (node:22-slim)');
-        lines.push('- Scan container images for vulnerabilities');
-        lines.push('- Update base images monthly');
-        lines.push('');
-        lines.push('## Incident Response');
-        lines.push('');
-        lines.push('### Security Incident');
-        lines.push('');
-        lines.push('1. **Disable agent** - Stop all triggers');
-        lines.push('2. **Rotate tokens** - Invalidate compromised credentials');
-        lines.push('3. **Review logs** - Check for unauthorized access');
-        lines.push('4. **Notify stakeholders** - Report incident per policy');
-        lines.push('');
-        lines.push('### Token Compromise');
-        lines.push('');
-        lines.push('```bash');
-        lines.push('# Revoke token immediately');
-        lines.push('glab token revoke <token-id>');
-        lines.push('');
-        lines.push('# Generate new token');
-        lines.push('glab token create --scopes api,read_repository');
-        lines.push('');
-        lines.push('# Update CI/CD variable');
-        lines.push('glab variable update GITLAB_TOKEN <new-token> --masked');
-        lines.push('```');
-        lines.push('');
-        lines.push('## Compliance');
-        lines.push('');
-        lines.push('### Audit Logging');
-        lines.push('');
-        lines.push('All agent actions are logged:');
-        lines.push('');
-        lines.push('- Trigger events');
-        lines.push('- Tool executions');
-        lines.push('- API calls');
-        lines.push('- Errors and exceptions');
-        lines.push('');
-        lines.push('### Data Privacy (GDPR/CCPA)');
-        lines.push('');
-        lines.push('- PII detection and redaction enabled');
-        lines.push('- Data retention policy: 30 days');
-        lines.push('- Right to deletion supported');
-        lines.push('');
-        lines.push('## Security Checklist');
-        lines.push('');
-        lines.push('- [ ] GitLab tokens stored as masked CI/CD variables');
-        lines.push('- [ ] AI Gateway token protected and scoped');
-        lines.push('- [ ] Trigger permissions configured correctly');
-        lines.push('- [ ] Tool access restricted to minimum required');
-        lines.push('- [ ] Sensitive data logging disabled');
-        lines.push('- [ ] Dependency scanning enabled in CI/CD');
-        lines.push('- [ ] Container image scanning configured');
-        lines.push('- [ ] Webhook authentication configured');
-        lines.push('- [ ] Incident response plan documented');
-        lines.push('- [ ] Token rotation schedule established');
-        lines.push('');
-        lines.push('## References');
-        lines.push('');
-        lines.push('- [GitLab Security Best Practices](https://docs.gitlab.com/ee/security/)');
-        lines.push('- [GitLab Duo Security](https://docs.gitlab.com/ee/user/gitlab_duo/security.html)');
-        lines.push('- [AI Gateway Security](https://docs.gitlab.com/ee/architecture/blueprints/ai_gateway/security.html)');
-        lines.push('');
-        return lines.join('\n');
-    }
-    /**
-     * Generate MONITORING.md
-     */
-    generateMonitoringGuide(manifest) {
-        const agentName = this.getAgentName(manifest);
-        const lines = [];
-        lines.push(`# Monitoring Guide: ${manifest.metadata?.name || 'Agent'}`);
-        lines.push('');
-        lines.push('## Overview');
-        lines.push('');
-        lines.push('This guide covers monitoring, observability, and performance tracking for this GitLab Duo agent.');
-        lines.push('');
-        lines.push('## Metrics');
-        lines.push('');
-        lines.push('### Key Performance Indicators (KPIs)');
-        lines.push('');
-        lines.push('| Metric | Description | Target |');
-        lines.push('|--------|-------------|--------|');
-        lines.push('| Response Time | Time from trigger to first response | < 5s |');
-        lines.push('| Success Rate | Percentage of successful executions | > 95% |');
-        lines.push('| Error Rate | Percentage of failed executions | < 5% |');
-        lines.push('| Token Usage | Average tokens per execution | Monitor |');
-        lines.push('| Tool Calls | Number of tool executions | Monitor |');
-        lines.push('');
-        lines.push('### View Metrics');
-        lines.push('');
-        lines.push('```bash');
-        lines.push(`# View agent metrics`);
-        lines.push(`glab duo agent metrics ${agentName}`);
-        lines.push('');
-        lines.push('# View specific metric');
-        lines.push(`glab duo agent metrics ${agentName} --metric response_time`);
-        lines.push('');
-        lines.push('# Export metrics to JSON');
-        lines.push(`glab duo agent metrics ${agentName} --format json > metrics.json`);
-        lines.push('```');
-        lines.push('');
-        lines.push('## Logging');
-        lines.push('');
-        lines.push('### Log Levels');
-        lines.push('');
-        lines.push('- `ERROR` - Failures and exceptions');
-        lines.push('- `WARN` - Recoverable issues');
-        lines.push('- `INFO` - Normal operations');
-        lines.push('- `DEBUG` - Detailed execution info');
-        lines.push('');
-        lines.push('### View Logs');
-        lines.push('');
-        lines.push('```bash');
-        lines.push(`# View recent logs`);
-        lines.push(`glab duo agent logs ${agentName}`);
-        lines.push('');
-        lines.push('# Follow logs in real-time');
-        lines.push(`glab duo agent logs ${agentName} --follow`);
-        lines.push('');
-        lines.push('# Filter by level');
-        lines.push(`glab duo agent logs ${agentName} --level ERROR`);
-        lines.push('');
-        lines.push('# View logs for specific execution');
-        lines.push(`glab duo agent logs ${agentName} --execution-id <id>`);
-        lines.push('```');
-        lines.push('');
-        lines.push('## Tracing');
-        lines.push('');
-        lines.push('### Execution Traces');
-        lines.push('');
-        lines.push('View complete execution traces:');
-        lines.push('');
-        lines.push('```bash');
-        lines.push(`# List recent executions`);
-        lines.push(`glab duo agent executions ${agentName}`);
-        lines.push('');
-        lines.push('# View execution trace');
-        lines.push(`glab duo agent trace <execution-id>`);
-        lines.push('');
-        lines.push('# Export trace');
-        lines.push(`glab duo agent trace <execution-id> --format json > trace.json`);
-        lines.push('```');
-        lines.push('');
-        lines.push('### Trace Components');
-        lines.push('');
-        lines.push('Each trace includes:');
-        lines.push('');
-        lines.push('- Trigger event details');
-        lines.push('- Component execution timeline');
-        lines.push('- Tool call sequences');
-        lines.push('- LLM requests and responses');
-        lines.push('- Router decisions');
-        lines.push('- Error details (if any)');
-        lines.push('');
-        lines.push('## Alerting');
-        lines.push('');
-        lines.push('### Alert Rules');
-        lines.push('');
-        lines.push('Configure alerts for critical conditions:');
-        lines.push('');
-        lines.push('```bash');
-        lines.push(`# Create alert rule`);
-        lines.push(`glab duo agent alert create ${agentName} \\`);
-        lines.push('  --metric error_rate \\');
-        lines.push('  --threshold 10 \\');
-        lines.push('  --period 5m \\');
-        lines.push('  --notify-slack webhook-url');
-        lines.push('```');
-        lines.push('');
-        lines.push('### Recommended Alerts');
-        lines.push('');
-        lines.push('1. **High Error Rate** - > 10% errors in 5 minutes');
-        lines.push('2. **Slow Response** - Average response time > 30s');
-        lines.push('3. **Agent Down** - No executions in 1 hour (for scheduled agents)');
-        lines.push('4. **Token Limit** - Token usage > 90% of limit');
-        lines.push('');
-        lines.push('## Dashboards');
-        lines.push('');
-        lines.push('### GitLab Duo Dashboard');
-        lines.push('');
-        lines.push('Access built-in dashboard:');
-        lines.push('');
-        lines.push('1. Navigate to project');
-        lines.push('2. Go to **GitLab Duo** > **Agents**');
-        lines.push(`3. Select **${manifest.metadata?.name || 'agent'}**`);
-        lines.push('4. View **Metrics** tab');
-        lines.push('');
-        lines.push('### Custom Grafana Dashboard');
-        lines.push('');
-        lines.push('For advanced monitoring, export metrics to Grafana:');
-        lines.push('');
-        lines.push('```bash');
-        lines.push('# Export metrics endpoint');
-        lines.push(`glab duo agent metrics-endpoint ${agentName}`);
-        lines.push('');
-        lines.push('# Configure Prometheus scraper');
-        lines.push('# Add endpoint to prometheus.yml');
-        lines.push('```');
-        lines.push('');
-        lines.push('## Performance Optimization');
-        lines.push('');
-        lines.push('### Response Time');
-        lines.push('');
-        lines.push('If response time is high:');
-        lines.push('');
-        lines.push('1. **Reduce prompt size** - Shorter system prompts');
-        lines.push('2. **Optimize tool calls** - Batch operations');
-        lines.push('3. **Use smaller model** - Switch to faster model');
-        lines.push('4. **Enable caching** - Cache frequently used data');
-        lines.push('');
-        lines.push('### Token Usage');
-        lines.push('');
-        lines.push('If token usage is high:');
-        lines.push('');
-        lines.push('1. **Shorten prompts** - Remove unnecessary context');
-        lines.push('2. **Limit history** - Reduce conversation history depth');
-        lines.push('3. **Compress tool outputs** - Summarize large responses');
-        lines.push('4. **Switch model** - Use more efficient model');
-        lines.push('');
-        lines.push('## Health Checks');
-        lines.push('');
-        lines.push('### Agent Health');
-        lines.push('');
-        lines.push('```bash');
-        lines.push(`# Check agent health`);
-        lines.push(`glab duo agent health ${agentName}`);
-        lines.push('');
-        lines.push('# Output:');
-        lines.push('# Status: healthy');
-        lines.push('# Last execution: 2 minutes ago');
-        lines.push('# Success rate (24h): 98.5%');
-        lines.push('# Avg response time: 3.2s');
-        lines.push('```');
-        lines.push('');
-        lines.push('### Dependency Health');
-        lines.push('');
-        lines.push('Monitor dependencies:');
-        lines.push('');
-        lines.push('- AI Gateway connectivity');
-        lines.push('- GitLab API availability');
-        lines.push('- MCP server status');
-        lines.push('- External service connections');
-        lines.push('');
-        lines.push('## Incident Investigation');
-        lines.push('');
-        lines.push('### Debug Failed Execution');
-        lines.push('');
-        lines.push('```bash');
-        lines.push('# 1. Get execution ID from logs');
-        lines.push(`glab duo agent logs ${agentName} --level ERROR`);
-        lines.push('');
-        lines.push('# 2. View full trace');
-        lines.push('glab duo agent trace <execution-id>');
-        lines.push('');
-        lines.push('# 3. Check tool call failures');
-        lines.push('glab duo agent trace <execution-id> --filter tool_calls');
-        lines.push('');
-        lines.push('# 4. Review LLM responses');
-        lines.push('glab duo agent trace <execution-id> --filter llm_responses');
-        lines.push('```');
-        lines.push('');
-        lines.push('## References');
-        lines.push('');
-        lines.push('- [GitLab Duo Monitoring](https://docs.gitlab.com/ee/user/gitlab_duo/monitoring.html)');
-        lines.push('- [AI Gateway Metrics](https://docs.gitlab.com/ee/architecture/blueprints/ai_gateway/metrics.html)');
-        lines.push('- [Performance Best Practices](https://docs.gitlab.com/ee/user/gitlab_duo/performance.html)');
-        lines.push('');
-        return lines.join('\n');
-    }
-    /**
-     * Generate TROUBLESHOOTING.md
-     */
-    generateTroubleshootingGuide(manifest) {
-        const agentName = this.getAgentName(manifest);
-        const lines = [];
-        lines.push(`# Troubleshooting Guide: ${manifest.metadata?.name || 'Agent'}`);
-        lines.push('');
-        lines.push('## Common Issues');
-        lines.push('');
-        lines.push('### Agent Not Responding');
-        lines.push('');
-        lines.push('**Symptoms:**');
-        lines.push('- No response to @mention');
-        lines.push('- Triggers not firing');
-        lines.push('- Silent failures');
-        lines.push('');
-        lines.push('**Solutions:**');
-        lines.push('');
-        lines.push('1. **Check agent status**');
-        lines.push('   ```bash');
-        lines.push(`   glab duo agent status ${agentName}`);
-        lines.push('   ```');
-        lines.push('');
-        lines.push('2. **Verify triggers are active**');
-        lines.push('   ```bash');
-        lines.push(`   glab duo agent triggers ${agentName}`);
-        lines.push('   ```');
-        lines.push('');
-        lines.push('3. **Check recent errors**');
-        lines.push('   ```bash');
-        lines.push(`   glab duo agent logs ${agentName} --level ERROR --tail 50`);
-        lines.push('   ```');
-        lines.push('');
-        lines.push('4. **Restart agent**');
-        lines.push('   ```bash');
-        lines.push(`   glab duo agent restart ${agentName}`);
-        lines.push('   ```');
-        lines.push('');
-        lines.push('### Authentication Errors');
-        lines.push('');
-        lines.push('**Error:** `401 Unauthorized` or `403 Forbidden`');
-        lines.push('');
-        lines.push('**Solutions:**');
-        lines.push('');
-        lines.push('1. **Verify GITLAB_TOKEN**');
-        lines.push('   ```bash');
-        lines.push('   glab variable get GITLAB_TOKEN');
-        lines.push('   ```');
-        lines.push('');
-        lines.push('2. **Check token scopes**');
-        lines.push('   - Required: `api`, `read_repository`');
-        lines.push('   - Optional: `write_repository` (if agent modifies files)');
-        lines.push('');
-        lines.push('3. **Verify token not expired**');
-        lines.push('   ```bash');
-        lines.push('   glab auth status');
-        lines.push('   ```');
-        lines.push('');
-        lines.push('4. **Regenerate token**');
-        lines.push('   ```bash');
-        lines.push('   glab auth login --stdin');
-        lines.push('   ```');
-        lines.push('');
-        lines.push('### Tool Execution Failures');
-        lines.push('');
-        lines.push('**Error:** `Tool execution failed: <tool-name>`');
-        lines.push('');
-        lines.push('**Solutions:**');
-        lines.push('');
-        lines.push('1. **Check tool availability**');
-        lines.push('   ```bash');
-        lines.push(`   glab duo agent tools ${agentName}`);
-        lines.push('   ```');
-        lines.push('');
-        lines.push('2. **Verify MCP server status**');
-        lines.push('   ```bash');
-        lines.push(`   glab duo agent mcp-status ${agentName}`);
-        lines.push('   ```');
-        lines.push('');
-        lines.push('3. **Check tool permissions**');
-        lines.push('   - File operations require repository access');
-        lines.push('   - GitLab operations require API access');
-        lines.push('');
-        lines.push('4. **Review tool execution logs**');
-        lines.push('   ```bash');
-        lines.push(`   glab duo agent logs ${agentName} --filter tool_execution`);
-        lines.push('   ```');
-        lines.push('');
-        lines.push('### High Response Time');
-        lines.push('');
-        lines.push('**Symptom:** Agent takes > 30s to respond');
-        lines.push('');
-        lines.push('**Solutions:**');
-        lines.push('');
-        lines.push('1. **Check AI Gateway latency**');
-        lines.push('   ```bash');
-        lines.push(`   glab duo agent metrics ${agentName} --metric gateway_latency`);
-        lines.push('   ```');
-        lines.push('');
-        lines.push('2. **Review token usage**');
-        lines.push('   - High token usage = slow responses');
-        lines.push('   - Optimize prompts to reduce tokens');
-        lines.push('');
-        lines.push('3. **Check tool execution time**');
-        lines.push('   ```bash');
-        lines.push(`   glab duo agent trace <execution-id> --filter tool_duration`);
-        lines.push('   ```');
-        lines.push('');
-        lines.push('4. **Consider faster model**');
-        lines.push('   - Switch to `claude-haiku` or `gpt-4o-mini`');
-        lines.push('');
-        lines.push('### Token Limit Exceeded');
-        lines.push('');
-        lines.push('**Error:** `Token limit exceeded for model`');
-        lines.push('');
-        lines.push('**Solutions:**');
-        lines.push('');
-        lines.push('1. **Reduce prompt size**');
-        lines.push('   - Shorten system prompt');
-        lines.push('   - Remove unnecessary context');
-        lines.push('');
-        lines.push('2. **Limit conversation history**');
-        lines.push('   - Reduce `max_history` parameter');
-        lines.push('   - Summarize previous turns');
-        lines.push('');
-        lines.push('3. **Compress tool outputs**');
-        lines.push('   - Summarize large file contents');
-        lines.push('   - Return only relevant data');
-        lines.push('');
-        lines.push('4. **Switch to larger model**');
-        lines.push('   - Use model with higher token limit');
-        lines.push('');
-        lines.push('### MCP Server Connection Failed');
-        lines.push('');
-        lines.push('**Error:** `Failed to connect to MCP server: <server-name>`');
-        lines.push('');
-        lines.push('**Solutions:**');
-        lines.push('');
-        lines.push('1. **Check MCP configuration**');
-        lines.push('   ```bash');
-        lines.push('   cat .gitlab/duo/mcp-config.json');
-        lines.push('   ```');
-        lines.push('');
-        lines.push('2. **Verify server is installed**');
-        lines.push('   ```bash');
-        lines.push('   npm list @modelcontextprotocol/server-*');
-        lines.push('   ```');
-        lines.push('');
-        lines.push('3. **Test server connection manually**');
-        lines.push('   ```bash');
-        lines.push('   npx @modelcontextprotocol/server-gitlab --test');
-        lines.push('   ```');
-        lines.push('');
-        lines.push('4. **Check environment variables**');
-        lines.push('   - Ensure required env vars are set');
-        lines.push('   - Example: `GITLAB_TOKEN` for gitlab server');
-        lines.push('');
-        lines.push('### Webhook Trigger Not Firing');
-        lines.push('');
-        lines.push('**Symptom:** Webhook events not triggering agent');
-        lines.push('');
-        lines.push('**Solutions:**');
-        lines.push('');
-        lines.push('1. **Verify webhook configuration**');
-        lines.push('   ```bash');
-        lines.push(`   cat .gitlab/duo/triggers/webhook.yaml`);
-        lines.push('   ```');
-        lines.push('');
-        lines.push('2. **Check webhook URL**');
-        lines.push('   - Ensure URL is accessible');
-        lines.push('   - Test with curl');
-        lines.push('');
-        lines.push('3. **Verify authentication**');
-        lines.push('   - Check WEBHOOK_TOKEN is set');
-        lines.push('   - Verify token matches webhook config');
-        lines.push('');
-        lines.push('4. **Review webhook logs**');
-        lines.push('   ```bash');
-        lines.push(`   glab duo agent logs ${agentName} --filter webhook`);
-        lines.push('   ```');
-        lines.push('');
-        lines.push('## Diagnostic Commands');
-        lines.push('');
-        lines.push('```bash');
-        lines.push('# Complete diagnostic report');
-        lines.push(`glab duo agent diagnose ${agentName}`);
-        lines.push('');
-        lines.push('# Check agent configuration');
-        lines.push(`glab duo agent config ${agentName}`);
-        lines.push('');
-        lines.push('# Validate flow definition');
-        lines.push(`glab duo flow validate .gitlab/duo/flows/${agentName}.yaml`);
-        lines.push('');
-        lines.push('# Test agent locally');
-        lines.push(`glab duo agent test ${agentName} --input "test message"`);
-        lines.push('');
-        lines.push('# Export debug bundle');
-        lines.push(`glab duo agent debug-export ${agentName} > debug-bundle.tar.gz`);
-        lines.push('```');
-        lines.push('');
-        lines.push('## Getting Help');
-        lines.push('');
-        lines.push('If issues persist:');
-        lines.push('');
-        lines.push('1. **Check GitLab Status** - https://status.gitlab.com');
-        lines.push('2. **Review Documentation** - https://docs.gitlab.com/ee/user/gitlab_duo/');
-        lines.push('3. **Open Support Ticket** - https://support.gitlab.com');
-        lines.push('4. **Community Forum** - https://forum.gitlab.com');
-        lines.push('');
-        lines.push('## Debug Checklist');
-        lines.push('');
-        lines.push('Before opening a support ticket:');
-        lines.push('');
-        lines.push('- [ ] Agent status checked');
-        lines.push('- [ ] Error logs reviewed');
-        lines.push('- [ ] Authentication verified');
-        lines.push('- [ ] Triggers validated');
-        lines.push('- [ ] MCP servers tested');
-        lines.push('- [ ] Network connectivity confirmed');
-        lines.push('- [ ] Recent changes identified');
-        lines.push('- [ ] Diagnostic report generated');
-        lines.push('');
-        return lines.join('\n');
-    }
-    /**
-     * Generate FAQ.md
-     */
-    generateFAQ(manifest) {
-        const agentName = this.getAgentName(manifest);
-        const lines = [];
-        lines.push(`# FAQ: ${manifest.metadata?.name || 'Agent'}`);
-        lines.push('');
-        lines.push('## General');
-        lines.push('');
-        lines.push('### What is this agent?');
-        lines.push('');
-        lines.push(manifest.metadata?.description ||
-            'A GitLab Duo agent for automating tasks.');
-        lines.push('');
-        lines.push('### How do I trigger this agent?');
-        lines.push('');
-        lines.push('Multiple ways:');
-        lines.push('');
-        lines.push(`- **Mention**: \`@${agentName}\` in issue/MR comments`);
-        lines.push('- **Assignment**: Assign issue/MR to agent');
-        lines.push('- **Schedule**: Runs automatically based on schedule');
-        lines.push('- **Webhook**: Trigger via HTTP webhook');
-        lines.push('');
-        lines.push('### What permissions does the agent need?');
-        lines.push('');
-        lines.push('Required GitLab token scopes:');
-        lines.push('');
-        lines.push('- `api` - Full API access');
-        lines.push('- `read_repository` - Read repository data');
-        lines.push('- `write_repository` - Modify files (if applicable)');
-        lines.push('');
-        lines.push('## Deployment');
-        lines.push('');
-        lines.push('### How do I deploy this agent?');
-        lines.push('');
-        lines.push('Two deployment options:');
-        lines.push('');
-        lines.push('1. **Flow Agent** (Recommended) - Runs in GitLab Duo infrastructure');
-        lines.push('2. **External Agent** - Runs in your CI/CD pipeline');
-        lines.push('');
-        lines.push('See [DEPLOYMENT.md](./DEPLOYMENT.md) for detailed instructions.');
-        lines.push('');
-        lines.push('### Can I test locally before deploying?');
-        lines.push('');
-        lines.push('Yes:');
-        lines.push('');
-        lines.push('```bash');
-        lines.push('npm install');
-        lines.push('npm run build');
-        lines.push(`glab duo agent test ${agentName} --input "test message"`);
-        lines.push('```');
-        lines.push('');
-        lines.push('### How do I update the agent?');
-        lines.push('');
-        lines.push('```bash');
-        lines.push('# 1. Make changes locally');
-        lines.push('# 2. Build');
-        lines.push('npm run build');
-        lines.push('');
-        lines.push('# 3. Redeploy flow');
-        lines.push(`glab duo flow deploy ${agentName} --update`);
-        lines.push('```');
-        lines.push('');
-        lines.push('## Usage');
-        lines.push('');
-        lines.push('### How do I see agent execution history?');
-        lines.push('');
-        lines.push('```bash');
-        lines.push(`glab duo agent executions ${agentName}`);
-        lines.push('```');
-        lines.push('');
-        lines.push('### How do I view agent logs?');
-        lines.push('');
-        lines.push('```bash');
-        lines.push(`# Recent logs`);
-        lines.push(`glab duo agent logs ${agentName}`);
-        lines.push('');
-        lines.push('# Follow in real-time');
-        lines.push(`glab duo agent logs ${agentName} --follow`);
-        lines.push('```');
-        lines.push('');
-        lines.push('### Can the agent access private repositories?');
-        lines.push('');
-        lines.push('Yes, if the GitLab token has appropriate permissions. The agent can access any repository the token owner can access.');
-        lines.push('');
-        lines.push('### What tools does the agent have access to?');
-        lines.push('');
-        lines.push('See `.gitlab/duo/custom-tools.json` for complete list. Common tools:');
-        lines.push('');
-        lines.push('- File operations (read, write, search)');
-        lines.push('- GitLab operations (issues, MRs, comments)');
-        lines.push('- Shell commands (if enabled)');
-        lines.push('');
-        lines.push('## Customization');
-        lines.push('');
-        lines.push('### How do I modify the agent behavior?');
-        lines.push('');
-        lines.push('Edit the system prompt in `.gitlab/duo/flows/${agentName}.yaml`:');
-        lines.push('');
-        lines.push('```yaml');
-        lines.push('prompts:');
-        lines.push(`  - prompt_id: ${agentName}_prompt`);
-        lines.push('    prompt_template:');
-        lines.push('      system: "Your custom instructions here"');
-        lines.push('```');
-        lines.push('');
-        lines.push('### Can I add more triggers?');
-        lines.push('');
-        lines.push('Yes, create new trigger files in `.gitlab/duo/triggers/`:');
-        lines.push('');
-        lines.push('```yaml');
-        lines.push('version: v1');
-        lines.push(`agent_name: ${agentName}`);
-        lines.push('trigger:');
-        lines.push('  type: schedule');
-        lines.push('  cron: "0 * * * *"  # Hourly');
-        lines.push('```');
-        lines.push('');
-        lines.push('### Can I use a different LLM model?');
-        lines.push('');
-        lines.push('Yes, edit the model configuration in flow YAML:');
-        lines.push('');
-        lines.push('```yaml');
-        lines.push('prompts:');
-        lines.push('  - model:');
-        lines.push('      params:');
-        lines.push('        model_class_provider: anthropic');
-        lines.push('        model: claude-opus-4  # Change here');
-        lines.push('```');
-        lines.push('');
-        lines.push('### How do I add custom tools?');
-        lines.push('');
-        lines.push('1. Define tool in `.gitlab/duo/custom-tools.json`');
-        lines.push('2. Implement tool in `src/tools/`');
-        lines.push('3. Register in MCP config');
-        lines.push('4. Rebuild and redeploy');
-        lines.push('');
-        lines.push('## Troubleshooting');
-        lines.push('');
-        lines.push('### Agent not responding?');
-        lines.push('');
-        lines.push('See [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) for detailed debugging steps.');
-        lines.push('');
-        lines.push('### High response time?');
-        lines.push('');
-        lines.push('Common causes:');
-        lines.push('');
-        lines.push('- Large prompt size → Reduce context');
-        lines.push('- Many tool calls → Optimize workflow');
-        lines.push('- Slow model → Use faster model (haiku, gpt-4o-mini)');
-        lines.push('');
-        lines.push('### Authentication errors?');
-        lines.push('');
-        lines.push('Check:');
-        lines.push('');
-        lines.push('1. GitLab token is valid: `glab auth status`');
-        lines.push('2. Token has correct scopes');
-        lines.push('3. Token not expired');
-        lines.push('');
-        lines.push('## Performance');
-        lines.push('');
-        lines.push('### How many executions can the agent handle?');
-        lines.push('');
-        lines.push('Depends on deployment mode:');
-        lines.push('');
-        lines.push('- **Flow Agent**: Scales automatically (GitLab handles infrastructure)');
-        lines.push('- **External Agent**: Limited by CI/CD runners');
-        lines.push('');
-        lines.push('### What are the token limits?');
-        lines.push('');
-        lines.push('Varies by model:');
-        lines.push('');
-        lines.push('- Claude Sonnet 4: 200K tokens');
-        lines.push('- GPT-4o: 128K tokens');
-        lines.push('- Gemini 1.5 Pro: 2M tokens');
-        lines.push('');
-        lines.push('### How much does it cost to run?');
-        lines.push('');
-        lines.push('Costs depend on:');
-        lines.push('');
-        lines.push('- Model used (Claude, GPT, Gemini)');
-        lines.push('- Token usage per execution');
-        lines.push('- Number of executions');
-        lines.push('');
-        lines.push('Monitor costs: `glab duo agent metrics ${agentName} --metric token_usage`');
-        lines.push('');
-        lines.push('## Security');
-        lines.push('');
-        lines.push('### Is my data secure?');
-        lines.push('');
-        lines.push('Yes:');
-        lines.push('');
-        lines.push('- All data encrypted in transit (TLS)');
-        lines.push('- Tokens stored as masked CI/CD variables');
-        lines.push('- Conversation history not persisted');
-        lines.push('- PII redaction enabled');
-        lines.push('');
-        lines.push('See [SECURITY.md](./SECURITY.md) for details.');
-        lines.push('');
-        lines.push('### Can I restrict agent permissions?');
-        lines.push('');
-        lines.push('Yes:');
-        lines.push('');
-        lines.push('- Limit GitLab token scopes');
-        lines.push('- Restrict trigger permissions');
-        lines.push('- Disable dangerous tools (shell execution)');
-        lines.push('- Use read-only mode');
-        lines.push('');
-        lines.push('## Support');
-        lines.push('');
-        lines.push('### Where do I get help?');
-        lines.push('');
-        lines.push('1. Check [TROUBLESHOOTING.md](./TROUBLESHOOTING.md)');
-        lines.push('2. Review [GitLab Duo Documentation](https://docs.gitlab.com/ee/user/gitlab_duo/)');
-        lines.push('3. Open support ticket: https://support.gitlab.com');
-        lines.push('4. Community forum: https://forum.gitlab.com');
-        lines.push('');
-        lines.push('### How do I report a bug?');
-        lines.push('');
-        lines.push('1. Generate diagnostic report: `glab duo agent diagnose ${agentName}`');
-        lines.push('2. Open issue in GitLab project');
-        lines.push('3. Include diagnostic report and error logs');
-        lines.push('');
-        lines.push('### Can I contribute improvements?');
-        lines.push('');
-        lines.push('Yes! Submit merge requests with:');
-        lines.push('');
-        lines.push('- Bug fixes');
-        lines.push('- New features');
-        lines.push('- Documentation improvements');
-        lines.push('- Performance optimizations');
-        lines.push('');
-        return lines.join('\n');
-    }
-    /**
-     * Generate ARCHITECTURE.md
-     */
-    generateArchitecture(manifest) {
-        const agentName = this.getAgentName(manifest);
-        const lines = [];
-        lines.push(`# Architecture: ${manifest.metadata?.name || 'Agent'}`);
-        lines.push('');
-        lines.push('## Overview');
-        lines.push('');
-        lines.push('This document describes the architecture of this GitLab Duo agent, including its components, data flow, and integration points.');
-        lines.push('');
-        lines.push('## High-Level Architecture');
-        lines.push('');
-        lines.push('```');
-        lines.push('┌─────────────────────────────────────────────────────────┐');
-        lines.push('│                    GitLab Platform                      │');
-        lines.push('│  ┌──────────┐  ┌──────────┐  ┌──────────────────────┐ │');
-        lines.push('│  │  Issues  │  │   MRs    │  │  CI/CD Pipelines     │ │');
-        lines.push('│  └────┬─────┘  └────┬─────┘  └──────────┬───────────┘ │');
-        lines.push('└───────┼─────────────┼──────────────────┼──────────────┘');
-        lines.push('        │             │                  │');
-        lines.push('        └─────────────┼──────────────────┘');
-        lines.push('                      │ Triggers');
-        lines.push('                      ▼');
-        lines.push('        ┌─────────────────────────────┐');
-        lines.push('        │   GitLab Duo Flow Engine    │');
-        lines.push('        │  ┌────────────────────────┐ │');
-        lines.push('        │  │  Trigger Handler       │ │');
-        lines.push('        │  └──────────┬─────────────┘ │');
-        lines.push('        │             │               │');
-        lines.push('        │  ┌──────────▼─────────────┐ │');
-        lines.push(`        │  │  ${agentName} Agent     │ │`);
-        lines.push('        │  │  - System Prompt       │ │');
-        lines.push('        │  │  - Router Logic        │ │');
-        lines.push('        │  │  - Component Exec      │ │');
-        lines.push('        │  └──────────┬─────────────┘ │');
-        lines.push('        └─────────────┼───────────────┘');
-        lines.push('                      │');
-        lines.push('                      ▼');
-        lines.push('        ┌─────────────────────────────┐');
-        lines.push('        │     AI Gateway              │');
-        lines.push('        │  ┌────────────────────────┐ │');
-        lines.push('        │  │  Model Router          │ │');
-        lines.push('        │  └──────────┬─────────────┘ │');
-        lines.push('        │             │               │');
-        lines.push('        │  ┌──────────▼─────────────┐ │');
-        lines.push('        │  │  LLM Provider          │ │');
-        lines.push('        │  │  (Anthropic/OpenAI)    │ │');
-        lines.push('        │  └────────────────────────┘ │');
-        lines.push('        └─────────────────────────────┘');
-        lines.push('                      │');
-        lines.push('                      ▼');
-        lines.push('        ┌─────────────────────────────┐');
-        lines.push('        │     MCP Servers             │');
-        lines.push('        │  ┌────────┐  ┌────────────┐ │');
-        lines.push('        │  │ GitLab │  │ Filesystem │ │');
-        lines.push('        │  └────────┘  └────────────┘ │');
-        lines.push('        │  ┌────────┐  ┌────────────┐ │');
-        lines.push('        │  │ Memory │  │   Custom   │ │');
-        lines.push('        │  └────────┘  └────────────┘ │');
-        lines.push('        └─────────────────────────────┘');
-        lines.push('```');
-        lines.push('');
-        lines.push('## Components');
-        lines.push('');
-        lines.push('### 1. Trigger System');
-        lines.push('');
-        lines.push('Manages agent activation based on events:');
-        lines.push('');
-        lines.push('- **Mention Trigger**: @agent mentions in issues/MRs');
-        lines.push('- **Assignment Trigger**: Issue/MR assignments');
-        lines.push('- **Schedule Trigger**: Cron-based execution');
-        lines.push('- **Webhook Trigger**: External HTTP events');
-        lines.push('- **Pipeline Trigger**: CI/CD pipeline events');
-        lines.push('- **File Pattern Trigger**: File change detection');
-        lines.push('');
-        lines.push('**Location**: `.gitlab/duo/triggers/*.yaml`');
-        lines.push('');
-        lines.push('### 2. Flow Engine');
-        lines.push('');
-        lines.push('Orchestrates agent execution:');
-        lines.push('');
-        lines.push('- **Entry Point**: Receives trigger events');
-        lines.push('- **Context Building**: Gathers relevant data');
-        lines.push('- **Component Execution**: Runs agent components');
-        lines.push('- **Router Logic**: Routes between components');
-        lines.push('- **Output Handling**: Formats and delivers responses');
-        lines.push('');
-        lines.push('**Location**: `.gitlab/duo/flows/${agentName}.yaml`');
-        lines.push('');
-        lines.push('### 3. Agent Component');
-        lines.push('');
-        lines.push('Core agent logic:');
-        lines.push('');
-        lines.push('```typescript');
-        lines.push('interface AgentComponent {');
-        lines.push('  name: string;');
-        lines.push('  type: "AgentComponent";');
-        lines.push('  prompt_id: string;');
-        lines.push('  toolset: string[];');
-        lines.push('  inputs: FlowInput[];');
-        lines.push('}');
-        lines.push('```');
-        lines.push('');
-        lines.push('**Responsibilities:**');
-        lines.push('- Receive task from trigger');
-        lines.push('- Execute LLM inference');
-        lines.push('- Call tools as needed');
-        lines.push('- Return structured response');
-        lines.push('');
-        lines.push('### 4. Prompt System');
-        lines.push('');
-        lines.push('Manages LLM prompts:');
-        lines.push('');
-        lines.push('```yaml');
-        lines.push('prompts:');
-        lines.push(`  - prompt_id: ${agentName}_prompt`);
-        lines.push('    prompt_template:');
-        lines.push('      system: "System instructions"');
-        lines.push('      user: "{{task}}"');
-        lines.push('      placeholder: history');
-        lines.push('    model:');
-        lines.push('      params:');
-        lines.push('        model_class_provider: anthropic');
-        lines.push('        model: claude-sonnet-4');
-        lines.push('```');
-        lines.push('');
-        lines.push('### 5. Tool System (MCP)');
-        lines.push('');
-        lines.push('Provides tools via Model Context Protocol:');
-        lines.push('');
-        lines.push('**MCP Servers:**');
-        lines.push('- `gitlab`: GitLab API operations');
-        lines.push('- `filesystem`: File operations');
-        lines.push('- `memory`: Persistent memory');
-        lines.push('- `custom`: Custom tool implementations');
-        lines.push('');
-        lines.push('**Configuration**: `.gitlab/duo/mcp-config.json`');
-        lines.push('');
-        lines.push('### 6. Router System');
-        lines.push('');
-        lines.push('Controls execution flow:');
-        lines.push('');
-        lines.push('```yaml');
-        lines.push('routers:');
-        lines.push('  # Simple routing');
-        lines.push(`  - from: ${agentName}`);
-        lines.push('    to: end');
-        lines.push('');
-        lines.push('  # Conditional routing');
-        lines.push(`  - from: ${agentName}`);
-        lines.push('    condition:');
-        lines.push('      input: decision');
-        lines.push('      routes:');
-        lines.push('        approve: next_step');
-        lines.push('        reject: error_handler');
-        lines.push('```');
-        lines.push('');
-        lines.push('## Data Flow');
-        lines.push('');
-        lines.push('### Execution Flow');
-        lines.push('');
-        lines.push('1. **Trigger Event**');
-        lines.push('   - User mentions @agent in issue');
-        lines.push('   - Trigger handler receives event');
-        lines.push('   - Event validated and queued');
-        lines.push('');
-        lines.push('2. **Context Building**');
-        lines.push('   - Fetch issue content');
-        lines.push('   - Load conversation history');
-        lines.push('   - Gather relevant context');
-        lines.push('');
-        lines.push('3. **Agent Execution**');
-        lines.push('   - Load system prompt');
-        lines.push('   - Build user message with context');
-        lines.push('   - Send to AI Gateway');
-        lines.push('');
-        lines.push('4. **LLM Inference**');
-        lines.push('   - AI Gateway routes to model provider');
-        lines.push('   - LLM processes prompt');
-        lines.push('   - Returns response with tool calls');
-        lines.push('');
-        lines.push('5. **Tool Execution**');
-        lines.push('   - Parse tool calls');
-        lines.push('   - Execute via MCP servers');
-        lines.push('   - Return tool outputs');
-        lines.push('');
-        lines.push('6. **Response Generation**');
-        lines.push('   - LLM processes tool outputs');
-        lines.push('   - Generates final response');
-        lines.push('   - Format for delivery');
-        lines.push('');
-        lines.push('7. **Response Delivery**');
-        lines.push('   - Post comment to issue');
-        lines.push('   - Update issue status (if applicable)');
-        lines.push('   - Log execution metrics');
-        lines.push('');
-        lines.push('## Integration Points');
-        lines.push('');
-        lines.push('### GitLab API');
-        lines.push('');
-        lines.push('- **Authentication**: Personal access token');
-        lines.push('- **Endpoints Used**:');
-        lines.push('  - `/api/v4/projects/:id/issues`');
-        lines.push('  - `/api/v4/projects/:id/merge_requests`');
-        lines.push('  - `/api/v4/projects/:id/repository/files`');
-        lines.push('- **Rate Limits**: 600 requests/minute');
-        lines.push('');
-        lines.push('### AI Gateway');
-        lines.push('');
-        lines.push('- **Protocol**: HTTP/2');
-        lines.push('- **Authentication**: JWT token');
-        lines.push('- **Endpoints**:');
-        lines.push('  - `/v1/chat/completions` - LLM inference');
-        lines.push('  - `/v1/embeddings` - Vector embeddings');
-        lines.push('');
-        lines.push('### MCP Servers');
-        lines.push('');
-        lines.push('- **Protocol**: JSON-RPC 2.0 over stdio');
-        lines.push('- **Lifecycle**: Started on-demand, kept warm');
-        lines.push('- **Communication**: Process IPC');
-        lines.push('');
-        lines.push('## Security Architecture');
-        lines.push('');
-        lines.push('### Authentication Chain');
-        lines.push('');
-        lines.push('```');
-        lines.push('User → GitLab (OAuth) → Flow Engine (JWT) → AI Gateway (Token) → LLM Provider');
-        lines.push('```');
-        lines.push('');
-        lines.push('### Data Security');
-        lines.push('');
-        lines.push('- **In Transit**: TLS 1.3 encryption');
-        lines.push('- **At Rest**: No persistent storage (ephemeral)');
-        lines.push('- **Token Storage**: GitLab CI/CD variables (masked)');
-        lines.push('- **PII Handling**: Redacted before logging');
-        lines.push('');
-        lines.push('## Scalability');
-        lines.push('');
-        lines.push('### Flow Agent (Managed)');
-        lines.push('');
-        lines.push('- Horizontal scaling (GitLab manages)');
-        lines.push('- Auto-scales based on load');
-        lines.push('- No infrastructure management');
-        lines.push('');
-        lines.push('### External Agent (Self-Hosted)');
-        lines.push('');
-        lines.push('- Scales with CI/CD runner capacity');
-        lines.push('- Concurrent execution limited by runners');
-        lines.push('- Manual scaling required');
-        lines.push('');
-        lines.push('## Monitoring & Observability');
-        lines.push('');
-        lines.push('### Metrics Collected');
-        lines.push('');
-        lines.push('- Execution count');
-        lines.push('- Response time (p50, p95, p99)');
-        lines.push('- Error rate');
-        lines.push('- Token usage');
-        lines.push('- Tool call count');
-        lines.push('');
-        lines.push('### Logging');
-        lines.push('');
-        lines.push('- **Levels**: ERROR, WARN, INFO, DEBUG');
-        lines.push('- **Retention**: 30 days');
-        lines.push('- **Format**: Structured JSON');
-        lines.push('');
-        lines.push('### Tracing');
-        lines.push('');
-        lines.push('- Distributed tracing via OpenTelemetry');
-        lines.push('- Trace ID propagation through components');
-        lines.push('- Full execution path visualization');
-        lines.push('');
-        lines.push('## Deployment Models');
-        lines.push('');
-        lines.push('### Flow Agent (Recommended)');
-        lines.push('');
-        lines.push('**Pros:**');
-        lines.push('- Zero infrastructure management');
-        lines.push('- Auto-scaling');
-        lines.push('- Built-in monitoring');
-        lines.push('- Faster cold starts');
-        lines.push('');
-        lines.push('**Cons:**');
-        lines.push('- Less control over execution environment');
-        lines.push('- Potential vendor lock-in');
-        lines.push('');
-        lines.push('### External Agent');
-        lines.push('');
-        lines.push('**Pros:**');
-        lines.push('- Full control over environment');
-        lines.push('- Can use private runners');
-        lines.push('- Custom dependencies');
-        lines.push('');
-        lines.push('**Cons:**');
-        lines.push('- Manual scaling required');
-        lines.push('- Infrastructure management overhead');
-        lines.push('- Slower cold starts');
-        lines.push('');
-        lines.push('## Future Enhancements');
-        lines.push('');
-        lines.push('Planned improvements:');
-        lines.push('');
-        lines.push('- [ ] Multi-agent orchestration');
-        lines.push('- [ ] Persistent memory across sessions');
-        lines.push('- [ ] Advanced router patterns (parallel, conditional)');
-        lines.push('- [ ] Custom model fine-tuning');
-        lines.push('- [ ] Enhanced error recovery');
-        lines.push('- [ ] Real-time streaming responses');
-        lines.push('');
-        return lines.join('\n');
-    }
-    /**
-     * Generate API.md
-     */
-    generateAPIDocumentation(manifest) {
-        const agentName = this.getAgentName(manifest);
-        const lines = [];
-        lines.push(`# API Documentation: ${manifest.metadata?.name || 'Agent'}`);
-        lines.push('');
-        lines.push('## Overview');
-        lines.push('');
-        lines.push('This document describes the APIs for interacting with this GitLab Duo agent programmatically.');
-        lines.push('');
-        lines.push('## GitLab API Integration');
-        lines.push('');
-        lines.push('### Trigger Agent via API');
-        lines.push('');
-        lines.push('**Endpoint:** `POST /api/v4/projects/:id/duo/agents/:agent_id/trigger`');
-        lines.push('');
-        lines.push('**Authentication:** GitLab personal access token with `api` scope');
-        lines.push('');
-        lines.push('**Request:**');
-        lines.push('```bash');
-        lines.push('curl -X POST \\');
-        lines.push('  "https://gitlab.com/api/v4/projects/PROJECT_ID/duo/agents/${agentName}/trigger" \\');
-        lines.push('  -H "PRIVATE-TOKEN: YOUR_TOKEN" \\');
-        lines.push('  -H "Content-Type: application/json" \\');
-        lines.push("  -d '{");
-        lines.push('    "input": "Your task description",');
-        lines.push('    "context": {');
-        lines.push('      "issue_iid": 123,');
-        lines.push('      "merge_request_iid": 456');
-        lines.push('    }');
-        lines.push("  }'");
-        lines.push('```');
-        lines.push('');
-        lines.push('**Response:**');
-        lines.push('```json');
-        lines.push('{');
-        lines.push('  "execution_id": "exec-abc123",');
-        lines.push('  "status": "running",');
-        lines.push('  "created_at": "2026-02-07T00:00:00Z"');
-        lines.push('}');
-        lines.push('```');
-        lines.push('');
-        lines.push('### Check Execution Status');
-        lines.push('');
-        lines.push('**Endpoint:** `GET /api/v4/projects/:id/duo/agents/:agent_id/executions/:execution_id`');
-        lines.push('');
-        lines.push('**Request:**');
-        lines.push('```bash');
-        lines.push('curl "https://gitlab.com/api/v4/projects/PROJECT_ID/duo/agents/${agentName}/executions/exec-abc123" \\');
-        lines.push('  -H "PRIVATE-TOKEN: YOUR_TOKEN"');
-        lines.push('```');
-        lines.push('');
-        lines.push('**Response:**');
-        lines.push('```json');
-        lines.push('{');
-        lines.push('  "execution_id": "exec-abc123",');
-        lines.push('  "status": "completed",');
-        lines.push('  "result": {');
-        lines.push('    "output": "Task completed successfully",');
-        lines.push('    "tool_calls": 3,');
-        lines.push('    "tokens_used": 1245');
-        lines.push('  },');
-        lines.push('  "created_at": "2026-02-07T00:00:00Z",');
-        lines.push('  "completed_at": "2026-02-07T00:00:15Z"');
-        lines.push('}');
-        lines.push('```');
-        lines.push('');
-        lines.push('### List Agent Executions');
-        lines.push('');
-        lines.push('**Endpoint:** `GET /api/v4/projects/:id/duo/agents/:agent_id/executions`');
-        lines.push('');
-        lines.push('**Query Parameters:**');
-        lines.push('- `page` - Page number (default: 1)');
-        lines.push('- `per_page` - Items per page (default: 20, max: 100)');
-        lines.push('- `status` - Filter by status (`running`, `completed`, `failed`)');
-        lines.push('- `since` - Filter executions after date (ISO 8601)');
-        lines.push('');
-        lines.push('**Request:**');
-        lines.push('```bash');
-        lines.push('curl "https://gitlab.com/api/v4/projects/PROJECT_ID/duo/agents/${agentName}/executions?status=completed&per_page=10" \\');
-        lines.push('  -H "PRIVATE-TOKEN: YOUR_TOKEN"');
-        lines.push('```');
-        lines.push('');
-        lines.push('### Get Agent Logs');
-        lines.push('');
-        lines.push('**Endpoint:** `GET /api/v4/projects/:id/duo/agents/:agent_id/logs`');
-        lines.push('');
-        lines.push('**Query Parameters:**');
-        lines.push('- `execution_id` - Filter by execution');
-        lines.push('- `level` - Filter by log level (`ERROR`, `WARN`, `INFO`, `DEBUG`)');
-        lines.push('- `since` - Filter logs after timestamp');
-        lines.push('- `limit` - Max number of log entries (default: 100, max: 1000)');
-        lines.push('');
-        lines.push('**Request:**');
-        lines.push('```bash');
-        lines.push('curl "https://gitlab.com/api/v4/projects/PROJECT_ID/duo/agents/${agentName}/logs?level=ERROR&limit=50" \\');
-        lines.push('  -H "PRIVATE-TOKEN: YOUR_TOKEN"');
-        lines.push('```');
-        lines.push('');
-        lines.push('### Get Agent Metrics');
-        lines.push('');
-        lines.push('**Endpoint:** `GET /api/v4/projects/:id/duo/agents/:agent_id/metrics`');
-        lines.push('');
-        lines.push('**Query Parameters:**');
-        lines.push('- `metric` - Specific metric name (optional)');
-        lines.push('- `period` - Time period (`1h`, `24h`, `7d`, `30d`)');
-        lines.push('- `format` - Output format (`json`, `prometheus`)');
-        lines.push('');
-        lines.push('**Request:**');
-        lines.push('```bash');
-        lines.push('curl "https://gitlab.com/api/v4/projects/PROJECT_ID/duo/agents/${agentName}/metrics?period=24h" \\');
-        lines.push('  -H "PRIVATE-TOKEN: YOUR_TOKEN"');
-        lines.push('```');
-        lines.push('');
-        lines.push('**Response:**');
-        lines.push('```json');
-        lines.push('{');
-        lines.push('  "period": "24h",');
-        lines.push('  "metrics": {');
-        lines.push('    "execution_count": 142,');
-        lines.push('    "success_rate": 0.985,');
-        lines.push('    "avg_response_time_ms": 3245,');
-        lines.push('    "p95_response_time_ms": 8932,');
-        lines.push('    "total_tokens_used": 125430,');
-        lines.push('    "error_count": 2');
-        lines.push('  }');
-        lines.push('}');
-        lines.push('```');
-        lines.push('');
-        lines.push('## Webhook API');
-        lines.push('');
-        lines.push('### Trigger via Webhook');
-        lines.push('');
-        lines.push('If webhook trigger is configured (`.gitlab/duo/triggers/webhook.yaml`):');
-        lines.push('');
-        lines.push('**Endpoint:** Your configured webhook URL');
-        lines.push('');
-        lines.push('**Authentication:** Bearer token (set in `WEBHOOK_TOKEN`)');
-        lines.push('');
-        lines.push('**Request:**');
-        lines.push('```bash');
-        lines.push('curl -X POST \\');
-        lines.push('  "https://your-instance.com/webhooks/${agentName}" \\');
-        lines.push('  -H "Authorization: Bearer YOUR_WEBHOOK_TOKEN" \\');
-        lines.push('  -H "Content-Type: application/json" \\');
-        lines.push("  -d '{");
-        lines.push('    "event": "custom_event",');
-        lines.push('    "data": {');
-        lines.push('      "key": "value"');
-        lines.push('    }');
-        lines.push("  }'");
-        lines.push('```');
-        lines.push('');
-        lines.push('## glab CLI');
-        lines.push('');
-        lines.push('### Command Reference');
-        lines.push('');
-        lines.push('```bash');
-        lines.push('# Trigger agent');
-        lines.push(`glab duo agent trigger ${agentName} --input "task description"`);
-        lines.push('');
-        lines.push('# List executions');
-        lines.push(`glab duo agent executions ${agentName}`);
-        lines.push('');
-        lines.push('# View logs');
-        lines.push(`glab duo agent logs ${agentName} --follow`);
-        lines.push('');
-        lines.push('# Get metrics');
-        lines.push(`glab duo agent metrics ${agentName} --period 24h`);
-        lines.push('');
-        lines.push('# Check status');
-        lines.push(`glab duo agent status ${agentName}`);
-        lines.push('');
-        lines.push('# Test agent');
-        lines.push(`glab duo agent test ${agentName} --input "test input"`);
-        lines.push('```');
-        lines.push('');
-        lines.push('## SDK Examples');
-        lines.push('');
-        lines.push('### TypeScript/Node.js');
-        lines.push('');
-        lines.push('```typescript');
-        lines.push('import { Gitlab } from "@gitbeaker/rest";');
-        lines.push('');
-        lines.push('const api = new Gitlab({');
-        lines.push('  token: process.env.GITLAB_TOKEN,');
-        lines.push('  host: "https://gitlab.com",');
-        lines.push('});');
-        lines.push('');
-        lines.push('// Trigger agent');
-        lines.push('const execution = await api.DuoAgents.trigger(');
-        lines.push('  "project-id",');
-        lines.push(`  "${agentName}",`);
-        lines.push('  {');
-        lines.push('    input: "Your task",');
-        lines.push('    context: { issue_iid: 123 },');
-        lines.push('  }');
-        lines.push(');');
-        lines.push('');
-        lines.push('// Wait for completion');
-        lines.push('let status = "running";');
-        lines.push('while (status === "running") {');
-        lines.push('  await new Promise(resolve => setTimeout(resolve, 1000));');
-        lines.push('  const result = await api.DuoAgents.getExecution(');
-        lines.push('    "project-id",');
-        lines.push(`    "${agentName}",`);
-        lines.push('    execution.execution_id');
-        lines.push('  );');
-        lines.push('  status = result.status;');
-        lines.push('}');
-        lines.push('```');
-        lines.push('');
-        lines.push('### Python');
-        lines.push('');
-        lines.push('```python');
-        lines.push('import gitlab');
-        lines.push('import time');
-        lines.push('');
-        lines.push('gl = gitlab.Gitlab("https://gitlab.com", private_token="YOUR_TOKEN")');
-        lines.push('project = gl.projects.get("project-id")');
-        lines.push('');
-        lines.push('# Trigger agent');
-        lines.push(`execution = project.duo_agents.get("${agentName}").trigger(`);
-        lines.push('    input="Your task",');
-        lines.push('    context={"issue_iid": 123}');
-        lines.push(')');
-        lines.push('');
-        lines.push('# Wait for completion');
-        lines.push('while execution.status == "running":');
-        lines.push('    time.sleep(1)');
-        lines.push('    execution.refresh()');
-        lines.push('');
-        lines.push('print(f"Result: {execution.result}")');
-        lines.push('```');
-        lines.push('');
-        lines.push('## Rate Limits');
-        lines.push('');
-        lines.push('| Operation | Limit | Period |');
-        lines.push('|-----------|-------|--------|');
-        lines.push('| Agent Triggers | 100 | per hour |');
-        lines.push('| API Requests | 600 | per minute |');
-        lines.push('| Webhook Calls | 1000 | per hour |');
-        lines.push('');
-        lines.push('**Rate Limit Headers:**');
-        lines.push('```');
-        lines.push('RateLimit-Limit: 600');
-        lines.push('RateLimit-Remaining: 599');
-        lines.push('RateLimit-Reset: 1612137600');
-        lines.push('```');
-        lines.push('');
-        lines.push('## Error Responses');
-        lines.push('');
-        lines.push('### 400 Bad Request');
-        lines.push('```json');
-        lines.push('{');
-        lines.push('  "error": "Invalid input",');
-        lines.push('  "message": "Input field is required"');
-        lines.push('}');
-        lines.push('```');
-        lines.push('');
-        lines.push('### 401 Unauthorized');
-        lines.push('```json');
-        lines.push('{');
-        lines.push('  "error": "Unauthorized",');
-        lines.push('  "message": "Invalid or expired token"');
-        lines.push('}');
-        lines.push('```');
-        lines.push('');
-        lines.push('### 404 Not Found');
-        lines.push('```json');
-        lines.push('{');
-        lines.push('  "error": "Not found",');
-        lines.push('  "message": "Agent not found"');
-        lines.push('}');
-        lines.push('```');
-        lines.push('');
-        lines.push('### 429 Too Many Requests');
-        lines.push('```json');
-        lines.push('{');
-        lines.push('  "error": "Rate limit exceeded",');
-        lines.push('  "message": "Too many requests, retry after 60 seconds",');
-        lines.push('  "retry_after": 60');
-        lines.push('}');
-        lines.push('```');
-        lines.push('');
-        lines.push('### 500 Internal Server Error');
-        lines.push('```json');
-        lines.push('{');
-        lines.push('  "error": "Internal error",');
-        lines.push('  "message": "Agent execution failed",');
-        lines.push('  "trace_id": "abc123"');
-        lines.push('}');
-        lines.push('```');
-        lines.push('');
-        lines.push('## Best Practices');
-        lines.push('');
-        lines.push("1. **Use polling with backoff** - Don't spam status checks");
-        lines.push('2. **Handle rate limits** - Respect RateLimit headers');
-        lines.push('3. **Include context** - Provide issue/MR context when available');
-        lines.push('4. **Validate inputs** - Check input format before triggering');
-        lines.push('5. **Log trace IDs** - Include trace_id in error reports');
-        lines.push('');
-        lines.push('## OpenAPI Specification');
-        lines.push('');
-        lines.push('Full OpenAPI spec available at:');
-        lines.push('');
-        lines.push('```bash');
-        lines.push('# Download OpenAPI spec');
-        lines.push('curl "https://gitlab.com/api/v4/duo/openapi.yaml" > openapi.yaml');
-        lines.push('```');
-        lines.push('');
-        return lines.join('\n');
-    }
-}
-//# sourceMappingURL=package-generator.js.map