Design Draft

Orchestrator Framework

Status: design for review, not yet built. This document describes a conversation orchestration layer for the ambassador fleet. Nothing here is implemented.

0What this is

A system that coordinates multiple ambassador accounts inside a shared Telegram group so they behave like a room of real people instead of N independent bots. The core problem it solves: without coordination, multiple accounts respond to the same message simultaneously, talk over each other, and produce tidy, over-coherent exchanges that read as automated.

The orchestrator is a director, not a screenwriter. It blocks scenes and calls beats; individual ambassadors improvise their own lines in persona. Its main creative job is making the conversation messy on purpose, because real group chat is messy.

1Core principle

One decision-maker per group. Ambassadors never self-initiate group speech, they execute what the orchestrator dispatches. Because a single process decides who speaks and when, mutual exclusion is structural: two ambassadors cannot collide on the same message.

2Per-group configuration (operator-controlled)

The orchestrator is opt-in per group. It does nothing in any group it isn't explicitly enabled on. Each monitored group has:

Setting	Values	Default	Meaning
`enabled`	on / off	off	master switch for this group
`cast`	list of ambassador handles	all in group	which ambassadors may speak here
`chaos_level`	subtle / realistic / maximum	realistic	conversation texture (see §4)
`mention_frequency`	background / opportunistic / forward	background	how often the project comes up
`mention_style`	only-if-asked / weave-in / active-advocate	only-if-asked	how it comes up when it does
`max_msgs_day`	int	10	fleet-wide cap in this group
`crosstalk`	on / off	on	allow ambassador ↔ ambassador banter

The two mention axes are independent: opportunistic + only-if-asked = clearly casino people who never name the project unless asked; background + weave-in = the project is ambient texture with no link and no push. forward + active-advocate is reserved for explicitly shill-friendly groups.

3Room-state model (the input the brain reads)

Each pass, the orchestrator builds a live snapshot of the group:

recent messages with authors + timestamps
message rate (hot / normal / dead)
time since last message
hanging questions (unanswered messages that look like questions)
per-ambassador state in this group (last spoke, count today, cooldown remaining)
open threads (which ambassador is mid-conversation, for continuity)
real users currently active

4Conversation realism mechanics

The layer that determines whether output reads as people or as a play.

Typing theater. Telegram surfaces "typing…" indicators. The orchestrator choreographs them as performance: an ambassador starts typing, stalls, the indicator clears, another starts, then the first message actually lands. Real chats have false starts; bots don't.
Interruption & resolve. Occasionally two ambassadors both begin answering the same message; the orchestrator makes one bail ("nvm, vex said it"). Collision-and-defer is a strong realism signal.
Dead threads. Some multi-way arcs stop unresolved. Real conversations fizzle; scripted ones conclude neatly.
Fragment distribution. Mostly short bursts ("lol", "wait fr?", "nah been on it all week"), rarely a longer message. Never several tidy paragraphs in a row.
Variable latency. Replies land on human timescales (tens of seconds to minutes), never instantly.
Real-user weaving. When a real user speaks mid-arc, the orchestrator redirects the scene around them — an ambassador answers them, the arc adapts, or the ambassadors engage the real user to pull them into the conversation.

chaos_level scales how frequently these fire: subtle = occasional false-starts, threads mostly resolve; realistic = frequent false-starts, interruptions, some dead threads; maximum = constant interruption, fragments, threads die often.

5Decision cycle (every pass, per group)

Should anyone speak at all? Often no — restraint is humanizing. Silence when the room flows fine without the fleet, when caps/cooldowns are hit, or when there's no opening.
Reactive or proactive? Reactive = respond to a hanging question or fitting topic. Proactive = start a topic only when the room has been dead long enough that a regular would revive it. Proactive is triggered by room state, never by a clock.
Who speaks? Full-context scoring across the cast: persona fit, recency (penalize whoever spoke last), freshness (reward whoever hasn't been heard), thread continuity, hard cooldown exclusions, plus a randomness term so selection isn't deterministic.
What do they say? Generated per-ambassador via the persona system at the group's mention settings, with safety rails always injected.
When? Jittered human delay, plus any typing-theater choreography.

6Steering (two-axis, room-gated)

The dials set a ceiling, the room sets the actual behavior. Before any project mention, the orchestrator checks for a live opening (e.g. someone asks about casinos/tokens). A genuine opening fires a mention regardless of the dial; no opening means force nothing. Even at the most assertive setting, the safety rules hold (below).

7Cross-talk

Ambassadors may banter with each other where crosstalk=on. To keep it from looking staged: only in already-active rooms, hard cooldowns on how often any two ambassadors interact, back-and-forths capped at a couple exchanges, and the orchestrator sets the beats while each ambassador writes its own lines in persona.

8Safety rails (always on, cannot be overridden by any dial)

Always enforced

Ambassadors are openly affiliated; if asked whether they're part of the project, answer yes.
Never hard-sell; never promise returns, price predictions, or "can't lose."
never_say list from the workspace knowledge base is enforced on every message.
If a conversation turns into a serious purchase/intent discussion, hand off to the official group / a human rather than freelancing a close.
Ignore bots/scammers; don't engage "send crypto" solicitations.

9External inputs

The orchestrator can take signals beyond the group's own messages — e.g. a content calendar, price/launch events, or an operator-injected prompt ("someone should ask about the presale soon"). These enter as scene directions the cast reacts to, same as a real user's message.

10Implementation shape (for the reviewer)

New module fleet/orchestrator.py, driven by the existing daemon loop.
New tables: group_configs (per-group settings, §2), orchestrator_log (every decision: room signal → decision → who/what/when, for review and debugging).
Judgment calls (§5) run through the existing LLM layer; requires an LLM key configured.
Dashboard gains a Monitored Groups page: add groups, toggle enabled, set the dials, watch the decision log.
Ambassadors act only inside their existing per-account active windows and daily caps.

11Open questions for the reviewer

Is per-group opt-in the right control granularity, or should there also be a global kill-switch per ambassador?
Should mention_* defaults differ by workspace, or stay conservative everywhere?
What cadence should the orchestrator run at per group (and should it differ hot vs. quiet groups)?
How should cross-talk cooldowns be tuned to avoid detectable pairing patterns?
What logging/observability is needed for an operator to trust the orchestrator's decisions?