samagotchi 0.102.0 → 0.103.0

data/lib/samagotchi/session_access/contract.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module SessionAccess
+    # Which session commands and flags run against another machine's
+    # sessions (chi --remote NAME …, CHI_REMOTE; SessionAccess::Dispatch)
+    # and which run on this machine only (refused under a remote, exit 2:
+    # "chi <cmd> runs on this machine only: run it on <remote>"). The v1 scope is the remote-sessions plan's
+    # D3: send, answer, note, a session's context (add, push, ls, show, rm)
+    # and sessions list/stop/restart/archive/unarchive/delete; the rest
+    # stays local. bin/chi's subcommands that act on the machine, not on
+    # sessions, are MACHINE. The run flags (--attach, -p, --resume) are not
+    # subcommands and not in this table (remote attach is its own phase).
+    #
+    # spec/session_access_contract_spec.rb fails when a subcommand, one of
+    # its subcommands or one of a supported one's flags is in neither.
+    module Contract
+      SUPPORTED = :supported
+      LOCAL_ONLY = :local_only
+
+      # bin/chi subcommands that act on this machine: never sessions. chi
+      # remote (this machine's list of remotes) runs here under a remote too
+      # (Dispatch); the others are refused there.
+      MACHINE = %w[bootstrap update models desktop memory bundle remote].freeze
+
+      # "command", "command sub" or either with a flag (its long name) →
+      # SUPPORTED or LOCAL_ONLY. A LOCAL_ONLY command or subcommand lists
+      # no flags: all of it is local.
+      TABLE = {
+        "send" => SUPPORTED,
+        "send --message" => SUPPORTED,
+        "send --new" => SUPPORTED,
+        # Required with --new under a remote (D4: no laptop path guessed).
+        "send --dir" => SUPPORTED,
+        "send --continues" => SUPPORTED,
+        "send --model" => SUPPORTED,
+        "send --llm-context" => SUPPORTED,
+        "send --llm-context-apply" => SUPPORTED,
+        "send --llm-context-budget" => SUPPORTED,
+        "send --thinking" => SUPPORTED,
+        "send --toolkit" => SUPPORTED,
+        "send --tool" => SUPPORTED,
+        "send --no-tool" => SUPPORTED,
+        "send --set" => SUPPORTED,
+        "send --parent-answers" => SUPPORTED,
+        "send --image" => SUPPORTED,
+        "send --wait" => SUPPORTED,
+        "send --cut" => SUPPORTED,
+        "send --queue" => SUPPORTED,
+        "send --timeout" => SUPPORTED,
+        "send --format" => SUPPORTED,
+        "send --turn" => SUPPORTED,
+        # Refused on both (there is no --all).
+        "send --all" => SUPPORTED,
+
+        "answer" => SUPPORTED,
+        "answer --question" => SUPPORTED,
+        "answer --option" => SUPPORTED,
+        "answer --text" => SUPPORTED,
+        "answer --dismiss" => SUPPORTED,
+        "answer --timeout" => SUPPORTED,
+        "answer --format" => SUPPORTED,
+
+        "note" => SUPPORTED,
+        "note --message" => SUPPORTED,
+        "note --source" => SUPPORTED,
+        "note --all" => SUPPORTED,
+
+        "context" => SUPPORTED,
+        "context add" => SUPPORTED,
+        "context add --cmd" => SUPPORTED,
+        "context add --push" => SUPPORTED,
+        "context add --every" => SUPPORTED,
+        "context add --why" => SUPPORTED,
+        "context add --hint" => SUPPORTED,
+        "context add --project" => LOCAL_ONLY,
+        "context push" => SUPPORTED,
+        "context push --message" => SUPPORTED,
+        "context push --project" => LOCAL_ONLY,
+        "context ls" => SUPPORTED,
+        "context ls --format" => SUPPORTED,
+        "context ls --project" => LOCAL_ONLY,
+        "context show" => SUPPORTED,
+        "context show --json" => SUPPORTED,
+        "context show --project" => LOCAL_ONLY,
+        "context rm" => SUPPORTED,
+        "context rm --project" => LOCAL_ONLY,
+        "context refresh" => LOCAL_ONLY,
+        "context mute" => LOCAL_ONLY,
+        "context unmute" => LOCAL_ONLY,
+
+        "sessions" => SUPPORTED,
+        "sessions list" => SUPPORTED,
+        "sessions list --sort" => SUPPORTED,
+        "sessions list --order" => SUPPORTED,
+        "sessions list --limit" => SUPPORTED,
+        "sessions list --cwd" => SUPPORTED,
+        "sessions list --format" => SUPPORTED,
+        # Remotely every project's by default (D4); --scope=project needs
+        # --cwd there.
+        "sessions list --scope" => SUPPORTED,
+        "sessions list --live" => SUPPORTED,
+        "sessions list --archived" => SUPPORTED,
+        "sessions stop" => SUPPORTED,
+        "sessions restart" => SUPPORTED,
+        "sessions archive" => SUPPORTED,
+        "sessions unarchive" => SUPPORTED,
+        "sessions delete" => SUPPORTED,
+        "sessions delete --force" => SUPPORTED,
+        "sessions prune" => LOCAL_ONLY,
+        "sessions clean" => LOCAL_ONLY,
+        "sessions stats" => LOCAL_ONLY,
+
+        "broadcast" => LOCAL_ONLY
+      }.freeze
+
+      module_function
+
+      # @param words [Array<String>] a command, maybe its subcommand, maybe
+      #   a flag's long name: status("context", "add", "--cmd")
+      # @return [Symbol, nil] SUPPORTED, LOCAL_ONLY, or nil when not listed
+      def status(*words) = TABLE[words.join(" ")]
+
+      # Whether +words+ run against a remote: the command, its subcommand
+      # and the flag each listed SUPPORTED.
+      def supported?(*words) = (1..words.size).all? { |n| status(*words.first(n)) == SUPPORTED }
+    end
+  end
+end

data/lib/samagotchi/session_access/dispatch.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require_relative "../session_access"
+require_relative "contract"
+require_relative "../remotes"
+require_relative "../cli/exit"
+
+module Samagotchi
+  module SessionAccess
+    # bin/chi's front for chi --remote NAME … and CHI_REMOTE=NAME: takes the
+    # flag off the front of the arguments (before the subcommand lookup),
+    # names the remote (the flag beats the env; no default remote), refuses
+    # what runs on this machine only (Contract) and runs a session command
+    # with a Remote for its SessionAccess. chi remote itself, --version and
+    # --help always run here.
+    class Dispatch
+      FLAG = "--remote"
+      ENV_KEY = "CHI_REMOTE"
+      # Run here whatever the remote: chi remote manages the remotes.
+      ALWAYS_HERE = %w[remote].freeze
+      # bin/chi's own words besides its SUBCOMMANDS (a refusal names them).
+      OWN_WORDS = %w[web scratch self].freeze
+      HELP = %w[--version -h --help].freeze
+      # The run flags (not subcommands) a refusal names: remote attach is
+      # its own phase (P4).
+      RUN_FLAGS = { "--attach" => "--attach", "--resume" => "--resume", "-p" => "-p", "--prompt" => "-p",
+                    "--shared" => "--shared", "--no-shared" => "--no-shared" }.freeze
+
+      # A usage error in the flag itself (--remote with no name, a bad one).
+      class Usage < StandardError; end
+
+      # The flag (any number of them at the front; the last wins) taken off
+      # +argv+, and the remote it and +env+ name.
+      # @return [Dispatch]
+      # @raise [Usage]
+      def self.from(argv, env: ENV)
+        rest = argv.dup
+        flag = nil
+        while (arg = rest.first) && (arg == FLAG || arg.start_with?("#{FLAG}="))
+          rest.shift
+          flag = arg == FLAG ? rest.shift : arg.delete_prefix("#{FLAG}=")
+          raise Usage, "#{FLAG} needs a remote's name (chi remote ls lists them)" if flag.nil? || flag.strip.empty? || flag.start_with?("-")
+        end
+        from_env = env.fetch(ENV_KEY, "").to_s.strip
+        new(rest, remote: flag || (from_env.empty? ? nil : from_env))
+      end
+
+      attr_reader :argv, :remote
+
+      def initialize(argv, remote:)
+        @argv = argv
+        @remote = remote
+      end
+
+      def remote? = !@remote.nil?
+
+      # Whether the arguments run here as they would without a remote: chi
+      # remote, --version, --help.
+      def here?
+        first = @argv.first
+        ALWAYS_HERE.include?(first) || (@argv.size == 1 && HELP.include?(first))
+      end
+
+      # The one refusal of a command or flag that runs on this machine only,
+      # or nil when the Contract lets it run against the remote.
+      # @return [String, nil]
+      def refusal
+        words = local_words or return nil
+
+        "chi #{words} runs on this machine only: run it on #{@remote}"
+      end
+
+      # The session command against the remote: refused (exit 2), or run
+      # with a Remote. A failure to reach it is the command's line, exit 1.
+      # @param subcommands [Hash] bin/chi's SUBCOMMANDS
+      # @return [Integer] the exit status
+      def run(subcommands, stderr: $stderr, transport: nil)
+        command = @argv.first
+        unless command.nil? || command.start_with?("-") || subcommands.key?(command) || OWN_WORDS.include?(command)
+          stderr.puts("Error: unknown command #{command} (see chi --help)")
+          return CLI::Exit::FAILED
+        end
+        if (message = refusal)
+          stderr.puts("Error: #{message}")
+          return CLI::Exit::USAGE
+        end
+
+        entry = Remotes.find(Remotes.check_name!(@remote))
+        path, klass = subcommands.fetch(@argv.first)
+        require path
+        access = Remote.new(entry, transport: transport)
+        Samagotchi.const_get(klass).new(@argv[1..] || [], access: access).run
+      rescue Remotes::Invalid => e
+        stderr.puts("Error: #{e.message}")
+        CLI::Exit::USAGE
+      rescue RemoteFailed => e
+        stderr.puts("chi #{@argv.first}: #{e.message}")
+        CLI::Exit::FAILED
+      end
+
+      private
+
+      # The words that run here only: the command (and its subcommand, a
+      # flag) the Contract lists local_only, a machine command, or the run
+      # flags (a session in this terminal, attach). nil: supported.
+      def local_words
+        command = @argv.first
+        return run_words if command.nil? || command.start_with?("-")
+        return command if Contract::MACHINE.include?(command) || Contract.status(command).nil?
+        return command if Contract.status(command) == Contract::LOCAL_ONLY
+
+        sub = @argv[1] if Contract::TABLE.key?("#{command} #{@argv[1]}")
+        return "#{command} #{sub}" if sub && Contract.status(command, sub) == Contract::LOCAL_ONLY
+
+        prefix = [command, sub].compact
+        flags.each do |flag|
+          return [*prefix, flag].join(" ") if Contract.status(*prefix, flag) == Contract::LOCAL_ONLY
+        end
+        nil
+      end
+
+      # The long flags given, up to a "--".
+      def flags
+        @argv.drop(1).take_while { |arg| arg != "--" }.select { |arg| arg.start_with?("--") }.map { |arg| arg.split("=", 2).first }
+      end
+
+      def run_words
+        flag = @argv.take_while { |arg| arg != "--" }.map { |arg| arg.split("=", 2).first }.find { |arg| RUN_FLAGS.key?(arg) }
+        flag ? RUN_FLAGS[flag] : "(a session in this terminal)"
+      end
+    end
+  end
+end

data/lib/samagotchi/session_access/http_transport.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+require "openssl"
+require_relative "../session_access"
+
+module Samagotchi
+  module SessionAccess
+    # A remote's chi web over HTTP (Net::HTTP), its access token as
+    # Authorization: Bearer: one request per call, each on its own
+    # connection (a command makes a handful). A connection that fails
+    # raises RemoteFailed naming the remote and why.
+    class HTTPTransport
+      # One answer: the status, the body, and the body read as JSON (nil
+      # when it isn't).
+      Reply = Data.define(:status, :body, :json) do
+        def self.of(status, body)
+          json = begin
+            JSON.parse(body.to_s)
+          rescue JSON::ParserError
+            nil
+          end
+          new(status: status.to_i, body: body.to_s, json: json)
+        end
+
+        def error = json.is_a?(Hash) ? json["error"] : nil
+      end
+
+      OPEN_TIMEOUT = 5
+      # Above chi web's longest answer (a wait route's 30 s, a create's
+      # wait for its worker).
+      READ_TIMEOUT = 75
+
+      # @param entry [Remotes::Entry]
+      def initialize(entry, open_timeout: OPEN_TIMEOUT, read_timeout: READ_TIMEOUT)
+        @entry = entry
+        @uri = URI(entry.url)
+        @open_timeout = open_timeout
+        @read_timeout = read_timeout
+      end
+
+      def inspect = "#<#{self.class.name} #{@entry.label}>"
+
+      # @param method [Symbol] :get, :post, :delete
+      # @param path [String] "/api/…"
+      # @param query [Hash, nil] the query's parameters (nil values left out)
+      # @param body [Hash, nil] sent as JSON
+      # @param raw [String, nil] sent as is (an image), with +content_type+
+      # @param read_timeout [Numeric, nil] this request's, instead of the
+      #   transport's (a remote attach's turn, its join reads)
+      # @return [Reply]
+      # @raise [RemoteFailed] it could not be asked
+      def call(method, path, query: nil, body: nil, raw: nil, content_type: nil, read_timeout: nil)
+        read_timeout ||= @read_timeout
+        request = build(method, path, query)
+        request["Authorization"] = "Bearer #{@entry.token}" if @entry.token
+        request["Accept"] = "application/json"
+        if raw
+          request["Content-Type"] = content_type || "application/octet-stream"
+          request.body = raw
+        elsif body
+          request["Content-Type"] = "application/json"
+          request.body = JSON.generate(body)
+        elsif method != :get
+          request["Content-Length"] = "0"
+        end
+        response = http(read_timeout).request(request)
+        Reply.of(response.code, response.body)
+      rescue Errno::ECONNREFUSED
+        failed("connection refused")
+      rescue Net::OpenTimeout, Errno::ETIMEDOUT
+        failed("no answer within #{@open_timeout} s")
+      rescue Net::ReadTimeout
+        failed("it took the request but sent no answer within #{read_timeout} s")
+      rescue SocketError => e
+        failed(e.message.include?("getaddrinfo") ? "can't find host #{@uri.host}" : e.message)
+      rescue Errno::EHOSTUNREACH, Errno::ENETUNREACH
+        failed("host unreachable")
+      rescue OpenSSL::SSL::SSLError => e
+        failed("TLS failed: #{e.message}")
+      rescue IOError, SystemCallError => e
+        failed("the connection broke (#{e.class.name.split("::").last})")
+      end
+
+      private
+
+      def http(read_timeout)
+        Net::HTTP.new(@uri.host, @uri.port).tap do |http|
+          http.use_ssl = @uri.scheme == "https"
+          http.open_timeout = @open_timeout
+          http.read_timeout = read_timeout
+          http.write_timeout = read_timeout
+          http.max_retries = 0
+        end
+      end
+
+      def build(method, path, query)
+        target = path
+        params = query&.compact
+        target = "#{path}?#{URI.encode_www_form(params)}" if params && !params.empty?
+        { get: Net::HTTP::Get, post: Net::HTTP::Post, delete: Net::HTTP::Delete }.fetch(method).new(target)
+      end
+
+      def failed(reason) = raise(RemoteFailed, "#{@entry.label}: #{reason}")
+    end
+  end
+end