unique-sdk 2026.28.0.dev10__tar.gz → 2026.28.0.dev11__tar.gz

{unique_sdk-2026.28.0.dev10 → unique_sdk-2026.28.0.dev11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-sdk
-Version: 2026.28.0.dev10
+Version: 2026.28.0.dev11
 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.28.0.dev10 → unique_sdk-2026.28.0.dev11}/pyproject.toml

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

{unique_sdk-2026.28.0.dev10 → unique_sdk-2026.28.0.dev11}/unique_sdk/cli/commands/_citation_manifest.py

@@ -20,6 +20,7 @@ from __future__ import annotations
 import fcntl
 import json
 import os
+import tempfile
 from collections.abc import Generator
 from contextlib import contextmanager
 from pathlib import Path
@@ -30,6 +31,7 @@ __all__ = [
     "_append_turn_refs_manifest_entry",
     "_locked_turn_refs_manifest",
     "_read_turn_refs_manifest",
+    "_rewrite_turn_refs_manifest",
 ]
 
 
@@ -135,6 +137,67 @@ def _append_turn_refs_manifest_entry(
         ) from exc
 
 
+def _rewrite_turn_refs_manifest(
+    refs_log_path: Path,
+    entries: list[dict[str, Any]],
+) -> None:
+    """Atomically replace the manifest with ``entries`` (one JSON object per
+    line, in order).
+
+    Used to backfill a previously-appended entry in place — e.g. when a later
+    tool call re-cites a deduped item and extracts ``details`` the first call
+    lacked. Must be called while holding ``_locked_turn_refs_manifest`` so the
+    read → mutate → rewrite sequence does not race a concurrent append.
+
+    Crash-safe: the new content is written to a sibling temp file and then
+    ``os.replace``-d over the manifest, so a failed/partial write never
+    truncates or corrupts the live manifest (the runner keeps reading the old
+    file until the rename succeeds). Same symlink/regular-file safety discipline
+    as the append path — rejects a symlinked dir/file, and the temp file is
+    created fresh with ``O_CREAT | O_EXCL | O_NOFOLLOW`` (via ``mkstemp``) so a
+    symlink swap between the check and the open 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)
+
+    # Unique temp name per call in the same directory (so os.replace is an
+    # atomic same-filesystem rename). ``mkstemp`` generates a fresh random name
+    # and opens it with ``O_CREAT | O_EXCL | O_NOFOLLOW`` (POSIX) at mode 0600 —
+    # a leftover temp from an earlier crashed rewrite can never collide and
+    # block subsequent backfills.
+    try:
+        fd, tmp_name = tempfile.mkstemp(
+            dir=refs_log_path.parent,
+            prefix=f"{refs_log_path.name}.",
+            suffix=".tmp",
+        )
+    except OSError as exc:
+        raise UnsafeRefsLogPathError(
+            f"failed to open refs log temp file safely: {refs_log_path}"
+        ) from exc
+    tmp_path = Path(tmp_name)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fp:
+            for entry in entries:
+                fp.write(json.dumps(entry, default=str, ensure_ascii=False) + "\n")
+        os.replace(tmp_path, refs_log_path)
+    except OSError as exc:
+        # The live manifest is untouched; drop the partial temp file.
+        try:
+            os.unlink(tmp_path)
+        except OSError:
+            pass
+        raise UnsafeRefsLogPathError(
+            f"failed to write refs log: {refs_log_path}"
+        ) from exc
+
+
 @contextmanager
 def _locked_turn_refs_manifest(
     refs_log_path: Path,

{unique_sdk-2026.28.0.dev10 → unique_sdk-2026.28.0.dev11}/unique_sdk/cli/commands/mcp.py

@@ -14,6 +14,7 @@ from unique_sdk.cli.commands._citation_manifest import (
     _append_turn_refs_manifest_entry,
     _locked_turn_refs_manifest,
     _read_turn_refs_manifest,
+    _rewrite_turn_refs_manifest,
 )
 from unique_sdk.cli.formatting import format_mcp_response
 from unique_sdk.cli.state import ShellState
@@ -43,6 +44,41 @@ _MCP_MAX_ITEMS_PER_CALL = 8
 # Keys an MCP tool's JSON result commonly uses for a record's human title.
 _TITLE_KEYS = ("title", "name", "displayName", "subject", "summary", "key")
 
+# Keys an MCP tool's JSON result commonly uses for the optional "details" line
+# (UN-22310) — e.g. a date and an author such as "10/10/2026 - Jamie Dimon".
+# Best-effort: only top-level record keys are inspected for these (nested
+# provenance is too tool-specific to generalize). The values themselves may be
+# nested one level — a date is read as a top-level string, while an author may
+# be a plain string or an object whose name is pulled via `_AUTHOR_NAME_KEYS`
+# (e.g. Atlassian's `{"displayName": "..."}`). The line is omitted when neither
+# a date nor an author is found.
+_DETAILS_DATE_KEYS = (
+    "date",
+    "updated",
+    "updatedAt",
+    "updatedDate",
+    "lastModified",
+    "modified",
+    "created",
+    "createdAt",
+    "createdDate",
+    "timestamp",
+)
+_DETAILS_AUTHOR_KEYS = (
+    "author",
+    "creator",
+    "owner",
+    "createdBy",
+    "updatedBy",
+    "by",
+    "sender",
+    "from",
+)
+# Keys to read a human name out of an author value that is itself an object
+# (e.g. Atlassian's ``{"displayName": "Jamie Dimon"}``).
+_AUTHOR_NAME_KEYS = ("displayName", "name", "fullName", "emailAddress", "email")
+_MCP_DETAILS_CHAR_LIMIT = 200
+
 # Canonical ``toolName`` written to both manifests: the **bare advertised tool
 # name** (the payload ``name`` the agent passes to ``unique-cli mcp``).
 # ``unique-cli mcp`` only runs in skills mode, where the agent invokes a tool by
@@ -83,6 +119,39 @@ def _title_from_json(obj: dict[str, Any]) -> str | None:
     return None
 
 
+def _first_str_by_keys(obj: dict[str, Any], keys: tuple[str, ...]) -> str | None:
+    for key in keys:
+        value = obj.get(key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return None
+
+
+def _author_display(obj: dict[str, Any]) -> str | None:
+    """Read an author name from a record, whether the author value is a plain
+    string or a nested object (e.g. ``{"displayName": "..."}``)."""
+    for key in _DETAILS_AUTHOR_KEYS:
+        value = obj.get(key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+        if isinstance(value, dict):
+            name = _first_str_by_keys(value, _AUTHOR_NAME_KEYS)
+            if name:
+                return name
+    return None
+
+
+def _details_from_json(obj: dict[str, Any]) -> str | None:
+    """Best-effort optional "details" line (UN-22310): a date and/or author
+    composed as "<date> - <author>". Returns ``None`` when neither is found."""
+    date = _first_str_by_keys(obj, _DETAILS_DATE_KEYS)
+    author = _author_display(obj)
+    parts = [part for part in (date, author) if part]
+    if not parts:
+        return None
+    return " - ".join(parts)[:_MCP_DETAILS_CHAR_LIMIT]
+
+
 def _titles_from_json(text: str) -> list[dict[str, Any]]:
     """Best-effort: pull a human title out of a JSON result (object or list of
     objects), e.g. an Atlassian page/issue returned as JSON-in-text. Returns []
@@ -98,7 +167,13 @@ def _titles_from_json(text: str) -> list[dict[str, Any]]:
         if isinstance(entry, dict):
             title = _title_from_json(entry)
             if title:
-                items.append({"title": title, "snippet": None})
+                items.append(
+                    {
+                        "title": title,
+                        "snippet": None,
+                        "details": _details_from_json(entry),
+                    }
+                )
     return items
 
 
@@ -189,6 +264,12 @@ def _annotate_mcp_results_for_citations(
                     numbers_by_key[_item_dedup_key(stored_tool, entry)] = entry[
                         "sourceNumber"
                     ]
+            entries_by_number = {
+                entry["sourceNumber"]: entry
+                for entry in entries
+                if isinstance(entry.get("sourceNumber"), int)
+            }
+            needs_rewrite = False
             for item in items:
                 key = _item_dedup_key(tool_name, item)
                 source_number = numbers_by_key.get(key)
@@ -200,6 +281,7 @@ def _annotate_mcp_results_for_citations(
                         "serverName": server_name,
                         "title": item.get("title"),
                         "snippet": item.get("snippet"),
+                        "details": item.get("details"),
                     }
                     try:
                         _append_turn_refs_manifest_entry(refs_log_path, manifest_entry)
@@ -210,7 +292,25 @@ def _annotate_mcp_results_for_citations(
                         break
                     numbers_by_key[key] = source_number
                     entries.append(manifest_entry)
+                    entries_by_number[source_number] = manifest_entry
+                else:
+                    # Deduped: a prior call already claimed this source number.
+                    # Backfill ``details`` the first call may have lacked (the
+                    # runner reads one entry per source number, so enriching it
+                    # in place is sufficient) — only when newly extracted.
+                    stored = entries_by_number.get(source_number)
+                    new_details = item.get("details")
+                    if stored is not None and new_details and not stored.get("details"):
+                        stored["details"] = new_details
+                        needs_rewrite = True
                 annotated.append((source_number, item))
+            if needs_rewrite:
+                try:
+                    _rewrite_turn_refs_manifest(refs_log_path, entries)
+                except (UnsafeRefsLogPathError, OSError) as exc:
+                    _LOGGER.warning(
+                        "mcp: failed to backfill refs manifest details: %s", exc
+                    )
     except (UnsafeRefsLogPathError, OSError) as exc:
         _LOGGER.warning("mcp: failed to append refs manifest: %s", exc)
         return []
@@ -224,7 +324,12 @@ def _citation_footer(annotated: list[tuple[int, dict[str, Any]]]) -> str:
     """Tell the agent which marker to cite each retrieved item with."""
     if not annotated:
         return ""
-    lines = ["", "Sources — cite each fact with the marker for the item it came from:"]
+    lines = [
+        "",
+        "Sources — MANDATORY: every fact you take from this result MUST be "
+        "cited inline with its [mcpsourceN] marker below, or it will not be "
+        "referenced in the answer:",
+    ]
     for source_number, item in annotated:
         label = item.get("title") or "this MCP tool result"
         lines.append(f"  [mcpsource{source_number}] {label}")