samagotchi 0.102.0 → 0.104.0

data/lib/samagotchi/terminal_ui/attach_launcher.rb

@@ -8,6 +8,7 @@ require_relative "../thinking_command"
 require_relative "../bridge_client"
 require_relative "../parent_report"
 require_relative "../cli/exit"
+require_relative "../launch_mode"
 require_relative "live_region"
 require_relative "plain_surface"
 require_relative "attached_loop"
@@ -23,6 +24,9 @@ module Samagotchi
       class Error < StandardError; end
 
       BRIDGE_WAIT = 10.0
+      # A connector that answered no session (its own failures raise Error
+      # with their words).
+      NOTHING_CONNECTED = "could not attach: no session was found or started"
 
       module_function
 
@@ -59,17 +63,27 @@ module Samagotchi
       #   loosening route from a command line)
       # @param state_dir [String, nil] where the sessions are (the default
       #   state dir by default): the worker's, for the attached loop too
+      # @param connector [#connect, nil] finds or starts the session
+      #   elsewhere: its #connect returns the AttachLink the loop runs on
+      #   (nil: this machine's, through .connect; a connector never falls
+      #   back to it), and its #client_id, when it has one, names this
+      #   TUI's streams and requests there (#client_id)
       # @return [Symbol] :detached, :closed when the worker went away,
       #   :failed when the --model switch didn't go through, or (input from a
       #   pipe) :turn_failed / :empty_answer / :unanswered (AttachedLoop#run)
       def run(attach: nil, shared: false, resume: nil, prompt: nil, model: nil, no_interrupt: false, default_input: true,
               memories: [], muted_memories: [], llm_context: {}, thinking: nil, appended_prompt_files: [], toolkit: nil,
-              toolkit_flags: [], settings: nil, parent_answers: nil, state_dir: nil)
+              toolkit_flags: [], settings: nil, parent_answers: nil, state_dir: nil, connector: nil)
         state_dir ||= Session.default_state_dir
-        client = connect(attach: attach, shared: shared, resume: resume, model: model, state_dir: state_dir,
-                         memories: memories, muted_memories: muted_memories, llm_context: llm_context, thinking: thinking,
-                         appended_prompt_files: appended_prompt_files, toolkit: toolkit, toolkit_flags: toolkit_flags,
-                         settings: settings, parent_answers: parent_answers)
+        link = connector && (connector.connect || raise(Error, NOTHING_CONNECTED))
+        client = if connector
+                   link.client
+                 else
+                   connect(attach: attach, shared: shared, resume: resume, model: model, state_dir: state_dir,
+                           memories: memories, muted_memories: muted_memories, llm_context: llm_context,
+                           thinking: thinking, appended_prompt_files: appended_prompt_files, toolkit: toolkit,
+                           toolkit_flags: toolkit_flags, settings: settings, parent_answers: parent_answers)
+                 end
         commands = []
         commands << "/model #{model}" if model && (attach || resume)
         commands << LLMContextOverride.command_line(llm_context) if (attach || resume) && !llm_context.empty?
@@ -77,21 +91,39 @@ module Samagotchi
         commands << "#{ThinkingCommand::NAME} #{thinking} --yes" if (attach || resume) && thinking
         first_command = commands.size > 1 ? commands : commands.first
         surface = open_surface
-        attached = AttachedLoop.new(client: client, screen: surface, client_id: "tui:#{Process.pid}", first_prompt: prompt,
-                                    first_command: first_command, no_interrupt: no_interrupt,
-                                    default_input: default_input && !prompt && !attach && !resume,
-                                    wait_at_eof: !$stdin.tty?,
-                                    as_parent: Guardrails::ParentApprovals.parent_process?, state_dir: state_dir)
+        options = { screen: surface, client_id: client_id(connector), first_prompt: prompt,
+                    first_command: first_command, no_interrupt: no_interrupt,
+                    default_input: default_input && !prompt && !attach && !resume,
+                    wait_at_eof: !$stdin.tty?,
+                    as_parent: Guardrails::ParentApprovals.parent_process? }
+        attached = if connector
+                     AttachedLoop.new(link: link, **options)
+                   else
+                     AttachedLoop.new(client: client, **options, state_dir: state_dir)
+                   end
         ended = begin
           attached.run
         ensure
           close_surface(surface)
         end
         if ended == :unanswered && attached.unanswered
-          report_unanswered(attached.unanswered, session_id: client.session_id, state_dir: state_dir)
+          # A link's strategy is read where the session is, now (L4), its
+          # commands spelled its way.
+          where = connector ? { strategy: link.parent_strategy, via: link.via } : {}
+          report_unanswered(attached.unanswered, session_id: client.session_id, state_dir: state_dir, **where)
         end
         report_ended(ended)
         ended
+      ensure
+        link&.close
+      end
+
+      # This TUI's client id: tui:PID, or the connector's own (a remote one
+      # adds the host, for the UIs there).
+      def client_id(connector)
+        return connector.client_id if connector.respond_to?(:client_id)
+
+        "tui:#{Process.pid}"
       end
 
       # A question left waiting (exit 3), in full on stderr as `chi send
@@ -100,10 +132,16 @@ module Samagotchi
       # @param pending [Hash] the pending question as the Bridge sent it
       # @param state_dir [String, nil] where the session file is: what a
       #   parent may pick follows its own parent_answers too
-      def report_unanswered(pending, session_id:, err: $stderr, state_dir: nil)
+      # @param strategy [Guardrails::ParentPolicy::Strategy, nil] that
+      #   strategy, read already (an AttachLink's); nil:
+      #   ParentReport.strategy_for here
+      # @param via [ChiInvocation, nil] how its commands are spelled (nil:
+      #   this machine's)
+      def report_unanswered(pending, session_id:, err: $stderr, state_dir: nil, strategy: nil, via: nil)
         question = PendingQuestion.from_file(pending)
-        strategy = ParentReport.strategy_for(session_id, state_dir: state_dir || Session.default_state_dir)
-        err.print("chi: #{ParentReport.question_text(question, session_id: session_id, strategy: strategy)}")
+        strategy ||= ParentReport.strategy_for(session_id, state_dir: state_dir || Session.default_state_dir)
+        words = via ? { via: via } : {}
+        err.print("chi: #{ParentReport.question_text(question, session_id: session_id, strategy: strategy, **words)}")
         err.flush
       end
 
@@ -157,6 +195,7 @@ module Samagotchi
           resume = attach
         end
 
+        await_leaving_worker(resume, sd, err) if resume
         session = if resume
                     SessionManager.resume_session(resume, state_dir: sd)
                   else
@@ -169,13 +208,23 @@ module Samagotchi
                                                                          parent_answers: parent_answers))
                   end
         client = BridgeClient.wait_for(session.id, session_dir: Session.session_dir(session.id, state_dir: sd), timeout: wait)
-        client || raise(Error, "the worker for session #{session.id} did not start its Bridge in time")
-      rescue SessionManager::OwnedByTUI
-        raise Error, "session #{resume} is open in a chi REPL; close it there first"
+        client || raise(Error, format(LaunchMode::BRIDGE_LATE, session.id))
+      rescue SessionManager::OwnedByTUI => e
+        raise Error, e.message
       rescue ArgumentError => e
         raise Error, e.message
       end
 
+      # The session's previous worker may still be leaving: its Bridge
+      # closed, the lock held while it writes its recap on leave (a resume
+      # now would start nothing, the lock taken). Wait for it to let go
+      # (OwnerLock.await_release), with one line saying so; any other owner
+      # is left to resume_session as before.
+      def await_leaving_worker(session_id, state_dir, err)
+        OwnerLock.await_release(Session.session_dir(session_id, state_dir: state_dir),
+                                on_wait: ->(_owner) { err.puts(LaunchMode::RECAP_WAIT) })
+      end
+
       # --model as typed: spawn_session stores the resolved ref and this name.
       def model_ref(model)
         ModelProfile.required_model_name(model)

data/lib/samagotchi/terminal_ui/attach_link.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class TerminalUI
+    # What the attached TUI (AttachedLoop) knows about *where* its session
+    # is, beside the client it sends requests with: how the worker is found
+    # again, what the worker can do, the session's files it reads (images,
+    # saved records, children), the session calls it makes (delete,
+    # archive), and how the commands it prints are spelled. LocalLink is
+    # this machine's (the session's state dir, its worker's Bridge); a
+    # remote attach plugs in another.
+    #
+    # Each method here raises NotImplementedError until a link defines it.
+    module AttachLink
+      # Which Tab completions the TUI offers beside the / commands.
+      # @!attribute paths [Boolean] @path: this machine's files
+      # @!attribute memories [Boolean] #name: this machine's memories
+      Completions = Data.define(:paths, :memories)
+
+      class Completions
+        ALL = new(paths: true, memories: true)
+      end
+
+      # The port a worker_changed event names (string or symbol keys; nil
+      # for a worker reached another way).
+      def self.event_port(event) = event[:port] || event["port"]
+
+      # @return [#session_id, #follow, #post_turn, ...] the session's client
+      #   (a BridgeClient on this machine), the newest after #switched
+      def client = raise(NotImplementedError)
+
+      # The session's live worker for the stream to follow (EventStream's
+      # rediscover).
+      # @return [Array(Object, String)] [a client, nil] for a live one,
+      #   [nil, nil] while there is none yet, or [:gone, reason] once no
+      #   worker is coming
+      def live_worker = raise(NotImplementedError)
+
+      # The stream moved to a new worker (its worker_changed event, string
+      # or symbol keys): requests go there too.
+      # @return [Object] the client from now on (#client)
+      def switched(_event) = raise(NotImplementedError)
+
+      # Whether the worker runs delivery: queue (/queue).
+      def queues? = raise(NotImplementedError)
+
+      # Whether the worker takes queued messages back (/unqueue).
+      def unqueues? = raise(NotImplementedError)
+
+      # The session's metrics for /stats, nil when the worker did not answer.
+      # @return [Hash, nil] string keys
+      # @raise [IOError] the session's machine couldn't be asked (a remote's
+      #   Unreachable: the loop shows its message)
+      def stats_metrics = raise(NotImplementedError)
+
+      # Store a prompt's @path images where the worker reads them.
+      # @param paths [Array<String>] the files as typed
+      # @return [Array<Hash>] refs ({file:, name:}) for the turn's images
+      # @raise [ImageStore::Error] one can't be used
+      def ingest_images(_paths) = raise(NotImplementedError)
+
+      # A turn's saved tool records ([] when none, never raises).
+      # @return [Array<Hash>]
+      def saved_tool_records(_turn_id) = raise(NotImplementedError)
+
+      # A turn's saved record (nil when none, never raises).
+      # @return [Hash, nil]
+      def saved_turn_record(_turn_id) = raise(NotImplementedError)
+
+      # The session's delegates' counts, the status row's children segment.
+      # @return [ChildrenStatus::Counts]
+      def children_counts = raise(NotImplementedError)
+
+      # /exit --delete, once the worker let go.
+      def delete_session = raise(NotImplementedError)
+
+      # /archive: SessionManager.archive_session's result ({discarded: […]}).
+      # @return [Hash]
+      def archive_session = raise(NotImplementedError)
+
+      # The newest chi installed where the worker runs, for the version line.
+      # @return [String, nil]
+      def installed_version = raise(NotImplementedError)
+
+      # The config's default model where the worker runs, as its /model
+      # names it.
+      # @return [String, nil]
+      def default_model_name = raise(NotImplementedError)
+
+      # What a parent agent may pick on the session's questions, read now
+      # (ParentReport.strategy_for).
+      def parent_strategy = raise(NotImplementedError)
+
+      # @return [Completions]
+      def completions = raise(NotImplementedError)
+
+      # The stream's sleeps between failed reconnects.
+      # @return [Array<Float>]
+      def reconnect_delays = raise(NotImplementedError)
+
+      # How the commands the TUI prints are spelled.
+      # @return [ChiInvocation]
+      def via = raise(NotImplementedError)
+
+      # Why the session's machine couldn't be asked the last time (for the
+      # stream's closing line), nil when there is nothing more to say.
+      # @return [String, nil]
+      def failure = raise(NotImplementedError)
+
+      # The attach is over (AttachLauncher.run): let go of what it held.
+      def close = raise(NotImplementedError)
+    end
+  end
+end