@agentunion/kite 1.3.1 → 1.4.0

package/kernel/registry_store.py

@@ -24,6 +24,7 @@ class RegistryStore:
         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,58 +58,112 @@ 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 ttl, heartbeat_interval, and 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"] = "online"
+        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 {"ttl": self.ttl, "heartbeat_interval": self.heartbeat_interval, "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}
+        # Update global timestamp
+        self.last_update_time = time.time()
+        return {}
 
     def heartbeat(self, module_id: str) -> dict:
-        """Renew heartbeat for a module."""
+        """Renew heartbeat for a module. Returns empty dict on success, raises exception on failure."""
         if module_id not in self.modules:
-            return {"ok": False, "error": "module not registered"}
+            raise KeyError(f"Module '{module_id}' not registered")
         self.heartbeats[module_id] = time.time()
-        self.modules[module_id]["status"] = "online"
-        return {"ok": True}
+        # Don't change status — heartbeat just keeps alive, doesn't upgrade state
+        return {}
+
+    def set_connected(self, module_id: str):
+        """Mark a module as connected (WS established, not yet registered).
+        Only upgrades from offline; doesn't downgrade from registered/ready."""
+        if module_id in self.modules:
+            if self.modules[module_id].get("status") == "offline":
+                self.modules[module_id]["status"] = "connected"
+
+    def set_ready(self, module_id: str):
+        """Mark a module as ready (received module.ready event)."""
+        if module_id in self.modules:
+            self.modules[module_id]["status"] = "ready"
 
     def set_offline(self, module_id: str):
-        """Mark a module as offline (called on WebSocket disconnect)."""
+        """Mark a module as offline (called after debounce on WebSocket disconnect)."""
         if module_id in self.modules:
             self.modules[module_id]["status"] = "offline"
 
+    def is_ready(self, module_id: str) -> bool:
+        """Check if a module is in ready state."""
+        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") != "offline":
+                if self.modules[mid].get("status") not in ("offline",):
                     self.modules[mid]["status"] = "offline"
                     expired.append(mid)
         return expired
@@ -160,17 +215,15 @@ 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():
-            if data.get("status") != "online":
+            if data.get("status") not in ("registered", "ready"):
                 continue
             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:
@@ -179,7 +232,6 @@ class RegistryStore:
                     results.append({
                         "field": fpath,
                         "module": mid,
-                        "api_endpoint": api_ep,
                         "value": fval,
                     })
             elif value:
@@ -188,14 +240,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,6 +73,12 @@ 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,
@@ -89,7 +95,6 @@ class RpcRouter:
             "kernel.health":          self._kernel_health,
             "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
@@ -124,15 +147,29 @@ class RpcRouter:
         if dot_idx > 0:
             target = method[:dot_idx]
             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):
@@ -237,64 +274,102 @@ 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})
-
-            # When Launcher registers, Kernel publishes its own module.ready
-            if mid == "launcher" and self.kernel_server:
-                if not self.kernel_server._ready_published:
-                    self.kernel_server.publish_ready()
-                    self.kernel_server._ready_published = True
-                    print(f"[kernel] launcher registered → kernel module.ready published")
+        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")
+
         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}'")
+
+        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_heartbeat(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 heartbeat for '{mid}'"}
+            raise PermissionError(f"Module '{caller_id}' cannot heartbeat for '{mid}'")
+
         return self.registry.heartbeat(mid)
 
     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.* ──
 
@@ -303,21 +378,26 @@ class RpcRouter:
         event_type = params.get("event", "")
         data = params.get("data")
         echo = params.get("echo", False)
+
+        # When a module publishes module.ready, update its status in registry
+        if event_type == "module.ready":
+            mid = (data or {}).get("module_id", caller_id)
+            self.registry.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.* ──
 
@@ -325,7 +405,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()
@@ -334,7 +423,7 @@ class RpcRouter:
             "module_count": len(self.registry.modules),
             "online_count": sum(
                 1 for m in self.registry.modules.values()
-                if m.get("status") == "online"
+                if m.get("status") in ("registered", "ready")
             ),
             "event_stats": eh_health.get("details", {}),
         }
@@ -346,15 +435,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 = {}
@@ -364,25 +453,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}