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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kimi-agent-module-api
-Version: 1.2.0
+Version: 2.0.0
 Summary: Stable contracts for community-built assistant modules
 Author: Webhead
 License-Expression: MIT
@@ -39,23 +39,58 @@ group:
 
 ```toml
 [project]
-dependencies = ["kimi-agent-module-api>=1,<2"]
+dependencies = ["kimi-agent-module-api>=2,<3"]
 
 [project.entry-points."kimi_agent.modules"]
 my_module = "my_module_package:SPEC"
 ```
 
+The source must pin the API contract it implements when constructing the
+specification:
+
+```python
+from kimi_agent_module_api import ModuleSpec
+
+SPEC = ModuleSpec(
+    name="my_module",
+    version="0.1.0",
+    create=create,
+    api_version=2,
+)
+```
+
+`api_version` is a required keyword. Keep it as a literal rather than deriving
+it from the installed SDK's `MODULE_API_VERSION`; unchanged module source must
+not silently claim compatibility merely because it was rebuilt with a newer
+SDK.
+
 The [module guide](https://github.com/webhead2oo9/kimi-agent/blob/main/docs/modules.md)
 documents installation, declarations, lifecycle, and every runtime port. The
 [reference module](https://github.com/webhead2oo9/kimi-agent/tree/main/bot/modules/example)
 is a complete, commented example that exercises most ports; start there.
 
 Guild-scoped live command replacement was added in 1.1. Modules using
-`InteractionRouter.replace_guild_commands()` should depend on
-`kimi-agent-module-api>=1.1,<2` and require the host capability
+`InteractionRouter.replace_guild_commands()` should require the host capability
 `discord.guild_commands.v1`.
 
 Version 1.2 adds typed modal forms and a narrow Components V2 layout model. Once a response uses
 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
+Modules using them should require
 `discord.modals.v1` and/or `discord.components_v2.v1`.
+
+Version 1.3 adds cached author classification to message-deletion events:
+`MessageDeleteEvent.author_is_bot` and `MessageBulkDeleteEvent.bot_message_ids`.
+The values remain unknown for messages that were absent from Discord's cache.
+
+Version 2 requires an explicit, source-pinned `ModuleSpec.api_version`, and
+removes the temporary guild-settings legacy flag and module table aliases.
+Modules must use namespaced guild documents and migrate legacy tables to the
+physical names returned by `ctx.storage.table()` before upgrading.
+
+## 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-2.0.0}/README.md

@@ -22,23 +22,58 @@ group:
 
 ```toml
 [project]
-dependencies = ["kimi-agent-module-api>=1,<2"]
+dependencies = ["kimi-agent-module-api>=2,<3"]
 
 [project.entry-points."kimi_agent.modules"]
 my_module = "my_module_package:SPEC"
 ```
 
+The source must pin the API contract it implements when constructing the
+specification:
+
+```python
+from kimi_agent_module_api import ModuleSpec
+
+SPEC = ModuleSpec(
+    name="my_module",
+    version="0.1.0",
+    create=create,
+    api_version=2,
+)
+```
+
+`api_version` is a required keyword. Keep it as a literal rather than deriving
+it from the installed SDK's `MODULE_API_VERSION`; unchanged module source must
+not silently claim compatibility merely because it was rebuilt with a newer
+SDK.
+
 The [module guide](https://github.com/webhead2oo9/kimi-agent/blob/main/docs/modules.md)
 documents installation, declarations, lifecycle, and every runtime port. The
 [reference module](https://github.com/webhead2oo9/kimi-agent/tree/main/bot/modules/example)
 is a complete, commented example that exercises most ports; start there.
 
 Guild-scoped live command replacement was added in 1.1. Modules using
-`InteractionRouter.replace_guild_commands()` should depend on
-`kimi-agent-module-api>=1.1,<2` and require the host capability
+`InteractionRouter.replace_guild_commands()` should require the host capability
 `discord.guild_commands.v1`.
 
 Version 1.2 adds typed modal forms and a narrow Components V2 layout model. Once a response uses
 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
+Modules using them should require
 `discord.modals.v1` and/or `discord.components_v2.v1`.
+
+Version 1.3 adds cached author classification to message-deletion events:
+`MessageDeleteEvent.author_is_bot` and `MessageBulkDeleteEvent.bot_message_ids`.
+The values remain unknown for messages that were absent from Discord's cache.
+
+Version 2 requires an explicit, source-pinned `ModuleSpec.api_version`, and
+removes the temporary guild-settings legacy flag and module table aliases.
+Modules must use namespaced guild documents and migrate legacy tables to the
+physical names returned by `ctx.storage.table()` before upgrading.
+
+## 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-2.0.0}/pyproject.toml

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

@@ -3,23 +3,19 @@
 from __future__ import annotations
 
 from collections.abc import Callable, Mapping, Sequence
-from dataclasses import dataclass, field
+from dataclasses import KW_ONLY, dataclass, field
 from pathlib import Path
 from typing import Any, Protocol, TypeVar
 
 from pydantic_settings import BaseSettings
 
+from kimi_agent_module_api import contracts as _contracts
 from kimi_agent_module_api.contracts import (
     ConfigSnapshot,
     RoleSnapshot,
     render_guild_settings,
-    DiscordActions,
-    EventBus,
-    GuildSettings,
     GuildSettingsSchema,
-    HealthReporter,
     InviteSnapshot,
-    InteractionRouter,
     LayoutGallery,
     LayoutItem,
     LayoutSection,
@@ -27,9 +23,7 @@ from kimi_agent_module_api.contracts import (
     LayoutSeparatorSpacing,
     LayoutText,
     ModalSpec,
-    ModuleHttp,
     ModulePermissions,
-    ModuleStorage,
     OutgoingLayout,
     ScopedModuleMigration,
     ProposalActor,
@@ -37,11 +31,8 @@ from kimi_agent_module_api.contracts import (
     ProposalRef,
     ProposalService,
     ProposalState,
-    Scheduler,
     ServiceDeclaration,
-    ServiceRegistry,
     ServiceRequirement,
-    TrustLookup,
     TextInputSpec,
     TextInputStyle,
 )
@@ -53,7 +44,7 @@ from kimi_agent_module_api.tools import (
 )
 from kimi_agent_module_api.trust import TrustTier
 
-MODULE_API_VERSION = 1
+MODULE_API_VERSION = 2
 MODULE_ENTRYPOINT_GROUP = "kimi_agent.modules"
 # Capabilities every compatible host advertises regardless of configuration.
 BASELINE_CAPABILITIES: frozenset[str] = frozenset({"discord.history.v1", "proposals.v2"})
@@ -82,10 +73,13 @@ class AppModule(Protocol):
 
 @dataclass(frozen=True)
 class ModuleSpec:
+    """A module declaration with an explicit, source-pinned host API version."""
+
     name: str
     version: str
     create: Callable[[ModuleLoadContext], AppModule]
-    api_version: int = MODULE_API_VERSION
+    _: KW_ONLY
+    api_version: int
     dependencies: tuple[str, ...] = ()
     settings: ModuleSettingsDefinition | None = None
     requires_capabilities: tuple[str, ...] = ()
@@ -94,7 +88,6 @@ class ModuleSpec:
     guild_settings: GuildSettingsSchema | None = None
     provides: tuple[ServiceDeclaration, ...] = ()
     consumes: tuple[ServiceRequirement, ...] = ()
-    table_aliases: Mapping[str, str] = field(default_factory=dict)
 
 
 @dataclass(frozen=True)
@@ -138,16 +131,16 @@ class ModuleRuntimeContext:
     is_guild_active: Callable[[int], bool]
     current_config_dir: Callable[[], Path]
     capabilities: ModuleCapabilities
-    events: EventBus
-    scheduler: Scheduler
-    storage: ModuleStorage
-    health: HealthReporter
-    discord: DiscordActions
-    interactions: InteractionRouter
-    http: ModuleHttp
-    services: ServiceRegistry
-    trust: TrustLookup
-    guild_settings: GuildSettings | None = None
+    events: _contracts.EventBus
+    scheduler: _contracts.Scheduler
+    storage: _contracts.ModuleStorage
+    health: _contracts.HealthReporter
+    discord: _contracts.DiscordActions
+    interactions: _contracts.InteractionRouter
+    http: _contracts.ModuleHttp
+    services: _contracts.ServiceRegistry
+    trust: _contracts.TrustLookup
+    guild_settings: _contracts.GuildSettings | None = None
     proposals: ProposalService | None = None
     raw_bot: Any = None
     raw_storage: Any = None

{kimi_agent_module_api-1.2.0 → kimi_agent_module_api-2.0.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):
@@ -1255,7 +1466,6 @@ class GuildSettingsSnapshot:
     valid: bool
     errors: tuple[str, ...]
     revision: str
-    legacy: bool = False
 
 
 class GuildSettings(Protocol):

{kimi_agent_module_api-1.2.0 → kimi_agent_module_api-2.0.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)