@bluefly/openstandardagents 0.3.3 → 0.3.5

package/dist/spec/v0.3.1/protocols/websocket.md

@@ -1,362 +0,0 @@
-# WebSocket Transport Protocol
-
-## Overview
-
-WebSocket transport enables bidirectional, real-time communication between OSSA agents over persistent connections. This specification defines how agents use WebSocket connections for agent-to-agent messaging, capability calls, and status updates.
-
-## Connection Lifecycle
-
-### Connection Establishment
-
-```typescript
-// Client initiates connection
-const ws = new WebSocket('wss://agent.example.com/ws');
-
-// Send agent registration on connect
-ws.onopen = () => {
-  ws.send(JSON.stringify({
-    type: 'register',
-    agentId: 'agent://example.com/my-agent',
-    capabilities: ['process_data', 'analyze_content'],
-    version: 'ossa/v0.3.1'
-  }));
-};
-```
-
-### Authentication
-
-WebSocket connections MUST authenticate using one of:
-
-1. **Bearer Token** - Include in initial HTTP upgrade request
-2. **Query Parameter** - For restricted environments: `?token=<jwt>`
-3. **Message-based Auth** - Send auth message after connection
-
-```http
-GET /ws HTTP/1.1
-Host: agent.example.com
-Upgrade: websocket
-Connection: Upgrade
-Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
-Sec-WebSocket-Version: 13
-Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
-```
-
-### Heartbeat/Keepalive
-
-Agents MUST implement ping/pong to maintain connection health:
-
-- Server sends `ping` every 30 seconds
-- Client responds with `pong` within 5 seconds
-- Connection closes after 3 missed pongs
-
-```json
-// Server ping
-{"type": "ping", "timestamp": "2025-12-18T14:00:00Z"}
-
-// Client pong
-{"type": "pong", "timestamp": "2025-12-18T14:00:00Z"}
-```
-
-## Message Format
-
-### Base Message Structure
-
-```typescript
-interface WebSocketEvent {
-  type: 'message' | 'capability_call' | 'status_update' | 'error' | 'ack';
-  id: string;                    // Unique message ID (UUID)
-  timestamp: string;              // ISO 8601 timestamp
-  payload: unknown;               // Message-specific payload
-  metadata: {
-    agentId: string;              // Sender agent URI
-    correlationId?: string;       // For request/response matching
-    replyTo?: string;             // WebSocket connection ID for responses
-    priority?: 'low' | 'normal' | 'high' | 'critical';
-    ttl?: number;                 // Time-to-live in seconds
-  };
-}
-```
-
-### Message Types
-
-#### 1. Message Event
-
-Pub/sub style message broadcast:
-
-```json
-{
-  "type": "message",
-  "id": "msg-123e4567-e89b-12d3-a456-426614174000",
-  "timestamp": "2025-12-18T14:00:00Z",
-  "payload": {
-    "channel": "content.published",
-    "data": {
-      "contentId": "node-123",
-      "title": "New Article",
-      "status": "published"
-    }
-  },
-  "metadata": {
-    "agentId": "agent://example.com/publisher",
-    "priority": "normal"
-  }
-}
-```
-
-#### 2. Capability Call
-
-RPC-style capability invocation:
-
-```json
-{
-  "type": "capability_call",
-  "id": "call-456e7890-a12b-34c5-d678-901234567890",
-  "timestamp": "2025-12-18T14:00:00Z",
-  "payload": {
-    "capability": "analyze_content",
-    "input": {
-      "contentId": "node-123",
-      "analysisType": "sentiment"
-    }
-  },
-  "metadata": {
-    "agentId": "agent://example.com/analyzer",
-    "correlationId": "req-789",
-    "replyTo": "ws-conn-abc123"
-  }
-}
-```
-
-#### 3. Status Update
-
-Agent health and status broadcasts:
-
-```json
-{
-  "type": "status_update",
-  "id": "status-901e2345-f67g-89h0-i123-456789012345",
-  "timestamp": "2025-12-18T14:00:00Z",
-  "payload": {
-    "status": "healthy",
-    "load": 0.45,
-    "activeConnections": 12,
-    "capabilities": ["process_data", "analyze_content"]
-  },
-  "metadata": {
-    "agentId": "agent://example.com/worker-1"
-  }
-}
-```
-
-#### 4. Error Event
-
-Error notifications:
-
-```json
-{
-  "type": "error",
-  "id": "err-234f5678-g90h-12i3-j456-789012345678",
-  "timestamp": "2025-12-18T14:00:00Z",
-  "payload": {
-    "code": "CAPABILITY_NOT_FOUND",
-    "message": "Capability 'unknown_capability' not found",
-    "details": {
-      "requestedCapability": "unknown_capability",
-      "availableCapabilities": ["process_data", "analyze_content"]
-    }
-  },
-  "metadata": {
-    "agentId": "agent://example.com/agent",
-    "correlationId": "req-789"
-  }
-}
-```
-
-#### 5. Acknowledgment
-
-Message delivery confirmation:
-
-```json
-{
-  "type": "ack",
-  "id": "ack-567g8901-h23i-45j6-k789-012345678901",
-  "timestamp": "2025-12-18T14:00:00Z",
-  "payload": {
-    "messageId": "msg-123e4567-e89b-12d3-a456-426614174000",
-    "status": "received"
-  },
-  "metadata": {
-    "agentId": "agent://example.com/receiver"
-  }
-}
-```
-
-## Error Handling
-
-### Reconnection Strategy
-
-Clients MUST implement exponential backoff for reconnection:
-
-```typescript
-const reconnect = (attempt: number) => {
-  const delay = Math.min(1000 * Math.pow(2, attempt), 30000);
-  setTimeout(() => connectWebSocket(), delay);
-};
-```
-
-### Connection Loss
-
-On connection loss:
-
-1. Client buffers outgoing messages (up to configured limit)
-2. Client attempts reconnection with exponential backoff
-3. On reconnect, client reregisters and resends buffered messages
-4. Messages older than TTL are discarded
-
-### Error Codes
-
-| Code | Description | Action |
-|------|-------------|--------|
-| `AUTH_FAILED` | Authentication failed | Refresh token and reconnect |
-| `CAPABILITY_NOT_FOUND` | Unknown capability | Check capability registration |
-| `RATE_LIMIT_EXCEEDED` | Too many messages | Implement backoff |
-| `PAYLOAD_TOO_LARGE` | Message exceeds size limit | Reduce payload or use chunking |
-| `PROTOCOL_ERROR` | Invalid message format | Fix message structure |
-
-## Message Ordering
-
-WebSocket transport provides **ordered delivery** per connection:
-
-- Messages sent on the same connection arrive in order
-- No ordering guarantees across different connections
-- Use `correlationId` for request/response matching
-
-## Reliability Features
-
-### At-Least-Once Delivery
-
-Implement using acknowledgments:
-
-```typescript
-// Sender waits for ACK
-const sendWithAck = async (message: WebSocketEvent) => {
-  ws.send(JSON.stringify(message));
-
-  return new Promise((resolve, reject) => {
-    const timeout = setTimeout(() => {
-      reject(new Error('ACK timeout'));
-    }, 5000);
-
-    ackHandlers.set(message.id, () => {
-      clearTimeout(timeout);
-      resolve();
-    });
-  });
-};
-```
-
-### Message Deduplication
-
-Receivers SHOULD track message IDs to prevent duplicate processing:
-
-```typescript
-const processedMessages = new Set<string>();
-
-ws.onmessage = (event) => {
-  const message = JSON.parse(event.data);
-
-  if (processedMessages.has(message.id)) {
-    return; // Duplicate, skip
-  }
-
-  processedMessages.add(message.id);
-  processMessage(message);
-
-  // Send ACK
-  ws.send(JSON.stringify({
-    type: 'ack',
-    payload: { messageId: message.id, status: 'received' }
-  }));
-};
-```
-
-## Security Considerations
-
-1. **TLS Required** - MUST use `wss://` in production
-2. **Token Expiry** - JWT tokens SHOULD have short expiry (15 minutes)
-3. **Rate Limiting** - Server SHOULD limit messages per connection
-4. **Message Size** - Server SHOULD enforce max message size (1MB default)
-5. **Origin Validation** - Server MUST validate `Origin` header
-
-## Performance Tuning
-
-### Message Batching
-
-For high-throughput scenarios, batch multiple messages:
-
-```json
-{
-  "type": "batch",
-  "messages": [
-    {"type": "message", "payload": {...}},
-    {"type": "message", "payload": {...}}
-  ]
-}
-```
-
-### Compression
-
-Enable WebSocket compression (permessage-deflate):
-
-```http
-Sec-WebSocket-Extensions: permessage-deflate; client_max_window_bits
-```
-
-## Examples
-
-### Agent-to-Agent Communication
-
-```typescript
-// Agent A sends capability call to Agent B
-ws.send(JSON.stringify({
-  type: 'capability_call',
-  id: uuid(),
-  timestamp: new Date().toISOString(),
-  payload: {
-    capability: 'process_data',
-    input: { data: [1, 2, 3] }
-  },
-  metadata: {
-    agentId: 'agent://example.com/agent-a',
-    correlationId: 'req-123',
-    replyTo: 'ws-conn-abc'
-  }
-}));
-
-// Agent B responds
-ws.send(JSON.stringify({
-  type: 'message',
-  id: uuid(),
-  timestamp: new Date().toISOString(),
-  payload: {
-    result: { processed: true, count: 3 }
-  },
-  metadata: {
-    agentId: 'agent://example.com/agent-b',
-    correlationId: 'req-123'
-  }
-}));
-```
-
-## Compatibility
-
-- WebSocket protocol version: RFC 6455
-- Minimum TLS version: 1.2
-- Supported subprotocols: `ossa.v0.3.1`
-- JSON payload encoding: UTF-8
-
-## References
-
-- [RFC 6455 - The WebSocket Protocol](https://tools.ietf.org/html/rfc6455)
-- [OSSA Message Envelope Specification](../messaging.md)
-- [Agent Discovery Protocol](../discovery.md)

package/dist/spec/v0.3.1/schemas/agent-unified.yaml

@@ -1,165 +0,0 @@
-# OSSA v0.3.1 - Unified Agent Schema
-# Universal agent platform: OSSA + GitLab Duo + Google A2A + MCP
-# Zero hardcoded models, runtime-agnostic, infrastructure-driven
-
-apiVersion: ossa/v0.3.1
-kind: Agent
-
-metadata:
-  name: string
-  version: string  # semver
-  description: string
-  labels:
-    domain: string
-    capability: string
-    runtime: string
-
-spec:
-  # ============================================
-  # UNIFIED LLM CONFIGURATION
-  # No hardcoded models, runtime-configurable
-  # ============================================
-  llm:
-    provider: ${LLM_PROVIDER:-anthropic}
-    model: ${LLM_MODEL:-claude-sonnet}
-    profile: ${LLM_PROFILE:-balanced}  # NEW: A2A compatible
-    temperature: ${LLM_TEMPERATURE:-0.1}
-    maxTokens: ${LLM_MAX_TOKENS:-16000}
-    topP: ${LLM_TOP_P:-0.9}
-
-    fallback_models:
-      - provider: ${LLM_FALLBACK_PROVIDER_1:-openai}
-        model: ${LLM_FALLBACK_MODEL_1:-gpt-4o}
-        condition: on_error
-      - provider: ${LLM_FALLBACK_PROVIDER_2:-google}
-        model: ${LLM_FALLBACK_MODEL_2:-gemini-2.0-flash}
-        condition: on_rate_limit
-
-    retry_config:
-      max_attempts: ${LLM_RETRY_ATTEMPTS:-3}
-      backoff_strategy: ${LLM_BACKOFF_STRATEGY:-exponential}
-
-  # ============================================
-  # EXECUTION PROFILES (Google A2A)
-  # Task-specific optimization
-  # ============================================
-  execution_profile:
-    default: ${LLM_PROFILE:-balanced}
-    profiles:
-      fast:
-        maxTokens: 4000
-        temperature: 0.0
-        description: "Quick responses for triage"
-      balanced:
-        maxTokens: 16000
-        temperature: 0.1
-        description: "General agent operations"
-      deep:
-        maxTokens: 32000
-        temperature: 0.2
-        reasoning_enabled: true
-        description: "Deep analysis and reasoning"
-      safe:
-        temperature: 0.0
-        validation_required: true
-        audit_log: true
-        description: "Compliance and security"
-
-  # ============================================
-  # RUNTIME DECLARATION (Multi-platform)
-  # ============================================
-  runtime:
-    type: ${AGENT_RUNTIME:-unified}
-    supports:
-      - google-a2a
-      - gitlab-duo
-      - ossa-mesh
-      - mcp
-      - local-execution
-    scheduling:
-      strategy: ${AGENT_SCHEDULING:-fair}
-      priority: ${AGENT_PRIORITY:-normal}
-      max_concurrent: ${AGENT_MAX_CONCURRENT:-10}
-      timeout_seconds: ${AGENT_TIMEOUT:-300}
-    resource_limits:
-      memory_mb: ${AGENT_MEMORY_MB:-512}
-      cpu_millicores: ${AGENT_CPU_MILLICORES:-500}
-
-  # ============================================
-  # CAPABILITIES (A2A/Duo compatible)
-  # ============================================
-  capabilities:
-    - name: ${CAPABILITY_SCAN:-security_scan}
-      type: action
-      runtime: llm
-      description: "Run security analysis"
-      input_schema:
-        type: object
-        required: [path]
-        properties:
-          path:
-            type: string
-          severity:
-            type: string
-            enum: [low, medium, high, critical]
-
-  # ============================================
-  # FUNCTIONS (A2A format)
-  # OpenAI-style function calling
-  # ============================================
-  functions:
-    - name: scan_security
-      description: "Run OSSA security analysis"
-      parameters:
-        type: object
-        properties:
-          path:
-            type: string
-            description: "Path to scan"
-          severity:
-            type: string
-            enum: [low, medium, high, critical]
-        required: [path]
-      returns:
-        type: object
-        properties:
-          findings:
-            type: array
-          score:
-            type: number
-
-  # ============================================
-  # EXTENSIONS (A2A compatible)
-  # ============================================
-  extensions:
-    - type: http
-      name: ossa-mesh
-      endpoint: ${OSSA_MESH_URL}
-      credentials_ref: OSSA_MESH_TOKEN
-    - type: mcp
-      name: gitlab-mcp
-      endpoint: ${GITLAB_MCP_URL}
-      credentials_ref: GITLAB_TOKEN
-
-  # ============================================
-  # EXISTING OSSA FEATURES
-  # ============================================
-  role: string
-  taxonomy:
-    domain: string
-    subdomain: string
-    capability: string
-
-  tools:
-    - name: string
-      description: string
-      source:
-        type: mcp
-        uri: string
-
-  knowledge_graph:
-    enabled: boolean
-    provider: string
-    connection:
-      endpoint: string
-      credentials_ref: string

package/dist/spec/v0.3.1/schemas/capabilities.yaml

@@ -1,102 +0,0 @@
-# OSSA v0.3.1 - Capabilities Schema
-# Google A2A and GitLab Duo compatible capability declarations
-
-$schema: http://json-schema.org/draft-07/schema#
-$id: https://openstandardagents.org/schemas/v0.3.1/capabilities.yaml
-
-title: Agent Capabilities
-description: |
-  Structured capability declarations compatible with Google A2A and GitLab Duo.
-  Maps agent actions to callable functions.
-
-type: array
-items:
-  type: object
-  required:
-    - name
-    - type
-  properties:
-    name:
-      type: string
-      description: Capability identifier
-      pattern: ^[a-z][a-z0-9_]*$
-      examples:
-        - security_scan
-        - code_review
-        - deploy_service
-        - analyze_logs
-
-    type:
-      type: string
-      description: Capability type
-      enum:
-        - action
-        - query
-        - transform
-        - validation
-        - orchestration
-
-    runtime:
-      type: string
-      description: Execution runtime
-      enum:
-        - llm
-        - code
-        - hybrid
-        - external
-      default: llm
-
-    description:
-      type: string
-      description: Human-readable capability description
-
-    input_schema:
-      type: object
-      description: JSON Schema for input validation
-
-    output_schema:
-      type: object
-      description: JSON Schema for output validation
-
-    requires:
-      type: array
-      description: Required dependencies
-      items:
-        type: string
-
-    timeout_seconds:
-      type: integer
-      description: Capability-specific timeout
-      default: 60
-
-    retry_policy:
-      type: object
-      properties:
-        max_attempts:
-          type: integer
-          default: 3
-        backoff:
-          type: string
-          enum: [exponential, linear, constant]
-
-examples:
-  - name: security_scan
-    type: action
-    runtime: hybrid
-    description: Run OSSA security analysis on codebase
-    input_schema:
-      type: object
-      required: [path]
-      properties:
-        path:
-          type: string
-        severity:
-          type: string
-          enum: [low, medium, high, critical]
-    output_schema:
-      type: object
-      properties:
-        findings:
-          type: array
-        score:
-          type: number

package/dist/spec/v0.3.1/schemas/functions.yaml

@@ -1,75 +0,0 @@
-# OSSA v0.3.1 - Functions Schema
-# Google A2A compatible function declarations (OpenAI function calling format)
-
-$schema: http://json-schema.org/draft-07/schema#
-$id: https://openstandardagents.org/schemas/v0.3.1/functions.yaml
-
-title: Agent Functions
-description: |
-  Function declarations in Google A2A / OpenAI format.
-  Enables structured function calling across all runtimes.
-
-type: array
-items:
-  type: object
-  required:
-    - name
-    - description
-    - parameters
-  properties:
-    name:
-      type: string
-      description: Function name
-      pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
-
-    description:
-      type: string
-      description: What the function does
-
-    parameters:
-      type: object
-      description: JSON Schema for function parameters
-      required:
-        - type
-        - properties
-      properties:
-        type:
-          type: string
-          const: object
-        properties:
-          type: object
-        required:
-          type: array
-          items:
-            type: string
-
-    returns:
-      type: object
-      description: Return value schema
-
-    strict:
-      type: boolean
-      description: Enforce strict schema validation
-      default: true
-
-examples:
-  - name: scan_security
-    description: Run OSSA security analysis
-    parameters:
-      type: object
-      properties:
-        path:
-          type: string
-          description: Path to scan
-        severity:
-          type: string
-          enum: [low, medium, high, critical]
-          description: Minimum severity level
-      required: [path]
-    returns:
-      type: object
-      properties:
-        findings:
-          type: array
-        score:
-          type: number