Add request metadata and cache-aware usage to UniResponse

docs/docs/.vitepress/config.mts

@@ -309,8 +309,8 @@ export default withMermaid({
                 link: "/guide/api-reference/classes/SuspendEnum",
               },
               {
-                text: "SuspendObjectStream",
-                link: "/guide/api-reference/classes/SuspendObjectStream",
+                text: "RequestMetadata",
+                link: "/guide/api-reference/classes/RequestMetadata",
               },
               {
                 text: "EmbeddingChunk",
@@ -663,8 +663,8 @@ export default withMermaid({
                 link: "/zh/guide/api-reference/classes/SuspendEnum",
               },
               {
-                text: "SuspendObjectStream",
-                link: "/zh/guide/api-reference/classes/SuspendObjectStream",
+                text: "RequestMetadata",
+                link: "/zh/guide/api-reference/classes/RequestMetadata",
               },
               {
                 text: "EmbeddingChunk",

docs/docs/guide/api-reference/classes/ChatManager.md

@@ -32,16 +32,12 @@ Clean up running chat objects under the specified key, keeping only up to `maxit
 
 **Returns:** `bool` — `True` if cleanup was performed, `False` otherwise
 
----
-
 ### `get_all_objs() -> list[ChatObjectMeta]`
 
 Get metadata for all running chat objects across all sessions.
 
 **Returns:** `list[ChatObjectMeta]` — List of all running chat object metadata snapshots
 
----
-
 ### `get_objs(session_id: str) -> list[ChatObject]`
 
 Get all active chat objects for a given session ID.
@@ -52,8 +48,6 @@ Get all active chat objects for a given session ID.
 
 **Returns:** `list[ChatObject]` — List of chat objects for the session
 
----
-
 ### `async clean_chat_objects(maxitems: int = 10) -> None`
 
 Asynchronously clean up all running chat objects across all sessions, limiting each session to `maxitems` objects.
@@ -62,8 +56,6 @@ Asynchronously clean up all running chat objects across all sessions, limiting e
 
 - `maxitems` (`int`, optional): Maximum number of objects per session. Defaults to `10`.
 
----
-
 ### `async add_chat_object(chat_object: ChatObject) -> None`
 
 Register a new `ChatObject` instance with the manager. Creates a metadata snapshot and inserts the object at the beginning of the session's list.

docs/docs/guide/api-reference/classes/ClientManager.md

@@ -57,8 +57,6 @@ Initializes the ClientManager (runs only once due to singleton pattern).
 
 **Note:** Initialization logic executes only on the first instantiation.
 
----
-
 _All other methods are inherited from [`MultiClientManager`](MultiClientManager.md):_
 
 - `get_client_by_script(server_script)` - Get client by server script

docs/docs/guide/api-reference/classes/MemoryLimiter.md

@@ -66,16 +66,12 @@ Override the default abstract instruction used for context summarization.
 - `TypeError`: If instruction is not a string
 - `ValueError`: If instruction is empty
 
----
-
 ### `get_abstract_instruction() -> str`
 
 Get the current abstract instruction text.
 
 **Returns:** `str`
 
----
-
 ### `reset_abstract_instruction()`
 
 Reset the abstract instruction to the framework default.

docs/docs/guide/api-reference/classes/ModelAdapter.md

@@ -8,7 +8,7 @@ The `ModelAdapter` class provides a unified interface for integrating different
 
 Adapters are automatically registered with the [`AdapterManager`](#adaptermanager) when defined, unless marked as abstract or explicitly disabled from registration.
 
-> **Note**: The `ModelAdapter` base class has been moved from `amrita_core.protocol` to `amrita_core.base.adapter`. The `amrita_core.protocol` module is now a deprecated re-export wrapper.
+> **Note**: The `ModelAdapter` base class has been moved from `amrita_core.protocol` to `amrita_core.base.adapter`. The `amrita_core.protocol` compatibility endpoint was removed in v0.10.x+; import from `amrita_core.base.adapter`.
 
 ## Class Definition
 

docs/docs/guide/api-reference/classes/RequestMetadata.md

@@ -0,0 +1,34 @@
+# RequestMetadata
+
+`RequestMetadata` captures per-request diagnostic information returned by every adapter call through `UniResponse.metadata`.
+
+## Properties
+
+- `request_id` (str): Auto-generated unique request ID (UUID4). Defaults to a new UUID if not provided.
+- `original_request_id` (str | None): Original request ID returned by the LLM provider adapter (e.g., OpenAI's `_request_id`, Anthropic's `request_id`). `None` when unavailable.
+- `model` (str): The model used for the request. Defaults to `"__NOT_GIVEN__"` when not available (e.g., streaming before the first chunk).
+- `stop_sequence` (str | None): The stop sequence that terminated generation, if any.
+- `stop_reason` (STOP_REASON | None): Why the generation stopped. One of:
+
+  | Value             | Meaning                    |
+  | ----------------- | -------------------------- |
+  | `"end_turn"`      | Natural completion         |
+  | `"max_tokens"`    | Hit max token limit        |
+  | `"stop_sequence"` | Matched a stop sequence    |
+  | `"tool_use"`      | Model called a tool        |
+  | `"pause_turn"`    | Anthropic pause turn       |
+  | `"refusal"`       | Content filtered / refused |
+
+## Usage
+
+```python
+from amrita_core.types.response import RequestMetadata
+
+# Accessed via UniResponse
+response: UniResponse = ...
+print(response.metadata.model)          # e.g. "gpt-4o"
+print(response.metadata.stop_reason)    # e.g. "end_turn"
+print(response.metadata.original_request_id)  # Provider's request ID
+```
+
+> **Note**: `extra="allow"` is configured, so provider-specific fields may appear in addition to the standard ones.

docs/docs/guide/api-reference/classes/StrategyLikedObject.md

@@ -44,8 +44,6 @@ Called once by the framework when the execution context is ready. Subclasses may
 
 **Returns:** `Self`
 
----
-
 ### `async single_execute() -> bool`
 
 Execute a single agent step for `"agent"` and `"agent-mixed"` category strategies. Called by the framework to perform one iteration of tool calling.
@@ -54,8 +52,6 @@ Execute a single agent step for `"agent"` and `"agent-mixed"` category strategie
 
 **Note:** This method is used by `"agent"` and `"agent-mixed"` category strategies. `"rag"` and `"workflow"` category strategies should implement `run()` instead.
 
----
-
 ### `async run() -> None`
 
 Run the complete agent strategy for `"rag"` and `"workflow"` category strategies. Gives full control to the strategy implementation for managing tool calling iterations, context construction, error handling, and response generation.
@@ -67,8 +63,6 @@ Run the complete agent strategy for `"rag"` and `"workflow"` category strategies
 
 **Note:** This method is used by `"rag"` and `"workflow"` category strategies. `"agent"` and `"agent-mixed"` category strategies should implement `single_execute()` instead.
 
----
-
 ### `async call_tool(tool_call: ToolCall) -> str`
 
 Execute a single tool call without modifying the agent's context.
@@ -83,16 +77,12 @@ Execute a single tool call without modifying the agent's context.
 
 **Returns:** `str` — The string response from the tool execution, or a default message if the tool returns `None`
 
----
-
 ### `async on_limited() -> None`
 
 Handle the event when the agent reaches its tool calling limit. Called when the agent strategy has reached the maximum allowed number of tool calls.
 
 **Default behavior:** Sends a notification message to the user about the limit being reached.
 
----
-
 ### `async on_exception(exc: BaseException) -> None`
 
 Handle exceptions that occur during strategy execution.
@@ -101,14 +91,10 @@ Handle exceptions that occur during strategy execution.
 
 - `exc` (`BaseException`): The exception that occurred
 
----
-
 ### `async on_post_process() -> None`
 
 Used to process after all steps are completed successfully.
 
----
-
 ### `classmethod get_category() -> Literal["agent", "workflow", "rag", "agent-mixed"]`
 
 Get the category of the agent strategy. This is an abstract method that must be implemented by subclasses.

docs/docs/guide/api-reference/classes/UniResponse.md

@@ -10,6 +10,7 @@ The UniResponse class provides a unified response format.
 - `tool_calls` (T_TOOL): Tool call results, T_TOOL is a generic parameter
 - `reasoning_content` (str | None): Reasoning/thinking content from the model, if the model supports it (e.g., o1, Claude with extended thinking)
 - `reasoning_signature` (str | None): Anthropic thinking signature, required for round-tripping thinking content with Anthropic API
+- `metadata` ([RequestMetadata](RequestMetadata.md)): Request metadata containing request ID, model name, stop reason, and original provider request ID
 
 ## Description
 

docs/docs/guide/api-reference/classes/UniResponseUsage.md

@@ -7,6 +7,8 @@ UniResponseUsage class represents usage statistics for responses.
 - `prompt_tokens` (T_INT): Number of tokens used in the prompt
 - `completion_tokens` (T_INT): Number of tokens used in the completion (generation)
 - `total_tokens` (T_INT): Total number of tokens used
+- `cache_creation` (int | None): Number of tokens used to create the cache entry (Anthropic prompt caching)
+- `cache_hit` (int | None): Number of tokens read from the cache (Anthropic prompt caching)
 
 ## Description
 

docs/docs/guide/api-reference/index.md

@@ -2,22 +2,7 @@
 
 ## 7.1 Core API Functions
 
-### 7.1.1 init() - Initialization (Deprecated)
-
-> **Deprecated**: The `init()` function is deprecated since v0.9.0rc1. It is now an empty stub and no longer performs any initialisation. Use `load_amrita()` for async initialisation instead.
-
-```python
-from amrita_core import init
-
-# No longer necessary - this is now a no-op
-init()
-```
-
-**Purpose**: Previously prepared internal components, initialized Jieba, and loaded built-in modules. Now deprecated.
-
-**Migration**: Remove any calls to `init()` in your code. Use `load_amrita()` when async initialisation is needed (e.g., for MCP client setup).
-
-### 7.1.2 load_amrita() - Loading Framework
+### 7.1.1 load_amrita() - Loading Framework
 
 The `load_amrita()` function asynchronously loads AmritaCore components, particularly when MCP client functionality is enabled.
 

docs/docs/guide/concepts/agent-strategy.md

@@ -217,14 +217,14 @@ async def use_builtin_strategies():
     )
 
     # Use the agents
-    chat1 = standard_agent.get_chatobject("What can you do?")
-    chat2 = hybrid_agent.get_chatobject("Analyze this data")
-    chat3 = no_action_agent.get_chatobject("Just respond directly")
-
-    async with chat1.begin(), chat2.begin(), chat3.begin():
-        response1 = await chat1.full_response()
-        response2 = await chat2.full_response()
-        response3 = await chat3.full_response()
+    chat = standard_agent.get_chatobject("What can you do?")
+
+    chat.begin()
+    async with chat:
+        async for chunk in chat.io_stream.get_response_generator():
+            content = chunk if isinstance(chunk, str) else chunk.get_content()
+            print(content, end="", flush=True)
+    # Chat is cleaned up automatically after exiting context
 ```
 
 ## Stateful Strategies with StrategyLikedObject

docs/docs/guide/concepts/data-backend.md

@@ -2,8 +2,6 @@
 
 The **data backend** mechanism decouples memory and ability management from `ChatObject`, enabling pluggable storage backends (in-memory global containers, databases, distributed caches, etc.) without changing the core execution logic.
 
----
-
 ## BackendSlots
 
 [`BackendSlots`](../api-reference/classes/BackendSlots.md) is a simple dataclass that holds two backend references:
@@ -19,8 +17,6 @@ class BackendSlots:
 
 `ChatObject` receives a `BackendSlots` instance and delegates all data I/O to it via the workflow nodes `_load_state` and `_commit_memory`.
 
----
-
 ## AbilityBackend (Abstract)
 
 [`AbilityBackend`](../api-reference/classes/AbilityBackend.md) defines the interface for loading session abilities:
@@ -45,8 +41,6 @@ class AbilityBackend:
 - `load_ability_all()`: returns a fully populated `AbilityContext`
 - `load_mcp_clients()` / `load_tools()` / `load_presets()`: granular loading, used when `DatabackendOptions` skip flags are set
 
----
-
 ## MemoryBackend (Abstract)
 
 [`MemoryBackend`](../api-reference/classes/MemoryBackend.md) defines the interface for loading and persisting conversation memory:
@@ -65,8 +59,6 @@ class MemoryBackend:
 - `load_memory()`: called at the start of each `ChatObject` execution
 - `commit_memory()`: called after completion to persist changes
 
----
-
 ## LegacyBackend — Built-in Global Container
 
 [`LegacyBackend`](../api-reference/classes/LegacyBackend.md) implements both `AbilityBackend` and `MemoryBackend` using in-process global containers. It is the **default** backend when none is provided:
@@ -96,8 +88,6 @@ backend = BackendSlots(ability=LegacyBackend(), memory=LegacyBackend())
 
 > **Note**: `LegacyBackend` stores data **in memory only**. Restart the process and all data is lost. For persistence, implement a custom backend.
 
----
-
 ## DatabackendOptions — Fine-Grained Control
 
 [`DatabackendOptions`](../api-reference/classes/DatabackendOptions.md) controls which backend operations are skipped during a `ChatObject` run:
@@ -117,8 +107,6 @@ options = DatabackendOptions(
 
 Pass options to `ChatObject` via the `backend_options` parameter, or to `AgentRuntime.get_chatobject()` via `**kwargs`.
 
----
-
 ## Custom Backend Example
 
 Implement a custom backend that persists memory to a JSON file:
@@ -169,8 +157,6 @@ runtime = AgentRuntime(
 )
 ```
 
----
-
 ## Data Flow Summary
 
 ```mermaid