langbot-plugin 0.4.2b4__tar.gz → 0.5.0a2__tar.gz

langbot_plugin-0.5.0a2/.github/workflows/cla.yml

@@ -0,0 +1,41 @@
+name: "CLA Assistant"
+on:
+  issue_comment:
+    types: [created]
+  pull_request_target:
+    types: [opened, closed, synchronize, reopened]
+
+permissions:
+  actions: write          # re-run the failed CLA check after signing
+  contents: read          # signatures are stored in the remote langbot-app/cla repo
+  pull-requests: write    # post guidance comments, lock PR after merge
+  statuses: write         # set the commit status
+
+jobs:
+  CLAAssistant:
+    runs-on: ubuntu-latest
+    steps:
+      - name: "CLA Assistant"
+        if: (github.event.comment.body == 'recheck' || github.event.comment.body == 'I have read the CLA Document and I hereby sign the CLA') || github.event_name == 'pull_request_target'
+        # Upstream repo was archived in 2026-03; pin to the v2.6.1 commit SHA.
+        uses: contributor-assistant/github-action@ca4a40a7d1004f18d9960b404b97e5f30a505a08 # v2.6.1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # repo-scope PAT with write access to langbot-app/cla
+          PERSONAL_ACCESS_TOKEN: ${{ secrets.CLA_PAT }}
+        with:
+          path-to-document: 'https://github.com/langbot-app/LangBot/blob/master/CLA.md'
+          remote-organization-name: 'langbot-app'
+          remote-repository-name: 'cla'
+          path-to-signatures: 'signatures/version1/cla.json'
+          branch: 'main'
+          allowlist: 'dependabot[bot],github-actions[bot],devin-ai-integration[bot],Copilot,renovate[bot],bot*'
+          custom-notsigned-prcomment: |
+            Thank you for your contribution! :heart: Before we can merge this pull request, we need you to sign the [LangBot Contributor License Agreement (CLA)](https://github.com/langbot-app/LangBot/blob/master/CLA.md). You keep full copyright of your code — the CLA grants us a license to use and distribute your contribution. Signing takes 10 seconds and covers all repositories in this organization, permanently.
+
+            感谢您的贡献！合并前请阅读并签署[贡献者许可协议（CLA）](https://github.com/langbot-app/LangBot/blob/master/CLA.md)。您保留代码的全部版权，签署仅需回复下方指定内容，一次签署对本组织全部仓库永久有效。
+          custom-allsigned-prcomment: 'All contributors have signed the CLA. :white_check_mark: 所有贡献者均已签署 CLA。'
+          lock-pullrequest-aftermerge: true
+        # SECURITY: this workflow runs on pull_request_target (it holds secrets and has
+        # write access to the base repository). NEVER add an actions/checkout step that
+        # checks out the PR's code here.

{langbot_plugin-0.4.2b4 → langbot_plugin-0.5.0a2}/AGENTS.md

@@ -816,34 +816,49 @@ Encapsulates plugin instance with:
 
 ### Communication Protocol (`runtime/io/`)
 
-**Action-Based Protocol**:
-- Bidirectional JSON messages
-- Request-response with sequence IDs
-- Streaming support via chunk status
-- File transfer (16KB chunks)
-
-**Action Structure**:
+This protocol is **JSON-RPC 2.0 in all but field names** — a bidirectional, action-based
+RPC carried over a single connection. It is the same shape the Language Server Protocol
+(LSP) and the Model Context Protocol (MCP) use: JSON-RPC 2.0 over stdio / WebSocket, with
+either peer free to initiate calls. We did not adopt the spec verbatim, but the semantics
+map 1:1, and it is useful to think of it that way:
+
+| Our field (`entities/io`)  | JSON-RPC 2.0             | Meaning |
+|----------------------------|--------------------------|---------|
+| `seq_id`                   | `id`                     | Correlates a response back to its request |
+| `action`                   | `method`                 | Which action to invoke |
+| `data` (in a request)      | `params`                 | Call arguments |
+| `data` (in a response)     | `result`                 | Return value (when `code == 0`) |
+| `code` + `message`         | `error.{code,message}`   | `code == 0` is success; non-zero carries the failure in `message` |
+| `chunk_status`             | (MCP-style streaming ext.) | `continue` per chunk, `end` closes a streamed response |
+
+Both peers share one connection and may call each other's actions. Requests and responses
+are told apart by shape: a message carrying `action` is an inbound request, one carrying
+`code` is a response. Each side allocates `seq_id` from its own incrementing counter, so the
+two id spaces are dispatched independently and never collide.
+
+**Request** (`ActionRequest`, `entities/io/req.py`):
 ```json
-{
-  "action": "action_name",
-  "seq": 12345,
-  "data": {...},
-  "chunk_status": "start|continue|end"
-}
+{ "seq_id": 12345, "action": "action_name", "data": {} }
 ```
 
-**Response Structure**:
+**Response** (`ActionResponse`, `entities/io/resp.py`):
 ```json
-{
-  "seq": 12345,
-  "ok": true,
-  "data": {...}
-}
+{ "seq_id": 12345, "code": 0, "message": "success", "data": {}, "chunk_status": "continue" }
 ```
 
-**Transport Implementations**:
-- `StdioHandler`: stdin/stdout communication
-- `WebSocketHandler`: WebSocket client/server
+- `code == 0` → success, payload in `data`; non-zero → error, human-readable text in `message`.
+- **Streaming**: the responder emits N chunks with `chunk_status: "continue"`, then a final
+  `chunk_status: "end"` (consumed by `Handler.call_action_generator`).
+- **File transfer**: large blobs travel as `__file_chunk` actions — 16KB base64 chunks,
+  reassembled to `data/temp/lbp/<file_key>` on the receiving side.
+
+**Core engine**: `runtime/io/handler.py` (`Handler`) owns `seq_id` allocation, the
+`resp_waiters` (single response) and `resp_queues` (streamed response) correlation maps,
+timeouts, and the receive loop (`Handler.run`).
+
+**Transport Implementations** (`Connection` subclasses, `runtime/io/connections/`):
+- `stdio.py`: stdin/stdout — default for subprocess (personal / lightweight) plugins
+- `ws.py`: WebSocket — for containerized / remote plugin deployments
 
 ## CLI Tools
 

langbot_plugin-0.5.0a2/CONTRIBUTING.md

@@ -0,0 +1,15 @@
+# Contributing to langbot-plugin-sdk
+
+Thank you for your interest in contributing! For general contribution guidelines, please refer to the [LangBot contribution guide](https://github.com/langbot-app/LangBot/blob/master/CONTRIBUTING.md).
+
+感谢您有意参与贡献！通用贡献指引请参阅 [LangBot 贡献指南](https://github.com/langbot-app/LangBot/blob/master/CONTRIBUTING.md)。
+
+## Contributor License Agreement (CLA)
+
+To protect the project and every contributor, we require all code contributors to sign the [LangBot Contributor License Agreement](https://github.com/langbot-app/LangBot/blob/master/CLA.md). You keep full copyright of your code — the CLA only grants us a license to use and distribute your contribution.
+
+Signing takes 10 seconds: when you open your first PR, a bot will guide you to reply with a single comment. One signature covers all repositories in this organization, permanently.
+
+为了保护项目和每一位贡献者，我们要求所有代码贡献者签署 [LangBot 贡献者许可协议（CLA）](https://github.com/langbot-app/LangBot/blob/master/CLA.md)。您保留自己代码的全部版权，CLA 仅授予项目使用、分发您贡献的许可。
+
+签署只需 10 秒：首次提交 PR 时，机器人会自动评论提示，按提示回复一句话即完成签署，此后对本组织所有仓库永久有效。

{langbot_plugin-0.4.2b4 → langbot_plugin-0.5.0a2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langbot-plugin
-Version: 0.4.2b4
+Version: 0.5.0a2
 Summary: This package contains the SDK, CLI for building plugins for LangBot, plus the runtime for hosting LangBot plugins
 Project-URL: Homepage, https://langbot.app
 Project-URL: Repository, https://github.com/langbot-app/langbot-plugin-sdk
@@ -14,6 +14,7 @@ Requires-Dist: dotenv>=0.9.9
 Requires-Dist: e2b>=2.15
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: jinja2>=3.1.6
+Requires-Dist: packaging>=24.0
 Requires-Dist: pip>=25.2
 Requires-Dist: pydantic-settings>=2.10.1
 Requires-Dist: pydantic>=2.11.5

{langbot_plugin-0.4.2b4 → langbot_plugin-0.5.0a2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "langbot-plugin"
-version = "0.4.2b4"
+version = "0.5.0a2"
 description = "This package contains the SDK, CLI for building plugins for LangBot, plus the runtime for hosting LangBot plugins"
 readme = "README.md"
 authors = [
@@ -14,6 +14,7 @@ dependencies = [
     "e2b>=2.15",
     "httpx>=0.28.1",
     "jinja2>=3.1.6",
+    "packaging>=24.0",
     "pip>=25.2",
     "pydantic>=2.11.5",
     "pydantic-settings>=2.10.1",

langbot_plugin-0.5.0a2/src/langbot_plugin/api/definition/abstract/platform/adapter.py

@@ -0,0 +1,386 @@
+from __future__ import annotations
+
+# Platform adapter abstract base classes
+import typing
+import abc
+import pydantic
+
+import langbot_plugin.api.entities.builtin.platform.message as platform_message
+import langbot_plugin.api.entities.builtin.platform.events as platform_events
+import langbot_plugin.api.entities.builtin.platform.entities as platform_entities
+import langbot_plugin.api.definition.abstract.platform.event_logger as abstract_platform_logger
+from langbot_plugin.api.entities.builtin.platform.errors import NotSupportedError
+
+
+class AbstractMessagePlatformAdapter(pydantic.BaseModel, metaclass=abc.ABCMeta):
+    """Message platform adapter base class."""
+
+    bot_account_id: str = pydantic.Field(default="")
+    """Bot account ID, should be set during initialization."""
+
+    config: dict
+
+    logger: abstract_platform_logger.AbstractEventLogger = pydantic.Field(exclude=True)
+
+    class Config:
+        arbitrary_types_allowed = True
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+    @abc.abstractmethod
+    async def send_message(
+        self, target_type: str, target_id: str, message: platform_message.MessageChain
+    ):
+        """Send a message proactively.
+
+        Args:
+            target_type: Target type, 'person' or 'group'.
+            target_id: Target ID.
+            message: Message chain to send.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def reply_message(
+        self,
+        message_source: platform_events.MessageEvent,
+        message: platform_message.MessageChain,
+        quote_origin: bool = False,
+    ):
+        """Reply to a message.
+
+        Args:
+            message_source: The source message event to reply to.
+            message: Message chain to send.
+            quote_origin: Whether to quote the original message. Defaults to False.
+        """
+        raise NotImplementedError
+
+    async def reply_message_chunk(
+        self,
+        message_source: platform_events.MessageEvent,
+        bot_message: dict,
+        message: platform_message.MessageChain,
+        quote_origin: bool = False,
+        is_final: bool = False,
+    ):
+        """Reply to a message (streaming output).
+
+        Args:
+            message_source: The source message event.
+            bot_message: Bot message context.
+            message: Message chain to send.
+            quote_origin: Whether to quote the original message. Defaults to False.
+            is_final: Whether this is the final chunk. Defaults to False.
+        """
+        raise NotImplementedError
+
+    async def create_message_card(
+        self, message_id: typing.Type[str, int], event: platform_events.MessageEvent
+    ) -> bool:
+        """Create a card message placeholder for streaming.
+
+        Args:
+            message_id: Message ID.
+            event: The source message event.
+        """
+        return False
+
+    async def is_muted(self, group_id: int) -> bool:
+        """Check if the bot is muted in the specified group."""
+        return False
+
+    @abc.abstractmethod
+    def register_listener(
+        self,
+        event_type: typing.Type[platform_events.Event],
+        callback: typing.Callable[
+            [platform_events.Event, AbstractMessagePlatformAdapter], None
+        ],
+    ):
+        """Register an event listener.
+
+        Args:
+            event_type: The event type to listen for.
+            callback: Callback function that receives the event and adapter.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def unregister_listener(
+        self,
+        event_type: typing.Type[platform_events.Event],
+        callback: typing.Callable[
+            [platform_events.Event, AbstractMessagePlatformAdapter], None
+        ],
+    ):
+        """Unregister an event listener.
+
+        Args:
+            event_type: The event type to stop listening for.
+            callback: The callback to remove.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def run_async(self):
+        """Start the adapter asynchronously."""
+        raise NotImplementedError
+
+    async def is_stream_output_supported(self) -> bool:
+        """Check if streaming output is supported."""
+        return False
+
+    @abc.abstractmethod
+    async def kill(self) -> bool:
+        """Shut down the adapter.
+
+        Returns:
+            True if shutdown succeeded. On hot-reload, returning False
+            prevents the underlying MessageSource from being reloaded.
+        """
+        raise NotImplementedError
+
+
+class AbstractPlatformAdapter(AbstractMessagePlatformAdapter):
+    """Platform adapter base class (EBA version).
+
+    Compared to the legacy AbstractMessagePlatformAdapter:
+    - Adds universal API methods (edit_message, delete_message, get_group_info, etc.)
+    - Adds pass-through API (call_platform_api)
+    - Adds capability declaration (get_supported_events, get_supported_apis)
+    - Event listeners support all event types, not just message events
+    """
+
+    # ---- Capability Declaration ----
+
+    def get_supported_events(self) -> list[str]:
+        """Return the list of event types supported by this adapter."""
+        return ["message.received"]
+
+    def get_supported_apis(self) -> list[str]:
+        """Return the list of APIs supported by this adapter."""
+        return ["send_message", "reply_message"]
+
+    # ---- Optional Message Methods ----
+
+    async def edit_message(
+        self,
+        chat_type: str,
+        chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+        new_content: platform_message.MessageChain,
+    ) -> None:
+        """Edit a previously sent message."""
+        raise NotSupportedError("edit_message")
+
+    async def delete_message(
+        self,
+        chat_type: str,
+        chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+    ) -> None:
+        """Delete / recall a message."""
+        raise NotSupportedError("delete_message")
+
+    async def forward_message(
+        self,
+        from_chat_type: str,
+        from_chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+        to_chat_type: str,
+        to_chat_id: typing.Union[int, str],
+    ) -> platform_events.MessageResult:
+        """Forward a message."""
+        raise NotSupportedError("forward_message")
+
+    async def get_message(
+        self,
+        chat_type: str,
+        chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+    ) -> platform_events.MessageReceivedEvent:
+        """Retrieve a specific message."""
+        raise NotSupportedError("get_message")
+
+    # ---- Optional Group Methods ----
+
+    async def get_group_info(
+        self,
+        group_id: typing.Union[int, str],
+    ) -> platform_entities.UserGroup:
+        """Get group information."""
+        raise NotSupportedError("get_group_info")
+
+    async def get_group_list(self) -> list[platform_entities.UserGroup]:
+        """Get the list of groups the bot has joined."""
+        raise NotSupportedError("get_group_list")
+
+    async def get_group_member_list(
+        self,
+        group_id: typing.Union[int, str],
+    ) -> list[platform_entities.UserGroupMember]:
+        """Get the member list of a group."""
+        raise NotSupportedError("get_group_member_list")
+
+    async def get_group_member_info(
+        self,
+        group_id: typing.Union[int, str],
+        user_id: typing.Union[int, str],
+    ) -> platform_entities.UserGroupMember:
+        """Get information about a specific group member."""
+        raise NotSupportedError("get_group_member_info")
+
+    async def set_group_name(
+        self,
+        group_id: typing.Union[int, str],
+        name: str,
+    ) -> None:
+        """Set the group name."""
+        raise NotSupportedError("set_group_name")
+
+    async def mute_member(
+        self,
+        group_id: typing.Union[int, str],
+        user_id: typing.Union[int, str],
+        duration: int = 0,
+    ) -> None:
+        """Mute a group member."""
+        raise NotSupportedError("mute_member")
+
+    async def unmute_member(
+        self,
+        group_id: typing.Union[int, str],
+        user_id: typing.Union[int, str],
+    ) -> None:
+        """Unmute a group member."""
+        raise NotSupportedError("unmute_member")
+
+    async def kick_member(
+        self,
+        group_id: typing.Union[int, str],
+        user_id: typing.Union[int, str],
+    ) -> None:
+        """Kick a member from the group."""
+        raise NotSupportedError("kick_member")
+
+    async def leave_group(
+        self,
+        group_id: typing.Union[int, str],
+    ) -> None:
+        """Make the bot leave a group."""
+        raise NotSupportedError("leave_group")
+
+    # ---- Optional User Methods ----
+
+    async def get_user_info(
+        self,
+        user_id: typing.Union[int, str],
+    ) -> platform_entities.User:
+        """Get user information."""
+        raise NotSupportedError("get_user_info")
+
+    async def get_friend_list(self) -> list[platform_entities.User]:
+        """Get the bot's friend list."""
+        raise NotSupportedError("get_friend_list")
+
+    async def approve_friend_request(
+        self,
+        request_id: typing.Union[int, str],
+        approve: bool = True,
+        remark: typing.Optional[str] = None,
+    ) -> None:
+        """Handle a friend request."""
+        raise NotSupportedError("approve_friend_request")
+
+    async def approve_group_invite(
+        self,
+        request_id: typing.Union[int, str],
+        approve: bool = True,
+    ) -> None:
+        """Handle a group invitation."""
+        raise NotSupportedError("approve_group_invite")
+
+    # ---- Optional Media Methods ----
+
+    async def upload_file(
+        self,
+        file_data: bytes,
+        filename: str,
+    ) -> str:
+        """Upload a file. Returns file ID or URL."""
+        raise NotSupportedError("upload_file")
+
+    async def get_file_url(
+        self,
+        file_id: str,
+    ) -> str:
+        """Get a file download URL."""
+        raise NotSupportedError("get_file_url")
+
+    # ---- Pass-through API ----
+
+    async def call_platform_api(
+        self,
+        action: str,
+        params: dict = {},
+    ) -> dict:
+        """Call an adapter-specific platform API."""
+        raise NotSupportedError("call_platform_api")
+
+
+class AbstractMessageConverter:
+    """Message chain converter base class."""
+
+    @staticmethod
+    def yiri2target(message_chain: platform_message.MessageChain):
+        """Convert internal message chain to platform-specific format.
+
+        Args:
+            message_chain: Internal message chain.
+
+        Returns:
+            Platform-specific message representation.
+        """
+        raise NotImplementedError
+
+    @staticmethod
+    def target2yiri(message_chain: typing.Any) -> platform_message.MessageChain:
+        """Convert platform-specific message to internal message chain.
+
+        Args:
+            message_chain: Platform-specific message.
+
+        Returns:
+            Internal message chain.
+        """
+        raise NotImplementedError
+
+
+class AbstractEventConverter:
+    """Event converter base class."""
+
+    @staticmethod
+    def yiri2target(event: typing.Type[platform_events.Event]):
+        """Convert internal event to platform-specific event.
+
+        Args:
+            event: Internal event.
+
+        Returns:
+            Platform-specific event.
+        """
+        raise NotImplementedError
+
+    @staticmethod
+    def target2yiri(event: typing.Any) -> platform_events.Event:
+        """Convert platform-specific event to internal event.
+
+        Args:
+            event: Platform-specific event.
+
+        Returns:
+            Internal event.
+        """
+        raise NotImplementedError