@agentunion/kite 1.3.2 → 1.4.0

package/extensions/channels/acp_channel/module.md

@@ -1,22 +1,23 @@
----
-name: acp_channel
-display_name: ACP Channel
-version: "1.0"
-type: channel
-state: enabled
-runtime: python
-entry: entry.py
-events:
-  - acp_channel.test
-subscriptions:
-  - module.started
-  - module.stopped
-  - module.shutdown
----
-
-# ACP Channel（ACP 协议通道）
-
-ACP 协议通道模块，负责接入外部消息通道。
-
-- 消息接入 — 通过 ACP 协议接收和发送消息
-- 事件通知 — 通过 Kernel 发布通道状态事件
+---
+name: acp_channel
+display_name: ACP Channel
+version: '1.0'
+type: channel
+state: enabled
+runtime: python
+entry: entry.py
+events:
+- acp_channel.test
+subscriptions:
+- module.started
+- module.stopped
+- module.shutdown
+advertise_ip: 127.0.0.1
+monitor: true
+---
+# ACP Channel（ACP 协议通道）
+
+ACP 协议通道模块，负责接入外部消息通道。
+
+- 消息接入 — 通过 ACP 协议接收和发送消息
+- 事件通知 — 通过 Kernel 发布通道状态事件

package/extensions/channels/acp_channel/server.py

@@ -1,215 +1,263 @@
-"""
-ACP Channel WebSocket client.
-Connects to Kernel via WebSocket JSON-RPC 2.0 for event publishing and subscription.
-"""
-
-import asyncio
-import json
-import time
-import uuid
-from datetime import datetime, timezone
-
-import websockets
-
-
-class AcpChannelServer:
-
-    def __init__(self, token: str = "", kernel_port: int = 0, boot_t0: float = 0):
-        self.token = token
-        self.kernel_port = kernel_port
-        self.boot_t0 = boot_t0
-        self._ws_task: asyncio.Task | None = None
-        self._test_task: asyncio.Task | None = None
-        self._ws: object | None = None
-        self._shutting_down = False
-        self._start_time = time.time()
-
-    async def run(self):
-        """Main entry point: start WebSocket loop and test event loop."""
-        if self.kernel_port:
-            self._ws_task = asyncio.create_task(self._ws_loop())
-        self._test_task = asyncio.create_task(self._test_event_loop())
-
-        # Wait for tasks to complete
-        tasks = [t for t in [self._ws_task, self._test_task] if t]
-        if tasks:
-            await asyncio.gather(*tasks, return_exceptions=True)
-
-        print("[acp_channel] Shutdown complete")
-
-    # ── Kernel WebSocket client ──
-
-    async def _ws_loop(self):
-        """Connect to Kernel, subscribe, register, and listen. Reconnect on failure."""
-        retry_delay = 0.3
-        max_delay = 5.0
-        max_retries = 10
-        attempt = 0
-        while not self._shutting_down:
-            try:
-                await self._ws_connect()
-                retry_delay = 0.3
-                attempt = 0
-            except asyncio.CancelledError:
-                return
-            except Exception as e:
-                attempt += 1
-                # Auth failure — don't retry
-                if hasattr(e, 'rcvd') and e.rcvd is not None:
-                    code = e.rcvd.code if hasattr(e.rcvd, 'code') else 0
-                    if code in (4001, 4003):
-                        print(f"[acp_channel] Kernel 认证失败 (code {code})，退出")
-                        import sys; sys.exit(1)
-                if attempt >= max_retries:
-                    print(f"[acp_channel] Kernel 重连失败 {max_retries} 次，退出")
-                    import sys; sys.exit(1)
-                print(f"[acp_channel] Kernel connection error: {e}, retrying in {retry_delay:.1f}s ({attempt}/{max_retries})")
-            self._ws = None
-            if self._shutting_down:
-                return
-            await asyncio.sleep(retry_delay)
-            retry_delay = min(retry_delay * 2, max_delay)
-
-    async def _ws_connect(self):
-        """Single WebSocket session: connect, subscribe, register, ready, receive loop."""
-        url = f"ws://127.0.0.1:{self.kernel_port}/ws?token={self.token}&id=acp_channel"
-        print(f"[acp_channel] Connecting to Kernel (port {self.kernel_port})")
-        async with websockets.connect(url, open_timeout=3, ping_interval=None, ping_timeout=None, close_timeout=10) as ws:
-            self._ws = ws
-            elapsed = time.monotonic() - self.boot_t0 if self.boot_t0 else 0
-            elapsed_str = f" ({elapsed:.1f}s)" if elapsed else ""
-            print(f"[acp_channel] Connected to Kernel{elapsed_str}")
-
-            # Step 1: Subscribe to events (先订阅)
-            await self._rpc_call(ws, "event.subscribe", {
-                "events": ["module.started", "module.stopped", "module.shutdown"],
-            })
-
-            # Step 2: Register to Kernel (再注册)
-            await self._rpc_call(ws, "registry.register", {
-                "module_id": "acp_channel",
-                "module_type": "channel",
-                "name": "ACP Channel",
-                "events_publish": {
-                    "acp_channel.test": {},
-                },
-                "events_subscribe": [
-                    "module.started",
-                    "module.stopped",
-                    "module.shutdown",
-                ],
-            })
-
-            # Step 3: Publish module.ready (every reconnect)
-            if not self._shutting_down:
-                await self._rpc_call(ws, "event.publish", {
-                    "event_id": str(uuid.uuid4()),
-                    "event": "module.ready",
-                    "data": {
-                        "module_id": "acp_channel",
-                        "graceful_shutdown": True,
-                    },
-                })
-                elapsed = time.monotonic() - self.boot_t0 if self.boot_t0 else 0
-                elapsed_str = f" ({elapsed:.1f}s)" if elapsed else ""
-                print(f"[acp_channel] module.ready published{elapsed_str}")
-
-            # Receive loop
-            async for raw in ws:
-                try:
-                    msg = json.loads(raw)
-                except (json.JSONDecodeError, TypeError):
-                    continue
-
-                try:
-                    has_method = "method" in msg
-                    has_id = "id" in msg
-
-                    if has_method and not has_id:
-                        # JSON-RPC Notification (event delivery)
-                        params = msg.get("params", {})
-                        event_name = params.get("event", "")
-                        if event_name == "module.shutdown":
-                            data = params.get("data", {})
-                            target = data.get("module_id", "")
-                            reason = data.get("reason", "")
-                            # Handle both targeted shutdown (module_id == "acp_channel") and broadcast shutdown (no module_id or launcher_lost)
-                            if target == "acp_channel" or not target or reason == "launcher_lost":
-                                await self._handle_shutdown(ws)
-                                return
-                    elif not has_method and has_id:
-                        # JSON-RPC Response (to our RPC calls)
-                        pass
-                except Exception as e:
-                    print(f"[acp_channel] 事件处理异常（已忽略）: {e}")
-
-    async def _handle_shutdown(self, ws):
-        """Handle module.shutdown: exiting → ack → cleanup → ready → exit."""
-        print("[acp_channel] Received module.shutdown")
-        self._shutting_down = True
-
-        # Step 0: Send module.exiting
-        await self._rpc_call(ws, "event.publish", {
-            "event_id": str(uuid.uuid4()),
-            "event": "module.exiting",
-            "data": {"module_id": "acp_channel", "action": "none"},
-        })
-
-        # Step 1: Send ack
-        await self._rpc_call(ws, "event.publish", {
-            "event_id": str(uuid.uuid4()),
-            "event": "module.shutdown.ack",
-            "data": {"module_id": "acp_channel", "estimated_cleanup": 2},
-        })
-        print("[acp_channel] shutdown ack sent")
-
-        # Step 2: Cleanup (cancel background tasks)
-        if self._test_task:
-            self._test_task.cancel()
-
-        # Step 3: Send ready (before closing WS!)
-        await self._rpc_call(ws, "event.publish", {
-            "event_id": str(uuid.uuid4()),
-            "event": "module.shutdown.ready",
-            "data": {"module_id": "acp_channel"},
-        })
-        print("[acp_channel] Shutdown ready sent")
-
-        # Step 4: Exit process
-        import sys
-        sys.exit(0)
-
-    async def _rpc_call(self, ws, method: str, params: dict = None):
-        """Send a JSON-RPC 2.0 request."""
-        msg = {"jsonrpc": "2.0", "id": str(uuid.uuid4()), "method": method}
-        if params:
-            msg["params"] = params
-        await ws.send(json.dumps(msg))
-
-    async def _publish_event(self, event: dict):
-        """Publish an event via JSON-RPC event.publish."""
-        if not self._ws:
-            return
-        try:
-            await self._rpc_call(self._ws, "event.publish", {
-                "event_id": str(uuid.uuid4()),
-                "event": event.get("event", ""),
-                "data": event.get("data", {}),
-            })
-        except Exception as e:
-            print(f"[acp_channel] Failed to publish event: {e}")
-
-    # ── Test event loop ──
-
-    async def _test_event_loop(self):
-        """Publish a test event every 10 seconds."""
-        while True:
-            await asyncio.sleep(10)
-            await self._publish_event({
-                "event": "acp_channel.test",
-                "data": {
-                    "message": "test event from acp_channel",
-                    "timestamp": datetime.now(timezone.utc).isoformat(),
-                },
-            })
-            print("[acp_channel] test event published")
+"""
+ACP Channel WebSocket client.
+Connects to Kernel via WebSocket JSON-RPC 2.0 for event publishing and subscription.
+"""
+
+import asyncio
+import json
+import os
+import time
+import uuid
+from datetime import datetime, timezone
+
+import websockets
+
+
+# System broadcast events (received by all modules, may not need handling)
+SYSTEM_BROADCAST_EVENTS = {
+    "module.ready", "module.registered", "module.started", "module.stopped",
+    "module.crashed", "module.exiting", "module.offline",
+    "module.shutdown.ack", "module.shutdown.ready",
+    "system.ready", "registry.updated",
+}
+
+
+class AcpChannelServer:
+
+    def __init__(self, token: str = "", kernel_port: int = 0, boot_t0: float = 0):
+        self.token = token
+        self.kernel_port = kernel_port
+        self.boot_t0 = boot_t0
+        self._ws_task: asyncio.Task | None = None
+        self._test_task: asyncio.Task | None = None
+        self._ws: object | None = None
+        self._shutting_down = False
+        self._exit_code = 0  # Exit code for main() to use
+        self._start_time = time.time()
+
+    async def run(self):
+        """Main entry point: start WebSocket loop and test event loop."""
+        if self.kernel_port:
+            self._ws_task = asyncio.create_task(self._ws_loop())
+        self._test_task = asyncio.create_task(self._test_event_loop())
+
+        # Wait for tasks to complete
+        tasks = [t for t in [self._ws_task, self._test_task] if t]
+        if tasks:
+            await asyncio.gather(*tasks, return_exceptions=True)
+
+        print("[acp_channel] Shutdown complete")
+
+    # ── Kernel WebSocket client ──
+
+    async def _ws_loop(self):
+        """Connect to Kernel, subscribe, register, and listen. Reconnect on failure."""
+        retry_delay = 0.3
+        max_delay = 5.0
+        max_retries = 10
+        attempt = 0
+        while not self._shutting_down:
+            try:
+                await self._ws_connect()
+                retry_delay = 0.3
+                attempt = 0
+            except asyncio.CancelledError:
+                return
+            except Exception as e:
+                attempt += 1
+                # Auth failure — don't retry
+                if hasattr(e, 'rcvd') and e.rcvd is not None:
+                    code = e.rcvd.code if hasattr(e.rcvd, 'code') else 0
+                    if code in (4001, 4003):
+                        print(f"[acp_channel] Kernel 认证失败 (code {code})，退出")
+                        self._exit_code = 1
+                        self._shutting_down = True
+                        return
+                if attempt >= max_retries:
+                    print(f"[acp_channel] Kernel 重连失败 {max_retries} 次，退出")
+                    self._exit_code = 1
+                    self._shutting_down = True
+                    return
+                print(f"[acp_channel] Kernel connection error: {e}, retrying in {retry_delay:.1f}s ({attempt}/{max_retries})")
+            self._ws = None
+            if self._shutting_down:
+                return
+            await asyncio.sleep(retry_delay)
+            retry_delay = min(retry_delay * 2, max_delay)
+
+    async def _ws_connect(self):
+        """Single WebSocket session: connect, subscribe, register, ready, receive loop."""
+        url = f"ws://127.0.0.1:{self.kernel_port}/ws?token={self.token}&id=acp_channel"
+        print(f"[acp_channel] Connecting to Kernel (port {self.kernel_port})")
+        async with websockets.connect(url, open_timeout=3, ping_interval=20, ping_timeout=20, close_timeout=10) as ws:
+            self._ws = ws
+            elapsed = time.monotonic() - self.boot_t0 if self.boot_t0 else 0
+            elapsed_str = f" ({elapsed:.1f}s)" if elapsed else ""
+            print(f"[acp_channel] Connected to Kernel{elapsed_str}")
+
+            # Step 1: Subscribe to events (先订阅)
+            await self._rpc_call(ws, "event.subscribe", {
+                "events": ["module.started", "module.stopped", "module.shutdown"],
+            })
+
+            # Step 2: Register to Kernel (再注册)
+            await self._rpc_call(ws, "registry.register", {
+                "module_id": "acp_channel",
+                "module_type": "channel",
+                "name": "ACP Channel",
+                "events_publish": {
+                    "acp_channel": {
+                        "test": {},
+                    }
+                },
+                "events_subscribe": [
+                    "module.started",
+                    "module.stopped",
+                    "module.shutdown",
+                ],
+            })
+
+            # Step 3: Publish module.ready (every reconnect)
+            if not self._shutting_down:
+                await self._rpc_call(ws, "event.publish", {
+                    "event_id": str(uuid.uuid4()),
+                    "event": "module.ready",
+                    "data": {
+                        "module_id": "acp_channel",
+                        "graceful_shutdown": True,
+                    },
+                })
+                elapsed = time.monotonic() - self.boot_t0 if self.boot_t0 else 0
+                elapsed_str = f" ({elapsed:.1f}s)" if elapsed else ""
+                print(f"[acp_channel] module.ready published{elapsed_str}")
+
+            # Receive loop
+            # CRITICAL: RPC 死锁防范
+            # - 入站 RPC 请求必须用 create_task() 异步执行，不可 await
+            # - 原因：如果 handler 内部调用 rpc_call() 发出站请求，出站响应需要本接收循环来分发
+            # - 如果接收循环被 await handler 阻塞，出站响应永远收不到 → 超时死锁
+            # - 事件通知和 RPC 响应可以同步处理（它们不会反向调用 rpc_call）
+
+            # Start heartbeat loop
+            heartbeat_task = asyncio.create_task(self._heartbeat_loop(ws))
+
+            async for raw in ws:
+                try:
+                    msg = json.loads(raw)
+                except (json.JSONDecodeError, TypeError):
+                    continue
+
+                try:
+                    has_method = "method" in msg
+                    has_id = "id" in msg
+
+                    if has_method and not has_id:
+                        # JSON-RPC Notification (event delivery)
+                        params = msg.get("params", {})
+                        event_type = params.get("event", "")
+                        data = params.get("data", {})
+
+                        # Layer 1: 处理订阅的事件
+                        if event_type == "module.shutdown":
+                            target = data.get("module_id", "")
+                            reason = data.get("reason", "")
+                            # Handle both targeted shutdown (module_id == "acp_channel") and broadcast shutdown (no module_id or launcher_lost)
+                            if target == "acp_channel" or not target or reason == "launcher_lost":
+                                await self._handle_shutdown(ws)
+                                return
+
+                        # Layer 2: 忽略系统广播事件
+                        if event_type in SYSTEM_BROADCAST_EVENTS:
+                            continue
+
+                        # Layer 3: 警告未知事件（仅开发环境）
+                        if os.environ.get("KITE_ENV") == "development":
+                            print(f"[acp_channel] Debug: Unhandled event: {event_type}")
+
+                    elif not has_method and has_id:
+                        # JSON-RPC Response (to our RPC calls)
+                        pass
+                except Exception as e:
+                    print(f"[acp_channel] 事件处理异常（已忽略）: {e}")
+
+    async def _handle_shutdown(self, ws):
+        """Handle module.shutdown: ack → exiting → cleanup → ready → exit."""
+        print("[acp_channel] Received module.shutdown")
+        self._shutting_down = True
+
+        # Step 1: Send ack (立即确认收到)
+        await self._rpc_call(ws, "event.publish", {
+            "event_id": str(uuid.uuid4()),
+            "event": "module.shutdown.ack",
+            "data": {"module_id": "acp_channel", "estimated_cleanup": 2},
+        })
+        print("[acp_channel] shutdown ack sent")
+
+        # Step 2: Send module.exiting (开始清理)
+        await self._rpc_call(ws, "event.publish", {
+            "event_id": str(uuid.uuid4()),
+            "event": "module.exiting",
+            "data": {"module_id": "acp_channel", "action": "none"},
+        })
+
+        # Step 3: Cleanup (cancel background tasks)
+        if self._test_task:
+            self._test_task.cancel()
+
+        # Step 4: Send ready (清理完成)
+        await self._rpc_call(ws, "event.publish", {
+            "event_id": str(uuid.uuid4()),
+            "event": "module.shutdown.ready",
+            "data": {"module_id": "acp_channel"},
+        })
+        print("[acp_channel] Shutdown ready sent")
+
+        # Step 4: Exit process
+        import sys
+        sys.exit(0)
+
+    async def _rpc_call(self, ws, method: str, params: dict = None):
+        """Send a JSON-RPC 2.0 request."""
+        msg = {"jsonrpc": "2.0", "id": str(uuid.uuid4()), "method": method}
+        if params:
+            msg["params"] = params
+        await ws.send(json.dumps(msg))
+
+    async def _heartbeat_loop(self, ws):
+        """Send registry.heartbeat every 30 seconds to prevent TTL expiration."""
+        while True:
+            try:
+                await asyncio.sleep(30)
+                if not self._shutting_down:
+                    await self._rpc_call(ws, "registry.heartbeat", {"module_id": "acp_channel"})
+            except Exception as e:
+                print(f"[acp_channel] Heartbeat error: {e}")
+                break
+
+    async def _publish_event(self, event: dict):
+        """Publish an event via JSON-RPC event.publish."""
+        if not self._ws:
+            return
+        try:
+            await self._rpc_call(self._ws, "event.publish", {
+                "event_id": str(uuid.uuid4()),
+                "event": event.get("event", ""),
+                "data": event.get("data", {}),
+            })
+        except Exception as e:
+            print(f"[acp_channel] Failed to publish event: {e}")
+
+    # ── Test event loop ──
+
+    async def _test_event_loop(self):
+        """Publish a test event every 10 seconds."""
+        while True:
+            await asyncio.sleep(10)
+            await self._publish_event({
+                "event": "acp_channel.test",
+                "data": {
+                    "message": "test event from acp_channel",
+                    "timestamp": datetime.now(timezone.utc).isoformat(),
+                },
+            })
+            print("[acp_channel] test event published")

package/extensions/event_hub_bench/entry.py

@@ -35,7 +35,113 @@ TAG = "[event_hub_bench]"
 
 
 # ── Module configuration ──
-MODULE_NAME = "event_hub_bench"
+
+def _load_module_config() -> dict:
+    """Load module configuration from module.md frontmatter.
+
+    Returns:
+        Dict with keys: name, preferred_port, advertise_ip
+
+    Raises:
+        SystemExit: If module.md is invalid or name is non-compliant
+    """
+    _this_dir = os.path.dirname(os.path.abspath(__file__))
+    module_md = os.path.join(_this_dir, "module.md")
+
+    # Calculate relative path for error messages
+    project_root = os.environ.get("KITE_PROJECT", "")
+    if project_root and _this_dir.startswith(project_root):
+        rel_path = os.path.relpath(_this_dir, project_root)
+    else:
+        rel_path = _this_dir
+
+    # Default values (will be overridden if valid config exists)
+    result = {
+        "name": "",
+        "preferred_port": 0,
+        "advertise_ip": "0.0.0.0"
+    }
+
+    # Check if module.md exists
+    if not os.path.exists(module_md):
+        print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+        print(f"  Path: {rel_path}/module.md")
+        print(f"  Reason: File not found")
+        sys.exit(1)
+
+    try:
+        with open(module_md, encoding="utf-8") as f:
+            text = f.read()
+
+        # Extract YAML frontmatter (between --- markers)
+        import re
+        m = re.match(r'^---\s*\n(.*?)\n---', text, re.DOTALL)
+        if not m:
+            print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+            print(f"  Path: {rel_path}/module.md")
+            print(f"  Reason: Missing YAML frontmatter")
+            sys.exit(1)
+
+        # Parse YAML frontmatter
+        try:
+            import yaml
+            fm = yaml.safe_load(m.group(1)) or {}
+        except ImportError:
+            print(f"[{rel_path}] ERROR: PyYAML not installed, cannot parse module.md")
+            sys.exit(1)
+        except Exception as e:
+            print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+            print(f"  Path: {rel_path}/module.md")
+            print(f"  Reason: YAML parse error: {e}")
+            sys.exit(1)
+
+        # Validate 'name' field (required)
+        if "name" not in fm:
+            print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+            print(f"  Path: {rel_path}/module.md")
+            print(f"  Reason: Missing 'name' field")
+            sys.exit(1)
+
+        raw_name = str(fm["name"]).strip()
+
+        if not raw_name:
+            print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+            print(f"  Path: {rel_path}/module.md")
+            print(f"  Reason: Empty module name")
+            sys.exit(1)
+
+        # Validate name characters
+        sanitized = re.sub(r'[^a-zA-Z0-9_\-]', '', raw_name)
+
+        if sanitized != raw_name:
+            invalid_chars = ''.join(sorted(set(c for c in raw_name if c not in sanitized)))
+            print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+            print(f"  Path: {rel_path}/module.md")
+            print(f"  Reason: Invalid characters in name '{raw_name}': {repr(invalid_chars)}")
+            sys.exit(1)
+
+        result["name"] = sanitized
+
+        # Extract optional fields
+        if "preferred_port" in fm:
+            try:
+                result["preferred_port"] = int(fm["preferred_port"])
+            except (ValueError, TypeError):
+                pass
+
+        if "advertise_ip" in fm:
+            result["advertise_ip"] = str(fm["advertise_ip"])
+
+    except SystemExit:
+        raise  # Re-raise exit to prevent catching by outer except
+    except Exception as e:
+        print(f"[{rel_path}] ERROR: Failed to read module.md: {e}")
+        sys.exit(1)
+
+    return result
+
+_module_config = _load_module_config()
+MODULE_NAME = _module_config["name"]
 
 
 # ── Timestamped print + log file writer ──