@bluefly/openstandardagents 0.4.2 → 0.4.4

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

@@ -0,0 +1,52 @@
+# GitLab Duo External Agent Configuration
+# Agent: mr-reviewer
+# 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: mr-reviewer
+description: Comprehensive MR review agent with AI Gateway integration
+
+# 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
+  - GITLAB_HOST
+  - GITLAB_TOKEN
+  - MR_IID
+  - PROJECT_ID
+
+# Inject AI Gateway token for model access
+injectGatewayToken: true
+
+# LLM configuration for AI Gateway
+llm:
+  provider: anthropic
+  model: claude-sonnet-4-20250514
+  temperature: 0.2
+  max_tokens: 16384
+
+# Webhook runtime configuration
+runtime:
+  type: webhook
+  port: 9090
+  path: /webhook/mr-reviewer
+
+# Usage:
+# 1. Register agent: glab duo agent register external-agent.yaml
+# 2. Test agent: glab duo agent test mr-reviewer
+# 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/infrastructure/token-rotation/README.md

@@ -0,0 +1,117 @@
+# Token Rotation Pattern - Reference Example
+
+> **Minimal reference** showing OSSA token rotation features. For production implementation, see [platform-agents/token-rotation-manager](https://gitlab.com/blueflyio/agent-platform/platform-agents/-/tree/main/packages/@ossa/token-rotation-manager).
+
+## What This Example Shows
+
+This manifest demonstrates **automated token rotation** using OSSA v0.4.4 features:
+
+### Key Features
+
+**1. Self-Rotation (`self_rotate: true`)**
+- Agent can rotate **its own token**
+- Requires `self_rotate` scope on service account
+- Prevents manual token management
+
+**2. Service Account Management (`manage_service_accounts: []`)**
+- Agent rotates **other service account tokens**
+- Manages multiple accounts (CI, security, content, etc.)
+- Central rotation orchestrator
+
+**3. Automated Refresh (`auto_refresh: true`)**
+- Automatically refreshes tokens before expiry
+- No manual intervention needed
+
+## When to Use This Pattern
+
+✅ **Use when:**
+- Managing 5+ service account tokens
+- Need automated rotation (security compliance)
+- Want zero-downtime rotation
+
+❌ **Don't use when:**
+- Single token (just use `auto_refresh`)
+- Manual token management required
+- No vault/secrets manager
+
+## Configuration
+
+### Rotation Policy
+
+```yaml
+authentication:
+  rotation_policy:
+    enabled: true                # Enable rotation
+    interval_days: 90            # Rotate every 90 days
+    notify_on_rotation: true     # Send notifications
+    manage_service_accounts:     # Accounts to rotate
+      - gitlab_token_webhook_manager
+      - gitlab_token_ci_orchestrator
+```
+
+### Self-Rotation
+
+```yaml
+authentication:
+  self_rotate: true  # Agent rotates its own token
+  scopes:
+    - api
+    - read_user
+    - self_rotate   # ⚠️ Required scope
+```
+
+## API Endpoints (Reference)
+
+Simple rotation API:
+
+```
+POST   /v1/token-rotation/validate    - Validate token scopes
+POST   /v1/token-rotation/rotate      - Rotate token
+POST   /v1/token-rotation/verify      - Verify new token
+GET    /v1/token-rotation/status      - Rotation status
+```
+
+See [`openapi.yaml`](./openapi.yaml) for full spec (minimal reference).
+
+## How It Works
+
+```
+┌─────────────────────────┐
+│  Scheduled Trigger      │
+│  (cron: "0 2 * * 0")    │
+└───────────┬─────────────┘
+            │
+            ▼
+┌─────────────────────────┐
+│  For Each Account:      │
+│  1. Validate current    │
+│  2. Rotate token        │
+│  3. Verify new token    │
+│  4. Update vault        │
+│  5. Notify if enabled   │
+└─────────────────────────┘
+```
+
+## Production Implementation
+
+For a complete, production-ready implementation with:
+- Full error handling
+- Rollback on failure
+- Comprehensive testing
+- CI/CD pipelines
+- Emergency rotation support
+
+See: [`platform-agents/@ossa/token-rotation-manager`](https://gitlab.com/blueflyio/agent-platform/platform-agents/-/tree/main/packages/@ossa/token-rotation-manager)
+
+## Pattern Documentation
+
+For design rationale and best practices, see:
+- [docs/patterns/token-rotation.md](../../docs/patterns/token-rotation.md)
+- [OSSA Agent Type: KAGENT](../../docs/agent-types/kagent.md)
+
+## Compliance
+
+Meets security standards:
+- **NIST 800-63B**: Token rotation requirements
+- **CIS Benchmarks**: Service account management
+- **OWASP**: Token lifecycle security

package/examples/infrastructure/token-rotation/manifest.ossa.yaml

@@ -0,0 +1,73 @@
+apiVersion: ossa/v0.4.4
+kind: Agent
+metadata:
+  name: token-rotation-manager
+  version: 1.0.0
+  description: Reference example for token rotation pattern
+  agentType: kagent
+  agentKind: executor
+  agentArchitecture:
+    pattern: single
+    capabilities:
+      - tools
+      - code
+      - memory
+    coordination:
+      style: autonomous
+      handoffStrategy: none
+    runtime:
+      scalability: single-instance
+      executionModel: batch
+
+spec:
+  role: |
+    Automated service account token rotation manager.
+
+    Rotates GitLab/GitHub service account tokens on schedule,
+    validates new tokens, and updates vault secrets.
+
+  llm:
+    provider: none # KAGENT doesn't need LLM
+
+  tools:
+    - name: validate_token
+      description: Validate a token has required scopes
+
+    - name: rotate_token
+      description: Rotate a service account token
+
+    - name: verify_token
+      description: Verify new token works correctly
+
+    - name: update_vault
+      description: Update Vault secret with new token
+
+  authentication:
+    type: service_account
+    scopes:
+      - api
+      - read_user
+      - write_repository
+    auto_refresh: true
+    self_rotate: true  # ⚠️ Key feature: Agent can rotate its own token
+    rotation_policy:
+      enabled: true
+      interval_days: 90  # Rotate every 90 days
+      notify_on_rotation: true
+      manage_service_accounts:  # ⚠️ Key feature: Manages other accounts
+        - gitlab_token_webhook_manager
+        - gitlab_token_ci_orchestrator
+        - gitlab_token_content_reviewer
+        - gitlab_token_security_scanner
+
+  schedule:
+    cron: "0 2 * * 0"  # Weekly Sunday 2:00 AM UTC
+    timezone: UTC
+
+  observability:
+    logging:
+      level: info
+      format: json
+    monitoring:
+      enabled: true
+      metrics_port: 9090

package/examples/infrastructure/token-rotation/openapi.yaml

@@ -0,0 +1,133 @@
+openapi: 3.1.0
+info:
+  title: Token Rotation Manager API
+  version: 1.0.0
+  description: |
+    Minimal reference API for token rotation pattern.
+
+    For production API, see platform-agents/@ossa/token-rotation-manager/openapi.yaml
+
+servers:
+  - url: https://workflow.blueflyagents.com/v1
+    description: Production
+
+paths:
+  /token-rotation/validate:
+    post:
+      summary: Validate token scopes
+      description: Check if token has required scopes
+      operationId: validateToken
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [token, scopes]
+              properties:
+                token:
+                  type: string
+                  description: Token to validate
+                scopes:
+                  type: array
+                  items:
+                    type: string
+                  description: Required scopes
+      responses:
+        '200':
+          description: Validation result
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  valid:
+                    type: boolean
+                  missingScopes:
+                    type: array
+                    items:
+                      type: string
+
+  /token-rotation/rotate:
+    post:
+      summary: Rotate service account token
+      description: Generate new token for service account
+      operationId: rotateToken
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [serviceAccount]
+              properties:
+                serviceAccount:
+                  type: string
+                  description: Service account name
+      responses:
+        '200':
+          description: New token generated
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  token:
+                    type: string
+                  expiresAt:
+                    type: string
+                    format: date-time
+
+  /token-rotation/verify:
+    post:
+      summary: Verify new token works
+      description: Test new token against API
+      operationId: verifyToken
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [token]
+              properties:
+                token:
+                  type: string
+      responses:
+        '200':
+          description: Token verified
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  valid:
+                    type: boolean
+                  scopes:
+                    type: array
+                    items:
+                      type: string
+
+  /token-rotation/status:
+    get:
+      summary: Get rotation status
+      description: Check when tokens were last rotated
+      operationId: getStatus
+      responses:
+        '200':
+          description: Rotation status
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  lastRotation:
+                    type: string
+                    format: date-time
+                  nextRotation:
+                    type: string
+                    format: date-time
+                  managedAccounts:
+                    type: array
+                    items:
+                      type: string

package/examples/knowledge-graph/drupal-agent-with-kg.ossa.yaml

@@ -0,0 +1,289 @@
+# OSSA v0.4.1 Agent with Knowledge Graph Extension
+# Portable, configurable - works with ANY git platform, vector DB, wiki format
+
+apiVersion: ossa/v0.4.1
+kind: Agent
+
+metadata:
+  name: drupal-content-moderator
+  namespace: mycompany
+  version: 1.0.0
+  description: Drupal content moderation agent with knowledge graph context
+  labels:
+    domain: drupal
+    tier: worker
+    has_knowledge_graph: "true"
+
+spec:
+  role: >
+    Review and moderate Drupal content for quality, security, and compliance.
+    Use knowledge graph to understand content relationships, wiki guidelines,
+    code implementations, and historical issues.
+
+  capabilities:
+    - name: content-analysis
+      description: Analyze content quality and compliance
+
+    - name: security-check
+      description: Check for security issues (XSS, SQL injection, etc.)
+
+    - name: guidelines-compliance
+      description: Verify compliance with wiki guidelines
+
+  tools:
+    - type: api
+      name: query_knowledge_graph
+      description: Query knowledge graph for context
+      input_schema:
+        type: object
+        properties:
+          semantic_query:
+            type: string
+            description: Natural language query
+          entity_types:
+            type: array
+            items:
+              type: string
+            description: Entity types to search
+          filters:
+            type: object
+            description: Filter criteria
+          include_relationships:
+            type: boolean
+            description: Include related entities
+        required: [semantic_query]
+
+  llm:
+    provider: anthropic
+    model: claude-sonnet-4-20250514
+    temperature: 0.3
+    max_tokens: 8192
+
+# =============================================================================
+# Knowledge Graph Extension (PORTABLE, CONFIGURABLE)
+# =============================================================================
+extensions:
+  knowledge_graph:
+    # Enable knowledge graph for this agent
+    enabled: true
+
+    # Data providers (supports ANY platform via env vars)
+    providers:
+      # Git platform (GitLab, GitHub, Gitea, etc.)
+      git:
+        type: gitlab  # or 'github', 'gitea', 'bitbucket'
+        url: ${GITLAB_URL:-https://gitlab.com}
+        token: ${GITLAB_TOKEN}
+        projects: ${GITLAB_PROJECT_IDS}
+        groups: ${GITLAB_GROUP_IDS}
+        api_version: v4
+
+      # Vector database (Qdrant, Pinecone, Weaviate, etc.)
+      vector_db:
+        type: qdrant  # or 'pinecone', 'weaviate', 'milvus'
+        url: ${QDRANT_URL}
+        collection: ${QDRANT_COLLECTION:-drupal-content-moderator-kg}
+        vector_size: 1536
+        distance_metric: cosine
+
+      # Wiki/documentation (Markdown, AsciiDoc, RST, etc.)
+      wiki:
+        type: markdown  # or 'asciidoc', 'rst', 'confluence'
+        path: ${WIKI_PATH}
+        format: md
+        recursive: true
+        exclude_patterns:
+          - node_modules
+          - .git
+          - vendor
+
+      # Source code indexing (optional)
+      codebase:
+        type: multi  # or 'typescript', 'php', 'python'
+        path: ${CODEBASE_PATH}
+        include_patterns:
+          - "**/*.php"
+          - "**/*.module"
+          - "**/*.inc"
+          - "**/*.ts"
+        exclude_patterns:
+          - node_modules
+          - vendor
+          - dist
+        parse_ast: true
+
+    # Entity types to index
+    entities:
+      # GitLab entities
+      - type: issue
+        enabled: true
+        embedding: true
+        filters:
+          labels: ["security", "content", "moderation"]
+
+      - type: merge_request
+        enabled: true
+        embedding: true
+        filters:
+          state: merged
+
+      - type: commit
+        enabled: false  # Skip commits for now
+        embedding: false
+
+      # Wiki entities
+      - type: wiki_page
+        enabled: true
+        embedding: true
+        fields:
+          - title
+          - content
+          - frontmatter
+
+      # Code entities
+      - type: file
+        enabled: true
+        embedding: false  # Don't embed large files
+        filters:
+          extensions: [".php", ".module", ".inc"]
+
+      - type: class
+        enabled: true
+        embedding: true
+
+      - type: function
+        enabled: true
+        embedding: true
+
+    # Relationships to track
+    relationships:
+      # Issue relationships
+      - from: issue
+        to: merge_request
+        type: fixes
+        bidirectional: false
+        extraction:
+          method: api  # GitLab API provides this
+
+      - from: issue
+        to: wiki_page
+        type: documented_by
+        extraction:
+          method: regex
+          pattern: '\[\[([^\]]+)\]\]'  # Wiki links in issue descriptions
+
+      # Wiki relationships
+      - from: wiki_page
+        to: wiki_page
+        type: links_to
+        bidirectional: false
+        extraction:
+          method: regex
+          pattern: '\[([^\]]+)\]\(([^)]+\.md)\)'  # Markdown links
+
+      - from: wiki_page
+        to: issue
+        type: references
+        extraction:
+          method: regex
+          pattern: '#(\d+)'  # Issue references (#123)
+
+      - from: wiki_page
+        to: merge_request
+        type: references
+        extraction:
+          method: regex
+          pattern: '!(\d+)'  # MR references (!456)
+
+      # Code relationships
+      - from: file
+        to: class
+        type: contains
+        extraction:
+          method: ast
+
+      - from: class
+        to: function
+        type: has_method
+        extraction:
+          method: ast
+
+      - from: function
+        to: function
+        type: calls
+        extraction:
+          method: ast
+
+    # Query configuration
+    query_config:
+      max_results: 10
+      similarity_threshold: 0.7
+      include_relationships: true
+      max_depth: 3
+      cache_ttl: 300
+
+    # Indexing configuration
+    indexing:
+      schedule: "0 2 * * *"  # Daily at 2 AM
+      incremental: true
+      batch_size: 100
+      parallel_workers: 4
+
+    # Embedding configuration
+    embeddings:
+      provider: openai  # or 'anthropic', 'cohere', 'local'
+      model: text-embedding-3-small
+      api_key: ${OPENAI_API_KEY}
+      dimensions: 1536
+
+# =============================================================================
+# Example Queries (How Agents Use Knowledge Graph)
+# =============================================================================
+
+# Query 1: Find content moderation guidelines
+# Agent: "What are the content moderation guidelines?"
+# KG Query:
+#   {
+#     semantic_query: "content moderation guidelines policy",
+#     entity_types: ["wiki_page"],
+#     include_relationships: true
+#   }
+# Result: wiki-page-content-policy.md + related issues + related code
+
+# Query 2: Find security vulnerabilities
+# Agent: "Are there known XSS vulnerabilities in the content module?"
+# KG Query:
+#   {
+#     semantic_query: "XSS cross-site scripting content module vulnerability",
+#     entity_types: ["issue", "merge_request", "wiki_page"],
+#     filters: { labels: ["security"] },
+#     include_relationships: true
+#   }
+# Result: issue-234 + mr-567 + wiki-security-guidelines.md + affected code files
+
+# Query 3: Find similar past issues
+# Agent: "Has this content issue been reported before?"
+# KG Query:
+#   {
+#     semantic_query: "spam content detection false positive",
+#     entity_types: ["issue"],
+#     filters: { state: "closed" },
+#     include_relationships: true
+#   }
+# Result: similar issues + their resolutions + related wiki docs
+
+# Query 4: Find code implementation
+# Agent: "How is content validation implemented?"
+# KG Query:
+#   {
+#     semantic_query: "content validation sanitize check",
+#     entity_types: ["function", "class", "file"],
+#     include_relationships: true
+#   }
+# Result: ContentValidator class + validate() function + usage examples
+
+# Query 5: Traverse graph for full context
+# Agent: "Show me the full context for issue #234"
+# KG Graph Traversal:
+#   issue-234 →[fixed_by]→ mr-567 →[modifies]→ file-ContentValidator.php →[contains]→ class-ContentValidator →[has_method]→ function-validate() →[documented_by]→ wiki-content-validation.md
+# Result: Full graph with all relationships