klaude-code 1.2.18__py3-none-any.whl → 1.2.20__py3-none-any.whl

klaude_code/core/tool/tool_context.py

@@ -9,6 +9,8 @@ from klaude_code.protocol import model
 from klaude_code.protocol.sub_agent import SubAgentResult
 from klaude_code.session.session import Session
 
+type FileTracker = MutableMapping[str, model.FileStatus]
+
 
 @dataclass
 class TodoContext:
@@ -44,15 +46,13 @@ class ToolContextToken:
     finishes running.
     """
 
-    file_tracker_token: Token[MutableMapping[str, float] | None] | None
+    file_tracker_token: Token[FileTracker | None] | None
     todo_token: Token[TodoContext | None] | None
 
 
 # Holds the current file tracker mapping for tool execution context.
 # Set by Agent/Reminder right before invoking a tool.
-current_file_tracker_var: ContextVar[MutableMapping[str, float] | None] = ContextVar(
-    "current_file_tracker", default=None
-)
+current_file_tracker_var: ContextVar[FileTracker | None] = ContextVar("current_file_tracker", default=None)
 
 
 # Holds the todo access context for tools.
@@ -83,7 +83,7 @@ def reset_tool_context(token: ToolContextToken) -> None:
 
 
 @contextmanager
-def tool_context(file_tracker: MutableMapping[str, float], todo_ctx: TodoContext) -> Generator[ToolContextToken]:
+def tool_context(file_tracker: FileTracker, todo_ctx: TodoContext) -> Generator[ToolContextToken]:
     """Context manager for setting and resetting tool execution context."""
 
     file_tracker_token = current_file_tracker_var.set(file_tracker)
@@ -102,7 +102,7 @@ def build_todo_context(session: Session) -> TodoContext:
     return TodoContext(get_todos=store.get, set_todos=store.set)
 
 
-def get_current_file_tracker() -> MutableMapping[str, float] | None:
+def get_current_file_tracker() -> FileTracker | None:
     """Return the current file tracker mapping for this tool context."""
 
     return current_file_tracker_var.get()

klaude_code/core/tool/tool_registry.py

@@ -66,7 +66,7 @@ def load_agent_tools(
 
     # Main agent tools
     if "gpt-5" in model_name:
-        tool_names = [tools.BASH, tools.APPLY_PATCH, tools.UPDATE_PLAN]
+        tool_names = [tools.BASH, tools.READ, tools.APPLY_PATCH, tools.UPDATE_PLAN]
     elif "gemini-3" in model_name:
         tool_names = [tools.BASH, tools.READ, tools.EDIT, tools.WRITE]
     else:

klaude_code/core/tool/tool_runner.py

@@ -4,13 +4,9 @@ from dataclasses import dataclass
 
 from klaude_code import const
 from klaude_code.core.tool.report_back_tool import ReportBackTool
-from klaude_code.core.tool.tool_abc import ToolABC
+from klaude_code.core.tool.tool_abc import ToolABC, ToolConcurrencyPolicy
 from klaude_code.core.tool.truncation import truncate_tool_output
 from klaude_code.protocol import model, tools
-from klaude_code.protocol.sub_agent import is_sub_agent_tool
-
-# Tools that can run concurrently (IO-bound, no local state mutations)
-_CONCURRENT_TOOLS: frozenset[str] = frozenset({tools.WEB_SEARCH, tools.WEB_FETCH})
 
 
 async def run_tool(tool_call: model.ToolCallItem, registry: dict[str, type[ToolABC]]) -> model.ToolResultItem:
@@ -214,14 +210,18 @@ class ToolExecutor:
 
         task.add_done_callback(_cleanup)
 
-    @staticmethod
     def _partition_tool_calls(
+        self,
         tool_calls: list[model.ToolCallItem],
     ) -> tuple[list[model.ToolCallItem], list[model.ToolCallItem]]:
         sequential_tool_calls: list[model.ToolCallItem] = []
         concurrent_tool_calls: list[model.ToolCallItem] = []
         for tool_call in tool_calls:
-            if is_sub_agent_tool(tool_call.name) or tool_call.name in _CONCURRENT_TOOLS:
+            tool_cls = self._registry.get(tool_call.name)
+            policy = (
+                tool_cls.metadata().concurrency_policy if tool_cls is not None else ToolConcurrencyPolicy.SEQUENTIAL
+            )
+            if policy == ToolConcurrencyPolicy.CONCURRENT:
                 concurrent_tool_calls.append(tool_call)
             else:
                 sequential_tool_calls.append(tool_call)

klaude_code/core/tool/web/web_fetch_tool.py

@@ -6,12 +6,12 @@ import urllib.error
 import urllib.request
 from http.client import HTTPResponse
 from pathlib import Path
-from urllib.parse import urlparse
+from urllib.parse import quote, urlparse, urlunparse
 
 from pydantic import BaseModel
 
 from klaude_code import const
-from klaude_code.core.tool.tool_abc import ToolABC, load_desc
+from klaude_code.core.tool.tool_abc import ToolABC, ToolConcurrencyPolicy, ToolMetadata, load_desc
 from klaude_code.core.tool.tool_registry import register
 from klaude_code.protocol import llm_param, model, tools
 
@@ -20,15 +20,70 @@ DEFAULT_USER_AGENT = "Mozilla/5.0 (compatible; KlaudeCode/1.0)"
 WEB_FETCH_SAVE_DIR = Path(const.TOOL_OUTPUT_TRUNCATION_DIR) / "web"
 
 
-def _extract_content_type(response: HTTPResponse) -> str:
-    """Extract the base content type without charset parameters."""
-    content_type = response.getheader("Content-Type", "")
-    return content_type.split(";")[0].strip().lower()
+def _encode_url(url: str) -> str:
+    """Encode non-ASCII characters in URL to make it safe for HTTP requests."""
+    parsed = urlparse(url)
+    encoded_path = quote(parsed.path, safe="/-_.~")
+    encoded_query = quote(parsed.query, safe="=&-_.~")
+    # Handle IDN (Internationalized Domain Names) by encoding to punycode
+    try:
+        netloc = parsed.netloc.encode("idna").decode("ascii")
+    except UnicodeError:
+        netloc = parsed.netloc
+    return urlunparse((parsed.scheme, netloc, encoded_path, parsed.params, encoded_query, parsed.fragment))
+
+
+def _extract_content_type_and_charset(response: HTTPResponse) -> tuple[str, str | None]:
+    """Extract the base content type and charset from Content-Type header."""
+    content_type_header = response.getheader("Content-Type", "")
+    parts = content_type_header.split(";")
+    content_type = parts[0].strip().lower()
+
+    charset = None
+    for part in parts[1:]:
+        part = part.strip()
+        if part.lower().startswith("charset="):
+            charset = part[8:].strip().strip("\"'")
+            break
+
+    return content_type, charset
+
+
+def _detect_encoding(data: bytes, declared_charset: str | None) -> str:
+    """Detect the encoding of the data."""
+    # 1. Use declared charset from HTTP header if available
+    if declared_charset:
+        return declared_charset
+
+    # 2. Try to detect from HTML meta tags (check first 2KB)
+    head = data[:2048].lower()
+    # <meta charset="xxx">
+    if match := re.search(rb'<meta[^>]+charset=["\']?([^"\'\s>]+)', head):
+        return match.group(1).decode("ascii", errors="ignore")
+    # <meta http-equiv="Content-Type" content="text/html; charset=xxx">
+    if match := re.search(rb'content=["\'][^"\']*charset=([^"\'\s;]+)', head):
+        return match.group(1).decode("ascii", errors="ignore")
+
+    # 3. Use chardet for automatic detection
+    import chardet
 
+    result = chardet.detect(data)
+    if result["encoding"] and result["confidence"] and result["confidence"] > 0.7:
+        return result["encoding"]
 
-def _validate_utf8(data: bytes) -> str:
-    """Validate and decode bytes as UTF-8."""
-    return data.decode("utf-8")
+    # 4. Default to UTF-8
+    return "utf-8"
+
+
+def _decode_content(data: bytes, declared_charset: str | None) -> str:
+    """Decode bytes to string with automatic encoding detection."""
+    encoding = _detect_encoding(data, declared_charset)
+
+    try:
+        return data.decode(encoding)
+    except (UnicodeDecodeError, LookupError):
+        # Fallback: try UTF-8 with replacement for invalid chars
+        return data.decode("utf-8", errors="replace")
 
 
 def _convert_html_to_markdown(html: str) -> str:
@@ -98,17 +153,22 @@ def _fetch_url(url: str, timeout: int = DEFAULT_TIMEOUT_SEC) -> tuple[str, str]:
         "Accept": "text/markdown, */*",
         "User-Agent": DEFAULT_USER_AGENT,
     }
-    request = urllib.request.Request(url, headers=headers)
+    encoded_url = _encode_url(url)
+    request = urllib.request.Request(encoded_url, headers=headers)
 
     with urllib.request.urlopen(request, timeout=timeout) as response:
-        content_type = _extract_content_type(response)
+        content_type, charset = _extract_content_type_and_charset(response)
         data = response.read()
-        text = _validate_utf8(data)
+        text = _decode_content(data, charset)
         return content_type, text
 
 
 @register(tools.WEB_FETCH)
 class WebFetchTool(ToolABC):
+    @classmethod
+    def metadata(cls) -> ToolMetadata:
+        return ToolMetadata(concurrency_policy=ToolConcurrencyPolicy.CONCURRENT, has_side_effects=True)
+
     @classmethod
     def schema(cls) -> llm_param.ToolSchema:
         return llm_param.ToolSchema(
@@ -149,7 +209,7 @@ class WebFetchTool(ToolABC):
         if not url.startswith(("http://", "https://")):
             return model.ToolResultItem(
                 status="error",
-                output="Invalid URL: must start with http:// or https://",
+                output=f"Invalid URL: must start with http:// or https:// (url={url})",
             )
 
         try:
@@ -170,25 +230,20 @@ class WebFetchTool(ToolABC):
         except urllib.error.HTTPError as e:
             return model.ToolResultItem(
                 status="error",
-                output=f"HTTP error {e.code}: {e.reason}",
+                output=f"HTTP error {e.code}: {e.reason} (url={url})",
             )
         except urllib.error.URLError as e:
             return model.ToolResultItem(
                 status="error",
-                output=f"URL error: {e.reason}",
-            )
-        except UnicodeDecodeError as e:
-            return model.ToolResultItem(
-                status="error",
-                output=f"Content is not valid UTF-8: {e}",
+                output=f"URL error: {e.reason} (url={url})",
             )
         except TimeoutError:
             return model.ToolResultItem(
                 status="error",
-                output=f"Request timed out after {DEFAULT_TIMEOUT_SEC} seconds",
+                output=f"Request timed out after {DEFAULT_TIMEOUT_SEC} seconds (url={url})",
             )
         except Exception as e:
             return model.ToolResultItem(
                 status="error",
-                output=f"Failed to fetch URL: {e}",
+                output=f"Failed to fetch URL: {e} (url={url})",
             )

klaude_code/core/tool/web/web_search_tool.py

@@ -4,7 +4,7 @@ from pathlib import Path
 
 from pydantic import BaseModel
 
-from klaude_code.core.tool.tool_abc import ToolABC, load_desc
+from klaude_code.core.tool.tool_abc import ToolABC, ToolConcurrencyPolicy, ToolMetadata, load_desc
 from klaude_code.core.tool.tool_registry import register
 from klaude_code.protocol import llm_param, model, tools
 
@@ -62,6 +62,10 @@ def _format_results(results: list[SearchResult]) -> str:
 
 @register(tools.WEB_SEARCH)
 class WebSearchTool(ToolABC):
+    @classmethod
+    def metadata(cls) -> ToolMetadata:
+        return ToolMetadata(concurrency_policy=ToolConcurrencyPolicy.CONCURRENT, has_side_effects=False)
+
     @classmethod
     def schema(cls) -> llm_param.ToolSchema:
         return llm_param.ToolSchema(

klaude_code/llm/anthropic/client.py

@@ -1,4 +1,5 @@
 import json
+import os
 from collections.abc import AsyncGenerator
 from typing import override
 
@@ -61,11 +62,20 @@ def build_payload(param: llm_param.LLMCallParameter) -> MessageCreateParamsStrea
 class AnthropicClient(LLMClientABC):
     def __init__(self, config: llm_param.LLMConfigParameter):
         super().__init__(config)
-        client = anthropic.AsyncAnthropic(
-            api_key=config.api_key,
-            base_url=config.base_url,
-            timeout=httpx.Timeout(300.0, connect=15.0, read=285.0),
-        )
+        # Remove ANTHROPIC_AUTH_TOKEN env var to prevent anthropic SDK from adding
+        # Authorization: Bearer header that may conflict with third-party APIs
+        # (e.g., deepseek, moonshot) that use Authorization header for authentication.
+        # The API key will be sent via X-Api-Key header instead.
+        saved_auth_token = os.environ.pop("ANTHROPIC_AUTH_TOKEN", None)
+        try:
+            client = anthropic.AsyncAnthropic(
+                api_key=config.api_key,
+                base_url=config.base_url,
+                timeout=httpx.Timeout(300.0, connect=15.0, read=285.0),
+            )
+        finally:
+            if saved_auth_token is not None:
+                os.environ["ANTHROPIC_AUTH_TOKEN"] = saved_auth_token
         self.client: anthropic.AsyncAnthropic = client
 
     @classmethod
@@ -120,35 +130,38 @@ class AnthropicClient(LLMClientABC):
                     case BetaRawContentBlockDeltaEvent() as event:
                         match event.delta:
                             case BetaThinkingDelta() as delta:
-                                metadata_tracker.record_token()
+                                if delta.thinking:
+                                    metadata_tracker.record_token()
                                 accumulated_thinking.append(delta.thinking)
                                 yield model.ReasoningTextDelta(
                                     content=delta.thinking,
                                     response_id=response_id,
                                 )
                             case BetaSignatureDelta() as delta:
-                                metadata_tracker.record_token()
                                 yield model.ReasoningEncryptedItem(
                                     encrypted_content=delta.signature,
                                     response_id=response_id,
                                     model=str(param.model),
                                 )
                             case BetaTextDelta() as delta:
-                                metadata_tracker.record_token()
+                                if delta.text:
+                                    metadata_tracker.record_token()
                                 accumulated_content.append(delta.text)
                                 yield model.AssistantMessageDelta(
                                     content=delta.text,
                                     response_id=response_id,
                                 )
                             case BetaInputJSONDelta() as delta:
-                                metadata_tracker.record_token()
                                 if current_tool_inputs is not None:
+                                    if delta.partial_json:
+                                        metadata_tracker.record_token()
                                     current_tool_inputs.append(delta.partial_json)
                             case _:
                                 pass
                     case BetaRawContentBlockStartEvent() as event:
                         match event.content_block:
                             case BetaToolUseBlock() as block:
+                                metadata_tracker.record_token()
                                 yield model.ToolCallStartItem(
                                     response_id=response_id,
                                     call_id=block.id,
@@ -161,6 +174,7 @@ class AnthropicClient(LLMClientABC):
                                 pass
                     case BetaRawContentBlockStopEvent() as event:
                         if len(accumulated_thinking) > 0:
+                            metadata_tracker.record_token()
                             full_thinking = "".join(accumulated_thinking)
                             yield model.ReasoningTextItem(
                                 content=full_thinking,
@@ -169,12 +183,14 @@ class AnthropicClient(LLMClientABC):
                             )
                             accumulated_thinking.clear()
                         if len(accumulated_content) > 0:
+                            metadata_tracker.record_token()
                             yield model.AssistantMessageItem(
                                 content="".join(accumulated_content),
                                 response_id=response_id,
                             )
                             accumulated_content.clear()
                         if current_tool_name and current_tool_call_id:
+                            metadata_tracker.record_token()
                             yield model.ToolCallItem(
                                 name=current_tool_name,
                                 call_id=current_tool_call_id,

klaude_code/llm/openai_compatible/client.py

@@ -23,7 +23,7 @@ def build_payload(param: llm_param.LLMCallParameter) -> tuple[CompletionCreatePa
 
     extra_body: dict[str, object] = {}
 
-    if param.thinking:
+    if param.thinking and param.thinking.type == "enabled":
         extra_body["thinking"] = {
             "type": param.thinking.type,
             "budget": param.thinking.budget_tokens,
@@ -182,7 +182,10 @@ class OpenAICompatibleClient(LLMClientABC):
             yield model.StreamErrorItem(error=f"{e.__class__.__name__} {e!s}")
 
         # Finalize
-        for item in state.flush_all():
+        flushed_items = state.flush_all()
+        if flushed_items:
+            metadata_tracker.record_token()
+        for item in flushed_items:
             yield item
 
         metadata_tracker.set_response_id(state.response_id)

klaude_code/llm/openrouter/client.py

@@ -35,7 +35,7 @@ def build_payload(
     extra_headers: dict[str, str] = {}
 
     if param.thinking:
-        if param.thinking.budget_tokens is not None:
+        if param.thinking.type != "disabled" and param.thinking.budget_tokens is not None:
             extra_body["reasoning"] = {
                 "max_tokens": param.thinking.budget_tokens,
                 "enable": True,
@@ -139,7 +139,8 @@ class OpenRouterClient(LLMClientABC):
                     for item in reasoning_details:
                         try:
                             reasoning_detail = ReasoningDetail.model_validate(item)
-                            metadata_tracker.record_token()
+                            if reasoning_detail.text or reasoning_detail.summary:
+                                metadata_tracker.record_token()
                             state.stage = "reasoning"
                             # Yield delta immediately for streaming
                             if reasoning_detail.text:
@@ -198,7 +199,10 @@ class OpenRouterClient(LLMClientABC):
             yield model.StreamErrorItem(error=f"{e.__class__.__name__} {e!s}")
 
         # Finalize
-        for item in state.flush_all():
+        flushed_items = state.flush_all()
+        if flushed_items:
+            metadata_tracker.record_token()
+        for item in flushed_items:
             yield item
 
         metadata_tracker.set_response_id(state.response_id)

klaude_code/llm/responses/client.py

@@ -77,6 +77,7 @@ async def parse_responses_stream(
                     yield model.StartItem(response_id=response_id)
                 case responses.ResponseReasoningSummaryTextDeltaEvent() as event:
                     if event.delta:
+                        metadata_tracker.record_token()
                         yield model.ReasoningTextDelta(
                             content=event.delta,
                             response_id=response_id,
@@ -89,10 +90,12 @@ async def parse_responses_stream(
                             model=str(param.model),
                         )
                 case responses.ResponseTextDeltaEvent() as event:
-                    metadata_tracker.record_token()
+                    if event.delta:
+                        metadata_tracker.record_token()
                     yield model.AssistantMessageDelta(content=event.delta, response_id=response_id)
                 case responses.ResponseOutputItemAddedEvent() as event:
                     if isinstance(event.item, responses.ResponseFunctionToolCall):
+                        metadata_tracker.record_token()
                         yield model.ToolCallStartItem(
                             response_id=response_id,
                             call_id=event.item.call_id,
@@ -102,6 +105,7 @@ async def parse_responses_stream(
                     match event.item:
                         case responses.ResponseReasoningItem() as item:
                             if item.encrypted_content:
+                                metadata_tracker.record_token()
                                 yield model.ReasoningEncryptedItem(
                                     id=item.id,
                                     encrypted_content=item.encrypted_content,
@@ -109,6 +113,7 @@ async def parse_responses_stream(
                                     model=str(param.model),
                                 )
                         case responses.ResponseOutputMessage() as item:
+                            metadata_tracker.record_token()
                             yield model.AssistantMessageItem(
                                 content="\n".join(
                                     [

klaude_code/protocol/model.py

@@ -69,6 +69,13 @@ class TodoItem(BaseModel):
     active_form: str = Field(default="", alias="activeForm")
 
 
+class FileStatus(BaseModel):
+    """Tracks file state including modification time and memory file flag."""
+
+    mtime: float
+    is_memory: bool = False
+
+
 class TodoUIExtra(BaseModel):
     todos: list[TodoItem]
     new_completed: list[str]
@@ -170,7 +177,7 @@ A conversation history input contains:
 - [DeveloperMessageItem]
 
 When adding a new item, please also modify the following:
-- session.py#_TypeMap
+- session/codec.py (ConversationItem registry derived from ConversationItem union)
 """
 
 

klaude_code/protocol/op.py

@@ -23,6 +23,10 @@ class OperationType(Enum):
     """Enumeration of supported operation types."""
 
     USER_INPUT = "user_input"
+    RUN_AGENT = "run_agent"
+    CHANGE_MODEL = "change_model"
+    CLEAR_SESSION = "clear_session"
+    EXPORT_SESSION = "export_session"
     INTERRUPT = "interrupt"
     INIT_AGENT = "init_agent"
     END = "end"
@@ -51,6 +55,49 @@ class UserInputOperation(Operation):
         await handler.handle_user_input(self)
 
 
+class RunAgentOperation(Operation):
+    """Operation for launching an agent task for a given session."""
+
+    type: OperationType = OperationType.RUN_AGENT
+    session_id: str
+    input: UserInputPayload
+
+    async def execute(self, handler: OperationHandler) -> None:
+        await handler.handle_run_agent(self)
+
+
+class ChangeModelOperation(Operation):
+    """Operation for changing the model used by the active agent session."""
+
+    type: OperationType = OperationType.CHANGE_MODEL
+    session_id: str
+    model_name: str
+
+    async def execute(self, handler: OperationHandler) -> None:
+        await handler.handle_change_model(self)
+
+
+class ClearSessionOperation(Operation):
+    """Operation for clearing the active session and starting a new one."""
+
+    type: OperationType = OperationType.CLEAR_SESSION
+    session_id: str
+
+    async def execute(self, handler: OperationHandler) -> None:
+        await handler.handle_clear_session(self)
+
+
+class ExportSessionOperation(Operation):
+    """Operation for exporting a session transcript to HTML."""
+
+    type: OperationType = OperationType.EXPORT_SESSION
+    session_id: str
+    output_path: str | None = None
+
+    async def execute(self, handler: OperationHandler) -> None:
+        await handler.handle_export_session(self)
+
+
 class InterruptOperation(Operation):
     """Operation for interrupting currently running tasks."""
 

klaude_code/protocol/op_handler.py

@@ -9,7 +9,15 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Protocol
 
 if TYPE_CHECKING:
-    from klaude_code.protocol.op import InitAgentOperation, InterruptOperation, UserInputOperation
+    from klaude_code.protocol.op import (
+        ChangeModelOperation,
+        ClearSessionOperation,
+        ExportSessionOperation,
+        InitAgentOperation,
+        InterruptOperation,
+        RunAgentOperation,
+        UserInputOperation,
+    )
 
 
 class OperationHandler(Protocol):
@@ -19,6 +27,22 @@ class OperationHandler(Protocol):
         """Handle a user input operation."""
         ...
 
+    async def handle_run_agent(self, operation: RunAgentOperation) -> None:
+        """Handle a run agent operation."""
+        ...
+
+    async def handle_change_model(self, operation: ChangeModelOperation) -> None:
+        """Handle a change model operation."""
+        ...
+
+    async def handle_clear_session(self, operation: ClearSessionOperation) -> None:
+        """Handle a clear session operation."""
+        ...
+
+    async def handle_export_session(self, operation: ExportSessionOperation) -> None:
+        """Handle an export session operation."""
+        ...
+
     async def handle_interrupt(self, operation: InterruptOperation) -> None:
         """Handle an interrupt operation."""
         ...

klaude_code/protocol/sub_agent/web.py

@@ -71,7 +71,7 @@ register_sub_agent(
         description=WEB_AGENT_DESCRIPTION,
         parameters=WEB_AGENT_PARAMETERS,
         prompt_file="prompts/prompt-sub-agent-web.md",
-        tool_set=(tools.BASH, tools.READ, tools.WEB_FETCH, tools.WEB_SEARCH),
+        tool_set=(tools.BASH, tools.READ, tools.WEB_FETCH, tools.WEB_SEARCH, tools.WRITE),
         prompt_builder=_web_agent_prompt_builder,
         active_form="Surfing",
         output_schema_arg="output_format",

klaude_code/session/codec.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import json
+from typing import Any, TypeGuard, cast, get_args
+
+from pydantic import BaseModel
+
+from klaude_code.protocol import model
+
+
+def _is_basemodel_subclass(tp: object) -> TypeGuard[type[BaseModel]]:
+    return isinstance(tp, type) and issubclass(tp, BaseModel)
+
+
+def _flatten_union(tp: object) -> list[object]:
+    args = list(get_args(tp))
+    if not args:
+        return [tp]
+    flattened: list[object] = []
+    for arg in args:
+        flattened.extend(_flatten_union(arg))
+    return flattened
+
+
+def _build_type_registry() -> dict[str, type[BaseModel]]:
+    registry: dict[str, type[BaseModel]] = {}
+    for tp in _flatten_union(model.ConversationItem):
+        if not _is_basemodel_subclass(tp):
+            continue
+        registry[tp.__name__] = tp
+    return registry
+
+
+_CONVERSATION_ITEM_TYPES: dict[str, type[BaseModel]] = _build_type_registry()
+
+
+def encode_conversation_item(item: model.ConversationItem) -> dict[str, Any]:
+    return {"type": item.__class__.__name__, "data": item.model_dump(mode="json")}
+
+
+def decode_conversation_item(obj: dict[str, Any]) -> model.ConversationItem | None:
+    t = obj.get("type")
+    data = obj.get("data", {})
+    if not isinstance(t, str) or not isinstance(data, dict):
+        return None
+    cls = _CONVERSATION_ITEM_TYPES.get(t)
+    if cls is None:
+        return None
+    try:
+        item = cls(**data)
+    except TypeError:
+        return None
+    # pyright: ignore[reportReturnType]
+    return item  # type: ignore[return-value]
+
+
+def encode_jsonl_line(item: model.ConversationItem) -> str:
+    return json.dumps(encode_conversation_item(item), ensure_ascii=False) + "\n"
+
+
+def decode_jsonl_line(line: str) -> model.ConversationItem | None:
+    line = line.strip()
+    if not line:
+        return None
+    try:
+        obj = json.loads(line)
+    except json.JSONDecodeError:
+        return None
+    if not isinstance(obj, dict):
+        return None
+    return decode_conversation_item(cast(dict[str, Any], obj))