langbot-plugin 0.4.4__tar.gz → 0.4.6__tar.gz

langbot_plugin-0.4.6/.github/workflows/test.yml

@@ -0,0 +1,93 @@
+name: Tests
+
+on:
+  push:
+    branches:
+      - main
+      - test-build
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  unit-tests:
+    name: Unit Tests
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+      - name: Set up Python
+        run: uv python install ${{ matrix.python-version }}
+      - name: Run tests with coverage
+        run: |
+          uv run --python ${{ matrix.python-version }} pytest \
+            --ignore=tests/packaging \
+            --cov=langbot_plugin \
+            --cov-report=term-missing \
+            --cov-fail-under=84
+
+  test-lint:
+    name: Lint and Format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+      - name: Ruff check
+        run: uv run ruff check src tests --output-format=concise
+      - name: Ruff format check
+        run: uv run ruff format --check src tests
+
+  package-smoke:
+    name: Package Smoke
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+      - name: Set up Python
+        run: uv python install 3.12
+      - name: Installed wheel CLI smoke
+        run: uv run --python 3.12 pytest -q tests/packaging
+
+  scoped-type-check:
+    name: Scoped Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+      - name: Mypy stable protocol modules
+        run: |
+          uv run mypy \
+            src/langbot_plugin/entities/io \
+            src/langbot_plugin/runtime/plugin/logbuffer.py \
+            src/langbot_plugin/utils/platform.py
+
+  action-consistency:
+    name: Action Protocol Consistency
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Check action enum / proxy / handler consistency
+        run: python scripts/check_action_consistency.py

langbot_plugin-0.4.6/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: langbot-plugin
+Version: 0.4.6
+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
+Project-URL: Issues, https://github.com/langbot-app/langbot-plugin-sdk/issues
+Author-email: Junyan Qin <rockchinq@gmail.com>
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: aiofiles>=24.1.0
+Requires-Dist: aiohttp>=3.9.0
+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
+Requires-Dist: pytest>=8.4.0
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: textual>=3.2.0
+Requires-Dist: types-aiofiles>=24.1.0.20250516
+Requires-Dist: types-pyyaml>=6.0.12.20250516
+Requires-Dist: watchdog>=6.0.0
+Requires-Dist: websockets>=15.0.1
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<h1>LangBot Plugin Infra</h1>
+
+<p>Plugin SDK, CLI, Plugin Runtime and Box sandbox runtime for <a href="https://github.com/langbot-app/LangBot">LangBot</a>.</p>
+
+[![PyPI](https://img.shields.io/pypi/v/langbot-plugin)](https://pypi.org/project/langbot-plugin/)
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)
+
+English / [简体中文](README_CN.md)
+
+[Documentation](https://docs.langbot.app/zh/plugin/dev/tutor) ·
+[Plugin Market](https://space.langbot.app) ·
+[LangBot](https://github.com/langbot-app/LangBot)
+
+</div>
+
+## Overview
+
+This repository is the shared infrastructure powering LangBot's plugin and
+sandbox subsystems. It is published to PyPI as the single
+[`langbot-plugin`](https://pypi.org/project/langbot-plugin/) package and ships
+three things:
+
+- **Plugin SDK & CLI** (`lbp`) — Python APIs, base classes and the `lbp`
+  command for scaffolding, building, debugging and publishing plugins.
+- **Plugin Runtime** (`lbp rt`) — the host process that discovers, installs and
+  runs plugins, bridging them to LangBot over stdio or WebSocket.
+- **Box Runtime** (`lbp box`) — the code-sandbox service backing LangBot's Box
+  subsystem, executing untrusted code via Docker / nsjail / E2B backends.
+
+LangBot depends on this package as the pinned `langbot-plugin==<x.y.z>` in its
+`pyproject.toml`; the canonical version lives in this repo's `pyproject.toml`.
+
+> The **Runtime** component (`src/langbot_plugin/runtime/`) is licensed
+> separately under **AGPL**; everything else in this repository is **Apache 2.0**.
+> See [`src/langbot_plugin/runtime/README.md`](src/langbot_plugin/runtime/README.md).
+
+## Install
+
+```bash
+pip install langbot-plugin
+# or, recommended
+uv tool install langbot-plugin
+
+lbp --help
+```
+
+## CLI at a glance
+
+| Command | Purpose |
+| --- | --- |
+| `lbp init <name>` | Scaffold a new plugin project |
+| `lbp comp <Type>` | Generate a component (Command / Tool / EventListener / KnowledgeEngine / Parser / Page) |
+| `lbp run` | Run / remote-debug a plugin against a running LangBot |
+| `lbp build` | Package the plugin into a distributable zip |
+| `lbp publish` | Publish to the LangBot Plugin Market |
+| `lbp login` / `lbp logout` | Authenticate with your LangBot account |
+| `lbp rt` | Launch a standalone Plugin Runtime (control `5400`, debug `5401`) |
+| `lbp box` | Launch a standalone Box sandbox runtime (default port `5410`) |
+| `lbp ver` | Print the CLI / package version |
+
+## Component types
+
+Plugins extend LangBot through six component types, scaffolded with
+`lbp comp <Type>`:
+
+- **Command** — user-triggered actions (e.g. `!weather tokyo`)
+- **Tool** — LLM-callable functions for AI agents
+- **EventListener** — handlers for message-pipeline events
+- **KnowledgeEngine** — custom knowledge-base retrieval for RAG
+- **Parser** — custom message / content parsing
+- **Page** — custom web page embedded in the LangBot admin panel
+
+## Documentation
+
+- Plugin development tutorial — https://docs.langbot.app/zh/plugin/dev/tutor
+- Debugging the Runtime / CLI / SDK — https://docs.langbot.app/zh/develop/plugin-runtime
+- Dev environment setup — https://docs.langbot.app/zh/develop/dev-config
+
+## License
+
+Apache 2.0, except the Plugin Runtime (`src/langbot_plugin/runtime/`) which is
+AGPL. See [LICENSE](LICENSE) and the
+[Runtime README](src/langbot_plugin/runtime/README.md).

langbot_plugin-0.4.6/README.md

@@ -0,0 +1,86 @@
+<div align="center">
+
+<h1>LangBot Plugin Infra</h1>
+
+<p>Plugin SDK, CLI, Plugin Runtime and Box sandbox runtime for <a href="https://github.com/langbot-app/LangBot">LangBot</a>.</p>
+
+[![PyPI](https://img.shields.io/pypi/v/langbot-plugin)](https://pypi.org/project/langbot-plugin/)
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)
+
+English / [简体中文](README_CN.md)
+
+[Documentation](https://docs.langbot.app/zh/plugin/dev/tutor) ·
+[Plugin Market](https://space.langbot.app) ·
+[LangBot](https://github.com/langbot-app/LangBot)
+
+</div>
+
+## Overview
+
+This repository is the shared infrastructure powering LangBot's plugin and
+sandbox subsystems. It is published to PyPI as the single
+[`langbot-plugin`](https://pypi.org/project/langbot-plugin/) package and ships
+three things:
+
+- **Plugin SDK & CLI** (`lbp`) — Python APIs, base classes and the `lbp`
+  command for scaffolding, building, debugging and publishing plugins.
+- **Plugin Runtime** (`lbp rt`) — the host process that discovers, installs and
+  runs plugins, bridging them to LangBot over stdio or WebSocket.
+- **Box Runtime** (`lbp box`) — the code-sandbox service backing LangBot's Box
+  subsystem, executing untrusted code via Docker / nsjail / E2B backends.
+
+LangBot depends on this package as the pinned `langbot-plugin==<x.y.z>` in its
+`pyproject.toml`; the canonical version lives in this repo's `pyproject.toml`.
+
+> The **Runtime** component (`src/langbot_plugin/runtime/`) is licensed
+> separately under **AGPL**; everything else in this repository is **Apache 2.0**.
+> See [`src/langbot_plugin/runtime/README.md`](src/langbot_plugin/runtime/README.md).
+
+## Install
+
+```bash
+pip install langbot-plugin
+# or, recommended
+uv tool install langbot-plugin
+
+lbp --help
+```
+
+## CLI at a glance
+
+| Command | Purpose |
+| --- | --- |
+| `lbp init <name>` | Scaffold a new plugin project |
+| `lbp comp <Type>` | Generate a component (Command / Tool / EventListener / KnowledgeEngine / Parser / Page) |
+| `lbp run` | Run / remote-debug a plugin against a running LangBot |
+| `lbp build` | Package the plugin into a distributable zip |
+| `lbp publish` | Publish to the LangBot Plugin Market |
+| `lbp login` / `lbp logout` | Authenticate with your LangBot account |
+| `lbp rt` | Launch a standalone Plugin Runtime (control `5400`, debug `5401`) |
+| `lbp box` | Launch a standalone Box sandbox runtime (default port `5410`) |
+| `lbp ver` | Print the CLI / package version |
+
+## Component types
+
+Plugins extend LangBot through six component types, scaffolded with
+`lbp comp <Type>`:
+
+- **Command** — user-triggered actions (e.g. `!weather tokyo`)
+- **Tool** — LLM-callable functions for AI agents
+- **EventListener** — handlers for message-pipeline events
+- **KnowledgeEngine** — custom knowledge-base retrieval for RAG
+- **Parser** — custom message / content parsing
+- **Page** — custom web page embedded in the LangBot admin panel
+
+## Documentation
+
+- Plugin development tutorial — https://docs.langbot.app/zh/plugin/dev/tutor
+- Debugging the Runtime / CLI / SDK — https://docs.langbot.app/zh/develop/plugin-runtime
+- Dev environment setup — https://docs.langbot.app/zh/develop/dev-config
+
+## License
+
+Apache 2.0, except the Plugin Runtime (`src/langbot_plugin/runtime/`) which is
+AGPL. See [LICENSE](LICENSE) and the
+[Runtime README](src/langbot_plugin/runtime/README.md).

langbot_plugin-0.4.6/README_CN.md

@@ -0,0 +1,83 @@
+<div align="center">
+
+<h1>LangBot Plugin Infra</h1>
+
+<p>为 <a href="https://github.com/langbot-app/LangBot">LangBot</a> 提供插件 SDK、CLI、插件运行时与 Box 代码沙箱运行时。</p>
+
+[![PyPI](https://img.shields.io/pypi/v/langbot-plugin)](https://pypi.org/project/langbot-plugin/)
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)
+
+[English](README.md) / 简体中文
+
+[文档](https://docs.langbot.app/zh/plugin/dev/tutor) ·
+[插件市场](https://space.langbot.app) ·
+[LangBot](https://github.com/langbot-app/LangBot)
+
+</div>
+
+## 简介
+
+此仓库是支撑 LangBot **插件系统**与**代码沙箱**的共享基础设施，以单一的
+[`langbot-plugin`](https://pypi.org/project/langbot-plugin/) 包发布到 PyPI，包含三部分：
+
+- **插件 SDK 与 CLI**（`lbp`）—— 插件开发的 Python API、基类，以及用于脚手架、
+  构建、调试和发布插件的 `lbp` 命令。
+- **插件运行时**（`lbp rt`）—— 负责发现、安装并运行插件的宿主进程，通过 stdio
+  或 WebSocket 与 LangBot 通信。
+- **Box 运行时**（`lbp box`）—— 支撑 LangBot Box 子系统的代码沙箱服务，通过
+  Docker / nsjail / E2B 后端执行不受信任的代码。
+
+LangBot 通过 `pyproject.toml` 中固定的 `langbot-plugin==<x.y.z>` 依赖此包；
+版本号以本仓库的 `pyproject.toml` 为准。
+
+> **运行时**组件（`src/langbot_plugin/runtime/`）单独采用 **AGPL** 许可证，
+> 本仓库其余部分采用 **Apache 2.0**，详见
+> [`src/langbot_plugin/runtime/README.md`](src/langbot_plugin/runtime/README.md)。
+
+## 安装
+
+```bash
+pip install langbot-plugin
+# 或（推荐）
+uv tool install langbot-plugin
+
+lbp --help
+```
+
+## CLI 速览
+
+| 命令 | 作用 |
+| --- | --- |
+| `lbp init <name>` | 初始化一个插件项目 |
+| `lbp comp <Type>` | 生成组件（Command / Tool / EventListener / KnowledgeEngine / Parser / Page） |
+| `lbp run` | 针对运行中的 LangBot 运行 / 远程调试插件 |
+| `lbp build` | 将插件打包为可分发的 zip |
+| `lbp publish` | 发布到 LangBot 插件市场 |
+| `lbp login` / `lbp logout` | 登录 / 登出 LangBot 账号 |
+| `lbp rt` | 启动独立的插件运行时（控制端口 `5400`，调试端口 `5401`） |
+| `lbp box` | 启动独立的 Box 代码沙箱运行时（默认端口 `5410`） |
+| `lbp ver` | 打印 CLI / 包版本 |
+
+## 组件类型
+
+插件通过六种组件类型扩展 LangBot，使用 `lbp comp <Type>` 生成：
+
+- **Command** —— 用户触发的指令（如 `!weather tokyo`）
+- **Tool** —— 供 AI Agent 调用的 LLM 工具函数
+- **EventListener** —— 消息流水线事件的处理器
+- **KnowledgeEngine** —— 用于 RAG 的自定义知识库检索
+- **Parser** —— 自定义消息 / 内容解析
+- **Page** —— 嵌入 LangBot 管理面板的自定义网页
+
+## 文档
+
+- 插件开发教程 —— https://docs.langbot.app/zh/plugin/dev/tutor
+- 调试运行时 / CLI / SDK —— https://docs.langbot.app/zh/develop/plugin-runtime
+- 开发环境配置 —— https://docs.langbot.app/zh/develop/dev-config
+
+## 许可证
+
+本仓库采用 Apache 2.0，但插件运行时（`src/langbot_plugin/runtime/`）单独采用
+AGPL。详见 [LICENSE](LICENSE) 与
+[运行时 README](src/langbot_plugin/runtime/README.md)。

{langbot_plugin-0.4.4 → langbot_plugin-0.4.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "langbot-plugin"
-version = "0.4.4"
+version = "0.4.6"
 description = "This package contains the SDK, CLI for building plugins for LangBot, plus the runtime for hosting LangBot plugins"
 readme = "README.md"
 authors = [

langbot_plugin-0.4.6/scripts/check_action_consistency.py

@@ -0,0 +1,277 @@
+#!/usr/bin/env python3
+"""Static consistency check for the action-based runtime protocol.
+
+The runtime protocol (``runtime/io/``) dispatches calls by action name: a sender
+calls ``call_action(SomeAction.MEMBER, ...)`` and a receiver must have registered
+a handler with ``@handler.action(SomeAction.MEMBER)``. If the handler is missing,
+the call fails *at runtime* with ``ValueError: Action <name> not found`` — a class
+of bug that unit tests miss because they mock the proxy layer, and that only shows
+up end-to-end (this is exactly how ``vector_list`` shipped broken: the enum member,
+the plugin-side proxy, and a proxy-level test all existed, but no runtime forwarder
+was registered).
+
+This checker parses the SDK with ``ast`` (no imports, no side effects) and enforces:
+
+1. ERROR: every action *invoked* in-repo (``call_action`` / ``call_action_generator``
+   with a literal ``EnumClass.MEMBER`` argument) has a matching ``.action(...)``
+   registration in-repo — UNLESS the action's receiver is an external process
+   (the LangBot host), whose handlers live in a different repository. This is the
+   invariant ``vector_list`` violated.
+2. ERROR: every ``EnumClass.MEMBER`` referenced by an invocation or registration
+   actually exists on that enum class (guards against typos / renames).
+3. WARN: enum members that are neither invoked nor registered anywhere in-repo —
+   candidate dead wiring ("enum without action"). Warning only, because a member
+   may legitimately be invoked or handled by the LangBot host (a separate repo).
+
+Action enum classes follow the ``<Sender>To<Receiver>Action`` naming convention.
+The *receiver* is what must hold the handler, so Rule 1 only applies when the
+receiver lives in this repository (Runtime or Plugin); actions received by the
+LangBot host are handled there and cannot be checked from here.
+
+Known, accepted exceptions are listed in ``KNOWN_EXCEPTIONS`` with a reason so the
+gate can go green on a branch while pre-existing debt is tracked explicitly rather
+than hidden.
+
+Exit code is non-zero if any unexpected ERROR is found. Run from the repo root:
+
+    python scripts/check_action_consistency.py
+"""
+
+from __future__ import annotations
+
+import ast
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SRC_ROOT = REPO_ROOT / "src" / "langbot_plugin"
+ENUMS_FILE = SRC_ROOT / "entities" / "io" / "actions" / "enums.py"
+
+INVOKE_METHODS = {"call_action", "call_action_generator"}
+REGISTER_METHODS = {"action"}
+
+# Receivers whose action handlers live in THIS repository. Actions whose receiver
+# is anything else (e.g. the LangBot host) are handled in another repo, so Rule 1
+# (invoked => registered) cannot and must not be enforced here.
+IN_REPO_RECEIVERS = {"Runtime", "Plugin"}
+
+# Accepted, documented exceptions to keep the gate green while tracking known debt.
+# Map (EnumClassName, MEMBER) -> reason. Remove an entry once the underlying issue
+# is fixed; the checker reports any entry that has become unnecessary.
+KNOWN_EXCEPTIONS: dict[tuple[str, str], str] = {
+    # invoke_llm_stream_events() references this member, but on the 0.4.x line the
+    # enum member and its runtime forwarder are absent (both exist and are wired on
+    # feat/agent-runner-plugin). Tracked for forward-port; the LangBot host already
+    # registers PluginToRuntimeAction.INVOKE_LLM_STREAM.
+    ("PluginToRuntimeAction", "INVOKE_LLM_STREAM"): (
+        "streaming LLM forwarder not yet ported to this branch; see feat/agent-runner-plugin"
+    ),
+}
+
+
+class Ref:
+    """A literal ``EnumClass.MEMBER`` reference at a source location."""
+
+    __slots__ = ("enum", "member", "file", "line")
+
+    def __init__(self, enum: str, member: str, file: Path, line: int):
+        self.enum = enum
+        self.member = member
+        self.file = file
+        self.line = line
+
+    @property
+    def key(self) -> tuple[str, str]:
+        return (self.enum, self.member)
+
+    def where(self) -> str:
+        rel = self.file.relative_to(REPO_ROOT)
+        return f"{rel}:{self.line}"
+
+
+def action_receiver(enum_name: str) -> str | None:
+    """Return the receiver segment of a ``<Sender>To<Receiver>Action`` enum name.
+
+    Returns ``None`` for names without a ``To`` segment (e.g. ``CommonAction``),
+    which are treated as in-repo.
+    """
+    if not enum_name.endswith("Action"):
+        return None
+    core = enum_name[: -len("Action")]
+    if "To" not in core:
+        return None
+    return core.rsplit("To", 1)[1]
+
+
+def receiver_in_repo(enum_name: str) -> bool:
+    receiver = action_receiver(enum_name)
+    return receiver is None or receiver in IN_REPO_RECEIVERS
+
+
+def load_enum_members() -> dict[str, set[str]]:
+    """Return {EnumClassName: {MEMBER, ...}} for every action enum class."""
+    tree = ast.parse(ENUMS_FILE.read_text(encoding="utf-8"), filename=str(ENUMS_FILE))
+    enums: dict[str, set[str]] = {}
+    for node in tree.body:
+        if not isinstance(node, ast.ClassDef):
+            continue
+        members: set[str] = set()
+        for stmt in node.body:
+            targets: list[ast.expr] = []
+            if isinstance(stmt, ast.Assign):
+                targets = stmt.targets
+            elif isinstance(stmt, ast.AnnAssign) and stmt.target is not None:
+                targets = [stmt.target]
+            for target in targets:
+                if isinstance(target, ast.Name) and target.id.isupper():
+                    members.add(target.id)
+        if members:
+            enums[node.name] = members
+    return enums
+
+
+def _enum_member_arg(arg: ast.expr, enum_names: set[str]) -> tuple[str, str] | None:
+    """If ``arg`` is ``EnumClass.MEMBER`` for a known enum, return (enum, member)."""
+    if (
+        isinstance(arg, ast.Attribute)
+        and isinstance(arg.value, ast.Name)
+        and arg.value.id in enum_names
+    ):
+        return (arg.value.id, arg.attr)
+    return None
+
+
+def scan(enum_names: set[str]) -> tuple[list[Ref], list[Ref]]:
+    """Walk the source tree, returning (invocations, registrations)."""
+    invocations: list[Ref] = []
+    registrations: list[Ref] = []
+
+    for path in sorted(SRC_ROOT.rglob("*.py")):
+        try:
+            tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+        except SyntaxError as exc:  # pragma: no cover - defensive
+            print(f"WARN: could not parse {path}: {exc}", file=sys.stderr)
+            continue
+
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.Call) or not isinstance(
+                node.func, ast.Attribute
+            ):
+                continue
+            method = node.func.attr
+            if not node.args:
+                continue
+            ref = _enum_member_arg(node.args[0], enum_names)
+            if ref is None:
+                continue
+            enum, member = ref
+            location = Ref(enum, member, path, node.lineno)
+            if method in INVOKE_METHODS:
+                invocations.append(location)
+            elif method in REGISTER_METHODS:
+                registrations.append(location)
+
+    return invocations, registrations
+
+
+def main() -> int:
+    if not ENUMS_FILE.exists():
+        print(f"ERROR: enum file not found: {ENUMS_FILE}", file=sys.stderr)
+        return 2
+
+    enums = load_enum_members()
+    enum_names = set(enums)
+    invocations, registrations = scan(enum_names)
+
+    registered_keys = {ref.key for ref in registrations}
+    invoked_keys = {ref.key for ref in invocations}
+
+    errors: list[str] = []
+    acknowledged: list[str] = []
+    used_exceptions: set[tuple[str, str]] = set()
+
+    # Rule 2: referenced members must exist on their enum (typo / rename guard).
+    for ref in invocations + registrations:
+        if ref.member in enums.get(ref.enum, set()):
+            continue
+        if ref.key in KNOWN_EXCEPTIONS:
+            used_exceptions.add(ref.key)
+            acknowledged.append(
+                f"{ref.enum}.{ref.member} at {ref.where()} — {KNOWN_EXCEPTIONS[ref.key]}"
+            )
+            continue
+        errors.append(
+            f"unknown action member {ref.enum}.{ref.member} referenced at "
+            f"{ref.where()} (not defined in {ENUMS_FILE.name})"
+        )
+
+    # Rule 1: every invoked action whose receiver is in-repo must be registered.
+    for ref in invocations:
+        if not receiver_in_repo(ref.enum):
+            continue  # receiver is the external LangBot host; handler lives there
+        if ref.key in registered_keys:
+            continue
+        if ref.key in KNOWN_EXCEPTIONS:
+            used_exceptions.add(ref.key)
+            acknowledged.append(
+                f"{ref.enum}.{ref.member} invoked at {ref.where()} but not registered "
+                f"— {KNOWN_EXCEPTIONS[ref.key]}"
+            )
+            continue
+        errors.append(
+            f"{ref.enum}.{ref.member} is invoked at {ref.where()} but no "
+            f"`.action({ref.enum}.{ref.member})` handler is registered anywhere in "
+            f'src/ — calls will fail at runtime with "Action {ref.member.lower()} not found"'
+        )
+
+    # Stale-allowlist guard: every KNOWN_EXCEPTIONS entry should still be needed.
+    for key in KNOWN_EXCEPTIONS:
+        if key not in used_exceptions:
+            errors.append(
+                f"stale KNOWN_EXCEPTIONS entry {key[0]}.{key[1]} — the underlying "
+                f"inconsistency is gone; remove it from {Path(__file__).name}"
+            )
+
+    # Rule 3 (warning): enum members with no invocation and no registration in-repo.
+    warnings: list[str] = []
+    for enum, members in sorted(enums.items()):
+        for member in sorted(members):
+            key = (enum, member)
+            if key not in invoked_keys and key not in registered_keys:
+                warnings.append(
+                    f"{enum}.{member} is never invoked nor registered in src/ "
+                    f"(handled by the LangBot host, or dead wiring?)"
+                )
+
+    print(
+        f"action-consistency: {len(enums)} enums, "
+        f"{len(invoked_keys)} invoked, {len(registered_keys)} registered"
+    )
+
+    if acknowledged:
+        print(f"\n{len(acknowledged)} known exception(s) (tracked debt):")
+        for line in acknowledged:
+            print(f"  KNOWN: {line}")
+
+    if warnings:
+        print(f"\n{len(warnings)} warning(s):")
+        for line in warnings:
+            print(f"  WARN: {line}")
+
+    if errors:
+        print(f"\n{len(errors)} error(s):", file=sys.stderr)
+        for line in errors:
+            print(f"  ERROR: {line}", file=sys.stderr)
+        print(
+            "\nAction protocol consistency check FAILED. "
+            "Register the missing handler(s) or fix the reference.",
+            file=sys.stderr,
+        )
+        return 1
+
+    print("\nAction protocol consistency check passed.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())