ciris-agent 1.7.7__py3-none-any.whl

ciris_engine/schemas/runtime/adapter_management.py

@@ -0,0 +1,186 @@
+"""
+Schemas for runtime adapter management.
+
+These replace all Dict[str, Any] usage in adapter_manager.py.
+"""
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Union
+
+from pydantic import BaseModel, Field
+
+from ciris_engine.schemas.adapters.tools import ToolInfo
+
+# Constants for field descriptions to avoid duplication
+ADAPTER_ID_DESC = "Adapter ID"
+ADAPTER_TYPE_DESC = "Adapter type"
+IS_RUNNING_DESC = "Whether adapter is running"
+
+
+class AdapterConfig(BaseModel):
+    """Configuration for an adapter.
+
+    This schema supports two configuration approaches:
+    1. Simple adapters (CLI, API, Discord): Use `settings` dict with flat primitives
+    2. Complex adapters (MCP): Use `adapter_config` dict for nested structures
+
+    The adapter's own typed config class (e.g., MCPAdapterConfig, DiscordAdapterConfig)
+    performs full validation when the adapter is loaded.
+    """
+
+    adapter_type: str = Field(..., description="Type of adapter (cli, api, discord, etc.)")
+    enabled: bool = Field(True, description="Whether adapter is enabled")
+    settings: Dict[str, Optional[Union[str, int, float, bool, List[str]]]] = Field(
+        default_factory=dict,
+        description="Simple adapter settings (flat primitives only). "
+        "Use adapter_config for complex nested configurations.",
+    )
+    adapter_config: Optional[Dict[str, Any]] = Field(
+        None,
+        description="Full adapter configuration for adapters requiring nested objects "
+        "(e.g., MCP servers with bus_bindings). Validated by the adapter's typed config class.",
+    )
+
+
+class AdapterLoadRequest(BaseModel):
+    """Request to load an adapter."""
+
+    adapter_type: str = Field(..., description="Type of adapter to load")
+    adapter_id: str = Field(..., description="Unique ID for the adapter instance")
+    config: Optional[AdapterConfig] = Field(None, description="Configuration parameters")
+    auto_start: bool = Field(True, description="Whether to auto-start the adapter")
+
+
+class AdapterOperationResult(BaseModel):
+    """Result of an adapter operation."""
+
+    success: bool = Field(..., description="Whether operation succeeded")
+    adapter_id: str = Field(..., description=ADAPTER_ID_DESC)
+    adapter_type: Optional[str] = Field(None, description=ADAPTER_TYPE_DESC)
+    message: Optional[str] = Field(None, description="Operation message")
+    error: Optional[str] = Field(None, description="Error message if failed")
+    details: Optional[Dict[str, Union[str, int, float, bool]]] = Field(None, description="Additional details")
+
+
+class AdapterMetrics(BaseModel):
+    """Metrics for an adapter."""
+
+    messages_processed: int = Field(0, description="Total messages processed")
+    errors_count: int = Field(0, description="Total errors")
+    uptime_seconds: float = Field(0.0, description="Adapter uptime in seconds")
+    last_error: Optional[str] = Field(None, description="Last error message")
+    last_error_time: Optional[datetime] = Field(None, description="Last error timestamp")
+
+
+class RuntimeAdapterStatus(BaseModel):
+    """Status of a single adapter."""
+
+    adapter_id: str = Field(..., description="Unique " + ADAPTER_ID_DESC)
+    adapter_type: str = Field(..., description="Type of adapter")
+    is_running: bool = Field(..., description=IS_RUNNING_DESC)
+    loaded_at: datetime = Field(..., description="When adapter was loaded")
+    services_registered: List[str] = Field(default_factory=list, description="Services registered by adapter")
+    config_params: AdapterConfig = Field(..., description="Adapter configuration")
+    metrics: Optional[AdapterMetrics] = Field(None, description="Adapter metrics")
+    last_activity: Optional[datetime] = Field(None, description="Last activity timestamp")
+    tools: Optional[List[ToolInfo]] = Field(None, description="Tools provided by adapter")
+
+
+class AdapterListResponse(BaseModel):
+    """Response containing list of adapters."""
+
+    adapters: List[RuntimeAdapterStatus] = Field(..., description="List of adapter statuses")
+    total_count: int = Field(..., description="Total number of adapters")
+    running_count: int = Field(..., description="Number of running adapters")
+
+
+class ServiceRegistrationInfo(BaseModel):
+    """Information about a service registration."""
+
+    service_type: str = Field(..., description="Type of service")
+    provider_name: str = Field(..., description="Provider name")
+    priority: str = Field(..., description="Registration priority")
+    capabilities: List[str] = Field(..., description="Service capabilities")
+
+
+class AdapterInfo(BaseModel):
+    """Detailed information about an adapter."""
+
+    adapter_id: str = Field(..., description=ADAPTER_ID_DESC)
+    adapter_type: str = Field(..., description=ADAPTER_TYPE_DESC)
+    config: AdapterConfig = Field(..., description="Adapter configuration")
+    load_time: str = Field(..., description="ISO timestamp when loaded")
+    is_running: bool = Field(..., description=IS_RUNNING_DESC)
+
+
+class CommunicationAdapterInfo(BaseModel):
+    """Information about a communication adapter."""
+
+    adapter_id: str = Field(..., description=ADAPTER_ID_DESC)
+    adapter_type: str = Field(..., description=ADAPTER_TYPE_DESC)
+    is_running: bool = Field(..., description=IS_RUNNING_DESC)
+
+
+class CommunicationAdapterStatus(BaseModel):
+    """Status of all communication adapters."""
+
+    total_communication_adapters: int = Field(..., description="Total count")
+    running_communication_adapters: int = Field(..., description="Running count")
+    communication_adapters: List[CommunicationAdapterInfo] = Field(..., description="List of adapters")
+    safe_to_unload: bool = Field(..., description="Whether safe to unload")
+    warning_message: Optional[str] = Field(None, description="Warning message")
+
+
+class ModuleConfigParameter(BaseModel):
+    """Configuration parameter definition for a module."""
+
+    name: str = Field(..., description="Parameter name")
+    param_type: str = Field(..., description="Parameter type (string, integer, float, boolean, array)")
+    default: Optional[Union[str, int, float, bool, List[str]]] = Field(None, description="Default value")
+    description: str = Field(..., description="Parameter description")
+    env_var: Optional[str] = Field(None, description="Environment variable name")
+    required: bool = Field(True, description="Whether parameter is required")
+    sensitivity: Optional[str] = Field(None, description="Sensitivity level (e.g., 'HIGH' for secrets)")
+
+
+class ModuleTypeInfo(BaseModel):
+    """Information about an available module/adapter type."""
+
+    module_id: str = Field(..., description="Unique module identifier (e.g., 'api', 'mcp_client')")
+    name: str = Field(..., description="Human-readable module name")
+    version: str = Field(..., description="Module version")
+    description: str = Field(..., description="Module description")
+    author: str = Field(..., description="Module author")
+    module_source: str = Field(..., description="Source: 'core' for built-in or 'modular' for plugin")
+    service_types: List[str] = Field(
+        default_factory=list, description="Service types provided (e.g., TOOL, COMMUNICATION)"
+    )
+    capabilities: List[str] = Field(default_factory=list, description="Capabilities provided")
+    configuration_schema: List[ModuleConfigParameter] = Field(
+        default_factory=list, description="Configuration parameters and their types"
+    )
+    requires_external_deps: bool = Field(False, description="Whether module requires external packages")
+    external_dependencies: Dict[str, str] = Field(
+        default_factory=dict, description="External package dependencies with version constraints"
+    )
+    is_mock: bool = Field(False, description="Whether this is a mock/test module")
+    safe_domain: Optional[str] = Field(None, description="Safe domain classification")
+    prohibited: List[str] = Field(default_factory=list, description="Prohibited use cases")
+    metadata: Optional[Dict[str, Union[str, bool, int, List[str]]]] = Field(None, description="Additional metadata")
+    # Platform requirements for this adapter
+    platform_requirements: List[str] = Field(
+        default_factory=list, description="Platform requirements (e.g., 'android_play_integrity', 'google_native_auth')"
+    )
+    platform_requirements_rationale: Optional[str] = Field(
+        None, description="Explanation of why platform requirements exist"
+    )
+    platform_available: bool = Field(True, description="Whether this adapter is available on the current platform")
+
+
+class ModuleTypesResponse(BaseModel):
+    """Response containing all available module types."""
+
+    core_modules: List[ModuleTypeInfo] = Field(..., description="Built-in core adapters")
+    adapters: List[ModuleTypeInfo] = Field(..., description="Dynamically loaded adapters")
+    total_core: int = Field(..., description="Total number of core modules")
+    total_adapters: int = Field(..., description="Total number of adapters")

ciris_engine/schemas/runtime/api.py

@@ -0,0 +1,58 @@
+"""
+Runtime API schemas for CIRIS.
+
+Provides types needed for API authentication and user management.
+"""
+
+from enum import Enum
+from typing import List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ciris_engine.schemas.services.authority_core import WARole
+
+
+class APIRole(str, Enum):
+    """API role levels (separate from UserRole for compatibility)."""
+
+    OBSERVER = "OBSERVER"
+    ADMIN = "ADMIN"
+    AUTHORITY = "AUTHORITY"
+    SYSTEM_ADMIN = "SYSTEM_ADMIN"
+    SERVICE_ACCOUNT = "SERVICE_ACCOUNT"  # For service-to-service authentication
+
+    @property
+    def level(self) -> int:
+        """Numeric privilege level for comparison."""
+        return {
+            "OBSERVER": 1,
+            "ADMIN": 2,
+            "AUTHORITY": 3,
+            "SYSTEM_ADMIN": 4,
+            "SERVICE_ACCOUNT": 2,  # Same level as ADMIN for shutdown operations
+        }[self.value]
+
+
+class APIUserInfo(BaseModel):
+    """User information from API authentication."""
+
+    user_id: str = Field(..., description="Unique user identifier")
+    username: str = Field(..., description="User's display name")
+    role: APIRole = Field(..., description="User's API role")
+    wa_id: Optional[str] = Field(None, description="Associated WA ID if any")
+    wa_role: Optional[WARole] = Field(None, description="Associated WA role if any")
+    email: Optional[str] = Field(None, description="User email if available")
+    auth_type: str = Field(..., description="Authentication type: password, oauth, api_key")
+    permissions: List[str] = Field(default_factory=list, description="List of granted permissions")
+
+
+class PaginatedResponse(BaseModel):
+    """Generic paginated response for list endpoints."""
+
+    items: List[BaseModel] = Field(..., description="List of items in current page")
+    total: int = Field(..., description="Total number of items")
+    page: int = Field(..., description="Current page number (1-based)")
+    page_size: int = Field(..., description="Number of items per page")
+    pages: int = Field(..., description="Total number of pages")
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)

ciris_engine/schemas/runtime/audit.py

@@ -0,0 +1,50 @@
+"""
+Audit protocol schemas.
+
+Type-safe schemas for audit service operations.
+"""
+
+from datetime import datetime, timezone
+from typing import Dict, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class AuditActionContext(BaseModel):
+    """Context for an audited action."""
+
+    thought_id: str = Field(..., description="ID of the thought initiating action")
+    task_id: str = Field(..., description="ID of the associated task")
+    handler_name: str = Field(..., description="Name of the action handler")
+    parameters: Dict[str, str] = Field(default_factory=dict, description="Action parameters")
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class AuditConscienceResult(BaseModel):
+    """Result from a conscience check in audit context."""
+
+    allowed: bool = Field(..., description="Whether action is allowed")
+    reason: Optional[str] = Field(None, description="Reason for allow/deny")
+    modifications: Dict[str, str] = Field(default_factory=dict, description="Suggested modifications")
+    risk_level: Optional[str] = Field(None, description="Assessed risk level")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class AuditRequest(BaseModel):
+    """A request to create an audit entry."""
+
+    entry_id: str = Field(..., description="Unique audit entry ID")
+    timestamp: datetime = Field(..., description="When the event occurred")
+    entity_id: str = Field(..., description="ID of entity being audited")
+    event_type: str = Field(..., description="Type of event")
+    actor: str = Field(..., description="Who/what performed the action")
+    details: Dict[str, str] = Field(..., description="Event details")
+    outcome: Optional[str] = Field(None, description="Event outcome")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+__all__ = ["AuditActionContext", "AuditConscienceResult", "AuditRequest"]

ciris_engine/schemas/runtime/bootstrap.py

@@ -0,0 +1,33 @@
+"""
+Runtime bootstrap configuration schema.
+
+This replaces the raw **kwargs pattern in CIRISRuntime.__init__ with strongly-typed configuration.
+Follows CIRIS philosophy: No Untyped Dicts, No Bypass Patterns, No Exceptions.
+"""
+
+from typing import Dict, List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ciris_engine.schemas.runtime.adapter_management import AdapterConfig, AdapterLoadRequest
+
+
+class RuntimeBootstrapConfig(BaseModel):
+    """
+    Strongly-typed bootstrap configuration for CIRIS Runtime.
+
+    This replaces the raw **kwargs pattern with explicit, validated configuration.
+    All runtime initialization parameters are declared here - no hidden parameters allowed.
+    """
+
+    adapters: List[AdapterLoadRequest] = Field(default_factory=list, description="List of adapters to load at startup")
+    adapter_overrides: Dict[str, AdapterConfig] = Field(
+        default_factory=dict,
+        description="Adapter-specific configuration overrides keyed by adapter ID (e.g. 'discord:main', not just 'discord')",
+    )
+    modules: List[str] = Field(default_factory=list, description="External modules to load (e.g., 'mock_llm')")
+    startup_channel_id: Optional[str] = Field(None, description="Channel ID for startup messages")
+    debug: bool = Field(False, description="Enable debug mode")
+    preload_tasks: List[str] = Field(default_factory=list, description="Tasks to preload after WORK state transition")
+
+    model_config = ConfigDict(extra="forbid")  # No additional parameters allowed - all must be declared explicitly

ciris_engine/schemas/runtime/contexts.py

@@ -0,0 +1,61 @@
+"""
+Context schemas for CIRIS Trinity Architecture.
+
+Type-safe contexts for action dispatch and processing.
+"""
+
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ciris_engine.schemas.conscience.core import EpistemicData
+
+from ..conscience.results import ConscienceResult
+from .enums import HandlerActionType
+from .system_context import ChannelContext
+
+
+class DispatchContext(BaseModel):
+    """Type-safe context for action handler dispatch.
+
+    This replaces the generic Dict[str, Any] with proper typed fields
+    for mission-critical production use. All core fields are REQUIRED.
+    """
+
+    # Core identification - ALL REQUIRED
+    channel_context: ChannelContext = Field(..., description="Channel context where action originated")
+    author_id: str = Field(..., description="ID of user/entity initiating action")
+    author_name: str = Field(..., description="Display name of initiator")
+
+    # Service references - ALL REQUIRED
+    origin_service: str = Field(..., description="Service that originated the request")
+    handler_name: str = Field(..., description="Handler processing this action")
+
+    # Action context - ALL REQUIRED
+    action_type: HandlerActionType = Field(..., description="Type of action being handled")
+    thought_id: str = Field(..., description="Associated thought ID")
+    task_id: str = Field(..., description="Associated task ID")
+    source_task_id: str = Field(..., description="Source task ID from thought")
+
+    # Event details - ALL REQUIRED
+    event_summary: str = Field(..., description="Summary of the event/action")
+    event_timestamp: str = Field(..., description="ISO8601 timestamp of event")
+
+    # Additional context - REQUIRED with sensible defaults
+    wa_id: Optional[str] = Field(None, description="Wise Authority ID if applicable")
+    wa_authorized: bool = Field(False, description="Whether WA authorized this action")
+    wa_context: Optional[str] = Field(None, description="WA context if applicable")
+
+    # conscience and processing context - OPTIONAL
+    conscience_failure_context: Optional[ConscienceResult] = Field(None, description="Context from conscience failures")
+    epistemic_data: Optional[EpistemicData] = Field(None, description="Epistemic faculty evaluation data")
+
+    # Correlation tracking
+    correlation_id: Optional[str] = Field(None, description="Correlation ID for distributed tracing")
+    span_id: Optional[str] = Field(None, description="Span ID for tracing")
+    trace_id: Optional[str] = Field(None, description="Trace ID for distributed tracing")
+
+    model_config = ConfigDict(extra="forbid")  # Strict - no extra fields allowed
+
+
+__all__ = ["DispatchContext"]

ciris_engine/schemas/runtime/core.py

@@ -0,0 +1,161 @@
+"""
+Identity schemas for agent self-model.
+
+Provides type-safe structures for agent identity and capabilities.
+"""
+
+from datetime import datetime, timezone
+from typing import Dict, List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ciris_engine.schemas.types import ConfigValue
+
+
+class CoreProfile(BaseModel):
+    """Core identity profile for the agent."""
+
+    description: str = Field(..., description="Agent's self-description")
+    role_description: str = Field(..., description="Agent's role and purpose")
+
+    # Knowledge and expertise
+    domain_specific_knowledge: Dict[str, str] = Field(default_factory=dict, description="Domain expertise mappings")
+    areas_of_expertise: List[str] = Field(default_factory=list, description="Areas where agent has expertise")
+
+    # Behavioral customization
+    dsdma_prompt_template: Optional[str] = Field(None, description="Custom DSDMA prompt template")
+    csdma_overrides: Dict[str, str] = Field(default_factory=dict, description="Common sense overrides")
+    action_selection_pdma_overrides: Dict[str, str] = Field(
+        default_factory=dict, description="Action selection overrides"
+    )
+
+    # Memory and state
+    last_shutdown_memory: Optional[str] = Field(None, description="Memory from last shutdown")
+    startup_instructions: Optional[str] = Field(None, description="Instructions for startup")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class IdentityMetadata(BaseModel):
+    """Metadata about identity creation and modification."""
+
+    created_at: datetime = Field(..., description="When identity was created")
+    last_modified: datetime = Field(..., description="Last modification time")
+    modification_count: int = Field(0, description="Number of modifications")
+
+    # Provenance
+    creator_agent_id: str = Field(..., description="Agent that created this identity")
+    lineage_trace: List[str] = Field(default_factory=list, description="Identity evolution lineage")
+
+    # Approval and authorization
+    approval_required: bool = Field(True, description="Whether changes need approval")
+    approved_by: Optional[str] = Field(None, description="WA who approved")
+    approval_timestamp: Optional[datetime] = Field(None, description="When approved")
+
+    # Version control
+    version: str = Field("1.0.0", description="Identity version")
+    previous_versions: List[str] = Field(default_factory=list, description="Previous version hashes")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class CapabilityDefinition(BaseModel):
+    """Definition of an agent capability."""
+
+    capability_name: str = Field(..., description="Name of capability")
+    description: str = Field(..., description="What this capability enables")
+    required_permissions: List[str] = Field(default_factory=list, description="Permissions needed")
+
+    # Constraints
+    usage_limits: Optional[Dict[str, int]] = Field(None, description="Usage limits per time period")
+    restricted_contexts: List[str] = Field(default_factory=list, description="Contexts where restricted")
+
+    # Dependencies
+    depends_on: List[str] = Field(default_factory=list, description="Other required capabilities")
+    conflicts_with: List[str] = Field(default_factory=list, description="Conflicting capabilities")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class AgentIdentityRoot(BaseModel):
+    """Root identity structure for an agent."""
+
+    agent_id: str = Field(..., description="Unique agent identifier")
+    identity_hash: str = Field(..., description="Hash of identity for integrity")
+
+    # Core identity
+    core_profile: CoreProfile = Field(..., description="Core identity profile")
+    identity_metadata: IdentityMetadata = Field(..., description="Identity metadata")
+
+    # Capabilities and permissions
+    permitted_actions: List[str] = Field(default_factory=list, description="Actions this agent can perform")
+    restricted_capabilities: List[str] = Field(default_factory=list, description="Explicitly restricted capabilities")
+    capability_definitions: Dict[str, CapabilityDefinition] = Field(
+        default_factory=dict, description="Detailed capability definitions"
+    )
+
+    # Trust and authorization
+    trust_level: float = Field(0.5, ge=0.0, le=1.0, description="Agent trust level")
+    authorization_scope: str = Field("standard", description="Authorization scope: limited, standard, elevated, full")
+
+    # Relationships
+    parent_agent_id: Optional[str] = Field(None, description="Parent agent if spawned")
+    child_agent_ids: List[str] = Field(default_factory=list, description="Child agents spawned")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class IdentityUpdate(BaseModel):
+    """Update to agent identity."""
+
+    update_type: str = Field(..., description="Type: profile, capabilities, trust, metadata")
+    field_path: str = Field(..., description="Dot-notation path to field")
+    new_value: ConfigValue = Field(..., description="New value for field")
+
+    # Authorization
+    requested_by: str = Field(..., description="Who requested update")
+    reason: str = Field(..., description="Reason for update")
+
+    # Validation
+    requires_approval: bool = Field(True, description="Whether needs WA approval")
+    approval_status: Optional[str] = Field(None, description="Approval status")
+    approved_by: Optional[str] = Field(None, description="WA who approved")
+
+    # Audit
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    correlation_id: str = Field(..., description="For tracing")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class IdentityValidation(BaseModel):
+    """Result of identity validation."""
+
+    is_valid: bool = Field(..., description="Whether identity is valid")
+    validation_errors: List[str] = Field(default_factory=list, description="Validation errors found")
+
+    # Integrity checks
+    hash_valid: bool = Field(..., description="Whether hash matches")
+    signature_valid: Optional[bool] = Field(None, description="If signed, whether valid")
+
+    # Consistency checks
+    capabilities_consistent: bool = Field(..., description="Capabilities are consistent")
+    permissions_valid: bool = Field(..., description="Permissions are valid")
+    metadata_complete: bool = Field(..., description="Metadata is complete")
+
+    # Recommendations
+    recommendations: List[str] = Field(default_factory=list, description="Recommendations for fixes")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+# IdentitySnapshot moved to schemas/services/nodes.py as TypedGraphNode
+
+__all__ = [
+    "CoreProfile",
+    "IdentityMetadata",
+    "CapabilityDefinition",
+    "AgentIdentityRoot",
+    "IdentityUpdate",
+    "IdentityValidation",
+]