@hueyexe/opencode-ensemble 0.9.1 → 0.11.0

package/src/dashboard.ts

@@ -0,0 +1,166 @@
+import type { Database } from "bun:sqlite"
+import { DASHBOARD_HEAD } from "./dashboard-html"
+import { DASHBOARD_JS_PART1 } from "./dashboard-js-part1"
+import { DASHBOARD_JS_PART2 } from "./dashboard-js-part2"
+import { DASHBOARD_JS_PART3 } from "./dashboard-js-part3"
+import { log } from "./log"
+
+/** Assemble the full dashboard HTML from parts. */
+const DASHBOARD_HTML = DASHBOARD_HEAD + "\n<script>" + DASHBOARD_JS_PART1 + DASHBOARD_JS_PART2 + DASHBOARD_JS_PART3 + "<\/script>\n</body></html>"
+
+interface TeamRow {
+  id: string
+  name: string
+  status: string
+  lead_agent: string | null
+  time_created: number
+  time_updated: number
+}
+
+interface MemberRow {
+  name: string
+  agent: string
+  status: string
+  execution_status: string
+  worktree_branch: string | null
+  prompt: string | null
+  model: string | null
+  plan_approval: string
+  time_created: number
+  time_updated: number
+}
+
+interface TaskRow {
+  id: string
+  content: string
+  status: string
+  priority: string
+  assignee: string | null
+  depends_on: string | null
+  time_created: number
+  time_updated: number
+}
+
+interface MessageRow {
+  id: string
+  from_name: string
+  to_name: string | null
+  content: string
+  delivered: number
+  read: number
+  time_created: number
+}
+
+function jsonResponse(data: unknown, status = 200): Response {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" },
+  })
+}
+
+function buildState(db: Database): { teams: unknown[] } {
+  const teams = db.query("SELECT id, name, status, lead_agent, time_created, time_updated FROM team ORDER BY time_created DESC").all() as TeamRow[]
+  const memberStmt = db.query("SELECT name, agent, status, execution_status, worktree_branch, prompt, model, plan_approval, time_created, time_updated FROM team_member WHERE team_id = ?")
+  const taskStmt = db.query("SELECT id, content, status, priority, assignee, depends_on, time_created, time_updated FROM team_task WHERE team_id = ?")
+  const msgStmt = db.query("SELECT id, from_name, to_name, content, delivered, read, time_created FROM team_message WHERE team_id = ? ORDER BY time_created DESC LIMIT 50")
+
+  return {
+    teams: teams.map((t) => ({
+      id: t.id,
+      name: t.name,
+      status: t.status,
+      leadAgent: t.lead_agent,
+      timeCreated: t.time_created,
+      timeUpdated: t.time_updated,
+      members: (memberStmt.all(t.id) as MemberRow[]).map((m) => ({
+        name: m.name,
+        agent: m.agent,
+        status: m.status,
+        executionStatus: m.execution_status,
+        worktreeBranch: m.worktree_branch,
+        prompt: m.prompt,
+        model: m.model,
+        planApproval: m.plan_approval,
+        timeCreated: m.time_created,
+        timeUpdated: m.time_updated,
+      })),
+      tasks: (taskStmt.all(t.id) as TaskRow[]).map((tk) => ({
+        id: tk.id,
+        content: tk.content,
+        status: tk.status,
+        priority: tk.priority,
+        assignee: tk.assignee,
+        dependsOn: tk.depends_on,
+        timeCreated: tk.time_created,
+        timeUpdated: tk.time_updated,
+      })),
+      messages: (msgStmt.all(t.id) as MessageRow[]).map((msg) => ({
+        id: msg.id,
+        fromName: msg.from_name,
+        toName: msg.to_name,
+        content: msg.content,
+        delivered: msg.delivered === 1,
+        read: msg.read === 1,
+        timeCreated: msg.time_created,
+      })),
+    })),
+  }
+}
+
+/**
+ * Start the dashboard HTTP server.
+ * Serves a JSON API for team state and the dashboard HTML.
+ * Singleton: if the port is already in use by another ensemble instance, skips silently.
+ * Returns the server instance, or null if skipped.
+ */
+export async function startDashboard(db: Database, port: number): Promise<ReturnType<typeof Bun.serve> | null> {
+  try {
+    const server = Bun.serve({
+      port,
+      fetch(req) {
+        const url = new URL(req.url)
+
+        if (url.pathname === "/api/health") {
+          return jsonResponse({ ensemble: true, pid: process.pid })
+        }
+
+        if (url.pathname === "/api/state") {
+          return jsonResponse(buildState(db))
+        }
+
+        if (url.pathname === "/") {
+          return new Response(DASHBOARD_HTML, {
+            headers: { "Content-Type": "text/html" },
+          })
+        }
+
+        return new Response("Not Found", { status: 404 })
+      },
+    })
+    log(`dashboard:started port=${port} url=http://localhost:${port}`)
+    return server
+  } catch (err) {
+    if (err && typeof err === "object" && "code" in err && err.code === "EADDRINUSE") {
+      try {
+        const res = await fetch(`http://localhost:${port}/api/health`)
+        const data = await res.json() as { ensemble?: boolean; pid?: number }
+        if (data.ensemble && data.pid) {
+          // Check if the other process is still alive
+          let alive = false
+          try { process.kill(data.pid, 0); alive = true } catch { /* process is dead */ }
+          if (alive && data.pid !== process.pid) {
+            log(`dashboard:already-running port=${port} pid=${data.pid}`)
+            return null
+          }
+          // Stale server from a dead process — warn the user
+          log(`dashboard:stale-server port=${port} stale-pid=${data.pid} — run: kill -9 ${data.pid} || lsof -ti:${port} | xargs kill -9`)
+          return null
+        }
+      } catch { /* health check failed — port held by something else */ }
+      log(`dashboard:port-in-use port=${port} (not an ensemble instance)`)
+      return null
+    }
+    log(`dashboard:failed err=${err instanceof Error ? err.message : String(err)}`)
+    return null
+  }
+}

package/src/index.ts

@@ -15,6 +15,7 @@ import { log, initLog } from "./log"
 import { findTeamBySession } from "./types"
 import { loadConfig } from "./config"
 import { ProgressTracker } from "./progress"
+import { startDashboard } from "./dashboard"
 import { executeTeamCreate } from "./tools/team-create"
 import { executeTeamSpawn } from "./tools/team-spawn"
 import { executeTeamMessage } from "./tools/team-message"
@@ -93,6 +94,13 @@ const plugin: Plugin = async (input) => {
       log(`init:recover-branches:failed err=${err instanceof Error ? err.message : String(err)}`)
     })
     log("init:recovery:done")
+
+    // Start dashboard server (main instance only, not worktree instances)
+    if (config.dashboardPort !== 0) {
+      startDashboard(db, config.dashboardPort).catch((err) => {
+        log(`init:dashboard:failed err=${err instanceof Error ? err.message : String(err)}`)
+      })
+    }
   } else {
     log(`init:skip-recovery (worktree instance: ${input.directory})`)
   }
@@ -114,6 +122,8 @@ const plugin: Plugin = async (input) => {
     stallMinSteps: config.stallMinSteps,
     stallTokenThreshold: config.stallTokenThreshold,
     cwd: input.directory,
+    peerMessageLimit: config.peerMessageLimit,
+    peerMessageWindowMs: config.peerMessageWindowMs,
   })
   watchdog.start()
 
@@ -198,6 +208,29 @@ const plugin: Plugin = async (input) => {
               })
             }
           }
+
+          // Also flush peer messages for teammates that just went idle
+          // Only flush messages older than 5s to avoid double-delivery with the direct promptAsync path
+          const member = db.query(
+            `SELECT tm.team_id, tm.name FROM team_member tm
+             JOIN team t ON tm.team_id = t.id
+             WHERE tm.session_id = ? AND t.status = 'active'`
+          ).get(sessionID) as { team_id: string; name: string } | null
+          if (member) {
+            const staleThreshold = Date.now() - 5000
+            const peerMsgs = db.query(
+              "SELECT COUNT(*) as c FROM team_message WHERE team_id = ? AND to_name = ? AND delivered = 0 AND time_created < ?"
+            ).get(member.team_id, member.name, staleThreshold) as { c: number }
+            if (peerMsgs.c > 0) {
+              log(`wake-peer: ${member.name} has ${peerMsgs.c} pending peer messages`)
+              client.session.promptAsync({
+                sessionID,
+                parts: [{ type: "text", text: `[System: ${peerMsgs.c} new message(s) from teammates]` }],
+              }).catch((err) => {
+                log(`wake-peer:failed err=${err instanceof Error ? err.message : String(err)}`)
+              })
+            }
+          }
         }
       }
 
@@ -317,6 +350,8 @@ const plugin: Plugin = async (input) => {
           const result = await executeTeamMessage(deps, args, ctx.sessionID)
           // Track message activity for stall detection
           progressTracker.recordMessage(ctx.sessionID)
+          // Track peer messages for chatty detection
+          if (args.to !== "lead") progressTracker.recordPeerMessage(ctx.sessionID)
           ctx.metadata({ title: `Message → ${args.to}` })
           return result
         },

package/src/progress.ts

@@ -12,7 +12,9 @@ export class ProgressTracker {
   private steps = new Map<string, StepRecord[]>()
   private lastMessageAt = new Map<string, number>()
   private lastTaskAt = new Map<string, number>()
+  private peerMessages = new Map<string, number[]>()
   private reported = new Set<string>()
+  private chattyReported = new Set<string>()
   private readonly maxSteps: number
 
   constructor(maxSteps = 10) {
@@ -27,6 +29,40 @@ export class ProgressTracker {
     this.steps.set(sessionId, records)
   }
 
+  /** Record a peer message (not to lead). Used for chatty detection. */
+  recordPeerMessage(sessionId: string): void {
+    const timestamps = this.peerMessages.get(sessionId) ?? []
+    timestamps.push(Date.now())
+    this.peerMessages.set(sessionId, timestamps)
+  }
+
+  /** Check if agent is chatty: more than `limit` peer messages within `windowMs`. */
+  isChatty(sessionId: string, limit: number, windowMs: number): boolean {
+    if (limit === 0) return false
+    const timestamps = this.peerMessages.get(sessionId)
+    if (!timestamps) return false
+    const cutoff = Date.now() - windowMs
+    const recent = timestamps.filter(t => t >= cutoff)
+    // Prune old timestamps
+    this.peerMessages.set(sessionId, recent)
+    return recent.length >= limit
+  }
+
+  /** Mark chatty as reported (avoid spam). */
+  markChattyReported(sessionId: string): void {
+    this.chattyReported.add(sessionId)
+  }
+
+  /** Check if chatty already reported. */
+  isChattyReported(sessionId: string): boolean {
+    return this.chattyReported.has(sessionId)
+  }
+
+  /** Clear chatty report (e.g., when agent sends result to lead). */
+  clearChattyReport(sessionId: string): void {
+    this.chattyReported.delete(sessionId)
+  }
+
   /** Record that this member sent a team_message. Clears stall report. */
   recordMessage(sessionId: string): void {
     this.lastMessageAt.set(sessionId, Date.now())
@@ -80,6 +116,8 @@ export class ProgressTracker {
     this.steps.delete(sessionId)
     this.lastMessageAt.delete(sessionId)
     this.lastTaskAt.delete(sessionId)
+    this.peerMessages.delete(sessionId)
     this.reported.delete(sessionId)
+    this.chattyReported.delete(sessionId)
   }
 }

package/src/system-prompt.ts

@@ -125,13 +125,39 @@ export function buildLeadSystemPrompt(db: Database, teamId: string): string {
 
 /**
  * Build the system prompt injected into a teammate's session.
- * Short role reminder with name, team name, and communication tool.
+ * Includes role reminder and delivers any pending peer messages.
  */
 export function buildTeammateSystemPrompt(db: Database, teamId: string, memberName: string): string {
   const team = db.query("SELECT name FROM team WHERE id = ?").get(teamId) as { name: string } | null
   if (!team) return ""
 
-  return `You are "${memberName}", a teammate in team "${team.name}". Use team_message to communicate. You MUST send your results to the lead via team_message before stopping.`
+  const lines = [
+    `You are "${memberName}", a teammate in team "${team.name}". Use team_message to communicate. You MUST send your results to the lead via team_message before stopping.`,
+  ]
+
+  // Deliver pending peer messages addressed to this teammate
+  const pendingMessages = db.query(
+    "SELECT id, from_name, content FROM team_message WHERE team_id = ? AND to_name = ? AND delivered = 0 ORDER BY time_created ASC"
+  ).all(teamId, memberName) as Array<{ id: string; from_name: string; content: string }>
+
+  if (pendingMessages.length > 0) {
+    lines.push("", "--- Messages for you ---")
+    const MAX_MSG = 500
+    for (const msg of pendingMessages) {
+      const parsed = parseTaskResult(msg.content)
+      if (parsed) {
+        lines.push(formatTaskResult(msg.from_name, { ...parsed, details: truncate(parsed.details, MAX_MSG) }))
+      } else if (msg.content.length > MAX_MSG) {
+        lines.push(`[From ${msg.from_name}]: ${msg.content.slice(0, MAX_MSG)}... (truncated)`)
+      } else {
+        lines.push(`[From ${msg.from_name}]: ${msg.content}`)
+      }
+      markDelivered(db, msg.id)
+    }
+    lines.push("--- End Messages ---")
+  }
+
+  return lines.join("\n")
 }
 
 /**

package/src/tools/team-message.ts

@@ -18,6 +18,22 @@ export async function executeTeamMessage(
   const senderName = teamInfo.role === "lead" ? "lead" : (teamInfo.memberName ?? "unknown")
 
   const recipientSessionId = resolveRecipientSession(deps.db, deps.registry, teamInfo.teamId, args.to)
+
+  // If recipient not found, store the message for later delivery (they may not be spawned yet)
+  // Reject approve/reject flags for unspawned recipients — plan approval requires the member to exist
+  if (!recipientSessionId && args.to !== "lead") {
+    if (args.approve || args.reject) {
+      throw new Error(`Cannot approve/reject plan for "${args.to}" — they haven't been spawned yet.`)
+    }
+    sendMessage(deps.db, {
+      teamId: teamInfo.teamId,
+      from: senderName,
+      to: args.to,
+      content: args.text,
+    })
+    log(`team_message:queued from=${senderName} to=${args.to} (recipient not yet spawned)`)
+    return `Message queued for ${args.to} — they haven't been spawned yet. It will be delivered when they join the team.`
+  }
   if (!recipientSessionId) throw new Error(`Recipient "${args.to}" not found in team "${teamInfo.teamName}"`)
 
   // Handle plan approval/rejection

package/src/tools/team-spawn.ts

@@ -253,6 +253,19 @@ export async function executeTeamSpawn(
     )
   }
 
+  // Collaboration guidance for peer-to-peer communication
+  if (otherMembers.length > 0) {
+    context.push(
+      "",
+      "Collaboration:",
+      "- Check team_tasks_list to see what other teammates are working on.",
+      "- If you need information another teammate has, message them directly via team_message.",
+      "- If you discover something relevant to another teammate's task, share it with them.",
+      "- Use team_broadcast for updates that affect the whole team.",
+      "- Keep peer messages focused and actionable — coordinate, don't chat.",
+    )
+  }
+
   context.push("", "When you finish your task:")
   if (!isReadOnly && worktreeBranch) {
     context.push(`1. Commit your changes: git add -A && git commit -m "your summary"`)

package/src/watchdog.ts

@@ -24,6 +24,10 @@ interface WatchdogOpts {
   stallTokenThreshold?: number
   /** Project directory for git operations. */
   cwd?: string
+  /** Max peer messages per agent per window before nudge. 0 disables. */
+  peerMessageLimit?: number
+  /** Time window for peer message rate limiting in ms. */
+  peerMessageWindowMs?: number
 }
 
 /**
@@ -41,6 +45,8 @@ export class Watchdog {
   private readonly stallMinSteps: number
   private readonly stallTokenThreshold: number
   private readonly cwd?: string
+  private readonly peerMessageLimit: number
+  private readonly peerMessageWindowMs: number
   private timer: ReturnType<typeof setInterval> | undefined
 
   constructor(opts: WatchdogOpts) {
@@ -54,6 +60,8 @@ export class Watchdog {
     this.stallMinSteps = opts.stallMinSteps ?? 3
     this.stallTokenThreshold = opts.stallTokenThreshold ?? 500
     this.cwd = opts.cwd
+    this.peerMessageLimit = opts.peerMessageLimit ?? 0
+    this.peerMessageWindowMs = opts.peerMessageWindowMs ?? 300_000
   }
 
   private static STALE_THRESHOLD_MS = Number(process.env.STALE_WORKTREE_THRESHOLD_MS) || 300_000
@@ -133,10 +141,46 @@ export class Watchdog {
     }
   }
 
+  /** Check for chatty agents sending too many peer messages. */
+  async checkChatty(): Promise<void> {
+    if (!this.progressTracker || this.peerMessageLimit === 0) return
+
+    const busy = this.db.query(
+      `SELECT tm.team_id, tm.name, tm.session_id
+       FROM team_member tm
+       JOIN team t ON tm.team_id = t.id
+       WHERE t.status = 'active' AND tm.status = 'busy'`
+    ).all() as Array<{ team_id: string; name: string; session_id: string }>
+
+    for (const member of busy) {
+      if (this.progressTracker.isChattyReported(member.session_id)) continue
+      if (!this.progressTracker.isChatty(member.session_id, this.peerMessageLimit, this.peerMessageWindowMs)) continue
+
+      this.progressTracker.markChattyReported(member.session_id)
+
+      // Nudge the agent
+      this.client.session.promptAsync({
+        sessionID: member.session_id,
+        parts: [{ type: "text", text: "[System]: You've sent several messages to teammates. Focus on completing your task and send your results to the lead via team_message." }],
+      }).catch(() => { /* best effort */ })
+
+      // Notify the lead
+      sendMessage(this.db, {
+        teamId: member.team_id,
+        from: "system",
+        to: "lead",
+        content: `Agent "${member.name}" is sending many peer messages and may be over-coordinating. Consider checking on them.`,
+      })
+
+      log(`watchdog:chatty member=${member.name} limit=${this.peerMessageLimit}`)
+    }
+  }
+
   /** Run a single check for stale busy members. */
   async check(): Promise<void> {
     await this.cleanupStaleWorktrees()
     await this.checkStalled()
+    await this.checkChatty()
     if (this.ttlMs === 0) return
 
     const cutoff = Date.now() - this.ttlMs