@hueyexe/opencode-ensemble 0.17.0 → 0.20.0

package/package.json

@@ -1,9 +1,14 @@
 {
   "name": "@hueyexe/opencode-ensemble",
-  "version": "0.17.0",
+  "version": "0.20.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.4"
   },
   "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/tool-arg-hint.ts

@@ -0,0 +1,71 @@
+/**
+ * Weak-model tool-argument fumble detection and error hints (issue #39).
+ *
+ * Some models trained on other harness conventions call OpenCode's built-in
+ * tools with aliased parameter names (e.g. `cmd` instead of the `shell`
+ * tool's `command`). OpenCode V2 rejects the call with a generic validation
+ * error that the model may fail to act on. This module detects that exact
+ * dead-call shape and produces an explicit hint appended to the error so
+ * the model can self-correct. Arguments are never rewritten — the model
+ * stays in the correction loop.
+ *
+ * V2 only: on V1, argument validation happens at the model-stream parse
+ * level, so tool hooks never see the failed call (see issue #39 triage).
+ */
+
+/**
+ * Canonical parameter plus the aliases weak models emit for it. Only the
+ * confirmed failure mode is listed; extend per-tool as reports come in.
+ */
+const ARG_ALIASES: Readonly<Record<string, { param: string; aliases: readonly string[] }>> = {
+  shell: { param: "command", aliases: ["cmd", "bash", "script"] },
+}
+
+/**
+ * Return the alias a weak model used instead of the tool's canonical
+ * parameter, or null when the input is not a recognized fumble. A fumble is
+ * only recognized when the canonical parameter is absent and a known alias
+ * is present as a non-empty string — i.e. only on calls that are already
+ * guaranteed to fail validation.
+ */
+export function detectArgFumble(tool: string, input: unknown): string | null {
+  const entry = ARG_ALIASES[tool]
+  if (!entry) return null
+  if (input === null || typeof input !== "object" || Array.isArray(input)) return null
+  const args = input as Record<string, unknown>
+  if (entry.param in args) return null
+  for (const alias of entry.aliases) {
+    const value = args[alias]
+    if (typeof value === "string" && value !== "") return alias
+  }
+  return null
+}
+
+/**
+ * Build the hint text for a fumbled tool call, or null when the input is
+ * not a recognized fumble.
+ */
+export function buildArgHint(tool: string, input: unknown): string | null {
+  const entry = ARG_ALIASES[tool]
+  if (!entry) return null
+  const alias = detectArgFumble(tool, input)
+  if (!alias) return null
+  return (
+    `Hint: the "${tool}" tool has no "${alias}" parameter. The correct parameter ` +
+    `name is "${entry.param}" — call the tool again with the same arguments, ` +
+    `moving the "${alias}" value into "${entry.param}".`
+  )
+}
+
+/**
+ * Append the fumble hint to a failed tool call's error message in place.
+ * Returns true when the message was modified. Never throws — a malformed
+ * error or input leaves the original message untouched.
+ */
+export function enrichToolError(tool: string, error: { message?: unknown }, input: unknown): boolean {
+  if (typeof error.message !== "string") return false
+  const hint = buildArgHint(tool, input)
+  if (!hint) return false
+  error.message = `${error.message}\n\n${hint}`
+  return true
+}

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

@@ -87,7 +87,11 @@ export async function executeTeamSpawn(
     .get(teamInfo.teamId, args.name)
   if (existing) throw new Error(`Teammate "${args.name}" already exists in team "${teamInfo.teamName}"`)
 
-  const isReadOnly = agent === "plan" || agent === "explore"
+  // Prefer the agent's own permission rules (V2) so any agent that denies
+  // edits — not only the built-in plan/explore — is treated as read-only and
+  // never gets a worktree or a shell allow. Fall back to the built-in names.
+  const isReadOnly = (await deps.client.agent?.readOnly(agent).catch(() => undefined))
+    ?? (agent === "plan" || agent === "explore")
   const useWorktree = args.worktree !== false && !isReadOnly && !isWorktreeDirectory(deps.directory)
   const usePlanApproval = args.plan_approval === true
 
@@ -147,12 +151,32 @@ 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) {
     permission.push(
       { permission: "edit", pattern: `${worktreeDir}/**`, action: "allow" },
+      // V2 checks files inside the session's location as paths relative to
+      // it. session.create above binds the location to the worktree (via
+      // workspaceID, or directory as fallback), so this rule scopes edits
+      // to the worktree. Files outside the worktree remain gated by
+      // external_directory.
+      { permission: "edit", pattern: "*", action: "allow" },
     )
     if (!isReadOnly) {
       permission.push({ permission: "bash", pattern: "*", action: "allow" })
@@ -170,6 +194,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
@@ -180,7 +210,14 @@ export async function executeTeamSpawn(
         parentID: sessionId,
         title: `${args.name} (@${agent} teammate)`,
         permission,
-        ...(workspaceId ? { workspaceID: workspaceId } : {}),
+        ...(workspaceId
+          ? { workspaceID: workspaceId }
+          // Workspace binding is preferred; when it is unavailable, bind the
+          // session to the worktree directory directly. Without a location,
+          // the teammate's location is the project root, edit paths are
+          // evaluated relative to it, and the `edit * allow` rule below
+          // would grant edits to the whole shared tree (PR #46 review).
+          : worktreeDir ? { directory: worktreeDir } : {}),
       }),
       getSpawnTimeout(), `session.create for "${args.name}"`
     )
@@ -425,6 +462,13 @@ export async function executeTeamSpawn(
   })
 
   const branchInfo = worktreeBranch ? ` (branch: ${worktreeBranch})` : ""
+  // Isolation is a claim the lead relies on, so say plainly when it did not
+  // complete. The toast alone left "spawned" as the only signal (issue #40).
+  // Covers both failure modes: no worktree at all (shared directory) or a
+  // worktree whose branch could not be created (unmergeable detached HEAD).
+  const isolationInfo = useWorktree && !worktreeBranch
+    ? ` (WARNING: worktree isolation did not complete — ${args.name} may share your working directory or lack a mergeable branch; edits can collide and team_merge may fail)`
+    : ""
   const planInfo = usePlanApproval ? " [plan mode — will send plan for approval]" : ""
   const claimInfo = claimedTaskContent
     ? ` (claimed task: ${args.claim_task})`
@@ -432,5 +476,5 @@ export async function executeTeamSpawn(
   // Reset circuit breaker on success
   spawnFailures.delete(teamInfo.teamId)
   log(`spawn:done name=${args.name} sessionId=${childSessionId}`)
-  return `Teammate "${args.name}" spawned (agent: ${agent})${branchInfo}${planInfo}${claimInfo}. They are working on: ${args.prompt.slice(0, 120)}${args.prompt.length > 120 ? "..." : ""}`
+  return `Teammate "${args.name}" spawned (agent: ${agent})${branchInfo}${isolationInfo}${planInfo}${claimInfo}. They are working on: ${args.prompt.slice(0, 120)}${args.prompt.length > 120 ? "..." : ""}`
 }

package/src/tools/team-tasks-add.ts

@@ -19,6 +19,23 @@ export async function executeTeamTasksAdd(
 ): Promise<string> {
   const teamInfo = requireTeamMember(deps, sessionId)
 
+  // Reject unknown dependency IDs before inserting anything: a task blocked on
+  // an ID that never existed can never unblock (issue #40). IDs are generated
+  // here, so new tasks can only depend on existing ones and no cycle can form.
+  const unknown = new Set<string>()
+  for (const task of args.tasks) {
+    for (const depId of task.depends_on ?? []) {
+      const exists = deps.db.query("SELECT 1 FROM team_task WHERE id = ? AND team_id = ?").get(depId, teamInfo.teamId)
+      if (!exists) unknown.add(depId)
+    }
+  }
+  if (unknown.size > 0) {
+    throw new Error(
+      `Unknown task ID${unknown.size > 1 ? "s" : ""} in depends_on: ${[...unknown].join(", ")}. ` +
+        "Use IDs from team_tasks_list, or add the prerequisite tasks first and reference the IDs they return.",
+    )
+  }
+
   const ids: string[] = []
   const now = Date.now()
 

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

@@ -35,6 +35,10 @@ export interface PermissionRule {
  * Makes mocking trivial in tests.
  */
 export interface PluginClient {
+  /** Optional agent introspection (V2). Undefined answers fall back to name checks. */
+  agent?: {
+    readOnly(agent: string): Promise<boolean | undefined>
+  }
   session: {
     create(options: {
       parentID?: string
@@ -50,6 +54,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 }> }>