reactifact 0.7.0__tar.gz → 0.9.0__tar.gz

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

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: reactifact
-Version: 0.7.0
+Version: 0.9.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
@@ -99,21 +106,21 @@ DOCS = {
 
 
 @produce(Evidence)
-async def find_evidence(context, inputs, event, effects):
-    question = next((a for a in inputs if isinstance(a.data, Question)), None)
+async def find_evidence(call):
+    question = next((a for a in call.inputs if isinstance(a.data, Question)), None)
     if question is None:
         return None
     hit = next((v for k, v in DOCS.items() if k in question.data.text.lower()), None)
     if hit is not None:
-        effects.create(Evidence(text=hit))
+        call.effects.create(Evidence(text=hit))
 
 
 @produce(Answer)
-async def answer_from_evidence(context, inputs, event, effects):
-    evidence = next((a for a in inputs if isinstance(a.data, Evidence)), None)
+async def answer_from_evidence(call):
+    evidence = next((a for a in call.inputs if isinstance(a.data, Evidence)), None)
     if evidence is None:
         return None
-    effects.create(Answer(text=evidence.data.text)).link("supported_by", evidence)
+    call.effects.create(Answer(text=evidence.data.text)).link("supported_by", evidence)
 
 
 search_agent = create_agent("search", consumes=[Consume(Question)], produces=[find_evidence])

{reactifact-0.7.0 → reactifact-0.9.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
@@ -61,21 +62,21 @@ DOCS = {
 
 
 @produce(Evidence)
-async def find_evidence(context, inputs, event, effects):
-    question = next((a for a in inputs if isinstance(a.data, Question)), None)
+async def find_evidence(call):
+    question = next((a for a in call.inputs if isinstance(a.data, Question)), None)
     if question is None:
         return None
     hit = next((v for k, v in DOCS.items() if k in question.data.text.lower()), None)
     if hit is not None:
-        effects.create(Evidence(text=hit))
+        call.effects.create(Evidence(text=hit))
 
 
 @produce(Answer)
-async def answer_from_evidence(context, inputs, event, effects):
-    evidence = next((a for a in inputs if isinstance(a.data, Evidence)), None)
+async def answer_from_evidence(call):
+    evidence = next((a for a in call.inputs if isinstance(a.data, Evidence)), None)
     if evidence is None:
         return None
-    effects.create(Answer(text=evidence.data.text)).link("supported_by", evidence)
+    call.effects.create(Answer(text=evidence.data.text)).link("supported_by", evidence)
 
 
 search_agent = create_agent("search", consumes=[Consume(Question)], produces=[find_evidence])

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "reactifact"
-version = "0.7.0"
+version = "0.9.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.9.0}/reactifact/__init__.py

@@ -31,7 +31,7 @@ from .effects import Effects, Handle
 from .events import Event, EventType
 from .interrupt import PendingQuestion
 from .patches import Create, Delete, Link, Patch, Relation, Unlink, Update
-from .produce import Produce, produce
+from .produce import Produce, ProduceCall, produce
 from .providers import (
     EmbeddingProvider,
     FakeEmbedder,
@@ -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.9.0"
 
 __all__ = [
     "Agent",
@@ -72,6 +72,7 @@ __all__ = [
     "Patch",
     "PendingQuestion",
     "Produce",
+    "ProduceCall",
     "Relation",
     "RunOutcome",
     "RunStats",

reactifact-0.9.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.9.0}/reactifact/agents.py

@@ -7,9 +7,9 @@ from typing import Any
 from .artifacts import Artifact
 from .consume import Consume
 from .context import Context
-from .events import Event
+from .events import Event, EventType
 from .patches import Patch
-from .produce import Produce
+from .produce import Produce, ProduceCall
 from .triggers import Trigger
 
 
@@ -25,6 +25,15 @@ class Agent(ABC):  # noqa: B024 — interface without abstract methods, run() ha
     produces: Sequence[Produce[Any]] | None = None
     #: Declarative capability labels (§25), consumed by the adaptive policy.
     capabilities: tuple[str, ...] = ()
+    #: Explicit trigger override — for the *imperative* style (`Agent`
+    #: subclass overriding `run()` directly, no `consumes`/`produces` at
+    #: all, see `run()`'s own docstring). That style never calls
+    #: `_collect_inputs()`, so `Consume` has nothing to attach to; `triggers`
+    #: is the only way such an agent says when to wake up. For the
+    #: declarative style (`consumes`/`produces`, the common case), leave this
+    #: unset — `triggers` auto-derives from `consumes` instead, and a
+    #: `Consume` that should feed inputs without also waking the agent uses
+    #: `Consume(..., wakes=False)` rather than a second, hand-maintained list.
     triggers: list[Trigger] = []
     # Run priority within a single generation: lower value runs earlier.
     # Useful for "finishers"/evaluators that logically run last (§24).
@@ -80,7 +89,17 @@ class Agent(ABC):  # noqa: B024 — interface without abstract methods, run() ha
                     )
 
     def matches(self, event: Event, context: Context | None = None) -> bool:
-        return any(trigger.matches(event, context) for trigger in self.triggers)
+        return bool(self.matching_triggers(event, context))
+
+    def matching_triggers(
+        self, event: Event, context: Context | None = None
+    ) -> list[Trigger]:
+        """Every trigger that matches `event` — `matches()` is just
+        `bool(...)` of this. `Runtime._arun_once_impl` uses the full list
+        (not just the bool) to decide whether *every* matching trigger asks
+        for debouncing (`Trigger.debounce`) before collapsing repeat events
+        into one run."""
+        return [trigger for trigger in self.triggers if trigger.matches(event, context)]
 
     def collect_inputs(self, context: Context) -> list[Artifact[Any]]:
         """Public access to the consumed artifacts.
@@ -90,15 +109,22 @@ 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]] = []
         for c in self.consumes:
-            artifacts = context.list_artifacts(c.artifact_type)
-            if c.condition:
-                artifacts = [a for a in artifacts if c.condition(a)]
-            inputs.extend(artifacts)
+            inputs.extend(c.collect(context))
+        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:
@@ -118,8 +144,9 @@ class Agent(ABC):  # noqa: B024 — interface without abstract methods, run() ha
     async def execute(self, context: Context, event: Event | None = None) -> None:
         """Runs the agent's produces (usually on an event).
 
-        Effects-first (§24): produces write `self.effects.*` and return None;
-        the *runtime* compiles the effect slot into one atomic patch. This method
+        Effects-first (§24): produces write `self.effects.*`/`call.effects.*`
+        and return None; the *runtime* compiles the effect slot into one
+        atomic patch. This method
         only *runs* the produces — it does not build a patch. (`run` remains the
         agent-level escape hatch for custom Agent subclasses that assemble a
         change-set by hand; the runtime merges its result after the effects.)
@@ -128,9 +155,56 @@ class Agent(ABC):  # noqa: B024 — interface without abstract methods, run() ha
             return None
         inputs = self._collect_inputs(context)
         for p in self.produces:
-            await p.produce(context, inputs, event)
+            runs, trigger = self._resolve_produce_call(p, event, context)
+            if not runs:
+                continue
+            call = ProduceCall(
+                context=context, inputs=inputs, event=event, trigger=trigger
+            )
+            await p.produce(call)
         return None
 
+    @staticmethod
+    def _resolve_produce_call(
+        p: Produce[Any], event: Event | None, context: Context
+    ) -> tuple[bool, Artifact[Any] | None]:
+        """Whether to call `p.produce()` for `event`, and the triggering
+        artifact to put on the `ProduceCall.trigger` field (see `Produce`'s
+        docstring, and `ProduceCall`'s, for the full contract).
+
+        `p.reacts_to is None` (the default): unrestricted, matching the
+        pre-`reacts_to` behavior where every produce ran on every event this
+        agent got — `trigger` is still resolved on a best-effort basis (for
+        a produce that wants it without narrowing `reacts_to`), but never a
+        reason to skip the call, since there's no per-type contract to hold
+        it to.
+
+        `p.reacts_to` set: exact type equality against `event.artifact_type`
+        (same convention as `Trigger.artifact_type`, not `issubclass` — that
+        one's a `Context.list_artifacts()` convention for querying by base
+        type). For a CREATED/UPDATED/STALE event, also requires
+        `context.get(event.artifact_id)` to still resolve — the artifact may
+        have been deleted by another agent earlier in the same generation
+        (the same race `Trigger.matches()` documents) — so `reacts_to`, once
+        set, guarantees `call.trigger` is always a live, correctly-typed
+        artifact. A DELETED event is exempt from that liveness requirement:
+        `context.get(...)` correctly returning `None` *is* the event there,
+        not a race, so the produce still runs with `trigger=None` —
+        deletion-reacting code is expected to handle that itself.
+        """
+        if event is None:
+            return (p.reacts_to is None), None
+        if p.reacts_to is not None and event.artifact_type not in p.reacts_to:
+            return False, None
+        trigger = context.get(event.artifact_id)
+        if (
+            p.reacts_to is not None
+            and trigger is None
+            and event.type is not EventType.ARTIFACT_DELETED
+        ):
+            return False, None
+        return True, trigger
+
 
 def create_agent(
     name: str,
@@ -156,7 +230,10 @@ def create_agent(
     )
     ```
 
-    Falls back to `name` defaults the same way as `Agent.__init__`.
+    Falls back to `name` defaults the same way as `Agent.__init__`. Pass
+    `triggers` only for the rare imperative style with no `consumes` at all
+    (see `Agent.triggers`'s own docstring) — the ordinary declarative case
+    should leave it unset and use `Consume(..., wakes=False)` instead.
     """
     agent = Agent(
         name=name, triggers=triggers if triggers is not None else [], priority=priority

{reactifact-0.7.0 → reactifact-0.9.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.9.0}/reactifact/chat.py

@@ -16,10 +16,11 @@ Two levels of use:
 from __future__ import annotations
 
 import asyncio
+import inspect
 import logging
 from collections.abc import AsyncGenerator, AsyncIterator, Callable, Sequence
 from contextlib import asynccontextmanager
-from typing import Any
+from typing import Any, Literal
 
 from pydantic import BaseModel
 
@@ -64,7 +65,7 @@ async def run_message(
     user_message: type[BaseModel],
     reply: Callable[[Context, str], dict[str, Any]],
     session_id: str = "",
-    create_message: Callable[[Context, str], str] | None = None,
+    create_message: Callable[..., str] | None = None,
     status_kinds: Sequence[str] = ("status",),
     fallback_reply: str = "No reply assembled.",
 ) -> AsyncIterator[ChatEvent]:
@@ -78,7 +79,11 @@ async def run_message(
     `create_message(ctx, text) -> msg_id` overrides how the turn enters the
     context (default: create a `user_message` artifact) — HITL apps where a
     new turn resumes a pending question instead of appending a message
-    (devops-style clarify) pass their own.
+    (devops-style clarify) pass their own. Also accepts the 3-arg shape
+    `create_message(ctx, text, session_id) -> msg_id` for a hook that needs
+    the current turn's `session_id` (e.g. to stamp it onto the created
+    artifact) — detected from the callable's own arity, so the 2-arg shape
+    keeps working unchanged.
 
     `status_kinds` selects which progress event kinds are forwarded as `status`
     frames (default: only `status`; e.g. tool-announcing demos also forward
@@ -92,7 +97,7 @@ async def run_message(
     ctx = runtime.context
     try:
         if create_message is not None:
-            msg_id = create_message(ctx, text)
+            msg_id = _call_create_message(create_message, ctx, text, session_id)
         else:
             msg_id = ctx.create(user_message(text=text, session_id=session_id)).id
     except Exception:
@@ -164,6 +169,45 @@ def _resolve(value: Any) -> Any:
     return value() if callable(value) else value
 
 
+def _accepts_arg(func: Callable[..., Any], count: int) -> bool:
+    """Whether `func` (already known callable) declares at least `count`
+    positional-or-keyword parameters — used to detect the opt-in, per-request
+    call shapes below without breaking the plain zero/two-arg factories that
+    predate them. A callable whose signature can't be inspected (a builtin, a
+    C extension) is assumed to be the old, arg-less shape."""
+    try:
+        params = inspect.signature(func).parameters
+    except (TypeError, ValueError):
+        return False
+    return len(params) >= count
+
+
+def _resolve_with_session(value: Any, session_id: str) -> Any:
+    """Like `_resolve`, but passes `session_id` to `value` when it declares a
+    parameter for it — the per-request factory shape
+    (`resources=lambda session_id: build_resources(session_id)`) alongside
+    the pre-existing zero-arg one (`resources=lambda: build_resources()`),
+    which keeps working unchanged. `ChatAssistant` already knows `session_id`
+    at the point it resolves `resources=`; this just lets a factory opt into
+    reading it instead of reaching for a contextvar/side-channel to get
+    per-request data (e.g. an authenticated user) into `RuntimeResources`.
+    """
+    if not callable(value):
+        return value
+    return value(session_id) if _accepts_arg(value, 1) else value()
+
+
+def _call_create_message(
+    create_message: Callable[..., str], ctx: Context, text: str, session_id: str
+) -> str:
+    """Calls `create_message` with `session_id` appended when it declares a
+    third parameter for it (`(ctx, text, session_id) -> msg_id`), alongside
+    the pre-existing two-arg shape (`(ctx, text) -> msg_id`)."""
+    if _accepts_arg(create_message, 3):
+        return create_message(ctx, text, session_id)
+    return create_message(ctx, text)
+
+
 # --- the canonical chat assistant ----------------------------------------- #
 
 
@@ -182,6 +226,23 @@ class ChatAssistant:
     turns/sessions — that instance is never closed automatically; close it
     yourself at real shutdown.
 
+    `session_save_policy=` passes straight through to `Runtime` — `"per_turn"`
+    trades finer crash-resilience granularity (a save at every commit, the
+    default) for one `session.save()` per turn instead of one per commit,
+    worthwhile once a multi-stage pipeline routinely produces several commits
+    per turn (see `Runtime.__init__`'s own docstring for the trade-off).
+
+    `resources=`/`create_message=` may optionally take the current turn's
+    `session_id` — `resources=lambda session_id: build_resources(session_id)`
+    (e.g. to attach an authenticated user looked up from the session) and
+    `create_message=lambda ctx, text, session_id: ...` — detected from each
+    callable's own arity, so the pre-existing zero/two-arg shapes keep
+    working unchanged. Without this, per-request data (who's asking, not
+    just what they asked) has no way into a turn short of a contextvar/
+    side-channel set by the caller before `stream()`/`invoke()` — `resources=`
+    and `create_message=` were otherwise the only two hooks in this class
+    that never saw it.
+
     Base usage:
 
         assistant = ChatAssistant(
@@ -203,15 +264,16 @@ class ChatAssistant:
         user_message: type[BaseModel],
         reply: Callable[[Context, str], dict[str, Any]],
         session_state: Callable[[Context], dict[str, Any]] | None = None,
-        resources: RuntimeResources | Callable[[], RuntimeResources] | None = None,
+        resources: RuntimeResources | Callable[..., RuntimeResources] | None = None,
         budget: Budget | None = None,
         max_concurrency: int | None = None,
         tracer: Any = None,
-        create_message: Callable[[Context, str], str] | None = None,
+        create_message: Callable[..., str] | None = None,
         status_kinds: Sequence[str] = ("status",),
         fallback_reply: str = "No reply assembled.",
         isolate_errors: bool = False,
         on_agent_error: Callable[[Agent, Event, BaseException], None] | None = None,
+        session_save_policy: Literal["per_commit", "per_turn"] = "per_commit",
     ):
         self.store = store
         self._agents = agents
@@ -227,6 +289,7 @@ class ChatAssistant:
         self._fallback_reply = fallback_reply
         self._isolate_errors = isolate_errors
         self._on_agent_error = on_agent_error
+        self._session_save_policy = session_save_policy
         # Serializes concurrent turns on the *same* session_id (a double
         # submit, a client retry): without this, two overlapping stream()
         # calls both load the same starting state and the later save() wins,
@@ -262,7 +325,9 @@ class ChatAssistant:
                         self._session_locks.pop(session_id, None)
 
     async def _open(self, session_id: str) -> Session:
-        return await self.store.open(session_id, resources=_resolve(self._resources))
+        return await self.store.open(
+            session_id, resources=_resolve_with_session(self._resources, session_id)
+        )
 
     def _build_runtime(self, session: Session) -> Runtime:
         return Runtime(
@@ -274,6 +339,7 @@ class ChatAssistant:
             tracer=_resolve(self._tracer),
             isolate_errors=self._isolate_errors,
             on_agent_error=self._on_agent_error,
+            session_save_policy=self._session_save_policy,
         )
 
     async def stream(self, text: str, session_id: str = "") -> AsyncIterator[ChatEvent]:

{reactifact-0.7.0 → reactifact-0.9.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)