comate-cli 0.7.8__tar.gz → 0.8.0__tar.gz

{comate_cli-0.7.8 → comate_cli-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: comate-cli
-Version: 0.7.8
+Version: 0.8.0
 Summary: Comate terminal CLI built on comate-agent-sdk
 Project-URL: Homepage, https://github.com/AndyLee1024/agent-sdk
 Project-URL: Repository, https://github.com/AndyLee1024/agent-sdk

{comate_cli-0.7.8 → comate_cli-0.8.0}/comate_cli/main.py

@@ -26,6 +26,15 @@ class _ArgumentError(ValueError):
     """Raised when CLI arguments are invalid."""
 
 
+PRINT_STDIN_IDLE_TIMEOUT_SECONDS = 3.0
+PRINT_OUTPUT_FORMAT_TEXT = "text"
+PRINT_OUTPUT_FORMAT_JSON = "json"
+PRINT_OUTPUT_FORMATS = frozenset({PRINT_OUTPUT_FORMAT_TEXT, PRINT_OUTPUT_FORMAT_JSON})
+PRINT_OUTPUT_FORMAT_UNSUPPORTED = frozenset({"stream-json"})
+
+ParsedArgs = tuple[bool, str | None, bool, str | None, str]
+
+
 class _TerminalStateGuard:
     """Best-effort tty restore guard for abnormal shutdown paths."""
 
@@ -200,37 +209,68 @@ def _usage_text() -> str:
     return (
         "Usage:\n"
         "  comate [--rpc-stdio]\n"
-        "  comate -p <prompt>\n"
+        "  comate -p [--output-format text|json] <prompt>\n"
         "  comate resume [<session_id>] [--rpc-stdio]\n"
         "  comate mcp <subcommand> [options]"
     )
 
 
-def _parse_args(argv: list[str]) -> tuple[bool, str | None, bool, str | None]:
+def _parse_args(argv: list[str]) -> ParsedArgs:
     rpc_stdio = False
     print_mode = False
+    output_format = PRINT_OUTPUT_FORMAT_TEXT
+    output_format_explicit = False
     positionals: list[str] = []
-    for arg in argv:
+
+    index = 0
+    while index < len(argv):
+        arg = argv[index]
         if arg == "--rpc-stdio":
             rpc_stdio = True
+            index += 1
             continue
         if arg in ("-p", "--print"):
             print_mode = True
+            index += 1
+            continue
+        if arg == "--output-format" or arg.startswith("--output-format="):
+            output_format_explicit = True
+            if arg == "--output-format":
+                index += 1
+                if index >= len(argv):
+                    raise _ArgumentError("--output-format requires one of: text, json")
+                value = argv[index]
+            else:
+                value = arg.partition("=")[2]
+                if not value:
+                    raise _ArgumentError("--output-format requires one of: text, json")
+            if value in PRINT_OUTPUT_FORMAT_UNSUPPORTED:
+                raise _ArgumentError(
+                    "--output-format stream-json is not supported in this release"
+                )
+            if value not in PRINT_OUTPUT_FORMATS:
+                raise _ArgumentError(f"Unsupported --output-format: {value}")
+            output_format = value
+            index += 1
             continue
         if arg.startswith("-"):
             raise _ArgumentError(f"Unknown option: {arg}")
         positionals.append(arg)
+        index += 1
+
+    if output_format_explicit and not print_mode:
+        raise _ArgumentError("--output-format can only be used with -p/--print")
 
     # -p mode: all positionals become the prompt
     if print_mode:
         if rpc_stdio:
             raise _ArgumentError("-p/--print and --rpc-stdio are mutually exclusive")
         print_prompt = " ".join(positionals) if positionals else ""
-        return rpc_stdio, None, False, print_prompt
+        return rpc_stdio, None, False, print_prompt, output_format
 
     # Non -p mode: original logic
     if not positionals:
-        return rpc_stdio, None, False, None
+        return rpc_stdio, None, False, None, output_format
 
     command = positionals[0]
     if command != "resume":
@@ -241,14 +281,75 @@ def _parse_args(argv: list[str]) -> tuple[bool, str | None, bool, str | None]:
             raise _ArgumentError(
                 "resume without <session_id> does not support --rpc-stdio"
             )
-        return rpc_stdio, None, True, None
+        return rpc_stdio, None, True, None, output_format
 
     if len(positionals) == 2:
-        return rpc_stdio, positionals[1], False, None
+        return rpc_stdio, positionals[1], False, None, output_format
 
     raise _ArgumentError("resume accepts at most one <session_id>")
 
 
+def _read_stdin_posix_idle_drain(
+    stdin: object,
+    *,
+    timeout_seconds: float,
+    chunk_size: int = 64 * 1024,
+) -> str:
+    import select
+
+    fileno = getattr(stdin, "fileno", None)
+    if not callable(fileno):
+        read = getattr(stdin, "read", None)
+        return str(read()) if callable(read) else ""
+
+    try:
+        fd = fileno()
+    except (AttributeError, OSError, ValueError):
+        read = getattr(stdin, "read", None)
+        return str(read()) if callable(read) else ""
+
+    chunks: list[bytes] = []
+    while True:
+        readable, _, _ = select.select([fd], [], [], timeout_seconds)
+        if not readable:
+            break
+        try:
+            chunk = os.read(fd, chunk_size)
+        except BlockingIOError:
+            break
+        except OSError:
+            break
+        if not chunk:
+            break
+        chunks.append(chunk)
+
+    encoding = str(getattr(stdin, "encoding", "") or "utf-8")
+    return b"".join(chunks).decode(encoding, errors="replace")
+
+
+def _read_stdin_if_ready(
+    stdin: object,
+    *,
+    timeout_seconds: float = PRINT_STDIN_IDLE_TIMEOUT_SECONDS,
+) -> str:
+    isatty = getattr(stdin, "isatty", None)
+    if callable(isatty) and isatty():
+        return ""
+
+    if os.name != "posix":
+        read = getattr(stdin, "read", None)
+        return str(read()) if callable(read) else ""
+
+    try:
+        return _read_stdin_posix_idle_drain(
+            stdin,
+            timeout_seconds=timeout_seconds,
+        )
+    except (OSError, ValueError):
+        read = getattr(stdin, "read", None)
+        return str(read()) if callable(read) else ""
+
+
 def main(argv: list[str] | None = None) -> None:
     run_argv = list(argv) if argv is not None else sys.argv[1:]
 
@@ -278,7 +379,9 @@ def main(argv: list[str] | None = None) -> None:
     _app_import_done_perf = time.perf_counter()
 
     try:
-        rpc_stdio, resume_session_id, resume_select, print_prompt = _parse_args(run_argv)
+        rpc_stdio, resume_session_id, resume_select, print_prompt, print_output_format = (
+            _parse_args(run_argv)
+        )
     except _ArgumentError as exc:
         sys.stderr.write(f"{exc}\n{_usage_text()}\n")
         raise SystemExit(2) from exc
@@ -286,9 +389,7 @@ def main(argv: list[str] | None = None) -> None:
     # Assemble print mode message
     print_message: str | None = None
     if print_prompt is not None:
-        stdin_text = ""
-        if not sys.stdin.isatty():
-            stdin_text = sys.stdin.read()
+        stdin_text = _read_stdin_if_ready(sys.stdin)
         parts = [p for p in (stdin_text.strip(), print_prompt.strip()) if p]
         if not parts:
             sys.stderr.write("Error: -p requires a prompt argument or stdin input\n")
@@ -302,6 +403,7 @@ def main(argv: list[str] | None = None) -> None:
                 resume_session_id=resume_session_id,
                 resume_select=resume_select,
                 print_message=print_message,
+                print_output_format=print_output_format,
                 process_start_perf=_PROCESS_START_PERF,
                 app_import_start_perf=_app_import_start_perf,
                 app_import_done_perf=_app_import_done_perf,

{comate_cli-0.7.8 → comate_cli-0.8.0}/comate_cli/terminal_agent/animations.py

@@ -254,7 +254,8 @@ LOADING_SPINNER_FRAMES: tuple[str, ...] = (
 HIDDEN_THINKING_BADGES: tuple[str, ...] = (
     "ultra thinking",
     "deep thinking",
-    "extended thinking"
+    "extended thinking",
+    "thinking some more with max effort"
 )
 
 
@@ -395,6 +396,24 @@ class SubmissionAnimator:
             self._is_active = False
             self._dirty = True
 
+    def hide_now(self) -> None:
+        task = self._task
+        if task is not None and not task.done():
+            task.cancel()
+
+            def _consume_cancelled(done_task: asyncio.Task[None]) -> None:
+                try:
+                    done_task.result()
+                except asyncio.CancelledError:
+                    return
+
+            task.add_done_callback(_consume_cancelled)
+        self._task = None
+        self._stop_event = None
+        self._status_hint = None
+        self._is_active = False
+        self._dirty = True
+
     @property
     def is_active(self) -> bool:
         return self._is_active
@@ -474,6 +493,13 @@ class StreamAnimationController:
     async def shutdown(self) -> None:
         await self._stop_if_needed(AnimationPhase.DONE)
 
+    def hide_now(self) -> None:
+        self._active_tool_call_ids.clear()
+        self._animator.set_status_hint(None)
+        self._animator.hide_now()
+        self._stopped = True
+        self._phase = AnimationPhase.DONE
+
     async def on_event(self, event: object) -> None:
         if self._stopped:
             return

{comate_cli-0.7.8 → comate_cli-0.8.0}/comate_cli/terminal_agent/app.py

@@ -5,7 +5,6 @@ import logging
 import os
 import random  # noqa: F401 - tests patch this module-level import for deterministic startup tips.
 import signal
-import sys
 import threading
 import time
 from collections.abc import Iterator
@@ -20,13 +19,30 @@ from comate_cli.terminal_agent.startup_profile import StartupProfiler
 if TYPE_CHECKING:
     from comate_agent_sdk.agent.chat_session import ChatSession
     from comate_agent_sdk.agent.core.template import AgentTemplate as Agent
-    from comate_agent_sdk.agent.events import TextEvent
     from comate_cli.terminal_agent.event_renderer import EventRenderer
     from comate_cli.terminal_agent.update_check import UpdateInfo
 
 console = Console()
 logger = logging.getLogger(__name__)
 _UPDATE_CHECK_DELAY_S = 1.0
+PRINT_MODE_DISALLOWED_TOOLS = (
+    "TeamCreate",
+    "TeamDelete",
+    "SendMessage",
+    "YieldTurn",
+)
+
+
+def _merge_disallowed_tools(*groups: tuple[str, ...] | None) -> tuple[str, ...] | None:
+    merged: list[str] = []
+    seen: set[str] = set()
+    for group in groups:
+        for name in group or ():
+            if name in seen:
+                continue
+            seen.add(name)
+            merged.append(name)
+    return tuple(merged) or None
 
 
 def _resolve_cli_project_root() -> Path:
@@ -221,6 +237,18 @@ def _import_preflight_runner():
     return run_preflight_if_needed
 
 
+def _import_print_mode_runner():
+    from comate_cli.terminal_agent.print_mode import run_print_mode
+
+    return run_print_mode
+
+
+def _import_print_mode_json_error_writer():
+    from comate_cli.terminal_agent.print_mode import write_json_error_result
+
+    return write_json_error_result
+
+
 def print_logo(*args, **kwargs) -> None:
     from comate_cli.terminal_agent.logo import print_logo as _print_logo
 
@@ -357,6 +385,7 @@ def _build_agent(
     *,
     project_root: Path | None = None,
     profiler: StartupProfiler | None = None,
+    extra_disallowed_tools: tuple[str, ...] | None = None,
 ) -> Agent:
     Agent, AgentConfig, CompactionConfig, EnvOptions = _import_sdk_agent_components(profiler)
     from comate_cli.terminal_agent.config import store
@@ -367,6 +396,7 @@ def _build_agent(
     snapshot = store.load()
     if profiler is not None:
         profiler.mark("agent.config.load.done")
+    disallowed_tools = _merge_disallowed_tools(extra_disallowed_tools)
 
     agent_config = AgentConfig(
         role="software_engineering",
@@ -374,11 +404,13 @@ def _build_agent(
         env_options=EnvOptions(system_env=True, git_env=True),
         use_streaming_task=True,
         include_cost=bool(getattr(snapshot, "token_cost_enabled", False)),
+        strict_hook_settings=False,
         memory_background_enabled=snapshot.memory_background_enabled,
         memory_dreaming_enabled=snapshot.memory_dreaming_enabled,
         compaction=CompactionConfig(
             threshold_ratio=snapshot.compaction_threshold_ratio,
         ),
+        disallowed_tools=disallowed_tools,
     )
     if profiler is not None:
         profiler.mark("agent.construct.start")
@@ -425,11 +457,10 @@ def _format_exit_usage_line(usage: object) -> str:
     input_tokens = max(total_prompt_tokens - total_prompt_cached_tokens, 0)
     total_tokens = input_tokens + total_completion_tokens
 
-    reasoning_part = f" (reasoning {total_reasoning_tokens:,})" if total_reasoning_tokens > 0 else ""
     return (
         f"Token usage: total={total_tokens:,} "
         f"input={input_tokens:,} (+ {total_prompt_cached_tokens:,} cached) "
-        f"output={total_completion_tokens:,}{reasoning_part}"
+        f"output={total_completion_tokens:,} (reasoning {total_reasoning_tokens:,})"
     )
 
 
@@ -502,28 +533,17 @@ async def _run_print_mode(
     message: str,
     *,
     project_root: Path,
+    output_format: str = "text",
 ) -> None:
-    ChatSession, TextEvent = _import_print_mode_components()
-    session = ChatSession(agent, cwd=project_root, persistent=False)
-    try:
-        await _preload_mcp_in_tui(session)
-
-        final_text = ""
-        async for event in session.query_stream(message):
-            if isinstance(event, TextEvent):
-                final_text = event.content
-
-        if final_text:
-            sys.stdout.write(final_text)
-            if not final_text.endswith("\n"):
-                sys.stdout.write("\n")
-            sys.stdout.flush()
-    except Exception as exc:
-        logger.error(f"Print mode failed: {exc}", exc_info=True)
-        sys.stderr.write(f"Error: {exc}\n")
-        raise SystemExit(1) from exc
-    finally:
-        await _graceful_shutdown(session)
+    run_print_mode = _import_print_mode_runner()
+    await run_print_mode(
+        agent,
+        message,
+        project_root=project_root,
+        output_format=output_format,
+        preload_mcp=_preload_mcp_in_tui,
+        graceful_shutdown=_graceful_shutdown,
+    )
 
 
 def _install_event_loop_exception_handler() -> None:
@@ -557,6 +577,7 @@ async def run(
     resume_session_id: str | None = None,
     resume_select: bool = False,
     print_message: str | None = None,
+    print_output_format: str = "text",
     process_start_perf: float | None = None,
     app_import_start_perf: float | None = None,
     app_import_done_perf: float | None = None,
@@ -576,14 +597,25 @@ async def run(
     profiler.mark("cli_project_root.done")
     profiler.mark("preflight.start")
     run_preflight_if_needed = _import_preflight_runner()
+    preflight_console = console
+    if print_message is not None and print_output_format == "json":
+        preflight_console = Console(stderr=True)
     preflight_result = await run_preflight_if_needed(
-        console=console,
+        console=preflight_console,
         project_root=project_root,
         interactive=not rpc_stdio and print_message is None,
     )
     profiler.mark("preflight.done")
     if preflight_result.should_abort_launch:
         if print_message is not None:
+            if print_output_format == "json":
+                write_json_error_result = _import_print_mode_json_error_writer()
+                detail = preflight_result.detail or preflight_result.status
+                write_json_error_result(
+                    error=f"Preflight failed: {detail}",
+                    stop_reason=None,
+                    session_id=None,
+                )
             raise SystemExit(1)
         return
 
@@ -604,7 +636,13 @@ async def run(
                 return
 
     profiler.mark("agent.build.start")
-    agent = _build_agent(project_root=project_root, profiler=profiler)
+    agent = _build_agent(
+        project_root=project_root,
+        profiler=profiler,
+        extra_disallowed_tools=(
+            PRINT_MODE_DISALLOWED_TOOLS if print_message is not None else None
+        ),
+    )
     profiler.mark("agent.build.done")
 
     if rpc_stdio and resume_select and not resume_session_id:
@@ -628,7 +666,12 @@ async def run(
 
     # --- Print mode branch ---
     if print_message is not None:
-        await _run_print_mode(agent, print_message, project_root=project_root)
+        await _run_print_mode(
+            agent,
+            print_message,
+            project_root=project_root,
+            output_format=print_output_format,
+        )
         return
 
     if resume_select and not resume_session_id:
@@ -718,6 +761,17 @@ async def run(
             )
     finally:
         try:
+            tui_exit_source = (
+                getattr(tui, "exit_source", None)
+                or getattr(tui, "_exit_source", None)
+                or "unknown"
+            )
+            logger.info(
+                "TUI branch leaving: exit_source=%s session_id=%s active_session_id=%s",
+                tui_exit_source,
+                getattr(session, "session_id", None),
+                getattr(active_session, "session_id", None),
+            )
             if update_check_task is not None:
                 await _cancel_background_task(
                     update_check_task,

{comate_cli-0.7.8 → comate_cli-0.8.0}/comate_cli/terminal_agent/event_renderer.py

@@ -14,6 +14,11 @@ from comate_agent_sdk.agent.events import (
     CompactionResultEvent,
     CompactionStartedEvent,
     PlanApprovalRequiredEvent,
+    ScheduledPromptCreatedEvent,
+    ScheduledPromptDeletedEvent,
+    ScheduledPromptFailedEvent,
+    ScheduledPromptFiredEvent,
+    ScheduledPromptMissedEvent,
     SessionInitEvent,
     StepCompleteEvent,
     StopEvent,
@@ -67,14 +72,13 @@ from comate_cli.terminal_agent.tool_fold import (
     is_foldable_tool,
 )
 from comate_cli.terminal_agent.env_utils import read_env_int
-from comate_cli.terminal_agent.custom_slash_commands import FILE_REF_PATTERN
+from comate_cli.terminal_agent.file_ref_hint import build_file_ref_hints
 logger = logging.getLogger(__name__)
 
 _DEFAULT_TOOL_ERROR_SUMMARY_MAX_LEN = 160
 _DEFAULT_TOOL_PANEL_MAX_LINES = 4
 _DEFAULT_TASK_PANEL_MAX_LINES = 6
 _RECENT_TEAM_EVENT_CACHE_SIZE = 128
-_FILE_REF_MAX_COUNT_BYTES = 10 * 1024 * 1024  # 10 MB
 _SYSTEM_MESSAGE_DEDUPE_WINDOW_SECONDS = 0.5
 
 
@@ -84,6 +88,25 @@ def _truncate(content: str, max_len: int = 120) -> str:
     return f"{content[:max_len]}..."
 
 
+def _scheduled_scope(durable: bool) -> str:
+    return "durable" if durable else "session-only"
+
+
+def _scheduled_failure_reason(reason: str) -> str:
+    text = " ".join(str(reason or "").split())
+    if not text:
+        return "unknown"
+    lowered = text.lower()
+    if "prompt" in lowered and not re.fullmatch(r"[A-Za-z0-9_.:/-]+", text):
+        colon = text.find(":")
+        if colon > 0:
+            text = text[:colon].strip()
+        else:
+            prompt_at = lowered.find("prompt")
+            text = text[:prompt_at].rstrip(": -") or "hidden"
+    return _truncate(text, 160)
+
+
 def _format_duration(seconds: float) -> str:
     elapsed = max(seconds, 0.0)
     if elapsed < 60:
@@ -697,32 +720,14 @@ class EventRenderer:
             self._maybe_append_file_ref_hint(normalized)
         self.flush_pending_logs()
 
+    def compute_file_ref_hints(self, text: str) -> list[str]:
+        """计算 text 中 @path 引用的展示提示行（scrollback 与 staging 共用单一事实源）。"""
+        return build_file_ref_hints(text, self._project_root)
+
     def _maybe_append_file_ref_hint(self, text: str) -> None:
         """Append dim ⎿ hints for valid @path references."""
-        if self._project_root is None:
-            return
-        for match in FILE_REF_PATTERN.finditer(text):
-            raw_path = match.group(1)
-            candidate = self._project_root / raw_path
-            try:
-                if candidate.is_dir():
-                    self._append_history_entry(
-                        HistoryEntry(entry_type="file_ref", text=f"Listed directory {raw_path}")
-                    )
-                    continue
-                if candidate.is_file():
-                    hint = f"Read {raw_path}"
-                    if candidate.stat().st_size <= _FILE_REF_MAX_COUNT_BYTES:
-                        try:
-                            with open(candidate, "rb") as fh:
-                                line_count = sum(1 for _ in fh)
-                            hint += f"  ({line_count} lines)"
-                        except OSError:
-                            pass
-                    self._append_history_entry(HistoryEntry(entry_type="file_ref", text=hint))
-                    continue
-            except OSError:
-                continue
+        for hint in self.compute_file_ref_hints(text):
+            self._append_history_entry(HistoryEntry(entry_type="file_ref", text=hint))
 
     def close(self) -> None:
         return
@@ -1540,6 +1545,52 @@ class EventRenderer:
                     output=output,
                     args=stored_args,
                 )
+            case ScheduledPromptCreatedEvent(
+                job_id=job_id,
+                cron=_,
+                human_schedule=human_schedule,
+                recurring=_,
+                durable=durable,
+            ):
+                self.append_system_message(
+                    (
+                        f"Scheduled task created: job={job_id} "
+                        f"schedule={human_schedule} scope={_scheduled_scope(durable)}"
+                    ),
+                    severity="info",
+                )
+            case ScheduledPromptDeletedEvent(job_id=job_id):
+                self.append_system_message(
+                    f"Scheduled task cancelled: job={job_id}",
+                    severity="info",
+                )
+            case ScheduledPromptFiredEvent(
+                job_id=_,
+                cron=_,
+                human_schedule=_,
+                recurring=_,
+                durable=_,
+                local_time=_,
+            ):
+                # Fired means the scheduler materialized pending work; the TUI uses it as a
+                # transient loading signal and should not persist every recurring tick.
+                pass
+            case ScheduledPromptMissedEvent(
+                job_id=job_id,
+                human_schedule=human_schedule,
+            ):
+                self.append_system_message(
+                    (
+                        "Missed scheduled task requires confirmation: "
+                        f"job={job_id} schedule={human_schedule}"
+                    ),
+                    severity="warning",
+                )
+            case ScheduledPromptFailedEvent(job_id=job_id, reason=reason):
+                self.append_system_message(
+                    f"Scheduled task failed: job={job_id} reason={_scheduled_failure_reason(reason)}",
+                    severity="error",
+                )
             case UsageDeltaEvent(
                 source=_,
                 model=_,

{comate_cli-0.7.8 → comate_cli-0.8.0}/comate_cli/terminal_agent/figures.py

@@ -95,7 +95,7 @@ TASK_PENDING = "▢"           # ▢
 TASK_BLOCKED = "▫"           # ▫
 
 # Mode 指示 & 中断
-FAST_PLAY_ICON = "⏵"         # ⏵ — Act mode（成对使用 ⏵⏵）
+FAST_PLAY_ICON = "⏵"         # ⏵ — YOLO mode（成对使用 ⏵⏵）
 STOP_ICON = "⏹"              # ⏹
 
 # 警告 & 省略

comate_cli-0.8.0/comate_cli/terminal_agent/file_ref_hint.py

@@ -0,0 +1,47 @@
+"""@路径引用的展示提示行计算。
+
+scrollback（event_renderer）与 staging 预览（render_panels）共用这一份逻辑，
+保证用户在 staging 区看到的 ``Read x (N lines)`` / ``Listed directory x`` 提示
+与刷入 scrollback 后逐字一致——这是「不让用户感知 staging 区存在」的关键。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from comate_cli.terminal_agent.custom_slash_commands import FILE_REF_PATTERN
+
+# 超过该体积的文件不再逐行统计，避免大文件计数拖慢渲染。
+_FILE_REF_MAX_COUNT_BYTES = 10 * 1024 * 1024  # 10 MB
+
+
+def build_file_ref_hints(text: str, project_root: Path | None) -> list[str]:
+    """扫描 ``text`` 中的 ``@path`` 引用，返回展示用提示行列表。
+
+    每条形如 ``Read <path>  (<N> lines)`` 或 ``Listed directory <path>``；
+    无效 / 不存在 / 不可访问的引用会被跳过。``project_root`` 为 ``None`` 时返回空列表。
+    """
+    if project_root is None:
+        return []
+    hints: list[str] = []
+    for match in FILE_REF_PATTERN.finditer(text):
+        raw_path = match.group(1)
+        candidate = project_root / raw_path
+        try:
+            if candidate.is_dir():
+                hints.append(f"Listed directory {raw_path}")
+                continue
+            if candidate.is_file():
+                hint = f"Read {raw_path}"
+                if candidate.stat().st_size <= _FILE_REF_MAX_COUNT_BYTES:
+                    try:
+                        with open(candidate, "rb") as fh:
+                            line_count = sum(1 for _ in fh)
+                        hint += f"  ({line_count} lines)"
+                    except OSError:
+                        pass
+                hints.append(hint)
+                continue
+        except OSError:
+            continue
+    return hints