kimi-agent-module-api 1.2.0__tar.gz → 1.3.0__tar.gz

{kimi_agent_module_api-1.2.0/src/kimi_agent_module_api.egg-info → kimi_agent_module_api-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kimi-agent-module-api
-Version: 1.2.0
+Version: 1.3.0
 Summary: Stable contracts for community-built assistant modules
 Author: Webhead
 License-Expression: MIT
@@ -59,3 +59,15 @@ Version 1.2 adds typed modal forms and a narrow Components V2 layout model. Once
 that layout model, Discord requires every later edit of the same message to remain a layout.
 Modules using them should depend on `kimi-agent-module-api>=1.2,<2` and require
 `discord.modals.v1` and/or `discord.components_v2.v1`.
+
+Version 1.3 adds cached author classification to message-deletion events:
+`MessageDeleteEvent.author_is_bot` and `MessageBulkDeleteEvent.bot_message_ids`.
+The values remain unknown for messages that were absent from Discord's cache.
+
+## Testing the SDK
+
+From this package directory, run its tests without installing the Kimi application:
+
+```console
+uv run --isolated --group test python -m pytest -q
+```

{kimi_agent_module_api-1.2.0 → kimi_agent_module_api-1.3.0}/README.md

@@ -42,3 +42,15 @@ Version 1.2 adds typed modal forms and a narrow Components V2 layout model. Once
 that layout model, Discord requires every later edit of the same message to remain a layout.
 Modules using them should depend on `kimi-agent-module-api>=1.2,<2` and require
 `discord.modals.v1` and/or `discord.components_v2.v1`.
+
+Version 1.3 adds cached author classification to message-deletion events:
+`MessageDeleteEvent.author_is_bot` and `MessageBulkDeleteEvent.bot_message_ids`.
+The values remain unknown for messages that were absent from Discord's cache.
+
+## Testing the SDK
+
+From this package directory, run its tests without installing the Kimi application:
+
+```console
+uv run --isolated --group test python -m pytest -q
+```

{kimi_agent_module_api-1.2.0 → kimi_agent_module_api-1.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kimi-agent-module-api"
-version = "1.2.0"
+version = "1.3.0"
 description = "Stable contracts for community-built assistant modules"
 requires-python = ">=3.14"
 authors = [{ name = "Webhead" }]
@@ -18,6 +18,9 @@ Repository = "https://github.com/webhead2oo9/kimi-agent"
 # kimi_agent_module_api.testing.MemoryStorage runs real SQL in unit tests.
 testing = ["aiosqlite"]
 
+[dependency-groups]
+test = ["aiosqlite", "pytest", "pytest-asyncio"]
+
 [build-system]
 requires = ["setuptools>=84"]
 build-backend = "setuptools.build_meta"
@@ -27,3 +30,7 @@ where = ["src"]
 
 [tool.setuptools.package-data]
 kimi_agent_module_api = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_default_fixture_loop_scope = "function"

{kimi_agent_module_api-1.2.0 → kimi_agent_module_api-1.3.0}/src/kimi_agent_module_api/contracts.py

@@ -12,6 +12,7 @@ owner manifest and enforced through the ports below; they are not a sandbox.
 from __future__ import annotations
 
 import json
+import keyword
 import math
 import re
 from collections.abc import AsyncIterator, Awaitable, Callable, Mapping, Sequence
@@ -326,6 +327,13 @@ CORE_TOPIC_PREFIX = "discord"
 _CORE_RESERVED_MODULE_NAMES = frozenset({CORE_TOPIC_PREFIX, "proposals"})
 CUSTOM_ID_PREFIX = "m"
 CUSTOM_ID_MAX_LENGTH = 100
+# A modal ID also carries a fixed-width per-open suffix so two people opening the
+# same form do not share one entry in the host's modal table. That suffix is not
+# the module's to spend, so a modal's declared ID has a smaller budget than a
+# button's. Fixed width on purpose: a variable one would shrink the budget as the
+# host ran, letting a modal open successfully and then fail later.
+MODAL_NONCE_CHARS = 8
+MODAL_CUSTOM_ID_MAX_LENGTH = CUSTOM_ID_MAX_LENGTH - 1 - MODAL_NONCE_CHARS
 
 
 def table_prefix(module_name: str) -> str:
@@ -987,6 +995,7 @@ class TrustLookup(Protocol):
 
 
 type CommandOptionKind = Literal["string", "integer", "boolean", "user", "channel", "role"]
+_OPTION_KINDS = frozenset({"string", "integer", "boolean", "user", "channel", "role"})
 
 
 @dataclass(frozen=True, slots=True)
@@ -1147,6 +1156,208 @@ class ModalSpec:
     parts: tuple[str, ...] = ()
 
 
+_OPTIONS_WITH_CHOICES = frozenset({"string", "integer"})
+# Keep command and group name validation in the SDK so the public fakes reject
+# the same payloads discord.py rejects while constructing the live tree.
+_COMMAND_NAME_RE = re.compile(
+    r"^[-_\w\u0e31-\u0e3a\u0e47-\u0e4e\u0900-\u0903\u093a\u093b\u093c"
+    r"\u093e\u093f\u0940-\u094f\u0955\u0956\u0957\u0962\u0963]{1,32}$"
+)
+_BUTTON_STYLES = frozenset({"primary", "secondary", "success", "danger"})
+_DISCORD_INTEGER_MAX = (1 << 53) - 1
+_DISCORD_INTEGER_MIN = -_DISCORD_INTEGER_MAX
+
+
+def validate_command_spec(spec: CommandSpec) -> None:
+    """Validate the Discord limits a command payload must satisfy.
+
+    A whole ``tree.sync()`` is one bulk PUT, so a single malformed command
+    rejects every command in that scope. Discord.py checks command and group
+    *names* itself and reorders required options ahead of optional ones; these
+    are the limits nothing else enforces before the payload reaches Discord.
+    """
+
+    for label, name in (("command", spec.name), ("command group", spec.group)):
+        if name is None:
+            continue
+        if (
+            not isinstance(name, str)
+            or _COMMAND_NAME_RE.fullmatch(name) is None
+            or name.lower() != name
+        ):
+            raise ModuleContractError(f"invalid {label} name {name!r}")
+    if not isinstance(spec.description, str) or not 1 <= len(spec.description) <= 100:
+        raise ModuleContractError("a command description must contain 1 to 100 characters")
+    if spec.group is not None and (
+        not isinstance(spec.group_description, str) or len(spec.group_description) > 100
+    ):
+        raise ModuleContractError("a command group description cannot exceed 100 characters")
+    if len(spec.options) > 25:
+        raise ModuleContractError("a command cannot declare more than 25 options")
+
+    names: set[str] = set()
+    for option in spec.options:
+        # Discord applies the slash-command name grammar to option names, while
+        # the host also builds each option into a Python parameter. Enforce the
+        # intersection here: this keeps valid leading underscores and lowercase
+        # Unicode identifiers while rejecting Discord-only names such as ``a-b``.
+        if (
+            not isinstance(option.name, str)
+            or _COMMAND_NAME_RE.fullmatch(option.name) is None
+            or option.name.lower() != option.name
+            or not option.name.isidentifier()
+            or keyword.iskeyword(option.name)
+        ):
+            raise ModuleContractError(f"invalid command option name {option.name!r}")
+        if option.name in names:
+            raise ModuleContractError("command option names must be unique")
+        names.add(option.name)
+        if option.kind not in _OPTION_KINDS:
+            raise ModuleContractError(f"unsupported command option kind {option.kind!r}")
+        if not isinstance(option.description, str) or not 1 <= len(option.description) <= 100:
+            raise ModuleContractError(
+                f"the description for option {option.name!r} must contain 1 to 100 characters"
+            )
+        if option.choices and option.autocomplete:
+            # Discord rejects a payload carrying both, and discord.py emits both.
+            raise ModuleContractError(
+                f"option {option.name!r} cannot use choices and autocomplete together"
+            )
+        if (option.choices or option.autocomplete) and option.kind not in _OPTIONS_WITH_CHOICES:
+            raise ModuleContractError(
+                f"option {option.name!r} cannot use choices or autocomplete on a "
+                f"{option.kind} option"
+            )
+        if len(option.choices) > 25:
+            raise ModuleContractError(f"option {option.name!r} cannot declare more than 25 choices")
+        values: set[str | int] = set()
+        for name, value in option.choices:
+            if not isinstance(name, str) or not 1 <= len(name) <= 100:
+                raise ModuleContractError(f"invalid choice name {name!r} on option {option.name!r}")
+            if isinstance(value, bool) or not isinstance(value, str | int):
+                raise ModuleContractError(
+                    f"invalid choice value {value!r} on option {option.name!r}"
+                )
+            # A choice whose value type disagrees with its option is a 400 on the
+            # whole payload, and nothing downstream cross-checks the two.
+            if not isinstance(value, str if option.kind == "string" else int):
+                raise ModuleContractError(
+                    f"choice values on {option.kind} option {option.name!r} must be "
+                    f"{'strings' if option.kind == 'string' else 'integers'}"
+                )
+            if (
+                option.kind == "integer"
+                and isinstance(value, int)
+                and not _DISCORD_INTEGER_MIN <= value <= _DISCORD_INTEGER_MAX
+            ):
+                raise ModuleContractError(
+                    f"an integer choice value on option {option.name!r} must be between "
+                    f"{_DISCORD_INTEGER_MIN} and {_DISCORD_INTEGER_MAX}"
+                )
+            if isinstance(value, str) and not 1 <= len(value) <= 100:
+                raise ModuleContractError(
+                    f"a choice value on option {option.name!r} must contain 1 to 100 characters"
+                )
+            if value in values:
+                raise ModuleContractError(f"choice values on option {option.name!r} must be unique")
+            values.add(value)
+        for bound in (option.min_value, option.max_value):
+            if bound is None:
+                continue
+            if isinstance(bound, bool) or not isinstance(bound, int):
+                raise ModuleContractError(f"option {option.name!r} bounds must be integers")
+            if option.kind != "integer":
+                # Only integer options carry the bounds through to Discord, so a
+                # bound anywhere else would be silently dropped.
+                raise ModuleContractError(
+                    f"option {option.name!r} cannot set min_value or max_value on a "
+                    f"{option.kind} option"
+                )
+            if not _DISCORD_INTEGER_MIN <= bound <= _DISCORD_INTEGER_MAX:
+                raise ModuleContractError(
+                    f"option {option.name!r} bounds must be between "
+                    f"{_DISCORD_INTEGER_MIN} and {_DISCORD_INTEGER_MAX}"
+                )
+        if (
+            option.min_value is not None
+            and option.max_value is not None
+            and option.min_value > option.max_value
+        ):
+            raise ModuleContractError(f"option {option.name!r} min_value cannot exceed max_value")
+
+
+def validate_button_spec(button: ButtonSpec) -> None:
+    """Validate Discord's hard button limits."""
+
+    if not isinstance(button.key, str) or not _TOPIC_SEGMENT_RE.fullmatch(button.key):
+        raise ModuleContractError(f"invalid button key {button.key!r}")
+    if any(not isinstance(part, str) or ":" in part for part in button.parts):
+        raise ModuleContractError("button custom_id parts must be strings without ':'")
+    if not isinstance(button.label, str) or len(button.label) > 80:
+        raise ModuleContractError("a button label cannot exceed 80 characters")
+    if button.style not in _BUTTON_STYLES:
+        raise ModuleContractError(f"invalid button style {button.style!r}")
+    if button.emoji is not None and (not isinstance(button.emoji, str) or not button.emoji):
+        raise ModuleContractError("a button emoji must be a non-empty string")
+    if not button.label and button.emoji is None:
+        raise ModuleContractError("a button must provide a label or emoji")
+
+
+def validate_component_spec(component: Any) -> None:
+    """Validate one interactive component, whichever kind it is."""
+
+    if isinstance(component, ButtonSpec):
+        validate_button_spec(component)
+    elif isinstance(component, SelectSpec):
+        validate_select_spec(component)
+    else:
+        raise ModuleContractError(f"unsupported component {component!r}")
+
+
+def validate_select_spec(select: SelectSpec) -> None:
+    """Validate Discord's hard select-menu limits."""
+
+    if not isinstance(select.key, str) or not _TOPIC_SEGMENT_RE.fullmatch(select.key):
+        raise ModuleContractError(f"invalid select key {select.key!r}")
+    if any(not isinstance(part, str) or ":" in part for part in select.parts):
+        raise ModuleContractError("select custom_id parts must be strings without ':'")
+    if select.placeholder is not None and (
+        not isinstance(select.placeholder, str) or len(select.placeholder) > 150
+    ):
+        raise ModuleContractError("a select placeholder cannot exceed 150 characters")
+    if not 1 <= len(select.options) <= 25:
+        raise ModuleContractError("a select must contain between one and 25 options")
+
+    values: set[str] = set()
+    for label, value, description in select.options:
+        if not isinstance(label, str) or not 1 <= len(label) <= 100:
+            raise ModuleContractError("a select option label must contain 1 to 100 characters")
+        if not isinstance(value, str) or not 1 <= len(value) <= 100:
+            raise ModuleContractError("a select option value must contain 1 to 100 characters")
+        if value in values:
+            raise ModuleContractError("select option values must be unique")
+        values.add(value)
+        if description is not None and (
+            not isinstance(description, str) or not 1 <= len(description) <= 100
+        ):
+            raise ModuleContractError(
+                "a select option description must contain 1 to 100 characters"
+            )
+
+    for name, bound, low in (
+        ("min_values", select.min_values, 0),
+        ("max_values", select.max_values, 1),
+    ):
+        if isinstance(bound, bool) or not isinstance(bound, int) or not low <= bound <= 25:
+            raise ModuleContractError(f"select {name} must be between {low} and 25")
+    if select.min_values > select.max_values:
+        raise ModuleContractError("select min_values cannot exceed max_values")
+    # max_values may exceed the option count (Discord clamps it), but a
+    # minimum above the count can never be satisfied, so the select is dead.
+    if select.min_values > len(select.options):
+        raise ModuleContractError("select min_values cannot exceed the number of options")
+
+
 def validate_modal_spec(modal: ModalSpec) -> None:
     """Validate Discord's hard modal and text-input limits."""
     if not isinstance(modal.key, str) or not _TOPIC_SEGMENT_RE.fullmatch(modal.key):

{kimi_agent_module_api-1.2.0 → kimi_agent_module_api-1.3.0}/src/kimi_agent_module_api/events.py

@@ -69,11 +69,13 @@ class MessageDeleteEvent:
     author_id: int | None
     cached_content: str | None
     cached_attachments: tuple[AttachmentSnapshot, ...]
+    author_is_bot: bool | None = None
 
 
 @dataclass(frozen=True, slots=True)
 class MessageBulkDeleteEvent:
     refs: tuple[MessageRef, ...]
+    bot_message_ids: tuple[int, ...] = ()
 
 
 @dataclass(frozen=True, slots=True)

{kimi_agent_module_api-1.2.0 → kimi_agent_module_api-1.3.0}/src/kimi_agent_module_api/testing.py

@@ -26,7 +26,9 @@ from kimi_agent_module_api.trust import TrustTier
 
 from kimi_agent_module_api.contracts import (
     ALL_DISCORD_ACTIONS,
+    MODAL_CUSTOM_ID_MAX_LENGTH,
     Backoff,
+    ButtonSpec,
     ChannelSnapshot,
     CommandSpec,
     GuildCommand,
@@ -58,10 +60,14 @@ from kimi_agent_module_api.contracts import (
     ProposalState,
     RoleSnapshot,
     ScopedModuleMigration,
+    SelectSpec,
     ServiceUnavailable,
     TrustTierName,
     UndeclaredDiscordAction,
     build_custom_id,
+    parse_custom_id,
+    validate_command_spec,
+    validate_component_spec,
     validate_modal_spec,
     validate_layout_components,
     validate_outgoing_layout,
@@ -590,6 +596,7 @@ class FakeInteraction:
         guild_name: str | None = "Test Guild",
         message: MessageRef | None = None,
         message_uses_layout: bool = False,
+        module_name: str | None = None,
     ) -> None:
         self._message = message
         self._guild_name = guild_name
@@ -604,6 +611,31 @@ class FakeInteraction:
         self.shown_modals: list[ModalSpec] = []
         self.deferred: bool | None = None
         self._original_uses_layout = message_uses_layout
+        parsed_custom_id = parse_custom_id(custom_id or "")
+        self._module_name = module_name or (
+            parsed_custom_id[0] if parsed_custom_id is not None else None
+        )
+
+    def _component_module_name(self) -> str:
+        if self._module_name is None:
+            raise ModuleContractError(
+                "FakeInteraction needs module_name to validate component custom_ids; "
+                "use FakeInteractions.interaction() or pass module_name explicitly"
+            )
+        return self._module_name
+
+    def _validate_components(
+        self, components: Sequence[Any], *, layout: OutgoingLayout | None
+    ) -> None:
+        for component in components:
+            validate_component_spec(component)
+            if isinstance(component, ButtonSpec | SelectSpec):
+                build_custom_id(
+                    self._component_module_name(),
+                    component.key,
+                    *component.parts,
+                )
+        validate_layout_components(components, layout=layout)
 
     @property
     def guild_id(self) -> int:
@@ -652,9 +684,9 @@ class FakeInteraction:
     ) -> None:
         if layout is not None and (content is not None or embed is not None):
             raise ModuleContractError("layout cannot be combined with content or embed")
+        self._validate_components(components, layout=layout)
         if layout is not None:
             validate_outgoing_layout(layout)
-            validate_layout_components(components, layout=layout)
         self.responses.append(
             FakeResponse(content, embed, ephemeral, tuple(components), "respond", layout=layout)
         )
@@ -665,6 +697,11 @@ class FakeInteraction:
 
     async def show_modal(self, modal: ModalSpec) -> None:
         validate_modal_spec(modal)
+        declared = build_custom_id(self._component_module_name(), modal.key, *modal.parts)
+        if len(declared) > MODAL_CUSTOM_ID_MAX_LENGTH:
+            raise ModuleContractError(
+                f"modal custom_id exceeds {MODAL_CUSTOM_ID_MAX_LENGTH} characters"
+            )
         self.shown_modals.append(modal)
 
     async def edit_original(
@@ -681,9 +718,9 @@ class FakeInteraction:
             )
         if layout is not None and (content is not None or embed is not None):
             raise ModuleContractError("layout cannot be combined with content or embed")
+        self._validate_components(components, layout=layout)
         if layout is not None:
             validate_outgoing_layout(layout)
-            validate_layout_components(components, layout=layout)
         self.responses.append(
             FakeResponse(content, embed, False, tuple(components), "edit", layout=layout)
         )
@@ -700,17 +737,107 @@ class FakeInteraction:
         return self.responses[-1]
 
 
+@dataclass(slots=True)
+class FakeInteractionOwnership:
+    """Shared top-level command ownership for a multi-module test host."""
+
+    routers: list[FakeInteractions] = field(default_factory=list)
+
+    def register(self, router: FakeInteractions) -> None:
+        self.routers.append(router)
+
+    def unregister(self, router: FakeInteractions) -> None:
+        if router in self.routers:
+            self.routers.remove(router)
+
+    def global_top_names(self) -> set[str]:
+        return {top_name for router in self.routers for top_name in router._global_top_kinds()}
+
+    def guild_top_names(
+        self,
+        guild_id: int,
+        *,
+        excluding: FakeInteractions | None = None,
+    ) -> set[str]:
+        return {
+            spec.group or spec.name
+            for router in self.routers
+            if router is not excluding
+            for spec, _handler in router.guild_commands.get(guild_id, {}).values()
+        }
+
+    def global_owner(self, top_name: str) -> tuple[FakeInteractions, str] | None:
+        for router in self.routers:
+            kind = router._global_top_kinds().get(top_name)
+            if kind is not None:
+                return router, kind
+        return None
+
+    def guild_owner(self, top_name: str, *, guild_id: int | None = None) -> FakeInteractions | None:
+        for router in self.routers:
+            guild_sets = (
+                (router.guild_commands.get(guild_id, {}),)
+                if guild_id is not None
+                else tuple(router.guild_commands.values())
+            )
+            for commands in guild_sets:
+                if any(
+                    (spec.group or spec.name) == top_name for spec, _handler in commands.values()
+                ):
+                    return router
+        return None
+
+
 class FakeInteractions:
     """Records command and component registrations; tests invoke handlers directly."""
 
-    def __init__(self, module_name: str) -> None:
+    def __init__(
+        self,
+        module_name: str,
+        *,
+        ownership: FakeInteractionOwnership | None = None,
+        is_guild_active: Callable[[int], bool] | None = None,
+    ) -> None:
         self.module_name = module_name
+        self.ownership = ownership or FakeInteractionOwnership()
+        self.ownership.register(self)
+        self._is_guild_active = (
+            is_guild_active if is_guild_active is not None else lambda _guild_id: True
+        )
         self.commands: dict[str, tuple[CommandSpec, Callable[..., Any]]] = {}
         self.guild_commands: dict[int, dict[str, tuple[CommandSpec, Callable[..., Any]]]] = {}
         self.guild_autocompletes: dict[int, dict[str, Callable[..., Any]]] = {}
         self.components: dict[tuple[str, str], Callable[..., Any]] = {}
         self.component_min_tiers: dict[tuple[str, str], TrustTierName] = {}
         self.autocompletes: dict[str, Callable[..., Any]] = {}
+        self._closed = False
+
+    def _ensure_open(self) -> None:
+        if self._closed:
+            raise RuntimeError(f"module {self.module_name!r} interactions are closed")
+
+    def interaction(self, **kwargs: Any) -> FakeInteraction:
+        """Create an interaction bound to this router's exact custom-ID namespace."""
+
+        self._ensure_open()
+        supplied = kwargs.pop("module_name", self.module_name)
+        if supplied != self.module_name:
+            raise ValueError(
+                f"interaction module_name {supplied!r} does not match {self.module_name!r}"
+            )
+        return FakeInteraction(module_name=self.module_name, **kwargs)
+
+    def _global_top_kinds(self) -> dict[str, str]:
+        """Top-level names the host tree would hold, derived so close() cannot drift.
+
+        Commands are stored by qualified name, but Discord and the host tree own
+        the *top* name, so every collision check has to look at that instead.
+        """
+
+        return {
+            (spec.group or spec.name): ("group" if spec.group else "command")
+            for spec, _handler in self.commands.values()
+        }
 
     def add_command(
         self,
@@ -719,11 +846,45 @@ class FakeInteractions:
         *,
         autocomplete: Callable[..., Any] | None = None,
     ) -> _Closable:
+        self._ensure_open()
+        validate_command_spec(spec)
+        if autocomplete is None and any(option.autocomplete for option in spec.options):
+            raise ModuleContractError(
+                f"module {self.module_name!r} command {spec.name!r} declares an autocomplete "
+                "option but supplied no autocomplete handler"
+            )
         qualified = f"{spec.group}.{spec.name}" if spec.group else spec.name
         if qualified in self.commands:
             raise ModuleContractError(
                 f"module {self.module_name!r} command {qualified!r} is already registered"
             )
+        top_name = spec.group or spec.name
+        kind = "group" if spec.group else "command"
+        existing_global = self.ownership.global_owner(top_name)
+        if existing_global is not None and existing_global[0] is not self:
+            raise ModuleContractError(
+                f"module {self.module_name!r} command {top_name!r} is already owned"
+            )
+        if existing_global is not None and existing_global[1] != kind:
+            raise ModuleContractError(
+                f"module {self.module_name!r} command {top_name!r} is both a command and a group"
+            )
+        if self.ownership.guild_owner(top_name) is not None:
+            raise ModuleContractError(
+                f"module {self.module_name!r} global command {top_name!r} "
+                "would shadow a guild command"
+            )
+        if spec.group is not None:
+            group_size = sum(
+                existing.group == spec.group for existing, _handler in self.commands.values()
+            )
+            if group_size >= 25:
+                raise ModuleContractError(
+                    f"module {self.module_name!r} command group {spec.group!r} "
+                    "cannot contain more than 25 commands"
+                )
+        if existing_global is None and len(self.ownership.global_top_names()) >= 100:
+            raise ModuleContractError("Discord allows at most 100 global slash commands")
         self.commands[qualified] = (spec, handler)
         if autocomplete is not None:
             self.autocompletes[qualified] = autocomplete
@@ -736,25 +897,53 @@ class FakeInteractions:
         guild_id: int,
         commands: Sequence[GuildCommand],
     ) -> None:
+        self._ensure_open()
         if guild_id <= 0:
             raise ModuleContractError("guild_id must be a positive Discord snowflake")
+        if commands and not self._is_guild_active(guild_id):
+            raise ModuleContractError(
+                f"module {self.module_name!r} is not active in guild {guild_id}"
+            )
         desired: dict[str, tuple[CommandSpec, Callable[..., Any]]] = {}
         autocompletes: dict[str, Callable[..., Any]] = {}
         top_kinds: dict[str, str] = {}
+        group_sizes: dict[str, int] = {}
+        for command in commands:
+            validate_command_spec(command.spec)
+            if command.autocomplete is None and any(
+                option.autocomplete for option in command.spec.options
+            ):
+                raise ModuleContractError(
+                    f"module {self.module_name!r} command {command.spec.name!r} declares an "
+                    "autocomplete option but supplied no autocomplete handler"
+                )
         for command in commands:
             top_name = command.spec.group or command.spec.name
             kind = "group" if command.spec.group else "command"
-            if top_name in self.commands:
+            if self.ownership.global_owner(top_name) is not None:
                 raise ModuleContractError(
                     f"module {self.module_name!r} guild command {top_name!r} "
                     "would shadow a global command"
                 )
+            guild_owner = self.ownership.guild_owner(top_name, guild_id=guild_id)
+            if guild_owner is not None and guild_owner is not self:
+                raise ModuleContractError(
+                    f"module {self.module_name!r} guild command {top_name!r} is already owned"
+                )
             previous_kind = top_kinds.setdefault(top_name, kind)
             if previous_kind != kind:
                 raise ModuleContractError(
                     f"module {self.module_name!r} guild command {top_name!r} "
                     "is both a command and a group"
                 )
+            if command.spec.group is not None:
+                group_size = group_sizes.get(command.spec.group, 0) + 1
+                if group_size > 25:
+                    raise ModuleContractError(
+                        f"module {self.module_name!r} guild command group "
+                        f"{command.spec.group!r} cannot contain more than 25 commands"
+                    )
+                group_sizes[command.spec.group] = group_size
             qualified = (
                 f"{command.spec.group}.{command.spec.name}"
                 if command.spec.group
@@ -768,6 +957,9 @@ class FakeInteractions:
             desired[qualified] = (command.spec, command.handler)
             if command.autocomplete is not None:
                 autocompletes[qualified] = command.autocomplete
+        other_top_names = self.ownership.guild_top_names(guild_id, excluding=self)
+        if len(other_top_names | set(top_kinds)) > 100:
+            raise ModuleContractError(f"guild {guild_id} would have more than 100 slash commands")
         if desired:
             self.guild_commands[guild_id] = desired
             self.guild_autocompletes[guild_id] = autocompletes
@@ -784,6 +976,7 @@ class FakeInteractions:
         expires_after_seconds: float | None = None,
         min_tier: TrustTierName = "member",
     ) -> _Closable:
+        self._ensure_open()
         if kind not in ("button", "select", "modal"):
             raise ModuleContractError(f"unsupported component kind {kind!r}")
         build_custom_id(self.module_name, key)
@@ -802,8 +995,23 @@ class FakeInteractions:
         )
 
     def custom_id(self, key: str, *parts: str) -> str:
+        self._ensure_open()
         return build_custom_id(self.module_name, key, *parts)
 
+    def close(self) -> None:
+        """Release fake registrations and shared ownership like the live router."""
+
+        if self._closed:
+            return
+        self._closed = True
+        self.commands.clear()
+        self.guild_commands.clear()
+        self.guild_autocompletes.clear()
+        self.components.clear()
+        self.component_min_tiers.clear()
+        self.autocompletes.clear()
+        self.ownership.unregister(self)
+
 
 class FakeGuildSettings:
     def __init__(
@@ -1038,6 +1246,7 @@ class RecordedTool:
     owner_only: bool
     guild_only: bool
     guild_ids: frozenset[int] | None
+    untrusted: bool
 
 
 class RecordingToolRegistry:
@@ -1058,6 +1267,7 @@ class RecordingToolRegistry:
         owner_only: bool = False,
         guild_only: bool = True,
         guild_ids: frozenset[int] | None = None,
+        untrusted: bool = True,
     ) -> None:
         self.tools[name] = RecordedTool(
             description,
@@ -1068,6 +1278,7 @@ class RecordingToolRegistry:
             owner_only,
             guild_only,
             guild_ids,
+            untrusted,
         )
 
 
@@ -1110,6 +1321,7 @@ __all__ = [
     "FakeHealth",
     "FakeHttp",
     "FakeInteraction",
+    "FakeInteractionOwnership",
     "FakeInteractions",
     "FakeProposals",
     "FakeResponse",

{kimi_agent_module_api-1.2.0 → kimi_agent_module_api-1.3.0}/src/kimi_agent_module_api/tools.py

@@ -43,6 +43,9 @@ class ModuleToolRegistry(Protocol):
     ``guild_only`` (the default) it is also hidden from DMs and personal chat,
     so its handler always sees a guild. ``guild_ids`` further scopes a tool to
     specific guilds (``None`` is everywhere; an empty set is nowhere).
+    Results default to untrusted because module tools commonly return Discord,
+    network, or user-authored data. Set ``untrusted=False`` only for output that
+    is wholly controlled by the installed module.
     """
 
     def register(
@@ -57,6 +60,7 @@ class ModuleToolRegistry(Protocol):
         owner_only: bool = False,
         guild_only: bool = True,
         guild_ids: frozenset[int] | None = None,
+        untrusted: bool = True,
     ) -> None: ...
 
 

{kimi_agent_module_api-1.2.0 → kimi_agent_module_api-1.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: 1.2.0
+Version: 1.3.0
 Summary: Stable contracts for community-built assistant modules
 Author: Webhead
 License-Expression: MIT
@@ -59,3 +59,15 @@ Version 1.2 adds typed modal forms and a narrow Components V2 layout model. Once
 that layout model, Discord requires every later edit of the same message to remain a layout.
 Modules using them should depend on `kimi-agent-module-api>=1.2,<2` and require
 `discord.modals.v1` and/or `discord.components_v2.v1`.
+
+Version 1.3 adds cached author classification to message-deletion events:
+`MessageDeleteEvent.author_is_bot` and `MessageBulkDeleteEvent.bot_message_ids`.
+The values remain unknown for messages that were absent from Discord's cache.
+
+## Testing the SDK
+
+From this package directory, run its tests without installing the Kimi application:
+
+```console
+uv run --isolated --group test python -m pytest -q
+```

{kimi_agent_module_api-1.2.0 → kimi_agent_module_api-1.3.0}/src/kimi_agent_module_api.egg-info/SOURCES.txt

@@ -14,4 +14,7 @@ src/kimi_agent_module_api.egg-info/PKG-INFO
 src/kimi_agent_module_api.egg-info/SOURCES.txt
 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
+src/kimi_agent_module_api.egg-info/top_level.txt
+tests/test_contracts.py
+tests/test_public_api.py
+tests/test_testing.py

kimi_agent_module_api-1.3.0/tests/test_contracts.py

@@ -0,0 +1,187 @@
+"""Representative contract tests owned by the standalone SDK package."""
+
+from __future__ import annotations
+
+import dataclasses
+from typing import Any
+
+import pytest
+from pydantic_settings import BaseSettings
+
+from kimi_agent_module_api import (
+    BASELINE_CAPABILITIES,
+    MODULE_API_VERSION,
+    ModuleCapabilities,
+    ModuleLoadContext,
+    ModulePermissions,
+    ModuleRuntimeContext,
+    ModuleSpec,
+    ModuleToolContext,
+    TrustTier,
+    render_guild_settings,
+)
+from kimi_agent_module_api.contracts import (
+    Backoff,
+    ButtonSpec,
+    CommandSpec,
+    EventTopicError,
+    GuildSettingField,
+    GuildSettingsSchema,
+    ModuleContractError,
+    ServiceDeclaration,
+    ServiceRequirement,
+    build_custom_id,
+    parse_custom_id,
+    split_topic,
+    table_prefix,
+    validate_command_spec,
+    validate_component_spec,
+    validate_guild_settings_schema,
+    validate_module_name,
+    validate_permissions,
+    validate_publish_topic,
+    validate_services,
+    validate_subscription,
+)
+from kimi_agent_module_api.events import CORE_TOPICS
+from kimi_agent_module_api.images import looks_like_image_attachment, sniff_image_media_type
+from kimi_agent_module_api.testing import load_context
+
+
+class DemoSettings(BaseSettings):
+    greeting: str = "hello"
+
+
+class OtherSettings(BaseSettings):
+    pass
+
+
+def _spec(name: str = "demo") -> ModuleSpec:
+    def create(_ctx: ModuleLoadContext) -> object:
+        raise AssertionError("not called")
+
+    return ModuleSpec(name=name, version="1.0.0", create=create)  # type: ignore[arg-type]
+
+
+def test_spec_and_runtime_context_keep_stable_defaults() -> None:
+    spec = _spec()
+    assert spec.api_version == MODULE_API_VERSION == 1
+    assert spec.permissions == ModulePermissions()
+    assert spec.dependencies == ()
+    required = {
+        field.name
+        for field in dataclasses.fields(ModuleRuntimeContext)
+        if field.default is dataclasses.MISSING
+    }
+    assert {"events", "scheduler", "storage", "discord", "interactions", "services"} <= required
+
+
+def test_load_context_exercises_public_create_helpers() -> None:
+    settings = DemoSettings(greeting="hi")
+    context, recorder = load_context(settings)
+
+    async def handler(_arguments: dict[str, Any], _ctx: ModuleToolContext) -> str:
+        return "ok"
+
+    assert context.settings_for(DemoSettings) is settings
+    context.registry.register("demo", "Demo", {"type": "object"}, handler)
+    context.register_tool_labels({"demo": "Doing a demo"})
+    context.declare_surface_tools("default", ("demo",))
+
+    assert recorder.labels == {"demo": "Doing a demo"}
+    assert recorder.surfaces == {"default": ("demo",)}
+    assert recorder.registry.tools["demo"].untrusted is True
+    assert context.capabilities.available == BASELINE_CAPABILITIES
+    with pytest.raises(TypeError, match="prepared module settings"):
+        context.settings_for(OtherSettings)
+
+
+def test_capabilities_and_trust_tiers_fail_closed() -> None:
+    capabilities = ModuleCapabilities(BASELINE_CAPABILITIES, False, False)
+    capabilities.require("discord.history.v1")
+    with pytest.raises(RuntimeError, match="does not provide"):
+        capabilities.require("discord.guild_commands.v1")
+    assert TrustTier.STAFF > TrustTier.REGULAR > TrustTier.MEMBER
+
+
+@pytest.mark.parametrize("name", ["Bad", "two words", "discord", "proposals"])
+def test_module_names_reject_reserved_or_malformed_values(name: str) -> None:
+    with pytest.raises(ModuleContractError):
+        validate_module_name(name)
+
+
+def test_topics_and_component_ids_enforce_module_namespaces() -> None:
+    assert table_prefix("audit-log") == "audit_log"
+    assert split_topic("discord.message") == ("discord", "message")
+    validate_publish_topic("case-manager", "case_manager.changed")
+    validate_subscription(
+        "case_audit",
+        ModulePermissions(event_topics=("case_manager.*",)),
+        "case_manager.changed",
+    )
+    custom_id = build_custom_id("case_manager", "approve", "123")
+    assert parse_custom_id(custom_id) == ("case_manager", "approve", ("123",))
+    with pytest.raises(EventTopicError):
+        validate_publish_topic("case-manager", "other.changed")
+    with pytest.raises(ModuleContractError):
+        build_custom_id("case_manager", "approve", "bad:part")
+
+
+def test_permissions_services_and_guild_settings_validate_together() -> None:
+    permissions = ModulePermissions(
+        discord_actions=frozenset({"send_message"}),
+        event_topics=("discord.message",),
+    )
+    validate_permissions("demo", permissions)
+    validate_services(
+        "consumer",
+        ("provider",),
+        (),
+        (ServiceRequirement("records.cases", 1, provider="provider"),),
+    )
+    validate_services("provider", (), (ServiceDeclaration("records.cases", 1),), ())
+    schema = GuildSettingsSchema(
+        fields=(GuildSettingField("mode", "enum", choices=("safe", "fast"), default="safe"),)
+    )
+    validate_guild_settings_schema("demo", schema)
+
+    with pytest.raises(ModuleContractError):
+        validate_permissions("demo", ModulePermissions(discord_actions=frozenset({"nuke"})))
+    with pytest.raises(ModuleContractError):
+        validate_guild_settings_schema(
+            "demo",
+            GuildSettingsSchema(fields=(GuildSettingField("Bad", "int"),)),
+        )
+
+
+def test_command_and_component_validation_match_discord_limits() -> None:
+    validate_command_spec(CommandSpec(name="ping", description="Ping the module"))
+    validate_component_spec(ButtonSpec("confirm", "Confirm"))
+    with pytest.raises(ModuleContractError):
+        validate_command_spec(CommandSpec(name="Bad", description="invalid name"))
+    with pytest.raises(ModuleContractError):
+        validate_component_spec(ButtonSpec("confirm", ""))
+
+
+def test_scheduler_backoff_rejects_non_finite_or_non_positive_values() -> None:
+    assert Backoff(base_seconds=2, max_seconds=8, multiplier=2) == Backoff(2, 8, 2)
+    for invalid in (0, -1, float("nan"), float("inf")):
+        with pytest.raises(ModuleContractError, match="backoff"):
+            Backoff(base_seconds=invalid)
+
+
+def test_rendered_settings_are_deterministic_and_safe() -> None:
+    assert render_guild_settings({"b": True, "a": [1, 2], "c": "x: y", "empty": None}) == (
+        '---\na: [1, 2]\nb: true\nc: "x: y"\n---\n'
+    )
+    with pytest.raises(ValueError, match="invalid guild setting name"):
+        render_guild_settings({"bad:key": True})
+
+
+def test_event_and_image_helpers_remain_host_independent() -> None:
+    assert CORE_TOPICS
+    assert all(split_topic(topic)[0] == "discord" for topic in CORE_TOPICS)
+    assert looks_like_image_attachment("photo.PNG", None)
+    assert looks_like_image_attachment(None, "image/jpeg")
+    assert sniff_image_media_type(b"\x89PNG\r\n\x1a\nrest") == "image/png"
+    assert sniff_image_media_type(b"not an image") is None

kimi_agent_module_api-1.3.0/tests/test_public_api.py

@@ -0,0 +1,43 @@
+"""The published SDK stays importable without the Kimi application runtime."""
+
+from __future__ import annotations
+
+import ast
+import importlib.util
+import sys
+from pathlib import Path
+
+import kimi_agent_module_api as api
+
+SDK_ROOT = Path(__file__).resolve().parents[1] / "src" / "kimi_agent_module_api"
+
+
+def test_public_exports_resolve() -> None:
+    assert api.__all__
+    assert all(getattr(api, name, None) is not None for name in api.__all__)
+
+
+def test_standalone_environment_has_no_core_runtime() -> None:
+    """CI runs this package from an isolated environment, outside core's import root."""
+    assert importlib.util.find_spec("app") is None
+    assert importlib.util.find_spec("discord") is None
+
+
+def test_sdk_imports_only_declared_dependencies() -> None:
+    allowed = set(sys.stdlib_module_names) | {
+        "aiosqlite",
+        "kimi_agent_module_api",
+        "pydantic_settings",
+    }
+    unexpected: dict[str, set[str]] = {}
+    for path in SDK_ROOT.glob("*.py"):
+        tree = ast.parse(path.read_text(encoding="utf-8"))
+        imported: set[str] = set()
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                imported.update(alias.name.split(".")[0] for alias in node.names)
+            elif isinstance(node, ast.ImportFrom) and node.module:
+                imported.add(node.module.split(".")[0])
+        if outside := imported - allowed:
+            unexpected[path.name] = outside
+    assert unexpected == {}

kimi_agent_module_api-1.3.0/tests/test_testing.py

@@ -0,0 +1,114 @@
+"""The SDK's protocol fakes work without importing host implementations."""
+
+from __future__ import annotations
+
+import pytest
+
+from kimi_agent_module_api.contracts import (
+    Backoff,
+    Event,
+    JobRun,
+    MessageRef,
+    MigrationContext,
+    ServiceUnavailable,
+    UndeclaredDiscordAction,
+)
+from kimi_agent_module_api.testing import (
+    FakeDiscordActions,
+    FakeEvents,
+    FakeInteraction,
+    FakeScheduler,
+    FakeServiceRegistry,
+    MemoryStorage,
+)
+
+
+@pytest.mark.asyncio
+async def test_fake_events_deliver_only_matching_subscriptions() -> None:
+    events = FakeEvents("demo")
+    seen: list[str] = []
+
+    async def handler(event: Event) -> None:
+        seen.append(event.topic)
+
+    registration = events.subscribe("discord.*", handler)
+    assert await events.deliver("discord.message", {"id": 1}) == 1
+    registration.close()
+    assert await events.deliver("discord.message_edit", {"id": 1}) == 0
+    assert seen == ["discord.message"]
+
+
+@pytest.mark.asyncio
+async def test_fake_scheduler_retries_then_settles_jobs() -> None:
+    scheduler = FakeScheduler()
+    attempts: list[int] = []
+
+    async def flaky(run: JobRun) -> None:
+        attempts.append(run.attempt)
+        if run.attempt == 1:
+            raise RuntimeError("retry")
+
+    scheduler.register("work", flaky)
+    await scheduler.run_every(
+        "job",
+        60,
+        "work",
+        backoff=Backoff(base_seconds=5, max_seconds=10, multiplier=2),
+    )
+
+    assert await scheduler.run_due(0) == 1
+    assert scheduler.jobs["job"].run_at == 5
+    assert await scheduler.run_due(5) == 1
+    assert scheduler.jobs["job"].run_at == 65
+    assert attempts == [1, 2]
+
+
+@pytest.mark.asyncio
+async def test_fake_discord_actions_enforce_declared_permissions() -> None:
+    actions = FakeDiscordActions("demo", frozenset({"send_message"}))
+    ref = await actions.send_message(42, "hello")
+
+    assert isinstance(ref, MessageRef)
+    assert actions.calls_for("send_message")[0].args[:2] == (42, "hello")
+    with pytest.raises(UndeclaredDiscordAction):
+        await actions.fetch_message(ref)
+
+
+@pytest.mark.asyncio
+async def test_fake_interaction_records_responses() -> None:
+    interaction = FakeInteraction(module_name="demo")
+    await interaction.respond("done", ephemeral=True)
+    await interaction.follow_up("more")
+
+    assert interaction.responses[0].content == "done"
+    assert interaction.responses[0].ephemeral is True
+    assert interaction.last.content == "more"
+
+
+def test_fake_service_proxy_closes_with_its_registration() -> None:
+    class Board:
+        def answer(self) -> int:
+            return 42
+
+    registry = FakeServiceRegistry()
+    registration = registry.provide("records.board", 1, Board())
+    proxy = registry.get("records.board", 1, Board)
+
+    assert proxy.answer() == 42
+    registration.close()
+    with pytest.raises(ServiceUnavailable):
+        proxy.answer()
+
+
+@pytest.mark.asyncio
+async def test_memory_storage_runs_scoped_migrations_and_transactions() -> None:
+    async def create(ctx: MigrationContext) -> None:
+        await ctx.connection.execute(f"CREATE TABLE {ctx.table('rows')} (value INTEGER)")
+
+    async with MemoryStorage.open("my-module") as storage:
+        assert storage.table("rows") == '"my_module_rows"'
+        await storage.migrate((("001", create),))
+        async with storage.write_transaction() as connection:
+            await connection.execute('INSERT INTO "my_module_rows" (value) VALUES (7)')
+        cursor = await storage.connection.execute('SELECT value FROM "my_module_rows"')
+        assert await cursor.fetchone() == (7,)