WIP: feat(conductor): add interactive conductor type

[BestSithInEU]

Summary

Add a new interactive conductor type that provides direct session control from messaging platforms (Telegram, Slack, Discord) — no Claude-powered conductor in the middle. The user becomes the orchestrator, interacting with individual agent-deck sessions through chat threads, inline keyboards, and paginated output.

Inspired by ccbot but built from scratch in Go as part of the agent-deck ecosystem.

Key differences from standard conductor

	Standard	Interactive
Orchestrator	Claude (conductor session)	Human (via chat)
Bridge	Python (bridge.py)	Go (per-platform binary)
Monitoring	Heartbeat-based polling	Real-time JSONL transcript watching
Interaction	Text relay	Inline keyboards, paginated output, screenshots
Session control	Via conductor Claude	Direct from chat commands

Architecture

Plugin-per-platform — shared Go core library (internal/bridge/core/) with thin platform binaries:

• cmd/agent-deck-bridge-telegram/
• cmd/agent-deck-bridge-slack/
• cmd/agent-deck-bridge-discord/

Each bridge runs as an independent systemd/launchd service. Fault isolation: one platform crashing doesn't affect others.

Core components:

• TranscriptWatcher — fsnotify on JSONL files with debouncing + poll fallback
• SessionRouter — chat thread/topic ↔ session mapping with per-platform persistence
• AuthManager — role-based (multi-admin + viewer) per platform
• ANSIRenderer — terminal screenshot to PNG with bundled monospace font
• Paginator — inline button navigation (prev/next) instead of message splitting

Implementation Plan

Phase 1: Core Library & ConductorMeta Extension

• Add Type field to ConductorMeta with GetType() accessor (default: "standard")
• Add InteractiveConductorSettings to ConductorSettings struct
• Extend SetupConductor() and handleConductorSetup() with --type flag
• Gate setup steps on type (skip heartbeat/Python for interactive, install Go bridge services)
• Implement internal/bridge/core/config.go — config loading from [conductor.interactive]
• Implement internal/bridge/core/auth.go — role-based auth manager
• Implement internal/bridge/core/executor.go — CLI wrapper for agent-deck commands

Phase 2: Transcript Watcher & Event System

• Define event types in internal/bridge/core/events.go
• Implement internal/bridge/core/watcher.go — fsnotify + tail-follow JSONL parser
• Map JSONL records to typed events (assistant response, tool use, permission request, state transition, etc.)
• Implement subscription model (discovered/subscribed/unsubscribed per session)
• Add debouncing (100ms coalesce window) and poll fallback (configurable, default 5s)

Phase 3: Session Router & State Persistence

• Implement internal/bridge/core/router.go — chat target ↔ session mapping
• Per-platform persistence (router-telegram.json, router-slack.json, router-discord.json)
• Auto-discovery on startup with lazy thread creation (avoid rate limits)
• New session detection via filesystem watching

Phase 4: Rendering & Pagination

• Implement internal/bridge/core/paginator.go — page splitting + inline button navigation
• Implement internal/bridge/core/renderer.go — ANSI-to-PNG using charmbracelet/x/ansi + golang.org/x/image
• Platform-aware message formatting (Telegram HTML, Slack blocks, Discord markdown)
• Command rate limiting (1/s per session for exec commands)

Phase 5: Platform Adapter Interface & Telegram Bridge

• Define PlatformAdapter interface in internal/bridge/platform/adapter.go
• Implement Telegram adapter (internal/bridge/platform/telegram/)
  • Bot setup, message routing, command handlers
  • Inline keyboard for permissions/plan mode
  • Paginated message editing (prev/next)
  • Thread mode auto-detection (supergroup topics vs flat)
  • Retry with Retry-After for 429 rate limits
• Implement cmd/agent-deck-bridge-telegram/main.go

Phase 6: Slack & Discord Bridges

• Implement Slack adapter (internal/bridge/platform/slack/) — Socket Mode, button attachments
• Implement Discord adapter (internal/bridge/platform/discord/) — button components, forum channels
• Implement cmd/agent-deck-bridge-slack/main.go and cmd/agent-deck-bridge-discord/main.go

Phase 7: Build & Deployment

• Add build targets to Makefile for bridge binaries
• Add bridge binaries to .goreleaser.yml
• Systemd service templates (Linux) and launchd plist templates (macOS)
• Wire into conductor setup --type interactive for automatic service installation

Chat Commands

Command	Role	Description
/help	viewer	List available commands
/status	viewer	Session status overview
/sessions	viewer	List all sessions
/subscribe <session>	viewer	Stream full output
/unsubscribe <session>	viewer	Stop streaming
/output <session>	viewer	Last response (paginated)
/screenshot <session>	viewer	Terminal screenshot as PNG
/send <session> <msg>	admin	Send message to session
/new <path> [-t title]	admin	Create session
/launch <path> -t <title> -m <msg>	admin	Create + start + prompt
/start / /stop / /restart <session>	admin	Session lifecycle
/worktree <path> -b <branch>	admin	Create session with worktree

Test Plan

• Unit tests for core library (watcher, router, auth, paginator, renderer)
• Unit tests for JSONL event mapping (parse real Claude JSONL samples)
• Integration test: ConductorMeta with type: "interactive" setup/teardown
• Integration test: conductor setup --type interactive skips heartbeat/Python
• Integration test: Telegram bot command parsing and routing
• Manual test: create interactive conductor, connect Telegram bot, send commands
• Manual test: subscribe to session, verify real-time transcript streaming
• Manual test: permission prompt → inline keyboard → allow/deny flow
• Manual test: /screenshot renders PNG correctly
• Manual test: paginated output with prev/next navigation
• Verify existing standard conductor tests still pass

Dependencies

Package	Purpose	Status
github.com/fsnotify/fsnotify	JSONL file watching	Already in go.mod
github.com/charmbracelet/x/ansi	ANSI parsing for screenshots	Already in go.mod
github.com/go-telegram-bot-api/telegram-bot-api/v5	Telegram bot	New
github.com/slack-go/slack	Slack bot (Socket Mode)	New
github.com/bwmarrin/discordgo	Discord bot	New
golang.org/x/image/font	Font rendering for PNG	New

[Copilot]

Pull request overview

Adds an initial stub artifact intended to relate to the proposed new interactive conductor type.

Changes:

• Add a new root-level .interactive-conductor file containing placeholder content.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[BestSithInEU]

What do you think @asheshgoplani ?