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

nexus/interfaces/cli/renderer.py

@@ -0,0 +1,118 @@
+"""Render safe RuntimeEvents for a terminal consumer."""
+
+from __future__ import annotations
+
+import typer
+
+from nexus.domain.runtime_events import (
+    AgentStepCompleted,
+    ApprovalRequested,
+    ApprovalResolved,
+    ApprovalSubject,
+    ChangedFileRecorded,
+    ContextBuilt,
+    ErrorOccurred,
+    FinalResult,
+    ModelCallFinished,
+    ObservabilityWarning,
+    PlanCreated,
+    RepairStarted,
+    ReplanOccurred,
+    RepositoryExplored,
+    RunInterrupted,
+    RuntimeEvent,
+    TaskStarted,
+    ToolFinished,
+    ToolStarted,
+    ValidationFinished,
+    ValidationStarted,
+)
+
+
+def render_event(event: RuntimeEvent) -> bool:
+    """Render one event and return whether it represents success/continuation."""
+
+    if isinstance(event, TaskStarted):
+        typer.echo("Task started")
+        return True
+    if isinstance(event, RepositoryExplored):
+        typer.echo(
+            f"Repository explored ({len(event.relevant_paths)} relevant paths; "
+            f"{event.exploration_tool_calls} tool calls)"
+        )
+        return True
+    if isinstance(event, ContextBuilt) and event.semantic_retrieval_status:
+        code = event.semantic_retrieval_status
+        remediation = ("Run nexus index --rebuild." if code == "INDEX_INCOMPATIBLE"
+                       else "Run nexus index." if code == "INDEX_NOT_FOUND"
+                       else "Check embedding/database availability and retry.")
+        typer.echo(f"Context warning [{code}]: using lexical context. {remediation}", err=True)
+        return True
+    if isinstance(event, FinalResult):
+        typer.echo(event.content)
+        if event.diff:
+            typer.echo(event.diff)
+        return event.status.value == "COMPLETED"
+    if isinstance(event, PlanCreated):
+        typer.echo(f"Plan {event.plan_id} v{event.plan_version}")
+        for summary in event.step_summaries:
+            typer.echo(f"  {summary}")
+        return True
+    if isinstance(event, ApprovalRequested) and event.subject is ApprovalSubject.PLAN:
+        typer.echo("Plan approval required")
+        typer.echo(f"  scope digest: {event.resource_or_command_summary}")
+        return True
+    if isinstance(event, ApprovalResolved):
+        typer.echo(f"Approval {event.decision.value.lower()} ({event.subject.value.lower()})")
+        return True
+    if isinstance(event, AgentStepCompleted):
+        typer.echo(
+            f"Agent step {event.step_count} completed ({event.decision_kind.value.lower()})"
+        )
+        return True
+    if isinstance(event, ModelCallFinished):
+        usage = event.usage.availability.value.lower()
+        typer.echo(
+            f"Model {event.phase.value.lower()} finished in {event.duration_ms} ms "
+            f"(reported tokens: {usage})"
+        )
+        return True
+    if isinstance(event, ToolStarted):
+        typer.echo(f"Tool {event.tool_name} started")
+        return True
+    if isinstance(event, ToolFinished):
+        outcome = "succeeded" if event.success else f"failed [{event.error_code}]"
+        typer.echo(f"Tool {event.tool_name} {outcome} in {event.duration_ms} ms")
+        return True
+    if isinstance(event, ReplanOccurred):
+        typer.echo(f"Plan regenerated (replan {event.replan_count})")
+        return True
+    if isinstance(event, ValidationStarted):
+        typer.echo(f"Validation started ({len(event.check_ids)} checks)")
+        return True
+    if isinstance(event, ValidationFinished):
+        typer.echo(
+            f"Validation {event.validation_status.value.lower()} "
+            f"({event.duration_ms if event.duration_ms is not None else 'unobserved'} ms)"
+        )
+        return True
+    if isinstance(event, RepairStarted):
+        typer.echo(f"Repair attempt {event.repair_count} started")
+        return True
+    if isinstance(event, ChangedFileRecorded):
+        typer.echo(f"Changed file: {event.relative_path}")
+        return True
+    if isinstance(event, ObservabilityWarning):
+        typer.echo(
+            f"Observability warning [{event.code}]: {event.sink.value.lower()} "
+            f"{event.operation.value.lower()} failed; fallback={event.fallback.value.lower()}",
+            err=True,
+        )
+        return True
+    if isinstance(event, RunInterrupted):
+        typer.echo(event.message)
+        return True
+    if isinstance(event, ErrorOccurred):
+        typer.echo(f"Error [{event.code}]: {event.message}", err=True)
+        return False
+    return True

nexus/security/__init__.py

@@ -0,0 +1,14 @@
+"""Centralized Day 3 security policies."""
+
+from nexus.security.approval_policies import AutoApprovalPolicy, InteractiveApprovalPolicy
+from nexus.security.command_policy import DefaultCommandPolicy
+from nexus.security.executables import TrustedExecutables
+from nexus.security.workspace import WorkspaceGuard
+
+__all__ = [
+    "AutoApprovalPolicy",
+    "DefaultCommandPolicy",
+    "InteractiveApprovalPolicy",
+    "TrustedExecutables",
+    "WorkspaceGuard",
+]

nexus/security/approval_policies.py

@@ -0,0 +1,73 @@
+"""Interactive and auto approval decisions without terminal input coupling."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from datetime import UTC, datetime
+
+from nexus.domain.approvals import ApprovalRequest
+from nexus.domain.ports.tooling import InteractiveDecisionCallback
+from nexus.domain.tooling import ApprovalDecision, RiskLevel
+from nexus.errors import PermissionDeniedError, ToolExecutionError
+
+
+class InteractiveApprovalPolicy:
+    def __init__(self, decision_callback: InteractiveDecisionCallback) -> None:
+        self._decision_callback = decision_callback
+
+    async def request(self, request: ApprovalRequest) -> ApprovalRequest:
+        _require_pending(request)
+        if request.risk_level is RiskLevel.DANGEROUS:
+            return _decide(
+                request,
+                ApprovalDecision.DENIED,
+                actor="security_policy",
+                reason="Dangerous operations are hard-denied.",
+            )
+        decision, reason = await self._decision_callback(request)
+        if decision not in {ApprovalDecision.APPROVED, ApprovalDecision.DENIED}:
+            raise ToolExecutionError(
+                "Interactive approval returned an invalid decision.",
+                code="INVALID_APPROVAL_TRANSITION",
+            )
+        return _decide(request, decision, actor="user", reason=reason)
+
+
+class AutoApprovalPolicy:
+    async def request(self, request: ApprovalRequest) -> ApprovalRequest:
+        _require_pending(request)
+        actor = (
+            "security_policy"
+            if request.risk_level is RiskLevel.DANGEROUS
+            else "auto_policy"
+        )
+        return _decide(
+            request,
+            ApprovalDecision.DENIED,
+            actor=actor,
+            reason="Auto policy cannot authorize this operation.",
+        )
+
+
+def _require_pending(request: ApprovalRequest) -> None:
+    if request.decision is not ApprovalDecision.PENDING:
+        raise PermissionDeniedError(
+            "Only a pending approval can be decided.",
+            code="INVALID_APPROVAL_TRANSITION",
+        )
+
+
+def _decide(
+    request: ApprovalRequest,
+    decision: ApprovalDecision,
+    *,
+    actor: str,
+    reason: str | None,
+) -> ApprovalRequest:
+    return replace(
+        request,
+        decision=decision,
+        actor=actor,
+        reason=reason,
+        decided_at=datetime.now(UTC),
+    )

nexus/security/command_policy.py

@@ -0,0 +1,117 @@
+"""Centralized SAFE/WRITE/DANGEROUS classification."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import MappingProxyType
+from typing import TypeGuard
+
+from nexus.domain.tooling import JsonObject, RiskLevel
+from nexus.security.executables import TrustedExecutables
+from nexus.security.git_commands import is_canonical_git_argv
+
+_READ_TOOLS = {"list_files", "search_files", "read_file", "lexical_search"}
+_GIT_TOOLS = {"git_status", "git_diff", "git_log"}
+_EDIT_TOOLS = {"apply_patch", "write_file"}
+_OPERATORS = {"&&", "||", "|", ">", ">>", "<", ";"}
+
+
+class DefaultCommandPolicy:
+    def __init__(
+        self,
+        executables: TrustedExecutables,
+        mcp_risks: Mapping[str, RiskLevel] | None = None,
+    ) -> None:
+        self._executables = executables
+        self._mcp_risks = MappingProxyType(dict(mcp_risks or {}))
+
+    def classify(self, *, operation: str, arguments: JsonObject) -> RiskLevel:
+        if operation in self._mcp_risks:
+            return self._mcp_risks[operation]
+        if operation in _READ_TOOLS:
+            return RiskLevel.SAFE
+        if operation in _GIT_TOOLS:
+            return self._classify_git(operation, arguments)
+        if operation in _EDIT_TOOLS:
+            return RiskLevel.WRITE
+        if operation != "shell":
+            return RiskLevel.DANGEROUS
+        argv = arguments.get("argv")
+        if not _is_string_list(argv):
+            return RiskLevel.DANGEROUS
+        normalized = self._executables.normalize_argv(argv)
+        if any(item in _OPERATORS for item in normalized):
+            return RiskLevel.DANGEROUS
+        if self._is_safe_inspection(normalized):
+            return RiskLevel.SAFE
+        if self._is_controlled_write(normalized):
+            return RiskLevel.WRITE
+        return RiskLevel.DANGEROUS
+
+    def _classify_git(self, operation: str, arguments: JsonObject) -> RiskLevel:
+        argv = arguments.get("argv")
+        if _is_string_list(argv):
+            normalized = self._executables.normalize_argv(argv)
+            return (
+                RiskLevel.SAFE
+                if is_canonical_git_argv(operation, normalized, self._executables.git)
+                else RiskLevel.DANGEROUS
+            )
+        if operation == "git_status":
+            return RiskLevel.SAFE if arguments == {} else RiskLevel.DANGEROUS
+        if operation == "git_diff":
+            return (
+                RiskLevel.SAFE
+                if set(arguments) <= {"staged"}
+                and isinstance(arguments.get("staged", False), bool)
+                else RiskLevel.DANGEROUS
+            )
+        value = arguments.get("max_entries", 20)
+        return (
+            RiskLevel.SAFE
+            if set(arguments) <= {"max_entries"}
+            and isinstance(value, int)
+            and not isinstance(value, bool)
+            and 1 <= value <= 100
+            else RiskLevel.DANGEROUS
+        )
+
+    def _is_safe_inspection(self, argv: list[str]) -> bool:
+        return argv in [
+            [self._executables.python, "--version"],
+            [self._executables.python, "-V"],
+            *(
+                [[self._executables.uv, "--version"]]
+                if self._executables.uv is not None
+                else []
+            ),
+            *(
+                [[self._executables.git, "--version"]]
+                if self._executables.git is not None
+                else []
+            ),
+        ]
+
+    def _is_controlled_write(self, argv: list[str]) -> bool:
+        direct = {
+            self._executables.pytest,
+            self._executables.ruff,
+            self._executables.mypy,
+        }
+        if argv[0] in direct - {None}:
+            return argv[0] != self._executables.ruff or argv[1:2] == ["check"]
+        uv = self._executables.uv
+        if uv is None or argv[0] != uv:
+            return False
+        if argv[1:2] == ["build"]:
+            return True
+        return len(argv) >= 3 and argv[1] == "run" and argv[2] in {
+            "pytest",
+            "mypy",
+        } or len(argv) >= 4 and argv[1:3] == ["run", "ruff"] and argv[3] == "check"
+
+
+def _is_string_list(value: object) -> TypeGuard[list[str]]:
+    return isinstance(value, list) and bool(value) and all(
+        isinstance(item, str) and bool(item) for item in value
+    )

nexus/security/executables.py

@@ -0,0 +1,107 @@
+"""Resolve a small trusted executable set without trusting the workspace."""
+
+from __future__ import annotations
+
+import os
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+from nexus.errors import ToolExecutionError
+
+
+@dataclass(frozen=True, slots=True)
+class TrustedExecutables:
+    python: str
+    uv: str | None
+    git: str | None
+    pytest: str | None
+    ruff: str | None
+    mypy: str | None
+
+    @classmethod
+    def resolve(cls, workspace: Path) -> TrustedExecutables:
+        sanitized_path = _sanitized_path(workspace)
+        python = _which_outside_workspace("python", workspace, sanitized_path)
+        if python is None:
+            raise ToolExecutionError("A trusted Python executable is unavailable.")
+        return cls(
+            python=python,
+            uv=_which_outside_workspace("uv", workspace, sanitized_path),
+            git=_which_outside_workspace("git", workspace, sanitized_path),
+            pytest=_which_outside_workspace("pytest", workspace, sanitized_path),
+            ruff=_which_outside_workspace("ruff", workspace, sanitized_path),
+            mypy=_which_outside_workspace("mypy", workspace, sanitized_path),
+        )
+
+    def normalize_argv(self, argv: list[str]) -> list[str]:
+        if not argv:
+            return []
+        resolved = self._resolve_requested(argv[0])
+        return [resolved or argv[0], *argv[1:]]
+
+    def _resolve_requested(self, requested: str) -> str | None:
+        requested_path = Path(requested)
+        normalized_name = requested_path.name.casefold()
+        if normalized_name.endswith(".exe"):
+            normalized_name = normalized_name[:-4]
+        candidates = {
+            "python": self.python,
+            "uv": self.uv,
+            "git": self.git,
+            "pytest": self.pytest,
+            "ruff": self.ruff,
+            "mypy": self.mypy,
+        }
+        candidate = candidates.get(normalized_name)
+        if candidate is None:
+            return None
+        if requested_path.is_absolute():
+            try:
+                if os.path.normcase(str(requested_path.resolve(strict=True))) != os.path.normcase(
+                    candidate
+                ):
+                    return None
+            except OSError:
+                return None
+        return candidate
+
+
+def _which_outside_workspace(
+    name: str,
+    workspace: Path,
+    search_path: str,
+) -> str | None:
+    located = shutil.which(name, path=search_path)
+    if located is None:
+        return None
+    resolved = Path(located).resolve(strict=True)
+    return None if _is_within(resolved, workspace) else str(resolved)
+
+
+def _sanitized_path(workspace: Path) -> str:
+    entries: list[str] = []
+    for value in os.environ.get("PATH", "").split(os.pathsep):
+        if not value:
+            continue
+        candidate = Path(value)
+        if not candidate.is_absolute():
+            continue
+        try:
+            resolved = candidate.resolve(strict=True)
+        except OSError:
+            continue
+        if resolved.is_dir() and not _is_within(resolved, workspace):
+            entries.append(str(resolved))
+    return os.pathsep.join(entries)
+
+
+def _is_within(path: Path, workspace: Path) -> bool:
+    normalized_path = os.path.normcase(str(path))
+    normalized_workspace = os.path.normcase(str(workspace.resolve(strict=True)))
+    try:
+        return os.path.commonpath([normalized_path, normalized_workspace]) == (
+            normalized_workspace
+        )
+    except ValueError:
+        return False

nexus/security/git_commands.py

@@ -0,0 +1,65 @@
+"""Canonical read-only Git argv construction and matching."""
+
+from __future__ import annotations
+
+
+def status_argv(git: str) -> list[str]:
+    return [
+        git,
+        "-c",
+        "core.fsmonitor=false",
+        "--no-pager",
+        "status",
+        "--short",
+        "--branch",
+    ]
+
+
+def diff_argv(git: str, *, staged: bool) -> list[str]:
+    argv = [
+        git,
+        "-c",
+        "core.fsmonitor=false",
+        "--no-pager",
+        "diff",
+        "--no-ext-diff",
+        "--no-textconv",
+    ]
+    if staged:
+        argv.append("--cached")
+    return argv
+
+
+def log_argv(git: str, *, max_entries: int) -> list[str]:
+    return [
+        git,
+        "-c",
+        "core.fsmonitor=false",
+        "--no-pager",
+        "log",
+        f"--max-count={max_entries}",
+        "--oneline",
+        "--no-decorate",
+    ]
+
+
+def is_canonical_git_argv(operation: str, argv: list[str], git: str | None) -> bool:
+    if git is None:
+        return False
+    if operation == "git_status":
+        return argv == status_argv(git)
+    if operation == "git_diff":
+        return argv in (diff_argv(git, staged=False), diff_argv(git, staged=True))
+    if operation == "git_log" and len(argv) == 8:
+        prefix = [git, "-c", "core.fsmonitor=false", "--no-pager", "log"]
+        if argv[:5] != prefix or argv[6:] != ["--oneline", "--no-decorate"]:
+            return False
+        value = argv[5]
+        if not value.startswith("--max-count="):
+            return False
+        try:
+            count = int(value.removeprefix("--max-count="))
+        except ValueError:
+            return False
+        return 1 <= count <= 100
+    return False

nexus/security/workspace.py

@@ -0,0 +1,93 @@
+"""Centralized repository-relative path containment."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from nexus.errors import PermissionDeniedError, ToolExecutionError
+
+
+class WorkspaceGuard:
+    def __init__(self, workspace: Path) -> None:
+        try:
+            self._workspace = workspace.resolve(strict=True)
+        except OSError as exc:
+            raise ToolExecutionError("The configured workspace does not exist.") from exc
+        if not self._workspace.is_dir():
+            raise ToolExecutionError("The configured workspace is not a directory.")
+        self._normalized_workspace = os.path.normcase(str(self._workspace))
+
+    @property
+    def root(self) -> Path:
+        return self._workspace
+
+    def resolve_existing(
+        self,
+        relative_path: str,
+        *,
+        require_file: bool = False,
+        require_directory: bool = False,
+    ) -> Path:
+        requested = Path(relative_path)
+        if requested.is_absolute():
+            raise self._denied()
+        try:
+            resolved = (self._workspace / requested).resolve(strict=True)
+        except (OSError, RuntimeError) as exc:
+            if ".." in requested.parts:
+                raise self._denied() from exc
+            raise ToolExecutionError(
+                "The requested workspace path does not exist.",
+                code="TOOL_EXECUTION_ERROR",
+            ) from exc
+        if not self._contains(resolved):
+            raise self._denied()
+        if require_file and not resolved.is_file():
+            raise ToolExecutionError("The requested path is not a regular file.")
+        if require_directory and not resolved.is_dir():
+            raise ToolExecutionError("The requested path is not a directory.")
+        return resolved
+
+    def relative_display(self, path: Path) -> str:
+        return path.relative_to(self._workspace).as_posix() or "."
+
+    def resolve_for_creation(self, relative_path: str) -> Path:
+        requested = Path(relative_path)
+        if requested.is_absolute() or ".." in requested.parts:
+            raise self._denied()
+        parent_requested = requested.parent
+        try:
+            parent = (self._workspace / parent_requested).resolve(strict=True)
+        except (OSError, RuntimeError) as exc:
+            if ".." in requested.parts:
+                raise self._denied() from exc
+            raise ToolExecutionError(
+                "The target parent directory does not exist.",
+                code="PARENT_DIRECTORY_MISSING",
+            ) from exc
+        if not self._contains(parent) or not parent.is_dir():
+            raise self._denied()
+        target = parent / requested.name
+        if target.exists() or target.is_symlink():
+            raise ToolExecutionError(
+                "The target file already exists.",
+                code="FILE_ALREADY_EXISTS",
+            )
+        return target
+
+    def _contains(self, path: Path) -> bool:
+        normalized = os.path.normcase(str(path))
+        try:
+            return os.path.commonpath([self._normalized_workspace, normalized]) == (
+                self._normalized_workspace
+            )
+        except ValueError:
+            return False
+
+    @staticmethod
+    def _denied() -> PermissionDeniedError:
+        return PermissionDeniedError(
+            "The requested path is outside the configured workspace.",
+            code="WORKSPACE_PATH_DENIED",
+        )

nexus/skills/__init__.py

@@ -0,0 +1,7 @@
+"""File-based Day 7 Skill services."""
+
+from nexus.skills.loader import FileSkillLoader
+from nexus.skills.registry import DefaultSkillRegistry
+from nexus.skills.selector import ModelSkillSelector
+
+__all__ = ["DefaultSkillRegistry", "FileSkillLoader", "ModelSkillSelector"]

nexus/skills/builtin/__init__.py

@@ -0,0 +1 @@
+"""Packaged Nexus builtin Skill resources."""

nexus/skills/builtin/debug-python/SKILL.md

@@ -0,0 +1,26 @@
++++
+id = "debug-python"
+name = "Debug Python"
+description = "Diagnose Python failures from reproducible repository evidence."
+usage_scenario = "Use for Python exceptions, failing tests, and behavioral regressions."
+priority = 60
+version = "1.0.0"
++++
+
+## Execution Principles
+
+Reproduce the failure first and keep observed evidence separate from hypotheses.
+
+## Recommended Tools
+
+Use bounded repository search, focused file reads, and the approved validation tools.
+
+## Workflow
+
+1. Reproduce the smallest failing case.
+2. Trace the narrowest relevant call path.
+3. Correct the evidenced cause and rerun focused validation.
+
+## Constraints
+
+Do not broaden scope, suppress failures, or bypass Plan, policy, sandbox, and validation.

nexus/skills/builtin/review-repository/SKILL.md

@@ -0,0 +1,26 @@
++++
+id = "review-repository"
+name = "Review Repository"
+description = "Review repository changes for correctness, regressions, and contract drift."
+usage_scenario = "Use for code review, architecture review, and change-risk assessment."
+priority = 40
+version = "1.0.0"
++++
+
+## Execution Principles
+
+Lead with concrete findings and verify each claim against the current diff and contracts.
+
+## Recommended Tools
+
+Use bounded search, focused source reads, git status/diff, and relevant validation evidence.
+
+## Workflow
+
+1. Establish the intended contract and change boundary.
+2. Inspect affected call paths and tests for behavioral risk.
+3. Report actionable findings by severity with precise evidence.
+
+## Constraints
+
+Do not invent defects, expose private reasoning, or treat successful tests as complete proof.

nexus/skills/builtin/write-tests/SKILL.md

@@ -0,0 +1,26 @@
++++
+id = "write-tests"
+name = "Write Tests"
+description = "Add focused tests that demonstrate behavior and guard regressions."
+usage_scenario = "Use when a task primarily asks for unit, integration, or regression tests."
+priority = 50
+version = "1.0.0"
++++
+
+## Execution Principles
+
+Test observable contracts and failure boundaries rather than private implementation details.
+
+## Recommended Tools
+
+Use focused repository reads, the existing test framework, and approved validation commands.
+
+## Workflow
+
+1. Identify the public behavior and existing test conventions.
+2. Add the smallest deterministic fixture that fails for the missing behavior.
+3. Run focused tests before the broader regression suite.
+
+## Constraints
+
+Do not weaken assertions, replace real evidence with mocks unnecessarily, or bypass policy.