feat(api, sdk): adding 'delete from selected id onward' endpoint and sdk functionality

Signed-off-by: Jan Jeliga <jeliga.jan@gmail.com>

Author: jjeliga

apps/agentstack-sdk-py/src/agentstack_sdk/platform/context.py

@@ -238,6 +238,21 @@ async def add_history_item(
                 )
             ).raise_for_status()
 
+    async def delete_history_from_id(
+        self: Context | str,
+        *,
+        from_id: UUID | str,
+        client: PlatformClient | None = None,
+    ) -> None:
+        """Delete all history items from a specific item onwards (inclusive)"""
+        target_context_id = self if isinstance(self, str) else self.id
+        async with client or get_platform_client() as platform_client:
+            _ = (
+                await platform_client.delete(
+                    url=f"/api/v1/contexts/{target_context_id}/history", params={"from_id": str(from_id)}
+                )
+            ).raise_for_status()
+
     async def list_history(
         self: Context | str,
         *,

apps/agentstack-server/src/agentstack_server/api/routes/contexts.py

@@ -151,3 +151,13 @@ async def list_context_history(
     pagination: Annotated[PaginationQuery, Query()],
 ) -> PaginatedResult[ContextHistoryItem]:
     return await context_service.list_history(context_id=context_id, user=user.user, pagination=pagination)
+
+
+@router.delete("/{context_id}/history", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_context_history_from_id(
+    context_id: UUID,
+    from_id: Annotated[UUID, Query()],
+    context_service: ContextServiceDependency,
+    user: Annotated[AuthorizedUser, Depends(RequiresContextPermissionsPath(context_data={"read", "write"}))],
+) -> None:
+    await context_service.delete_history_from_id(context_id=context_id, from_id=from_id, user=user.user)

apps/agentstack-server/src/agentstack_server/domain/repositories/context.py

@@ -47,3 +47,5 @@ async def list_history(
         order_by: str = "created_at",
         order="desc",
     ) -> PaginatedResult[ContextHistoryItem]: ...
+
+    async def delete_history_from_id(self, *, context_id: UUID, from_id: UUID) -> int: ...

apps/agentstack-server/src/agentstack_server/infrastructure/persistence/repositories/context.py

@@ -213,6 +213,28 @@ async def list_history(
             has_more=result.has_more,
         )
 
+    async def delete_history_from_id(self, *, context_id: UUID, from_id: UUID) -> int:
+        """Delete all history items from a specific item onwards (inclusive) for a context"""
+        # First, get the created_at timestamp of the item to delete from
+        query_item = select(context_history_table.c.created_at).where(
+            context_history_table.c.id == from_id,
+            context_history_table.c.context_id == context_id,
+        )
+        result = await self._connection.execute(query_item)
+        row = result.first()
+        if not row:
+            raise EntityNotFoundError("context_history_item", from_id)
+
+        created_at = row[0]
+
+        # Delete all history items from the specified item onwards (created_at >= the target item's created_at)
+        query = delete(context_history_table).where(
+            context_history_table.c.context_id == context_id,
+            context_history_table.c.created_at >= created_at,
+        )
+        result = await self._connection.execute(query)
+        return result.rowcount
+
     def _row_to_context_history_item(self, row: Row) -> ContextHistoryItem:
         return ContextHistoryItem(
             id=row.id,

apps/agentstack-server/src/agentstack_server/service_layer/services/contexts.py

@@ -271,3 +271,12 @@ async def list_history(
                 order=pagination.order,
                 order_by=pagination.order_by,
             )
+
+    async def delete_history_from_id(self, *, context_id: UUID, from_id: UUID, user: User) -> None:
+        """Delete all history items from a specific item onwards (inclusive)"""
+        async with self._uow() as uow:
+            # Verify user has access to this context
+            await uow.contexts.get(context_id=context_id, user_id=user.id)
+            # Delete history items from the specified ID onwards
+            await uow.contexts.delete_history_from_id(context_id=context_id, from_id=from_id)
+            await uow.commit()

apps/agentstack-server/tests/e2e/routes/test_contexts.py

@@ -269,3 +269,43 @@ async def test_context_provider_filtering(subtests):
     with subtests.test("get context includes provider_id"):
         fetched_context = await Context.get(context_with_provider1.id)
         assert fetched_context.provider_id == provider1.id
+
+
+@pytest.mark.usefixtures("clean_up", "setup_platform_client")
+async def test_delete_context_history_from_id(subtests):
+    """Test deleting context history from a specific item ID onwards."""
+
+    context = None
+    history_items = []
+    n_messages = 3
+
+    with subtests.test("create context and add multiple history items"):
+        context = await Context.create()
+        for i in range(n_messages):
+            message = AgentMessage(text=f"Test message {i}")
+            await context.add_history_item(data=message)
+
+        history = await context.list_history(limit=50)
+        history_items = history.items
+        assert len(history.items) == n_messages
+
+    with subtests.test("delete history from a middle item onwards"):
+        await context.delete_history_from_id(from_id=history_items[1].id)
+
+        remaining_history = await context.list_history(limit=50)
+        remaining_ids = [item.id for item in remaining_history.items]
+        assert len(remaining_history.items) == 1
+        assert history_items[0].id in remaining_ids
+        assert history_items[1].id not in remaining_ids
+        assert history_items[2].id not in remaining_ids
+
+    with subtests.test("delete with nonexistent item_id raises error"):
+        nonexistent_id = uuid.uuid4()
+        with pytest.raises(HTTPStatusError) as exc_info:
+            await context.delete_history_from_id(from_id=nonexistent_id)
+        assert exc_info.value.response.status_code == 404
+
+    with subtests.test("delete from first item deletes all"):
+        await context.delete_history_from_id(from_id=remaining_ids[0])
+        remaining_history = await context.list_history(limit=50)
+        assert len(remaining_history.items) == 0

docs/development/agent-integration/multi-turn.mdx

@@ -276,3 +276,45 @@ This advanced example demonstrates several key concepts:
 - **Memory Management**: Converts conversation history to framework format and loads it into agent memory
 - **Tool Usage**: Includes thinking tools and conditional requirements for better reasoning
 - **Persistent Storage**: Uses `PlatformContextStore` for conversation persistence
+
+### Editing and Removing Messages from History
+
+Sometimes you may need to edit a previous message in a conversation or remove messages that are no longer relevant. 
+The Agent Stack provides a mechanism to delete history items from a specific point onward, allowing you to effectively “rewind” the conversation and replace a message with an edited version. 
+Possible use cases include editing a previous message, clearing irrelevant exchanges, or removing messages that resulted from processing errors.
+
+Here's an example of a function for editing a user message in a conversation using the context API, assuming you know the message id:
+
+```python
+import uuid
+from typing import Any
+
+from a2a.types import Message, Part, Role, TextPart
+from agentstack_sdk.platform.context import Context
+from agentstack_sdk.server.context import RunContext
+
+async def edit_message_in_context(run_context: RunContext, message_id: str, new_text: str, metadata: dict[str, Any] | None = None):
+    """Edit a message in the conversation history"""
+    context = await Context.get(run_context.context_id)
+
+    # Step 1: Delete from this message onwards
+    await context.delete_history_from_id(from_id=message_id)
+
+    # Step 2: Add the corrected message
+    corrected_message = Message(
+        message_id=str(uuid.uuid4()),
+        parts=[Part(root=TextPart(text=new_text))],
+        role=Role.user,
+        context_id=context.id,
+        metadata=metadata,
+    )
+    await run_context.store(data=corrected_message)
+```
+
+<Tip>
+When you delete history from a specific message onwards, all messages created after that point (including the message itself) are removed. This effectively creates a new conversation branch starting from the message before the deleted one.
+</Tip>
+
+<Warning>
+This operation is permanent. Once messages are deleted, they cannot be recovered. Consider informing users about this operation or implementing a confirmation step for important conversations.
+</Warning>