kimi-agent-module-api 2.0.0__tar.gz → 2.2.0__tar.gz

{kimi_agent_module_api-2.0.0/src/kimi_agent_module_api.egg-info → kimi_agent_module_api-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kimi-agent-module-api
-Version: 2.0.0
+Version: 2.2.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.
@@ -69,23 +71,39 @@ documents installation, declarations, lifecycle, and every runtime port. The
 [reference module](https://github.com/webhead2oo9/kimi-agent/tree/main/bot/modules/example)
 is a complete, commented example that exercises most ports; start there.
 
-Guild-scoped live command replacement was added in 1.1. Modules using
+Modules using guild-scoped live command replacement through
 `InteractionRouter.replace_guild_commands()` should require the host capability
 `discord.guild_commands.v1`.
 
-Version 1.2 adds typed modal forms and a narrow Components V2 layout model. Once a response uses
+The SDK provides typed modal forms and a narrow Components V2 layout model. Once a response uses
 that layout model, Discord requires every later edit of the same message to remain a layout.
 Modules using them should require
 `discord.modals.v1` and/or `discord.components_v2.v1`.
 
-Version 1.3 adds cached author classification to message-deletion events:
+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.
 
-Version 2 requires an explicit, source-pinned `ModuleSpec.api_version`, and
-removes the temporary guild-settings legacy flag and module table aliases.
-Modules must use namespaced guild documents and migrate legacy tables to the
-physical names returned by `ctx.storage.table()` before upgrading.
+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.
+
+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. 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
 

{kimi_agent_module_api-2.0.0 → kimi_agent_module_api-2.2.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.
@@ -52,23 +54,39 @@ documents installation, declarations, lifecycle, and every runtime port. The
 [reference module](https://github.com/webhead2oo9/kimi-agent/tree/main/bot/modules/example)
 is a complete, commented example that exercises most ports; start there.
 
-Guild-scoped live command replacement was added in 1.1. Modules using
+Modules using guild-scoped live command replacement through
 `InteractionRouter.replace_guild_commands()` should require the host capability
 `discord.guild_commands.v1`.
 
-Version 1.2 adds typed modal forms and a narrow Components V2 layout model. Once a response uses
+The SDK provides typed modal forms and a narrow Components V2 layout model. Once a response uses
 that layout model, Discord requires every later edit of the same message to remain a layout.
 Modules using them should require
 `discord.modals.v1` and/or `discord.components_v2.v1`.
 
-Version 1.3 adds cached author classification to message-deletion events:
+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.
 
-Version 2 requires an explicit, source-pinned `ModuleSpec.api_version`, and
-removes the temporary guild-settings legacy flag and module table aliases.
-Modules must use namespaced guild documents and migrate legacy tables to the
-physical names returned by `ctx.storage.table()` before upgrading.
+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.
+
+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. 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
 

{kimi_agent_module_api-2.0.0 → kimi_agent_module_api-2.2.0}/pyproject.toml

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

{kimi_agent_module_api-2.0.0 → kimi_agent_module_api-2.2.0}/src/kimi_agent_module_api/__init__.py

@@ -37,6 +37,7 @@ 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,
@@ -152,6 +153,7 @@ __all__ = [
     "MODULE_ENTRYPOINT_GROUP",
     "AppModule",
     "ConfigSnapshot",
+    "FileAccessError",
     "GuildSettingsSchema",
     "InviteSnapshot",
     "LayoutGallery",
@@ -183,6 +185,9 @@ __all__ = [
     "ServiceRequirement",
     "TextInputSpec",
     "TextInputStyle",
+    "ToolAttachment",
+    "ToolFile",
+    "ToolFiles",
     "TrustTier",
     "render_guild_settings",
 ]

{kimi_agent_module_api-2.0.0 → kimi_agent_module_api-2.2.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.2.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.0.0 → kimi_agent_module_api-2.2.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.0.0 → kimi_agent_module_api-2.2.0}/src/kimi_agent_module_api/tools.py

@@ -7,6 +7,7 @@ from dataclasses import dataclass, field
 from typing import Any, Protocol
 
 from kimi_agent_module_api.trust import TrustTier
+from kimi_agent_module_api.files import ToolFiles
 
 
 @dataclass(frozen=True, slots=True)
@@ -29,6 +30,12 @@ class ModuleToolContext:
     trust_tier: TrustTier
     # Operator per-tool configuration from ``<CONFIG_DIR>/tools/<tool>.md``.
     tool_configs: Mapping[str, Mapping[str, Any]] = field(default_factory=dict)
+    # 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
 
 
 type ModuleToolHandler = Callable[[dict[str, Any], ModuleToolContext], Coroutine[Any, Any, str]]

{kimi_agent_module_api-2.0.0 → kimi_agent_module_api-2.2.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.0.0
+Version: 2.2.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.
@@ -69,23 +71,39 @@ documents installation, declarations, lifecycle, and every runtime port. The
 [reference module](https://github.com/webhead2oo9/kimi-agent/tree/main/bot/modules/example)
 is a complete, commented example that exercises most ports; start there.
 
-Guild-scoped live command replacement was added in 1.1. Modules using
+Modules using guild-scoped live command replacement through
 `InteractionRouter.replace_guild_commands()` should require the host capability
 `discord.guild_commands.v1`.
 
-Version 1.2 adds typed modal forms and a narrow Components V2 layout model. Once a response uses
+The SDK provides typed modal forms and a narrow Components V2 layout model. Once a response uses
 that layout model, Discord requires every later edit of the same message to remain a layout.
 Modules using them should require
 `discord.modals.v1` and/or `discord.components_v2.v1`.
 
-Version 1.3 adds cached author classification to message-deletion events:
+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.
 
-Version 2 requires an explicit, source-pinned `ModuleSpec.api_version`, and
-removes the temporary guild-settings legacy flag and module table aliases.
-Modules must use namespaced guild documents and migrate legacy tables to the
-physical names returned by `ctx.storage.table()` before upgrading.
+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.
+
+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. 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
 

{kimi_agent_module_api-2.0.0 → kimi_agent_module_api-2.2.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.0.0 → kimi_agent_module_api-2.2.0}/tests/test_contracts.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from importlib.metadata import version
 import dataclasses
 from typing import Any
 
@@ -82,6 +83,10 @@ def test_spec_and_runtime_context_keep_stable_defaults() -> None:
     assert {"events", "scheduler", "storage", "discord", "interactions", "services"} <= required
 
 
+def test_distribution_version_includes_tool_files_contract() -> None:
+    assert version("kimi-agent-module-api") == "2.2.0"
+
+
 def test_spec_requires_an_explicit_keyword_api_version() -> None:
     def create(_ctx: ModuleLoadContext) -> AppModule:
         raise AssertionError("not called")

kimi_agent_module_api-2.2.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