@bluefly/openstandardagents 0.3.0 → 0.3.2

package/spec/v0.3.2/protocols/delegation.yaml

@@ -0,0 +1,239 @@
+# ============================================================================
+# 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.2/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/spec/v0.3.2/protocols/sse.md

@@ -0,0 +1,494 @@
+# 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)