@rrr2010/opencode-roundtable 0.3.0 → 0.3.2

package/README.md

@@ -1,203 +1,244 @@
-# opencode-roundtable
-
-OpenCode plugin that orchestrates **multi-agent round-robin debates**.
-Agents with different personalities debate a topic turn by turn, sharing
-context while keeping their own system prompts and tools.
-
-A built-in observer automatically consolidates every debate into an
-executive summary.
-
-## Installation
-
-### npm (recommended)
-
-```json
-{
-  "plugin": ["@rrr2010/opencode-roundtable@latest"]
-}
-```
-
-OpenCode auto-installs npm plugins on startup. No manual copy needed.
-
-### Local (dev)
-
-```bash
-git clone https://github.com/opencode-ai/roundtable
-cd roundtable
-bun run build
-npm link
-```
-
-Then add `"@rrr2010/opencode-roundtable"` to your opencode.json `plugin` array.
-```
-
-Add to `opencode.json` — OpenCode installs it with Bun on startup.
-
-## Features
-
-- **Round-robin debate** — agents speak in sequence, each seeing the full discussion history
-- **Shared context** — tool outputs and discoveries are visible to all participants
-- **Built-in observer** — automatically consolidates the debate into an executive summary (overridable with a specific agent)
-- **Isolated session** — the debate runs in a child session, keeping the main session clean
-- **Extend mode** — continue a concluded roundtable with more rounds or a new topic
-- **Agent discovery** — `available_agents` tool helps the orchestrator know which agents exist
-- **Parallel roundtables** — multiple independent debates can run simultaneously
-- **User intervention** — the human can jump into the debate at any time
-- **Stuck session recovery** — if an extend is aborted mid-way, the next call auto-recovers
-
-## Tool API
-
-### `roundtable()`
-
-```typescript
-roundtable({
-  agents?: string[],    // Names in speaking order (min 2). Required for new debates.
-  prompt: string,       // Topic or challenge. For multi-round, include per-round instructions.
-  rounds?: number,      // Complete rounds (default: 1, max: 50)
-  observer?: string,    // Agent for final consolidation (default: built-in)
-  sessionID?: string,   // ses_xxxx — pass to extend a concluded debate
-  title?: string,       // Custom title (default: auto-generated from prompt)
-})
-```
-
-**Returns:** `{ sessionID: string, summary: string }` after the debate concludes.
-
-**Side effect:** injects system-level prompts into each agent's context (role, topic, turn routing, lifecycle signals).
-
-### `available_agents()`
-
-```typescript
-available_agents()
-```
-
-**Returns:** `"Available agents: pm, dev, rv, ..."` — a formatted string of agent names.
-
-## Usage Examples
-
-### Basic — one round, built-in observer
-
-```typescript
-roundtable({
-  agents: ["pm", "dev"],
-  prompt: "What architecture should we use?",
-})
-```
-
-### Multi-round with per-round instructions
-
-```typescript
-roundtable({
-  agents: ["pm", "dev"],
-  prompt: "Round 1: list pros. Round 2: list cons. Round 3: propose an implementation plan.",
-  rounds: 3,
-})
-```
-
-### Explicit observer
-
-```typescript
-roundtable({
-  agents: ["pm", "dev"],
-  prompt: "Should we migrate to microservices?",
-  rounds: 2,
-  observer: "rv",
-})
-```
-
-### Extend a concluded debate
-
-```typescript
-roundtable({
-  sessionID: "ses_abc123",
-  rounds: 2,
-  prompt: "Dive deeper into operational costs",
-})
-```
-
-The session ID is injected into S1 as a noReply when the roundtable starts — check S1 context to find it.
-
-### Discover agents first
-
-```typescript
-const agents = available_agents()
-// agents => "Available agents: pm, dev, rv, build, plan"
-roundtable({
-  agents: ["pm", "dev"],
-  prompt: "...",
-})
-```
-
-## Configuration
-
-Place `~/.config/opencode/roundtable.json` to override defaults:
-
-```json
-{
-  "$schema": "https://raw.githubusercontent.com/opencode-ai/roundtable/main/docs/roundtable.schema.json",
-  "defaultTimeoutMs": 300000,
-  "loopSimilarityThreshold": 0.85,
-  "toolOutputPreviewMax": 500,
-  "maxRounds": 10,
-  "defaultObserverPrompt": "You are an impartial roundtable observer..."
-}
-```
-
-If the file doesn't exist, it's created automatically with defaults.
-
-## Tips
-
-### Agent selection
-
-Choose agents whose expertise matches the topic:
-
-| Agent | Best for |
-|-------|----------|
-| `pm` | Product decisions, strategy, trade-offs |
-| `dev` | Technical complexity, implementation effort |
-| `rv` | Code review, docs quality, inconsistency detection |
-| `plan` | Architecture planning, scope definition |
-| `build` | Implementation details, execution |
-
-### Multi-round strategy
-
-For complex topics, structure rounds progressively:
-
-1. **Round 1:** Explore — each agent lists their perspective
-2. **Round 2:** Challenge — agents critique each other's positions
-3. **Round 3+:** Converge — propose concrete solutions
-
-Include all round instructions in the `prompt` parameter — all agents see the full agenda.
-
-### Extend mode
-
-- Use the session ID from the S1 noReply message
-- Original topic is preserved; new prompt becomes the continuation
-- Agents must be the same as the original debate
-- Continue an extend for iterative refinement
-
-## Agent colors (recommended)
-
-```json
-{
-  "agent": {
-    "pm":   { "color": "#3498db" },
-    "dev":  { "color": "#2ecc71" },
-    "rv":   { "color": "#e74c3c" },
-    "plan": { "color": "#f39c12" },
-    "build": { "color": "#9b59b6" }
-  }
-}
-```
-
-## Documentation
-
-- [docs/SPEC.md](./docs/SPEC.md) — Full technical specification
-
-## Requirements
-
-- OpenCode (latest version)
-- No external dependencies
-
-## License
-
-MIT
+# opencode-roundtable
+
+OpenCode plugin that orchestrates **multi-agent round-robin debates**.
+Agents with different personalities debate a topic turn by turn, sharing
+context while keeping their own system prompts and tools.
+
+A built-in observer automatically consolidates every debate into an
+executive summary.
+
+## Installation
+
+### npm (recommended)
+
+```json
+{
+  "plugin": ["@rrr2010/opencode-roundtable@latest"]
+}
+```
+
+OpenCode auto-installs npm plugins on startup. No manual copy needed.
+
+### Local (dev)
+
+```bash
+git clone https://github.com/opencode-ai/roundtable
+cd roundtable
+bun run build
+npm link
+```
+
+Then add `"@rrr2010/opencode-roundtable"` to your opencode.json `plugin` array.
+
+## Features
+
+- **Round-robin debate** — agents speak in sequence, each seeing the full discussion history
+- **Shared context** — tool outputs and discoveries are visible to all participants
+- **Built-in observer** — automatically consolidates the debate into an executive summary (overridable with a specific agent)
+- **Isolated session** — the debate runs in a child session, keeping the main session clean
+- **File persistence** — state stored on disk, survives restarts
+- **Extend mode** — continue a concluded roundtable with more rounds or a new topic
+- **Agent discovery** — `available_agents` tool helps the orchestrator know which agents exist
+- **Active roundtables** — `active_roundtables` tool lists current debates with status
+- **TUI plugin** — badge `[RT]`, `← Back` link, `/roundtables` command
+- **Auto-navigate** — optional auto-navigation between sessions on create/conclude
+- **Parallel roundtables** — multiple independent debates can run simultaneously
+- **User intervention** — the human can jump into the debate at any time
+- **Loop detection** — Jaccard bigram similarity detects agent impasses early
+
+## Tool API
+
+### `roundtable()`
+
+```typescript
+roundtable({
+  agents?: string[],    // Names in speaking order (min 2). Required for new debates.
+  prompt: string,       // Topic or challenge. For multi-round, include per-round instructions.
+  rounds?: number,      // Complete rounds (default: 1, max: 50)
+  observer?: string,    // Agent for final consolidation (default: built-in)
+  sessionID?: string,   // ses_xxxx — pass to extend a concluded debate
+  title?: string,       // Custom title (default: auto-generated from prompt)
+  observerPrompt?: string, // Override the observer consolidation prompt (e.g., "Save a detailed report to report.md")
+})
+```
+
+**Returns:** `{ sessionID: string, summary: string }` after the debate concludes.
+
+**Side effect:** injects system-level prompts into each agent's context during
+the debate (role-setting, topic, turn routing, and lifecycle signals).
+
+### `available_agents()`
+
+```typescript
+available_agents()
+```
+
+**Returns:** `"Available agents: pm, dev, rv, ..."` — a formatted string of agent names.
+
+### `active_roundtables()`
+
+```typescript
+active_roundtables()
+```
+
+**Returns:** clickable session listings with status, e.g.:
+```
+Active roundtables:
+- #ses_xxx · pm→dev→rv (R1/2) · debating
+- #ses_yyy · pm→dev (R2/2) · consolidating
+```
+
+## Usage Examples
+
+### Basic — one round, built-in observer
+
+```typescript
+roundtable({
+  agents: ["pm", "dev"],
+  prompt: "What architecture should we use?",
+})
+```
+
+### Multi-round with per-round instructions
+
+```typescript
+roundtable({
+  agents: ["pm", "dev"],
+  prompt: "Round 1: list pros. Round 2: list cons. Round 3: propose an implementation plan.",
+  rounds: 3,
+})
+```
+
+### Explicit observer
+
+```typescript
+roundtable({
+  agents: ["pm", "dev"],
+  prompt: "Should we migrate to microservices?",
+  rounds: 2,
+  observer: "rv",
+})
+```
+
+### Extend a concluded debate
+
+```typescript
+roundtable({
+  sessionID: "ses_abc123",
+  rounds: 2,
+  prompt: "Dive deeper into operational costs",
+})
+```
+
+The session ID is shown in the S1 noReply message when the roundtable
+starts — check S1 context to find it.
+
+### Discover agents first
+
+```typescript
+const agents = available_agents()
+// agents => "Available agents: pm, dev, rv, build, plan"
+roundtable({
+  agents: ["pm", "dev"],
+  prompt: "...",
+})
+```
+
+### List active roundtables
+
+```typescript
+const active = active_roundtables()
+// active => "Active roundtables:\n- #ses_xxx · pm→dev (R1/2) · debating"
+```
+
+## Configuration
+
+Place `~/.config/opencode/roundtable.json` to override defaults:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/opencode-ai/roundtable/main/docs/roundtable.schema.json",
+  "defaultTimeoutMs": 300000,
+  "loopSimilarityThreshold": 0.85,
+  "toolOutputPreviewMax": 500,
+  "maxRounds": 10,
+  "defaultObserverPrompt": "You are an impartial roundtable observer...",
+  "navigation": "link"
+}
+```
+
+If the file doesn't exist, it's created automatically with defaults.
+
+### Navigation modes
+
+| Value | Behavior |
+|-------|----------|
+| `"link"` (default) | No auto-navigation. Relies on native `#ses_xxx` link rendering |
+| `"auto"` | Auto-navigates S1→S2 on create, S2→S1 on conclude |
+| `"none"` | No automatic navigation |
+
+### TUI Features
+
+The plugin registers a TUI component that provides:
+
+- **`[RT]` badge** — shown in the sidebar for roundtable sessions
+- **`← Back` link** — clickable link on child sessions, navigates to parent
+- **`/roundtables` command** — slash command opens a dialog with clickable session list
+
+## Tips
+
+### Agent selection
+
+Choose agents whose expertise matches the topic:
+
+| Agent | Best for |
+|-------|----------|
+| `pm` | Product decisions, strategy, trade-offs |
+| `dev` | Technical complexity, implementation effort |
+| `rv` | Code review, docs quality, inconsistency detection |
+| `plan` | Architecture planning, scope definition |
+| `build` | Implementation details, execution |
+
+### Multi-round strategy
+
+For complex topics, structure rounds progressively:
+
+1. **Round 1:** Explore — each agent lists their perspective
+2. **Round 2:** Challenge — agents critique each other's positions
+3. **Round 3+:** Converge — propose concrete solutions
+
+Include all round instructions in the `prompt` parameter — all agents see the full agenda.
+
+### Extend mode
+
+- Use the session ID from the S1 noReply message when the roundtable starts
+- Original topic is preserved; new prompt becomes the continuation
+- Agents must be the same as the original debate (validated)
+- Continue an extend for iterative refinement
+
+## Agent colors (recommended)
+
+```json
+{
+  "agent": {
+    "pm":   { "color": "#3498db" },
+    "dev":  { "color": "#2ecc71" },
+    "rv":   { "color": "#e74c3c" },
+    "plan": { "color": "#f39c12" },
+    "build": { "color": "#9b59b6" }
+  }
+}
+```
+
+## Documentation
+
+- [docs/SPEC.md](./docs/SPEC.md) — Full technical specification
+
+## Requirements
+
+- OpenCode (latest version)
+- No external dependencies
+
+## License
+
+MIT

package/dist/index.js

@@ -28,7 +28,8 @@ var DEFAULT_CONFIG = {
     "5. **Suggested next steps**"
   ].join(`
 `),
-  maxRounds: 10
+  maxRounds: 10,
+  navigation: "link"
 };
 var config = { ...DEFAULT_CONFIG };
 function getConfig() {
@@ -40,7 +41,8 @@ function validateConfig(raw) {
     loopSimilarityThreshold: typeof raw.loopSimilarityThreshold === "number" && raw.loopSimilarityThreshold >= 0 && raw.loopSimilarityThreshold <= 1 ? raw.loopSimilarityThreshold : DEFAULT_CONFIG.loopSimilarityThreshold,
     toolOutputPreviewMax: typeof raw.toolOutputPreviewMax === "number" && raw.toolOutputPreviewMax >= 100 ? raw.toolOutputPreviewMax : DEFAULT_CONFIG.toolOutputPreviewMax,
     defaultObserverPrompt: typeof raw.defaultObserverPrompt === "string" && raw.defaultObserverPrompt.length > 0 ? raw.defaultObserverPrompt : DEFAULT_CONFIG.defaultObserverPrompt,
-    maxRounds: typeof raw.maxRounds === "number" && raw.maxRounds >= 1 ? raw.maxRounds : DEFAULT_CONFIG.maxRounds
+    maxRounds: typeof raw.maxRounds === "number" && raw.maxRounds >= 1 ? raw.maxRounds : DEFAULT_CONFIG.maxRounds,
+    navigation: raw.navigation === "selectSession" || raw.navigation === "none" || raw.navigation === "auto" ? raw.navigation : DEFAULT_CONFIG.navigation
   };
 }
 async function loadConfig(ctx) {
@@ -335,6 +337,23 @@ Continuation: ${extendPrompt}`;
   ].join(`
 `);
 }
+async function navigateToSession(ctx, targetID, _parentID) {
+  try {
+    if (typeof ctx.client.tui.selectSession === "function") {
+      await ctx.client.tui.selectSession({ sessionID: targetID });
+      return true;
+    }
+    await ctx.client.tui.publish({
+      body: {
+        type: "tui.session.select",
+        properties: { sessionID: targetID }
+      }
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
 async function scanOrphanRoundtables(ctx) {
   const sessionIDs = await listStateFiles();
   let loaded = 0;
@@ -380,11 +399,11 @@ function buildAgentPrompt(state, agent) {
 `);
 }
 function buildObserverPrompt(state, observer) {
-  const observerPrompt = getConfig().defaultObserverPrompt;
+  const observerPrompt = state.observerPrompt ?? getConfig().defaultObserverPrompt;
   if (observer === "built-in")
     return observerPrompt;
   return `You are an impartial roundtable observer.
-` + `Your role: ${observer}. Provide an executive summary of the debate.
+` + `Your role: ${observer}.
 
 ` + observerPrompt;
 }
@@ -393,7 +412,10 @@ function buildObserverPrompt(state, observer) {
 async function startNewRoundtable(ctx, args, toolCtx) {
   const agents = args.agents;
   const newSession = await ctx.client.session.create({
-    body: { title: generateDefaultTitle({ ...args, agents }) }
+    body: {
+      title: generateDefaultTitle({ ...args, agents }),
+      parentID: toolCtx.sessionID
+    }
   });
   const sessionID = newSession.data.id;
   const parentSessionID = toolCtx.sessionID;
@@ -411,7 +433,8 @@ async function startNewRoundtable(ctx, args, toolCtx) {
     errors: [],
     createdAt: Date.now(),
     currentGeneration: 0,
-    userInterjections: []
+    userInterjections: [],
+    observerPrompt: args.observerPrompt
   };
   states.set(sessionID, state);
   try {
@@ -423,10 +446,20 @@ async function startNewRoundtable(ctx, args, toolCtx) {
         noReply: true,
         parts: [{
           type: "text",
-          text: `The roundtable has started (agents: ${agents.join(", ")}, ${args.rounds} round(s)). To extend it later, use the tool roundtable({sessionID: "${sessionID}", rounds: N, prompt: "..."})`
+          text: `⚙ Roundtable started — #${sessionID} • ${agents.join(" → ")} • ${args.rounds} round(s)`
         }]
       }
     });
+    await ctx.client.session.prompt({
+      path: { id: sessionID },
+      body: {
+        noReply: true,
+        parts: [{ type: "text", text: `⚙ Parent: #${parentSessionID}` }]
+      }
+    });
+    if (getConfig().navigation === "auto") {
+      await navigateToSession(ctx, sessionID, parentSessionID);
+    }
     await ctx.client.tui.showToast({
       body: {
         message: `Roundtable started in #${sessionID} (${agents.join(" → ")} · ${args.rounds} round(s))`,
@@ -484,10 +517,13 @@ async function sendToAgent(ctx, state) {
   }
 }
 async function updateSessionTitle(ctx, state) {
-  const summary = state.prompt.length > 60 ? state.prompt.slice(0, 57) + "..." : state.prompt;
+  const summary = state.prompt.length > 40 ? state.prompt.slice(0, 37) + "..." : state.prompt;
+  const agentList = state.agents.join("→");
+  const roundInfo = `R${state.currentRound + 1}/${state.totalRounds}`;
+  const title = `⚡ "${summary}" · ${agentList} (${roundInfo} · ↑ #${state.parentSessionID})`;
   await ctx.client.session.update({
     path: { id: state.sessionID },
-    body: { title: `(Roundtable) - ${summary}` }
+    body: { title }
   });
 }
 async function sendObserverPrompt(ctx, state) {
@@ -533,14 +569,17 @@ async function finalizeRoundtable(ctx, state) {
       pendingResults.delete(sessionID);
     }
     await injectRoundtableDelimiter(ctx, sessionID);
-    const shortPrompt = state.prompt.length > 50 ? state.prompt.slice(0, 47) + "..." : state.prompt;
+    const shortPrompt = state.prompt.length > 40 ? state.prompt.slice(0, 37) + "..." : state.prompt;
     await ctx.client.session.update({
       path: { id: sessionID },
-      body: { title: `(Roundtable) - ${shortPrompt} · CONCLUDED` }
+      body: { title: `⚡ "${shortPrompt}" · ${state.agents.join("→")} ✓` }
     });
     try {
       await saveStateFile(state);
     } catch {}
+    if (getConfig().navigation === "auto") {
+      await navigateToSession(ctx, state.parentSessionID, sessionID);
+    }
     await ctx.client.tui.showToast({
       body: { message: "Roundtable concluded", variant: "success" }
     });
@@ -845,7 +884,8 @@ async function extendRoundtable(ctx, args, _toolCtx) {
     errors: [...originalState.errors],
     createdAt: Date.now(),
     currentGeneration: 0,
-    userInterjections: [...originalState.userInterjections ?? []]
+    userInterjections: [...originalState.userInterjections ?? []],
+    observerPrompt: args.observerPrompt ?? originalState.observerPrompt
   };
   states.set(sessionID, newState);
   try {
@@ -861,7 +901,7 @@ async function extendRoundtable(ctx, args, _toolCtx) {
         noReply: true,
         parts: [{
           type: "text",
-          text: `The roundtable has been extended (${args.rounds} more round(s)). To extend again, use the tool roundtable({sessionID: "${sessionID}", rounds: N, prompt: "..."})`
+          text: `⚙ Roundtable extended — #${sessionID} • +${args.rounds} round(s)`
         }]
       }
     });
@@ -945,7 +985,8 @@ var RoundtablePlugin = async (ctx) => {
           rounds: tool.schema.number().min(1).max(50).describe("Number of complete rounds (each round = all agents speak once). " + "Default: 1. Max: 50. For complex topics with 2+ rounds, include per-round focus " + "instructions in the prompt parameter so all agents see the agenda."),
           observer: tool.schema.string().optional().describe("Agent name for final consolidation. The observer does not debate — it " + "summarizes after all rounds. Omit to use the built-in observer."),
           sessionID: tool.schema.string().optional().describe("Session ID (format: ses_xxxx) from a previous roundtable call to " + "continue a concluded debate. Omit this parameter and pass agents + " + "prompt to start a fresh debate."),
-          title: tool.schema.string().optional().describe("Custom title for the session (max 200 chars). If omitted, auto-generated " + 'as "(Roundtable) - {first 80 chars of prompt, truncated at word boundary}".')
+          title: tool.schema.string().optional().describe("Custom title for the session (max 200 chars). If omitted, auto-generated " + 'as "(Roundtable) - {first 80 chars of prompt, truncated at word boundary}".'),
+          observerPrompt: tool.schema.string().optional().describe("Override the default observer consolidation prompt. Use this to control " + "the format and focus of the final summary — e.g., ask the observer to " + "save a detailed report to file, focus on technical decisions only, " + "output as JSON, extract action items, etc. " + "If omitted, the default observer prompt is used (executive summary).")
         },
         async execute(args, toolCtx) {
           try {
@@ -1002,6 +1043,22 @@ var RoundtablePlugin = async (ctx) => {
             return "Error: Could not fetch agent list. The server might not be ready.";
           }
         }
+      }),
+      active_roundtables: tool({
+        description: "Lists all active roundtables with their status. " + "Each entry shows session ID, agents, current round, and phase. " + "Returns clickable session IDs that can be used to navigate.",
+        args: {},
+        async execute() {
+          const active = [];
+          for (const [sid, s] of states) {
+            const status = s.phase === "active" ? "debating" : s.phase === "observing" ? "consolidating" : s.phase === "done" ? "concluded" : s.phase;
+            active.push(`- #${sid} · ${s.agents.join("→")} (R${s.currentRound + 1}/${s.totalRounds}) · ${status}`);
+          }
+          if (active.length === 0)
+            return "No active roundtables.";
+          return `Active roundtables:
+${active.join(`
+`)}`;
+        }
       })
     }
   };
@@ -1010,5 +1067,5 @@ export {
   RoundtablePlugin
 };
 
-//# debugId=BEEF18A38922C86164756E2164756E21
+//# debugId=C8BED17810CFAA4D64756E2164756E21
 //# sourceMappingURL=index.js.map