maivn-shared 0.2.0__py3-none-any.whl

maivn_shared/__init__.py

@@ -0,0 +1,269 @@
+"""Maivn Core - Core domain models and utilities for the Maivn platform.
+
+This package provides the fundamental building blocks for Maivn applications:
+- Domain entities (tools, sessions, messages, dependencies)
+- Infrastructure (logging, HTTP client, API endpoints)
+- Utilities
+"""
+
+from __future__ import annotations
+
+from .core import (
+    ASSIGNMENT_COMPLETED_EVENT_NAME,
+    ASSIGNMENT_RECEIVED_EVENT_NAME,
+    ENRICHMENT_EVENT_NAME,
+    ERROR_EVENT_NAME,
+    FINAL_EVENT_NAME,
+    HEARTBEAT_EVENT_NAME,
+    INTERRUPT_REQUEST_EVENT_NAME,
+    INTERRUPT_REQUIRED_EVENT_NAME,
+    MEMORY_ENRICHMENT_PHASES,
+    MEMORY_GRAPH_EXTRACTING_ENRICHMENT_PHASE,
+    MEMORY_INDEXED_ENRICHMENT_PHASE,
+    MEMORY_INDEXING_ENRICHMENT_PHASE,
+    MEMORY_INSIGHT_EXTRACTED_ENRICHMENT_PHASE,
+    MEMORY_INSIGHT_EXTRACTING_ENRICHMENT_PHASE,
+    MEMORY_RETRIEVED_ENRICHMENT_PHASE,
+    MEMORY_RETRIEVING_ENRICHMENT_PHASE,
+    MEMORY_SKILL_EXTRACTED_ENRICHMENT_PHASE,
+    MEMORY_SKILL_EXTRACTING_ENRICHMENT_PHASE,
+    MEMORY_SUMMARIZED_ENRICHMENT_PHASE,
+    MEMORY_SUMMARIZING_ENRICHMENT_PHASE,
+    MESSAGE_REDACTION_APPLIED_ENRICHMENT_PHASE,
+    MODEL_TOOL_COMPLETE_EVENT_NAME,
+    PROGRESS_UPDATE_EVENT_NAME,
+    REDACTION_ENRICHMENT_PHASES,
+    REDACTION_PREVIEWED_ENRICHMENT_PHASE,
+    RESOURCE_DEDUP_REUSED_ENRICHMENT_PHASE,
+    RESOURCE_ENRICHMENT_PHASES,
+    RESOURCE_EXTRACTED_ENRICHMENT_PHASE,
+    RESOURCE_EXTRACTING_ENRICHMENT_PHASE,
+    RESOURCE_REGISTERED_ENRICHMENT_PHASE,
+    RESOURCE_REGISTERING_ENRICHMENT_PHASE,
+    RESOURCE_VERSION_SUPERSEDED_ENRICHMENT_PHASE,
+    STATUS_MESSAGE_EVENT_NAME,
+    SYSTEM_TOOL_CHUNK_EVENT_NAME,
+    SYSTEM_TOOL_COMPLETE_EVENT_NAME,
+    SYSTEM_TOOL_ERROR_EVENT_NAME,
+    SYSTEM_TOOL_START_EVENT_NAME,
+    TOOL_EVENT_NAME,
+    UPDATE_EVENT_NAME,
+    create_uuid,
+)
+from .domain.entities import (
+    HIPAA_SAFE_HARBOR_CATEGORIES,
+    SWARM_AGENT_INVOCATION_METADATA_KEY,
+    SWARM_INVOCATION_INTENT_METADATA_KEY,
+    AgentDependency,
+    AIMessage,
+    ArgsSchema,
+    AwaitForDependency,
+    BaseDependency,
+    BaseMessage,
+    DataDependency,
+    ExecutionInstanceControl,
+    ExecutionTiming,
+    HumanMessage,
+    InterruptDependency,
+    MemoryAssetsConfig,
+    MemoryConfig,
+    MemoryInsightExtractionConfig,
+    MemoryLevel,
+    MemoryPersistenceMode,
+    MemoryResourceConfig,
+    MemoryRetrievalConfig,
+    MemorySharingScope,
+    MemorySkillConfig,
+    MemorySkillExtractionConfig,
+    NestedSynthesisMode,
+    PIIWhitelist,
+    PIIWhitelistEntry,
+    PrivateData,
+    RedactedMessage,
+    RedactionPreviewRequest,
+    RedactionPreviewResponse,
+    ReevaluateDependency,
+    SessionExecutionConfig,
+    SessionOrchestrationConfig,
+    SessionRequest,
+    SessionResponse,
+    SessionStartRequest,
+    SessionStartupResponse,
+    StructuredOutputConfig,
+    SwarmAgentConfig,
+    SwarmConfig,
+    SystemMessage,
+    SystemToolsConfig,
+    ToolCall,
+    ToolDependency,
+    ToolExecutionResult,
+    ToolMessage,
+    ToolResumePayload,
+    ToolSpec,
+    ToolType,
+    apply_session_configs_to_metadata,
+)
+from .domain.exceptions import (
+    ConfigurationError,
+    MaivnError,
+    SerializationError,
+    ValidationError,
+    is_retryable,
+    wrap_exception,
+)
+from .domain.factories import build_tool_spec_from_function
+from .infrastructure import (
+    HttpClient,
+    HttpClientProtocol,
+    HttpError,
+    MaivnLogger,
+    ServerEndpoints,
+    SessionClientProtocol,
+    SSEClientProtocol,
+    get_logger,
+    get_optional_logger,
+)
+from .infrastructure.logging import Colors, LogLevel, LogStyles
+from .utils import (
+    dumps,
+    dumps_bytes,
+    extract_tool_names,
+    loads,
+    serialize_error,
+    serialize_with_metadata,
+    to_jsonable,
+)
+
+__all__ = [
+    # Core - Utilities
+    "create_uuid",
+    # Core - Events
+    "TOOL_EVENT_NAME",
+    "INTERRUPT_REQUEST_EVENT_NAME",
+    "INTERRUPT_REQUIRED_EVENT_NAME",
+    "ASSIGNMENT_RECEIVED_EVENT_NAME",
+    "ASSIGNMENT_COMPLETED_EVENT_NAME",
+    "MODEL_TOOL_COMPLETE_EVENT_NAME",
+    "HEARTBEAT_EVENT_NAME",
+    "UPDATE_EVENT_NAME",
+    "PROGRESS_UPDATE_EVENT_NAME",
+    "STATUS_MESSAGE_EVENT_NAME",
+    "FINAL_EVENT_NAME",
+    "ERROR_EVENT_NAME",
+    "SYSTEM_TOOL_START_EVENT_NAME",
+    "SYSTEM_TOOL_CHUNK_EVENT_NAME",
+    "SYSTEM_TOOL_COMPLETE_EVENT_NAME",
+    "SYSTEM_TOOL_ERROR_EVENT_NAME",
+    "ENRICHMENT_EVENT_NAME",
+    "MEMORY_SUMMARIZING_ENRICHMENT_PHASE",
+    "MEMORY_SUMMARIZED_ENRICHMENT_PHASE",
+    "MEMORY_RETRIEVING_ENRICHMENT_PHASE",
+    "MEMORY_RETRIEVED_ENRICHMENT_PHASE",
+    "MEMORY_INDEXING_ENRICHMENT_PHASE",
+    "MEMORY_INDEXED_ENRICHMENT_PHASE",
+    "MEMORY_GRAPH_EXTRACTING_ENRICHMENT_PHASE",
+    "MEMORY_SKILL_EXTRACTING_ENRICHMENT_PHASE",
+    "MEMORY_INSIGHT_EXTRACTING_ENRICHMENT_PHASE",
+    "MEMORY_SKILL_EXTRACTED_ENRICHMENT_PHASE",
+    "MEMORY_INSIGHT_EXTRACTED_ENRICHMENT_PHASE",
+    "MEMORY_ENRICHMENT_PHASES",
+    "MESSAGE_REDACTION_APPLIED_ENRICHMENT_PHASE",
+    "REDACTION_PREVIEWED_ENRICHMENT_PHASE",
+    "REDACTION_ENRICHMENT_PHASES",
+    "RESOURCE_REGISTERING_ENRICHMENT_PHASE",
+    "RESOURCE_REGISTERED_ENRICHMENT_PHASE",
+    "RESOURCE_DEDUP_REUSED_ENRICHMENT_PHASE",
+    "RESOURCE_VERSION_SUPERSEDED_ENRICHMENT_PHASE",
+    "RESOURCE_EXTRACTING_ENRICHMENT_PHASE",
+    "RESOURCE_EXTRACTED_ENRICHMENT_PHASE",
+    "RESOURCE_ENRICHMENT_PHASES",
+    # Domain - Entities - Memory Config
+    "MemoryConfig",
+    "MemoryAssetsConfig",
+    "MemoryInsightExtractionConfig",
+    "MemoryLevel",
+    "MemoryPersistenceMode",
+    "MemoryResourceConfig",
+    "MemoryRetrievalConfig",
+    "MemorySharingScope",
+    "MemorySkillConfig",
+    "MemorySkillExtractionConfig",
+    "NestedSynthesisMode",
+    # Domain - Entities - Session
+    "SWARM_AGENT_INVOCATION_METADATA_KEY",
+    "SWARM_INVOCATION_INTENT_METADATA_KEY",
+    "RedactionPreviewRequest",
+    "RedactionPreviewResponse",
+    "SessionExecutionConfig",
+    "SessionOrchestrationConfig",
+    "SessionRequest",
+    "SessionResponse",
+    "SessionStartupResponse",
+    "SessionStartRequest",
+    "StructuredOutputConfig",
+    "SwarmAgentConfig",
+    "SwarmConfig",
+    "SystemToolsConfig",
+    "apply_session_configs_to_metadata",
+    # Domain - Entities - Tool Specification
+    "ArgsSchema",
+    "ToolSpec",
+    "ToolType",
+    "ToolCall",
+    "ToolExecutionResult",
+    # Domain - Entities - Messages
+    "BaseMessage",
+    "HumanMessage",
+    "PrivateData",
+    "RedactedMessage",
+    "AIMessage",
+    "SystemMessage",
+    "ToolMessage",
+    # Domain - Entities - PII Whitelist
+    "HIPAA_SAFE_HARBOR_CATEGORIES",
+    "PIIWhitelist",
+    "PIIWhitelistEntry",
+    # Domain - Entities - Dependencies
+    "BaseDependency",
+    "AgentDependency",
+    "AwaitForDependency",
+    "DataDependency",
+    "ExecutionInstanceControl",
+    "ExecutionTiming",
+    "InterruptDependency",
+    "ReevaluateDependency",
+    "ToolDependency",
+    "ToolResumePayload",
+    # Domain - Exceptions
+    "MaivnError",
+    "ConfigurationError",
+    "ValidationError",
+    "SerializationError",
+    "wrap_exception",
+    "is_retryable",
+    # Domain - Factories
+    "build_tool_spec_from_function",
+    # Infrastructure - Logging
+    "MaivnLogger",
+    "LogLevel",
+    "Colors",
+    "LogStyles",
+    "get_logger",
+    "get_optional_logger",
+    # Infrastructure - HTTP
+    "HttpClient",
+    "HttpError",
+    "HttpClientProtocol",
+    "SSEClientProtocol",
+    "ServerEndpoints",
+    "SessionClientProtocol",
+    # Utilities - Serialization
+    "dumps",
+    "dumps_bytes",
+    "loads",
+    "to_jsonable",
+    "serialize_error",
+    "serialize_with_metadata",
+    # Utilities - Tools
+    "extract_tool_names",
+]

maivn_shared/__version__.py

@@ -0,0 +1,11 @@
+"""Package version for maivn-shared.
+
+Exposed via ``maivn_shared.__version__`` for tooling and client diagnostics.
+"""
+
+# MARK: Version
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+__version__ = "0.2.0"

maivn_shared/core/__init__.py

@@ -0,0 +1,105 @@
+"""Core application services and utilities for maivn-core."""
+
+from __future__ import annotations
+
+# MARK: - Utilities
+from .data import create_uuid
+
+# MARK: - Events
+from .events import (
+    ASSIGNMENT_COMPLETED_EVENT_NAME,
+    # MARK: - Assignment Events
+    ASSIGNMENT_RECEIVED_EVENT_NAME,
+    # MARK: - Enrichment Events
+    ENRICHMENT_EVENT_NAME,
+    ERROR_EVENT_NAME,
+    FINAL_EVENT_NAME,
+    # MARK: - Lifecycle Events
+    HEARTBEAT_EVENT_NAME,
+    INTERRUPT_REQUEST_EVENT_NAME,
+    INTERRUPT_REQUIRED_EVENT_NAME,
+    MEMORY_ENRICHMENT_PHASES,
+    MEMORY_GRAPH_EXTRACTING_ENRICHMENT_PHASE,
+    MEMORY_INDEXED_ENRICHMENT_PHASE,
+    MEMORY_INDEXING_ENRICHMENT_PHASE,
+    MEMORY_INSIGHT_EXTRACTED_ENRICHMENT_PHASE,
+    MEMORY_INSIGHT_EXTRACTING_ENRICHMENT_PHASE,
+    MEMORY_RETRIEVED_ENRICHMENT_PHASE,
+    MEMORY_RETRIEVING_ENRICHMENT_PHASE,
+    MEMORY_SKILL_EXTRACTED_ENRICHMENT_PHASE,
+    MEMORY_SKILL_EXTRACTING_ENRICHMENT_PHASE,
+    MEMORY_SUMMARIZED_ENRICHMENT_PHASE,
+    MEMORY_SUMMARIZING_ENRICHMENT_PHASE,
+    MESSAGE_REDACTION_APPLIED_ENRICHMENT_PHASE,
+    # MARK: - Model Events
+    MODEL_TOOL_COMPLETE_EVENT_NAME,
+    PROGRESS_UPDATE_EVENT_NAME,
+    REDACTION_ENRICHMENT_PHASES,
+    REDACTION_PREVIEWED_ENRICHMENT_PHASE,
+    RESOURCE_DEDUP_REUSED_ENRICHMENT_PHASE,
+    RESOURCE_ENRICHMENT_PHASES,
+    RESOURCE_EXTRACTED_ENRICHMENT_PHASE,
+    RESOURCE_EXTRACTING_ENRICHMENT_PHASE,
+    RESOURCE_REGISTERED_ENRICHMENT_PHASE,
+    RESOURCE_REGISTERING_ENRICHMENT_PHASE,
+    RESOURCE_VERSION_SUPERSEDED_ENRICHMENT_PHASE,
+    STATUS_MESSAGE_EVENT_NAME,
+    SYSTEM_TOOL_CHUNK_EVENT_NAME,
+    SYSTEM_TOOL_COMPLETE_EVENT_NAME,
+    SYSTEM_TOOL_ERROR_EVENT_NAME,
+    # MARK: - System Tool Events
+    SYSTEM_TOOL_START_EVENT_NAME,
+    # MARK: - Tool Events
+    TOOL_EVENT_NAME,
+    UPDATE_EVENT_NAME,
+)
+
+__all__ = [
+    # MARK: - Utilities
+    "create_uuid",
+    # MARK: - Tool Events
+    "TOOL_EVENT_NAME",
+    "INTERRUPT_REQUEST_EVENT_NAME",
+    "INTERRUPT_REQUIRED_EVENT_NAME",
+    # MARK: - Assignment Events
+    "ASSIGNMENT_RECEIVED_EVENT_NAME",
+    "ASSIGNMENT_COMPLETED_EVENT_NAME",
+    # MARK: - Model Events
+    "MODEL_TOOL_COMPLETE_EVENT_NAME",
+    # MARK: - Lifecycle Events
+    "HEARTBEAT_EVENT_NAME",
+    "UPDATE_EVENT_NAME",
+    "PROGRESS_UPDATE_EVENT_NAME",
+    "STATUS_MESSAGE_EVENT_NAME",
+    "FINAL_EVENT_NAME",
+    "ERROR_EVENT_NAME",
+    # MARK: - System Tool Events
+    "SYSTEM_TOOL_START_EVENT_NAME",
+    "SYSTEM_TOOL_CHUNK_EVENT_NAME",
+    "SYSTEM_TOOL_COMPLETE_EVENT_NAME",
+    "SYSTEM_TOOL_ERROR_EVENT_NAME",
+    # MARK: - Enrichment Events
+    "ENRICHMENT_EVENT_NAME",
+    "MEMORY_SUMMARIZING_ENRICHMENT_PHASE",
+    "MEMORY_SUMMARIZED_ENRICHMENT_PHASE",
+    "MEMORY_RETRIEVING_ENRICHMENT_PHASE",
+    "MEMORY_RETRIEVED_ENRICHMENT_PHASE",
+    "MEMORY_INDEXING_ENRICHMENT_PHASE",
+    "MEMORY_INDEXED_ENRICHMENT_PHASE",
+    "MEMORY_GRAPH_EXTRACTING_ENRICHMENT_PHASE",
+    "MEMORY_SKILL_EXTRACTING_ENRICHMENT_PHASE",
+    "MEMORY_INSIGHT_EXTRACTING_ENRICHMENT_PHASE",
+    "MEMORY_SKILL_EXTRACTED_ENRICHMENT_PHASE",
+    "MEMORY_INSIGHT_EXTRACTED_ENRICHMENT_PHASE",
+    "MEMORY_ENRICHMENT_PHASES",
+    "MESSAGE_REDACTION_APPLIED_ENRICHMENT_PHASE",
+    "REDACTION_PREVIEWED_ENRICHMENT_PHASE",
+    "REDACTION_ENRICHMENT_PHASES",
+    "RESOURCE_REGISTERING_ENRICHMENT_PHASE",
+    "RESOURCE_REGISTERED_ENRICHMENT_PHASE",
+    "RESOURCE_DEDUP_REUSED_ENRICHMENT_PHASE",
+    "RESOURCE_VERSION_SUPERSEDED_ENRICHMENT_PHASE",
+    "RESOURCE_EXTRACTING_ENRICHMENT_PHASE",
+    "RESOURCE_EXTRACTED_ENRICHMENT_PHASE",
+    "RESOURCE_ENRICHMENT_PHASES",
+]

maivn_shared/core/data/__init__.py

@@ -0,0 +1,11 @@
+"""Data utilities for maivn-core."""
+
+from __future__ import annotations
+
+# MARK: - ID Generation
+from .id_generator import create_uuid
+
+__all__ = [
+    # MARK: - ID Generation
+    "create_uuid",
+]

maivn_shared/core/data/id_generator.py

@@ -0,0 +1,94 @@
+"""UUID generation utilities for maivn-core.
+
+This module provides utilities for generating unique identifiers,
+supporting both random and deterministic UUID generation.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+# MARK: - UUID Utilities
+
+
+def create_uuid(obj: object | None = None) -> str:
+    """Create a unique identifier as a string.
+
+    If an object is provided, generate a deterministic UUID v5 using the object's
+    intrinsic properties (module + qualname for functions/classes, or repr for others).
+    Otherwise, return a random UUID v4.
+
+    Args:
+        obj: Optional object to generate deterministic UUID from
+
+    Returns:
+        UUID string (deterministic if obj provided, random otherwise)
+    """
+    if obj is None:
+        return str(uuid.uuid4())
+
+    identifier = _get_deterministic_identifier(obj)
+    return str(uuid.uuid5(uuid.NAMESPACE_DNS, identifier))
+
+
+# MARK: - Helper Functions
+
+
+def _get_deterministic_identifier(obj: object) -> str:
+    """Get a deterministic identifier string for an object.
+
+    For functions and classes, uses module + qualname for consistency across runs.
+    For other objects, falls back to type name + repr.
+
+    Args:
+        obj: Object to generate identifier for
+
+    Returns:
+        Deterministic identifier string
+    """
+    if callable(obj) or isinstance(obj, type):
+        identifier = _get_callable_identifier(obj)
+        if identifier:
+            return identifier
+
+    return _get_fallback_identifier(obj)
+
+
+def _get_callable_identifier(obj: object) -> str | None:
+    """Get identifier for callable objects using module and qualname.
+
+    Args:
+        obj: Callable object or type
+
+    Returns:
+        Identifier string or None if not determinable
+    """
+    module = getattr(obj, "__module__", None)
+    if not module:
+        return None
+
+    qualname = getattr(obj, "__qualname__", None)
+    if qualname:
+        return f"{module}.{qualname}"
+
+    name = getattr(obj, "__name__", None)
+    if name:
+        return f"{module}.{name}"
+
+    return None
+
+
+def _get_fallback_identifier(obj: object) -> str:
+    """Get fallback identifier using type and repr.
+
+    Args:
+        obj: Object to generate identifier for
+
+    Returns:
+        Fallback identifier string
+    """
+    type_name = type(obj).__name__
+    try:
+        return f"{type_name}:{repr(obj)}"
+    except Exception:
+        return f"{type_name}:{id(obj)}"

maivn_shared/core/events.py

@@ -0,0 +1,211 @@
+"""Shared event-name constants used across Maivn services and SDK."""
+
+from __future__ import annotations
+
+# MARK: - Tool Events
+
+TOOL_EVENT_NAME = "tool_event"
+"""Primary event name emitted by the server bridge and consumed by the SDK."""
+
+INTERRUPT_REQUEST_EVENT_NAME = "interrupt_request"
+"""Interrupt request event emitted when a tool requires user input."""
+
+INTERRUPT_REQUIRED_EVENT_NAME = "interrupt_required"
+"""Interrupt required event indicating user action is needed."""
+
+# MARK: - Assignment Events
+
+ASSIGNMENT_RECEIVED_EVENT_NAME = "assignment_received"
+"""Emitted when an assignment is received by an agent."""
+
+ASSIGNMENT_COMPLETED_EVENT_NAME = "assignment_completed"
+"""Emitted when an assignment is completed by an agent."""
+
+# MARK: - Model Events
+
+MODEL_TOOL_COMPLETE_EVENT_NAME = "model_tool_complete"
+"""Emitted when a model tool call completes."""
+
+# MARK: - Lifecycle Events
+
+HEARTBEAT_EVENT_NAME = "heartbeat"
+"""Periodic heartbeat event for connection health."""
+
+UPDATE_EVENT_NAME = "update"
+"""Progress update event during execution."""
+
+PROGRESS_UPDATE_EVENT_NAME = "progress_update"
+"""Progress update event for streamed response content during execution."""
+
+STATUS_MESSAGE_EVENT_NAME = "status_message"
+"""Standalone status message emitted at swarm lifecycle milestones.
+
+Unlike ``progress_update`` (which carries streaming deltas that accumulate
+into a single response), a ``status_message`` is a self-contained,
+human-readable notification (e.g. "Dispatching 3 agents: ...").  Clients
+should display each one as its own UI element rather than appending to
+the assistant response stream.
+
+Payload: ``{"message": str, "assistant_id": str}``
+"""
+
+FINAL_EVENT_NAME = "final"
+"""Final event indicating execution completion."""
+
+ERROR_EVENT_NAME = "error"
+"""Error event indicating execution failure."""
+
+# MARK: - System Tool Events
+
+SYSTEM_TOOL_START_EVENT_NAME = "system_tool_start"
+"""Emitted when a system tool (web_search, repl, think) starts execution."""
+
+SYSTEM_TOOL_CHUNK_EVENT_NAME = "system_tool_chunk"
+"""Emitted when a system tool produces a streaming chunk during execution."""
+
+SYSTEM_TOOL_COMPLETE_EVENT_NAME = "system_tool_complete"
+"""Emitted when a system tool completes execution."""
+
+SYSTEM_TOOL_ERROR_EVENT_NAME = "system_tool_error"
+"""Emitted when a system tool encounters an error."""
+
+# MARK: - Enrichment Events
+
+ENRICHMENT_EVENT_NAME = "enrichment"
+"""Emitted when an agent transitions to a new execution phase (evaluating, planning, etc.)."""
+
+MEMORY_SUMMARIZING_ENRICHMENT_PHASE = "memory_summarizing"
+"""Enrichment phase emitted before memory summarize-mode execution."""
+
+MEMORY_SUMMARIZED_ENRICHMENT_PHASE = "memory_summarized"
+"""Enrichment phase emitted after memory summarize-mode execution completes."""
+
+MEMORY_RETRIEVING_ENRICHMENT_PHASE = "memory_retrieving"
+"""Enrichment phase emitted before memory retrieve-mode execution."""
+
+MEMORY_RETRIEVED_ENRICHMENT_PHASE = "memory_retrieved"
+"""Enrichment phase emitted after memory retrieval completes."""
+
+MEMORY_INDEXING_ENRICHMENT_PHASE = "memory_indexing"
+"""Enrichment phase emitted before memory index-mode execution."""
+
+MEMORY_INDEXED_ENRICHMENT_PHASE = "memory_indexed"
+"""Enrichment phase emitted after memory index-mode execution completes."""
+
+MEMORY_GRAPH_EXTRACTING_ENRICHMENT_PHASE = "memory_graph_extracting"
+"""Enrichment phase emitted before graph/entity extraction in index-mode."""
+
+MEMORY_SKILL_EXTRACTING_ENRICHMENT_PHASE = "memory_skill_extracting"
+"""Enrichment phase emitted while post-run skill extraction is in progress."""
+
+MEMORY_INSIGHT_EXTRACTING_ENRICHMENT_PHASE = "memory_insight_extracting"
+"""Enrichment phase emitted while post-run insight extraction is in progress."""
+
+MEMORY_SKILL_EXTRACTED_ENRICHMENT_PHASE = "memory_skill_extracted"
+"""Enrichment phase emitted after post-run skill extraction completes."""
+
+MEMORY_INSIGHT_EXTRACTED_ENRICHMENT_PHASE = "memory_insight_extracted"
+"""Enrichment phase emitted after post-run insight extraction completes."""
+
+MEMORY_ENRICHMENT_PHASES = (
+    MEMORY_SUMMARIZING_ENRICHMENT_PHASE,
+    MEMORY_SUMMARIZED_ENRICHMENT_PHASE,
+    MEMORY_RETRIEVING_ENRICHMENT_PHASE,
+    MEMORY_RETRIEVED_ENRICHMENT_PHASE,
+    MEMORY_INDEXING_ENRICHMENT_PHASE,
+    MEMORY_INDEXED_ENRICHMENT_PHASE,
+    MEMORY_GRAPH_EXTRACTING_ENRICHMENT_PHASE,
+    MEMORY_SKILL_EXTRACTING_ENRICHMENT_PHASE,
+    MEMORY_INSIGHT_EXTRACTING_ENRICHMENT_PHASE,
+    MEMORY_SKILL_EXTRACTED_ENRICHMENT_PHASE,
+    MEMORY_INSIGHT_EXTRACTED_ENRICHMENT_PHASE,
+)
+"""Canonical memory-related enrichment phase identifiers."""
+
+REDACTION_PREVIEWED_ENRICHMENT_PHASE = "redaction_previewed"
+"""Enrichment phase emitted when an explicit redaction preview completes."""
+
+MESSAGE_REDACTION_APPLIED_ENRICHMENT_PHASE = "message_redaction_applied"
+"""Enrichment phase emitted when message redaction is applied during normal execution setup."""
+
+REDACTION_ENRICHMENT_PHASES = (
+    REDACTION_PREVIEWED_ENRICHMENT_PHASE,
+    MESSAGE_REDACTION_APPLIED_ENRICHMENT_PHASE,
+)
+"""Canonical redaction-related enrichment phase identifiers."""
+
+RESOURCE_REGISTERING_ENRICHMENT_PHASE = "resource_registering"
+"""Enrichment phase emitted when resource registration begins."""
+
+RESOURCE_REGISTERED_ENRICHMENT_PHASE = "resource_registered"
+"""Enrichment phase emitted when resource registration completes."""
+
+RESOURCE_DEDUP_REUSED_ENRICHMENT_PHASE = "resource_dedup_reused"
+"""Enrichment phase emitted when existing resource content is reused (dedup)."""
+
+RESOURCE_VERSION_SUPERSEDED_ENRICHMENT_PHASE = "resource_version_superseded"
+"""Enrichment phase emitted when a previous resource version is superseded."""
+
+RESOURCE_EXTRACTING_ENRICHMENT_PHASE = "resource_extracting"
+"""Enrichment phase emitted when resource extraction starts."""
+
+RESOURCE_EXTRACTED_ENRICHMENT_PHASE = "resource_extracted"
+"""Enrichment phase emitted when resource extraction completes."""
+
+RESOURCE_ENRICHMENT_PHASES = (
+    RESOURCE_REGISTERING_ENRICHMENT_PHASE,
+    RESOURCE_REGISTERED_ENRICHMENT_PHASE,
+    RESOURCE_DEDUP_REUSED_ENRICHMENT_PHASE,
+    RESOURCE_VERSION_SUPERSEDED_ENRICHMENT_PHASE,
+    RESOURCE_EXTRACTING_ENRICHMENT_PHASE,
+    RESOURCE_EXTRACTED_ENRICHMENT_PHASE,
+)
+"""Canonical resource-related enrichment phase identifiers."""
+
+__all__ = [
+    # Tool Events
+    "TOOL_EVENT_NAME",
+    "INTERRUPT_REQUEST_EVENT_NAME",
+    "INTERRUPT_REQUIRED_EVENT_NAME",
+    # Assignment Events
+    "ASSIGNMENT_RECEIVED_EVENT_NAME",
+    "ASSIGNMENT_COMPLETED_EVENT_NAME",
+    # Model Events
+    "MODEL_TOOL_COMPLETE_EVENT_NAME",
+    # Lifecycle Events
+    "HEARTBEAT_EVENT_NAME",
+    "UPDATE_EVENT_NAME",
+    "PROGRESS_UPDATE_EVENT_NAME",
+    "STATUS_MESSAGE_EVENT_NAME",
+    "FINAL_EVENT_NAME",
+    "ERROR_EVENT_NAME",
+    # System Tool Events
+    "SYSTEM_TOOL_START_EVENT_NAME",
+    "SYSTEM_TOOL_CHUNK_EVENT_NAME",
+    "SYSTEM_TOOL_COMPLETE_EVENT_NAME",
+    "SYSTEM_TOOL_ERROR_EVENT_NAME",
+    # Enrichment Events
+    "ENRICHMENT_EVENT_NAME",
+    "MEMORY_SUMMARIZING_ENRICHMENT_PHASE",
+    "MEMORY_SUMMARIZED_ENRICHMENT_PHASE",
+    "MEMORY_RETRIEVING_ENRICHMENT_PHASE",
+    "MEMORY_RETRIEVED_ENRICHMENT_PHASE",
+    "MEMORY_INDEXING_ENRICHMENT_PHASE",
+    "MEMORY_INDEXED_ENRICHMENT_PHASE",
+    "MEMORY_GRAPH_EXTRACTING_ENRICHMENT_PHASE",
+    "MEMORY_SKILL_EXTRACTING_ENRICHMENT_PHASE",
+    "MEMORY_INSIGHT_EXTRACTING_ENRICHMENT_PHASE",
+    "MEMORY_SKILL_EXTRACTED_ENRICHMENT_PHASE",
+    "MEMORY_INSIGHT_EXTRACTED_ENRICHMENT_PHASE",
+    "MEMORY_ENRICHMENT_PHASES",
+    "REDACTION_PREVIEWED_ENRICHMENT_PHASE",
+    "MESSAGE_REDACTION_APPLIED_ENRICHMENT_PHASE",
+    "REDACTION_ENRICHMENT_PHASES",
+    "RESOURCE_REGISTERING_ENRICHMENT_PHASE",
+    "RESOURCE_REGISTERED_ENRICHMENT_PHASE",
+    "RESOURCE_DEDUP_REUSED_ENRICHMENT_PHASE",
+    "RESOURCE_VERSION_SUPERSEDED_ENRICHMENT_PHASE",
+    "RESOURCE_EXTRACTING_ENRICHMENT_PHASE",
+    "RESOURCE_EXTRACTED_ENRICHMENT_PHASE",
+    "RESOURCE_ENRICHMENT_PHASES",
+]