robot_lab-a2a 0.1.0

data/docs/assets/images/architecture.svg

@@ -0,0 +1,258 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 900 600" width="900" height="600">
+  <rect width="900" height="600" fill="#0e0e14"/>
+
+  <!-- ── Title ── -->
+  <text x="450" y="36" text-anchor="middle" fill="#e0e0f0" font-family="Roboto Mono, Consolas, monospace" font-size="18" font-weight="bold">robot_lab-a2a  —  Architecture</text>
+
+  <!-- ══════════════════════════════════════════════════════════════
+       Column labels
+  ══════════════════════════════════════════════════════════════ -->
+  <text x="68"  y="68" text-anchor="middle" fill="#888" font-family="Roboto Mono, monospace" font-size="10">CLIENT</text>
+  <text x="230" y="68" text-anchor="middle" fill="#888" font-family="Roboto Mono, monospace" font-size="10">HTTP LAYER</text>
+  <text x="450" y="68" text-anchor="middle" fill="#888" font-family="Roboto Mono, monospace" font-size="10">ADAPTER LAYER</text>
+  <text x="700" y="68" text-anchor="middle" fill="#888" font-family="Roboto Mono, monospace" font-size="10">ROBOT LAYER</text>
+
+  <!-- ══════════════════════════════════════════════════════════════
+       A2A CLIENT  (col 1)
+  ══════════════════════════════════════════════════════════════ -->
+  <rect x="14" y="80" width="108" height="440" rx="8" fill="#1a1030" stroke="#6633bb" stroke-width="1.5"/>
+  <text x="68" y="100" text-anchor="middle" fill="#bb88ff" font-family="Roboto Mono, monospace" font-size="11" font-weight="bold">A2A Client</text>
+
+  <!-- SDK box -->
+  <rect x="24" y="110" width="88" height="34" rx="5" fill="#2a1f50" stroke="#7755cc" stroke-width="1"/>
+  <text x="68" y="124" text-anchor="middle" fill="#ccaaff" font-family="Roboto Mono, monospace" font-size="9" font-weight="bold">Ruby SDK</text>
+  <text x="68" y="137" text-anchor="middle" fill="#9977cc" font-family="Roboto Mono, monospace" font-size="8">A2A.client(url:)</text>
+
+  <!-- curl box -->
+  <rect x="24" y="154" width="88" height="26" rx="5" fill="#2a1f50" stroke="#7755cc" stroke-width="1"/>
+  <text x="68" y="171" text-anchor="middle" fill="#ccaaff" font-family="Roboto Mono, monospace" font-size="9">curl / HTTP</text>
+
+  <!-- tasks/send -->
+  <rect x="24" y="200" width="88" height="50" rx="5" fill="#1e1440" stroke="#5533aa" stroke-width="1" stroke-dasharray="4,2"/>
+  <text x="68" y="215" text-anchor="middle" fill="#aa88ee" font-family="Roboto Mono, monospace" font-size="8">tasks/send</text>
+  <text x="68" y="228" text-anchor="middle" fill="#8866cc" font-family="Roboto Mono, monospace" font-size="8">tasks/get</text>
+  <text x="68" y="241" text-anchor="middle" fill="#8866cc" font-family="Roboto Mono, monospace" font-size="8">tasks/cancel</text>
+
+  <!-- input_required round-trip note -->
+  <rect x="24" y="268" width="88" height="44" rx="5" fill="#2a1040" stroke="#cc44bb" stroke-width="1" stroke-dasharray="4,2"/>
+  <text x="68" y="283" text-anchor="middle" fill="#ee88dd" font-family="Roboto Mono, monospace" font-size="8">input_required</text>
+  <text x="68" y="296" text-anchor="middle" fill="#cc66bb" font-family="Roboto Mono, monospace" font-size="8">→ send reply</text>
+  <text x="68" y="308" text-anchor="middle" fill="#cc66bb" font-family="Roboto Mono, monospace" font-size="8">  with task_id</text>
+
+  <!-- agentCard -->
+  <rect x="24" y="328" width="88" height="26" rx="5" fill="#1e1440" stroke="#5533aa" stroke-width="1" stroke-dasharray="4,2"/>
+  <text x="68" y="345" text-anchor="middle" fill="#aa88ee" font-family="Roboto Mono, monospace" font-size="8">GET agentCard</text>
+
+  <!-- ══════════════════════════════════════════════════════════════
+       HTTP LAYER — simple_a2a  (col 2)
+  ══════════════════════════════════════════════════════════════ -->
+  <rect x="140" y="80" width="180" height="440" rx="8" fill="#0e1e30" stroke="#3388cc" stroke-width="1.5"/>
+  <text x="230" y="100" text-anchor="middle" fill="#66bbff" font-family="Roboto Mono, monospace" font-size="11" font-weight="bold">simple_a2a</text>
+
+  <!-- Falcon/Rack -->
+  <rect x="152" y="110" width="156" height="30" rx="5" fill="#0d2a40" stroke="#2277aa" stroke-width="1"/>
+  <text x="230" y="121" text-anchor="middle" fill="#55aaee" font-family="Roboto Mono, monospace" font-size="9" font-weight="bold">Falcon HTTP server</text>
+  <text x="230" y="133" text-anchor="middle" fill="#3388bb" font-family="Roboto Mono, monospace" font-size="8">JSON-RPC 2.0  /  SSE</text>
+
+  <!-- App router -->
+  <rect x="152" y="150" width="156" height="50" rx="5" fill="#0d2a40" stroke="#2277aa" stroke-width="1"/>
+  <text x="230" y="165" text-anchor="middle" fill="#55aaee" font-family="Roboto Mono, monospace" font-size="9" font-weight="bold">App (Roda)</text>
+  <text x="230" y="178" text-anchor="middle" fill="#3388bb" font-family="Roboto Mono, monospace" font-size="8">dispatch → handle_send</text>
+  <text x="230" y="191" text-anchor="middle" fill="#3388bb" font-family="Roboto Mono, monospace" font-size="8">handle_get / cancel / list</text>
+
+  <!-- Context / ResumeContext -->
+  <rect x="152" y="212" width="72" height="44" rx="5" fill="#0d2233" stroke="#1a5577" stroke-width="1"/>
+  <text x="188" y="227" text-anchor="middle" fill="#44aacc" font-family="Roboto Mono, monospace" font-size="8" font-weight="bold">Context</text>
+  <text x="188" y="239" text-anchor="middle" fill="#2288aa" font-family="Roboto Mono, monospace" font-size="7">task, message</text>
+  <text x="188" y="250" text-anchor="middle" fill="#2288aa" font-family="Roboto Mono, monospace" font-size="7">storage, events</text>
+
+  <rect x="234" y="212" width="74" height="44" rx="5" fill="#1a1040" stroke="#cc44bb" stroke-width="1"/>
+  <text x="271" y="227" text-anchor="middle" fill="#ee88dd" font-family="Roboto Mono, monospace" font-size="8" font-weight="bold">ResumeContext</text>
+  <text x="271" y="239" text-anchor="middle" fill="#cc66bb" font-family="Roboto Mono, monospace" font-size="7">resume_message</text>
+  <text x="271" y="250" text-anchor="middle" fill="#cc66bb" font-family="Roboto Mono, monospace" font-size="7">task_id routing</text>
+
+  <!-- Storage -->
+  <rect x="152" y="268" width="156" height="34" rx="5" fill="#0d2a40" stroke="#2277aa" stroke-width="1"/>
+  <text x="230" y="281" text-anchor="middle" fill="#55aaee" font-family="Roboto Mono, monospace" font-size="9" font-weight="bold">Storage::Memory</text>
+  <text x="230" y="294" text-anchor="middle" fill="#3388bb" font-family="Roboto Mono, monospace" font-size="8">task persistence (in-process)</text>
+
+  <!-- AgentCard -->
+  <rect x="152" y="314" width="156" height="30" rx="5" fill="#0d2a40" stroke="#2277aa" stroke-width="1"/>
+  <text x="230" y="326" text-anchor="middle" fill="#55aaee" font-family="Roboto Mono, monospace" font-size="9" font-weight="bold">AgentCard</text>
+  <text x="230" y="339" text-anchor="middle" fill="#3388bb" font-family="Roboto Mono, monospace" font-size="8">name, skills, capabilities</text>
+
+  <!-- ══════════════════════════════════════════════════════════════
+       ADAPTER LAYER  (col 3)
+  ══════════════════════════════════════════════════════════════ -->
+  <rect x="338" y="80" width="224" height="440" rx="8" fill="#0e1e16" stroke="#33aa66" stroke-width="1.5"/>
+  <text x="450" y="100" text-anchor="middle" fill="#66ee99" font-family="Roboto Mono, monospace" font-size="11" font-weight="bold">RobotLab::A2A</text>
+
+  <!-- Server builder -->
+  <rect x="350" y="110" width="200" height="34" rx="5" fill="#0a2818" stroke="#228855" stroke-width="1"/>
+  <text x="450" y="125" text-anchor="middle" fill="#44dd88" font-family="Roboto Mono, monospace" font-size="9" font-weight="bold">Server</text>
+  <text x="450" y="138" text-anchor="middle" fill="#229955" font-family="Roboto Mono, monospace" font-size="8">add_robot  /  add_network  /  run  /  to_app</text>
+
+  <!-- RobotAdapter -->
+  <rect x="350" y="156" width="200" height="118" rx="5" fill="#0a2818" stroke="#228855" stroke-width="1"/>
+  <text x="450" y="172" text-anchor="middle" fill="#44dd88" font-family="Roboto Mono, monospace" font-size="9" font-weight="bold">RobotAdapter</text>
+
+  <!-- :none -->
+  <rect x="360" y="180" width="56" height="22" rx="3" fill="#062010" stroke="#115533" stroke-width="1"/>
+  <text x="388" y="195" text-anchor="middle" fill="#33bb77" font-family="Roboto Mono, monospace" font-size="8">:none</text>
+
+  <!-- :a2a_tool -->
+  <rect x="424" y="180" width="60" height="22" rx="3" fill="#1a1040" stroke="#cc44bb" stroke-width="1"/>
+  <text x="454" y="195" text-anchor="middle" fill="#ee88dd" font-family="Roboto Mono, monospace" font-size="8">:a2a_tool</text>
+
+  <!-- :io_bridge -->
+  <rect x="492" y="180" width="52" height="22" rx="3" fill="#0a1e30" stroke="#3388cc" stroke-width="1"/>
+  <text x="518" y="195" text-anchor="middle" fill="#66bbff" font-family="Roboto Mono, monospace" font-size="8">:io_bridge</text>
+
+  <!-- AskUserTool -->
+  <rect x="360" y="212" width="86" height="52" rx="3" fill="#1a1040" stroke="#cc44bb" stroke-width="1" stroke-dasharray="3,2"/>
+  <text x="403" y="227" text-anchor="middle" fill="#ee88dd" font-family="Roboto Mono, monospace" font-size="8" font-weight="bold">AskUserTool</text>
+  <text x="403" y="240" text-anchor="middle" fill="#cc66bb" font-family="Roboto Mono, monospace" font-size="7">push event_queue</text>
+  <text x="403" y="252" text-anchor="middle" fill="#cc66bb" font-family="Roboto Mono, monospace" font-size="7">block answer_queue</text>
+
+  <!-- IoBridge -->
+  <rect x="454" y="212" width="88" height="52" rx="3" fill="#0a1e30" stroke="#3388cc" stroke-width="1" stroke-dasharray="3,2"/>
+  <text x="498" y="227" text-anchor="middle" fill="#66bbff" font-family="Roboto Mono, monospace" font-size="8" font-weight="bold">IoBridge</text>
+  <text x="498" y="240" text-anchor="middle" fill="#3388aa" font-family="Roboto Mono, monospace" font-size="7">buffer write/puts</text>
+  <text x="498" y="252" text-anchor="middle" fill="#3388aa" font-family="Roboto Mono, monospace" font-size="7">gets → block queue</text>
+
+  <!-- Thread box -->
+  <rect x="360" y="274" width="88" height="26" rx="3" fill="#0a1a10" stroke="#115533" stroke-width="1"/>
+  <text x="404" y="287" text-anchor="middle" fill="#44cc77" font-family="Roboto Mono, monospace" font-size="8">Thread (per call)</text>
+  <text x="404" y="299" text-anchor="middle" fill="#228844" font-family="Roboto Mono, monospace" font-size="7">robot.run(input)</text>
+
+  <!-- NetworkAdapter -->
+  <rect x="350" y="312" width="200" height="50" rx="5" fill="#0a2818" stroke="#228855" stroke-width="1"/>
+  <text x="450" y="328" text-anchor="middle" fill="#44dd88" font-family="Roboto Mono, monospace" font-size="9" font-weight="bold">NetworkAdapter  (:none)</text>
+  <text x="450" y="341" text-anchor="middle" fill="#229955" font-family="Roboto Mono, monospace" font-size="8">network.run(message:)</text>
+  <text x="450" y="353" text-anchor="middle" fill="#229955" font-family="Roboto Mono, monospace" font-size="8">.last_text_content</text>
+
+  <!-- Registry -->
+  <rect x="350" y="376" width="200" height="58" rx="5" fill="#1e1a00" stroke="#ccaa00" stroke-width="1.5"/>
+  <text x="450" y="393" text-anchor="middle" fill="#ffdd44" font-family="Roboto Mono, monospace" font-size="9" font-weight="bold">Registry  (Mutex)</text>
+  <text x="450" y="407" text-anchor="middle" fill="#cc9900" font-family="Roboto Mono, monospace" font-size="8">task_id → Entry</text>
+  <text x="450" y="419" text-anchor="middle" fill="#cc9900" font-family="Roboto Mono, monospace" font-size="8">Entry: thread | event_queue</text>
+  <text x="450" y="431" text-anchor="middle" fill="#cc9900" font-family="Roboto Mono, monospace" font-size="8">       | answer_queue</text>
+
+  <!-- ══════════════════════════════════════════════════════════════
+       ROBOT LAYER  (col 4)
+  ══════════════════════════════════════════════════════════════ -->
+  <rect x="580" y="80" width="306" height="440" rx="8" fill="#1e1205" stroke="#dd8822" stroke-width="1.5"/>
+  <text x="733" y="100" text-anchor="middle" fill="#ffaa44" font-family="Roboto Mono, monospace" font-size="11" font-weight="bold">RobotLab</text>
+
+  <!-- Robot box -->
+  <rect x="592" y="110" width="138" height="160" rx="5" fill="#281600" stroke="#aa6600" stroke-width="1"/>
+  <text x="661" y="128" text-anchor="middle" fill="#ffaa44" font-family="Roboto Mono, monospace" font-size="9" font-weight="bold">Robot</text>
+  <text x="661" y="143" text-anchor="middle" fill="#cc8833" font-family="Roboto Mono, monospace" font-size="8">robot.name</text>
+  <text x="661" y="156" text-anchor="middle" fill="#cc8833" font-family="Roboto Mono, monospace" font-size="8">robot.description</text>
+  <text x="661" y="169" text-anchor="middle" fill="#cc8833" font-family="Roboto Mono, monospace" font-size="8">robot.run(text) → reply</text>
+
+  <!-- AskUser tool (inside robot) -->
+  <rect x="602" y="182" width="118" height="36" rx="3" fill="#1e0e00" stroke="#cc6600" stroke-width="1" stroke-dasharray="3,2"/>
+  <text x="661" y="197" text-anchor="middle" fill="#ffaa55" font-family="Roboto Mono, monospace" font-size="8">RobotLab::AskUser</text>
+  <text x="661" y="209" text-anchor="middle" fill="#aa6633" font-family="Roboto Mono, monospace" font-size="7">→ replaced by AskUserTool</text>
+
+  <!-- local_tools / io note -->
+  <rect x="602" y="228" width="118" height="36" rx="3" fill="#1e0e00" stroke="#7755aa" stroke-width="1" stroke-dasharray="3,2"/>
+  <text x="661" y="243" text-anchor="middle" fill="#bb88ff" font-family="Roboto Mono, monospace" font-size="8">local_tools  (Array)</text>
+  <text x="661" y="255" text-anchor="middle" fill="#9966cc" font-family="Roboto Mono, monospace" font-size="7">input= / output= (io_bridge)</text>
+
+  <!-- Network box -->
+  <rect x="748" y="110" width="128" height="100" rx="5" fill="#200a28" stroke="#cc55dd" stroke-width="1"/>
+  <text x="812" y="128" text-anchor="middle" fill="#ee88ff" font-family="Roboto Mono, monospace" font-size="9" font-weight="bold">Network</text>
+  <text x="812" y="143" text-anchor="middle" fill="#bb66dd" font-family="Roboto Mono, monospace" font-size="8">network.run(message:)</text>
+  <text x="812" y="157" text-anchor="middle" fill="#bb66dd" font-family="Roboto Mono, monospace" font-size="8">.last_text_content</text>
+
+  <!-- Pipeline stages -->
+  <rect x="758" y="168" width="108" height="34" rx="3" fill="#180820" stroke="#aa44cc" stroke-width="1" stroke-dasharray="3,2"/>
+  <text x="812" y="183" text-anchor="middle" fill="#dd88ff" font-family="Roboto Mono, monospace" font-size="8">Step A → Step B</text>
+  <text x="812" y="196" text-anchor="middle" fill="#9944bb" font-family="Roboto Mono, monospace" font-size="7">→ Step C  (pipeline)</text>
+
+  <!-- LLM note -->
+  <rect x="592" y="290" width="274" height="46" rx="5" fill="#1a1000" stroke="#886622" stroke-width="1"/>
+  <text x="729" y="308" text-anchor="middle" fill="#ddaa44" font-family="Roboto Mono, monospace" font-size="9" font-weight="bold">LLM / External Services</text>
+  <text x="729" y="323" text-anchor="middle" fill="#886633" font-family="Roboto Mono, monospace" font-size="8">ruby_llm, openai, anthropic, etc.  (optional, robot-internal)</text>
+
+  <!-- ══════════════════════════════════════════════════════════════
+       ARROWS
+  ══════════════════════════════════════════════════════════════ -->
+  <defs>
+    <marker id="a1" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto">
+      <path d="M0,0 L8,4 L0,8 Z" fill="#6633bb"/>
+    </marker>
+    <marker id="a2" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto">
+      <path d="M0,0 L8,4 L0,8 Z" fill="#3388cc"/>
+    </marker>
+    <marker id="a3" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto">
+      <path d="M0,0 L8,4 L0,8 Z" fill="#33aa66"/>
+    </marker>
+    <marker id="a4" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto">
+      <path d="M0,0 L8,4 L0,8 Z" fill="#dd8822"/>
+    </marker>
+    <marker id="a5" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto">
+      <path d="M0,0 L8,4 L0,8 Z" fill="#cc44bb"/>
+    </marker>
+    <marker id="a6" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto">
+      <path d="M0,0 L8,4 L0,8 Z" fill="#ccaa00"/>
+    </marker>
+  </defs>
+
+  <!-- Client → simple_a2a  (HTTP POST) -->
+  <line x1="122" y1="127" x2="140" y2="127" stroke="#6633bb" stroke-width="2" marker-end="url(#a1)"/>
+  <text x="131" y="122" text-anchor="middle" fill="#9966cc" font-family="Roboto Mono, monospace" font-size="7">POST</text>
+
+  <!-- simple_a2a → executor.call() -->
+  <line x1="320" y1="185" x2="338" y2="185" stroke="#3388cc" stroke-width="2" marker-end="url(#a2)"/>
+  <text x="329" y="180" text-anchor="middle" fill="#4499bb" font-family="Roboto Mono, monospace" font-size="7">call</text>
+
+  <!-- RobotAdapter → Robot -->
+  <line x1="562" y1="200" x2="580" y2="200" stroke="#33aa66" stroke-width="2" marker-end="url(#a3)"/>
+  <text x="571" y="195" text-anchor="middle" fill="#55cc88" font-family="Roboto Mono, monospace" font-size="7">run</text>
+
+  <!-- NetworkAdapter → Network -->
+  <line x1="562" y1="335" x2="748" y2="165" stroke="#33aa66" stroke-width="1.5" stroke-dasharray="5,3" marker-end="url(#a3)"/>
+
+  <!-- input_required return arrow (dashed, upward) -->
+  <path d="M 403 264 Q 271 360 271 258" fill="none" stroke="#cc44bb" stroke-width="1.5" stroke-dasharray="5,3" marker-end="url(#a5)"/>
+  <text x="300" y="320" text-anchor="middle" fill="#cc44bb" font-family="Roboto Mono, monospace" font-size="8">input_required</text>
+
+  <!-- Resume arrow: ResumeContext → answer_queue -->
+  <path d="M 271 212 Q 271 170 403 212" fill="none" stroke="#cc44bb" stroke-width="1.5" stroke-dasharray="5,3" marker-end="url(#a5)"/>
+  <text x="330" y="168" text-anchor="middle" fill="#cc44bb" font-family="Roboto Mono, monospace" font-size="8">resume</text>
+
+  <!-- Registry ↔ RobotAdapter (dashed) -->
+  <line x1="404" y1="274" x2="404" y2="376" stroke="#ccaa00" stroke-width="1.5" stroke-dasharray="4,3" marker-end="url(#a6)"/>
+  <text x="416" y="332" fill="#998800" font-family="Roboto Mono, monospace" font-size="7">register/</text>
+  <text x="416" y="342" fill="#998800" font-family="Roboto Mono, monospace" font-size="7">fetch</text>
+
+  <!-- ══════════════════════════════════════════════════════════════
+       LEGEND
+  ══════════════════════════════════════════════════════════════ -->
+  <rect x="14" y="540" width="872" height="46" rx="6" fill="#111118" stroke="#333344" stroke-width="1"/>
+  <text x="28" y="556" fill="#888" font-family="Roboto Mono, monospace" font-size="9">Legend:</text>
+
+  <rect x="75"  y="546" width="30" height="10" rx="2" fill="#1a1030" stroke="#6633bb" stroke-width="1"/>
+  <text x="111" y="556" fill="#aaa" font-family="Roboto Mono, monospace" font-size="9">A2A protocol</text>
+
+  <rect x="190" y="546" width="30" height="10" rx="2" fill="#0e1e30" stroke="#3388cc" stroke-width="1"/>
+  <text x="226" y="556" fill="#aaa" font-family="Roboto Mono, monospace" font-size="9">HTTP layer</text>
+
+  <rect x="300" y="546" width="30" height="10" rx="2" fill="#0e1e16" stroke="#33aa66" stroke-width="1"/>
+  <text x="336" y="556" fill="#aaa" font-family="Roboto Mono, monospace" font-size="9">Adapter layer</text>
+
+  <rect x="420" y="546" width="30" height="10" rx="2" fill="#1e1205" stroke="#dd8822" stroke-width="1"/>
+  <text x="456" y="556" fill="#aaa" font-family="Roboto Mono, monospace" font-size="9">Robot layer</text>
+
+  <line x1="535" y1="551" x2="565" y2="551" stroke="#cc44bb" stroke-width="1.5" stroke-dasharray="4,2"/>
+  <text x="572" y="556" fill="#aaa" font-family="Roboto Mono, monospace" font-size="9">interactive flow</text>
+
+  <line x1="665" y1="551" x2="695" y2="551" stroke="#ccaa00" stroke-width="1.5" stroke-dasharray="4,2"/>
+  <text x="702" y="556" fill="#aaa" font-family="Roboto Mono, monospace" font-size="9">Registry lookup</text>
+
+  <!-- second legend row -->
+  <text x="28" y="578" fill="#666" font-family="Roboto Mono, monospace" font-size="8">Dashed borders = injected/optional component   |   Solid borders = always-present component</text>
+</svg>

data/docs/examples.md

@@ -0,0 +1,116 @@
+# Examples
+
+## Layout
+
+```
+examples/
+  run                     # launcher script
+  01_sync_robot/
+    server.rb             # starts the A2A server
+    client.rb             # sends a task and prints the result
+  02_interactive_a2a_tool/
+    server.rb
+    client.rb
+  03_robot_network/
+    server.rb
+    client.rb
+```
+
+## How to run
+
+From the repo root, pass the example directory name to `examples/run`:
+
+```bash
+bundle exec ruby examples/run 01_sync_robot
+```
+
+From inside `examples/` directly:
+
+```bash
+cd examples
+./run 01_sync_robot
+```
+
+The launcher starts `server.rb` in the background, waits for it to bind, then runs `client.rb` in the foreground so you see the output. Press Ctrl-C to stop.
+
+To run server and client separately (useful for inspecting raw SSE output):
+
+```bash
+# Terminal 1
+bundle exec ruby examples/01_sync_robot/server.rb
+
+# Terminal 2
+bundle exec ruby examples/01_sync_robot/client.rb
+```
+
+## 01_sync_robot
+
+**Demonstrates:** The simplest possible integration. A robot with no user prompts is registered in `:none` mode and invoked with a single text message.
+
+**What it shows:**
+
+- `Server.new.add_robot(...).run(port:)` pattern
+- A single `tasks/send` POST
+- Parsing the SSE stream to extract `task_complete` payload
+
+**Expected output (client):**
+
+```
+Sending task...
+[event: task_started]
+[event: task_complete]
+Reply: The answer is 42.
+Done.
+```
+
+## 02_interactive_a2a_tool
+
+**Demonstrates:** A robot that calls `RobotLab::AskUser` during execution. The gem injects `AskUserTool`, converts the blocking call to an A2A `input_required` event, and the client resumes with the answer.
+
+**Two-turn flow:**
+
+1. Client sends initial task → server starts robot thread → robot calls `AskUser("What is your name?")` → SSE delivers `input_required` event with prompt and task ID.
+2. Client sends a second `tasks/send` with the task ID and the user's answer → `AskUserTool` unblocks → robot continues → SSE delivers `task_complete`.
+
+**What it shows:**
+
+- `interactive: :a2a_tool` server setup
+- How to extract `task_id` and `input_required` prompt from the first SSE stream
+- How to construct the resume request with `task_id`
+
+**Expected output (client):**
+
+```
+Turn 1 — sending initial task...
+[event: task_started]
+[event: input_required] prompt: "What is your name?"
+task_id: abc-123-def
+
+Turn 2 — resuming with answer...
+[event: task_started]
+[event: task_complete]
+Reply: Hello, Alice! Nice to meet you.
+Done.
+```
+
+## 03_robot_network
+
+**Demonstrates:** A `RobotLab::Network` (multi-stage pipeline) exposed as a single A2A agent via `NetworkAdapter` in `:none` mode.
+
+**Pipeline stages:** The example network typically chains two or three robots — for example, a research robot that gathers context, followed by a synthesis robot that produces a final answer. Each stage's output feeds the next.
+
+**What it shows:**
+
+- `add_network` registration
+- That the caller sees only one A2A endpoint regardless of how many internal stages the network has
+- `network.run(message: text).last_text_content` as the final reply
+
+**Expected output (client):**
+
+```
+Sending task to network...
+[event: task_started]
+[event: task_complete]
+Reply: [synthesised answer from the final pipeline stage]
+Done.
+```

data/docs/getting-started.md

@@ -0,0 +1,103 @@
+# Getting Started
+
+## Requirements
+
+- Ruby >= 3.2
+- The `robot_lab` gem (provides `RobotLab::Robot` and `RobotLab::Network`)
+- Bundler
+
+## Installation
+
+### As a gem dependency
+
+Add to your `Gemfile`:
+
+```ruby
+gem "robot_lab-a2a"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+### As a local path dependency (for development)
+
+If you are working directly in this repo or have a local checkout of `robot_lab-a2a`:
+
+```ruby
+# Gemfile
+gem "robot_lab-a2a", path: "../robot_lab-a2a"
+```
+
+The gem also depends on `simple_a2a`. For interactive resume support (`input_required`/resume lifecycle), you need a build of `simple_a2a` that includes `ResumeContext`. If your local copy is newer than the released gem, use a path dependency for that too:
+
+```ruby
+gem "simple_a2a", path: "../simple_a2a"
+```
+
+## Sync Robot (5 minutes)
+
+### 1. Define your robot
+
+```ruby
+# my_robot.rb
+require "robot_lab"
+
+class GreeterRobot < RobotLab::Robot
+  def initialize
+    super(
+      name: "Greeter",
+      description: "Returns a greeting for any input",
+      model: "gpt-4o-mini"
+    )
+  end
+
+  # robot_lab calls run(text) and expects a result with a .reply method
+end
+```
+
+### 2. Start the server
+
+```ruby
+# server.rb
+require "robot_lab/a2a"
+require_relative "my_robot"
+
+robot = GreeterRobot.new
+
+RobotLab::A2A::Server.new
+  .add_robot(robot, name: "Greeter", description: "Returns a greeting")
+  .run(port: 7000)
+```
+
+```bash
+bundle exec ruby server.rb
+# => Listening on http://0.0.0.0:7000
+```
+
+### 3. Send a task
+
+The server exposes each robot at its DNS-label path. `GreeterRobot` registered as `"Greeter"` becomes `/greeter`.
+
+```bash
+curl -X POST http://localhost:7000/greeter/tasks/send \
+  -H "Content-Type: application/json" \
+  -d '{"message": {"role": "user", "parts": [{"text": "Hello!"}]}}'
+```
+
+The response is a stream of SSE events ending with a `task_complete` event whose payload contains the robot's reply.
+
+### 4. Inspect the agent card
+
+Every registered agent exposes its capabilities at `/.well-known/agent.json` (via `simple_a2a`):
+
+```bash
+curl http://localhost:7000/greeter/.well-known/agent.json
+```
+
+## What's next
+
+- [Interactive Modes](interactive-modes.md) — enable multi-turn conversations with `:a2a_tool` or `:io_bridge`
+- [Server API](server-api.md) — full reference for `Server.new`, `add_robot`, `add_network`, `run`, and `to_app`

data/docs/index.md

@@ -0,0 +1,23 @@
+# robot_lab-a2a
+
+`robot_lab-a2a` is an Agent2Agent (A2A) protocol adapter for RobotLab. It wraps RobotLab robots and networks in an HTTP+SSE server so any A2A-compliant client can invoke them, receive streaming events, and participate in multi-turn conversations — all without a terminal.
+
+## How it fits together
+
+![Architecture diagram](assets/images/architecture.png)
+
+## Key concepts
+
+- **Server** (`RobotLab::A2A::Server`) — fluent builder that registers robots and networks as A2A agents, then starts an HTTP+SSE server via `simple_a2a`.
+- **RobotAdapter** — wraps any `RobotLab::Robot`. Supports three modes: `:none` (synchronous), `:a2a_tool` (injects `AskUserTool` for multi-turn via Thread+Queue), and `:io_bridge` (replaces robot I/O streams for robots that use `gets`/`puts` directly).
+- **NetworkAdapter** — wraps a `RobotLab::Network`. Runs the full pipeline in `:none` mode and returns the last text content.
+- **AskUserTool** — drop-in replacement for `RobotLab::AskUser`. Converts a blocking terminal prompt into an A2A `input_required` event and waits for a client resume.
+- **IoBridge** — IO-compatible object that buffers robot output and converts `gets` calls into `input_required` events, enabling interactive mode for robots that talk to raw streams.
+- **Registry** — thread-safe singleton (Mutex-protected) keyed by A2A task ID. Holds `Entry(thread, event_queue, answer_queue)` so HTTP resume requests can find and unblock the correct robot thread.
+
+## Documentation pages
+
+- [Getting Started](getting-started.md) — installation, first server, client usage
+- [Interactive Modes](interactive-modes.md) — `:none`, `:a2a_tool`, `:io_bridge` in depth
+- [Server API](server-api.md) — full constructor and method reference
+- [Examples](examples.md) — walkthrough of the bundled example scripts

data/docs/interactive-modes.md

@@ -0,0 +1,104 @@
+# Interactive Modes
+
+## Why interactive matters
+
+RobotLab's `AskUser` tool blocks the robot thread and reads from a terminal. That works fine for CLI scripts but breaks completely in an HTTP server: there is no terminal, and the HTTP request has already returned by the time the robot needs an answer.
+
+`robot_lab-a2a` solves this by converting blocking terminal prompts into A2A `input_required` events. The robot thread pauses on a Ruby `Queue`. The HTTP layer serialises the prompt as an SSE event to the A2A client. When the client sends a resume request, the answer is placed onto the queue and the robot thread continues — all without any terminal.
+
+Three modes are available. Choose based on how your robot is implemented.
+
+## `:none` mode
+
+The default. The robot receives the initial text message, runs to completion, and returns a single reply. No user interaction occurs during execution.
+
+```ruby
+RobotLab::A2A::Server.new                        # interactive: :none is the default
+  .add_robot(robot, name: "Summariser", description: "Summarises text")
+  .run(port: 7000)
+```
+
+**Robot interface required:** `robot.run(text)` returns a result responding to `.reply`.
+
+Use `:none` when your robot never calls `AskUser` or reads from stdin.
+
+## `:a2a_tool` mode
+
+The server injects an `AskUserTool` instance into `robot.local_tools` before the robot thread starts, and removes it on teardown. `AskUserTool` is a drop-in replacement for `RobotLab::AskUser` that uses `Queue` instead of `$stdin`.
+
+**Turn 1 — initial request:**
+
+```bash
+curl -X POST http://localhost:7000/my-robot/tasks/send \
+  -H "Content-Type: application/json" \
+  -d '{"message": {"role": "user", "parts": [{"text": "Plan a trip"}]}}'
+```
+
+The server starts the robot on a new Thread, keyed in `Registry` by the A2A task ID. When the robot calls `AskUser`, `AskUserTool#execute`:
+
+1. Pushes `{type: :ask, prompt: "Where do you want to go?"}` onto `event_queue`.
+2. Blocks on `answer_queue`.
+
+The SSE stream delivers an `input_required` event to the client containing the prompt text and the task ID.
+
+**Turn 2 — resume:**
+
+```bash
+curl -X POST http://localhost:7000/my-robot/tasks/send \
+  -H "Content-Type: application/json" \
+  -d '{
+    "task_id": "<task-id-from-turn-1>",
+    "message": {"role": "user", "parts": [{"text": "Paris"}]}
+  }'
+```
+
+`simple_a2a` routes this to the resume handler. The server looks up the task in `Registry`, places `"Paris"` onto `answer_queue`, and the blocked `AskUserTool#execute` returns `"Paris"` to the robot. The robot continues. If it calls `AskUser` again, the cycle repeats. When the robot finishes, a `task_complete` event closes the SSE stream.
+
+**Setup:**
+
+```ruby
+RobotLab::A2A::Server.new(interactive: :a2a_tool)
+  .add_robot(robot, name: "Planner", description: "Plans trips interactively")
+  .run(port: 7000)
+```
+
+**Robot interface required:**
+
+- `robot.run(text)` — entry point.
+- `robot.local_tools` — mutable `Array` that the server prepends `AskUserTool` to. The instance variable is `@local_tools`.
+
+**Important:** Interactive resume requires a build of `simple_a2a` that includes `ResumeContext` support. See [Getting Started — Installation](getting-started.md#installation) for the path dependency pattern.
+
+## `:io_bridge` mode
+
+For robots that communicate via raw Ruby IO (`puts`/`gets`) rather than the `AskUser` tool. The server replaces `robot.input` and `robot.output` with an `IoBridge` instance before starting the robot thread, and restores the originals on teardown.
+
+`IoBridge` behaviour:
+
+- **Writes** (`write`, `puts`, `print`) — accumulate into an internal buffer.
+- **`gets`** — flushes the buffer as an `input_required` SSE event (the buffered text becomes the prompt), then blocks on `answer_queue` until the A2A client resumes. The answer is returned from `gets` to the robot.
+
+The two-turn client pattern is identical to `:a2a_tool`.
+
+```ruby
+RobotLab::A2A::Server.new(interactive: :io_bridge)
+  .add_robot(robot, name: "IO Robot", description: "Uses gets/puts for interaction")
+  .run(port: 7000)
+```
+
+**Robot interface required:**
+
+- `robot.input=` / `robot.output=` — settable IO attributes.
+- The robot must use `@input.gets` and `@output.puts` (or equivalent) rather than `$stdin`/`$stdout` directly.
+
+**Important:** Interactive resume requires `simple_a2a` with `ResumeContext` support.
+
+## Choosing a mode
+
+| Mode | Robot interface required | Typical use case |
+|---|---|---|
+| `:none` | `robot.run(text) → result.reply` | Fully autonomous robots with no user prompts |
+| `:a2a_tool` | `robot.run(text)` + mutable `robot.local_tools` | Robots that use `RobotLab::AskUser` as a tool |
+| `:io_bridge` | `robot.run(text)` + settable `robot.input=` / `robot.output=` | Robots that interact via raw stdin/stdout streams |
+
+When in doubt, start with `:none`. Upgrade to `:a2a_tool` if your robot uses `AskUser`, or `:io_bridge` if it uses raw IO.