@agentunion/kite 1.3.2 → 1.5.0

package/kernel/registry_store.py

@@ -20,10 +20,8 @@ class RegistryStore:
         self.launcher_token = launcher_token
         self.token_map: dict[str, str] = {}       # module_id -> token
         self.modules: dict[str, dict] = {}         # module_id -> registration payload
-        self.heartbeats: dict[str, float] = {}     # module_id -> last heartbeat timestamp
-        self.ttl = 60           # seconds before marking offline
-        self.heartbeat_interval = 30
         self.is_debug = os.environ.get("KITE_DEBUG") == "1"
+        self.last_update_time = time.time()        # Global registry update timestamp
 
     # ── Token verification ──
 
@@ -57,45 +55,72 @@ class RegistryStore:
     _REQUIRED_FIELDS = ("module_id", "module_type")  # api_endpoint now optional
 
     def register_module(self, data: dict) -> dict:
-        """Register or update a module. Idempotent — same module_id overwrites."""
+        """Register or update a module. Idempotent — same module_id overwrites.
+        Returns dict with changed flag on success, raises exception on failure."""
         # Validate required fields
         missing = [f for f in self._REQUIRED_FIELDS if not data.get(f)]
         if missing:
-            return {"ok": False, "error": f"Missing required fields: {', '.join(missing)}"}
+            raise ValueError(f"Missing required fields: {', '.join(missing)}")
 
         mid = data["module_id"]
 
-        # Warn on tool name conflicts
+        # Validate nested dict structure for lookup-able fields
+        # Only check known wrapper fields (tools, hooks, events_publish)
+        # RPC methods are registered directly at top level with their actual names
+        # events_subscribe is a list, not a dict
+        for field_name in ["tools", "hooks", "events_publish"]:
+            field_value = data.get(field_name)
+            if field_value is not None:
+                if not isinstance(field_value, dict):
+                    raise TypeError(f"Field '{field_name}' must be a dict (nested structure), got {type(field_value).__name__}")
+                # Check if it's a flat dict with dot-notation keys (common mistake)
+                if any("." in str(k) for k in field_value.keys()):
+                    raise ValueError(
+                        f"Field '{field_name}' contains dot-notation keys (e.g., 'module.config.get'). "
+                        f"Use nested dict structure instead: {{'module': {{'config': {{'get': ...}}}}}}. "
+                        f"See docs/模块开发指南.md section 4.3 for correct format."
+                    )
+
+        # Warn on tool name conflicts (skip 'rpc' — it's a standard tool every module registers)
         new_tools = data.get("tools", {})
         if isinstance(new_tools, dict):
             for tool_name in new_tools:
+                if tool_name == "rpc":
+                    continue
                 for other_mid, other_data in self.modules.items():
                     if other_mid == mid:
                         continue
                     if tool_name in other_data.get("tools", {}):
                         print(f"[kernel] WARNING: tool '{tool_name}' registered by both '{other_mid}' and '{mid}'")
 
+        # Check if content changed (compare with existing registration)
+        changed = True
+        old_record = self.modules.get(mid)
+        if old_record:
+            # Strip action field from new data
+            new_record = {k: v for k, v in data.items() if k != "action"}
+            # Compare without status and registered_at fields
+            old_data = {k: v for k, v in old_record.items() if k not in ("status", "registered_at")}
+            changed = (new_record != old_data)
+
         # Strip action field — it's a request verb, not part of the registration payload
         record = {k: v for k, v in data.items() if k != "action"}
         record["status"] = "registered"  # State machine: connected → registered (via register RPC)
         record["registered_at"] = time.time()
         self.modules[mid] = record
-        self.heartbeats[mid] = time.time()
-        return {"ok": True, "ttl": self.ttl, "heartbeat_interval": self.heartbeat_interval}
+
+        # Update global timestamp if content changed
+        if changed:
+            self.last_update_time = time.time()
+
+        return {"changed": changed}
 
     def deregister_module(self, module_id: str) -> dict:
-        """Remove a module record immediately."""
+        """Remove a module record immediately. Returns empty dict."""
         self.modules.pop(module_id, None)
-        self.heartbeats.pop(module_id, None)
-        return {"ok": True}
-
-    def heartbeat(self, module_id: str) -> dict:
-        """Renew heartbeat for a module."""
-        if module_id not in self.modules:
-            return {"ok": False, "error": "module not registered"}
-        self.heartbeats[module_id] = time.time()
-        # Don't change status — heartbeat just keeps alive, doesn't upgrade state
-        return {"ok": True}
+        # Update global timestamp
+        self.last_update_time = time.time()
+        return {}
 
     def set_connected(self, module_id: str):
         """Mark a module as connected (WS established, not yet registered).
@@ -119,17 +144,6 @@ class RegistryStore:
         mod = self.modules.get(module_id)
         return mod is not None and mod.get("status") == "ready"
 
-    def check_ttl(self) -> list[str]:
-        """Mark modules as offline if heartbeat expired. Returns list of newly-offline module_ids."""
-        now = time.time()
-        expired = []
-        for mid, last in list(self.heartbeats.items()):
-            if mid in self.modules and now - last > self.ttl:
-                if self.modules[mid].get("status") not in ("offline",):
-                    self.modules[mid]["status"] = "offline"
-                    expired.append(mid)
-        return expired
-
     # ── Get by dot-path ──
 
     def get_by_path(self, path: str) -> Any | None:
@@ -177,7 +191,7 @@ class RegistryStore:
     def lookup(self, field: str = None, module: str = None, value: str = None) -> list[dict]:
         """
         Search across all online modules. All three params support glob patterns.
-        Returns list of {field, module, api_endpoint, value}.
+        Returns list of {field, module, value}.
         """
         results = []
         for mid, data in self.modules.items():
@@ -186,8 +200,6 @@ class RegistryStore:
             if module and not fnmatch.fnmatch(mid, module):
                 continue
 
-            api_ep = data.get("api_endpoint", "")
-
             if field:
                 matches = self._match_fields(data, field)
                 for fpath, fval in matches:
@@ -196,7 +208,6 @@ class RegistryStore:
                     results.append({
                         "field": fpath,
                         "module": mid,
-                        "api_endpoint": api_ep,
                         "value": fval,
                     })
             elif value:
@@ -205,14 +216,12 @@ class RegistryStore:
                         results.append({
                             "field": k,
                             "module": mid,
-                            "api_endpoint": api_ep,
                             "value": v,
                         })
             else:
                 results.append({
                     "field": "module_id",
                     "module": mid,
-                    "api_endpoint": api_ep,
                     "value": mid,
                 })
 

package/kernel/rpc_router.py

@@ -73,11 +73,16 @@ class RpcRouter:
         self.connections = connections
         self.kernel_server = kernel_server  # Direct reference to KernelServer
 
+        # RPC 统计计数器
+        self._rpc_total = 0  # 总 RPC 调用次数
+        self._rpc_builtin = 0  # 内置方法调用次数
+        self._rpc_forwarded = 0  # 转发调用次数
+        self._rpc_errors = 0  # 错误次数
+
         # Builtin method dispatch table
         self.methods: dict[str, callable] = {
             "registry.register":      self._registry_register,
             "registry.deregister":    self._registry_deregister,
-            "registry.heartbeat":     self._registry_heartbeat,
             "registry.lookup":        self._registry_lookup,
             "registry.get":           self._registry_get,
             "registry.verify":        self._registry_verify,
@@ -87,9 +92,9 @@ class RpcRouter:
             "kernel.ping":            self._kernel_ping,
             "kernel.stats":           self._kernel_stats,
             "kernel.health":          self._kernel_health,
+            "kernel.latencies":       self._kernel_latencies,
             "kernel.generate_tokens": self._kernel_generate_tokens,
             "kernel.register_tokens": self._kernel_register_tokens,
-            "kernel.shutdown":        self._kernel_shutdown,
         }
 
         # Pending cross-module forwards: internal_id -> PendingForward
@@ -102,6 +107,9 @@ class RpcRouter:
         method = msg.get("method", "")
         msg_id = msg.get("id")
 
+        # 统计：总调用次数
+        self._rpc_total += 1
+
         # JSON-RPC Notification (no id) — currently not handled from clients
         if msg_id is None:
             return
@@ -111,12 +119,27 @@ class RpcRouter:
         # Builtin method
         handler = self.methods.get(method)
         if handler:
+            # 统计：内置方法调用
+            self._rpc_builtin += 1
             try:
                 result = await handler(caller_id, params)
-                await ws.send_text(_result_msg(msg_id, result))
             except Exception as e:
+                # 统计：错误次数
+                self._rpc_errors += 1
                 print(f"[kernel] RPC handler error ({method}): {e}")
-                await ws.send_text(_error_msg(msg_id, INTERNAL_ERROR, str(e)))
+                try:
+                    await ws.send_text(_error_msg(msg_id, INTERNAL_ERROR, str(e)))
+                except Exception:
+                    # Can't send error response, connection closed
+                    pass
+                return
+
+            # Send result (may fail if connection closed during shutdown)
+            try:
+                await ws.send_text(_result_msg(msg_id, result))
+            except Exception as e:
+                # Connection closed during shutdown — this is normal, exit silently
+                pass
             return
 
         # Cross-module forward: method prefix is target module_id
@@ -126,19 +149,27 @@ class RpcRouter:
             if target in self.connections:
                 # Check if target module is ready (state machine protection)
                 if not self.registry.is_ready(target):
+                    # 统计：错误次数
+                    self._rpc_errors += 1
                     await ws.send_text(_error_msg(
                         msg_id, MODULE_OFFLINE,
                         f"Module not ready: {target} (status: {self.registry.modules.get(target, {}).get('status', 'unknown')})"))
                     return
+                # 统计：转发调用
+                self._rpc_forwarded += 1
                 await self._forward(caller_id, ws, msg_id, target, method, params)
                 return
             # Target not connected — check if registered but offline
             if target in self.registry.modules:
+                # 统计：错误次数
+                self._rpc_errors += 1
                 await ws.send_text(_error_msg(
                     msg_id, MODULE_OFFLINE, f"Module offline: {target}"))
                 return
 
         # Method not found
+        # 统计：错误次数
+        self._rpc_errors += 1
         await ws.send_text(_error_msg(msg_id, METHOD_NOT_FOUND, f"Method not found: {method}"))
 
     async def handle_response(self, module_id: str, msg: dict):
@@ -187,6 +218,11 @@ class RpcRouter:
         # Strip target prefix from method for the forwarded request
         actual_method = method[len(target) + 1:]  # e.g. "watchdog.get_status" -> "get_status"
 
+        # Inject caller_id into params for permission checking
+        if not isinstance(params, dict):
+            params = {}
+        params["_caller_id"] = caller_id
+
         # Record pending forward
         loop = asyncio.get_event_loop()
         pending = PendingForward(
@@ -243,62 +279,93 @@ class RpcRouter:
     async def _registry_register(self, caller_id: str, params: dict) -> dict:
         mid = params.get("module_id")
         if not mid:
-            return {"ok": False, "error": "module_id required"}
+            raise ValueError("module_id required")
         # Permission: only Launcher or the module itself
         if caller_id != "launcher" and caller_id != mid:
-            return {"ok": False, "error": f"Module '{caller_id}' cannot register as '{mid}'"}
+            raise PermissionError(f"Module '{caller_id}' cannot register as '{mid}'")
+
+        print(f"[kernel] registry.register called by {caller_id} for module {mid}")
+        print(f"[kernel]   rpc_methods: {params.get('rpc_methods')}")
+
         result = self.registry.register_module(params)
-        if result.get("ok"):
-            self.event_hub.publish_internal("module.registered", {"module_id": mid})
+        self.event_hub.publish_internal("module.registered", {"module_id": mid}, source=self.kernel_server.module_id)
+
+        # Only publish registry.updated if content actually changed
+        if result.get("changed", True):
+            from datetime import datetime, timezone
+            self.event_hub.publish_internal("registry.updated", {
+                "module_id": mid,
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+                "action": "register",
+            }, source=self.kernel_server.module_id)
+            print(f"[kernel] registry.updated published for {mid}")
+        else:
+            print(f"[kernel] {mid} re-registered with no changes, skipping registry.updated")
+
+        # When Launcher registers, Kernel publishes its own module.ready
+        if mid == "launcher" and self.kernel_server:
+            self.kernel_server.publish_ready()
+            print(f"[kernel] launcher registered → kernel module.ready published")
 
-            # When Launcher registers, Kernel publishes its own module.ready
-            if mid == "launcher" and self.kernel_server:
-                self.kernel_server.publish_ready()
-                print(f"[kernel] launcher registered → kernel module.ready published")
         return result
 
     async def _registry_deregister(self, caller_id: str, params: dict) -> dict:
         mid = params.get("module_id")
         if not mid:
-            return {"ok": False, "error": "module_id required"}
+            raise ValueError("module_id required")
         if caller_id != "launcher" and caller_id != mid:
-            return {"ok": False, "error": f"Module '{caller_id}' cannot deregister '{mid}'"}
-        result = self.registry.deregister_module(mid)
-        if result.get("ok"):
-            self.event_hub.publish_internal("module.unregistered", {"module_id": mid})
-        return result
+            raise PermissionError(f"Module '{caller_id}' cannot deregister '{mid}'")
 
-    async def _registry_heartbeat(self, caller_id: str, params: dict) -> dict:
-        mid = params.get("module_id")
-        if not mid:
-            return {"ok": False, "error": "module_id required"}
-        if caller_id != "launcher" and caller_id != mid:
-            return {"ok": False, "error": f"Module '{caller_id}' cannot heartbeat for '{mid}'"}
-        return self.registry.heartbeat(mid)
+        self.registry.deregister_module(mid)
+        self.event_hub.publish_internal("module.unregistered", {"module_id": mid}, source=self.kernel_server.module_id)
+
+        # Publish registry.updated event for cache invalidation
+        from datetime import datetime, timezone
+        self.event_hub.publish_internal("registry.updated", {
+            "module_id": mid,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "action": "deregister",
+        }, source=self.kernel_server.module_id)
+
+        return {}
 
     async def _registry_lookup(self, caller_id: str, params: dict) -> dict:
+        field = params.get("field")
+        module = params.get("module")
+        value = params.get("value")
+
+        print(f"[kernel] registry.lookup called by {caller_id}: field={field}, module={module}, value={value}")
+
         results = self.registry.lookup(
-            field=params.get("field"),
-            module=params.get("module"),
-            value=params.get("value"),
+            field=field,
+            module=module,
+            value=value,
         )
-        return {"ok": True, "results": results}
+
+        print(f"[kernel] registry.lookup results: {len(results)} matches")
+        for r in results:
+            print(f"[kernel]   - {r['module']}.{r['field']} = {r['value']}")
+
+        return {
+            "results": results,
+            "last_update_time": self.registry.last_update_time
+        }
 
     async def _registry_get(self, caller_id: str, params: dict) -> dict:
         path = params.get("path", "")
         if not path:
-            return {"ok": False, "error": "path required"}
+            raise ValueError("path required")
         val, found = self.registry.get_by_path(path)
         if not found:
-            return {"ok": False, "error": f"Path not found: {path}"}
-        return {"ok": True, "value": val}
+            raise KeyError(f"Path not found: {path}")
+        return {"value": val}
 
     async def _registry_verify(self, caller_id: str, params: dict) -> dict:
         token = params.get("token", "")
         module_id = self.registry.verify_token(token)
-        if module_id:
-            return {"ok": True, "module_id": module_id}
-        return {"ok": False}
+        if not module_id:
+            raise PermissionError("Invalid token")
+        return {"module_id": module_id}
 
     # ── Builtin handlers: event.* ──
 
@@ -311,23 +378,24 @@ class RpcRouter:
         # When a module publishes module.ready, update its status in registry
         if event_type == "module.ready":
             mid = (data or {}).get("module_id", caller_id)
+            print(f"[kernel] DEBUG: 收到 module.ready 事件，module_id={mid}, caller_id={caller_id}")
             self.registry.set_ready(mid)
+            print(f"[kernel] DEBUG: 已调用 set_ready({mid})")
 
         return self.event_hub.publish_event(caller_id, event_id, event_type, data, echo)
 
     async def _event_subscribe(self, caller_id: str, params: dict) -> dict:
         events = params.get("events", [])
         if not isinstance(events, list) or not events:
-            return {"ok": False, "error": "events must be a non-empty list"}
+            raise ValueError("events must be a non-empty list")
         self.event_hub.handle_subscribe(caller_id, events)
-        return {"ok": True}
+        return {}
 
     async def _event_unsubscribe(self, caller_id: str, params: dict) -> dict:
         events = params.get("events", [])
         if not isinstance(events, list) or not events:
-            return {"ok": False, "error": "events must be a non-empty list"}
-        self.event_hub.handle_unsubscribe(caller_id, events)
-        return {"ok": True}
+            raise ValueError("events must be a non-empty list")
+        return self.event_hub.handle_unsubscribe(caller_id, events)
 
     # ── Builtin handlers: kernel.* ──
 
@@ -335,7 +403,16 @@ class RpcRouter:
         return {"pong": True, "timestamp": datetime.now(timezone.utc).isoformat()}
 
     async def _kernel_stats(self, caller_id: str, params: dict) -> dict:
-        return self.event_hub.get_stats()
+        event_stats = self.event_hub.get_stats()
+        return {
+            **event_stats,
+            "rpc": {
+                "total": self._rpc_total,
+                "builtin": self._rpc_builtin,
+                "forwarded": self._rpc_forwarded,
+                "errors": self._rpc_errors
+            }
+        }
 
     async def _kernel_health(self, caller_id: str, params: dict) -> dict:
         eh_health = self.event_hub.get_health()
@@ -349,6 +426,34 @@ class RpcRouter:
             "event_stats": eh_health.get("details", {}),
         }
 
+    async def _kernel_latencies(self, caller_id: str, params: dict) -> dict:
+        """Get ping/pong latencies for all connected modules.
+
+        Returns:
+            {
+                "latencies": {
+                    "module1": {
+                        "outbound": 12.34,  # ms, Kernel → module
+                        "inbound": 23.45,   # ms, module → Kernel
+                        "status": "ok" | "timeout" | "never"
+                    },
+                    ...
+                }
+            }
+        """
+        result = {}
+        for module_id in self.kernel_server.connections.keys():
+            latency_data = self.kernel_server._pong_latencies.get(module_id, {})
+            status = self.kernel_server._pong_status.get(module_id, "never")
+
+            result[module_id] = {
+                "outbound": latency_data.get("outbound"),
+                "inbound": latency_data.get("inbound"),
+                "status": status,
+            }
+
+        return {"latencies": result}
+
     async def _kernel_generate_tokens(self, caller_id: str, params: dict) -> dict:
         """Generate tokens for a list of module names.
 
@@ -356,15 +461,15 @@ class RpcRouter:
             params: {"modules": ["mod1", "mod2", ...]}
 
         Returns:
-            {"ok": True, "tokens": {"mod1": "token1", "mod2": "token2", ...}}
+            {"tokens": {"mod1": "token1", "mod2": "token2", ...}}
         """
         # Only Launcher may request token generation
         if caller_id != "launcher":
-            return {"ok": False, "error": "Only Launcher may generate tokens"}
+            raise PermissionError("Only Launcher may generate tokens")
 
         modules = params.get("modules", [])
         if not isinstance(modules, list):
-            return {"ok": False, "error": "modules must be a list"}
+            raise ValueError("modules must be a list")
 
         import secrets
         tokens = {}
@@ -374,25 +479,13 @@ class RpcRouter:
         # Register tokens in registry
         self.registry.register_tokens(tokens)
 
-        return {"ok": True, "tokens": tokens}
+        return {"tokens": tokens}
 
     async def _kernel_register_tokens(self, caller_id: str, params: dict) -> dict:
         # Only Launcher may register tokens
         if caller_id != "launcher":
-            return {"ok": False, "error": "Only Launcher may register tokens"}
+            raise PermissionError("Only Launcher may register tokens")
         self.registry.register_tokens(params)
-        return {"ok": True}
-
-    async def _kernel_shutdown(self, caller_id: str, params: dict) -> dict:
-        """Shutdown Kernel. Only Launcher may call this."""
-        if caller_id != "launcher":
-            return {"ok": False, "error": "Only Launcher may shutdown Kernel"}
-
-        print("[kernel] Received shutdown request from Launcher")
-
-        # Schedule shutdown (don't block RPC response)
-        if self.kernel_server:
-            asyncio.create_task(self.kernel_server.shutdown())
+        return {}
 
-        return {"ok": True}