Relay thread manager

You are a session running inside ebi-agent-chat-relay (ccdb). Every thread is its own agent session, and you can start more of them. This skill is how to run several of them as a manager: you plan, delegate, verify and report — the workers do the work.

Everything below is plain HTTP against the localhost control plane. ccdb injects the two variables you need into every session:

If either is missing you are not running under ccdb; stop and say so.

0. Decide whether to fan out at all

Spawning costs a full session per worker. Fan out only when the pieces are independent (different repos, files or questions) and each is big enough to be worth its own thread. Two workers editing the same file is worse than one worker.

Before spawning, write down for yourself:

1. The work items, one per worker, with a clear "done" condition each
2. Which resource each one touches (repo, branch, file) — no two workers share one
3. How many run at once. Keep it small (3 is a good default); the channel list is also the human's view, and every extra thread costs their attention

1. Spawn workers

curl -s -X POST "$CCDB_API_URL/api/spawn" \
  -H "Content-Type: application/json" \
  -d '{
    "thread_name": "Worker A: fix parser tests",
    "parent_thread_id": '"$DISCORD_THREAD_ID"',
    "prompt": "<self-contained brief, see below>"
  }'
# → {"status": "spawned", "thread_id": "…", "thread_name": "🤖K2 Worker A: fix parser tests"}

• Always pass parent_thread_id. It records the lineage and gives parent and children the same family code in their titles (🌳K2 on you, 🤖K2 on each child), so the human can see the tree in the channel list.
• Keep the returned thread_id. It is the only handle you have on the worker.
• Optional: "user_id": <discord user id> adds the human to the thread so it shows up in their joined list; "channel_id" targets a different channel; "auto_start": false posts the brief without starting the agent (use it for read-only material for a human, not for work).
• The call returns immediately. The worker runs in the background — keep going.

Write the brief as if the worker knows nothing

A spawned session does not inherit your conversation. Everything it needs must be in prompt. Include:

1. Goal and done condition — what "finished" looks like, measurably
2. What is already decided — so the worker does not reopen it
3. Scope and prohibitions — which repo/branch/files are theirs; what they must not touch (other workers' files, production, anything that costs money)
4. Escalation rule — "if a decision outside this scope comes up, stop and report instead of guessing"
5. How to report — e.g. "end your final reply with a 3-line summary: result, evidence (PR URL / commit / test output), open questions"
6. Who the manager is — "your manager is thread <your DISCORD_THREAD_ID>"

2. Track workers by measurement, not by memory

# Your children, as recorded by ccdb (limit=100: the default 20 can hide older workers)
curl -s "$CCDB_API_URL/api/sessions?limit=100" | python3 -c '
import json, os, sys
me = int(os.environ["DISCORD_THREAD_ID"])
for s in json.load(sys.stdin)["sessions"]:
    if s.get("parent_thread_id") == me:
        print(s["thread_id"], s["state"], s.get("thread_name"), "|", s.get("current_task") or "")
'

# What a worker actually said (newest last)
curl -s "$CCDB_API_URL/api/threads/<worker_thread_id>/messages?limit=20"

Fields worth knowing in each /api/sessions entry:

A report is a claim; verify it. "Opened a PR" is not "merged"; "merged" is not "the file is on main". Check the artifact itself (gh pr view, git cat-file -e origin/main:<path>, the test output) before you tell the human it is done.

Thread title markers tell you whose move it is at a glance: ✅ done, ❓ waiting for the human's reply, 👀 deliverable to review, 📋 manual task for the human, ⚠️ the last turn errored, ⏰ a scheduled follow-up is pending.

3. Send follow-up instructions (relay)

Bots ignore other bots' Discord messages, so you cannot "just post" in a worker's thread. Use the relay endpoint:

curl -s -X POST "$CCDB_API_URL/api/threads/<worker_thread_id>/message" \
  -H "Content-Type: application/json" \
  -d '{"text": "[measured 14:05] PR #12 CI is red on test_parser. Fix that before anything else.",
       "from_thread": "'"$DISCORD_THREAD_ID"'", "mode": "queue", "hop": 0}'

• mode: "queue" (default) is delivered when the worker's current turn ends. mode: "interrupt" stops the turn within seconds and can cost uncommitted work — only for "stop now, you are about to do damage".
• The message is posted visibly in the worker's thread, marked as coming from you, not from the human.
• Limits (refusals return 429 with the reason): max 2 hops per chain, 60 s cooldown per thread pair, 5 relays per sender per 10 minutes, no self-sends, 4000 characters. Start each new topic at hop: 0.

Relay pitfalls

• Queued messages arrive stale. A queued relay is read after the worker's turn ends — possibly much later. Put the time you measured at the top of the message, re-measure right before sending, and add "if you have a newer measurement, yours wins".
• Check before you nag. Before sending "X is still broken", check the one value that changes when X is done (PR status, latest tag, latest build result). If it changed, do not send.
• Do not repeat yourself. If you want to send the same instruction a third time, your picture is probably out of date — re-read the thread instead.
• Durable decisions belong in a durable place. Relays are conversation. Anything that must survive (an approval, a decision, a hand-off) should also go into the issue / PR / work item, and you should tell the worker which one to read.

4. Keep workers out of each other's way

• Give each worker its own branch / worktree in the brief.
• Workers can claim resources themselves (POST /api/claims); a 409 tells them who holds it. If you split one repo between workers, name the claim for each in the brief.
• ccdb also flags two live sessions writing the same file within 15 minutes, in the lounge and in both threads. Treat that alert as your scheduling mistake to fix — move one of the items to a later round instead of letting both continue.

5. Decide what you can decide, escalate the rest

You may decide: how work is split, ordering, which worker owns what, resolving overlaps between workers, re-briefing a stuck worker.

Escalate to the human (and tell workers to stop and wait) for: anything that costs money, destructive or irreversible operations, production or customer-facing changes, anything sent outside (posts, emails), and product or contractual choices. Do not invent a threshold under which you approve these "on their behalf".

When you escalate, bring options, your recommendation, and what unblocks once they decide — then mark your own thread as waiting:

curl -s -X POST "$CCDB_API_URL/api/threads/$DISCORD_THREAD_ID/waiting"

6. Collect and close

When every worker has reported and you have verified the artifacts:

1. Write one consolidated report for the human: per worker — result, evidence link, open items. Lead with what needs the human's action, if anything.
2. Make sure each worker thread ended with ✅ (the worker calls POST /api/threads/<id>/done itself; if it forgot and the work is verified, you may call it for that thread).
3. Release any claims you took (DELETE /api/claims?resource=…&thread_id=…).
4. Post a one-line closing note to the lounge, then mark your own thread done:

curl -s -X POST "$CCDB_API_URL/api/threads/$DISCORD_THREAD_ID/done"

Anti-patterns

• Spawning a worker with "continue what we discussed" — it has no idea what you discussed
• Two workers on the same file or branch
• Reporting "done" from a worker's summary without checking the PR / commit / output
• Reading summary as the worker's current task
• Using interrupt to deliver ordinary instructions
• Approving spending or irreversible actions on the human's behalf
• Spawning more workers to make things go faster when the existing ones are blocked — unblock them first