mycode-sdk 0.8.7__tar.gz → 0.8.8__tar.gz

{mycode_sdk-0.8.7 → mycode_sdk-0.8.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mycode-sdk
-Version: 0.8.7
+Version: 0.8.8
 Summary: Lightweight Python SDK for building AI agents.
 Project-URL: Homepage, https://github.com/legibet/mycode
 Project-URL: Repository, https://github.com/legibet/mycode
@@ -18,9 +18,9 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development
 Requires-Python: >=3.12
-Requires-Dist: anthropic>=0.74.0
-Requires-Dist: google-genai>=1.68.0
-Requires-Dist: openai>=2.11.0
+Requires-Dist: anthropic>=0.102.0
+Requires-Dist: google-genai>=2.3.0
+Requires-Dist: openai>=2.36.0
 Description-Content-Type: text/markdown
 
 # mycode-sdk

{mycode_sdk-0.8.7 → mycode_sdk-0.8.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mycode-sdk"
-version = "0.8.7"
+version = "0.8.8"
 description = "Lightweight Python SDK for building AI agents."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -23,9 +23,9 @@ classifiers = [
 ]
 keywords = ["agent", "llm", "anthropic", "openai", "gemini", "sdk"]
 dependencies = [
-    "anthropic>=0.74.0",
-    "google-genai>=1.68.0",
-    "openai>=2.11.0",
+    "anthropic>=0.102.0",
+    "google-genai>=2.3.0",
+    "openai>=2.36.0",
 ]
 
 [project.urls]

{mycode_sdk-0.8.7 → mycode_sdk-0.8.8}/src/mycode/__init__.py

@@ -39,9 +39,6 @@ from mycode.tools import (
 # The package metadata in mycode/pyproject.toml is the single version source.
 __version__ = metadata.version("mycode-sdk")
 
-# Built-in tool specs exposed as module-level constants so callers can pick
-# which ones to register (``tools=[read_tool, bash_tool]``) rather than
-# getting all four by default.
 read_tool, write_tool, edit_tool, bash_tool = DEFAULT_TOOL_SPECS
 
 __all__ = [

{mycode_sdk-0.8.7 → mycode_sdk-0.8.8}/src/mycode/agent.py

@@ -136,10 +136,9 @@ class Agent:
             raise ValueError(msg)
         self.messages: list[ConversationMessage] = list(messages)
 
-        # Tool runtime: one executor per agent. ``tool_output_dir`` is where
-        # tools can drop artifacts — defaults to a session-adjacent directory
-        # so logs (e.g. bash spill files) live next to the session JSONL.
-        # When no session is configured, use a tempdir scoped to session_id.
+        # ``tool_output_dir`` defaults to a session-adjacent directory so logs
+        # (e.g. bash spill files) live next to the session JSONL; without a
+        # session, fall back to a tempdir scoped to ``session_id``.
         if session_dir is not None:
             tool_output_dir = session_dir / self.session_id / "tool-output"
         else:
@@ -434,21 +433,12 @@ class Agent:
         *,
         on_persist: PersistCallback | None = None,
     ) -> AsyncIterator[Event]:
-        """Run the full agent loop for one user message.
-
-        Each turn asks the provider for one assistant message. If the assistant
-        requests tools, the agent runs them locally, appends one user-side
-        tool_result message, and continues until the assistant stops using tools.
-
-        When a ``session_dir`` is configured, every emitted message is appended
-        to the on-disk session log. ``on_persist`` fires *before* that append
-        regardless of whether a store is configured, so callers can plug in a
-        custom backend or stage related records (the web server uses it to
-        land a rewind marker first).
-        """
+        """Run the full agent loop for one user message."""
 
         async def persist(message: ConversationMessage) -> None:
             if on_persist is not None:
+                # Callers may need to write related records before the SDK
+                # appends this message to its own session log.
                 await on_persist(message)
             if self._store is None:
                 return
@@ -517,7 +507,6 @@ class Agent:
             )
 
             try:
-                # Phase 1: ask the provider for exactly one assistant turn.
                 async for provider_event in self._stream_provider_turn(adapter, request):
                     if self._cancel_event.is_set():
                         provider_cancelled = True
@@ -675,8 +664,8 @@ class Agent:
                     yield Event("error", {"message": "cancelled"})
                     return
                 except Exception:
-                    # Best-effort: transient failures retry next threshold check;
-                    # persistent ones surface from phase 1 of the next turn.
+                    # Compaction must not block the current answer; the full
+                    # transcript is still available for the next turn.
                     logger.warning(
                         "Context compaction failed, continuing without compaction",
                         exc_info=True,
@@ -686,7 +675,6 @@ class Agent:
                 break
 
         else:
-            # while loop exhausted max_turns without breaking
             yield Event("error", {"message": "max_turns reached"})
             return
 

{mycode_sdk-0.8.7 → mycode_sdk-0.8.8}/src/mycode/messages.py

@@ -1,23 +1,18 @@
 """Internal conversation model shared by the runtime, session store, CLI, and UI.
 
-The runtime persists a single message shape everywhere:
-
-- 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
-formats. The agent loop and session store should never need to know provider wire
-details.
-
-Metadata contract:
-
-- assistant message `meta` keeps normalized top-level fields only:
-  `provider`, `model`, `provider_message_id`, `stop_reason`, `total_tokens`,
-  `context_window` (see docs/sessions.md for `total_tokens` semantics)
-- provider-specific assistant message extras live under `meta.native`
-- provider-specific block replay hints live under `block.meta.native`
-- local display metadata, such as `block.meta.duration_ms`, is never sent
-  upstream; provider adapters must explicitly project only supported fields
+Provider adapters translate this shape to and from provider-specific wire
+formats so the agent loop and session store stay provider-agnostic.
+
+Metadata layout:
+
+- assistant message ``meta`` keeps only normalized top-level fields:
+  ``provider``, ``model``, ``provider_message_id``, ``stop_reason``,
+  ``total_tokens``, ``context_window`` (see docs/sessions.md for
+  ``total_tokens`` semantics)
+- provider-specific extras live under ``meta.native`` on messages and
+  ``block.meta.native`` on blocks
+- local display metadata such as ``block.meta.duration_ms`` is never sent
+  upstream
 """
 
 from __future__ import annotations

{mycode_sdk-0.8.7 → mycode_sdk-0.8.8}/src/mycode/models.py

@@ -42,12 +42,7 @@ def load_models_catalog() -> dict[str, Any] | None:
 
 
 def infer_provider_from_model(model: str | None) -> str | None:
-    """Return the canonical built-in provider id for a known model id, else None.
-
-    Recognizes well-known prefixes on bare model ids and ``provider/model``
-    ids alike. Returns ``None`` for unknown ids — callers should require an
-    explicit provider in that case rather than guess.
-    """
+    """Return the canonical built-in provider id for a known model id, else None."""
 
     bare = (model or "").strip().split("/", 1)[-1].strip().lower()
     if bare.startswith("claude-"):

{mycode_sdk-0.8.7 → mycode_sdk-0.8.8}/src/mycode/providers/anthropic_like.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import hashlib
 from collections.abc import AsyncIterator
-from typing import Any, cast
+from typing import Any, cast, override
 
 from anthropic import APIError, AsyncAnthropic
 
@@ -32,19 +32,7 @@ _THINKING_BUDGETS: dict[str, int] = {"low": 2048, "medium": 8192, "high": 24576,
 
 
 class AnthropicLikeAdapter(ProviderAdapter):
-    """Shared Messages adapter for Anthropic-compatible providers.
-
-    Anthropic, Moonshot, and MiniMax all document agent usage around the
-    Anthropic Messages protocol. The differences we care about are limited to:
-
-    - default base URL
-    - API key env var names
-    - optional thinking defaults
-    - provider-native metadata carried in content blocks
-
-    MiniMax requires the full assistant content (all blocks) to be sent on
-    multi-turn tool-loop requests — not just the text portion.
-    """
+    """Shared Messages adapter for Anthropic-compatible providers."""
 
     def thinking_config(self, request: ProviderRequest) -> dict[str, Any] | None:
         del request
@@ -90,6 +78,7 @@ class AnthropicLikeAdapter(ProviderAdapter):
             payload["output_config"] = output_config
         return payload
 
+    @override
     def project_tool_call_id(self, tool_call_id: str, used_tool_call_ids: set[str]) -> str:
         """Return a short ASCII ID without introducing collisions.
 
@@ -138,6 +127,7 @@ class AnthropicLikeAdapter(ProviderAdapter):
 
             return
 
+    @override
     async def stream_turn(self, request: ProviderRequest) -> AsyncIterator[ProviderStreamEvent]:
         api_key = self.require_api_key(request.api_key)
         client = AsyncAnthropic(
@@ -326,6 +316,7 @@ class AnthropicAdapter(AnthropicLikeAdapter):
     default_models = ("claude-sonnet-4-6", "claude-opus-4-7")
     supports_reasoning_effort = True
 
+    @override
     def thinking_config(self, request: ProviderRequest) -> dict[str, Any] | None:
         effort = request.reasoning_effort
         if not effort:
@@ -340,6 +331,7 @@ class AnthropicAdapter(AnthropicLikeAdapter):
             return thinking
         return self.manual_thinking_config(effort)
 
+    @override
     def output_config(self, request: ProviderRequest) -> dict[str, Any] | None:
         effort = request.reasoning_effort
         if not effort or effort == "none":
@@ -363,9 +355,8 @@ class AnthropicAdapter(AnthropicLikeAdapter):
 class MoonshotAIAdapter(AnthropicLikeAdapter):
     """Moonshot's Anthropic-compatible Messages endpoint.
 
-    kimi-k2.6 tool loops work through this endpoint. When thinking is enabled,
-    prior reasoning blocks must be replayed in the conversation history —
-    Moonshot does not strip them on the server side.
+    When thinking is enabled, prior reasoning blocks must be replayed in the
+    conversation history — Moonshot does not strip them on the server side.
     """
 
     provider_id = "moonshotai"
@@ -375,6 +366,7 @@ class MoonshotAIAdapter(AnthropicLikeAdapter):
     default_models = ("kimi-k2.6",)
     supports_reasoning_effort = True
 
+    @override
     def thinking_config(self, request: ProviderRequest) -> dict[str, Any] | None:
         return self.manual_thinking_config(request.reasoning_effort)
 
@@ -394,5 +386,6 @@ class MiniMaxAdapter(AnthropicLikeAdapter):
     default_models = ("MiniMax-M2.7", "MiniMax-M2.7-highspeed")
     supports_reasoning_effort = True
 
+    @override
     def thinking_config(self, request: ProviderRequest) -> dict[str, Any] | None:
         return self.manual_thinking_config(request.reasoning_effort)

{mycode_sdk-0.8.7 → mycode_sdk-0.8.8}/src/mycode/providers/base.py

@@ -1,14 +1,8 @@
 """Shared provider adapter interfaces.
 
-The agent loop talks to providers through a small normalized contract:
-
-- input: `ProviderRequest`
-- output: streamed `ProviderStreamEvent` objects
-
-Concrete adapters are free to use the official SDK or protocol that best matches
-their upstream provider. Each adapter is also responsible for projecting the
-canonical session transcript into a provider-safe replay history before a new
-request is sent upstream.
+Each adapter implements `stream_turn()` and reuses `prepare_messages()` to
+project the canonical session transcript into a provider-safe replay history
+before sending a request upstream.
 """
 
 from __future__ import annotations
@@ -205,6 +199,8 @@ def repair_messages_for_replay(
                 block_type = raw_block.get("type")
                 if block_type in {"text", "thinking"}:
                     text = str(raw_block.get("text") or "")
+                    # Empty native thinking blocks may still carry signatures or
+                    # provider replay state.
                     if text or get_native_meta(raw_block):
                         content.append(dict(raw_block))
                     continue
@@ -256,6 +252,8 @@ def repair_messages_for_replay(
                 if supported:
                     content.append(dict(raw_block))
                 else:
+                    # Preserve that the file existed even when the target
+                    # provider cannot accept the original media payload.
                     default_mime = "image" if block_type == "image" else "application/pdf"
                     label = "image input" if block_type == "image" else "PDF input"
                     name = html.escape(str(raw_block.get("name") or f"attached-{block_type}"), quote=True)

{mycode_sdk-0.8.7 → mycode_sdk-0.8.8}/src/mycode/providers/gemini.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from collections.abc import AsyncIterator
-from typing import Any
+from typing import Any, override
 from urllib.parse import urlparse
 
 from google import genai
@@ -51,6 +51,7 @@ class GoogleGeminiAdapter(ProviderAdapter):
     default_models = ("gemini-3.1-pro-preview", "gemini-3-flash-preview")
     supports_reasoning_effort = True
 
+    @override
     async def stream_turn(self, request: ProviderRequest) -> AsyncIterator[ProviderStreamEvent]:
         api_key = self.require_api_key(request.api_key)
         client = genai.Client(api_key=api_key, http_options=self._http_options(request.api_base))

{mycode_sdk-0.8.7 → mycode_sdk-0.8.8}/src/mycode/providers/openai_chat.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import json
 from collections.abc import AsyncIterator
 from dataclasses import dataclass
-from typing import Any
+from typing import Any, override
 
 from openai import APIError, AsyncOpenAI
 
@@ -42,6 +42,7 @@ class OpenAIChatAdapter(ProviderAdapter):
     env_api_key_names = ("OPENAI_API_KEY",)
     auto_discoverable = False
 
+    @override
     async def stream_turn(self, request: ProviderRequest) -> AsyncIterator[ProviderStreamEvent]:
         api_key = self.require_api_key(request.api_key)
         client = AsyncOpenAI(
@@ -50,8 +51,6 @@ class OpenAIChatAdapter(ProviderAdapter):
             timeout=DEFAULT_REQUEST_TIMEOUT,
         )
 
-        # Keep the streamed turn state local to this adapter so the wire-format
-        # mapping stays readable in one file.
         tool_calls: dict[int, _ChatToolCallState] = {}
         text_parts: list[str] = []
         thinking_parts: list[str] = []
@@ -338,6 +337,7 @@ class DeepSeekAdapter(OpenAIChatAdapter):
     auto_discoverable = True
     supports_reasoning_effort = True
 
+    @override
     def _build_provider_payload_overrides(self, request: ProviderRequest) -> dict[str, Any]:
         if request.reasoning_effort == "none":
             return {"extra_body": {"thinking": {"type": "disabled"}}}
@@ -353,9 +353,8 @@ class DeepSeekAdapter(OpenAIChatAdapter):
 class ZAIAdapter(OpenAIChatAdapter):
     """Z.AI's OpenAI-compatible chat endpoint.
 
-    GLM models think by default. We still send the explicit thinking parameter
-    so that clear_thinking=False preserves reasoning across multi-turn tool loops
-    instead of resetting it on each turn.
+    GLM models think by default. The explicit thinking parameter is sent only
+    so ``clear_thinking=False`` preserves reasoning across multi-turn tool loops.
     """
 
     provider_id = "zai"
@@ -365,6 +364,7 @@ class ZAIAdapter(OpenAIChatAdapter):
     default_models = ("glm-5.1", "glm-5-turbo")
     auto_discoverable = True
 
+    @override
     def _build_provider_payload_overrides(self, request: ProviderRequest) -> dict[str, Any]:
         return {"extra_body": {"thinking": {"type": "enabled", "clear_thinking": False}}}
 
@@ -380,6 +380,7 @@ class OpenRouterAdapter(OpenAIChatAdapter):
     auto_discoverable = True
     supports_reasoning_effort = True
 
+    @override
     def _build_provider_payload_overrides(self, request: ProviderRequest) -> dict[str, Any]:
         if not request.reasoning_effort:
             return {}

{mycode_sdk-0.8.7 → mycode_sdk-0.8.8}/src/mycode/providers/openai_responses.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import json
 from collections.abc import AsyncIterator
 from copy import deepcopy
-from typing import Any, cast
+from typing import Any, cast, override
 
 from openai import APIError, AsyncOpenAI
 
@@ -33,6 +33,7 @@ class OpenAIResponsesAdapter(ProviderAdapter):
     default_models = ("gpt-5.5", "gpt-5.4-mini")
     supports_reasoning_effort = True
 
+    @override
     async def stream_turn(self, request: ProviderRequest) -> AsyncIterator[ProviderStreamEvent]:
         api_key = self.require_api_key(request.api_key)
         client = AsyncOpenAI(

{mycode_sdk-0.8.7 → mycode_sdk-0.8.8}/src/mycode/session.py

@@ -20,23 +20,19 @@ from typing import TypedDict, cast
 
 from mycode.messages import ConversationMessage, flatten_message_text
 
-# ---------------------------------------------------------------------
-# Session format defaults
-# ---------------------------------------------------------------------
-
 MESSAGE_FORMAT_VERSION = 7
 DEFAULT_SESSION_TITLE = "New chat"
 
 
-# ---------------------------------------------------------------------
-# Rewind session events
-# ---------------------------------------------------------------------
-
-
 def _now() -> str:
     return datetime.now(UTC).isoformat()
 
 
+# ---------------------------------------------------------------------
+# Rewind markers
+# ---------------------------------------------------------------------
+
+
 def build_rewind_event(rewind_to: int) -> ConversationMessage:
     """Build a rewind marker to append to session JSONL."""
 
@@ -112,7 +108,7 @@ class SessionStore:
         self.data_dir.mkdir(parents=True, exist_ok=True)
 
     # ---------------------------------------------------------------------
-    # Session paths
+    # Paths and meta I/O
     # ---------------------------------------------------------------------
 
     def session_dir(self, session_id: str) -> Path:

{mycode_sdk-0.8.7 → mycode_sdk-0.8.8}/src/mycode/tools.py

@@ -1,14 +1,9 @@
 """Tool execution runtime.
 
-The SDK ships four built-in coding tools (``read`` / ``write`` / ``edit`` /
-``bash``) as :data:`DEFAULT_TOOL_SPECS`. SDK users register additional tools
-either by building :class:`ToolSpec` directly or by wrapping a typed function
-with :func:`tool`.
-
-Every tool runner receives a :class:`ToolContext` and a raw argument dict.
-Context exposes the runtime state (cwd, output directory, image support) plus
-typed facades for the four built-ins so custom tools can invoke them without
-stringly-typed dispatch::
+The four built-in tools (``read`` / ``write`` / ``edit`` / ``bash``) are
+bundled as :data:`DEFAULT_TOOL_SPECS`. Custom tools wrap a typed Python
+function with :func:`tool` and can invoke the built-ins through the facades
+on :class:`ToolContext`::
 
     @tool
     def smart_read(ctx: ToolContext, path: str) -> str:
@@ -42,11 +37,10 @@ from mycode.messages import image_block, text_block
 # ---------------------------------------------------------------------------
 # Limits
 # ---------------------------------------------------------------------------
-# read
+
 DEFAULT_MAX_LINES = 2000
 DEFAULT_MAX_BYTES = 50 * 1024
 READ_MAX_LINE_CHARS = 2000
-# bash
 BASH_TIMEOUT_SECONDS = 120
 _BASH_MAX_IN_MEMORY_BYTES = 5_000_000
 
@@ -60,20 +54,13 @@ ToolOutputCallback = Callable[[str], None]
 
 @dataclass(frozen=True)
 class ToolExecutionResult:
-    """Result of one tool run.
-
-    Two consumers read this:
-
-    - **provider** — gets ``output`` (a text summary) and, for multimodal
-      returns, ``content`` (structured blocks such as an image). ``output``
-      is replayed on later turns.
-    - **UI** — reads ``metadata`` for structured rendering (e.g. edit patch
-      and stats). When ``metadata`` is absent, the UI falls back to ``output``
-      as a one-line summary.
-    """
+    """Result of one tool run."""
 
+    # Replayed to providers on later turns.
     output: str
+    # Structured replay content, e.g. an image returned by a tool.
     content: list[dict[str, Any]] | None = None
+    # UI-only structured data such as edit patches and line stats.
     metadata: dict[str, Any] | None = None
     is_error: bool = False
 
@@ -83,18 +70,13 @@ ToolRunner = Callable[["ToolContext", dict[str, Any]], ToolExecutionResult]
 
 @dataclass(frozen=True)
 class ToolSpec:
-    """One tool the agent can call.
-
-    ``runner`` receives a :class:`ToolContext` and the raw argument dict.
-    Tools that emit incremental output (``bash``) set ``streams_output=True``
-    and push lines via ``ctx.emit``; the agent forwards them as
-    ``tool_output`` events live during execution.
-    """
+    """One tool the agent can call."""
 
     name: str
     description: str
     input_schema: dict[str, Any]
     runner: ToolRunner
+    # Streaming tools push incremental output through ToolContext.emit.
     streams_output: bool = False
 
 
@@ -107,26 +89,17 @@ class ToolSpec:
 class ToolContext:
     """Per-call runtime context handed to every tool runner.
 
-    ``cwd`` / ``tool_output_dir`` / ``supports_image_input`` describe where
-    the tool runs and what the model accepts. ``tool_call_id`` and ``emit``
-    are set by the agent for live streaming; they are ``None`` when a tool
-    is invoked outside the agent loop (e.g. TUI attachment read).
-
-    The four facades :meth:`read`, :meth:`write`, :meth:`edit`, :meth:`bash`
-    are the SDK-friendly way to invoke the built-in tools from custom code.
-    :meth:`call` is a generic fallback for dispatching to any registered
-    tool by name.
+    Includes typed facades for built-in tools and generic registry dispatch.
     """
 
     executor: ToolExecutor
     cwd: str
     tool_output_dir: Path
     supports_image_input: bool = False
+    # Only agent-loop calls have a provider tool-call id and live output sink.
     tool_call_id: str | None = None
     emit: ToolOutputCallback | None = None
 
-    # Typed facades for the built-ins.
-
     def read(
         self,
         path: str,
@@ -146,14 +119,10 @@ class ToolContext:
         return self.call("bash", {"command": command, "timeout": timeout})
 
     def call(self, name: str, args: dict[str, Any]) -> ToolExecutionResult:
-        """Dispatch to a tool by name. Used by the facades above and by
-        custom tools that wrap another registered tool."""
+        """Dispatch through the registry, including from custom tool wrappers."""
 
         return self.executor.execute(name, args, self)
 
-    # Subprocess hooks — used by bash to register/unregister its child so
-    # ``Agent.cancel`` and ``cancel_all_tools`` can terminate it.
-
     def track_proc(self, proc: subprocess.Popen[str]) -> None:
         self.executor.track_proc(proc)
 
@@ -167,12 +136,7 @@ class ToolContext:
 
 
 class ToolExecutor:
-    """Tool registry plus subprocess lifecycle for one agent session.
-
-    Agents construct one executor internally; SDK users normally pass
-    ``tools=[...]`` to :class:`~mycode.agent.Agent` rather than building
-    this directly.
-    """
+    """Tool registry plus subprocess lifecycle for one agent session."""
 
     def __init__(self, tools: Sequence[ToolSpec]):
         names = [spec.name for spec in tools]
@@ -184,8 +148,6 @@ class ToolExecutor:
 
     @property
     def definitions(self) -> list[dict[str, Any]]:
-        """Provider-facing tool definitions (name / description / schema)."""
-
         return [
             {"name": spec.name, "description": spec.description, "input_schema": spec.input_schema}
             for spec in self._tools.values()
@@ -230,10 +192,9 @@ class ToolExecutor:
 # ---------------------------------------------------------------------------
 # Subprocess lifecycle (process-global)
 # ---------------------------------------------------------------------------
-# Bash registers each child in both the executor and this module-level set.
-# The executor set scopes cancellation to one session (multiple agents may
-# run concurrently in the same process); the global set is a shutdown-time
-# safety net exposed as ``cancel_all_tools``.
+# The executor's tracking set scopes cancellation to one session (multiple
+# agents may run concurrently in the same process); this module-level set is
+# a shutdown-time safety net exposed as ``cancel_all_tools``.
 
 _ACTIVE_PROCS: set[subprocess.Popen[str]] = set()
 _ACTIVE_PROCS_LOCK = threading.Lock()
@@ -580,8 +541,6 @@ def _run_edit(ctx: ToolContext, args: dict[str, Any]) -> ToolExecutionResult:
                 is_error=True,
             )
 
-        # Fuzzy fallback: normalize both sides, find in normalized space,
-        # but map the span back to the original text for replacement.
         if norm_text is None:
             norm_text, norm_imap = _normalize_text(text)
         norm_old, _ = _normalize_text(old_text)
@@ -604,6 +563,8 @@ def _run_edit(ctx: ToolContext, args: dict[str, Any]) -> ToolExecutionResult:
 
         idx = norm_text.find(norm_old)
         assert norm_imap is not None
+        # Normalized matching tolerates whitespace drift; replacement still
+        # uses original offsets so untouched content is preserved exactly.
         orig_start = norm_imap[idx]
         end_idx = idx + len(norm_old)
         orig_end = norm_imap[end_idx] if end_idx < len(norm_imap) else len(text)
@@ -1009,14 +970,11 @@ def tool(
     description: str | None = None,
     streams_output: bool = False,
 ) -> ToolSpec | Callable[[Callable[..., Any]], ToolSpec]:
-    """Wrap a plain Python function as a :class:`ToolSpec`.
-
-    Sync and async functions are both supported. If the first parameter is
-    annotated :class:`ToolContext`, the context is injected automatically
-    and the remaining parameters drive the JSON schema sent to the provider.
+    """Wrap a sync or async Python function as a :class:`ToolSpec`.
 
-    The function may return a :class:`ToolExecutionResult` or any
-    JSON-serializable value; non-result values are wrapped as text output.
+    A first parameter annotated :class:`ToolContext` is injected automatically;
+    the remaining parameters drive the input schema. The function may return a
+    :class:`ToolExecutionResult` or any JSON-serializable value.
     """
 
     def wrap(fn: Callable[..., Any]) -> ToolSpec:
@@ -1026,6 +984,8 @@ def tool(
         except Exception:
             resolved_hints = {}
         wants_context = bool(parameters) and resolved_hints.get(parameters[0].name) is ToolContext
+        # ToolContext is injected locally and must not appear in the provider
+        # input schema.
         tool_params = parameters[1:] if wants_context else parameters
         param_names = {p.name for p in tool_params}
         input_schema, coercions = _build_input_schema(tool_params, resolved_hints)
@@ -1070,7 +1030,7 @@ def _build_input_schema(
 ) -> tuple[dict[str, Any], dict[str, Callable[[Any], Any]]]:
     """Build the JSON schema for ``parameters`` and a per-name coercion map.
 
-    The coercion map carries post-JSON conversions for annotations with no
+    The coercion map carries post-JSON conversions for annotations without a
     native JSON type (currently only ``Path``).
     """