reactifact 0.6.1__tar.gz → 0.8.0__tar.gz

{reactifact-0.6.1 → reactifact-0.8.0}/PKG-INFO

@@ -1,20 +1,22 @@
 Metadata-Version: 2.4
 Name: reactifact
-Version: 0.6.1
+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 :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 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,16 +36,25 @@ 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
 
-# reactifact
+<p align="center">
+  <img src="docs/img/reactifact-hero.png" alt="reactifact — Agents that react to artifacts, not graphs" width="800">
+</p>
 
 **Stop drawing the graph. Build agents as reactions to versioned, provable artifacts.**
 
 [![CI](https://github.com/bzdvdn/reactifact/actions/workflows/ci.yml/badge.svg)](https://github.com/bzdvdn/reactifact/actions/workflows/ci.yml)
-[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue)](https://github.com/bzdvdn/reactifact)
+[![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%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
@@ -56,6 +67,11 @@ react to events — there is no graph, no node pipeline.
 
 ![Left: a hand-wired fetch → verify → answer pipeline. Right: reactifact — search_agent and answer_agent each declare only what they consume and produce, wired together by Context, never each other.](docs/img/wiring.svg)
 
+Two agents explore independently on their own forks and merge back automatically
+— and when they disagree, reactifact refuses to merge silently:
+
+![forklab demo: two strategies (depth/breadth) investigate on separate forks and merge cleanly; a second run edits the same artifact on both forks and reactifact raises MergeConflict instead of guessing, then re-merges under an explicit policy.](docs/img/forklab-demo.gif)
+
 ```bash
 pip install reactifact
 ```
@@ -157,12 +173,33 @@ actual state.
 | Retries/rollback are manual | Context is **git-like versioned** (diff, rollback, branch, merge) |
 | "Who produced this?" is lost | **Provenance** links every derived artifact to its inputs |
 | The model guesses the numbers | **Calculations are calculated** — the LLM is a reasoning component, not the source of truth |
+| Tracing needs a SaaS add-on | **Native trace store** (SQLite + dashboard), exportable to Langfuse/Postgres |
+| MCP via a framework adapter | **MCP both ways** built in — call any server, or expose your own `Context` as one |
+| Pulls in a framework's dependency tree | **3 core deps**: `pydantic`, `httpx`, `python-dotenv` |
 
 Reactive. Deterministic. Accountable.
 
 Full breakdown, including where reactifact is *not* the right choice:
 [docs/en/comparison.md](docs/en/comparison.md).
 
+**Proof, not a claim** — [`examples/ledger`](examples/ledger) is a 4-artifact
+billing calc (`LaborCost`, `Tax`, `Discount`, `Total`) with no LLM, fully
+offline. Edit *one* fact and see what actually reruns:
+
+```text
+>>> editing ONLY TaxRate (0.08 -> 0.12) — a fact nothing about
+>>> LaborCost or Discount ever consumed.
+
+  LaborCost    value=500.0      version=0   # untouched
+  Tax          value=60.0       version=1   # recomputed
+  Discount     value=25.0       version=0   # untouched
+  Total        value=535.0      version=1   # recomputed
+```
+
+2 of 4 artifacts recompute — the 2 that actually depend on `TaxRate` —
+because `Artifact.version` tracks real consumption, not a graph edge you drew
+by hand. Run it yourself: `uv run python -m examples.ledger.main`.
+
 ## Core primitives
 
 - **Context** — versioned working state, git-like commits, `diff`/`rollback`/`merge`.
@@ -170,7 +207,7 @@ Full breakdown, including where reactifact is *not* the right choice:
 - **Effects** — an agent states its change via `self.effects.create/update/link/ask`; the runtime compiles it.
 - **Patch** — the compiled, validated change-set applied as one atomic commit.
 - **Agent** — a thin container declaring `consumes`/`produces`; logic lives in a `Produce`.
-- **Source** — retrieval is a capability: vector search is *one* strategy; direct API, keyword, SQL, filesystem are equally first-class.
+- **Source** — retrieval is a capability: vector search is *one* strategy, not the only one; filesystem, CSV, and the web are equally first-class today (direct API, keyword, and SQL sources are on the [roadmap](docs/roadmap.md#next), not yet shipped).
 - **Provenance** — every derived artifact links to what produced it
   (`Answer —supported_by→ Claim —derived_from→ Evidence —extracted_from→ Doc`).
 - **HITL** — humans as `effects.ask(...)` → `PendingQuestion`, answered via `effects.resume(...)` like any agent.
@@ -211,7 +248,7 @@ uv run python ./examples/devops/web.py         # HITL ops assistant + trace dash
 ```
 
 Classic-pattern ports run as one-liners too:
-`python -m examples.{reflection,map_reduce,supervisor,summarize,time_travel,adaptive,ledger}.main`.
+`python -m examples.{reflection,map_reduce,supervisor,summarize,time_travel,plan_execute,adaptive,ledger}.main`.
 
 ## Examples (in-repo, not shipped)
 
@@ -224,7 +261,7 @@ Classic-pattern ports run as one-liners too:
 - `ledger` — offline proof of reactive recompute: edit one fact, only its real `Consume`rs re-run.
 - `llm_ladder` — the workflow from one LLM call to state-changing patches (3 levels).
 - `adaptive` — hybrid scheduler: rule filters + deterministic rank + LLM tie-break + `rank_limit`.
-- `{reflection,map_reduce,supervisor,summarize,time_travel}` — canonical ports (see [port-matrix](docs/en/port-matrix.md)).
+- `{reflection,map_reduce,supervisor,summarize,time_travel,plan_execute}` — canonical ports (see [port-matrix](docs/en/port-matrix.md)).
 
 ## Documentation
 
@@ -236,6 +273,7 @@ Classic-pattern ports run as one-liners too:
 - [Comparison](docs/en/comparison.md) — reactifact vs LangGraph/CrewAI, feature by feature, and when *not* to use reactifact.
 - [Tutorial · llm-ladder](docs/en/examples.md#tutorial-ladder) — learn the workflow.
 - [docs/constitution.md](docs/constitution.md) — the full design rationale and invariants.
+- [Roadmap](docs/roadmap.md) — what's next, and what's deliberately out of scope.
 
 ## Development
 

reactifact-0.6.1/reactifact.egg-info/PKG-INFO → reactifact-0.8.0/README.md

@@ -1,49 +1,16 @@
-Metadata-Version: 2.4
-Name: reactifact
-Version: 0.6.1
-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: Changelog, https://github.com/bzdvdn/reactifact/blob/master/CHANGELOG.md
-Keywords: agents,llm,ai-agents,reactive,provenance,orchestration,agentic
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Typing :: Typed
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: pydantic>=2.13.4
-Requires-Dist: httpx>=0.27
-Requires-Dist: python-dotenv>=1.0
-Provides-Extra: dev
-Requires-Dist: ruff>=0.8; extra == "dev"
-Requires-Dist: mypy>=1.11; extra == "dev"
-Requires-Dist: pytest>=9.1.1; extra == "dev"
-Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
-Provides-Extra: web
-Requires-Dist: fastapi>=0.115; extra == "web"
-Requires-Dist: uvicorn[standard]>=0.30; extra == "web"
-Provides-Extra: pg
-Requires-Dist: psycopg[binary]>=3.2; extra == "pg"
-Provides-Extra: mcp
-Requires-Dist: mcp>=2.2; extra == "mcp"
-Dynamic: license-file
-
-# reactifact
+<p align="center">
+  <img src="docs/img/reactifact-hero.png" alt="reactifact — Agents that react to artifacts, not graphs" width="800">
+</p>
 
 **Stop drawing the graph. Build agents as reactions to versioned, provable artifacts.**
 
 [![CI](https://github.com/bzdvdn/reactifact/actions/workflows/ci.yml/badge.svg)](https://github.com/bzdvdn/reactifact/actions/workflows/ci.yml)
-[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue)](https://github.com/bzdvdn/reactifact)
+[![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%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
@@ -56,6 +23,11 @@ react to events — there is no graph, no node pipeline.
 
 ![Left: a hand-wired fetch → verify → answer pipeline. Right: reactifact — search_agent and answer_agent each declare only what they consume and produce, wired together by Context, never each other.](docs/img/wiring.svg)
 
+Two agents explore independently on their own forks and merge back automatically
+— and when they disagree, reactifact refuses to merge silently:
+
+![forklab demo: two strategies (depth/breadth) investigate on separate forks and merge cleanly; a second run edits the same artifact on both forks and reactifact raises MergeConflict instead of guessing, then re-merges under an explicit policy.](docs/img/forklab-demo.gif)
+
 ```bash
 pip install reactifact
 ```
@@ -157,12 +129,33 @@ actual state.
 | Retries/rollback are manual | Context is **git-like versioned** (diff, rollback, branch, merge) |
 | "Who produced this?" is lost | **Provenance** links every derived artifact to its inputs |
 | The model guesses the numbers | **Calculations are calculated** — the LLM is a reasoning component, not the source of truth |
+| Tracing needs a SaaS add-on | **Native trace store** (SQLite + dashboard), exportable to Langfuse/Postgres |
+| MCP via a framework adapter | **MCP both ways** built in — call any server, or expose your own `Context` as one |
+| Pulls in a framework's dependency tree | **3 core deps**: `pydantic`, `httpx`, `python-dotenv` |
 
 Reactive. Deterministic. Accountable.
 
 Full breakdown, including where reactifact is *not* the right choice:
 [docs/en/comparison.md](docs/en/comparison.md).
 
+**Proof, not a claim** — [`examples/ledger`](examples/ledger) is a 4-artifact
+billing calc (`LaborCost`, `Tax`, `Discount`, `Total`) with no LLM, fully
+offline. Edit *one* fact and see what actually reruns:
+
+```text
+>>> editing ONLY TaxRate (0.08 -> 0.12) — a fact nothing about
+>>> LaborCost or Discount ever consumed.
+
+  LaborCost    value=500.0      version=0   # untouched
+  Tax          value=60.0       version=1   # recomputed
+  Discount     value=25.0       version=0   # untouched
+  Total        value=535.0      version=1   # recomputed
+```
+
+2 of 4 artifacts recompute — the 2 that actually depend on `TaxRate` —
+because `Artifact.version` tracks real consumption, not a graph edge you drew
+by hand. Run it yourself: `uv run python -m examples.ledger.main`.
+
 ## Core primitives
 
 - **Context** — versioned working state, git-like commits, `diff`/`rollback`/`merge`.
@@ -170,7 +163,7 @@ Full breakdown, including where reactifact is *not* the right choice:
 - **Effects** — an agent states its change via `self.effects.create/update/link/ask`; the runtime compiles it.
 - **Patch** — the compiled, validated change-set applied as one atomic commit.
 - **Agent** — a thin container declaring `consumes`/`produces`; logic lives in a `Produce`.
-- **Source** — retrieval is a capability: vector search is *one* strategy; direct API, keyword, SQL, filesystem are equally first-class.
+- **Source** — retrieval is a capability: vector search is *one* strategy, not the only one; filesystem, CSV, and the web are equally first-class today (direct API, keyword, and SQL sources are on the [roadmap](docs/roadmap.md#next), not yet shipped).
 - **Provenance** — every derived artifact links to what produced it
   (`Answer —supported_by→ Claim —derived_from→ Evidence —extracted_from→ Doc`).
 - **HITL** — humans as `effects.ask(...)` → `PendingQuestion`, answered via `effects.resume(...)` like any agent.
@@ -211,7 +204,7 @@ uv run python ./examples/devops/web.py         # HITL ops assistant + trace dash
 ```
 
 Classic-pattern ports run as one-liners too:
-`python -m examples.{reflection,map_reduce,supervisor,summarize,time_travel,adaptive,ledger}.main`.
+`python -m examples.{reflection,map_reduce,supervisor,summarize,time_travel,plan_execute,adaptive,ledger}.main`.
 
 ## Examples (in-repo, not shipped)
 
@@ -224,7 +217,7 @@ Classic-pattern ports run as one-liners too:
 - `ledger` — offline proof of reactive recompute: edit one fact, only its real `Consume`rs re-run.
 - `llm_ladder` — the workflow from one LLM call to state-changing patches (3 levels).
 - `adaptive` — hybrid scheduler: rule filters + deterministic rank + LLM tie-break + `rank_limit`.
-- `{reflection,map_reduce,supervisor,summarize,time_travel}` — canonical ports (see [port-matrix](docs/en/port-matrix.md)).
+- `{reflection,map_reduce,supervisor,summarize,time_travel,plan_execute}` — canonical ports (see [port-matrix](docs/en/port-matrix.md)).
 
 ## Documentation
 
@@ -236,6 +229,7 @@ Classic-pattern ports run as one-liners too:
 - [Comparison](docs/en/comparison.md) — reactifact vs LangGraph/CrewAI, feature by feature, and when *not* to use reactifact.
 - [Tutorial · llm-ladder](docs/en/examples.md#tutorial-ladder) — learn the workflow.
 - [docs/constitution.md](docs/constitution.md) — the full design rationale and invariants.
+- [Roadmap](docs/roadmap.md) — what's next, and what's deliberately out of scope.
 
 ## Development
 

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "reactifact"
-version = "0.6.1"
+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"
@@ -12,13 +12,15 @@ license = "MIT"
 license-files = ["LICENSE"]
 keywords = ["agents", "llm", "ai-agents", "reactive", "provenance", "orchestration", "agentic"]
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Topic :: Scientific/Engineering :: Artificial Intelligence",
     "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"]
@@ -93,6 +105,15 @@ reactifact = ["py.typed"]
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 
+# Enforced by CI's `pytest --cov=reactifact --cov-fail-under=85` (see
+# .github/workflows/ci.yml). Current coverage is ~90%; 85% leaves headroom
+# for `reactifact/tracing/postgres.py`, whose own test intentionally only
+# checks the graceful-ImportError path without `psycopg` installed (`pg` is
+# an opt-in extra with no external service in CI) rather than needing a
+# per-file carve-out.
+[tool.coverage.report]
+fail_under = 85
+
 [tool.ruff]
 target-version = "py311"
 line-length = 88

{reactifact-0.6.1 → 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.6.1"
+__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.6.1 → 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.6.1 → reactifact-0.8.0}/reactifact/branching.py

@@ -5,8 +5,12 @@
 git-like state operations `Context.clone()`/`.branch()`/`.merge_from()`/
 `.merge()` delegate to — moved here so the git-like algorithm lives next to
 the concept it implements, not folded into `Context`'s general CRUD/relations/
-HITL surface. `BranchStore` only *persists* named forks so they survive a
-restart:
+HITL surface. Application code should call the `Context` methods (see
+[docs/en/branching.md](../docs/en/branching.md)); these module-level
+functions are exported for building on `Context` without one already in
+hand (e.g. `BranchStore`'s own load/merge path below), not as an equally
+first-class alternative entry point. `BranchStore` only *persists* named
+forks so they survive a restart:
 
     store = BranchStore(SQLiteKVBackend("sessions.sqlite3"))
     await store.save_branch(ctx_branch, session_id="demo", name="hypothesis-a")
@@ -59,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
 
 
@@ -91,13 +96,8 @@ def merge_context_from(target: Context, other: Context) -> None:
                 operations.append(Update(other_id, new_data))
         else:
             new_data = other_artifact.data.model_copy(deep=True)
-            # NOTE: no `id=other_id` — matches the pre-extraction behavior of
-            # `Context.merge_from()` exactly (a merged-in artifact absent from
-            # `target` gets a freshly minted id, not `other_id`). Not fixed
-            # here — a real behavior change belongs in its own change, not a
-            # pure extraction.
-            target.create(new_data)
-            operations.append(Create(new_data))
+            target.create(new_data, id=other_id)
+            operations.append(Create(new_data, id=other_id))
     for rel in other.relations():
         if (rel.source_id, rel.relation, rel.target_id) not in target._relations:
             target.link(rel.source_id, rel.relation, rel.target_id)
@@ -210,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.6.1 → 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)