Document Joiner. (#2183)

Fixes #2112.

packages/website/src/docs/kits/agents/index.md

@@ -232,8 +232,25 @@ When placed into the flow of work, Human shows the intermediate output and asks
 
 ## Joiner
 
-TO DO:
+While not powered by an LLM or representing a real person, Joiner is an essential part of any team of workers. Depending on how it is configured, Joiner acts a helper that, respectively, joins or merges conversation contexts.
 
-- Describe how joiner works
+{{ "/breadboard/static/boards/joiner-example.bgl.json" | board }}
 
-- Create a graph that joins contexts.
+When the flow of work splits across multiple workers, we can rely on Joiner to bring it all together.
+
+When first added to the board, Joiner has no incoming ports: we have to explicitly inform it about all the context we'd like to join. To do so, use the "ad hoc" wiring technique in Breadboard. Drag a wire from each outgoing port we want to be joined into the center of the Joiner, then release. A small dialog box will pop up asking to name the port. Give it an informative name (can only contain lowercase alphanumeric characters, dashes, or numbers) and the wire will appear.
+
+{{ "/breadboard/static/boards/new-joiner-port.bgl.json" | board }}
+
+Joiner has one configuration option, a checkbox on whether or not to merge the last items of all incoming context into one.
+
+![Joiner Merge option](/breadboard/static/images/agent-kit/joiner-merge.png)
+
+When that checkbox is not checked, joiner will take all of the incoming conversation contexts and just string them together into one mega conversation context.
+
+When the checkbox is checked, it will only take the last item of each conversation context and turn them into a new conversation context that contains only one item, merging them as parts of that item.
+
+In either case, the order of items (or contexts) is determined by the alphabetical sort of the incoming ports for the Joiner.
+
+> [!TIP]
+> It's a good practice to name ports in a way that makes the order evident. Like in the example above, the ports are named "a-picture", "b-voice", and "c-text" to ensure that the picture goes first, followed by voice and then text.

packages/website/src/static/boards/joiner-example.bgl.json

@@ -0,0 +1,208 @@
+{
+  "title": "Card Maker",
+  "version": "0.0.1",
+  "metadata": {
+    "comments": [
+      {
+        "id": "comment-571ff92f",
+        "text": "Writes contents of \na game card",
+        "metadata": {
+          "visual": {
+            "x": -129,
+            "y": 70,
+            "collapsed": false
+          }
+        }
+      },
+      {
+        "id": "comment-6ce6abeb",
+        "text": "Uses the contents to craft a prompt and create picture.",
+        "metadata": {
+          "visual": {
+            "x": -77,
+            "y": -175,
+            "collapsed": false
+          }
+        }
+      },
+      {
+        "id": "comment-b99d3821",
+        "text": "Narrates the text \nof the card",
+        "metadata": {
+          "visual": {
+            "x": 50,
+            "y": -29,
+            "collapsed": false
+          }
+        }
+      },
+      {
+        "id": "comment-6907d9cd",
+        "text": "Joins picture, voice, and text into one card.",
+        "metadata": {
+          "visual": {
+            "x": 268,
+            "y": 113,
+            "collapsed": false
+          }
+        }
+      }
+    ]
+  },
+  "edges": [
+    {
+      "from": "input",
+      "to": "specialist-42832612",
+      "out": "context",
+      "in": "in"
+    },
+    {
+      "from": "specialist-42832612",
+      "to": "specialist-5b7a9d43",
+      "out": "out",
+      "in": "in"
+    },
+    {
+      "from": "specialist-42832612",
+      "to": "specialist-6a61c0b5",
+      "out": "out",
+      "in": "in"
+    },
+    {
+      "from": "specialist-42832612",
+      "to": "joiner-22b013c9",
+      "out": "out",
+      "in": "c-text"
+    },
+    {
+      "from": "specialist-5b7a9d43",
+      "to": "joiner-22b013c9",
+      "out": "out",
+      "in": "a-picture"
+    },
+    {
+      "from": "specialist-6a61c0b5",
+      "to": "joiner-22b013c9",
+      "out": "out",
+      "in": "b-voice"
+    },
+    {
+      "from": "joiner-22b013c9",
+      "to": "output",
+      "out": "context",
+      "in": "context"
+    }
+  ],
+  "nodes": [
+    {
+      "type": "input",
+      "id": "input",
+      "configuration": {
+        "schema": {
+          "properties": {
+            "context": {
+              "type": "array",
+              "title": "Context",
+              "examples": [],
+              "items": {
+                "type": "object",
+                "behavior": ["llm-content"]
+              },
+              "default": "[{\"role\":\"user\",\"parts\":[{\"text\":\"\"}]}]"
+            }
+          },
+          "type": "object",
+          "required": []
+        }
+      },
+      "metadata": {
+        "visual": {
+          "x": -213,
+          "y": -127,
+          "collapsed": false
+        }
+      }
+    },
+    {
+      "type": "output",
+      "id": "output",
+      "configuration": {
+        "schema": {
+          "properties": {
+            "context": {
+              "type": "array",
+              "title": "Context",
+              "examples": [],
+              "items": {
+                "type": "object",
+                "behavior": ["llm-content"]
+              },
+              "default": "null"
+            }
+          },
+          "type": "object",
+          "required": []
+        }
+      },
+      "metadata": {
+        "visual": {
+          "x": 369,
+          "y": -148,
+          "collapsed": false
+        }
+      }
+    },
+    {
+      "id": "specialist-42832612",
+      "type": "specialist",
+      "metadata": {
+        "visual": {
+          "x": -167,
+          "y": 126,
+          "collapsed": false
+        },
+        "title": "Writer",
+        "logLevel": "debug"
+      }
+    },
+    {
+      "id": "specialist-5b7a9d43",
+      "type": "specialist",
+      "metadata": {
+        "visual": {
+          "x": 45,
+          "y": -123,
+          "collapsed": false
+        },
+        "title": "Illustrator",
+        "logLevel": "debug"
+      }
+    },
+    {
+      "id": "specialist-6a61c0b5",
+      "type": "specialist",
+      "metadata": {
+        "visual": {
+          "x": 90,
+          "y": 24,
+          "collapsed": false
+        },
+        "title": "Narrator",
+        "logLevel": "debug"
+      }
+    },
+    {
+      "id": "joiner-22b013c9",
+      "type": "joiner",
+      "metadata": {
+        "visual": {
+          "x": 354,
+          "y": 2,
+          "collapsed": false
+        },
+        "title": "Card Maker",
+        "logLevel": "debug"
+      }
+    }
+  ]
+}

packages/website/src/static/boards/new-joiner-port.bgl.json

@@ -0,0 +1,59 @@
+{
+  "title": "Wiring Joiner ",
+  "version": "0.0.1",
+  "metadata": {
+    "comments": [
+      {
+        "id": "comment-f59dbc67",
+        "text": "Drag a wire from \"Context Out\" ...",
+        "metadata": {
+          "visual": {
+            "x": 19,
+            "y": -46,
+            "collapsed": false
+          }
+        }
+      },
+      {
+        "id": "comment-58b1c17b",
+        "text": "... to the center of Joiner and then let go. You will then be asked to name the incoming port for this wire.",
+        "metadata": {
+          "visual": {
+            "x": 259,
+            "y": -1,
+            "collapsed": false
+          }
+        }
+      }
+    ]
+  },
+  "edges": [],
+  "nodes": [
+    {
+      "id": "specialist-be4d952e",
+      "type": "specialist",
+      "metadata": {
+        "visual": {
+          "x": -39,
+          "y": 8,
+          "collapsed": false
+        },
+        "title": "Illustrator",
+        "logLevel": "debug"
+      }
+    },
+    {
+      "id": "joiner-ddb55d72",
+      "type": "joiner",
+      "metadata": {
+        "visual": {
+          "x": 221,
+          "y": -71,
+          "collapsed": false
+        },
+        "title": "Card Maker",
+        "logLevel": "debug"
+      }
+    }
+  ]
+}