samagotchi 0.102.0 → 0.103.0

data/lib/samagotchi/sessions_command.rb

@@ -15,6 +15,7 @@ require_relative "terminal_ui/formatting"
 require_relative "terminal_ui/event_renderer"
 require_relative "cli/command"
 require_relative "cli/flags"
+require_relative "session_access/local"
 
 module Samagotchi
   # `chi sessions`: list, stop, restart, archive/unarchive, delete, prune,
@@ -81,10 +82,15 @@ module Samagotchi
     INTEGER_OPTIONS = %i[days keep limit].freeze
 
     # @param argv [Array<String>] the arguments after "sessions"
-    def initialize(argv, stdout: $stdout, stderr: $stderr)
+    # @param access [SessionAccess::Local, nil] where the sessions are;
+    #   default this machine's (delete, archive and unarchive build their
+    #   own unless one is given)
+    def initialize(argv, stdout: $stdout, stderr: $stderr, access: nil)
       @argv = argv.dup
       @stdout = stdout
       @stderr = stderr
+      @given_access = access
+      @access = access || Samagotchi::SessionAccess::Local.new
     end
 
     # @return [Integer] exit status
@@ -99,9 +105,10 @@ module Samagotchi
 
       case @sub
       when "delete"
-        return Samagotchi::SessionDeleteCommand.new(@argv[1..], stdout: @stdout, stderr: @stderr).run
+        return Samagotchi::SessionDeleteCommand.new(@argv[1..], stdout: @stdout, stderr: @stderr, access: @given_access).run
       when "archive", "unarchive"
-        return Samagotchi::SessionArchiveCommand.new(@sub, @argv[1..], stdout: @stdout, stderr: @stderr).run
+        return Samagotchi::SessionArchiveCommand.new(@sub, @argv[1..], stdout: @stdout, stderr: @stderr,
+                                                                       access: @given_access).run
       end
 
       parsed = parse_flags(FLAGS.fetch(@sub), @argv[1..])
@@ -166,7 +173,16 @@ module Samagotchi
 
       # The current git project's sessions (Samagotchi::ProjectScope), like
       # chi web's; --scope=all, a folder in no repo or an explicit --cwd: every
-      # project's.
+      # project's. Machine-local (this cwd's project): remotely every
+      # project's (D4), and --scope=project is --cwd's project there (the
+      # server finds its root). The rows are the server's (list_summaries).
+      if @access.remote?
+        return usage_error("--scope=project on a remote needs --cwd: a folder there") if scope == "project" && !cwd
+
+        project = scope == "project" ? cwd : nil
+        scope_note = ->(count) { "#{count} session(s) in #{File.basename(project)} on #{@access.name} (--scope=all: every project)" }
+        return list_summaries(project, scope_note)
+      end
       project = scope == "all" || cwd ? nil : Samagotchi::ProjectScope.root_for(Dir.pwd)
       scope_note = ->(count) { "#{count} session(s) in #{File.basename(project)} (--scope=all: every project)" }
 
@@ -181,7 +197,7 @@ module Samagotchi
     def list_summaries(project, scope_note)
       live, cwd, limit, include_archived, format, sort, order =
         @opts.values_at(:live, :cwd, :limit, :include_archived, :format, :sort, :order)
-      summaries = Samagotchi::SessionManager.session_summaries(
+      summaries = @access.summaries(
         live: live, cwd: cwd, limit: limit || (live ? 10 : nil), include_tests: Samagotchi::Session.test_session_env?,
         project_root: project,
         include_archived: include_archived, sort: sort, order: order
@@ -245,10 +261,12 @@ module Samagotchi
       sort, order, limit, include_archived = @opts.values_at(:sort, :order, :limit, :include_archived)
       sort ||= "updated_at"
       order ||= "desc"
-      sessions = Samagotchi::SessionManager.list_sessions(sort: sort, order: order, limit: limit, project_root: project,
-                                                          include_archived: include_archived)
+      sessions = @access.list(sort: sort, order: order, limit: limit, project_root: project, include_archived: include_archived)
       # The session's title, else the saved recap's first sentence, else the
       # last prompt (or the first message, before any turn), cut as before.
+      # These rows read each session's folder here (its recap, saved
+      # context, owner): machine-local, the server's rows remotely (P2's
+      # list parity).
       state_dir = Samagotchi::Session.default_state_dir
       list_text = lambda do |s|
         recap = s.title ? nil : Samagotchi::RecapStore.preview(Samagotchi::Session.session_dir(s.id, state_dir: state_dir))
@@ -297,7 +315,8 @@ module Samagotchi
     # One session's cost, tokens and progress, for a script or an agent that
     # drives sessions (chi send --wait): a live worker's GET stats, else the
     # snapshot its saved analytics.json rebuilds. Never starts a worker, and
-    # never sends the model anything.
+    # never sends the model anything. Local only (SessionAccess::Contract):
+    # the Bridge's stats and analytics.json on this machine.
     def stats(ids)
       return usage_error("give a session id") if ids.empty?
       return usage_error("stats takes one session id") if ids.size > 1
@@ -369,8 +388,8 @@ module Samagotchi
       # error line, so the output keeps the order of the ids given.
       ok = ids.uniq.map do |given|
         begin
-          id = Samagotchi::Session.resolve_id(given)
-          released = Samagotchi::SessionManager.stop_session(id, wait: 10)
+          id = @access.resolve_id(given)
+          released = @access.stop(id, wait: 10)
         rescue Samagotchi::SessionManager::OwnedByTUI => e
           @stdout.flush
           @stderr.puts e.message
@@ -380,11 +399,13 @@ module Samagotchi
           @stderr.puts e.message
           next false
         end
+        # Remotely no chi --resume (remote attach is its own phase).
+        resume = @access.invocation.resume(id)
         if released
-          @stdout.puts "Stopped session #{id}. chi --resume #{id} starts a fresh worker."
+          @stdout.puts "Stopped session #{id}.#{" #{resume} starts a fresh worker." if resume}"
         else
           @stdout.flush
-          @stderr.puts "Stopped session #{id}, but its worker is still shutting down; try chi --resume #{id} in a moment."
+          @stderr.puts "Stopped session #{id}, but its worker is still shutting down#{"; try #{resume} in a moment" if resume}."
         end
         true
       end
@@ -398,8 +419,8 @@ module Samagotchi
 
       ok = ids.uniq.map do |given|
         begin
-          id = Samagotchi::Session.resolve_id(given)
-          result = Samagotchi::SessionManager.restart_session(id)
+          id = @access.resolve_id(given)
+          result = @access.restart(id)
         rescue Samagotchi::SessionManager::OwnedByTUI => e
           @stdout.flush
           @stderr.puts e.message
@@ -426,6 +447,7 @@ module Samagotchi
       "Restarted session #{result.session_id} on chi #{result.version}#{from}."
     end
 
+    # Local only (SessionAccess::Contract): this machine's retention sweep.
     def prune(sub)
       days, keep, keep_status, dry_run, test_only = @opts.values_at(:days, :keep, :keep_status, :dry_run, :test_only)
       test_only = true if sub == "clean" && !@opts[:all]

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,33 +91,55 @@ 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, 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
       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
       # --wait` prints it (ParentReport), so a script or a parent agent
       # can answer it with chi answer.
       # @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
 
@@ -169,7 +205,7 @@ 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")
+        client || raise(Error, format(LaunchMode::BRIDGE_LATE, session.id))
       rescue SessionManager::OwnedByTUI
         raise Error, "session #{resume} is open in a chi REPL; close it there first"
       rescue ArgumentError => e

data/lib/samagotchi/terminal_ui/attach_link.rb

@@ -0,0 +1,104 @@
+# 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
+      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)
+    end
+  end
+end