@hueyexe/opencode-ensemble 0.17.0 → 0.18.0

package/src/v2-setup.ts

@@ -0,0 +1,349 @@
+import type { Database } from "./db"
+import { createDb, getDbPath } from "./db"
+import type { MemberRegistry, DescendantTracker } from "./state"
+import { MemberRegistry as MemberRegistryImpl, DescendantTracker as DescendantTrackerImpl, PendingPurgeApprovals } from "./state"
+import { dispatchV2Event, type V2EventLike } from "./v2-events"
+import { deliverPrompt, type V2SessionPort } from "./v2-session"
+import type { V2Context } from "./v2-client"
+import { createV2Client } from "./v2-client"
+import { registerV2Tools } from "./v2-tools"
+import type { ToolDeps } from "./types"
+import { ProgressTracker } from "./progress"
+import { checkToolIsolation, shouldNudgeIdleMember } from "./hooks"
+import { hasReportedCompletion } from "./messaging"
+import { rehydrateRegistry } from "./recovery"
+import { findTeamBySession } from "./types"
+import { loadConfig } from "./config"
+import { TokenBucket } from "./rate-limit"
+import { ActivityBuffer, recordFromToolBefore, recordFromToolAfter } from "./activity"
+import { buildLeadSystemPrompt, buildTeammateSystemPrompt, buildTeamCompactionContext } from "./system-prompt"
+import { startDashboard, type DashboardServer } from "./dashboard"
+import { EnsembleRpc, emitMemberEvent, emitNoticeEvent } from "./v2-rpc"
+import { isWorktreeInstance } from "./util"
+import { vlog } from "./log"
+
+/** V2 setup context subset (structural, mock-friendly). */
+export interface V2SetupContext {
+  location: { directory: string }
+  options: Record<string, unknown>
+  session: V2Context["session"] & {
+    hook(name: string, cb: (event: never) => unknown): Promise<{ dispose(): Promise<void> }>
+  }
+  worktree: V2Context["worktree"]
+  permission: V2Context["permission"]
+  event: {
+    subscribe(opts?: { signal?: AbortSignal }): AsyncIterable<V2EventLike>
+  }
+  tool: {
+    hook(name: string, cb: (event: never) => unknown): Promise<{ dispose(): Promise<void> }>
+    transform(cb: (editor: never) => void): Promise<{ dispose(): Promise<void> }>
+  }
+  rpc: {
+    register(
+      definition: unknown,
+      handlers: Record<string, (input: unknown, context: unknown) => Promise<unknown>>,
+    ): Promise<{ events: { emit(name: string, data: unknown): Promise<unknown> } }>
+  }
+  shell: {
+    hook(name: string, cb: (event: never) => unknown): Promise<{ dispose(): Promise<void> }>
+  }
+}
+
+/** Extract answer text from a V2 tool result for approval matching. */
+export function extractQuestionOutput(result?: {
+  content?: string | Array<{ type?: string; text?: string }>
+}): string {
+  const content = result?.content
+  if (typeof content === "string") return content
+  if (Array.isArray(content)) {
+    return content
+      .filter((part) => part.type === "text")
+      .map((part) => part.text ?? "")
+      .join("\n")
+  }
+  return ""
+}
+
+/** Options for setupEnsemble. */
+export interface SetupOptions {
+  /** SQLite path. Defaults to the global ensemble.db. */
+  dbPath?: string
+  /** Dashboard port. Defaults to config; 0 disables. */
+  dashboardPort?: number
+}
+
+/** Live handle for a V2 ensemble instance. */
+export interface EnsembleHandle {
+  db: Database
+  registry: MemberRegistry
+  tracker: DescendantTracker
+  /** Dispatch one event (used by the live subscription loop; tests call directly). */
+  dispatch(event: V2EventLike): Promise<void>
+  /** Stop the event loop and release resources. */
+  dispose(): Promise<void>
+}
+
+/**
+ * Initialize Ensemble on a V2 plugin context: database, registries, event
+ * subscription, tool hooks, session hooks, and shell env. Tool registration
+ * lands in the next slice.
+ */
+export async function setupEnsemble(
+  ctx: V2SetupContext,
+  options: SetupOptions = {},
+): Promise<EnsembleHandle> {
+  const db = createDb(options.dbPath ?? getDbPath())
+  const config = loadConfig(ctx.location.directory)
+  const registry: MemberRegistry = new MemberRegistryImpl()
+  const tracker: DescendantTracker = new DescendantTrackerImpl()
+  const purgeApprovals = new PendingPurgeApprovals()
+  const activityBuffer = new ActivityBuffer()
+  const progressTracker = new ProgressTracker()
+  const nudgedMembers = new Set<string>()
+
+  // Rehydrate the in-memory registry from SQLite so members from before a
+  // restart are visible again. Without this, their events are ignored and
+  // teams freeze silently after every server restart (seen live 2026-09-14).
+  const rehydrated = rehydrateRegistry(db, registry)
+  if (rehydrated > 0) vlog(`init:registry:rehydrated members=${rehydrated}`)
+
+  /** Send the idle-without-report nudge once per member. */
+  const nudgeMember = (teamId: string, memberName: string, sessionId: string): void => {
+    const nudgeKey = `${teamId}:${memberName}`
+    if (nudgedMembers.has(nudgeKey)) return
+    if (!shouldNudgeIdleMember(db, teamId, memberName)) return
+    if (hasReportedCompletion(db, teamId, memberName)) return
+    nudgedMembers.add(nudgeKey)
+    // Persist so hot-reloads don't re-nudge: every setup re-runs the sweep,
+    // and without this each file save re-nudged every silent member (seen
+    // live 2026-09-14 — 40+ nudges on one scout).
+    db.run("UPDATE team_member SET last_nudged_at = ? WHERE team_id = ? AND name = ?", [
+      Date.now(),
+      teamId,
+      memberName,
+    ])
+    vlog(`nudge:idle-without-report name=${memberName}`)
+    void deliverPrompt(
+      ctx.session as unknown as V2SessionPort,
+      sessionId,
+      "[System]: You completed your work but did not report results. Send your findings to the lead via team_message now.",
+    ).catch((err) => {
+      vlog(`nudge:idle-without-report:failed name=${memberName} err=${err instanceof Error ? err.message : String(err)}`)
+    })
+  }
+
+  // Startup sweep: members already idle (e.g. finished while the plugin was
+  // down) never emit a fresh transition, so nudge them now. Skip members
+  // nudged within the hour — the guard survives reloads via the DB column.
+  const nudgeCutoff = Date.now() - 60 * 60 * 1000
+  const silent = 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 = 'ready'
+       AND (tm.last_nudged_at IS NULL OR tm.last_nudged_at < ?)`,
+  ).all(nudgeCutoff) as Array<{ team_id: string; name: string; session_id: string }>
+  for (const member of silent) nudgeMember(member.team_id, member.name, member.session_id)
+  const rateLimiter = new TokenBucket({
+    capacity: config.rateLimitCapacity,
+    refillRate: 2,
+    refillIntervalMs: 1000,
+  })
+  const controller = new AbortController()
+
+  const dispatch = async (event: V2EventLike): Promise<void> => {
+    const transition = dispatchV2Event(db, registry, tracker, event)
+    // Idle-without-report nudge (parity with V1): a member that went idle
+    // without ever messaging the lead gets ONE reminder to report via
+    // team_message. Without this, weak models finish silently and the lead
+    // waits forever — the exact failure seen live on 2026-09-14.
+    if (transition && transition.to === "ready" && transition.from === "busy") {
+      const entry = registry.getByName(transition.teamId, transition.memberName)
+      if (entry) nudgeMember(transition.teamId, transition.memberName, entry.sessionId)
+    }
+    if (transition && rpc) {
+      await emitMemberEvent(rpc, transition).catch(() => {
+        // Companions are optional — never break the state machine for them.
+      })
+      if (transition.to === "ready" && transition.from === "busy") {
+        await emitNoticeEvent(rpc, {
+          title: "Team",
+          message: `${transition.memberName} finished`,
+          variant: "success",
+        }).catch(() => undefined)
+      } else if (transition.to === "error") {
+        await emitNoticeEvent(rpc, {
+          title: "Team",
+          message: `${transition.memberName} errored`,
+          variant: "error",
+        }).catch(() => undefined)
+      }
+    }
+  }
+
+  // RPC bridge for terminal companions (toasts, navigation). Best-effort:
+  // a failed registration must not break tools, hooks, or events.
+  let rpc: { events: { emit(name: string, data: unknown): Promise<unknown> } } | null = null
+  try {
+    rpc = await ctx.rpc.register(EnsembleRpc, {
+      summary: async (input) => {
+        const team = (input as { team?: string }).team ?? ""
+        const row = db.query("SELECT status FROM team WHERE name = ?").get(team) as {
+          status: string
+        } | null
+        if (!row) return { text: `No team "${team}".` }
+        const members = db.query("SELECT name, status FROM team_member WHERE team_id IN (SELECT id FROM team WHERE name = ?)").all(team) as Array<{
+          name: string
+          status: string
+        }>
+        const summary = members.map((m) => `${m.name}: ${m.status}`).join(", ")
+        return { text: `Team "${team}" (${row.status}): ${summary || "no members"}` }
+      },
+      teamContext: async (input) => {
+        const sessionID = (input as { sessionID?: string }).sessionID ?? ""
+        const teamInfo = findTeamBySession(db, registry, sessionID)
+        if (!teamInfo) return { team: null, members: [], tasks: { pending: 0, done: 0 } }
+        const members = db.query("SELECT name, status FROM team_member WHERE team_id = ?").all(
+          teamInfo.teamId,
+        ) as Array<{ name: string; status: string }>
+        const pending = (
+          db.query("SELECT COUNT(*) as c FROM team_task WHERE team_id = ? AND status != 'completed'").get(
+            teamInfo.teamId,
+          ) as { c: number }
+        ).c
+        const done = (
+          db.query("SELECT COUNT(*) as c FROM team_task WHERE team_id = ? AND status = 'completed'").get(
+            teamInfo.teamId,
+          ) as { c: number }
+        ).c
+        return { team: teamInfo.teamName, members, tasks: { pending, done } }
+      },
+    })
+  } catch (err) {
+    vlog(`init:rpc:failed err=${err instanceof Error ? err.message : String(err)}`)
+  }
+
+  // Live event loop — fire-and-forget; dispose() aborts it.
+  void (async () => {
+    try {
+      for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
+        await dispatch(event)
+      }
+    } catch {
+      // Aborted on dispose or stream error — nothing to report.
+    }
+  })()
+
+  await ctx.tool.hook("execute.before", (raw) => {
+    const input = raw as unknown as { tool: string; sessionID: string }
+    checkToolIsolation(registry, tracker, input.tool, input.sessionID, db)
+    if (input.tool.startsWith("team_")) {
+      if (!rateLimiter.tryConsume()) {
+        return rateLimiter.waitForToken().then(() => undefined)
+      }
+    }
+    recordFromToolBefore({ sessionID: input.sessionID, tool: input.tool }, registry, activityBuffer)
+  })
+
+  await ctx.tool.hook("execute.after", (raw) => {
+    const event = raw as unknown as {
+      tool: string
+      sessionID: string
+      input: unknown
+      status: string
+      result?: { content?: string | Array<{ type?: string; text?: string }> }
+    }
+    if (event.tool === "question") {
+      // Feed the answer text to purge approvals (team_cleanup confirm flow).
+      // The question tool renders in every client, so this is the universal
+      // approval channel on V2 — no forms or TUI needed.
+      purgeApprovals.recordQuestionAnswer(
+        event.sessionID,
+        extractQuestionOutput(event.result),
+        event.input,
+      )
+    }
+    recordFromToolAfter(
+      { sessionID: event.sessionID, tool: event.tool },
+      {},
+      registry,
+      activityBuffer,
+    )
+  })
+
+  await ctx.session.hook("context", (raw) => {
+    const event = raw as unknown as {
+      sessionID: string
+      system: Array<{ type: string; text: string }>
+    }
+    if (!event.sessionID) return
+    const teamInfo = findTeamBySession(db, registry, event.sessionID)
+    if (!teamInfo) return
+    const prompt =
+      teamInfo.role === "lead"
+        ? buildLeadSystemPrompt(db, teamInfo.teamId, config)
+        : buildTeammateSystemPrompt(db, teamInfo.teamId, teamInfo.memberName ?? "unknown")
+    vlog(`system-prompt:injected role=${teamInfo.role} len=${prompt.length}`)
+    event.system.push({ type: "text", text: prompt })
+    if (teamInfo.role === "member") {
+      // V2 invokes plugin tools through Code Mode, not direct calls —
+      // without this hint teammates attempt direct calls that the runtime
+      // rejects with "No tool named team_message is currently available"
+      // (seen live 2026-09-14: explore scout denied twice, gave up).
+      event.system.push({
+        type: "text",
+        text: 'Ensemble tools on this platform are called through the execute tool, e.g. tools.team_message({ to: "lead", text: "..." }). Do not call them directly.',
+      })
+    }
+  })
+
+  await ctx.session.hook("compaction", (raw) => {
+    const event = raw as unknown as {
+      sessionID: string
+      system: Array<{ type: string; text: string }>
+    }
+    if (!event.sessionID) return
+    const teamInfo = findTeamBySession(db, registry, event.sessionID)
+    if (!teamInfo) return
+    const context = buildTeamCompactionContext(db, teamInfo.teamId, teamInfo.role, teamInfo.memberName)
+    event.system.push({ type: "text", text: context })
+  })
+
+  // OQ-V2-shell: the V2 shell hook carries no sessionID, so per-session
+  // ENSEMBLE_* env cannot be scoped. Registered as a placeholder until the
+  // API gains session scope — team tools and prompts carry identity instead.
+  await ctx.shell.hook("create.before", () => undefined)
+
+  const client = createV2Client(ctx, rpc ? { rpcEmitter: rpc } : {})
+  const deps: ToolDeps = {
+    db,
+    registry,
+    tracker,
+    purgeApprovals,
+    client,
+    directory: ctx.location.directory,
+    config,
+    progressTracker,
+  }
+  await registerV2Tools(ctx.tool, deps)
+
+  // Dashboard mirrors V1: main instance only, skipped when port is 0.
+  let dashboard: DashboardServer | null = null
+  const dashboardPort = options.dashboardPort ?? config.dashboardPort
+  if (dashboardPort !== 0 && !isWorktreeInstance(ctx.location.directory)) {
+    dashboard = await startDashboard(db, dashboardPort, { activityBuffer, client }).catch((err) => {
+      vlog(`init:dashboard:failed err=${err instanceof Error ? err.message : String(err)}`)
+      return null
+    })
+  }
+
+  return {
+    db,
+    registry,
+    tracker,
+    dispatch,
+    dispose: async () => {
+      controller.abort()
+      dashboard?.stop()
+    },
+  }
+}

package/src/v2-tools.ts

@@ -0,0 +1,349 @@
+import type { ToolDeps } from "./types"
+import { executeTeamCreate } from "./tools/team-create"
+import { executeTeamSpawn } from "./tools/team-spawn"
+import { executeTeamMessage } from "./tools/team-message"
+import { executeTeamBroadcast } from "./tools/team-broadcast"
+import { executeTeamTasksList } from "./tools/team-tasks-list"
+import { executeTeamTasksAdd } from "./tools/team-tasks-add"
+import { executeTeamTasksComplete } from "./tools/team-tasks-complete"
+import { executeTeamClaim } from "./tools/team-claim"
+import { executeTeamResults } from "./tools/team-results"
+import { executeTeamShutdown } from "./tools/team-shutdown"
+import { executeTeamCleanup } from "./tools/team-cleanup"
+import { executeTeamMerge } from "./tools/team-merge"
+import { executeTeamStatus } from "./tools/team-status"
+import { executeTeamView } from "./tools/team-view"
+
+/** V2 tool definition (JSON Schema input, structured content output). */
+export interface V2ToolDef {
+  name: string
+  description: string
+  input: Record<string, unknown>
+  execute(input: unknown, context: { sessionID: string }): Promise<{ content: string }>
+}
+
+/** Minimal structural subset of the V2 tool domain. */
+export interface V2ToolDomain {
+  transform(cb: (editor: { add(def: V2ToolDef): void }) => void): Promise<{ dispose(): Promise<void> }>
+}
+
+/** JSON Schema string property. */
+function str(description: string): Record<string, unknown> {
+  return { type: "string", description }
+}
+
+/** JSON Schema boolean property with default. */
+function bool(description: string, fallback: boolean): Record<string, unknown> {
+  return { type: "boolean", description, default: fallback }
+}
+
+/** Task priority enum shared by the schema and the runtime validator. */
+const TASK_PRIORITIES = ["high", "medium", "low"] as const
+type TaskPriority = (typeof TASK_PRIORITIES)[number]
+
+/** JSON Schema enum property for task priority. */
+function priority(): Record<string, unknown> {
+  return { type: "string", description: "Task priority", enum: [...TASK_PRIORITIES], default: "medium" }
+}
+
+/** Throw on unknown priority — fail fast instead of writing garbage to SQLite. */
+export function normalizePriority(value: string | undefined): TaskPriority {
+  if (value === undefined) return "medium"
+  if ((TASK_PRIORITIES as readonly string[]).includes(value)) return value as TaskPriority
+  throw new Error(`Invalid priority "${value}" — expected one of: high, medium, low.`)
+}
+
+/**
+ * Register all 14 team tools on a V2 context. Each execute delegates to the
+ * same implementation V1 uses (DRY) — only arg transport changes from Zod to
+ * JSON Schema. V1 applied schema defaults before execute; V2 may not, so
+ * priority is normalized here (team_tasks_add writes it straight to SQLite).
+ *
+ * Purge approval (team_cleanup) has no approver on V2 yet — the question-tool
+ * flow it used is TUI-side. Preview works; confirmed purge needs the forms
+ * slice. team_view resolves without navigating (no server-side TUI select).
+ */
+export async function registerV2Tools(domain: V2ToolDomain, deps: ToolDeps): Promise<void> {
+  const run = <A>(
+    fn: (deps: ToolDeps, args: A, sessionID: string) => Promise<string>,
+    track?: (sessionID: string, args: A) => void,
+  ) => async (input: unknown, context: { sessionID: string }) => {
+    const args = input as A
+    track?.(context.sessionID, args)
+    return { content: await fn(deps, args, context.sessionID) }
+  }
+  const runSession = (fn: (deps: ToolDeps, sessionID: string) => Promise<string>) => async (
+    _input: unknown,
+    context: { sessionID: string },
+  ) => ({ content: await fn(deps, context.sessionID) })
+
+  await domain.transform((editor) => {
+    editor.add({
+      name: "team_create",
+      description: "Create a new agent team. You become the team lead. Use this before spawning teammates.",
+      input: {
+        type: "object",
+        properties: {
+          name: str("Team name (lowercase alphanumeric with hyphens, 1-64 chars)"),
+          project_name: str("Project display name for first use of this working directory."),
+        },
+        required: ["name"],
+        additionalProperties: false,
+      },
+      execute: run(executeTeamCreate),
+    })
+
+    editor.add({
+      name: "team_spawn",
+      description:
+        "Spawn a new teammate that works in parallel. The teammate starts immediately with the given prompt. " +
+        "Each teammate gets their own git worktree for file isolation. " +
+        "Teammates work asynchronously and will message you when done. Do not poll for their status.",
+      input: {
+        type: "object",
+        properties: {
+          name: str("Teammate name (lowercase alphanumeric with hyphens)"),
+          agent: str("Agent type (e.g. 'build', 'plan', 'explore')"),
+          prompt: str("Task instructions for the teammate"),
+          model: str("Model in provider/model format (optional, uses default)"),
+          claim_task: str("Task ID to auto-claim for this teammate (optional)"),
+          worktree: bool("Create a git worktree for file isolation (default: true, set false for read-only agents)", true),
+          plan_approval: bool("Require teammate to send a plan for approval before writing files (default: false)", false),
+        },
+        required: ["name", "prompt"],
+        additionalProperties: false,
+      },
+      execute: run(executeTeamSpawn),
+    })
+
+    editor.add({
+      name: "team_message",
+      description:
+        "Send a message to a specific teammate or to the lead. Use 'lead' to message the team lead. " +
+        "Lead only: pass 'model' (provider/model) to update a teammate's model in-place.",
+      input: {
+        type: "object",
+        properties: {
+          to: str("Recipient name ('lead' or teammate name)"),
+          text: str("Message content (max 10KB). Optional only when 'model' is provided."),
+          approve: bool("Approve a teammate's plan (only when recipient has plan_approval='pending')", false),
+          reject: str("Reject a teammate's plan with reason (only when recipient has plan_approval='pending')"),
+          force: bool("Lead only. Re-activate a teammate who already reported task completion.", false),
+          model: str("Lead only: update the recipient teammate's model in-place, in 'provider/model' format."),
+        },
+        required: ["to"],
+        additionalProperties: false,
+      },
+      execute: run(executeTeamMessage, (sessionID, args) => {
+        const to = args.to ?? ""
+        deps.progressTracker.recordMessage(sessionID)
+        if (to !== "lead") deps.progressTracker.recordPeerMessage(sessionID)
+      }),
+    })
+
+    editor.add({
+      name: "team_broadcast",
+      description: "Send a message to all teammates and the lead (excluding yourself).",
+      input: {
+        type: "object",
+        properties: { text: str("Message content (max 10KB)") },
+        required: ["text"],
+        additionalProperties: false,
+      },
+      execute: run(executeTeamBroadcast, (sessionID) => {
+          deps.progressTracker.recordMessage(sessionID)
+          deps.progressTracker.recordPeerMessage(sessionID)
+        },
+      ),
+    })
+
+    editor.add({
+      name: "team_tasks_list",
+      description:
+        "View the shared team task board. Use this to check task status, not to wait for teammates. Teammates will message you when done.",
+      input: { type: "object", properties: {}, additionalProperties: false },
+      execute: runSession(executeTeamTasksList),
+    })
+
+    editor.add({
+      name: "team_tasks_add",
+      description: "Add tasks to the shared team task board so teammates can see what work is available and claim it.",
+      input: {
+        type: "object",
+        properties: {
+          tasks: {
+            type: "array",
+            description: "Tasks to add",
+            items: {
+              type: "object",
+              properties: {
+                content: str("Task description"),
+                priority: priority(),
+                depends_on: {
+                  type: "array",
+                  items: { type: "string" },
+                  description: "Task IDs this depends on",
+                },
+              },
+              required: ["content"],
+              additionalProperties: false,
+            },
+          },
+        },
+        required: ["tasks"],
+        additionalProperties: false,
+      },
+      execute: async (input: unknown, context: { sessionID: string }) => {
+        const args = input as {
+          tasks: Array<{ content: string; priority?: string; depends_on?: string[] }>
+        }
+        const content = await executeTeamTasksAdd(
+          deps,
+          {
+            tasks: args.tasks.map((task) => ({
+              content: task.content,
+              priority: normalizePriority(task.priority),
+              ...(task.depends_on ? { depends_on: task.depends_on } : {}),
+            })),
+          },
+          context.sessionID,
+        )
+        return { content }
+      },
+    })
+
+    editor.add({
+      name: "team_tasks_complete",
+      description: "Mark a task as completed on the shared board. This unblocks any tasks that depend on it.",
+      input: {
+        type: "object",
+        properties: { task_id: str("ID of the task to mark complete") },
+        required: ["task_id"],
+        additionalProperties: false,
+      },
+      execute: run(executeTeamTasksComplete, (sessionID) =>
+        deps.progressTracker.recordTaskComplete(sessionID),
+      ),
+    })
+
+    editor.add({
+      name: "team_claim",
+      description: "Claim a pending task from the shared task list. Only unclaimed, unblocked tasks can be claimed.",
+      input: {
+        type: "object",
+        properties: { task_id: str("ID of the task to claim") },
+        required: ["task_id"],
+        additionalProperties: false,
+      },
+      execute: run(executeTeamClaim),
+    })
+
+    editor.add({
+      name: "team_results",
+      description:
+        "Retrieve full message content from teammates. Returns unread messages and marks them as read. Use this after receiving a truncated message notification.",
+      input: {
+        type: "object",
+        properties: { from: str("Filter messages by sender name (optional, returns all if omitted)") },
+        additionalProperties: false,
+      },
+      execute: run(executeTeamResults),
+    })
+
+    editor.add({
+      name: "team_shutdown",
+      description:
+        "Request a teammate to shut down. The teammate finishes current work then stops. Pass force: true to abort immediately without waiting.",
+      input: {
+        type: "object",
+        properties: {
+          member: str("Teammate name to shut down"),
+          force: bool("Force immediate abort without waiting for current work to finish", false),
+        },
+        required: ["member"],
+        additionalProperties: false,
+      },
+      execute: run(executeTeamShutdown),
+    })
+
+    editor.add({
+      name: "team_cleanup",
+      description:
+        "Clean up the current team, or purge archived teams after human approval. Omit purge for normal cleanup.",
+      input: {
+        type: "object",
+        properties: {
+          force: bool("Force cleanup even if members are active (will abort them)", false),
+          acknowledge_uncommitted: bool("Acknowledge uncommitted changes", false),
+          purge: {
+            type: "array",
+            items: { type: "string" },
+            description: "Archived team names to permanently delete, or ['*'] for all archived teams.",
+          },
+          confirm_purge: bool("Set true only after the user explicitly approves the purge preview.", false),
+          confirm_token: str("Confirmation token from the purge preview."),
+        },
+        additionalProperties: false,
+      },
+      execute: async (input: unknown, context: { sessionID: string }) => {
+        const args = input as {
+          force?: boolean
+          acknowledge_uncommitted?: boolean
+          purge?: string[]
+          confirm_purge?: boolean
+          confirm_token?: string
+        }
+        const content = await executeTeamCleanup(
+          deps,
+          {
+            force: args.force ?? false,
+            acknowledge_uncommitted: args.acknowledge_uncommitted,
+            purge: args.purge,
+            confirm_purge: args.confirm_purge,
+            confirm_token: args.confirm_token,
+          },
+          context.sessionID,
+        )
+        return { content }
+      },
+    })
+
+    editor.add({
+      name: "team_merge",
+      description:
+        "Merge a shutdown teammate's branch into the working directory as unstaged changes. Use this after team_shutdown to review and integrate a teammate's work. The teammate must be shut down first.",
+      input: {
+        type: "object",
+        properties: { member: str("Teammate name whose branch to merge") },
+        required: ["member"],
+        additionalProperties: false,
+      },
+      execute: run(executeTeamMerge),
+    })
+
+    editor.add({
+      name: "team_status",
+      description:
+        "View team members with their current status, agent type, and session IDs. Use this to check who is working, idle, or shut down. Includes a task summary.",
+      input: { type: "object", properties: {}, additionalProperties: false },
+      execute: runSession(executeTeamStatus),
+    })
+
+    editor.add({
+      name: "team_view",
+      description:
+        "Resolve a teammate's session so the user can inspect it. Default reports the session ID + status without switching. " +
+        "navigate: true switches the user's client — ONLY when the user explicitly asked to view the teammate's session.",
+      input: {
+        type: "object",
+        properties: {
+          member: str("Teammate name to view"),
+          navigate: bool("Switch the user's client to this session. Only when the user explicitly asked.", false),
+        },
+        required: ["member"],
+        additionalProperties: false,
+      },
+      execute: run(executeTeamView),
+    })
+  })
+}