Skip to content

v0.2.9

Choose a tag to compare

View all tags
@flux423 flux423 released this 06 Dec 02:20
· 2220 commits to main since this release
v0.2.9
4f340ce

Release Date: December 5, 2025
Milestone: v0.2.9 - Stability & Polish

🎯 Overview

Version 0.2.9 is a major stability and feature release that transforms OSSA from a specification into a complete agent development platform. This release introduces foundational AI capabilities (reasoning, prompts, knowledge graphs), comprehensive specification documentation, enterprise-grade CI/CD automation, and critical security fixes.

✨ New Features

Core Specification Enhancements

1. Reasoning Strategies (spec.reasoning) - #107

Declarative configuration for agent reasoning patterns with full observability.

  • Strategy Selection: ReAct, Chain of Thought (CoT), Tree of Thought (ToT), and custom strategies
  • Controlled Reasoning: Configurable step and depth limits to prevent runaway reasoning
  • Observability: Export reasoning traces to OTEL, JSON, or Markdown formats
  • Self-Reflection: Built-in confidence thresholds for agent self-assessment
spec:
  reasoning:
    strategy: "react"
    max_steps: 10
    trace_export: "otel"
    self_reflection:
      enabled: true
      confidence_threshold: 0.8

2. Prompt Management (spec.prompts) - #108

Structured prompt templating and versioning system for reproducible agent behavior.

  • Template System: System and user prompt templates with file references
  • Versioning: Semantic versioning support for A/B testing and rollback
  • Variable Interpolation: Dynamic template variable substitution
  • Few-Shot Learning: Support for up to 20 examples per prompt
  • Registry Integration: Connect to external prompt registries (Langfuse, PromptLayer)
spec:
  prompts:
    system:
      template: "file://prompts/system.txt"
      version: "1.2.0"
    user:
      template: "You are {{role}} helping with {{task}}"
      variables:
        role: "assistant"
        task: "code review"

3. Knowledge Graph Integration (spec.knowledge_graph) - #109

Native graph database support for structured knowledge representation.

  • Multi-Provider Support: Neo4j, Neptune, Dgraph, Memgraph, and custom providers
  • Secure Connections: Credential references for secure database access
  • Schema Constraints: Define entity and relationship types
  • Flexible Sync: Real-time, batch, or on-demand synchronization modes
spec:
  knowledge_graph:
    provider: "neo4j"
    connection:
      uri: "bolt://localhost:7687"
      credentials_ref: "neo4j-creds"
    sync_mode: "real-time"

4. Identity & Observability - #100, #101

Critical additions for production agent debugging and tracing.

  • Identity Block (spec.identity): Instance ID, session ID, and interaction ID generation
  • OpenTelemetry Semantic Conventions: Standard attributes for agent tracing
    • ossa.agent.id, ossa.agent.name, ossa.agent.version
    • ossa.session.id, ossa.interaction.id, ossa.turn.number
    • ossa.capability.name, ossa.tool.name, ossa.state.mode
spec:
  identity:
    instance_id:
      generation: uuid_v4
      scope: pod
    interaction_id:
      generation: uuid_v4
      scope: turn

Specification Documentation - #110, #111, #112, #113, #114

Complete formal specifications for OSSA's core concepts:

Agent-to-Agent (A2A) Protocol - #110

  • Message envelope JSON Schema
  • AgentCard discovery mechanism
  • Authentication requirements (mTLS, Bearer tokens, OIDC)
  • Routing patterns: Direct, Broadcast, Topic, Request/Response
  • Task lifecycle: submitted → accepted → working → completed/failed/cancelled

Capability Schema & Registry - #111

  • Capability URI scheme: ossa:<domain>/<capability>@<version>
  • Standard capability domains: security, content, code, a2a, state, observability
  • Capability definition schema with input/output contracts
  • MCP binding specification
  • Versioning and deprecation policy

Security Model - #112

  • Agent identity and attestation (X.509, JWT, SPIFFE)
  • Authorization models: RBAC, ABAC, ReBAC
  • Secrets management (Vault, K8s secrets, environment variables)
  • Sandboxing requirements (process, container, VM isolation)
  • Audit logging format (OpenTelemetry compatible)

Conformance Testing - #113

  • Three conformance levels: Basic, Standard, Enterprise
  • CLI validation commands: ossa validate --level=standard
  • Test fixture library for validation
  • Certification badge specification
  • CI/CD integration guide

Agent Manifest Specification - #114

  • Complete narrative documentation for OSSA manifest format
  • Field-by-field explanations with best practices
  • 5+ complete examples (minimal worker, production orchestrator, security-hardened)
  • Anti-patterns to avoid
  • Migration guide from v0.2.8

Extensions

agents.md Extension - #91

Support for OpenAI's repository-level agent guidance format (20,000+ OSS projects).

  • Auto-generate AGENTS.md from OSSA manifests
  • Bidirectional mapping: OSSA ↔ agents.md
  • CLI commands: ossa agents-md generate|validate|sync
  • Integration with Cursor extension
extensions:
  agents_md:
    enabled: true
    generate: true
    output_path: "AGENTS.md"
    sections:
      dev_environment:
        enabled: true
      testing:
        enabled: true
      pr_instructions:
        enabled: true

🔧 CI/CD & Automation Improvements

Release Automation - #92, #93, #94, #116

Merge Trains - #92

  • Enabled GitLab Merge Trains for protected branches
  • Eliminates branch divergence and sync chaos
  • Auto-rebase on target branch updates
  • Merged result pipeline validation

GitLab Releases - #93

  • Auto-create GitLab Release objects on npm publish
  • Release notes auto-generated from milestone issues
  • Asset links: npm package, JSON schema
  • Milestone linking

Main↔Development Sync - #94

  • Automated sync of main → development post-release
  • Prevents branch divergence
  • Auto-creates sync MR or direct merge
  • Eliminates manual sync commits

Milestone-Driven Release Process - #116

  • Check ACTIVE milestone (not closed) for release readiness
  • Post-release cleanup: tag issues/MRs, close milestone, create next milestone
  • Zero human intervention required
  • Enforces Closes #XXX pattern in MRs

🔒 Security Fixes

Critical: Deserialization Vulnerability - #97

  • Severity: Critical (CWE-502)
  • Issue: User-controlled data in yaml.load() could result in Remote Code Injection
  • Location: scripts/generate-agents-catalog.ts:26
  • Fix: Replaced unsafe yaml.load() with safe parsing
  • Scanner: Semgrep (NodeJS Scan)

🐛 Bug Fixes & Improvements

Pipeline Fixes - #118

  • Fixed undefined CI variable ${AGENT_PLATFORM_GROUP} causing stuck pipelines
  • Replaced with ${AGENT_PLATFORM_PROJECT} across all trigger jobs
  • Resolved 3+ day pipeline hang on tag v0.2.8

Git Workflow - #95

  • Configured squash merge as default for feature branches
  • Cleaner git history with one commit per feature
  • Squash commit template for consistent messages

Test Infrastructure - #90

  • Full agent flow verification tests
  • Webhook-triggered issue-triage agent validation
  • OSSA manifest validation in CI

📚 Documentation

New Documentation

  • spec/v0.2.9/agent.md - Complete agent manifest specification
  • spec/v0.2.9/a2a-protocol.md - Agent-to-Agent protocol
  • spec/v0.2.9/capability-schema.md - Capability registry specification
  • spec/v0.2.9/security-model.md - Security and compliance model
  • spec/v0.2.9/conformance-testing.md - Conformance levels and testing
  • spec/v0.2.9/semantic-conventions.md - OpenTelemetry conventions
  • examples/advanced/reasoning-agent.yaml - Demonstrates all v0.2.9 features

Updated Documentation

  • README.md with v0.2.9 version references
  • CHANGELOG.md with complete v0.2.9 entry
  • Migration guide from v0.2.8

🔄 Migration Guide

This is a backward-compatible release. All v0.2.8 manifests will continue to work without modification.

Adopting New Features

# Add reasoning strategies
spec:
  reasoning:
    strategy: "react"
    max_steps: 10

# Add prompt management
spec:
  prompts:
    system:
      template: "file://prompts/system.txt"
      version: "1.0.0"

# Add knowledge graph
spec:
  knowledge_graph:
    provider: "neo4j"
    connection:
      endpoint: "bolt://localhost:7687"

# Add identity tracking
spec:
  identity:
    instance_id:
      generation: uuid_v4
      scope: pod

Breaking Changes

None - This is a fully backward-compatible release.

📦 Package Updates

  • Version: 0.2.9
  • Schema: ./spec/v0.2.9/ossa-0.2.9.schema.json
  • npm Package: @bluefly/openstandardagents@0.2.9
  • TypeScript Types: Updated for all new features
  • Validation Service: Updated to v0.2.9 schema

🔗 Issues Closed

Specification & Schema (P0):

  • #107 - Reasoning strategies block (ReAct, CoT, ToT)
  • #108 - Prompt templates and versioning block
  • #109 - Knowledge graph integration block
  • #100 - Identity block with instance_id and interaction_id
  • #101 - OpenTelemetry semantic conventions
  • #110 - Agent-to-Agent Protocol specification
  • #111 - Capability Schema and Registry specification
  • #112 - Security Model specification
  • #113 - Conformance Testing specification
  • #114 - Agent Manifest specification (agent.md)

Extensions (P1):

  • #91 - OpenAI agents.md extension

CI/CD & Automation (P1-P2):

  • #92 - Enable GitLab Merge Trains
  • #93 - Create GitLab Releases with changelog
  • #94 - Automate main→development sync
  • #95 - Configure squash merge as default
  • #116 - Redesign release process (milestone-driven)

Security (Critical):

  • #97 - Fix deserialization vulnerability (CWE-502)

Bug Fixes:

  • #118 - Pipeline audit and CI variable fixes
  • #90 - Full agent flow verification tests

Release Management:

  • #119 - Release v0.2.9 tracking issue

🚀 Getting Started

Installation

npm install @bluefly/openstandardagents@0.2.9

Validate Your Agents

# Basic validation
ossa validate my-agent.ossa.yaml

# Standard conformance
ossa validate my-agent.ossa.yaml --level=standard

# Enterprise conformance
ossa validate my-agent.ossa.yaml --level=enterprise

Generate agents.md

ossa agents-md generate --manifest .agents/my-agent/manifest.yaml

📊 Statistics

  • Issues Closed: 18
  • Merge Requests: 20+
  • New Specifications: 5 (A2A, Capability, Security, Conformance, Manifest)
  • New Schema Blocks: 4 (reasoning, prompts, knowledge_graph, identity)
  • Security Fixes: 1 critical vulnerability
  • Documentation Pages: 7 new specification documents

🎯 What's Next?

Looking ahead to v0.3.0, we're exploring:

  • Multi-agent orchestration patterns
  • Enhanced security and compliance features
  • Performance optimization tooling
  • Runtime SDK implementation
  • Production deployment guides

🙏 Acknowledgments

Special thanks to all who have commented and promoted OssA.And to bluefly, who made this release possible through issue reports, code contributions, and specification feedback.

Full Changelog: CHANGELOG.md
Milestone: v0.2.9 - Stability & Polish
Release: GitLab Release

Assets 2
Loading