foxclaw 0.1.0 → 0.1.2

package/python/foxclaw/kernel/sentinel_client.py

@@ -0,0 +1,246 @@
+"""SentinelClient —— 主进程侧与守门人进程通信的 IPC 客户端。
+
+用 stdio JSON-lines 与 foxclaw.kernel.sentinel 子进程通信。线程安全(串行锁),超时 fail-closed。
+evaluate 的签名与 skills.permission.evaluate 对齐,返回重建的 PermissionDecision(而非原始 dict),
+因此可直接注入 kernel.policy_gate 的 action_evaluator,PolicyGate / SkillAdapter 零改动。
+
+fail-closed 语义:守门人进程不可达(启动失败/超时/崩溃)时,evaluate 返回 deny —— 宁可拦错
+不漏放,绝不静默降级回「进程内放行」。mint 失败返回 None,execute_web 失败返回 blocked。
+"""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import threading
+from pathlib import Path
+
+
+class SentinelUnavailable(RuntimeError):
+    pass
+
+
+def _project_root() -> str:
+    # foxclaw/kernel/sentinel_client.py → parents[0]=kernel, [1]=foxclaw, [2]=Foxclaw
+    return str(Path(__file__).resolve().parents[2])
+
+
+class SentinelClient:
+    def __init__(self, timeout: float = 5.0, cmd=None, data_dir: str = None):
+        self._timeout = timeout
+        self._data_dir = data_dir
+        self._lock = threading.Lock()
+        self._req_id = 0
+        self._proc = None
+        self._spawn(cmd)
+
+    # ── 进程生命周期 ─────────────────────────────────────────
+    def _spawn(self, cmd) -> None:
+        if cmd is None:
+            cmd = [sys.executable, "-m", "foxclaw.kernel.sentinel"]
+        try:
+            env = dict(os.environ)
+            if self._data_dir:
+                env["FOXCLAW_GUARDIAN_DATA_DIR"] = str(self._data_dir)
+            self._proc = subprocess.Popen(
+                cmd, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+                stderr=subprocess.DEVNULL, text=True, encoding="utf-8",
+                errors="replace", bufsize=1, cwd=_project_root(), env=env)
+        except Exception as e:
+            raise RuntimeError(f"Sentinel 启动失败: {e}")
+        try:
+            self._request("ping", {})  # 握手:启动失败/坏路径在此显式报错,不静默降级
+        except Exception as e:
+            self._kill()
+            raise RuntimeError(f"Sentinel 握手失败: {e}")
+
+    def _kill(self) -> None:
+        if self._proc is not None:
+            try:
+                self._proc.kill()
+            except Exception:
+                pass
+
+    def close(self) -> None:
+        if self._proc is not None and self._proc.poll() is None:
+            try:
+                self._request("shutdown", {})
+            except Exception:
+                pass
+            try:
+                self._proc.terminate()
+            except Exception:
+                pass
+
+    # ── IPC 核心 ─────────────────────────────────────────────
+    def _request(self, op: str, payload: dict):
+        with self._lock:
+            self._req_id += 1
+            mid = self._req_id
+            msg = json.dumps({"id": mid, "op": op, **payload}, ensure_ascii=False)
+            try:
+                self._proc.stdin.write(msg + "\n")
+                self._proc.stdin.flush()
+                line = self._proc.stdout.readline()
+            except Exception as e:
+                raise SentinelUnavailable(f"IPC 通信失败: {e}")
+            if not line:
+                raise SentinelUnavailable("守门人进程已退出")
+            try:
+                resp = json.loads(line)
+            except Exception:
+                raise SentinelUnavailable("守门人返回非法 JSON")
+            if not resp.get("ok"):
+                raise SentinelUnavailable(resp.get("error", "unknown error"))
+            return resp.get("result")
+
+    # ── 序列化(只传 evaluate 需要的字段,不含 handler/凭证)────
+    @staticmethod
+    def _serialize_skill(skill) -> dict:
+        _tl = getattr(skill, "trust_level", None)
+        try:
+            trust = _tl() if callable(_tl) else "low"
+        except Exception:
+            trust = "low"
+        return {
+            "id": getattr(skill, "id", ""),
+            "kind": getattr(skill, "kind", "local"),
+            "side_effect": getattr(skill, "side_effect", "write"),   # 未声明 → 有副作用
+            "destructive": bool(getattr(skill, "destructive", False)),
+            "external": bool(getattr(skill, "external", False)),
+            "read_only": getattr(skill, "read_only", None),
+            "params": getattr(skill, "params", {}) or {},
+            "trust": trust,
+        }
+
+    @staticmethod
+    def _serialize_rules(rules) -> dict:
+        if rules is None:
+            return {}
+        return {
+            "deny": list(getattr(rules, "deny", []) or []),
+            "ask": list(getattr(rules, "ask", []) or []),
+            "allow": list(getattr(rules, "allow", []) or []),
+        }
+
+    # ── 对外接口 ─────────────────────────────────────────────
+    def evaluate(self, skill, args, rules=None, confirmed=False, mode="strict",
+                 taint_level=0, taint_threshold=0):
+        """动作裁决(跨进程)。签名对齐 skills.permission.evaluate,返回 PermissionDecision。"""
+        from foxclaw.skills.permission import PermissionDecision
+        payload = {
+            "skill": self._serialize_skill(skill),
+            "args": args or {},
+            "rules": self._serialize_rules(rules),
+            "confirmed": bool(confirmed),
+            "mode": mode,
+            "taint_level": taint_level,
+            "taint_threshold": taint_threshold,
+        }
+        try:
+            d = self._request("evaluate", payload)
+        except SentinelUnavailable as e:
+            # fail-closed:守门人不可达 → deny,绝不降级放行
+            return PermissionDecision("deny", 0,
+                                      reason=f"守门人不可达(fail-closed): {e}",
+                                      reason_code="SENTINEL_UNAVAILABLE")
+        return PermissionDecision(
+            decision=d.get("decision", "deny"),
+            stage=int(d.get("stage", 0)),
+            reason=d.get("reason", ""),
+            trust_downgrade=bool(d.get("trust_downgrade", False)),
+            requires_confirmation=bool(d.get("requires_confirmation", False)),
+            reason_code=d.get("reason_code", ""),
+        )
+
+    def mint(self, ref: str, ttl: float = None):
+        """为 ref 签发一次性能力令牌。返回 token(绝不返回真值);失败返回 None。"""
+        payload = {"ref": ref}
+        if ttl is not None:
+            payload["ttl"] = ttl
+        try:
+            return self._request("mint", payload).get("token")
+        except SentinelUnavailable:
+            return None
+
+    def revoke(self, token: str) -> bool:
+        """主动撤销令牌。返回是否真的撤销了一个活跃令牌;失败返回 False。"""
+        try:
+            return bool(self._request("revoke", {"token": token}).get("revoked"))
+        except SentinelUnavailable:
+            return False
+
+    def mcp_register(self, servers: list) -> bool:
+        """把 MCP server 配置(含 headers 凭证)推送给守门人,覆盖式更新。失败返回 False。"""
+        try:
+            d = self._request("mcp_register", {"servers": list(servers or [])})
+            return isinstance(d, dict) and int(d.get("count", 0)) >= 0
+        except SentinelUnavailable:
+            return False
+
+    def mcp_call(self, skill, args) -> dict:
+        """mcp 代执行:主进程只传意图(server_id + tool + args),守门人持有凭证并调用。
+        返回 SkillResult.to_dict()。fail-closed:守门人不可达 → blocked(绝不落到主进程直连外部)。"""
+        from foxclaw.skills import SkillResult
+        skill_id = getattr(skill, "id", "")
+        payload = {
+            "skill_id": skill_id,
+            "server_id": getattr(skill, "mcp_server", "") or "",
+            "tool": getattr(skill, "mcp_tool", "") or "",
+            "args": args or {},
+        }
+        try:
+            d = self._request("mcp_call", payload)
+        except SentinelUnavailable as e:
+            return SkillResult(skill_id, False, status="blocked",
+                               message=f"守门人不可达(fail-closed): {e}").to_dict()
+        if not isinstance(d, dict):
+            return SkillResult(skill_id, False, status="blocked",
+                               message="守门人返回异常").to_dict()
+        return d
+
+    def mcp_list_tools(self, server_id: str):
+        """发现阶段代执行:守门人用自己持有的 headers 连外部 MCP 拉工具,返回序列化后的
+        dict 列表(每项含 name/description/inputSchema/annotations)。失败抛 SentinelUnavailable(带具体错误)。"""
+        d = self._request("mcp_list_tools", {"server_id": server_id})
+        if not isinstance(d, dict) or "tools" not in d:
+            err = d.get("error") if isinstance(d, dict) else "list_tools 失败"
+            raise SentinelUnavailable(f"守门人 list_tools 失败: {err}")
+        return list(d["tools"])
+
+    def execute_web(self, skill, args) -> dict:
+        """web_api 代执行:先 mint 一次性令牌,守门人 redeem 后注入真凭证发请求。
+        返回 SkillResult.to_dict()(同状态语义),供 SkillAdapter._invoke_web_via_sentinel 重建。
+        fail-closed:守门人不可达/令牌签发失败 → blocked(绝不落到主进程直发,否则凭证/SSRF 双失守)。"""
+        from foxclaw.skills import SkillResult
+        skill_id = getattr(skill, "id", "")
+        secret_ref = getattr(skill, "secret_ref", "") or ""
+
+        token = None
+        if secret_ref:
+            token = self.mint(secret_ref)
+            if not token:
+                return SkillResult(skill_id, False, status="blocked",
+                                   message="签发凭证能力令牌失败(fail-closed)").to_dict()
+
+        payload = {
+            "skill_id": skill_id,
+            "endpoint": getattr(skill, "endpoint", ""),
+            "method": getattr(skill, "http_method", "GET"),
+            "token": token or "",
+            "auth_scheme": getattr(skill, "auth_scheme", "bearer") or "bearer",
+            "param_location": getattr(skill, "param_location", "auto"),
+            "timeout": float(getattr(skill, "timeout", 10.0)),
+            "allow_local": bool(getattr(skill, "allow_local", False)),
+            "args": args or {},
+        }
+        try:
+            d = self._request("execute_web", payload)
+        except SentinelUnavailable as e:
+            return SkillResult(skill_id, False, status="blocked",
+                               message=f"守门人不可达(fail-closed): {e}").to_dict()
+        if not isinstance(d, dict):
+            return SkillResult(skill_id, False, status="blocked",
+                               message="守门人返回异常").to_dict()
+        return d

package/python/foxclaw/kernel/spine.py

@@ -0,0 +1,97 @@
+"""
+EventSpine —— 全系统唯一的进程内事件脊柱(P0 第二项:统一事件总线)。
+
+审计结论:此前 4 套并存且不互通的发布订阅(HarnessEventBus / SystemBus /
+HKC EventBus / steering_queue),WS 只桥接了 harness 一套 → truth/process 等
+系统事件根本到不了前端。EventSpine 把它们收敛成一条脊柱 + 若干"投影"(projection):
+WS / CLI / robot / edge 都只是订阅脊柱的投影,不再各自接线。
+
+设计:
+  · 主题(topic)用 `domain.entity.action` 命名;subscribe 支持**前缀匹配**
+    (订阅 "harness" 命中 "harness.drift.blocked";订阅 "" 命中一切)。
+  · project(sink):sink 收到**每一条**事件(WS/robot/edge 的统一出口)。
+  · 并发纪律与 SystemBus 一致:锁只护 history + 订阅表快照,handler 在锁外执行,
+    保证全局锁序恒为 spine→(pm/hmr),无反向嵌套 → 无死锁。
+  · Event 刻意提供 .channel/.payload/.to_dict(),与旧 BusMessage 同形,
+    使 SystemBus 可退化为本脊柱的薄门面而不改任何既有消费者。
+"""
+from __future__ import annotations
+import threading
+import time
+import uuid
+from collections import deque
+from dataclasses import dataclass, field
+from typing import Callable, Optional
+
+
+@dataclass
+class Event:
+    topic: str
+    payload: dict
+    ts: float = field(default_factory=time.time)
+    source: str = ""
+    correlation_id: str = field(default_factory=lambda: uuid.uuid4().hex[:12])
+
+    # ── 与旧 BusMessage 同形,便于 SystemBus 无痛门面化 ──
+    @property
+    def channel(self) -> str:
+        return self.topic
+
+    def to_dict(self) -> dict:
+        return {"channel": self.topic, "topic": self.topic, "payload": self.payload,
+                "ts": self.ts, "source": self.source, "correlation_id": self.correlation_id}
+
+
+class EventSpine:
+    """进程内唯一事件脊柱。发布/订阅(前缀匹配) + 投影 + 有界历史。线程安全。"""
+
+    def __init__(self, history_limit: int = 1000):
+        self._subs: list[tuple[str, Callable]] = []      # (topic_prefix, handler)
+        self._projections: list[Callable] = []           # 每条事件都收到
+        self._history: deque = deque(maxlen=history_limit)
+        self._lock = threading.RLock()
+
+    def subscribe(self, topic_prefix: str, handler: Callable):
+        """订阅某主题(前缀匹配)。handler(event) 在发布线程、锁外被调用。"""
+        with self._lock:
+            self._subs.append((topic_prefix or "", handler))
+
+    def project(self, sink: Callable):
+        """注册投影:每一条事件都会送给 sink(event)。用于 WS / robot / edge 统一出口。"""
+        with self._lock:
+            self._projections.append(sink)
+
+    def publish(self, topic: str, payload: dict = None, source: str = "",
+                correlation_id: str = None) -> Event:
+        evt = Event(topic=topic, payload=payload or {}, source=source,
+                    **({"correlation_id": correlation_id} if correlation_id else {}))
+        with self._lock:
+            self._history.append(evt)
+            # 锁内只做"快照",handler/sink 在锁外执行(避免与 pm/hmr 锁形成环)
+            handlers = [h for pfx, h in self._subs if topic.startswith(pfx)]
+            projections = list(self._projections)
+        for h in handlers:
+            try:
+                h(evt)
+            except Exception as e:
+                print(f"[EventSpine] handler error on '{topic}': {e}")
+        for sink in projections:
+            try:
+                sink(evt)
+            except Exception as e:
+                print(f"[EventSpine] projection error on '{topic}': {e}")
+        return evt
+
+    def history(self, topic_prefix: Optional[str] = None, limit: int = 50) -> list:
+        with self._lock:
+            items = [e for e in self._history
+                     if topic_prefix is None or e.topic.startswith(topic_prefix)]
+        return [e.to_dict() for e in items[-limit:]]
+
+    def stats(self) -> dict:
+        with self._lock:
+            # 【P4-2】补 history_limit(deque.maxlen):只报 history_size 无法判断「是否已满」。
+            return {"subscriptions": len(self._subs),
+                    "projections": len(self._projections),
+                    "history_size": len(self._history),
+                    "history_limit": self._history.maxlen}