reactifact 0.7.0__tar.gz → 0.8.0__tar.gz

{reactifact-0.7.0/reactifact.egg-info → reactifact-0.8.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: reactifact
-Version: 0.7.0
+Version: 0.8.0
 Summary: Reactive, artifact-driven agent runtime: agents transform versioned, typed, provenance-aware artifacts inside an evolving context
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/bzdvdn/reactifact
 Project-URL: Repository, https://github.com/bzdvdn/reactifact
-Project-URL: Documentation, https://github.com/bzdvdn/reactifact/tree/master/docs
+Project-URL: Documentation, https://bzdvdn.github.io/reactifact/
 Project-URL: Changelog, https://github.com/bzdvdn/reactifact/blob/master/CHANGELOG.md
 Keywords: agents,llm,ai-agents,reactive,provenance,orchestration,agentic
 Classifier: Development Status :: 4 - Beta
@@ -15,6 +15,8 @@ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -34,6 +36,10 @@ Provides-Extra: pg
 Requires-Dist: psycopg[binary]>=3.2; extra == "pg"
 Provides-Extra: mcp
 Requires-Dist: mcp>=2.2; extra == "mcp"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.27; extra == "docs"
 Dynamic: license-file
 
 <p align="center">
@@ -44,10 +50,11 @@ Dynamic: license-file
 
 [![CI](https://github.com/bzdvdn/reactifact/actions/workflows/ci.yml/badge.svg)](https://github.com/bzdvdn/reactifact/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/bzdvdn/reactifact/graph/badge.svg)](https://codecov.io/gh/bzdvdn/reactifact)
-[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue)](https://github.com/bzdvdn/reactifact)
+[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](https://github.com/bzdvdn/reactifact)
 [![PyPI version](https://img.shields.io/pypi/v/reactifact)](https://pypi.org/project/reactifact/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/bzdvdn/reactifact)
+[![Docs](https://img.shields.io/badge/docs-bzdvdn.github.io%2Freactifact-blue)](https://bzdvdn.github.io/reactifact/)
 
 Most agent frameworks make you **draw the graph**: connect nodes, wire memory,
 declare control flow. But a knowledge question — *"why did infra costs jump in

{reactifact-0.7.0 → reactifact-0.8.0}/README.md

@@ -6,10 +6,11 @@
 
 [![CI](https://github.com/bzdvdn/reactifact/actions/workflows/ci.yml/badge.svg)](https://github.com/bzdvdn/reactifact/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/bzdvdn/reactifact/graph/badge.svg)](https://codecov.io/gh/bzdvdn/reactifact)
-[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue)](https://github.com/bzdvdn/reactifact)
+[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](https://github.com/bzdvdn/reactifact)
 [![PyPI version](https://img.shields.io/pypi/v/reactifact)](https://pypi.org/project/reactifact/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/bzdvdn/reactifact)
+[![Docs](https://img.shields.io/badge/docs-bzdvdn.github.io%2Freactifact-blue)](https://bzdvdn.github.io/reactifact/)
 
 Most agent frameworks make you **draw the graph**: connect nodes, wire memory,
 declare control flow. But a knowledge question — *"why did infra costs jump in

{reactifact-0.7.0 → reactifact-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "reactifact"
-version = "0.7.0"
+version = "0.8.0"
 description = "Reactive, artifact-driven agent runtime: agents transform versioned, typed, provenance-aware artifacts inside an evolving context"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -19,6 +19,8 @@ classifiers = [
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Typing :: Typed",
 ]
 dependencies = [
@@ -30,7 +32,7 @@ dependencies = [
 [project.urls]
 Homepage = "https://github.com/bzdvdn/reactifact"
 Repository = "https://github.com/bzdvdn/reactifact"
-Documentation = "https://github.com/bzdvdn/reactifact/tree/master/docs"
+Documentation = "https://bzdvdn.github.io/reactifact/"
 Changelog = "https://github.com/bzdvdn/reactifact/blob/master/CHANGELOG.md"
 
 [project.optional-dependencies]
@@ -50,6 +52,11 @@ pg = [
 mcp = [
     "mcp>=2.2",
 ]
+docs = [
+    "mkdocs>=1.6",
+    "mkdocs-material>=9.5",
+    "mkdocstrings[python]>=0.27",
+]
 
 # uv-native groups mirror the extras so `uv run`/`uv sync` installs the web demo
 # deps by default (no `--extra` flag needed to boot the examples). Extras stay
@@ -74,6 +81,11 @@ pg = [
 mcp = [
     "mcp>=2.2",
 ]
+docs = [
+    "mkdocs>=1.6",
+    "mkdocs-material>=9.5",
+    "mkdocstrings[python]>=0.27",
+]
 
 [tool.uv]
 default-groups = ["dev", "web", "mcp"]

{reactifact-0.7.0 → reactifact-0.8.0}/reactifact/__init__.py

@@ -48,7 +48,7 @@ from .session import Session, SessionStore
 from .tools import FunctionTool, Tool, ToolOutput, tool
 from .triggers import Trigger
 
-__version__ = "0.7.0"
+__version__ = "0.8.0"
 
 __all__ = [
     "Agent",

reactifact-0.8.0/reactifact/agent_tool.py

@@ -0,0 +1,115 @@
+"""reactifact.agent_tool — a sub-agent as a `Tool` (delegation, §46).
+
+`AgentAsTool` lets an `LLMAgent`/`HITLLMAgent` loop call another agent as an
+ordinary tool: "delegate to X" runs a fresh, isolated nested `Runtime` to
+completion and returns its final answer as the tool result. The delegating
+loop sees only the final text — not the sub-agent's own tool calls, retries,
+or internal reasoning.
+
+Two deliberate constraints, not omissions:
+
+- **Isolation is a fresh `Context`, not `context.branch()`.** The sub-agent
+  sees only the `query` it's given, nothing of the parent's history — no
+  prompt bloat from an unrelated conversation, and no accidental fork/merge
+  semantics (`branch()` exists for alternative-state exploration meant to be
+  merged back later, §39/§40; a one-shot delegate-and-discard call needs
+  neither). If a sub-agent genuinely needs to see the parent's state, build
+  its `Context` yourself and don't use this tool.
+- **HITL sub-agents are rejected, not silently broken.** `Tool.execute` has
+  no channel back to a human — nothing would ever answer a `PendingQuestion`
+  the sub-agent raises inside its own isolated `Context`, and the nested run
+  would just finish with no `ToolAnswer`. `execute()` checks for this and
+  returns a `ToolOutput(error=...)` naming the unanswered question, instead
+  of returning empty text with no explanation.
+
+Because `Tool.execute` receives only `args` (no `context`, see `tools.py`),
+the sub-agent's `LLMProvider`/budget cannot be inherited implicitly from
+whatever loop is calling this tool — pass them explicitly via `resources=`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from pydantic import BaseModel
+
+from .agents import Agent
+from .budget import Budget
+from .context import Context
+from .resources import RuntimeResources
+from .runtime import Runtime
+from .tool_use import ToolAnswer
+from .tools import Tool, ToolOutput
+
+
+class SubTask(BaseModel):
+    """Default input artifact for `AgentAsTool` — override via `input_type`
+    with any model that has a `text: str` field (the convention `ToolUse`'s
+    own `_goal` reads, `tool_use.py`)."""
+
+    text: str
+
+
+class AgentAsTool(Tool):
+    """Wraps `agent_factory()` as a callable tool (see module docstring)."""
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        description: str,
+        agent_factory: Callable[[], Agent],
+        resources: RuntimeResources,
+        input_type: type[BaseModel] = SubTask,
+        output_type: type[BaseModel] | None = None,
+        max_runs: int = 20,
+        destructive: bool = False,
+    ):
+        self.name = name
+        self.description = description
+        self.agent_factory = agent_factory
+        self.resources = resources
+        self.input_type = input_type
+        self.output_type = output_type or ToolAnswer
+        self.max_runs = max_runs
+        self.destructive = destructive
+        self.schema = {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "The task/question to delegate to the sub-agent.",
+                }
+            },
+            "required": ["query"],
+        }
+
+    async def execute(self, args: dict[str, Any]) -> ToolOutput:
+        query = str(args.get("query", ""))
+        sub_context = Context(resources=self.resources)
+        sub_agent = self.agent_factory()
+        sub_runtime = Runtime(
+            sub_context, agents=[sub_agent], budget=Budget(max_runs=self.max_runs)
+        )
+        sub_context.create(self.input_type(text=query))
+        await sub_runtime.arun()
+
+        if sub_context.has_pending_question():
+            pending = sub_context.latest_pending_question()
+            question = pending.data.question if pending is not None else ""
+            return ToolOutput(
+                error=(
+                    f"sub-agent '{sub_agent.name}' needs clarification it wasn't "
+                    f"given and can't ask for: {question!r}. Give '{self.name}' a "
+                    "more complete query and try again."
+                )
+            )
+
+        outputs = sub_context.list_artifacts(self.output_type)
+        if not outputs:
+            return ToolOutput(
+                error=f"sub-agent '{sub_agent.name}' produced no {self.output_type.__name__}"
+            )
+        text = getattr(outputs[-1].data, "text", "") or ""
+        return ToolOutput(text=text)

{reactifact-0.7.0 → reactifact-0.8.0}/reactifact/agents.py

@@ -90,7 +90,14 @@ class Agent(ABC):  # noqa: B024 — interface without abstract methods, run() ha
         return self._collect_inputs(context)
 
     def _collect_inputs(self, context: Context) -> list[Artifact[Any]]:
-        """Collects all artifacts matching consumes and conditions."""
+        """Collects all artifacts matching consumes and conditions.
+
+        Ranking/truncation, if any, is a `Runtime`-level policy
+        (`context.resources.context_builder`, see `context_builder.py`), not
+        this agent's — applied here so both this and `collect_inputs()`
+        (used by the runtime for provenance) see the identical, already
+        built list.
+        """
         if not self.consumes:
             return []
         inputs: list[Artifact[Any]] = []
@@ -99,6 +106,9 @@ class Agent(ABC):  # noqa: B024 — interface without abstract methods, run() ha
             if c.condition:
                 artifacts = [a for a in artifacts if c.condition(a)]
             inputs.extend(artifacts)
+        builder = context.resources.context_builder
+        if builder is not None:
+            inputs = builder.build(context, self, inputs)
         return inputs
 
     async def run(self, event: Event, context: Context) -> Patch | None:

{reactifact-0.7.0 → reactifact-0.8.0}/reactifact/branching.py

@@ -63,6 +63,7 @@ def clone_context(source: Context) -> Context:
     new_ws._log = source._log.copy()
     new_ws._relations = source._relations.copy()
     new_ws._recompute_stale()
+    new_ws._reindex_by_type()
     return new_ws
 
 
@@ -209,6 +210,7 @@ def merge_contexts(
         # `delete()` — resync `_stale` from scratch rather than risk it
         # drifting from the post-merge state.
         target._recompute_stale()
+        target._reindex_by_type()
 
 
 class BranchStore:

{reactifact-0.7.0 → reactifact-0.8.0}/reactifact/checkpoints.py

@@ -112,11 +112,18 @@ class FileBackend(CheckpointBackend):
     """File backend: state is stored in a single JSON file."""
 
     def __init__(self, path: str):
-        self.path = path
+        self.path = Path(path)
 
     def _save_sync(self, data: dict[str, Any]) -> None:
-        with open(self.path, "w", encoding="utf-8") as f:
+        # Atomic write (tmp + rename), same reasoning as `FileKVBackend._set_sync`:
+        # a direct write left a truncated/corrupt file on a process kill mid-write
+        # (OOM, deploy, kill -9) — the next `load()` would raise JSONDecodeError
+        # and the session would be unrecoverable.
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = self.path.with_suffix(self.path.suffix + ".tmp")
+        with open(tmp, "w", encoding="utf-8") as f:
             json.dump(data, f, indent=2)
+        tmp.replace(self.path)
 
     async def save(self, data: dict[str, Any]) -> None:
         await asyncio.to_thread(self._save_sync, data)

{reactifact-0.7.0 → reactifact-0.8.0}/reactifact/context.py

@@ -81,6 +81,16 @@ class Context:
         # version. Kept up to date by `update()`/`log_commit()` so
         # `stale_artifacts()`/`has_stale()` never rescan the whole context.
         self._stale: set[str] = set()
+        # Incrementally maintained: exact `type(data)` -> ids of that exact
+        # type. Kept up to date by `create()`/`update()`/`delete()` so
+        # `list_artifacts(T)` doesn't call `isinstance()` per artifact — it
+        # unions the ids of every *distinct type ever created* that is an
+        # `issubclass` of `T` (a small set — bounded by distinct types, not
+        # artifact count) into an O(1) membership test, still walked in
+        # insertion order to preserve tie-break order in callers' own sorts.
+        # Any bulk rewrite that bypasses create/update/delete must call
+        # `_reindex_by_type()` (mirrors `_recompute_stale()`, same reasoning).
+        self._by_type: dict[type, set[str]] = {}
 
     # ---- announce: agent progress events streamed out ----
 
@@ -116,6 +126,7 @@ class Context:
             return self._artifacts[id]
         artifact = Artifact(data=data, id=id)
         self._artifacts[artifact.id] = artifact
+        self._by_type.setdefault(type(data), set()).add(artifact.id)
         self._events.append(
             Event(
                 type=EventType.ARTIFACT_CREATED,
@@ -140,7 +151,12 @@ class Context:
             return None
         if artifact.data == new_data:
             return artifact
+        old_type = type(artifact.data)
         artifact.update(new_data)
+        new_type = type(new_data)
+        if new_type is not old_type:
+            self._by_type.get(old_type, set()).discard(artifact_id)
+            self._by_type.setdefault(new_type, set()).add(artifact_id)
         self._events.append(
             Event(
                 type=EventType.ARTIFACT_UPDATED,
@@ -165,6 +181,7 @@ class Context:
         if artifact is None:
             return False
         self._stale.discard(artifact_id)
+        self._by_type.get(type(artifact.data), set()).discard(artifact_id)
         self._events.append(
             Event(
                 type=EventType.ARTIFACT_DELETED,
@@ -185,13 +202,22 @@ class Context:
     def list_artifacts(
         self, artifact_type: type[TArtifact] | None = None
     ) -> list[Artifact[Any]]:
-        """Returns a list of artifacts, optionally filtered by data type."""
+        """Returns a list of artifacts, optionally filtered by data type.
+
+        Preserves insertion order (matters: ties in a caller's own sort key,
+        e.g. `updated_at`, break in creation order, same as before this
+        method stopped `isinstance`-scanning every artifact).
+        """
         if artifact_type is None:
             return list(self._artifacts.values())
+        matching_ids: set[str] = set()
+        for t, ids in self._by_type.items():
+            if issubclass(t, artifact_type):
+                matching_ids |= ids
         return [
             cast(Artifact[TArtifact], a)
-            for a in self._artifacts.values()
-            if isinstance(a.data, artifact_type)
+            for aid, a in self._artifacts.items()
+            if aid in matching_ids
         ]
 
     def latest(self, artifact_type: type[TArtifact]) -> Artifact[TArtifact] | None:
@@ -493,6 +519,18 @@ class Context:
                     break
         self._stale = stale
 
+    def _reindex_by_type(self) -> None:
+        """Full rebuild of `_by_type` from current artifacts.
+
+        Same reasoning as `_recompute_stale()`: only needed after a bulk
+        rewrite that bypasses `create`/`update`/`delete` — call it alongside
+        `_recompute_stale()` at every such site, never on its own.
+        """
+        by_type: dict[type, set[str]] = {}
+        for aid, artifact in self._artifacts.items():
+            by_type.setdefault(type(artifact.data), set()).add(aid)
+        self._by_type = by_type
+
     def _rebuild_artifacts_from_commits(
         self, upto_version: int
     ) -> dict[str, Artifact[Any]]:
@@ -534,6 +572,7 @@ class Context:
         self._events = []
         self._log.truncate(version)
         self._recompute_stale()
+        self._reindex_by_type()
 
     def to_dict(self) -> dict[str, Any]:
         return {
@@ -559,6 +598,7 @@ class Context:
         ws._fork_name = d.get("fork_name", "")
         ws._base = Context.from_dict(d["base"]) if d.get("base") is not None else None
         ws._recompute_stale()
+        ws._reindex_by_type()
         return ws
 
     async def save_checkpoint(self, backend_or_path: str | CheckpointBackend) -> None:

reactifact-0.8.0/reactifact/context_builder.py

@@ -0,0 +1,157 @@
+"""reactifact.context_builder — Runtime-level policy for what goes into an
+agent's inputs (ranking/truncation), separate from the agent itself.
+
+An `Agent` only declares *which* artifact types/conditions it consumes
+(`Consume`); it says nothing about *how many* or *which* matching artifacts
+actually go into a produce call when there are more candidates than fit a
+prompt. That decision is a `Runtime`-level concern — set it once via
+`RuntimeResources(context_builder=...)` and every agent's
+`collect_inputs()` (`Agent._collect_inputs`, `agents.py`) routes through it,
+so a builder set on the `Context` a `Runtime` was constructed with applies
+uniformly, without each `Agent` subclass reimplementing ranking/truncation.
+
+Two implementations ship here: `DefaultContextBuilder` (no-op — today's
+"every matching artifact, unranked" behavior) and `TokenBudgetContextBuilder`
+(rank candidates, keep a prefix that fits a token budget).
+
+Known limitation (not solved here): `build()` sees the *combined* candidate
+list across every `Consume` an agent declares, not each `Consume` separately.
+A high-volume type (e.g. many `Evidence`) can starve out a low-volume one
+(e.g. the single triggering `Question`) under a tight budget if the
+low-volume artifact ranks lower (e.g. it's older). If that bites, pass a
+`rank_key` that accounts for it, or budget per `Consume` with several
+smaller agents instead of one broad one.
+
+One specific case of that limitation *is* solved: an agent often consumes
+one real content type (`Evidence`) plus a marker type it only needs for
+triggering (a completion/wake-up artifact with little or no meaningful
+text) — see `TokenBudgetContextBuilder`'s `exempt_types`.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, Protocol
+
+from .artifacts import Artifact
+
+if TYPE_CHECKING:
+    from .agents import Agent
+    from .context import Context
+
+
+class TokenCounter(Protocol):
+    """Estimates how many tokens a piece of text costs.
+
+    Exactness is not the contract — see `HeuristicTokenCounter`. Plug in a
+    real tokenizer (tiktoken, a provider's count-tokens endpoint, ...) via
+    this protocol when you need precision for a specific provider.
+    """
+
+    def count(self, text: str) -> int: ...
+
+
+class HeuristicTokenCounter:
+    """Provider-agnostic token estimate: zero dependencies, deliberately
+    conservative (overestimates rather than underestimates).
+
+    ~3.5 chars/token instead of the commonly quoted ~4: a budget built on
+    this errs toward trimming a bit more context, not toward overflowing a
+    provider's window. Good enough for a soft truncation threshold; not a
+    substitute for the real `usage` a provider returns after the call
+    (`LLMResponse.usage`, `providers/contracts.py`).
+    """
+
+    chars_per_token: float = 3.5
+
+    def count(self, text: str) -> int:
+        if not text:
+            return 0
+        return max(1, int(len(text) / self.chars_per_token) + 1)
+
+
+def _default_render(artifact: Artifact[Any]) -> str:
+    return str(artifact.data.model_dump_json())
+
+
+class ContextBuilder(ABC):
+    """Ranks/truncates the artifacts a single agent run would otherwise see.
+
+    Called once per agent run with every candidate matched by that agent's
+    `consumes` (combined across all of them). Returning the list unchanged
+    reproduces today's behavior.
+    """
+
+    @abstractmethod
+    def build(
+        self,
+        context: Context,
+        agent: Agent,
+        candidates: list[Artifact[Any]],
+    ) -> list[Artifact[Any]]: ...
+
+
+class DefaultContextBuilder(ContextBuilder):
+    """No-op: every consumes-matched artifact, in collection order."""
+
+    def build(
+        self, context: Context, agent: Agent, candidates: list[Artifact[Any]]
+    ) -> list[Artifact[Any]]:
+        return candidates
+
+
+class TokenBudgetContextBuilder(ContextBuilder):
+    """Ranks candidates (newest-first by default) and keeps a prefix that
+    fits `max_tokens`, estimated via `token_counter`.
+
+    At least one *costed* (non-exempt) artifact is always kept, even if it
+    alone exceeds the budget — an agent silently getting zero real content
+    is worse than one that gets an oversized item; `max_tokens` is a soft
+    cap, not a hard clip.
+
+    `exempt_types`: artifact types that cost nothing and never trigger that
+    clip — for a marker/trigger type an agent only consumes to wake up
+    (little or no meaningful text), not to reason over. Without this, a
+    freshly created marker can rank first (newest) and either eat the whole
+    budget itself or — worse — silently consume the "at least one" slot,
+    leaving zero real content if the budget is then too tight for the next
+    (real) candidate. Exempt artifacts are still ranked and still kept
+    (still wake the agent up); they just never count toward `max_tokens` or
+    toward what counts as "at least one" content item.
+    """
+
+    def __init__(
+        self,
+        *,
+        max_tokens: int | None = None,
+        token_counter: TokenCounter | None = None,
+        rank_key: Callable[[Artifact[Any]], Any] | None = None,
+        render: Callable[[Artifact[Any]], str] | None = None,
+        exempt_types: tuple[type, ...] = (),
+    ):
+        self.max_tokens = max_tokens
+        self.token_counter = token_counter or HeuristicTokenCounter()
+        self.rank_key = rank_key or (lambda a: a.updated_at)
+        self.render = render or _default_render
+        self.exempt_types = exempt_types
+
+    def build(
+        self, context: Context, agent: Agent, candidates: list[Artifact[Any]]
+    ) -> list[Artifact[Any]]:
+        ranked = sorted(candidates, key=self.rank_key, reverse=True)
+        if self.max_tokens is None:
+            return ranked
+        kept: list[Artifact[Any]] = []
+        used = 0
+        kept_content = False
+        for artifact in ranked:
+            exempt = type(artifact.data) in self.exempt_types
+            cost = 0 if exempt else self.token_counter.count(self.render(artifact))
+            if kept_content and used + cost > self.max_tokens:
+                break
+            kept.append(artifact)
+            used += cost
+            if not exempt:
+                kept_content = True
+        return kept

{reactifact-0.7.0 → reactifact-0.8.0}/reactifact/llm_agent.py

@@ -137,6 +137,7 @@ class HITLLMAgent(Agent):
     tools: Sequence[Tool] | dict[str, Tool] = ()
     max_steps: int = 8
     max_asks: int = 2
+    max_approvals: int = 3
     resume_announce: Callable[[str], str] | None = None
     temperature: float | None = None
     max_tokens: int | None = None
@@ -162,6 +163,7 @@ class HITLLMAgent(Agent):
                 tools=self.tools,
                 max_steps=self.max_steps,
                 max_asks=self.max_asks,
+                max_approvals=self.max_approvals,
                 resume_announce=self.resume_announce,
                 temperature=self.temperature,
                 max_tokens=self.max_tokens,

{reactifact-0.7.0 → reactifact-0.8.0}/reactifact/recipes/__init__.py

@@ -13,6 +13,17 @@ keep reappearing across agent codebases and the bundled examples:
 - `StatusMachine` — a `Produce` that deterministically advances an artifact's
   `status` lifecycle driven by a pure `next_status(context, key)` (§67, §69) —
   see `recipes.status`;
+- `PlanExecute` — sequential plan → execute → finish: ordering, gating each
+  step on its predecessor's result, and completion detection owned by the
+  recipe; domain supplies `plan`/`execute_step`/`finish` (§24, §42, §69) —
+  see `recipes.plan_execute`;
+- `Router` / `ApprovalGate` — classify a request into a route with a
+  deterministic fallback, and ask a human to sign off on a report before
+  finalizing it (§60, §67) — see `recipes.supervisor`;
+- `ReflectionLoop` — generate → critique → regenerate: round-capping, the
+  accept threshold, and completion detection owned by the recipe; domain
+  supplies `draft`/`critique`/`rewrite`/`finish` (§24, §42, §69) — see
+  `recipes.reflection`;
 - `WindowSummarizer` / `WindowPruner` / `llm_summarizer` — bounded
   conversation memory: periodic summarization + pruning as two plain
   `Produce`s, domain owns the summarizer callback and the summary artifact
@@ -34,15 +45,22 @@ from __future__ import annotations
 
 from .inputs import find, find_all
 from .memory import WindowPruner, WindowSummarizer, llm_summarizer
+from .plan_execute import PlanExecute
+from .reflection import ReflectionLoop
 from .resolve import materialize_doc
 from .rollback import changed_fields, downstream_fields, earliest_stage
 from .search import fan_out_sources
 from .skills import Skill, load_skills, match_skills
 from .status import StatusMachine
+from .supervisor import ApprovalGate, Router
 from .text import EN_STOPWORDS, keyword_score, stem, stem_words
 
 __all__ = [
+    "ApprovalGate",
     "EN_STOPWORDS",
+    "PlanExecute",
+    "ReflectionLoop",
+    "Router",
     "Skill",
     "StatusMachine",
     "WindowPruner",