ciris-agent 1.7.7__py3-none-any.whl

ciris_engine/logic/adapters/api/routes/wa.py

@@ -0,0 +1,369 @@
+"""
+Wise Authority Service endpoints for CIRIS API v3 (Simplified).
+
+Manages human-in-the-loop deferrals and permissions.
+"""
+
+import logging
+import uuid
+from datetime import datetime, timezone
+from typing import List, Optional
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
+
+from ciris_engine.protocols.services.governance.wise_authority import WiseAuthorityServiceProtocol
+from ciris_engine.schemas.api.responses import ErrorCode, ErrorDetail, ErrorResponse, ResponseMetadata, SuccessResponse
+from ciris_engine.schemas.api.wa import (
+    DeferralListResponse,
+    PermissionsListResponse,
+    ResolveDeferralRequest,
+    ResolveDeferralResponse,
+    WAGuidanceRequest,
+    WAGuidanceResponse,
+    WAStatusResponse,
+)
+from ciris_engine.schemas.services.authority_core import DeferralResponse
+
+from ..constants import ERROR_WISE_AUTHORITY_SERVICE_NOT_AVAILABLE
+from ..dependencies.auth import AuthContext, require_authority, require_observer
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/wa", tags=["wise_authority"])
+
+
+@router.get("/deferrals")
+async def get_deferrals(
+    request: Request,
+    wa_id: Optional[str] = Query(None, description="Filter by WA ID"),
+    auth: AuthContext = Depends(require_observer),
+) -> SuccessResponse[DeferralListResponse]:
+    """
+    Get list of pending deferrals.
+
+    Returns all pending deferrals that need WA review. Can optionally
+    filter by WA ID to see deferrals assigned to a specific authority.
+
+    Requires OBSERVER role or higher.
+    """
+    # Get WA service from app state
+    if not hasattr(request.app.state, "wise_authority_service"):
+        raise HTTPException(
+            status_code=503,
+            detail=ErrorResponse(
+                error=ErrorDetail(
+                    code=ErrorCode.SERVICE_UNAVAILABLE, message=ERROR_WISE_AUTHORITY_SERVICE_NOT_AVAILABLE
+                )
+            ).model_dump(mode="json"),
+        )
+
+    wa_service: WiseAuthorityServiceProtocol = request.app.state.wise_authority_service
+
+    try:
+        # Get pending deferrals (UI fields now included in PendingDeferral schema)
+        deferrals = await wa_service.get_pending_deferrals(wa_id=wa_id)
+
+        response = DeferralListResponse(deferrals=deferrals, total=len(deferrals))
+
+        return SuccessResponse(
+            data=response,
+            metadata=ResponseMetadata(
+                timestamp=datetime.now(timezone.utc), request_id=str(uuid.uuid4()), duration_ms=0
+            ),
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to get deferrals: {e}")
+        raise HTTPException(
+            status_code=500,
+            detail=ErrorResponse(
+                error=ErrorDetail(code=ErrorCode.INTERNAL_ERROR, message=f"Failed to retrieve deferrals: {str(e)}")
+            ).model_dump(mode="json"),
+        )
+
+
+@router.post("/deferrals/{deferral_id}/resolve", response_model=SuccessResponse[ResolveDeferralResponse])
+async def resolve_deferral(
+    request: Request,
+    deferral_id: str,
+    resolve_request: ResolveDeferralRequest,
+    auth: AuthContext = Depends(require_authority),
+) -> SuccessResponse[ResolveDeferralResponse]:
+    """
+    Resolve a pending deferral with guidance.
+
+    Allows a WA with AUTHORITY role to approve, reject, or modify
+    a deferred decision. The resolution includes wisdom guidance
+    integrated into the decision.
+
+    Requires AUTHORITY role.
+    """
+    # Get WA service from app state
+    if not hasattr(request.app.state, "wise_authority_service"):
+        raise HTTPException(
+            status_code=503,
+            detail=ErrorResponse(
+                error=ErrorDetail(
+                    code=ErrorCode.SERVICE_UNAVAILABLE, message=ERROR_WISE_AUTHORITY_SERVICE_NOT_AVAILABLE
+                )
+            ).model_dump(mode="json"),
+        )
+
+    wa_service: WiseAuthorityServiceProtocol = request.app.state.wise_authority_service
+
+    try:
+        # Create deferral response with integrated guidance
+        deferral_response = DeferralResponse(
+            approved=(resolve_request.resolution == "approve"),
+            reason=resolve_request.guidance or f"Resolved by {auth.user_id}",
+            modified_time=None,  # Time modifications not needed in simplified version
+            wa_id=auth.user_id,  # Use authenticated user as WA
+            signature=f"api_{auth.user_id}_{datetime.now(timezone.utc).isoformat()}",
+        )
+
+        # Resolve the deferral
+        success = await wa_service.resolve_deferral(deferral_id, deferral_response)
+
+        if not success:
+            raise HTTPException(
+                status_code=400,
+                detail=ErrorResponse(
+                    error=ErrorDetail(
+                        code=ErrorCode.VALIDATION_ERROR,
+                        message="Failed to resolve deferral - it may have already been resolved",
+                    )
+                ).model_dump(mode="json"),
+            )
+
+        response = ResolveDeferralResponse(
+            success=True, deferral_id=deferral_id, resolved_at=datetime.now(timezone.utc)
+        )
+
+        # Sanitize user input for logging to prevent log injection
+        safe_resolution = "".join(
+            c if c.isprintable() and c not in "\n\r\t" else " " for c in resolve_request.resolution
+        )
+        safe_deferral_id = "".join(c if c.isprintable() and c not in "\n\r\t" else " " for c in deferral_id)
+        logger.info(f"Deferral {safe_deferral_id} resolved by {auth.user_id} with resolution: {safe_resolution}")
+
+        return SuccessResponse(
+            data=response,
+            metadata=ResponseMetadata(
+                timestamp=datetime.now(timezone.utc), request_id=str(uuid.uuid4()), duration_ms=0
+            ),
+        )
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        # Use hash instead of user input to prevent log injection
+        import hashlib
+
+        deferral_hash = hashlib.sha256(deferral_id.encode()).hexdigest()[:8]
+        logger.error(f"Failed to resolve deferral [id_hash:{deferral_hash}]: {e}")
+        raise HTTPException(
+            status_code=500,
+            detail=ErrorResponse(
+                error=ErrorDetail(code=ErrorCode.INTERNAL_ERROR, message=f"Failed to resolve deferral: {str(e)}")
+            ).model_dump(mode="json"),
+        )
+
+
+@router.get("/permissions", response_model=SuccessResponse[PermissionsListResponse])
+async def get_permissions(
+    request: Request,
+    wa_id: Optional[str] = Query(None, description="WA ID to get permissions for (defaults to current user)"),
+    auth: AuthContext = Depends(require_observer),
+) -> SuccessResponse[PermissionsListResponse]:
+    """
+    Get WA permission status.
+
+    Returns permission status for a specific WA. If no WA ID
+    is provided, returns permissions for the authenticated user.
+    This simplified endpoint focuses on viewing permissions only.
+
+    Requires OBSERVER role or higher.
+    """
+    # Get WA service from app state
+    if not hasattr(request.app.state, "wise_authority_service"):
+        raise HTTPException(
+            status_code=503,
+            detail=ErrorResponse(
+                error=ErrorDetail(
+                    code=ErrorCode.SERVICE_UNAVAILABLE, message=ERROR_WISE_AUTHORITY_SERVICE_NOT_AVAILABLE
+                )
+            ).model_dump(mode="json"),
+        )
+
+    wa_service: WiseAuthorityServiceProtocol = request.app.state.wise_authority_service
+
+    try:
+        # Use authenticated user's ID if no WA ID provided
+        target_wa_id = wa_id or auth.user_id
+
+        # Get permissions
+        permissions = await wa_service.list_permissions(target_wa_id)
+
+        response = PermissionsListResponse(permissions=permissions, wa_id=target_wa_id)
+
+        return SuccessResponse(
+            data=response,
+            metadata=ResponseMetadata(
+                timestamp=datetime.now(timezone.utc), request_id=str(uuid.uuid4()), duration_ms=0
+            ),
+        )
+
+    except Exception as e:
+        # Sanitize user input before logging to prevent log injection
+        safe_target_wa_id = "".join(c if c.isprintable() and c not in "\n\r\t" else " " for c in target_wa_id)
+        logger.error(f"Failed to get permissions for {safe_target_wa_id}: {e}")
+        raise HTTPException(
+            status_code=500,
+            detail=ErrorResponse(
+                error=ErrorDetail(code=ErrorCode.INTERNAL_ERROR, message=f"Failed to retrieve permissions: {str(e)}")
+            ).model_dump(mode="json"),
+        )
+
+
+@router.get("/status", response_model=SuccessResponse[WAStatusResponse])
+async def get_wa_status(
+    request: Request, auth: AuthContext = Depends(require_observer)
+) -> SuccessResponse[WAStatusResponse]:
+    """
+    Get current WA service status.
+
+    Returns information about the WA service including:
+    - Number of active WAs
+    - Number of pending deferrals
+    - Service health status
+
+    Requires OBSERVER role or higher.
+    """
+    # Get WA service from app state
+    if not hasattr(request.app.state, "wise_authority_service"):
+        raise HTTPException(
+            status_code=503,
+            detail=ErrorResponse(
+                error=ErrorDetail(
+                    code=ErrorCode.SERVICE_UNAVAILABLE, message=ERROR_WISE_AUTHORITY_SERVICE_NOT_AVAILABLE
+                )
+            ).model_dump(mode="json"),
+        )
+
+    wa_service: WiseAuthorityServiceProtocol = request.app.state.wise_authority_service
+
+    try:
+        # Get service status
+        is_healthy = True
+        if hasattr(wa_service, "is_healthy"):
+            is_healthy = await wa_service.is_healthy()
+
+        # Get pending deferrals count
+        pending_deferrals = await wa_service.get_pending_deferrals()
+
+        # Get active WAs (in a real implementation, this would query WA registry)
+        # For now, we'll just report if the service is available
+        active_was = 1 if is_healthy else 0
+
+        response = WAStatusResponse(
+            service_healthy=is_healthy,
+            active_was=active_was,
+            pending_deferrals=len(pending_deferrals),
+            deferrals_24h=len(pending_deferrals),  # Simplified - would track over time
+            average_resolution_time_minutes=0.0,  # Would calculate from historical data
+            timestamp=datetime.now(timezone.utc),
+        )
+
+        return SuccessResponse(
+            data=response,
+            metadata=ResponseMetadata(
+                timestamp=datetime.now(timezone.utc), request_id=str(uuid.uuid4()), duration_ms=0
+            ),
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to get WA status: {e}")
+        raise HTTPException(
+            status_code=500,
+            detail=ErrorResponse(
+                error=ErrorDetail(code=ErrorCode.INTERNAL_ERROR, message=f"Failed to retrieve WA status: {str(e)}")
+            ).model_dump(mode="json"),
+        )
+
+
+@router.post("/guidance", response_model=SuccessResponse[WAGuidanceResponse])
+async def request_guidance(
+    request: Request, guidance_request: WAGuidanceRequest, auth: AuthContext = Depends(require_observer)
+) -> SuccessResponse[WAGuidanceResponse]:
+    """
+    Request guidance from WA on a specific topic.
+
+    This endpoint allows requesting wisdom guidance without
+    creating a formal deferral. Useful for proactive wisdom
+    integration.
+
+    Requires OBSERVER role or higher.
+    """
+    # Get WA service from app state
+    if not hasattr(request.app.state, "wise_authority_service"):
+        raise HTTPException(
+            status_code=503,
+            detail=ErrorResponse(
+                error=ErrorDetail(
+                    code=ErrorCode.SERVICE_UNAVAILABLE, message=ERROR_WISE_AUTHORITY_SERVICE_NOT_AVAILABLE
+                )
+            ).model_dump(mode="json"),
+        )
+
+    # wa_service would be used in full implementation
+    # wa_service: WiseAuthorityServiceProtocol = request.app.state.wise_authority_service
+
+    try:
+        # In a real implementation, this would query available WAs for guidance
+        # For now, we'll provide a simple response
+
+        # Check if this is about an ethical concern
+        is_ethical = any(
+            word in guidance_request.topic.lower() for word in ["ethical", "moral", "right", "wrong", "should"]
+        )
+
+        if is_ethical:
+            guidance = (
+                "Consider the Ubuntu principle: 'I am because we are.' "
+                "Evaluate how this decision impacts the community as a whole. "
+                "Seek consensus and ensure actions align with collective well-being."
+            )
+        else:
+            guidance = (
+                "For technical decisions, consider long-term maintainability, "
+                "scalability, and alignment with system principles. "
+                "Document your reasoning for future reference."
+            )
+
+        response = WAGuidanceResponse(
+            guidance=guidance,
+            wa_id="system",  # In production, would be the actual WA who provided guidance
+            confidence=0.85 if is_ethical else 0.75,
+            additional_context={
+                "topic": guidance_request.topic,
+                "context_provided": bool(guidance_request.context),
+                "urgency": guidance_request.urgency.value if guidance_request.urgency else "normal",
+            },
+            timestamp=datetime.now(timezone.utc),
+        )
+
+        return SuccessResponse(
+            data=response,
+            metadata=ResponseMetadata(
+                timestamp=datetime.now(timezone.utc), request_id=str(uuid.uuid4()), duration_ms=0
+            ),
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to get guidance: {e}")
+        raise HTTPException(
+            status_code=500,
+            detail=ErrorResponse(
+                error=ErrorDetail(code=ErrorCode.INTERNAL_ERROR, message=f"Failed to retrieve guidance: {str(e)}")
+            ).model_dump(mode="json"),
+        )

ciris_engine/logic/adapters/api/service_configuration.py

@@ -0,0 +1,177 @@
+"""
+Service configuration for API Platform.
+
+Provides a declarative, human-readable configuration for which agent services
+the API adapter needs and how they should be mapped.
+"""
+
+from dataclasses import dataclass
+from typing import List, Optional, Tuple
+
+
+@dataclass
+class ServiceMapping:
+    """Defines how a single service should be mapped from runtime to API."""
+
+    runtime_attr: str  # Attribute name in runtime
+    app_state_name: Optional[str] = None  # Name in app.state (defaults to runtime_attr)
+    special_handler: Optional[str] = None  # Special processing function name
+    description: str = ""  # Human-readable description
+
+    def __post_init__(self) -> None:
+        # If no app_state_name specified, use runtime_attr
+        if self.app_state_name is None:
+            self.app_state_name = self.runtime_attr
+        # Ensure app_state_name is never None after initialization
+        assert self.app_state_name is not None
+
+
+class ApiServiceConfiguration:
+    """
+    Declarative configuration for API adapter service requirements.
+
+    This clearly documents:
+    1. The 22 core CIRIS services organized by category
+    2. Additional services needed by the API
+    3. Adapter-specific services that will be created
+
+    Based on the official service list from CLAUDE.md:
+    - Graph Services (7): memory, consent, config, telemetry, audit, incident_management, tsdb_consolidation
+    - Infrastructure Services (4): authentication, resource_monitor, database_maintenance, secrets
+    - Lifecycle Services (4): time, shutdown, initialization, task_scheduler
+    - Governance Services (4): wise_authority, adaptive_filter, visibility, self_observation
+    - Runtime Services (2): llm, runtime_control
+    - Tool Services (1): secrets_tool
+    """
+
+    # ========== THE 22 CORE CIRIS SERVICES ==========
+
+    # 7 Graph Services - Data persistence and tracking
+    GRAPH_SERVICES = [
+        ServiceMapping("memory_service", description="Graph-based memory storage and retrieval"),
+        ServiceMapping(
+            "consent_service",
+            app_state_name="consent_manager",
+            description="Consent, data retention, and DSAR automation",
+        ),
+        ServiceMapping("config_service", description="Configuration management"),
+        ServiceMapping("telemetry_service", description="Telemetry data collection and storage"),
+        ServiceMapping("audit_service", description="Audit trail and compliance logging"),
+        ServiceMapping("incident_management_service", description="Incident tracking and management"),
+        ServiceMapping("tsdb_consolidation_service", description="Time-series data consolidation"),
+    ]
+
+    # 4 Infrastructure Services - System operations
+    INFRASTRUCTURE_SERVICES = [
+        ServiceMapping(
+            "authentication_service",
+            special_handler="_handle_auth_service",
+            description="User authentication and session management",
+        ),
+        ServiceMapping("resource_monitor", app_state_name="resource_monitor", description="System resource monitoring"),
+        ServiceMapping("database_maintenance_service", description="Database maintenance operations"),
+        ServiceMapping("secrets_service", description="Secrets and credential management"),
+    ]
+
+    # 4 Lifecycle Services - Service lifecycle management
+    LIFECYCLE_SERVICES = [
+        ServiceMapping("time_service", description="Centralized time management"),
+        ServiceMapping("shutdown_service", description="Graceful shutdown coordination"),
+        ServiceMapping("initialization_service", description="Service initialization management"),
+        ServiceMapping("task_scheduler", description="Task scheduling and execution"),
+    ]
+
+    # 4 Governance Services - System oversight and adaptation
+    GOVERNANCE_SERVICES = [
+        ServiceMapping(
+            "wa_auth_system", app_state_name="wise_authority_service", description="Wise Authority decision system"
+        ),
+        ServiceMapping("adaptive_filter_service", description="Adaptive content filtering"),
+        ServiceMapping("visibility_service", description="System visibility and monitoring"),
+        ServiceMapping("self_observation_service", description="Self-monitoring and adaptation"),
+    ]
+
+    # 2 Runtime Services - Execution and processing
+    RUNTIME_SERVICES = [
+        ServiceMapping("llm_service", description="Language model integration"),
+        ServiceMapping(
+            "runtime_control_service",
+            app_state_name="main_runtime_control_service",
+            description="Main runtime control from agent",
+        ),
+    ]
+
+    # 1 Tool Service - Specialized operations
+    TOOL_SERVICES = [
+        ServiceMapping("secrets_tool_service", description="Secrets management tool"),
+    ]
+
+    # Note: service_registry, agent_processor, and message_handler are infrastructure components,
+    # not services, and should not be injected into app.state
+
+    # Infrastructure Components - Required by API endpoints but not official services
+    INFRASTRUCTURE_COMPONENTS = [
+        ServiceMapping("service_registry", description="Service registry for health checks and service discovery"),
+        ServiceMapping(
+            "bus_manager",
+            special_handler="_handle_bus_manager",
+            description="Bus manager for message buses (tool_bus, memory_bus, etc.)",
+        ),
+    ]
+
+    @classmethod
+    def get_current_mappings_as_tuples(cls) -> List[Tuple[str, str, Optional[str]]]:
+        """
+        Returns all mappings in the same format as the existing code.
+        This ensures backward compatibility during the refactor.
+        """
+        result: List[Tuple[str, str, Optional[str]]] = []
+        all_mappings = (
+            cls.GRAPH_SERVICES
+            + cls.INFRASTRUCTURE_SERVICES
+            + cls.LIFECYCLE_SERVICES
+            + cls.GOVERNANCE_SERVICES
+            + cls.RUNTIME_SERVICES
+            + cls.TOOL_SERVICES
+            + cls.INFRASTRUCTURE_COMPONENTS
+        )
+
+        for mapping in all_mappings:
+            # app_state_name is guaranteed to be str after __post_init__
+            assert mapping.app_state_name is not None
+            result.append((mapping.runtime_attr, mapping.app_state_name, mapping.special_handler))
+
+        return result
+
+    # Adapter-created services - will be defined after AdapterService class
+    ADAPTER_CREATED_SERVICES: List["AdapterService"] = []
+
+
+@dataclass
+class AdapterService:
+    """Defines an adapter-created service."""
+
+    attr_name: str  # Attribute name on the adapter (e.g., 'runtime_control')
+    app_state_name: str  # Name in app.state
+    description: str  # Human-readable description
+
+
+# Adapter-created services configuration
+ApiServiceConfiguration.ADAPTER_CREATED_SERVICES = [
+    AdapterService(
+        "runtime_control",
+        "runtime_control_service",
+        "APIRuntimeControlService - API-specific runtime control with pause/resume",
+    ),
+    AdapterService(
+        "communication",
+        "communication_service",
+        "APICommunicationService - Handles API message sending and response routing",
+    ),
+    AdapterService("tool_service", "tool_service", "APIToolService - Provides tool execution capabilities for the API"),
+    AdapterService(
+        "adapter_configuration_service",
+        "adapter_configuration_service",
+        "AdapterConfigurationService - Manages interactive adapter configuration workflows",
+    ),
+]

ciris_engine/logic/adapters/api/services/__init__.py

@@ -0,0 +1 @@
+"""API services module."""