Add tmux pane management for background agent sessions (#1094)

* feat(config): add TmuxConfigSchema for tmux subagent pane management Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai> * feat(shared): add tmux module structure * feat(shared/tmux): implement tmux pane utilities Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai> * test(tmux-subagent): add TmuxSessionManager tests (TDD RED) Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai> * feat(tmux-subagent): implement TmuxSessionManager Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai> * feat(integration): wire TmuxSessionManager with 500ms delay - Task 5: Add 500ms delay in BackgroundManager after session creation - Task 6: Wire TmuxSessionManager event handlers (session.created/deleted) - Both changes integrate tmux pane management into plugin lifecycle Co-authored-by: Sisyphus <ultrawork@oh-my-opencode> --------- Co-authored-by: justsisyphus <justsisyphus@users.noreply.github.com> Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai> Co-authored-by: Sisyphus <ultrawork@oh-my-opencode>
2026-01-25 15:34:10 +09:00
parent bccc943173
commit aead4aebd2
16 changed files with 893 additions and 39 deletions
@@ -30,3 +30,4 @@ export * from "./model-resolver"
 export * from "./model-availability"
 export * from "./case-insensitive"
 export * from "./session-utils"
+export * from "./tmux"
@@ -0,0 +1,11 @@
+// Polling interval for background session status checks
+export const POLL_INTERVAL_BACKGROUND_MS = 2000
+
+// Maximum idle time before session considered stale
+export const SESSION_TIMEOUT_MS = 10 * 60 * 1000  // 10 minutes
+
+// Grace period for missing session before cleanup
+export const SESSION_MISSING_GRACE_MS = 6000  // 6 seconds
+
+// Delay after pane spawn before sending prompt
+export const PANE_SPAWN_DELAY_MS = 500
@@ -0,0 +1,3 @@
+export * from "./types"
+export * from "./constants"
+export * from "./tmux-utils"
@@ -0,0 +1,195 @@
+import { describe, test, expect, beforeEach, afterEach, mock } from "bun:test"
+import {
+  isInsideTmux,
+  isServerRunning,
+  resetServerCheck,
+  spawnTmuxPane,
+  closeTmuxPane,
+  applyLayout,
+} from "./tmux-utils"
+
+describe("isInsideTmux", () => {
+  test("returns true when TMUX env is set", () => {
+    // #given
+    const originalTmux = process.env.TMUX
+    process.env.TMUX = "/tmp/tmux-1000/default"
+
+    // #when
+    const result = isInsideTmux()
+
+    // #then
+    expect(result).toBe(true)
+
+    // cleanup
+    process.env.TMUX = originalTmux
+  })
+
+  test("returns false when TMUX env is not set", () => {
+    // #given
+    const originalTmux = process.env.TMUX
+    delete process.env.TMUX
+
+    // #when
+    const result = isInsideTmux()
+
+    // #then
+    expect(result).toBe(false)
+
+    // cleanup
+    process.env.TMUX = originalTmux
+  })
+
+  test("returns false when TMUX env is empty string", () => {
+    // #given
+    const originalTmux = process.env.TMUX
+    process.env.TMUX = ""
+
+    // #when
+    const result = isInsideTmux()
+
+    // #then
+    expect(result).toBe(false)
+
+    // cleanup
+    process.env.TMUX = originalTmux
+  })
+})
+
+describe("isServerRunning", () => {
+  const originalFetch = globalThis.fetch
+
+  beforeEach(() => {
+    resetServerCheck()
+  })
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+  })
+
+  test("returns true when server responds OK", async () => {
+    // #given
+    globalThis.fetch = mock(async () => ({ ok: true })) as any
+
+    // #when
+    const result = await isServerRunning("http://localhost:4096")
+
+    // #then
+    expect(result).toBe(true)
+  })
+
+  test("returns false when server not reachable", async () => {
+    // #given
+    globalThis.fetch = mock(async () => {
+      throw new Error("ECONNREFUSED")
+    }) as any
+
+    // #when
+    const result = await isServerRunning("http://localhost:4096")
+
+    // #then
+    expect(result).toBe(false)
+  })
+
+  test("returns false when fetch returns not ok", async () => {
+    // #given
+    globalThis.fetch = mock(async () => ({ ok: false })) as any
+
+    // #when
+    const result = await isServerRunning("http://localhost:4096")
+
+    // #then
+    expect(result).toBe(false)
+  })
+
+  test("caches successful result", async () => {
+    // #given
+    const fetchMock = mock(async () => ({ ok: true })) as any
+    globalThis.fetch = fetchMock
+
+    // #when
+    await isServerRunning("http://localhost:4096")
+    await isServerRunning("http://localhost:4096")
+
+    // #then - should only call fetch once due to caching
+    expect(fetchMock.mock.calls.length).toBe(1)
+  })
+
+  test("does not cache failed result", async () => {
+    // #given
+    const fetchMock = mock(async () => {
+      throw new Error("ECONNREFUSED")
+    }) as any
+    globalThis.fetch = fetchMock
+
+    // #when
+    await isServerRunning("http://localhost:4096")
+    await isServerRunning("http://localhost:4096")
+
+    // #then - should call fetch 4 times (2 attempts per call, 2 calls)
+    expect(fetchMock.mock.calls.length).toBe(4)
+  })
+
+  test("uses different cache for different URLs", async () => {
+    // #given
+    const fetchMock = mock(async () => ({ ok: true })) as any
+    globalThis.fetch = fetchMock
+
+    // #when
+    await isServerRunning("http://localhost:4096")
+    await isServerRunning("http://localhost:5000")
+
+    // #then - should call fetch twice for different URLs
+    expect(fetchMock.mock.calls.length).toBe(2)
+  })
+})
+
+describe("resetServerCheck", () => {
+  test("clears cache without throwing", () => {
+    // #given, #when, #then
+    expect(() => resetServerCheck()).not.toThrow()
+  })
+
+  test("allows re-checking after reset", async () => {
+    // #given
+    const originalFetch = globalThis.fetch
+    const fetchMock = mock(async () => ({ ok: true })) as any
+    globalThis.fetch = fetchMock
+
+    // #when
+    await isServerRunning("http://localhost:4096")
+    resetServerCheck()
+    await isServerRunning("http://localhost:4096")
+
+    // #then - should call fetch twice after reset
+    expect(fetchMock.mock.calls.length).toBe(2)
+
+    // cleanup
+    globalThis.fetch = originalFetch
+  })
+})
+
+describe("tmux pane functions", () => {
+  test("spawnTmuxPane is exported as function", async () => {
+    // #given, #when
+    const result = typeof spawnTmuxPane
+
+    // #then
+    expect(result).toBe("function")
+  })
+
+  test("closeTmuxPane is exported as function", async () => {
+    // #given, #when
+    const result = typeof closeTmuxPane
+
+    // #then
+    expect(result).toBe("function")
+  })
+
+  test("applyLayout is exported as function", async () => {
+    // #given, #when
+    const result = typeof applyLayout
+
+    // #then
+    expect(result).toBe("function")
+  })
+})
@@ -0,0 +1,129 @@
+import { spawn } from "bun"
+import type { TmuxConfig, TmuxLayout } from "../../config/schema"
+import type { SpawnPaneResult } from "./types"
+import { getTmuxPath } from "../../tools/interactive-bash/utils"
+
+let serverAvailable: boolean | null = null
+let serverCheckUrl: string | null = null
+
+export function isInsideTmux(): boolean {
+  return !!process.env.TMUX
+}
+
+export async function isServerRunning(serverUrl: string): Promise<boolean> {
+  if (serverCheckUrl === serverUrl && serverAvailable === true) {
+    return true
+  }
+
+  const healthUrl = new URL("/health", serverUrl).toString()
+  const timeoutMs = 3000
+  const maxAttempts = 2
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    const controller = new AbortController()
+    const timeout = setTimeout(() => controller.abort(), timeoutMs)
+
+    try {
+      const response = await fetch(healthUrl, { signal: controller.signal }).catch(
+        () => null
+      )
+      clearTimeout(timeout)
+
+      if (response?.ok) {
+        serverCheckUrl = serverUrl
+        serverAvailable = true
+        return true
+      }
+    } finally {
+      clearTimeout(timeout)
+    }
+
+    if (attempt < maxAttempts) {
+      await new Promise((r) => setTimeout(r, 250))
+    }
+  }
+
+  return false
+}
+
+export function resetServerCheck(): void {
+  serverAvailable = null
+  serverCheckUrl = null
+}
+
+export async function spawnTmuxPane(
+  sessionId: string,
+  description: string,
+  config: TmuxConfig,
+  serverUrl: string
+): Promise<SpawnPaneResult> {
+  if (!config.enabled) return { success: false }
+  if (!isInsideTmux()) return { success: false }
+  if (!(await isServerRunning(serverUrl))) return { success: false }
+
+  const tmux = await getTmuxPath()
+  if (!tmux) return { success: false }
+
+  const opencodeCmd = `opencode attach ${serverUrl} --session ${sessionId}`
+
+  const args = [
+    "split-window",
+    "-h",
+    "-d",
+    "-P",
+    "-F",
+    "#{pane_id}",
+    opencodeCmd,
+  ]
+
+  const proc = spawn([tmux, ...args], { stdout: "pipe", stderr: "pipe" })
+  const exitCode = await proc.exited
+  const stdout = await new Response(proc.stdout).text()
+  const paneId = stdout.trim()
+
+  if (exitCode !== 0 || !paneId) {
+    return { success: false }
+  }
+
+  const title = `omo-subagent-${description.slice(0, 20)}`
+  spawn([tmux, "select-pane", "-t", paneId, "-T", title], {
+    stdout: "ignore",
+    stderr: "ignore",
+  })
+
+  await applyLayout(tmux, config.layout, config.main_pane_size)
+
+  return { success: true, paneId }
+}
+
+export async function closeTmuxPane(paneId: string): Promise<boolean> {
+  if (!isInsideTmux()) return false
+
+  const tmux = await getTmuxPath()
+  if (!tmux) return false
+
+  const proc = spawn([tmux, "kill-pane", "-t", paneId], {
+    stdout: "ignore",
+    stderr: "ignore",
+  })
+  const exitCode = await proc.exited
+
+  return exitCode === 0
+}
+
+export async function applyLayout(
+  tmux: string,
+  layout: TmuxLayout,
+  mainPaneSize: number
+): Promise<void> {
+  spawn([tmux, "select-layout", layout], { stdout: "ignore", stderr: "ignore" })
+
+  if (layout.startsWith("main-")) {
+    const dimension =
+      layout === "main-horizontal" ? "main-pane-height" : "main-pane-width"
+    spawn([tmux, "set-window-option", dimension, `${mainPaneSize}%`], {
+      stdout: "ignore",
+      stderr: "ignore",
+    })
+  }
+}
@@ -0,0 +1,4 @@
+export interface SpawnPaneResult {
+  success: boolean
+  paneId?: string  // e.g., "%42"
+}