claude-smart 0.2.45 → 0.2.47

package/plugin/vendor/reflexio/reflexio/server/services/playbook/{playbook_aggregator.py → components/aggregator.py}

@@ -4,6 +4,7 @@ import hashlib
 import logging
 import os
 import time
+import uuid
 from collections.abc import Sequence
 from typing import TYPE_CHECKING
 
@@ -12,13 +13,9 @@ if TYPE_CHECKING:
 
 from reflexio.models.api_schema.service_schemas import (
     AgentPlaybook,
-    AgentPlaybookSnapshot,
     AgentPlaybookSourceWindow,
-    AgentPlaybookUpdateEntry,
-    PlaybookAggregationChangeLog,
     PlaybookStatus,
     UserPlaybook,
-    agent_playbook_to_snapshot,
 )
 from reflexio.models.config_schema import (
     SINGLETON_USER_PLAYBOOK_NAME,
@@ -27,15 +24,21 @@ from reflexio.models.config_schema import (
 from reflexio.server.api_endpoints.request_context import RequestContext
 from reflexio.server.llm.litellm_client import LiteLLMClient
 from reflexio.server.services.operation_state_utils import OperationStateManager
+from reflexio.server.services.playbook.aggregation_prompt_processing import (
+    AggregationPromptProcessingContext,
+    AggregationPromptProcessor,
+)
 from reflexio.server.services.playbook.playbook_service_constants import (
     PlaybookServiceConstants,
 )
 from reflexio.server.services.playbook.playbook_service_utils import (
     PlaybookAggregationOutput,
     PlaybookAggregatorRequest,
+    StructuredPlaybookContent,
     ensure_playbook_content,
 )
 from reflexio.server.services.service_utils import log_model_response
+from reflexio.server.tracing import capture_anomaly, sentry_tags
 from reflexio.server.usage_metrics import record_usage_event
 
 logger = logging.getLogger(__name__)
@@ -52,17 +55,25 @@ class PlaybookAggregator:
         llm_client: LiteLLMClient,
         request_context: RequestContext,
         agent_version: str,
+        aggregation_prompt_processor: AggregationPromptProcessor | None = None,
     ) -> None:
         self.client = llm_client
         self.storage = request_context.storage
         self.configurator = request_context.configurator
         self.request_context = request_context
         self.agent_version = agent_version
+        self.aggregation_prompt_processor = aggregation_prompt_processor
 
     # ===============================
     # private methods - operation state
     # ===============================
 
+    @staticmethod
+    def _format_prompt_extra_instructions(instructions: str | None) -> str:
+        if not instructions or not instructions.strip():
+            return ""
+        return f"{instructions.strip()}\n"
+
     def _create_state_manager(self) -> OperationStateManager:
         """
         Create an OperationStateManager for the playbook aggregator.
@@ -103,7 +114,7 @@ class PlaybookAggregator:
         # Count user playbooks with ID greater than last processed using efficient count query
         # Only count current user playbooks (status=None), not archived or pending ones.
         # Singleton aggregation operates on the user's whole playbook set — no name filter.
-        new_count = self.storage.count_user_playbooks(  # type: ignore[reportOptionalMemberAccess]
+        new_count = self.storage.count_user_playbooks(  # pyright: ignore[reportOptionalMemberAccess]
             min_user_playbook_id=last_processed_id,
             agent_version=self.agent_version,
             status_filter=[None],
@@ -194,6 +205,98 @@ class PlaybookAggregator:
             blocks.append("\n".join(lines))
         return "\n\n".join(blocks) if blocks else "(No playbook items)"
 
+    def _preprocess_prompt_field(
+        self,
+        text: str | None,
+        shared_state: dict[str, object],
+        processing_context: AggregationPromptProcessingContext | None = None,
+    ) -> str | None:
+        if text is None or self.aggregation_prompt_processor is None:
+            return text
+        result = self.aggregation_prompt_processor.preprocess_prompt_text(
+            text,
+            shared_state=shared_state,
+            context=processing_context,
+        )
+        if processing_context is not None and (result.changed or result.text != text):
+            processing_context.changed = True
+        return result.text
+
+    def _preprocess_user_playbook_for_prompt(
+        self,
+        playbook: UserPlaybook,
+        shared_state: dict[str, object],
+        processing_context: AggregationPromptProcessingContext | None = None,
+    ) -> UserPlaybook:
+        if self.aggregation_prompt_processor is None:
+            return playbook
+        return playbook.model_copy(
+            update={
+                "content": self._preprocess_prompt_field(
+                    playbook.content, shared_state, processing_context
+                )
+                or "",
+                "trigger": self._preprocess_prompt_field(
+                    playbook.trigger, shared_state, processing_context
+                ),
+                "rationale": self._preprocess_prompt_field(
+                    playbook.rationale, shared_state, processing_context
+                ),
+            }
+        )
+
+    def _aggregation_prompt_extra_instructions_for_context(
+        self,
+        processing_context: AggregationPromptProcessingContext | None,
+    ) -> str:
+        if (
+            processing_context is None
+            or not processing_context.changed
+            or self.aggregation_prompt_processor is None
+        ):
+            return ""
+
+        context_instructions = self.aggregation_prompt_processor.prompt_instructions(
+            processing_context
+        )
+        if not isinstance(context_instructions, str):
+            context_instructions = None
+        return self._format_prompt_extra_instructions(context_instructions)
+
+    def _postprocess_aggregation_output(
+        self,
+        value: object,
+        processing_context: AggregationPromptProcessingContext | None = None,
+    ) -> tuple[object, int]:
+        if self.aggregation_prompt_processor is None:
+            return value, 0
+        result = self.aggregation_prompt_processor.postprocess_aggregation_output(
+            value,
+            context=processing_context,
+        )
+        return result.value, result.artifacts_removed
+
+    def _postprocess_aggregation_response(
+        self,
+        response: PlaybookAggregationOutput,
+        processing_context: AggregationPromptProcessingContext | None = None,
+    ) -> tuple[PlaybookAggregationOutput, int]:
+        processed, artifact_count = self._postprocess_aggregation_output(
+            response,
+            processing_context,
+        )
+        if not isinstance(processed, PlaybookAggregationOutput):
+            return response, 0
+        return processed, artifact_count
+
+    def _record_postprocessing_artifacts(self, artifact_count: int) -> None:
+        if artifact_count <= 0:
+            return
+        logger.warning(
+            "Post-processed %d residual artifacts in aggregated playbook output",
+            artifact_count,
+        )
+
     @staticmethod
     def _get_direction_key(fb: UserPlaybook) -> str:
         """
@@ -465,102 +568,6 @@ class PlaybookAggregator:
 
         return changed_clusters, playbook_ids_to_archive
 
-    def _build_change_log(
-        self,
-        playbook_name: str,
-        full_archive: bool,
-        before_playbooks_by_id: dict[int, AgentPlaybook],
-        saved_playbooks: list[AgentPlaybook],
-        archived_playbook_ids: list[int],
-        prev_fingerprints: dict,
-    ) -> PlaybookAggregationChangeLog:
-        """Build a PlaybookAggregationChangeLog from the aggregation run results.
-
-        Args:
-            playbook_name: The playbook name being aggregated
-            full_archive: Whether this was a full archive (rerun/first run)
-            before_playbooks_by_id: Snapshot of playbooks before archiving, keyed by playbook_id
-            saved_playbooks: Newly saved playbooks from this run
-            archived_playbook_ids: AgentPlaybook IDs that were selectively archived (incremental mode)
-            prev_fingerprints: Previous cluster fingerprints (empty for full archive)
-
-        Returns:
-            PlaybookAggregationChangeLog with added/removed/updated lists populated
-        """
-        added: list[AgentPlaybookSnapshot] = []
-        removed: list[AgentPlaybookSnapshot] = []
-        updated: list[AgentPlaybookUpdateEntry] = []
-
-        if full_archive:
-            # No 1:1 mapping — all old playbooks are removed, all new are added
-            removed = [
-                agent_playbook_to_snapshot(fb) for fb in before_playbooks_by_id.values()
-            ]
-            added = [agent_playbook_to_snapshot(fb) for fb in saved_playbooks if fb]
-        else:
-            # Incremental mode: map old playbook_ids to new playbooks via fingerprints
-            # Build a set of old playbook_ids that were archived
-            archived_id_set = set(archived_playbook_ids)
-
-            # Build mapping: old_playbook_id -> new_playbook_id via fingerprint changes
-            # prev_fingerprints maps fp_hash -> {playbook_id, user_playbook_ids}
-            # new_fingerprints maps fp_hash -> {playbook_id, user_playbook_ids}
-            # If an old fingerprint disappeared and a new one appeared, and
-            # the old fp had a playbook_id in archived_id_set, we can try to pair them.
-            # However, without a direct cluster-level old->new mapping, we use a simpler approach:
-            # archived playbooks that have a corresponding new playbook (by position in saved list) are updates.
-
-            # Collect old playbook_ids from disappeared fingerprints
-            old_fp_playbook_ids = {}
-            for fp, fp_data in prev_fingerprints.items():
-                fid = fp_data.get("agent_playbook_id")
-                if fid is not None and fid in archived_id_set:
-                    old_fp_playbook_ids[fid] = fp
-
-            # For each saved playbook, try to match with an archived old playbook
-            matched_old_ids: set[int] = set()
-            for saved_fb in saved_playbooks:
-                if not saved_fb:
-                    continue
-                # Try to find an old playbook from the archived set to pair with
-                paired_old_id = None
-                for old_id in list(old_fp_playbook_ids.keys()):
-                    if old_id not in matched_old_ids:
-                        paired_old_id = old_id
-                        matched_old_ids.add(old_id)
-                        break
-
-                if (
-                    paired_old_id is not None
-                    and paired_old_id in before_playbooks_by_id
-                ):
-                    updated.append(
-                        AgentPlaybookUpdateEntry(
-                            before=agent_playbook_to_snapshot(
-                                before_playbooks_by_id[paired_old_id]
-                            ),
-                            after=agent_playbook_to_snapshot(saved_fb),
-                        )
-                    )
-                else:
-                    added.append(agent_playbook_to_snapshot(saved_fb))
-
-            # Remaining archived playbooks that weren't paired are removals
-            for old_id in archived_id_set:
-                if old_id not in matched_old_ids and old_id in before_playbooks_by_id:
-                    removed.append(
-                        agent_playbook_to_snapshot(before_playbooks_by_id[old_id])
-                    )
-
-        return PlaybookAggregationChangeLog(
-            playbook_name=playbook_name,
-            agent_version=self.agent_version,
-            run_mode="full_archive" if full_archive else "incremental",
-            added_agent_playbooks=added,
-            removed_agent_playbooks=removed,
-            updated_agent_playbooks=updated,
-        )
-
     # ===============================
     # public methods
     # ===============================
@@ -572,6 +579,8 @@ class PlaybookAggregator:
             dict: Aggregation stats with keys: clusters_found, user_playbooks_processed, playbooks_generated, skipped (optional)
         """
         aggregation_start = time.perf_counter()
+        # Stable id for this aggregation run — groups all lineage events produced below.
+        _run_id = str(uuid.uuid4())
         _empty_stats = {
             "clusters_found": 0,
             "user_playbooks_processed": 0,
@@ -667,6 +676,12 @@ class PlaybookAggregator:
             playbook_name,
             self.agent_version,
         )
+        logger.info(
+            "Aggregation prompt processor: %s",
+            type(self.aggregation_prompt_processor).__name__
+            if self.aggregation_prompt_processor is not None
+            else "disabled",
+        )
 
         # Get existing APPROVED and PENDING playbooks before archiving (to pass to LLM for deduplication).
         # Singleton aggregation pulls the user's whole set — no name filter.
@@ -694,11 +709,6 @@ class PlaybookAggregator:
         )
         clusters = self.get_clusters(user_playbooks, playbook_aggregator_config)
 
-        # Capture all current playbooks before archiving (for change log)
-        before_playbooks_by_id: dict[int, AgentPlaybook] = {
-            fb.agent_playbook_id: fb for fb in existing_playbooks
-        }
-
         # Determine which clusters changed (skip for rerun)
         mgr = self._create_state_manager()
         archived_playbook_ids = []
@@ -764,10 +774,6 @@ class PlaybookAggregator:
                     len(archived_playbook_ids),
                 )
 
-                # Selectively archive only playbooks from changed/disappeared clusters
-                if archived_playbook_ids:
-                    self.storage.archive_agent_playbooks_by_ids(archived_playbook_ids)  # type: ignore[reportOptionalMemberAccess]
-
         try:
             # Emit the started event inside the protected block so any failure
             # from here on is paired with an aggregation_failed event.
@@ -789,6 +795,37 @@ class PlaybookAggregator:
             )
             new_playbooks = [playbook for playbook, _ in generated_pairs]
 
+            previous_fingerprints_for_changed_clusters = {}
+            changed_fps_by_previous_fp = {}
+            changed_fps_with_replacements = set()
+            previous_playbook_id_by_fp = {}
+            if not playbook_aggregator_request.rerun and prev_fingerprints:
+                for cluster_playbooks in changed_clusters.values():
+                    fp = self._compute_cluster_fingerprint(cluster_playbooks)
+                    current_user_ids = {
+                        fb.user_playbook_id
+                        for fb in cluster_playbooks
+                        if fb.user_playbook_id is not None
+                    }
+                    matched_prev_fingerprints = {
+                        prev_fp: fp_data
+                        for prev_fp, fp_data in prev_fingerprints.items()
+                        if fp_data.get("agent_playbook_id") is not None
+                        and current_user_ids
+                        & set(fp_data.get("user_playbook_ids") or [])
+                    }
+                    if matched_prev_fingerprints:
+                        previous_fingerprints_for_changed_clusters[fp] = (
+                            matched_prev_fingerprints
+                        )
+                        for prev_fp, fp_data in matched_prev_fingerprints.items():
+                            changed_fps_by_previous_fp.setdefault(prev_fp, set()).add(
+                                fp
+                            )
+                            playbook_id = fp_data.get("agent_playbook_id")
+                            if playbook_id is not None:
+                                previous_playbook_id_by_fp[prev_fp] = playbook_id
+
             # Lazy archive: only full-archive when the LLM produced replacements.
             # Skipping the archive when new_playbooks is empty preserves existing
             # PENDING/APPROVED playbooks that the LLM identified as duplicates.
@@ -806,17 +843,12 @@ class PlaybookAggregator:
                     )
                     full_archive = False
 
-            # Save playbooks (returns playbooks with playbook_id populated)
-            saved_playbooks = self.storage.save_agent_playbooks(new_playbooks)  # type: ignore[reportOptionalMemberAccess]
-
             # Build new fingerprint state
             new_fingerprints = {}
 
             if not playbook_aggregator_request.rerun:
                 # Carry forward unchanged fingerprints from previous state
-                prev_fps = mgr.get_cluster_fingerprints(
-                    name=playbook_name, version=self.agent_version
-                )
+                prev_fps = prev_fingerprints
                 current_fp_set = set()
                 for cluster_playbooks in clusters.values():
                     fp = self._compute_cluster_fingerprint(cluster_playbooks)
@@ -837,31 +869,47 @@ class PlaybookAggregator:
                     }
                 )
 
-            # Initialize changed cluster fingerprints before assigning saved IDs
-            # below. ``generated_pairs`` preserves the exact source cluster for
-            # every non-duplicate playbook the LLM produced.
-            for cluster_playbooks in changed_clusters.values():
-                fp = self._compute_cluster_fingerprint(cluster_playbooks)
-                raw_ids = sorted(fb.user_playbook_id for fb in cluster_playbooks)
-
-                new_fingerprints[fp] = {
-                    "agent_playbook_id": None,
-                    "user_playbook_ids": raw_ids,
-                }
-
-            saved_playbook_list = list(saved_playbooks)
-
-            # Assign saved playbook ids to the exact source cluster that generated them.
-            for saved_fb, (_, cluster_playbooks) in zip(
-                saved_playbook_list, generated_pairs, strict=False
-            ):
+            saved_playbook_list: list[AgentPlaybook] = []
+            selective_supersede_playbook_ids = set()
+            replaced_previous_fingerprints = set()
+
+            # Save each playbook + its aggregate event atomically, then assign
+            # fingerprints and source-windows for the saved row.
+            for playbook, cluster_playbooks in generated_pairs:
+                run_mode = "full_archive" if full_archive else "incremental"
+                member_ids = [
+                    str(fb.user_playbook_id)
+                    for fb in cluster_playbooks
+                    if fb.user_playbook_id
+                ]
+                saved_fb = self.storage.save_agent_playbook_with_aggregate_event(  # type: ignore[reportOptionalMemberAccess]
+                    playbook,
+                    source_ids=member_ids,
+                    request_id=_run_id,
+                    run_mode=run_mode,
+                )
+                saved_playbook_list.append(saved_fb)
                 if saved_fb and saved_fb.agent_playbook_id:
                     fp_key = self._compute_cluster_fingerprint(cluster_playbooks)
+                    changed_fps_with_replacements.add(fp_key)
                     raw_ids = sorted(fb.user_playbook_id for fb in cluster_playbooks)
                     new_fingerprints[fp_key] = {
                         "agent_playbook_id": saved_fb.agent_playbook_id,
                         "user_playbook_ids": raw_ids,
                     }
+                    for prev_fp in previous_fingerprints_for_changed_clusters.get(
+                        fp_key, {}
+                    ):
+                        all_overlapping_clusters_replaced = (
+                            changed_fps_by_previous_fp.get(prev_fp, set()).issubset(
+                                changed_fps_with_replacements
+                            )
+                        )
+                        playbook_id = previous_playbook_id_by_fp.get(prev_fp)
+                        if all_overlapping_clusters_replaced:
+                            replaced_previous_fingerprints.add(prev_fp)
+                            if playbook_id is not None:
+                                selective_supersede_playbook_ids.add(playbook_id)
                     self.storage.set_source_windows_for_agent_playbook(  # type: ignore[reportOptionalMemberAccess]
                         saved_fb.agent_playbook_id,
                         [
@@ -876,6 +924,33 @@ class PlaybookAggregator:
                         ],
                     )
 
+            # Changed clusters that did not get a replacement keep their previous
+            # fingerprint/playbook mapping so a later successful replacement can
+            # supersede the old playbook. Brand-new duplicate clusters still get
+            # a None marker to avoid repeated LLM calls for the same fingerprint.
+            for cluster_playbooks in changed_clusters.values():
+                fp = self._compute_cluster_fingerprint(cluster_playbooks)
+                if fp in new_fingerprints:
+                    continue
+
+                previous_for_cluster = previous_fingerprints_for_changed_clusters.get(
+                    fp, {}
+                )
+                preserved_previous = {
+                    prev_fp: fp_data
+                    for prev_fp, fp_data in previous_for_cluster.items()
+                    if prev_fp not in replaced_previous_fingerprints
+                }
+                if preserved_previous:
+                    new_fingerprints.update(preserved_previous)
+                    continue
+
+                raw_ids = sorted(fb.user_playbook_id for fb in cluster_playbooks)
+                new_fingerprints[fp] = {
+                    "agent_playbook_id": None,
+                    "user_playbook_ids": raw_ids,
+                }
+
             # Store fingerprints in operation state
             mgr.update_cluster_fingerprints(
                 name=playbook_name,
@@ -886,39 +961,70 @@ class PlaybookAggregator:
             # Update operation state with the highest user_playbook_id processed
             self._update_operation_state(playbook_name, user_playbooks)
 
-            # Build and save change log
-            try:
-                change_log = self._build_change_log(
-                    playbook_name=playbook_name,
-                    full_archive=full_archive,
-                    before_playbooks_by_id=before_playbooks_by_id,
-                    saved_playbooks=saved_playbook_list,
-                    archived_playbook_ids=archived_playbook_ids,
-                    prev_fingerprints=(prev_fingerprints if not full_archive else {}),
-                )
-                self.storage.add_playbook_aggregation_change_log(change_log)  # type: ignore[reportOptionalMemberAccess]
-                logger.info(
-                    "User playbook aggregation change log for '%s' (agent_version=%s): %d agent playbooks added, %d removed, %d updated",
-                    playbook_name,
-                    self.agent_version,
-                    len(change_log.added_agent_playbooks),
-                    len(change_log.removed_agent_playbooks),
-                    len(change_log.updated_agent_playbooks),
-                )
-            except Exception:
-                logger.exception(
-                    "Failed to save playbook aggregation change log for '%s', continuing",
-                    playbook_name,
+            # Remove archived playbooks after successful aggregation. ALWAYS soft-supersede
+            # (never hard-delete) so the removal is reconstructable from lineage — mirrors the
+            # profile dedup always-soft path (#206).
+            archived_ids_without_overlapping_changed_cluster: set[int] = set()
+            if new_playbooks and prev_fingerprints:
+                archived_id_set = set(archived_playbook_ids)
+                for prev_fp, fp_data in prev_fingerprints.items():
+                    playbook_id = fp_data.get("agent_playbook_id")
+                    if (
+                        playbook_id in archived_id_set
+                        and prev_fp not in changed_fps_by_previous_fp
+                    ):
+                        archived_ids_without_overlapping_changed_cluster.add(
+                            playbook_id
+                        )
+            ids_to_supersede = {
+                *selective_supersede_playbook_ids,
+                *archived_ids_without_overlapping_changed_cluster,
+            }
+            if not _run_id:
+                # Empty request_id makes the removal unreconstructable (lineage events are keyed
+                # on it). Fail loud and skip removal — never silently hard-delete.
+                capture_anomaly(
+                    "lineage.aggregation.missing_request_id",
+                    level="error",
+                    org_id=self.request_context.org_id,
                 )
-
-            # Delete archived playbooks after successful aggregation
-            if full_archive:
-                for name in full_archive_playbook_names:
-                    self.storage.delete_archived_agent_playbooks_by_playbook_name(  # type: ignore[reportOptionalMemberAccess]
-                        name, agent_version=self.agent_version
+            else:
+                try:
+                    if full_archive:
+                        for name in full_archive_playbook_names:
+                            self.storage.supersede_agent_playbooks_by_playbook_name(  # type: ignore[reportOptionalMemberAccess]
+                                name,
+                                agent_version=self.agent_version,
+                                request_id=_run_id,
+                            )
+                    elif ids_to_supersede:
+                        self.storage.supersede_agent_playbooks_by_ids(  # type: ignore[reportOptionalMemberAccess]
+                            sorted(ids_to_supersede),
+                            request_id=_run_id,
+                        )
+                    elif archived_playbook_ids:
+                        logger.info(
+                            "Skipping selective supersede of %s (agent_version=%s): LLM produced 0 new playbooks; existing PENDING/APPROVED playbooks preserved",
+                            archived_playbook_ids,
+                            self.agent_version,
+                        )
+                except Exception:
+                    with sentry_tags(
+                        subsystem="playbook_aggregation",
+                        op="supersede_agent_playbooks",
+                        org_id=self.request_context.org_id,
+                        request_id=_run_id,
+                    ):
+                        logger.exception(
+                            "Failed to soft-supersede archived agent playbooks (run %s)",
+                            _run_id,
+                        )
+                    capture_anomaly(
+                        "lineage.aggregation.supersede_failed",
+                        level="error",
+                        org_id=self.request_context.org_id,
+                        request_id=_run_id,
                     )
-            elif archived_playbook_ids:
-                self.storage.delete_agent_playbooks_by_ids(archived_playbook_ids)  # type: ignore[reportOptionalMemberAccess]
 
             self._enqueue_playbook_optimization(saved_playbook_list)
 
@@ -1197,19 +1303,35 @@ class PlaybookAggregator:
         direction_overlap_threshold: float = 0.6,
     ) -> list[tuple[AgentPlaybook, list[UserPlaybook]]]:
         """Generate agent playbooks while preserving their exact source cluster."""
-        # Format existing approved playbooks for the prompt
+        new_playbooks: list[tuple[AgentPlaybook, list[UserPlaybook]]] = []
         approved_playbooks_str = (
             "\n".join([f"- {fb.content}" for fb in existing_approved_playbooks])
             if existing_approved_playbooks
             else "None"
         )
-
-        new_playbooks: list[tuple[AgentPlaybook, list[UserPlaybook]]] = []
         for cluster_playbooks in clusters.values():
+            shared_state: dict[str, object] = {}
+            processing_context = AggregationPromptProcessingContext(
+                data={
+                    "agent_version": self.agent_version,
+                    "org_id": self.request_context.org_id,
+                }
+            )
+            if self.aggregation_prompt_processor is None:
+                prompt_cluster_playbooks = cluster_playbooks
+            else:
+                prompt_cluster_playbooks = [
+                    self._preprocess_user_playbook_for_prompt(
+                        playbook, shared_state, processing_context
+                    )
+                    for playbook in cluster_playbooks
+                ]
+
             playbook = self._generate_playbook_from_cluster(
-                cluster_playbooks,
+                prompt_cluster_playbooks,
                 approved_playbooks_str,
                 direction_overlap_threshold=direction_overlap_threshold,
+                processing_context=processing_context,
             )
             if playbook is not None:
                 new_playbooks.append((playbook, cluster_playbooks))
@@ -1259,6 +1381,7 @@ class PlaybookAggregator:
         cluster_playbooks: list[UserPlaybook],
         existing_approved_playbooks_str: str,
         direction_overlap_threshold: float = 0.6,
+        processing_context: AggregationPromptProcessingContext | None = None,
     ) -> AgentPlaybook | None:
         """
         Generate a playbook from a cluster using structured JSON output.
@@ -1289,14 +1412,21 @@ class PlaybookAggregator:
             # Build content directly as a freeform summary
             content_text = f"When {trigger}, {first_content}."
 
-            return AgentPlaybook(
-                playbook_name=cluster_playbooks[0].playbook_name,
-                agent_version=cluster_playbooks[0].agent_version,
-                content=content_text,
-                trigger=trigger,
-                playbook_status=PlaybookStatus.PENDING,
-                playbook_metadata="mock_generated",
+            response = PlaybookAggregationOutput(
+                playbook=StructuredPlaybookContent(
+                    content=content_text,
+                    trigger=trigger,
+                )
             )
+            response, artifact_count = self._postprocess_aggregation_response(
+                response,
+                processing_context,
+            )
+            self._record_postprocessing_artifacts(artifact_count)
+            playbook = self._process_aggregation_response(response, cluster_playbooks)
+            if playbook is None:
+                return None
+            return playbook.model_copy(update={"playbook_metadata": "mock_generated"})
 
         # Format raw playbooks for prompt using structured format
         raw_playbooks_str = self._format_structured_cluster_input(
@@ -1312,6 +1442,9 @@ class PlaybookAggregator:
                     {
                         "user_playbooks": raw_playbooks_str,
                         "existing_approved_playbooks": existing_approved_playbooks_str,
+                        "aggregation_prompt_extra_instructions": self._aggregation_prompt_extra_instructions_for_context(
+                            processing_context
+                        ),
                     },
                 ),
             }
@@ -1324,6 +1457,18 @@ class PlaybookAggregator:
                 response_format=PlaybookAggregationOutput,
                 parse_structured_output=True,
             )
+            if isinstance(response, PlaybookAggregationOutput):
+                response, artifact_count = self._postprocess_aggregation_response(
+                    response,
+                    processing_context,
+                )
+                self._record_postprocessing_artifacts(artifact_count)
+            else:
+                response, artifact_count = self._postprocess_aggregation_output(
+                    response,
+                    processing_context,
+                )
+                self._record_postprocessing_artifacts(artifact_count)
             log_model_response(logger, "Aggregation structured response", response)
 
             if not isinstance(response, PlaybookAggregationOutput):
@@ -1335,9 +1480,14 @@ class PlaybookAggregator:
 
             return self._process_aggregation_response(response, cluster_playbooks)
         except Exception as exc:
+            processed_error, artifact_count = self._postprocess_aggregation_output(
+                str(exc),
+                processing_context,
+            )
+            self._record_postprocessing_artifacts(artifact_count)
             logger.error(
                 "AgentPlaybook aggregation failed due to %s, returning None.",
-                str(exc),
+                processed_error,
             )
             return None
 
@@ -1349,7 +1499,10 @@ class PlaybookAggregator:
 
         Args:
             response: Parsed PlaybookAggregationOutput from LLM
-            cluster_playbooks: Original cluster playbooks for metadata
+            cluster_playbooks: Cluster playbooks used only for non-user metadata
+                such as playbook name and agent version. Callers may pass
+                prompt-preprocessed copies here, so this method must not read
+                user-authored fields from them.
 
         Returns:
             AgentPlaybook or None if no playbook should be generated
@@ -1365,6 +1518,9 @@ class PlaybookAggregator:
         # content is always the LLM's freeform summary;
         # fall back to formatted structured fields for backward compatibility
         playbook_content = ensure_playbook_content(structured.content, structured)
+        if not playbook_content.strip():
+            logger.info("Aggregated playbook has no valid content, skipping")
+            return None
         logger.info(
             "Aggregated playbook content (freeform): %.200s",
             playbook_content,