Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

10.2 KB
Raw Blame
import { useCallback, useEffect, useRef, useState } from 'react';
import { useNavigate } from 'react-router';
import { useSocket } from './useSocket';
import { useThemeContext } from '../components/ThemeContext';
import {
  createShellTerminal,
  readTerminalTheme,
  TERMINAL_SCROLLBACK_LINES,
} from '../components/shell/createShellTerminal';
import { attachDictationBridge } from '../lib/terminalDictation';

export const ITERM_SHELL_PATH = '/shell/iterm';

/**
 * useItermSession — socket + terminal state for the Shell page's iTerm2 view
 * (#8114). Sibling of useShellSession, but it speaks ONLY the `iterm:*` events,
 * so an iTerm2 session never enters the PortOS shell tab strip or registry.
 *
 * Differences from a PortOS PTY that shape this hook:
 *   - iTerm2 owns the size. The terminal is sized to the server-reported grid
 *     with `term.resize(cols, rows)` (never fit to the container, never a
 *     resize event back), and the container scrolls when narrower.
 *   - Many viewers may watch one session, so there is no claim/detached dance:
 *     attaching only adds this socket as a viewer.
 *   - PortOS cannot create, stop or restart iTerm2 sessions.
 *
 * The selected session lives in the URL (`/shell/iterm/:itermSessionId`).
 * With no id, the first listed session is selected with a replace navigation;
 * an id the connected bridge no longer lists falls back to the view root.
 * `pendingRef = { target, generation }` gates `iterm:attached` by strict
 * equality so a response for a session the user already left is dropped.
 *
 * @param {object} params
 * @param {string|undefined} params.itermSessionId - selection from the URL
 * @param {boolean} params.enabled - false while the feature is off: no subscription
 */
export function useItermSession({ itermSessionId, enabled = true } = {}) {
  const socket = useSocket();
  const navigate = useNavigate();
  // navigate's identity can change per location; keep it out of the socket
  // effect's deps so a selection never tears down the list subscription.
  const navigateRef = useRef(navigate);
  useEffect(() => { navigateRef.current = navigate; }, [navigate]);
  const { themeId, theme: activeTheme } = useThemeContext();
  const themeMode = activeTheme?.mode ?? 'night';
  const terminalRef = useRef(null);
  const termRef = useRef(null);
  const attachedIdRef = useRef(null);
  const pendingRef = useRef({ target: null, generation: 0 });
  const [sessions, setSessions] = useState(null); // null = not listed yet
  const [status, setStatus] = useState(null);
  const [attachedId, setAttachedId] = useState(null);

  const setPending = useCallback((target) => {
    pendingRef.current = { target, generation: pendingRef.current.generation + 1 };
  }, []);

  // Terminal lifetime = component lifetime.
  useEffect(() => {
    if (!enabled || !terminalRef.current || termRef.current) return undefined;
    termRef.current = createShellTerminal(terminalRef.current, {
      scrollback: TERMINAL_SCROLLBACK_LINES,
      cursorBlink: false,
    });
    return () => {
      termRef.current?.dispose();
      termRef.current = null;
    };
  }, [enabled]);

  useEffect(() => {
    if (termRef.current) termRef.current.options.theme = readTerminalTheme();
  }, [themeId, themeMode]);

  const sizeTo = useCallback((cols, rows) => {
    const term = termRef.current;
    if (!term || !(cols > 0) || !(rows > 0)) return;
    if (term.cols !== cols || term.rows !== rows) term.resize(cols, rows);
  }, []);

  const emitInput = useCallback((data, { focus = true } = {}) => {
    const id = attachedIdRef.current;
    if (!socket || !id || pendingRef.current.target) return false;
    socket.emit('iterm:input', { id, data });
    if (focus) termRef.current?.focus();
    return true;
  }, [socket]);

  // Keystrokes typed into the terminal go to the viewed iTerm2 session verbatim.
  // Dictation takes the bridge (lib/terminalDictation.js): the terminal runs in
  // screen-reader mode, where xterm drops the insertText events dictation fires.
  useEffect(() => {
    const term = termRef.current;
    if (!term) return undefined;
    const send = (data) => emitInput(data, { focus: false });
    const disposable = term.onData(send);
    const detachDictation = attachDictationBridge(term, send);
    return () => {
      detachDictation();
      disposable.dispose();
    };
  }, [emitInput, enabled]);

  // List subscription + event wiring.
  useEffect(() => {
    if (!socket || !enabled) return undefined;

    const handleConnect = () => socket.emit('iterm:list');
    // The server drops a disconnected socket's views, so forget ours too; the
    // null list makes the URL effect re-attach once the reconnect re-lists.
    const handleDisconnect = () => {
      attachedIdRef.current = null;
      setAttachedId(null);
      setPending(null);
      setSessions(null);
    };
    const handleSessions = ({ sessions: list, status: nextStatus } = {}) => {
      setSessions(Array.isArray(list) ? list : []);
      setStatus(nextStatus ?? null);
      const active = list?.find?.((s) => s.id === attachedIdRef.current);
      if (active) sizeTo(active.cols, active.rows);
    };
    const handleAttached = ({ id, cols, rows, bufferedOutput }) => {
      if (pendingRef.current.target !== id) return;
      setPending(null);
      attachedIdRef.current = id;
      setAttachedId(id);
      const term = termRef.current;
      if (!term) return;
      term.reset();
      sizeTo(cols, rows);
      if (bufferedOutput) term.write(bufferedOutput);
    };
    const handleOutput = ({ id, data, reset = false, scrollbackRows = 0 }) => {
      if (id !== attachedIdRef.current || pendingRef.current.target) return;
      const term = termRef.current;
      if (!term) return;
      if (reset) {
        term.reset();
        term.write(data);
        return;
      }
      const rows = Number.isInteger(scrollbackRows) ? Math.max(0, scrollbackRows) : 0;
      const advance = rows > 0 && term.rows > 0
        ? `\x1b[${term.rows};1H${'\n'.repeat(Math.min(rows, term.rows))}`
        : '';
      term.write(`${advance}${data}`);
    };
    const handleExit = ({ id }) => {
      if (id !== attachedIdRef.current) return;
      attachedIdRef.current = null;
      setAttachedId(null);
      termRef.current?.writeln('\r\n\x1b[33m[iTerm2 session closed]\x1b[0m');
      // No navigation here: the bridge also sends this when its iTerm2
      // connection drops, and the URL must survive that. The next list
      // decides — re-attach if it is back, fall back if it is really gone.
    };
    const handleError = ({ id, error, code }) => {
      // A host-control refusal (#8708) may answer the uncorrelated list request.
      const refused = code === 'HOST_CONTROL_FORBIDDEN';
      if (!refused && id !== pendingRef.current.target && id !== attachedIdRef.current) return;
      if (id === pendingRef.current.target) setPending(null);
      termRef.current?.writeln(`\r\n\x1b[31m[Error: ${error}]\x1b[0m`);
    };

    socket.on('connect', handleConnect);
    socket.on('disconnect', handleDisconnect);
    socket.on('iterm:sessions', handleSessions);
    socket.on('iterm:attached', handleAttached);
    socket.on('iterm:output', handleOutput);
    socket.on('iterm:exit', handleExit);
    socket.on('iterm:error', handleError);
    if (socket.connected) handleConnect();

    return () => {
      socket.off('connect', handleConnect);
      socket.off('disconnect', handleDisconnect);
      socket.off('iterm:sessions', handleSessions);
      socket.off('iterm:attached', handleAttached);
      socket.off('iterm:output', handleOutput);
      socket.off('iterm:exit', handleExit);
      socket.off('iterm:error', handleError);
      if (socket.connected) {
        const viewing = attachedIdRef.current ?? pendingRef.current.target;
        if (viewing) socket.emit('iterm:detach', { id: viewing });
        socket.emit('iterm:unlist');
      }
      attachedIdRef.current = null;
    };
  }, [socket, enabled, setPending, sizeTo]);

  const sessionIds = sessions?.map((s) => s.id).join('\n') ?? null;
  // Only a connected bridge's list is authoritative about what exists; while
  // iTerm2 is reconnecting the list is empty and the URL must stay put.
  const listAuthoritative = status?.state === 'connected';

  // URL → attachment. No id: select the first session. Unknown id once the
  // list is in: fall back to the view root rather than a dead deep link.
  useEffect(() => {
    if (!socket || !enabled || sessionIds === null) return;
    const ids = sessionIds ? sessionIds.split('\n') : [];
    if (!itermSessionId) {
      if (ids.length > 0) navigateRef.current(`${ITERM_SHELL_PATH}/${ids[0]}`, { replace: true });
      return;
    }
    if (!ids.includes(itermSessionId)) {
      if (listAuthoritative) navigateRef.current(ITERM_SHELL_PATH, { replace: true });
      return;
    }
    if (attachedIdRef.current === itermSessionId || pendingRef.current.target === itermSessionId) return;
    // Stop viewing whatever this replaces — including an attach still in
    // flight, whose late reply the pending guard will drop.
    const superseded = attachedIdRef.current ?? pendingRef.current.target;
    if (superseded) socket.emit('iterm:detach', { id: superseded });
    attachedIdRef.current = null;
    setAttachedId(null);
    setPending(itermSessionId);
    const term = termRef.current;
    if (term) {
      term.reset();
      term.writeln('\x1b[36mAttaching to iTerm2 session...\x1b[0m');
    }
    socket.emit('iterm:attach', { id: itermSessionId });
  }, [socket, enabled, itermSessionId, sessionIds, listAuthoritative, setPending]);

  const selectSession = useCallback((id) => {
    if (id !== itermSessionId) navigateRef.current(`${ITERM_SHELL_PATH}/${id}`);
  }, [itermSessionId]);

  const sendNavKey = useCallback((key) => {
    // The frames carry no DECCKM state, so arrows always go out in CSI form,
    // which shells, vim and Claude Code all accept.
    emitInput(key.seq ?? `\x1b[${key.code}`, { focus: false });
  }, [emitInput]);

  const activeSession = sessions?.find((s) => s.id === attachedId) ?? null;

  return {
    terminalRef,
    sessions: sessions ?? [],
    listed: sessions !== null,
    status,
    activeSession,
    connected: Boolean(attachedId),
    selectSession,
    emitInput,
    sendCtrlB: () => emitInput('\x02'),
    sendCtrlC: () => emitInput('\x03'),
    sendEsc: () => emitInput('\x1b'),
    sendNavKey,
  };
}