foxclaw 0.1.0 → 0.1.3

package/python/foxclaw/kernel/policy_gate.py

@@ -0,0 +1,108 @@
+"""
+PolicyGate —— 统一准入门(v2 ① Step4)。
+
+审计:系统有两个"门",分属不同策略域、返回不同裁决形状:
+  · Harness(推理漂移:语义/工具/范围)—— 内联在 _think,返回 HarnessResult(PASS/WARN/BLOCK);
+  · skill-guard(动作权限:destructive/trust/deny>ask>allow)—— 在 SkillAdapter.invoke,返回 PermissionDecision。
+
+PolicyGate 把它们统一到**一套 Verdict 词汇(allow/warn/deny/confirm)+ 一个接口**下:
+引擎实现不动(它们是策略实现),门面只做**归一化** + 动作路径的**统一 policy.decision 审计事件**。
+两条路都经门面走(pass-through:底层同一次 check/evaluate、同一结果 → 行为逐字不变)。
+
+不 import Harness/skills(避免 kernel→上层环):harness 作参数传入(鸭子类型);
+动作评估器 evaluate 由 Foxclaw **注入**。
+"""
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Any, Callable, Optional
+
+from ..core.governance_audit import new_decision_id
+
+
+@dataclass
+class Verdict:
+    allowed: bool
+    level: str
+    reason: str = ""
+    source: str = ""
+    raw: Any = None
+    decision_id: str = field(default="")
+
+
+class PolicyGate:
+    def __init__(self, spine=None, action_evaluator: Optional[Callable] = None,
+                 auditor=None):
+        self._spine = spine
+        self._eval = action_evaluator
+        self._auditor = auditor
+
+    @property
+    def auditor(self):
+        """SkillAdapter 经此取审计器,把执行终态关联到裁决 decision_id(P3-4 跨层关联)。"""
+        return self._auditor
+
+    def check_reasoning(self, harness, node) -> Verdict:
+        """经统一门做推理漂移准入。底层仍是那一次 harness.check(同一 HarnessResult),
+        Harness 自身已 emit harness_block/warn 事件,门面**不重复 emit**。行为一致。
+
+        【P1-2】非 allow(warn/deny)时另记一条 governance.decision(layer=harness)——
+        那是**统一审计流**的新增记录,不是重复 emit 既有 harness_* 事件;PASS 高频常态不记。"""
+        r = harness.check(node)
+        level = "deny" if r.is_blocked else ("warn" if r.is_warned else "allow")
+        v = Verdict(allowed=not r.is_blocked, level=level,
+                    reason=(r.reason or ""), source="harness", raw=r,
+                    decision_id=new_decision_id())
+        if level != "allow":
+            self._audit(v, actor=getattr(node, "agent_id", ""),
+                        action=f"reasoning:{getattr(node, 'type', '')}",
+                        detail={"node_id": getattr(node, "id", ""),
+                                "dominant_dim": getattr(r, "dominant_dim", "")})
+        return v
+
+    def check_action(self, skill, args: dict, rules=None,
+                     confirmed: bool = False, mode: str = "strict",
+                     taint_level: int = 0, taint_threshold: int = 0) -> Verdict:
+        """经统一门做动作权限准入。底层仍是 permission.evaluate(同一 PermissionDecision);
+        归一化为 Verdict,并对**非 allow**发统一 policy.decision.* 审计事件(动作路径原本无统一事件)。
+
+        【P3-4】每次裁决都带 decision_id(allow 也带——调用方 SkillAdapter 拿它做执行审计的
+        correlation_id,把「谁批准的」与「执行结果」join 起来)。
+
+        【污点门槛透传】taint_level/threshold 原样交给评估器。此前门面没接这两个参数,导致
+        permission.evaluate 的 Stage 3.5(碰过敏感数据 → 外发/副作用须确认)只有工具路径能触发,
+        技能路径永不触发。注入的评估器(permission.evaluate / sentinel.evaluate)签名都带这两个
+        kwarg;默认 0 = 关闭,既有调用方行为不变。"""
+        if self._eval is None:
+            return Verdict(True, "allow", "无动作评估器(降级放行)", "permission", None,
+                           decision_id=new_decision_id())
+        d = self._eval(skill, args, rules=rules, confirmed=confirmed, mode=mode,
+                       taint_level=taint_level, taint_threshold=taint_threshold)
+        level = {"allow": "allow", "ask": "confirm", "deny": "deny"}.get(d.decision, "deny")
+        v = Verdict(allowed=(d.decision == "allow"), level=level,
+                    reason=(d.reason or ""), source="permission", raw=d,
+                    decision_id=new_decision_id())
+        if level != "allow":
+            self._emit(v, getattr(skill, "id", ""))
+            self._audit(v, actor="", action=f"action:{getattr(skill, 'id', '')}",
+                        detail={"stage": getattr(d, "stage", 0),
+                                "trust_downgrade": getattr(d, "trust_downgrade", False)})
+        return v
+
+    def _emit(self, v: Verdict, skill_id: str) -> None:
+        if self._spine is None:
+            return
+        try:
+            self._spine.publish(f"policy.decision.{v.level}", {
+                "source": v.source, "level": v.level,
+                "reason": v.reason, "skill": skill_id,
+                "decision_id": v.decision_id}, source="policy_gate")
+        except Exception:
+            pass
+
+    def _audit(self, v: Verdict, actor: str, action: str, detail: dict) -> None:
+        """记统一治理审计流(P1-2)。审计器可空;记录失败绝不影响裁决(审计器内部已兜)。"""
+        if self._auditor is None:
+            return
+        self._auditor.record(layer=v.source, actor=actor, action=action,
+                             verdict=v.level, reason=v.reason,
+                             detail=detail, decision_id=v.decision_id)

package/python/foxclaw/kernel/process_manager.py

@@ -0,0 +1,186 @@
+"""
+进程管理器 (ProcessManager)
+
+把每个任务建模成操作系统的"进程",管理其完整生命周期:
+  created → queued → scheduled → running → completed / failed
+
+借鉴 Codex 版 Foxclaw 的 ProcessManager,适配本项目:
+- 与认知调度器结合:进程携带调度决策(优先级/路由)
+- 与真值管线结合:状态变更可发事件
+- 保留 state_history:每个进程的完整状态轨迹可追溯(对齐可观测原则)
+
+这让"任务执行"从一次性函数调用,变成可观测、可追溯的"进程生命周期"。
+"""
+from __future__ import annotations
+import threading
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+_VALID_TRANSITIONS = {
+    "created":   {"queued", "failed"},
+    "queued":    {"scheduled", "failed"},
+    "scheduled": {"running", "failed"},
+    "running":   {"completed", "failed"},
+    "completed": set(),
+    "failed":    set(),
+}
+_TERMINAL = {"completed", "failed"}
+
+
+@dataclass
+class ProcessRecord:
+    task: str
+    agent_id: Optional[str] = None
+    state: str = "created"
+    process_id: str = field(default_factory=lambda: f"proc_{uuid.uuid4().hex[:8]}")
+    priority: float = 0.0
+    route_hint: Optional[str] = None
+    created_at: float = field(default_factory=time.time)
+    updated_at: float = field(default_factory=time.time)
+    state_history: list = field(default_factory=list)
+    fail_reason: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        return {
+            "process_id": self.process_id, "task": self.task,
+            "agent_id": self.agent_id, "state": self.state,
+            "priority": self.priority, "route_hint": self.route_hint,
+            "state_history": self.state_history, "fail_reason": self.fail_reason,
+            "created_at": self.created_at, "updated_at": self.updated_at,
+        }
+
+
+class ProcessManager:
+    """进程生命周期管理。每个任务一个进程,状态受状态机约束。"""
+
+    def __init__(self, bus=None, history_limit: int = 1000):
+        self._processes: dict[str, ProcessRecord] = {}
+        self.bus = bus
+        self._history_limit = history_limit
+        self._active = 0
+        self._lock = threading.RLock()
+
+    def create(self, task: str, agent_id: str | None = None,
+               schedule: dict | None = None) -> ProcessRecord:
+        """创建进程(任务进入系统)。携带调度决策。"""
+        rec = ProcessRecord(
+            task=task, agent_id=agent_id,
+            priority=(schedule or {}).get("priority", 0.0),
+            route_hint=(schedule or {}).get("route_hint"),
+        )
+        with self._lock:
+            rec.state_history.append("created")
+            self._transition(rec, "queued")
+            if schedule:
+                self._transition(rec, "scheduled")
+            self._processes[rec.process_id] = rec
+            self._active += 1
+            self._evict_if_needed()
+            self._emit(rec)
+        return rec
+
+    def mark_running(self, process_id: str) -> Optional[ProcessRecord]:
+        with self._lock:
+            rec = self._processes.get(process_id)
+            if rec is None:
+                return None
+            if rec.state == "queued":
+                self._transition(rec, "scheduled")
+            return self._safe_transition(process_id, "running")
+
+    def mark_completed(self, process_id: str) -> Optional[ProcessRecord]:
+        with self._lock:
+            return self._safe_transition(process_id, "completed")
+
+    def mark_failed(self, process_id: str, reason: str = "") -> Optional[ProcessRecord]:
+        with self._lock:
+            rec = self._processes.get(process_id)
+            if rec is None:
+                return None
+            if rec.state in _TERMINAL:
+                return rec
+            self._transition(rec, "failed")
+            rec.fail_reason = reason
+            self._emit(rec)
+            return rec
+
+    def get(self, process_id: str) -> Optional[ProcessRecord]:
+        with self._lock:
+            return self._processes.get(process_id)
+
+    def list(self, state: str | None = None, limit: int = 50) -> list:
+        with self._lock:
+            items = list(self._processes.values())
+        if state:
+            items = [r for r in items if r.state == state]
+        items.sort(key=lambda r: r.created_at, reverse=True)
+        return [r.to_dict() for r in items[:limit]]
+
+    def active_count(self) -> int:
+        """活跃(非终态:queued/scheduled/running/created)进程数,O(1) 增量维护。
+        供高频 lifecycle 事件消费(免去每次 stats() 遍历全部进程)。"""
+        with self._lock:
+            return self._active
+
+    def stats(self) -> dict:
+        with self._lock:
+            counts: dict[str, int] = {}
+            for r in self._processes.values():
+                counts[r.state] = counts.get(r.state, 0) + 1
+            return {"total": len(self._processes), "by_state": counts,
+                    "active": self._active}
+
+    def _safe_transition(self, process_id: str, next_state: str) -> Optional[ProcessRecord]:
+        rec = self._processes.get(process_id)
+        if rec is None:
+            return None
+        if rec.state in _TERMINAL:
+            return rec
+        if rec.state == next_state:
+            return rec
+        self._transition(rec, next_state)
+        self._emit(rec)
+        return rec
+
+    def _transition(self, rec: ProcessRecord, next_state: str):
+        """受状态机约束的状态流转。真正非法的跳转(如跳过中间态)抛错 fail-fast。
+
+        【P5-3】终态守卫:已是终态的进程再流转 → 幂等忽略(不改状态、不重复 -1)。
+        此前"不会重复 -1"完全依赖上游 _safe_transition/mark_failed 的守卫——若未来
+        新增调用点直接调本方法,活跃计数会被重复扣减(可扣成负数,stats 失真)。
+        这里是双保险。注意行为变更:终态 → 任何状态,从抛 ValueError 变为静默忽略。
+        """
+        if rec.state in _TERMINAL:
+            return
+        allowed = _VALID_TRANSITIONS.get(rec.state, set())
+        if next_state not in allowed:
+            raise ValueError(
+                f"非法状态流转: {rec.state} → {next_state}(进程 {rec.process_id})")
+        if next_state in _TERMINAL:
+            self._active -= 1
+        rec.state = next_state
+        rec.updated_at = time.time()
+        rec.state_history.append(next_state)
+
+    def _emit(self, rec: ProcessRecord):
+        if self.bus is not None:
+            try:
+                self.bus.publish(f"task.lifecycle.{rec.state}", {
+                    "process_id": rec.process_id, "state": rec.state, "phase": rec.state,
+                    "task": rec.task, "agent_id": rec.agent_id,
+                })
+            except Exception:
+                pass
+
+    def _evict_if_needed(self):
+        """超出上限时,清理最老的终态进程(保留活跃进程)。"""
+        if len(self._processes) <= self._history_limit:
+            return
+        terminal = [(pid, r) for pid, r in self._processes.items()
+                    if r.state in _TERMINAL]
+        terminal.sort(key=lambda x: x[1].created_at)
+        for pid, _ in terminal[:len(self._processes) - self._history_limit]:
+            del self._processes[pid]

package/python/foxclaw/kernel/scheduler.py

@@ -0,0 +1,125 @@
+"""
+Scheduler —— 微内核的任务调度器(v2 ① Step1:准入 + 记账 + 生命周期事件)。
+
+审计:调度散在主管 _schedule / AHS / SteeringQueue,无全局并发配额/背压。
+本调度器把"任务准入"收敛到一处:并发配额(信号量)+ 记账 + task.lifecycle.* 事件。
+
+**为什么用线程级 Semaphore 而非 asyncio**:本系统是多线程/多事件循环模型
+(每请求 `to_thread + asyncio.run` 各自独立事件循环,见 api.py)。asyncio 原语绑定单一
+事件循环、无法跨循环共享;线程级 Semaphore 跨线程/跨循环通用,契合既有模型。
+
+Step1 范围(behavior-preserving):
+  · 默认 max_concurrency=None → **无上限**,run() 直通,行为与现在逐字一致;
+  · 设了上限 → 超额任务在 run() 里阻塞等待空位(背压);
+  · 每个任务 emit task.lifecycle.{scheduled,started,completed,failed} + 记账(供 /api/scheduler)。
+优先级 v0 只**记录**(FIFO 准入);严格优先级/抢占留 Step5。
+"""
+from __future__ import annotations
+import heapq
+import threading
+from typing import Any, Callable, Optional
+
+
+class _PriorityAdmission:
+    """并发准入(Step5):最多 max 个在跑;超额者**按优先级排队**(高优先先获空位)。
+    这是"下一个跑谁"的准入优先级——**不抢占正在跑的任务**(线程模型下杀线程不安全)。
+    max=None → 无限制、零等待(behavior-preserving)。"""
+
+    def __init__(self, max_slots: Optional[int]):
+        self.max = max_slots
+        self._free = max_slots or 0
+        self._cv = threading.Condition()
+        self._heap: list = []
+        self._seq = 0
+
+    def acquire(self, priority: int = 0) -> None:
+        if self.max is None:
+            return
+        with self._cv:
+            self._seq += 1
+            ticket = (-priority, self._seq)
+            heapq.heappush(self._heap, ticket)
+            while not (self._free > 0 and self._heap[0] == ticket):
+                self._cv.wait()
+            heapq.heappop(self._heap)
+            self._free -= 1
+            if self._free > 0 and self._heap:
+                self._cv.notify_all()
+
+    def release(self) -> None:
+        if self.max is None:
+            return
+        with self._cv:
+            self._free += 1
+            self._cv.notify_all()
+
+
+class Scheduler:
+    def __init__(self, max_concurrency: Optional[int] = None, spine=None,
+                 process_manager=None):
+        self.max_concurrency = max_concurrency if (max_concurrency and max_concurrency > 0) else None
+        self._adm = _PriorityAdmission(self.max_concurrency)
+        self._spine = spine
+        self.process_manager = process_manager
+        self._lock = threading.Lock()
+        self._stats = {"submitted": 0, "running": 0, "completed": 0,
+                       "failed": 0, "peak_running": 0}
+
+    def run(self, fn: Callable[[], Any], priority: int = 0,
+            agent_id: str = "", task: str = "") -> Any:
+        """准入受控地执行 fn(同步可调用,通常是 `lambda: asyncio.run(os.run(...))`)。
+        有并发上限时先获取空位(阻塞=背压),跑完释放;记账由本调度器,生命周期事件由 pm(或回退)。"""
+        pm = self.process_manager
+        with self._lock:
+            self._stats["submitted"] += 1
+        proc = None
+        if pm is not None:
+            proc = pm.create(task, agent_id=agent_id, schedule={"priority": priority})
+        else:
+            self._emit("scheduled", agent_id, task, priority)
+        self._adm.acquire(priority)
+        try:
+            with self._lock:
+                self._stats["running"] += 1
+                if self._stats["running"] > self._stats["peak_running"]:
+                    self._stats["peak_running"] = self._stats["running"]
+            if proc is not None:
+                pm.mark_running(proc.process_id)
+            else:
+                self._emit("running", agent_id, task, priority)
+            result = fn()
+            with self._lock:
+                self._stats["completed"] += 1
+            if proc is not None:
+                pm.mark_completed(proc.process_id)
+            else:
+                self._emit("completed", agent_id, task, priority)
+            return result
+        except Exception:
+            with self._lock:
+                self._stats["failed"] += 1
+            if proc is not None:
+                pm.mark_failed(proc.process_id, reason="error")
+            else:
+                self._emit("failed", agent_id, task, priority)
+            raise
+        finally:
+            with self._lock:
+                self._stats["running"] -= 1
+            self._adm.release()
+
+    def stats(self) -> dict:
+        with self._lock:
+            s: dict[str, int | None] = dict(self._stats)
+        s["max_concurrency"] = self.max_concurrency
+        return s
+
+    def _emit(self, phase: str, agent_id: str, task: str, priority: int) -> None:
+        if self._spine is None:
+            return
+        try:
+            self._spine.publish(f"task.lifecycle.{phase}", {
+                "agent_id": agent_id, "task": (task or "")[:120],
+                "priority": priority, "phase": phase}, source="scheduler")
+        except Exception:
+            pass