feat(sdk): add host integration extension points

docs/python-sdk.md

@@ -490,6 +490,7 @@ Run the agent once and return a `RunResult`.
 | `sender_id` | `str` | `"user"` | Logical sender identifier used in runtime context. |
 | `media` | `list[str] \| None` | `None` | Optional local media paths attached to the message. |
 | `ephemeral` | `bool` | `False` | Run without persisting the turn or compacting session history. |
+| `attributes` | `Mapping[str, Any] \| None` | `None` | Caller-owned request data for host integrations. It is available to context providers and turn-hook factories, but is not added to trusted message metadata or persisted in session messages. |
 | `hooks` | `list[AgentHook] \| None` | `None` | Lifecycle hooks for this run only. |
 | `model` | `str \| None` | `None` | Override the model for this run only. |
 | `model_preset` | `str \| None` | `None` | Override the model preset for this run only. |
@@ -631,9 +632,67 @@ Do not expose exported snapshots directly to chat users.
 |-------------------|-------------|
 | `model` | Current runtime model name. |
 | `workspace` | Current runtime workspace path. |
+| `add_context_provider(provider)` | Register an async per-turn context provider and return an unsubscribe callback. |
+| `subscribe(event_type, handler)` | Subscribe a sync or async handler to one runtime event type and return an unsubscribe callback. |
 | `await compact_session(session_key)` | Run token/replay-window consolidation for a session. |
 | `await compact_idle_session(session_key, max_suffix=8)` | Run idle-session compaction and return its summary. |
 
+### Host integration context and persistence events
+
+Host applications can attach external context without copying or modifying the
+nanobot agent loop. A context provider receives a `RequestContext` before each
+model turn and may return one or more `RuntimeContextBlock` values. Use
+`attributes` for caller-owned routing data; nanobot keeps it separate from
+trusted channel metadata and does not persist it in session messages.
+
+`SessionTurnPersisted` is published after a non-ephemeral turn has been saved.
+Its handler may read the completed transcript through `bot.sessions`. Runtime
+event handlers run in registration order, and async handlers are awaited before
+the run continues.
+
+```python
+from nanobot import (
+    Nanobot,
+    RequestContext,
+    RuntimeContextBlock,
+    SessionTurnPersisted,
+)
+
+
+async def run_with_external_memory(openviking) -> None:
+    async with Nanobot.from_config() as bot:
+        async def load_context(request: RequestContext):
+            resource = request.attributes.get("resource")
+            if not resource:
+                return None
+            text = await openviking.search(resource, request.original_user_text or "")
+            return RuntimeContextBlock(source="openviking", content=text)
+
+        async def sync_saved_turn(event: SessionTurnPersisted):
+            snapshot = bot.sessions.export(event.context.session_key)
+            if snapshot is not None:
+                await openviking.sync(
+                    resource=event.context.attributes.get("resource"),
+                    messages=snapshot.messages,
+                )
+
+        remove_context = bot.runtime.add_context_provider(load_context)
+        remove_sync = bot.runtime.subscribe(SessionTurnPersisted, sync_saved_turn)
+        try:
+            await bot.run(
+                "Continue the architecture discussion",
+                session_key="project:openviking",
+                attributes={"resource": "viking://projects/openviking"},
+            )
+        finally:
+            remove_sync()
+            remove_context()
+```
+
+Context providers are trusted host extensions: their returned text becomes
+model-visible context. Validate and delimit untrusted external content before
+returning it. `SessionTurnPersisted` is not emitted for `ephemeral=True` runs.
+
 ## Hooks
 
 Hooks let you observe or customize the agent loop. Subclass `AgentHook` and override the methods you need.