fusion-harness 0.2.1__tar.gz

fusion_harness-0.2.1/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: fusion-harness
+Version: 0.2.1
+Summary: Canonical agent harness kernel: funnels, hooks, permissions, compaction
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23; extra == "test"
+
+# fusion-harness
+
+Canonical agent harness kernel for the Fusion ecosystem: budget funnels, lifecycle
+hooks, permission engine, and context compaction. Pure stdlib, zero dependencies.
+
+## Consumers
+
+- **fusion-agent-studio** and **fusion-cowork** import this package directly
+  (hard dependency — `pip install -e fusion-harness`; no in-tree fallback copies).
+- **fusion-code** (TypeScript) keeps its own implementation held to the same
+  [kernel contract](docs/contract.md) by parity tests — cross-language runtime
+  sharing is not the goal; contract conformance is.
+
+The behavior contract for all runtimes lives in [docs/contract.md](docs/contract.md).
+
+## Modules
+
+- `fusion_harness.funnels` — `LLMFunnel`, `ToolFunnel`, `LifecycleBus` (budget enforcement + lifecycle events)
+- `fusion_harness.permissions` — `PermissionEngine` (deny-first permission checks)
+- `fusion_harness.hooks` — `HookEngine` (lifecycle hook registry + dispatch)
+- `fusion_harness.compactor` — `Compactor` (context window compaction with retention)
+
+## Security defaults (0.2.0, breaking)
+
+Permission enforcement is **fail-closed by default**: a `ToolFunnel` without a
+wired `PermissionEngine` denies every tool call. Headless/CI deployments opt out
+explicitly:
+
+```bash
+export FUSION_FUNNEL_PERMISSIONS=off   # or FUSION_FUNNEL_REQUIRE_PERMISSIONS=0
+```
+
+Every call skipped this way logs `permission enforcement DISABLED via ...` — no
+deployment is silently unarmed. See [docs/contract.md](docs/contract.md) §5 for
+the full environment variable table.
+
+## Install
+
+From PyPI:
+
+```bash
+pip install fusion-harness
+```
+
+From source (development):
+
+```bash
+pip install -e ".[test]"
+```
+
+Releases are published by CI on tag push (`.github/workflows/release.yml`) via
+PyPI trusted publishing.
+
+## Usage
+
+```python
+from fusion_harness import Compactor, LLMFunnel, LifecycleBus, PermissionEngine, ToolFunnel
+```
+
+## Test
+
+```bash
+pytest tests/        # unit coverage per module: funnels, permissions, hooks, compactor
+```
+
+The suite is the executable form of the contract: dangerous-pattern denies,
+layered rule precedence, fail-closed hook semantics, compaction levels, and the
+enforcement default flip. Consumer repos' CI (agent-studio, cowork) is the
+downstream detector for hidden passthrough assumptions.
+
+## License
+
+Same license as the fusion monorepo.

fusion_harness-0.2.1/README.md

@@ -0,0 +1,73 @@
+# fusion-harness
+
+Canonical agent harness kernel for the Fusion ecosystem: budget funnels, lifecycle
+hooks, permission engine, and context compaction. Pure stdlib, zero dependencies.
+
+## Consumers
+
+- **fusion-agent-studio** and **fusion-cowork** import this package directly
+  (hard dependency — `pip install -e fusion-harness`; no in-tree fallback copies).
+- **fusion-code** (TypeScript) keeps its own implementation held to the same
+  [kernel contract](docs/contract.md) by parity tests — cross-language runtime
+  sharing is not the goal; contract conformance is.
+
+The behavior contract for all runtimes lives in [docs/contract.md](docs/contract.md).
+
+## Modules
+
+- `fusion_harness.funnels` — `LLMFunnel`, `ToolFunnel`, `LifecycleBus` (budget enforcement + lifecycle events)
+- `fusion_harness.permissions` — `PermissionEngine` (deny-first permission checks)
+- `fusion_harness.hooks` — `HookEngine` (lifecycle hook registry + dispatch)
+- `fusion_harness.compactor` — `Compactor` (context window compaction with retention)
+
+## Security defaults (0.2.0, breaking)
+
+Permission enforcement is **fail-closed by default**: a `ToolFunnel` without a
+wired `PermissionEngine` denies every tool call. Headless/CI deployments opt out
+explicitly:
+
+```bash
+export FUSION_FUNNEL_PERMISSIONS=off   # or FUSION_FUNNEL_REQUIRE_PERMISSIONS=0
+```
+
+Every call skipped this way logs `permission enforcement DISABLED via ...` — no
+deployment is silently unarmed. See [docs/contract.md](docs/contract.md) §5 for
+the full environment variable table.
+
+## Install
+
+From PyPI:
+
+```bash
+pip install fusion-harness
+```
+
+From source (development):
+
+```bash
+pip install -e ".[test]"
+```
+
+Releases are published by CI on tag push (`.github/workflows/release.yml`) via
+PyPI trusted publishing.
+
+## Usage
+
+```python
+from fusion_harness import Compactor, LLMFunnel, LifecycleBus, PermissionEngine, ToolFunnel
+```
+
+## Test
+
+```bash
+pytest tests/        # unit coverage per module: funnels, permissions, hooks, compactor
+```
+
+The suite is the executable form of the contract: dangerous-pattern denies,
+layered rule precedence, fail-closed hook semantics, compaction levels, and the
+enforcement default flip. Consumer repos' CI (agent-studio, cowork) is the
+downstream detector for hidden passthrough assumptions.
+
+## License
+
+Same license as the fusion monorepo.

fusion_harness-0.2.1/fusion_harness/__init__.py

@@ -0,0 +1,33 @@
+"""fusion-harness — canonical agent harness kernel (funnels/hooks/permissions/compactor).
+
+Extracted from fusion-agent-studio N0 kernel (#357). Pure stdlib, no deps.
+Consumers: fusion-agent-studio (shim import), fusion-cowork, fusion-code.
+"""
+
+from fusion_harness.compactor import CompactionConfig, Compactor
+from fusion_harness.funnels import LifecycleBus, LLMFunnel, ToolFunnel
+from fusion_harness.hooks import HookConfig, HookEngine, HookResult
+from fusion_harness.permissions import (
+    PermissionDecision,
+    PermissionEngine,
+    PermissionMode,
+    PermissionRule,
+)
+
+KERNEL_VERSION = "0.2.1"
+
+__all__ = [
+    "KERNEL_VERSION",
+    "CompactionConfig",
+    "Compactor",
+    "HookConfig",
+    "HookEngine",
+    "HookResult",
+    "LLMFunnel",
+    "LifecycleBus",
+    "PermissionDecision",
+    "PermissionEngine",
+    "PermissionMode",
+    "PermissionRule",
+    "ToolFunnel",
+]

fusion_harness-0.2.1/fusion_harness/compactor.py

@@ -0,0 +1,444 @@
+# Canonical kernel module lives here; agent_runtime imports via shim (#357).
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import re
+from dataclasses import dataclass, field
+
+logger = logging.getLogger(__name__)
+
+_RETENTION_HEADER = "[Retention List]"
+
+
+@dataclass
+class RetentionList:
+    todos: list[str] = field(default_factory=list)
+    interfaces: list[str] = field(default_factory=list)
+    constraints: list[str] = field(default_factory=list)
+    active_tasks: list[str] = field(default_factory=list)
+
+    @classmethod
+    def from_messages(cls, messages: list[dict], max_per_section: int = 20) -> RetentionList:
+        rl = cls()
+        for m in messages:
+            content = m.get("content") or ""
+            if not isinstance(content, str):
+                content = str(content)
+            for raw in content.splitlines():
+                line = raw.strip()
+                if not line or len(line) > 200:
+                    continue
+                if "TODO" in line or "待办" in line:
+                    rl._add(rl.todos, line, max_per_section)
+                if re.match(r"^\s*(async def |def |class )\w+", line) or "接口" in line:
+                    rl._add(rl.interfaces, line, max_per_section)
+                if "constraint" in line.lower() or "约束" in line:
+                    rl._add(rl.constraints, line, max_per_section)
+                if "pending" in line.lower() or "in_progress" in line or "进行中" in line:
+                    rl._add(rl.active_tasks, line, max_per_section)
+        logger.info(
+            "retention extracted todos=%d interfaces=%d constraints=%d tasks=%d",
+            len(rl.todos),
+            len(rl.interfaces),
+            len(rl.constraints),
+            len(rl.active_tasks),
+        )
+        return rl
+
+    def _add(self, bucket: list[str], item: str, cap: int) -> None:
+        if len(bucket) < cap and item not in bucket:
+            bucket.append(item)
+
+    def non_empty(self) -> bool:
+        return bool(self.todos or self.interfaces or self.constraints or self.active_tasks)
+
+    def render(self) -> str:
+        lines = [f"{_RETENTION_HEADER} (kept verbatim across compaction)"]
+        if self.todos:
+            lines.append("TODOs: " + "; ".join(self.todos))
+        if self.interfaces:
+            lines.append("Interfaces: " + "; ".join(self.interfaces))
+        if self.constraints:
+            lines.append("Constraints: " + "; ".join(self.constraints))
+        if self.active_tasks:
+            lines.append("Active tasks: " + "; ".join(self.active_tasks))
+        return "\n".join(lines)
+
+
+@dataclass
+class CompactionConfig:
+    context_window: int = 32768
+    warning_buffer: int = 3000
+    error_buffer: int = 2000
+    manual_buffer: int = 500
+    keep_recent_rounds: int = 3
+    tool_result_head: int = 200
+    tool_result_tail: int = 100
+    tool_result_max_lines: int = 50
+    retention_max_per_section: int = 20
+
+    def warning_threshold(self) -> int:
+        return self.context_window - self.warning_buffer
+
+    def error_threshold(self) -> int:
+        return self.context_window - self.error_buffer
+
+    def manual_threshold(self) -> int:
+        return self.context_window - self.manual_buffer
+
+
+class Compactor:
+    def __init__(
+        self,
+        config: CompactionConfig | None = None,
+        llm_gateway=None,
+        memory_engine=None,
+        lifecycle_bus=None,
+        hooks=None,
+    ):
+        self.config = config or CompactionConfig()
+        self.llm_gateway = llm_gateway
+        self.memory_engine = memory_engine
+        self.lifecycle_bus = lifecycle_bus
+        self.hooks = hooks
+
+    def _persist_summary(self, summary: str, original_count: int) -> None:
+        if self.memory_engine is None or not summary:
+            return
+        try:
+            self.memory_engine.store_summary(
+                summary, scope="compaction", original_count=original_count
+            )
+            logger.info("persisted compaction summary orig_count=%d", original_count)
+        except Exception as exc:
+            logger.warning("failed to persist compaction summary: %s", exc)
+
+    def estimate_tokens(self, messages: list[dict]) -> int:
+        total = 0
+        for m in messages:
+            content = m.get("content") or ""
+            if not isinstance(content, str):
+                content = str(content)
+            total += len(content)
+            for tc in m.get("tool_calls") or []:
+                fn = tc.get("function", {})
+                total += len(fn.get("name", "")) + len(fn.get("arguments", ""))
+        return max(1, total // 4)
+
+    def summarize_messages(self, messages: list[dict]) -> str:
+        # N12: public summarizer for fork summary-resume (deterministic
+        # extraction, same path as hard compaction).
+        return self._summarize(messages)
+
+    def should_compact(self, messages: list[dict]) -> str:
+        tokens = self.estimate_tokens(messages)
+        if tokens >= self.config.error_threshold():
+            return "error"
+        if tokens >= self.config.warning_threshold():
+            return "warning"
+        if tokens >= self.config.manual_threshold():
+            return "manual"
+        return "none"
+
+    async def compact_async(self, messages: list[dict], level: str = "warning") -> list[dict]:
+        # A5: summarization runs on the local MLX server when a gateway is
+        # wired. The sync pipeline is offloaded to a thread so the event loop
+        # stays free; any failure degrades to the deterministic extractor.
+        if self.llm_gateway is not None and level != "none" and self._mlx_enabled():
+            return await asyncio.to_thread(self._compact_blocking, messages, level)
+        return self.compact(messages, level)
+
+    @staticmethod
+    def _mlx_enabled() -> bool:
+        return os.environ.get("FUSION_COMPACT_MLX", "1").strip().lower() not in (
+            "0",
+            "false",
+            "no",
+            "off",
+        )
+
+    def _compact_blocking(self, messages: list[dict], level: str) -> list[dict]:
+        return self.compact(messages, level, summarize=self._summarize_via_mlx)
+
+    def _summarize_via_mlx(self, messages: list[dict], hard: bool = False) -> str:
+        try:
+            prompt = self._summary_prompt(messages, hard)
+            resp = asyncio.run(
+                self.llm_gateway.chat(
+                    messages=[{"role": "user", "content": prompt}],
+                    model="default",
+                    max_tokens=400,
+                    temperature=0.2,
+                )
+            )
+            content = getattr(resp, "content", "") or ""
+            if not content and isinstance(resp, dict):
+                content = resp.get("content", "") or ""
+            content = str(content).strip()
+            if content:
+                logger.info("compaction summary via local mlx chars=%d", len(content))
+                return "[Compacted prior context]\n" + content
+            logger.warning("mlx compaction summary empty, falling back to deterministic")
+        except Exception as exc:
+            logger.warning("mlx compaction summary failed, deterministic fallback: %s", exc)
+        return self._summarize(messages, hard)
+
+    @staticmethod
+    def _summary_prompt(messages: list[dict], hard: bool) -> str:
+        lines = []
+        for m in messages[:80]:
+            role = m.get("role", "")
+            content = m.get("content") or ""
+            if not isinstance(content, str):
+                content = str(content)
+            if content:
+                lines.append(f"{role}: {content[:400]}")
+        body = "\n".join(lines)[:12000]
+        return (
+            "Summarize this agent conversation for continuation. Keep concrete "
+            "decisions, file paths, interfaces, constraints and open TODOs. "
+            "Be terse, use bullet lines.\n\n" + body
+        )
+
+    def compact(
+        self,
+        messages: list[dict],
+        level: str = "warning",
+        summarize=None,
+    ) -> list[dict]:
+        logger.info("compaction phase=1 trigger level=%s", level)
+        payload = {"level": level, "before_msgs": len(messages)}
+        if level != "none":
+            self._fire_compact_before(payload)
+            self._emit_lifecycle("compact_before", payload)
+        rl = RetentionList()
+        if level != "none":
+            logger.info("compaction phase=2 summarize")
+            try:
+                rl = RetentionList.from_messages(
+                    messages, self.config.retention_max_per_section
+                )
+            except Exception as exc:
+                logger.warning("retention extraction failed: %s", exc)
+            logger.info(
+                "compaction phase=3 retention extracted todos=%d interfaces=%d constraints=%d tasks=%d",
+                len(rl.todos),
+                len(rl.interfaces),
+                len(rl.constraints),
+                len(rl.active_tasks),
+            )
+        before_tokens = self.estimate_tokens(messages)
+        msgs = self._microcompact(list(messages))
+        if self.estimate_tokens(msgs) >= self.config.warning_threshold():
+            msgs = self._smart_truncate(msgs, summarize)
+        if (
+            level == "error"
+            and self.estimate_tokens(msgs) >= self.config.error_threshold()
+        ):
+            msgs = self._hard_compact(msgs, summarize)
+        after_tokens = self.estimate_tokens(msgs)
+        logger.info(
+            "compaction phase=4 drop before_msgs=%d after_msgs=%d before_tok=%d after_tok=%d",
+            len(messages),
+            len(msgs),
+            before_tokens,
+            after_tokens,
+        )
+        if level != "none" and rl.non_empty():
+            msgs = self._inject_retention(msgs, rl)
+            logger.info("compaction phase=5 retention injected")
+        logger.info(
+            "compact level=%s before_msgs=%d after_msgs=%d before_tok=%d after_tok=%d",
+            level,
+            len(messages),
+            len(msgs),
+            before_tokens,
+            after_tokens,
+        )
+        if level != "none":
+            self._emit_lifecycle("compact_after", {**payload, "after_msgs": len(msgs)})
+        return msgs
+
+    def _fire_compact_before(self, payload: dict) -> None:
+        if self.hooks is None:
+            return
+        try:
+            try:
+                asyncio.get_running_loop()
+            except RuntimeError:
+                logger.debug("COMPACT_BEFORE skipped: no running event loop")
+                return
+            asyncio.ensure_future(self.hooks.fire("COMPACT_BEFORE", payload))
+        except Exception as exc:
+            logger.warning("COMPACT_BEFORE hook dispatch failed: %s", exc)
+
+    def _emit_lifecycle(self, event: str, payload: dict) -> None:
+        if self.lifecycle_bus is None:
+            return
+        try:
+            self.lifecycle_bus.emit("agent", event, payload, session_id="")
+        except Exception as exc:
+            logger.warning("lifecycle %s emit failed: %s", event, exc)
+
+    def _inject_retention(self, messages: list[dict], rl: RetentionList) -> list[dict]:
+        out = [
+            m
+            for m in messages
+            if not (
+                m.get("role") == "system"
+                and str(m.get("content") or "").startswith(_RETENTION_HEADER)
+            )
+        ]
+        retention_msg = {"role": "system", "content": rl.render()}
+        idx = 0
+        for i, m in enumerate(out):
+            if m.get("role") == "system":
+                idx = i + 1
+            else:
+                break
+        logger.info("retention injected at index=%d", idx)
+        return out[:idx] + [retention_msg] + out[idx:]
+
+    def reactive_strip(self, messages: list[dict]) -> list[dict]:
+        system_msgs, rest = self._partition(messages)
+        if len(rest) <= 2:
+            stripped = [self._truncate_tool(m) for m in rest]
+        else:
+            keep_tail = rest[-2:]
+            dropped = rest[:-2]
+            summary = self._summarize(dropped)
+            self._persist_summary(summary, len(dropped))
+            stripped = [{"role": "system", "content": summary}] + [
+                self._truncate_tool(m) for m in keep_tail
+            ]
+        logger.info(
+            "reactive_strip before_msgs=%d after_msgs=%d before_tok=%d after_tok=%d",
+            len(messages),
+            len(system_msgs) + len(stripped),
+            self.estimate_tokens(messages),
+            self.estimate_tokens(system_msgs + stripped),
+        )
+        return system_msgs + stripped
+
+    def _microcompact(self, messages: list[dict]) -> list[dict]:
+        out = []
+        for m in messages:
+            if m.get("role") == "tool":
+                m = self._truncate_tool(m)
+            out.append(m)
+        return out
+
+    def _truncate_tool(self, m: dict) -> dict:
+        content = m.get("content") or ""
+        if not isinstance(content, str):
+            content = str(content)
+        limit = self.config.tool_result_head + self.config.tool_result_tail
+        if len(content) <= limit:
+            return m
+        head = content[: self.config.tool_result_head]
+        tail = content[-self.config.tool_result_tail :]
+        dropped = len(content) - len(head) - len(tail)
+        logger.debug("truncate_tool dropped=%d", dropped)
+        return {**m, "content": f"{head}\n...[truncated {dropped} chars]...\n{tail}"}
+
+    def _smart_truncate(self, messages: list[dict], summarize=None) -> list[dict]:
+        system_msgs, rest = self._partition(messages)
+        rounds = self._split_rounds(rest)
+        keep = self.config.keep_recent_rounds
+        if len(rounds) <= keep:
+            return messages
+        dropped = rounds[: len(rounds) - keep]
+        kept = rounds[len(rounds) - keep :]
+        dropped_msgs = [m for r in dropped for m in r]
+        summary = (summarize or self._summarize)(dropped_msgs)
+        self._persist_summary(summary, len(dropped_msgs))
+        logger.info(
+            "smart_truncate dropped_rounds=%d kept_rounds=%d", len(dropped), len(kept)
+        )
+        return (
+            system_msgs
+            + [{"role": "system", "content": summary}]
+            + [m for r in kept for m in r]
+        )
+
+    def _hard_compact(self, messages: list[dict], summarize=None) -> list[dict]:
+        system_msgs, rest = self._partition(messages)
+        rounds = self._split_rounds(rest)
+        if len(rounds) <= 1:
+            return messages
+        dropped = rounds[: len(rounds) - 1]
+        kept = rounds[-1:]
+        dropped_msgs = [m for r in dropped for m in r]
+        summary = (summarize or self._summarize)(dropped_msgs, hard=True)
+        self._persist_summary(summary, len(dropped_msgs))
+        logger.info(
+            "hard_compact dropped_rounds=%d kept_rounds=%d", len(dropped), len(kept)
+        )
+        return (
+            system_msgs
+            + [{"role": "system", "content": summary}]
+            + [m for r in kept for m in r]
+        )
+
+    def _summarize(self, messages: list[dict], hard: bool = False) -> str:
+        user_intents = []
+        tool_names = []
+        conclusions = []
+        for m in messages:
+            role = m.get("role")
+            content = m.get("content") or ""
+            if not isinstance(content, str):
+                content = str(content)
+            if role == "user" and content:
+                user_intents.append(content[:120])
+            elif role == "assistant":
+                if content:
+                    conclusions.append(content[:120])
+                for tc in m.get("tool_calls") or []:
+                    fn = tc.get("function", {})
+                    name = fn.get("name", "")
+                    if name and name not in tool_names:
+                        tool_names.append(name)
+        parts = ["[Compacted prior context]"]
+        if user_intents:
+            parts.append("User asked: " + " | ".join(user_intents[:5]))
+        if tool_names:
+            parts.append("Tools used: " + ", ".join(tool_names[:10]))
+        if conclusions:
+            parts.append("Conclusions: " + " | ".join(conclusions[:5]))
+        if hard:
+            parts.append("(hard-compact: only most recent round retained)")
+        return "\n".join(parts)
+
+    def _partition(self, messages: list[dict]) -> tuple[list[dict], list[dict]]:
+        system_msgs = []
+        rest = []
+        for m in messages:
+            if m.get("role") == "system" and not rest:
+                system_msgs.append(m)
+            else:
+                rest.append(m)
+        return system_msgs, rest
+
+    def _split_rounds(self, messages: list[dict]) -> list[list[dict]]:
+        rounds: list[list[dict]] = []
+        current: list[dict] = []
+        for m in messages:
+            if m.get("role") == "user":
+                if current:
+                    rounds.append(current)
+                current = [m]
+            else:
+                current.append(m)
+        if current:
+            rounds.append(current)
+        return rounds
+
+
+__all__ = [
+    "CompactionConfig",
+    "Compactor",
+    "RetentionList",
+]