@bluefly/openstandardagents 0.2.9 → 0.3.0

package/spec/schema/components/llm-config.schema.json

@@ -0,0 +1,67 @@
+{
+  "$id": "https://ossa.dev/schema/components/llm-config.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "OSSA LLM Configuration Component",
+  "description": "Reusable LLM configuration for OSSA agents",
+  "type": "object",
+  "properties": {
+    "provider": {
+      "type": "string",
+      "enum": ["openai", "anthropic", "google", "azure", "bedrock", "ollama", "custom"],
+      "description": "LLM provider"
+    },
+    "model": {
+      "type": "string",
+      "description": "Model identifier"
+    },
+    "temperature": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 2,
+      "description": "Sampling temperature"
+    },
+    "maxTokens": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Maximum tokens in response"
+    },
+    "topP": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Top-p (nucleus) sampling"
+    },
+    "frequencyPenalty": {
+      "type": "number",
+      "minimum": -2,
+      "maximum": 2,
+      "description": "Frequency penalty for repetition"
+    },
+    "presencePenalty": {
+      "type": "number",
+      "minimum": -2,
+      "maximum": 2,
+      "description": "Presence penalty for topic diversity"
+    },
+    "stopSequences": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Stop sequences to end generation"
+    },
+    "responseFormat": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["text", "json_object", "json_schema"]
+        },
+        "schema": {
+          "type": "object",
+          "description": "JSON Schema for structured output"
+        }
+      }
+    }
+  },
+  "required": ["provider", "model"],
+  "additionalProperties": false
+}

package/spec/schema/components/metadata.schema.json

@@ -0,0 +1,37 @@
+{
+  "$id": "https://ossa.dev/schema/components/metadata.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "OSSA Metadata Component",
+  "description": "Reusable metadata block for OSSA resources",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]*[a-z0-9]$",
+      "maxLength": 63,
+      "description": "DNS-1123 compliant resource name"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9.-]+)?$",
+      "description": "Semantic version string"
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 1024,
+      "description": "Human-readable description"
+    },
+    "labels": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "description": "Key-value labels for categorization"
+    },
+    "annotations": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "description": "Key-value annotations for tooling"
+    }
+  },
+  "required": ["name", "version"],
+  "additionalProperties": false
+}

package/spec/schema/components/tool.schema.json

@@ -0,0 +1,64 @@
+{
+  "$id": "https://ossa.dev/schema/components/tool.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "OSSA Tool Component",
+  "description": "Reusable tool definition for OSSA agents",
+  "type": "object",
+  "properties": {
+    "type": {
+      "type": "string",
+      "enum": ["mcp", "http", "function", "kubernetes"],
+      "description": "Tool integration type"
+    },
+    "name": {
+      "type": "string",
+      "description": "Unique tool identifier"
+    },
+    "description": {
+      "type": "string",
+      "description": "Human-readable tool description"
+    },
+    "server": {
+      "type": "string",
+      "description": "MCP server name (for type: mcp)"
+    },
+    "namespace": {
+      "type": "string",
+      "description": "Tool namespace for grouping"
+    },
+    "endpoint": {
+      "type": "string",
+      "format": "uri",
+      "description": "HTTP endpoint (for type: http)"
+    },
+    "capabilities": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "List of capability identifiers"
+    },
+    "config": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Tool-specific configuration"
+    },
+    "auth": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["none", "bearer", "basic", "api-key", "oauth2"]
+        },
+        "credentials": {
+          "type": "string",
+          "description": "Reference to credentials secret"
+        }
+      }
+    },
+    "input_schema": {
+      "type": "object",
+      "description": "JSON Schema for tool input parameters"
+    }
+  },
+  "required": ["type"],
+  "additionalProperties": false
+}

package/spec/schema/extensions/a2a.extension.schema.json

@@ -0,0 +1,127 @@
+{
+  "$id": "https://ossa.dev/schema/extensions/a2a.extension.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "OSSA A2A Protocol Extension",
+  "description": "Agent-to-Agent protocol support for multi-agent orchestration",
+  "type": "object",
+  "properties": {
+    "enabled": {
+      "type": "boolean",
+      "default": false,
+      "description": "Enable A2A protocol support"
+    },
+    "version": {
+      "type": "string",
+      "enum": ["1.0", "1.1"],
+      "default": "1.0",
+      "description": "A2A protocol version"
+    },
+    "agent_card": {
+      "type": "object",
+      "description": "Agent card for A2A discovery",
+      "properties": {
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "Public URL where agent card is published"
+        },
+        "name": {
+          "type": "string",
+          "description": "Human-readable agent name"
+        },
+        "description": {
+          "type": "string",
+          "description": "Agent description"
+        },
+        "capabilities": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "List of capabilities this agent provides"
+        },
+        "skills": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "List of skills this agent has"
+        },
+        "input_modes": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["text", "audio", "image", "video", "file"]
+          },
+          "description": "Supported input modalities"
+        },
+        "output_modes": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["text", "audio", "image", "video", "file"]
+          },
+          "description": "Supported output modalities"
+        }
+      }
+    },
+    "messaging": {
+      "type": "object",
+      "description": "Messaging configuration",
+      "properties": {
+        "protocol": {
+          "type": "string",
+          "enum": ["http", "grpc", "websocket"],
+          "default": "http",
+          "description": "Transport protocol"
+        },
+        "format": {
+          "type": "string",
+          "enum": ["json-rpc", "protobuf", "json"],
+          "default": "json-rpc",
+          "description": "Message format"
+        },
+        "streaming": {
+          "type": "boolean",
+          "default": false,
+          "description": "Enable streaming responses"
+        }
+      }
+    },
+    "discovery": {
+      "type": "object",
+      "description": "Agent discovery configuration",
+      "properties": {
+        "method": {
+          "type": "string",
+          "enum": ["static", "registry", "broadcast", "dns"],
+          "default": "static",
+          "description": "Discovery method"
+        },
+        "registry_url": {
+          "type": "string",
+          "format": "uri",
+          "description": "Registry URL for agent discovery"
+        },
+        "refresh_interval_seconds": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 300,
+          "description": "Discovery refresh interval"
+        }
+      }
+    },
+    "authentication": {
+      "type": "object",
+      "description": "A2A authentication settings",
+      "properties": {
+        "method": {
+          "type": "string",
+          "enum": ["none", "mtls", "jwt", "api-key"],
+          "default": "none"
+        },
+        "credentials_ref": {
+          "type": "string",
+          "description": "Reference to credentials secret"
+        }
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/spec/v0.2.8/ossa-0.2.8.schema.json

@@ -40,7 +40,7 @@
     },
     "extensions": {
       "type": "object",
-      "description": "Framework-specific extensions for integration with kagent, buildkit, drupal, librechat, mcp, langchain, crewai, openai_agents, cursor, langflow, autogen, vercel_ai, llamaindex, langgraph, anthropic, and other frameworks",
+      "description": "Framework-specific extensions for integration with kagent, buildkit, drupal, librechat, mcp, langchain, crewai, openai_agents, cursor, langflow, autogen, vercel_ai, llamaindex, langgraph, anthropic, agents_md, and other frameworks",
       "properties": {
         "kagent": {
           "$ref": "#/definitions/KAgentExtension"
@@ -92,6 +92,9 @@
         },
         "a2a": {
           "$ref": "#/definitions/A2AExtension"
+        },
+        "agents_md": {
+          "$ref": "#/definitions/AgentsMdExtension"
         }
       },
       "additionalProperties": true
@@ -1672,6 +1675,10 @@
                 "type": "string"
               },
               "description": "Glob patterns to exclude from context"
+            },
+            "agents_md_path": {
+              "type": "string",
+              "description": "Path to AGENTS.md file for Cursor to read (default: AGENTS.md)"
             }
           }
         },
@@ -2406,6 +2413,93 @@
       },
       "additionalProperties": true
     },
+    "AgentsMdSection": {
+      "type": "object",
+      "description": "Configuration for a single agents.md section",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": true,
+          "description": "Whether this section is enabled"
+        },
+        "source": {
+          "type": "string",
+          "description": "OSSA manifest path to derive content from (e.g., 'spec.tools', 'spec.constraints')"
+        },
+        "custom": {
+          "type": "string",
+          "description": "Custom markdown content for this section"
+        },
+        "title_format": {
+          "type": "string",
+          "description": "Format string for section title (supports template variables)"
+        }
+      },
+      "additionalProperties": false
+    },
+    "AgentsMdExtension": {
+      "type": "object",
+      "description": "OpenAI agents.md repository guidance generation extension",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": false,
+          "description": "Enable agents.md generation"
+        },
+        "generate": {
+          "type": "boolean",
+          "default": true,
+          "description": "Auto-generate AGENTS.md from manifest"
+        },
+        "output_path": {
+          "type": "string",
+          "default": "AGENTS.md",
+          "description": "Output path for generated AGENTS.md file"
+        },
+        "sections": {
+          "type": "object",
+          "description": "Configuration for agents.md sections",
+          "properties": {
+            "dev_environment": {
+              "$ref": "#/definitions/AgentsMdSection",
+              "description": "Development environment setup instructions"
+            },
+            "testing": {
+              "$ref": "#/definitions/AgentsMdSection",
+              "description": "Testing instructions and requirements"
+            },
+            "pr_instructions": {
+              "$ref": "#/definitions/AgentsMdSection",
+              "description": "Pull request guidelines and requirements"
+            }
+          },
+          "additionalProperties": false
+        },
+        "sync": {
+          "type": "object",
+          "description": "Synchronization configuration",
+          "properties": {
+            "on_manifest_change": {
+              "type": "boolean",
+              "default": true,
+              "description": "Automatically sync AGENTS.md when manifest changes"
+            },
+            "include_comments": {
+              "type": "boolean",
+              "default": true,
+              "description": "Include explanatory comments in generated AGENTS.md"
+            }
+          },
+          "additionalProperties": false
+        },
+        "cursor_integration": {
+          "type": "boolean",
+          "default": false,
+          "description": "Generate Cursor-compatible content in AGENTS.md"
+        }
+      },
+      "additionalProperties": true
+    },
     "Security": {
       "type": "object",
       "description": "Security configuration for agent operations",

package/spec/v0.3.0/UNIFIED-SCHEMA.md

@@ -0,0 +1,120 @@
+# OSSA v0.3.0 - Unified Agent Schema
+
+## The Rocketship 🚀
+
+This schema unifies OSSA, GitLab Duo, Google A2A, and MCP into a single universal agent platform.
+
+### What Changed
+
+**Before (v0.2.x):**
+```yaml
+llm:
+  provider: anthropic
+  model: claude-sonnet-4-20250514
+```
+
+**After (v0.3.0):**
+```yaml
+llm:
+  provider: ${LLM_PROVIDER:-anthropic}
+  model: ${LLM_MODEL:-claude-sonnet}
+  profile: ${LLM_PROFILE:-balanced}
+  fallback_models:
+    - provider: ${LLM_FALLBACK_PROVIDER_1:-openai}
+      model: ${LLM_FALLBACK_MODEL_1:-gpt-4o}
+```
+
+### Key Features
+
+1. **Zero Hardcoded Models** - All LLM config is runtime-configurable
+2. **Execution Profiles** - Google A2A compatible (fast/balanced/deep/safe)
+3. **Multi-Runtime Support** - Works with Duo, A2A, OSSA, MCP
+4. **Fallback Models** - Multi-provider resilience
+5. **Structured Functions** - A2A/OpenAI function calling format
+6. **Extensions** - Pluggable external behaviors
+
+### Compatibility Matrix
+
+| Feature | OSSA v0.2.x | Duo | A2A | v0.3.0 |
+|---------|-------------|-----|-----|--------|
+| Runtime-configurable models | ❌ | ❌ | ✅ | ✅ |
+| Execution profiles | ❌ | ❌ | ✅ | ✅ |
+| Multi-provider fallback | partial | ❌ | ✅ | ✅ |
+| Structured functions | ❌ | partial | ✅ | ✅ |
+| Extensions | partial | partial | ✅ | ✅ |
+
+### Migration
+
+```bash
+# Auto-migrate all agents
+./scripts/migrate-to-unified-llm.sh
+
+# Generate new agent
+./scripts/generate-agent.sh my-agent worker
+
+# Validate
+ossa validate examples/
+```
+
+### Environment Variables
+
+```bash
+# Primary LLM
+export LLM_PROVIDER=anthropic
+export LLM_MODEL=claude-sonnet-4
+export LLM_PROFILE=balanced
+
+# Fallbacks
+export LLM_FALLBACK_PROVIDER_1=openai
+export LLM_FALLBACK_MODEL_1=gpt-4o
+
+# Runtime
+export AGENT_RUNTIME=unified
+export AGENT_SCHEDULING=fair
+export AGENT_PRIORITY=normal
+```
+
+### Execution Profiles
+
+- **fast** - Quick responses (4K tokens, temp=0.0)
+- **balanced** - General ops (16K tokens, temp=0.1)
+- **deep** - Analysis (32K tokens, temp=0.2, reasoning enabled)
+- **safe** - Compliance (temp=0.0, validation required)
+
+### CI Enforcement
+
+Add to `.gitlab-ci.yml`:
+
+```yaml
+include:
+  - local: .gitlab/ci/validate-no-hardcoded-models.yml
+```
+
+This blocks any MR with hardcoded model names.
+
+### Example Agent
+
+See: `examples/unified/security-scanner.ossa.yaml`
+
+### Schema Files
+
+- `schemas/unified-llm.yaml` - LLM configuration
+- `schemas/runtime.yaml` - Runtime declaration
+- `schemas/capabilities.yaml` - Capability definitions
+- `schemas/functions.yaml` - Function declarations
+- `schemas/agent-unified.yaml` - Complete agent schema
+
+### Why This Matters
+
+1. **No More Breaking Changes** - Model updates don't require code changes
+2. **Multi-Provider** - Switch between Anthropic/OpenAI/Google/Groq instantly
+3. **Future-Proof** - New runtimes (A2A, Duo) work without modification
+4. **Cost Optimization** - Use cheap models for triage, expensive for analysis
+5. **Compliance** - Audit trail of which models were used when
+
+### Next Steps
+
+1. Run migration: `./scripts/migrate-to-unified-llm.sh`
+2. Update CI: Add validation rule
+3. Test: `ossa validate examples/`
+4. Deploy: Agents auto-detect runtime