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

{kimi_agent_module_api-2.3.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.3.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
@@ -116,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.3.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
@@ -99,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.3.0 → kimi_agent_module_api-2.4.0}/pyproject.toml

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

@@ -46,6 +46,15 @@ from kimi_agent_module_api.tools import (
     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"
@@ -147,6 +156,7 @@ class ModuleRuntimeContext:
     proposals: ProposalService | None = None
     raw_bot: Any = None
     raw_storage: Any = None
+    scheduled_results: ScheduledResults | None = None
 
 
 __all__ = [
@@ -183,6 +193,13 @@ __all__ = [
     "ProposalService",
     "ProposalState",
     "RoleSnapshot",
+    "ScheduledResult",
+    "ScheduledResultAccessError",
+    "ScheduledResultAttachment",
+    "ScheduledResultFiles",
+    "ScheduledResultHandler",
+    "ScheduledResultMessage",
+    "ScheduledResults",
     "ScopedModuleMigration",
     "ServiceDeclaration",
     "ServiceRequirement",

{kimi_agent_module_api-2.3.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.3.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.3.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.3.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
@@ -116,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.3.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.3.0 → kimi_agent_module_api-2.4.0}/tests/test_contracts.py

@@ -84,8 +84,8 @@ def test_spec_and_runtime_context_keep_stable_defaults() -> None:
     assert {"events", "scheduler", "storage", "discord", "interactions", "services"} <= required
 
 
-def test_distribution_version_includes_triggering_message_snapshot_contract() -> None:
-    assert version("kimi-agent-module-api") == "2.3.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:

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())