nexus-coding-agent 0.1.0__py3-none-any.whl

nexus/domain/skills.py

@@ -0,0 +1,129 @@
+"""Frozen Day 7 Skill values."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import PurePosixPath
+
+_SKILL_ID = re.compile(r"^[a-z][a-z0-9-]{0,63}$")
+_SEMVER_CORE = re.compile(r"^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$")
+
+
+class SkillSource(StrEnum):
+    REPOSITORY = "repository"
+    USER_GLOBAL = "user_global"
+    BUILTIN = "builtin"
+
+
+@dataclass(frozen=True, slots=True)
+class SkillLocation:
+    source: SkillSource
+    relative_path: str
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.source, SkillSource) or not isinstance(self.relative_path, str):
+            raise ValueError("Skill location fields are invalid.")
+        path = PurePosixPath(self.relative_path)
+        if (
+            path.is_absolute()
+            or len(path.parts) != 2
+            or path.parts[-1] != "SKILL.md"
+            or not _SKILL_ID.fullmatch(path.parts[0])
+            or self.relative_path != path.as_posix()
+        ):
+            raise ValueError("Skill location must use <skill-id>/SKILL.md.")
+
+
+@dataclass(frozen=True, slots=True)
+class SkillMetadata:
+    skill_id: str
+    name: str
+    description: str
+    usage_scenario: str
+    source: SkillSource
+    priority: int
+    version: str
+    location: SkillLocation
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.skill_id, str) or not _SKILL_ID.fullmatch(self.skill_id):
+            raise ValueError("Skill ID is invalid.")
+        for field_name, value, maximum in (
+            ("name", self.name, 100),
+            ("description", self.description, 500),
+            ("usage_scenario", self.usage_scenario, 500),
+        ):
+            if not isinstance(value, str):
+                raise ValueError(f"Skill {field_name} is invalid.")
+            normalized = value.strip()
+            if not normalized or len(normalized) > maximum:
+                raise ValueError(f"Skill {field_name} is invalid.")
+            object.__setattr__(self, field_name, normalized)
+        if (
+            isinstance(self.priority, bool)
+            or not isinstance(self.priority, int)
+            or not 0 <= self.priority <= 100
+        ):
+            raise ValueError("Skill priority must be an integer from 0 through 100.")
+        if not isinstance(self.version, str) or not _SEMVER_CORE.fullmatch(self.version):
+            raise ValueError("Skill version must use SemVer core form.")
+        if not isinstance(self.location, SkillLocation) or not isinstance(
+            self.source, SkillSource
+        ):
+            raise ValueError("Skill source and location are invalid.")
+        if self.location.source is not self.source:
+            raise ValueError("Skill source and location source must match.")
+        if PurePosixPath(self.location.relative_path).parts[0] != self.skill_id:
+            raise ValueError("Skill directory and ID must match.")
+
+
+@dataclass(frozen=True, slots=True)
+class SelectedSkill:
+    metadata: SkillMetadata
+    body: str
+    selected_reason: str
+
+    def __post_init__(self) -> None:
+        if (
+            not isinstance(self.body, str)
+            or not self.body.strip()
+            or "\r" in self.body
+            or not self.body.endswith("\n")
+            or self.body.endswith("\n\n")
+        ):
+            raise ValueError("Selected Skill body is not normalized.")
+        normalized_reason = _selection_summary(self.selected_reason)
+        object.__setattr__(self, "selected_reason", normalized_reason)
+
+
+@dataclass(frozen=True, slots=True)
+class SkillSelectionResult:
+    selected_skill_ids: tuple[str, ...]
+    selection_reason_summary: str
+
+    def __post_init__(self) -> None:
+        if isinstance(self.selected_skill_ids, str):
+            raise ValueError("Selected Skill IDs must be a sequence of identities.")
+        skill_ids = tuple(self.selected_skill_ids)
+        if len(skill_ids) > 2 or len(skill_ids) != len(set(skill_ids)) or any(
+            not isinstance(skill_id, str) or not _SKILL_ID.fullmatch(skill_id)
+            for skill_id in skill_ids
+        ):
+            raise ValueError("Selected Skill IDs must be valid and unique.")
+        object.__setattr__(self, "selected_skill_ids", skill_ids)
+        object.__setattr__(
+            self,
+            "selection_reason_summary",
+            _selection_summary(self.selection_reason_summary),
+        )
+
+
+def _selection_summary(value: str) -> str:
+    if not isinstance(value, str):
+        raise ValueError("Skill selection summary is invalid.")
+    normalized = value.strip()
+    if not normalized or len(normalized) > 1000:
+        raise ValueError("Skill selection summary is invalid.")
+    return normalized

nexus/domain/tooling.py

@@ -0,0 +1,163 @@
+"""Nexus-owned Day 3 tool, policy, and sandbox values."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from uuid import UUID
+
+JsonObject = dict[str, object]
+
+
+class RiskLevel(StrEnum):
+    SAFE = "SAFE"
+    WRITE = "WRITE"
+    DANGEROUS = "DANGEROUS"
+
+
+class ApprovalDecision(StrEnum):
+    PENDING = "PENDING"
+    APPROVED = "APPROVED"
+    DENIED = "DENIED"
+
+
+class PolicyDecision(StrEnum):
+    ALLOWED = "ALLOWED"
+    DENIED = "DENIED"
+
+
+@dataclass(frozen=True, slots=True)
+class ToolInvocation:
+    invocation_id: str
+    tool_name: str
+    arguments: JsonObject
+    run_id: str
+    session_id: str
+
+    def __post_init__(self) -> None:
+        _validate_uuid(self.invocation_id, "invocation_id")
+        _validate_uuid(self.run_id, "run_id")
+        _validate_uuid(self.session_id, "session_id")
+        if not self.tool_name:
+            raise ValueError("tool_name must not be empty.")
+        if any(not isinstance(key, str) for key in self.arguments):
+            raise ValueError("Tool argument keys must be strings.")
+        if not _is_json_value(self.arguments):
+            raise ValueError("Tool arguments must contain only JSON-compatible values.")
+        object.__setattr__(self, "arguments", dict(self.arguments))
+
+
+@dataclass(frozen=True, slots=True)
+class ToolError:
+    code: str
+    message: str
+    retryable: bool
+
+    def __post_init__(self) -> None:
+        if not self.code or not self.message:
+            raise ValueError("ToolError code and message must not be empty.")
+
+
+@dataclass(frozen=True, slots=True)
+class ToolResult:
+    invocation_id: str
+    tool_name: str
+    success: bool
+    output: JsonObject | None
+    error: ToolError | None
+    risk_level: RiskLevel
+    policy_decision: PolicyDecision
+    approval_decision: ApprovalDecision | None
+    duration_ms: int
+
+    def __post_init__(self) -> None:
+        _validate_uuid(self.invocation_id, "invocation_id")
+        if not self.tool_name:
+            raise ValueError("tool_name must not be empty.")
+        if self.duration_ms < 0:
+            raise ValueError("duration_ms must not be negative.")
+        if self.success and self.error is not None:
+            raise ValueError("A successful ToolResult cannot contain an error.")
+        if self.success and self.policy_decision is not PolicyDecision.ALLOWED:
+            raise ValueError("A successful ToolResult must be allowed by policy.")
+        if not self.success and self.error is None:
+            raise ValueError("A failed ToolResult must contain a ToolError.")
+        if self.output is not None and not _is_json_value(self.output):
+            raise ValueError("Tool output must contain only JSON-compatible values.")
+        if self.output is not None:
+            object.__setattr__(self, "output", dict(self.output))
+
+
+@dataclass(frozen=True, slots=True)
+class SandboxRequest:
+    operation: str
+    argv: list[str]
+    cwd: str
+    timeout_seconds: float
+
+    def __post_init__(self) -> None:
+        if not self.operation:
+            raise ValueError("Sandbox operation must not be empty.")
+        if not self.argv or any(
+            not isinstance(item, str) or not item for item in self.argv
+        ):
+            raise ValueError("Sandbox argv must contain non-empty strings.")
+        if not self.cwd:
+            raise ValueError("Sandbox cwd must not be empty.")
+        if not 0 < self.timeout_seconds <= 300.0:
+            raise ValueError("Sandbox timeout must be in (0, 300].")
+        object.__setattr__(self, "argv", list(self.argv))
+
+
+@dataclass(frozen=True, slots=True)
+class SandboxResult:
+    argv: list[str]
+    cwd: str
+    risk_level: RiskLevel
+    policy_decision: PolicyDecision
+    exit_code: int | None
+    stdout: str
+    stderr: str
+    duration_ms: int
+    timed_out: bool
+    output_truncated: bool
+    error: ToolError | None
+
+    def __post_init__(self) -> None:
+        if self.duration_ms < 0:
+            raise ValueError("duration_ms must not be negative.")
+        if self.policy_decision is PolicyDecision.DENIED and self.exit_code is not None:
+            raise ValueError("A denied SandboxResult cannot have an exit code.")
+        if self.timed_out and self.exit_code is not None:
+            raise ValueError("A timed-out SandboxResult cannot have an exit code.")
+        object.__setattr__(self, "argv", list(self.argv))
+
+
+def risk_rank(risk: RiskLevel) -> int:
+    return {
+        RiskLevel.SAFE: 0,
+        RiskLevel.WRITE: 1,
+        RiskLevel.DANGEROUS: 2,
+    }[risk]
+
+
+def _validate_uuid(value: str, field_name: str) -> None:
+    try:
+        parsed = UUID(value)
+    except ValueError as exc:
+        raise ValueError(f"{field_name} must be a UUID string.") from exc
+    if str(parsed) != value:
+        raise ValueError(f"{field_name} must use canonical UUID text.")
+
+
+def _is_json_value(value: object) -> bool:
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return True
+    if isinstance(value, list):
+        return all(_is_json_value(item) for item in value)
+    if isinstance(value, dict):
+        return all(
+            isinstance(key, str) and _is_json_value(item)
+            for key, item in value.items()
+        )
+    return False

nexus/domain/validation.py

@@ -0,0 +1,161 @@
+"""Day 4 validation values and deterministic repairability rules."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from uuid import UUID
+
+from nexus.domain.tooling import JsonObject, ToolResult
+
+
+class ValidationStatus(StrEnum):
+    PASS = "PASS"
+    FAIL = "FAIL"
+    UNKNOWN = "UNKNOWN"
+
+
+class ValidationConfidence(StrEnum):
+    HIGH = "HIGH"
+    MEDIUM = "MEDIUM"
+    LOW = "LOW"
+
+
+class ValidationCheckKind(StrEnum):
+    TEST = "TEST"
+    BUILD = "BUILD"
+    LINT = "LINT"
+    TYPE_CHECK = "TYPE_CHECK"
+    REPOSITORY_COMMAND = "REPOSITORY_COMMAND"
+    GENERATED_TARGETED_TEST = "GENERATED_TARGETED_TEST"
+    BASIC_EXECUTION = "BASIC_EXECUTION"
+    DIFF_INSPECTION = "DIFF_INSPECTION"
+
+
+@dataclass(frozen=True, slots=True)
+class ValidationCheck:
+    check_id: str
+    sequence: int
+    kind: ValidationCheckKind
+    tool_name: str
+    arguments: JsonObject
+    selection_reason: str
+    required: bool
+
+    def __post_init__(self) -> None:
+        _validate_uuid(self.check_id, "check_id")
+        if self.sequence < 1 or not self.tool_name or not self.selection_reason.strip():
+            raise ValueError("ValidationCheck identity and description are invalid.")
+        if not _is_json_value(self.arguments):
+            raise ValueError("ValidationCheck arguments must be JSON-compatible.")
+        object.__setattr__(self, "arguments", dict(self.arguments))
+
+
+@dataclass(frozen=True, slots=True)
+class ValidationCheckResult:
+    check: ValidationCheck
+    status: ValidationStatus
+    tool_result: ToolResult | None
+    evidence_summary: str
+
+    def __post_init__(self) -> None:
+        if not self.evidence_summary.strip():
+            raise ValueError("Validation evidence_summary must not be empty.")
+        if self.tool_result is not None and (
+            self.tool_result.invocation_id != self.check.check_id
+            or self.tool_result.tool_name != self.check.tool_name
+        ):
+            raise ValueError("Validation Tool evidence has mismatched identity.")
+
+
+@dataclass(frozen=True, slots=True)
+class ValidationPlan:
+    checks: tuple[ValidationCheck, ...]
+
+    def __post_init__(self) -> None:
+        checks = tuple(self.checks)
+        if [check.sequence for check in checks] != list(range(1, len(checks) + 1)):
+            raise ValueError("ValidationCheck sequence must be contiguous from one.")
+        if len({check.check_id for check in checks}) != len(checks):
+            raise ValueError("ValidationCheck IDs must be unique.")
+        object.__setattr__(self, "checks", checks)
+
+
+@dataclass(frozen=True, slots=True)
+class ValidationResult:
+    selected_checks: tuple[ValidationCheck, ...]
+    executed_checks: tuple[ValidationCheckResult, ...]
+    status: ValidationStatus
+    confidence: ValidationConfidence
+    repairable: bool
+    repair_count: int
+    summary: str
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "selected_checks", tuple(self.selected_checks))
+        object.__setattr__(self, "executed_checks", tuple(self.executed_checks))
+        if self.repair_count < 0 or not self.summary.strip():
+            raise ValueError("ValidationResult count and summary are invalid.")
+        if self.status is not ValidationStatus.FAIL and self.repairable:
+            raise ValueError("Only a failed ValidationResult may be repairable.")
+        if self.repairable != aggregate_repairable(self.status, self.executed_checks):
+            raise ValueError("ValidationResult repairable does not match frozen aggregation.")
+
+
+_REPAIRABLE_KINDS = {
+    ValidationCheckKind.TEST,
+    ValidationCheckKind.BUILD,
+    ValidationCheckKind.LINT,
+    ValidationCheckKind.TYPE_CHECK,
+    ValidationCheckKind.GENERATED_TARGETED_TEST,
+    ValidationCheckKind.BASIC_EXECUTION,
+}
+
+
+def is_mechanically_repairable(result: ValidationCheckResult) -> bool:
+    tool_result = result.tool_result
+    return (
+        result.status is ValidationStatus.FAIL
+        and result.check.kind in _REPAIRABLE_KINDS
+        and tool_result is not None
+        and tool_result.error is not None
+        and tool_result.error.code == "COMMAND_EXIT_NONZERO"
+    )
+
+
+def aggregate_repairable(
+    status: ValidationStatus,
+    results: tuple[ValidationCheckResult, ...],
+) -> bool:
+    if status is not ValidationStatus.FAIL:
+        return False
+    required_failures = tuple(
+        result
+        for result in results
+        if result.check.required and result.status is ValidationStatus.FAIL
+    )
+    return bool(required_failures) and all(
+        is_mechanically_repairable(result) for result in required_failures
+    )
+
+
+def _validate_uuid(value: str, field_name: str) -> None:
+    try:
+        parsed = UUID(value)
+    except (AttributeError, TypeError, ValueError) as exc:
+        raise ValueError(f"{field_name} must be a canonical UUID string.") from exc
+    if str(parsed) != value:
+        raise ValueError(f"{field_name} must be a canonical UUID string.")
+
+
+def _is_json_value(value: object) -> bool:
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return True
+    if isinstance(value, list):
+        return all(_is_json_value(item) for item in value)
+    if isinstance(value, dict):
+        return all(
+            isinstance(key, str) and _is_json_value(item)
+            for key, item in value.items()
+        )
+    return False

nexus/errors/__init__.py

@@ -0,0 +1,82 @@
+"""Nexus-owned error types exposed across stable boundaries."""
+
+from __future__ import annotations
+
+
+class NexusError(Exception):
+    """Base class for safe, structured Nexus failures."""
+
+    default_code = "NEXUS_ERROR"
+    default_retryable = False
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str | None = None,
+        retryable: bool | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code or self.default_code
+        self.retryable = self.default_retryable if retryable is None else retryable
+
+
+class ConfigurationError(NexusError):
+    """The resolved Nexus configuration is missing or invalid."""
+
+    default_code = "CONFIGURATION_ERROR"
+
+
+class ModelError(NexusError):
+    """A model operation failed behind the ModelGateway boundary."""
+
+    default_code = "MODEL_ERROR"
+
+
+class MCPError(NexusError):
+    """An MCP connection, discovery, or call failed behind the adapter boundary."""
+
+    default_code = "MCP_ERROR"
+
+
+class SessionError(NexusError):
+    """A session operation failed a Nexus business rule or persistence boundary."""
+
+    default_code = "SESSION_ERROR"
+
+
+class ToolExecutionError(NexusError):
+    """A tool operation failed behind the structured Tool boundary."""
+
+    default_code = "TOOL_EXECUTION_ERROR"
+
+
+class ContextError(NexusError):
+    """Repository exploration or bounded context construction failed."""
+
+    default_code = "CONTEXT_ERROR"
+
+
+class ValidationError(NexusError):
+    """Validation planning or execution could not produce truthful evidence."""
+
+    default_code = "VALIDATION_ERROR"
+
+
+class PermissionDeniedError(NexusError):
+    """A centralized security policy denied an operation."""
+
+    default_code = "PERMISSION_DENIED"
+
+
+__all__ = [
+    "ConfigurationError",
+    "ContextError",
+    "MCPError",
+    "ModelError",
+    "NexusError",
+    "PermissionDeniedError",
+    "SessionError",
+    "ToolExecutionError",
+    "ValidationError",
+]

nexus/evaluation/__init__.py

@@ -0,0 +1,7 @@
+"""Nexus-owned deterministic evaluation subsystem."""
+
+from nexus.evaluation.evaluator import DefaultDeterministicEvaluator
+from nexus.evaluation.loader import EvalSuiteLoader
+from nexus.evaluation.models import *  # noqa: F403
+
+__all__ = ["DefaultDeterministicEvaluator", "EvalSuiteLoader"]

nexus/evaluation/assertions.py

@@ -0,0 +1,4 @@
+"""Assertion semantics consume only the typed evidence bundle.
+
+Day 9 intentionally defines no second public assertion-engine interface.
+"""