@bluefly/openstandardagents 0.3.1 → 0.3.3

package/dist/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.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.0 → v0.3.2}/protocols/websocket.md

@@ -18,7 +18,7 @@ ws.onopen = () => {
     type: 'register',
     agentId: 'agent://example.com/my-agent',
     capabilities: ['process_data', 'analyze_content'],
-    version: 'ossa/v0.3.0'
+    version: 'ossa/v0.3.3'
   }));
 };
 ```
@@ -352,7 +352,7 @@ ws.send(JSON.stringify({
 
 - WebSocket protocol version: RFC 6455
 - Minimum TLS version: 1.2
-- Supported subprotocols: `ossa.v0.3.0`
+- Supported subprotocols: `ossa.v0.3.3`
 - JSON payload encoding: UTF-8
 
 ## References

package/dist/spec/v0.3.2/runtime/RUNTIME.md

@@ -0,0 +1,457 @@
+# OSSA v0.3.3 Runtime Specification
+
+This document provides human-readable documentation for the OSSA Agent Runtime Specification, which defines how agents execute, communicate, and manage state.
+
+## Overview
+
+The runtime specification consists of two main components:
+
+1. **runtime.yaml** - Core runtime behavior including lifecycle, control signals, execution model, and network isolation
+2. **memory-model.yaml** - Memory management including short-term and long-term storage
+
+## Agent Lifecycle
+
+All OSSA agents follow a standard 5-phase lifecycle:
+
+```
+init -> plan -> act -> reflect -> terminate
+                 ^         |
+                 |         v
+                 +---------+
+               (iteration loop)
+```
+
+### Phase Descriptions
+
+#### 1. Init Phase
+**Purpose**: Prepare the agent for execution
+
+**Activities**:
+- Load configuration and credentials
+- Establish connections to tools and services
+- Validate input parameters
+- Set up logging and telemetry
+
+**Default Timeout**: 30 seconds
+
+**Success Signal**: `ready`
+
+#### 2. Plan Phase
+**Purpose**: Analyze task and generate execution strategy
+
+**Activities**:
+- Analyze the task/goal
+- Retrieve relevant context from memory
+- Generate execution plan
+- Determine required tools and delegations
+
+**Default Timeout**: 60 seconds
+
+**Success Signal**: `plan_ready`
+
+#### 3. Act Phase
+**Purpose**: Execute the planned actions
+
+**Activities**:
+- Execute planned steps
+- Make tool calls
+- Delegate to sub-agents
+- Produce artifacts/outputs
+
+**Default Timeout**: 300 seconds
+
+**Success Signal**: `action_complete`
+
+#### 4. Reflect Phase
+**Purpose**: Evaluate results and decide next steps
+
+**Activities**:
+- Evaluate action results
+- Update memory with learnings
+- Determine if goal is achieved
+- Decide on iteration or termination
+
+**Default Timeout**: 30 seconds
+
+**Success Signal**: `reflection_complete`
+
+#### 5. Terminate Phase
+**Purpose**: Clean up and finalize
+
+**Activities**:
+- Finalize outputs
+- Persist state to long-term memory
+- Release resources
+- Emit completion telemetry
+
+**Default Timeout**: 15 seconds
+
+**Success Signal**: `terminated`
+
+### Lifecycle Transitions
+
+| From | To | Condition |
+|------|-----|-----------|
+| init | plan | `ready` signal received |
+| plan | act | `plan_ready` signal received |
+| act | reflect | `action_complete` signal received |
+| reflect | act | `iteration_needed` (goal not yet achieved) |
+| reflect | terminate | `goal_achieved` |
+| any | terminate | `halt_signal` or `error_unrecoverable` |
+
+### Iteration Control
+
+- **max_iterations**: Maximum plan-act-reflect cycles (default: 10)
+- **total_timeout_seconds**: Maximum total execution time (default: 3600)
+
+## Control Signals
+
+Control signals are the standard communication primitives between agents, runtimes, and external systems.
+
+### Standard Signals
+
+#### tool_call
+Invoke an external tool or capability.
+
+```yaml
+type: tool_call
+async: true
+timeout_seconds: 60
+payload:
+  tool_name: "security_scan"
+  parameters:
+    path: "/src"
+    severity: "high"
+  correlation_id: "uuid"
+```
+
+#### delegation
+Delegate work to another agent.
+
+```yaml
+type: delegation
+async: true
+timeout_seconds: 300
+payload:
+  target_agent: "code-review-agent"
+  task:
+    action: "review"
+    files: ["src/main.py"]
+  context:
+    pr_number: 123
+  callback: "https://callback.example.com/results"
+```
+
+#### halt
+Immediately stop agent execution.
+
+```yaml
+type: halt
+async: false
+timeout_seconds: 5
+payload:
+  reason: "user_interrupt"  # or: resource_limit, policy_violation, external_signal, parent_termination
+  graceful: true
+  message: "User requested cancellation"
+```
+
+#### error
+Indicate an error condition.
+
+```yaml
+type: error
+async: false
+payload:
+  error_code: "TOOL_ERROR"  # INIT_FAILED, PLAN_FAILED, ACTION_FAILED, etc.
+  message: "Tool execution failed"
+  recoverable: false
+  details:
+    tool: "security_scan"
+    exit_code: 1
+```
+
+#### ready
+Signal that agent is ready for work.
+
+```yaml
+type: ready
+payload:
+  capabilities:
+    - "security_scan"
+    - "code_review"
+  version: "1.0.0"
+```
+
+#### heartbeat
+Periodic liveness signal.
+
+```yaml
+type: heartbeat
+interval_seconds: 30
+payload:
+  timestamp: "2024-01-15T10:30:00Z"
+  phase: "act"
+  metrics:
+    memory_mb: 256
+    cpu_percent: 15
+```
+
+## Execution Model
+
+### Timeout Configuration
+
+Multiple timeout levels protect against runaway executions:
+
+| Timeout | Default | Range | Description |
+|---------|---------|-------|-------------|
+| default_seconds | 300 | 1-3600 | Default operation timeout |
+| llm_call_seconds | 60 | 5-300 | LLM API call timeout |
+| tool_call_seconds | 60 | 1-600 | Tool invocation timeout |
+| delegation_seconds | 300 | 30-3600 | Agent delegation timeout |
+
+### Sandbox Configuration
+
+Agents run in isolated sandboxes to prevent unauthorized access:
+
+```yaml
+sandbox:
+  enabled: true
+  type: container  # or: vm, wasm, process, none
+  filesystem:
+    read_paths:
+      - /app/data
+    write_paths:
+      - /app/output
+    deny_paths:
+      - /etc/passwd
+      - /etc/shadow
+      - ~/.ssh
+      - ~/.aws
+  capabilities: []  # Linux capabilities
+  syscall_filter: default  # strict, default, permissive
+```
+
+### Resource Limits
+
+```yaml
+resource_limits:
+  memory_mb: 512
+  cpu_millicores: 1000
+  gpu_memory_mb: 0
+  max_open_files: 256
+  max_processes: 10
+  max_network_connections: 50
+```
+
+## Network Isolation Model
+
+### Isolation Modes
+
+| Mode | Description |
+|------|-------------|
+| strict | No network access except explicitly allowed |
+| namespace | Isolated network namespace per agent |
+| mesh | Service mesh with controlled inter-agent communication |
+| none | No network isolation (development only) |
+
+### Egress Rules
+
+Control outbound traffic:
+
+```yaml
+egress:
+  allowed_domains:
+    - api.openai.com
+    - api.anthropic.com
+    - "*.googleapis.com"
+  blocked_domains: []
+  allowed_ports:
+    - 443
+    - 80
+  rate_limit:
+    requests_per_second: 100
+    bytes_per_second: 10485760  # 10 MB/s
+```
+
+### Ingress Rules
+
+Control inbound traffic:
+
+```yaml
+ingress:
+  allowed_sources:
+    - "10.0.0.0/8"
+    - "agent-orchestrator"
+  allowed_ports:
+    - 8080
+    - 8443
+  require_mtls: true
+```
+
+### Agent Mesh
+
+Configuration for agent-to-agent communication:
+
+```yaml
+agent_mesh:
+  enabled: true
+  discovery: kubernetes  # or: dns, consul, static
+  encryption: mtls       # or: none, tls, wireguard
+  allowed_agents:
+    - security-scanner
+    - code-reviewer
+  denied_agents: []
+```
+
+## Memory Model
+
+### Short-Term Memory
+
+Volatile memory for immediate context:
+
+#### Conversation Context
+- Maximum messages: 100 (default)
+- Maximum tokens: 32,000 (default)
+- Truncation strategies: sliding_window, summarize, oldest_first, importance_based
+
+#### Working Memory
+- Scratchpad for intermediate computations
+- Maximum size: 64 MB (default)
+- TTL: 3600 seconds (default)
+
+#### Session State
+- Session-level state management
+- Session TTL: 3600 seconds (default)
+- Maximum concurrent sessions: 100 (default)
+
+### Long-Term Memory
+
+Persistent storage for knowledge and state:
+
+#### Supported Providers
+- Relational: postgres, sqlite
+- Document: mongodb, dynamodb
+- Vector: qdrant, pinecone, weaviate, chromadb, milvus
+- Graph: neo4j
+- Hybrid: postgres with pgvector
+
+#### Knowledge Base
+- Schema format: JSON Schema or RDF
+- Versioning enabled by default
+- Maximum entries: 100,000 (default)
+
+#### Vector Store
+- Embedding model: configurable (default: text-embedding-3-small)
+- Dimensions: 1536 (default)
+- Distance metric: cosine, euclidean, or dot_product
+- Index type: hnsw, flat, ivf, scann
+
+#### Conversation History
+- Retention: 90 days (default)
+- Indexing for search
+- Auto-summarization of old conversations
+
+#### Agent State
+- Checkpoint interval: 60 seconds (default)
+- Maximum checkpoints: 10 (default)
+- Compression enabled by default
+
+### Memory Provider Interface
+
+All memory providers MUST implement these operations:
+
+| Operation | Description | Required |
+|-----------|-------------|----------|
+| get | Retrieve entry by key | Yes |
+| set | Store entry | Yes |
+| delete | Remove entry | Yes |
+| exists | Check if key exists | Yes |
+| list | List keys matching pattern | Yes |
+| clear | Clear namespace | Yes |
+| search | Semantic search (vector) | No |
+| batch_get | Retrieve multiple entries | No |
+| batch_set | Store multiple entries | No |
+| expire | Set expiration | No |
+| increment | Atomic increment | No |
+
+### Memory Lifecycle
+
+#### Garbage Collection
+- Strategies: lru, lfu, ttl, size_based, hybrid
+- Run interval: 3600 seconds (default)
+- Trigger threshold: 80% memory usage
+
+#### Backup
+- Interval: 24 hours (default)
+- Retention: 7 backups (default)
+- Encryption enabled by default
+
+#### Compaction
+- Fragmentation threshold: 30%
+- Run interval: 24 hours (default)
+
+## Example Configuration
+
+```yaml
+apiVersion: ossa/v0.3.3
+kind: RuntimeSpec
+
+lifecycle:
+  phases:
+    init:
+      timeout_seconds: 30
+    plan:
+      timeout_seconds: 60
+    act:
+      timeout_seconds: 300
+    reflect:
+      timeout_seconds: 30
+    terminate:
+      timeout_seconds: 15
+  max_iterations: 10
+
+control_signals:
+  tool_call:
+    async: true
+    timeout_seconds: 60
+  delegation:
+    async: true
+    timeout_seconds: 300
+
+execution:
+  timeout:
+    default_seconds: 300
+    llm_call_seconds: 60
+  sandbox:
+    enabled: true
+    type: container
+  resource_limits:
+    memory_mb: 512
+    cpu_millicores: 1000
+
+network_isolation:
+  enabled: true
+  mode: namespace
+  egress:
+    allowed_domains:
+      - api.openai.com
+      - api.anthropic.com
+    allowed_ports:
+      - 443
+  agent_mesh:
+    enabled: true
+    encryption: mtls
+```
+
+## Related Specifications
+
+- [Agent Unified Schema](../schemas/agent-unified.yaml) - Agent manifest specification
+- [Runtime Binding](../schemas/runtime.yaml) - Runtime declaration in manifests
+- [Capabilities Schema](../schemas/capabilities.yaml) - Capability declarations
+- [Access Tiers](../access_tiers.yaml) - Permission and access control
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 0.3.3 | 2024-01 | Initial runtime specification with lifecycle, control signals, execution model, network isolation, and memory model |