From 957e57bb82b8c71e627640a6fe32912a0532c761 Mon Sep 17 00:00:00 2001
From: CREDO23 <bakerathierry@gmail.com>
Date: Wed, 22 Jul 2026 19:34:56 +0200
Subject: [PATCH] feat: register a scraper run as a citation

---
 .../capabilities/core/access/run_citation.py  | 23 +++++++++++++++++++
 1 file changed, 23 insertions(+)
 create mode 100644 surfsense_backend/app/capabilities/core/access/run_citation.py

diff --git a/surfsense_backend/app/capabilities/core/access/run_citation.py b/surfsense_backend/app/capabilities/core/access/run_citation.py
new file mode 100644
index 000000000..9b7c3f3db
--- /dev/null
+++ b/surfsense_backend/app/capabilities/core/access/run_citation.py
@@ -0,0 +1,23 @@
+"""Register a recorded scraper run as a citable ``[n]``."""
+
+from __future__ import annotations
+
+from app.agents.chat.multi_agent_chat.shared.citations import (
+    CitationRegistry,
+    CitationSourceType,
+)
+
+
+def attach_run_citation(
+    registry: CitationRegistry,
+    *,
+    run_external_id: str,
+    capability: str,
+) -> tuple[int, str]:
+    """Register the ``run_<uuid>`` handle; return its ``[n]`` and the label line."""
+    n = registry.register(
+        CitationSourceType.RUN,
+        {"run_id": run_external_id},
+        {"capability": capability},
+    )
+    return n, f"\n\nCite this scraper run as [{n}] after any claim drawn from its data."