Dirigent/FEAT.md

# Dirigent — Feature List

All implemented features across all versions.

---

## Core: Rule-Based No-Reply Gate
- Deterministic logic in `before_model_resolve` hook decides whether to route to no-reply model
- **human-list** mode: humanList senders bypass gate; others need end symbol to pass
- **agent-list** mode: agentList senders need end symbol; others bypass
- Non-Discord messages skip entirely
- DM sessions (no metadata) always bypass
- Per-channel policy overrides via JSON file (runtime-updateable)

## Core: End-Symbol Enforcement
- Injects prompt instruction: "Your response MUST end with 🔚"
- Gateway keywords (NO_REPLY, HEARTBEAT_OK) exempt from end symbol
- Group chats get additional rule: "If not relevant, reply NO_REPLY"
- End symbols configurable per-channel via policy

## Core: No-Reply API
- OpenAI-compatible API (`/v1/chat/completions`, `/v1/responses`, `/v1/models`)
- Always returns `NO_REPLY` — used as the override model target
- Optional bearer auth (`AUTH_TOKEN`)
- Auto-started/stopped with gateway lifecycle

## Turn-Based Speaking (Multi-Bot)
- Only the current speaker is allowed to respond; others forced to no-reply model
- Turn order auto-populated from bot accounts seen in each channel
- Turn advances on end-symbol (successful speech) or NO_REPLY
- Successful speech resets NO_REPLY cycle counter
- If all bots NO_REPLY in a cycle → channel goes **dormant**
- Dormant reactivation: human message → first in order; bot message → next after sender
- Turn timeout: auto-advance after 60s of inactivity
- Manual control: `/dirigent turn-status`, `/dirigent turn-advance`, `/dirigent turn-reset`

## Human @Mention Override *(v0.3.0)*
- When a `humanList` user @mentions specific agents (`<@USER_ID>`):
  - Extracts mentioned Discord user IDs from message content
  - Maps userIds → accountIds via reverse bot token lookup
  - Filters to agents in the current turn order
  - Orders by their position in the current turn order
  - Temporarily replaces speaking order with only those agents
  - Cycle: a → b → c → (back to a) → restore original order, go dormant
- Edge cases:
  - All override agents NO_REPLY → restore + dormant
  - `resetTurn` clears any active override
  - Human message without mentions → restores override, normal flow
  - Mentioned users not in turn order → ignored

## Agent Identity Injection
- Group chat prompts include: agent name, Discord accountId, Discord userId
- userId resolved from bot token (base64 first segment)

## Wait for Human Reply *(v0.3.0)*
- Configurable wait identifier (default: `👤`)
- Agent ends message with `👤` instead of `🔚` when it needs a human to reply
- Triggers "waiting for human" state:
  - All agents routed to no-reply model
  - Turn manager goes dormant
  - State clears automatically when a human sends a message
- Prompt injection tells agents:
  - Use wait identifier only when confident the human is actively participating
  - Do NOT use it speculatively
- Works with mention override: wait identifier during override also triggers waiting state

## Scheduling Identifier
- Configurable identifier (default: `➡️`) used for moderator handoff
- Handoff format: `<@TARGET_USER_ID>➡️` (non-semantic scheduling signal)
- Agent prompt explains: identifier is meaningless — check chat history, decide whether to reply
- If nothing to say → NO_REPLY

## Moderator Bot Presence
- Maintains Discord Gateway WebSocket connection for moderator bot
- Shows "online" status with "Moderating" activity
- Handles reconnect, resume, heartbeat, invalid session recovery
- Singleton guard prevents duplicate connections
- Sends handoff messages to trigger next speaker's turn

## Individual Tools *(v0.3.0)*
Six standalone tools (split from former monolithic `dirigent_tools`):

### Discord Control
- **`dirigent_discord_channel_create`** — Create private Discord channel with user/role permissions
- **`dirigent_discord_channel_update`** — Update permissions on existing private channel
- **`dirigent_discord_member_list`** — List guild members with pagination and field projection

### Policy Management
- **`dirigent_policy_get`** — Get all channel policies
- **`dirigent_policy_set`** — Set/update a channel policy (listMode, humanList, agentList, endSymbols)
- **`dirigent_policy_delete`** — Delete a channel policy

### Turn Management (internal only — not exposed as tools)
Turn management is handled entirely by the plugin. Manual control via slash commands:
- `/dirigent turn-status` — Show turn state
- `/dirigent turn-advance` — Manually advance to next speaker
- `/dirigent turn-reset` — Reset turn order (go dormant, clear overrides)

## Slash Command: `/dirigent`
- `status` — Show all channel policies
- `turn-status` — Show turn state for current channel
- `turn-advance` — Manually advance turn
- `turn-reset` — Reset turn order

## Project Rename (WhisperGate → Dirigent) *(v0.2.0)*
- All plugin ids, tool names, config keys, file paths, docs updated
- Legacy `whispergate` config key still supported as fallback

## Installer Script *(updated v0.3.0)*
- `scripts/install-dirigent-openclaw.mjs`
- `--install` / `--uninstall` / `--update` modes
- **Dynamic OpenClaw dir resolution**: `$OPENCLAW_DIR` → `openclaw config get dataDir` → `~/.openclaw`
- Builds dist and copies to `$(openclaw_dir)/plugins/dirigent`
- `--update`: pulls latest from git `latest` branch, then reinstalls
- Auto-reinstall (uninstall + install) if already installed
- Backup before changes, rollback on failure
- Records stored in `$(openclaw_dir)/dirigent-install-records/`

## Discord Control API (Sidecar)
- Private channel create/update with permission overwrites
- Member list with pagination + field projection
- Guardrails: action validation, id-list limits, response-size limit
- Runs as optional companion service (`discord-control-api/`)