mycode-cli 0.1.2__py3-none-any.whl → 0.2.0__py3-none-any.whl

mycode/cli/chat.py

@@ -7,15 +7,18 @@ import html
 import re
 import shlex
 from base64 import b64encode
+from collections.abc import Iterable
 from pathlib import Path
-from typing import Any
+from typing import Any, override
 
 from prompt_toolkit import PromptSession
 from prompt_toolkit.application import Application, get_app
-from prompt_toolkit.completion import Completer, Completion
-from prompt_toolkit.formatted_text import ANSI
+from prompt_toolkit.completion import CompleteEvent, Completer, Completion
+from prompt_toolkit.document import Document
+from prompt_toolkit.formatted_text import ANSI, StyleAndTextTuples
 from prompt_toolkit.history import FileHistory
 from prompt_toolkit.key_binding import KeyBindings
+from prompt_toolkit.key_binding.key_processor import KeyPressEvent
 from prompt_toolkit.keys import Keys
 from prompt_toolkit.layout import Layout
 from prompt_toolkit.widgets import RadioList
@@ -23,9 +26,9 @@ from rich.text import Text
 
 from mycode.core.agent import Agent
 from mycode.core.config import resolve_mycode_home
-from mycode.core.messages import build_message, image_block, text_block
+from mycode.core.messages import build_message, document_block, image_block, text_block
 from mycode.core.session import SessionStore
-from mycode.core.tools import detect_image_mime_type, resolve_path
+from mycode.core.tools import detect_document_mime_type, detect_image_mime_type, resolve_path
 
 from .render import ReplyRenderer, TerminalView, format_local_timestamp
 from .runtime import (
@@ -62,17 +65,19 @@ _AT_PATH_RE = re.compile(r"(?<!\S)@(?:(?P<quote>['\"])(?P<quoted>[^'\"]*)|(?P<pl
 _FOCUSED_STYLE = "bold blue" if TERMINAL_THEME == "light" else "bold cyan"
 
 
-class _InlineRadioList[T](RadioList):
+class _InlineRadioList[T](RadioList[T]):
     """Arrow-key list that shows > on the focused item and exits on Enter."""
 
+    @override
     def _handle_enter(self) -> None:
         # Only called by Enter/Space (not arrows), so safe to exit.
         self.current_value = self.values[self._selected_index][0]
         get_app().exit(result=self.current_value)
 
-    def _get_text_fragments(self):
+    @override
+    def _get_text_fragments(self) -> StyleAndTextTuples:
         # Override rendering: show > based on focus, not checked state.
-        result: list[tuple[str, str]] = []
+        result: StyleAndTextTuples = []
         for i, (_value, text) in enumerate(self.values):
             focused = i == self._selected_index
             style = _FOCUSED_STYLE if focused else ""
@@ -97,7 +102,7 @@ async def choose[T](options: list[tuple[T, str]], *, default: T | None = None) -
 
     @kb.add("c-c")
     @kb.add("escape")
-    def _cancel(event) -> None:
+    def _cancel(event: KeyPressEvent) -> None:
         event.app.exit(result=None)
 
     app: Application[T | None] = Application(
@@ -116,7 +121,8 @@ class _PromptCompleter(Completer):
     def __init__(self, *, cwd: str | None = None) -> None:
         self._cwd = cwd
 
-    def get_completions(self, document, complete_event):
+    def get_completions(self, document: Document, complete_event: CompleteEvent) -> Iterable[Completion]:
+        del complete_event
         text_before_cursor = document.text_before_cursor
         text = text_before_cursor.lstrip()
         if self._cwd:
@@ -186,16 +192,25 @@ def _build_chat_key_bindings() -> KeyBindings:
     """Build key bindings for the main chat prompt."""
     kb = KeyBindings()
 
-    kb.add("c-l")(lambda event: event.app.renderer.clear())
+    def _clear(event: KeyPressEvent) -> None:
+        event.app.renderer.clear()
+
+    kb.add("c-l")(_clear)
 
     # In multiline mode the default Enter inserts a newline; override it to submit.
-    kb.add("enter", eager=True)(lambda event: event.current_buffer.validate_and_handle())
+    def _submit(event: KeyPressEvent) -> None:
+        event.current_buffer.validate_and_handle()
+
+    kb.add("enter", eager=True)(_submit)
 
     # Esc+Enter (Meta+Enter) inserts a newline for multiline input.
-    kb.add("escape", "enter")(lambda event: event.current_buffer.insert_text("\n"))
+    def _insert_newline(event: KeyPressEvent) -> None:
+        event.current_buffer.insert_text("\n")
+
+    kb.add("escape", "enter")(_insert_newline)
 
     @kb.add(Keys.BracketedPaste, eager=True)
-    def _handle_bracketed_paste(event) -> None:
+    def _handle_bracketed_paste(event: KeyPressEvent) -> None:
         pasted = event.data.replace("\r\n", "\n").replace("\r", "\n")
         event.current_buffer.insert_text(_rewrite_pasted_file_paths(pasted) or pasted)
 
@@ -225,7 +240,7 @@ class TerminalChat:
         self.store = store
         self.session_id = session_id
         self.view = view or TerminalView()
-        self.prompt_session = PromptSession(
+        self.prompt_session: PromptSession[str] = PromptSession(
             history=FileHistory(history_file_path()),
             completer=_PromptCompleter(cwd=self.agent.cwd),
             key_bindings=_build_chat_key_bindings(),
@@ -284,9 +299,9 @@ class TerminalChat:
     def _build_user_message(self, text: str) -> dict[str, Any]:
         """Build one user message with the raw prompt first, then resolved attachments.
 
-        Text files are appended as extra text blocks in their final provider-facing
-        form. Images are appended as image blocks. Only explicit `@path` tokens
-        that resolve to real files are attached.
+        Text files are appended as extra text blocks. Images and PDFs become
+        native blocks only when the current model supports that input type.
+        Only explicit `@path` tokens that resolve to real files are attached.
         """
 
         blocks = [text_block(text)]
@@ -309,10 +324,27 @@ class TerminalChat:
                 continue
             seen.add(path_text)
 
-            image_mime_type = detect_image_mime_type(path)
-            if image_mime_type:
-                image_data = b64encode(path.read_bytes()).decode("utf-8")
-                blocks.append(image_block(image_data, mime_type=image_mime_type, name=path.name))
+            # Detect image or document; bundle (kind, mime, supported) together.
+            media: tuple[str, str, bool] | None = None
+            if m := detect_image_mime_type(path):
+                media = ("image", m, self.agent.supports_image_input)
+            elif m := detect_document_mime_type(path):
+                media = ("document", m, self.agent.supports_pdf_input)
+
+            if media:
+                kind, mime_type, supported = media
+                if supported:
+                    data = b64encode(path.read_bytes()).decode("utf-8")
+                    fn = image_block if kind == "image" else document_block
+                    blocks.append(fn(data, mime_type=mime_type, name=path.name))
+                else:
+                    label = "image input" if kind == "image" else "PDF input"
+                    blocks.append(
+                        text_block(
+                            f'<file name="{html.escape(path_text, quote=True)}" media_type="{mime_type}" kind="{kind}">Current model does not support {label}.</file>',
+                            meta={"attachment": True, "path": path_text},
+                        )
+                    )
                 continue
 
             # Reuse the existing read tool so attached text files follow the same
@@ -459,20 +491,16 @@ class TerminalChat:
 
         # Collect real user text messages (skip synthetic compact summaries
         # and tool-result-only user messages).
-        user_turns: list[tuple[int, str]] = []  # (message_index, full_text)
+        user_turns: dict[int, str] = {}  # message_index -> text
         for i, msg in enumerate(messages):
             if msg.get("role") != "user":
                 continue
             if (msg.get("meta") or {}).get("synthetic"):
                 continue
-            blocks = msg.get("content") or []
-            text = ""
-            for b in blocks:
+            for b in msg.get("content") or []:
                 if isinstance(b, dict) and b.get("type") == "text" and b.get("text"):
-                    text = str(b["text"]).strip()
+                    user_turns[i] = str(b["text"]).strip()
                     break
-            if text:
-                user_turns.append((i, text))
 
         if not user_turns:
             self.view.console.print("[dim]no user messages to rewind to[/dim]")
@@ -480,7 +508,7 @@ class TerminalChat:
 
         # Build selector options — most recent first.
         options: list[tuple[int, str]] = []
-        for msg_index, text in reversed(user_turns):
+        for msg_index, text in reversed(list(user_turns.items())):
             preview = text.replace("\n", " ")[:60]
             if len(text) > 60:
                 preview += "..."
@@ -490,12 +518,7 @@ class TerminalChat:
         if selected is None:
             return None
 
-        # Look up the full text of the selected message for prefill.
-        original_text = ""
-        for msg_index, text in user_turns:
-            if msg_index == selected:
-                original_text = text
-                break
+        original_text = user_turns.get(selected, "")
 
         # Persist the rewind event and truncate in-memory messages.
         await self.store.append_rewind(self.session_id, selected)

mycode/cli/main.py

@@ -11,6 +11,7 @@ import typer
 
 from mycode.core.agent import Agent
 from mycode.core.config import get_settings, resolve_provider
+from mycode.core.messages import ConversationMessage
 from mycode.core.session import SessionStore
 
 from .chat import TerminalChat
@@ -22,9 +23,6 @@ session_app = typer.Typer(help="Session management")
 app.add_typer(session_app, name="session")
 
 
-# -- Shared helpers ----------------------------------------------------------
-
-
 async def run_noninteractive(
     agent: Agent,
     *,
@@ -32,11 +30,11 @@ async def run_noninteractive(
     session_id: str,
     message: str,
 ) -> int:
-    """Run one CLI message and print only the final assistant reply."""
+    """Run one message non-interactively and print only the final assistant reply."""
 
-    latest_assistant: dict | None = None
+    latest_assistant: ConversationMessage | None = None
 
-    async def persist(payload: dict) -> None:
+    async def persist(payload: ConversationMessage) -> None:
         nonlocal latest_assistant
         if payload.get("role") == "assistant":
             latest_assistant = payload
@@ -67,7 +65,7 @@ async def run_noninteractive(
 
 
 def _validate_session_options(session: str | None, continue_last: bool) -> None:
-    """Reject conflicting session options."""
+    """Reject conflicting --session and --continue options."""
 
     if session and continue_last:
         raise typer.BadParameter("--session and --continue are mutually exclusive")

mycode/cli/render.py

@@ -412,6 +412,8 @@ class ReplyRenderer:
                 case "error":
                     exit_code = 1
                     self.error(event.data.get("message", ""))
+                case _:
+                    pass
 
         self.finish()
         return exit_code
@@ -711,19 +713,21 @@ class ReplyRenderer:
         self._thinking_collapsed = False
         self._thinking_start_time = None
 
-    def _build_live_renderable(self):
+    def _build_live_renderable(self) -> Spinner | _LeftMarkdown:
         """Build the Rich renderable used while a reply is streaming."""
 
         # No content yet: plain spinner
         if not self._reasoning and not self._text:
             return Spinner("dots", style="dim")
 
-        # Thinking in progress: show rolling preview of reasoning content
+        # Thinking in progress: show rolling preview of reasoning content.
+        # Join only the tail to avoid O(full_length) work on every frame.
         if self._reasoning and not self._text:
-            content = " ".join("".join(self._reasoning).split())
+            tail = "".join(self._reasoning[-30:])
+            content = " ".join(tail.split())
             if content:
                 preview = content[-80:].strip()
-                if len(content) > 80:
+                if len(self._reasoning) > 30 or len(content) > 80:
                     preview = "…" + preview
                 return Spinner("dots", text=Text(f" {preview}", style=THINKING), style="dim")
             return Spinner("dots", text=Text(" thinking…", style=THINKING), style="dim")

mycode/cli/runtime.py

@@ -64,6 +64,7 @@ def build_agent(
         settings=settings,
         reasoning_effort=resolved_provider.reasoning_effort,
         supports_image_input=resolved_provider.supports_image_input,
+        supports_pdf_input=resolved_provider.supports_pdf_input,
         max_tokens=resolved_provider.max_tokens,
         context_window=resolved_provider.context_window,
         compact_threshold=settings.compact_threshold,
@@ -87,6 +88,7 @@ def clone_agent(agent: Agent, *, store: SessionStore, session_id: str, messages:
         max_tokens=agent.max_tokens,
         reasoning_effort=agent.reasoning_effort,
         supports_image_input=agent.supports_image_input,
+        supports_pdf_input=agent.supports_pdf_input,
         settings=agent.settings,
     )
 
@@ -255,6 +257,7 @@ async def update_agent_runtime(
         or agent.max_tokens != resolved.max_tokens
         or agent.context_window != resolved.context_window
         or agent.supports_image_input != resolved.supports_image_input
+        or agent.supports_pdf_input != resolved.supports_pdf_input
     )
 
     agent.provider = resolved.provider
@@ -265,6 +268,7 @@ async def update_agent_runtime(
     agent.max_tokens = resolved.max_tokens
     agent.context_window = resolved.context_window
     agent.supports_image_input = bool(resolved.supports_image_input)
+    agent.supports_pdf_input = bool(resolved.supports_pdf_input)
     agent.settings = settings
     if hasattr(agent, "tools") and hasattr(agent.tools, "supports_image_input"):
         agent.tools.supports_image_input = bool(agent.supports_image_input)

mycode/core/agent.py

@@ -7,7 +7,7 @@ import logging
 from collections.abc import AsyncIterator, Awaitable, Callable
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any
+from typing import Any, cast
 
 from mycode.core.config import Settings, get_settings
 from mycode.core.messages import (
@@ -62,6 +62,7 @@ class Agent:
         compact_threshold: float | None = None,
         reasoning_effort: str | None = None,
         supports_image_input: bool | None = None,
+        supports_pdf_input: bool | None = None,
         settings: Settings | None = None,
         system: str | None = None,
         tool_executor: ToolExecutor | None = None,
@@ -79,6 +80,7 @@ class Agent:
         self.compact_threshold = compact_threshold if compact_threshold is not None else DEFAULT_COMPACT_THRESHOLD
         self.reasoning_effort = reasoning_effort
         self.supports_image_input: bool = bool(supports_image_input)
+        self.supports_pdf_input: bool = bool(supports_pdf_input)
         self.settings = settings or get_settings(self.cwd)
         self.system = system or build_system_prompt(self.cwd, self.settings)
         self._cancel_event = asyncio.Event()
@@ -99,9 +101,7 @@ class Agent:
 
     @staticmethod
     def _tool_done_event(tool_id: str, result: ToolExecutionResult) -> Event:
-        """Build the standard tool_done event payload."""
-
-        data = {
+        data: dict[str, Any] = {
             "tool_use_id": tool_id,
             "model_text": result.model_text,
             "display_text": result.display_text,
@@ -109,10 +109,7 @@ class Agent:
         }
         if result.content:
             data["content"] = result.content
-        return Event(
-            "tool_done",
-            data,
-        )
+        return Event("tool_done", data)
 
     async def _run_streaming_tool(self, *, tool_id: str, name: str, args: dict[str, Any]) -> AsyncIterator[Event]:
         """Run one streaming tool and forward live output until it finishes."""
@@ -236,12 +233,16 @@ class Agent:
         """Iterate one provider turn with best-effort cancellation support."""
 
         provider_stream: AsyncIterator[ProviderStreamEvent] = adapter.stream_turn(request)
+
+        async def next_provider_event() -> ProviderStreamEvent:
+            return await anext(provider_stream)
+
         try:
             while True:
                 if self._cancel_event.is_set():
                     raise asyncio.CancelledError
 
-                self._provider_event_task = asyncio.create_task(anext(provider_stream))
+                self._provider_event_task = asyncio.create_task(next_provider_event())
                 try:
                     yield await self._provider_event_task
                 except StopAsyncIteration:
@@ -249,8 +250,8 @@ class Agent:
                 finally:
                     self._provider_event_task = None
         finally:
-            close = getattr(provider_stream, "aclose", None)
-            if callable(close):
+            close = cast(Callable[[], Awaitable[None]] | None, getattr(provider_stream, "aclose", None))
+            if close is not None:
                 try:
                     await close()
                 except Exception:
@@ -271,17 +272,19 @@ class Agent:
 
         self._cancel_event.clear()
         supports_image_input = self.supports_image_input
+        supports_pdf_input = self.supports_pdf_input
         self.tools.supports_image_input = supports_image_input
 
         if isinstance(user_input, str):
             user_message = user_text_message(user_input)
         else:
-            user_message = {
+            user_message: ConversationMessage = {
                 "role": str(user_input.get("role") or "user"),
                 "content": [dict(b) for b in user_input.get("content") or [] if isinstance(b, dict)],
             }
-            if isinstance(user_input.get("meta"), dict):
-                user_message["meta"] = dict(user_input["meta"])
+            raw_meta = user_input.get("meta")
+            if isinstance(raw_meta, dict):
+                user_message["meta"] = {str(k): v for k, v in raw_meta.items()}
 
         if user_message.get("role") != "user":
             yield Event("error", {"message": "user input must be a user message"})
@@ -292,6 +295,11 @@ class Agent:
         ):
             yield Event("error", {"message": "current model does not support image input"})
             return
+        if not supports_pdf_input and any(
+            isinstance(block, dict) and block.get("type") == "document" for block in user_message.get("content") or []
+        ):
+            yield Event("error", {"message": "current model does not support PDF input"})
+            return
 
         self.messages.append(user_message)
         if on_persist:
@@ -319,6 +327,7 @@ class Agent:
                 api_base=self.api_base,
                 reasoning_effort=self.reasoning_effort,
                 supports_image_input=supports_image_input,
+                supports_pdf_input=supports_pdf_input,
             )
 
             try:
@@ -467,6 +476,7 @@ class Agent:
             api_key=self.api_key,
             api_base=self.api_base,
             supports_image_input=self.supports_image_input,
+            supports_pdf_input=self.supports_pdf_input,
         )
 
         summary_message: ConversationMessage | None = None

mycode/core/config.py

@@ -40,6 +40,7 @@ class ModelConfig:
     max_output_tokens: int | None = None
     supports_reasoning: bool | None = None
     supports_image_input: bool | None = None
+    supports_pdf_input: bool | None = None
 
 
 @dataclass(frozen=True)
@@ -79,6 +80,7 @@ class ResolvedProvider:
     context_window: int | None = 128_000
     supports_reasoning: bool | None = None
     supports_image_input: bool | None = None
+    supports_pdf_input: bool | None = None
     provider_name: str | None = None
 
     @property
@@ -139,6 +141,7 @@ def _normalize_models(value: Any) -> dict[str, ModelConfig]:
             max_output_tokens=as_int(raw_config.get("max_output_tokens")),
             supports_reasoning=as_bool(raw_config.get("supports_reasoning")),
             supports_image_input=as_bool(raw_config.get("supports_image_input")),
+            supports_pdf_input=as_bool(raw_config.get("supports_pdf_input")),
         )
     return models
 
@@ -293,20 +296,21 @@ def get_settings(cwd: str | None = None) -> Settings:
 
             raw_providers[name] = merged
 
-        default = data.get("default") if isinstance(data.get("default"), dict) else {}
-        if "provider" in default:
-            value = default.get("provider")
-            default_provider = value if isinstance(value, str) else None
-        if "model" in default:
-            value = default.get("model")
-            default_model = value if isinstance(value, str) else None
-        if "reasoning_effort" in default:
-            value = default.get("reasoning_effort")
-            default_reasoning_effort = value if isinstance(value, str) else None
-        if "compact_threshold" in default:
-            parsed_threshold = _parse_compact_threshold(default.get("compact_threshold"))
-            if parsed_threshold is not None:
-                compact_threshold = parsed_threshold
+        default = data.get("default")
+        if isinstance(default, dict):
+            if "provider" in default:
+                v = default.get("provider")
+                default_provider = v if isinstance(v, str) else None
+            if "model" in default:
+                v = default.get("model")
+                default_model = v if isinstance(v, str) else None
+            if "reasoning_effort" in default:
+                v = default.get("reasoning_effort")
+                default_reasoning_effort = v if isinstance(v, str) else None
+            if "compact_threshold" in default:
+                parsed_threshold = _parse_compact_threshold(default.get("compact_threshold"))
+                if parsed_threshold is not None:
+                    compact_threshold = parsed_threshold
 
     return Settings(
         providers=_build_providers(raw_providers),
@@ -341,24 +345,27 @@ def resolve_provider(
             api_base=api_base,
         )
 
-    for available_name, _ in _available_provider_references(settings):
+    refs = _available_provider_references(settings)
+    if refs:
         return _resolve_provider_runtime(
             settings,
-            selected_name=available_name,
+            selected_name=refs[0][0],
             model=model,
             api_key=api_key,
             api_base=api_base,
         )
 
-    env_names: list[str] = []
-    for provider_id in list_env_discoverable_providers():
-        for env_name in provider_env_api_key_names(provider_id):
-            if env_name not in env_names:
-                env_names.append(env_name)
+    env_names = list(
+        dict.fromkeys(
+            env_name
+            for provider_id in list_env_discoverable_providers()
+            for env_name in provider_env_api_key_names(provider_id)
+        )
+    )
     checked = ", ".join(env_names) or "<api key env>"
     raise ValueError(
         "no available providers found; set one of the supported API key env vars "
-        f"({checked}) or configure a provider in ~/.mycode/config.json or <workspace>/.mycode/config.json"
+        + f"({checked}) or configure a provider in ~/.mycode/config.json or <workspace>/.mycode/config.json"
     )
 
 
@@ -461,6 +468,7 @@ def _resolve_provider_runtime(
                     max_output_tokens=model_config.max_output_tokens,
                     supports_reasoning=model_config.supports_reasoning,
                     supports_image_input=model_config.supports_image_input,
+                    supports_pdf_input=model_config.supports_pdf_input,
                 )
             else:
                 # Per-field: use the config override when set, keep catalog value otherwise.
@@ -478,11 +486,16 @@ def _resolve_provider_runtime(
                     supports_image_input=model_config.supports_image_input
                     if model_config.supports_image_input is not None
                     else model_metadata.supports_image_input,
+                    supports_pdf_input=model_config.supports_pdf_input
+                    if model_config.supports_pdf_input is not None
+                    else model_metadata.supports_pdf_input,
                 )
 
-    configured_effort = settings.default_reasoning_effort
-    if provider_config and provider_config.reasoning_effort is not None:
-        configured_effort = provider_config.reasoning_effort
+    configured_effort = (
+        provider_config.reasoning_effort
+        if provider_config and provider_config.reasoning_effort is not None
+        else settings.default_reasoning_effort
+    )
 
     if configured_effort is not None and configured_effort not in _VALID_REASONING_EFFORTS:
         supported = ", ".join(_VALID_REASONING_EFFORTS)
@@ -490,16 +503,18 @@ def _resolve_provider_runtime(
 
     supports_reasoning = model_metadata.supports_reasoning if model_metadata else None
     supports_image_input = model_metadata.supports_image_input if model_metadata else None
+    supports_pdf_input = model_metadata.supports_pdf_input if model_metadata else None
     adapter = get_provider_adapter(provider_type)
-    if (
-        configured_effort is None
-        or model_metadata is None
-        or supports_reasoning is not True
-        or not adapter.supports_reasoning_effort
-    ):
-        reasoning_effort = None
-    else:
-        reasoning_effort = configured_effort
+    reasoning_effort = (
+        configured_effort
+        if (
+            configured_effort is not None
+            and model_metadata is not None
+            and supports_reasoning is True
+            and adapter.supports_reasoning_effort
+        )
+        else None
+    )
 
     resolved_api_key = api_key
     if not resolved_api_key and provider_config:
@@ -521,10 +536,11 @@ def _resolve_provider_runtime(
         api_key=resolved_api_key,
         api_base=resolved_api_base,
         reasoning_effort=reasoning_effort,
-        max_tokens=model_metadata.max_output_tokens if model_metadata and model_metadata.max_output_tokens else 16_384,
-        context_window=model_metadata.context_window if model_metadata and model_metadata.context_window else 128_000,
+        max_tokens=(model_metadata.max_output_tokens if model_metadata else None) or 16_384,
+        context_window=(model_metadata.context_window if model_metadata else None) or 128_000,
         supports_reasoning=supports_reasoning,
         supports_image_input=supports_image_input,
+        supports_pdf_input=supports_pdf_input,
     )
 
 

mycode/core/messages.py

@@ -2,7 +2,7 @@
 
 The runtime persists a single message shape everywhere:
 
-- user message: text blocks, image blocks, and tool_result blocks
+- user message: text blocks, image blocks, document blocks, and tool_result blocks
 - assistant message: thinking blocks, text blocks, and tool_use blocks
 
 Provider adapters translate between this internal shape and provider-specific wire
@@ -21,6 +21,8 @@ from __future__ import annotations
 
 from typing import Any
 
+from mycode.core.utils import omit_none
+
 ContentBlock = dict[str, Any]
 ConversationMessage = dict[str, Any]
 
@@ -54,6 +56,21 @@ def image_block(
     return block
 
 
+def document_block(
+    data: str,
+    *,
+    mime_type: str,
+    name: str | None = None,
+    meta: dict[str, Any] | None = None,
+) -> ContentBlock:
+    block: ContentBlock = {"type": "document", "data": data, "mime_type": mime_type}
+    if name:
+        block["name"] = name
+    if meta:
+        block["meta"] = dict(meta)
+    return block
+
+
 def tool_use_block(
     *,
     tool_id: str,
@@ -141,7 +158,7 @@ def assistant_message(
     if usage is not None:
         meta["usage"] = usage
     if native_meta:
-        native = {key: value for key, value in native_meta.items() if value is not None}
+        native = omit_none(native_meta)
         if native:
             meta["native"] = native
     return build_message("assistant", blocks, meta=meta or None)
@@ -159,8 +176,7 @@ def flatten_message_text(message: ConversationMessage, *, include_thinking: bool
         # Attached file snapshots should not become session titles or history labels.
         if meta.get("attachment"):
             continue
-        if block.get("type") == "text":
-            parts.append(str(block.get("text") or ""))
-        elif include_thinking and block.get("type") == "thinking":
+        btype = block.get("type")
+        if btype == "text" or (include_thinking and btype == "thinking"):
             parts.append(str(block.get("text") or ""))
     return " ".join(part.strip() for part in parts if part and part.strip()).strip()