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

{kimi_agent_module_api-2.2.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.2.0
+Version: 2.3.0
 Summary: Stable contracts for community-built assistant modules
 Author: Webhead
 License-Expression: MIT
@@ -84,11 +84,13 @@ 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()`.
@@ -101,7 +103,9 @@ keep `api_version=2` and receive `files=None` without the permission.
 `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
+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.
 

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

@@ -67,11 +67,13 @@ 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()`.
@@ -84,7 +86,9 @@ keep `api_version=2` and receive `files=None` without the permission.
 `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
+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.
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "kimi-agent-module-api"
-version = "2.2.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.2.0 → kimi_agent_module_api-2.3.0}/src/kimi_agent_module_api/__init__.py

@@ -42,6 +42,8 @@ from kimi_agent_module_api.tools import (
     ModuleToolContext,
     ModuleToolHandler,
     ModuleToolRegistry,
+    ModuleTurnBudget,
+    TriggeringDiscordMessageSnapshot,
 )
 from kimi_agent_module_api.trust import TrustTier
 
@@ -173,6 +175,7 @@ __all__ = [
     "ModuleToolContext",
     "ModuleToolHandler",
     "ModuleToolRegistry",
+    "ModuleTurnBudget",
     "OutgoingLayout",
     "ProposalActor",
     "ProposalError",
@@ -188,6 +191,7 @@ __all__ = [
     "ToolAttachment",
     "ToolFile",
     "ToolFiles",
+    "TriggeringDiscordMessageSnapshot",
     "TrustTier",
     "render_guild_settings",
 ]

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

@@ -6,8 +6,29 @@ from collections.abc import Callable, Coroutine, Mapping
 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
+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)
@@ -36,6 +57,13 @@ class ModuleToolContext:
     # 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]]
@@ -71,4 +99,10 @@ class ModuleToolRegistry(Protocol):
     ) -> None: ...
 
 
-__all__ = ["ModuleToolContext", "ModuleToolHandler", "ModuleToolRegistry"]
+__all__ = [
+    "ModuleToolContext",
+    "ModuleToolHandler",
+    "ModuleToolRegistry",
+    "ModuleTurnBudget",
+    "TriggeringDiscordMessageSnapshot",
+]

{kimi_agent_module_api-2.2.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.2.0
+Version: 2.3.0
 Summary: Stable contracts for community-built assistant modules
 Author: Webhead
 License-Expression: MIT
@@ -84,11 +84,13 @@ 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()`.
@@ -101,7 +103,9 @@ keep `api_version=2` and receive `files=None` without the permission.
 `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
+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.
 

{kimi_agent_module_api-2.2.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_tool_files_contract() -> None:
-    assert version("kimi-agent-module-api") == "2.2.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: