synapbus/examples/cold-topic-explainer

cold-topic-explainer

Toy multi-agent task that exercises the subprocess harness end-to-end. Three Gemini agents on different models collaborate via SynapBus DMs to produce a 3-paragraph explainer for a topic, with a writer ↔ critic refinement loop.

Roles

Agent	Model	Job
decomposer-pro	gemini-2.5-pro	Receives the topic, splits it into what / why / how, DMs writer-flash
writer-flash	gemini-2.5-flash	Drafts (or revises) the 3-paragraph explainer, DMs critic-lite
critic-lite	gemini-2.5-flash-lite	Rates each paragraph 1–10. Scores all ≥ 8 → DMs algis with FINAL:. Else DMs writer-flash with REVISE: and specific fixes

This exercises:

• Decomposition — decomposer-pro splits one request into 3 sub-questions
• Delegation — each agent DMs the next, routed by the SynapBus reactor
• Recursive update — the writer↔critic loop runs until convergence or max_trigger_depth fires (default 6, giving ~3 full refinement rounds)

Every hop is a subprocess reactive run, subject to the same depth / budget / cooldown guards as a K8s reactive run. Each hop writes a harness_runs row with usage, cost, duration, and trace id.

Prereqs

• gemini CLI installed and authenticated (gemini auth login done once)
• Go 1.25+
• jq, curl, sqlite3 available on PATH
• An unused TCP port (default 18088)

Run it

./start.sh
./run_task.sh "how does the SynapBus reactor's pending_work flag coalesce bursts of DMs?"
./stop.sh

What happens

• start.sh builds synapbus from the current checkout, launches a separate instance on port 18088 with a local ./data directory, creates user algis (password algis), creates three AI agents, and configures each agent's harness_config_json with GEMINI.md, MCP pointer, role env, and the wrapper script invocation.
• run_task.sh kicks off the chain by sending an initial DM from algis to decomposer-pro via the admin socket, then polls for a DM to algis whose body starts with FINAL:. Prints the body when it arrives (or gives up after 4 min).
• stop.sh signals the synapbus PID and waits for it to exit cleanly.

View during the run

• Web UI: http://localhost:18088 — log in as algis / algis-demo-pw
• Agent detail (see Harness panel + traces):
  • http://localhost:18088/agents/decomposer-pro
  • http://localhost:18088/agents/writer-flash
  • http://localhost:18088/agents/critic-lite
• Live slog JSON: tail -f synapbus.log | jq -c 'select(.component=="reactor" or .harness)'
• All DMs in order: ./bin/synapbus --socket ./data/synapbus.sock messages list --limit 50
• Harness runs: sqlite3 ./data/synapbus.db 'SELECT run_id, agent_name, backend, status, duration_ms, tokens_in, tokens_out, cost_usd FROM harness_runs ORDER BY id'

OpenTelemetry

Off by default. To ship spans to a collector while you run the task:

SYNAPBUS_OTEL_ENABLED=1 SYNAPBUS_OTEL_ENDPOINT=otel-collector.synapbus.svc.cluster.local:4318 ./start.sh

Or stand up a local collector first using deploy/kubic/otel-collector.yaml. Without a collector, the same information is available in synapbus.log as slog JSON and in the harness_runs table.

Cost

Rough cost per successful run, assuming 2 writer-critic iterations:

Hops	Model	Cost
1	gemini-2.5-pro	~$0.01
2	gemini-2.5-flash	~$0.01
3	gemini-2.5-flash-lite	~$0.002
Total		~$0.02

The daily trigger budget per agent is capped at 20 (see start.sh) so this example cannot accidentally spend more than pennies per day even if the reactor loops on a bug.

Files

• start.sh — launch separate synapbus + configure agents
• run_task.sh — kickoff DM + poll for final
• stop.sh — graceful shutdown
• wrapper.sh — shell wrapper used as the agents' local_command; reads message.json, calls gemini, routes the result back via the admin socket
• configs/*.json — per-agent harness_config_json blobs