Function expand_at_mentions

src/command_system/input_processing.py:485–622

Resolve ``@path`` mentions and build context attachments. Mirrors ``processAtMentionedFiles`` in ``typescript/src/utils/attachments.ts``: if a mention resolves to a directory we build a ``Listed directory`` attachment containing its entries (up to 1000); if it resolves to a readable

(
    text: str,
    *,
    cwd: str | None = None,
)

def expand_at_mentions(
    text: str,
    *,
    cwd: str | None = None,
) -> tuple[str, list[dict[str, Any]]]:
    """Resolve ``@path`` mentions and build context attachments.

    Mirrors ``processAtMentionedFiles`` in
    ``typescript/src/utils/attachments.ts``: if a mention resolves to a
    directory we build a ``Listed directory`` attachment containing its
    entries (up to 1000); if it resolves to a readable image file
    (png/jpg/jpeg/gif/webp) we attach a ``kind="image"`` attachment with
    base64 + media_type via the image pipeline, so the REPL can inline it
    as a real image content block in the user message instead of mojibake
    in a system-reminder. Other readable files we attach the
    file's contents verbatim. The returned ``text`` is left unchanged — the
    caller prepends / appends the attachments before sending to the model.
    """
    cwd = cwd or os.getcwd()
    seen: set[str] = set()
    attachments: list[dict[str, Any]] = []

    for match in _FILE_MENTION_RE.finditer(text):
        raw = match.group(1).rstrip(".,!?:;\"'`)]}")
        if not raw:
            continue
        # Skip bare @word mentions (no path separator / dot / home marker).
        if not (
            raw.startswith(("/", "~", "./", "../"))
            or "/" in raw
            or "." in raw
        ):
            continue

        # C5: the search dialog inserts ``@file#Lline`` (TS
        # attachments.ts:2859-2861 parses the ``#L10-20`` fragment).
        # Degraded port: strip the fragment so the FILE attaches — the
        # line reference stays visible to the model in the prompt text;
        # range slicing is a noted follow-up.
        fragment_match = re.search(r"#L\d+(?:-\d+)?$", raw)
        if fragment_match:
            raw = raw[: fragment_match.start()]
            if not raw:
                continue

        expanded = os.path.expanduser(raw)
        if not os.path.isabs(expanded):
            expanded = os.path.abspath(os.path.join(cwd, expanded))
        if expanded in seen:
            continue
        seen.add(expanded)

        try:
            if os.path.isdir(expanded):
                entries = sorted(os.listdir(expanded))
                truncated = len(entries) > _MAX_DIR_ENTRIES
                shown = entries[:_MAX_DIR_ENTRIES]
                if truncated: