Files
Codeman/src/mux-interface.ts
T

167 lines
5.0 KiB
TypeScript
Raw Normal View History

2026-02-12 10:29:57 +01:00
/**
2026-02-18 12:51:35 +01:00
* @fileoverview Terminal multiplexer abstraction layer (tmux).
2026-02-12 10:29:57 +01:00
*
2026-02-18 12:51:35 +01:00
* Defines the TerminalMultiplexer interface that TmuxManager implements.
2026-02-12 10:29:57 +01:00
*
* @module mux-interface
*/
import type { EventEmitter } from 'node:events';
import type { ProcessStats, PersistedRespawnConfig, NiceConfig } from './types.js';
/**
2026-02-18 12:51:35 +01:00
* Multiplexer session metadata.
2026-02-12 10:29:57 +01:00
*/
export interface MuxSession {
/** Claudeman session ID */
sessionId: string;
/** Multiplexer session name (e.g., "claudeman-abc12345") */
muxName: string;
/** Process PID */
pid: number;
/** Timestamp when created */
createdAt: number;
/** Working directory */
workingDir: string;
/** Session mode: claude or shell */
mode: 'claude' | 'shell';
/** Whether webserver is attached to this session */
attached: boolean;
/** Session display name (tab name) */
name?: string;
/** Persisted respawn controller configuration (restored on server restart) */
respawnConfig?: PersistedRespawnConfig;
/** Whether Ralph / Todo tracking is enabled */
ralphEnabled?: boolean;
}
/**
* MuxSession with optional process resource statistics.
*/
export interface MuxSessionWithStats extends MuxSession {
/** Optional resource statistics */
stats?: ProcessStats;
}
/**
* Terminal multiplexer interface.
*
2026-02-18 12:51:35 +01:00
* Implemented by TmuxManager.
2026-02-12 10:29:57 +01:00
*
* Events emitted:
* - `sessionCreated` (session: MuxSession) - New session created
* - `sessionKilled` (data: { sessionId: string }) - Session terminated
* - `sessionDied` (data: { sessionId: string }) - Session died unexpectedly
* - `statsUpdated` (sessions: MuxSessionWithStats[]) - Stats refreshed
*/
export interface TerminalMultiplexer extends EventEmitter {
/** Which backend this instance uses */
2026-02-18 12:51:35 +01:00
readonly backend: 'tmux';
2026-02-12 10:29:57 +01:00
// ========== Lifecycle ==========
/**
* Create a new multiplexer session.
* The session runs the appropriate command (claude or shell) in detached mode.
*/
createSession(
sessionId: string,
workingDir: string,
mode: 'claude' | 'shell',
name?: string,
niceConfig?: NiceConfig,
2026-02-18 23:14:39 +01:00
model?: string,
2026-02-12 10:29:57 +01:00
): Promise<MuxSession>;
/**
* Kill a session and all its child processes.
* Uses a multi-strategy approach (children → process group → mux kill → SIGKILL).
*/
killSession(sessionId: string): Promise<boolean>;
/** Clean up resources (stop stats collection, etc.) */
destroy(): void;
// ========== Queries ==========
/** Get all tracked sessions */
getSessions(): MuxSession[];
/** Get a session by Claudeman session ID */
getSession(sessionId: string): MuxSession | undefined;
/** Get all sessions with process resource statistics */
getSessionsWithStats(): Promise<MuxSessionWithStats[]>;
/** Get process stats for a single session */
getProcessStats(sessionId: string): Promise<ProcessStats | null>;
// ========== Input ==========
/**
2026-02-18 12:51:35 +01:00
* Send input to a session via tmux send-keys.
2026-02-12 10:29:57 +01:00
*/
sendInput(sessionId: string, input: string): Promise<boolean>;
2026-02-12 10:29:57 +01:00
// ========== Metadata ==========
/** Update the display name of a session */
updateSessionName(sessionId: string, name: string): boolean;
/** Mark session as attached/detached */
setAttached(sessionId: string, attached: boolean): void;
/** Register an externally-created session for tracking */
registerSession(session: MuxSession): void;
/** Update persisted respawn config for a session */
updateRespawnConfig(sessionId: string, config: PersistedRespawnConfig | undefined): void;
/** Clear respawn config when respawn is stopped */
clearRespawnConfig(sessionId: string): void;
/** Update Ralph enabled state for a session */
updateRalphEnabled(sessionId: string, enabled: boolean): void;
// ========== Discovery ==========
/**
* Reconcile tracked sessions with actual running sessions.
* Finds dead sessions and discovers unknown ones.
*/
reconcileSessions(): Promise<{ alive: string[]; dead: string[]; discovered: string[] }>;
// ========== Stats Collection ==========
/** Start periodic process stats collection */
startStatsCollection(intervalMs?: number): void;
/** Stop periodic process stats collection */
stopStatsCollection(): void;
// ========== PTY Attachment ==========
/**
2026-02-18 12:51:35 +01:00
* Get the command to spawn for attaching to a session ('tmux').
2026-02-12 10:29:57 +01:00
*/
getAttachCommand(): string;
/**
* Get the arguments for attaching to a session by mux name.
*/
getAttachArgs(muxName: string): string[];
// ========== Availability ==========
/** Check if the multiplexer binary is available on the system */
isAvailable(): boolean;
/** Check if a multiplexer session actually exists (process-level check, not just tracked) */
muxSessionExists(muxName: string): boolean;
/** Check if the pane in a session is dead (command exited but remain-on-exit keeps it alive) */
isPaneDead(muxName: string): boolean;
/** Respawn a dead pane with a fresh command. Returns the new PID or null on failure. */
respawnPane(sessionId: string, workingDir: string, mode: 'claude' | 'shell', niceConfig?: NiceConfig, model?: string): Promise<number | null>;
2026-02-12 10:29:57 +01:00
}