fred-runtime 3.3.3__tar.gz → 3.3.5__tar.gz

{fred_runtime-3.3.3 → fred_runtime-3.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fred-runtime
-Version: 3.3.3
+Version: 3.3.5
 Summary: Runtime adapters and infrastructure wiring for Fred v2 agents.
 Author-email: Thales <noreply@thalesgroup.com>
 License: Apache-2.0
@@ -13,14 +13,14 @@ Classifier: Operating System :: OS Independent
 Requires-Python: <3.13,>=3.12
 Description-Content-Type: text/markdown
 Requires-Dist: fred-core>=3.4.1
-Requires-Dist: fred-sdk>=3.3.1
+Requires-Dist: fred-sdk>=3.3.3
 Requires-Dist: alembic>=1.18.4
-Requires-Dist: deepagents>=0.4.11
+Requires-Dist: deepagents>=0.6.12
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: langchain-mcp-adapters>=0.2.1
-Requires-Dist: langchain>=0.3.0
+Requires-Dist: langchain>=1.3.14
 Requires-Dist: langchain-core>=0.3.0
-Requires-Dist: langgraph>=1.1.3
+Requires-Dist: langgraph>=1.2.9
 Requires-Dist: langfuse>=3.0.0
 Requires-Dist: requests<3,>=2.32
 Requires-Dist: PyYAML>=6.0

{fred_runtime-3.3.3 → fred_runtime-3.3.5}/fred_runtime/app/agent_app.py

@@ -3419,13 +3419,12 @@ def _build_agent_router(
 
     @router.delete(
         "/checkpoints/{session_id}",
-        status_code=status.HTTP_204_NO_CONTENT,
-        response_model=None,
+        status_code=status.HTTP_200_OK,
     )
     async def delete_checkpoint_thread(
         session_id: str,
         caller: KeycloakUser | None = Depends(_authenticated_user),
-    ) -> None:
+    ) -> dict[str, int]:
         """
         Purge all checkpoint data for one session.
 
@@ -3438,7 +3437,8 @@ def _build_agent_router(
         History store rows are NOT deleted — use DELETE /sessions/{session_id}
         to remove those separately.
 
-        Returns 204 on success, 403 when not owned, 503 when no checkpointer.
+        Returns {"deleted": n} (n = checkpoint rows removed) on success,
+        403 when not owned, 503 when no checkpointer.
         """
         caller_uid = caller.uid if caller is not None else None
         history_store = _get_history_store_for_owned_access(caller)
@@ -3453,7 +3453,8 @@ def _build_agent_router(
                 detail="Access denied.",
             )
         cp = _get_checkpointer()
-        await cp.adelete_thread(session_id)
+        deleted = await cp.adelete_thread(session_id)
+        return {"deleted": deleted}
 
     @router.post(
         "/execute",

{fred_runtime-3.3.3 → fred_runtime-3.3.5}/fred_runtime/capabilities/document_access/capability.py

@@ -62,6 +62,10 @@ from __future__ import annotations
 import json
 from collections.abc import Sequence
 
+from fred_core.store.vector_search import (
+    DEFAULT_MIN_SOURCE_SCORE_RATIO,
+    select_citable_sources,
+)
 from fred_sdk.contracts.capability import (
     AgentCapability,
     CapabilityContext,
@@ -78,7 +82,7 @@ from fred_sdk.contracts.models import FieldSpec
 from fred_sdk.contracts.runtime import DocumentSearchResult
 from langchain.agents.middleware import AgentMiddleware
 from langchain_core.tools import BaseTool, tool
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 # The tool-result `tool_ref` this capability stamps on its artifact — distinct
 # from the builtin `knowledge.search` ref so the two paths stay traceable apart.
@@ -131,6 +135,9 @@ class DocumentAccessConfig(BaseModel):
     list means "no capability-side narrowing at this level" (the session binding
     still bounds it). `default_top_k` and `search_policy` set retrieval
     defaults; `show_document_scope_control` toggles the computed chat control.
+    `min_source_score_ratio` bounds what's citable as a "source" in the chat
+    UI (RAG-DATASET-DISCOVERY-RFC.md §7) — it never narrows what the model
+    itself sees, only what a human is shown as evidence.
     """
 
     library_tag_ids: list[str] = []
@@ -138,6 +145,16 @@ class DocumentAccessConfig(BaseModel):
     default_top_k: int = 8
     search_policy: str | None = None
     show_document_scope_control: bool = True
+    min_source_score_ratio: float = Field(
+        default=DEFAULT_MIN_SOURCE_SCORE_RATIO,
+        ge=0.0,
+        le=1.0,
+        description=(
+            "A hit must score at least this fraction of the best hit in the "
+            "same search call to be citable as a source. Does not affect what "
+            "the model itself can read — only the human-facing Sources panel."
+        ),
+    )
 
 
 class DocumentAccessTurnOptions(BaseModel):
@@ -189,6 +206,7 @@ class _DocumentAccessMiddleware(AgentMiddleware):
         )
         default_top_k = config.default_top_k if config.default_top_k > 0 else 8
         search_policy = config.search_policy
+        min_source_score_ratio = config.min_source_score_ratio
 
         @tool(
             "search_documents_using_vectorization",
@@ -206,6 +224,10 @@ class _DocumentAccessMiddleware(AgentMiddleware):
             conversational exchanges (greetings, thanks, clarifying what was just
             said).
 
+            Covers prose/text documents. If a hit describes a structured/tabular
+            dataset (a "dataset pointer"), do not answer from it directly — pivot
+            to the tabular/SQL tool it names instead.
+
             Returns ranked hits with title and content. Only use information
             actually present in the returned hits; never invent facts beyond
             them.
@@ -241,13 +263,19 @@ class _DocumentAccessMiddleware(AgentMiddleware):
                     for hit in hits
                 ],
             }
-            # `blocks` feed the LLM the hit JSON; `sources` carry the typed hits
-            # the chat Sources panel renders (the runtime merges artifact
-            # sources onto the tool_result/final events).
+            # `blocks` feed the LLM the full hit set (the model needs to see a
+            # dataset pointer to know to pivot to the tabular tool, and every
+            # hit to reason with) — `sources` (the chat Sources panel) is
+            # narrowed separately: never a pointer chunk (no real content to
+            # cite), and never a hit that's noise relative to the best match
+            # in this call (found live citing near-zero-relevance paragraphs
+            # from an unrelated document, RAG-DATASET-DISCOVERY-RFC.md §7).
             artifact = ToolInvocationResult(
                 tool_ref=DOCUMENT_ACCESS_TOOL_REF,
                 blocks=(ToolContentBlock(kind=ToolContentKind.JSON, data=content),),
-                sources=tuple(hits),
+                sources=select_citable_sources(
+                    hits, min_score_ratio=min_source_score_ratio
+                ),
             )
             return json.dumps(content), artifact
 
@@ -316,6 +344,20 @@ class DocumentAccessCapability(
                 ),
                 default=True,
             ),
+            FieldSpec(
+                key="min_source_score_ratio",
+                type="number",
+                title="Minimum source relevance ratio",
+                description=(
+                    "A hit must score at least this fraction of the best hit "
+                    "in the same search to be shown as a cited source. Only "
+                    "affects the human-facing Sources panel, never what the "
+                    "model itself can read."
+                ),
+                default=DEFAULT_MIN_SOURCE_SCORE_RATIO,
+                min=0.0,
+                max=1.0,
+            ),
         ],
         # No new chat part / side panel / router / owned table — the pilot's
         # smallest real surface (RFC §10). team_scope=default_on: baseline

{fred_runtime-3.3.3 → fred_runtime-3.3.5}/fred_runtime/cli/pod_client.py

@@ -265,10 +265,11 @@ class AgentPodClient:
         response.raise_for_status()
         return int(response.json().get("deleted", 0))
 
-    def delete_checkpoint(self, session_id: str) -> None:
+    def delete_checkpoint(self, session_id: str) -> int:
         url = f"{self.base_url}/agents/checkpoints/{session_id}"
         response = self.http_client.delete(url, headers=self._auth_headers())
         response.raise_for_status()
+        return int(response.json().get("deleted", 0))
 
     def get_checkpoint_stats(self) -> dict[str, Any]:
         url = f"{self.base_url}/agents/checkpoints/_stats"

{fred_runtime-3.3.3 → fred_runtime-3.3.5}/fred_runtime/integrations/kf_vector_search/toolkit.py

@@ -49,7 +49,7 @@ from typing import Sequence
 
 from fred_core.common import OwnerFilter
 from fred_core.common.team_id import is_personal_team_id
-from fred_core.store.vector_search import VectorSearchHit
+from fred_core.store.vector_search import VectorSearchHit, select_citable_sources
 from fred_sdk.contracts.context import (
     ToolContentBlock,
     ToolContentKind,
@@ -168,7 +168,10 @@ class KfVectorSearchToolkit:
             # Return a ToolInvocationResult directly: the runtime-provider resolver
             # invokes this tool with a plain args dict, so a content_and_artifact
             # tuple would lose the artifact (and its sources). `blocks` feed the LLM
-            # the hit JSON; `sources` carry the typed hits the Sources panel renders.
+            # the full hit set; `sources` (the Sources panel) is narrowed separately —
+            # never a dataset pointer chunk, never a hit that's noise relative to the
+            # best match in this call (RAG-DATASET-DISCOVERY-RFC.md §7). Mirrors
+            # `_invoke_knowledge_search`'s use of the same shared default ratio.
             return ToolInvocationResult(
                 tool_ref=KF_VECTOR_SEARCH_PROVIDER,
                 blocks=(
@@ -180,7 +183,7 @@ class KfVectorSearchToolkit:
                         },
                     ),
                 ),
-                sources=tuple(hits),
+                sources=select_citable_sources(hits),
             )
 
         return [search_documents_using_vectorization]

{fred_runtime-3.3.3 → fred_runtime-3.3.5}/fred_runtime/integrations/v2_runtime/adapters.py

@@ -48,7 +48,7 @@ from fred_core.kpi.base_kpi_writer import BaseKPIWriter
 from fred_core.kpi.kpi_writer_structures import KPIActor
 from fred_core.portable import LoggingTracer, MetricsProvider, Tracer, get_tracer
 from fred_core.security.oidc import get_keycloak_client_id, get_keycloak_url
-from fred_core.store.vector_search import VectorSearchHit
+from fred_core.store.vector_search import VectorSearchHit, select_citable_sources
 from fred_sdk.contracts.context import (
     BoundRuntimeContext,
     FsEntry,
@@ -514,6 +514,13 @@ class FredKnowledgeSearchToolInvoker(ToolInvokerPort):
                 k: v for k, v in hit.model_dump(mode="json").items() if k in _LLM_FIELDS
             }
 
+        # `sources` is narrowed separately from the model-visible content: never
+        # a dataset pointer chunk (no real content to cite), and never a hit
+        # that's noise relative to the best match in this call
+        # (RAG-DATASET-DISCOVERY-RFC.md §7). This builtin tool predates
+        # capability config fields, so unlike document_access's
+        # `min_source_score_ratio`, the ratio here is the shared default, not
+        # yet independently tunable per agent instance.
         return ToolInvocationResult(
             tool_ref=request.tool_ref,
             blocks=(
@@ -525,7 +532,7 @@ class FredKnowledgeSearchToolInvoker(ToolInvokerPort):
                     },
                 ),
             ),
-            sources=tuple(hits),
+            sources=select_citable_sources(hits),
         )
 
     async def _invoke_traces_summarize_conversation(

{fred_runtime-3.3.3 → fred_runtime-3.3.5}/fred_runtime/react/react_runtime.py

@@ -33,6 +33,7 @@ open.
 from __future__ import annotations
 
 import logging
+import time
 import uuid
 from collections.abc import AsyncIterator, Sequence
 from contextlib import nullcontext
@@ -219,6 +220,11 @@ def _tool_thought_title(tool_name: str) -> str:
     return f"Calling {readable}"
 
 
+def _elapsed_ms_since(started_at: float) -> int:
+    """Return the whole-millisecond duration elapsed since a monotonic timestamp."""
+    return int((time.monotonic() - started_at) * 1000)
+
+
 class _TransportBackedReActExecutor(Executor[ReActInput, ReActOutput]):
     """
     Executes one ReAct run against the compiled LangChain/LangGraph agent.
@@ -341,11 +347,15 @@ class _TransportBackedReActExecutor(Executor[ReActInput, ReActOutput]):
         # Maps tool call_id → thought_id so THOUGHT_END can close the block
         # opened by THOUGHT_START before the corresponding TOOL_CALL event.
         active_thought_ids: dict[str, str] = {}
+        # Maps tool call_id → monotonic start time so THOUGHT_END can report a
+        # real `duration_ms` instead of leaving the field permanently unset.
+        active_thought_started_at: dict[str, float] = {}
         # Open model-native reasoning block (RUNTIME-05 Layer 2b). When a provider
         # streams reasoning chunks (Mistral ThinkChunk, Claude thinking), they are
         # promoted to a single THOUGHT block with source="model_native" that must be
         # closed before the first answer delta and before the run ends.
         model_native_thought_id: str | None = None
+        model_native_thought_started_at: float | None = None
         phase_timer_ctx.__enter__()
         try:
             async for raw_event in self._compiled_agent.astream(
@@ -372,6 +382,7 @@ class _TransportBackedReActExecutor(Executor[ReActInput, ReActOutput]):
                     for fragment in decoded.thought_fragments:
                         if model_native_thought_id is None:
                             model_native_thought_id = uuid.uuid4().hex
+                            model_native_thought_started_at = time.monotonic()
                             yield ThoughtStartEvent(
                                 sequence=sequence,
                                 thought_id=model_native_thought_id,
@@ -393,9 +404,15 @@ class _TransportBackedReActExecutor(Executor[ReActInput, ReActOutput]):
                             yield ThoughtEndEvent(
                                 sequence=sequence,
                                 thought_id=model_native_thought_id,
+                                duration_ms=_elapsed_ms_since(
+                                    model_native_thought_started_at
+                                )
+                                if model_native_thought_started_at is not None
+                                else None,
                             )
                             sequence += 1
                             model_native_thought_id = None
+                            model_native_thought_started_at = None
                         if not suppress_assistant_deltas:
                             yield AssistantDeltaRuntimeEvent(
                                 sequence=sequence,
@@ -448,11 +465,17 @@ class _TransportBackedReActExecutor(Executor[ReActInput, ReActOutput]):
                         )
                         sequence += 1
                         thought_id = active_thought_ids.pop(message.tool_call_id, None)
+                        thought_started_at = active_thought_started_at.pop(
+                            message.tool_call_id, None
+                        )
                         if thought_id:
                             yield ThoughtEndEvent(
                                 sequence=sequence,
                                 thought_id=thought_id,
                                 conclusion="Error" if is_error else "Done",
+                                duration_ms=_elapsed_ms_since(thought_started_at)
+                                if thought_started_at is not None
+                                else None,
                             )
                             sequence += 1
                         continue
@@ -463,6 +486,7 @@ class _TransportBackedReActExecutor(Executor[ReActInput, ReActOutput]):
                             call_id = str(tool_call.get("id") or "")
                             thought_id = uuid.uuid4().hex
                             active_thought_ids[call_id] = thought_id
+                            active_thought_started_at[call_id] = time.monotonic()
                             yield ThoughtStartEvent(
                                 sequence=sequence,
                                 thought_id=thought_id,
@@ -502,9 +526,13 @@ class _TransportBackedReActExecutor(Executor[ReActInput, ReActOutput]):
                 yield ThoughtEndEvent(
                     sequence=sequence,
                     thought_id=model_native_thought_id,
+                    duration_ms=_elapsed_ms_since(model_native_thought_started_at)
+                    if model_native_thought_started_at is not None
+                    else None,
                 )
                 sequence += 1
                 model_native_thought_id = None
+                model_native_thought_started_at = None
 
             if last_tool_error is not None or last_assistant_message is not None:
                 final_content = (
@@ -532,14 +560,18 @@ class _TransportBackedReActExecutor(Executor[ReActInput, ReActOutput]):
                     is_error=True,
                 )
                 sequence += 1
+                thought_started_at = active_thought_started_at.get(call_id)
                 yield ThoughtEndEvent(
                     sequence=sequence,
                     thought_id=thought_id,
                     conclusion="Error",
-                    duration_ms=None,
+                    duration_ms=_elapsed_ms_since(thought_started_at)
+                    if thought_started_at is not None
+                    else None,
                 )
                 sequence += 1
             active_thought_ids.clear()
+            active_thought_started_at.clear()
             # Close an open model-native reasoning block so its accordion does not
             # spin forever after a mid-stream failure.
             if model_native_thought_id is not None:
@@ -547,6 +579,9 @@ class _TransportBackedReActExecutor(Executor[ReActInput, ReActOutput]):
                     sequence=sequence,
                     thought_id=model_native_thought_id,
                     conclusion="Error",
+                    duration_ms=_elapsed_ms_since(model_native_thought_started_at)
+                    if model_native_thought_started_at is not None
+                    else None,
                 )
                 sequence += 1
             raise

{fred_runtime-3.3.3 → fred_runtime-3.3.5}/fred_runtime/runtime_support/sql_checkpointer.py

@@ -589,7 +589,21 @@ class FredSqlCheckpointer(BaseCheckpointSaver[str]):
     def delete_thread(self, thread_id: str) -> None:  # type: ignore[override]
         raise _sync_checkpointer_error("delete_thread")
 
-    async def adelete_thread(self, thread_id: str) -> None:
+    async def adelete_thread(self, thread_id: str) -> int:  # type: ignore[override]
+        """
+        Delete all checkpoint rows for one thread and return the checkpoint count.
+
+        Why this exists:
+        - Callers erasing a conversation (CTRLP-12) need an honest deleted-row
+          count for their receipt, matching the sibling history-store delete
+          which already returns one. Before this, callers had no way to know
+          how much was actually purged.
+        - The returned count is the number of rows removed from
+          `checkpoints_table` (one row per turn) — the same unit the
+          `/agents/checkpoints/{session_id}` listing endpoint reports elsewhere.
+          `writes`/`blobs`/`thread_owner` rows are still purged but are
+          implementation detail, not a separately meaningful count.
+        """
         async with self.phase("v2_checkpoint_delete_thread"):
             await self._ensure_tables()
             async with self.store.begin() as conn:
@@ -598,7 +612,7 @@ class FredSqlCheckpointer(BaseCheckpointSaver[str]):
                         self.writes_table.c.thread_id == thread_id
                     )
                 )
-                await conn.execute(
+                result = await conn.execute(
                     delete(self.checkpoints_table).where(
                         self.checkpoints_table.c.thread_id == thread_id
                     )
@@ -616,6 +630,7 @@ class FredSqlCheckpointer(BaseCheckpointSaver[str]):
                         self.thread_owner_table.c.thread_id == thread_id
                     )
                 )
+                return result.rowcount or 0
 
     # ------------------------- owner / age index (CTRLP-12 A4) -------------------------
 

{fred_runtime-3.3.3 → fred_runtime-3.3.5}/fred_runtime.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fred-runtime
-Version: 3.3.3
+Version: 3.3.5
 Summary: Runtime adapters and infrastructure wiring for Fred v2 agents.
 Author-email: Thales <noreply@thalesgroup.com>
 License: Apache-2.0
@@ -13,14 +13,14 @@ Classifier: Operating System :: OS Independent
 Requires-Python: <3.13,>=3.12
 Description-Content-Type: text/markdown
 Requires-Dist: fred-core>=3.4.1
-Requires-Dist: fred-sdk>=3.3.1
+Requires-Dist: fred-sdk>=3.3.3
 Requires-Dist: alembic>=1.18.4
-Requires-Dist: deepagents>=0.4.11
+Requires-Dist: deepagents>=0.6.12
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: langchain-mcp-adapters>=0.2.1
-Requires-Dist: langchain>=0.3.0
+Requires-Dist: langchain>=1.3.14
 Requires-Dist: langchain-core>=0.3.0
-Requires-Dist: langgraph>=1.1.3
+Requires-Dist: langgraph>=1.2.9
 Requires-Dist: langfuse>=3.0.0
 Requires-Dist: requests<3,>=2.32
 Requires-Dist: PyYAML>=6.0

{fred_runtime-3.3.3 → fred_runtime-3.3.5}/fred_runtime.egg-info/SOURCES.txt

@@ -129,6 +129,7 @@ tests/test_graph_runtime_observability.py
 tests/test_history.py
 tests/test_kf_vector_search_toolkit.py
 tests/test_kf_workspace_client.py
+tests/test_knowledge_search_tool_invoker_sources.py
 tests/test_kpi_display.py
 tests/test_mcp_config.py
 tests/test_model_routing.py

{fred_runtime-3.3.3 → fred_runtime-3.3.5}/fred_runtime.egg-info/requires.txt

@@ -1,12 +1,12 @@
 fred-core>=3.4.1
-fred-sdk>=3.3.1
+fred-sdk>=3.3.3
 alembic>=1.18.4
-deepagents>=0.4.11
+deepagents>=0.6.12
 httpx>=0.28.1
 langchain-mcp-adapters>=0.2.1
-langchain>=0.3.0
+langchain>=1.3.14
 langchain-core>=0.3.0
-langgraph>=1.1.3
+langgraph>=1.2.9
 langfuse>=3.0.0
 requests<3,>=2.32
 PyYAML>=6.0

{fred_runtime-3.3.3 → fred_runtime-3.3.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fred-runtime"
-version = "3.3.3"
+version = "3.3.5"
 description = "Runtime adapters and infrastructure wiring for Fred v2 agents."
 readme = "README.md"
 requires-python = ">=3.12,<3.13"
@@ -8,14 +8,14 @@ license = { text = "Apache-2.0" }
 authors = [{ name = "Thales", email = "noreply@thalesgroup.com" }]
 dependencies = [
   "fred-core>=3.4.1",
-  "fred-sdk>=3.3.1",
+  "fred-sdk>=3.3.3",
   "alembic>=1.18.4",
-  "deepagents>=0.4.11",
+  "deepagents>=0.6.12",
   "httpx>=0.28.1",
   "langchain-mcp-adapters>=0.2.1",
-  "langchain>=0.3.0",
+  "langchain>=1.3.14",
   "langchain-core>=0.3.0",
-  "langgraph>=1.1.3",
+  "langgraph>=1.2.9",
   "langfuse>=3.0.0",
   "requests>=2.32,<3",
   "PyYAML>=6.0",

{fred_runtime-3.3.3 → fred_runtime-3.3.5}/tests/test_agent_app.py

@@ -366,6 +366,86 @@ def test_create_agent_app_executes_local_authored_tools_and_honors_base_url(
     assert payloads[-1]["content"] == "Echo complete."
 
 
+def test_delete_checkpoint_thread_returns_deleted_count(monkeypatch, tmp_path) -> None:
+    """
+    `DELETE /agents/checkpoints/{session_id}` must report how many checkpoint
+    rows it actually purged, mirroring the sibling `DELETE /agents/sessions/{id}`
+    (history) endpoint's `{"deleted": n}` body.
+
+    Why this exists:
+    - before this fix the endpoint returned a bare 204 with no body, so
+      `ConversationErasureService` (control-plane, CTRLP-12) could not report a
+      real `deleted_count` for the `runtime_checkpoint` store in its erase
+      receipt — every erasure looked identical whether it purged one
+      checkpoint or a hundred.
+
+    How to use it:
+    - run via the default offline `make test` suite in `fred-runtime`
+    """
+
+    model = ToolFriendlyFakeChatModel(
+        responses=[
+            AIMessage(
+                content="",
+                tool_calls=[
+                    {
+                        "id": "call-echo-1",
+                        "name": "demo_echo",
+                        "args": {"text": "hello"},
+                    }
+                ],
+            ),
+            AIMessage(content="Echo complete."),
+        ]
+    )
+    monkeypatch.setattr(
+        agent_app_module,
+        "_build_chat_model_factory",
+        lambda config: StaticChatModelFactory(model),
+    )
+
+    definition = _EchoAgent()
+    registry: dict[str, ReActAgentDefinition] = {definition.agent_id: definition}
+    app = create_agent_app(registry=registry, config=_build_test_config(tmp_path))
+
+    with TestClient(app) as client:
+        execute_response = client.post(
+            "/pod/v1/agents/execute",
+            json={
+                "agent_id": "rags.sample.echo",
+                "input": "hello",
+                "session_id": "session-checkpoint-delete",
+                "runtime_context": {"user_id": "alice"},
+            },
+        )
+        assert execute_response.status_code == 200
+
+        threads_before = client.get(
+            "/pod/v1/agents/checkpoints/session-checkpoint-delete"
+        )
+        assert threads_before.status_code == 200
+        assert len(threads_before.json()["checkpoints"]) > 0
+
+        delete_response = client.delete(
+            "/pod/v1/agents/checkpoints/session-checkpoint-delete"
+        )
+        assert delete_response.status_code == 200
+        deleted = delete_response.json()["deleted"]
+        assert deleted > 0
+
+        threads_after = client.get(
+            "/pod/v1/agents/checkpoints/session-checkpoint-delete"
+        )
+        assert threads_after.json()["checkpoints"] == []
+
+        # Idempotent: a retry against an already-purged thread deletes nothing.
+        retry_response = client.delete(
+            "/pod/v1/agents/checkpoints/session-checkpoint-delete"
+        )
+        assert retry_response.status_code == 200
+        assert retry_response.json() == {"deleted": 0}
+
+
 class _ContextPromptAgent(ReActAgent):
     """Tiny agent that surfaces the bound context_prompt_text through a tool."""