unique-sdk 2026.24.0.dev2__tar.gz → 2026.24.0.dev4__tar.gz

{unique_sdk-2026.24.0.dev2 → unique_sdk-2026.24.0.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-sdk
-Version: 2026.24.0.dev2
+Version: 2026.24.0.dev4
 Summary: 
 Author: Martin Fadler, Konstantin Krauss, Andreas Hauri
 Author-email: Martin Fadler <martin.fadler@unique.ch>, Konstantin Krauss <konstantin@unique.ch>, Andreas Hauri <andreas@unique.ch>

{unique_sdk-2026.24.0.dev2 → unique_sdk-2026.24.0.dev4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_sdk"
-version = "2026.24.0.dev2"
+version = "2026.24.0.dev4"
 description = ""
 readme = "README.md"
 license = { text = "MIT" }

{unique_sdk-2026.24.0.dev2 → unique_sdk-2026.24.0.dev4}/unique_sdk/_unique_response.py

@@ -19,4 +19,7 @@ class UniqueResponse(UniqueResponseBase):
     def __init__(self, body: str, code: int, headers: Mapping[str, str]):
         UniqueResponseBase.__init__(self, code, headers)
         self.body = body
-        self.data = json.loads(body, object_pairs_hook=OrderedDict)
+        if not body or body.isspace():
+            self.data = OrderedDict()
+        else:
+            self.data = json.loads(body, object_pairs_hook=OrderedDict)

{unique_sdk-2026.24.0.dev2 → unique_sdk-2026.24.0.dev4}/unique_sdk/cli/cli.py

@@ -26,7 +26,12 @@ from unique_sdk.cli.commands.scheduled_tasks import (
     cmd_schedule_list,
     cmd_schedule_update,
 )
-from unique_sdk.cli.commands.search import cmd_search
+from unique_sdk.cli.commands.search import (
+    cmd_search,
+)
+from unique_sdk.cli.commands.search import (
+    is_error_output as _is_search_error_output,
+)
 from unique_sdk.cli.commands.subagent import cmd_subagent
 from unique_sdk.cli.commands.subagent import (
     is_error_output as _is_subagent_error_output,
@@ -390,9 +395,12 @@ def search(
             k, v = kv.split("=", 1)
             parsed_metadata.append((k, v))
 
-    click.echo(
-        cmd_search(state, query, folder=folder, metadata=parsed_metadata, limit=limit)
+    output = cmd_search(
+        state, query, folder=folder, metadata=parsed_metadata, limit=limit
     )
+    click.echo(output)
+    if _is_search_error_output(output):
+        ctx.exit(1)
 
 
 @main.command()

unique_sdk-2026.24.0.dev4/unique_sdk/cli/commands/_citation_manifest.py

@@ -0,0 +1,185 @@
+"""Shared helpers for the per-turn citation refs manifest under ``.unique/``.
+
+Both ``unique-cli search`` (KB) and ``unique-cli web-search`` (web) append
+to a small per-turn JSONL file inside the current workspace's ``.unique``
+directory so that the Swappable Intelligence runner can later substitute
+``[sourceN]`` / ``[websourceN]`` markers in the LLM answer with footnotes
+and reference chips.
+
+The handshake is symmetric across the two callers — the file name, lock
+file name, and on-disk layout differ, but the safety + locking +
+read/append semantics are identical. This module owns that machinery so
+neither caller has to maintain its own copy.
+
+Each caller passes its own ``refs_log_path`` (absolute path) and lock
+filename in. Nothing in this module is web- or KB-specific.
+"""
+
+from __future__ import annotations
+
+import fcntl
+import json
+import os
+from collections.abc import Generator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any
+
+__all__ = [
+    "UnsafeRefsLogPathError",
+    "_append_turn_refs_manifest_entry",
+    "_locked_turn_refs_manifest",
+    "_read_turn_refs_manifest",
+]
+
+
+class UnsafeRefsLogPathError(OSError):
+    """Raised when the internal refs log path would follow a symlink.
+
+    Callers should treat this as a hard failure for the current command —
+    refuse to render results, and surface the error via the caller's
+    usual ``<prefix>: <message>`` error string convention.
+    """
+
+
+def _assert_safe_refs_log_path(refs_log_path: Path) -> None:
+    """Reject symlinks for the parent dir, the manifest, or any file at
+    the same path that is not a regular file.
+
+    This is intentionally strict: the manifest path is a fixed,
+    well-known handoff path used by another process (the runner) running
+    in the same workspace. Following symlinks here would let a malicious
+    workspace redirect writes elsewhere.
+
+    Writer-side counterpart to the reader-side check at
+    ``swappable_intelligence.runner.CodingAgentRunner._is_safe_refs_log_path``
+    in ``monorepo``. The two run in different processes (this one in the
+    agent's bash sandbox, the reader in assistants-core) so they cannot
+    share code; keep the rejection policy aligned across the two when
+    either is edited.
+    """
+    refs_log_dir = refs_log_path.parent
+    if refs_log_dir.is_symlink() or (
+        refs_log_dir.exists() and not refs_log_dir.is_dir()
+    ):
+        raise UnsafeRefsLogPathError(
+            f"refusing unsafe refs log directory: {refs_log_dir}"
+        )
+    if refs_log_path.is_symlink():
+        raise UnsafeRefsLogPathError(f"refusing unsafe refs log file: {refs_log_path}")
+    if refs_log_path.exists() and not refs_log_path.is_file():
+        raise UnsafeRefsLogPathError(f"refusing unsafe refs log file: {refs_log_path}")
+
+
+def _read_turn_refs_manifest(refs_log_path: Path) -> list[dict[str, Any]]:
+    """Return all valid JSON object lines from the manifest, in order.
+
+    Blank lines and lines that fail to parse as a JSON object are
+    silently skipped — this matches the runner's tolerance for malformed
+    lines and keeps a stray partial write from breaking the next call.
+    """
+    _assert_safe_refs_log_path(refs_log_path)
+    if not refs_log_path.is_file():
+        return []
+    try:
+        raw_lines = refs_log_path.read_text(encoding="utf-8").splitlines()
+    except OSError as exc:
+        raise UnsafeRefsLogPathError(
+            f"failed to read refs log: {refs_log_path}"
+        ) from exc
+
+    entries: list[dict[str, Any]] = []
+    for raw in raw_lines:
+        if not raw.strip():
+            continue
+        try:
+            payload = json.loads(raw)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(payload, dict):
+            entries.append(payload)
+    return entries
+
+
+def _append_turn_refs_manifest_entry(
+    refs_log_path: Path,
+    payload: dict[str, Any],
+) -> None:
+    """Append one JSON object as a single line, creating parents if needed.
+
+    Uses ``O_NOFOLLOW`` and a 0o600 mode so a symlink swap between the
+    safety check and the open call still fails closed.
+    """
+    _assert_safe_refs_log_path(refs_log_path)
+    try:
+        refs_log_path.parent.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        raise UnsafeRefsLogPathError(
+            f"failed to create refs log directory: {refs_log_path.parent}"
+        ) from exc
+    _assert_safe_refs_log_path(refs_log_path)
+    flags = os.O_WRONLY | os.O_CREAT | os.O_APPEND
+    flags |= getattr(os, "O_NOFOLLOW", 0)
+    try:
+        fd = os.open(refs_log_path, flags, 0o600)
+    except OSError as exc:
+        raise UnsafeRefsLogPathError(
+            f"failed to open refs log safely: {refs_log_path}"
+        ) from exc
+    try:
+        with os.fdopen(fd, "a", encoding="utf-8") as fp:
+            fp.write(json.dumps(payload, default=str, ensure_ascii=False) + "\n")
+    except OSError as exc:
+        raise UnsafeRefsLogPathError(
+            f"failed to write refs log: {refs_log_path}"
+        ) from exc
+
+
+@contextmanager
+def _locked_turn_refs_manifest(
+    refs_log_path: Path,
+    *,
+    lock_filename: str,
+) -> Generator[None, None, None]:
+    """Hold an ``fcntl.flock`` on a sibling lock file for the duration of
+    a read-existing → compute-next-number → append-new sequence.
+
+    The lock file lives in the same ``.unique`` directory as the manifest
+    so concurrent ``unique-cli`` invocations from the same workspace
+    serialise their appends and never race the source-number counter.
+    """
+    lock_path = refs_log_path.parent / lock_filename
+    _assert_safe_refs_log_path(lock_path)
+    try:
+        refs_log_path.parent.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        raise UnsafeRefsLogPathError(
+            f"failed to create refs log directory: {refs_log_path.parent}"
+        ) from exc
+    _assert_safe_refs_log_path(lock_path)
+
+    flags = os.O_RDWR | os.O_CREAT
+    flags |= getattr(os, "O_NOFOLLOW", 0)
+    try:
+        fd = os.open(lock_path, flags, 0o600)
+    except OSError as exc:
+        raise UnsafeRefsLogPathError(
+            f"failed to open refs lock safely: {lock_path}"
+        ) from exc
+
+    try:
+        fcntl.flock(fd, fcntl.LOCK_EX)
+    except OSError as exc:
+        os.close(fd)
+        raise UnsafeRefsLogPathError(
+            f"failed to lock refs manifest: {lock_path}"
+        ) from exc
+
+    try:
+        yield
+    finally:
+        try:
+            fcntl.flock(fd, fcntl.LOCK_UN)
+        except OSError:
+            pass
+        os.close(fd)

unique_sdk-2026.24.0.dev4/unique_sdk/cli/commands/search.py

@@ -0,0 +1,262 @@
+"""Search command: combined KB search with folder/metadata filters.
+
+Always emits results wrapped in ``<sourceN>...</sourceN>`` blocks and
+appends a per-turn ContentChunk-shaped manifest at
+``<cwd>/.unique/kb-search-refs.jsonl``. The Swappable Intelligence
+runner reads that manifest after the turn to convert ``[sourceN]``
+markers in the LLM answer into ``<sup>N</sup>`` footnotes plus
+clickable reference chips on the Unique platform.
+
+The manifest format is identical to the legacy ``bundled_skills/kb-search``
+``search.py`` from the monorepo — that bundle is being retired in favor of
+this CLI command.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import unique_sdk
+from unique_sdk import UQLCombinator, UQLOperator
+from unique_sdk.cli.commands._citation_manifest import (
+    UnsafeRefsLogPathError,
+    _append_turn_refs_manifest_entry,
+    _locked_turn_refs_manifest,
+    _read_turn_refs_manifest,
+)
+from unique_sdk.cli.state import ShellState
+
+DEFAULT_LIMIT = 200
+
+SEARCH_ERROR_PREFIX = "search:"
+
+_REFS_LOG_RELATIVE_PATH = Path(".unique") / "kb-search-refs.jsonl"
+_LOCK_FILENAME = "kb-search-refs.lock"
+
+
+def _build_metadata_filter(
+    folder_scope_id: str | None,
+    extra_metadata: list[tuple[str, str]] | None,
+) -> dict[str, Any] | None:
+    """Build a UniqueQL metadata filter from folder scope and key=value pairs."""
+    conditions: list[dict[str, Any]] = []
+
+    if folder_scope_id:
+        conditions.append(
+            {
+                "path": ["folderIdPath"],
+                "operator": UQLOperator.CONTAINS,
+                "value": f"uniquepathid://{folder_scope_id}",
+            }
+        )
+
+    if extra_metadata:
+        for key, value in extra_metadata:
+            conditions.append(
+                {
+                    "path": [key],
+                    "operator": UQLOperator.EQUALS,
+                    "value": value,
+                }
+            )
+
+    if not conditions:
+        return None
+
+    if len(conditions) == 1:
+        return conditions[0]
+
+    return {UQLCombinator.AND: conditions}
+
+
+def _resolve_folder_to_scope_id(state: ShellState, folder: str) -> str:
+    """Resolve a folder path or scope ID to a scope ID."""
+    if folder.startswith("scope_"):
+        return folder
+
+    if not folder.startswith("/"):
+        folder = f"{state.cwd.rstrip('/')}/{folder}"
+
+    info = unique_sdk.Folder.get_info(
+        user_id=state.config.user_id,
+        company_id=state.config.company_id,
+        folderPath=folder,
+    )
+    scope_id = info.get("id")
+    if not scope_id:
+        raise ValueError(f"Could not resolve folder: {folder}")
+    return scope_id
+
+
+def _format_source_block(source_number: int, result: Any) -> str:
+    """Render one search result as a ``<sourceN>...</sourceN>`` block.
+
+    Mirrors the legacy ``unique_ai`` source format that the Swappable
+    Intelligence runner's reference post-processor recognises — ``<sourceN>``
+    open/close tags with ``<|document|>``, ``<|page|>``, ``<|info|>``
+    sub-sections. The chunk-level metadata (startPage, endPage, url, etc.)
+    is captured in full in the JSONL manifest for the runner to consume;
+    only the human-relevant bits appear in the on-screen block.
+    """
+    title = (
+        getattr(result, "title", None)
+        or getattr(result, "key", None)
+        or f"content {getattr(result, 'id', '?')}"
+    )
+    content_id = getattr(result, "id", "") or ""
+    text = getattr(result, "text", "") or ""
+    start_page = getattr(result, "startPage", 0) or 0
+    end_page = getattr(result, "endPage", 0) or 0
+
+    sections: list[str] = []
+    sections.append(f"<|document|>{title}</|document|>")
+    if start_page and end_page and start_page > 0 and end_page > 0:
+        page_range = (
+            str(start_page) if start_page == end_page else f"{start_page}-{end_page}"
+        )
+        sections.append(f"<|page|>{page_range}</|page|>")
+    if content_id:
+        sections.append(f"<|info|>{content_id}</|info|>")
+    sections.append(text.strip())
+
+    body = "\n".join(sections)
+    return f"<source{source_number}>\n{body}\n</source{source_number}>"
+
+
+def _result_to_chunk_payload(result: Any) -> dict[str, Any]:
+    """Convert a ``unique_sdk.Search`` result into a ContentChunk-shaped dict.
+
+    Keys are camelCase aliases of ``unique_toolkit.content.ContentChunk``
+    fields so the runner can rehydrate them via
+    ``ContentChunk.model_validate(...)``. All keys are emitted (with
+    ``None`` when absent) to keep the per-line shape stable.
+    """
+
+    def _get(name: str, default: Any = None) -> Any:
+        return getattr(result, name, default)
+
+    metadata = _get("metadata")
+    return {
+        "id": _get("id", "") or "",
+        "chunkId": _get("chunkId"),
+        "text": _get("text", "") or "",
+        "order": _get("order", 0) or 0,
+        "key": _get("key"),
+        "url": _get("url"),
+        "title": _get("title"),
+        "startPage": _get("startPage"),
+        "endPage": _get("endPage"),
+        "metadata": metadata if isinstance(metadata, dict) else None,
+        "createdAt": _get("createdAt"),
+        "updatedAt": _get("updatedAt"),
+    }
+
+
+def _format_results_with_citations(
+    results: list[Any],
+    *,
+    refs_log_path: Path,
+) -> str:
+    """Number, format, and persist each result inside one locked critical section.
+
+    Reads the existing manifest under lock so ``sourceN`` numbering keeps
+    growing across multiple ``unique-cli search`` invocations within the
+    same turn — the runner truncates the manifest at turn start, so the
+    first call in a turn starts at 1.
+    """
+    if not results:
+        return "No results found."
+
+    with _locked_turn_refs_manifest(refs_log_path, lock_filename=_LOCK_FILENAME):
+        existing_entries = _read_turn_refs_manifest(refs_log_path)
+        starting_number = len(existing_entries) + 1
+
+        blocks: list[str] = []
+        for offset, result in enumerate(results):
+            source_number = starting_number + offset
+            blocks.append(_format_source_block(source_number, result))
+            _append_turn_refs_manifest_entry(
+                refs_log_path,
+                _result_to_chunk_payload(result),
+            )
+
+    return f"Found {len(results)} result(s):\n\n" + "\n\n".join(blocks)
+
+
+def cmd_search(
+    state: ShellState,
+    query: str,
+    folder: str | None = None,
+    metadata: list[tuple[str, str]] | None = None,
+    limit: int = DEFAULT_LIMIT,
+    *,
+    refs_log_path: Path | None = None,
+) -> str:
+    """Execute a combined search with optional folder and metadata filters.
+
+    Args:
+        state: Shell state carrying user/company credentials and cwd.
+        query: Search string.
+        folder: Optional folder path, name, or scope ID. Overrides
+            ``state.scope_id`` and ``state.workspace_scope_ids``.
+        metadata: Optional ``[(key, value), ...]`` metadata filters
+            combined with AND.
+        limit: Maximum number of results.
+        refs_log_path: Override the per-turn citation manifest path —
+            for tests; production callers leave this ``None`` so the
+            manifest lives at ``<cwd>/.unique/kb-search-refs.jsonl`` and
+            the Swappable Intelligence runner can find it.
+    """
+    try:
+        folder_scope_id: str | None = None
+        if folder:
+            folder_scope_id = _resolve_folder_to_scope_id(state, folder)
+        elif state.scope_id:
+            folder_scope_id = state.scope_id
+
+        scope_ids: list[str] | None = None
+        if folder_scope_id:
+            scope_ids = [folder_scope_id]
+        elif not folder and state.workspace_scope_ids:
+            scope_ids = state.workspace_scope_ids
+
+        metadata_filter = _build_metadata_filter(
+            folder_scope_id if metadata else None,
+            metadata,
+        )
+
+        search_params: dict[str, Any] = {
+            "searchString": query,
+            "searchType": "COMBINED",
+            "limit": limit,
+        }
+        if scope_ids:
+            search_params["scopeIds"] = scope_ids
+        if metadata_filter:
+            search_params["metaDataFilter"] = metadata_filter
+
+        results = unique_sdk.Search.create(
+            user_id=state.config.user_id,
+            company_id=state.config.company_id,
+            **search_params,
+        )
+
+    except (ValueError, unique_sdk.APIError) as e:
+        return f"{SEARCH_ERROR_PREFIX} {e}"
+
+    log_path = refs_log_path or (Path.cwd() / _REFS_LOG_RELATIVE_PATH)
+    try:
+        return _format_results_with_citations(results, refs_log_path=log_path)
+    except UnsafeRefsLogPathError as exc:
+        return f"{SEARCH_ERROR_PREFIX} {exc}"
+
+
+def is_error_output(output: str) -> bool:
+    """Return ``True`` when ``output`` is a CLI error message.
+
+    Mirrors :func:`unique_sdk.cli.commands.web_search.is_error_output` so
+    the Click layer can translate a returned error string into a non-zero
+    exit code without changing the existing string-returning contract.
+    """
+    return output.startswith(SEARCH_ERROR_PREFIX)

{unique_sdk-2026.24.0.dev2 → unique_sdk-2026.24.0.dev4}/unique_sdk/cli/commands/web_search.py

@@ -18,9 +18,17 @@ Override precedence (highest first):
 from __future__ import annotations
 
 import json
+import logging
+from pathlib import Path
 from typing import Any, cast
 
 import unique_sdk
+from unique_sdk.cli.commands._citation_manifest import (
+    UnsafeRefsLogPathError,
+    _append_turn_refs_manifest_entry,
+    _locked_turn_refs_manifest,
+    _read_turn_refs_manifest,
+)
 from unique_sdk.cli.commands.web_search_config import (
     ConfigOverrides,
     WebSearchCLIConfigError,
@@ -28,14 +36,124 @@ from unique_sdk.cli.commands.web_search_config import (
 )
 from unique_sdk.cli.state import ShellState
 
+_LOGGER = logging.getLogger(__name__)
+
 DEFAULT_PARALLEL = 10
 _SNIPPET_PREVIEW_LIMIT = 200
 _CONTENT_PREVIEW_LIMIT = 500
+_WEB_REFS_LOG_RELATIVE_PATH = Path(".unique") / "web-refs.jsonl"
+_WEB_REFS_LOCK_FILENAME = "web-refs.lock"
 
 WEB_SEARCH_ERROR_PREFIX = "web-search:"
 WEB_CRAWL_ERROR_PREFIX = "web-crawl:"
 
 
+def _source_numbers_by_url(entries: list[dict[str, Any]]) -> dict[str, int]:
+    by_url: dict[str, int] = {}
+    for entry in entries:
+        url = entry.get("url")
+        source_number = entry.get("sourceNumber")
+        if isinstance(url, str) and isinstance(source_number, int):
+            by_url.setdefault(url.strip(), source_number)
+    return by_url
+
+
+def _next_source_number(entries: list[dict[str, Any]]) -> int:
+    source_numbers = [
+        entry["sourceNumber"]
+        for entry in entries
+        if isinstance(entry.get("sourceNumber"), int)
+    ]
+    return max(source_numbers, default=0) + 1
+
+
+def _annotate_web_results_for_citations(
+    payload: dict[str, Any],
+    *,
+    refs_log_path: Path | None = None,
+) -> dict[str, Any]:
+    """Add per-turn web citation numbers and append the refs manifest.
+
+    Web results are deduped by URL: the same URL keeps the same
+    ``sourceNumber`` across consecutive ``search`` / ``crawl`` calls in
+    the same turn, so the crawled-content row carries the same citation
+    marker the search-snippet row already advertised.
+    """
+    refs_log_path = refs_log_path or (Path.cwd() / _WEB_REFS_LOG_RELATIVE_PATH)
+    with _locked_turn_refs_manifest(
+        refs_log_path, lock_filename=_WEB_REFS_LOCK_FILENAME
+    ):
+        entries = _read_turn_refs_manifest(refs_log_path)
+        source_numbers_by_url = _source_numbers_by_url(entries)
+        annotated = dict(payload)
+        annotated_results: list[dict[str, Any]] = []
+
+        for raw_result in payload.get("results") or []:
+            if not isinstance(raw_result, dict):
+                _LOGGER.warning(
+                    "skipping non-dict web result while annotating citations: %r",
+                    raw_result,
+                )
+                continue
+            result = dict(raw_result)
+            url = str(result.get("url") or "").strip()
+            if not url:
+                annotated_results.append(result)
+                continue
+
+            source_number = source_numbers_by_url.get(url)
+            if source_number is None:
+                source_number = _next_source_number(entries)
+                source_numbers_by_url[url] = source_number
+                entries.append({"sourceNumber": source_number, "url": url})
+
+            result["sourceNumber"] = source_number
+            result["citation"] = f"websource{source_number}"
+            manifest_entry = {
+                "sourceNumber": source_number,
+                "url": url,
+                "title": result.get("title"),
+                "snippet": result.get("snippet"),
+                "content": result.get("content"),
+                "error": result.get("error"),
+            }
+            _append_turn_refs_manifest_entry(refs_log_path, manifest_entry)
+            annotated_results.append(result)
+
+        annotated["results"] = annotated_results
+        return annotated
+
+
+def _row_label_for_result(result: dict[str, Any], fallback_index: int) -> int:
+    """Return the human row label for a single result.
+
+    In the happy path ``_annotate_web_results_for_citations`` runs before
+    the formatter and stamps every dict result with an ``int``
+    ``sourceNumber`` that matches the ``[websourceN]`` marker the LLM is
+    told to emit; the formatter then surfaces that same number as the row
+    label so the on-screen list and the citation namespace agree.
+
+    The ``fallback_index`` branch only fires when ``sourceNumber`` is
+    missing or non-int — i.e. a contract violation from the annotator
+    (or annotation was skipped). We never want the formatter to crash,
+    but the fallback row label deliberately *will not* match a
+    ``[websourceN]`` marker, so the agent would cite a number that is
+    not in the manifest. Warn loudly so the bug is observable instead of
+    silently degrading citations.
+    """
+    source_number = result.get("sourceNumber")
+    if isinstance(source_number, int):
+        return source_number
+    _LOGGER.warning(
+        "web result is missing a numeric `sourceNumber` after citation "
+        "annotation; falling back to row index %d. URL=%r — this row will "
+        "not be citable as [websourceN].",
+        fallback_index,
+        result.get("url"),
+    )
+    return fallback_index
+
+
 def _format_search_results(payload: dict[str, Any]) -> str:
     """Render a /web-search-api/search response for terminal display."""
     results: list[dict[str, Any]] = payload.get("results", [])
@@ -54,7 +172,10 @@ def _format_search_results(payload: dict[str, Any]) -> str:
         snippet = (result.get("snippet") or "").replace("\n", " ").strip()
         content = result.get("content") or ""
 
-        lines.append(f"  {i}. {title}")
+        citation = result.get("citation")
+        citation_suffix = f" [{citation}]" if citation else ""
+        row_label = _row_label_for_result(result, i)
+        lines.append(f"  {row_label}. {title}{citation_suffix}")
         lines.append(f"     {url}")
 
         if snippet:
@@ -99,7 +220,10 @@ def _format_crawl_results(payload: dict[str, Any]) -> str:
         content = entry.get("content") or ""
         error = entry.get("error")
 
-        lines.append(f"  {i}. {url}")
+        citation = entry.get("citation")
+        citation_suffix = f" [{citation}]" if citation else ""
+        row_label = _row_label_for_result(entry, i)
+        lines.append(f"  {row_label}. {url}{citation_suffix}")
         if error:
             lines.append(f"     ERROR: {error}")
         elif content.strip():
@@ -254,7 +378,10 @@ def cmd_web_search(
     except (ValueError, unique_sdk.APIError) as exc:
         return f"{WEB_SEARCH_ERROR_PREFIX} {exc}"
 
-    payload = _payload_from_resource(resource)
+    try:
+        payload = _annotate_web_results_for_citations(_payload_from_resource(resource))
+    except UnsafeRefsLogPathError as exc:
+        return f"{WEB_SEARCH_ERROR_PREFIX} {exc}"
     if output_json:
         return _format_search_results_json(payload)
     return _format_search_results(payload)
@@ -315,7 +442,10 @@ def cmd_web_crawl(
     except (ValueError, unique_sdk.APIError) as exc:
         return f"{WEB_CRAWL_ERROR_PREFIX} {exc}"
 
-    payload = _payload_from_resource(resource)
+    try:
+        payload = _annotate_web_results_for_citations(_payload_from_resource(resource))
+    except UnsafeRefsLogPathError as exc:
+        return f"{WEB_CRAWL_ERROR_PREFIX} {exc}"
     if output_json:
         return _format_crawl_results_json(payload)
     return _format_crawl_results(payload)