npm - @bluefly/openstandardagents - Versions diffs - 0.3.3 → 0.3.5 - Mend

@bluefly/openstandardagents 0.3.3 → 0.3.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1236) hide show

package/dist/spec/v0.3.2/protocols/delegation.yaml DELETED Viewed

@@ -1,239 +0,0 @@
-# ============================================================================
-# OSSA Cross-Tier Delegation Protocol (Reference)
-# ============================================================================
-# Defines how agents delegate tasks across access tiers while maintaining
-# separation of duties and audit compliance.
-#
-# NOTE: This is a reference specification, not an OSSA manifest.
-# It documents the delegation protocol for implementation guidance.
-#
-# @see https://openstandardagents.org/spec/v0.3.3/access-tiers
-# ============================================================================
-# Specification metadata
-name: cross-tier-delegation
-version: 1.0.0
-description: "Protocol for delegating tasks between agents of different access tiers"
-# Delegation Matrix
-# =================
-# Defines which tiers can delegate to which other tiers
-# Key: source tier, Value: allowed target tiers
-delegation_matrix:
-  tier_1_read:
-    can_delegate_to:
-      - tier_1_read  # Peer delegation OK
-    cannot_delegate_to:
-      - tier_2_write_limited
-      - tier_3_write_elevated
-      - tier_4_policy
-    reason: "Read-only agents cannot initiate write operations"
-  tier_2_write_limited:
-    can_delegate_to:
-      - tier_1_read  # Can request analysis
-      - tier_2_write_limited  # Peer delegation OK
-    cannot_delegate_to:
-      - tier_3_write_elevated  # Cannot escalate privileges
-      - tier_4_policy  # Cannot influence policy
-    reason: "Limited write agents cannot escalate to elevated or policy tiers"
-  tier_3_write_elevated:
-    can_delegate_to:
-      - tier_1_read  # Can request analysis
-      - tier_2_write_limited  # Can request documentation
-      - tier_3_write_elevated  # Peer delegation with approval
-    cannot_delegate_to:
-      - tier_4_policy  # Executor/Governor separation
-    reason: "Operators cannot influence policy definitions"
-  tier_4_policy:
-    can_delegate_to:
-      - tier_1_read  # Can request compliance audits
-      - tier_4_policy  # Peer delegation for policy review
-    cannot_delegate_to:
-      - tier_2_write_limited  # Governor/Executor separation
-      - tier_3_write_elevated  # Governor/Executor separation
-    execution_only_via: "tier_3_write_elevated with approval chain"
-    reason: "Policy tier enforces separation - execution through operators only"
-# Delegation Request Schema
-delegation_request:
-  type: object
-  required:
-    - request_id
-    - source_agent
-    - target_agent
-    - task
-    - justification
-  properties:
-    request_id:
-      type: string
-      format: uuid
-      description: "Unique delegation request identifier"
-    source_agent:
-      type: object
-      required:
-        - agent_id
-        - tier
-      properties:
-        agent_id:
-          type: string
-        tier:
-          type: string
-          enum: [tier_1_read, tier_2_write_limited, tier_3_write_elevated, tier_4_policy]
-        session_id:
-          type: string
-    target_agent:
-      type: object
-      required:
-        - agent_id
-        - tier
-      properties:
-        agent_id:
-          type: string
-        tier:
-          type: string
-        capabilities_required:
-          type: array
-          items:
-            type: string
-    task:
-      type: object
-      required:
-        - type
-        - payload
-      properties:
-        type:
-          type: string
-          description: "Task type identifier"
-        payload:
-          type: object
-          description: "Task-specific payload"
-        timeout_seconds:
-          type: integer
-          default: 300
-        priority:
-          type: string
-          enum: [low, normal, high, critical]
-          default: normal
-    justification:
-      type: string
-      minLength: 10
-      description: "Reason for delegation (required for audit)"
-    context:
-      type: object
-      properties:
-        parent_request_id:
-          type: string
-          description: "Parent request if this is a sub-delegation"
-        trace_id:
-          type: string
-          description: "Distributed tracing ID"
-        workflow_id:
-          type: string
-          description: "Associated workflow if any"
-# Delegation Response Schema
-delegation_response:
-  type: object
-  required:
-    - request_id
-    - status
-    - timestamp
-  properties:
-    request_id:
-      type: string
-      format: uuid
-    status:
-      type: string
-      enum:
-        - accepted  # Delegation accepted, processing
-        - completed  # Task completed successfully
-        - rejected  # Delegation denied (tier violation, etc.)
-        - failed  # Task execution failed
-        - timeout  # Task timed out
-        - cancelled  # Delegation cancelled by source
-    error:
-      type: object
-      properties:
-        code:
-          type: string
-          enum:
-            - TIER_VIOLATION  # Delegation matrix violation
-            - CAPABILITY_MISSING  # Target lacks required capability
-            - APPROVAL_REQUIRED  # Needs human approval
-            - APPROVAL_DENIED  # Human rejected delegation
-            - TARGET_UNAVAILABLE  # Target agent not available
-            - EXECUTION_ERROR  # Task execution failed
-            - TIMEOUT  # Task exceeded timeout
-            - RESOURCE_EXHAUSTED  # Rate limit or quota exceeded
-        message:
-          type: string
-# Approval Chains for Elevated Delegations
-approval_chains:
-  standard:
-    description: "Standard approval for tier_3 operations"
-    approvers:
-      - role: team-lead
-      - role: security-reviewer
-    require: 1
-    timeout_hours: 4
-  elevated:
-    description: "Elevated approval for sensitive operations"
-    approvers:
-      - role: security-lead
-      - role: compliance-officer
-      - role: engineering-manager
-    require: 2
-    timeout_hours: 8
-    escalation:
-      after_hours: 2
-      to: [cto, ciso]
-  critical:
-    description: "Critical approval for production changes"
-    approvers:
-      - role: sre-lead
-      - role: security-lead
-      - role: release-manager
-    require: 2
-    timeout_hours: 24
-# Audit Requirements by Tier Combination
-audit_requirements:
-  tier_1_to_tier_1:
-    level: standard
-    retention_days: 30
-  tier_2_to_tier_1:
-    level: standard
-    retention_days: 30
-  tier_3_to_any:
-    level: detailed
-    retention_days: 90
-  tier_4_to_any:
-    level: comprehensive
-    retention_days: 365
-# Rate Limiting
-rate_limits:
-  per_source_agent:
-    requests_per_minute: 60
-    requests_per_hour: 1000
-  per_target_agent:
-    concurrent_delegations: 10
-    queue_depth: 50

package/dist/spec/v0.3.2/protocols/sse.md DELETED Viewed

@@ -1,494 +0,0 @@
-# Server-Sent Events (SSE) Transport Protocol
-## Overview
-Server-Sent Events (SSE) provides unidirectional server-to-client streaming over HTTP. This specification defines how OSSA agents use SSE for real-time event delivery, status updates, and streaming responses.
-## Connection Model
-SSE is a **one-way protocol**: server sends events to client. For bidirectional communication, combine SSE (server→client) with HTTP POST (client→server).
-```
-Client ─────POST───────> Server  (Commands/Requests)
-       <────SSE Events── Server  (Events/Responses)
-```
-## Connection Establishment
-### Client Connection
-```typescript
-const eventSource = new EventSource('https://agent.example.com/events', {
-  withCredentials: true
-});
-eventSource.addEventListener('message', (event) => {
-  const data = JSON.parse(event.data);
-  console.log('Received:', data);
-});
-eventSource.addEventListener('error', (error) => {
-  console.error('Connection error:', error);
-});
-```
-### Server Response Format
-```http
-HTTP/1.1 200 OK
-Content-Type: text/event-stream
-Cache-Control: no-cache, no-store, must-revalidate
-Connection: keep-alive
-X-Accel-Buffering: no
-data: {"type":"connected","timestamp":"2025-12-18T14:00:00Z"}
-```
-## Event Format
-### SSE Message Structure
-```
-event: <event-type>
-id: <message-id>
-retry: <reconnect-time-ms>
-data: <json-payload>
-```
-### OSSA Event Schema
-```typescript
-interface SSEEvent {
-  type: 'message' | 'status' | 'capability_response' | 'error';
-  id: string;                    // Unique event ID
-  timestamp: string;              // ISO 8601 timestamp
-  payload: unknown;               // Event-specific data
-  metadata: {
-    agentId: string;              // Source agent URI
-    streamId?: string;            // For multi-stream scenarios
-    correlationId?: string;       // Links to originating request
-    sequence?: number;            // Event sequence number
-    final?: boolean;              // Indicates last event in sequence
-  };
-}
-```
-## Event Types
-### 1. Message Event
-Standard event delivery:
-```
-event: message
-id: msg-123e4567-e89b-12d3-a456-426614174000
-data: {
-data:   "type": "message",
-data:   "timestamp": "2025-12-18T14:00:00Z",
-data:   "payload": {
-data:     "channel": "content.published",
-data:     "data": {"contentId": "node-123", "status": "published"}
-data:   },
-data:   "metadata": {
-data:     "agentId": "agent://example.com/publisher",
-data:     "sequence": 42
-data:   }
-data: }
-```
-### 2. Status Update
-Agent health and status streams:
-```
-event: status
-id: status-456e7890-a12b-34c5-d678-901234567890
-data: {
-data:   "type": "status",
-data:   "timestamp": "2025-12-18T14:00:00Z",
-data:   "payload": {
-data:     "status": "healthy",
-data:     "load": 0.45,
-data:     "uptime": 86400
-data:   },
-data:   "metadata": {
-data:     "agentId": "agent://example.com/worker-1"
-data:   }
-data: }
-```
-### 3. Capability Response
-Streaming response to capability invocation:
-```
-event: capability_response
-id: resp-789a0123-b45c-67d8-e901-234567890123
-data: {
-data:   "type": "capability_response",
-data:   "timestamp": "2025-12-18T14:00:00Z",
-data:   "payload": {
-data:     "capability": "analyze_content",
-data:     "result": {"sentiment": "positive", "score": 0.85}
-data:   },
-data:   "metadata": {
-data:     "agentId": "agent://example.com/analyzer",
-data:     "correlationId": "req-789",
-data:     "final": true
-data:   }
-data: }
-```
-### 4. Error Event
-Error notifications:
-```
-event: error
-id: err-234f5678-g90h-12i3-j456-789012345678
-data: {
-data:   "type": "error",
-data:   "timestamp": "2025-12-18T14:00:00Z",
-data:   "payload": {
-data:     "code": "PROCESSING_ERROR",
-data:     "message": "Failed to process request",
-data:     "retryable": true
-data:   },
-data:   "metadata": {
-data:     "agentId": "agent://example.com/agent",
-data:     "correlationId": "req-789"
-data:   }
-data: }
-```
-## Authentication
-### Bearer Token
-```typescript
-// Modern browsers
-const eventSource = new EventSource('https://agent.example.com/events', {
-  withCredentials: true
-});
-// Server sets cookie or client sends Authorization header
-// Note: EventSource doesn't support custom headers in browsers
-// Use cookie-based auth or proxy
-```
-### Query Parameter Authentication
-For environments without cookie support:
-```typescript
-const token = await getAuthToken();
-const eventSource = new EventSource(
-  `https://agent.example.com/events?token=${token}`
-);
-```
-## Reconnection and Reliability
-### Automatic Reconnection
-EventSource automatically reconnects with:
-- Default retry: 3 seconds
-- Server can customize via `retry` field
-```
-retry: 5000
-data: {"type":"message","payload":{...}}
-```
-### Last-Event-ID
-Client sends last received event ID on reconnect:
-```http
-GET /events HTTP/1.1
-Host: agent.example.com
-Last-Event-ID: msg-123e4567-e89b-12d3-a456-426614174000
-```
-Server resumes from that event:
-```typescript
-app.get('/events', (req, res) => {
-  const lastEventId = req.headers['last-event-id'];
-  // Replay events after lastEventId
-  if (lastEventId) {
-    const missedEvents = getEventsSince(lastEventId);
-    missedEvents.forEach(event => sendSSE(res, event));
-  }
-  // Continue with live events
-  streamLiveEvents(res);
-});
-```
-## Streaming Patterns
-### 1. Event Stream
-Continuous event delivery:
-```typescript
-// Server
-app.get('/events', (req, res) => {
-  res.setHeader('Content-Type', 'text/event-stream');
-  res.setHeader('Cache-Control', 'no-cache');
-  res.setHeader('Connection', 'keep-alive');
-  const sendEvent = (event: SSEEvent) => {
-    res.write(`event: ${event.type}\n`);
-    res.write(`id: ${event.id}\n`);
-    res.write(`data: ${JSON.stringify(event)}\n\n`);
-  };
-  // Subscribe to events
-  const subscription = eventBus.subscribe((event) => {
-    sendEvent(event);
-  });
-  req.on('close', () => {
-    subscription.unsubscribe();
-  });
-});
-```
-### 2. Request-Response Streaming
-Long-running capability execution:
-```typescript
-// Client initiates capability call via POST
-const response = await fetch('/capabilities/analyze', {
-  method: 'POST',
-  body: JSON.stringify({ contentId: 'node-123' })
-});
-const { streamId } = await response.json();
-// Subscribe to result stream
-const eventSource = new EventSource(`/events?stream=${streamId}`);
-eventSource.addEventListener('capability_response', (event) => {
-  const data = JSON.parse(event.data);
-  if (data.metadata.final) {
-    eventSource.close();
-    console.log('Final result:', data.payload.result);
-  } else {
-    console.log('Progress:', data.payload);
-  }
-});
-```
-### 3. Multiplexed Streams
-Multiple logical streams over one SSE connection:
-```typescript
-// Client subscribes to multiple channels
-const eventSource = new EventSource(
-  '/events?channels=content.published,user.login,agent.status'
-);
-eventSource.addEventListener('message', (event) => {
-  const data = JSON.parse(event.data);
-  switch (data.payload.channel) {
-    case 'content.published':
-      handleContentPublished(data);
-      break;
-    case 'user.login':
-      handleUserLogin(data);
-      break;
-    case 'agent.status':
-      handleAgentStatus(data);
-      break;
-  }
-});
-```
-## Heartbeat and Keepalive
-Server SHOULD send periodic comments to prevent connection timeout:
-```
-: heartbeat - 2025-12-18T14:00:00Z
-data: {"type":"message","payload":{...}}
-: heartbeat - 2025-12-18T14:01:00Z
-```
-Recommended heartbeat interval: 30 seconds
-## Error Handling
-### Connection Errors
-```typescript
-eventSource.addEventListener('error', (error) => {
-  if (eventSource.readyState === EventSource.CLOSED) {
-    console.log('Connection closed permanently');
-    // Implement custom reconnection logic if needed
-  } else {
-    console.log('Connection error, auto-reconnecting...');
-  }
-});
-```
-### Event Processing Errors
-```typescript
-eventSource.addEventListener('message', (event) => {
-  try {
-    const data = JSON.parse(event.data);
-    processEvent(data);
-  } catch (error) {
-    console.error('Failed to process event:', error);
-    // Log but don't close connection
-  }
-});
-```
-## Performance Considerations
-### Buffering
-Disable buffering for real-time delivery:
-```http
-X-Accel-Buffering: no
-```
-Nginx:
-```nginx
-location /events {
-  proxy_pass http://backend;
-  proxy_buffering off;
-  proxy_cache off;
-}
-```
-### Connection Limits
-- Browser limit: 6 connections per domain
-- Use single SSE connection per domain
-- Multiplex channels over one connection
-### Memory Management
-Server SHOULD:
-1. Limit event buffer size (e.g., last 100 events)
-2. Implement event expiry (e.g., 5 minutes)
-3. Track active connections and enforce limits
-## Security Considerations
-1. **HTTPS Required** - Always use HTTPS in production
-2. **CORS** - Configure proper CORS headers
-3. **Authentication** - Use cookie-based or query param auth
-4. **Rate Limiting** - Limit events per connection
-5. **Event Filtering** - Only send events user has permission to see
-```http
-Access-Control-Allow-Origin: https://trusted-domain.com
-Access-Control-Allow-Credentials: true
-```
-## Bidirectional Communication
-Combine SSE with HTTP POST for bidirectional flow:
-```typescript
-// Client sends command
-const response = await fetch('/capabilities/process', {
-  method: 'POST',
-  body: JSON.stringify({ data: 'input' })
-});
-const { taskId } = await response.json();
-// Server streams progress via SSE
-const eventSource = new EventSource(`/events?task=${taskId}`);
-eventSource.addEventListener('capability_response', (event) => {
-  const data = JSON.parse(event.data);
-  updateProgress(data.payload);
-  if (data.metadata.final) {
-    eventSource.close();
-  }
-});
-```
-## Examples
-### Real-time Status Dashboard
-```typescript
-// Server
-app.get('/agent-status', (req, res) => {
-  res.setHeader('Content-Type', 'text/event-stream');
-  res.setHeader('Cache-Control', 'no-cache');
-  res.setHeader('Connection', 'keep-alive');
-  const interval = setInterval(() => {
-    const status = {
-      type: 'status',
-      id: uuid(),
-      timestamp: new Date().toISOString(),
-      payload: {
-        activeAgents: getActiveAgentCount(),
-        queueDepth: getQueueDepth(),
-        throughput: getThroughput()
-      },
-      metadata: {
-        agentId: 'agent://example.com/monitor'
-      }
-    };
-    res.write(`event: status\n`);
-    res.write(`id: ${status.id}\n`);
-    res.write(`data: ${JSON.stringify(status)}\n\n`);
-  }, 5000);
-  req.on('close', () => clearInterval(interval));
-});
-// Client
-const eventSource = new EventSource('/agent-status');
-eventSource.addEventListener('status', (event) => {
-  const status = JSON.parse(event.data);
-  updateDashboard(status.payload);
-});
-```
-## Compatibility
-- Protocol: SSE (HTML5 EventSource API)
-- Content-Type: `text/event-stream`
-- Character encoding: UTF-8
-- Browser support: All modern browsers
-- Fallback: Long-polling for older browsers
-## References
-- [HTML5 Server-Sent Events](https://html.spec.whatwg.org/multipage/server-sent-events.html)
-- [MDN EventSource API](https://developer.mozilla.org/en-US/docs/Web/API/EventSource)
-- [OSSA Message Envelope Specification](../messaging.md)