@bluefly/openstandardagents 0.2.7 → 0.2.9

package/scripts/eslint-to-codequality.cjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const crypto = require('crypto');
+
+const eslintResults = JSON.parse(fs.readFileSync(process.argv[2] || 'eslint-report.json', 'utf8'));
+
+const codeQualityReport = [];
+
+eslintResults.forEach(file => {
+  file.messages.forEach(msg => {
+    const fingerprint = crypto
+      .createHash('md5')
+      .update(`${file.filePath}:${msg.line}:${msg.ruleId}`)
+      .digest('hex');
+
+    codeQualityReport.push({
+      description: msg.message,
+      check_name: msg.ruleId || 'eslint',
+      fingerprint,
+      severity: msg.severity === 2 ? 'major' : 'minor',
+      location: {
+        path: file.filePath.replace(process.cwd() + '/', ''),
+        lines: {
+          begin: msg.line
+        }
+      }
+    });
+  });
+});
+
+fs.writeFileSync(
+  process.argv[3] || 'gl-code-quality-report.json',
+  JSON.stringify(codeQualityReport, null, 2)
+);

package/scripts/generate-agents-catalog.ts

@@ -23,7 +23,8 @@ function findAgents(): Agent[] {
     const manifestPath = join(AGENTS_DIR, entry, 'manifest.ossa.yaml');
     try {
       const content = readFileSync(manifestPath, 'utf-8');
-      const data = yaml.load(content) as any;
+      // Use safeLoad to prevent arbitrary code execution (CWE-502)
+      const data = yaml.load(content, { schema: yaml.JSON_SCHEMA }) as Record<string, unknown>;
       
       if (data?.agent) {
         agents.push({

package/scripts/generate-api-docs.ts

@@ -154,7 +154,8 @@ function main() {
     try {
       const specPath = join(coreDir, file);
       const specContent = readFileSync(specPath, 'utf-8');
-      const spec = yaml.load(specContent) as OpenAPISpec;
+      // Use JSON_SCHEMA to prevent arbitrary code execution (CWE-502)
+      const spec = yaml.load(specContent, { schema: yaml.JSON_SCHEMA }) as OpenAPISpec;
       
       const docContent = generateAPIDoc(spec, file);
       const outputFile = join(OUTPUT_DIR, file.replace('.openapi.yaml', '.md'));

package/scripts/generate-examples-docs.ts

@@ -31,7 +31,8 @@ function findYamlFiles(dir: string, category: string = ''): Example[] {
     } else if (entry.match(/\.(yaml|yml)$/)) {
       try {
         const content = readFileSync(fullPath, 'utf-8');
-        const data = yaml.load(content) as any;
+        // Use JSON_SCHEMA to prevent arbitrary code execution (CWE-502)
+        const data = yaml.load(content, { schema: yaml.JSON_SCHEMA }) as any;
         
         if (data?.agent) {
           examples.push({

package/scripts/generate-llms-ctx.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+# Generate llms-ctx.txt files from llms.txt
+
+set -e
+
+echo "Installing llms-txt..."
+pip install llms-txt --quiet
+
+echo "Generating llms-ctx.txt (without Optional)..."
+llms_txt2ctx llms.txt > llms-ctx.txt
+
+echo "Generating llms-ctx-full.txt (with Optional)..."
+llms_txt2ctx llms.txt --optional True > llms-ctx-full.txt
+
+echo "✅ Generated:"
+echo "  - llms-ctx.txt ($(wc -l < llms-ctx.txt) lines)"
+echo "  - llms-ctx-full.txt ($(wc -l < llms-ctx-full.txt) lines)"

package/scripts/generate-schema-docs.ts

@@ -5,8 +5,28 @@
  * Usage: npm run docs:schema:generate
  */
 
-import { readFileSync, writeFileSync, mkdirSync } from 'fs';
-import { join } from 'path';
+import { readFileSync, writeFileSync, mkdirSync, readdirSync } from 'fs';
+import { join, resolve } from 'path';
+
+// Dynamic version detection - find latest spec directory
+function getLatestSchemaVersion(): { dir: string; file: string } {
+  const specDir = join(process.cwd(), 'spec');
+  const dirs = readdirSync(specDir, { withFileTypes: true })
+    .filter(d => d.isDirectory() && d.name.startsWith('v'))
+    .map(d => d.name)
+    .sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
+
+  if (dirs.length === 0) {
+    throw new Error('No schema version directories found in spec/');
+  }
+
+  const latestDir = dirs[0];
+  const version = latestDir.slice(1); // Remove 'v' prefix
+  return {
+    dir: latestDir,
+    file: `ossa-${version}.schema.json`
+  };
+}
 
 interface SchemaProperty {
   type: string | string[];
@@ -25,8 +45,10 @@ interface SchemaProperty {
   items?: SchemaProperty;
 }
 
-const SPEC_DIR = join(process.cwd(), 'spec/v0.2.5-RC');
-const OUTPUT_DIR = join(process.cwd(), 'website/content/docs/schema-reference');
+// Dynamic paths based on detected version
+const schemaVersion = getLatestSchemaVersion();
+const SPEC_DIR = join(process.cwd(), 'spec', schemaVersion.dir);
+const OUTPUT_DIR = join(process.cwd(), 'docs/schema-reference');
 
 // Field documentation metadata
 const FIELD_DOCS: Record<string, {
@@ -211,8 +233,9 @@ function main() {
   // Create output directory
   mkdirSync(OUTPUT_DIR, { recursive: true });
   
-  // Read schema
-  const schemaPath = join(SPEC_DIR, 'ossa-0.2.5-RC.schema.json');
+  // Read schema dynamically
+  const schemaPath = join(SPEC_DIR, schemaVersion.file);
+  console.log(`📜 Using schema: ${schemaVersion.dir}/${schemaVersion.file}`);
   const schemaContent = readFileSync(schemaPath, 'utf-8');
   const schema = JSON.parse(schemaContent);
   
@@ -259,9 +282,7 @@ The OSSA schema defines the structure of agent manifests. Every field serves a s
 
 ## Schema Versions
 
-- **Current**: v0.2.5-RC
-- **Stable**: v0.2.4
-- **Previous**: v0.2.3, v0.2.2
+- **Current**: ${schemaVersion.dir}
 
 See [Versioning Guide](../guides/versioning.md) for migration information.
 
@@ -276,7 +297,7 @@ ossa validate agent.ossa.yaml
 ## Complete Schema
 
 View the complete JSON Schema:
-- [v0.2.5-RC Schema](https://github.com/blueflyio/openstandardagents/blob/main/spec/v0.2.5-RC/ossa-0.2.5-RC.schema.json)
+- [${schemaVersion.dir} Schema](https://github.com/blueflyio/openstandardagents/blob/main/spec/${schemaVersion.dir}/${schemaVersion.file})
 
 ## Related Documentation
 

package/scripts/sync-version.js

@@ -5,18 +5,10 @@ import { resolve } from 'path';
 
 const { version } = JSON.parse(readFileSync('package.json', 'utf-8'));
 
-const files = [
-  {
-    path: 'website/src/config.ts',
-    pattern: /version:\s*['"][\d.]+['"]/,
-    replacement: `version: '${version}'`
-  },
-  {
-    path: 'src/version.ts',
-    pattern: /VERSION\s*=\s*['"][\d.]+['"]/,
-    replacement: `VERSION = '${version}'`
-  }
-];
+// Website moved to openstandardagents.org repository
+// Version is read from package.json at runtime via scripts/lib/version.ts
+// No hardcoded version files to sync
+const files = [];
 
 console.log(`📦 Syncing version: ${version}\n`);
 

package/scripts/validate-schema.ts

@@ -33,7 +33,8 @@ async function main() {
     // Get additional args
     const args = process.argv.slice(2);
     // Use ajv-cli compile to validate schema syntax (no data file needed)
-    const command = `npx ajv-cli compile -s ${schemaPath} ${args.join(' ')}`;
+    // --strict=false allows unknown formats like "uri"
+    const command = `npx ajv-cli compile -s ${schemaPath} --strict=false ${args.join(' ')}`;
     
     // Run validation
     execCommand(command, { stdio: 'inherit' });

package/spec/v0.2.8/CHANGELOG.md

@@ -0,0 +1,401 @@
+# OSSA v0.2.8 Release Notes
+
+**Release Date**: 2025-11-24
+**Type**: Minor Release
+**Status**: STABLE
+
+## Overview
+
+OSSA v0.2.8 introduces significant new features for transport metadata, state management, enhanced security, and capability versioning. This release enhances OSSA integration with Google ADK, A2A protocol, OpenAI Agents SDK, and Microsoft Autogen Framework.
+
+## What's New
+
+### Transport Metadata for Capabilities
+
+Support for protocol-specific transport configuration, enabling streaming and advanced communication patterns.
+
+```yaml
+tools:
+  - type: http
+    name: chat-api
+    transport:
+      protocol: http
+      streaming: response          # Server streams to client
+      binding: /v1/chat/stream
+      content_type: text/event-stream
+```
+
+**Supported protocols**: `http`, `grpc`, `a2a`, `mcp`, `websocket`, `custom`
+
+**Streaming modes**:
+- `none` - Standard request/response
+- `request` - Client streams to server
+- `response` - Server streams to client (SSE, streaming LLM)
+- `bidirectional` - Full duplex (WebSocket, gRPC)
+
+**Use cases**:
+- Google ADK bidirectional streaming
+- A2A protocol agent-to-agent communication
+- Streaming LLM responses
+- Real-time collaborative agents
+
+### State/Memory Block
+
+Agent state management configuration for stateful and long-running agents.
+
+```yaml
+spec:
+  state:
+    mode: session                  # stateless | session | long_running
+    storage:
+      type: vector-db             # memory | vector-db | kv | rdbms | custom
+      retention: 30d
+      config:
+        provider: pinecone
+        index: agent-memory
+    context_window:
+      max_messages: 100
+      max_tokens: 32000
+      strategy: summarization      # sliding_window | summarization | importance_weighted
+```
+
+**Storage types**:
+- `memory` - In-process (lost on restart)
+- `vector-db` - Vector database (Pinecone, Weaviate, Chroma)
+- `kv` - Key-value store (Redis, DynamoDB)
+- `rdbms` - Relational database
+- `custom` - Custom implementation
+
+**Critical for**:
+- OpenAI Agents SDK session continuity
+- Microsoft Autogen Framework workflows
+- RAG systems with context retention
+- Multi-turn conversations
+
+### Enhanced Security with Scopes
+
+Fine-grained permission scopes and compliance tags for capabilities.
+
+```yaml
+tools:
+  - type: http
+    name: database-api
+    auth:
+      type: bearer
+      credentials: secret:db-api-key
+      scopes:                      # NEW: OAuth2-like scopes
+        - read:data
+        - execute:query
+    compliance_tags:               # NEW: Compliance framework tags
+      - pii
+      - gdpr
+      - hipaa
+    capabilities:
+      - name: query_users
+        scopes:                    # Per-capability scopes
+          - read:users
+        compliance_tags:
+          - pii
+```
+
+**Security scopes**:
+- `read:data`, `write:data` - Data access
+- `admin:system`, `admin:users` - Administrative operations
+- `execute:code`, `execute:query` - Execution permissions
+
+**Compliance tags**:
+- `pii` - Personally identifiable information
+- `hipaa` - HIPAA compliance required
+- `gdpr` - GDPR compliance required
+- `fedramp` - FedRAMP requirements
+- `soc2` - SOC2 Type II controls
+
+### Capability Versioning
+
+Independent versioning and deprecation for capabilities.
+
+```yaml
+capabilities:
+  - name: search_documents
+    version: '2.1'                 # NEW: Capability version
+    deprecated: false
+
+  - name: search_legacy
+    version: '1.0'
+    deprecated: true               # NEW: Deprecation flag
+    deprecation_message: |         # NEW: Migration guidance
+      Deprecated in v0.2.4. Will be removed in v0.3.0.
+      Use 'search_documents' capability instead.
+      Migration: Change capability name and update input schema
+      to use 'query' instead of 'search_term'.
+```
+
+**Benefits**:
+- Independent capability lifecycle management
+- Clear migration paths for breaking changes
+- Backward compatibility tracking
+- API versioning best practices
+
+### Google ADK Extension
+
+Integration with Google's Agent Development Kit (ADK).
+
+```yaml
+extensions:
+  google_adk:
+    enabled: true
+    agent_type: llm_agent          # llm_agent | sequential_agent | parallel_agent | loop_agent
+    model: gemini-2.0-flash-exp
+    instruction: "You are a helpful research assistant."
+    session:
+      service: in_memory           # in_memory | database | vertex_ai
+      state_schema:
+        search_history: array
+        current_topic: string
+    memory:
+      enabled: true
+      service: vertex_ai_rag
+    callbacks:
+      before_model_callback: validate_input
+      after_model_callback: log_response
+```
+
+**Agent types**:
+- `llm_agent` - Single LLM-powered agent
+- `sequential_agent` - Pipeline of agents
+- `parallel_agent` - Concurrent agent execution
+- `loop_agent` - Iterative agent with conditions
+
+**Features**:
+- Session management (in_memory, database, Vertex AI)
+- Memory service integration (Vertex AI RAG)
+- Lifecycle callbacks
+- Sub-agent orchestration
+
+### Schema Updates
+
+#### apiVersion Pattern
+Updated to support v0.2.8:
+```regex
+^ossa/v(0\.2\.[2-4](-dev)?|1)(\.[0-9]+)?(-[a-zA-Z0-9]+)?$
+```
+
+**Valid versions**:
+- `ossa/v0.2.2`
+- `ossa/v0.2.4`
+- `ossa/v0.2.8`
+- `ossa/v1`
+- `ossa/v1.0`
+
+#### Tool Type Enum
+Added `a2a` to supported tool types:
+```json
+"type": {
+  "enum": ["mcp", "kubernetes", "http", "grpc", "function", "a2a", "custom"]
+}
+```
+
+#### New Definitions
+- `Transport` - Transport metadata schema
+- `State` - State/memory configuration schema
+- `Capability` - Enhanced capability with versioning and scopes
+- `GoogleADKExtension` - Google ADK integration
+
+## Breaking Changes
+
+**None** - This release maintains full backward compatibility with v0.2.3.
+
+All new features are additive and optional.
+
+## Deprecations
+
+**None** - No features deprecated in this release.
+
+## Migration from v0.2.3
+
+### Required Changes
+**None** - v0.2.3 manifests work without modification.
+
+### Recommended Changes
+
+1. **Add state configuration for stateful agents**:
+```yaml
+spec:
+  state:
+    mode: session
+    storage:
+      type: memory
+      retention: 24h
+```
+
+2. **Add transport metadata for streaming capabilities**:
+```yaml
+tools:
+  - type: http
+    transport:
+      protocol: http
+      streaming: response
+```
+
+3. **Add compliance tags for regulated environments**:
+```yaml
+tools:
+  - type: http
+    compliance_tags:
+      - pii
+      - gdpr
+```
+
+4. **Version capabilities for better lifecycle management**:
+```yaml
+capabilities:
+  - name: my_capability
+    version: '1.0'
+```
+
+See [migrations/v0.2.3-to-v0.2.4.md](migrations/v0.2.3-to-v0.2.4.md) for detailed migration guide.
+
+## Installation
+
+### Development Version
+```bash
+npm install -g @bluefly/openstandardagents@0.2.8
+```
+
+### Verify Installation
+```bash
+ossa --version
+# Output: 0.2.8
+```
+
+## Compatibility
+
+| Component | Version | Status |
+|-----------|---------|--------|
+| Node.js | >=18.0.0 | Required |
+| npm | >=9.0.0 | Required |
+| kAgent | v1alpha1, v1alpha2 | Full support |
+| Drupal | 11.x, 10.x | Full support |
+| OpenAI Agents SDK | v2.x | Full support |
+| LangChain | v0.3.x | Full support |
+| CrewAI | v0.11.x | Full support |
+| MCP | Latest | Full support |
+| Google ADK | Preview | Experimental |
+| A2A Protocol | v0.1 | Experimental |
+
+## Known Issues
+
+- Transport metadata validation is experimental and may be refined
+- State storage backends are limited to documented types
+- Capability versioning pattern may change before stable release
+- Google ADK extension is based on ADK preview release
+
+## Testing
+
+All existing tests pass. New tests added for:
+- Transport metadata validation
+- State configuration validation
+- Security scopes validation
+- Capability versioning validation
+- Google ADK extension validation
+
+## Security
+
+No new security vulnerabilities introduced.
+
+**Recommendations**:
+- Use scopes to enforce least-privilege access
+- Apply compliance_tags consistently for regulated data
+- Review security implications of new transport modes
+
+## Use Cases
+
+### Streaming LLM Agent
+```yaml
+spec:
+  tools:
+    - type: http
+      transport:
+        protocol: http
+        streaming: response
+        content_type: text/event-stream
+```
+
+### Stateful Chat Agent
+```yaml
+spec:
+  state:
+    mode: session
+    storage:
+      type: memory
+      retention: 24h
+    context_window:
+      max_messages: 50
+```
+
+### HIPAA-Compliant Agent
+```yaml
+spec:
+  tools:
+    - type: http
+      auth:
+        scopes: [read:phi, write:phi]
+      compliance_tags: [hipaa, pii]
+```
+
+### Google ADK Multi-Agent
+```yaml
+extensions:
+  google_adk:
+    enabled: true
+    agent_type: sequential_agent
+    sub_agents: [researcher, writer, reviewer]
+```
+
+## Roadmap to v0.2.4 Stable
+
+- [ ] Finalize transport metadata validation rules
+- [ ] Extend state storage backend options
+- [ ] Refine capability versioning semantics
+- [ ] Update Google ADK extension for GA release
+- [ ] Enhanced A2A protocol support
+- [ ] Additional examples and migration guides
+
+## Contributors
+
+- Transport and streaming design
+- State management implementation
+- Security scopes and compliance tagging
+- Capability versioning system
+- Google ADK extension
+
+## Feedback
+
+This is a development release. Please provide feedback:
+
+- **Issues**: https://github.com/blueflyio/openstandardagents/issues
+- **Documentation**: https://github.com/blueflyio/openstandardagents
+
+## Next Steps
+
+### v0.2.4 Stable (Planned)
+- Finalized transport and state schemas
+- Comprehensive examples
+- Full test coverage
+- Production-ready Google ADK extension
+
+### v0.3.0 (Future)
+- Agent composition patterns
+- Distributed state management
+- Cross-agent memory sharing
+- Enhanced A2A protocol support
+
+## Support
+
+- **Documentation**: https://github.com/blueflyio/openstandardagents
+- **Issues**: https://github.com/blueflyio/openstandardagents/issues
+- **Examples**: https://github.com/blueflyio/openstandardagents/tree/main/examples
+
+---
+
+**Full Changelog**: [v0.2.5...v0.2.8](https://github.com/blueflyio/openstandardagents/compare/v0.2.5...v0.2.8)

package/spec/v0.2.8/README.md

@@ -0,0 +1,72 @@
+# OSSA v0.2.8 Specification
+
+**Release Date**: November 24, 2025
+**Status**: Stable Release
+**Version**: 0.2.8
+
+## Overview
+
+OSSA (Open Standard for Scalable AI Agents) v0.2.8 is a minor release introducing enhanced transport metadata, state management, security features, and capability versioning for better framework integration.
+
+## What's in This Directory
+
+- **`ossa-0.2.8.schema.json`** - JSON Schema definition for OSSA v0.2.8 agent manifests
+- **`ossa-0.2.8.yaml`** - YAML specification document
+- **`CHANGELOG.md`** - Detailed release notes and feature descriptions
+- **`README.md`** - This file
+- **`migrations/`** - Upgrade guides from previous versions
+
+## Key Features
+
+### 🔄 Transport Metadata
+- Protocol-specific configuration for capabilities
+- Streaming support (SSE, WebSocket, gRPC)
+- Enhanced integration with Google ADK, A2A protocol, MCP
+
+### 🔒 Enhanced Security
+- Security policies for tools and memory
+- Access control for capabilities
+- Audit logging support
+
+### 📊 State Management
+- Persistent and ephemeral state handling
+- State versioning and migration
+- Multi-agent state coordination
+
+### 🔧 Capability Versioning
+- Semantic versioning for tools and capabilities
+- Backward compatibility tracking
+- Deprecation warnings
+
+## Compatibility
+
+- **Backward Compatible**: Yes (with v0.2.2, v0.2.3, v0.2.4)
+- **Breaking Changes**: None
+- **Supported API Versions**: `ossa/v0.2.2`, `ossa/v0.2.3`, `ossa/v0.2.4`, `ossa/v0.2.8`, `ossa/v1`
+
+## Migration
+
+To upgrade from previous versions, see the migration guides:
+- [v0.2.4 → v0.2.8](./migrations/v0.2.4-to-v0.2.8.md)
+- [v0.2.3 → v0.2.8](./migrations/v0.2.3-to-v0.2.8.md)
+
+## Validation
+
+To validate manifests against this schema:
+
+```bash
+npm install @bluefly/openstandardagents
+ossa validate your-agent.yaml
+```
+
+## Resources
+
+- **Website**: https://openstandardagents.org
+- **Schema URL**: https://openstandardagents.org/schemas/v0.2.8/agent.json
+- **GitHub**: https://github.com/blueflyio/openstandardagents
+- **GitHub Mirror**: https://github.com/blueflyio/openstandardagents
+- **npm Package**: https://npmjs.com/package/@bluefly/openstandardagents
+
+## License
+
+MIT License - See root LICENSE file for details.