Add presentation refs and snapshot compare flow

Author: ChesterRa

docs/standards/CCCS_V1.md

@@ -292,20 +292,52 @@ type AttachmentRefV1 = {
 ### 8.2 `ReferenceV1`
 
 ```ts
-type ReferenceV1 = {
-  kind?: "file" | "url" | "commit" | "text"  // default "url"
-  url?: string
-  path?: string
-  title?: string
-  sha?: string
-  bytes?: number
-  // extra fields MAY exist; clients MUST ignore unknown fields
-}
+type ReferenceV1 =
+  | {
+      kind?: "file" | "url" | "commit" | "text"  // default "url"
+      url?: string
+      path?: string
+      title?: string
+      sha?: string
+      bytes?: number
+      // extra fields MAY exist; clients MUST ignore unknown fields
+    }
+  | {
+      kind: "presentation_ref"
+      v?: 1
+      slot_id: string
+      label?: string
+      locator_label?: string
+      title?: string
+      card_type?: string
+      status?: "open" | "needs_user" | "resolved"
+      href?: string
+      excerpt?: string
+      locator?: Record<string, unknown>
+      snapshot?: {
+        path: string
+        mime_type?: string
+        bytes?: number
+        sha256?: string
+        width?: number
+        height?: number
+        captured_at?: string
+        source?: "browser_surface" | "pdf_viewer" | "viewer_dom" | string
+      }
+      // extra fields MAY exist; clients MUST ignore unknown fields
+    }
 ```
 
 **Rules**
 - Attachments SHOULD include content hashes where possible (`sha256`) to enable reproducibility/auditing.
 - `path` MUST be stable and retrievable within the group’s storage scope.
+- `kind="presentation_ref"` is a structured evidence anchor into a group Presentation slot.
+  - `slot_id` MUST identify the target slot within the group presentation surface.
+  - `locator` SHOULD carry best-effort position hints for the current view (for example page, heading, row, or scroll state).
+  - `snapshot`, when present, SHOULD be treated as a best-effort visual anchor for the quoted view.
+    - `snapshot.path` MUST be a stable group-scoped blob path.
+    - Implementations SHOULD use `locator` for precise recovery when possible, and `snapshot` as a visual fallback when precise recovery is unavailable.
+  - `status`, when present, is advisory metadata for the referenced discussion state; ledger-derived obligation status remains authoritative.
 
 ### 8.3 Attachment Resolution (Non‑Normative Guidance)
 

src/cccc/daemon/messaging/chat_ops.py

@@ -68,6 +68,7 @@ def _build_delivery_text(
     priority: str,
     reply_required: bool,
     event_id: str,
+    refs: list[dict[str, Any]],
     attachments: list[dict[str, Any]],
     src_group_id: str = "",
     src_event_id: str = "",
@@ -82,6 +83,9 @@ def _build_delivery_text(
         prefix_lines.append(f"[cccc] RELAYED FROM (group_id={src_group_id}, event_id={src_event_id}):")
     if prefix_lines:
         delivery_text = "\n".join(prefix_lines) + "\n" + delivery_text
+    ref_lines = _render_delivery_refs(refs)
+    if ref_lines:
+        delivery_text = (delivery_text.rstrip("\n") + "\n\n" + "\n".join(ref_lines)).strip()
     if attachments:
         lines = ["[cccc] Attachments:"]
         for attachment in attachments[:8]:
@@ -95,6 +99,112 @@ def _build_delivery_text(
     return delivery_text
 
 
+def _compact_delivery_text(value: Any, *, limit: int) -> str:
+    text = re.sub(r"\s+", " ", str(value or "").strip())
+    if not text:
+        return ""
+    if len(text) <= limit:
+        return text
+    return text[: max(1, limit - 1)].rstrip() + "…"
+
+
+def _presentation_slot_label(slot_id: str, label: str) -> str:
+    if label:
+        return label
+    match = re.search(r"(\d+)$", slot_id)
+    if match:
+        try:
+            return f"P{int(match.group(1))}"
+        except Exception:
+            pass
+    return slot_id or "Presentation"
+
+
+def _render_delivery_refs(refs: list[dict[str, Any]]) -> list[str]:
+    if not refs:
+        return []
+
+    lines = ["[cccc] References:"]
+    rendered = 0
+
+    for ref in refs:
+        if not isinstance(ref, dict):
+            continue
+        kind = str(ref.get("kind") or "").strip()
+        if kind == "presentation_ref":
+            slot_id = _compact_delivery_text(ref.get("slot_id"), limit=32)
+            label = _presentation_slot_label(
+                slot_id,
+                _compact_delivery_text(ref.get("label"), limit=24),
+            )
+            locator_label = _compact_delivery_text(ref.get("locator_label"), limit=48)
+            title = _compact_delivery_text(ref.get("title"), limit=72)
+            header = f"- {label}"
+            if slot_id:
+                header += f" ({slot_id})"
+            if locator_label:
+                header += f" · {locator_label}"
+            if title:
+                header += f" — {title}"
+            lines.append(header)
+            excerpt = _compact_delivery_text(ref.get("excerpt"), limit=120)
+            if excerpt:
+                lines.append(f'  excerpt: "{excerpt}"')
+            href = _compact_delivery_text(ref.get("href"), limit=120)
+            if href:
+                lines.append(f"  href: {href}")
+            locator = ref.get("locator") if isinstance(ref.get("locator"), dict) else {}
+            locator_url = _compact_delivery_text(locator.get("url"), limit=120)
+            if locator_url and locator_url != href:
+                lines.append(f"  view_url: {locator_url}")
+            captured_at = _compact_delivery_text(locator.get("captured_at"), limit=48)
+            if captured_at:
+                lines.append(f"  captured_at: {captured_at}")
+            viewer_scroll_top = locator.get("viewer_scroll_top")
+            if isinstance(viewer_scroll_top, (int, float)) or str(viewer_scroll_top or "").strip():
+                try:
+                    scroll_value = int(float(viewer_scroll_top))
+                except Exception:
+                    scroll_value = None
+                if scroll_value is not None and scroll_value >= 0:
+                    lines.append(f"  scroll_top: {scroll_value}")
+            snapshot = ref.get("snapshot") if isinstance(ref.get("snapshot"), dict) else {}
+            snapshot_path = _compact_delivery_text(snapshot.get("path"), limit=120)
+            if snapshot_path:
+                width = snapshot.get("width")
+                height = snapshot.get("height")
+                size_label = ""
+                try:
+                    width_value = int(width)
+                    height_value = int(height)
+                    if width_value > 0 and height_value > 0:
+                        size_label = f" ({width_value}x{height_value})"
+                except Exception:
+                    size_label = ""
+                lines.append(f"  snapshot: {snapshot_path}{size_label}")
+            rendered += 1
+            if rendered >= 4:
+                break
+            continue
+
+        summary = _compact_delivery_text(
+            ref.get("title") or ref.get("path") or ref.get("url") or kind,
+            limit=96,
+        )
+        if summary:
+            prefix = kind or "ref"
+            lines.append(f"- {prefix}: {summary}")
+            rendered += 1
+        if rendered >= 4:
+            break
+
+    if rendered == 0:
+        return []
+    if len(refs) > rendered:
+        lines.append(f"- … ({len(refs) - rendered} more)")
+    return lines
+
+
 def _touch_registry_updated_at(group_id: str, ts: str) -> None:
     try:
         reg = load_registry()
@@ -106,6 +216,16 @@ def _touch_registry_updated_at(group_id: str, ts: str) -> None:
         pass
 
 
+def _normalize_refs(raw: Any) -> list[dict[str, Any]]:
+    if not isinstance(raw, list):
+        return []
+    refs: list[dict[str, Any]] = []
+    for item in raw:
+        if isinstance(item, dict):
+            refs.append(item)
+    return refs
+
+
 def _notify_headless_targets(
     *,
     group: Any,
@@ -269,6 +389,7 @@ def handle_send(
         attachments = normalize_attachments(group, args.get("attachments"))
     except Exception as e:
         return _error("invalid_attachments", str(e))
+    refs = _normalize_refs(args.get("refs"))
 
     if not text.strip() and not attachments:
         return _error("empty_message", "message text cannot be empty")
@@ -285,6 +406,7 @@ def handle_send(
             priority=priority,
             reply_required=reply_required,
             to=to,
+            refs=refs,
             attachments=attachments,
             source_platform=source_platform or None,
             source_user_name=source_user_name or None,
@@ -307,6 +429,7 @@ def handle_send(
         priority=priority,
         reply_required=reply_required,
         event_id=event_id,
+        refs=refs,
         attachments=attachments,
         src_group_id=src_group_id,
         src_event_id=src_event_id,
@@ -447,6 +570,7 @@ def handle_reply(
         attachments = normalize_attachments(group, args.get("attachments"))
     except Exception as e:
         return _error("invalid_attachments", str(e))
+    refs = _normalize_refs(args.get("refs"))
     if not text.strip() and not attachments:
         return _error("empty_message", "message text cannot be empty")
 
@@ -464,6 +588,7 @@ def handle_reply(
             to=to,
             reply_to=reply_to,
             quote_text=quote_text,
+            refs=refs,
             attachments=attachments,
             source_platform=original_source_platform or None,
             source_user_name=original_source_user_name or None,
@@ -508,6 +633,7 @@ def handle_reply(
         priority=priority,
         reply_required=reply_required,
         event_id=event_id,
+        refs=refs,
         attachments=attachments,
     )
     for actor in list_actors(group):

src/cccc/daemon/ops/maintenance_ops.py

@@ -98,6 +98,9 @@ def handle_send_cross_group(
     attachments_raw = args.get("attachments")
     if attachments_raw:
         return _error("attachments_not_supported", "attachments are not supported for cross-group messages yet")
+    refs_raw = args.get("refs")
+    if isinstance(refs_raw, list) and any(isinstance(item, dict) for item in refs_raw):
+        return _error("refs_not_supported", "quoted refs are not supported for cross-group messages yet")
     if priority not in ("normal", "attention"):
         return _error("invalid_priority", "priority must be 'normal' or 'attention'")
     if not src_group_id:

src/cccc/ports/mcp/handlers/cccc_messaging.py

@@ -43,6 +43,7 @@ def message_send(
     to: Optional[List[str]] = None,
     priority: str = "normal",
     reply_required: bool = False,
+    refs: Optional[List[Dict[str, Any]]] = None,
 ) -> Dict[str, Any]:
     """Send a message to the group (or cross-group)."""
     text = _normalize_runtime_escaped_text(group_id=group_id, actor_id=actor_id, text=text)
@@ -64,6 +65,7 @@ def message_send(
                     "to": to if to is not None else [],
                     "priority": prio,
                     "reply_required": reply_required_flag,
+                    "refs": refs if refs is not None else [],
                 },
             }
         )
@@ -79,6 +81,7 @@ def message_send(
                 "path": "",
                 "priority": prio,
                 "reply_required": reply_required_flag,
+                "refs": refs if refs is not None else [],
             },
         }
     )
@@ -93,6 +96,7 @@ def message_reply(
     to: Optional[List[str]] = None,
     priority: str = "normal",
     reply_required: bool = False,
+    refs: Optional[List[Dict[str, Any]]] = None,
 ) -> Dict[str, Any]:
     """Reply to a message."""
     if not str(reply_to or "").strip():
@@ -113,6 +117,7 @@ def message_reply(
                 "to": to if to is not None else [],
                 "priority": prio,
                 "reply_required": reply_required_flag,
+                "refs": refs if refs is not None else [],
             },
         }
     )

src/cccc/ports/mcp/server.py

@@ -281,12 +281,14 @@ def _handle_cccc_namespace(name: str, arguments: Dict[str, Any]) -> Optional[Dic
         gid = _resolve_group_id(arguments)
         aid = _resolve_self_actor_id(arguments)
         to_raw = arguments.get("to")
+        refs_raw = arguments.get("refs")
         if isinstance(to_raw, list):
             to_val: Optional[List[str]] = [str(x).strip() for x in to_raw if str(x).strip()]
         elif isinstance(to_raw, str) and to_raw.strip():
             to_val = [to_raw.strip()]
         else:
             to_val = None
+        refs_val = [item for item in refs_raw if isinstance(item, dict)] if isinstance(refs_raw, list) else None
         return message_send(
             group_id=gid,
             dst_group_id=arguments.get("dst_group_id"),
@@ -295,18 +297,21 @@ def _handle_cccc_namespace(name: str, arguments: Dict[str, Any]) -> Optional[Dic
             to=to_val,
             priority=str(arguments.get("priority") or "normal"),
             reply_required=coerce_bool(arguments.get("reply_required"), default=False),
+            refs=refs_val,
         )
 
     if name == "cccc_message_reply":
         gid = _resolve_group_id(arguments)
         aid = _resolve_self_actor_id(arguments)
         to_raw = arguments.get("to")
+        refs_raw = arguments.get("refs")
         if isinstance(to_raw, list):
             to_val_reply: Optional[List[str]] = [str(x).strip() for x in to_raw if str(x).strip()]
         elif isinstance(to_raw, str) and to_raw.strip():
             to_val_reply = [to_raw.strip()]
         else:
             to_val_reply = None
+        refs_val_reply = [item for item in refs_raw if isinstance(item, dict)] if isinstance(refs_raw, list) else None
         reply_to = str(arguments.get("event_id") or arguments.get("reply_to") or "").strip()
         return message_reply(
             group_id=gid,
@@ -316,6 +321,7 @@ def _handle_cccc_namespace(name: str, arguments: Dict[str, Any]) -> Optional[Dic
             to=to_val_reply,
             priority=str(arguments.get("priority") or "normal"),
             reply_required=coerce_bool(arguments.get("reply_required"), default=False),
+            refs=refs_val_reply,
         )
 
     if name == "cccc_file":

src/cccc/ports/mcp/toolspecs.py

@@ -118,6 +118,7 @@ def _obj(properties: dict, required: list[str] | None = None) -> dict:
                 },
                 "priority": {"type": "string", "enum": ["normal", "attention"], "default": "normal"},
                 "reply_required": {"type": "boolean", "default": False},
+                "refs": {"type": "array", "items": {"type": "object"}},
             },
             required=["text"],
         ),
@@ -140,6 +141,7 @@ def _obj(properties: dict, required: list[str] | None = None) -> dict:
                 },
                 "priority": {"type": "string", "enum": ["normal", "attention"], "default": "normal"},
                 "reply_required": {"type": "boolean", "default": False},
+                "refs": {"type": "array", "items": {"type": "object"}},
             },
             required=["text"],
         ),