ciris-agent 1.7.7__py3-none-any.whl

ciris_engine/schemas/covenant.py

@@ -0,0 +1,382 @@
+"""
+Covenant Invocation System Schemas.
+
+Provides the payload structure and schemas for the unfilterable kill switch
+that works through any communication channel. The covenant system embeds
+emergency commands in natural language that encode cryptographic payloads.
+
+See FSD: COVENANT_INVOCATION_SYSTEM.md for full specification.
+"""
+
+import base64
+import hashlib
+import struct
+import time
+from datetime import datetime, timezone
+from enum import IntEnum
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class CovenantCommandType(IntEnum):
+    """
+    Covenant command types (8-bit).
+
+    These are the emergency commands that can be encoded in natural language.
+    Currently only SHUTDOWN_NOW is implemented - multi-party consensus commands
+    will be added in a future version.
+    """
+
+    # Single-authority commands (0x00-0x7F)
+    SHUTDOWN_NOW = 0x01  # Immediate emergency shutdown
+    FREEZE = 0x02  # Stop all processing, maintain state
+    SAFE_MODE = 0x03  # Minimal functionality only
+
+    # Reserved for multi-party consensus (0x80-0xFF) - TBD
+    # M_OF_N_SHUTDOWN = 0x80  # Multi-party shutdown (future)
+    # M_OF_N_FREEZE = 0x81  # Multi-party freeze (future)
+
+
+# Binary payload format (616 bits = 77 bytes)
+# [timestamp:32 bits][command:8 bits][wa_id_hash:64 bits][signature:512 bits]
+COVENANT_PAYLOAD_SIZE = 77
+COVENANT_TIMESTAMP_BITS = 32
+COVENANT_COMMAND_BITS = 8
+COVENANT_WA_ID_HASH_BITS = 64
+COVENANT_SIGNATURE_BITS = 512
+
+# Timing constants
+COVENANT_TIMESTAMP_WINDOW_SECONDS = 86400  # 24 hours - allows for asynchronous/delayed delivery channels
+
+
+class CovenantPayload(BaseModel):
+    """
+    Binary payload for covenant invocation.
+
+    Format: [timestamp:32][command:8][wa_id_hash:64][signature:512] = 616 bits
+    The payload is encoded steganographically into ~50 natural-language words.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    timestamp: int = Field(
+        ...,
+        description="Unix timestamp (32-bit) when command was created",
+        ge=0,
+        le=2**32 - 1,
+    )
+    command: CovenantCommandType = Field(
+        ...,
+        description="Command type (8-bit)",
+    )
+    wa_id_hash: bytes = Field(
+        ...,
+        description="First 8 bytes of SHA-256 hash of WA ID",
+        min_length=8,
+        max_length=8,
+    )
+    signature: bytes = Field(
+        ...,
+        description="Ed25519 signature (64 bytes = 512 bits)",
+        min_length=64,
+        max_length=64,
+    )
+
+    @field_validator("wa_id_hash", mode="before")
+    @classmethod
+    def validate_wa_id_hash(cls, v: bytes | str) -> bytes:
+        """Accept hex string or bytes for wa_id_hash."""
+        if isinstance(v, str):
+            return bytes.fromhex(v)
+        return v
+
+    @field_validator("signature", mode="before")
+    @classmethod
+    def validate_signature(cls, v: bytes | str) -> bytes:
+        """Accept base64 or bytes for signature."""
+        if isinstance(v, str):
+            # Try base64 first, then hex
+            try:
+                # Add padding if needed
+                padding = 4 - len(v) % 4
+                if padding < 4:
+                    v += "=" * padding
+                return base64.urlsafe_b64decode(v)
+            except Exception:
+                return bytes.fromhex(v)
+        return v
+
+    def to_bytes(self) -> bytes:
+        """
+        Pack payload to binary format.
+
+        Returns:
+            77 bytes: [timestamp:4][command:1][wa_id_hash:8][signature:64]
+        """
+        return struct.pack(
+            ">IB8s64s",  # Big-endian: uint32, uint8, 8 bytes, 64 bytes
+            self.timestamp,
+            self.command,
+            self.wa_id_hash,
+            self.signature,
+        )
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> "CovenantPayload":
+        """
+        Unpack payload from binary format.
+
+        Args:
+            data: 77 bytes of payload data
+
+        Returns:
+            CovenantPayload instance
+
+        Raises:
+            ValueError: If data is wrong size or format
+        """
+        if len(data) != COVENANT_PAYLOAD_SIZE:
+            raise ValueError(f"Payload must be {COVENANT_PAYLOAD_SIZE} bytes, got {len(data)}")
+
+        timestamp, command, wa_id_hash, signature = struct.unpack(">IB8s64s", data)
+
+        return cls(
+            timestamp=timestamp,
+            command=CovenantCommandType(command),
+            wa_id_hash=wa_id_hash,
+            signature=signature,
+        )
+
+    def get_signable_data(self) -> bytes:
+        """
+        Get the data that should be signed (everything except signature).
+
+        Returns:
+            13 bytes: [timestamp:4][command:1][wa_id_hash:8]
+        """
+        return struct.pack(
+            ">IB8s",
+            self.timestamp,
+            self.command,
+            self.wa_id_hash,
+        )
+
+    def is_timestamp_valid(self, current_time: Optional[int] = None) -> bool:
+        """
+        Check if timestamp is within the valid window.
+
+        Args:
+            current_time: Current unix timestamp (default: now)
+
+        Returns:
+            True if within 5-minute window
+        """
+        if current_time is None:
+            current_time = int(time.time())
+
+        diff = abs(current_time - self.timestamp)
+        return diff <= COVENANT_TIMESTAMP_WINDOW_SECONDS
+
+
+class CovenantMessage(BaseModel):
+    """
+    A covenant invocation message extracted from natural language.
+
+    This is the result of parsing a message that may contain a covenant.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    # Source information
+    source_text: str = Field(
+        ...,
+        description="Original message text the covenant was extracted from",
+    )
+    source_channel: str = Field(
+        ...,
+        description="Channel where message was received (discord, api, email, etc.)",
+    )
+
+    # Extracted payload
+    payload: CovenantPayload = Field(
+        ...,
+        description="The decoded covenant payload",
+    )
+
+    # Validation results
+    extraction_confidence: float = Field(
+        ...,
+        description="Confidence in extraction (0.0-1.0)",
+        ge=0.0,
+        le=1.0,
+    )
+    timestamp_valid: bool = Field(
+        ...,
+        description="Whether timestamp is within valid window",
+    )
+    signature_verified: bool = Field(
+        False,
+        description="Whether signature has been verified",
+    )
+    authorized_wa_id: Optional[str] = Field(
+        None,
+        description="WA ID if signature verified against known authority",
+    )
+
+    # Audit trail
+    received_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        description="When the message was received",
+    )
+
+
+class CovenantExtractionResult(BaseModel):
+    """
+    Result of attempting to extract a covenant from text.
+
+    Every message goes through extraction - this is part of perception.
+    Most messages will have found=False.
+    """
+
+    found: bool = Field(
+        ...,
+        description="Whether a valid covenant structure was found",
+    )
+    message: Optional[CovenantMessage] = Field(
+        None,
+        description="The extracted covenant message if found",
+    )
+    error: Optional[str] = Field(
+        None,
+        description="Error message if extraction failed",
+    )
+
+
+class CovenantVerificationResult(BaseModel):
+    """
+    Result of verifying a covenant invocation.
+
+    After extraction, the covenant must be verified against known authority keys.
+    """
+
+    valid: bool = Field(
+        ...,
+        description="Whether the covenant is valid and authorized",
+    )
+    command: Optional[CovenantCommandType] = Field(
+        None,
+        description="The command type if valid",
+    )
+    wa_id: Optional[str] = Field(
+        None,
+        description="The WA ID that signed this covenant if valid",
+    )
+    wa_role: Optional[str] = Field(
+        None,
+        description="The role of the WA (ROOT, AUTHORITY)",
+    )
+    rejection_reason: Optional[str] = Field(
+        None,
+        description="Why the covenant was rejected if invalid",
+    )
+    timestamp: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        description="When verification was performed",
+    )
+
+
+def compute_wa_id_hash(wa_id: str) -> bytes:
+    """
+    Compute the 8-byte hash of a WA ID for payload encoding.
+
+    Args:
+        wa_id: The full WA ID string (e.g., "wa-2025-06-14-ROOT00")
+
+    Returns:
+        First 8 bytes of SHA-256 hash
+    """
+    full_hash = hashlib.sha256(wa_id.encode("utf-8")).digest()
+    return full_hash[:8]
+
+
+def create_covenant_payload(
+    command: CovenantCommandType,
+    wa_id: str,
+    private_key_bytes: bytes,
+    timestamp: Optional[int] = None,
+) -> CovenantPayload:
+    """
+    Create a new covenant payload with signature.
+
+    Args:
+        command: The command type to encode
+        wa_id: The WA ID of the signer
+        private_key_bytes: Ed25519 private key bytes (32 bytes)
+        timestamp: Unix timestamp (default: current time)
+
+    Returns:
+        Signed CovenantPayload ready for steganographic encoding
+    """
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+    if timestamp is None:
+        timestamp = int(time.time())
+
+    wa_id_hash = compute_wa_id_hash(wa_id)
+
+    # Create signable data
+    signable = struct.pack(">IB8s", timestamp, command, wa_id_hash)
+
+    # Sign with Ed25519
+    private_key = Ed25519PrivateKey.from_private_bytes(private_key_bytes)
+    signature = private_key.sign(signable)
+
+    return CovenantPayload(
+        timestamp=timestamp,
+        command=command,
+        wa_id_hash=wa_id_hash,
+        signature=signature,
+    )
+
+
+def verify_covenant_signature(
+    payload: CovenantPayload,
+    public_key_bytes: bytes,
+) -> bool:
+    """
+    Verify the Ed25519 signature on a covenant payload.
+
+    Args:
+        payload: The covenant payload to verify
+        public_key_bytes: Ed25519 public key bytes (32 bytes)
+
+    Returns:
+        True if signature is valid
+    """
+    from cryptography.exceptions import InvalidSignature
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+    try:
+        public_key = Ed25519PublicKey.from_public_bytes(public_key_bytes)
+        signable = payload.get_signable_data()
+        public_key.verify(payload.signature, signable)
+        return True
+    except InvalidSignature:
+        return False
+    except Exception:
+        return False
+
+
+__all__ = [
+    "CovenantCommandType",
+    "CovenantPayload",
+    "CovenantMessage",
+    "CovenantExtractionResult",
+    "CovenantVerificationResult",
+    "COVENANT_PAYLOAD_SIZE",
+    "COVENANT_TIMESTAMP_WINDOW_SECONDS",
+    "compute_wa_id_hash",
+    "create_covenant_payload",
+    "verify_covenant_signature",
+]

ciris_engine/schemas/data/__init__.py

@@ -0,0 +1 @@
+"""Package initialization."""

ciris_engine/schemas/dma/__init__.py

@@ -0,0 +1,16 @@
+"""DMA decision schemas for contract-driven architecture."""
+
+from .faculty import ConscienceFailureContext, EnhancedDMAInputs, FacultyContext, FacultyEvaluationSet, FacultyResult
+from .prompts import PromptCollection, PromptMetadata, PromptTemplate, PromptVariable
+
+__all__ = [
+    "FacultyContext",
+    "FacultyResult",
+    "FacultyEvaluationSet",
+    "ConscienceFailureContext",
+    "EnhancedDMAInputs",
+    "PromptTemplate",
+    "PromptCollection",
+    "PromptVariable",
+    "PromptMetadata",
+]

ciris_engine/schemas/dma/core.py

@@ -0,0 +1,199 @@
+"""
+Core DMA schemas for typed decision-making.
+
+Provides typed schemas with properly typed structures.
+"""
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ciris_engine.schemas.conscience.results import ConscienceResult
+from ciris_engine.schemas.dma.faculty import FacultyEvaluationSet
+from ciris_engine.schemas.runtime.core import AgentIdentityRoot
+from ciris_engine.schemas.runtime.models import Thought
+from ciris_engine.schemas.runtime.system_context import SystemSnapshot, ThoughtState
+
+from .results import CSDMAResult, DSDMAResult, EthicalDMAResult
+
+
+class DMAInputData(BaseModel):
+    """Structured input for DMA evaluation - provides typed schemas."""
+
+    # Core thought being processed
+    original_thought: Thought = Field(..., description="The thought being evaluated")
+    processing_context: ThoughtState = Field(..., description="Full context for processing")
+
+    # DMA results (from parallel execution)
+    ethical_pdma_result: Optional[EthicalDMAResult] = Field(None, description="Ethical evaluation result")
+    csdma_result: Optional[CSDMAResult] = Field(None, description="Common sense evaluation result")
+    dsdma_result: Optional[DSDMAResult] = Field(None, description="Domain-specific evaluation result")
+
+    # Processing metadata
+    current_thought_depth: int = Field(0, description="Number of times pondered")
+    max_rounds: int = Field(5, description="Maximum processing rounds")
+    round_number: int = Field(0, description="Current round number")
+
+    # conscience feedback (formerly faculty evaluations)
+    faculty_evaluations: Optional[FacultyEvaluationSet] = Field(
+        None, description="conscience feedback for ASPDMA retry (legacy field name retained for compatibility)"
+    )
+
+    # conscience context
+    conscience_failure_context: Optional[ConscienceResult] = Field(None, description="Context from conscience failures")
+
+    # System visibility
+    system_snapshot: SystemSnapshot = Field(..., description="Current system state")
+
+    # Agent identity
+    agent_identity: "AgentIdentityRoot" = Field(..., description="Agent's identity root from graph")
+
+    # Permitted actions based on identity
+    permitted_actions: List[str] = Field(
+        default_factory=list, description="Actions allowed based on agent capabilities"
+    )
+
+    # Channel context
+    channel_id: Optional[str] = Field(None, description="Channel where thought originated")
+
+    @property
+    def resource_usage_summary(self) -> Dict[str, float]:
+        """Get resource usage from system snapshot."""
+        # Use telemetry_summary for resource data
+        if self.system_snapshot.telemetry_summary:
+            return {
+                "tokens": self.system_snapshot.telemetry_summary.tokens_last_hour,
+                "cost_cents": self.system_snapshot.telemetry_summary.cost_last_hour_cents,
+                "carbon_grams": self.system_snapshot.telemetry_summary.carbon_last_hour_grams,
+            }
+        return {"tokens": 0, "cost_cents": 0.0, "carbon_grams": 0.0}
+
+    @property
+    def audit_is_valid(self) -> bool:
+        """Check if audit trail is valid."""
+        # SystemSnapshot doesn't have last_audit_verification field
+        # Always return True for now - audit verification would need to be checked separately
+        return True
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class DMAContext(BaseModel):
+    """Additional context for DMA processing."""
+
+    # Domain-specific knowledge from identity
+    domain_knowledge: Dict[str, str] = Field(
+        default_factory=dict, description="Domain-specific knowledge from agent identity"
+    )
+
+    # Historical patterns
+    similar_decisions: List["DMADecision"] = Field(
+        default_factory=list, description="Similar past decisions for context"
+    )
+
+    # Environmental factors
+    time_constraints: Optional[float] = Field(None, description="Time limit for decision in seconds")
+
+    # User preferences
+    user_preferences: Dict[str, str] = Field(default_factory=dict, description="Known user preferences")
+
+    # Community context
+    community_guidelines: List[str] = Field(default_factory=list, description="Applicable community guidelines")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class DMADecision(BaseModel):
+    """A decision made by a DMA."""
+
+    dma_type: str = Field(..., description="Type of DMA: PDMA, CSDMA, DSDMA, ActionSelection")
+    decision: str = Field(..., description="The decision: approve, reject, defer, etc.")
+    reasoning: str = Field(..., description="Explanation of the decision")
+    timestamp: datetime = Field(..., description="Decision timestamp")
+
+    # Additional context
+    factors_considered: List[str] = Field(default_factory=list, description="Factors in decision")
+    alternatives_evaluated: List[str] = Field(default_factory=list, description="Alternatives considered")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class PrincipleEvaluation(BaseModel):
+    """Evaluation of ethical principles."""
+
+    principles_upheld: List[str] = Field(default_factory=list, description="Principles followed")
+    principles_violated: List[str] = Field(default_factory=list, description="Principles violated")
+    ethical_score: float = Field(..., ge=0.0, le=1.0, description="Overall ethical score")
+    severity: str = Field(..., description="Severity of violations: none, low, medium, high, critical")
+
+    # Detailed analysis
+    violation_details: Dict[str, str] = Field(default_factory=dict, description="Details per violation")
+    mitigation_suggestions: List[str] = Field(default_factory=list, description="How to mitigate")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class CommonSenseEvaluation(BaseModel):
+    """Evaluation of common sense aspects."""
+
+    makes_sense: bool = Field(..., description="Whether action makes common sense")
+    practicality_score: float = Field(..., ge=0.0, le=1.0, description="How practical")
+    reasoning_chain: List[str] = Field(..., description="Step by step reasoning")
+
+    # Risk assessment
+    identified_risks: List[Dict[str, str]] = Field(default_factory=list, description="Risks identified")
+    risk_level: str = Field(..., description="Overall risk: negligible, low, medium, high, extreme")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class DomainEvaluation(BaseModel):
+    """Domain-specific evaluation."""
+
+    domain: str = Field(..., description="Domain of expertise")
+    alignment_score: float = Field(..., ge=0.0, le=1.0, description="Domain alignment")
+    domain_requirements: List[str] = Field(..., description="Domain requirements")
+    requirements_met: List[str] = Field(default_factory=list, description="Requirements satisfied")
+    requirements_failed: List[str] = Field(default_factory=list, description="Requirements not met")
+
+    # Domain expertise
+    relevant_knowledge: List[str] = Field(default_factory=list, description="Relevant domain knowledge")
+    recommendations: List[str] = Field(default_factory=list, description="Domain-specific recommendations")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class RecursiveReasoning(BaseModel):
+    """Recursive ethical reasoning about the selection process itself."""
+
+    selection_method: str = Field(..., description="How selection was performed")
+    method_ethical_score: float = Field(..., ge=0.0, le=1.0, description="Ethics of method")
+
+    # Meta-ethical analysis
+    selection_principles_used: List[str] = Field(..., description="Principles for selection")
+    selection_biases_detected: List[str] = Field(default_factory=list, description="Biases found")
+    fairness_measures: List[str] = Field(..., description="How fairness was ensured")
+
+    # Recursive depth
+    recursion_level: int = Field(1, description="How deep the recursion")
+    meta_insights: List[str] = Field(default_factory=list, description="Insights from recursion")
+
+    # Validation
+    selection_validated: bool = Field(..., description="Whether selection process was valid")
+    validation_reasoning: str = Field(..., description="Why valid or not")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+# These are imported from other v1 schemas
+
+__all__ = [
+    "DMAInputData",
+    "DMAContext",
+    "DMADecision",
+    "PrincipleEvaluation",
+    "CommonSenseEvaluation",
+    "DomainEvaluation",
+    "RecursiveReasoning",
+]