ciris-agent 1.7.7__py3-none-any.whl

ciris_engine/protocols/services/graph/telemetry.py

@@ -0,0 +1,51 @@
+"""Telemetry Service Protocol."""
+
+from abc import abstractmethod
+from datetime import datetime
+from typing import TYPE_CHECKING, Dict, List, Optional, Protocol
+
+if TYPE_CHECKING:
+    from ciris_engine.schemas.services.graph.telemetry import TelemetryData, AggregatedTelemetryResponse
+
+from ...runtime.base import GraphServiceProtocol
+
+
+class TelemetryServiceProtocol(GraphServiceProtocol, Protocol):
+    """Protocol for telemetry service."""
+
+    @abstractmethod
+    async def record_metric(
+        self,
+        metric_name: str,
+        value: float = 1.0,
+        tags: Optional[Dict[str, str]] = None,
+        handler_name: Optional[str] = None,
+    ) -> None:
+        """Record a telemetry metric."""
+        ...
+
+    @abstractmethod
+    async def query_metrics(
+        self,
+        metric_name: str,
+        start_time: Optional[datetime] = None,
+        end_time: Optional[datetime] = None,
+        tags: Optional[Dict[str, str]] = None,
+    ) -> List["TelemetryData"]:
+        """Query metrics."""
+        ...
+
+    @abstractmethod
+    async def get_metric_summary(self, metric_name: str, window_minutes: int = 60) -> "TelemetryData":
+        """Get metric summary statistics."""
+        ...
+
+    @abstractmethod
+    async def get_metric_count(self) -> int:
+        """Get total count of metrics stored."""
+        ...
+
+    @abstractmethod
+    async def get_telemetry_summary(self) -> "AggregatedTelemetryResponse":
+        """Get comprehensive telemetry summary."""
+        ...

ciris_engine/protocols/services/graph/tsdb_consolidation.py

@@ -0,0 +1,87 @@
+"""
+Protocol for TSDB Consolidation Service.
+
+This service consolidates time-series telemetry data into permanent summaries
+for long-term memory (1000+ years).
+"""
+
+from abc import abstractmethod
+from datetime import datetime
+from typing import TYPE_CHECKING, Optional, Protocol, runtime_checkable
+
+from ...runtime.base import GraphServiceProtocol
+
+if TYPE_CHECKING:
+    from ciris_engine.schemas.services.core import ServiceCapabilities, ServiceStatus
+    from ciris_engine.schemas.services.graph.consolidation import TSDBPeriodSummary
+    from ciris_engine.schemas.services.graph_core import NodeType
+
+
+@runtime_checkable
+class TSDBConsolidationServiceProtocol(GraphServiceProtocol, Protocol):
+    """Protocol for TSDB consolidation service.
+
+    Consolidates TSDB telemetry nodes into 6-hour summaries for permanent storage.
+    Runs every 6 hours and deletes raw nodes older than 24 hours.
+    """
+
+    @abstractmethod
+    async def start(self) -> None:
+        """Start the consolidation service and begin periodic consolidation."""
+        ...
+
+    @abstractmethod
+    async def stop(self) -> None:
+        """Stop the consolidation service gracefully, running final consolidation."""
+        ...
+
+    @abstractmethod
+    async def is_healthy(self) -> bool:
+        """Check if the service is healthy.
+
+        Returns:
+            True if service is running and has required dependencies
+        """
+        ...
+
+    @abstractmethod
+    def get_capabilities(self) -> "ServiceCapabilities":
+        """Get service capabilities.
+
+        Returns:
+            ServiceCapabilities with actions, version, dependencies, and metadata
+        """
+        ...
+
+    @abstractmethod
+    def get_status(self) -> "ServiceStatus":
+        """Get service status.
+
+        Returns:
+            ServiceStatus with health, uptime, metrics, and last consolidation info
+        """
+        ...
+
+    @abstractmethod
+    def get_node_type(self) -> "NodeType":
+        """Get the node type this service manages.
+
+        Returns:
+            NodeType.TSDB_SUMMARY
+        """
+        ...
+
+    @abstractmethod
+    async def get_summary_for_period(
+        self, period_start: datetime, period_end: datetime
+    ) -> Optional["TSDBPeriodSummary"]:
+        """Get the summary for a specific period.
+
+        Args:
+            period_start: Start of the period
+            period_end: End of the period
+
+        Returns:
+            TSDBPeriodSummary containing summary data if found, or None if not found
+        """
+        ...

ciris_engine/protocols/services/infrastructure/__init__.py

@@ -0,0 +1,11 @@
+"""Infrastructure service protocols."""
+
+from .authentication import AuthenticationServiceProtocol
+from .database_maintenance import DatabaseMaintenanceServiceProtocol
+from .resource_monitor import ResourceMonitorServiceProtocol
+
+__all__ = [
+    "AuthenticationServiceProtocol",
+    "ResourceMonitorServiceProtocol",
+    "DatabaseMaintenanceServiceProtocol",
+]

ciris_engine/protocols/services/infrastructure/authentication.py

@@ -0,0 +1,159 @@
+"""Authentication Service Protocol.
+
+Handles identity verification and token management for Wise Authorities.
+Authentication = "Who are you?"
+"""
+
+from abc import abstractmethod
+from datetime import datetime
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Protocol, Tuple, Union
+
+from ...runtime.base import ServiceProtocol
+
+if TYPE_CHECKING:
+    from ciris_engine.schemas.runtime.models import Task
+    from ciris_engine.schemas.services.authority_core import TokenType, WACertificate, WARole
+else:
+    from ciris_engine.schemas.services.authority_core import WACertificate, WARole, TokenType
+
+from ciris_engine.schemas.services.authority.wise_authority import AuthenticationResult, TokenVerification, WAUpdate
+
+
+class AuthenticationServiceProtocol(ServiceProtocol, Protocol):
+    """Protocol for authentication service - identity management."""
+
+    @abstractmethod
+    async def authenticate(self, token: str) -> Optional[AuthenticationResult]:
+        """Authenticate a WA token and return identity info."""
+        ...
+
+    @abstractmethod
+    async def create_token(self, wa_id: str, token_type: TokenType, ttl: int = 3600) -> str:
+        """Create a new authentication token."""
+        ...
+
+    @abstractmethod
+    async def verify_token(self, token: str) -> Optional[TokenVerification]:
+        """Verify and decode a token."""
+        ...
+
+    @abstractmethod
+    async def create_wa(
+        self, name: str, email: str, scopes: List[str], role: WARole = WARole.OBSERVER
+    ) -> WACertificate:
+        """Create a new Wise Authority identity."""
+        ...
+
+    @abstractmethod
+    async def revoke_wa(self, wa_id: str, reason: str) -> bool:
+        """Revoke a Wise Authority identity."""
+        ...
+
+    @abstractmethod
+    async def update_wa(
+        self, wa_id: str, updates: Optional[WAUpdate] = None, **kwargs: Union[str, bool, datetime]
+    ) -> Optional[WACertificate]:
+        """Update a Wise Authority identity."""
+        ...
+
+    @abstractmethod
+    async def list_was(self, active_only: bool = True) -> List[WACertificate]:
+        """List Wise Authority identities."""
+        ...
+
+    @abstractmethod
+    async def get_wa(self, wa_id: str) -> Optional[WACertificate]:
+        """Get a specific Wise Authority by ID."""
+        ...
+
+    @abstractmethod
+    async def rotate_keys(self, wa_id: str) -> bool:
+        """Rotate cryptographic keys for a WA."""
+        ...
+
+    @abstractmethod
+    async def bootstrap_if_needed(self) -> None:
+        """Bootstrap the system with root WA if needed."""
+        ...
+
+    @abstractmethod
+    async def create_channel_token(self, wa_id: str, channel_id: str, ttl: int = 3600) -> str:
+        """Create a channel-specific token."""
+        ...
+
+    @abstractmethod
+    def verify_token_sync(self, token: str) -> Optional[Dict[str, Any]]:
+        """Synchronously verify a token (for non-async contexts)."""
+        ...
+
+    @abstractmethod
+    async def update_last_login(self, wa_id: str) -> None:
+        """Update the last login timestamp for a WA."""
+        ...
+
+    @abstractmethod
+    def create_gateway_token(self, wa: "WACertificate", expires_hours: int = 8) -> str:
+        """Create gateway-signed token (for OAuth/password auth)."""
+        ...
+
+    @abstractmethod
+    async def get_wa_by_oauth(self, provider: str, external_id: str) -> Optional["WACertificate"]:
+        """Get WA certificate by OAuth identity."""
+        ...
+
+    @abstractmethod
+    async def link_oauth_identity(
+        self,
+        wa_id: str,
+        provider: str,
+        external_id: str,
+        *,
+        account_name: Optional[str] = None,
+        metadata: Optional[Dict[str, str]] = None,
+        primary: bool = False,
+    ) -> Optional["WACertificate"]:
+        """Associate an additional OAuth identity with a WA."""
+        ...
+
+    @abstractmethod
+    async def unlink_oauth_identity(self, wa_id: str, provider: str, external_id: str) -> Optional["WACertificate"]:
+        """Remove an associated OAuth identity from a WA."""
+        ...
+
+    @abstractmethod
+    def generate_keypair(self) -> Tuple[bytes, bytes]:
+        """Generate Ed25519 keypair (private, public)."""
+        ...
+
+    @abstractmethod
+    def hash_password(self, password: str) -> str:
+        """Hash password using PBKDF2."""
+        ...
+
+    @abstractmethod
+    def sign_data(self, data: bytes, private_key: bytes) -> str:
+        """Sign data with Ed25519 private key."""
+        ...
+
+    @abstractmethod
+    async def sign_task(self, task: "Task", wa_id: str) -> Tuple[str, str]:
+        """Sign a task with a WA's private key.
+
+        Returns:
+            Tuple of (signature, signed_at timestamp)
+        """
+        ...
+
+    @abstractmethod
+    async def verify_task_signature(self, task: "Task") -> bool:
+        """Verify a task's signature.
+
+        Returns:
+            True if signature is valid, False otherwise
+        """
+        ...
+
+    @abstractmethod
+    async def get_system_wa_id(self) -> Optional[str]:
+        """Get the system WA ID for signing system tasks."""
+        ...

ciris_engine/protocols/services/infrastructure/credit_gate.py

@@ -0,0 +1,46 @@
+"""Protocols for credit gating providers used by the resource monitor."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from ciris_engine.schemas.services.credit_gate import (
+    CreditAccount,
+    CreditCheckResult,
+    CreditContext,
+    CreditSpendRequest,
+    CreditSpendResult,
+)
+
+
+@runtime_checkable
+class CreditGateProtocol(Protocol):
+    """Contract for asynchronous credit gating providers."""
+
+    async def start(self) -> None:
+        """Initialise provider resources (e.g., network clients)."""
+        ...
+
+    async def stop(self) -> None:
+        """Release provider resources."""
+        ...
+
+    async def check_credit(
+        self,
+        account: CreditAccount,
+        context: CreditContext | None = None,
+    ) -> CreditCheckResult:
+        """Check whether the account currently holds sufficient credit."""
+        ...
+
+    async def spend_credit(
+        self,
+        account: CreditAccount,
+        request: CreditSpendRequest,
+        context: CreditContext | None = None,
+    ) -> CreditSpendResult:
+        """Attempt to spend credit for the supplied account."""
+        ...
+
+
+__all__ = ["CreditGateProtocol"]

ciris_engine/protocols/services/infrastructure/database_maintenance.py

@@ -0,0 +1,25 @@
+"""Database Maintenance Service Protocol.
+
+Handles periodic database cleanup and archival operations.
+"""
+
+from abc import abstractmethod
+from typing import Optional, Protocol
+
+from ...runtime.base import ServiceProtocol
+from ..lifecycle.time import TimeServiceProtocol
+
+
+class DatabaseMaintenanceServiceProtocol(ServiceProtocol, Protocol):
+    """Protocol for database maintenance service."""
+
+    @abstractmethod
+    async def perform_startup_cleanup(self, time_service: Optional[TimeServiceProtocol] = None) -> None:
+        """
+        Performs database cleanup at startup:
+        1. Removes orphaned active tasks and thoughts.
+        2. Archives tasks and thoughts older than the configured threshold.
+        3. Cleans up thoughts with invalid context.
+        Logs actions taken.
+        """
+        ...

ciris_engine/protocols/services/infrastructure/resource_monitor.py

@@ -0,0 +1,83 @@
+"""
+Protocol for Resource Monitor Service.
+
+Monitors system resources, enforces limits, and triggers protective actions
+for 1000-year sustainable operation.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Optional, Protocol, runtime_checkable
+
+from ...runtime.base import ServiceProtocol
+
+# Import forward references
+if TYPE_CHECKING:
+    from ciris_engine.protocols.services.lifecycle.time import TimeServiceProtocol
+    from ciris_engine.schemas.services.credit_gate import (
+        CreditAccount,
+        CreditCheckResult,
+        CreditContext,
+        CreditSpendRequest,
+        CreditSpendResult,
+    )
+    from ciris_engine.schemas.services.infrastructure.resource_monitor import ResourceBudget, ResourceSnapshot
+
+
+@runtime_checkable
+class ResourceMonitorServiceProtocol(ServiceProtocol, Protocol):
+    """Protocol for resource monitoring service.
+
+    Tracks CPU, memory, disk, token usage and active thoughts.
+    Enforces limits through throttle, defer, reject, and shutdown signals.
+    Critical for preventing resource exhaustion over centuries of operation.
+    """
+
+    budget: "ResourceBudget"
+    snapshot: "ResourceSnapshot"
+    time_service: Optional["TimeServiceProtocol"]
+
+    async def start(self) -> None:
+        """Start resource monitoring with periodic checks."""
+        ...
+
+    async def stop(self) -> None:
+        """Stop resource monitoring gracefully."""
+        ...
+
+    async def record_tokens(self, tokens: int) -> None:
+        """Record token usage for rate limiting.
+
+        Args:
+            tokens: Number of tokens consumed
+        """
+        ...
+
+    async def check_available(self, resource: str, amount: int = 0) -> bool:
+        """Check if resource is available before consuming.
+
+        Args:
+            resource: Resource name (memory_mb, tokens_hour, thoughts_active)
+            amount: Additional amount to be consumed
+
+        Returns:
+            True if resource is available, False if would exceed warning threshold
+        """
+        ...
+
+    async def check_credit(
+        self,
+        account: "CreditAccount",
+        context: "CreditContext" | None = None,
+    ) -> "CreditCheckResult":
+        """Check whether a credit account currently has available balance."""
+        ...
+
+    async def spend_credit(
+        self,
+        account: "CreditAccount",
+        request: "CreditSpendRequest",
+        context: "CreditContext" | None = None,
+    ) -> "CreditSpendResult":
+        """Spend credit for an account when an interaction is approved."""
+        ...

ciris_engine/protocols/services/lifecycle/__init__.py

@@ -0,0 +1,13 @@
+"""Lifecycle service protocols."""
+
+from .initialization import InitializationServiceProtocol
+from .scheduler import TaskSchedulerServiceProtocol
+from .shutdown import ShutdownServiceProtocol
+from .time import TimeServiceProtocol
+
+__all__ = [
+    "TimeServiceProtocol",
+    "ShutdownServiceProtocol",
+    "InitializationServiceProtocol",
+    "TaskSchedulerServiceProtocol",
+]

ciris_engine/protocols/services/lifecycle/initialization.py

@@ -0,0 +1,41 @@
+"""Initialization Service Protocol."""
+
+from abc import abstractmethod
+from typing import Awaitable, Callable, Optional, Protocol
+
+from ciris_engine.schemas.services.lifecycle.initialization import InitializationStatus, InitializationVerification
+from ciris_engine.schemas.services.operations import InitializationPhase
+
+from ...runtime.base import ServiceProtocol
+
+
+class InitializationServiceProtocol(ServiceProtocol, Protocol):
+    """Protocol for initialization service."""
+
+    @abstractmethod
+    def register_step(
+        self,
+        phase: InitializationPhase,
+        name: str,
+        handler: Callable[[], Awaitable[None]],
+        verifier: Optional[Callable[[], Awaitable[bool]]] = None,
+        critical: bool = True,
+        timeout: float = 30.0,
+    ) -> None:
+        """Register an initialization step."""
+        ...
+
+    @abstractmethod
+    async def initialize(self) -> bool:
+        """Initialize the entire system."""
+        ...
+
+    @abstractmethod
+    async def verify_initialization(self) -> InitializationVerification:
+        """Verify all components are initialized."""
+        ...
+
+    @abstractmethod
+    async def get_initialization_status(self) -> InitializationStatus:
+        """Get detailed initialization status."""
+        ...

ciris_engine/protocols/services/lifecycle/scheduler.py

@@ -0,0 +1,42 @@
+"""Task Scheduler Service Protocol."""
+
+from abc import abstractmethod
+from typing import Any, Dict, List, Optional, Protocol
+
+from ciris_engine.schemas.runtime.extended import ScheduledTask, ScheduledTaskInfo
+
+from ...runtime.base import ServiceProtocol
+
+
+class TaskSchedulerServiceProtocol(ServiceProtocol, Protocol):
+    """Protocol for task scheduler service."""
+
+    @abstractmethod
+    async def schedule_task(
+        self,
+        name: str,
+        goal_description: str,
+        trigger_prompt: str,
+        origin_thought_id: str,
+        defer_until: Optional[str] = None,
+        schedule_cron: Optional[str] = None,
+    ) -> ScheduledTask:
+        """Schedule a new task."""
+        ...
+
+    @abstractmethod
+    async def cancel_task(self, task_id: str) -> bool:
+        """Cancel a scheduled task."""
+        ...
+
+    @abstractmethod
+    async def get_scheduled_tasks(self) -> List[ScheduledTaskInfo]:
+        """Get all scheduled tasks."""
+        ...
+
+    @abstractmethod
+    async def schedule_deferred_task(
+        self, thought_id: str, task_id: str, defer_until: str, reason: str, context: Optional[Dict[str, Any]] = None
+    ) -> ScheduledTask:
+        """Schedule a deferred task for future reactivation."""
+        ...

ciris_engine/protocols/services/lifecycle/shutdown.py

@@ -0,0 +1,50 @@
+"""Shutdown Service Protocol."""
+
+from abc import abstractmethod
+from typing import Callable, Optional, Protocol
+
+from ...runtime.base import ServiceProtocol
+
+
+class ShutdownServiceProtocol(ServiceProtocol, Protocol):
+    """Protocol for shutdown service."""
+
+    @abstractmethod
+    async def request_shutdown(self, reason: str) -> None:
+        """Request system shutdown."""
+        ...
+
+    @abstractmethod
+    def is_shutdown_requested(self) -> bool:
+        """Check if shutdown has been requested."""
+        ...
+
+    @abstractmethod
+    def is_force_shutdown(self) -> bool:
+        """Check if this is a forced/emergency shutdown."""
+        ...
+
+    @abstractmethod
+    def get_shutdown_reason(self) -> Optional[str]:
+        """Get the reason for shutdown."""
+        ...
+
+    @abstractmethod
+    def register_shutdown_handler(self, handler: Callable[[], None]) -> None:
+        """Register a shutdown handler."""
+        ...
+
+    @abstractmethod
+    async def emergency_shutdown(self, reason: str, timeout_seconds: int = 5) -> None:
+        """Execute emergency shutdown without negotiation."""
+        ...
+
+    @abstractmethod
+    def wait_for_shutdown(self) -> None:
+        """Wait for shutdown to be requested (blocking)."""
+        ...
+
+    @abstractmethod
+    async def wait_for_shutdown_async(self) -> None:
+        """Wait for shutdown to be requested (async)."""
+        ...

ciris_engine/protocols/services/lifecycle/time.py

@@ -0,0 +1,31 @@
+"""Time Service Protocol."""
+
+from abc import abstractmethod
+from datetime import datetime
+from typing import Protocol
+
+from ...runtime.base import ServiceProtocol
+
+
+class TimeServiceProtocol(ServiceProtocol, Protocol):
+    """Protocol for time service - provides consistent time operations."""
+
+    @abstractmethod
+    def now(self) -> datetime:
+        """Get current time in UTC with timezone info."""
+        ...
+
+    @abstractmethod
+    def now_iso(self) -> str:
+        """Get current time as ISO string."""
+        ...
+
+    @abstractmethod
+    def timestamp(self) -> float:
+        """Get current Unix timestamp."""
+        ...
+
+    @abstractmethod
+    def get_uptime(self) -> float:
+        """Get service uptime in seconds."""
+        ...

ciris_engine/protocols/services/runtime/__init__.py

@@ -0,0 +1,13 @@
+"""Core service protocols."""
+
+from .llm import LLMServiceProtocol
+from .runtime_control import RuntimeControlServiceProtocol
+from .secrets import SecretsServiceProtocol
+from .tool import ToolServiceProtocol
+
+__all__ = [
+    "LLMServiceProtocol",
+    "ToolServiceProtocol",
+    "SecretsServiceProtocol",
+    "RuntimeControlServiceProtocol",
+]