@hueyexe/opencode-ensemble 0.17.0 → 0.18.0

package/src/v2-client.ts

@@ -0,0 +1,227 @@
+import type { PluginClient } from "./types"
+import { runCommand } from "./process"
+
+/** V2 plugin context subset Ensemble needs (structural, mock-friendly). */
+export interface V2Context {
+  session: {
+    create(input: Record<string, unknown>): Promise<{ id: string }>
+    prompt(input: Record<string, unknown>): Promise<unknown>
+    switchAgent(input: Record<string, unknown>): Promise<unknown>
+    switchModel(input: Record<string, unknown>): Promise<unknown>
+    interrupt(input: Record<string, unknown>): Promise<unknown>
+    get(input: Record<string, unknown>): Promise<unknown>
+    context(input: Record<string, unknown>): Promise<unknown[]>
+    active(): Promise<Record<string, { type: string }>>
+    synthetic(input: Record<string, unknown>): Promise<unknown>
+  }
+  worktree: {
+    create(input: Record<string, unknown>): Promise<{ directory: string }>
+    remove(input: Record<string, unknown>): Promise<unknown>
+    list(): Promise<Array<{ directory: string }>>
+    refresh(): Promise<unknown>
+  }
+  permission: {
+    rules(input: Record<string, unknown>): Promise<unknown>
+  }
+}
+
+/** Prefix marking a workspace id that is really a local directory (see below). */
+const DIR_WORKSPACE_PREFIX = "v2dir:"
+
+/** Injectable shell lookups (default to git; overridden in tests). */
+export interface V2ClientDeps {
+  /** Current branch checked out in a directory, or null when unknown. */
+  gitBranch?: (directory: string) => Promise<string | null>
+  /** Worktree directory currently on a branch, or null when none. */
+  gitDir?: (branch: string) => Promise<string | null>
+  /** RPC emitter for companion events (team_view navigation). */
+  rpcEmitter?: { events: { emit(name: string, data: unknown): Promise<unknown> } }
+}
+
+/** Current branch in a directory via git. */
+async function gitBranchDefault(directory: string): Promise<string | null> {
+  try {
+    const result = await runCommand(["git", "branch", "--show-current"], { cwd: directory })
+    const branch = result.stdout.trim()
+    return result.exitCode === 0 && branch ? branch : null
+  } catch {
+    return null
+  }
+}
+
+/** Concatenate the text parts of a promptAsync payload into one string. */
+function joinParts(parts: Array<{ type: "text"; text: string }>): string {
+  return parts
+    .filter((part) => part.type === "text")
+    .map((part) => part.text)
+    .join("\n")
+}
+
+/**
+ * Adapt a V2 plugin context to the shared PluginClient interface so all 14
+ * team tools run unchanged on V2 (DRY: one adapter, zero logic forks).
+ *
+ * Mapping notes (all spike-verified live against v2.0.3 unless marked OQ):
+ * - create: V1 `permission` rules become V2 `{action, resource, effect}`;
+ *   `workspaceID`/`directory` nest under `location`.
+ * - promptAsync: queue delivery wakes idle sessions; `agent` is applied via
+ *   switchAgent first (V2 binds the agent at create/admission, and the shared
+ *   create signature has no agent slot — only spawn passes one).
+ * - abort: interrupt. status: derived from the active set — sessions absent
+ *   from it read as idle, which matches the shutdown default (team-shutdown
+ *   treats unknown as idle). OQ-V2-status: if V2 ever reports non-running
+ *   states here, extend the mapping.
+ * - tui.*: no-op. Toasts and session-select move to the CLI (`./tui`) plugin
+ *   in a later phase — the server plugin must not depend on a TUI.
+ * - worktree.create: V2 reports only the directory, so the branch is read
+ *   back via git (falls back to the requested name). OQ-V2-branch.
+ * - worktree.list: V2 entries carry directory only; name is the basename
+ *   (recovery filters on the `ensemble-` prefix — a non-matching dir is
+ *   skipped, never wrongly deleted). reset has no production callers and
+ *   maps to refresh. OQ-V2-wtname.
+ * - workspace.*: V2 ctx has no workspace domain (workspaces are
+ *   provider-based). create bridges a branch to its worktree directory and
+ *   returns a `v2dir:<dir>` id; session.create routes that id to
+ *   location.directory, preserving worktree isolation with zero tool
+ *   changes. list returns [] and remove resolves — the DB workspace_id
+ *   column stays the source of truth and is still nulled by cleanup.
+ */
+export function createV2Client(ctx: V2Context, deps: V2ClientDeps = {}): PluginClient {
+  const gitBranch = deps.gitBranch ?? gitBranchDefault
+  return {
+    session: {
+      create: async (options) => {
+        const input: Record<string, unknown> = { title: options.title }
+        if (options.parentID) input["parentID"] = options.parentID
+        // V1 action names predate the V2 vocabulary: bash is now shell.
+        const V1_ACTION_MAP: Record<string, string> = { bash: "shell" }
+        const permissions = options.permission?.map((rule) => ({
+          action: V1_ACTION_MAP[rule.permission] ?? rule.permission,
+          resource: rule.pattern,
+          effect: rule.action,
+        }))
+        if (permissions) input["permissions"] = permissions
+        if (options.workspaceID ?? options.directory) {
+          if (options.workspaceID?.startsWith(DIR_WORKSPACE_PREFIX)) {
+            input["location"] = {
+              directory: options.workspaceID.slice(DIR_WORKSPACE_PREFIX.length),
+            }
+          } else {
+            input["location"] = {
+              ...(options.directory ? { directory: options.directory } : {}),
+              ...(options.workspaceID ? { workspaceID: options.workspaceID } : {}),
+            }
+          }
+        }
+        const created = await ctx.session.create(input)
+        if (permissions) {
+          // Session.create permissions lose to agent rules (last match wins
+          // and agent rules apply later), which strips team tools from
+          // read-only agents. Re-assert here: rules() evaluates after the
+          // agent's rules, restoring the tools. OQ-V2-rules.
+          await ctx.permission.rules({ sessionID: created.id, permissions })
+        }
+        return { data: { id: created.id } }
+      },
+      promptAsync: async (options) => {
+        // Synthetic (system) messages render as persistent transcript entries
+        // instead of fake user turns — the native form for agent notifications.
+        if (options.synthetic) {
+          return ctx.session.synthetic({ sessionID: options.sessionID, text: joinParts(options.parts), delivery: "queue" })
+        }
+        if (options.agent) {
+          await ctx.session.switchAgent({ sessionID: options.sessionID, agent: options.agent })
+        }
+        // V2 binds model at create/admission; the shared create signature has
+        // no model slot, so apply it here (spawn is the only model passer).
+        // Caught live: without this, teammates inherit the server default.
+        if (options.model) {
+          await ctx.session.switchModel({
+            sessionID: options.sessionID,
+            model: { providerID: options.model.providerID, id: options.model.modelID },
+          })
+        }
+        const text = joinParts(options.parts)
+        return ctx.session.prompt({ sessionID: options.sessionID, text, delivery: "queue" })
+      },
+      abort: async (options) => ctx.session.interrupt({ sessionID: options.sessionID }),
+      status: async () => {
+        const active = await ctx.session.active()
+        const data: Record<string, { type: string }> = {}
+        for (const sessionID of Object.keys(active)) data[sessionID] = { type: "busy" }
+        return { data }
+      },
+      messages: async (options) => {
+        const messages = await ctx.session.context({ sessionID: options.sessionID })
+        return { data: messages as Array<{ info: unknown; parts: unknown[] }> }
+      },
+      get: async (options) => {
+        const data = await ctx.session.get({ sessionID: options.sessionID })
+        return { data }
+      },
+    },
+    tui: {
+      showToast: async () => undefined,
+      selectSession: async (options) => {
+        // Native agent switching on V2: shared team_view calls this, the
+        // companion receives the event and navigates the TUI to the
+        // teammate session. No server-side TUI API exists on V2.
+        if (deps.rpcEmitter) {
+          await deps.rpcEmitter.events.emit("view", { sessionID: options.sessionID }).catch(() => {
+            // Companion optional — never fail team_view for it.
+          })
+        }
+        return undefined
+      },
+    },
+    worktree: {
+      create: async (options) => {
+        const name = (options.worktreeCreateInput as { name?: string } | undefined)?.name ?? "ensemble-worktree"
+        const created = await ctx.worktree.create({ name })
+        const branch = (await gitBranch(created.directory)) ?? name
+        return { data: { name, branch, directory: created.directory } }
+      },
+      remove: async (options) => {
+        const directory = (options.worktreeRemoveInput as { directory: string }).directory
+        return ctx.worktree.remove({ directory, force: false })
+      },
+      list: async () => {
+        const entries = await ctx.worktree.list()
+        return {
+          data: entries.map((entry) => ({
+            name: entry.directory.split("/").pop() ?? entry.directory,
+            branch: "",
+            directory: entry.directory,
+          })),
+        }
+      },
+      reset: async () => ctx.worktree.refresh(),
+    },
+    workspace: {
+      create: async (options) => {
+        const branch = (options as { branch?: string }).branch ?? ""
+        const directory = await deps.gitDir?.(branch)
+        if (!directory) throw new Error(`V2 workspace bridge: no worktree found on branch "${branch}"`)
+        return {
+          data: {
+            id: `${DIR_WORKSPACE_PREFIX}${directory}`,
+            type: "local",
+            branch,
+            directory,
+            projectID: "",
+          },
+        }
+      },
+      remove: async () => undefined,
+      list: async () => ({
+        data: [] as Array<{
+          id: string
+          type: string
+          branch: string | null
+          directory: string | null
+          projectID: string
+        }>,
+      }),
+    },
+  } as PluginClient
+}

package/src/v2-events.ts

@@ -0,0 +1,73 @@
+import type { Database } from "./db"
+import type { MemberRegistry, DescendantTracker } from "./state"
+import {
+  handleSessionCreatedEvent,
+  handleSessionStatusEvent,
+  type StatusTransition,
+} from "./hooks"
+
+/** Minimal structural shape of a V2 server event. */
+export interface V2EventLike {
+  type: string
+  data?: {
+    sessionID?: string
+    parentID?: string
+    status?: string | { type?: string }
+    attempt?: number
+    at?: number
+    error?: { message?: string }
+  }
+}
+
+/**
+ * Dispatch a V2 server event to the shared member state machine in hooks.ts.
+ * Returns the status transition when one occurred (for notifications).
+ */
+export function dispatchV2Event(
+  db: Database,
+  registry: MemberRegistry,
+  tracker: DescendantTracker,
+  event: V2EventLike,
+): StatusTransition | undefined {
+  const data = event.data ?? {}
+  switch (event.type) {
+    case "session.status": {
+      const raw = data.status
+      const status = typeof raw === "string" ? raw : raw?.type
+      if (status === "idle" || status === "busy") {
+        return handleSessionStatusEvent(db, registry, data.sessionID ?? "", status)
+      }
+      if (status === "retry") {
+        return handleSessionStatusEvent(db, registry, data.sessionID ?? "", "retry")
+      }
+      return undefined
+    }
+    case "session.idle":
+      if (!data.sessionID) return undefined
+      return handleSessionStatusEvent(db, registry, data.sessionID, "idle")
+    case "session.execution.started":
+      if (!data.sessionID) return undefined
+      return handleSessionStatusEvent(db, registry, data.sessionID, "busy")
+    case "session.execution.succeeded":
+    case "session.execution.failed":
+      // Ended means idle even on failure — the idle-without-report nudge then
+      // prompts the teammate to report, which surfaces the failure to the lead.
+      if (!data.sessionID) return undefined
+      return handleSessionStatusEvent(db, registry, data.sessionID, "idle")
+    case "session.created":
+      handleSessionCreatedEvent(tracker, data.sessionID ?? "", data.parentID)
+      return undefined
+    case "session.retry.scheduled": {
+      if (!data.sessionID) return undefined
+      const attempt = typeof data.attempt === "number" ? data.attempt : 0
+      const next = typeof data.at === "number" ? data.at : Date.now()
+      return handleSessionStatusEvent(db, registry, data.sessionID, "retry", {
+        attempt,
+        message: data.error?.message ?? "rate limited",
+        next,
+      })
+    }
+    default:
+      return undefined
+  }
+}

package/src/v2-rpc.ts

@@ -0,0 +1,24 @@
+import { EnsembleRpc } from "./rpc"
+
+export { EnsembleRpc }
+
+/** Minimal structural shape of an RPC registration's event emitter. */
+export interface RpcEmitter {
+  events: { emit(name: string, data: unknown): Promise<unknown> }
+}
+
+/** Publish a member status transition for companions. */
+export async function emitMemberEvent(
+  registration: RpcEmitter,
+  data: { memberName: string; teamId: string; from: string; to: string },
+): Promise<void> {
+  await registration.events.emit("member", data)
+}
+
+/** Publish a toast payload for companions. */
+export async function emitNoticeEvent(
+  registration: RpcEmitter,
+  data: { title?: string; message: string; variant?: string },
+): Promise<void> {
+  await registration.events.emit("notice", data)
+}

package/src/v2-session.ts

@@ -0,0 +1,56 @@
+/** V2 session adapter (issue #36). Wraps the `ctx.session` subset Ensemble uses. */
+
+/** A V2 permission rule: ordered, last match wins. Child sessions inherit. */
+export interface V2PermissionRule {
+  action: string
+  resource: string
+  effect: "allow" | "deny" | "ask"
+}
+
+/** Minimal structural subset of the V2 `ctx.session` domain. */
+export interface V2SessionPort {
+  create(input: {
+    title?: string
+    agent?: string
+    parentID?: string
+    permissions?: V2PermissionRule[]
+  }): Promise<{ id: string }>
+  prompt(input: { sessionID: string; text: string; delivery?: "steer" | "queue" }): Promise<unknown>
+  interrupt(input: { sessionID: string }): Promise<unknown>
+}
+
+/** Input for spawning a teammate session on V2. */
+export interface CreateTeammateInput {
+  title: string
+  agent: string
+  parentID?: string
+  permissions?: V2PermissionRule[]
+}
+
+/** Create a teammate session. Returns the child session ID. */
+export async function createTeammateSession(
+  port: V2SessionPort,
+  input: CreateTeammateInput,
+): Promise<string> {
+  const created = await port.create({
+    title: input.title,
+    agent: input.agent,
+    ...(input.parentID ? { parentID: input.parentID } : {}),
+    ...(input.permissions ? { permissions: input.permissions } : {}),
+  })
+  return created.id
+}
+
+/** Deliver a system text to a session. Uses queue delivery (spike-verified). */
+export async function deliverPrompt(
+  port: V2SessionPort,
+  sessionID: string,
+  text: string,
+): Promise<unknown> {
+  return port.prompt({ sessionID, text, delivery: "queue" })
+}
+
+/** Interrupt a teammate session (V2 replacement for abort). Best-effort. */
+export async function interruptTeammate(port: V2SessionPort, sessionID: string): Promise<unknown> {
+  return port.interrupt({ sessionID })
+}