@bluefly/openstandardagents 0.3.5 → 0.3.6

package/spec/v0.3.6/CHANGELOG.md

@@ -0,0 +1,171 @@
+# Changelog
+All notable changes to OSSA will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.6] - 2026-01-23
+### Added
+- **Token Efficiency Framework**: Comprehensive cost optimization with significant token savings
+  - Context Management: Semantic pruning, summarization, and caching strategies
+  - Prompt Caching: Provider-specific caching (Anthropic, OpenAI) with 90% savings on repeated context
+  - Token Budgets: Hard limits with soft/hard/adaptive enforcement
+  - Tool Output Limits: Prevent excessive tool outputs with smart truncation
+  - Knowledge Graph Efficiency: Significant token reduction through structured code indexing
+  - Checkpoint Compression: Delta-based state compression for long-running agents
+- **Composite Identity Support**: GitLab Duo-inspired identity merging (vendor-neutral)
+  - Primary identity (service account) + secondary identity (human user)
+  - Merge strategies: restrictive (intersection), permissive (union), custom
+  - Full attribution and audit trail for compliance
+  - Explicit permission management (read, write, execute)
+- **Agent Catalog Metadata**: Discovery and publication support
+  - Visibility controls: public, private, internal
+  - Categories, tags, and search metadata
+  - Pricing models: free, freemium, paid, enterprise
+  - Ratings and documentation links
+- **Efficiency Tier System**: Declarative optimization levels
+  - Premium: No optimization (full quality)
+  - Standard: Basic pruning (moderate savings)
+  - Economy: Aggressive optimization (maximum savings)
+  - Custom: Explicit configuration
+- **Knowledge Graph Integration**: MCP-based codebase understanding
+  - Provider-agnostic (GitLab, GitHub, local, custom)
+  - Index types: files, classes, functions, dependencies, relationships
+  - Query capabilities: semantic search, dependency traversal, code navigation
+  - Significant token reduction vs full codebase inclusion
+- **Version-Specific Schema Naming**: Schema files now use version-specific names (ossa-{version}.schema.json)
+
+### Changed
+- **Schema Naming Convention**: Changed from `ossa-agent.schema.json` to `ossa-0.3.6.schema.json` for website compatibility
+- **Specification**: Updated to v0.3.6 with token efficiency and enterprise features
+- **Package Version**: Bumped to 0.3.6 in package.json and .version.json
+- **Backward Compatibility**: All v0.3.5 agents work with v0.3.6 runtime (100% backward compatible)
+
+### Fixed
+- **Website Integration**: Ensured schema naming matches website validator expectations
+- **Example Validation**: Fixed YAML formatting issues in examples (removed document separators, fixed numeric formats)
+
+## [0.3.5] - 2026-01-15
+### Added
+- **Completion Signals**: Standardized agent termination conditions enabling intelligent workflow orchestration
+- **Session Checkpointing**: Resilient, resumable agent state for long-running tasks and cost optimization
+- **Mixture of Experts (MoE)**: Agent-controlled expert model selection for intelligent routing and cost optimization
+- **BAT Framework**: Best Available Technology selection with multi-dimensional criteria
+- **MOE Metrics**: Measure of Effectiveness framework with primary, secondary, and operational categories
+- **Flow-Based Orchestration**: Native Flow kind support with state machines and transitions (100% compatibility with LangGraph, Temporal, n8n)
+- **Dynamic Capability Discovery**: Runtime-adaptive capabilities with automatic refresh
+- **Feedback & Learning Loops**: Continuous improvement with native feedback tools and learning strategies
+- **Infrastructure Substrate**: Infrastructure as agent-addressable resources for infrastructure-aware deployment
+- **Enhanced A2A Protocol**: Production-ready agent-to-agent communication with completion signals and checkpoint sync
+
+### Changed
+- **Specification**: Updated to v0.3.5 - The OpenAPI for Software Agents
+- **Enterprise Focus**: Refocused all documentation on enterprise adoption and business value
+- **README**: Complete rewrite emphasizing vendor neutrality, cost optimization, and production reliability
+- **Documentation**: Updated all docs (README, llms.txt, CONTRIBUTING) to remove GitLab references, focus on GitHub (public mirror)
+- **Backward Compatibility**: All v0.3.4 agents work with v0.3.5 runtime (100% backward compatible)
+- **Migration Guide**: Complete migration guide available in `spec/v0.3/MIGRATION-v0.3.4-to-v0.3.5.md`
+
+### Fixed
+- **ESLint Configuration**: Fixed 2195 lint errors by disabling problematic rule and excluding test files from type-checking
+- **OpenTelemetry Dependencies**: Added missing dependencies and removed unnecessary @ts-expect-error directives
+- **Build Errors**: Fixed TypeScript compilation errors
+- **Version Sync**: Updated package.json and .version.json to 0.3.5
+
+## [0.3.4] - 2026-01-13
+### Added
+- **BAT (Browser Automation Testing)**: E2E testing, visual regression, performance testing configuration
+- **MOE (Model Output Evaluation)**: Output validation, quality scoring, auto-correction, context enrichment
+- **Dynamic Version Detection**: Version now derived from git tags (not static .version.json)
+- **Browser Automation Tool Type**: Added `browser-automation` tool type for Playwright/Selenium/Cypress
+- **Testing Capabilities**: Added testing, browser_automation, output_evaluation capability types to taxonomy
+- **AG2 Swarm Topology Support**: Comprehensive swarm topology patterns for multi-agent orchestration
+  - Sequential, fan-out, fan-in, hierarchical, mesh, hub-and-spoke, pipeline, and dynamic topologies
+  - Speaker selection strategies and transition rules
+  - Termination conditions and orchestration modes
+- **AG2 Group Chat Extension**: Multi-agent group chat configuration schemas
+  - Round-robin, auto, manual, and random speaker selection
+  - Conversation termination conditions
+  - Message history management
+  - Context variables and shared state
+- **AG2 Nested Chat Support**: Hierarchical conversation patterns
+  - Trigger conditions for nested conversations
+  - Context propagation strategies (full, summary, selective)
+  - Result aggregation modes
+  - Carryover configuration for context transfer
+- **Human-in-the-Loop Protocols**:
+  - Intervention points schema defining when human authorization is required
+  - Human input modes (ALWAYS, NEVER, TERMINATE)
+  - Multi-step approval workflows with escalation policies
+  - Notification channels and timeout handling
+- **Agent-to-Agent Interoperability**:
+  - Service discovery with health checks and registry integration
+  - Handoff protocol for task delegation between agents
+  - Capability advertisement for agent discovery
+  - Load balancing and capability matching
+- **State Management & Memory Portability**:
+  - Context serialization for save/restore operations
+  - Memory portability between runtimes (working, long-term, episodic, semantic, procedural)
+  - Teachability configuration for agent learning
+  - Vector store support for semantic search
+- **New Top-level Schema Properties**:
+  - `orchestration`: Swarm topology and group chat configuration
+  - `hitl`: Human-in-the-loop configuration
+  - `a2a`: Agent-to-agent interoperability
+  - `state_management`: Context and memory configuration
+- **Example Manifests**: Three complete AG2 integration examples
+  - Hierarchical software development swarm
+  - Group chat research team
+  - Fan-out data processing pipeline
+
+### Changed
+- **Version Management**: `.version.json` is now DEPRECATED - version comes from git tags dynamically
+- **Version Services**: All version services now use `VersionDetectionService` to read from git tags
+- Updated main schema to v0.3.4 with AG2 integration support
+- Updated package.json exports to include all new AG2 schemas
+
+### Fixed
+- Fixed test validation for platform extensions
+- Fixed cross-platform compatibility validation
+
+## [0.3.3] - 2025-01-11
+### Added
+- **Skills Compatibility Extension**: New extension for cross-platform agent skill compatibility
+- **llms.txt Extension**: Full support for llmstxt.org standard with bidirectional sync
+- **AGENTS.md Extension**: Complete agents.md integration with OpenAI agents.md format
+- **Migration System Fix**: Fixed version placeholder handling in migration detection
+- **OpenAPI Compliance**: All CLI commands now defined in OpenAPI specifications
+- **Zod Validation**: Complete runtime validation with Zod schemas
+- **CRUD Operations**: Full Create/Read/Update/Delete for all resources
+- **TypeScript SDK**: Rebuilt SDK following SOLID, DRY, Zod, OpenAPI principles
+- **Extension Development Tools**: TypeScript-based extension team management
+
+### Changed
+- Migrated all shell scripts to TypeScript (project compliance)
+- Reorganized SDK structure into src/sdks/
+- Enhanced version management with proper placeholder handling
+- Improved error messages and validation feedback
+- CI/CD: Install git before using git commands in sync:auto
+- CI/CD: Remove all release jobs, auto-deploy pages on main
+- CI/CD: Update OSSA_VERSION to 0.3.3 on main
+- CI/CD: Update versions.json to 0.3.3 on main
+- CI/CD: Add rebase before push in sync:auto job to handle concurrent commits
+- CI/CD: Allow changelog:generate to fail until push token configured
+- CI/CD: Only run changelog:generate on release branches
+- CI/CD: Auto-deploy pages on main instead of manual
+- CI/CD: Remove resource_group for auto pages deploy
+- CI/CD: Remove environment block from pages job
+- CI/CD: Add missing documentation files from framework website
+- CI/CD: Add all automation documentation files from framework website
+- CI/CD: Sync main into release/v0.3.x for clean deploy
+
+### Fixed
+- Fixed migration detection breaking when package.json contains 0.3.4 placeholder
+- Fixed version comparison logic to handle template placeholders correctly
+- Removed all shell scripts, replaced with TypeScript implementations
+- Fixed CI/CD configuration for proper Docker image usage
+- Fixed hardcoded version detection and validation
+
+[0.3.5]: https://github.com/blueflyio/openstandardagents/compare/v0.3.4...v0.3.5
+[0.3.4]: https://github.com/blueflyio/openstandardagents/compare/v0.3.3...v0.3.4
+[0.3.3]: https://github.com/blueflyio/openstandardagents/releases/tag/v0.3.3

package/spec/v0.3.6/README.md

@@ -0,0 +1,382 @@
+# Open Standard for Software Agents (OSSA)
+
+> **The OpenAPI for Software Agents** - An open specification for production-ready AI agent systems
+
+> **Built for Enterprise Adoption**: OSSA enables companies to build, deploy, and manage AI agents with vendor neutrality, production-grade reliability, and enterprise compliance built-in.
+
+> **v0.3.5 Released**: 10 major features including Completion Signals, Checkpointing, MoE, Flow Orchestration, and more. [See what's new →](spec/v0.3/README.md)
+
+> **For Developers**: See [AGENTS.md](AGENTS.md) for setup and development guidelines. See [llms.txt](llms.txt) for LLM-friendly project overview.
+
+[![npm version](https://img.shields.io/npm/v/@bluefly/openstandardagents)](https://www.npmjs.com/package/@bluefly/openstandardagents)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![GitHub Actions](https://github.com/blueflyio/openstandardagents/workflows/CI/badge.svg)](https://github.com/blueflyio/openstandardagents/actions)
+
+## Why Companies Choose OSSA
+
+**OSSA is an emerging open standard for production AI agent systems** - designed for companies building enterprise-grade agent infrastructure.
+
+### Business Value
+
+- **Vendor Lock-In Elimination** - Switch AI providers (OpenAI, Anthropic, Google) without code changes
+- **Cost Optimization** - Designed to reduce LLM costs via intelligent expert selection (MoE)
+- **Production Reliability** - Improved session recovery with checkpointing and fault tolerance
+- **Enterprise Compliance** - Built-in support for SOC2, HIPAA, GDPR, FedRAMP requirements
+- **Future-Proof Architecture** - Write once, deploy anywhere as AI landscape evolves
+- **Risk Mitigation** - Standardized contracts reduce vendor dependency and technical debt  
+
+### Enterprise Features
+
+- **Vendor-Neutral Contracts** - Works with OpenAI, Anthropic, Google, Azure, AWS, and more
+- **Production-Grade Reliability** - Checkpointing, completion signals, fault tolerance
+- **Enterprise Security** - Built-in access control, audit logging, compliance badges
+- **Observability & Monitoring** - OpenTelemetry, LangSmith, Phoenix, Langfuse integration
+- **Kubernetes-Native** - GitOps-ready, cloud-agnostic deployment
+- **Framework Agnostic** - Works with LangChain, LangFlow, CrewAI, AutoGen, Temporal, n8n
+- **Type-Safe TypeScript SDK** - Full validation and IntelliSense support (Python SDK planned)
+
+### What is OSSA?
+
+OSSA is a **specification standard** (like OpenAPI for REST APIs) that defines contracts and metadata for production agent systems. It's not a framework - it's the standard that frameworks and platforms adopt.
+
+**Key Differentiators:**
+- **The OpenAPI for Agents** - Open specification standard for agent systems
+- **100% Backward Compatible** - Upgrade without breaking changes
+- **Production-Ready** - Built for enterprise scale and reliability
+- **Open Source** - Apache 2.0 licensed, community-driven
+
+## Quick Start
+
+### Install
+
+```bash
+npm install @bluefly/openstandardagents
+# or
+pnpm add @bluefly/openstandardagents
+# or
+yarn add @bluefly/openstandardagents
+```
+
+### Create Your First Agent
+
+```yaml
+# my-agent.ossa.yaml
+apiVersion: ossa/v0.3.5
+kind: Agent
+metadata:
+  name: my-first-agent
+  version: 1.0.0
+spec:
+  role: "A helpful assistant that answers questions"
+  runtime:
+    type: node
+    image: node:20-alpine
+  capabilities:
+    - type: text-generation
+      provider: openai
+      model: gpt-4
+  triggers:
+    - type: webhook
+      endpoint: /chat
+  completion:
+    default_signal: complete
+  checkpointing:
+    enabled: true
+```
+
+### v0.3.5: The OpenAPI for Software Agents
+
+OSSA v0.3.5 introduces **10 major features** transforming it into the definitive OpenAPI for Software Agents:
+
+- **Completion Signals** - Standardized agent termination conditions
+- **Session Checkpointing** - Resilient, resumable agent state
+- **Mixture of Experts (MoE)** - Agent-controlled expert selection
+- **BAT Framework** - Best Available Technology selection
+- **MOE Metrics** - Measure of Effectiveness evaluation
+- **Flow-Based Orchestration** - Native Flow kind support
+- **Dynamic Capability Discovery** - Runtime-adaptive capabilities
+- **Feedback & Learning Loops** - Continuous improvement
+- **Infrastructure Substrate** - Infrastructure as agent-addressable resources
+- **Enhanced A2A Protocol** - Production-ready agent-to-agent communication
+
+**100% Backward Compatible** - All v0.3.4 agents work with v0.3.5 runtime.
+
+### AG2 Multi-Agent Swarm (v0.3.4+)
+
+OSSA v0.3.4+ adds first-class support for AG2 (AutoGen) swarm topologies:
+
+```yaml
+# ag2-swarm.ossa.yaml
+apiVersion: ossa/v0.3.5
+kind: Agent
+metadata:
+  name: software-dev-swarm
+  labels:
+    framework: ag2
+    pattern: hierarchical
+
+orchestration:
+  swarm_topology:
+    topology_type: hierarchical
+    hierarchical:
+      root: agent://supervisor
+      levels:
+        - agents:
+            - uri: agent://tech-lead
+              children:
+                - agent://coder
+                - agent://reviewer
+    speaker_selection_strategy:
+      method: capability_match
+
+  group_chat:
+    participants:
+      - agent://supervisor
+      - agent://tech-lead
+      - agent://coder
+      - agent://reviewer
+    manager: agent://supervisor
+    max_round: 20
+
+hitl:
+  enabled: true
+  human_input_mode: TERMINATE
+  intervention_points:
+    - id: code_review
+      trigger:
+        type: on_decision
+      mode: ALWAYS
+
+a2a:
+  service_discovery:
+    enabled: true
+  handoff_protocol:
+    strategy: capability_match
+
+state_management:
+  teachability:
+    enabled: true
+    learning_modes:
+      - feedback
+      - observation
+```
+
+See [examples/ag2/](spec/v0.3.4/examples/ag2/) for AG2 examples, and [v0.3.5 examples](spec/v0.3/examples/) for new v0.3.5 features.
+
+### Validate Your Agent
+
+```bash
+# Using the CLI
+npx @bluefly/openstandardagents validate my-agent.ossa.yaml
+
+# Or install globally
+npm install -g @bluefly/openstandardagents
+ossa validate my-agent.ossa.yaml
+```
+
+### Use in Code
+
+```typescript
+import { OSSASDKClient } from '@bluefly/openstandardagents/typescript';
+
+const client = new OSSASDKClient();
+const manifest = client.loadManifest('my-agent.ossa.yaml');
+const validation = client.validateManifest(manifest);
+
+if (validation.valid) {
+  console.log('Agent manifest is valid!');
+} else {
+  console.error('Validation errors:', validation.errors);
+}
+```
+
+## Documentation
+
+- **[Official Website](https://openstandardagents.org)** - Complete specification and guides
+- **[Quick Start Guide](docs/QUICKSTART.md)** - Get started in 5 minutes
+- **[API Reference](docs/api-reference/)** - Complete API documentation
+- **[Examples](examples/)** - 100+ reference examples
+- **[Migration Guides](migrations/guides/)** - Upgrade between versions
+
+## Project Structure
+
+```
+openstandardagents/
+├── spec/              # OSSA specification schemas
+│   └── v0.3/         # Current specification version
+├── src/              # TypeScript source code
+│   ├── cli/          # CLI commands
+│   ├── dev-cli/      # Developer CLI tools
+│   ├── services/     # Core services
+│   ├── adapters/     # Framework adapters
+│   ├── tools/        # Development tools
+│   ├── sdks/         # SDK implementations
+│   ├── runtime/      # Runtime execution
+│   ├── types/        # TypeScript types
+│   └── utils/        # Utilities
+├── examples/         # Reference examples
+├── tests/            # Test suite
+└── docs/             # Documentation
+```
+
+## Development
+
+### Prerequisites
+
+- Node.js >= 20.0.0
+- npm, pnpm, or yarn
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/blueflyio/openstandardagents.git
+cd openstandardagents
+
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Build
+npm run build
+
+# Validate all examples
+npm run validate:all
+```
+
+### Available Commands
+
+```bash
+# Validation
+npm run validate:all              # Validate all manifests
+ossa validate <file>              # Validate specific file
+
+# Code Generation
+npm run generate:types           # Generate TypeScript types
+npm run generate:zod             # Generate Zod schemas
+npm run generate:all             # Generate everything
+
+# Migration
+npm run migrate                  # Migrate manifests to latest version
+npm run migrate:check            # Check which files need migration
+
+# Migration
+ossa migrate <file>              # Migrate manifests to latest version
+
+# Developer CLI (for contributors)
+ossa-dev version sync            # Sync version across all files
+ossa-dev version release         # Release new version
+ossa-dev spec generate           # Generate spec from source
+ossa-dev spec validate           # Validate generated spec
+
+# Documentation
+npm run docs:generate            # Generate documentation
+```
+
+## Enterprise Adoption
+
+### Who Uses OSSA?
+
+Companies use OSSA to:
+- **Build vendor-neutral AI agent infrastructure** - Avoid lock-in to specific AI providers
+- **Standardize agent development** - Consistent patterns across teams and projects
+- **Enable multi-cloud deployment** - Deploy agents on AWS, GCP, Azure, or on-premises
+- **Ensure compliance** - Meet SOC2, HIPAA, GDPR requirements with built-in controls
+- **Reduce costs** - Optimize LLM spending with intelligent expert selection
+- **Future-proof investments** - Adapt to new AI models and frameworks without rewrites
+
+### Adoption Path
+
+1. **Start Small** - Migrate one agent to OSSA format
+2. **Validate** - Use OSSA CLI to validate and test
+3. **Scale** - Standardize all agents on OSSA
+4. **Integrate** - Connect to existing CI/CD and observability tools
+5. **Optimize** - Leverage v0.3.5 features (MoE, checkpointing) for cost and reliability gains
+
+### Migration Support
+
+- **From Custom Agents** - Use OSSA CLI to convert existing agent definitions
+- **From LangChain/CrewAI** - Migration tools for popular frameworks
+- **From Other Standards** - Migration guides available for common formats
+- **Zero Downtime** - Migrate incrementally, agents continue working during transition
+
+### Enterprise Support
+
+- **Documentation** - Comprehensive guides, examples, and API reference
+- **Community** - Active Discord community and GitHub discussions
+- **Migration Tools** - Automated migration CLI for seamless upgrades
+- **Compliance** - Built-in security and compliance features
+
+## Contributing
+
+We welcome contributions from companies and individuals! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+### Quick Contribution Guide
+
+1. **Fork the repository**: https://github.com/blueflyio/openstandardagents
+2. **Create a feature branch**: `git checkout -b feature/amazing-feature`
+3. **Make your changes** and add tests
+4. **Run validations**: `npm run validate:all && npm test`
+5. **Commit**: Follow [Conventional Commits](https://www.conventionalcommits.org/)
+6. **Push and create a Pull Request**
+
+### Code of Conduct
+
+Please read [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) before contributing.
+
+## What's Included
+
+### Specification
+
+- **JSON Schema** - Complete validation schemas for all OSSA versions
+- **OpenAPI Specs** - API definitions for agent communication
+- **Migration Guides** - Step-by-step upgrade instructions
+
+### Tools
+
+- **CLI** - Command-line tool for validation, generation, and migration
+- **Developer CLI** - Version management and spec generation tools
+- **TypeScript SDK** - Type-safe client library
+- **Python SDK** - Planned for future release (TypeScript available now)
+- **Framework Integrations** - Import/export from LangChain, LangFlow, CrewAI, AutoGen
+- **Observability Adapters** - Phoenix/Arize, Langfuse, LangSmith, OpenTelemetry support
+
+### Examples
+
+- **Reference Examples** - Example implementations for common patterns
+- **Platform Adapters** - Integrations with LangChain, CrewAI, etc.
+- **Multi-Agent Workflows** - Complex orchestration examples
+
+## Resources
+
+- **Website**: https://openstandardagents.org - Complete specification and enterprise guides
+- **npm Package**: https://www.npmjs.com/package/@bluefly/openstandardagents
+- **Community**: [Discord](https://discord.gg/ZZqad3v4) - Join our developer community
+- **Documentation**: [Full Docs](https://openstandardagents.org/docs) - API reference, guides, examples
+- **Issues**: [GitHub Issues](https://github.com/blueflyio/openstandardagents/issues)
+- **Star Us**: [GitHub](https://github.com/blueflyio/openstandardagents) - Help us grow the ecosystem
+
+## License
+
+Apache-2.0 - See [LICENSE](LICENSE) for details.
+
+## Design Goals
+
+OSSA is designed to provide:
+- **Cost Reduction** - Optimize LLM costs via MoE and intelligent routing
+- **Improved Reliability** - Enhanced session recovery with checkpointing
+- **Zero Vendor Lock-in** - Seamless provider switching through standardization
+- **Faster Development** - Accelerated agent development with standardized patterns
+- **Compliance Support** - Built-in features for SOC2, HIPAA, GDPR requirements
+
+## Acknowledgments
+
+OSSA is maintained by the open-source community and adopted by companies worldwide. Special thanks to all contributors and adopters!
+
+---
+
+**Built for Enterprise. Open for Everyone.**
+
+**Join the companies standardizing on OSSA** - [Get Started](https://openstandardagents.org/docs/getting-started)