ask-computer 0.1.0

data/lib/ask/computer/driver.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Ask
+  module Computer
+    class Driver
+      attr_reader :config
+
+      def initialize(config = Ask::Computer.config)
+        @config = config
+        @client = nil
+        @mutex = Mutex.new
+      end
+
+      def client
+        @mutex.synchronize { @client ||= build_client }
+      end
+
+      def start
+        client.start
+        self
+      rescue Errno::ENOENT, IOError => e
+        raise DriverNotAvailable,
+          "Cua Driver not found (#{config.driver_command}): #{e.message}. " \
+          "Install it: /bin/bash -c \"$(curl -fsSL https://cua.ai/driver/install.sh)\" — https://cua.ai/docs"
+      rescue StandardError => e
+        raise DriverNotAvailable, "Failed to start Cua Driver (#{config.driver_command}): #{e.message}"
+      end
+
+      def stop
+        @mutex.synchronize do
+          @client&.stop
+          @client = nil
+        end
+      end
+
+      def started?
+        !!(@client&.initialized?)
+      end
+
+      def tools
+        ensure_started
+        client.tools
+      end
+
+      def call_tool(name, arguments = {})
+        ensure_started
+        client.call_tool(name.to_s, arguments)
+      rescue DriverNotStarted
+        raise
+      rescue StandardError => e
+        if defined?(Ask::MCP::Error) && e.is_a?(Ask::MCP::Error)
+          raise map_mcp_error(e)
+        end
+        raise Ask::Computer::Error, e.message
+      end
+
+      def history_available?
+        ensure_started
+        names = client.tools.keys.map(&:to_s)
+        names.include?("history_status") || names.include?("history_query")
+      rescue Ask::Computer::Error
+        false
+      end
+
+      private
+
+      def ensure_started
+        raise DriverNotStarted, "Driver not started — call #start first" unless started?
+      end
+
+      def build_client
+        require "ask/mcp"
+        if config.driver_url?
+          Ask::MCP.from_http(config.driver_url)
+        else
+          Ask::MCP.from_stdio(config.driver_command, Array(config.driver_args))
+        end
+      end
+
+      def map_mcp_error(error)
+        message = error.message.to_s
+        code = extract_code(message)
+        return Ask::Computer::Error.from_code(code, message) if code
+
+        if message.match?(/permission|denied|unauthorized|forbidden/i)
+          PermissionDenied.new(message)
+        else
+          Ask::Computer::Error.new(message)
+        end
+      end
+
+      def extract_code(message)
+        if (m = message.match(/"code"\s*:\s*"(?<code>[^"]+)"/))
+          m[:code]
+        elsif (m = message.match(/\b(history_\w+|invalid_history\w*)\b/))
+          m[1]
+        end
+      end
+    end
+  end
+end

data/lib/ask/computer/errors.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Ask
+  module Computer
+    class Error < StandardError
+      CODE_MAP = {
+        "history_preview_not_admitted" => "HistoryNotAdmitted",
+        "history_key_locked" => "HistoryKeyLocked",
+        "history_key_unavailable" => "HistoryKeyUnavailable",
+        "history_key_corrupt" => "HistoryKeyCorrupt",
+        "history_key_destroy_failed" => "HistoryKeyCorrupt",
+        "history_storage_unavailable" => "HistoryStorageUnavailable",
+        "history_storage_corrupt" => "HistoryStorageCorrupt",
+        "history_quota_reached" => "HistoryQuotaReached",
+        "history_writer_stopped" => "HistoryWriterStopped",
+        "history_events_dropped" => "HistoryEventsDropped",
+        "invalid_history_query" => "InvalidHistoryQuery",
+        "invalid_history_query_range" => "InvalidHistoryQueryRange"
+      }.freeze
+
+      def self.from_code(code, message = nil)
+        klass_name = CODE_MAP[code.to_s]
+        klass = klass_name ? Ask::Computer.const_get(klass_name) : self
+        klass.new(message || code.to_s)
+      end
+    end
+    class DriverNotAvailable < Error; end
+    class DriverNotStarted < Error; end
+    class HistoryNotAvailable < Error; end
+    class HistoryNotAdmitted < Error; end
+    class HistoryKeyLocked < Error; end
+    class HistoryKeyUnavailable < Error; end
+    class HistoryKeyCorrupt < Error; end
+    class HistoryStorageUnavailable < Error; end
+    class HistoryStorageCorrupt < Error; end
+    class HistoryQuotaReached < Error; end
+    class HistoryWriterStopped < Error; end
+    class HistoryEventsDropped < Error; end
+    class InvalidHistoryQuery < Error; end
+    class InvalidHistoryQueryRange < Error; end
+    class PermissionDenied < Error; end
+
+    CODE_MAP = Error::CODE_MAP
+  end
+end

data/lib/ask/computer/history.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+module Ask
+  module Computer
+    Status = Data.define(
+      :supported, :admitted, :enabled, :paused, :encrypted,
+      :profile, :retention_days, :quota_bytes, :bytes_used,
+      :dropped_events, :health, :raw
+    ) do
+      def enabled? = !!enabled
+      def paused? = !!paused
+      def healthy? = health.to_s == "ready"
+      def available? = supported && admitted && enabled && !paused? && healthy?
+    end
+
+    Event = Data.define(
+      :specversion, :id, :source, :type, :subject, :time,
+      :datacontenttype, :dataschema, :data, :raw
+    )
+
+    QueryResult = Data.define(:events, :metadata_only, :model_context_disclosure, :raw) do
+      def metadata_only? = !!metadata_only
+    end
+
+    class History
+      DEFAULT_LIMIT = 50
+      MAX_LIMIT = 200
+
+      def initialize(driver = nil)
+        @driver = driver || Ask::Computer.driver
+      end
+
+      def status
+        payload = call("history_status", {})
+        build_status(payload)
+      end
+
+      def query(limit: DEFAULT_LIMIT, session_id: nil, since_sequence: nil, until_sequence: nil)
+        args = {}
+        args[:limit] = Integer(limit) if limit
+        args[:session_id] = session_id if session_id
+        args[:since_sequence] = Integer(since_sequence) if since_sequence
+        args[:until_sequence] = Integer(until_sequence) if until_sequence
+
+        validate_query_args!(args)
+        payload = call("history_query", args)
+        build_result(payload)
+      end
+
+      def recent(limit: DEFAULT_LIMIT, session_id: nil)
+        query(limit: limit, session_id: session_id)
+      end
+
+      def each_page(limit: DEFAULT_LIMIT, session_id: nil)
+        return enum_for(:each_page, limit: limit, session_id: session_id) unless block_given?
+
+        cursor = nil
+        loop do
+          args = { limit: limit }
+          args[:session_id] = session_id if session_id
+          args[:until_sequence] = cursor if cursor
+          result = query(**args)
+          break if result.events.empty?
+
+          yield result
+          break if result.events.size < limit
+
+          earliest = result.events.map { |e| e.data[:sequence] || e.data["sequence"] }.compact.min
+          break unless earliest && earliest > 1
+
+          cursor = earliest - 1
+        end
+      end
+
+      private
+
+      def call(name, args)
+        raw = @driver.call_tool(name, args)
+        payload = unwrap_content(raw)
+        if payload.is_a?(Array) && payload.first.is_a?(Hash)
+          text = payload.first[:text] || payload.first["text"]
+          raise HistoryNotAvailable, text if text.is_a?(String) && text.match?(/Unknown tool/i)
+        elsif payload.is_a?(Hash)
+          text = payload[:text] || payload["text"]
+          raise HistoryNotAvailable, text if text.is_a?(String) && text.match?(/Unknown tool/i)
+        end
+        payload
+      rescue Ask::Computer::Error
+        raise
+      rescue StandardError => e
+        code = extract_code(e.message)
+        raise Ask::Computer::Error.from_code(code, e.message) if code
+
+        raise Ask::Computer::Error, e.message
+      end
+
+      def unwrap_content(raw)
+        if raw.is_a?(Array)
+          if raw.first.is_a?(Hash)
+            text = raw.first[:text] || raw.first["text"]
+            if text.is_a?(String)
+              begin
+                parsed = JSON.parse(text, symbolize_names: true)
+                return parsed if parsed.is_a?(Hash)
+              rescue JSON::ParserError
+              end
+            end
+          end
+          return raw
+        end
+
+        return raw if raw.is_a?(Hash) && !raw.key?(:content) && !raw.key?("content")
+
+        content = raw[:content] || raw["content"] if raw.is_a?(Hash)
+        return raw unless content.is_a?(Array) && content.first
+
+        first = content.first
+        text = first[:text] || first["text"]
+        return raw unless text
+
+        JSON.parse(text, symbolize_names: true)
+      rescue JSON::ParserError
+        raw
+      end
+
+      def build_status(payload)
+        h = stringify(payload)
+        Status.new(
+          supported: !!h["supported"],
+          admitted: !!h["admitted"],
+          enabled: !!h["enabled"],
+          paused: !!h["paused"],
+          encrypted: !!h["encrypted"],
+          profile: h["profile"],
+          retention_days: h["retention_days"]&.to_i || 7,
+          quota_bytes: h["quota_bytes"]&.to_i || 104_857_600,
+          bytes_used: h["bytes_used"]&.to_i || 0,
+          dropped_events: h["dropped_events"]&.to_i || 0,
+          health: h["health"]&.to_s || "unknown",
+          raw: payload
+        )
+      end
+
+      def build_result(payload)
+        h = stringify(payload)
+        events = Array(h["events"]).map { |e| build_event(e) }
+        QueryResult.new(
+          events: events,
+          metadata_only: h["metadata_only"],
+          model_context_disclosure: h["model_context_disclosure"],
+          raw: payload
+        )
+      end
+
+      def build_event(hash)
+        h = stringify(hash)
+        Event.new(
+          specversion: h["specversion"],
+          id: h["id"],
+          source: h["source"],
+          type: h["type"],
+          subject: h["subject"],
+          time: h["time"],
+          datacontenttype: h["datacontenttype"],
+          dataschema: h["dataschema"],
+          data: h["data"] || {},
+          raw: hash
+        )
+      end
+
+      def stringify(obj)
+        return obj unless obj.is_a?(Hash)
+
+        obj.transform_keys(&:to_s)
+      end
+
+      def validate_query_args!(args)
+        if args[:limit] && (args[:limit] < 1 || args[:limit] > MAX_LIMIT)
+          raise InvalidHistoryQuery, "limit must be 1..#{MAX_LIMIT} (got #{args[:limit]})"
+        end
+        if args[:session_id] && (args[:session_id].to_s.empty? || args[:session_id].to_s.length > 128)
+          raise InvalidHistoryQuery, "session_id must be 1..128 characters"
+        end
+        if args[:since_sequence] && args[:since_sequence] < 1
+          raise InvalidHistoryQuery, "since_sequence must be >= 1"
+        end
+        if args[:until_sequence] && args[:until_sequence] < 1
+          raise InvalidHistoryQuery, "until_sequence must be >= 1"
+        end
+        if args[:since_sequence] && args[:until_sequence] && args[:since_sequence] > args[:until_sequence]
+          raise InvalidHistoryQueryRange, "since_sequence (#{args[:since_sequence]}) must not exceed until_sequence (#{args[:until_sequence]})"
+        end
+      end
+
+      def extract_code(message)
+        if (m = message.match(/"code"\s*:\s*"(?<code>[^"]+)"/))
+          m[:code]
+        elsif (m = message.match(/\b(history_\w+|invalid_history\w*)\b/))
+          m[1]
+        end
+      end
+    end
+  end
+end

data/lib/ask/computer/installer.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Ask
+  module Computer
+    class Installer
+      INSTALL_URL = "https://cua.ai/driver/install.sh"
+      UNINSTALL_URL = "https://cua.ai/driver/uninstall.sh"
+
+      Result = Data.define(:ok, :command, :stdout, :stderr, :exit_code, :message) do
+        def ok? = !!ok
+        def success? = ok?
+      end
+
+      class << self
+        def installed?
+          !which(cua_bin).nil?
+        end
+
+        def version
+          out, _err, status = Open3.capture3(cua_bin, "--version")
+          return nil unless status.success?
+          out.strip
+        rescue StandardError
+          nil
+        end
+
+        def history_status
+          out, err, status = Open3.capture3(cua_bin, "history", "status", "--json")
+          raw = out.empty? ? err : out
+          return Result.new(ok: false, command: "#{cua_bin} history status", stdout: out, stderr: err, exit_code: status.exitstatus, message: raw.strip) unless status.success?
+          Result.new(ok: true, command: "#{cua_bin} history status", stdout: out, stderr: err, exit_code: 0, message: out.strip)
+        rescue StandardError => e
+          Result.new(ok: false, command: "#{cua_bin} history status", stdout: "", stderr: e.message, exit_code: 1, message: e.message)
+        end
+
+        def install(channel: "stable", bin_dir: nil, no_modify_path: false, dry_run: false)
+          args = []
+          args += ["--channel", channel.to_s] if channel
+          args += ["--bin-dir", bin_dir] if bin_dir && !bin_dir.empty?
+          args << "--no-modify-path" if no_modify_path
+
+          cmd = build_install_command(args)
+          return Result.new(ok: true, command: cmd, stdout: "", stderr: "", exit_code: 0, message: "dry run: #{cmd}") if dry_run
+
+          run_shell(cmd)
+        end
+
+        def enable_history
+          run_cua("history", "enable")
+        end
+
+        def disable_history
+          run_cua("history", "disable")
+        end
+
+        def history_enable_result
+          enable_history
+        end
+
+        def uninstall(purge: false)
+          args = purge ? ["--purge"] : []
+          cmd = "/bin/bash -c \"$(curl -fsSL #{UNINSTALL_URL})\"#{args.empty? ? "" : " -- #{args.join(" ")}"}"
+          run_shell(cmd)
+        end
+
+        def status
+          {
+            installed: installed?,
+            version: installed? ? version : nil,
+            bin: which(cua_bin),
+            history: history_status_payload
+          }
+        end
+
+        def setup(channel: "stable", enable_history: false, bin_dir: nil, no_modify_path: false, dry_run: false)
+          steps = []
+          unless installed?
+            r = install(channel: channel, bin_dir: bin_dir, no_modify_path: no_modify_path, dry_run: dry_run)
+            steps << [:install, r]
+            return steps unless r.ok?
+          else
+            steps << [:install, Result.new(ok: true, command: "already installed", stdout: "", stderr: "", exit_code: 0, message: "cua-driver already installed (#{version})")]
+          end
+
+          if enable_history
+            if dry_run
+              r = Result.new(ok: true, command: "#{cua_bin} history enable", stdout: "", stderr: "", exit_code: 0, message: "dry run: #{cua_bin} history enable")
+            else
+              r = enable_history
+            end
+            steps << [:enable_history, r]
+          end
+
+          steps
+        end
+
+        private
+
+        def cua_bin
+          Ask::Computer.config.driver_command
+        end
+
+        def which(bin)
+          out, _err, status = Open3.capture3("which", bin)
+          return nil unless status.success?
+          path = out.strip
+          path.empty? ? nil : path
+        rescue StandardError
+          nil
+        end
+
+        def build_install_command(extra_args)
+          arg_str = extra_args.empty? ? "" : " -- #{extra_args.join(" ")}"
+          "/bin/bash -c \"$(curl -fsSL #{INSTALL_URL})\"#{arg_str}"
+        end
+
+        def run_shell(cmd)
+          out, err, status = Open3.capture3("/bin/bash", "-c", cmd)
+          ok = status.success?
+          msg = ok ? out.strip : (err.strip.empty? ? out.strip : err.strip)
+          Result.new(ok: ok, command: cmd, stdout: out, stderr: err, exit_code: status.exitstatus, message: msg)
+        rescue StandardError => e
+          Result.new(ok: false, command: cmd, stdout: "", stderr: e.message, exit_code: 1, message: e.message)
+        end
+
+        def run_cua(*args)
+          out, err, status = Open3.capture3(cua_bin, *args)
+          ok = status.success?
+          msg = ok ? out.strip : (err.strip.empty? ? out.strip : err.strip)
+          Result.new(ok: ok, command: "#{cua_bin} #{args.join(" ")}", stdout: out, stderr: err, exit_code: status.exitstatus, message: msg)
+        rescue StandardError => e
+          Result.new(ok: false, command: "#{cua_bin} #{args.join(" ")}", stdout: "", stderr: e.message, exit_code: 1, message: e.message)
+        end
+
+        def history_status_payload
+          r = history_status
+          return { ok: false, message: r.message } unless r.ok?
+          begin
+            require "json"
+            JSON.parse(r.stdout)
+          rescue StandardError
+            { ok: true, raw: r.stdout }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ask/computer/sandbox.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Ask
+  module Computer
+    class Sandbox
+      attr_reader :driver
+
+      def initialize(driver = nil)
+        @driver = driver || Ask::Computer.driver
+      end
+
+      def screenshot
+        result = @driver.call_tool("computer_screenshot", {})
+        extract_image(result)
+      end
+
+      def ephemeral(image = "linux", &block)
+        started = ensure_sandbox_tool?
+        raise DriverNotAvailable, "Sandbox not available on this driver" unless started
+
+        result = @driver.call_tool("sandbox_create", { image: image.to_s })
+        id = result["sandbox_id"] || result[:sandbox_id] || result.dig("content", 0, "text")
+        handle = Handle.new(id.to_s, @driver)
+        return handle unless block
+
+        begin
+          yield handle
+        ensure
+          handle.destroy
+        end
+      end
+
+      class Handle
+        attr_reader :id, :driver
+
+        def initialize(id, driver)
+          @id = id
+          @driver = driver
+        end
+
+        def screenshot
+          @driver.call_tool("sandbox_screenshot", { sandbox_id: id })
+        end
+
+        def click(x, y)
+          @driver.call_tool("sandbox_click", { sandbox_id: id, x: Integer(x), y: Integer(y) })
+        end
+
+        def type(text)
+          @driver.call_tool("sandbox_type", { sandbox_id: id, text: text.to_s })
+        end
+
+        def shell(command)
+          @driver.call_tool("sandbox_shell", { sandbox_id: id, command: command.to_s })
+        end
+
+        def destroy
+          @driver.call_tool("sandbox_destroy", { sandbox_id: id })
+        rescue StandardError
+          nil
+        end
+      end
+
+      private
+
+      def ensure_sandbox_tool?
+        tools = @driver.tools
+        tools.key?("sandbox_create") || tools.key?(:sandbox_create)
+      rescue StandardError
+        false
+      end
+
+      def extract_image(result)
+        return result if result.is_a?(Hash) && (result["type"] == "image" || result[:type] == "image")
+
+        content = result[:content] || result["content"]
+        return result unless content.is_a?(Array)
+
+        image = content.find { |c| (c[:type] || c["type"]) == "image" }
+        image || result
+      end
+    end
+  end
+end

data/lib/ask/computer/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ask
+  module Computer
+    VERSION = "0.1.0"
+  end
+end

data/lib/ask/computer.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "computer/version"
+require_relative "computer/errors"
+require_relative "computer/config"
+require_relative "computer/context"
+
+module Ask
+  module Computer
+    class << self
+      def config
+        @config ||= Config.new
+      end
+
+      def configure
+        yield config if block_given?
+        config
+      end
+
+      def reset!
+        @config = Config.new
+        @driver = nil
+        @history = nil
+        @sandbox = nil
+      end
+
+      def driver
+        @driver ||= Driver.new(config)
+      end
+
+      def driver=(instance)
+        @driver = instance
+      end
+
+      def history(driver = nil)
+        History.new(driver || self.driver)
+      end
+
+      def sandbox(driver = nil)
+        Sandbox.new(driver || self.driver)
+      end
+
+      # Launch (or find) a desktop app and resolve its live window.
+      #
+      #   app = Ask::Computer.launch("com.apple.calculator")
+      #   app.press("7")
+      #
+      def launch(bundle_id_or_name, driver: nil)
+        App.launch(bundle_id_or_name, driver: driver || self.driver)
+      end
+
+      def installer
+        Installer
+      end
+
+      def installed? = Installer.installed?
+      def install(...) = Installer.install(...)
+      def setup(...) = Installer.setup(...)
+      def status = Installer.status
+    end
+
+    autoload :Driver, "ask/computer/driver"
+    autoload :App, "ask/computer/app"
+    autoload :EmptyAccessibilityTree, "ask/computer/app"
+    autoload :History, "ask/computer/history"
+    autoload :Sandbox, "ask/computer/sandbox"
+    autoload :Installer, "ask/computer/installer"
+    autoload :CLI, "ask/computer/cli"
+  end
+end