kimi-agent-module-api 2.1.0__tar.gz → 2.3.0__tar.gz

{kimi_agent_module_api-2.1.0/src/kimi_agent_module_api.egg-info → kimi_agent_module_api-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kimi-agent-module-api
-Version: 2.1.0
+Version: 2.3.0
 Summary: Stable contracts for community-built assistant modules
 Author: Webhead
 License-Expression: MIT
@@ -30,6 +30,8 @@ implementation, or module loader. It exports:
   (storage, scheduler, events, Discord actions, interactions, HTTP, services,
   trust, proposals, health) plus the validators the host runs at preflight.
 - `kimi_agent_module_api.events`: the normalized `discord.*` event payloads.
+- `kimi_agent_module_api.files`: `ToolFiles`, `ToolAttachment`, `ToolFile`, and
+  `FileAccessError` for invocation-scoped attachment and workspace reads.
 - `kimi_agent_module_api.testing`: a fake for every port, `load_context()` for
   exercising `create()`, and `MemoryStorage` (install the `testing` extra) so a
   module can unit test itself with only this package installed.
@@ -82,15 +84,31 @@ Message-deletion events include cached author classification:
 `MessageDeleteEvent.author_is_bot` and `MessageBulkDeleteEvent.bot_message_ids`.
 The values remain unknown for messages that were absent from Discord's cache.
 
-SDK 2.1 adds `ModuleToolContext.trigger_discord_message_id`. Mention-path tool
-calls receive the exact source Discord message snowflake; other surfaces receive
-`None`. Modules that act on a user's source message should require
-`kimi-agent-module-api>=2.1,<3`, reject `None`, fetch that exact message through
-`ctx.discord`, and verify its author before acting.
+SDK 2.1 adds `ModuleToolContext.trigger_discord_message_id`. SDK 2.3 adds
+`trigger_discord_message_snapshot`, an immutable host-owned capture of the
+message, guild, channel, author, content, and bot status made at turn entry.
+Mention-path tool calls receive both; personal and non-message surfaces receive
+`None`. Modules that need authoritative evidence from the triggering message
+should require `kimi-agent-module-api>=2.3,<3` and use the snapshot instead of
+re-fetching mutable or deletable Discord state.
 
 Modules use namespaced guild documents and the physical table names returned
 by `ctx.storage.table()`.
 
+SDK 2.2 adds optional `ModuleToolContext.files`. Declare
+`ModulePermissions(tool_files=True)`, depend on `kimi-agent-module-api>=2.2,<3`,
+and require `tools.files.v1` in `ModuleSpec.requires_capabilities`. Existing modules
+keep `api_version=2` and receive `files=None` without the permission.
+`ctx.files.attachments` lists admitted current/reply entries;
+`read_attachment(id, max_bytes=...)` and `read_workspace(path, max_bytes=...)`
+return bounded bytes without network downloads. The reader expires when the handler
+returns and is scoped to the actual caller. `testing.FakeToolFiles` supports
+independent tests. Module `ctx.http` methods apply an 8 MiB host ceiling even when
+callers supply `max_bytes`; `download` buffers and validates the bounded response
+before yielding chunks so connections are released on early consumer exit. See the
+[file access guide](https://github.com/webhead2oo9/kimi-agent/blob/main/docs/module-files.md)
+for moderation, reply-image availability, privacy, and limits.
+
 ## Testing the SDK
 
 From this package directory, run its tests without installing the Kimi application:

{kimi_agent_module_api-2.1.0 → kimi_agent_module_api-2.3.0}/README.md

@@ -13,6 +13,8 @@ implementation, or module loader. It exports:
   (storage, scheduler, events, Discord actions, interactions, HTTP, services,
   trust, proposals, health) plus the validators the host runs at preflight.
 - `kimi_agent_module_api.events`: the normalized `discord.*` event payloads.
+- `kimi_agent_module_api.files`: `ToolFiles`, `ToolAttachment`, `ToolFile`, and
+  `FileAccessError` for invocation-scoped attachment and workspace reads.
 - `kimi_agent_module_api.testing`: a fake for every port, `load_context()` for
   exercising `create()`, and `MemoryStorage` (install the `testing` extra) so a
   module can unit test itself with only this package installed.
@@ -65,15 +67,31 @@ Message-deletion events include cached author classification:
 `MessageDeleteEvent.author_is_bot` and `MessageBulkDeleteEvent.bot_message_ids`.
 The values remain unknown for messages that were absent from Discord's cache.
 
-SDK 2.1 adds `ModuleToolContext.trigger_discord_message_id`. Mention-path tool
-calls receive the exact source Discord message snowflake; other surfaces receive
-`None`. Modules that act on a user's source message should require
-`kimi-agent-module-api>=2.1,<3`, reject `None`, fetch that exact message through
-`ctx.discord`, and verify its author before acting.
+SDK 2.1 adds `ModuleToolContext.trigger_discord_message_id`. SDK 2.3 adds
+`trigger_discord_message_snapshot`, an immutable host-owned capture of the
+message, guild, channel, author, content, and bot status made at turn entry.
+Mention-path tool calls receive both; personal and non-message surfaces receive
+`None`. Modules that need authoritative evidence from the triggering message
+should require `kimi-agent-module-api>=2.3,<3` and use the snapshot instead of
+re-fetching mutable or deletable Discord state.
 
 Modules use namespaced guild documents and the physical table names returned
 by `ctx.storage.table()`.
 
+SDK 2.2 adds optional `ModuleToolContext.files`. Declare
+`ModulePermissions(tool_files=True)`, depend on `kimi-agent-module-api>=2.2,<3`,
+and require `tools.files.v1` in `ModuleSpec.requires_capabilities`. Existing modules
+keep `api_version=2` and receive `files=None` without the permission.
+`ctx.files.attachments` lists admitted current/reply entries;
+`read_attachment(id, max_bytes=...)` and `read_workspace(path, max_bytes=...)`
+return bounded bytes without network downloads. The reader expires when the handler
+returns and is scoped to the actual caller. `testing.FakeToolFiles` supports
+independent tests. Module `ctx.http` methods apply an 8 MiB host ceiling even when
+callers supply `max_bytes`; `download` buffers and validates the bounded response
+before yielding chunks so connections are released on early consumer exit. See the
+[file access guide](https://github.com/webhead2oo9/kimi-agent/blob/main/docs/module-files.md)
+for moderation, reply-image availability, privacy, and limits.
+
 ## Testing the SDK
 
 From this package directory, run its tests without installing the Kimi application:

{kimi_agent_module_api-2.1.0 → kimi_agent_module_api-2.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kimi-agent-module-api"
-version = "2.1.0"
+version = "2.3.0"
 description = "Stable contracts for community-built assistant modules"
 requires-python = ">=3.14"
 authors = [{ name = "Webhead" }]

{kimi_agent_module_api-2.1.0 → kimi_agent_module_api-2.3.0}/src/kimi_agent_module_api/__init__.py

@@ -37,10 +37,13 @@ from kimi_agent_module_api.contracts import (
     TextInputStyle,
 )
 from kimi_agent_module_api.settings import ModuleSetting, ModuleSettingsDefinition
+from kimi_agent_module_api.files import FileAccessError, ToolAttachment, ToolFile, ToolFiles
 from kimi_agent_module_api.tools import (
     ModuleToolContext,
     ModuleToolHandler,
     ModuleToolRegistry,
+    ModuleTurnBudget,
+    TriggeringDiscordMessageSnapshot,
 )
 from kimi_agent_module_api.trust import TrustTier
 
@@ -152,6 +155,7 @@ __all__ = [
     "MODULE_ENTRYPOINT_GROUP",
     "AppModule",
     "ConfigSnapshot",
+    "FileAccessError",
     "GuildSettingsSchema",
     "InviteSnapshot",
     "LayoutGallery",
@@ -171,6 +175,7 @@ __all__ = [
     "ModuleToolContext",
     "ModuleToolHandler",
     "ModuleToolRegistry",
+    "ModuleTurnBudget",
     "OutgoingLayout",
     "ProposalActor",
     "ProposalError",
@@ -183,6 +188,10 @@ __all__ = [
     "ServiceRequirement",
     "TextInputSpec",
     "TextInputStyle",
+    "ToolAttachment",
+    "ToolFile",
+    "ToolFiles",
+    "TriggeringDiscordMessageSnapshot",
     "TrustTier",
     "render_guild_settings",
 ]

{kimi_agent_module_api-2.1.0 → kimi_agent_module_api-2.3.0}/src/kimi_agent_module_api/contracts.py

@@ -143,6 +143,8 @@ class ModulePermissions:
     override_target_policy: bool = False
     raw_bot: bool = False
     raw_storage: bool = False
+    # Read admitted attachments and caller-owned workspace files in tool handlers.
+    tool_files: bool = False
 
 
 @dataclass(frozen=True, slots=True)

kimi_agent_module_api-2.3.0/src/kimi_agent_module_api/files.py

@@ -0,0 +1,61 @@
+"""Read-only, caller-scoped file access during one module tool invocation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal, Protocol
+
+
+class FileAccessError(ValueError):
+    """A bounded, safe-to-display file error; never includes host paths or URLs."""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+@dataclass(frozen=True, slots=True)
+class ToolAttachment:
+    """An admitted attachment or an explicit unavailable entry.
+
+    ``id`` is opaque and valid only for this invocation. ``workspace_path`` is
+    relative to the caller's workspace, and may be reused in later turns.
+    Reply images have generated filenames when the host has no source name.
+    No Discord SDK objects, signed URLs, or absolute paths are exposed.
+    """
+
+    id: str
+    filename: str
+    size: int
+    media_type: str | None
+    source: Literal["current", "reply"] = "current"
+    workspace_path: str | None = None
+    unavailable_reason: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ToolFile:
+    filename: str
+    media_type: str | None
+    data: bytes = field(repr=False)
+
+
+class ToolFiles(Protocol):
+    """Available only when ``permissions.tool_files`` is declared.
+
+    Reads are bounded by the requested limit and host limits, and share an
+    aggregate byte budget per invocation. They use the caller's workspace and
+    admitted turn inputs; they never fetch arbitrary URLs or re-fetch Discord.
+    The port expires when the handler returns. Copying bytes does not extend
+    the host's privacy/retention guarantees; modules own any further persistence.
+    """
+
+    @property
+    def attachments(self) -> tuple[ToolAttachment, ...]: ...
+
+    async def read_attachment(self, attachment_id: str, *, max_bytes: int) -> ToolFile: ...
+
+    async def read_workspace(self, path: str, *, max_bytes: int) -> ToolFile: ...
+
+
+__all__ = ["FileAccessError", "ToolAttachment", "ToolFile", "ToolFiles"]

{kimi_agent_module_api-2.1.0 → kimi_agent_module_api-2.3.0}/src/kimi_agent_module_api/testing.py

@@ -23,6 +23,7 @@ from typing import Any, TypeVar, overload
 from pydantic_settings import BaseSettings
 
 from kimi_agent_module_api.trust import TrustTier
+from kimi_agent_module_api.files import FileAccessError, ToolAttachment, ToolFile
 
 from kimi_agent_module_api.contracts import (
     ALL_DISCORD_ACTIONS,
@@ -1313,6 +1314,70 @@ def load_context(
     return context, recorder
 
 
+class FakeToolFiles:
+    """In-memory invocation files; paths and IDs are exact fixture keys.
+
+    ``close()`` simulates handler return. Bounds and aggregate accounting match
+    the host. This fake never reads the test process's filesystem or network.
+    """
+
+    def __init__(
+        self,
+        attachments: tuple[ToolAttachment, ...] = (),
+        *,
+        attachment_files: Mapping[str, ToolFile] | None = None,
+        workspace_files: Mapping[str, ToolFile] | None = None,
+        max_bytes: int = 50 * 1024 * 1024,
+    ) -> None:
+        self._attachments = attachments
+        self.attachment_files = dict(attachment_files or {})
+        self.workspace_files = dict(workspace_files or {})
+        self.reads: list[tuple[str, str, int]] = []
+        self._remaining = min(max_bytes, 50 * 1024 * 1024)
+        self._active = True
+
+    def close(self) -> None:
+        self._active = False
+
+    def _check_active(self) -> None:
+        if not self._active:
+            raise FileAccessError("expired", "File access expired when the tool invocation ended.")
+
+    @property
+    def attachments(self) -> tuple[ToolAttachment, ...]:
+        self._check_active()
+        return self._attachments
+
+    def _read(self, file: ToolFile | None, max_bytes: int) -> ToolFile:
+        self._check_active()
+        if type(max_bytes) is not int or max_bytes < 1:
+            raise FileAccessError("invalid_limit", "max_bytes must be a positive integer.")
+        if self._remaining <= 0:
+            raise FileAccessError(
+                "budget_exhausted", "The invocation's file read budget is exhausted."
+            )
+        if file is None:
+            raise FileAccessError("unavailable", "File is not available in this fixture.")
+        if len(file.data) > min(max_bytes, self._remaining):
+            raise FileAccessError("too_large", "File exceeds the file read limit.")
+        self._remaining -= len(file.data)
+        return file
+
+    async def read_attachment(self, attachment_id: str, *, max_bytes: int) -> ToolFile:
+        self._check_active()
+        entry = next((item for item in self.attachments if item.id == attachment_id), None)
+        if entry is None:
+            raise FileAccessError("unknown_attachment", "Unknown attachment for this invocation.")
+        if entry.unavailable_reason:
+            raise FileAccessError("unavailable", entry.unavailable_reason)
+        self.reads.append(("attachment", attachment_id, max_bytes))
+        return self._read(self.attachment_files.get(attachment_id), max_bytes)
+
+    async def read_workspace(self, path: str, *, max_bytes: int) -> ToolFile:
+        self.reads.append(("workspace", path, max_bytes))
+        return self._read(self.workspace_files.get(path), max_bytes)
+
+
 __all__ = [
     "DiscordCall",
     "FakeDiscordActions",
@@ -1327,6 +1392,7 @@ __all__ = [
     "FakeResponse",
     "FakeScheduler",
     "FakeServiceRegistry",
+    "FakeToolFiles",
     "FakeTrust",
     "LoadContextRecorder",
     "MemoryStorage",

{kimi_agent_module_api-2.1.0 → kimi_agent_module_api-2.3.0}/src/kimi_agent_module_api/tools.py

@@ -6,9 +6,31 @@ from collections.abc import Callable, Coroutine, Mapping
 from dataclasses import dataclass, field
 from typing import Any, Protocol
 
+from kimi_agent_module_api.files import ToolFiles
 from kimi_agent_module_api.trust import TrustTier
 
 
+class ModuleTurnBudget(Protocol):
+    """Host-owned counters shared by every module call in one outer model turn."""
+
+    def consume(self, name: str, limit: int) -> bool:
+        """Consume one named allowance, or return ``False`` without changing it."""
+
+        ...
+
+
+@dataclass(frozen=True, slots=True)
+class TriggeringDiscordMessageSnapshot:
+    """Immutable evidence captured from the Discord message at turn entry."""
+
+    message_id: int
+    guild_id: int
+    channel_id: int
+    author_id: int
+    content: str
+    author_is_bot: bool
+
+
 @dataclass(frozen=True, slots=True)
 class ModuleToolContext:
     """Who is calling a module tool, and from where.
@@ -32,6 +54,16 @@ class ModuleToolContext:
     # Discord message that initiated this model turn. It is absent for personal
     # app commands and other surfaces that are not rooted in a Discord message.
     trigger_discord_message_id: int | None = None
+    # Invocation-scoped read-only port. Declare permissions.tool_files and
+    # require tools.files.v1; never retain this port beyond the handler.
+    files: ToolFiles | None = None
+    # Host-owned values captured before turn preparation can await. Unlike a
+    # later Discord fetch, this evidence cannot change or disappear mid-turn.
+    # Added after all API 2.2 fields to preserve positional construction.
+    trigger_discord_message_snapshot: TriggeringDiscordMessageSnapshot | None = None
+    # Mutable host-owned port whose lifetime is the complete outer model turn.
+    # Counters are automatically namespaced to the installed module.
+    turn_budget: ModuleTurnBudget | None = None
 
 
 type ModuleToolHandler = Callable[[dict[str, Any], ModuleToolContext], Coroutine[Any, Any, str]]
@@ -67,4 +99,10 @@ class ModuleToolRegistry(Protocol):
     ) -> None: ...
 
 
-__all__ = ["ModuleToolContext", "ModuleToolHandler", "ModuleToolRegistry"]
+__all__ = [
+    "ModuleToolContext",
+    "ModuleToolHandler",
+    "ModuleToolRegistry",
+    "ModuleTurnBudget",
+    "TriggeringDiscordMessageSnapshot",
+]

{kimi_agent_module_api-2.1.0 → kimi_agent_module_api-2.3.0/src/kimi_agent_module_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kimi-agent-module-api
-Version: 2.1.0
+Version: 2.3.0
 Summary: Stable contracts for community-built assistant modules
 Author: Webhead
 License-Expression: MIT
@@ -30,6 +30,8 @@ implementation, or module loader. It exports:
   (storage, scheduler, events, Discord actions, interactions, HTTP, services,
   trust, proposals, health) plus the validators the host runs at preflight.
 - `kimi_agent_module_api.events`: the normalized `discord.*` event payloads.
+- `kimi_agent_module_api.files`: `ToolFiles`, `ToolAttachment`, `ToolFile`, and
+  `FileAccessError` for invocation-scoped attachment and workspace reads.
 - `kimi_agent_module_api.testing`: a fake for every port, `load_context()` for
   exercising `create()`, and `MemoryStorage` (install the `testing` extra) so a
   module can unit test itself with only this package installed.
@@ -82,15 +84,31 @@ Message-deletion events include cached author classification:
 `MessageDeleteEvent.author_is_bot` and `MessageBulkDeleteEvent.bot_message_ids`.
 The values remain unknown for messages that were absent from Discord's cache.
 
-SDK 2.1 adds `ModuleToolContext.trigger_discord_message_id`. Mention-path tool
-calls receive the exact source Discord message snowflake; other surfaces receive
-`None`. Modules that act on a user's source message should require
-`kimi-agent-module-api>=2.1,<3`, reject `None`, fetch that exact message through
-`ctx.discord`, and verify its author before acting.
+SDK 2.1 adds `ModuleToolContext.trigger_discord_message_id`. SDK 2.3 adds
+`trigger_discord_message_snapshot`, an immutable host-owned capture of the
+message, guild, channel, author, content, and bot status made at turn entry.
+Mention-path tool calls receive both; personal and non-message surfaces receive
+`None`. Modules that need authoritative evidence from the triggering message
+should require `kimi-agent-module-api>=2.3,<3` and use the snapshot instead of
+re-fetching mutable or deletable Discord state.
 
 Modules use namespaced guild documents and the physical table names returned
 by `ctx.storage.table()`.
 
+SDK 2.2 adds optional `ModuleToolContext.files`. Declare
+`ModulePermissions(tool_files=True)`, depend on `kimi-agent-module-api>=2.2,<3`,
+and require `tools.files.v1` in `ModuleSpec.requires_capabilities`. Existing modules
+keep `api_version=2` and receive `files=None` without the permission.
+`ctx.files.attachments` lists admitted current/reply entries;
+`read_attachment(id, max_bytes=...)` and `read_workspace(path, max_bytes=...)`
+return bounded bytes without network downloads. The reader expires when the handler
+returns and is scoped to the actual caller. `testing.FakeToolFiles` supports
+independent tests. Module `ctx.http` methods apply an 8 MiB host ceiling even when
+callers supply `max_bytes`; `download` buffers and validates the bounded response
+before yielding chunks so connections are released on early consumer exit. See the
+[file access guide](https://github.com/webhead2oo9/kimi-agent/blob/main/docs/module-files.md)
+for moderation, reply-image availability, privacy, and limits.
+
 ## Testing the SDK
 
 From this package directory, run its tests without installing the Kimi application:

{kimi_agent_module_api-2.1.0 → kimi_agent_module_api-2.3.0}/src/kimi_agent_module_api.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ pyproject.toml
 src/kimi_agent_module_api/__init__.py
 src/kimi_agent_module_api/contracts.py
 src/kimi_agent_module_api/events.py
+src/kimi_agent_module_api/files.py
 src/kimi_agent_module_api/images.py
 src/kimi_agent_module_api/py.typed
 src/kimi_agent_module_api/settings.py
@@ -16,5 +17,6 @@ src/kimi_agent_module_api.egg-info/dependency_links.txt
 src/kimi_agent_module_api.egg-info/requires.txt
 src/kimi_agent_module_api.egg-info/top_level.txt
 tests/test_contracts.py
+tests/test_files.py
 tests/test_public_api.py
 tests/test_testing.py

{kimi_agent_module_api-2.1.0 → kimi_agent_module_api-2.3.0}/tests/test_contracts.py

@@ -2,8 +2,8 @@
 
 from __future__ import annotations
 
-from importlib.metadata import version
 import dataclasses
+from importlib.metadata import version
 from typing import Any
 
 import pytest
@@ -19,6 +19,7 @@ from kimi_agent_module_api import (
     ModuleRuntimeContext,
     ModuleSpec,
     ModuleToolContext,
+    TriggeringDiscordMessageSnapshot,
     TrustTier,
     render_guild_settings,
 )
@@ -83,8 +84,66 @@ def test_spec_and_runtime_context_keep_stable_defaults() -> None:
     assert {"events", "scheduler", "storage", "discord", "interactions", "services"} <= required
 
 
-def test_distribution_version_includes_trigger_message_contract() -> None:
-    assert version("kimi-agent-module-api") == "2.1.0"
+def test_distribution_version_includes_triggering_message_snapshot_contract() -> None:
+    assert version("kimi-agent-module-api") == "2.3.0"
+
+
+def test_triggering_discord_message_snapshot_is_immutable() -> None:
+    snapshot = TriggeringDiscordMessageSnapshot(
+        message_id=11,
+        guild_id=22,
+        channel_id=33,
+        author_id=44,
+        content="original",
+        author_is_bot=False,
+    )
+
+    with pytest.raises(dataclasses.FrozenInstanceError):
+        snapshot.content = "edited"  # type: ignore[misc]
+
+
+def test_module_tool_context_preserves_api_2_2_nine_positional_arguments() -> None:
+    files = object()
+
+    context = ModuleToolContext(
+        11,
+        "Alice",
+        22,
+        33,
+        44,
+        TrustTier.REGULAR,
+        {"demo": {"enabled": True}},
+        55,
+        files,  # type: ignore[arg-type]
+    )
+
+    assert context.files is files
+    assert context.trigger_discord_message_snapshot is None
+
+
+def test_module_tool_context_adds_turn_budget_after_prior_positional_fields() -> None:
+    class Budget:
+        def consume(self, name: str, limit: int) -> bool:
+            return bool(name) and limit > 0
+
+    snapshot = TriggeringDiscordMessageSnapshot(55, 22, 33, 11, "content", False)
+    budget = Budget()
+    context = ModuleToolContext(
+        11,
+        "Alice",
+        22,
+        33,
+        44,
+        TrustTier.REGULAR,
+        {},
+        55,
+        None,
+        snapshot,
+        budget,
+    )
+
+    assert context.trigger_discord_message_snapshot is snapshot
+    assert context.turn_budget is budget
 
 
 def test_spec_requires_an_explicit_keyword_api_version() -> None:

kimi_agent_module_api-2.3.0/tests/test_files.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import pytest
+
+from kimi_agent_module_api import FileAccessError, ToolAttachment, ToolFile, ToolFiles
+from kimi_agent_module_api.testing import FakeToolFiles
+
+
+@pytest.mark.asyncio
+async def test_fake_preserves_bytes_and_enforces_aggregate_budget() -> None:
+    attachment = ToolAttachment("a", "image.png", 3, "image/png")
+    file = ToolFile("image.png", "image/png", b"raw")
+    fake = FakeToolFiles(
+        (attachment,),
+        attachment_files={"a": file},
+        workspace_files={"saved.png": file},
+        max_bytes=5,
+    )
+    port: ToolFiles = fake
+    assert (await port.read_attachment("a", max_bytes=3)).data == b"raw"
+    with pytest.raises(FileAccessError, match="limit"):
+        await port.read_workspace("saved.png", max_bytes=3)
+    assert "raw" not in repr(file)
+    fake.close()
+    with pytest.raises(FileAccessError) as error:
+        await port.read_attachment("a", max_bytes=3)
+    assert error.value.code == "expired"
+
+
+@pytest.mark.asyncio
+async def test_fake_does_not_read_unavailable_attachments() -> None:
+    fake = FakeToolFiles(
+        (ToolAttachment("a", "audio.wav", 3, "audio/wav", unavailable_reason="Blocked"),),
+        attachment_files={"a": ToolFile("audio.wav", "audio/wav", b"raw")},
+    )
+    with pytest.raises(FileAccessError, match="Blocked"):
+        await fake.read_attachment("a", max_bytes=3)
+    with pytest.raises(FileAccessError) as error:
+        await fake.read_attachment("other", max_bytes=3)
+    assert error.value.code == "unknown_attachment"
+    assert not fake.reads