aria-code 0.167.0__py3-none-win_amd64.whl

aria_code/apps/cli/earnings_view.py

@@ -0,0 +1,172 @@
+"""/earnings SYMBOL: the next report, the last four against estimates, and the quarterly numbers.
+
+/earnings handed off to /report, which wrote a general technical-analysis
+report: price, moving averages, RSI. Nothing about earnings. This shows
+what the command names, from yfinance: the next report date with the
+consensus range, reported EPS against the estimate for recent quarters, and
+revenue, net income and diluted EPS by quarter. `/earnings SYMBOL --report`
+still writes the Markdown report.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any, Optional
+
+
+def _num(value: Any) -> Optional[float]:
+    try:
+        number = float(value)
+    except (TypeError, ValueError):
+        return None
+    return None if math.isnan(number) or math.isinf(number) else number
+
+
+def fetch_earnings(symbol: str, ticker: Any = None) -> dict:
+    """Earnings data for ``symbol`` from yfinance (or the ``ticker`` object given)."""
+    import logging
+
+    # yfinance logs "HTTP Error 404 …" straight to the terminal for a symbol
+    # without earnings; the answer below says so in a sentence instead.
+    yf_log = logging.getLogger("yfinance")
+    previous = yf_log.level
+    yf_log.setLevel(logging.CRITICAL)
+    try:
+        return _fetch_earnings(symbol, ticker)
+    finally:
+        yf_log.setLevel(previous)
+
+
+def _fetch_earnings(symbol: str, ticker: Any = None) -> dict:
+    if ticker is None:
+        try:
+            import yfinance as yf
+        except ImportError:
+            return {"success": False, "error": "yfinance is not installed"}
+        ticker = yf.Ticker(symbol)
+    out: dict = {"success": True, "symbol": symbol.upper(), "history": [], "quarters": [], "next": {}}
+
+    try:
+        dates = ticker.earnings_dates
+    except Exception:
+        dates = None
+    if dates is not None and not getattr(dates, "empty", True):
+        for when, row in dates.sort_index(ascending=False).iterrows():
+            reported = _num(row.get("Reported EPS"))
+            estimate = _num(row.get("EPS Estimate"))
+            if reported is None:
+                continue
+            surprise = _num(row.get("Surprise(%)"))
+            if surprise is None and estimate:
+                surprise = (reported - estimate) / abs(estimate) * 100
+            out["history"].append({"date": str(when)[:10], "estimate": estimate, "reported": reported,
+                                   "surprise_pct": surprise})
+            if len(out["history"]) == 4:
+                break
+
+    try:
+        calendar = ticker.calendar or {}
+    except Exception:
+        calendar = {}
+    if isinstance(calendar, dict) and calendar:
+        upcoming = calendar.get("Earnings Date") or []
+        out["next"] = {
+            "date": str(upcoming[0]) if upcoming else None,
+            "eps_avg": _num(calendar.get("Earnings Average")),
+            "eps_low": _num(calendar.get("Earnings Low")),
+            "eps_high": _num(calendar.get("Earnings High")),
+            "revenue_avg": _num(calendar.get("Revenue Average")),
+        }
+
+    try:
+        income = ticker.quarterly_income_stmt
+    except Exception:
+        income = None
+    if income is not None and not getattr(income, "empty", True):
+        for column in list(income.columns)[:5]:
+            def field(name: str) -> Optional[float]:
+                return _num(income.at[name, column]) if name in income.index else None
+            revenue, net = field("Total Revenue"), field("Net Income")
+            out["quarters"].append({
+                "period": str(column)[:10], "revenue": revenue, "net_income": net,
+                "eps": field("Diluted EPS"),
+                "net_margin": net / revenue * 100 if revenue and net is not None else None,
+            })
+
+    if not (out["history"] or out["quarters"] or out["next"]):
+        return {"success": False, "symbol": symbol.upper(),
+                "error": f"No earnings data for {symbol.upper()} (ETFs, indices and some non-US listings have none)"}
+    return out
+
+
+def _money(value: Optional[float]) -> str:
+    if value is None:
+        return "—"
+    for size, unit in ((1e12, "T"), (1e9, "B"), (1e6, "M")):
+        if abs(value) >= size:
+            return f"{value / size:.2f}{unit}"
+    return f"{value:,.0f}"
+
+
+def render_earnings(data: dict, console, lang: str = "en") -> None:
+    from rich.padding import Padding
+    from rich.table import Table
+
+    zh = str(lang).lower().startswith("zh")
+    T = (lambda a, b: a) if zh else (lambda a, b: b)
+    symbol = data.get("symbol", "")
+    console.print()
+    console.print(f"  [bold]{symbol} {T('财报', 'earnings')}[/bold]  [dim]yfinance[/dim]")
+
+    nxt = data.get("next") or {}
+    if nxt.get("date"):
+        parts = [f"{T('下次财报', 'Next report')} {nxt['date']}"]
+        if nxt.get("eps_avg") is not None:
+            band = (f" ({nxt['eps_low']:.2f}–{nxt['eps_high']:.2f})"
+                    if nxt.get("eps_low") is not None and nxt.get("eps_high") is not None else "")
+            parts.append(f"{T('EPS 一致预期', 'EPS consensus')} {nxt['eps_avg']:.2f}{band}")
+        if nxt.get("revenue_avg"):
+            parts.append(f"{T('营收预期', 'revenue consensus')} {_money(nxt['revenue_avg'])}")
+        console.print("  [dim]" + " · ".join(parts) + "[/dim]")
+
+    history = data.get("history") or []
+    if history:
+        console.print()
+        table = Table(box=None, show_header=True, header_style="bold", padding=(0, 2))
+        table.add_column(T("公布日", "Reported"))
+        table.add_column(T("EPS 预期", "EPS est."), justify="right")
+        table.add_column(T("EPS 实际", "EPS actual"), justify="right")
+        table.add_column(T("超预期", "Surprise"), justify="right")
+        for row in history:
+            surprise = row.get("surprise_pct")
+            colour = "green" if (surprise or 0) > 0 else "red" if (surprise or 0) < 0 else "dim"
+            table.add_row(row["date"], f"{row['estimate']:.2f}" if row.get("estimate") is not None else "—",
+                          f"{row['reported']:.2f}",
+                          f"[{colour}]{surprise:+.1f}%[/{colour}]" if surprise is not None else "—")
+        console.print(Padding(table, (0, 0, 0, 2)))
+        beats = sum(1 for r in history if (r.get("surprise_pct") or 0) > 0)
+        console.print(f"  [dim]{T(f'近 {len(history)} 次中 {beats} 次超预期', f'Beat the estimate in {beats} of the last {len(history)}')}[/dim]")
+
+    quarters = data.get("quarters") or []
+    if quarters:
+        console.print()
+        table = Table(box=None, show_header=True, header_style="bold", padding=(0, 2))
+        table.add_column(T("季度末", "Quarter"))
+        table.add_column(T("营收", "Revenue"), justify="right")
+        table.add_column(T("净利润", "Net income"), justify="right")
+        table.add_column(T("净利率", "Net margin"), justify="right")
+        table.add_column(T("稀释 EPS (GAAP)", "Diluted EPS (GAAP)"), justify="right")
+        for q in quarters:
+            table.add_row(q["period"], _money(q.get("revenue")), _money(q.get("net_income")),
+                          f"{q['net_margin']:.1f}%" if q.get("net_margin") is not None else "—",
+                          f"{q['eps']:.2f}" if q.get("eps") is not None else "—")
+        console.print(Padding(table, (0, 0, 0, 2)))
+        console.print(f"  [dim]{T('上表 EPS 为公司公布的调整后口径，此处为 GAAP 稀释口径，两者可能不同', 'EPS above is as reported against estimates (adjusted); here it is GAAP diluted, which can differ')}[/dim]")
+        if len(quarters) == 5 and quarters[0].get("revenue") and quarters[4].get("revenue"):
+            yoy = quarters[0]["revenue"] / quarters[4]["revenue"] * 100 - 100
+            console.print(f"  [dim]{T('最近一季营收同比', 'Latest quarter revenue year on year')} {yoy:+.1f}%[/dim]")
+    console.print(f"  [dim]{T('完整报告：', 'Full report: ')}/earnings {symbol} --report[/dim]")
+    console.print()
+
+
+__all__ = ["fetch_earnings", "render_earnings"]

aria_code/apps/cli/endpoint_migration.py

@@ -0,0 +1,64 @@
+"""The server an install talks to, and the old default that stranded it on localhost.
+
+``default_config()`` used to save ``api_url = http://localhost:8000``. That
+looked like a default but was written into every user's config.json on first
+run, where it became indistinguishable from a choice. Anyone who installed
+from GitHub then had every backend call, and Google sign-in, aimed at a
+developer backend on their own machine: a refused connection, or on a machine
+that happened to run one, a page reading ``{"detail":"Not Found"}``. Fixing the
+default in code cannot reach a config that already holds the old value, so the
+old default is recognised here and replaced once, written back and announced,
+the same way a retired model is (see model_retirement).
+
+What counts as a choice and is left alone:
+
+* ``ARTHERA_API_URL`` in the environment, which now also overrides a saved value
+  (in memory only), so a developer with a real local backend sets it once;
+* any ``api_url`` other than the exact old default, such as a staging server;
+* ``api_url_pinned: true``, an escape hatch for someone who wants localhost.
+
+``local_mode`` is not touched: choosing a local model is a different decision
+from where the backend lives.
+"""
+
+from __future__ import annotations
+
+import os
+from aria_code.service_endpoints import API_URL, current_url
+
+PRODUCTION_API_URL = API_URL
+LEGACY_DEFAULT_API_URL = "http://localhost:8000"
+# The product moved from arthera.finance to arthera.xyz and the old domain no
+# longer answers, so a config that was migrated to (or installed with) the old
+# production address points at nothing. It is replaced the same way the
+# localhost default is.
+RETIRED_API_URLS = ("http://localhost:8000", "https://api.arthera.finance")
+
+
+def _norm(url: object) -> str:
+    return str(url or "").strip().rstrip("/").lower()
+
+
+def migrate_config(config: dict) -> list[tuple[str, str, str]]:
+    """Move the old localhost default to production in place; return (key, old, new)."""
+    old = config.get("api_url")
+    retired = bool(old) and current_url(str(old)) != str(old).strip().rstrip('/')
+    env = os.getenv("ARTHERA_API_URL", "").strip()
+    if env:
+        # An explicit environment choice wins over the file for this run only;
+        # nothing is rewritten, so unsetting the variable restores the file.
+        config["api_url"] = current_url(env)
+        return []
+    if retired:
+        config["api_url"] = PRODUCTION_API_URL
+        return [("api_url", str(old), PRODUCTION_API_URL)]
+    if config.get("api_url_pinned"):
+        return []
+    old = config.get("api_url")
+    if _norm(old) not in {LEGACY_DEFAULT_API_URL, "https://api.arthera.finance", "https://cn.arthera.finance"}:
+        return []
+    config["api_url"] = PRODUCTION_API_URL
+    return [("api_url", str(old), PRODUCTION_API_URL)]
+
+
+__all__ = ["LEGACY_DEFAULT_API_URL", "PRODUCTION_API_URL", "RETIRED_API_URLS", "migrate_config"]

aria_code/apps/cli/exec_events.py

@@ -0,0 +1,255 @@
+"""JSON events for `aria-code -p … --format jsonl`, one per line, as the turn runs.
+
+`-p --json` printed one document at the end, so a CI job saw nothing until the
+turn was over and could not tell which tool ran, how long it took or where
+it failed. With jsonl each step is a line on stdout as it happens:
+
+    {"type": "turn.started", "prompt": "...", "model": "...", "ts": ...}
+    {"type": "tool.started", "tool": "run_command", "params": {...}, "ts": ...}
+    {"type": "tool.completed", "tool": "run_command", "success": true, "elapsed_s": 1.2,
+     "error": "", "ts": ...}
+    {"type": "turn.completed", "success": true, "response": "...", "tools_used": [...], ...}
+
+Tool parameters are shortened and secrets masked: a written file's contents
+or a command's token have no place in a CI log.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+from typing import Any, TextIO
+
+from aria_code.apps.cli.runtime_consumer import MEASURED_ELAPSED_KEY, _redact_activity_text
+
+PARAM_CHARS = 300
+
+
+def json_safe(value: Any) -> Any:
+    """``value`` with anything json cannot write turned into text."""
+    return json.loads(json.dumps(value, ensure_ascii=False, default=str))
+
+
+RESULT_CHARS = 20_000
+
+
+def _full() -> bool:
+    """ARIA_EVENTS_FULL=1: keep whole parameters and tool results (eval trajectories).
+
+    The default view is for logs and CI: short, file bodies by size. A
+    trajectory to learn from needs what was written and what came back.
+    """
+    import os
+
+    return os.environ.get("ARIA_EVENTS_FULL", "").strip() in ("1", "true", "yes")
+
+
+_SECRET = re.compile(
+    r"(?i)\b(api[_-]?key|token|password|passwd|secret)(\s*[=:]\s*)[^\s'\"]+"
+    r"|\b(bearer|basic)(\s+)[A-Za-z0-9._~+/=-]+"
+    r"|\b(?:sk|pk|rk)-[A-Za-z0-9_-]{8,}|\bgh[pousr]_[A-Za-z0-9]{12,}|\bAIza[0-9A-Za-z_-]{20,}"
+    r"|\bya29\.[0-9A-Za-z_-]+"
+)
+
+
+def _mask_text(text: str) -> str:
+    """Secret-shaped values masked; whitespace, indentation and newlines kept."""
+    def repl(match: "re.Match") -> str:
+        if match.group(1):
+            return f"{match.group(1)}{match.group(2)}***"
+        if match.group(3):
+            return f"{match.group(3)}{match.group(4)}***"
+        return "***"
+    return _SECRET.sub(repl, str(text))
+
+
+def _mask_value(value: Any) -> Any:
+    if isinstance(value, str):
+        return _mask_text(value)
+    if isinstance(value, dict):
+        return {k: _mask_value(v) for k, v in value.items() if not str(k).startswith("_")}
+    if isinstance(value, list):
+        return [_mask_value(v) for v in value]
+    return value
+
+
+def _param_view(params: dict) -> dict:
+    if _full():
+        return _mask_value(json_safe(dict(params or {})))
+    view = {}
+    for key, value in (params or {}).items():
+        if str(key).startswith("_"):
+            continue                       # execution context the host added
+        if isinstance(value, str):
+            # A file's contents is not a parameter worth a log line; its size is.
+            view[key] = (f"<{len(value)} chars>" if len(value) > 2000
+                         else _redact_activity_text(value, limit=PARAM_CHARS))
+        elif isinstance(value, (int, float, bool)) or value is None:
+            view[key] = value
+        else:
+            view[key] = _redact_activity_text(json.dumps(value, ensure_ascii=False, default=str),
+                                              limit=PARAM_CHARS)
+    return view
+
+
+class ExecEvents:
+    """Writes events to ``out``; does nothing when ``out`` is None."""
+
+    def __init__(self, out: TextIO | None):
+        self.out = out
+        # Preserve the established JSONL contract unless a streaming consumer
+        # opts in. Never emit provider reasoning; only visible answer tokens.
+        import os
+        self.streaming = out is not None and os.environ.get("ARIA_EVENTS_STREAM", "").strip().lower() in (
+            "1", "true", "yes",
+        )
+
+    def text_delta(self, text: str) -> None:
+        if self.streaming and text:
+            self.emit("answer.delta", text=text)
+
+    def status(self, state: str, message: str) -> None:
+        if self.streaming:
+            self.emit("turn.status", state=_redact_activity_text(state, limit=80),
+                      message=_redact_activity_text(message, limit=PARAM_CHARS))
+
+    def emit(self, event_type: str, **fields: Any) -> None:
+        if self.out is None:
+            return
+        record = {"type": event_type, **json_safe(fields), "ts": round(time.time(), 3)}
+        try:
+            self.out.write(json.dumps(record, ensure_ascii=False) + "\n")
+            self.out.flush()
+        except (OSError, ValueError):
+            self.out = None                # the reader went away; stop writing
+
+    def tool_started(self, tool: str, params: dict) -> None:
+        self.emit("tool.started", tool=tool, params=_param_view(params))
+
+    def tool_completed(self, tool: str, result: dict) -> None:
+        result = result if isinstance(result, dict) else {"success": bool(result)}
+        fields: dict[str, Any] = {"tool": tool, "success": bool(result.get("success", True))}
+        if isinstance(result.get(MEASURED_ELAPSED_KEY), (int, float)):
+            fields["elapsed_s"] = round(float(result[MEASURED_ELAPSED_KEY]), 3)
+        if result.get("error"):
+            fields["error"] = _redact_activity_text(result["error"], limit=PARAM_CHARS)
+        data = result.get("data") if isinstance(result.get("data"), dict) else {}
+        if result.get("reused") is True:
+            fields["reused"] = True
+        # Counts describe the returned data, never inferred model prose.
+        if tool == "list_files" and isinstance(data.get("items"), list):
+            fields["item_count"] = len(data["items"])
+        for key in ("exit_code", "path", "process_id", "change_id"):
+            if key in data:
+                fields[key] = data[key]
+        if _full():
+            masked = _mask_value(json_safe(result))
+            body = json.dumps(masked, ensure_ascii=False)
+            fields["result"] = masked if len(body) <= RESULT_CHARS else body[:RESULT_CHARS] + "…"
+        brief = _brief(tool, data)
+        if brief:
+            fields["brief"] = brief
+        self.emit("tool.completed", **fields)
+
+
+def _tool_name(tool: str) -> str:
+    return str(tool or "").rsplit("__", 1)[-1]
+
+
+def _brief_bodies(data: dict) -> list[dict]:
+    bodies = [data]
+    nested = data.get("data")
+    if isinstance(nested, dict):
+        bodies.append(nested)
+    metrics = data.get("metrics")
+    if isinstance(metrics, dict):
+        bodies.append(metrics)
+    content = data.get("content")
+    if isinstance(content, str) and content.lstrip().startswith("{"):
+        try:
+            inner = json.loads(content)
+        except json.JSONDecodeError:
+            inner = None
+        if isinstance(inner, dict):
+            bodies.append(inner)
+            if isinstance(inner.get("data"), dict):
+                bodies.append(inner["data"])
+            if isinstance(inner.get("metrics"), dict):
+                bodies.append(inner["metrics"])
+    return bodies
+
+
+def _brief_num(body: dict, *keys: str) -> float | None:
+    for key in keys:
+        value = body.get(key)
+        if isinstance(value, bool) or not isinstance(value, (int, float)):
+            continue
+        if value != value or value in (float("inf"), float("-inf")):
+            continue
+        return float(value)
+    return None
+
+
+def _brief_text(body: dict, *keys: str) -> str:
+    for key in keys:
+        value = body.get(key)
+        if not isinstance(value, str):
+            continue
+        text = " ".join(value.split())
+        if text:
+            return text[:24]
+    return ""
+
+
+def _brief_percent(body: dict, fraction_key: str, pct_key: str) -> float | None:
+    direct = _brief_num(body, pct_key)
+    if direct is not None:
+        return round(direct, 2)
+    fraction = _brief_num(body, fraction_key)
+    if fraction is None:
+        return None
+    return round(fraction * 100, 2)
+
+
+def _brief(tool: str, data: dict) -> dict | None:
+    """One terminal line of numbers the tool returned. Missing fields stay out."""
+    if not isinstance(data, dict) or not data:
+        return None
+    bodies = _brief_bodies(data)
+    for body in bodies:
+        diff = body.get("diff")
+        if isinstance(diff, str) and diff:
+            added = sum(1 for line in diff.splitlines() if line.startswith("+") and not line.startswith("+++"))
+            removed = sum(1 for line in diff.splitlines() if line.startswith("-") and not line.startswith("---"))
+            return {"kind": "edit", "added": added, "removed": removed}
+    name = _tool_name(tool)
+    if name in {"get_market_data", "get_crypto_data", "get_forex_data", "financial_quote"}:
+        for body in bodies:
+            price = _brief_num(body, "price", "latest_close", "current_price")
+            if price is None:
+                continue
+            brief: dict[str, Any] = {"kind": "quote", "price": price}
+            label = _brief_text(body, "name", "symbol")
+            if label:
+                brief["name"] = label
+            change = _brief_num(body, "change_pct", "change_pct_24h", "changePercent")
+            if change is not None:
+                brief["change_pct"] = change
+            if isinstance(body.get("stale"), bool):
+                brief["stale"] = body["stale"]
+            return brief
+    if name in {"backtest_strategy", "cloud_backtest", "run_portfolio_backtest", "financial_backtest"}:
+        for body in bodies:
+            returned = _brief_percent(body, "total_return", "total_return_pct")
+            if returned is None:
+                continue
+            brief = {"kind": "backtest", "return_pct": returned}
+            drawdown = _brief_percent(body, "max_drawdown", "max_drawdown_pct")
+            if drawdown is not None:
+                brief["drawdown_pct"] = round(abs(drawdown), 2)
+            return brief
+    return None
+
+
+__all__ = ["ExecEvents", "json_safe"]

aria_code/apps/cli/file_references.py

@@ -0,0 +1,155 @@
+"""Candidates for an `@` file reference, the way Claude Code and Codex offer them.
+
+Typing `@` in a prompt names a file or folder. The old completion listed one
+directory at a time, like a shell, which makes a file three levels down take
+three Tabs. This searches the whole workspace instead: `@auth` finds
+`src/api/auth.py`, `@rdme` finds `README.md`, and `@src/` lists what is in
+`src/`. Files the project ignores (`.gitignore`) and build clutter are left out.
+
+The result is a list of whole replacement texts: the prompt as typed, with the
+`@token` replaced by one candidate. That is the shape the Go runtime has always
+answered with, so the frontend has one way to read both.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import time
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+#: How many candidates a request returns.
+LIMIT = 8
+
+_SKIP_DIRS = {
+    ".git", "node_modules", "__pycache__", ".venv", "venv", "dist", "build", "target",
+    ".mypy_cache", ".pytest_cache", ".ruff_cache", ".next", ".cache", "site-packages",
+}
+_MAX_FILES = 20000
+_TTL_SECONDS = 10.0
+_cache: Dict[str, Tuple[float, List[str]]] = {}
+
+
+def _git_files(root: Path) -> Optional[List[str]]:
+    if not (root / ".git").exists():
+        return None
+    try:
+        out = subprocess.run(
+            ["git", "-C", str(root), "ls-files", "-co", "--exclude-standard", "-z"],
+            capture_output=True, timeout=3, check=True,
+        ).stdout
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return [p for p in out.decode("utf-8", "replace").split("\0") if p][:_MAX_FILES]
+
+
+def _walk_files(root: Path) -> List[str]:
+    found: List[str] = []
+    for current, dirs, names in os.walk(root):
+        dirs[:] = sorted(d for d in dirs if d not in _SKIP_DIRS and not d.startswith("."))
+        base = Path(current).relative_to(root)
+        for name in sorted(names):
+            if name.startswith(".") and name not in (".gitignore", ".env.example"):
+                continue
+            found.append((base / name).as_posix())
+            if len(found) >= _MAX_FILES:
+                return found
+    return found
+
+
+def workspace_files(root: Path, now: Optional[float] = None) -> List[str]:
+    """Every file in the workspace (relative, `/`-separated), cached for a few seconds."""
+    key = str(root)
+    stamp = time.monotonic() if now is None else now
+    hit = _cache.get(key)
+    if hit and stamp - hit[0] < _TTL_SECONDS:
+        return hit[1]
+    files = _git_files(root)
+    if files is None:
+        files = _walk_files(root)
+    _cache[key] = (stamp, files)
+    return files
+
+
+def _token(text: str) -> Optional[Tuple[int, str]]:
+    """Where the `@token` starts and what has been typed of it, or None."""
+    start = text.rfind("@")
+    if start < 0 or (start > 0 and text[start - 1] not in " \t\n"):
+        return None
+    token = text[start + 1:]
+    if token.startswith("file:"):
+        token = token[5:]
+    token = token.lstrip('"')
+    if any(c in token for c in "\n\r\t"):
+        return None
+    return start, token
+
+
+def _is_subsequence(needle: str, hay: str) -> bool:
+    it = iter(hay)
+    return all(c in it for c in needle)
+
+
+def _children(files: List[str], prefix: str) -> List[str]:
+    """What sits directly inside `prefix` ('' for the top level): folders end in `/`."""
+    seen: Dict[str, None] = {}
+    for path in files:
+        if not path.startswith(prefix):
+            continue
+        rest = path[len(prefix):]
+        if not rest:
+            continue
+        head, sep, _ = rest.partition("/")
+        seen[prefix + head + ("/" if sep else "")] = None
+    entries = list(seen)
+    return sorted(entries, key=lambda e: (not e.endswith("/"), e.lower()))
+
+
+def _search(files: List[str], query: str) -> List[str]:
+    q = query.lower()
+    dirs: Dict[str, None] = {}
+    for path in files:
+        parts = path.split("/")
+        for i in range(1, len(parts)):
+            dirs["/".join(parts[:i]) + "/"] = None
+    scored: List[Tuple[int, int, str]] = []
+    for path in [*files, *dirs]:
+        low = path.lower()
+        bare = low.rstrip("/")
+        base = bare.rsplit("/", 1)[-1]
+        if base.startswith(q):
+            tier = 0
+        elif low.startswith(q):
+            tier = 1
+        elif q in base:
+            tier = 2
+        elif q in low:
+            tier = 3
+        elif _is_subsequence(q, base):
+            tier = 4
+        elif _is_subsequence(q, low):
+            tier = 5
+        else:
+            continue
+        scored.append((tier, len(path), path))
+    scored.sort()
+    return [path for _, _, path in scored]
+
+
+def reference_candidates(text: str, root: Path, limit: int = LIMIT) -> List[str]:
+    """Replacement prompts for the `@token` at the end of `text`, best first."""
+    found = _token(text)
+    if found is None:
+        return []
+    start, token = found
+    files = workspace_files(root)
+    if token == "" or token.endswith("/"):
+        paths = _children(files, token)
+    else:
+        paths = _search(files, token)
+    out: List[str] = []
+    for path in paths[:limit]:
+        shown = f'"{path}"' if " " in path else path
+        out.append(f"{text[:start]}@{shown}")
+    return out