samagotchi 0.102.0 → 0.104.0

data/lib/samagotchi/participants.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "time"
+require_relative "atomic_file"
+require_relative "archive_store"
+require_relative "session"
+require_relative "web/grants"
+
+module Samagotchi
+  # A session's participants: the people (or agents) its owner invited to
+  # review it (`chi share`, the owner's participants routes), each through a
+  # Web::Grants grant. Two files in the session dir, neither in the session
+  # JSON (chi web never saves that, and a worker would overwrite a field it
+  # added):
+  # - participants.json, the sidecar: who is or was invited, never a token
+  #   or a digest. Written by whoever changes a grant (chi web, chi share);
+  #   the worker reads it (Participants.read; P3's system-prompt line). A
+  #   session nobody was invited to has none, so its files stay as they were.
+  # - participants.jsonl, the audit trail (0600, append-only): grants issued,
+  #   revoked and expired, a participant's first use and each new peer,
+  #   every route refused to them.
+  # Neither is copied to a continue, a fork or a delegate. See
+  # docs/internals/participants.md.
+  module Participants
+    FILE = "participants.json"
+    LOG = "participants.jsonl"
+
+    # One participant as the sidecar has them. +removed_at+ when the grant
+    # was revoked (nil while it works, or once it simply expired:
+    # +expires_at+ says when).
+    Entry = Data.define(:id, :kind, :name, :role, :added_at, :expires_at, :removed_at) do
+      def self.from_h(hash) = new(**members.to_h { |key| [key, hash[key.to_s]] })
+
+      # Still in the review at +now+.
+      def active?(now)
+        removed_at.nil? && Time.iso8601(expires_at.to_s) > now
+      rescue ArgumentError
+        false
+      end
+    end
+
+    module_function
+
+    # @return [Array<Entry>] the session's participants, [] without any
+    def read(session_id, state_dir: Session.default_state_dir)
+      file = File.join(Session.session_dir(session_id, state_dir: state_dir), FILE)
+      return [] unless File.exist?(file)
+
+      data = JSON.parse(File.read(file))
+      Array(data.is_a?(Hash) ? data["participants"] : nil).filter_map { |hash| Entry.from_h(hash) if hash.is_a?(Hash) }
+    rescue JSON::ParserError, SystemCallError
+      []
+    end
+
+    # The sidecar rewritten from +grants+ (that session's Web::Grants::Grant
+    # list). Nothing is written for a session without grants, nor for one
+    # whose dir is gone.
+    def write(session_id, grants, state_dir: Session.default_state_dir)
+      return if grants.empty?
+
+      dir = Session.session_dir(session_id, state_dir: state_dir)
+      return unless File.directory?(dir)
+
+      entries = grants.map do |grant|
+        { "id" => grant.id, "kind" => grant.kind, "name" => grant.name, "role" => grant.role,
+          "added_at" => grant.created_at, "expires_at" => grant.expires_at, "removed_at" => grant.revoked_at }
+      end
+      AtomicFile.write(File.join(dir, FILE), "#{JSON.pretty_generate({ "participants" => entries })}\n", perm: 0o600)
+    end
+
+    # One audit line: {"at", "event", …fields}. Nothing for a session whose
+    # dir is gone (deleted, pruned).
+    def log(session_id, event, state_dir: Session.default_state_dir, at: Time.now, **fields)
+      dir = Session.session_dir(session_id, state_dir: state_dir)
+      return unless File.directory?(dir)
+
+      line = JSON.generate({ "at" => at.utc.iso8601(3), "event" => event.to_s }.merge(fields.transform_keys(&:to_s)))
+      File.open(File.join(dir, LOG), File::WRONLY | File::APPEND | File::CREAT, 0o600) { |io| io.write("#{line}\n") }
+    end
+
+    # Invites a participant to +session_id+: the grant (+grants+, a
+    # Web::Grants), the sidecar and the audit line.
+    # @return [Web::Grants::Issued]
+    # @raise [Web::Grants::Invalid] an archived session, or bad values
+    # @raise [ArgumentError] no such session
+    def invite(grants, session_id:, name:, kind: "human", ttl: nil, state_dir: Session.default_state_dir)
+      raise ArgumentError, "Session not found: #{session_id}" unless File.exist?(Session.session_file(session_id, state_dir: state_dir))
+      if ArchiveStore.archived?(Session.session_dir(session_id, state_dir: state_dir))
+        raise Web::Grants::Invalid, "session #{session_id[0, 8]} is archived: unarchive it to invite anyone"
+      end
+
+      issued = grants.issue(session_id: session_id, name: name, kind: kind, **{ ttl: ttl }.compact)
+      write(session_id, grants.list(session_id: session_id), state_dir: state_dir)
+      grant = issued.grant
+      log(session_id, :issued, state_dir: state_dir, participant: grant.id, name: grant.name, kind: grant.kind,
+                               role: grant.role, expires_at: grant.expires_at)
+      issued
+    end
+
+    # Revokes grants (Web::Grants#revoke's arguments) and brings each
+    # affected session's sidecar and audit trail along.
+    # @return [Array<Web::Grants::Grant>] the grants it revoked
+    def revoke(grants, session_id: nil, id: nil, by: "owner", state_dir: Session.default_state_dir)
+      revoked = grants.revoke(session_id: session_id, id: id, by: by)
+      revoked.group_by(&:session_id).each do |sid, ended|
+        write(sid, grants.list(session_id: sid), state_dir: state_dir)
+        ended.each { |grant| log(sid, :revoked, state_dir: state_dir, participant: grant.id, by: by) }
+      end
+      revoked
+    end
+
+    # Ends the grants of sessions that were archived or deleted
+    # (SessionManager): +by+ "archive" or "delete". Nothing is written for a
+    # session nobody was invited to.
+    def end_sessions(session_ids, by:, state_dir: Session.default_state_dir)
+      grants = Web::Grants.new(Web::Grants.path(state_dir: state_dir))
+      session_ids.each { |sid| revoke(grants, session_id: sid, by: by, state_dir: state_dir) }
+    end
+  end
+end

data/lib/samagotchi/remote_attach_command.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require_relative "session"
+require_relative "session_access"
+require_relative "session_access/remote"
+require_relative "launch_mode"
+require_relative "model_profile"
+require_relative "cli/exit"
+require_relative "terminal_ui"
+require_relative "terminal_ui/attach_launcher"
+require_relative "terminal_ui/remote_connector"
+
+module Samagotchi
+  # chi --remote NAME --attach ID | --resume ID | --dir DIR [-p TEXT]: the
+  # attached TUI on a session of another machine, through its chi web
+  # (bin/chi branches here after RunOptions.parse, before its own checks,
+  # which are this machine's). The run flags come parsed; the ones that
+  # run this machine's REPL or read its files were refused already
+  # (SessionAccess::Contract::RUN). The setup flags go as typed: that
+  # machine checks them against its own config and bundles.
+  class RemoteAttachCommand
+    # @param options [Hash] RunOptions.parse's
+    # @param access [SessionAccess::Remote]
+    def initialize(options, access:, stderr: $stderr, launcher: TerminalUI::AttachLauncher,
+                   connector: TerminalUI::RemoteConnector)
+      @options = options
+      @access = access
+      @stderr = stderr
+      @launcher = launcher
+      @connector = connector
+    end
+
+    # @return [Integer] the exit status: AttachLauncher.exit_status's, 1 a
+    #   launch that failed, 2 a usage error, 130 a Ctrl-C before the TUI
+    #   ran (the wake, a wait for a leaving worker there)
+    def run
+      if (conflict = LaunchMode.attached_conflict(@options))
+        return failed(conflict)
+      end
+
+      existing = @options[:attach] || @options[:resume]
+      return usage(new_needs_dir) if !existing && !absolute_dir?
+
+      @access.require_feature!(SessionAccess::Remote::ATTACH_FEATURE)
+      id = existing ? @access.resolve(existing) : create
+      return id if id.is_a?(Integer)
+
+      ignored(id) if existing
+      launch(id, existing: existing)
+    rescue TerminalUI::AttachLauncher::Error, SessionAccess::RemoteFailed, SessionAccess::Refused,
+           SessionManager::OwnedByTUI, ModelProfile::MissingModel, ArgumentError => e
+      e.is_a?(SessionAccess::BadRequest) ? usage(e.message) : failed(e.message)
+    rescue Interrupt
+      CLI::Exit::INTERRUPTED
+    end
+
+    private
+
+    def launch(id, existing:)
+      model = @options[:model]
+      ended = @launcher.run(attach: (id if @options[:attach]), resume: (id if @options[:resume]), prompt: @options[:prompt],
+                            model: (model if existing), no_interrupt: !!@options[:no_interrupt],
+                            default_input: !@options[:no_default_input],
+                            llm_context: (existing && @options[:llm_context]) || {},
+                            thinking: (@options[:thinking] if existing),
+                            connector: @connector.new(@access, session_id: id))
+      @launcher.exit_status(ended)
+    end
+
+    # A new session there, idle (its -p goes in once attached), as chi send
+    # --new makes one: the create's warnings printed as it prints them.
+    # @return [String, Integer] its id, or the exit status of a refusal
+    def create
+      settings = Array(@options[:sets]).to_h do |pair|
+        key, sep, value = pair.partition("=")
+        return usage("--set takes KEY=VALUE, not #{pair}") if sep.empty? || key.strip.empty?
+
+        [key.strip, value]
+      end
+      llm = @options[:llm_context] || {}
+      words = SessionAccess::SetupWords.new(
+        llm_context: (llm unless llm.empty?), thinking: @options[:thinking]&.to_s, toolkit: @options[:toolkit],
+        tools: Array(@options[:tools]), no_tools: Array(@options[:no_tools]),
+        settings: (settings unless settings.empty?), parent_answers: @options[:parent_answers]
+      )
+      created = @access.create(SessionAccess::NewSession.new(prompt: nil, idle: true, working_directory: @options[:dir],
+                                                             model_name: @options[:model], setup: words,
+                                                             client_id: @connector.client_id))
+      @stderr.puts("chi: warning: #{created.model_warning}") if created.model_warning
+      @stderr.puts("chi: warning: --parent-answers #{created.parent_answers_warning}") if created.parent_answers_warning
+      created.id
+    end
+
+    # An existing session keeps its own setup: the line says which flags
+    # went unused, as chi --attach here says it.
+    def ignored(id)
+      flags = [("--dir" if @options[:dir]), ("--toolkit" if @options[:toolkit]), ("--tool" if @options[:tools]),
+               ("--no-tool" if @options[:no_tools]), ("--set" if @options[:sets]),
+               ("--parent-answers" if @options[:parent_answers])].compact
+      TerminalUI::AttachLauncher.warn_memory_flags_ignored(id, [], [], @stderr, toolkit_flags: flags)
+    end
+
+    def absolute_dir? = @options[:dir].to_s.start_with?("/")
+
+    def new_needs_dir
+      "a new session on #{@access.name} needs --dir, that machine's absolute path (or --attach ID / --resume ID)"
+    end
+
+    def failed(message)
+      @stderr.puts("Error: #{message}")
+      CLI::Exit::FAILED
+    end
+
+    def usage(message)
+      @stderr.puts("Error: #{message}")
+      CLI::Exit::USAGE
+    end
+  end
+end

data/lib/samagotchi/remote_command.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "cli/command"
+require_relative "cli/exit"
+require_relative "cli/flags"
+require_relative "paths"
+require_relative "remotes"
+require_relative "session_access"
+require_relative "session_access/http_transport"
+require_relative "session_access/remote"
+
+module Samagotchi
+  # `chi remote`: the other machines whose sessions chi --remote NAME (or
+  # CHI_REMOTE=NAME) reaches through their chi web (Remotes,
+  # SessionAccess::Remote). add checks the address and the token with GET
+  # /api/info before it saves anything; ls never prints a token.
+  class RemoteCommand
+    include CLI::Command
+
+    USAGE = <<~TEXT
+      Usage: chi remote <add|ls|rm> [options]
+        add NAME URL [--token-file FILE | --token-stdin]
+              a machine's chi web (http://LAN-IP:PORT, as chi web prints it with web.host: lan;
+              port 4567 by default), with its access token (chi web's LAN link carries it, after
+              ?token=). It is checked first: the chi it runs, or why it can't be reached. Saved
+              in #{Paths.tilde(Remotes.path)} (0600); an existing NAME is replaced.
+        ls [--format json]    the remotes (never their tokens)
+        rm NAME               forget one
+      Then: chi --remote NAME send|answer|note|context|sessions …, or CHI_REMOTE=NAME.
+    TEXT
+
+    SUBCOMMANDS = %w[add ls rm].freeze
+
+    FLAGS = {
+      "add" => CLI::Flags.new(help: HELP_WORDS) do |f|
+        f.value "--token-file"
+        f.switch "--token-stdin"
+      end,
+      "ls" => CLI::Flags.new(help: HELP_WORDS) { |f| f.value "--format" },
+      "rm" => CLI::Flags.new(help: HELP_WORDS)
+    }.freeze
+
+    # @param transport [#call, nil] (entry) → a transport for add's check;
+    #   HTTPTransport by default
+    def initialize(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr, path: Remotes.path, transport: nil)
+      @argv = argv.dup
+      @stdin = stdin
+      @stdout = stdout
+      @stderr = stderr
+      @path = path
+      @transport = transport || ->(entry) { SessionAccess::HTTPTransport.new(entry) }
+    end
+
+    # @return [Integer] exit status: 0 done, 1 refused or unreachable, 2 usage
+    def run
+      @sub = @argv[0]
+      if @sub.nil? || HELP_WORDS.include?(@sub)
+        @stdout.puts(USAGE)
+        return 0
+      end
+      return usage_error("unknown subcommand #{@sub}") unless SUBCOMMANDS.include?(@sub)
+
+      parsed = parse_flags(FLAGS.fetch(@sub), @argv[1..])
+      return parsed if parsed.is_a?(Integer)
+
+      send(:"run_#{@sub}", parsed.options, parsed.args)
+    rescue Remotes::Invalid => e
+      error_line("#{command_name}: #{e.message}")
+      CLI::Exit::FAILED
+    end
+
+    private
+
+    def command_name = @sub && SUBCOMMANDS.include?(@sub) ? "chi remote #{@sub}" : "chi remote"
+    def usage_on_error = nil
+
+    def run_add(options, args)
+      return usage_error("give NAME and URL") unless args.size == 2
+      return usage_error("--token-file and --token-stdin: choose one") if options[:token_file] && options[:token_stdin]
+
+      name, url = args
+      begin
+        Remotes.check_name!(name)
+        url = Remotes.normalize_url(url)
+      rescue Remotes::Invalid => e
+        return usage_error(e.message)
+      end
+      token = read_token(options)
+      return CLI::Exit::FAILED if token == false
+
+      entry = Remotes::Entry.new(name: name, url: url, token: token)
+      found = check(entry) or return CLI::Exit::FAILED
+      Remotes.put(entry, path: @path)
+      @stdout.puts("#{name}  #{url}  chi #{found["version"]}, #{lan_words(found, entry)}")
+      0
+    end
+
+    def run_ls(options, args)
+      return usage_error("ls takes no arguments") unless args.empty?
+
+      format = options[:format]
+      return usage_error("unknown format #{format.inspect}: use --format text|json") unless [nil, "text", "json"].include?(format)
+
+      entries = Remotes.all(path: @path)
+      if format == "json"
+        @stdout.puts(JSON.generate(entries.map { |e| { name: e.name, url: e.url, token: !e.token.nil? } }))
+      elsif entries.empty?
+        @stdout.puts("no remotes (chi remote add NAME URL --token-file FILE)")
+      else
+        width = entries.map { |e| e.name.length }.max
+        entries.each { |e| @stdout.puts("#{e.name.ljust(width)}  #{e.url}#{"  (no token)" unless e.token}") }
+      end
+      0
+    end
+
+    def run_rm(_options, args)
+      return usage_error("give one NAME") unless args.size == 1
+      raise Remotes::NotFound, args.first unless Remotes.remove(args.first, path: @path)
+
+      @stdout.puts("#{args.first}  removed")
+      0
+    end
+
+    # The token from its file or stdin; nil for none (a loopback chi web
+    # needs none), false after the error line.
+    def read_token(options)
+      text = if options[:token_file]
+               begin
+                 File.read(File.expand_path(options[:token_file]))
+               rescue SystemCallError => e
+                 error_line("#{command_name}: can't read #{options[:token_file]}: #{e.message.sub(/ @ .*/, "")}")
+                 return false
+               end
+             elsif options[:token_stdin]
+               read_stdin.to_s
+             end
+      return nil if text.nil?
+
+      token = text.strip
+      return token unless token.empty? || token.match?(/\s/)
+
+      error_line("#{command_name}: #{options[:token_file] || "stdin"} holds no token (one line, chi web's web-token file)")
+      false
+    end
+
+    # GET /api/info with the token: the answer, or nil after the line that
+    # says why it can't be used.
+    def check(entry)
+      reply = @transport.call(entry).call(:get, "/api/info")
+      problem = SessionAccess::Remote.info_problem(entry, reply)
+      return fail_line(problem.message) if problem
+
+      reply.json
+    rescue SessionAccess::RemoteFailed => e
+      fail_line("#{e.message}: start chi web on #{entry.host} with web.host: lan")
+    end
+
+    def lan_words(found, entry)
+      return "loopback only" unless found["lan"]
+
+      found["lan"] == entry.host ? "LAN #{found["lan"]}" : "LAN #{found["lan"]} (reached as #{entry.host})"
+    end
+
+    def fail_line(message)
+      error_line("#{command_name}: #{message}")
+      nil
+    end
+  end
+end

data/lib/samagotchi/remotes.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "uri"
+require "yaml"
+require "fileutils"
+require_relative "paths"
+require_relative "atomic_file"
+
+module Samagotchi
+  # chi's remotes: other machines' chi web, each by a name chi --remote NAME
+  # (or CHI_REMOTE=NAME) takes. They live in one file only you can read,
+  # $XDG_CONFIG_HOME/samagotchi/remotes.yml (0600), their access tokens
+  # inside (a token runs commands as you on that machine):
+  #
+  #   remotes:
+  #     studio:
+  #       url: http://192.168.1.29:4567
+  #       token: …
+  #
+  # chi remote add / ls / rm write and read it (RemoteCommand).
+  module Remotes
+    FILE = "remotes.yml"
+    # A name as git takes a remote's, short: letters, digits, - and _.
+    NAME = /\A[A-Za-z0-9][A-Za-z0-9_-]{0,39}\z/
+
+    # One remote: its +name+, chi web's +url+ (scheme, host and port, no
+    # path) and its access +token+ (nil for a loopback chi web, which needs
+    # none). #inspect leaves the token out.
+    Entry = Data.define(:name, :url, :token) do
+      def host = URI(url).host
+
+      # How a failure names it: "remote studio (http://192.168.1.29:4567)".
+      def label = "remote #{name} (#{url})"
+
+      def inspect = "#<Samagotchi::Remotes::Entry name=#{name.inspect} url=#{url.inspect} token=[redacted]>"
+      alias_method :to_s, :inspect
+    end
+
+    # A name or URL chi remote can't take, or a remotes.yml it can't read:
+    # the message says which.
+    class Invalid < StandardError; end
+
+    # No remote by that name: the one message chi --remote, CHI_REMOTE and
+    # chi remote rm give.
+    class NotFound < Invalid
+      def initialize(name)
+        super("no remote #{name} (chi remote ls lists them; chi remote add NAME URL adds one)")
+      end
+    end
+
+    module_function
+
+    # @return [String] $XDG_CONFIG_HOME/samagotchi/remotes.yml
+    def path(env: ENV) = File.join(Paths.config_home(env: env), Paths::APP_DIR, FILE)
+
+    # @return [Array<Entry>] by name
+    # @raise [Invalid] a file that isn't remotes.yml's shape
+    def all(path: self.path)
+      raw = File.exist?(path) ? YAML.safe_load_file(path) : nil
+      remotes = raw.is_a?(Hash) ? raw["remotes"] : nil
+      return [] if raw.nil? || (raw.is_a?(Hash) && remotes.nil?)
+      raise Invalid, "#{Paths.tilde(path)}: remotes: is a map of names" unless remotes.is_a?(Hash)
+
+      remotes.map do |name, fields|
+        unless fields.is_a?(Hash) && fields["url"].is_a?(String)
+          raise Invalid, "#{Paths.tilde(path)}: remote #{name} has no url"
+        end
+
+        Entry.new(name: name.to_s, url: fields["url"], token: fields["token"]&.to_s)
+      end.sort_by(&:name)
+    rescue Psych::Exception => e
+      raise Invalid, "#{Paths.tilde(path)}: #{e.message}"
+    end
+
+    # @return [Entry]
+    # @raise [NotFound]
+    def find(name, path: self.path)
+      all(path: path).find { |entry| entry.name == name } or raise NotFound, name
+    end
+
+    # Saves +entry+, replacing one of its name.
+    def put(entry, path: self.path)
+      write(all(path: path).reject { |other| other.name == entry.name } + [entry], path)
+    end
+
+    # @return [Boolean] whether there was one
+    def remove(name, path: self.path)
+      entries = all(path: path)
+      kept = entries.reject { |entry| entry.name == name }
+      return false if kept.size == entries.size
+
+      write(kept, path)
+      true
+    end
+
+    # @raise [Invalid] unless +name+ is one
+    def check_name!(name)
+      return name if NAME.match?(name.to_s)
+
+      raise Invalid, "a remote's name is letters, digits, - and _ (up to 40), not #{name.inspect}"
+    end
+
+    # chi web's address as chi remote add takes it: http(s)://HOST:PORT,
+    # the port 4567 (chi web's default) when none is given, no path.
+    # @return [String]
+    # @raise [Invalid]
+    def normalize_url(text)
+      text = text.to_s.strip
+      text = "http://#{text}" unless text.match?(%r{\A[a-z][a-z0-9+.-]*://}i)
+      uri = URI.parse(text)
+      unless %w[http https].include?(uri.scheme&.downcase) && uri.host && !uri.host.empty?
+        raise Invalid, "give chi web's address, http://HOST:PORT, not #{text}"
+      end
+      raise Invalid, "give chi web's address alone, http://HOST:PORT, without a path or query" unless ["", "/"].include?(uri.path) && uri.query.nil?
+
+      port = uri.port == uri.default_port && !text.match?(%r{://[^/]+:\d+}) ? 4567 : uri.port
+      host = uri.host.include?(":") && !uri.host.start_with?("[") ? "[#{uri.host}]" : uri.host
+      "#{uri.scheme.downcase}://#{host.downcase}:#{port}"
+    rescue URI::InvalidURIError
+      raise Invalid, "give chi web's address, http://HOST:PORT, not #{text}"
+    end
+
+    def write(entries, path)
+      FileUtils.mkdir_p(File.dirname(path))
+      remotes = entries.sort_by(&:name).to_h { |entry| [entry.name, { "url" => entry.url, "token" => entry.token }.compact] }
+      AtomicFile.write(path, YAML.dump({ "remotes" => remotes }), perm: 0o600)
+    end
+    private_class_method :write
+  end
+end