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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kimi-agent-module-api
-Version: 1.3.0
+Version: 2.1.0
 Summary: Stable contracts for community-built assistant modules
 Author: Webhead
 License-Expression: MIT
@@ -39,31 +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
+Modules using guild-scoped live command replacement through
+`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
+The SDK provides 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:
+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.
+
+Modules use namespaced guild documents and the physical table names returned
+by `ctx.storage.table()`.
+
 ## Testing the SDK
 
 From this package directory, run its tests without installing the Kimi application:

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

@@ -22,31 +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
+Modules using guild-scoped live command replacement through
+`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
+The SDK provides 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:
+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.
+
+Modules use namespaced guild documents and the physical table names returned
+by `ctx.storage.table()`.
+
 ## Testing the SDK
 
 From this package directory, run its tests without installing the Kimi application:

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

@@ -1,6 +1,6 @@
 [project]
 name = "kimi-agent-module-api"
-version = "1.3.0"
+version = "2.1.0"
 description = "Stable contracts for community-built assistant modules"
 requires-python = ">=3.14"
 authors = [{ name = "Webhead" }]

{kimi_agent_module_api-1.3.0 → kimi_agent_module_api-2.1.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.3.0 → kimi_agent_module_api-2.1.0}/src/kimi_agent_module_api/contracts.py

@@ -1466,7 +1466,6 @@ class GuildSettingsSnapshot:
     valid: bool
     errors: tuple[str, ...]
     revision: str
-    legacy: bool = False
 
 
 class GuildSettings(Protocol):

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

@@ -29,6 +29,9 @@ class ModuleToolContext:
     trust_tier: TrustTier
     # Operator per-tool configuration from ``<CONFIG_DIR>/tools/<tool>.md``.
     tool_configs: Mapping[str, Mapping[str, Any]] = field(default_factory=dict)
+    # Discord message that initiated this model turn. It is absent for personal
+    # app commands and other surfaces that are not rooted in a Discord message.
+    trigger_discord_message_id: int | None = None
 
 
 type ModuleToolHandler = Callable[[dict[str, Any], ModuleToolContext], Coroutine[Any, Any, str]]

{kimi_agent_module_api-1.3.0 → kimi_agent_module_api-2.1.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.3.0
+Version: 2.1.0
 Summary: Stable contracts for community-built assistant modules
 Author: Webhead
 License-Expression: MIT
@@ -39,31 +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
+Modules using guild-scoped live command replacement through
+`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
+The SDK provides 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:
+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.
+
+Modules use namespaced guild documents and the physical table names returned
+by `ctx.storage.table()`.
+
 ## Testing the SDK
 
 From this package directory, run its tests without installing the Kimi application:

{kimi_agent_module_api-1.3.0 → kimi_agent_module_api-2.1.0}/tests/test_contracts.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from importlib.metadata import version
 import dataclasses
 from typing import Any
 
@@ -11,6 +12,7 @@ from pydantic_settings import BaseSettings
 from kimi_agent_module_api import (
     BASELINE_CAPABILITIES,
     MODULE_API_VERSION,
+    AppModule,
     ModuleCapabilities,
     ModuleLoadContext,
     ModulePermissions,
@@ -57,15 +59,20 @@ class OtherSettings(BaseSettings):
 
 
 def _spec(name: str = "demo") -> ModuleSpec:
-    def create(_ctx: ModuleLoadContext) -> object:
+    def create(_ctx: ModuleLoadContext) -> AppModule:
         raise AssertionError("not called")
 
-    return ModuleSpec(name=name, version="1.0.0", create=create)  # type: ignore[arg-type]
+    return ModuleSpec(
+        name=name,
+        version="1.0.0",
+        create=create,
+        api_version=MODULE_API_VERSION,
+    )
 
 
 def test_spec_and_runtime_context_keep_stable_defaults() -> None:
     spec = _spec()
-    assert spec.api_version == MODULE_API_VERSION == 1
+    assert spec.api_version == MODULE_API_VERSION == 2
     assert spec.permissions == ModulePermissions()
     assert spec.dependencies == ()
     required = {
@@ -76,6 +83,20 @@ def test_spec_and_runtime_context_keep_stable_defaults() -> None:
     assert {"events", "scheduler", "storage", "discord", "interactions", "services"} <= required
 
 
+def test_distribution_version_includes_trigger_message_contract() -> None:
+    assert version("kimi-agent-module-api") == "2.1.0"
+
+
+def test_spec_requires_an_explicit_keyword_api_version() -> None:
+    def create(_ctx: ModuleLoadContext) -> AppModule:
+        raise AssertionError("not called")
+
+    with pytest.raises(TypeError, match="required keyword-only argument: 'api_version'"):
+        ModuleSpec("demo", "1.0.0", create)  # type: ignore[call-arg]
+    with pytest.raises(TypeError, match="positional arguments"):
+        ModuleSpec("demo", "1.0.0", create, MODULE_API_VERSION)  # type: ignore[call-arg]
+
+
 def test_load_context_exercises_public_create_helpers() -> None:
     settings = DemoSettings(greeting="hi")
     context, recorder = load_context(settings)

{kimi_agent_module_api-1.3.0 → kimi_agent_module_api-2.1.0}/tests/test_public_api.py

@@ -17,6 +17,22 @@ def test_public_exports_resolve() -> None:
     assert all(getattr(api, name, None) is not None for name in api.__all__)
 
 
+def test_contract_ports_are_not_accidental_package_root_exports() -> None:
+    hidden_ports = {
+        "DiscordActions",
+        "EventBus",
+        "GuildSettings",
+        "HealthReporter",
+        "InteractionRouter",
+        "ModuleHttp",
+        "ModuleStorage",
+        "Scheduler",
+        "ServiceRegistry",
+        "TrustLookup",
+    }
+    assert hidden_ports.isdisjoint(vars(api))
+
+
 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