@phenx-inc/ctlsurf 0.11.0 → 0.12.0

package/src/main/ssh.ts

@@ -0,0 +1,348 @@
+/**
+ * Remote SSH support
+ *
+ * Lets a tab run a coding agent on a remote machine by spawning `ssh` in the
+ * local PTY (see pty.ts) instead of the agent binary directly. Because every
+ * byte still flows through the PTY, the agent-state monitor (agentState.ts)
+ * keeps driving the dock "awaiting input" indicator for remote agents.
+ *
+ * Design notes:
+ * - Hosts come from the user's own ~/.ssh/config (key-based auth). A short MRU
+ *   list of recently-used targets is kept for quick reconnect.
+ * - We never store passwords. For hosts that need a password, ssh's own prompt
+ *   collects it over the PTY — it never passes through our code/args/env/disk.
+ *   That also means we can't enumerate tmux sessions non-interactively for such
+ *   hosts (BatchMode is rejected), so we fall back to an attach-or-create
+ *   bootstrap that runs entirely on the remote.
+ * - tmux keeps the remote agent alive across SSH drops; sessions are named
+ *   `ctlsurf_N` so several can coexist and be reattached.
+ */
+
+import fs from 'fs'
+import os from 'os'
+import path from 'path'
+import { spawn } from 'child_process'
+import { AgentConfig } from './agents'
+
+/** Prefix for tmux sessions this app creates, so reconnects can find them. */
+export const TMUX_SESSION_PREFIX = 'ctlsurf_'
+
+export interface SshHost {
+  /** The `Host` alias as written in ~/.ssh/config (what you pass to `ssh`). */
+  alias: string
+  /** Resolved HostName, if the config specifies one (for display only). */
+  hostName?: string
+  /** Configured User, if any (for display only). */
+  user?: string
+}
+
+export interface SshHostList {
+  configHosts: SshHost[]
+  recents: string[]
+}
+
+export interface ProbeResult {
+  /** A usable, key-authenticated connection was established. */
+  reachable: boolean
+  /**
+   * Reachable network-wise but key auth was refused (host likely wants a
+   * password). We can't enumerate tmux here; the UI should offer the
+   * interactive attach-or-create path instead.
+   */
+  authRequired: boolean
+  /** Human-readable reason when reachable is false. */
+  error?: string
+  /** Whether tmux is installed on the remote. */
+  tmuxInstalled: boolean
+  /** All tmux session names found on the remote. */
+  sessions: string[]
+  /** Sessions created by this app (prefix `ctlsurf_`). */
+  ctlsurfSessions: string[]
+}
+
+// ─── ~/.ssh/config parsing ─────────────────────────
+
+/**
+ * Parse ~/.ssh/config into concrete Host aliases. Wildcard patterns (`*`, `?`)
+ * are skipped — they're match rules, not connectable targets. Negated tokens
+ * (`!pattern`) are ignored too. Best-effort: unknown directives are skipped and
+ * a malformed file yields an empty list rather than throwing.
+ */
+export function listSshHosts(configPath?: string): SshHost[] {
+  const file = configPath || path.join(os.homedir(), '.ssh', 'config')
+  let raw: string
+  try {
+    raw = fs.readFileSync(file, 'utf-8')
+  } catch {
+    return []
+  }
+
+  const hosts: SshHost[] = []
+  // Aliases declared on the current `Host` line; later HostName/User apply to all.
+  let current: SshHost[] = []
+
+  const flush = () => {
+    for (const h of current) hosts.push(h)
+    current = []
+  }
+
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim()
+    if (!trimmed || trimmed.startsWith('#')) continue
+
+    // Directives are "Keyword value..." separated by whitespace or '='.
+    const m = trimmed.match(/^(\S+)[\s=]+(.+)$/)
+    if (!m) continue
+    const keyword = m[1].toLowerCase()
+    const value = m[2].trim()
+
+    if (keyword === 'host') {
+      flush()
+      const aliases = value
+        .split(/\s+/)
+        .filter((a) => a && !a.includes('*') && !a.includes('?') && !a.startsWith('!'))
+      current = aliases.map((alias) => ({ alias }))
+    } else if (keyword === 'hostname') {
+      for (const h of current) h.hostName = value
+    } else if (keyword === 'user') {
+      for (const h of current) h.user = value
+    }
+  }
+  flush()
+
+  // De-dupe by alias, preserving first occurrence (ssh's own precedence).
+  const seen = new Set<string>()
+  return hosts.filter((h) => (seen.has(h.alias) ? false : (seen.add(h.alias), true)))
+}
+
+// ─── Recent hosts (MRU) ────────────────────────────
+
+const RECENTS_FILE = 'ssh-recents.json'
+const MAX_RECENTS = 8
+
+function recentsPath(settingsDir: string): string {
+  return path.join(settingsDir, RECENTS_FILE)
+}
+
+export function getRecentHosts(settingsDir: string): string[] {
+  try {
+    const raw = JSON.parse(fs.readFileSync(recentsPath(settingsDir), 'utf-8'))
+    if (Array.isArray(raw)) return raw.filter((x) => typeof x === 'string')
+  } catch {
+    /* no recents yet */
+  }
+  return []
+}
+
+/** Record `target` as most-recently-used (newest first, de-duped, capped). */
+export function addRecentHost(settingsDir: string, target: string): void {
+  const t = target.trim()
+  if (!t) return
+  const next = [t, ...getRecentHosts(settingsDir).filter((x) => x !== t)].slice(0, MAX_RECENTS)
+  try {
+    fs.mkdirSync(settingsDir, { recursive: true })
+    fs.writeFileSync(recentsPath(settingsDir), JSON.stringify(next, null, 2))
+  } catch {
+    /* non-fatal: recents are a convenience */
+  }
+}
+
+// ─── Non-interactive probe ─────────────────────────
+
+// Remote one-liner: prove tmux presence, then list sessions. Markers let us
+// parse a single combined stdout stream regardless of shell chrome.
+const PROBE_REMOTE_CMD =
+  'command -v tmux >/dev/null 2>&1 && echo __TMUX_OK__; tmux ls 2>/dev/null; echo __DONE__'
+
+/**
+ * Probe a remote host without any interaction. Uses BatchMode so it fails fast
+ * (rather than hanging on a password prompt) when key auth isn't available —
+ * that case is reported as `authRequired`, signalling the UI to use the
+ * interactive path. Only meaningful for key-authenticated hosts.
+ */
+export function probeRemote(target: string): Promise<ProbeResult> {
+  return new Promise((resolve) => {
+    const args = [
+      '-o', 'BatchMode=yes',
+      '-o', 'ConnectTimeout=8',
+      '-o', 'StrictHostKeyChecking=accept-new',
+      target,
+      PROBE_REMOTE_CMD,
+    ]
+    let stdout = ''
+    let stderr = ''
+    let settled = false
+    const done = (r: ProbeResult) => {
+      if (settled) return
+      settled = true
+      resolve(r)
+    }
+
+    let child: ReturnType<typeof spawn>
+    try {
+      child = spawn('ssh', args, { stdio: ['ignore', 'pipe', 'pipe'] })
+    } catch (err: any) {
+      done({ reachable: false, authRequired: false, error: err?.message || 'spawn failed', tmuxInstalled: false, sessions: [], ctlsurfSessions: [] })
+      return
+    }
+
+    // Hard ceiling in case ssh wedges despite ConnectTimeout.
+    const killTimer = setTimeout(() => {
+      try { child.kill() } catch { /* already gone */ }
+      done({ reachable: false, authRequired: false, error: 'Timed out connecting', tmuxInstalled: false, sessions: [], ctlsurfSessions: [] })
+    }, 12_000)
+
+    child.stdout?.on('data', (d) => { stdout += d.toString() })
+    child.stderr?.on('data', (d) => { stderr += d.toString() })
+
+    child.on('error', (err) => {
+      clearTimeout(killTimer)
+      done({ reachable: false, authRequired: false, error: err.message, tmuxInstalled: false, sessions: [], ctlsurfSessions: [] })
+    })
+
+    child.on('close', (code) => {
+      clearTimeout(killTimer)
+      if (!stdout.includes('__DONE__')) {
+        // The remote command never ran → couldn't connect/authenticate.
+        const authRequired = /permission denied|password|publickey/i.test(stderr)
+        const error = authRequired
+          ? 'Key auth refused (password required)'
+          : (stderr.trim().split('\n').pop() || `ssh exited ${code}`)
+        done({ reachable: false, authRequired, error, tmuxInstalled: false, sessions: [], ctlsurfSessions: [] })
+        return
+      }
+      const tmuxInstalled = stdout.includes('__TMUX_OK__')
+      const sessions = parseTmuxSessions(stdout)
+      done({
+        reachable: true,
+        authRequired: false,
+        tmuxInstalled,
+        sessions,
+        ctlsurfSessions: sessions.filter((s) => s.startsWith(TMUX_SESSION_PREFIX)),
+      })
+    })
+  })
+}
+
+// ─── Password prompt detection (for one-shot injection) ────
+
+/** Remove ANSI escape sequences so a colon-terminated prompt matches cleanly. */
+export function stripAnsiSeq(s: string): string {
+  return s.replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, '')
+}
+
+// ssh's password/passphrase prompts, e.g. "user@host's password: " or
+// "Enter passphrase for key '/path': ". Anchored to end-of-buffer so it only
+// fires on the live prompt, not on the word appearing mid-output.
+const PASSWORD_PROMPT_RE = /(?:password|passphrase)[^\n]*:\s*$/i
+
+/** Whether the (ANSI-stripped) trailing output is sitting at a password prompt. */
+export function isPasswordPrompt(tail: string): boolean {
+  return PASSWORD_PROMPT_RE.test(tail)
+}
+
+/** Extract session names from `tmux ls` output ("name: 1 windows ..." per line). */
+export function parseTmuxSessions(stdout: string): string[] {
+  const out: string[] = []
+  for (const line of stdout.split('\n')) {
+    const t = line.trim()
+    if (!t || t.startsWith('__')) continue
+    const m = t.match(/^([^:\s]+):/)
+    if (m) out.push(m[1])
+  }
+  return out
+}
+
+/** Lowest free `ctlsurf_N` (N >= 1) given the sessions already on the host. */
+export function nextSessionName(existing: string[]): string {
+  const used = new Set(
+    existing
+      .filter((s) => s.startsWith(TMUX_SESSION_PREFIX))
+      .map((s) => parseInt(s.slice(TMUX_SESSION_PREFIX.length), 10))
+      .filter((n) => Number.isInteger(n) && n > 0),
+  )
+  let n = 1
+  while (used.has(n)) n++
+  return `${TMUX_SESSION_PREFIX}${n}`
+}
+
+// ─── Remote command builder ────────────────────────
+
+export type RemoteAction =
+  /** Reattach an existing tmux session. */
+  | { kind: 'attach'; session: string }
+  /** Create (or attach, via -A) a tmux session running the agent. */
+  | { kind: 'new-tmux'; session: string }
+  /** Run the agent directly, no tmux (no persistence). */
+  | { kind: 'no-tmux' }
+  /** Password hosts: let the remote decide attach-or-create vs bare agent. */
+  | { kind: 'auto'; session: string }
+
+export interface BuildRemoteOptions {
+  /** SSH target: a ~/.ssh/config alias or `user@host`. */
+  target: string
+  action: RemoteAction
+  /** Remote command to run as the agent. Empty string = remote login shell. */
+  agentCmd?: string
+}
+
+// Single-quote a string for safe embedding in a remote sh command.
+function shQuote(s: string): string {
+  return `'${s.replace(/'/g, `'\\''`)}'`
+}
+
+function remoteCommandFor(action: RemoteAction, agentCmd: string): string {
+  const inner = agentCmd.trim() // e.g. "claude"; empty → shell
+  switch (action.kind) {
+    case 'attach':
+      return `tmux attach -t ${shQuote(action.session)}`
+    case 'new-tmux':
+      // -A: attach if the session somehow already exists, else create it.
+      return inner
+        ? `tmux new-session -A -s ${shQuote(action.session)} ${shQuote(inner)}`
+        : `tmux new-session -A -s ${shQuote(action.session)}`
+    case 'no-tmux':
+      return inner
+    case 'auto':
+      // Password host: probe + branch entirely on the remote so we never need
+      // a second (password-prompting) connection.
+      return inner
+        ? `if command -v tmux >/dev/null 2>&1; then tmux new-session -A -s ${shQuote(action.session)} ${shQuote(inner)}; else ${inner}; fi`
+        : `if command -v tmux >/dev/null 2>&1; then tmux new-session -A -s ${shQuote(action.session)}; else exec "$SHELL" -l; fi`
+  }
+}
+
+/**
+ * Build an AgentConfig that runs the chosen remote action via `ssh` in the PTY.
+ * The id is prefixed `remote-` so isRemoteAgent()/isCodingAgent() keep the tab
+ * out of local-only plumbing (transcripts, ctlsurf worker socket) while the
+ * always-on state monitor still drives the dock indicator.
+ */
+export function buildRemoteAgent(opts: BuildRemoteOptions): AgentConfig {
+  const { target, action } = opts
+  const agentCmd = opts.agentCmd ?? 'claude'
+  const remoteCmd = remoteCommandFor(action, agentCmd)
+
+  // `-t` forces a pseudo-terminal so the remote TUI (tmux/claude) renders.
+  const args = remoteCmd ? ['-t', target, remoteCmd] : ['-t', target]
+
+  const safeTarget = target.replace(/[^a-zA-Z0-9_.@-]/g, '_')
+  const label =
+    action.kind === 'attach' ? action.session
+      : action.kind === 'new-tmux' || action.kind === 'auto' ? action.session
+        : 'direct'
+
+  const agentLabel = agentCmd.trim() || 'shell'
+  const desc =
+    action.kind === 'attach' ? `SSH ${target} → attach tmux ${action.session}`
+      : action.kind === 'no-tmux' ? `SSH ${target} → ${agentLabel}`
+        : `SSH ${target} → tmux ${('session' in action) ? action.session : ''} → ${agentLabel}`
+
+  return {
+    id: `remote-${safeTarget}-${label}`,
+    name: `${target} · ${label}`,
+    command: 'ssh',
+    args,
+    description: desc,
+  }
+}

package/src/preload/index.ts

@@ -39,6 +39,32 @@ const api = {
   getDefaultAgent: (): Promise<AgentConfig> =>
     ipcRenderer.invoke('agents:default'),
 
+  // Remote (SSH)
+  sshListHosts: (): Promise<{
+    configHosts: Array<{ alias: string; hostName?: string; user?: string }>
+    recents: string[]
+  }> => ipcRenderer.invoke('ssh:listHosts'),
+  sshProbe: (target: string): Promise<{
+    reachable: boolean
+    authRequired: boolean
+    error?: string
+    tmuxInstalled: boolean
+    sessions: string[]
+    ctlsurfSessions: string[]
+  }> => ipcRenderer.invoke('ssh:probe', target),
+  sshBuildAgent: (target: string, action: unknown, agentCmd?: string): Promise<AgentConfig> =>
+    ipcRenderer.invoke('ssh:buildAgent', target, action, agentCmd),
+  sshAddRecent: (target: string): Promise<{ ok: boolean }> =>
+    ipcRenderer.invoke('ssh:addRecent', target),
+  sshSetPassword: (target: string, password: string): Promise<{ ok: boolean }> =>
+    ipcRenderer.invoke('ssh:setPassword', target, password),
+
+  // ctlsurf project selection (for remote sessions)
+  listProjects: (): Promise<{ ok: boolean; projects: Array<{ id: string; name: string; root_path: string }>; error?: string }> =>
+    ipcRenderer.invoke('ctlsurf:listProjects'),
+  bindProject: (rootPath: string): Promise<{ ok: boolean; error?: string }> =>
+    ipcRenderer.invoke('ctlsurf:bindProject', rootPath),
+
   // App info
   getHomePath: (): Promise<string> =>
     ipcRenderer.invoke('app:homePath'),

package/src/renderer/App.tsx

@@ -5,6 +5,7 @@ import { SpeakControls } from './components/SpeakControls'
 import { CtlsurfPanel } from './components/CtlsurfPanel'
 import { EditorPanel } from './components/EditorPanel'
 import { AgentPicker } from './components/AgentPicker'
+import { ProjectPicker } from './components/ProjectPicker'
 import {
   PaneLayout,
   type LayoutNode,
@@ -36,6 +37,13 @@ declare global {
       onPtyExit: (callback: (tabId: string, code: number) => void) => () => void
       listAgents: () => Promise<AgentConfig[]>
       getDefaultAgent: () => Promise<AgentConfig>
+      sshListHosts: () => Promise<{ configHosts: Array<{ alias: string; hostName?: string; user?: string }>; recents: string[] }>
+      sshProbe: (target: string) => Promise<{ reachable: boolean; authRequired: boolean; error?: string; tmuxInstalled: boolean; sessions: string[]; ctlsurfSessions: string[] }>
+      sshBuildAgent: (target: string, action: unknown, agentCmd?: string) => Promise<AgentConfig>
+      sshAddRecent: (target: string) => Promise<{ ok: boolean }>
+      sshSetPassword: (target: string, password: string) => Promise<{ ok: boolean }>
+      listProjects: () => Promise<{ ok: boolean; projects: Array<{ id: string; name: string; root_path: string }>; error?: string }>
+      bindProject: (rootPath: string) => Promise<{ ok: boolean; error?: string }>
       getHomePath: () => Promise<string>
       getCwd: () => Promise<string>
       getProjectName: () => Promise<string | null>
@@ -155,6 +163,9 @@ export default function App() {
   // Agent picker state: which tab is being configured (null = initial picker for first tab)
   const [pickerTargetTabId, setPickerTargetTabId] = useState<string | null>(tabs[0].id)
   const [showAgentPicker, setShowAgentPicker] = useState(true)
+  // Project picker: shown right after a remote (SSH) session connects, to bind
+  // it to a ctlsurf project.
+  const [showProjectPicker, setShowProjectPicker] = useState(false)
 
   // Track which panes are in the layout tree
   const visiblePaneIds = findPaneIds(layout)
@@ -316,6 +327,11 @@ export default function App() {
     }
     setShowAgentPicker(false)
     setPickerTargetTabId(null)
+    // Remote (SSH) sessions have no meaningful local cwd, so prompt the user to
+    // bind this session to a ctlsurf project once the terminal is up.
+    if (agent.id.startsWith('remote-')) {
+      setShowProjectPicker(true)
+    }
   }, [pickerTargetTabId, tabs])
 
   const closeTab = useCallback(async (tabId: string) => {
@@ -608,6 +624,10 @@ export default function App() {
         />
       )}
 
+      {showProjectPicker && (
+        <ProjectPicker onDone={() => setShowProjectPicker(false)} />
+      )}
+
       {showFloatingMic && (
         <FloatingMic
           onTranscript={handleVoiceTranscript}

package/src/renderer/components/AgentPicker.tsx

@@ -1,4 +1,5 @@
 import { useEffect, useState } from 'react'
+import { RemoteConnect } from './RemoteConnect'
 
 interface AgentConfig {
   id: string
@@ -19,6 +20,7 @@ export function AgentPicker({ agents, cwd, onSelect, onChangeCwd }: AgentPickerP
   const displayPath = cwd.replace(/^\/Users\/[^/]+/, '~')
   const [logChat, setLogChat] = useState(false)
   const [loaded, setLoaded] = useState(false)
+  const [remoteMode, setRemoteMode] = useState(false)
 
   useEffect(() => {
     let cancelled = false
@@ -43,6 +45,15 @@ export function AgentPicker({ agents, cwd, onSelect, onChangeCwd }: AgentPickerP
     onSelect(agent)
   }
 
+  if (remoteMode) {
+    return (
+      <RemoteConnect
+        onConnect={(agent) => { handleSelect(agent) }}
+        onBack={() => setRemoteMode(false)}
+      />
+    )
+  }
+
   return (
     <div className="agent-picker-overlay">
       <div className="agent-picker-modal">
@@ -66,6 +77,13 @@ export function AgentPicker({ agents, cwd, onSelect, onChangeCwd }: AgentPickerP
               <span className="agent-picker-desc">{a.description}</span>
             </button>
           ))}
+          <button
+            className="agent-picker-item"
+            onClick={() => setRemoteMode(true)}
+          >
+            <span className="agent-picker-name">🌐 Remote (SSH)</span>
+            <span className="agent-picker-desc">Run an agent on a remote machine</span>
+          </button>
         </div>
 
         <label className="agent-picker-option" onClick={(e) => e.stopPropagation()}>

package/src/renderer/components/ProjectPicker.tsx

@@ -0,0 +1,121 @@
+import { useEffect, useState } from 'react'
+
+interface Project {
+  id: string
+  name: string
+  root_path: string
+}
+
+interface ProjectPickerProps {
+  /** Called when the user picks a project or skips — the overlay should close. */
+  onDone: () => void
+}
+
+type State = 'loading' | 'ready' | 'error'
+
+// Shown right after a remote (SSH) session connects: lets the user bind it to a
+// ctlsurf project so chat logging, tickets, and remote-control attach there.
+export function ProjectPicker({ onDone }: ProjectPickerProps) {
+  const [state, setState] = useState<State>('loading')
+  const [projects, setProjects] = useState<Project[]>([])
+  const [errorMsg, setErrorMsg] = useState('')
+  const [binding, setBinding] = useState(false)
+  const [filter, setFilter] = useState('')
+
+  useEffect(() => {
+    let cancelled = false
+    window.worker.listProjects().then((r) => {
+      if (cancelled) return
+      if (r.ok) {
+        setProjects(r.projects || [])
+        setState('ready')
+      } else {
+        setErrorMsg(r.error || 'Could not load projects')
+        setState('error')
+      }
+    }).catch((err) => {
+      if (cancelled) return
+      setErrorMsg(err?.message || 'Could not load projects')
+      setState('error')
+    })
+    return () => { cancelled = true }
+  }, [])
+
+  const pick = async (p: Project) => {
+    setBinding(true)
+    try {
+      await window.worker.bindProject(p.root_path)
+    } catch { /* non-fatal — session still runs unbound */ }
+    onDone()
+  }
+
+  const shown = filter.trim()
+    ? projects.filter((p) =>
+        p.name.toLowerCase().includes(filter.toLowerCase()) ||
+        p.root_path.toLowerCase().includes(filter.toLowerCase()))
+    : projects
+
+  return (
+    <div className="agent-picker-overlay">
+      <div className="agent-picker-modal">
+        <div className="agent-picker-brand">ctlsurf</div>
+        <div className="agent-picker-title">SELECT CTLSURF PROJECT</div>
+        <div className="remote-target-line">Bind this remote session to a project</div>
+
+        {state === 'loading' && (
+          <div className="remote-status">
+            <div className="remote-spinner" />
+            <div>Loading projects…</div>
+          </div>
+        )}
+
+        {state === 'error' && (
+          <>
+            <div className="remote-note">{errorMsg}</div>
+          </>
+        )}
+
+        {state === 'ready' && (
+          <>
+            {projects.length === 0 && (
+              <div className="remote-note">No ctlsurf projects found. You can skip and bind one later.</div>
+            )}
+
+            {projects.length > 6 && (
+              <input
+                className="remote-input"
+                style={{ width: '100%', boxSizing: 'border-box', margin: '4px 0 8px' }}
+                type="text"
+                placeholder="Filter projects…"
+                value={filter}
+                onChange={(e) => setFilter(e.target.value)}
+                autoCapitalize="off"
+                autoCorrect="off"
+                spellCheck={false}
+              />
+            )}
+
+            <div className="agent-picker-list remote-host-scroll">
+              {shown.map((p) => (
+                <button
+                  key={p.id}
+                  className="agent-picker-item project-item"
+                  disabled={binding}
+                  onClick={() => pick(p)}
+                  title={p.root_path}
+                >
+                  <span className="agent-picker-name">{p.name}</span>
+                  <span className="agent-picker-desc">{p.root_path}</span>
+                </button>
+              ))}
+            </div>
+          </>
+        )}
+
+        <button className="remote-link" disabled={binding} onClick={onDone}>
+          Skip — no project
+        </button>
+      </div>
+    </div>
+  )
+}