@agentuity/opencode 0.1.39 → 0.1.41

package/src/tmux/executor.ts

@@ -0,0 +1,286 @@
+import type { PaneAction, WindowState, TmuxConfig } from './types';
+import { runTmuxCommand, runTmuxCommandSync } from './utils';
+
+/**
+ * Escape a string for safe use in shell commands.
+ * Wraps in single quotes and escapes any internal single quotes.
+ */
+function shellEscape(str: string): string {
+	// Replace single quotes with '\'' (end quote, escaped quote, start quote)
+	return `'${str.replace(/'/g, "'\\''")}'`;
+}
+
+/** Maximum retries for recursive spawn attempts to prevent infinite loops */
+const MAX_SPAWN_RETRIES = 3;
+
+export interface ActionResult {
+	success: boolean;
+	paneId?: string;
+	windowId?: string;
+	error?: string;
+}
+
+/**
+ * State for separate-window mode - tracks the dedicated "Agents" window
+ */
+let agentsWindowId: string | undefined;
+
+/**
+ * Execute a single pane action
+ *
+ * All agents spawn in a dedicated "Agents" window with tiled grid layout.
+ */
+export async function executeAction(
+	action: PaneAction,
+	ctx: { config: TmuxConfig; serverUrl: string; windowState: WindowState }
+): Promise<ActionResult> {
+	switch (action.type) {
+		case 'spawn':
+			return spawnInAgentsWindow(action, { serverUrl: ctx.serverUrl });
+		case 'close':
+			return closePane(action);
+		case 'replace':
+			return replacePane(action, ctx);
+	}
+}
+
+/**
+ * Execute multiple actions in sequence
+ */
+export async function executeActions(
+	actions: PaneAction[],
+	ctx: { config: TmuxConfig; serverUrl: string; windowState: WindowState }
+): Promise<{
+	success: boolean;
+	spawnedPaneId?: string;
+	results: Array<{ action: PaneAction; result: ActionResult }>;
+}> {
+	const results: Array<{ action: PaneAction; result: ActionResult }> = [];
+	let spawnedPaneId: string | undefined;
+
+	for (const action of actions) {
+		const result = await executeAction(action, ctx);
+		results.push({ action, result });
+		if (!result.success) {
+			return { success: false, spawnedPaneId, results };
+		}
+		if (action.type === 'spawn' && result.paneId) {
+			spawnedPaneId = result.paneId;
+		}
+	}
+
+	return { success: true, spawnedPaneId, results };
+}
+
+/**
+ * Close an existing pane
+ * Uses: tmux kill-pane -t <paneId>
+ */
+async function closePane(action: Extract<PaneAction, { type: 'close' }>): Promise<ActionResult> {
+	const result = await runTmuxCommand(['kill-pane', '-t', action.paneId]);
+	if (!result.success) {
+		return { success: false, error: result.output };
+	}
+	return { success: true };
+}
+
+/**
+ * Close a pane by its ID
+ * Exported for use by TmuxSessionManager when sessions complete
+ */
+export async function closePaneById(paneId: string): Promise<ActionResult> {
+	const result = await runTmuxCommand(['kill-pane', '-t', paneId]);
+	if (!result.success) {
+		return { success: false, error: result.output };
+	}
+	return { success: true };
+}
+
+/**
+ * Replace an existing pane with a new session
+ * Pane self-destructs when command exits (session complete, server died, etc.)
+ */
+async function replacePane(
+	action: Extract<PaneAction, { type: 'replace' }>,
+	ctx: { serverUrl: string }
+): Promise<ActionResult> {
+	// Pane kills itself when opencode attach exits (for any reason)
+	// Use shellEscape to prevent shell injection via session IDs
+	const escapedServerUrl = shellEscape(ctx.serverUrl);
+	const escapedSessionId = shellEscape(action.newSessionId);
+	const command = `opencode attach ${escapedServerUrl} --session ${escapedSessionId}; tmux kill-pane`;
+	const result = await runTmuxCommand(['respawn-pane', '-k', '-t', action.paneId, command]);
+	if (!result.success) {
+		return { success: false, error: result.output };
+	}
+	return { success: true, paneId: action.paneId };
+}
+
+/**
+ * Spawn agent in a dedicated "Agents" window with tiled grid layout
+ *
+ * On first spawn: Creates a new window named "Agents"
+ * Subsequent spawns: Splits within that window
+ * After each spawn: Applies tiled layout for a clean grid
+ *
+ * This keeps the main pane untouched while grouping all agent panes together.
+ * Tip: Click a pane to select it, then press Ctrl-b z to zoom/unzoom.
+ *
+ * @param retryCount - Internal counter to prevent infinite recursion (default 0)
+ */
+async function spawnInAgentsWindow(
+	action: Extract<PaneAction, { type: 'spawn' }>,
+	ctx: { serverUrl: string },
+	retryCount = 0
+): Promise<ActionResult> {
+	// Prevent infinite recursion if tmux keeps failing
+	if (retryCount >= MAX_SPAWN_RETRIES) {
+		return {
+			success: false,
+			error: `Failed to spawn agent pane after ${MAX_SPAWN_RETRIES} attempts`,
+		};
+	}
+
+	// Pane kills itself when opencode attach exits (session complete, server died, etc.)
+	// Use shellEscape to prevent shell injection via session IDs
+	const escapedServerUrl = shellEscape(ctx.serverUrl);
+	const escapedSessionId = shellEscape(action.sessionId);
+	const command = `opencode attach ${escapedServerUrl} --session ${escapedSessionId}; tmux kill-pane`;
+	const layout = 'tiled'; // Always use tiled layout for grid arrangement
+
+	// Check if we have a cached agents window ID and if it still exists
+	if (agentsWindowId) {
+		const checkResult = await runTmuxCommand([
+			'list-panes',
+			'-t',
+			agentsWindowId,
+			'-F',
+			'#{pane_id}',
+		]);
+
+		if (!checkResult.success) {
+			// Window no longer exists, clear the cache
+			agentsWindowId = undefined;
+		}
+	}
+
+	// If no agents window exists, create one
+	if (!agentsWindowId) {
+		const createResult = await runTmuxCommand([
+			'new-window',
+			'-d', // Don't switch to new window
+			'-P',
+			'-F',
+			'#{window_id}:#{pane_id}',
+			'-n',
+			'Agents',
+			command,
+		]);
+
+		if (!createResult.success) {
+			return { success: false, error: createResult.output };
+		}
+
+		// Parse window_id:pane_id from output
+		const output = createResult.output?.trim() || '';
+		const [windowId, paneId] = output.split(':');
+		agentsWindowId = windowId;
+
+		// Apply initial layout (useful when more panes are added later)
+		if (agentsWindowId && layout) {
+			await runTmuxCommand(['select-layout', '-t', agentsWindowId, layout]);
+		}
+
+		return { success: true, paneId, windowId };
+	}
+
+	// Agents window exists - split within it
+	// First, get the first pane in the agents window to use as split target
+	const listResult = await runTmuxCommand([
+		'list-panes',
+		'-t',
+		agentsWindowId,
+		'-F',
+		'#{pane_id}',
+	]);
+
+	if (!listResult.success || !listResult.output) {
+		// Fallback: create new window (with retry counter)
+		agentsWindowId = undefined;
+		return spawnInAgentsWindow(action, ctx, retryCount + 1);
+	}
+
+	const targetPaneId = listResult.output.split('\n')[0]?.trim();
+	if (!targetPaneId) {
+		// Fallback: create new window (with retry counter)
+		agentsWindowId = undefined;
+		return spawnInAgentsWindow(action, ctx, retryCount + 1);
+	}
+
+	// Split within the agents window
+	const splitResult = await runTmuxCommand([
+		'split-window',
+		action.splitDirection,
+		'-t',
+		targetPaneId,
+		'-P',
+		'-F',
+		'#{pane_id}',
+		command,
+	]);
+
+	if (!splitResult.success) {
+		return { success: false, error: splitResult.output };
+	}
+
+	const paneId = splitResult.output?.trim();
+
+	// Apply the configured layout to the agents window (e.g., tiled for grid)
+	if (agentsWindowId && layout) {
+		await runTmuxCommand(['select-layout', '-t', agentsWindowId, layout]);
+	}
+
+	return {
+		success: true,
+		paneId: paneId || undefined,
+		windowId: agentsWindowId,
+	};
+}
+
+/**
+ * Reset the agents window state (for cleanup)
+ */
+export function resetAgentsWindow(): void {
+	agentsWindowId = undefined;
+}
+
+/**
+ * Close the agents window if it exists
+ * This kills the entire window, which closes all panes within it
+ */
+export async function closeAgentsWindow(): Promise<void> {
+	if (!agentsWindowId) return;
+
+	// Kill the entire window (closes all panes within it)
+	await runTmuxCommand(['kill-window', '-t', agentsWindowId]);
+	agentsWindowId = undefined;
+}
+
+/**
+ * Synchronously close the agents window (for shutdown)
+ * Uses spawnSync to ensure it completes before process exit
+ */
+export function closeAgentsWindowSync(): void {
+	if (!agentsWindowId) return;
+
+	// Kill the entire window synchronously
+	runTmuxCommandSync(['kill-window', '-t', agentsWindowId]);
+	agentsWindowId = undefined;
+}
+
+/**
+ * Get the current agents window ID (for testing/debugging)
+ */
+export function getAgentsWindowId(): string | undefined {
+	return agentsWindowId;
+}

package/src/tmux/index.ts

@@ -0,0 +1,11 @@
+export * from './types';
+export * from './utils';
+export { queryWindowState } from './state-query';
+export { decideSpawnActions, calculateCapacity } from './decision-engine';
+export {
+	executeAction,
+	executeActions,
+	closeAgentsWindow,
+	closeAgentsWindowSync,
+} from './executor';
+export { TmuxSessionManager } from './manager';

package/src/tmux/manager.ts

@@ -0,0 +1,331 @@
+import type { PluginInput } from '@opencode-ai/plugin';
+import type {
+	PaneAction,
+	TmuxConfig,
+	TmuxPaneInfo,
+	TrackedSession,
+	WindowState,
+	SessionMapping,
+} from './types';
+import { POLL_INTERVAL_MS, SESSION_MISSING_GRACE_MS, SESSION_TIMEOUT_MS } from './types';
+import { getCurrentPaneId, getTmuxPath, isInsideTmux } from './utils';
+import { queryWindowState } from './state-query';
+import { decideSpawnActions } from './decision-engine';
+import {
+	executeActions,
+	closeAgentsWindow,
+	closeAgentsWindowSync,
+	closePaneById,
+} from './executor';
+
+/**
+ * Check if the OpenCode server is running by hitting the health endpoint
+ */
+async function isServerRunning(serverUrl: string): Promise<boolean> {
+	try {
+		const healthUrl = new URL('/health', serverUrl).toString();
+		const response = await fetch(healthUrl, {
+			signal: AbortSignal.timeout(2000),
+		});
+		return response.ok;
+	} catch {
+		return false;
+	}
+}
+
+export interface TmuxSessionManagerCallbacks {
+	onLog?: (message: string) => void;
+}
+
+/**
+ * Manages tmux panes for background agents.
+ *
+ * Architecture:
+ * 1. QUERY: Get actual tmux pane state (source of truth)
+ * 2. DECIDE: Pure function determines actions based on state
+ * 3. EXECUTE: Execute actions with verification
+ * 4. UPDATE: Update internal cache only after tmux confirms success
+ */
+export class TmuxSessionManager {
+	private sessions = new Map<string, TrackedSession>();
+	private pendingSessions = new Set<string>();
+	private pollInterval?: ReturnType<typeof setInterval>;
+	private sourcePaneId: string | undefined;
+
+	constructor(
+		private ctx: PluginInput,
+		private config: TmuxConfig,
+		private callbacks?: TmuxSessionManagerCallbacks
+	) {
+		this.sourcePaneId = getCurrentPaneId();
+	}
+
+	/**
+	 * Check if tmux integration is enabled and available
+	 */
+	isEnabled(): boolean {
+		return this.config.enabled && isInsideTmux();
+	}
+
+	/**
+	 * Handle a new background session being created
+	 * This is called by BackgroundManager when a background task starts
+	 */
+	async onSessionCreated(event: {
+		sessionId: string;
+		parentId: string;
+		title: string;
+	}): Promise<void> {
+		if (!this.isEnabled()) return;
+		if (this.pendingSessions.has(event.sessionId) || this.sessions.has(event.sessionId)) return;
+		this.pendingSessions.add(event.sessionId);
+
+		try {
+			const tmuxPath = await getTmuxPath();
+			if (!tmuxPath) {
+				this.log('tmux binary not found.');
+				return;
+			}
+
+			if (!this.sourcePaneId) {
+				this.sourcePaneId = getCurrentPaneId();
+			}
+
+			if (!this.sourcePaneId) {
+				this.log('Unable to determine source pane id.');
+				return;
+			}
+
+			const state = await queryWindowState(this.sourcePaneId);
+			if (!state) {
+				this.log('Failed to query tmux window state.');
+				return;
+			}
+
+			const decision = decideSpawnActions(
+				state,
+				event.sessionId,
+				event.title,
+				{
+					mainPaneMinWidth: this.config.mainPaneMinWidth,
+					agentPaneMinWidth: this.config.agentPaneMinWidth,
+					maxPanes: this.config.maxPanes,
+				},
+				this.getSessionMappings()
+			);
+
+			if (!decision.canSpawn) {
+				if (decision.reason) {
+					this.log(`Cannot spawn pane: ${decision.reason}`);
+				}
+				return;
+			}
+
+			const serverUrl = this.getServerUrl();
+			if (!serverUrl) {
+				this.log('Unable to determine OpenCode server URL.');
+				return;
+			}
+
+			// Check if server is actually running before attempting to spawn
+			const serverRunning = await isServerRunning(serverUrl);
+			if (!serverRunning) {
+				this.log(
+					`Server not running at ${serverUrl}. Start opencode with --port flag to enable tmux integration.`
+				);
+				return;
+			}
+
+			const result = await executeActions(decision.actions, {
+				config: this.config,
+				serverUrl,
+				windowState: state,
+			});
+
+			if (!result.success) {
+				this.log('Failed to execute tmux actions.');
+				return;
+			}
+
+			this.applyActionResults(decision.actions, result.spawnedPaneId);
+			if (this.sessions.size > 0) {
+				this.startPolling();
+			}
+		} finally {
+			this.pendingSessions.delete(event.sessionId);
+		}
+	}
+
+	/**
+	 * Handle a session being deleted
+	 *
+	 * Explicitly kills the pane when a background session completes.
+	 * We can't rely on `opencode attach` exiting because it's an interactive
+	 * terminal that keeps running even after the session goes idle.
+	 */
+	async onSessionDeleted(event: { sessionId: string }): Promise<void> {
+		if (!this.isEnabled()) return;
+
+		// Find the session in our mappings
+		const session = this.sessions.get(event.sessionId);
+		if (!session) return;
+
+		// Kill the pane explicitly - opencode attach won't exit on its own
+		const result = await closePaneById(session.paneId);
+		if (!result.success) {
+			this.log(`Failed to close pane ${session.paneId}: ${result.error}`);
+		}
+
+		// Update internal state
+		this.sessions.delete(event.sessionId);
+
+		if (this.sessions.size === 0) {
+			this.stopPolling();
+		}
+	}
+
+	/**
+	 * Clean up all panes on shutdown
+	 *
+	 * Kills the entire "Agents" window, which closes all agent panes at once.
+	 */
+	async cleanup(): Promise<void> {
+		this.stopPolling();
+
+		// Kill the entire agents window - this closes all panes at once
+		await closeAgentsWindow();
+		this.sessions.clear();
+	}
+
+	/**
+	 * Synchronous cleanup for shutdown (ensures completion before exit)
+	 *
+	 * Uses spawnSync to guarantee the tmux commands complete before the
+	 * process exits, which is necessary for signal handlers.
+	 */
+	cleanupSync(): void {
+		this.stopPolling();
+
+		// Kill the entire agents window synchronously
+		closeAgentsWindowSync();
+		this.sessions.clear();
+	}
+
+	/**
+	 * Start polling for session status
+	 */
+	private startPolling(): void {
+		if (this.pollInterval) return;
+		this.pollInterval = setInterval(() => {
+			void this.pollSessions();
+		}, POLL_INTERVAL_MS);
+	}
+
+	/**
+	 * Stop polling
+	 */
+	private stopPolling(): void {
+		if (!this.pollInterval) return;
+		clearInterval(this.pollInterval);
+		this.pollInterval = undefined;
+	}
+
+	/**
+	 * Poll active sessions for status changes
+	 */
+	private async pollSessions(): Promise<void> {
+		if (!this.isEnabled()) return;
+		if (!this.sourcePaneId) return;
+
+		const state = await queryWindowState(this.sourcePaneId);
+		if (!state) return;
+
+		const now = Date.now();
+		for (const session of this.sessions.values()) {
+			const pane = findPane(state, session.paneId);
+			if (pane) {
+				session.lastSeenAt = new Date();
+				continue;
+			}
+
+			const missingFor = now - session.lastSeenAt.getTime();
+			if (missingFor > SESSION_MISSING_GRACE_MS) {
+				this.sessions.delete(session.sessionId);
+				continue;
+			}
+
+			const age = now - session.createdAt.getTime();
+			if (age > SESSION_TIMEOUT_MS) {
+				this.sessions.delete(session.sessionId);
+			}
+		}
+
+		if (this.sessions.size === 0) {
+			this.stopPolling();
+		}
+	}
+
+	/**
+	 * Get session mappings for decision engine
+	 */
+	private getSessionMappings(): SessionMapping[] {
+		return Array.from(this.sessions.values()).map((session) => ({
+			sessionId: session.sessionId,
+			paneId: session.paneId,
+			createdAt: session.createdAt,
+		}));
+	}
+
+	private getServerUrl(): string | undefined {
+		const ctx = this.ctx as unknown as {
+			serverUrl?: string | URL;
+			baseUrl?: string | URL;
+			client?: { baseUrl?: string | URL };
+		};
+		const serverUrl = ctx.serverUrl ?? ctx.baseUrl ?? ctx.client?.baseUrl;
+		if (!serverUrl) return undefined;
+		return typeof serverUrl === 'string' ? serverUrl : serverUrl.toString();
+	}
+
+	private applyActionResults(actions: PaneAction[], spawnedPaneId: string | undefined): void {
+		const now = new Date();
+		for (const action of actions) {
+			switch (action.type) {
+				case 'close':
+					this.sessions.delete(action.sessionId);
+					break;
+				case 'replace':
+					this.sessions.delete(action.oldSessionId);
+					this.sessions.set(action.newSessionId, {
+						sessionId: action.newSessionId,
+						paneId: action.paneId,
+						description: action.description,
+						createdAt: now,
+						lastSeenAt: now,
+					});
+					break;
+				case 'spawn': {
+					const paneId = spawnedPaneId;
+					if (!paneId) break;
+					this.sessions.set(action.sessionId, {
+						sessionId: action.sessionId,
+						paneId,
+						description: action.description,
+						createdAt: now,
+						lastSeenAt: now,
+					});
+					break;
+				}
+			}
+		}
+	}
+
+	private log(message: string): void {
+		this.callbacks?.onLog?.(`[tmux] ${message}`);
+	}
+}
+
+function findPane(state: WindowState, paneId: string): TmuxPaneInfo | undefined {
+	if (state.mainPane?.paneId === paneId) return state.mainPane;
+	return state.agentPanes.find((pane) => pane.paneId === paneId);
+}

package/src/tmux/state-query.ts

@@ -0,0 +1,74 @@
+import type { WindowState, TmuxPaneInfo } from './types';
+import { runTmuxCommand } from './utils';
+
+/**
+ * Query the current tmux window state
+ * Returns information about all panes in the current window
+ */
+export async function queryWindowState(sourcePaneId: string): Promise<WindowState | null> {
+	const result = await runTmuxCommand([
+		'list-panes',
+		'-t',
+		sourcePaneId,
+		'-F',
+		'#{pane_id},#{pane_width},#{pane_height},#{pane_left},#{pane_top},#{pane_title},#{pane_active},#{window_width},#{window_height}',
+	]);
+
+	if (!result.success) {
+		return null;
+	}
+
+	const lines = result.output
+		.split('\n')
+		.map((line) => line.trim())
+		.filter(Boolean);
+	if (lines.length === 0) return null;
+
+	const panes: TmuxPaneInfo[] = [];
+	let windowWidth = 0;
+	let windowHeight = 0;
+
+	for (const line of lines) {
+		const parts = line.split(',');
+		if (parts.length < 9) continue;
+
+		const windowWidthValue = Number(parts[parts.length - 2]);
+		const windowHeightValue = Number(parts[parts.length - 1]);
+		const isActiveValue = parts[parts.length - 3] === '1';
+		const title = parts.slice(5, parts.length - 3).join(',');
+
+		const width = Number(parts[1]);
+		const height = Number(parts[2]);
+		const left = Number(parts[3]);
+		const top = Number(parts[4]);
+		if ([width, height, left, top].some((value) => Number.isNaN(value))) {
+			continue;
+		}
+
+		const paneInfo: TmuxPaneInfo = {
+			paneId: parts[0],
+			width,
+			height,
+			left,
+			top,
+			title,
+			isActive: isActiveValue,
+		};
+
+		if (!Number.isNaN(windowWidthValue)) windowWidth = windowWidthValue;
+		if (!Number.isNaN(windowHeightValue)) windowHeight = windowHeightValue;
+		panes.push(paneInfo);
+	}
+
+	if (panes.length === 0) return null;
+
+	const mainPane = panes.find((pane) => pane.paneId === sourcePaneId) ?? null;
+	const agentPanes = panes.filter((pane) => pane.paneId !== sourcePaneId);
+
+	return {
+		windowWidth,
+		windowHeight,
+		mainPane,
+		agentPanes,
+	};
+}