synapbus/specs/018-dynamic-agent-spawning/quickstart.md

Quickstart: Dynamic Agent Spawning

A 10-minute walkthrough for building the feature against the current SynapBus codebase. This doc mirrors the structure of examples/cold-topic-explainer/README.md.

Prerequisites

• Go 1.25+
• gemini CLI installed and authenticated (gemini auth login once) — or any other LLM the coordinator can target
• jq, curl, sqlite3 on $PATH
• A free TCP port for an isolated instance (default 18088)
• The current checkout on the 018-dynamic-agent-spawning branch

1. Build and run the instance

cd examples/doc-gardener
./start.sh

start.sh will:

1. Rebuild the synapbus binary from the current checkout into ./bin/synapbus.
2. Wipe ./data and launch a fresh instance on port 18088 with a local ./data directory.
3. Create a user algis (password algis-demo-pw).
4. Create a coordinator agent named doc-gardener-coordinator with its fixed system prompt and the tool scope [create_goal, propose_task_tree, propose_agent, send_message, search_messages, my_status].
5. Pre-create the #approvals and #requests channels with workflow enabled.
6. Leave synapbus running in the background (pid in .synapbus.pid, logs in synapbus.log).

2. Kick off a goal

./run_task.sh --auto-approve

run_task.sh does:

1. DMs the coordinator a create_goal instruction (or calls the create_goal MCP tool directly via the admin socket) with title "Verify docs.mcpproxy.app against source" and a paragraph-long description.
2. Launches ./auto_approve.sh & in the background, which polls #approvals every second and posts approve reactions on any pending proposal.
3. Polls the goal's backing channel (#goal-verify-docs-mcpproxy-app-against-source) for a FINAL: message from the coordinator, or until a 5-minute timeout.
4. On completion, prints the final status and the path to run ./report.sh.

3. Render the report

./report.sh

report.sh runs ./bin/doc-gardener-report (a tiny Go binary compiled from report.go) which:

1. Reads the goal id from .last_goal_id.
2. Calls the internal goal-snapshot service to fetch: goal meta, task tree, spawned agents, reputation deltas, cost breakdown, timeline.
3. Renders report.html.tmpl into report.html.
4. Opens the file in the default browser via open report.html (macOS) or prints the path on Linux.

4. Observe during the run

• Web UI: http://localhost:18088 — log in as algis. New /goals page lists the goal; click in for the tree + timeline.
• Goal channel: http://localhost:18088/channels/goal-verify-docs-mcpproxy-app-against-source
• Approvals queue: http://localhost:18088/channels/approvals — watch the auto-approver react.
• Agent details: http://localhost:18088/agents/doc-gardener-coordinator
• Harness runs:

  sqlite3 ./data/synapbus.db \
    "SELECT run_id, agent_name, task_id, duration_ms, tokens_in, tokens_out, cost_usd
       FROM harness_runs ORDER BY id;"
  

• Task tree:

  sqlite3 ./data/synapbus.db -header -column \
    "SELECT id, parent_task_id, status, title, spent_tokens, spent_dollars_cents FROM tasks;"
  

• Reputation deltas:

  sqlite3 ./data/synapbus.db -header -column \
    "SELECT config_hash, task_domain, score_delta, evidence_ref, created_at
       FROM reputation_evidence ORDER BY created_at;"
  

5. Stop and clean

./stop.sh

stop.sh signals the synapbus process, waits for clean exit, and leaves ./data and ./report.html in place for post-mortem.

What success looks like

• report.html exists and opens in a browser.
• It shows at least:
  • 1 goal (title + status)
  • ≥ 3 tasks in a tree
  • ≥ 1 spawned specialist with config_hash and a reputation row
  • ≥ 1 done task AND ≥ 1 verified artifact (or ≥ 1 failed task with reason)
  • A non-zero cost breakdown by billing code
  • A chronological timeline with at least 10 events
• harness_runs shows at least one run per spawned specialist with non-zero duration_ms and tokens_out.
• The Web UI /goals page renders the same tree and stays under 1 s load time.

Troubleshooting

Symptom	Likely cause	Fix
./start.sh hangs at "waiting for admin socket"	Port conflict	SYNAPBUS_PORT=18089 ./start.sh
Coordinator never posts a proposal	Gemini auth missing or wrong model	gemini auth login; edit configs/coordinator.json model field
Tasks never claimed	Auto-approve not running	Check auto_approve.pid; run ./auto_approve.sh manually
Budget exceeded immediately	Budget too low	Increase budget_dollars_cents in run_task.sh goal create call
report.html is empty	Goal not yet decomposed	Wait for proposal + approval + at least one specialist run