@bluefly/openstandardagents 0.2.4 → 0.2.7

package/website/content/docs/schema-reference/index.md

@@ -1,176 +1,45 @@
----
-title: "Schema Reference"
-description: "Complete reference documentation for the OSSA v0.2.x Agent Manifest Schema"
-weight: 50
----
+# Schema Reference
 
-# OSSA Schema Reference
+Complete reference for the OSSA agent manifest schema.
 
-Complete reference documentation for the Open Standard for Scalable Agents (OSSA) v0.2.x schema.
+## Overview
 
-The OSSA schema provides a declarative, framework-agnostic way to define AI agents with full portability across platforms and orchestration frameworks.
+The OSSA schema defines the structure of agent manifests. Every field serves a specific purpose in the agent lifecycle.
 
-## Schema Overview
+## Core Fields
 
-The OSSA manifest is a JSON/YAML document that defines:
+### Agent Identification
+- [agent.id](./agent-id.md) - Unique agent identifier
+- [agent.name](./agent-name.md) - Human-readable name
+- [agent.version](./agent-version.md) - Semantic version
+- [agent.role](./agent-role.md) - Agent role classification
 
-- **Agent metadata** - Name, version, labels, and annotations
-- **Agent specification** - Role, LLM configuration, tools, and capabilities
-- **Autonomy settings** - Decision-making level and approval requirements
-- **Constraints** - Cost, performance, and resource limits
-- **Observability** - Tracing, metrics, and logging configuration
-- **Framework extensions** - Integration with kagent, BuildKit, Drupal, LibreChat, and 14+ other frameworks
+### Agent Capabilities
+- [agent.capabilities](./agent-capabilities.md) - What the agent can do
 
-## Schema Version
+## Schema Versions
 
-```yaml
-apiVersion: ossa/v0.2.x
-```
+- **Current**: v0.2.5-RC
+- **Stable**: v0.2.4
+- **Previous**: v0.2.3, v0.2.2
 
-The current stable version is `ossa/v0.2.x` (v0.2.2, v0.2.3, v0.2.4+). The schema also supports `ossa/v1` for forward compatibility.
-
-## Schema Components
-
-### Core Objects
-
-- [**OSSA Manifest**](./ossa-manifest.md) - Root manifest object with metadata and spec
-- [**Agent Spec**](./agent-spec.md) - Agent specification including role, LLM, and tools
-- [**LLM Configuration**](./llm-config.md) - Language model provider and parameters
-- [**Tools**](./tools.md) - Tool definitions for MCP, Kubernetes, HTTP, and custom integrations
-
-### Configuration Objects
-
-- [**Taxonomy**](./taxonomy.md) - Agent domain, subdomain, and capability classification
-- [**Autonomy**](./autonomy.md) - Decision-making level and action controls
-- [**Constraints**](./constraints.md) - Cost, performance, and resource constraints
-- [**Observability**](./observability.md) - Tracing, metrics, and logging
-
-### Framework Extensions
-
-- [**kagent Extension**](./extensions/kagent.md) - Kubernetes-native agent deployment
-- [**BuildKit Extension**](./extensions/buildkit.md) - Agent BuildKit orchestration
-- [**Drupal Extension**](./extensions/drupal.md) - Drupal LLM Platform integration
-- [**LibreChat Extension**](./extensions/librechat.md) - LibreChat integration
-- [**MCP Extension**](./extensions/mcp.md) - Model Context Protocol servers
-- [**LangChain Extension**](./extensions/langchain.md) - LangChain framework
-- [**CrewAI Extension**](./extensions/crewai.md) - CrewAI multi-agent framework
-- [**OpenAI Agents Extension**](./extensions/openai-agents.md) - OpenAI Agents SDK
-- [**Cursor Extension**](./extensions/cursor.md) - Cursor IDE integration
-- [**Langflow Extension**](./extensions/langflow.md) - Langflow workflow orchestration
-- [**AutoGen Extension**](./extensions/autogen.md) - Microsoft AutoGen
-- [**Vercel AI Extension**](./extensions/vercel-ai.md) - Vercel AI SDK
-- [**LlamaIndex Extension**](./extensions/llamaindex.md) - LlamaIndex RAG framework
-- [**LangGraph Extension**](./extensions/langgraph.md) - LangGraph state machines
-- [**Anthropic Extension**](./extensions/anthropic.md) - Anthropic Claude API
-
-## Quick Example
-
-```yaml
-apiVersion: ossa/v0.2.x
-kind: Agent
-metadata:
-  name: code-reviewer
-  version: 1.0.0
-  description: Automated code review agent
-  labels:
-    domain: development
-    capability: code-review
-spec:
-  taxonomy:
-    domain: development
-    subdomain: quality-assurance
-    capability: code-review
-  role: |
-    You are a code review specialist. Analyze code for:
-    - Security vulnerabilities
-    - Performance issues
-    - Best practices adherence
-    - Code quality and maintainability
-  llm:
-    provider: anthropic
-    model: claude-3-5-sonnet-20241022
-    temperature: 0.3
-    maxTokens: 4096
-  tools:
-    - type: mcp
-      server: filesystem
-      capabilities:
-        - read_file
-        - list_directory
-    - type: mcp
-      server: git
-      capabilities:
-        - git_diff
-        - git_log
-  autonomy:
-    level: supervised
-    approval_required: false
-    allowed_actions:
-      - read_code
-      - analyze_security
-      - generate_report
-  constraints:
-    cost:
-      maxTokensPerDay: 1000000
-      maxCostPerDay: 50.0
-      currency: USD
-    performance:
-      maxLatencySeconds: 30
-      timeoutSeconds: 120
-  observability:
-    tracing:
-      enabled: true
-      exporter: otlp
-    metrics:
-      enabled: true
-      exporter: prometheus
-    logging:
-      level: info
-      format: json
-```
+See [Versioning Guide](../guides/versioning.md) for migration information.
 
 ## Validation
 
-All OSSA manifests must conform to the JSON Schema:
-
-```
-https://openstandardagents.org/schemas/v0.2.x/agent.json
-```
-
-Use the schema for validation in your tools and editors:
-
-**VSCode/Cursor:**
-```json
-{
-  "$schema": "https://openstandardagents.org/schemas/v0.2.x/agent.json"
-}
-```
+Validate your agent manifests:
 
-**Command-line validation:**
 ```bash
-ossa validate manifest.json
+ossa validate agent.ossa.yaml
 ```
 
-## Framework Compatibility
-
-The OSSA schema is designed for framework-agnostic portability. The same manifest can be deployed to:
-
-- **kagent.dev** - Kubernetes-native agent platform
-- **Agent BuildKit** - Multi-runtime orchestration
-- **Drupal LLM Platform** - Drupal-based agent management
-- **LibreChat** - Open-source chat interface
-- **LangChain, CrewAI, AutoGen** - Python agent frameworks
-- **OpenAI Agents SDK** - Official OpenAI agent runtime
-- **Cursor, Continue** - IDE-integrated coding agents
-- **Vercel AI SDK** - Edge/Node.js deployment
-- **LlamaIndex, LangGraph** - RAG and state machine frameworks
+## Complete Schema
 
-See the [Extensions](./extensions/) section for framework-specific configuration.
+View the complete JSON Schema:
+- [v0.2.5-RC Schema](https://github.com/blueflyio/openstandardagents/blob/main/spec/v0.2.6/ossa-0.2.6.schema.json)
 
-## Additional Resources
+## Related Documentation
 
-- [OSSA Specification](/docs/)
-- [Getting Started Guide](/docs/getting-started/)
-- [Examples](/docs/examples/)
-- [GitHub Repository](https://github.com/blueflyio/openstandardagents)
-- [Schema Download](https://openstandardagents.org/schemas/v0.2.x/agent.json)
+- [CLI Reference](../cli-reference/index.md)
+- [API Reference](../api-reference/index.md)
+- [Creating Agents Guide](../guides/creating-agents.md)

package/website/content/docs/schema-reference/llm-config.md

@@ -356,7 +356,7 @@ llm:
 ## Complete Example
 
 ```yaml
-apiVersion: ossa/v0.2.3
+apiVersion: ossa/v0.2.x
 kind: Agent
 metadata:
   name: technical-writer

package/website/content/docs/schema-reference/observability.md

@@ -352,7 +352,7 @@ observability:
 ### Production Observability Stack
 
 ```yaml
-apiVersion: ossa/v0.2.3
+apiVersion: ossa/v0.2.x
 kind: Agent
 metadata:
   name: production-agent
@@ -379,7 +379,7 @@ spec:
 ### Development Environment
 
 ```yaml
-apiVersion: ossa/v0.2.3
+apiVersion: ossa/v0.2.x
 kind: Agent
 metadata:
   name: dev-agent
@@ -405,7 +405,7 @@ spec:
 ### Cloud-Native (Grafana Stack)
 
 ```yaml
-apiVersion: ossa/v0.2.3
+apiVersion: ossa/v0.2.x
 kind: Agent
 metadata:
   name: cloud-agent
@@ -432,7 +432,7 @@ spec:
 ### Minimal Observability
 
 ```yaml
-apiVersion: ossa/v0.2.3
+apiVersion: ossa/v0.2.x
 kind: Agent
 metadata:
   name: minimal-agent
@@ -456,7 +456,7 @@ spec:
 ### High-Volume Agent
 
 ```yaml
-apiVersion: ossa/v0.2.3
+apiVersion: ossa/v0.2.x
 kind: Agent
 metadata:
   name: high-volume-agent

package/website/content/docs/schema-reference/ossa-manifest.md

@@ -12,7 +12,7 @@ The root object of an OSSA agent manifest. This is the top-level container for a
 
 | Field Name | Type | Required | Description |
 |------------|------|----------|-------------|
-| `apiVersion` | string | **Yes** | OSSA API version. Must match pattern `ossa/v(0.2.[2-3]\|1)`. Examples: `ossa/v1`, `ossa/v0.2.3` |
+| `apiVersion` | string | **Yes** | OSSA API version. Must match pattern `ossa/v(0.2.[2-3]\|1)`. Examples: `ossa/v1`, `ossa/v0.2.x` |
 | `kind` | string | **Yes** | Resource type. Currently only `Agent` is supported |
 | `metadata` | [Metadata](#metadata-object) | **Yes** | Agent metadata including name, version, labels, and annotations |
 | `spec` | [AgentSpec](./agent-spec.md) | **Yes** | Agent specification defining behavior, capabilities, and configuration |
@@ -82,7 +82,7 @@ Framework-specific extensions enable integration with various agent platforms an
 ### Extensions Example
 
 ```yaml
-apiVersion: ossa/v0.2.3
+apiVersion: ossa/v0.2.x
 kind: Agent
 metadata:
   name: multi-platform-agent
@@ -120,7 +120,7 @@ extensions:
 ## Complete Example
 
 ```yaml
-apiVersion: ossa/v0.2.3
+apiVersion: ossa/v0.2.x
 kind: Agent
 
 metadata:
@@ -251,7 +251,7 @@ extensions:
 
 ### apiVersion Validation
 - Must match regex: `^ossa/v(0\.2\.[2-3]|1)(\.0)?(-[a-zA-Z0-9]+)?$`
-- Valid examples: `ossa/v1`, `ossa/v0.2.3`, `ossa/v0.2.3`, `ossa/v1.0`
+- Valid examples: `ossa/v1`, `ossa/v0.2.x`, `ossa/v0.2.4`, `ossa/v1.0`
 - Invalid examples: `v1`, `ossa/v2`, `ossa/0.2.3`
 
 ### kind Validation
@@ -300,8 +300,8 @@ https://openstandardagents.org/schemas/v0.2.3/agent.json
 Use it for validation and editor autocomplete:
 ```json
 {
-  "$schema": "https://openstandardagents.org/schemas/v0.2.3/agent.json",
-  "apiVersion": "ossa/v0.2.3",
+  "$schema": "https://openstandardagents.org/schemas/v0.2.x/agent.json",
+  "apiVersion": "ossa/v0.2.x",
   "kind": "Agent",
   "metadata": { ... },
   "spec": { ... }

package/website/content/docs/schema-reference/taxonomy.md

@@ -323,7 +323,7 @@ taxonomy:
 ### Infrastructure Kubernetes Troubleshooting Agent
 
 ```yaml
-apiVersion: ossa/v0.2.3
+apiVersion: ossa/v0.2.x
 kind: Agent
 metadata:
   name: k8s-troubleshooter
@@ -362,7 +362,7 @@ spec:
 ### Security Vulnerability Scanner
 
 ```yaml
-apiVersion: ossa/v0.2.3
+apiVersion: ossa/v0.2.x
 kind: Agent
 metadata:
   name: vulnerability-scanner
@@ -400,7 +400,7 @@ spec:
 ### Documentation Generator
 
 ```yaml
-apiVersion: ossa/v0.2.3
+apiVersion: ossa/v0.2.x
 kind: Agent
 metadata:
   name: api-doc-generator

package/website/content/docs/types-reference/index.md

@@ -0,0 +1,105 @@
+# TypeScript Types Reference
+
+Auto-generated from `src/types/index.ts`
+
+## Interfaces
+
+### Capability
+
+```typescript
+export interface Capability {
+  name: string;
+  description: string;
+  input_schema: Record<string, unknown> | string;
+  output_schema: Record<string, unknown> | string;
+  examples?: Array<{
+    name?: string;
+    input?: Record<string, unknown>;
+    output?: Record<string, unknown>;
+  }
+```
+
+### OssaAgent
+
+```typescript
+export interface OssaAgent {
+  // v0.2.3 format
+  apiVersion?: string;
+  kind?: string;
+  metadata?: {
+    name: string;
+    version?: string;
+    description?: string;
+    labels?: Record<string, string>;
+    annotations?: Record<string, string>;
+  }
+```
+
+### ValidationResult
+
+```typescript
+export interface ValidationResult {
+  valid: boolean;
+  errors: ErrorObject[];
+  warnings: string[];
+  manifest?: OssaAgent;
+}
+```
+
+### AgentTemplate
+
+```typescript
+export interface AgentTemplate {
+  id: string;
+  name: string;
+  role: string;
+  description?: string;
+  runtimeType?: string;
+  capabilities?: Capability[];
+}
+```
+
+### IValidationService
+
+```typescript
+export interface IValidationService {
+  validate(
+    manifest: unknown,
+    version: SchemaVersion
+  ): Promise<ValidationResult>;
+}
+```
+
+### ISchemaRepository
+
+```typescript
+export interface ISchemaRepository {
+  getSchema(version: SchemaVersion): Promise<Record<string, unknown>>;
+  clearCache(): void;
+  getAvailableVersions(): string[];
+  getCurrentVersion(): string;
+}
+```
+
+### IManifestRepository
+
+```typescript
+export interface IManifestRepository {
+  load(path: string): Promise<unknown>;
+  save(path: string, manifest: OssaAgent): Promise<void>;
+}
+```
+
+## Type Aliases
+
+### SchemaVersion
+
+```typescript
+export type SchemaVersion = string;
+```
+
+## Usage
+
+```typescript
+import { OSSAManifest, AgentSpec } from '@bluefly/openstandardagents';
+```

package/website/content/docs/use-cases/00-index.md

@@ -391,5 +391,5 @@ All use cases are provided under Apache 2.0 license. Implementation code may be
 ---
 
 **Last Updated**: November 2024
-**OSSA Version**: v0.2.3
+**OSSA Version**: v0.2.x
 **Status**: Production Ready

package/{docs/VERSIONING.md → website/content/docs/versioning.md}

@@ -1,3 +1,7 @@
+---
+title: "VERSIONING"
+---
+
 # OSSA Versioning Strategy
 
 ## Semantic Versioning with Semantic-Release
@@ -144,9 +148,9 @@ OSSA schema versions follow specification versions:
 ```
 Package Version  → Schema Directory
 -----------------------------------------
-v0.2.2          → spec/v0.2.2/
-v0.3.0          → spec/v0.3.0/
-v1.0.0          → spec/v1.0.0/
+v0.2.2          → spec/v0.2.6/
+v0.3.0          → spec/v0.2.6/
+v1.0.0          → spec/v0.2.6/
 ```
 
 ### Schema Compatibility
@@ -275,8 +279,8 @@ git commit -m "chore: update docs [skip ci]"
 ## Support
 
 - **Documentation**: [docs/](../docs/)
-- **Issues**: https://gitlab.bluefly.io/llm/openapi-ai-agents-standard/-/issues
-- **Releases**: https://gitlab.bluefly.io/llm/openapi-ai-agents-standard/-/releases
+- **Issues**: https://github.com/blueflyio/openstandardagents/issues
+- **Releases**: https://github.com/blueflyio/openstandardagents/releases
 
 ---
 

package/website/dev.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+# OSSA Website - Dev Server with OrbStack
+# Auto-detects worktree and sets unique domain
+#
+# Usage:
+#   cd website && ./dev.sh           # Start dev server
+#   cd website && ./dev.sh down      # Stop dev server
+#   cd website && ./dev.sh logs      # View logs
+
+set -e
+
+# Detect if we're in a worktree or main repo
+# Structure: /worktrees/<worktree-name>/website or /openstandardagents/website
+REPO_DIR=$(dirname "$PWD")
+REPO_NAME=$(basename "$REPO_DIR")
+PARENT_OF_REPO=$(basename "$(dirname "$REPO_DIR")")
+
+# Determine domain based on location
+if [ "$PARENT_OF_REPO" = "worktrees" ]; then
+  # In a worktree: use worktree name
+  DOMAIN="$REPO_NAME"
+elif [ "$REPO_NAME" = "openstandardagents" ]; then
+  # In main repo: ossa.orb.local
+  DOMAIN="ossa"
+else
+  DOMAIN="$REPO_NAME"
+fi
+
+export OSSA_DOMAIN="$DOMAIN"
+
+echo "🌐 Domain: https://${DOMAIN}.orb.local"
+echo ""
+
+case "${1:-up}" in
+  up|start)
+    docker compose -f docker-compose.dev.yml up -d
+    echo ""
+    echo "✅ Dev server starting at https://${DOMAIN}.orb.local"
+    echo "   Run './dev.sh logs' to view output"
+    ;;
+  down|stop)
+    docker compose -f docker-compose.dev.yml down
+    ;;
+  logs)
+    docker compose -f docker-compose.dev.yml logs -f
+    ;;
+  restart)
+    docker compose -f docker-compose.dev.yml restart
+    ;;
+  *)
+    echo "Usage: ./dev.sh [up|down|logs|restart]"
+    ;;
+esac

package/website/docker-compose.dev.yml

@@ -0,0 +1,36 @@
+# OSSA Website - Development with OrbStack
+# Works from any worktree - domain derived from parent directory name
+#
+# Usage:
+#   cd website && docker compose -f docker-compose.dev.yml up
+#
+# Domains:
+#   /openstandardagents/website     → ossa.orb.local (main repo)
+#   /worktrees/website-design       → website-design.orb.local
+#   /worktrees/ossa-97-sync-cli     → ossa-97-sync-cli.orb.local
+
+services:
+  ossa-dev:
+    image: node:22-alpine
+    working_dir: /app
+    command: sh -c "npm install --legacy-peer-deps && npm run dev"
+    ports:
+      - "3000"
+    volumes:
+      - .:/app
+      - node_modules:/app/node_modules
+      - ../examples:/examples:ro
+    environment:
+      - NODE_ENV=development
+      - WATCHPACK_POLLING=true
+    labels:
+      # OrbStack auto-domain: uses parent directory name
+      - "dev.orbstack.domains=${OSSA_DOMAIN:-ossa}.orb.local"
+    healthcheck:
+      test: ["CMD", "wget", "-q", "--spider", "http://localhost:3000"]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+
+volumes:
+  node_modules:

package/website/lib/version.ts

@@ -2,11 +2,28 @@
 // AUTO-GENERATED - DO NOT EDIT DIRECTLY
 // Update package.json version instead, then run: npm run sync-version
 
-export const OSSA_VERSION = "0.2.3";
+import versionsData from './versions.json';
+
+export const OSSA_VERSION = "0.2.6";
 export const OSSA_VERSION_TAG = `v${OSSA_VERSION}`;
 export const OSSA_API_VERSION = `ossa/v${OSSA_VERSION}`;
 export const OSSA_SCHEMA_VERSION = OSSA_VERSION;
 
+// Aliases for backward compatibility
+export const STABLE_VERSION = OSSA_VERSION;
+export const STABLE_VERSION_TAG = OSSA_VERSION_TAG;
+
+// Version data from versions.json
+export const STABLE_VERSIONS = versionsData.all.filter((v: any) => v.type === 'stable');
+export const DEV_VERSIONS = versionsData.all.filter((v: any) => v.type === 'dev' || v.type === 'prerelease');
+export const ALL_VERSIONS = versionsData.all;
+export const DEV_VERSION_TAG = versionsData.dev ? `v${versionsData.dev}` : undefined;
+
+// Utility to get version info
+export function getVersionInfo(version: string): any {
+  return versionsData.all.find((v: any) => v.version === version);
+}
+
 // Utility to get schema path
 export function getSchemaPath(ver = OSSA_VERSION): string {
   return `/schemas/ossa-${ver}.schema.json`;