openclacky 0.9.34 → 0.9.35

data/lib/clacky/tools/terminal/persistent_session.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Clacky
+  module Tools
+    class Terminal < Base
+      # Holds (at most) ONE long-lived PTY shell session that is reused
+      # across multiple terminal calls. Reusing the session eliminates the
+      # ~1s cold-start cost of `zsh -l -i` / `bash -l -i` on every command.
+      #
+      # Reuse rules:
+      #   - Only non-background, non-dedicated calls take from the persistent
+      #     slot. background / env-overridden calls spawn a fresh session.
+      #   - Before each call we diff rc-file mtime(s); if changed, we
+      #     `source` them once inside the live shell so the user sees freshly
+      #     installed PATH / functions / aliases on the very next command.
+      #   - If a command leaves the session in a non-clean state (marker not
+      #     hit — i.e. the program is still running and interactive), the
+      #     session is "donated" to the caller as a dedicated session_id and
+      #     the persistent slot is cleared (next call rebuilds a fresh one).
+      #   - If cleanup fails or a spawn fails, we transparently fall back to
+      #     the old one-shot `bash --noprofile --norc -i` spawn.
+      #
+      # Thread safety:
+      #   - Each persistent session has its own mutex (Session#mutex) that
+      #     serialises PTY writes (unchanged).
+      #   - The PersistentSessionPool itself is guarded by a class-level
+      #     mutex so concurrent terminal calls don't race on acquire/release.
+      class PersistentSessionPool
+        class << self
+          def instance
+            @instance ||= new
+          end
+
+          def reset!
+            if @instance
+              begin
+                @instance.shutdown!
+              rescue StandardError
+                # swallow — best-effort during tests / shutdown
+              end
+            end
+            @instance = nil
+          end
+        end
+
+        def initialize
+          @mutex            = Mutex.new
+          @session          = nil   # currently-idle persistent session, or nil
+          @rc_fingerprint   = nil   # mtime snapshot used to detect rc changes
+          @last_env_keys    = []    # keys we exported last time; unset them on env change
+          @disabled         = false # set to true after a spawn failure to stop retrying
+        end
+
+        # Acquire a persistent session for a new command.
+        #
+        # Returns [session, reused:] where `session` is a running PTY
+        # session ready to accept a command (no concurrent command in
+        # flight). Raises SpawnFailed if we can't build one.
+        #
+        # `reused:` is true when an existing session was handed out; false
+        # when we had to spawn a fresh one.
+        #
+        # Side effects when reusing:
+        #   - Sources rc files if their mtimes changed.
+        #   - `cd`s to `cwd` if given.
+        #   - Resets env vars that were exported last time and exports the
+        #     new ones (only when `env` is non-nil).
+        def acquire(runner:, cwd: nil, env: nil)
+          @mutex.synchronize do
+            return [nil, false] if @disabled
+
+            # 1) Make sure the stored session is still healthy.
+            if @session
+              unless session_healthy?(@session)
+                drop_locked
+              end
+            end
+
+            # 2) Spawn a fresh one if we don't have anything warm.
+            unless @session
+              begin
+                @session = runner.spawn_persistent_session
+              rescue StandardError => e
+                @disabled = true
+                raise SpawnFailed, e.message
+              end
+              @rc_fingerprint = current_rc_fingerprint
+              @last_env_keys  = []
+              reused = false
+            else
+              reused = true
+            end
+
+            # 3) If rc files changed since last use, re-source them once.
+            if reused && rc_changed?
+              runner.source_rc_in_session(@session, rc_files_for_shell(@session.shell_name))
+              @rc_fingerprint = current_rc_fingerprint
+            end
+
+            # 4) Reset env — unset old, export new.
+            if env && !env.empty?
+              new_keys = env.keys.map(&:to_s)
+              to_unset = @last_env_keys - new_keys
+              runner.reset_env_in_session(@session, unset_keys: to_unset, set_env: env)
+              @last_env_keys = new_keys
+            elsif !@last_env_keys.empty?
+              runner.reset_env_in_session(@session, unset_keys: @last_env_keys, set_env: {})
+              @last_env_keys = []
+            end
+
+            # 5) cd to the requested directory.
+            if cwd && Dir.exist?(cwd.to_s)
+              runner.cd_in_session(@session, cwd.to_s)
+            end
+
+            session = @session
+            # Remove it from the slot for the duration of the command so
+            # a concurrent caller can't grab the same shell mid-run.
+            @session = nil
+
+            [session, reused]
+          end
+        end
+
+        # Put a session back into the persistent slot after a successful
+        # command. If the slot is already filled (concurrent call built
+        # another one), we just discard the extra to avoid leaks.
+        def release(session)
+          @mutex.synchronize do
+            if @session.nil? && session_healthy?(session)
+              @session = session
+            else
+              # Either we already have one, or this one looks unhealthy.
+              # Let the caller's cleanup_session path handle teardown.
+            end
+          end
+        end
+
+        # The caller has decided the session is unusable (e.g. command left
+        # an interactive program running). Forget it without killing — the
+        # caller is keeping the PTY alive for their own use.
+        def discard
+          @mutex.synchronize { @session = nil }
+        end
+
+        # Shut the persistent session down (typically at_exit).
+        def shutdown!
+          @mutex.synchronize do
+            sess = @session
+            @session = nil
+            next unless sess
+            begin
+              Process.kill("TERM", sess.pid)
+            rescue StandardError
+              # ignore
+            end
+          end
+        end
+
+        def drop_locked
+          sess = @session
+          @session = nil
+          return unless sess
+          begin
+            Process.kill("TERM", sess.pid)
+          rescue StandardError
+            # ignore
+          end
+          SessionManager.forget(sess.id)
+        end
+
+        private :drop_locked
+
+        def session_healthy?(session)
+          return false unless session
+          return false if %w[exited killed].include?(session.status.to_s)
+          # Probe the child process to make sure it's still alive.
+          begin
+            Process.kill(0, session.pid)
+            true
+          rescue Errno::ESRCH
+            false
+          rescue StandardError
+            # EPERM etc. — assume alive
+            true
+          end
+        end
+
+        private :session_healthy?
+
+        # --- rc mtime tracking ---------------------------------------------------
+
+        def current_rc_fingerprint
+          files = rc_files_for_shell(nil) # superset of all known rc files
+          files.each_with_object({}) do |path, h|
+            h[path] = File.mtime(path).to_f if File.exist?(path)
+          end
+        end
+
+        private :current_rc_fingerprint
+
+        def rc_changed?
+          new_fp = current_rc_fingerprint
+          changed = (new_fp != @rc_fingerprint)
+          changed
+        end
+
+        private :rc_changed?
+
+        # Return the rc files relevant to the given shell. If shell_name is
+        # nil (used by current_rc_fingerprint when we have no session), we
+        # return a superset so we always catch changes regardless of shell.
+        def rc_files_for_shell(shell_name)
+          home = ENV["HOME"].to_s
+          case shell_name
+          when "zsh"
+            %w[.zshrc .zprofile .zshenv]
+          when "bash"
+            %w[.bashrc .bash_profile .profile]
+          else
+            %w[.zshrc .zprofile .zshenv .bashrc .bash_profile .profile]
+          end.map { |f| File.join(home, f) }.select { |f| File.exist?(f) }
+        end
+
+        private :rc_files_for_shell
+      end
+
+      # Raised by the pool when a persistent spawn can't be created; callers
+      # should fall back to a one-shot session.
+      class SpawnFailed < StandardError; end
+    end
+  end
+end
+
+# Ensure the persistent shell is cleaned up on interpreter exit. Session-
+# level kill_all! in SessionManager handles anything that's still registered,
+# but we also explicitly SIGTERM the pool's current slot so the child shell
+# doesn't linger.
+at_exit do
+  begin
+    Clacky::Tools::Terminal::PersistentSessionPool.instance.shutdown!
+  rescue StandardError
+    # never raise from at_exit
+  end
+end

data/lib/clacky/tools/terminal/session_manager.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tmpdir"
+require "securerandom"
+
+module Clacky
+  module Tools
+    class Terminal < Base
+      # In-process registry of interactive PTY sessions.
+      #
+      # Lifecycle: sessions die with the openclacky process because the child
+      # bash is a grandchild of openclacky (PTY.spawn forks then execs), and
+      # we also SIGKILL them on interpreter exit via an at_exit hook.
+      #
+      # Thread-safety: all mutations go through a class-level Mutex.  The
+      # reader thread writes to Session#log_io concurrently with the main
+      # thread reading log_file, but File IO is append-safe on POSIX so we
+      # don't need to lock reads — we just pin them by byte offset.
+      #
+      # Status values:
+      #   "starting" - PTY spawned, setup in progress
+      #   "running"  - ready to receive commands
+      #   "exited"   - child process ended
+      #   "killed"   - we signalled it
+      class SessionManager
+        Session = Struct.new(
+          :id,              # Integer, 1-based unique id within this openclacky process
+          :pid,             # Integer, PID of the PTY child
+          :command,         # String, original command launched
+          :cwd,             # String, working directory at launch
+          :started_at,      # Time
+          :log_file,        # String path, raw PTY output append-only
+          :log_io,          # File, write handle owned by reader thread
+          :reader,          # IO, PTY read end
+          :writer,          # IO, PTY write end
+          :reader_thread,   # Thread, reads PTY → log file
+          :status,          # "starting" | "running" | "exited" | "killed"
+          :exit_code,       # Integer or nil
+          :mode,            # "shell" (marker-based) | "raw" (idle-based)
+          :marker_token,    # String, unique per-session token for PROMPT_COMMAND
+          :marker_regex,    # Regexp, compiled match for marker
+          :read_offset,     # Integer, bytes already returned by previous read calls
+          :mutex,           # per-session mutex for PTY writes
+          :shell_name,      # "zsh" | "bash" | "sh" — informs marker syntax & rc reload
+          keyword_init: true
+        )
+
+        @sessions = {}
+        @next_id  = 0
+        @mutex    = Mutex.new
+
+        class << self
+          # Register a new session.  Caller has already spawned the PTY and
+          # started the reader thread; we just record the metadata.
+          def register(pid:, command:, cwd:, log_file:, log_io:, reader:, writer:,
+                       reader_thread:, mode:, marker_token: nil, shell_name: nil)
+            @mutex.synchronize do
+              @next_id += 1
+              session = Session.new(
+                id: @next_id,
+                pid: pid,
+                command: command,
+                cwd: cwd,
+                started_at: Time.now,
+                log_file: log_file,
+                log_io: log_io,
+                reader: reader,
+                writer: writer,
+                reader_thread: reader_thread,
+                status: "starting",
+                exit_code: nil,
+                mode: mode,
+                marker_token: marker_token,
+                marker_regex: marker_token ? /__CLACKY_DONE_#{marker_token}_(\d+)__/ : nil,
+                read_offset: 0,
+                mutex: Mutex.new,
+                shell_name: shell_name
+              )
+              @sessions[session.id] = session
+              session
+            end
+          end
+
+          def get(id)
+            @mutex.synchronize { @sessions[id] }
+          end
+
+          def list
+            refresh_all
+            @mutex.synchronize { @sessions.values.sort_by(&:id) }
+          end
+
+          # Send signal to child, mark as killed.  Returns the Session, or nil
+          # if unknown.
+          def kill(id, signal: "TERM")
+            session = @mutex.synchronize { @sessions[id] }
+            return nil unless session
+
+            begin
+              Process.kill(signal, session.pid)
+            rescue Errno::ESRCH, Errno::EPERM
+              # Already dead — fall through and mark killed.
+            end
+
+            @mutex.synchronize do
+              if session.status == "starting" || session.status == "running"
+                session.status = "killed"
+              end
+            end
+            session
+          end
+
+          # Forget a session (after it has been killed/exited).  Does NOT kill
+          # the process — callers should kill first.
+          def forget(id)
+            @mutex.synchronize { @sessions.delete(id) }
+          end
+
+          # Refresh status of one session in-place (mutex-held).
+          private def refresh_locked(session)
+            return unless session.status == "starting" || session.status == "running"
+
+            # Probe the child with kill(0).
+            begin
+              Process.kill(0, session.pid)
+            rescue Errno::ESRCH
+              session.status = "exited"
+            rescue Errno::EPERM
+              # Process exists but owned by someone else; keep as-is.
+            end
+          end
+
+          def refresh_all
+            @mutex.synchronize do
+              @sessions.each_value { |s| refresh_locked(s) }
+            end
+          end
+
+          def refresh(id)
+            @mutex.synchronize do
+              session = @sessions[id]
+              refresh_locked(session) if session
+              session
+            end
+          end
+
+          # Mark running (called by the Terminal action after setup completes).
+          def mark_running(id)
+            @mutex.synchronize do
+              session = @sessions[id]
+              session.status = "running" if session && session.status == "starting"
+            end
+          end
+
+          def advance_offset(id, new_offset)
+            @mutex.synchronize do
+              s = @sessions[id]
+              s.read_offset = new_offset if s
+            end
+          end
+
+          def log_dir
+            @log_dir ||= begin
+              dir = File.join(Dir.tmpdir, "clacky-terminals-#{Process.pid}")
+              FileUtils.mkdir_p(dir)
+              dir
+            end
+          end
+
+          def allocate_log_file
+            @mutex.synchronize do
+              next_id = @next_id + 1
+              File.join(log_dir, "#{next_id}.log")
+            end
+          end
+
+          # Kill every live session. Called from at_exit.
+          def kill_all!
+            (@sessions.values rescue []).each do |s|
+              next if s.status == "exited" || s.status == "killed"
+              Process.kill("KILL", s.pid) rescue nil
+              s.log_io&.close rescue nil
+            end
+          end
+
+          # Test-only: clear state without killing processes.
+          def reset!
+            @mutex.synchronize do
+              @sessions.clear
+              @next_id = 0
+              @log_dir = nil
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+# Ensure orphaned PTY children are reaped even on unclean exit.
+at_exit do
+  begin
+    Clacky::Tools::Terminal::SessionManager.kill_all!
+  rescue StandardError
+    # never raise out of at_exit
+  end
+end