@bluefly/openstandardagents 0.5.0 → 0.5.3

package/examples/gitlab-duo/README.md

@@ -1,307 +0,0 @@
-# GitLab Duo Agent Platform Export
-
-This directory contains examples of GitLab Duo Flow Registry v1 configurations generated from OSSA manifests.
-
-## Overview
-
-The GitLab Duo export transforms OSSA agents into production-ready GitLab Duo flows that can run natively on GitLab's Agent Platform.
-
-## Features
-
-- **Flow Registry v1 Compliance**: Generated flows follow GitLab's Flow Registry v1 specification
-- **Automatic Environment Detection**: Selects `ambient`, `chat`, or `chat-partial` based on autonomy level
-- **MCP Tool Integration**: Maps OSSA tools to GitLab's built-in MCP tools
-- **Inline Prompt Definitions**: Embeds system prompts and LLM configuration
-- **Multi-Provider Support**: Works with Anthropic, OpenAI, and Google Vertex AI
-
-## Usage
-
-### Generate Flow from OSSA Manifest
-
-```bash
-# Using OSSA CLI
-ossa export creative-agent-naming.ossa.yaml --platform gitlab --format flow -o .gitlab/duo/flows/
-
-# This generates:
-# .gitlab/duo/flows/creative-agent-naming.yaml
-```
-
-### OSSA Manifest Example
-
-```yaml
-apiVersion: ossa/v0.4.5
-kind: Agent
-metadata:
-  name: code-review-agent
-  version: 1.0.0
-  description: AI-powered code review assistant
-spec:
-  role: |
-    You are an expert code reviewer with deep knowledge of software engineering
-    best practices, security vulnerabilities, and performance optimization.
-  llm:
-    provider: anthropic
-    model: claude-sonnet-4-20250514
-    temperature: 0.7
-    maxTokens: 4096
-  autonomy:
-    level: supervised
-    approvalRequired:
-      - critical-actions
-    maxTurns: 10
-  tools:
-    - name: read
-      description: Read file contents
-    - name: search
-      description: Search codebase
-    - name: comment
-      description: Add comments to merge requests
-```
-
-### Generated Flow Structure
-
-```yaml
-version: v1                          # Flow Registry v1
-environment: chat                    # Collaborative mode
-name: code-review-agent
-description: AI-powered code review assistant
-product_group: agent_foundations
-
-components:
-  - name: code_review_agent
-    type: AgentComponent             # Multi-turn agent with tools
-    prompt_id: code_review_agent_prompt
-    toolset:
-      - read_file
-      - search_files
-      - add_comment
-    ui_log_events:
-      - on_agent_final_answer
-      - on_tool_execution_success
-
-routers:
-  - from: code_review_agent
-    to: end
-
-prompts:
-  - prompt_id: code_review_agent_prompt
-    model:
-      params:
-        model_class_provider: anthropic
-        model: claude-sonnet-4-20250514
-        max_tokens: 4096
-        temperature: 0.7
-    prompt_template:
-      system: "You are an expert code reviewer..."
-      user: "{{task}}"
-      placeholder: history            # Enable conversation history
-
-flow:
-  entry_point: code_review_agent
-```
-
-## Environment Types
-
-The generator automatically selects the appropriate environment based on your agent's autonomy configuration:
-
-### `ambient` (Hands-off)
-- **When**: `autonomy.level: autonomous` AND no approval requirements
-- **Use Case**: Scheduled tasks, automated analysis, background jobs
-- **Example**: Nightly security scans, automated dependency updates
-
-### `chat` (Collaborative)
-- **When**: `autonomy.level: supervised` OR `autonomy.level: collaborative`
-- **Use Case**: Interactive code reviews, pair programming, debugging
-- **Example**: On-demand code reviews, interactive issue triage
-
-### `chat-partial` (Simple Conversation)
-- **When**: `autonomy.maxTurns: 1` AND no tools
-- **Use Case**: Q&A, documentation lookup, simple queries
-- **Example**: "What does this function do?", "Explain this error"
-
-## Tool Mapping
-
-OSSA tools are automatically mapped to GitLab's built-in MCP tools:
-
-| OSSA Tool | GitLab MCP Tool | Description |
-|-----------|-----------------|-------------|
-| `read` | `read_file` | Read file contents |
-| `write` | `create_file_with_contents` | Create new files |
-| `update` | `update_file` | Modify existing files |
-| `list` | `list_dir` | List directory contents |
-| `search` | `search_files` | Search across codebase |
-| `create-issue` | `create_issue` | Create GitLab issues |
-| `create-mr` | `create_merge_request` | Create merge requests |
-| `comment` | `add_comment` | Add comments to issues/MRs |
-| `shell` | `execute_shell_command` | Execute shell commands |
-
-**Default Tools**: Every agent includes `read_file`, `list_dir`, and `search_files` by default.
-
-## LLM Provider Support
-
-### Anthropic (Claude)
-```yaml
-llm:
-  provider: anthropic
-  model: claude-sonnet-4-20250514
-  # Also supports: claude-opus-4, claude-haiku-3
-```
-
-### OpenAI (GPT)
-```yaml
-llm:
-  provider: openai
-  model: gpt-4o-mini
-  # Also supports: gpt-4o, gpt-4-turbo
-```
-
-### Google Vertex AI (Gemini)
-```yaml
-llm:
-  provider: google
-  model: gemini-1.5-pro
-  # Also supports: gemini-1.5-flash
-```
-
-## Deployment
-
-### 1. Create Flow in GitLab Project
-
-```bash
-# Create the flows directory
-mkdir -p .gitlab/duo/flows
-
-# Copy generated flow
-cp creative-agent-naming-flow.yaml .gitlab/duo/flows/
-
-# Commit and push
-git add .gitlab/duo/flows/creative-agent-naming-flow.yaml
-git commit -m "feat: add code review agent flow"
-git push
-```
-
-### 2. Enable in GitLab Duo
-
-1. Navigate to your project in GitLab
-2. Go to **Settings** → **Duo** → **Flows**
-3. Your flow should appear in the list
-4. Enable the flow
-5. Configure triggers (comments, schedules, webhooks)
-
-### 3. Test the Flow
-
-```bash
-# Trigger via comment in MR
-@creative-agent-naming-flow review this code
-
-# Or use GitLab Duo Chat
-/duo ask creative-agent-naming-flow to analyze this merge request
-```
-
-## Advanced Configuration
-
-### Multi-Turn Conversations
-
-Flows automatically support conversation history via the `placeholder: history` field:
-
-```yaml
-prompt_template:
-  system: "You are a helpful assistant"
-  user: "{{task}}"
-  placeholder: history  # Enables multi-turn
-```
-
-### Custom Timeouts
-
-Adjust execution timeout based on task complexity:
-
-```yaml
-params:
-  timeout: 300  # 5 minutes for complex tasks
-```
-
-### UI Events
-
-Control what gets logged to the GitLab UI:
-
-```yaml
-ui_log_events:
-  - on_agent_final_answer      # Show final response
-  - on_tool_execution_success  # Show successful tool calls
-  - on_tool_execution_failed   # Show failed tool calls
-  - on_llm_start              # Show LLM invocation start
-  - on_llm_end                # Show LLM completion
-```
-
-## Examples
-
-### Code Review Agent
-See: `code-review-flow.yaml`
-- **Environment**: chat (supervised)
-- **Tools**: read_file, search_files, add_comment
-- **Use Case**: Interactive MR reviews
-
-### Security Scanner Agent
-```yaml
-environment: ambient  # Autonomous, hands-off
-components:
-  - name: security_scanner
-    type: AgentComponent
-    toolset:
-      - read_file
-      - search_files
-      - create_issue
-```
-**Use Case**: Scheduled security scans, automated issue creation
-
-### Documentation Helper
-```yaml
-environment: chat-partial  # Simple Q&A
-autonomy:
-  maxTurns: 1
-tools: []  # No tools needed
-```
-**Use Case**: Quick documentation lookups
-
-## Troubleshooting
-
-### Flow Not Appearing in GitLab
-
-**Check**:
-- Flow file is in `.gitlab/duo/flows/` directory
-- YAML is valid (run `yamllint`)
-- Flow follows v1 specification
-- Project has GitLab Duo enabled
-
-### Agent Not Responding
-
-**Check**:
-- Triggers are configured correctly
-- AI Gateway token is valid
-- Model name is correct for provider
-- Toolset includes required tools
-
-### Permission Errors
-
-**Check**:
-- Agent has GitLab API access
-- User mentioning agent has permissions
-- Project has Duo agent execution enabled
-
-## Resources
-
-- **GitLab Duo Agent Platform**: https://docs.gitlab.com/user/duo_agent_platform/
-- **Flow Registry v1 Spec**: https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/-/blob/main/docs/flow_registry/v1.md
-- **OSSA Specification**: https://openstandardagents.org/
-- **MCP Tools Reference**: https://docs.gitlab.com/user/duo_agent_platform/tools/
-
-## Contributing
-
-Improvements to the GitLab Duo export generator are welcome! Key areas:
-
-1. **Router Generation**: Support complex multi-agent workflows
-2. **Tool Mapping**: Add more OSSA → GitLab MCP tool mappings
-3. **External Agent**: Generate External Agent configurations
-4. **Trigger Config**: Automatic trigger configuration generation
-
-See: `src/adapters/gitlab/flow-generator.ts`

package/examples/gitlab-duo/code-review-flow.yaml

@@ -1,62 +0,0 @@
-# GitLab Duo Flow - Code Review Agent
-# Generated from OSSA manifest using GitLabDuoFlowGenerator
-
-version: v1
-environment: chat
-name: code-review-agent
-description: AI-powered code review assistant for merge requests
-product_group: agent_foundations
-
-components:
-  - name: code_review_agent
-    type: AgentComponent
-    prompt_id: code_review_agent_prompt
-    prompt_version: null
-    inputs:
-      - from: context:goal
-        as: task
-    toolset:
-      - read_file
-      - list_dir
-      - search_files
-      - add_comment
-    ui_log_events:
-      - on_agent_final_answer
-      - on_tool_execution_success
-      - on_tool_execution_failed
-    ui_role_as: agent
-
-routers:
-  - from: code_review_agent
-    to: end
-
-prompts:
-  - prompt_id: code_review_agent_prompt
-    name: Code Review Agent System Prompt
-    model:
-      params:
-        model_class_provider: anthropic
-        model: claude-sonnet-4-20250514
-        max_tokens: 4096
-        temperature: 0.7
-    unit_primitives: []
-    prompt_template:
-      system: >
-        You are an expert code reviewer with deep knowledge of software engineering best practices,
-        security vulnerabilities, and performance optimization. Your role is to:
-
-        1. Review code changes for bugs, security issues, and potential improvements
-        2. Provide constructive, actionable feedback
-        3. Suggest specific code improvements with examples
-        4. Highlight positive aspects of the code
-        5. Check for adherence to coding standards and best practices
-
-        Always be respectful, educational, and focused on helping developers improve their code.
-      user: "{{task}}"
-      placeholder: history
-    params:
-      timeout: 180
-      stop: []
-
-flow:
-  entry_point: code_review_agent

package/examples/gitlab-duo/external-agent-example.ts

@@ -1,192 +0,0 @@
-/**
- * Example: GitLab Duo External Agent Generation
- *
- * Demonstrates generating external agent YAML configurations from OSSA manifests.
- * External agents run in GitLab CI/CD pipelines and use AI Gateway for model access.
- */
-
-import { ExternalAgentGenerator } from '../../src/adapters/gitlab/external-agent-generator.js';
-import type { OssaAgent } from '../../src/types/index.js';
-import { writeFileSync } from 'fs';
-import { join } from 'path';
-
-const generator = new ExternalAgentGenerator();
-
-// Example 1: Node.js webhook agent with AI Gateway
-const webhookAgent: OssaAgent = {
-  apiVersion: 'ossa/v0.4.4',
-  kind: 'Agent',
-  metadata: {
-    name: 'mr-reviewer',
-    version: '1.0.0',
-    description: 'Comprehensive MR review agent with AI Gateway integration',
-  },
-  spec: {
-    role: 'You are an expert code reviewer',
-    llm: {
-      provider: 'anthropic',
-      model: 'claude-sonnet-4-20250514',
-      temperature: 0.2,
-      maxTokens: 16384,
-    },
-    runtime: {
-      type: 'webhook',
-      port: 9090,
-      path: '/webhook/mr-reviewer',
-    },
-    workflow: {
-      steps: [
-        {
-          id: 'fetch-changes',
-          action: 'tool-invoke',
-          tool: 'getMRChanges',
-          params: {
-            projectId: '${PROJECT_ID}',
-            mrIid: '${MR_IID}',
-          },
-        },
-      ],
-    },
-    tools: [
-      { name: 'getMRChanges', description: 'Get MR changes' },
-      { name: 'postMRComment', description: 'Post review comment' },
-    ],
-  },
-};
-
-// Example 2: Python agent with custom image
-const pythonAgent: OssaAgent = {
-  apiVersion: 'ossa/v0.4.4',
-  kind: 'Agent',
-  metadata: {
-    name: 'data-analyzer',
-    version: '1.0.0',
-    description: 'Python-based data analysis agent',
-  },
-  spec: {
-    role: 'You are a data analysis expert',
-    llm: {
-      provider: 'openai',
-      model: 'gpt-4o',
-      temperature: 0.5,
-      maxTokens: 8192,
-    },
-    runtime: {
-      type: 'python',
-    },
-    tools: [],
-  },
-};
-
-// Example 3: Go agent with custom commands
-const goAgent: OssaAgent = {
-  apiVersion: 'ossa/v0.4.4',
-  kind: 'Agent',
-  metadata: {
-    name: 'security-scanner',
-    version: '1.0.0',
-    description: 'Go-based security scanner',
-  },
-  spec: {
-    role: 'You are a security expert',
-    llm: {
-      provider: 'anthropic',
-      model: 'claude-sonnet-4-20250514',
-    },
-    runtime: {
-      type: 'go',
-      command: ['go build -o scanner .', './scanner --mode=full'],
-    },
-    tools: [],
-  },
-};
-
-// Example 4: Agent with custom variables
-const customVarsAgent: OssaAgent = {
-  apiVersion: 'ossa/v0.4.4',
-  kind: 'Agent',
-  metadata: {
-    name: 'deployment-agent',
-    version: '1.0.0',
-    description: 'Deployment automation agent with custom variables',
-  },
-  spec: {
-    role: 'You are a deployment expert',
-    llm: {
-      provider: 'anthropic',
-      model: 'claude-sonnet-4-20250514',
-    },
-    tools: [
-      {
-        name: 'deploy-service',
-        auth: {
-          type: 'bearer',
-          credentials: 'DEPLOY_TOKEN',
-        },
-      },
-    ],
-  },
-  extensions: {
-    gitlab: {
-      variables: ['KUBERNETES_CONTEXT', 'HELM_VERSION'],
-    },
-  },
-};
-
-// Generate external agent configurations
-console.log('='.repeat(80));
-console.log('GitLab Duo External Agent Generator - Examples');
-console.log('='.repeat(80));
-console.log();
-
-const examples = [
-  { name: 'webhook-agent', manifest: webhookAgent },
-  { name: 'python-agent', manifest: pythonAgent },
-  { name: 'go-agent', manifest: goAgent },
-  { name: 'custom-vars-agent', manifest: customVarsAgent },
-];
-
-for (const { name, manifest } of examples) {
-  console.log(`\n${'='.repeat(80)}`);
-  console.log(`Example: ${name}`);
-  console.log('='.repeat(80));
-
-  const result = generator.generate(manifest);
-
-  if (!result.success) {
-    console.error(`ERROR: ${result.error}`);
-    continue;
-  }
-
-  console.log('\nConfiguration:');
-  console.log(JSON.stringify(result.config, null, 2));
-
-  console.log('\nGenerated YAML:');
-  console.log(result.yaml);
-
-  // Optionally save to file
-  const outputPath = join(
-    process.cwd(),
-    'examples/gitlab-duo/generated',
-    `${name}.yaml`
-  );
-  try {
-    writeFileSync(outputPath, result.yaml!);
-    console.log(`\n✓ Saved to: ${outputPath}`);
-  } catch (error) {
-    console.log(`\n✗ Could not save to: ${outputPath}`);
-  }
-}
-
-console.log('\n' + '='.repeat(80));
-console.log('External Agent Generation Complete');
-console.log('='.repeat(80));
-console.log();
-console.log('Next steps:');
-console.log('1. Register agent: glab duo agent register <agent-name>.yaml');
-console.log('2. Test agent: glab duo agent test <agent-name>');
-console.log('3. Deploy agent: Agent runs in GitLab CI/CD when triggered');
-console.log();
-console.log('Documentation:');
-console.log('https://docs.gitlab.com/ee/user/gitlab_duo/external_agents.html');
-console.log();

package/examples/gitlab-duo/generated/custom-vars-agent.yaml

@@ -1,45 +0,0 @@
-# GitLab Duo External Agent Configuration
-# Agent: deployment-agent
-# Generated from OSSA manifest v1.0.0
-
-# External agents run in GitLab CI/CD pipelines and use AI Gateway
-# for model access. This YAML defines the agent execution environment.
-
-name: deployment-agent
-description: Deployment automation agent with custom variables
-
-# Docker image for agent execution
-image: node:22-slim
-
-# Commands to execute agent
-commands:
-  - npm ci
-  - npm run build
-  - node dist/index.js
-
-# Environment variables required by agent
-variables:
-  - AI_FLOW_CONTEXT
-  - AI_FLOW_EVENT
-  - AI_FLOW_INPUT
-  - DEPLOY_TOKEN
-  - GITLAB_HOST
-  - GITLAB_TOKEN
-  - HELM_VERSION
-  - KUBERNETES_CONTEXT
-
-# Inject AI Gateway token for model access
-injectGatewayToken: true
-
-# LLM configuration for AI Gateway
-llm:
-  provider: anthropic
-  model: claude-sonnet-4-20250514
-
-# Usage:
-# 1. Register agent: glab duo agent register external-agent.yaml
-# 2. Test agent: glab duo agent test deployment-agent
-# 3. Deploy agent: Agent runs in GitLab CI/CD when triggered
-
-# Documentation:
-# https://docs.gitlab.com/ee/user/gitlab_duo/external_agents.html

package/examples/gitlab-duo/generated/go-agent.yaml

@@ -1,41 +0,0 @@
-# GitLab Duo External Agent Configuration
-# Agent: security-scanner
-# Generated from OSSA manifest v1.0.0
-
-# External agents run in GitLab CI/CD pipelines and use AI Gateway
-# for model access. This YAML defines the agent execution environment.
-
-name: security-scanner
-description: Go-based security scanner
-
-# Docker image for agent execution
-image: golang:1.22-alpine
-
-# Commands to execute agent
-commands:
-  - go build -o scanner .
-  - ./scanner --mode=full
-
-# Environment variables required by agent
-variables:
-  - AI_FLOW_CONTEXT
-  - AI_FLOW_EVENT
-  - AI_FLOW_INPUT
-  - GITLAB_HOST
-  - GITLAB_TOKEN
-
-# Inject AI Gateway token for model access
-injectGatewayToken: true
-
-# LLM configuration for AI Gateway
-llm:
-  provider: anthropic
-  model: claude-sonnet-4-20250514
-
-# Usage:
-# 1. Register agent: glab duo agent register external-agent.yaml
-# 2. Test agent: glab duo agent test security-scanner
-# 3. Deploy agent: Agent runs in GitLab CI/CD when triggered
-
-# Documentation:
-# https://docs.gitlab.com/ee/user/gitlab_duo/external_agents.html

package/examples/gitlab-duo/generated/python-agent.yaml

@@ -1,43 +0,0 @@
-# GitLab Duo External Agent Configuration
-# Agent: data-analyzer
-# Generated from OSSA manifest v1.0.0
-
-# External agents run in GitLab CI/CD pipelines and use AI Gateway
-# for model access. This YAML defines the agent execution environment.
-
-name: data-analyzer
-description: Python-based data analysis agent
-
-# Docker image for agent execution
-image: python:3.12-slim
-
-# Commands to execute agent
-commands:
-  - pip install --no-cache-dir -r requirements.txt
-  - python main.py
-
-# Environment variables required by agent
-variables:
-  - AI_FLOW_CONTEXT
-  - AI_FLOW_EVENT
-  - AI_FLOW_INPUT
-  - GITLAB_HOST
-  - GITLAB_TOKEN
-
-# Inject AI Gateway token for model access
-injectGatewayToken: true
-
-# LLM configuration for AI Gateway
-llm:
-  provider: openai
-  model: gpt-4o
-  temperature: 0.5
-  max_tokens: 8192
-
-# Usage:
-# 1. Register agent: glab duo agent register external-agent.yaml
-# 2. Test agent: glab duo agent test data-analyzer
-# 3. Deploy agent: Agent runs in GitLab CI/CD when triggered
-
-# Documentation:
-# https://docs.gitlab.com/ee/user/gitlab_duo/external_agents.html