@ngocsangairvds/vsaf 3.2.14 → 3.2.16

package/tools/vds-scripts/multi_agent_orchestrator/src/vds_multi_agent_orchestrator/models.py

@@ -1,389 +0,0 @@
-"""Data models for multi-agent coordination system."""
-
-import json
-import re
-from dataclasses import dataclass, field
-from datetime import UTC, datetime
-from enum import StrEnum
-from typing import Any
-
-from vds_agent_core.security.credentials import looks_like_raw_credential
-
-# Phase 225 Track-B (FR-226.4): credentials may not be inlined in Agent
-# settings dicts. Only ``${env:VAR_NAME}`` indirection is permitted for
-# values destined for ``api_key`` (and other secret fields).
-_ENV_INDIRECTION_RE = re.compile(r"^\$\{env:[A-Za-z_][A-Za-z0-9_]*\}$")
-_SECRET_FIELDS: frozenset[str] = frozenset({"api_key", "auth_token", "token", "secret"})
-# Redaction sentinel returned by GET /agents/<id> for any secret field.
-_REDACTED_SECRET = "${env:REDACTED}"
-# W7 v20.6.1 logic-MEDIUM-3 fix: cap recursion depth to prevent malicious
-# JSON nesting (`{"a": {"a": ...}}` 10k deep) from triggering RecursionError
-# at request-ingestion. Real Agent payloads nest 1-3 deep at most.
-_MAX_CREDENTIAL_SCAN_DEPTH = 64
-
-
-def _validate_no_raw_credentials(
-    settings_dict: dict[str, Any] | None, *, field_label: str
-) -> dict[str, Any] | None:
-    """Reject raw ``sk-``/``hf_``/``Bearer `` values in agent settings dicts.
-
-    Used by AgentRegistrationRequest validators (FR-226.4, NFR-225.14).
-    Returns the dict unchanged if it is valid; raises ``ValueError`` otherwise.
-
-    W6 BLOCKER-2 fix: recurses into nested dicts and lists so a payload like
-    ``{"nested": {"api_key": "sk-secret"}}`` cannot bypass the validator.
-    W7 logic-MEDIUM-3 fix: bounded recursion depth (see
-    ``_MAX_CREDENTIAL_SCAN_DEPTH``) prevents malicious deep-nesting DoS.
-    """
-    if settings_dict is None:
-        return None
-    if not isinstance(settings_dict, dict):
-        raise ValueError(f"{field_label} must be a dict; got {type(settings_dict).__name__}")
-    _scan_for_raw_credentials(settings_dict, path=field_label, depth=0)
-    return settings_dict
-
-
-def _scan_for_raw_credentials(value: Any, *, path: str, depth: int = 0) -> None:
-    """Walk a JSON-shaped structure rejecting raw credential prefixes anywhere.
-
-    Recurses through dicts and lists; checks scalar leaf values via
-    ``looks_like_raw_credential``. Path is reported on error for operator
-    debuggability (e.g. ``llm_settings.nested.api_key``).
-
-    W7 v20.6.1 logic-MEDIUM-3 fix: ``depth`` parameter caps recursion at
-    ``_MAX_CREDENTIAL_SCAN_DEPTH``; deeper structures raise ``ValueError``
-    rather than triggering ``RecursionError`` (DoS prevention).
-    """
-    if depth > _MAX_CREDENTIAL_SCAN_DEPTH:
-        raise ValueError(
-            f"{path} exceeds credential-scan recursion depth "
-            f"({_MAX_CREDENTIAL_SCAN_DEPTH}); reject suspicious payload"
-        )
-    if isinstance(value, dict):
-        for k, v in value.items():
-            _scan_for_raw_credentials(v, path=f"{path}.{k}", depth=depth + 1)
-    elif isinstance(value, list):
-        for i, item in enumerate(value):
-            _scan_for_raw_credentials(item, path=f"{path}[{i}]", depth=depth + 1)
-    elif looks_like_raw_credential(value):
-        raise ValueError(
-            f"{path} contains a raw credential prefix "
-            "(sk-/hf_/Bearer ); use ${env:VAR_NAME} indirection instead"
-        )
-
-
-def redact_agent_secrets(settings_dict: dict[str, Any] | None) -> dict[str, Any] | None:
-    """Return a copy of ``settings_dict`` with secret fields redacted.
-
-    Used by GET /agents/<id> response handlers (NFR-225.14). Operates on a
-    copy so callers can serialize without mutating the source.
-
-    W7 v20.6.1 logic-MEDIUM-5 fix: recurses through nested dicts and lists.
-    Previously only the top-level secret keys were redacted, which leaked
-    secrets stored at depth (e.g. ``{"providers": [{"api_key": "..."}]}``).
-    Mirrors the recursion shape of ``_scan_for_raw_credentials`` so accept
-    and redact decisions stay symmetric.
-    """
-    if settings_dict is None:
-        return None
-    if not isinstance(settings_dict, dict):
-        return settings_dict
-    return _walk_and_redact(settings_dict, depth=0)
-
-
-def _walk_and_redact(value: Any, *, depth: int = 0) -> Any:
-    """Walk ``value`` returning a new structure with secret fields redacted.
-
-    Returns scalars unchanged; copies dicts and lists; replaces values whose
-    KEY appears in ``_SECRET_FIELDS`` with ``_REDACTED_SECRET``. Recursion
-    depth bound mirrors ``_MAX_CREDENTIAL_SCAN_DEPTH``.
-    """
-    if depth > _MAX_CREDENTIAL_SCAN_DEPTH:
-        # Defensive: stop recursing rather than raise, since GET responses
-        # should never crash on a malformed-but-already-stored payload.
-        return _REDACTED_SECRET
-    if isinstance(value, dict):
-        out: dict[str, Any] = {}
-        for k, v in value.items():
-            # NFR-225.14 contract: ALL secret-keyed values are redacted at the
-            # GET response boundary, regardless of whether the stored value is
-            # a raw credential or an env-indirection reference. The validator
-            # at request-ingestion already rejects raw credentials, so stored
-            # values should already be ``${env:VAR}`` references; redacting
-            # them uniformly preserves a consistent on-the-wire shape.
-            if k in _SECRET_FIELDS and v is not None:
-                out[k] = _REDACTED_SECRET
-            else:
-                out[k] = _walk_and_redact(v, depth=depth + 1)
-        return out
-    if isinstance(value, list):
-        return [_walk_and_redact(item, depth=depth + 1) for item in value]
-    return value
-
-
-class TaskStatusEnum(StrEnum):
-    """Task status enumeration."""
-
-    PENDING = "pending"
-    IN_PROGRESS = "in_progress"
-    COMPLETED = "completed"
-    FAILED = "failed"
-    BLOCKED = "blocked"
-
-
-class AgentStatusEnum(StrEnum):
-    """Agent status enumeration."""
-
-    AVAILABLE = "available"
-    BUSY = "busy"
-    OFFLINE = "offline"
-    ERROR = "error"
-
-
-class ImportanceLevel(StrEnum):
-    """Memory importance levels for VDS-AI-Memory integration."""
-
-    LOW = "low"
-    MEDIUM = "medium"
-    HIGH = "high"
-    CRITICAL = "critical"
-
-
-class MemoryCategory(StrEnum):
-    """Memory categories for VDS-AI-Memory integration."""
-
-    GENERAL = "general"
-    BUSINESS_LOGIC = "business-logic"
-    SESSION_SUMMARY = "session-summary"
-    ERROR = "error"
-    PERFORMANCE = "performance"
-    VALIDATION = "validation"
-
-
-@dataclass
-class Task:
-    """Task data model."""
-
-    id: str
-    service_id: str
-    task_type: str
-    phase: str
-    dependencies: list[str] = field(default_factory=list)
-    status: TaskStatusEnum = TaskStatusEnum.PENDING
-    assigned_agent: str | None = None
-    created_at: datetime = field(default_factory=lambda: datetime.now(UTC))
-    started_at: datetime | None = None
-    completed_at: datetime | None = None
-    progress: float = 0.0
-    result: dict[str, Any] | None = None
-    error_message: str | None = None
-
-    def to_dict(self) -> dict[str, Any]:
-        """Convert task to dictionary for Redis storage."""
-        return {
-            "id": self.id,
-            "service_id": self.service_id,
-            "task_type": self.task_type,
-            "phase": self.phase,
-            "dependencies": json.dumps(self.dependencies),
-            "status": self.status.value,
-            "assigned_agent": self.assigned_agent,
-            "created_at": self.created_at.isoformat(),
-            "started_at": self.started_at.isoformat() if self.started_at else None,
-            "completed_at": self.completed_at.isoformat() if self.completed_at else None,
-            "progress": self.progress,
-            "result": json.dumps(self.result) if self.result else None,
-            "error_message": self.error_message,
-        }
-
-    @classmethod
-    def from_dict(cls, data: dict[str, Any]) -> "Task":
-        """Create task from dictionary loaded from Redis."""
-        return cls(
-            id=data["id"],
-            service_id=data["service_id"],
-            task_type=data["task_type"],
-            phase=data["phase"],
-            dependencies=json.loads(data.get("dependencies", "[]")),
-            status=TaskStatusEnum(data["status"]),
-            assigned_agent=data.get("assigned_agent"),
-            created_at=datetime.fromisoformat(data["created_at"]),
-            started_at=datetime.fromisoformat(data["started_at"])
-            if data.get("started_at")
-            else None,
-            completed_at=datetime.fromisoformat(data["completed_at"])
-            if data.get("completed_at")
-            else None,
-            progress=float(data.get("progress", 0.0)),
-            result=json.loads(data["result"]) if data.get("result") else None,
-            error_message=data.get("error_message"),
-        )
-
-
-@dataclass
-class Agent:
-    """Agent data model.
-
-    Phase 225 Track-B (FR-226.4): ``llm_settings`` and ``embedding_settings``
-    carry per-agent overrides loaded by ``LLMSettings.for_agent`` /
-    ``EmbeddingSettings.for_agent`` as Path B input. Values must use
-    ``${env:VAR_NAME}`` indirection; raw credentials are rejected at the
-    request-ingestion validator (NFR-225.14).
-    """
-
-    agent_id: str
-    capabilities: list[str]
-    max_concurrent_tasks: int = 1
-    current_tasks: int = 0
-    status: AgentStatusEnum = AgentStatusEnum.AVAILABLE
-    registered_at: datetime = field(default_factory=lambda: datetime.now(UTC))
-    last_heartbeat: datetime = field(default_factory=lambda: datetime.now(UTC))
-    llm_settings: dict[str, Any] | None = None
-    embedding_settings: dict[str, Any] | None = None
-
-    def to_dict(self) -> dict[str, Any]:
-        """Convert agent to dictionary for Redis storage."""
-        return {
-            "agent_id": self.agent_id,
-            "capabilities": json.dumps(self.capabilities),
-            "max_concurrent_tasks": self.max_concurrent_tasks,
-            "current_tasks": self.current_tasks,
-            "status": self.status.value,
-            "registered_at": self.registered_at.isoformat(),
-            "last_heartbeat": self.last_heartbeat.isoformat(),
-            "llm_settings": json.dumps(self.llm_settings) if self.llm_settings else None,
-            "embedding_settings": (
-                json.dumps(self.embedding_settings) if self.embedding_settings else None
-            ),
-        }
-
-    @classmethod
-    def from_dict(cls, data: dict[str, Any]) -> "Agent":
-        """Create agent from dictionary loaded from Redis."""
-        llm_settings_raw = data.get("llm_settings")
-        embedding_settings_raw = data.get("embedding_settings")
-        return cls(
-            agent_id=data["agent_id"],
-            capabilities=json.loads(data["capabilities"]),
-            max_concurrent_tasks=int(data["max_concurrent_tasks"]),
-            current_tasks=int(data.get("current_tasks", 0)),
-            status=AgentStatusEnum(data["status"]),
-            registered_at=datetime.fromisoformat(data["registered_at"]),
-            last_heartbeat=datetime.fromisoformat(data["last_heartbeat"]),
-            llm_settings=(
-                json.loads(llm_settings_raw)
-                if isinstance(llm_settings_raw, str) and llm_settings_raw
-                else llm_settings_raw
-            ),
-            embedding_settings=(
-                json.loads(embedding_settings_raw)
-                if isinstance(embedding_settings_raw, str) and embedding_settings_raw
-                else embedding_settings_raw
-            ),
-        )
-
-
-@dataclass
-class ServiceConfig:
-    """Service configuration for documentation generation."""
-
-    service_id: str
-    service_name: str
-    category: str
-    priority: str
-    has_complex_state_transitions: bool = False
-    handles_sensitive_data: bool = False
-    is_intelligent_service: bool = False
-    has_cross_service_dependencies: bool = False
-    brd_sections: list[str] = field(default_factory=list)
-
-    @property
-    def is_high_priority(self) -> bool:
-        """Check if service is high priority."""
-        return self.priority.lower() == "high"
-
-
-@dataclass
-class MemoryCreateRequest:
-    """Request model for VDS-AI-Memory integration."""
-
-    content: str
-    category: MemoryCategory
-    importance: ImportanceLevel
-    session_id: str
-    user_id: str
-    metadata: dict[str, Any] = field(default_factory=dict)
-    force_mem0: bool = False
-
-
-@dataclass
-class MemorySearchRequest:
-    """Search request model for VDS-AI-Memory integration."""
-
-    query: str
-    session_id: str
-    user_id: str
-    limit: int = 10
-    metadata_filters: dict[str, Any] | None = None
-
-
-@dataclass
-class TaskProgress:
-    """Task progress update model."""
-
-    task_id: str
-    agent_id: str
-    progress: float
-    status: TaskStatusEnum | None = None
-    message: str | None = None
-    timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
-
-
-@dataclass
-class ConflictInfo:
-    """Conflict information model."""
-
-    conflict_type: str
-    file_path: str
-    agent_id: str
-    operation: str
-    duration_minutes: float
-    details: dict[str, Any] = field(default_factory=dict)
-
-
-@dataclass
-class ChangeLogEntry:
-    """Change log entry model."""
-
-    agent_id: str
-    file_path: str
-    operation: str
-    task_id: str | None = None
-    git_commit_hash: str | None = None
-    timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
-    details: dict[str, Any] = field(default_factory=dict)
-
-
-# Exception classes
-class ConflictError(Exception):
-    """Raised when a conflict is detected in multi-agent operations."""
-
-    pass
-
-
-class ValidationError(Exception):
-    """Raised when validation fails."""
-
-    pass
-
-
-class TaskAcquisitionError(Exception):
-    """Raised when task acquisition fails."""
-
-    pass
-
-
-class AgentRegistrationError(Exception):
-    """Raised when agent registration fails."""
-
-    pass