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

nexus/config/loader.py

@@ -0,0 +1,253 @@
+"""Resolve Day 1 configuration with the frozen per-field precedence."""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from pydantic import ValidationError
+
+from nexus.config.models import RuntimeConfig
+from nexus.errors import ConfigurationError
+
+_ENV_FIELDS = {
+    "NEXUS_MODEL_PROVIDER": "model_provider",
+    "NEXUS_MODEL_NAME": "model_name",
+    "NEXUS_MODEL_BASE_URL": "model_base_url",
+    "NEXUS_MODEL_API_KEY": "model_api_key",
+    "NEXUS_DATABASE_URL": "database_url",
+    "NEXUS_APPROVAL_MODE": "approval_mode",
+    "NEXUS_MAX_STEPS": "max_steps",
+    "NEXUS_MAX_REPAIR_ATTEMPTS": "max_repair_attempts",
+    "NEXUS_MAX_REPLANS": "max_replans",
+    "NEXUS_MAX_SELECTED_SKILLS": "max_selected_skills",
+    "NEXUS_CONSOLE_TRACING_ENABLED": "console_tracing_enabled",
+    "NEXUS_LANGSMITH_TRACING_ENABLED": "langsmith_tracing_enabled",
+    "NEXUS_LANGSMITH_PROJECT": "langsmith_project",
+    "NEXUS_LANGSMITH_ENDPOINT": "langsmith_endpoint",
+    "NEXUS_LANGSMITH_WORKSPACE_ID": "langsmith_workspace_id",
+    "NEXUS_LANGSMITH_API_KEY": "langsmith_api_key",
+}
+
+_CONTEXT_INTEGERS = (
+    "max_retrieved_chunks", "max_exploration_seed_chunks", "max_code_context_tokens",
+    "max_recent_observations", "max_model_input_tokens", "max_file_size_bytes",
+)
+_ENV_FIELDS.update({f"NEXUS_{name.upper()}": name for name in _CONTEXT_INTEGERS})
+_ENV_FIELDS.update({
+    "NEXUS_SEMANTIC_ENABLED": "semantic_enabled",
+    "NEXUS_EMBEDDING_MODEL": "embedding_model",
+    "NEXUS_EMBEDDING_DIMENSION": "embedding_dimension",
+    "NEXUS_EMBEDDING_BASE_URL": "embedding_base_url",
+    "NEXUS_EMBEDDING_API_KEY": "embedding_api_key",
+})
+
+
+def load_runtime_config(
+    *,
+    cli_model: str | None = None,
+    cli_base_url: str | None = None,
+    repo_root: Path | None = None,
+    user_config_path: Path | None = None,
+    environ: Mapping[str, str] | None = None,
+) -> RuntimeConfig:
+    """Load configuration per field from lowest to highest priority."""
+
+    environment = os.environ if environ is None else environ
+    resolved: dict[str, Any] = {}
+    resolved.update(_environment_values(environment))
+
+    user_path = user_config_path or (Path.home() / ".nexus" / "config.toml")
+    resolved.update(_toml_values(user_path, allow_remote_observability=True))
+
+    repository = repo_root or Path.cwd()
+    resolved.update(
+        _toml_values(
+            repository / ".nexus" / "config.toml",
+            allow_mcp=False,
+            allow_remote_observability=False,
+        )
+    )
+
+    if cli_model is not None:
+        resolved["model_name"] = cli_model
+    if cli_base_url is not None:
+        resolved["model_base_url"] = cli_base_url
+
+    try:
+        return RuntimeConfig.model_validate(resolved)
+    except ValidationError as exc:
+        code = (
+            "TRACE_CONFIGURATION_INVALID"
+            if any("langsmith" in str(error).lower() for error in exc.errors())
+            else None
+        )
+        raise ConfigurationError("Runtime configuration is invalid.", code=code) from exc
+
+
+def _environment_values(environ: Mapping[str, str]) -> dict[str, Any]:
+    return {
+        field: environ[variable]
+        for variable, field in _ENV_FIELDS.items()
+        if variable in environ
+    }
+
+
+def _toml_values(
+    path: Path,
+    *,
+    allow_mcp: bool = True,
+    allow_remote_observability: bool = True,
+) -> dict[str, Any]:
+    if not path.is_file():
+        return {}
+    try:
+        with path.open("rb") as config_file:
+            document = tomllib.load(config_file)
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        raise ConfigurationError(f"Could not read Nexus configuration at {path}.") from exc
+
+    if not allow_mcp and "mcp" in document:
+        raise ConfigurationError(
+            "Repository configuration must not define [mcp]; MCP process and server "
+            "configuration is allowed only in the user-level ~/.nexus/config.toml."
+        )
+    observability = _table(document, "observability", path)
+    if not allow_remote_observability and _contains_key(document, "langsmith"):
+        raise ConfigurationError(
+            "Repository configuration must not define LangSmith observability.",
+            code="TRACE_CONFIGURATION_INVALID",
+        )
+
+    model = _table(document, "model", path)
+    database = _table(document, "database", path)
+    runtime = _table(document, "runtime", path)
+    context = _table(document, "context", path)
+    embedding = _table(document, "embedding", path)
+    skills = _table(document, "skills", path)
+    mcp = _table(document, "mcp", path)
+    console = _table(observability, "console", path)
+    langsmith = _table(observability, "langsmith", path)
+    if "api_key" in embedding:
+        raise ConfigurationError("Embedding API keys are not supported in Nexus TOML.")
+    if "api_key" in model:
+        raise ConfigurationError(
+            f"API keys are not supported in Nexus TOML configuration at {path}."
+        )
+    if "api_key" in langsmith:
+        raise ConfigurationError(
+            "LangSmith API keys are accepted only from NEXUS_LANGSMITH_API_KEY.",
+            code="TRACE_CONFIGURATION_INVALID",
+        )
+
+    values: dict[str, Any] = {}
+    for name in _CONTEXT_INTEGERS:
+        _copy_optional_integer(context, name, name, values, path)
+    if "semantic_enabled" in context:
+        if not isinstance(context["semantic_enabled"], bool):
+            raise ConfigurationError("semantic_enabled must be a TOML boolean.")
+        values["semantic_enabled"] = context["semantic_enabled"]
+    for name in ("provider", "model", "base_url"):
+        _copy_optional_string(embedding, name, f"embedding_{name}", values, path)
+    _copy_optional_integer(embedding, "dimension", "embedding_dimension", values, path)
+    _copy_optional_integer(
+        skills,
+        "max_selected_skills",
+        "max_selected_skills",
+        values,
+        path,
+    )
+    _copy_optional_string(model, "provider", "model_provider", values, path)
+    _copy_optional_string(model, "name", "model_name", values, path)
+    _copy_optional_string(model, "base_url", "model_base_url", values, path)
+    _copy_optional_string(database, "url", "database_url", values, path)
+    _copy_optional_string(runtime, "approval_mode", "approval_mode", values, path)
+    _copy_optional_integer(runtime, "max_steps", "max_steps", values, path)
+    _copy_optional_integer(
+        runtime,
+        "max_repair_attempts",
+        "max_repair_attempts",
+        values,
+        path,
+    )
+    _copy_optional_integer(runtime, "max_replans", "max_replans", values, path)
+    if "enabled" in mcp:
+        if not isinstance(mcp["enabled"], bool):
+            raise ConfigurationError("mcp.enabled must be a TOML boolean.")
+        values["mcp_enabled"] = mcp["enabled"]
+    if "servers" in mcp:
+        servers = mcp["servers"]
+        if not isinstance(servers, list) or any(
+            not isinstance(server, Mapping) for server in servers
+        ):
+            raise ConfigurationError("mcp.servers must be an array of tables.")
+        values["mcp_servers"] = [dict(server) for server in servers]
+    if "enabled" in console:
+        if not isinstance(console["enabled"], bool):
+            raise ConfigurationError("observability.console.enabled must be a TOML boolean.")
+        values["console_tracing_enabled"] = console["enabled"]
+    if "enabled" in langsmith:
+        if not isinstance(langsmith["enabled"], bool):
+            raise ConfigurationError(
+                "observability.langsmith.enabled must be a TOML boolean.",
+                code="TRACE_CONFIGURATION_INVALID",
+            )
+        values["langsmith_tracing_enabled"] = langsmith["enabled"]
+    for name, target in (
+        ("project", "langsmith_project"),
+        ("endpoint", "langsmith_endpoint"),
+        ("workspace_id", "langsmith_workspace_id"),
+    ):
+        _copy_optional_string(langsmith, name, target, values, path)
+    return values
+
+
+def _table(document: Mapping[str, Any], name: str, path: Path) -> Mapping[str, Any]:
+    value = document.get(name, {})
+    if not isinstance(value, Mapping):
+        raise ConfigurationError(f"[{name}] must be a TOML table in {path}.")
+    return value
+
+
+def _copy_optional_string(
+    source: Mapping[str, Any],
+    source_key: str,
+    target_key: str,
+    target: dict[str, Any],
+    path: Path,
+) -> None:
+    if source_key not in source:
+        return
+    value = source[source_key]
+    if not isinstance(value, str):
+        raise ConfigurationError(f"{source_key} must be a string in {path}.")
+    target[target_key] = value
+
+
+def _copy_optional_integer(
+    source: Mapping[str, Any],
+    source_key: str,
+    target_key: str,
+    target: dict[str, Any],
+    path: Path,
+) -> None:
+    if source_key not in source:
+        return
+    value = source[source_key]
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise ConfigurationError(f"{source_key} must be an integer in {path}.")
+    target[target_key] = value
+
+
+def _contains_key(value: object, prohibited: str) -> bool:
+    if isinstance(value, Mapping):
+        return any(
+            prohibited in str(key).lower() or _contains_key(item, prohibited)
+            for key, item in value.items()
+        )
+    if isinstance(value, list):
+        return any(_contains_key(item, prohibited) for item in value)
+    return False

nexus/config/models.py

@@ -0,0 +1,310 @@
+"""Typed Day 1 runtime configuration."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from urllib.parse import urlsplit, urlunsplit
+
+from pydantic import BaseModel, ConfigDict, Field, SecretStr, field_validator, model_validator
+
+from nexus.domain.tooling import RiskLevel
+from nexus.errors import ConfigurationError
+
+DEFAULT_DATABASE_URL = "postgresql+asyncpg://nexus:nexus@localhost:5432/nexus"
+SUPPORTED_MODEL_PROVIDER = "openai_compatible"
+
+
+class ApprovalMode(StrEnum):
+    APPROVAL = "approval"
+    AUTO = "auto"
+
+
+class MCPTransport(StrEnum):
+    STDIO = "stdio"
+
+
+class MCPToolRiskConfig(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    tool_name: str
+    risk_level: RiskLevel
+
+    @field_validator("tool_name")
+    @classmethod
+    def validate_tool_name(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError("MCP tool_name must not be empty.")
+        return value
+
+
+class MCPServerConfig(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    server_id: str = Field(pattern=r"^[a-z][a-z0-9_-]{0,63}$")
+    enabled: bool = True
+    transport: MCPTransport = MCPTransport.STDIO
+    command: str
+    args: tuple[str, ...] = ()
+    inherit_environment: bool = True
+    connect_timeout_seconds: float = Field(default=10.0, gt=0, le=60)
+    tool_timeout_seconds: float = Field(default=30.0, gt=0, le=300)
+    max_connect_attempts: int = Field(default=2, ge=1, le=3)
+    tool_risks: tuple[MCPToolRiskConfig, ...] = ()
+
+    @field_validator("command")
+    @classmethod
+    def validate_command(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError("MCP command must not be empty.")
+        return value
+
+    @field_validator("args")
+    @classmethod
+    def validate_args(cls, value: tuple[str, ...]) -> tuple[str, ...]:
+        if any(not item.strip() for item in value):
+            raise ValueError("MCP args must contain only non-empty strings.")
+        return value
+
+    @field_validator("max_connect_attempts", mode="before")
+    @classmethod
+    def reject_boolean_attempts(cls, value: object) -> object:
+        if isinstance(value, bool):
+            raise ValueError("MCP max_connect_attempts must be an integer.")
+        return value
+
+    @model_validator(mode="after")
+    def validate_unique_risks(self) -> MCPServerConfig:
+        names = [item.tool_name for item in self.tool_risks]
+        if len(names) != len(set(names)):
+            raise ValueError("MCP tool_risks contains duplicate tool_name entries.")
+        return self
+
+
+class RuntimeConfig(BaseModel):
+    """The exact approved Day 1 configuration surface."""
+
+    model_config = ConfigDict(frozen=True)
+
+    model_provider: str = SUPPORTED_MODEL_PROVIDER
+    model_name: str | None = None
+    model_base_url: str | None = None
+    model_api_key: SecretStr | None = None
+    database_url: str = DEFAULT_DATABASE_URL
+    approval_mode: ApprovalMode = ApprovalMode.APPROVAL
+    max_steps: int = 30
+    max_repair_attempts: int = 3
+    max_replans: int = 2
+    semantic_enabled: bool = False
+    lexical_top_k: int = Field(default=20, ge=20, le=20)
+    semantic_top_k: int = Field(default=20, ge=20, le=20)
+    rrf_k: int = Field(default=60, ge=60, le=60)
+    final_candidate_count: int = Field(default=12, ge=12, le=12)
+    max_retrieved_chunks: int = Field(default=12, ge=0, le=12)
+    max_exploration_seed_chunks: int = Field(default=6, ge=0, le=6)
+    max_code_context_tokens: int = Field(default=12000, ge=0, le=12000)
+    max_recent_observations: int = Field(default=8, ge=0, le=8)
+    max_model_input_tokens: int = Field(default=24000, ge=1, le=24000)
+    max_file_size_bytes: int = Field(default=1048576, ge=1)
+    embedding_provider: str = "openai_compatible"
+    embedding_model: str = ""
+    embedding_dimension: int = Field(default=0, ge=0)
+    embedding_base_url: str = ""
+    embedding_api_key: SecretStr | None = None
+    max_selected_skills: int = Field(default=2, ge=0, le=2)
+    mcp_enabled: bool = False
+    mcp_servers: tuple[MCPServerConfig, ...] = ()
+    console_tracing_enabled: bool = False
+    langsmith_tracing_enabled: bool = False
+    langsmith_project: str = "nexus"
+    langsmith_endpoint: str | None = None
+    langsmith_workspace_id: str | None = None
+    langsmith_api_key: SecretStr | None = None
+
+    def require_embedding(self) -> None:
+        """Validate only when a semantic/index capability is actually requested."""
+        if (
+            self.embedding_provider != "openai_compatible"
+            or not self.embedding_model.strip()
+            or self.embedding_dimension <= 0
+            or not self.embedding_base_url.startswith(("https://", "http://"))
+            or self.embedding_api_key is None
+            or not self.embedding_api_key.get_secret_value().strip()
+        ):
+            raise ConfigurationError(
+                "Configure embedding provider/model/dimension/base_url and "
+                "NEXUS_EMBEDDING_API_KEY, or disable semantic retrieval."
+            )
+
+    @model_validator(mode="after")
+    def validate_context_budget(self) -> RuntimeConfig:
+        if self.max_code_context_tokens > self.max_model_input_tokens:
+            raise ValueError("Code context budget must not exceed total model input budget.")
+        return self
+
+    @field_validator("model_provider")
+    @classmethod
+    def validate_provider(cls, value: str) -> str:
+        if value != SUPPORTED_MODEL_PROVIDER:
+            raise ValueError(f"unsupported Day 1 model provider: {value!r}")
+        return value
+
+    @field_validator(
+        "model_name",
+        "model_base_url",
+        "langsmith_endpoint",
+        "langsmith_workspace_id",
+        mode="before",
+    )
+    @classmethod
+    def normalize_optional_text(cls, value: object) -> object:
+        if isinstance(value, str):
+            normalized = value.strip()
+            return normalized or None
+        return value
+
+    @field_validator("model_name")
+    @classmethod
+    def validate_model_name_length(cls, value: str | None) -> str | None:
+        if value is not None and len(value) > 256:
+            raise ValueError("Model name is too long for safe observability.")
+        return value
+
+    @field_validator("database_url")
+    @classmethod
+    def validate_database_url(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError("database URL must not be empty")
+        if not value.startswith("postgresql+asyncpg://"):
+            raise ValueError("Day 1 database URL must use postgresql+asyncpg")
+        return value
+
+    @field_validator(
+        "max_steps",
+        "max_repair_attempts",
+        "max_replans",
+        "lexical_top_k",
+        "semantic_top_k",
+        "rrf_k",
+        "final_candidate_count",
+        "max_retrieved_chunks",
+        "max_exploration_seed_chunks",
+        "max_code_context_tokens",
+        "max_recent_observations",
+        "max_model_input_tokens",
+        "max_file_size_bytes",
+        "embedding_dimension",
+        "max_selected_skills",
+        mode="before",
+    )
+    @classmethod
+    def reject_boolean_limits(cls, value: object) -> object:
+        if isinstance(value, bool):
+            raise ValueError("Runtime limits must be integers, not booleans.")
+        return value
+
+    @model_validator(mode="after")
+    def validate_day4_limits(self) -> RuntimeConfig:
+        if self.max_steps <= 0:
+            raise ValueError("max_steps must be greater than zero.")
+        if self.max_repair_attempts < 0 or self.max_replans < 0:
+            raise ValueError("Repair and Replan limits must not be negative.")
+        return self
+
+    @model_validator(mode="after")
+    def validate_unique_mcp_servers(self) -> RuntimeConfig:
+        server_ids = [server.server_id for server in self.mcp_servers]
+        if len(server_ids) != len(set(server_ids)):
+            raise ValueError("MCP server_id values must be unique.")
+        return self
+
+    @field_validator("langsmith_project")
+    @classmethod
+    def validate_langsmith_project(cls, value: str) -> str:
+        normalized = value.strip()
+        if not normalized or len(normalized) > 256:
+            raise ValueError("LangSmith project must be a bounded non-empty identifier.")
+        return normalized
+
+    @field_validator("langsmith_workspace_id")
+    @classmethod
+    def validate_langsmith_workspace_id(cls, value: str | None) -> str | None:
+        if value is not None and len(value) > 256:
+            raise ValueError("LangSmith workspace ID is too long.")
+        return value
+
+    @field_validator("langsmith_endpoint")
+    @classmethod
+    def validate_langsmith_endpoint(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        parts = urlsplit(value)
+        if (
+            parts.scheme not in {"http", "https"}
+            or not parts.hostname
+            or parts.username is not None
+            or parts.password is not None
+            or parts.query
+            or parts.fragment
+        ):
+            raise ValueError("LangSmith endpoint must be a credential-free HTTP(S) URL.")
+        return value
+
+    @model_validator(mode="after")
+    def validate_langsmith_enablement(self) -> RuntimeConfig:
+        if self.langsmith_tracing_enabled and (
+            self.langsmith_api_key is None
+            or not self.langsmith_api_key.get_secret_value().strip()
+        ):
+            raise ValueError("Enabled LangSmith tracing requires NEXUS_LANGSMITH_API_KEY.")
+        return self
+
+    def __repr__(self) -> str:
+        api_key = "**********" if self.model_api_key is not None else "None"
+        return (
+            "RuntimeConfig("
+            f"model_provider={self.model_provider!r}, "
+            f"model_name={self.model_name!r}, "
+            f"model_base_url={self.model_base_url!r}, "
+            f"model_api_key={api_key}, "
+            f"database_url={redact_database_url(self.database_url)!r}, "
+            f"approval_mode={self.approval_mode.value!r}, "
+            f"max_steps={self.max_steps!r}, "
+            f"max_repair_attempts={self.max_repair_attempts!r}, "
+            f"max_replans={self.max_replans!r}, "
+            f"mcp_enabled={self.mcp_enabled!r}, "
+            f"mcp_server_count={len(self.mcp_servers)!r}, "
+            f"console_tracing_enabled={self.console_tracing_enabled!r}, "
+            f"langsmith_tracing_enabled={self.langsmith_tracing_enabled!r}, "
+            f"langsmith_project={self.langsmith_project!r}, "
+            f"langsmith_endpoint={redact_endpoint(self.langsmith_endpoint)!r}, "
+            f"langsmith_workspace_id={self.langsmith_workspace_id!r}, "
+            f"langsmith_api_key={'**********' if self.langsmith_api_key else 'None'}"
+            ")"
+        )
+
+    __str__ = __repr__
+
+
+def redact_database_url(value: str) -> str:
+    """Hide embedded database credentials while preserving useful location data."""
+
+    try:
+        parts = urlsplit(value)
+    except ValueError:
+        return "<redacted-database-url>"
+    if parts.username is None and parts.password is None:
+        return value
+
+    hostname = parts.hostname or ""
+    port = f":{parts.port}" if parts.port is not None else ""
+    redacted_netloc = f"***:***@{hostname}{port}"
+    return urlunsplit((parts.scheme, redacted_netloc, parts.path, parts.query, parts.fragment))
+
+
+def redact_endpoint(value: str | None) -> str | None:
+    if value is None:
+        return None
+    parts = urlsplit(value)
+    hostname = parts.hostname or ""
+    port = f":{parts.port}" if parts.port is not None else ""
+    return urlunsplit((parts.scheme, f"{hostname}{port}", "", "", ""))

nexus/context/__init__.py

@@ -0,0 +1,6 @@
+"""Selective Day 4 repository context services."""
+
+from nexus.context.builder import BoundedContextBuilder
+from nexus.context.explorer import SelectiveRepositoryExplorer
+
+__all__ = ["BoundedContextBuilder", "SelectiveRepositoryExplorer"]

nexus/context/budget.py

@@ -0,0 +1,24 @@
+"""Shared Day 5 model-input accounting exposed through the Day 7 guard port."""
+
+from collections.abc import Sequence
+
+from nexus.context.manager import model_input_tokens
+from nexus.domain.model import ModelMessage
+from nexus.errors import ContextError
+
+
+class Day5ModelInputBudgetGuard:
+    def __init__(self, maximum: int) -> None:
+        self._maximum = maximum
+
+    def ensure_fits(
+        self,
+        messages: Sequence[ModelMessage],
+        *,
+        error_code: str,
+    ) -> None:
+        if model_input_tokens(messages) > self._maximum:
+            raise ContextError(
+                "The complete model request exceeds the configured input budget.",
+                code=error_code,
+            )

nexus/context/builder.py

@@ -0,0 +1,92 @@
+"""Bounded Day 4 context seed construction."""
+
+from __future__ import annotations
+
+from pathlib import PurePosixPath
+from uuid import uuid4
+
+from nexus.application.tool_runtime import ToolRuntime
+from nexus.domain.exploration import (
+    ContextBuildRequest,
+    RepositoryInstruction,
+    SelectedFileContext,
+    WorkingContext,
+)
+from nexus.domain.tooling import ToolInvocation
+from nexus.errors import ContextError
+
+
+class BoundedContextBuilder:
+    def __init__(self, tool_runtime: ToolRuntime) -> None:
+        self._tool_runtime = tool_runtime
+
+    async def build(self, request: ContextBuildRequest) -> WorkingContext:
+        selected: list[SelectedFileContext] = []
+        retained = 0
+        truncated = request.exploration.truncated
+        for evidence in request.exploration.relevant_files[:8]:
+            result = await self._tool_runtime.execute(
+                ToolInvocation(
+                    str(uuid4()),
+                    "read_file",
+                    {"path": evidence.path, "start_line": 1, "max_lines": 400},
+                    request.run_id,
+                    request.session_id,
+                )
+            )
+            if not result.success or result.output is None:
+                truncated = True
+                continue
+            content = result.output.get("content")
+            if not isinstance(content, str):
+                truncated = True
+                continue
+            remaining = 48_000 - retained
+            if remaining <= 0:
+                truncated = True
+                break
+            bounded = content[:remaining]
+            retained += len(bounded)
+            item_truncated = result.output.get("truncated") is True or len(bounded) < len(content)
+            truncated = truncated or item_truncated
+            selected.append(
+                SelectedFileContext(
+                    evidence.path,
+                    bounded,
+                    _applicable_instructions(
+                        evidence.path,
+                        request.exploration.instructions,
+                    ),
+                    evidence.discovery_reason,
+                    item_truncated,
+                )
+            )
+        if request.exploration.relevant_files and not selected:
+            raise ContextError(
+                "Nexus could not build context from selected repository evidence.",
+                code="CONTEXT_BUILD_FAILED",
+                retryable=True,
+            )
+        return WorkingContext(
+            request.task,
+            request.exploration.instructions,
+            request.exploration.manifests,
+            request.exploration.top_level_paths,
+            tuple(selected),
+            truncated,
+        )
+
+
+def _applicable_instructions(
+    path: str,
+    instructions: tuple[RepositoryInstruction, ...],
+) -> tuple[str, ...]:
+    target = PurePosixPath(path)
+    applicable = [
+        instruction
+        for instruction in instructions
+        if instruction.scope_path == "."
+        or PurePosixPath(instruction.scope_path) == target.parent
+        or PurePosixPath(instruction.scope_path) in target.parents
+    ]
+    return tuple(item.path for item in sorted(applicable, key=lambda item: (item.depth, item.path)))