claude-smart 0.2.48 → 0.2.50

package/plugin/vendor/reflexio/reflexio/client/client.py

@@ -15,6 +15,13 @@ import requests
 from pydantic import ConfigDict
 
 from reflexio.defaults import DEFAULT_AGENT_VERSION
+from reflexio.models.api_schema.eval_overview_schema import (
+    GradeOnDemandRequest,
+    GradeOnDemandResponse,
+    RegenerateRequest,
+    RegenerateStartResponse,
+    RegenerateStatusResponse,
+)
 from reflexio.models.api_schema.retriever_schema import (
     ConversationTurn,
     GetAgentPlaybooksRequest,
@@ -26,6 +33,8 @@ from reflexio.models.api_schema.retriever_schema import (
     GetProfilesViewResponse,
     GetRequestsRequest,
     GetRequestsViewResponse,
+    GetRetrievedLearningEvaluationResultsRequest,
+    GetRetrievedLearningEvaluationResultsResponse,
     GetUserPlaybooksRequest,
     GetUserPlaybooksViewResponse,
     GetUserProfilesRequest,
@@ -306,9 +315,8 @@ class ReflexioClient:
         if headers:
             request_headers.update(headers)
 
-        self.session.headers.update(request_headers)
         kwargs.setdefault("timeout", self.timeout)
-        response = self.session.request(method, url, **kwargs)
+        response = self.session.request(method, url, headers=request_headers, **kwargs)
         response.raise_for_status()
 
         # Empty body on a successful response (e.g. 204 No Content).
@@ -445,12 +453,17 @@ class ReflexioClient:
                 explicit retry after reauth or limit reset.
 
         Returns:
-            PublishUserInteractionResponse: Server response. In
-                ``wait_for_response=False`` mode this is a bare
-                acknowledgement ("Interaction queued for processing")
-                without extraction counts; in ``wait_for_response=True``
-                mode it includes request_id, storage routing, and
-                deltas.
+            PublishUserInteractionResponse: Server response.
+
+                In deferred mode (``wait_for_response=False``) the
+                response carries ``learning_status="deferred"`` and a
+                ``request_id``; ``profiles_added``/``playbooks_added`` are
+                0 because extraction has not run yet. Poll
+                ``get_learning_status(request_id)`` for completion.
+
+                In ``wait_for_response=True`` mode the server waits for
+                extraction and the response includes ``request_id``,
+                storage routing, and real profile/playbook deltas.
         """
         if session_id is None or not session_id.strip():
             raise ValueError("session_id is required and cannot be empty")
@@ -481,6 +494,35 @@ class ReflexioClient:
         self._cache.invalidate("get_agent_playbooks")
         return result
 
+    def get_learning_status(self, request_id: str) -> str:
+        """Poll the learning status for a previously published request.
+
+        Call this after a deferred ``publish_interaction`` (where
+        ``wait_for_response=False``).  The response carries
+        ``learning_status="deferred"`` to signal that extraction has been
+        queued; use this method to track progress once the durable queue
+        is active.
+
+        Args:
+            request_id: The ``request_id`` of the published interaction, as
+                returned in ``PublishUserInteractionResponse.request_id``
+                (populated on both the deferred and ``wait_for_response=True``
+                paths) or known by the caller.
+
+        Returns:
+            One of: ``"pending"`` | ``"processing"`` | ``"done"`` | ``"failed"``.
+
+        Raises:
+            requests.HTTPError: 404 when the request_id is not known to the
+                server for this org.
+        """
+        response = self._make_request(
+            "GET",
+            "/api/learning_status",
+            params={"request_id": request_id},
+        )
+        return str(response["status"])
+
     def search_interactions(
         self,
         request: SearchInteractionRequest | dict | None = None,
@@ -1886,6 +1928,116 @@ class ReflexioClient:
         )
         return GetEvaluationResultsViewResponse(**response)
 
+    def get_retrieved_learning_evaluation_results(
+        self,
+        request: GetRetrievedLearningEvaluationResultsRequest | dict | None = None,
+        *,
+        user_id: str | None = None,
+        session_id: str | None = None,
+        limit: int | None = None,
+    ) -> GetRetrievedLearningEvaluationResultsResponse:
+        """Get per-learning relevance and impact verdicts for retrieved context."""
+        req = self._build_request(
+            request,
+            GetRetrievedLearningEvaluationResultsRequest,
+            user_id=user_id,
+            session_id=session_id,
+            limit=limit,
+        )
+        response = self._make_request(
+            "POST",
+            "/api/get_retrieved_learning_evaluation_results",
+            json=req.model_dump(),
+        )
+        return GetRetrievedLearningEvaluationResultsResponse(**response)
+
+    def regenerate_evaluations(
+        self,
+        request: RegenerateRequest | dict | None = None,
+        *,
+        from_ts: int | None = None,
+        to_ts: int | None = None,
+        evaluation_name: str | None = None,
+    ) -> RegenerateStartResponse:
+        """Start a replay-the-judge regeneration job over a time window.
+
+        Args:
+            request: Optional ``RegenerateRequest`` or dict. If omitted,
+                keyword arguments are used.
+            from_ts: Inclusive lower bound of the window as Unix seconds.
+            to_ts: Inclusive upper bound of the window as Unix seconds.
+            evaluation_name: Deprecated compatibility field accepted by the
+                API but ignored by the singleton evaluator.
+
+        Returns:
+            RegenerateStartResponse: The job id and number of queued sessions.
+        """
+        req = self._build_request(
+            request,
+            RegenerateRequest,
+            from_ts=from_ts,
+            to_ts=to_ts,
+            evaluation_name=evaluation_name,
+        )
+        response = self._make_request(
+            "POST",
+            "/api/evaluations/regenerate",
+            json=req.model_dump(),
+        )
+        return RegenerateStartResponse(**response)
+
+    def get_evaluation_regeneration_status(
+        self, job_id: str
+    ) -> RegenerateStatusResponse:
+        """Get status for an evaluation regeneration job."""
+        response = self._make_request(
+            "GET",
+            f"/api/evaluations/regenerate/{job_id}",
+        )
+        return RegenerateStatusResponse(**response)
+
+    def cancel_evaluation_regeneration(self, job_id: str) -> dict[str, str]:
+        """Request cancellation for an evaluation regeneration job."""
+        return self._make_request(
+            "DELETE",
+            f"/api/evaluations/regenerate/{job_id}",
+        )
+
+    def grade_on_demand(
+        self,
+        request: GradeOnDemandRequest | dict | None = None,
+        *,
+        session_id: str | None = None,
+        agent_version: str | None = None,
+        evaluation_name: str | None = None,
+    ) -> GradeOnDemandResponse:
+        """Grade a single session synchronously.
+
+        Args:
+            request: Optional ``GradeOnDemandRequest`` or dict. If omitted,
+                keyword arguments are used.
+            session_id: Session to grade.
+            agent_version: Agent version to grade.
+            evaluation_name: Deprecated compatibility field accepted by the
+                API but ignored by the singleton evaluator.
+
+        Returns:
+            GradeOnDemandResponse: Result id, cache flag, or skipped reason.
+        """
+        req = self._build_request(
+            request,
+            GradeOnDemandRequest,
+            session_id=session_id,
+            agent_version=agent_version,
+            evaluation_name=evaluation_name,
+        )
+        response = self._make_request(
+            "POST",
+            "/api/evaluations/grade_on_demand",
+            json=req.model_dump(),
+        )
+        return GradeOnDemandResponse(**response)
+
     def _poll_operation_status(
         self,
         service_name: str,
@@ -2365,7 +2517,12 @@ class ReflexioClient:
                 "profiles", "user_playbooks", "agent_playbooks".
             agent_playbook_status_filter (Optional[list[Union[PlaybookStatus, str]]]):
                 Agent-playbook approval statuses to include.
-            enable_reformulation (Optional[bool]): Enable LLM query reformulation (default: False)
+            enable_reformulation (Optional[bool]): Enable the pre-search LLM
+                query reformulation call (default: False). Besides rewriting
+                the query, it extracts temporal signals — time windows
+                ("this week"), as-of boundaries, and current-value intent —
+                that make retrieval time-sensitive (window filters,
+                freshness-preferred ranking for superseded facts).
             enable_agent_answer (Optional[bool]): Enable agentic answer synthesis when
                 the configured search backend supports it (default: False).
             conversation_history (Optional[list[ConversationTurn] | list[dict]]): Prior conversation turns for context-aware query reformulation. Accepts ConversationTurn objects or dicts with "role" and "content" keys.

package/plugin/vendor/reflexio/reflexio/integrations/openclaw/plugin/src/openclaw_smart/state.py

@@ -36,7 +36,9 @@ _DEFAULT_STATE_DIR = Path.home() / ".openclaw-smart" / "sessions"
 
 _TOOL_DATA_FIELD_MAX_LEN = 256
 
-_VALID_CITATION_KINDS = frozenset({"playbook", "profile"})
+_VALID_CITATION_KINDS = frozenset(
+    {"playbook", "profile", "user_playbook", "agent_playbook"}
+)
 
 
 def _truncate_tool_data_field(value: Any) -> Any:
@@ -240,13 +242,18 @@ def _to_wire_citations(cited_items: Any) -> list[dict[str, str]]:
         kind = item.get("kind")
         if not isinstance(real_id, str) or not real_id:
             continue
-        if kind not in _VALID_CITATION_KINDS:
+        wire_kind = kind
+        if kind == "playbook":
+            source_kind = item.get("source_kind")
+            if source_kind in {"user_playbook", "agent_playbook"}:
+                wire_kind = source_kind
+        if wire_kind not in _VALID_CITATION_KINDS:
             continue
         tag = item.get("id")
         title = item.get("title")
         out.append(
             {
-                "kind": kind,
+                "kind": wire_kind,
                 "real_id": real_id,
                 "tag": tag if isinstance(tag, str) else "",
                 "title": title if isinstance(title, str) else "",

package/plugin/vendor/reflexio/reflexio/integrations/openclaw/plugin/tests/test_state.py

@@ -233,3 +233,31 @@ def test_safe_session_ids_accepted():
         path = state.session_path(sid)
         assert path is not None, f"safe id {sid!r} should have been accepted"
         assert path.name == f"{sid}.jsonl"
+
+
+def test_to_wire_citations_preserves_explicit_playbook_source_kind() -> None:
+    wire = state._to_wire_citations(
+        [
+            {
+                "id": "s1-1",
+                "kind": "playbook",
+                "source_kind": "agent_playbook",
+                "real_id": "20",
+                "title": "Agent",
+            },
+            {
+                "id": "s2-1",
+                "kind": "playbook",
+                "source_kind": "user_playbook",
+                "real_id": "101",
+                "title": "User",
+            },
+            {"id": "p1-1", "kind": "profile", "real_id": "p1", "title": "Profile"},
+        ]
+    )
+
+    assert [item["kind"] for item in wire] == [
+        "agent_playbook",
+        "user_playbook",
+        "profile",
+    ]

package/plugin/vendor/reflexio/reflexio/lib/_search.py

@@ -6,6 +6,8 @@ from reflexio.models.api_schema.retriever_schema import (
     GetAgentSuccessEvaluationResultsResponse,
     GetRequestsRequest,
     GetRequestsResponse,
+    GetRetrievedLearningEvaluationResultsRequest,
+    GetRetrievedLearningEvaluationResultsResponse,
     RequestData,
     Session,
     UnifiedSearchRequest,
@@ -72,6 +74,45 @@ class SearchMixin(ReflexioBase):
                 success=False, agent_success_evaluation_results=[], msg=str(e)
             )
 
+    def get_retrieved_learning_evaluation_results(
+        self,
+        request: GetRetrievedLearningEvaluationResultsRequest | dict,
+    ) -> GetRetrievedLearningEvaluationResultsResponse:
+        """Get per-learning retrieved-learning evaluation verdicts.
+
+        Args:
+            request (GetRetrievedLearningEvaluationResultsRequest | dict): The
+                read request (optional user/session filters + limit).
+
+        Returns:
+            GetRetrievedLearningEvaluationResultsResponse: Matching verdicts
+            ordered by created_at DESC, result_id DESC.
+        """
+        if not self._is_storage_configured():
+            return GetRetrievedLearningEvaluationResultsResponse(
+                success=True, results=[], msg=STORAGE_NOT_CONFIGURED_MSG
+            )
+        if isinstance(request, dict):
+            request = GetRetrievedLearningEvaluationResultsRequest(**request)
+        try:
+            results = self._get_storage().get_retrieved_learning_evaluation_results(
+                user_id=request.user_id,
+                session_id=request.session_id,
+                limit=request.limit,
+            )
+            return GetRetrievedLearningEvaluationResultsResponse(
+                success=True,
+                results=results,
+                msg=f"Found {len(results)} retrieved-learning evaluation result(s)",
+            )
+        except Exception:
+            _LOGGER.exception("Failed to read retrieved-learning evaluation results")
+            return GetRetrievedLearningEvaluationResultsResponse(
+                success=False,
+                results=[],
+                msg="Failed to read retrieved-learning evaluation results",
+            )
+
     def get_requests(
         self,
         request: GetRequestsRequest | dict,

package/plugin/vendor/reflexio/reflexio/models/api_schema/domain/entities.py

@@ -33,7 +33,11 @@ __all__ = [
     "BlockingIssue",
     "BlockingIssueKind",
     "ToolUsed",
+    "CitationKind",
     "Citation",
+    "RetrievedLearningKind",
+    "RetrievedLearning",
+    "LearningImpact",
     "Interaction",
     "Request",
     "UserProfile",
@@ -41,6 +45,7 @@ __all__ = [
     "ProfileChangeLog",
     "AgentPlaybook",
     "AgentSuccessEvaluationResult",
+    "RetrievedLearningEvaluationResult",
     "DeleteUserProfileRequest",
     "DeleteUserProfileResponse",
     "DeleteUserInteractionRequest",
@@ -123,12 +128,15 @@ __all__ = [
     "LineageEvent",
     "LineageContext",
     "RecordRef",
+    "LearningStatusResponse",
 ]
 
 # ===============================
 # Data Models
 # ===============================
 
+type CitationKind = Literal["playbook", "profile", "user_playbook", "agent_playbook"]
+
 
 class Citation(BaseModel):
     """A playbook or profile item the agent cited as influential.
@@ -140,22 +148,52 @@ class Citation(BaseModel):
     it was applied?).
 
     Attributes:
-        kind (Literal["playbook", "profile"]): Which kind of cited
-            item this references.
+        kind (CitationKind): Which kind of cited item this references.
+            ``"playbook"`` is the legacy compatibility value.
+            ``"user_playbook"`` is the direct tuner target.
+            ``"agent_playbook"`` references an org-level playbook row.
+            ``"profile"`` references a user profile row.
         real_id (str): Stable storage id — ``user_playbook_id`` for
-            playbooks, ``profile_id`` for profiles.
+            user playbooks, ``agent_playbook_id`` for agent playbooks,
+            and ``profile_id`` for profiles.
         tag (str): Injection-time rank tag (e.g. ``"r1-301"``,
             ``"p1-0f37"``). Per-injection, not stable across sessions;
             kept as a debug aid.
         title (str): Short human-readable label for logs and UI.
     """
 
-    kind: Literal["playbook", "profile"]
+    kind: CitationKind
     real_id: str
     tag: str = ""
     title: str = ""
 
 
+# Canonical kinds accepted and persisted by retrieved-learning evaluation.
+# Unlike ``Citation.kind`` there is no legacy ``"playbook"`` alias.
+type RetrievedLearningKind = Literal["profile", "user_playbook", "agent_playbook"]
+
+type LearningImpact = Literal["positive", "negative", "neutral"]
+
+
+class RetrievedLearning(BaseModel):
+    """A learning the caller retrieved and injected into the agent context.
+
+    Deliberately minimal — just the identity pair. It does NOT reuse
+    ``Citation``: citations carry injection-time debug fields (``tag``,
+    ``title``) that callers should not need to supply (or see) when declaring
+    what was retrieved.
+
+    Attributes:
+        kind (RetrievedLearningKind): Which kind of learning this references.
+        learning_id (str): Stable storage id — ``profile_id`` for profiles,
+            ``user_playbook_id`` for user playbooks, ``agent_playbook_id``
+            for agent playbooks (numeric ids as decimal strings).
+    """
+
+    kind: RetrievedLearningKind
+    learning_id: str = Field(min_length=1, max_length=1_000)
+
+
 # information about the user interaction sent by the client
 class Interaction(BaseModel):
     interaction_id: int = 0  # 0 = placeholder for DB auto-increment
@@ -172,6 +210,10 @@ class Interaction(BaseModel):
     expert_content: str = ""
     tools_used: list[ToolUsed] = Field(default_factory=list)
     citations: list[Citation] = Field(default_factory=list)
+    # Every learning retrieved and injected for this turn — including ones
+    # that did not end up influencing the response (contrast: ``citations``
+    # is the agent's claim of influence).
+    retrieved_learnings: list[RetrievedLearning] = Field(default_factory=list)
     embedding: EmbeddingVector = []
 
     @field_validator("interacted_image_url", mode="after")
@@ -398,17 +440,107 @@ class AgentSuccessEvaluationResult(BaseModel):
     embedding: EmbeddingVector = []
 
 
+class RetrievedLearningEvaluationResult(BaseModel):
+    """Latest per-learning relevance/impact verdict for one evaluated session.
+
+    One row per ``(user_id, session_id, kind, learning_id)``. The table holds
+    the most recent successfully persisted evaluation set for a session, not
+    an append-only history.
+
+    Attributes:
+        result_id (int): DB auto-increment identifier (0 = placeholder).
+        user_id (str): Session owner.
+        session_id (str): Evaluated session.
+        agent_version (str): Version supplied to group evaluation;
+            informational, not part of the uniqueness key.
+        kind (RetrievedLearningKind): The learning kind.
+        learning_id (str): Stable storage id, matching
+            ``RetrievedLearning.learning_id``.
+        is_relevant (bool | None): Whether the learning applies to the
+            session. ``None`` only when the relevance judge/chunk failed.
+        relevance_reason (str): Judge reasoning; empty when ``is_relevant``
+            is ``None``.
+        impact (LearningImpact | None): Whether the learning improved,
+            harmed, or did not materially change the response. ``None`` only
+            when the impact judge/chunk failed.
+        impact_reason (str): Judge reasoning; empty when ``impact`` is
+            ``None``.
+        created_at (int): Earliest request timestamp in the evaluated
+            session.
+    """
+
+    result_id: int = 0
+    user_id: str
+    session_id: str
+    agent_version: str = ""
+    kind: RetrievedLearningKind
+    learning_id: str
+    is_relevant: bool | None = None
+    relevance_reason: str = ""
+    impact: LearningImpact | None = None
+    impact_reason: str = ""
+    created_at: int = Field(default_factory=lambda: int(datetime.now(UTC).timestamp()))
+
+
 class PlaybookRetrievalLogItem(BaseModel):
-    """One retrieved agent playbook plus the serve-time attribution snapshot."""
+    """One retrieved playbook plus the serve-time attribution snapshot.
+
+    ``agent_playbook_id`` remains as a nullable legacy compatibility field for
+    old agent-only rows. New rows should prefer ``target_kind`` + ``target_id``.
+    """
 
     retrieval_log_item_id: int = 0
     retrieval_log_id: int = 0
     ordinal: int
-    agent_playbook_id: int
+    agent_playbook_id: int | None = Field(default=None, gt=0)
+    target_kind: Literal["agent_playbook", "user_playbook"] | None = None
+    target_id: int | None = Field(default=None, gt=0)
+    target_title: str = ""
+    target_content: str = ""
+    target_trigger: str | None = None
     source_user_playbook_ids: list[int] = Field(default_factory=list)
     source_interaction_ids_by_user_playbook_id: dict[str, list[int]] = Field(
         default_factory=dict
     )
+    source_window_snapshot_mode: Literal["final_response", "live_lookup_compat"] = (
+        "live_lookup_compat"
+    )
+
+    @model_validator(mode="after")
+    def backfill_legacy_target_fields(self) -> Self:
+        if self.target_kind is None:
+            if self.agent_playbook_id is None:
+                raise ValueError(
+                    "PlaybookRetrievalLogItem requires target_kind/target_id or"
+                    " legacy agent_playbook_id"
+                )
+            self.target_kind = "agent_playbook"
+            self.target_id = self.agent_playbook_id
+            return self
+
+        if self.target_id is None:
+            if self.target_kind != "agent_playbook" or self.agent_playbook_id is None:
+                raise ValueError(
+                    "PlaybookRetrievalLogItem.target_id is required for explicit"
+                    " targets"
+                )
+            self.target_id = self.agent_playbook_id
+
+        if self.target_kind == "user_playbook":
+            if self.agent_playbook_id is not None:
+                raise ValueError(
+                    "user_playbook retrieval-log items cannot carry agent_playbook_id"
+                )
+            return self
+
+        if self.agent_playbook_id is None:
+            self.agent_playbook_id = self.target_id
+        elif self.agent_playbook_id != self.target_id:
+            raise ValueError(
+                "agent_playbook retrieval-log item agent_playbook_id must match"
+                " target_id"
+            )
+        return self
 
 
 class PlaybookRetrievalLog(BaseModel):
@@ -598,19 +730,19 @@ class BulkDeleteResponse(BaseModel):
 
 
 class DeleteRequestsByIdsRequest(BaseModel):
-    request_ids: list[str] = Field(min_length=1)
+    request_ids: list[str] = Field(min_length=1, max_length=10_000)
 
 
 class DeleteProfilesByIdsRequest(BaseModel):
-    profile_ids: list[str] = Field(min_length=1)
+    profile_ids: list[str] = Field(min_length=1, max_length=10_000)
 
 
 class DeleteAgentPlaybooksByIdsRequest(BaseModel):
-    agent_playbook_ids: list[int] = Field(min_length=1)
+    agent_playbook_ids: list[int] = Field(min_length=1, max_length=10_000)
 
 
 class DeleteUserPlaybooksByIdsRequest(BaseModel):
-    user_playbook_ids: list[int] = Field(min_length=1)
+    user_playbook_ids: list[int] = Field(min_length=1, max_length=10_000)
 
 
 # Clear all data scoped to a single user_id (interactions, requests, user
@@ -631,16 +763,25 @@ class ClearUserDataResponse(BaseModel):
 # user provided interaction data from the request
 class InteractionData(BaseModel):
     created_at: int = Field(default_factory=lambda: int(datetime.now(UTC).timestamp()))
-    role: str = "User"
-    content: str = ""
-    shadow_content: str = ""
-    expert_content: str = ""
+    role: str = Field(default="User", max_length=1_000)
+    content: str = Field(default="", max_length=1_000_000)
+    shadow_content: str = Field(default="", max_length=1_000_000)
+    expert_content: str = Field(default="", max_length=1_000_000)
     user_action: UserActionType = UserActionType.NONE
-    user_action_description: str = ""
-    interacted_image_url: str = ""
-    image_encoding: str = ""  # base64 encoded image
-    tools_used: list[ToolUsed] = Field(default_factory=list)
-    citations: list[Citation] = Field(default_factory=list)
+    user_action_description: str = Field(default="", max_length=10_000)
+    interacted_image_url: str = Field(default="", max_length=2_048)
+    image_encoding: str = Field(
+        default="", max_length=15_000_000
+    )  # base64 encoded image
+    tools_used: list[ToolUsed] = Field(default_factory=list, max_length=1_000)
+    citations: list[Citation] = Field(default_factory=list, max_length=1_000)
+    # Learnings (profiles / user playbooks / agent playbooks) the caller
+    # retrieved and injected into the agent context for this turn. Distinct
+    # from ``citations`` (agent-claimed influence): this is everything that
+    # was injected, whether or not it helped.
+    retrieved_learnings: list[RetrievedLearning] = Field(
+        default_factory=list, max_length=1_000
+    )
 
     @field_validator("interacted_image_url", mode="after")
     @classmethod
@@ -652,11 +793,10 @@ class InteractionData(BaseModel):
 class PublishUserInteractionRequest(BaseModel):
     request_id: NonEmptyStr | None = None
     user_id: NonEmptyStr
-    interaction_data_list: list[InteractionData] = Field(min_length=1)
-    source: str = ""
-    agent_version: str = (
-        ""  # this is used for aggregating interactions for generating agent playbooks
-    )
+    interaction_data_list: list[InteractionData] = Field(min_length=1, max_length=1_000)
+    source: str = Field(default="", max_length=1_000)
+    # this is used for aggregating interactions for generating agent playbooks
+    agent_version: str = Field(default="", max_length=1_000)
     session_id: NonEmptyStr  # used for grouping requests together
     skip_aggregation: bool = (
         False  # when True, extract profiles/playbooks but skip aggregation
@@ -673,6 +813,19 @@ class PublishUserInteractionRequest(BaseModel):
             raise ValueError("evaluation_only publishes require session_id")
         return self
 
+    @model_validator(mode="after")
+    def validate_retrieved_learnings_total(self) -> Self:
+        total = sum(
+            len(interaction.retrieved_learnings)
+            for interaction in self.interaction_data_list
+        )
+        if total > 1_000:
+            raise ValueError(
+                "a publish request may carry at most 1000 retrieved_learnings"
+                f" across all interactions (got {total})"
+            )
+        return self
+
 
 # publish user interaction response
 class PublishUserInteractionResponse(BaseModel):
@@ -689,6 +842,23 @@ class PublishUserInteractionResponse(BaseModel):
     profiles_updated: int | None = None
     playbooks_added: int | None = None
     playbooks_updated: int | None = None
+    # Set to "deferred" when the server queued extraction asynchronously.
+    # None on the sync (wait_for_response=True) path. Poll GET
+    # /api/learning_status?request_id=... to track progress once the
+    # durable queue is active.
+    learning_status: str | None = None
+
+
+class LearningStatusResponse(BaseModel):
+    """Response for GET /api/learning_status.
+
+    Attributes:
+        status: One of ``pending | processing | done | failed``.
+            Coverage-based: reflects whether a durable learning job has
+            processed through the request's creation timestamp.
+    """
+
+    status: Literal["pending", "processing", "done", "failed"]
 
 
 # whoami response — caller identity + resolved storage routing (masked)
@@ -712,7 +882,7 @@ class MyConfigResponse(BaseModel):
 
 # add user playbook request/response
 class AddUserPlaybookRequest(BaseModel):
-    user_playbooks: list[UserPlaybook] = Field(min_length=1)
+    user_playbooks: list[UserPlaybook] = Field(min_length=1, max_length=1_000)
 
     @model_validator(mode="after")
     def check_content_fields(self) -> Self: