react-agent-harness 0.1.0__tar.gz → 0.2.0__tar.gz

{react_agent_harness-0.1.0/react_agent_harness.egg-info → react_agent_harness-0.2.0}/PKG-INFO

@@ -1,9 +1,10 @@
 Metadata-Version: 2.4
 Name: react-agent-harness
-Version: 0.1.0
+Version: 0.2.0
 Summary: Multi-agent LLM orchestration: hybrid DAG planning, two-tier memory, streaming
 Requires-Python: >=3.10
 License-File: LICENSE
+Requires-Dist: prompt_toolkit>=3.0
 Provides-Extra: lance
 Requires-Dist: lancedb>=0.6; extra == "lance"
 Requires-Dist: pyarrow>=14; extra == "lance"

{react_agent_harness-0.1.0 → react_agent_harness-0.2.0}/README.md

@@ -38,6 +38,7 @@ harness/events.py           BusEvent + EventType — canonical event vocabulary
 harness/llm/openai.py       OpenAILLM — OpenAI adapter with usage + cost tracking
 harness/annotation.py       Annotation store + AnnotationHook — RLHF trajectory capture
 harness/hitl.py             HITL approval gate — interactive CLI, session-allow list
+harness/steering.py         Async steering — agent.steer(text), StdinRouter pub/sub, FileSteer, factory helpers
 harness/checkpoint.py       CheckpointStore + _ResumeHint + maybe_resume_key — pluggable run-state persistence (file + Redis); auto-resume built into dispatch_stream / run_stream
 harness/otel.py             OTELHook — OpenTelemetry span exporter (opt-in)
 harness/executor_bridge.py  ExecutorBridge + ExecutorTool — controlled subprocess launcher with optional Docker sandboxing
@@ -720,3 +721,94 @@ When the human types a correction instead of y/n:
 
 The `annotation_store` and `checkpoint_store` are independent — both can be
 wired simultaneously for RLHF data collection with HITL review.
+
+## Async steering
+
+HITL is synchronous — it only fires when a gated tool is about to run. For
+out-of-band course-correction (HTTP handler, supervisor agent, file watcher,
+or a human typing in the terminal), each `BaseAgent` exposes a
+non-blocking `steer(text)` method. Items are drained at the **top of each
+ReAct iteration**, before the per-step checkpoint write and before the
+next think, then appended to `WorkingMemory` as a `Human guidance: <text>`
+user message. The LLM sees them on the next think and adjusts. One
+`HUMAN_GUIDANCE` `BusEvent` fires per drained item.
+
+Why a queue instead of writing straight to `WorkingMemory`: `steer()` is
+synchronous and callable from any coroutine; `WorkingMemory.append` is
+async (eviction can call the LLM). The queue is the producer/consumer
+boundary, enforces step-boundary delivery, and keeps WM single-writer.
+
+### Programmatic API (always available)
+
+```python
+agent.steer("skip the legal database, use academic sources only")
+```
+
+Fires immediately; the agent picks it up at the next step boundary.
+Worst-case latency = remaining tool time + next-think time.
+
+### Sources via factory (so orchestrated agents are reachable)
+
+`BaseAgent` and `AgentRuntime` both accept `steering_source_factory` — a
+callable `(agent) -> async ctx mgr`. The agent enters the source on
+`run_stream`, exits on completion. No live-agent registry; agents the
+runtime constructs internally still get steering.
+
+Two built-in factories:
+
+```python
+from harness.steering import file_steering_factory, stdin_steering_factory
+
+# 1. File-based — one file per agent, polled for appends (no shared resource)
+runtime = AgentRuntime(
+    ...,
+    steering_source_factory=file_steering_factory(
+        "/tmp/ah-{run_id}-{agent_id}.steer"
+    ),
+)
+# Steer from any other terminal:
+#   echo "wrap up and synthesise" >> /tmp/ah-<run_id>-researcher.steer
+
+# 2. Stdin-based — single shared StdinRouter with prefix routing
+runtime = AgentRuntime(
+    ...,
+    steering_source_factory=stdin_steering_factory(),
+)
+# At the terminal:
+#   researcher: skip the legal db, focus on academic
+#   writer:     keep the report under 500 words
+#   *:          stop after this step
+```
+
+Single-agent stdin runs accept lines with no prefix. Multi-agent runs
+require `agent_id: text` (or `*: text` for broadcast); unknown or
+unprefixed lines print a stderr hint and are discarded.
+
+The stdin factory's underlying `StdinRouter` is started/stopped
+automatically — the runtime detects the factory's async-context-manager
+shape and wraps `dispatch_stream` / `run_stream` / `run_routed_stream`
+around it. Ref-counted so nested calls (`dispatch_stream → run_stream`)
+don't double-start the router.
+
+### HITL coordination
+
+When a `StdinRouter` is active, HITL calls `router.claim_next_line()`
+**before** printing its approval banner — the next stdin line resolves
+HITL's pending Future and bypasses pub/sub. After resolution, subsequent
+lines route to steering subscribers normally. When no router is active,
+HITL falls back to a standalone `prompt_toolkit` session, ensuring consistent
+key-bindings (like Enter-submits and Alt-Enter/Ctrl-J-newline) across both paths.
+
+### Constraints
+
+- Steering arrives **between steps**, never mid-tool, never mid-think.
+  Tools that are already running complete; the LLM stream that's
+  already producing completes; guidance lands at the next safe boundary.
+- Guidance queued **after** the LLM emits `action: "finish"` is lost —
+  the agent already decided it's done.
+- Crash between drain and next checkpoint write → the queued items are
+  in the persisted WM. Crash between checkpoint write and next drain →
+  lost; re-steer after `--resume`.
+
+See `examples/complex_sysaudit_demo.py` for stdin steering across three
+agents alongside HITL on the shell tool.

{react_agent_harness-0.1.0 → react_agent_harness-0.2.0}/agents/base.py

@@ -27,6 +27,7 @@ Token management:
 from __future__ import annotations
 
 import asyncio
+import contextlib
 import json
 import logging
 import uuid
@@ -132,6 +133,7 @@ class BaseAgent:
         guard,
         llm,
         checkpoint_store: Any | None = None,  # FileCheckpointStore / RedisCheckpointStore
+        steering_source_factory: Any | None = None,  # (BaseAgent) -> async ctx mgr
     ) -> None:
         self.config = config
         self.role = config.role  # exposed for orchestrator planner prompt
@@ -145,10 +147,60 @@ class BaseAgent:
         self._task: str = ""
         self._last_think_error: str | None = None
         self._ckp_id: str = ""  # f"{run_id}:{agent_id}" — unique per agent per run
+        # Async steering queue — items drained at the top of each ReAct
+        # step (before checkpoint, before think). Created eagerly so
+        # callers can steer() before run_stream starts.
+        self._steering: asyncio.Queue[str] = asyncio.Queue()
+        # Optional factory: called once at run_stream entry. Must return an
+        # async context manager that, while active, may call agent.steer().
+        # The agent owns the source's lifecycle — no live-instance registry.
+        self._steering_source_factory = steering_source_factory
         self._resume_key: str = (
             ""  # key printed in --resume banner; set by orchestrator to outer run_id
         )
 
+    # ── Async steering ────────────────────────────────────────────────────────
+
+    def steer(self, text: str) -> None:
+        """Inject human guidance to be consumed at the next ReAct step boundary.
+
+        Non-blocking and safe to call concurrently from any coroutine in the
+        same event loop. Drained at the top of the next iteration (before
+        the per-step checkpoint write and before the next think call), then
+        appended to WorkingMemory as a user message and emitted as a
+        HUMAN_GUIDANCE BusEvent.
+
+        Worst-case latency = time remaining in the current tool +
+        next-think duration. Guidance arriving after the LLM has already
+        emitted action="finish" is lost — the agent has decided it's done.
+        """
+        if not text or not text.strip():
+            return
+        self._steering.put_nowait(text.strip())
+
+    async def _drain_steering(self, step: int) -> AsyncGenerator[BusEvent, None]:
+        """Drain any queued guidance into WorkingMemory; yield one event each.
+
+        Called at the top of each ReAct iteration. Items are FIFO. Empty
+        queue is a no-op (zero overhead when no one is steering).
+        """
+        while not self._steering.empty():
+            try:
+                text = self._steering.get_nowait()
+            except asyncio.QueueEmpty:
+                break  # defensive — single consumer, should never fire
+            await self._working_memory.append("user", f"Human guidance: {text}")
+            self._tracer.log(
+                "human_guidance",
+                self.config.agent_id,
+                {"step": step, "text": text},
+            )
+            yield BusEvent(
+                type=EventType.HUMAN_GUIDANCE,
+                agent_id=self.config.agent_id,
+                payload={"step": step, "text": text},
+            )
+
     # ── Streaming entry point (canonical) ─────────────────────────────────────
 
     async def run_stream(
@@ -170,17 +222,25 @@ class BaseAgent:
         await self._working_memory.append("system", system, pinned=True)
         await self._working_memory.append("user", task)
 
-        async with _ResumeHint(
-            self._resume_key,
-            self._checkpoint_store,
-            f"Agent {self.config.agent_id}",
-            check_key=self._ckp_id,
-        ) as hint:
-            async for event in self._run_stream_internal(run_id):
-                if event.type == EventType.TASK_DONE:
-                    await self._clear_checkpoint(run_id)
-                    hint.done = True
-                yield event
+        # Steering source is owned by the agent for the duration of the run.
+        # nullcontext when no factory is configured — zero overhead.
+        source_cm = (
+            self._steering_source_factory(self)
+            if self._steering_source_factory is not None
+            else contextlib.nullcontext()
+        )
+        async with source_cm:
+            async with _ResumeHint(
+                self._resume_key,
+                self._checkpoint_store,
+                f"Agent {self.config.agent_id}",
+                check_key=self._ckp_id,
+            ) as hint:
+                async for event in self._run_stream_internal(run_id):
+                    if event.type == EventType.TASK_DONE:
+                        await self._clear_checkpoint(run_id)
+                        hint.done = True
+                    yield event
 
     async def _resume_stream(
         self,
@@ -203,17 +263,23 @@ class BaseAgent:
                 yield event
             start_step = pending["step"] + 1
 
-        async with _ResumeHint(
-            self._resume_key,
-            self._checkpoint_store,
-            f"Agent {self.config.agent_id}",
-            check_key=self._ckp_id,
-        ) as hint:
-            async for event in self._run_stream_internal(run_id, start_step=start_step):
-                if event.type == EventType.TASK_DONE:
-                    await self._clear_checkpoint(run_id)
-                    hint.done = True
-                yield event
+        source_cm = (
+            self._steering_source_factory(self)
+            if self._steering_source_factory is not None
+            else contextlib.nullcontext()
+        )
+        async with source_cm:
+            async with _ResumeHint(
+                self._resume_key,
+                self._checkpoint_store,
+                f"Agent {self.config.agent_id}",
+                check_key=self._ckp_id,
+            ) as hint:
+                async for event in self._run_stream_internal(run_id, start_step=start_step):
+                    if event.type == EventType.TASK_DONE:
+                        await self._clear_checkpoint(run_id)
+                        hint.done = True
+                    yield event
 
     async def _run_stream_internal(
         self,
@@ -295,6 +361,10 @@ class BaseAgent:
     ) -> AsyncGenerator[BusEvent, None]:
         for step in range(start_step, self.config.max_steps):
             self._guard.check()
+            # Drain steering queue BEFORE the checkpoint write so any
+            # queued guidance is captured by the persisted WM.
+            async for guidance_event in self._drain_steering(step):
+                yield guidance_event
             if (
                 self._checkpoint_store is not None
                 and self.config.checkpoint_every > 0

{react_agent_harness-0.1.0 → react_agent_harness-0.2.0}/harness/events.py

@@ -18,6 +18,7 @@ Event lifecycle within a single goal:
   Orchestrated path (run / run_stream):
     PLAN                  — orchestrator emitted a static DAG
     (per task in DAG)
+        HUMAN_GUIDANCE?   — async steering drained at top of step
         THOUGHT           — agent's next-step reasoning
         TOKEN*            — partial LLM output (only when client streams)
         ACTION            — agent chose a tool + args
@@ -46,6 +47,7 @@ class EventType(str, Enum):
     TOKEN = "token"
     ACTION = "action"
     OBSERVATION = "observation"
+    HUMAN_GUIDANCE = "human_guidance"  # async steering injected at step boundary
     TASK_DONE = "task_done"
     REPLAN = "replan"
     SYNTHESIS = "synthesis"

{react_agent_harness-0.1.0 → react_agent_harness-0.2.0}/harness/hitl.py

@@ -176,14 +176,48 @@ async def request_approval(
 
     Holds stdout_lock for the duration so concurrent agent events don't
     interleave with the banner or the input prompt.
+
+    Input always goes through prompt_toolkit:
+      - If a steering router is active, HITL claims the next stdin read
+        via the router. Text submitted at the active steering prompt is
+        routed to HITL instead of subscribers; if the router reaches a
+        pending claim between steering prompt cycles, it shows HITL's
+        approval prompt directly.
+      - If no router is active, HITL spins up a one-shot PromptSession
+        for the approval prompt. Same UX either way.
     """
+    from harness.steering import get_active_router
+
     async with stdout_lock:
+        router = get_active_router()
+        approve_prompt = "  Approve? [y/n/a/correction]: "
+        # If a router is active, reserve the next stdin read BEFORE printing
+        # the banner so the user's typed answer routes to HITL (not steering).
+        hitl_future: Any = (
+            router.claim_next_line(prompt=approve_prompt) if router is not None else None
+        )
+
         _print_banner(req)
 
         guard.suspend()
         try:
-            loop = asyncio.get_running_loop()
-            raw = await loop.run_in_executor(None, input, "  Approve? [y/n/a/correction]: ")
+            if hitl_future is not None:
+                raw = await hitl_future
+            else:
+                # Standalone: one-shot prompt_toolkit session with the same
+                # Enter-submits / Ctrl+J-newline bindings as steering so
+                # single-token answers (y/n/a) and multi-line corrections
+                # both compose naturally.
+                from prompt_toolkit import PromptSession
+
+                from harness.steering import StdinRouter
+
+                session: PromptSession = PromptSession()
+                raw = await session.prompt_async(
+                    approve_prompt,
+                    multiline=True,
+                    key_bindings=StdinRouter._build_key_bindings(),
+                )
         finally:
             guard.resume()
 

{react_agent_harness-0.1.0 → react_agent_harness-0.2.0}/harness/runtime.py

@@ -284,6 +284,7 @@ class AgentRuntime:
         enable_otel: bool = False,
         annotation_store: Any | None = None,  # InMemoryAnnotationStore or compatible
         checkpoint_store: Any | None = None,  # FileCheckpointStore / RedisCheckpointStore
+        steering_source_factory: Any | None = None,  # passed to each spawned BaseAgent
     ) -> None:
         self._agent_registry = agent_registry
         self._tool_registry = tool_registry
@@ -292,6 +293,7 @@ class AgentRuntime:
         self._guardrail_config = guardrail_config or GuardrailConfig()
         self._enable_otel = enable_otel
         self._annotation_store = annotation_store
+        self._steering_source_factory = steering_source_factory
         # Auto-create a FileCheckpointStore if any agent uses hitl_tools or
         # checkpoint_every — zero-dep default, no configuration required.
         if checkpoint_store is None and any(
@@ -304,6 +306,21 @@ class AgentRuntime:
             checkpoint_store = FileCheckpointStore()
         self._checkpoint_store = checkpoint_store
 
+    def _steering_lifecycle(self):
+        """Wrap the dispatch in the steering factory's lifecycle if it has one.
+
+        Factories with shared resources (e.g. a StdinRouter) expose
+        `__aenter__/__aexit__`. File-based factories don't. We detect at
+        runtime and use nullcontext for the latter so the wrapping is
+        always safe.
+        """
+        import contextlib
+
+        f = self._steering_source_factory
+        if f is not None and hasattr(f, "__aenter__") and hasattr(f, "__aexit__"):
+            return f
+        return contextlib.nullcontext()
+
     def _make_tracer(self) -> Tracer:
         """Create a fresh Tracer, attaching configured hooks."""
         tracer = Tracer()
@@ -337,6 +354,7 @@ class AgentRuntime:
             guard=guard,
             llm=self._llm,
             checkpoint_store=self._checkpoint_store,
+            steering_source_factory=self._steering_source_factory,
         )
         async for event in agent.run_stream(task, run_id=run_id):
             yield event
@@ -386,6 +404,7 @@ class AgentRuntime:
             guard=guard,
             llm=self._llm,
             checkpoint_store=self._checkpoint_store,
+            steering_source_factory=self._steering_source_factory,
         )
         agent._working_memory = wm
         agent._task = checkpoint["task"]
@@ -492,6 +511,7 @@ class AgentRuntime:
                 guard=guard,
                 llm=self._llm,
                 checkpoint_store=self._checkpoint_store,
+                steering_source_factory=self._steering_source_factory,
             )
             agent._working_memory = wm
             agent._task = checkpoint["task"]
@@ -551,6 +571,7 @@ class AgentRuntime:
                 guard=guard,
                 llm=self._llm,
                 checkpoint_store=self._checkpoint_store,
+                steering_source_factory=self._steering_source_factory,
             )
             for agent_id in self._agent_registry.all_ids()
         }
@@ -603,50 +624,58 @@ class AgentRuntime:
         Auto-resume: when --resume <key> is in sys.argv and a checkpoint store is
         configured, the saved run is transparently restored and streamed — callers
         need no resume-specific handling.
+
+        Steering: if `steering_source_factory` exposes async context manager
+        methods (e.g. `stdin_steering_factory()` which owns a shared
+        StdinRouter), this method wraps the entire dispatch in that
+        lifecycle so callers don't manage the shared resource themselves.
         """
         from harness.events import BusEvent, EventType
 
-        if self._checkpoint_store is not None:
-            from harness.checkpoint import maybe_resume_key
+        async with self._steering_lifecycle():
+            if self._checkpoint_store is not None:
+                from harness.checkpoint import maybe_resume_key
 
-            resume_key = maybe_resume_key()
-            if resume_key:
-                async for event in self.resume_stream(resume_key):
-                    yield event
-                return
-
-        complexity = await self._classify(goal)
-        path = "routed" if complexity == "simple" else "orchestrated"
-        yield BusEvent(
-            type=EventType.DISPATCH,
-            agent_id="orchestrator",
-            payload={"complexity": complexity, "path": path},
-        )
+                resume_key = maybe_resume_key()
+                if resume_key:
+                    async for event in self.resume_stream(resume_key):
+                        yield event
+                    return
 
-        if complexity == "simple":
-            # Own the full OTEL lifecycle for the simple path so dispatch + route
-            # events appear in the same trace as the agent work.
-            tracer = self._make_tracer()
-            run_id = str(uuid.uuid4())
-            tracer.start_run(run_id, goal)
-            try:
-                tracer.log("dispatch", "orchestrator", {"complexity": complexity, "path": path})
-                agent_id, rationale = await self.route(goal)
-                logger.info("Router → %s (%s)", agent_id, rationale)
-                tracer.log("route", agent_id, {"agent_id": agent_id, "rationale": rationale})
-                yield BusEvent(
-                    type=EventType.ROUTE,
-                    agent_id=agent_id,
-                    payload={"agent_id": agent_id, "rationale": rationale},
-                )
-                async for event in self._run_agent_with_tracer(agent_id, goal, tracer, run_id):
+            complexity = await self._classify(goal)
+            path = "routed" if complexity == "simple" else "orchestrated"
+            yield BusEvent(
+                type=EventType.DISPATCH,
+                agent_id="orchestrator",
+                payload={"complexity": complexity, "path": path},
+            )
+
+            if complexity == "simple":
+                # Own the full OTEL lifecycle for the simple path so dispatch + route
+                # events appear in the same trace as the agent work.
+                tracer = self._make_tracer()
+                run_id = str(uuid.uuid4())
+                tracer.start_run(run_id, goal)
+                try:
+                    tracer.log("dispatch", "orchestrator", {"complexity": complexity, "path": path})
+                    agent_id, rationale = await self.route(goal)
+                    logger.info("Router → %s (%s)", agent_id, rationale)
+                    tracer.log("route", agent_id, {"agent_id": agent_id, "rationale": rationale})
+                    yield BusEvent(
+                        type=EventType.ROUTE,
+                        agent_id=agent_id,
+                        payload={"agent_id": agent_id, "rationale": rationale},
+                    )
+                    async for event in self._run_agent_with_tracer(agent_id, goal, tracer, run_id):
+                        yield event
+                finally:
+                    tracer.end_run()
+            else:
+                # Orchestrated path owns its own trace via _build_orchestrator.
+                # run_stream re-enters _steering_lifecycle as nullcontext when
+                # the factory is already active (idempotent), so no double-start.
+                async for event in self.run_stream(goal):
                     yield event
-            finally:
-                tracer.end_run()
-        else:
-            # Orchestrated path owns its own trace via _build_orchestrator.
-            async for event in self.run_stream(goal):
-                yield event
 
     async def dispatch(self, goal: str) -> dict:
         """Blocking dispatch. Returns TASK_DONE payload for simple goals,
@@ -707,22 +736,23 @@ class AgentRuntime:
         """
         from harness.events import BusEvent, EventType
 
-        tracer = self._make_tracer()
-        run_id = str(uuid.uuid4())
-        tracer.start_run(run_id, goal)
-        try:
-            agent_id, rationale = await self.route(goal)
-            logger.info("Router → %s (%s)", agent_id, rationale)
-            tracer.log("route", agent_id, {"agent_id": agent_id, "rationale": rationale})
-            yield BusEvent(
-                type=EventType.ROUTE,
-                agent_id=agent_id,
-                payload={"agent_id": agent_id, "rationale": rationale},
-            )
-            async for event in self._run_agent_with_tracer(agent_id, goal, tracer, run_id):
-                yield event
-        finally:
-            tracer.end_run()
+        async with self._steering_lifecycle():
+            tracer = self._make_tracer()
+            run_id = str(uuid.uuid4())
+            tracer.start_run(run_id, goal)
+            try:
+                agent_id, rationale = await self.route(goal)
+                logger.info("Router → %s (%s)", agent_id, rationale)
+                tracer.log("route", agent_id, {"agent_id": agent_id, "rationale": rationale})
+                yield BusEvent(
+                    type=EventType.ROUTE,
+                    agent_id=agent_id,
+                    payload={"agent_id": agent_id, "rationale": rationale},
+                )
+                async for event in self._run_agent_with_tracer(agent_id, goal, tracer, run_id):
+                    yield event
+            finally:
+                tracer.end_run()
 
     async def run_routed(self, goal: str) -> dict:
         """Blocking routed run. Returns the TASK_DONE payload dict."""
@@ -793,17 +823,18 @@ class AgentRuntime:
         Auto-resume: when --resume <key> is in sys.argv and a checkpoint store is
         configured, the saved run is transparently restored and streamed.
         """
-        if self._checkpoint_store is not None:
-            from harness.checkpoint import maybe_resume_key
-
-            resume_key = maybe_resume_key()
-            if resume_key:
-                async for event in self.resume_stream(resume_key):
-                    yield event
-                return
-        orchestrator, _tracer, _guard = self._build_orchestrator()
-        async for event in orchestrator.run_stream(goal):
-            yield event
+        async with self._steering_lifecycle():
+            if self._checkpoint_store is not None:
+                from harness.checkpoint import maybe_resume_key
+
+                resume_key = maybe_resume_key()
+                if resume_key:
+                    async for event in self.resume_stream(resume_key):
+                        yield event
+                    return
+            orchestrator, _tracer, _guard = self._build_orchestrator()
+            async for event in orchestrator.run_stream(goal):
+                yield event
 
 
 # ── Helpers ───────────────────────────────────────────────────────────────────