foxclaw 0.1.0 → 0.1.3

package/python/foxclaw/kernel/sentinel.py

@@ -0,0 +1,443 @@
+"""Sentinel —— Foxclaw 的独立守门人进程(Muse「Harness/Sentinel 分离」的本地最小版)。
+
+背景:foxclaw 的动作裁决(skills.permission.evaluate)+ 统一门(kernel.policy_gate)此前都是
+**主 Agent 进程内的软件模块**。好处是零开销、易测;代价是:一旦 Agent 进程被 RCE,裁决逻辑、
+规则表、以及散落在 os.environ 里的真实凭证会一起暴露 —— 那是「用提示词约束模型」的残留,
+不是「用系统结构约束 Agent」。
+
+本模块把两件事挪出主进程,放进一个**独立进程**:
+  1. evaluate —— 动作裁决(纯函数,跨进程执行);
+  2. mint/redeem —— 凭证代注入(真实凭证只存在于守门人进程,主进程只拿一次性可撤销令牌,真值永不出进程);
+  3. mcp_register/mcp_call —— MCP 代执行(守门人持有 MCP server 配置与凭证,主进程只发意图)。
+
+跨平台:stdio JSON-lines(Windows 无 unix socket)。父进程 spawn 本进程经管道通信。
+默认关闭:不设 FOXCLAW_GUARDIAN=1 时,foxclaw 完全走原进程内路径,行为逐字不变。
+
+独立启动(部署到常开机时也可这样常驻): python -m foxclaw.kernel.sentinel
+"""
+from __future__ import annotations
+
+import json
+import os
+import secrets
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+
+def load_vault() -> dict:
+    vault: dict = {}
+    prefix = "FOXCLAW_GUARDIAN_SECRET_"
+    for k, v in os.environ.items():
+        if k.startswith(prefix) and v:
+            vault[k[len(prefix):].lower()] = v
+    path = os.environ.get("FOXCLAW_GUARDIAN_SECRETS", "").strip()
+    if path and Path(path).exists():
+        try:
+            d = json.loads(Path(path).read_text(encoding="utf-8"))
+            if isinstance(d, dict):
+                vault.update({str(k).lower(): v for k, v in d.items()})
+        except Exception:
+            pass
+    return vault
+
+
+def _mcp_servers_path() -> str:
+    """守门人侧 MCP 配置持久化文件。优先 FOXCLAW_GUARDIAN_MCP_SERVERS 显式指定;
+    否则用 FOXCLAW_GUARDIAN_DATA_DIR 下的 mcp_guardian_servers.json。主进程的 mcp_servers.json 已不含 headers。"""
+    p = os.environ.get("FOXCLAW_GUARDIAN_MCP_SERVERS", "").strip()
+    if p:
+        return p
+    d = os.environ.get("FOXCLAW_GUARDIAN_DATA_DIR", "").strip()
+    if d:
+        return str(Path(d) / "mcp_guardian_servers.json")
+    return ""
+
+
+def load_mcp_servers() -> dict:
+    servers: dict = {}
+    path = _mcp_servers_path()
+    if not path or not Path(path).exists():
+        return servers
+    try:
+        d = json.loads(Path(path).read_text(encoding="utf-8"))
+        for c in d.get("servers", []) or []:
+            sid = str(c.get("id", "")).strip()
+            if not sid:
+                continue
+            servers[sid] = {
+                "name": c.get("name") or sid,
+                "url": c.get("url", ""),
+                "headers": dict(c.get("headers") or {}),
+                "transport": c.get("transport") or "streamable_http",
+            }
+    except Exception:
+        pass
+    return servers
+
+
+def _persist_mcp_servers(servers: dict) -> None:
+    path = _mcp_servers_path()
+    if not path:
+        return
+    try:
+        out = {"servers": [dict(v) for v in servers.values()]}
+        Path(path).parent.mkdir(parents=True, exist_ok=True)
+        tmp = Path(path).with_suffix(".tmp")
+        tmp.write_text(json.dumps(out, ensure_ascii=False, indent=1), encoding="utf-8")
+        tmp.replace(Path(path))
+    except Exception:
+        pass
+
+
+class TokenStore:
+    def __init__(self, default_ttl: float = 60.0):
+        self._default_ttl = default_ttl
+        self._tokens: dict = {}
+
+    def mint(self, ref: str, ttl: float | None = None) -> dict:
+        """为某 ref 签发能力令牌。返回 {token, expires_in},绝不返回真值。"""
+        ttl = ttl if ttl is not None else self._default_ttl
+        token = secrets.token_urlsafe(32)
+        self._tokens[token] = {
+            "ref": ref,
+            "expires_at": time.monotonic() + ttl,
+            "used": False,
+            "revoked": False,
+        }
+        return {"token": token, "expires_in": ttl}
+
+    def redeem(self, token: str):
+        """一次性兑换:返回绑定的 ref 并立即作废。无效/过期/已用/已撤销 → None。"""
+        rec = self._tokens.get(token or "")
+        if rec is None or rec["revoked"] or rec["used"]:
+            return None
+        if time.monotonic() > rec["expires_at"]:
+            self._tokens.pop(token, None)
+            return None
+        rec["used"] = True
+        return rec["ref"]
+
+    def revoke(self, token: str) -> bool:
+        """主动撤销。返回是否真的撤销了一个活跃令牌。"""
+        rec = self._tokens.get(token or "")
+        if rec is None or rec["used"] or rec["revoked"]:
+            return False
+        rec["revoked"] = True
+        return True
+
+
+def _rebuild_skill(sd: dict):
+    """主进程只传 evaluate 需要的字段 + 已算好的 trust。重建为鸭子类型对象。"""
+    from types import SimpleNamespace
+    trust = sd.get("trust", "low")
+    return SimpleNamespace(
+        id=sd.get("id", ""),
+        kind=sd.get("kind", "local"),
+        side_effect=sd.get("side_effect", "write"),
+        destructive=bool(sd.get("destructive", False)),
+        external=bool(sd.get("external", False)),
+        read_only=sd.get("read_only", None),
+        params=sd.get("params", {}) or {},
+        trust_level=lambda trust=trust: trust,
+    )
+
+
+def _rebuild_rules(rd: dict):
+    from foxclaw.skills.permission import PermissionRules
+    return PermissionRules(
+        deny=list(rd.get("deny") or []),
+        ask=list(rd.get("ask") or []),
+        allow=list(rd.get("allow") or []),
+    )
+
+
+def _handle_evaluate(msg: dict) -> dict:
+    from foxclaw.skills.permission import evaluate
+    skill = _rebuild_skill(msg.get("skill") or {})
+    rules = _rebuild_rules(msg.get("rules") or {})
+    d = evaluate(
+        skill, msg.get("args") or {}, rules=rules,
+        confirmed=bool(msg.get("confirmed")),
+        mode=msg.get("mode", "strict"),
+        taint_level=int(msg.get("taint_level", 0)),
+        taint_threshold=int(msg.get("taint_threshold", 0)),
+    )
+    return d.to_dict()
+
+
+def _handle_mint(msg: dict, vault: dict, store: TokenStore) -> dict:
+    ref = str(msg.get("ref", "")).lower()
+    if not ref:
+        return {"error": "missing ref"}
+    if ref not in vault:
+        return {"error": f"unknown secret ref: {ref}"}
+    ttl = msg.get("ttl")
+    ttl = float(ttl) if ttl else None
+    out = store.mint(ref, ttl)
+    print(f"[Sentinel] mint {ref}", file=sys.stderr, flush=True)
+    return out
+
+
+def _handle_revoke(msg: dict, store: TokenStore) -> dict:
+    token = str(msg.get("token", "") or "")
+    if not token:
+        return {"error": "missing token"}
+    ok = store.revoke(token)
+    print(f"[Sentinel] revoke {'ok' if ok else 'miss'}", file=sys.stderr, flush=True)
+    return {"revoked": ok}
+
+
+def _handle_mcp_register(msg: dict, servers: dict) -> dict:
+    """主进程推送 MCP server 配置给守门人,全量同步。headers 非空则覆盖、为空则保留旧值:
+    第4步起主进程不长期持有 headers(日常只推元数据),仅在 add_server 那一次临时带 headers。
+    凭证只在守门人进程内,主进程之后只发意图(server_id + tool + args)。"""
+    items = msg.get("servers") or []
+    new_servers: dict = {}
+    for c in items:
+        sid = str(c.get("id", "")).strip()
+        if not sid:
+            continue
+        headers = dict(c.get("headers") or {})
+        old = servers.get(sid)
+        if not headers and old:
+            headers = dict(old.get("headers") or {})
+        new_servers[sid] = {
+            "name": c.get("name") or sid,
+            "url": c.get("url", ""),
+            "headers": headers,
+            "transport": c.get("transport") or "streamable_http",
+        }
+    servers.clear()
+    servers.update(new_servers)
+    _persist_mcp_servers(servers)
+    print(f"[Sentinel] mcp_register {len(servers)} servers", file=sys.stderr, flush=True)
+    return {"count": len(servers)}
+
+
+def _handle_mcp_call(msg: dict, servers: dict) -> dict:
+    """mcp 代执行:守门人进程持有 MCP server 配置(含凭证),在进程内调用 MCP,返回 SkillResult.to_dict()。
+    主进程只传意图(server_id + tool + args),拿不到凭证、不直连外部。"""
+    from foxclaw.skills import SkillResult, _mark_untrusted
+
+    skill_id = msg.get("skill_id", "mcp")
+    server_id = str(msg.get("server_id", "") or "")
+    tool = str(msg.get("tool", "") or "")
+    args = dict(msg.get("args") or {})
+
+    if not server_id or not tool:
+        return SkillResult(skill_id, False, status="not_connected",
+                           message="未配置 MCP server/tool").to_dict()
+    cfg = servers.get(server_id)
+    if cfg is None:
+        return SkillResult(skill_id, False, status="not_connected",
+                           message=f"MCP server「{server_id}」未在守门人注册").to_dict()
+
+    try:
+        from foxclaw.skills.mcp_client import _get_bridge, _amcp_call_tool
+        out = _get_bridge().run(_amcp_call_tool(
+            cfg["url"], dict(cfg.get("headers") or {}), cfg["transport"], tool, args))
+        if out.get("isError"):
+            return SkillResult(skill_id, False, status="blocked",
+                               message=f"MCP 工具返回错误: {out.get('content') or 'unknown'}").to_dict()
+        out = _mark_untrusted(out)
+        print(f"[Sentinel] mcp_call {server_id}.{tool}", file=sys.stderr, flush=True)
+        return SkillResult(skill_id, True, output=out,
+                           message="MCP 调用完成(外部不可信数据)").to_dict()
+    except Exception as e:
+        return SkillResult(skill_id, False, status="blocked",
+                           message=f"MCP 调用失败: {e}").to_dict()
+
+
+def _serialize_tool(tool) -> dict:
+    """把 mcp.types.Tool 序列化为纯 dict(跨进程 JSON 可传)。annotations 决定 side_effect/destructive。"""
+    ann = getattr(tool, "annotations", None)
+    return {
+        "name": getattr(tool, "name", "") or "",
+        "description": getattr(tool, "description", "") or "",
+        "inputSchema": getattr(tool, "inputSchema", {}) or {},
+        "annotations": {
+            "readOnlyHint": getattr(ann, "readOnlyHint", None) if ann else None,
+            "destructiveHint": getattr(ann, "destructiveHint", None) if ann else None,
+        },
+    }
+
+
+def _handle_mcp_list_tools(msg: dict, servers: dict) -> dict:
+    """发现阶段代执行:守门人用自己持有的 headers 连外部 MCP 拉工具列表,序列化为 dict 列表返回。
+    主进程不碰 headers、不直连外部;工具注解(side_effect/destructive)也由守门人侧真实返回。"""
+    server_id = str(msg.get("server_id", "") or "")
+    cfg = servers.get(server_id)
+    if cfg is None:
+        return {"error": f"MCP server「{server_id}」未在守门人注册"}
+    try:
+        from foxclaw.skills.mcp_client import _get_bridge, _amcp_list_tools
+        tools = _get_bridge().run(_amcp_list_tools(
+            cfg["url"], dict(cfg.get("headers") or {}), cfg["transport"]))
+        out = [_serialize_tool(t) for t in tools]
+        print(f"[Sentinel] mcp_list_tools {server_id} -> {len(out)} tools", file=sys.stderr, flush=True)
+        return {"tools": out}
+    except Exception as e:
+        return {"error": f"list_tools 失败: {e}"}
+
+
+def _inject_secret(headers: dict, args: dict, auth_scheme: str, secret: str) -> None:
+    """按 auth_scheme 把真凭证注入请求(只在守门人进程内,真值不出进程)。
+    bearer / header:<name> / query:<name>;空或未知 → 不注入(调用方未声明注入方式)。"""
+    scheme = (auth_scheme or "").strip()
+    if scheme == "bearer":
+        headers["Authorization"] = f"Bearer {secret}"
+    elif scheme.startswith("header:"):
+        headers[scheme[len("header:"):]] = secret
+    elif scheme.startswith("query:"):
+        args[scheme[len("query:"):]] = secret
+
+
+def _handle_execute_web(msg: dict, vault: dict, store: TokenStore) -> dict:
+    """web_api 代执行:守门人进程注入真凭证后发 HTTP,返回 SkillResult.to_dict()。
+    凭证来源优先级:一次性能力令牌(token,先 redeem) > 直接 ref(兼容第 1 步)。
+    真值只在守门人进程内从 vault 取,永不出进程。"""
+    from foxclaw.skills import SkillResult
+    from foxclaw.skills import ssrf_check
+
+    skill_id = msg.get("skill_id", "web_api")
+    endpoint = msg.get("endpoint", "")
+    method = (msg.get("method") or "GET").upper()
+    token = str(msg.get("token", "") or "")
+    secret_ref = str(msg.get("secret_ref", "")).lower()
+    auth_scheme = msg.get("auth_scheme", "bearer") or "bearer"
+    args = dict(msg.get("args") or {})
+    loc = msg.get("param_location", "auto")
+    timeout = float(msg.get("timeout", 10.0))
+    allow_local = bool(msg.get("allow_local", False))
+
+    if not endpoint:
+        return SkillResult(skill_id, False, status="not_connected",
+                           message="未配置 endpoint").to_dict()
+
+    secret = None
+    used_ref = None
+    if token:
+        ref = store.redeem(token)
+        if ref is None:
+            return SkillResult(skill_id, False, status="blocked",
+                               message="能力令牌无效/已过期/已使用/已撤销").to_dict()
+        secret = vault.get(ref)
+        used_ref = ref
+        if secret is None:
+            return SkillResult(skill_id, False, status="blocked",
+                               message=f"令牌绑定的凭证 ref「{ref}」已不在 vault 中").to_dict()
+    elif secret_ref:
+        secret = vault.get(secret_ref)
+        used_ref = secret_ref
+        if secret is None:
+            return SkillResult(skill_id, False, status="blocked",
+                               message=f"凭证 ref「{secret_ref}」未在守门人 vault 中配置").to_dict()
+
+    block = ssrf_check(endpoint, allow_local=allow_local)
+    if block:
+        return SkillResult(skill_id, False, status="blocked",
+                           message=f"端点被安全策略拒绝: {block}").to_dict()
+
+    headers = {"User-Agent": "Foxclaw/1.0"}
+    if secret is not None:
+        _inject_secret(headers, args, auth_scheme, secret)
+
+    if loc == "auto":
+        loc = "query" if method in ("GET", "DELETE") else "json"
+
+    try:
+        import httpx
+    except ImportError:
+        return SkillResult(skill_id, False, status="blocked",
+                           message="缺少 httpx 依赖,无法发起 Web API 调用").to_dict()
+
+    req_kwargs: dict[str, Any] = {"headers": headers, "timeout": timeout, "follow_redirects": False}
+    if loc == "query":
+        req_kwargs["params"] = args
+    else:
+        req_kwargs["json"] = args
+
+    try:
+        with httpx.Client() as client:
+            resp = client.request(method, endpoint, **req_kwargs)
+    except httpx.TimeoutException:
+        return SkillResult(skill_id, False, status="timeout",
+                           message=f"Web API 调用超时(>{timeout}s)").to_dict()
+    except httpx.RequestError as e:
+        return SkillResult(skill_id, False, status="blocked",
+                           message=f"Web API 请求失败: {e}").to_dict()
+
+    if 300 <= resp.status_code < 400:
+        return SkillResult(skill_id, False, status="blocked",
+                           message=f"Web API 返回重定向 HTTP {resp.status_code}(已阻止跟随)").to_dict()
+    if resp.status_code >= 400:
+        return SkillResult(skill_id, False, status="blocked",
+                           message=f"Web API 返回 HTTP {resp.status_code}",
+                           output={"status_code": resp.status_code, "body": resp.text[:500]}).to_dict()
+    try:
+        data = resp.json()
+    except Exception:
+        data = {"text": resp.text[:2000]}
+    print(f"[Sentinel] execute_web {method} {endpoint} ref={used_ref or '-'}", file=sys.stderr, flush=True)
+    return SkillResult(skill_id, True, status="done",
+                       output={"status_code": resp.status_code, "data": data},
+                       message=f"Web API 调用成功(HTTP {resp.status_code})").to_dict()
+
+
+def _reply(resp: dict) -> None:
+    sys.stdout.write(json.dumps(resp, ensure_ascii=False) + "\n")
+    sys.stdout.flush()
+
+
+def serve_stdio(vault: dict, store: TokenStore, servers: dict) -> None:
+    """JSON-lines 循环:stdin 读一行请求 → stdout 回一行响应。父进程退出(stdin 关闭)时自然结束。"""
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            msg = json.loads(line)
+        except Exception:
+            _reply({"id": None, "ok": False, "error": "bad json"})
+            continue
+        mid = msg.get("id")
+        op = msg.get("op")
+        try:
+            result: dict[str, object]
+            if op == "ping":
+                result = {"pong": True}
+            elif op == "evaluate":
+                result = _handle_evaluate(msg)
+            elif op == "mint":
+                result = _handle_mint(msg, vault, store)
+            elif op == "revoke":
+                result = _handle_revoke(msg, store)
+            elif op == "mcp_register":
+                result = _handle_mcp_register(msg, servers)
+            elif op == "mcp_call":
+                result = _handle_mcp_call(msg, servers)
+            elif op == "mcp_list_tools":
+                result = _handle_mcp_list_tools(msg, servers)
+            elif op == "execute_web":
+                result = _handle_execute_web(msg, vault, store)
+            elif op == "shutdown":
+                _reply({"id": mid, "ok": True, "result": {"bye": True}})
+                return
+            else:
+                result = {"error": f"unknown op: {op}"}
+            _reply({"id": mid, "ok": True, "result": result})
+        except Exception as e:
+            _reply({"id": mid, "ok": False, "error": str(e)})
+
+
+def main(argv=None) -> None:
+    vault = load_vault()
+    store = TokenStore()
+    servers = load_mcp_servers()
+    serve_stdio(vault, store, servers)
+
+
+if __name__ == "__main__":
+    main()

package/python/foxclaw/kernel/sentinel_client.py

@@ -0,0 +1,243 @@
+"""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:
+    return str(Path(__file__).resolve().parents[2])
+
+
+class SentinelClient:
+    def __init__(self, timeout: float = 5.0, cmd=None, data_dir: str | None = None):
+        self._timeout = timeout
+        self._data_dir = data_dir
+        self._lock = threading.Lock()
+        self._req_id = 0
+        self._proc: subprocess.Popen[str] | None = 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
+
+    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:
+                proc = self._proc
+                if proc is None or proc.stdin is None or proc.stdout is None:
+                    raise SentinelUnavailable("守门人进程未启动")
+                proc.stdin.write(msg + "\n")
+                proc.stdin.flush()
+                line = 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")
+
+    @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:
+            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 = None):
+        """为 ref 签发一次性能力令牌。返回 token(绝不返回真值);失败返回 None。"""
+        payload: dict[str, object] = {"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