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

nexus/domain/agent_decision.py

@@ -0,0 +1,113 @@
+"""Structured Day 4 Agent decision and deterministic observation values."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from uuid import UUID
+
+from nexus.domain.exploration import WorkingContext
+from nexus.domain.planning import Plan, RepairGuidance
+from nexus.domain.tooling import JsonObject
+from nexus.domain.validation import ValidationResult
+
+
+class AgentDecisionKind(StrEnum):
+    TOOL_ACTION = "TOOL_ACTION"
+    CONTINUE = "CONTINUE"
+    TASK_READY = "TASK_READY"
+
+
+class AgentRoute(StrEnum):
+    TOOL_REQUIRED = "TOOL_REQUIRED"
+    CONTINUE = "CONTINUE"
+    TASK_READY = "TASK_READY"
+
+
+class ObserveRoute(StrEnum):
+    REPLAN_REQUIRED = "REPLAN_REQUIRED"
+    CONTINUE = "CONTINUE"
+
+
+class ValidationRoute(StrEnum):
+    PASSED = "PASSED"
+    REPAIR_AVAILABLE = "REPAIR_AVAILABLE"
+    FAILED = "FAILED"
+
+
+@dataclass(frozen=True, slots=True)
+class ToolAction:
+    tool_name: str
+    arguments: JsonObject
+
+    def __post_init__(self) -> None:
+        if not self.tool_name:
+            raise ValueError("ToolAction tool_name must not be empty.")
+        if not _is_json_value(self.arguments):
+            raise ValueError("ToolAction arguments must be JSON-compatible.")
+        object.__setattr__(self, "arguments", dict(self.arguments))
+
+
+@dataclass(frozen=True, slots=True)
+class AgentDecision:
+    kind: AgentDecisionKind
+    action: ToolAction | None
+    summary: str
+
+    def __post_init__(self) -> None:
+        if not self.summary.strip():
+            raise ValueError("AgentDecision summary must not be empty.")
+        if (self.kind is AgentDecisionKind.TOOL_ACTION) != (self.action is not None):
+            raise ValueError("AgentDecision action does not match its kind.")
+
+
+@dataclass(frozen=True, slots=True)
+class Observation:
+    invocation_id: str
+    tool_name: str
+    success: bool
+    evidence_summary: str
+    error_code: str | None
+    replan_reason: str | None
+
+    def __post_init__(self) -> None:
+        _validate_uuid(self.invocation_id, "invocation_id")
+        if not self.tool_name or not self.evidence_summary.strip():
+            raise ValueError("Observation Tool identity and evidence must not be empty.")
+        if self.error_code == "PLAN_SCOPE_DENIED":
+            if not (self.replan_reason or "").strip():
+                raise ValueError("PLAN_SCOPE_DENIED requires a material Replan reason.")
+        elif self.replan_reason is not None:
+            raise ValueError("Day 4 permits no additional semantic Replan trigger.")
+
+
+@dataclass(frozen=True, slots=True)
+class AgentDecisionRequest:
+    task: str
+    context: WorkingContext
+    plan: Plan
+    observations: tuple[Observation, ...]
+    validation_result: ValidationResult | None = None
+    repair_guidance: RepairGuidance | None = None
+
+
+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/domain/agent_state.py

@@ -0,0 +1,49 @@
+"""Nexus-owned graph state through Day 4."""
+
+from dataclasses import dataclass, field
+
+from nexus.domain.agent_decision import Observation, ToolAction
+from nexus.domain.approvals import ApprovalRequest
+from nexus.domain.exploration import ExplorationResult, WorkingContext
+from nexus.domain.model import ModelMessage, TokenUsageAggregate
+from nexus.domain.planning import (
+    ApprovedPlanEvidence,
+    ChangedFile,
+    Plan,
+    RepairGuidance,
+    TerminalStatus,
+)
+from nexus.domain.runtime_events import RuntimeStatus
+from nexus.domain.tooling import ToolResult
+from nexus.domain.validation import ValidationResult
+
+
+@dataclass(frozen=True, slots=True)
+class AgentState:
+    """Nexus-owned state passed through the graph boundary."""
+
+    task: str
+    messages: list[ModelMessage]
+    run_id: str
+    session_id: str | None
+    status: RuntimeStatus
+    exploration: ExplorationResult | None = None
+    context: WorkingContext | None = None
+    plan: Plan | None = None
+    plan_history: tuple[Plan, ...] = ()
+    observations: tuple[Observation, ...] = ()
+    tool_results: tuple[ToolResult, ...] = ()
+    pending_tool_action: ToolAction | None = None
+    latest_tool_result: ToolResult | None = None
+    pending_plan_approval: ApprovalRequest | None = None
+    approved_plan: ApprovedPlanEvidence | None = None
+    repair_guidance: RepairGuidance | None = None
+    validation_result: ValidationResult | None = None
+    changed_files: tuple[ChangedFile, ...] = ()
+    step_count: int = 0
+    tool_call_count: int = 0
+    llm_call_count: int = 0
+    replan_count: int = 0
+    repair_count: int = 0
+    terminal_status: TerminalStatus | None = None
+    token_usage: TokenUsageAggregate = field(default_factory=TokenUsageAggregate)

nexus/domain/approvals.py

@@ -0,0 +1,64 @@
+"""Nexus-owned Day 3 approval lifecycle entity."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from uuid import UUID
+
+from nexus.domain.tooling import ApprovalDecision, RiskLevel
+
+_ACTORS = {"runtime", "user", "auto_policy", "security_policy"}
+
+
+@dataclass(frozen=True, slots=True)
+class ApprovalRequest:
+    approval_id: str
+    run_id: str
+    session_id: str
+    operation: str
+    risk_level: RiskLevel
+    resource_or_command_summary: str
+    decision: ApprovalDecision
+    actor: str
+    reason: str | None
+    created_at: datetime
+    decided_at: datetime | None
+
+    def __post_init__(self) -> None:
+        _validate_uuid(self.approval_id, "approval_id")
+        _validate_uuid(self.run_id, "run_id")
+        _validate_uuid(self.session_id, "session_id")
+        _validate_timestamp(self.created_at, "created_at")
+        if self.decided_at is not None:
+            _validate_timestamp(self.decided_at, "decided_at")
+        if not self.operation or not self.resource_or_command_summary:
+            raise ValueError("Approval operation, summary, and actor must not be empty.")
+        if self.actor not in _ACTORS:
+            raise ValueError("Approval actor is not a frozen Day 3 actor.")
+        if self.decision is ApprovalDecision.PENDING:
+            if self.decided_at is not None or self.actor != "runtime":
+                raise ValueError("A pending approval must have runtime actor and no decided_at.")
+        elif self.decided_at is None:
+            raise ValueError("A terminal approval must have decided_at.")
+        elif self.decision is ApprovalDecision.APPROVED and not (
+            self.actor == "user"
+            or self.actor == "auto_policy" and self.operation == "approve_plan"
+        ):
+            raise ValueError("Only the user or scoped Plan auto policy may approve.")
+        elif self.decision is ApprovalDecision.DENIED and self.actor == "runtime":
+            raise ValueError("The runtime actor cannot own a terminal denial.")
+
+
+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 _validate_timestamp(value: datetime, field_name: str) -> None:
+    if value.tzinfo is None or value.utcoffset() is None:
+        raise ValueError(f"{field_name} must be timezone-aware.")

nexus/domain/context.py

@@ -0,0 +1,108 @@
+"""Frozen Day 5 retrieval, indexing and embedding values."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from nexus.domain.exploration import ExplorationResult
+
+
+class RetrievalSource(StrEnum):
+    LEXICAL = "LEXICAL"
+    SEMANTIC = "SEMANTIC"
+
+
+@dataclass(frozen=True, slots=True)
+class CodeChunk:
+    file_path: str
+    language: str
+    symbol: str | None
+    start_line: int
+    end_line: int
+    content: str
+    content_hash: str
+    file_hash: str
+
+
+@dataclass(frozen=True, slots=True)
+class ContextCandidate:
+    chunk: CodeChunk
+    lexical_rank: int | None
+    semantic_rank: int | None
+    semantic_score: float | None
+    rrf_score: float
+    sources: tuple[RetrievalSource, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class ContextBudget:
+    max_retrieved_chunks: int
+    max_exploration_seed_chunks: int
+    max_code_context_tokens: int
+    max_recent_observations: int
+
+
+@dataclass(frozen=True, slots=True)
+class RetrievalQuery:
+    repository_id: str
+    workspace_path: str
+    text: str
+    limit: int
+
+
+@dataclass(frozen=True, slots=True)
+class RetrievalResult:
+    candidates: tuple[ContextCandidate, ...]
+    semantic_used: bool
+    semantic_status: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class ContextRequest:
+    task: str
+    repository_id: str
+    workspace_path: str
+    exploration: ExplorationResult
+    run_id: str
+    session_id: str
+
+
+@dataclass(frozen=True, slots=True)
+class EmbeddingConfig:
+    provider: str
+    model: str
+    dimension: int
+
+
+@dataclass(frozen=True, slots=True)
+class IndexRequest:
+    repository_id: str
+    workspace_path: str
+    rebuild: bool
+
+
+@dataclass(frozen=True, slots=True)
+class IndexResult:
+    repository_id: str
+    scanned_files: int
+    indexed_files: int
+    unchanged_files: int
+    removed_files: int
+    skipped_files: int
+    chunk_count: int
+    rebuilt: bool
+
+
+class IndexCompatibilityStatus(StrEnum):
+    COMPATIBLE = "COMPATIBLE"
+    INDEX_NOT_FOUND = "INDEX_NOT_FOUND"
+    INDEX_INCOMPATIBLE = "INDEX_INCOMPATIBLE"
+
+
+@dataclass(frozen=True, slots=True)
+class IndexCompatibility:
+    status: IndexCompatibilityStatus
+    reason: str | None

nexus/domain/exploration.py

@@ -0,0 +1,86 @@
+"""Day 4 selective exploration and bounded context values."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from nexus.domain.context import ContextCandidate
+from nexus.domain.persistence import SessionTurn
+from nexus.domain.skills import SelectedSkill, SkillSelectionResult
+
+if TYPE_CHECKING:
+    from nexus.domain.agent_decision import Observation
+
+from nexus.domain.tooling import ToolResult
+
+
+@dataclass(frozen=True, slots=True)
+class ExplorationRequest:
+    task: str
+    run_id: str
+    session_id: str
+
+
+@dataclass(frozen=True, slots=True)
+class RepositoryInstruction:
+    path: str
+    scope_path: str
+    depth: int
+    content: str
+    truncated: bool
+
+
+@dataclass(frozen=True, slots=True)
+class RepositoryFileEvidence:
+    path: str
+    category: str
+    discovery_reason: str
+    summary: str
+
+
+@dataclass(frozen=True, slots=True)
+class ExplorationResult:
+    instructions: tuple[RepositoryInstruction, ...]
+    manifests: tuple[RepositoryFileEvidence, ...]
+    top_level_paths: tuple[str, ...]
+    relevant_files: tuple[RepositoryFileEvidence, ...]
+    initial_git_status: ToolResult
+    tool_results: tuple[ToolResult, ...]
+    truncated: bool
+
+
+@dataclass(frozen=True, slots=True)
+class SelectedFileContext:
+    path: str
+    content: str
+    applicable_instruction_paths: tuple[str, ...]
+    discovery_reason: str
+    truncated: bool
+
+
+@dataclass(frozen=True, slots=True)
+class WorkingContext:
+    task: str
+    repository_instructions: tuple[RepositoryInstruction, ...]
+    manifest_summaries: tuple[RepositoryFileEvidence, ...]
+    top_level_paths: tuple[str, ...]
+    selected_files: tuple[SelectedFileContext, ...]
+    truncated: bool
+    retrieved_candidates: tuple[ContextCandidate, ...] = ()
+    compacted_conversation: str | None = None
+    semantic_retrieval_used: bool = False
+    semantic_retrieval_status: str | None = None
+    recent_observations: tuple[Observation, ...] = ()
+    recent_conversation_turns: tuple[SessionTurn, ...] = ()
+    compacted_observations: str | None = None
+    selected_skills: tuple[SelectedSkill, ...] = ()
+    skill_selection_result: SkillSelectionResult | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ContextBuildRequest:
+    task: str
+    exploration: ExplorationResult
+    run_id: str
+    session_id: str

nexus/domain/mcp.py

@@ -0,0 +1,51 @@
+"""Nexus-owned, SDK-neutral MCP metadata values."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from nexus.domain.tooling import JsonObject
+
+
+@dataclass(frozen=True, slots=True)
+class MCPToolDescriptor:
+    server_id: str
+    remote_name: str
+    registry_name: str
+    description: str | None
+    input_schema: JsonObject
+
+    def __post_init__(self) -> None:
+        if not self.server_id or not self.remote_name or not self.registry_name:
+            raise ValueError("MCP Tool identity must not be empty.")
+        if self.description is not None and not isinstance(self.description, str):
+            raise ValueError("MCP Tool description must be text or None.")
+        if not _is_json_value(self.input_schema):
+            raise ValueError("MCP input schema must be a JSON object.")
+        object.__setattr__(self, "input_schema", dict(self.input_schema))
+
+
+@dataclass(frozen=True, slots=True)
+class MCPConnectionInfo:
+    server_id: str
+    connected: bool
+    server_name: str | None
+    server_version: str | None
+    negotiated_protocol_version: str | None
+
+    def __post_init__(self) -> None:
+        if not self.server_id:
+            raise ValueError("MCP server_id must not be empty.")
+
+
+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/model.py

@@ -0,0 +1,173 @@
+"""Provider-neutral model request, response, and usage values."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Literal
+
+ModelRole = Literal["system", "user", "assistant"]
+
+
+class UsageAvailability(StrEnum):
+    REPORTED = "REPORTED"
+    PARTIAL = "PARTIAL"
+    UNAVAILABLE = "UNAVAILABLE"
+
+
+class ModelCallPhase(StrEnum):
+    DIRECT_RESPONSE = "DIRECT_RESPONSE"
+    PLAN = "PLAN"
+    REPLAN = "REPLAN"
+    REPAIR = "REPAIR"
+    AGENT_STEP = "AGENT_STEP"
+    SKILL_SELECTION = "SKILL_SELECTION"
+
+
+@dataclass(frozen=True, slots=True)
+class TokenUsage:
+    input_tokens: int | None
+    output_tokens: int | None
+    total_tokens: int | None
+    availability: UsageAvailability
+
+    def __post_init__(self) -> None:
+        values = (self.input_tokens, self.output_tokens, self.total_tokens)
+        if any(value is not None and value < 0 for value in values):
+            raise ValueError("Token usage values must not be negative.")
+        known = sum(value is not None for value in values)
+        if self.availability is UsageAvailability.UNAVAILABLE and known != 0:
+            raise ValueError("UNAVAILABLE token usage cannot contain reported values.")
+        if self.availability is UsageAvailability.REPORTED and known != 3:
+            raise ValueError("REPORTED token usage requires a complete usage triple.")
+        if self.availability is UsageAvailability.PARTIAL and known not in {1, 2}:
+            raise ValueError("PARTIAL token usage requires one or two reported values.")
+        if known == 3:
+            assert self.input_tokens is not None
+            assert self.output_tokens is not None
+            if self.total_tokens != self.input_tokens + self.output_tokens:
+                raise ValueError("Token total must equal input plus output tokens.")
+
+    @classmethod
+    def unavailable(cls) -> TokenUsage:
+        return cls(None, None, None, UsageAvailability.UNAVAILABLE)
+
+
+@dataclass(frozen=True, slots=True)
+class TokenUsageAggregate:
+    input_tokens_reported: int = 0
+    output_tokens_reported: int = 0
+    total_tokens_reported: int = 0
+    calls_with_reported_usage: int = 0
+    calls_with_partial_usage: int = 0
+    calls_with_unavailable_usage: int = 0
+    usage_complete: bool = True
+
+    def __post_init__(self) -> None:
+        counters = (
+            self.input_tokens_reported,
+            self.output_tokens_reported,
+            self.total_tokens_reported,
+            self.calls_with_reported_usage,
+            self.calls_with_partial_usage,
+            self.calls_with_unavailable_usage,
+        )
+        if any(value < 0 for value in counters):
+            raise ValueError("Token usage aggregate values must not be negative.")
+        complete = (
+            self.calls_with_partial_usage == 0
+            and self.calls_with_unavailable_usage == 0
+        )
+        if self.usage_complete is not complete:
+            raise ValueError("Token usage aggregate completeness is inconsistent.")
+
+    @property
+    def call_count(self) -> int:
+        return (
+            self.calls_with_reported_usage
+            + self.calls_with_partial_usage
+            + self.calls_with_unavailable_usage
+        )
+
+    def add(self, usage: TokenUsage) -> TokenUsageAggregate:
+        return TokenUsageAggregate(
+            input_tokens_reported=self.input_tokens_reported + (usage.input_tokens or 0),
+            output_tokens_reported=self.output_tokens_reported + (usage.output_tokens or 0),
+            total_tokens_reported=self.total_tokens_reported + (usage.total_tokens or 0),
+            calls_with_reported_usage=(
+                self.calls_with_reported_usage
+                + int(usage.availability is UsageAvailability.REPORTED)
+            ),
+            calls_with_partial_usage=(
+                self.calls_with_partial_usage
+                + int(usage.availability is UsageAvailability.PARTIAL)
+            ),
+            calls_with_unavailable_usage=(
+                self.calls_with_unavailable_usage
+                + int(usage.availability is UsageAvailability.UNAVAILABLE)
+            ),
+            usage_complete=(
+                self.usage_complete
+                and usage.availability is UsageAvailability.REPORTED
+            ),
+        )
+
+    def to_usage(self) -> TokenUsage:
+        if self.call_count == 0 or (
+            self.calls_with_reported_usage == 0
+            and self.calls_with_partial_usage == 0
+        ):
+            return TokenUsage.unavailable()
+        availability = (
+            UsageAvailability.REPORTED
+            if self.usage_complete
+            else UsageAvailability.PARTIAL
+        )
+        if availability is UsageAvailability.PARTIAL:
+            values: tuple[int | None, int | None, int | None] = (
+                self.input_tokens_reported,
+                self.output_tokens_reported,
+                None,
+            )
+        else:
+            values = (
+                self.input_tokens_reported,
+                self.output_tokens_reported,
+                self.total_tokens_reported,
+            )
+        return TokenUsage(*values, availability)
+
+    def to_dict(self) -> dict[str, int | bool]:
+        return {
+            "input_tokens_reported": self.input_tokens_reported,
+            "output_tokens_reported": self.output_tokens_reported,
+            "total_tokens_reported": self.total_tokens_reported,
+            "calls_with_reported_usage": self.calls_with_reported_usage,
+            "calls_with_partial_usage": self.calls_with_partial_usage,
+            "calls_with_unavailable_usage": self.calls_with_unavailable_usage,
+            "usage_complete": self.usage_complete,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class ModelMessage:
+    """A minimal Nexus-owned chat message."""
+
+    role: ModelRole
+    content: str
+
+
+@dataclass(frozen=True, slots=True)
+class ModelResponse:
+    """A normalized non-streaming model response."""
+
+    content: str
+    usage: TokenUsage | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ModelChunk:
+    """A normalized streaming model fragment."""
+
+    content: str
+    usage: TokenUsage | None = None