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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kimi-agent-module-api
-Version: 2.2.0
+Version: 2.4.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.scheduled_results`: durable subscriptions to published
+  task output, typed results, and bounded attachment readers (SDK 2.4).
 - `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
@@ -84,11 +86,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 +105,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.
 
@@ -112,3 +118,14 @@ From this package directory, run its tests without installing the Kimi applicati
 ```console
 uv run --isolated --group test python -m pytest -q
 ```
+
+SDK 2.4 adds `ScheduledResults`: named, guild-scoped subscriptions to task output
+following confirmed Discord publication. Declare
+`ModulePermissions(scheduled_results=("my_subscription",))`, require the host
+capability `scheduled_results.v1`, and register through `ctx.scheduled_results`
+during startup. Handlers receive a typed `ScheduledResult` and an invocation-scoped
+`ScheduledResultFiles` reader. Returning acknowledges the result; exceptions retry
+with the same notification ID. Use that ID for idempotent processing.
+`FakeScheduledResults` supports standalone tests. See the
+[published-result guide](https://github.com/Kimi-Discord-Agent/kimi-agent/blob/main/docs/module-scheduled-results.md)
+for access checks, limits, retention, and deletion responsibilities.

{kimi_agent_module_api-2.2.0 → kimi_agent_module_api-2.4.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.scheduled_results`: durable subscriptions to published
+  task output, typed results, and bounded attachment readers (SDK 2.4).
 - `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
@@ -67,11 +69,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 +88,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.
 
@@ -95,3 +101,14 @@ From this package directory, run its tests without installing the Kimi applicati
 ```console
 uv run --isolated --group test python -m pytest -q
 ```
+
+SDK 2.4 adds `ScheduledResults`: named, guild-scoped subscriptions to task output
+following confirmed Discord publication. Declare
+`ModulePermissions(scheduled_results=("my_subscription",))`, require the host
+capability `scheduled_results.v1`, and register through `ctx.scheduled_results`
+during startup. Handlers receive a typed `ScheduledResult` and an invocation-scoped
+`ScheduledResultFiles` reader. Returning acknowledges the result; exceptions retry
+with the same notification ID. Use that ID for idempotent processing.
+`FakeScheduledResults` supports standalone tests. See the
+[published-result guide](https://github.com/Kimi-Discord-Agent/kimi-agent/blob/main/docs/module-scheduled-results.md)
+for access checks, limits, retention, and deletion responsibilities.

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

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

@@ -42,8 +42,19 @@ from kimi_agent_module_api.tools import (
     ModuleToolContext,
     ModuleToolHandler,
     ModuleToolRegistry,
+    ModuleTurnBudget,
+    TriggeringDiscordMessageSnapshot,
 )
 from kimi_agent_module_api.trust import TrustTier
+from kimi_agent_module_api.scheduled_results import (
+    ScheduledResult,
+    ScheduledResultAccessError,
+    ScheduledResultAttachment,
+    ScheduledResultFiles,
+    ScheduledResultHandler,
+    ScheduledResultMessage,
+    ScheduledResults,
+)
 
 MODULE_API_VERSION = 2
 MODULE_ENTRYPOINT_GROUP = "kimi_agent.modules"
@@ -145,6 +156,7 @@ class ModuleRuntimeContext:
     proposals: ProposalService | None = None
     raw_bot: Any = None
     raw_storage: Any = None
+    scheduled_results: ScheduledResults | None = None
 
 
 __all__ = [
@@ -173,6 +185,7 @@ __all__ = [
     "ModuleToolContext",
     "ModuleToolHandler",
     "ModuleToolRegistry",
+    "ModuleTurnBudget",
     "OutgoingLayout",
     "ProposalActor",
     "ProposalError",
@@ -180,6 +193,13 @@ __all__ = [
     "ProposalService",
     "ProposalState",
     "RoleSnapshot",
+    "ScheduledResult",
+    "ScheduledResultAccessError",
+    "ScheduledResultAttachment",
+    "ScheduledResultFiles",
+    "ScheduledResultHandler",
+    "ScheduledResultMessage",
+    "ScheduledResults",
     "ScopedModuleMigration",
     "ServiceDeclaration",
     "ServiceRequirement",
@@ -188,6 +208,7 @@ __all__ = [
     "ToolAttachment",
     "ToolFile",
     "ToolFiles",
+    "TriggeringDiscordMessageSnapshot",
     "TrustTier",
     "render_guild_settings",
 ]

{kimi_agent_module_api-2.2.0 → kimi_agent_module_api-2.4.0}/src/kimi_agent_module_api/contracts.py

@@ -145,6 +145,8 @@ class ModulePermissions:
     raw_storage: bool = False
     # Read admitted attachments and caller-owned workspace files in tool handlers.
     tool_files: bool = False
+    # Names of durable, explicitly guild-scoped published-task subscriptions.
+    scheduled_results: tuple[str, ...] = ()
 
 
 @dataclass(frozen=True, slots=True)
@@ -439,6 +441,11 @@ def validate_permissions(module_name: str, permissions: ModulePermissions) -> No
             )
     for rule in permissions.http_hosts:
         validate_host_rule(rule)
+    names = permissions.scheduled_results
+    if len(set(names)) != len(names) or any(
+        not re.fullmatch(r"[a-z0-9_]{1,64}", name) for name in names
+    ):
+        raise ModuleContractError("scheduled-result subscription names must be unique and valid")
 
 
 def validate_services(

kimi_agent_module_api-2.4.0/src/kimi_agent_module_api/scheduled_results.py

@@ -0,0 +1,105 @@
+"""Durable subscriptions to confirmed Discord publications, separate from module jobs."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Literal, Protocol
+
+from kimi_agent_module_api.contracts import MessageRef, ModuleContractError
+
+MAX_RESULT_FILE_BYTES = 8 * 1024 * 1024
+MAX_RESULT_TOTAL_FILE_BYTES = 16 * 1024 * 1024
+
+
+class ScheduledResultAccessError(ModuleContractError):
+    """The subscription or its retained output is unavailable to this caller."""
+
+
+@dataclass(frozen=True, slots=True)
+class ScheduledResultAttachment:
+    id: str
+    filename: str
+    size_bytes: int
+    description: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ScheduledResultMessage:
+    message: MessageRef
+    content: str
+    attachments: tuple[ScheduledResultAttachment, ...] = ()
+    # The published Discord embed as JSON, capped at 32 KiB. No network fetches.
+    embed_json: str | None = None
+    embed_unavailable_reason: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ScheduledResult:
+    notification_id: str
+    subscription: str
+    task_id: str
+    run_id: str
+    revision: int
+    guild_id: int
+    owner_id: int
+    published_at: float
+    expires_at: float
+    messages: tuple[ScheduledResultMessage, ...]
+    outcome: Literal["completed"] = "completed"
+
+
+class ScheduledResultFiles(Protocol):
+    """Read only this notification's attachments during its handler invocation.
+
+    The host rechecks access on every read. Reads are capped at 8 MiB each and
+    16 MiB total per invocation, including repeated reads. Handles expire on
+    return, cancellation, deletion, or retention expiry; copy bytes deliberately.
+    """
+
+    async def read(
+        self, attachment_id: str, *, max_bytes: int = MAX_RESULT_FILE_BYTES
+    ) -> bytes: ...
+
+
+type ScheduledResultHandler = Callable[[ScheduledResult, ScheduledResultFiles], Awaitable[None]]
+
+
+class ScheduledResults(Protocol):
+    """A module-bound port. Declare each name in ``permissions.scheduled_results``.
+
+    Register on every start. A name is scoped to one guild per registration;
+    the same name may be registered in several guilds. Existing subscriptions
+    survive downtime; new registrations never replay historical publications.
+    Returning acknowledges the notification. Raising retries with the same ID.
+    Use that ID to make your own writes/remote requests idempotent.
+    """
+
+    async def subscribe(
+        self, name: str, *, guild_id: int, handler: ScheduledResultHandler
+    ) -> None: ...
+
+    async def unsubscribe(self, name: str, *, guild_id: int) -> None:
+        """Forget this subscription and its pending/acknowledged notifications."""
+        ...
+
+
+def validate_result_subscription(name: str, guild_id: int) -> None:
+    # Keep validation here usable by the host and standalone test fakes.
+    if (
+        not isinstance(name, str)
+        or not 1 <= len(name) <= 64
+        or any(char not in "abcdefghijklmnopqrstuvwxyz0123456789_" for char in name)
+    ):
+        raise ModuleContractError("scheduled-result names use 1-64 lowercase letters, digits or _")
+    if isinstance(guild_id, bool) or not isinstance(guild_id, int) or not 0 < guild_id < 2**64:
+        raise ModuleContractError("scheduled-result subscriptions require a positive guild ID")
+
+
+def validate_result_read_limit(max_bytes: int) -> None:
+    if (
+        isinstance(max_bytes, bool)
+        or not isinstance(max_bytes, int)
+        or not (0 < max_bytes <= MAX_RESULT_FILE_BYTES)
+    ):
+        raise ScheduledResultAccessError("attachment read limit must be between 1 byte and 8 MiB")

{kimi_agent_module_api-2.2.0 → kimi_agent_module_api-2.4.0}/src/kimi_agent_module_api/testing.py

@@ -24,6 +24,15 @@ 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.scheduled_results import (
+    MAX_RESULT_FILE_BYTES,
+    MAX_RESULT_TOTAL_FILE_BYTES,
+    ScheduledResult,
+    ScheduledResultAccessError,
+    ScheduledResultHandler,
+    validate_result_read_limit,
+    validate_result_subscription,
+)
 
 from kimi_agent_module_api.contracts import (
     ALL_DISCORD_ACTIONS,
@@ -85,6 +94,93 @@ _MAX_FLOAT_LOG = math.log(sys.float_info.max)
 _T = TypeVar("_T")
 
 
+class FakeScheduledResultFiles:
+    """An invocation-scoped reader; the same size/lifetime limits as the host."""
+
+    def __init__(
+        self, files: Mapping[str, bytes], *, available: Callable[[], bool] = lambda: True
+    ) -> None:
+        self.files = files
+        self.available = available
+        self.open = True
+        self.remaining = MAX_RESULT_TOTAL_FILE_BYTES
+
+    async def read(self, attachment_id: str, *, max_bytes: int = MAX_RESULT_FILE_BYTES) -> bytes:
+        validate_result_read_limit(max_bytes)
+        data = self.files.get(attachment_id)
+        if (
+            not self.open
+            or not self.available()
+            or self.remaining <= 0
+            or data is None
+            or len(data) > min(max_bytes, self.remaining)
+        ):
+            raise ScheduledResultAccessError("Result file unavailable or read limit exceeded")
+        self.remaining -= len(data)
+        return data
+
+
+class FakeScheduledResults:
+    """Drive retries explicitly with ``deliver``; successful IDs are acknowledged.
+
+    A failed invocation propagates its exception and can be delivered again.
+    Supply the original result object to model a restart or duplicate attempt.
+    This fake has no background runner, Discord access, or persistence.
+    """
+
+    def __init__(
+        self,
+        declared: tuple[str, ...] = (),
+        *,
+        is_guild_active: Callable[[int], bool] = lambda _guild_id: True,
+    ) -> None:
+        self.declared, self.is_guild_active = declared, is_guild_active
+        self.handlers: dict[tuple[str, int], ScheduledResultHandler] = {}
+        self.acknowledged: set[str] = set()
+        self.attempts: list[str] = []
+
+    def _validate(self, name: str, guild_id: int) -> None:
+        validate_result_subscription(name, guild_id)
+        if name not in self.declared:
+            raise ScheduledResultAccessError("Undeclared scheduled-result subscription")
+
+    async def subscribe(self, name: str, *, guild_id: int, handler: ScheduledResultHandler) -> None:
+        self._validate(name, guild_id)
+        self.handlers[name, guild_id] = handler
+
+    async def unsubscribe(self, name: str, *, guild_id: int) -> None:
+        self._validate(name, guild_id)
+        self.handlers.pop((name, guild_id), None)
+
+    async def deliver(
+        self,
+        result: ScheduledResult,
+        *,
+        files: Mapping[str, bytes] | None = None,
+        preview: bool = False,
+    ) -> None:
+        if preview or result.notification_id in self.acknowledged:
+            return
+        handler = self.handlers.get((result.subscription, result.guild_id))
+        if handler is None or not self.is_guild_active(result.guild_id):
+            raise ScheduledResultAccessError("Subscriber unavailable in this guild")
+        visible = {a.id for m in result.messages for a in m.attachments}
+        reader = FakeScheduledResultFiles(
+            {k: v for k, v in (files or {}).items() if k in visible},
+            available=lambda: (
+                self.is_guild_active(result.guild_id)
+                and result.subscription in self.declared
+                and self.handlers.get((result.subscription, result.guild_id)) is handler
+            ),
+        )
+        self.attempts.append(result.notification_id)
+        try:
+            await handler(result, reader)
+            self.acknowledged.add(result.notification_id)
+        finally:
+            reader.open = False
+
+
 @dataclass(slots=True)
 class _Closable:
     _on_close: Callable[[], object]
@@ -1390,6 +1486,8 @@ __all__ = [
     "FakeInteractions",
     "FakeProposals",
     "FakeResponse",
+    "FakeScheduledResultFiles",
+    "FakeScheduledResults",
     "FakeScheduler",
     "FakeServiceRegistry",
     "FakeToolFiles",

{kimi_agent_module_api-2.2.0 → kimi_agent_module_api-2.4.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.4.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.4.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.scheduled_results`: durable subscriptions to published
+  task output, typed results, and bounded attachment readers (SDK 2.4).
 - `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
@@ -84,11 +86,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 +105,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.
 
@@ -112,3 +118,14 @@ From this package directory, run its tests without installing the Kimi applicati
 ```console
 uv run --isolated --group test python -m pytest -q
 ```
+
+SDK 2.4 adds `ScheduledResults`: named, guild-scoped subscriptions to task output
+following confirmed Discord publication. Declare
+`ModulePermissions(scheduled_results=("my_subscription",))`, require the host
+capability `scheduled_results.v1`, and register through `ctx.scheduled_results`
+during startup. Handlers receive a typed `ScheduledResult` and an invocation-scoped
+`ScheduledResultFiles` reader. Returning acknowledges the result; exceptions retry
+with the same notification ID. Use that ID for idempotent processing.
+`FakeScheduledResults` supports standalone tests. See the
+[published-result guide](https://github.com/Kimi-Discord-Agent/kimi-agent/blob/main/docs/module-scheduled-results.md)
+for access checks, limits, retention, and deletion responsibilities.

{kimi_agent_module_api-2.2.0 → kimi_agent_module_api-2.4.0}/src/kimi_agent_module_api.egg-info/SOURCES.txt

@@ -7,6 +7,7 @@ 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/scheduled_results.py
 src/kimi_agent_module_api/settings.py
 src/kimi_agent_module_api/testing.py
 src/kimi_agent_module_api/tools.py
@@ -19,4 +20,5 @@ 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_scheduled_results.py
 tests/test_testing.py

{kimi_agent_module_api-2.2.0 → kimi_agent_module_api-2.4.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_scheduled_result_contract() -> None:
+    assert version("kimi-agent-module-api") == "2.4.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.4.0/tests/test_scheduled_results.py

@@ -0,0 +1,99 @@
+"""Exercise the public subscriber contract without importing a host."""
+
+from __future__ import annotations
+
+from dataclasses import FrozenInstanceError, replace
+
+import pytest
+
+from kimi_agent_module_api import (
+    ModulePermissions,
+    ScheduledResult,
+    ScheduledResultAccessError,
+    ScheduledResultAttachment,
+    ScheduledResultMessage,
+)
+from kimi_agent_module_api.contracts import MessageRef, ModuleContractError, validate_permissions
+from kimi_agent_module_api.testing import FakeScheduledResults
+
+
+def result():
+    return ScheduledResult(
+        notification_id="notification",
+        subscription="reports",
+        task_id="task",
+        run_id="run",
+        revision=3,
+        guild_id=100,
+        owner_id=10,
+        published_at=1000,
+        expires_at=2000,
+        messages=(
+            ScheduledResultMessage(
+                MessageRef(100, 300, 900),
+                "Published",
+                (ScheduledResultAttachment("file", "result.txt", 3),),
+            ),
+        ),
+    )
+
+
+def test_result_is_immutable_and_permissions_must_be_named():
+    with pytest.raises(FrozenInstanceError):
+        result().owner_id = 99
+    validate_permissions("reports", ModulePermissions(scheduled_results=("reports",)))
+    for names in (("Upper Case",), ("reports", "reports"), ("",)):
+        with pytest.raises(ModuleContractError):
+            validate_permissions("reports", ModulePermissions(scheduled_results=names))
+
+
+@pytest.mark.asyncio
+async def test_fake_retry_acknowledgement_preview_and_file_lifetime():
+    fake = FakeScheduledResults(("reports",))
+    attempts, readers = [], []
+
+    async def handler(notification, files):
+        attempts.append(notification.notification_id)
+        readers.append(files)
+        assert await files.read("file") == b"abc"
+        with pytest.raises(ScheduledResultAccessError):
+            await files.read("not published")
+        with pytest.raises(ScheduledResultAccessError):
+            await files.read("file", max_bytes=2)
+        if len(attempts) == 1:
+            raise RuntimeError("retry me")
+
+    await fake.subscribe("reports", guild_id=100, handler=handler)
+    await fake.deliver(result(), preview=True)
+    assert attempts == []
+    files = {"file": b"abc", "not published": b"private"}
+    with pytest.raises(RuntimeError, match="retry me"):
+        await fake.deliver(result(), files=files)
+    assert not fake.acknowledged
+    await fake.deliver(result(), files=files)
+    await fake.deliver(result(), files=files)
+    assert attempts == ["notification", "notification"]
+    assert fake.acknowledged == {"notification"}
+    for reader in readers:
+        with pytest.raises(ScheduledResultAccessError):
+            await reader.read("file")
+
+
+@pytest.mark.asyncio
+async def test_fake_permission_and_guild_scope():
+    fake = FakeScheduledResults(("reports",), is_guild_active=lambda guild: guild == 100)
+
+    async def handler(_result, _files):
+        pass
+
+    with pytest.raises(ScheduledResultAccessError):
+        await fake.subscribe("other", guild_id=100, handler=handler)
+    with pytest.raises(ModuleContractError):
+        await fake.subscribe("reports", guild_id=0, handler=handler)
+    await fake.subscribe("reports", guild_id=200, handler=handler)
+    with pytest.raises(ScheduledResultAccessError):
+        await fake.deliver(replace(result(), guild_id=200))
+    await fake.subscribe("reports", guild_id=100, handler=handler)
+    await fake.unsubscribe("reports", guild_id=100)
+    with pytest.raises(ScheduledResultAccessError):
+        await fake.deliver(result())