shikiru-cli 0.2.0__py3-none-any.whl

shikiru/operator/commands.py

@@ -0,0 +1,319 @@
+"""Operator command acknowledgements over the typed command queue."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from datetime import timedelta
+from enum import StrEnum, auto
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel, ConfigDict, PrivateAttr
+
+from shikiru.domain.commands import (
+    COMMAND_POLL_SECONDS,
+    AcceptResolution,
+    AnswerResolution,
+    Cancel,
+    CancelResolution,
+    HandBack,
+    Pause,
+    Prioritize,
+    Resolution,
+    ResolutionKind,
+    Resolve,
+    Resume,
+    Retry,
+    RetryResolution,
+    Say,
+    SetRung,
+    Stop,
+    Submit,
+    TakeOver,
+)
+from shikiru.domain.tasks import title_from_request
+from shikiru.errors import DatabaseError
+from shikiru.store.commands import CommandQueue, CommandStatus
+from shikiru.store.database import OperationalDatabaseError
+
+if TYPE_CHECKING:
+    from shikiru.agents.contracts import Rung
+    from shikiru.clock import Clock
+    from shikiru.config.settings import ComplexityName
+    from shikiru.domain.commands import Command
+    from shikiru.domain.tasks import Mode, Role
+
+COMMAND_ACK_WAIT_SECONDS = 10.0
+QUEUED_MESSAGE = "applies when the engine starts"
+ACK_TIMEOUT_MESSAGE = (
+    f"engine did not acknowledge the command within {COMMAND_ACK_WAIT_SECONDS:g} seconds"
+)
+
+EngineState = Callable[[], bool]
+
+
+class AckStatus(StrEnum):
+    """The operator-visible command lifecycle, including an engine-down queue state."""
+
+    DONE = auto()
+    REJECTED = auto()
+    QUEUED = auto()
+
+
+class Ack(BaseModel):
+    """The result returned after a command is queued or handled by the engine."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    id: int
+    status: AckStatus
+    result: dict[str, Any] | None = None
+    message: str | None = None
+    _submitted_task_id: str | None = PrivateAttr(default=None)
+
+    @property
+    def submitted_task_id(self) -> str | None:
+        """Return the task identity allocated for a submitted command, when applicable."""
+        return self._submitted_task_id
+
+    @classmethod
+    def from_command(
+        cls,
+        command: Command,
+        *,
+        command_id: int,
+        status: AckStatus,
+        result: dict[str, Any] | None,
+        message: str | None,
+    ) -> Ack:
+        """Create an acknowledgement while retaining submitted task identity for human output."""
+        ack = cls(id=command_id, status=status, result=result, message=message)
+        if isinstance(command, Submit):
+            ack._submitted_task_id = command.task_id
+        return ack
+
+
+class OperatorCommands:
+    """Append typed commands and wait briefly for a running engine's acknowledgement.
+
+    A database that stays locked past its busy timeout raises `DatabaseError`; nothing is queued.
+    """
+
+    def __init__(
+        self,
+        queue: CommandQueue,
+        clock: Clock,
+        *,
+        engine_up: EngineState,
+    ) -> None:
+        """Use `queue` and `clock` for command and acknowledgement boundaries."""
+        self._queue = queue
+        self._clock = clock
+        self._engine_up = engine_up
+
+    async def send(self, command: Command) -> Ack:
+        """Queue `command`, returning done/rejected or queued when the engine is down."""
+        try:
+            queued = self._queue.append(command)
+        except OperationalDatabaseError as error:
+            message = f"the state database is busy and the command was not queued: {error}"
+            raise DatabaseError(message) from error
+        if not self._engine_up():
+            return _queued_ack(queued.id, queued.command, QUEUED_MESSAGE)
+        deadline = self._clock.now() + timedelta(seconds=COMMAND_ACK_WAIT_SECONDS)
+        while True:
+            outcome = self._queue.status(queued.id)
+            if outcome is not None and outcome.status is not CommandStatus.PENDING:
+                status = (
+                    AckStatus.DONE if outcome.status is CommandStatus.DONE else AckStatus.REJECTED
+                )
+                message = _result_message(outcome.result)
+                return Ack.from_command(
+                    queued.command,
+                    command_id=outcome.id,
+                    status=status,
+                    result=outcome.result,
+                    message=message,
+                )
+            if self._clock.now() >= deadline:
+                return _queued_ack(queued.id, queued.command, ACK_TIMEOUT_MESSAGE)
+            await self._clock.sleep(COMMAND_POLL_SECONDS)
+
+    async def submit_task(
+        self,
+        request: str,
+        *,
+        title: str | None = None,
+        mode: Mode | None = None,
+        complexity: ComplexityName | None = None,
+        priority: int = 0,
+        depends_on: Sequence[str] = (),
+        leader: Rung | None = None,
+        implementer: Rung | None = None,
+    ) -> Ack:
+        """Queue a `Submit` command, allocating its task id atomically in the store."""
+        return await self.send(
+            self.prepare_submit_task(
+                request,
+                title=title,
+                mode=mode,
+                complexity=complexity,
+                priority=priority,
+                depends_on=depends_on,
+                leader=leader,
+                implementer=implementer,
+            )
+        )
+
+    def prepare_submit_task(
+        self,
+        request: str,
+        *,
+        title: str | None = None,
+        mode: Mode | None = None,
+        complexity: ComplexityName | None = None,
+        priority: int = 0,
+        depends_on: Sequence[str] = (),
+        leader: Rung | None = None,
+        implementer: Rung | None = None,
+    ) -> Submit:
+        """Prepare the typed submission used by both palette recovery and dispatch."""
+        task_title = title if title is not None else title_from_request(request)
+        return Submit(
+            title=task_title,
+            request=request,
+            mode=mode,
+            complexity=complexity,
+            priority=priority,
+            depends_on=list(depends_on),
+            leader=leader,
+            implementer=implementer,
+        )
+
+    async def prioritize_task(self, task_id: str, priority: int) -> Ack:
+        """Queue a `Prioritize` command."""
+        return await self.send(self.prepare_prioritize_task(task_id, priority))
+
+    def prepare_prioritize_task(self, task_id: str, priority: int) -> Prioritize:
+        """Prepare the typed priority command used by the palette and dispatcher."""
+        return Prioritize(task_id=task_id, priority=priority)
+
+    async def pause_task(self, task_id: str, *, now: bool = False) -> Ack:
+        """Queue a `Pause` command."""
+        return await self.send(self.prepare_pause_task(task_id, now=now))
+
+    def prepare_pause_task(self, task_id: str, *, now: bool = False) -> Pause:
+        """Prepare the typed pause command used by the palette and dispatcher."""
+        return Pause(task_id=task_id, now=now)
+
+    async def resume_task(self, task_id: str) -> Ack:
+        """Queue a `Resume` command."""
+        return await self.send(self.prepare_resume_task(task_id))
+
+    def prepare_resume_task(self, task_id: str) -> Resume:
+        """Prepare the typed resume command used by the palette and dispatcher."""
+        return Resume(task_id=task_id)
+
+    async def cancel_task(self, task_id: str) -> Ack:
+        """Queue a `Cancel` command."""
+        return await self.send(self.prepare_cancel_task(task_id))
+
+    def prepare_cancel_task(self, task_id: str) -> Cancel:
+        """Prepare the typed cancel command used by the palette and dispatcher."""
+        return Cancel(task_id=task_id)
+
+    async def retry_task(self, task_id: str) -> Ack:
+        """Queue a `Retry` command."""
+        return await self.send(self.prepare_retry_task(task_id))
+
+    def prepare_retry_task(self, task_id: str) -> Retry:
+        """Prepare the typed retry command used by the palette and dispatcher."""
+        return Retry(task_id=task_id)
+
+    async def set_rung(self, task_id: str, role: Role, rung: Rung) -> Ack:
+        """Queue a `SetRung` command."""
+        return await self.send(self.prepare_set_rung(task_id, role, rung))
+
+    def prepare_set_rung(self, task_id: str, role: Role, rung: Rung) -> SetRung:
+        """Prepare the typed rung command used by the palette and dispatcher."""
+        return SetRung(task_id=task_id, role=role, rung=rung)
+
+    async def send_message(self, task_id: str, role: Role, text: str) -> Ack:
+        """Queue a `Say` command for the role's next turn."""
+        return await self.send(self.prepare_send_message(task_id, role, text))
+
+    def prepare_send_message(self, task_id: str, role: Role, text: str) -> Say:
+        """Prepare the typed guidance command used by the palette and dispatcher."""
+        return Say(task_id=task_id, role=role, text=text)
+
+    async def take_over(self, task_id: str, role: Role) -> Ack:
+        """Queue a `TakeOver` command for the role's pane."""
+        return await self.send(self.prepare_take_over(task_id, role))
+
+    def prepare_take_over(self, task_id: str, role: Role) -> TakeOver:
+        """Prepare the typed takeover command used by the palette and dispatcher."""
+        return TakeOver(task_id=task_id, role=role)
+
+    async def hand_back(self, task_id: str, role: Role) -> Ack:
+        """Queue a `HandBack` command returning the role's session to the engine."""
+        return await self.send(self.prepare_hand_back(task_id, role))
+
+    def prepare_hand_back(self, task_id: str, role: Role) -> HandBack:
+        """Prepare the typed hand-back command used by the palette and dispatcher."""
+        return HandBack(task_id=task_id, role=role)
+
+    async def resolve_escalation(self, escalation_id: str, resolution: Resolution) -> Ack:
+        """Queue a `Resolve` command for one open escalation."""
+        return await self.send(self.prepare_resolve_escalation(escalation_id, resolution))
+
+    def prepare_resolve_escalation(
+        self,
+        escalation_id: str,
+        resolution: Resolution,
+    ) -> Resolve:
+        """Prepare the typed resolution command used by the palette and dispatcher."""
+        return Resolve(escalation_id=escalation_id, resolution=resolution)
+
+    def prepare_palette_resolution(
+        self,
+        escalation_id: str,
+        kind: ResolutionKind,
+        *,
+        answer: str,
+        retry_rung: Rung | None,
+    ) -> Resolve:
+        """Prepare one resolution command from the palette's selected form fields."""
+        if kind is ResolutionKind.ANSWER:
+            resolution: Resolution = AnswerResolution(text=answer)
+        elif kind is ResolutionKind.RETRY:
+            resolution = RetryResolution(rung=retry_rung)
+        elif kind is ResolutionKind.ACCEPT:
+            resolution = AcceptResolution()
+        else:
+            resolution = CancelResolution()
+        return self.prepare_resolve_escalation(escalation_id, resolution)
+
+    async def stop_engine(self) -> Ack:
+        """Queue the orderly engine `Stop` command."""
+        return await self.send(self.prepare_stop_engine())
+
+    def prepare_stop_engine(self) -> Stop:
+        """Prepare the typed stop command used by the palette and dispatcher."""
+        return Stop()
+
+
+def _queued_ack(command_id: int, command: Command, message: str) -> Ack:
+    result = {"task_id": command.task_id} if isinstance(command, Submit) else None
+    return Ack.from_command(
+        command,
+        command_id=command_id,
+        status=AckStatus.QUEUED,
+        result=result,
+        message=message,
+    )
+
+
+def _result_message(result: dict[str, Any] | None) -> str | None:
+    if result is None:
+        return None
+    error = result.get("error")
+    return str(error) if error is not None else None

shikiru/operator/detectors.py

@@ -0,0 +1,374 @@
+"""Project detection and config rendering shared by non-interactive init and the wizard."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from shikiru.agents.contracts import ModelCatalog, Rung, short_rung_text
+from shikiru.config.loader import validate_project_config_text
+from shikiru.errors import ConfigError, ProjectNotRepositoryRootError, RepositoryHasNoCommitsError
+from shikiru.operator.toml_text import toml_key, toml_value
+from shikiru.paths import EXCLUDE_LINE, SHIKIRU_DIR_NAME, project_config_path
+from shikiru.private import create_private_text, make_private_dir
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+    from typing import Any
+
+    from shikiru.agents.settings import AgentSettings
+    from shikiru.config.settings import ComplexityName
+    from shikiru.operator.doctor import DoctorReport
+    from shikiru.operator.plugin_checks import (
+        AgentCapabilityResult,
+        OptionsRejection,
+        PluginChecks,
+    )
+    from shikiru.workspace.caches import CacheCloner
+    from shikiru.workspace.git import Git, LineChangeStats
+
+MAX_SCAN_DEPTH = 4
+TRACKER_DIRECTORY = "tasks"
+TRACKER_NAMES = ("plan", "todo")
+MARKDOWN_SUFFIX = ".md"
+CACHE_NAMES = (
+    ".venv",
+    "node_modules",
+    "target",
+    ".gradle",
+    ".pytest_cache",
+)
+DEFAULT_MODEL = "default"
+LEADER_ROLE = "leader"
+IMPLEMENTER_ROLE = "implementer"
+HELPER_ROLE = "helper"
+ROLE_NAMES = (LEADER_ROLE, IMPLEMENTER_ROLE, HELPER_ROLE)
+COMPLEXITY_NAMES: tuple[ComplexityName, ...] = ("low", "normal", "high")
+EXCLUDED_DIRECTORIES = frozenset({SHIKIRU_DIR_NAME, ".git"})
+
+
+def not_repository_root(root: Path) -> str:
+    """Explain why `root` cannot be a Shikiru project: it is not a git repository root."""
+    return (
+        f"{root} is not a git repository root; Shikiru supports one repository per project, "
+        "so run it from the repository's top-level directory"
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class DetectedProject:
+    """All filesystem and plugin facts used to write a default project config."""
+
+    name: str
+    base: str
+    worktree_clean: bool
+    caches: tuple[str, ...]
+    trackers: tuple[str, ...]
+    agents: tuple[str, ...]
+    agent_settings: tuple[AgentSettings, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class InitWizardResult:
+    """The config path and final Doctor result returned when the wizard is complete."""
+
+    config_path: Path
+    doctor_report: DoctorReport | None
+    doctor_error: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class OrchestrationChoices:
+    """The orchestration values the wizard writes to the project config."""
+
+    max_parallel: int
+    max_iterations: int
+    integration: str
+    pr_feedback: str
+    push_interval_seconds: int
+    max_quota_wait: int
+    stall: int
+    tool: int
+    max_cpu_pct: int
+    min_free_ram_gb: float
+
+
+class ProjectDetectors:
+    """Detect the repository base, trackers, installed agents and caches for `init`."""
+
+    def __init__(
+        self,
+        root: Path,
+        *,
+        git: Git,
+        plugin_checks: PluginChecks,
+        cache_cloner: CacheCloner,
+    ) -> None:
+        """Inspect `root` through injected git and agent-plugin check boundaries."""
+        self._root = root.resolve()
+        self._git = git
+        self._plugin_checks = plugin_checks
+        self._cache_cloner = cache_cloner
+
+    async def detect(self) -> DetectedProject:
+        """Return deterministic project facts, or an actionable config error."""
+        await self._validate_root()
+        return await self._detect_project()
+
+    async def _detect_project(self) -> DetectedProject:
+        agents = await self._agents()
+        if not agents:
+            message = "no shikiru.agents plugin is installed"
+            raise ConfigError(message)
+        base = await self._git.current_branch(self._root)
+        worktree_clean = not await self._git.status_porcelain(self._root)
+        return DetectedProject(
+            name=self._root.name,
+            base=base,
+            worktree_clean=worktree_clean,
+            caches=tuple(await self._caches()),
+            trackers=tuple(self._trackers()),
+            agents=agents,
+            agent_settings=tuple(self._plugin_checks.settings(name) for name in agents),
+        )
+
+    async def initialize(self) -> Path:
+        """Detect facts, write config and exclude `.shikiru/` in the repository."""
+        await self._validate_root()
+        config_path = project_config_path(self._root)
+        if await asyncio.to_thread(config_path.is_file):
+            return config_path
+        project = await self._detect_project()
+        await self._write_and_exclude(config_path, render_config(project))
+        return config_path
+
+    async def initialize_config(
+        self,
+        *,
+        trackers: Sequence[str],
+        caches: Sequence[str],
+        ladders: Mapping[str, Sequence[Rung]],
+        complexity: Mapping[ComplexityName, Sequence[Rung]] | None = None,
+        orchestration: OrchestrationChoices,
+        agent_options: Mapping[str, Mapping[str, object]] | None = None,
+    ) -> Path:
+        """Write the wizard's validated configuration and exclude `.shikiru/`."""
+        await self._validate_root()
+        project = await self._detect_project()
+        config_path = project_config_path(self._root)
+        contents = render_config(
+            project,
+            trackers=trackers,
+            caches=caches,
+            ladders=ladders,
+            complexity=complexity,
+            orchestration=orchestration,
+            agent_options=agent_options,
+        )
+        validate_project_config_text(contents)
+        await self._write_and_exclude(config_path, contents)
+        return config_path
+
+    async def check_cow_support(self) -> bool:
+        """Probe copy-on-write support using disposable files on the project filesystem."""
+        return await self._cache_cloner.check_support(self._root)
+
+    async def working_tree_line_changes(self) -> LineChangeStats:
+        """Return tracked and untracked working-tree change totals for the project repository."""
+        return await self._git.working_tree_line_changes(self._root)
+
+    async def model_catalog(self, name: str, options: Mapping[str, Any]) -> ModelCatalog | None:
+        """Return an agent's optional authoritative choices through the injected plugin boundary."""
+        return await self._plugin_checks.model_catalog(name, options)
+
+    def agent_options_rejection(
+        self, name: str, options: Mapping[str, Any]
+    ) -> OptionsRejection | None:
+        """Return the plugin's rejection of `options` for `name`, or `None` when accepted."""
+        return self._plugin_checks.options_rejection(name, options)
+
+    def agent_capabilities(self, name: str, options: Mapping[str, Any]) -> AgentCapabilityResult:
+        """Return generic optional capabilities through the injected plugin boundary."""
+        return self._plugin_checks.capabilities(name, options)
+
+    async def _validate_root(self) -> None:
+        repository_root = await self._git.repository_root(self._root)
+        if repository_root != self._root:
+            raise ProjectNotRepositoryRootError(
+                not_repository_root(self._root),
+                project_root=self._root,
+                repository_root=repository_root,
+            )
+        if not await self._git.has_commit(self._root):
+            message = (
+                f"{self._root} is a git repository without commits; create an initial commit, "
+                "then run shikiru init"
+            )
+            raise RepositoryHasNoCommitsError(message, project_root=self._root)
+
+    async def _write_and_exclude(self, config_path: Path, contents: str) -> None:
+        try:
+            await asyncio.to_thread(_write_config, config_path, contents)
+        except FileExistsError as error:
+            message = f"{config_path} already exists; refusing to overwrite it"
+            raise ConfigError(message) from error
+        await self._git.append_to_exclude(self._root, EXCLUDE_LINE)
+
+    def _trackers(self) -> list[str]:
+        candidates: set[str] = set()
+        for path in _files_at_depth(self._root, MAX_SCAN_DEPTH):
+            relative = path.relative_to(self._root).as_posix()
+            name = path.stem.lower()
+            if (
+                path.parent.name == TRACKER_DIRECTORY
+                or name.startswith(TRACKER_NAMES)
+                or name.endswith(TRACKER_NAMES)
+            ) and path.suffix.lower() == MARKDOWN_SUFFIX:
+                candidates.add(relative)
+        return sorted(candidates)
+
+    async def _caches(self) -> list[str]:
+        ignored = await self._git.ignored_paths(self._root)
+        return sorted(
+            path.relative_to(self._root).as_posix() for path in ignored if path.name in CACHE_NAMES
+        )
+
+    async def _agents(self) -> tuple[str, ...]:
+        results = [
+            await self._plugin_checks.check(name, {}) for name in self._plugin_checks.names()
+        ]
+        names = tuple(result.name for result in results if result.ok)
+        if names:
+            return names
+        if not results:
+            message = "no shikiru.agents plugin is installed"
+        else:
+            details = "; ".join(f"{result.name}: {result.detail}" for result in results)
+            message = f"no installed agent plugin passed doctor(): {details}"
+        raise ConfigError(message)
+
+
+def render_config(
+    project: DetectedProject,
+    *,
+    trackers: Sequence[str] | None = None,
+    caches: Sequence[str] | None = None,
+    ladders: Mapping[str, Sequence[Rung]] | None = None,
+    complexity: Mapping[ComplexityName, Sequence[Rung]] | None = None,
+    orchestration: OrchestrationChoices | None = None,
+    agent_options: Mapping[str, Mapping[str, object]] | None = None,
+) -> str:
+    """Render a complete default config from detected project facts."""
+    agent = project.agents[0]
+    lines = [
+        "[project]",
+        f"name = {json.dumps(project.name)}",
+        f"trackers = {json.dumps(list(project.trackers if trackers is None else trackers))}",
+        "",
+    ]
+    lines.extend(
+        (
+            "[repo]",
+            f"base = {json.dumps(project.base)}",
+            f"caches = {json.dumps(list(project.caches if caches is None else caches))}",
+            "",
+        )
+    )
+    for name in project.agents:
+        lines.append(f"[agents.{toml_key(name)}]")
+        options = (agent_options or {}).get(name, {})
+        if options:
+            lines.append("")
+            lines.append(f"[agents.{toml_key(name)}.options]")
+            lines.extend(f"{toml_key(key)} = {toml_value(value)}" for key, value in options.items())
+        lines.append("")
+    selected_ladders = (
+        ladders
+        if ladders is not None
+        else {role: (Rung(agent=agent, model=DEFAULT_MODEL),) for role in ROLE_NAMES}
+    )
+    for role in ROLE_NAMES:
+        lines.append(f"[roles.{role}]")
+        lines.append(f"ladder = {_render_ladder(selected_ladders[role])}")
+        lines.append("")
+    for name in COMPLEXITY_NAMES:
+        rungs = complexity.get(name) if complexity is not None else None
+        if rungs is not None:
+            lines.append(f"[roles.{IMPLEMENTER_ROLE}.complexity.{name}]")
+            lines.append(f"ladder = {_render_ladder(rungs)}")
+            lines.append("")
+    if orchestration is not None:
+        lines.extend(
+            (
+                "[orchestration]",
+                f"max_parallel = {orchestration.max_parallel}",
+                f"max_iterations = {orchestration.max_iterations}",
+                f"integration = {json.dumps(orchestration.integration)}",
+                f"pr_feedback = {json.dumps(orchestration.pr_feedback)}",
+                f"push_interval_seconds = {orchestration.push_interval_seconds}",
+                "",
+                "[orchestration.timeouts]",
+                f"stall = {orchestration.stall}",
+                f"tool = {orchestration.tool}",
+                f"max_quota_wait = {orchestration.max_quota_wait}",
+                "",
+                "[orchestration.resources]",
+                f"max_cpu_pct = {orchestration.max_cpu_pct}",
+                f"min_free_ram_gb = {orchestration.min_free_ram_gb}",
+                "",
+            )
+        )
+    return "\n".join(lines)
+
+
+def _render_ladder(rungs: Sequence[Rung]) -> str:
+    rung_texts = [_render_rung(rung) for rung in rungs]
+    return f"[{', '.join(rung_texts)}]"
+
+
+def _render_rung(rung: Rung) -> str:
+    short = short_rung_text(rung)
+    if short is not None:
+        return json.dumps(short)
+    return (
+        "{ "
+        + ", ".join(
+            value
+            for value in (
+                f"agent = {json.dumps(rung.agent)}",
+                f"model = {json.dumps(rung.model)}",
+                None if rung.effort is None else f"effort = {json.dumps(rung.effort)}",
+            )
+            if value is not None
+        )
+        + " }"
+    )
+
+
+def _write_config(config_path: Path, contents: str) -> None:
+    make_private_dir(config_path.parent)
+    create_private_text(config_path, contents)
+
+
+def _files_at_depth(root: Path, max_depth: int) -> list[Path]:
+    files: list[Path] = []
+    pending: list[tuple[Path, int]] = [(root, 0)]
+    while pending:
+        directory, depth = pending.pop()
+        with os.scandir(directory) as entries:
+            for entry in sorted(entries, key=lambda item: item.name):
+                if entry.name in EXCLUDED_DIRECTORIES:
+                    continue
+                entry_depth = depth + 1
+                if entry_depth > max_depth:
+                    continue
+                path = Path(entry.path)
+                if entry.is_dir(follow_symlinks=False):
+                    pending.append((path, entry_depth))
+                elif entry.is_file(follow_symlinks=False):
+                    files.append(path)
+    return files