feat: Add InterruptService for human-in-the-loop graph workflows

Author: drahnreb

contributing/samples/graph_agent_dynamic_queue/agent.py

@@ -166,7 +166,7 @@ async def dynamic_task_dispatcher(
   result = ""
   async for event in agent.run_async(agent_ctx):
     if event.content and event.content.parts:
-      result = event.content.parts[0].text or ""
+      result += event.content.parts[0].text or ""
 
   print(f"   Result: {result[:100]}...")
 
@@ -203,7 +203,7 @@ def build_dynamic_task_queue_graph() -> GraphAgent:
   graph.add_node("task_dispatcher", function=dynamic_task_dispatcher)
 
   # Loop back to dispatcher while tasks remain.
-  # Check task_queue directly (mutated in-place by the function node).
+  # Check task_queue directly (updated via output_mapper return value).
   # The return dict {"tasks_remaining": N} is stored under state.data["task_dispatcher"]
   # by the output mapper, so state.data.get("tasks_remaining") would always be 0.
   graph.add_edge(
@@ -283,7 +283,12 @@ async def main():
   fresh_session = await session_service.get_session(
       app_name="dynamic_queue_demo", user_id="demo_user", session_id=session.id
   )
-  final_session = fresh_session or session
+  if fresh_session is None:
+    print(
+        "WARNING: session_service.get_session returned None, using stale copy"
+    )
+    fresh_session = session
+  final_session = fresh_session
   final_data = final_session.state.get("graph_data", {})
   final_state = GraphState(data=final_data) if final_data else GraphState()
 

contributing/samples/graph_agent_hitl_orchestrated/README.md

@@ -0,0 +1,51 @@
+# Composable HITL Orchestrated Pipeline
+
+Demonstrates how to compose HITL review loops as reusable `NestedGraphNode` building blocks in a larger orchestrated pipeline.
+
+## Graph Structure
+
+**Outer graph** (`document_pipeline`):
+```
+[classify] --> [process] --> [aggregate]
+```
+
+**Inner graph** (`review_stage`, wrapped as `NestedGraphNode`):
+```
+[execute] --> [review_gate] --> approved? --> [done]
+                    |
+                    v rejected
+               [revise] --> [review_gate]  (loop)
+```
+
+## Key Concepts
+
+- **Reusable HITL block**: The inner review graph is built once and wrapped in `NestedGraphNode`
+- **Clean abstraction**: Outer orchestrator doesn't know about inner HITL details
+- **Independent review cycles**: Each inner graph has its own interrupt timing
+- **Observability**: `_debug_process_output` tracks nested graph output (via Part B observability)
+- **Rule-based classification**: `classify` node determines stages without LLM
+
+## Running
+
+```bash
+# Without LLM (deterministic fallback):
+python -m contributing.samples.graph_agent_hitl_orchestrated.agent
+
+# With LLM:
+export GOOGLE_API_KEY="your-key"
+python -m contributing.samples.graph_agent_hitl_orchestrated.agent
+```
+
+## How It Works
+
+1. `classify` reads input document, determines processing stages (extract/summarize/translate)
+2. `process` (NestedGraphNode) runs the inner review graph with HITL loop
+3. Inner `execute` performs the stage task, `review_gate` pauses for human approval
+4. If rejected: inner `revise` incorporates feedback, loops back
+5. If approved: inner `done` returns output to outer graph
+6. `aggregate` combines results into final output
+
+## Differences from `graph_agent_hitl_review`
+
+- `graph_agent_hitl_review`: Standalone HITL review loop
+- `graph_agent_hitl_orchestrated`: Wraps the review pattern as a NestedGraphNode in a larger pipeline, showing composability