@hueyexe/opencode-ensemble 0.17.0 → 0.18.0

package/package.json

@@ -1,9 +1,14 @@
 {
   "name": "@hueyexe/opencode-ensemble",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Agent teams for OpenCode — parallel agents with peer-to-peer communication, shared tasks, and coordinated execution",
   "module": "src/index.ts",
   "main": "dist/index.js",
+  "exports": {
+    ".": "./src/index.ts",
+    "./rpc": "./src/rpc.ts",
+    "./tui": "./src/tui.tsx"
+  },
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -30,6 +35,7 @@
     "lint": "bunx biome lint src/",
     "typecheck": "tsc --noEmit",
     "test": "bun test",
+    "eval:smoke": "bun eval/smoke.ts",
     "build": "bun build src/index.ts --outdir dist --target node",
     "prepublishOnly": "bun run typecheck && bun test && bun run build"
   },
@@ -39,13 +45,20 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.9",
-    "@types/bun": "latest"
+    "@opentui/core": "0.5.10",
+    "@opentui/solid": "0.5.10",
+    "@types/bun": "latest",
+    "solid-js": "1.9.0"
   },
   "peerDependencies": {
-    "typescript": "^5"
+    "typescript": "^5",
+    "@opentui/core": ">=0.5.10",
+    "@opentui/solid": ">=0.5.10",
+    "solid-js": ">=1.9.0"
   },
   "dependencies": {
     "@opencode-ai/plugin": "^1.17.18",
-    "@opencode-ai/sdk": "^1.17.18"
+    "@opencode-ai/sdk": "^1.17.18",
+    "@opencode/plugin": "2.0.3"
   }
-}
+}

package/src/index.ts

@@ -1,4 +1,6 @@
 import type { Plugin } from "@opencode-ai/plugin"
+import { Plugin as PluginV2 } from "@opencode/plugin"
+import { setupEnsemble, type V2SetupContext } from "./v2-setup"
 import { tool } from "@opencode-ai/plugin"
 import { OpencodeClient } from "@opencode-ai/sdk/v2"
 import path from "node:path"
@@ -656,10 +658,11 @@ const plugin: Plugin = async (input) => {
       }),
 
       team_view: tool({
-        description: "Navigate the TUI to a teammate's session so you can see what they are doing. " +
-          "Use the session picker (ctrl+p) to return to the lead session.",
+        description: "Resolve a teammate's session so the user can inspect it. Default reports the session ID + status without switching. " +
+          "Pass navigate: true ONLY when the user explicitly asked to view the teammate's session — it switches their client to it. Return via the session picker (ctrl+p).",
         args: {
           member: tool.schema.string().describe("Teammate name to view"),
+          navigate: tool.schema.boolean().default(false).describe("Switch the user's client to this session. Only when the user explicitly asked."),
         },
         async execute(args, ctx) {
           const result = await executeTeamView(deps, args, ctx.sessionID)
@@ -671,4 +674,24 @@ const plugin: Plugin = async (input) => {
   }
 }
 
-export default plugin
+/**
+ * Dual V1/V2 export (issue #36).
+ * - V2 reads `id` + `setup()` and ignores `server()`.
+ * - V1 (>=1.18.29) calls `server()` and ignores the V2 fields.
+ * The V2 setup body lands in later phases; the V1 implementation below is
+ * unchanged so current users keep working during the port.
+ */
+export default {
+  ...PluginV2.define({
+    id: "ensemble",
+    async setup(ctx) {
+      // Dual support (issue #36): V2 initializes here; the V1 server()
+      // below keeps serving V1 hosts. Tool registration lands next slice.
+      const handle = await setupEnsemble(ctx as unknown as V2SetupContext)
+      return () => {
+        void handle.dispose()
+      }
+    },
+  }),
+  server: plugin,
+}

package/src/log.ts

@@ -11,3 +11,12 @@ export function log(msg: string): void {
   if (!_client) return
   _client.app.log({ service: "ensemble", level: "info", message: msg }).catch(() => {})
 }
+
+/**
+ * V2 fallback logger. The V2 plugin context exposes no app.log, so server
+ * log lines go to stdout with a prefix (the host captures plugin stdout
+ * into its own log). Used only by V2 setup paths.
+ */
+export function vlog(msg: string): void {
+  console.log(`[ensemble] ${msg}`)
+}

package/src/notify.ts

@@ -116,10 +116,12 @@ export function notifyLead(
   if (!team?.lead_session_id) return id
 
   // Fire-and-forget wake — the system prompt transform delivers the actual
-  // content on the lead's next turn.
+  // content on the lead's next turn. Synthetic: renders as a persistent
+  // system entry, not a fake user turn.
   client.session.promptAsync({
     sessionID: team.lead_session_id,
     parts: [{ type: "text", text: "[System: New team message from system]" }],
+    synthetic: true,
   }).catch((err) => {
     log(`notifyLead:wake:failed team=${teamId} err=${err instanceof Error ? err.message : String(err)}`)
   })

package/src/rpc.ts

@@ -0,0 +1,99 @@
+import { Rpc } from "@opencode/plugin/rpc"
+
+/**
+ * RPC contract between the server plugin and terminal companions.
+ * Published as `./rpc` so companions import the shape without the
+ * implementation. Companion behavior (toasts, navigation) is enhancement
+ * only — every client works fully without it.
+ */
+export const EnsembleRpc = Rpc.define({
+  id: "ensemble",
+  methods: {
+    summary: {
+      input: {
+        type: "object",
+        properties: { team: { type: "string" } },
+        required: ["team"],
+        additionalProperties: false,
+      },
+      output: {
+        type: "object",
+        properties: { text: { type: "string" } },
+        required: ["text"],
+        additionalProperties: false,
+      },
+    },
+    teamContext: {
+      input: {
+        type: "object",
+        properties: { sessionID: { type: "string" } },
+        required: ["sessionID"],
+        additionalProperties: false,
+      },
+      output: {
+        type: "object",
+        properties: {
+          team: { type: ["string", "null"] },
+          members: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: { name: { type: "string" }, status: { type: "string" } },
+              required: ["name", "status"],
+              additionalProperties: false,
+            },
+          },
+          tasks: {
+            type: "object",
+            properties: {
+              pending: { type: "number" },
+              done: { type: "number" },
+            },
+            required: ["pending", "done"],
+            additionalProperties: false,
+          },
+        },
+        required: ["team", "members", "tasks"],
+        additionalProperties: false,
+      },
+    },
+  },
+  events: {
+    member: {
+      schema: {
+        type: "object",
+        properties: {
+          memberName: { type: "string" },
+          teamId: { type: "string" },
+          from: { type: "string" },
+          to: { type: "string" },
+        },
+        required: ["memberName", "teamId", "from", "to"],
+        additionalProperties: false,
+      },
+    },
+    notice: {
+      schema: {
+        type: "object",
+        properties: {
+          title: { type: "string" },
+          message: { type: "string" },
+          variant: { type: "string" },
+        },
+        required: ["message"],
+        additionalProperties: false,
+      },
+    },
+    view: {
+      schema: {
+        type: "object",
+        properties: {
+          sessionID: { type: "string" },
+          memberName: { type: "string" },
+        },
+        required: ["sessionID"],
+        additionalProperties: false,
+      },
+    },
+  },
+})

package/src/tools/team-message.ts

@@ -125,6 +125,7 @@ export async function executeTeamMessage(
     deps.client.session.promptAsync({
       sessionID: recipientSessionId,
       parts: [{ type: "text", text: `[System: New team message from ${senderName}]` }],
+      synthetic: true,
     }).catch((err) => {
       log(`team_message:wake-lead:failed from=${senderName} err=${err instanceof Error ? err.message : String(err)}`)
     })

package/src/tools/team-spawn.ts

@@ -147,7 +147,21 @@ export async function executeTeamSpawn(
   // Permission rules on session.create are the hard gate (server-enforced).
   // For read-only agents, deny write tools and explicitly allow team tools.
   // For all agents with worktrees, allowlist the worktree path for edit/bash.
-  const TEAM_TOOLS = ["team_message", "team_broadcast", "team_tasks_list", "team_tasks_add", "team_tasks_complete", "team_claim"] as const
+  // The 9 member-accessible tools per the documented tool table: the 6 worker
+  // tools plus the 3 inspection tools (team_results/team_status/team_view —
+  // any member). Caught live 2026-09-15: teammates could not read each
+  // other's messages because team_results was missing from this list.
+  const TEAM_TOOLS = [
+    "team_message",
+    "team_broadcast",
+    "team_tasks_list",
+    "team_tasks_add",
+    "team_tasks_complete",
+    "team_claim",
+    "team_results",
+    "team_status",
+    "team_view",
+  ] as const
   const permission: PermissionRule[] = []
 
   if (worktreeDir) {
@@ -170,6 +184,12 @@ export async function executeTeamSpawn(
     ...TEAM_TOOLS.map(t => ({ permission: t, pattern: "*", action: "allow" as const })),
   )
 
+  // Code Mode is the invocation path for plugin tools on V2 — without this,
+  // read-only agents (deny-all policies like explore's) cannot reach any
+  // team tool. Safe: nested calls inside execute still enforce their own
+  // permissions, so explore stays read-only.
+  permission.push({ permission: "execute", pattern: "*", action: "allow" })
+
   // Create child session — bind to workspace if available (server-enforced CWD isolation).
   // Falls back to no workspace binding if workspace.create failed.
   let childSessionId: string | undefined

package/src/tools/team-view.ts

@@ -2,12 +2,14 @@ import type { ToolDeps } from "../types"
 import { requireTeamMember } from "./shared"
 
 /**
- * Execute the team_view tool. Navigates the TUI to a teammate's session
- * so the user can see what they're doing.
+ * Execute the team_view tool. Resolves a teammate's session; navigates the
+ * TUI to it ONLY when navigate: true is passed — an agent must never hijack
+ * the user's client unprompted. Default behavior reports where the session
+ * is so the user can open it themselves (ctrl+p).
  */
 export async function executeTeamView(
   deps: ToolDeps,
-  args: { member: string },
+  args: { member: string; navigate?: boolean },
   sessionId: string,
 ): Promise<string> {
   const teamInfo = requireTeamMember(deps, sessionId)
@@ -16,9 +18,13 @@ export async function executeTeamView(
     .get(teamInfo.teamId, args.member) as { session_id: string; status: string; agent: string } | null
   if (!member) throw new Error(`Teammate "${args.member}" not found in team "${teamInfo.teamName}"`)
 
+  if (args.navigate !== true) {
+    return `${args.member}'s session: ${member.session_id} (status: ${member.status}, agent: ${member.agent}). Open it from the session picker (ctrl+p) — or ask to view it and I'll switch for you.`
+  }
+
   try {
     await deps.client.tui.selectSession({ sessionID: member.session_id })
-    return `Switched to ${args.member}'s session.`
+    return `Switched to ${args.member}'s session. Use the session picker (ctrl+p) to return.`
   } catch {
     return `Could not switch to ${args.member}'s session (${member.session_id}). The session may not be accessible from the TUI.`
   }

package/src/tui-view.ts

@@ -0,0 +1,50 @@
+/** Minimal member shape for sidebar rendering. */
+export interface SidebarMember {
+  name: string
+  status: string
+}
+
+/** Rendered sidebar model: counts plus one line per member. */
+export interface SidebarSummary {
+  team: string
+  working: number
+  idle: number
+  total: number
+  lines: string[]
+}
+
+/** Glyph per member status (paired with text elsewhere — never color-only). */
+function glyph(status: string): string {
+  switch (status) {
+    case "busy":
+      return "●"
+    case "ready":
+      return "○"
+    case "shutdown_requested":
+      return "◐"
+    case "shutdown":
+      return "■"
+    case "error":
+      return "✕"
+    default:
+      return "?"
+  }
+}
+
+/**
+ * Build the sidebar model for a team. Busy members count as working, ready
+ * as idle, terminal states (shutdown/error) as done.
+ */
+export function summarizeMembers(team: string, members: SidebarMember[]): SidebarSummary {
+  if (members.length === 0) {
+    return { team, working: 0, idle: 0, total: 0, lines: ["No teammates"] }
+  }
+  let working = 0
+  let idle = 0
+  const lines = members.map((member) => {
+    if (member.status === "busy") working += 1
+    else if (member.status === "ready") idle += 1
+    return `${glyph(member.status)} ${member.name} (${member.status})`
+  })
+  return { team, working, idle, total: members.length, lines }
+}

package/src/tui.tsx

@@ -0,0 +1,101 @@
+/** @jsxImportSource @opentui/solid */
+import "@opentui/solid"
+import { createSignal, onCleanup, onMount, Show } from "solid-js"
+import { Plugin } from "@opencode/plugin/tui"
+import { EnsembleRpc } from "./rpc"
+
+/** Team context shape from the server bridge. */
+interface TeamContextData {
+  team: string | null
+  members: Array<{ name: string; status: string }>
+  tasks: { pending: number; done: number }
+}
+
+/** Sidebar widget: team members with status plus task counts. */
+function TeamSidebar(props: { fetchContext: () => Promise<TeamContextData | null>; onEvent: (cb: () => void) => () => void }) {
+  const [state, setState] = createSignal<TeamContextData | null>(null)
+  const load = async (): Promise<void> => {
+    try {
+      setState(await props.fetchContext())
+    } catch {
+      // Server unreachable — keep the last known state.
+    }
+  }
+  onMount(() => {
+    void load()
+    const off = props.onEvent(() => void load())
+    onCleanup(off)
+    // Heartbeat: events alone go stale (cleanup emits nothing, events can be
+    // missed across reconnects). Re-fetch on a slow tick — local RPC read.
+    const tick = setInterval(() => void load(), 10_000)
+    onCleanup(() => clearInterval(tick))
+  })
+  return (
+    <Show when={state()?.team} fallback={<text>Ensemble: no active team</text>}>
+      <box flexDirection="column">
+        <text>Ensemble: {state()?.team}</text>
+        {(state()?.members ?? []).map((member) => (
+          <text>
+            {member.status === "busy" ? "●" : member.status === "ready" ? "○" : "■"} {member.name} ({member.status})
+          </text>
+        ))}
+        <text>
+          tasks: {(state()?.tasks.pending ?? 0)} open / {(state()?.tasks.done ?? 0)} done
+        </text>
+      </box>
+    </Show>
+  )
+}
+
+/**
+ * Terminal companion for opencode-ensemble (issue #36).
+ *
+ * Two persistent surfaces only — transient toasts were removed as noise
+ * (live state lives in the sidebar; events live in the transcript as
+ * synthetic system lines):
+ *   1. Sidebar widget: live member status + task counts.
+ *   2. Native agent switching: team_view with navigate: true (user opt-in
+ *      only — agents never hijack the client unprompted).
+ *
+ * Enhancement only: desktop, web, and companion-less terminals lose nothing
+ * functional — tools, approvals, model-context messages, and the dashboard
+ * all live server-side.
+ */
+export default Plugin.define({
+  id: "ensemble.tui",
+  setup(context) {
+    const rpc = context.client.rpc(EnsembleRpc)
+
+    // Native agent switching: team_view(navigate: true) emits "view";
+    // the companion navigates the TUI to the teammate session (ctrl+p to return).
+    const offView = rpc.events.on("view", (event) => {
+      const data = event.data as unknown as { sessionID: string }
+      if (!data.sessionID) return
+      if (context.ui.tabs.enabled()) {
+        void context.ui.tabs.focus(data.sessionID)
+      } else {
+        void context.ui.router.navigate({ type: "session", sessionID: data.sessionID })
+      }
+    })
+
+    const onEvent = (cb: () => void): (() => void) => rpc.events.on("member", cb)
+
+    const offSidebar = context.ui.slot({
+      append: "sidebar.content",
+      render: (panel: { sessionID?: string }) => (
+        <TeamSidebar
+          fetchContext={async () => {
+            if (!panel.sessionID) return null
+            return (await rpc.teamContext({ sessionID: panel.sessionID })) as TeamContextData
+          }}
+          onEvent={onEvent}
+        />
+      ),
+    })
+
+    return () => {
+      offView()
+      offSidebar()
+    }
+  },
+})

package/src/types.ts

@@ -50,6 +50,8 @@ export interface PluginClient {
       agent?: string
       tools?: Record<string, boolean>
       system?: string
+      /** V2: deliver as a synthetic (system) message instead of a user prompt. */
+      synthetic?: boolean
     }): Promise<unknown>
     abort(options: { sessionID: string }): Promise<unknown>
     status(): Promise<{ data?: Record<string, { type: string }> }>