ask-computer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f378e2e365393b2cd3dce570227e5e9cf0c95f6c193a154b2752d3d8249eb8c0
+  data.tar.gz: 22f6341c0f2e846c79feb01ecc350dc880032073eac0b70a2045103aa91f69a5
+SHA512:
+  metadata.gz: dd7433804fd2c620263caed3aba79fac7afbcb77f9916ec8a5b710a26868e6afe115cc04ee1a4d8d66e1a1abfbfdbf060c12e08aacd70b2746ba6095c5520182
+  data.tar.gz: 954591cc19cfc242a2b28bbdd35c0e6dbaf544a554339b64322485ac1742e200543b3926ceb1f546bd9e4d4f473f37b0029983a9745f55c40c8f70e01a1661a4

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## [0.1.0] - 2026-08-20
+
+### Added
+
+- Initial release of `ask-computer` — computer use for the ask-rb ecosystem.
+- `Ask::Computer` — driver/history/sandbox facades with `configure` / `reset!`.
+- `Ask::Computer::Driver` — MCP stdio/HTTP client for Cua Driver (`call_tool`, `tools`, `history_available?`, `start`/`stop`).
+- `Ask::Computer::History` — encrypted history client (`status`, `query`, `recent`, `each_page`) with RFC validation (1..200 limit, inclusive sequence bounds, session_id 1..128).
+- `Ask::Computer::Sandbox` — VM sandbox facade (`screenshot`, `ephemeral` with `Handle`).
+- `Ask::Computer::Error` hierarchy mapped from RFC codes (`HistoryKeyLocked`, `StorageCorrupt`, `QuotaReached`, etc.) via `Error.from_code`.
+- `Ask::Tools::Computer::*` — `HistoryStatus`, `HistoryQuery`, `Screenshot`, `Click`, `Type`, `Key` as `Ask::Tool` subclasses.
+- Bundled skill `computer.use_computer` (`SKILL.md` + `references/history.md`) discovered by `ask-skills` `Source::Gems` — no `ask-skills` runtime dep needed.
+- Dependencies: `ask-core >= 0.11.3`, `ask-tools >= 0.6.2`.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaka Ruto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,141 @@
+# ask-computer
+
+[![Gem Version](https://badge.fury.io/rb/ask-computer.svg)](https://badge.fury.io/rb/ask-computer)
+
+Computer use for the ask-rb ecosystem. Drive desktop apps in the background via Cua Driver — screenshots, clicks, typing, sandboxed VMs, and encrypted Computer History. Wraps Cua's MCP tools as `Ask::Tool` subclasses and ships a bundled `computer.use_computer` skill discovered by `ask-skills`.
+
+## Installation
+
+```ruby
+gem "ask-computer"
+```
+
+```bash
+bundle install
+```
+
+### Cua Driver — Easy Setup
+
+`ask-computer` talks to a running Cua Driver daemon via MCP (stdio `cua-driver mcp`).
+
+**One command (recommended):**
+
+```bash
+bundle exec ask-computer setup --with-history          # stable + history
+bundle exec ask-computer setup --channel nightly --with-history  # nightly preview for Computer History
+bundle exec ask-computer setup --dry-run               # preview without running
+```
+
+Or step by step:
+
+```bash
+bundle exec ask-computer install --channel nightly     # or stable (default)
+bundle exec ask-computer history enable
+bundle exec ask-computer status                        # driver version + history health
+bundle exec ask-computer history status                # raw history JSON
+```
+
+Ruby API for the same flow:
+
+```ruby
+require "ask-computer"
+
+Ask::Computer.setup(channel: "nightly", enable_history: true)
+Ask::Computer.status        # => { installed: true, version: "cua-driver 0.21.0", history: { "health" => "ready" } }
+Ask::Computer.install(channel: "stable", dry_run: true)  # preview the shell command
+Ask::Computer::Installer.version   # => "cua-driver 0.21.0"
+```
+
+Manual install still works: `/bin/bash -c "$(curl -fsSL https://cua.ai/driver/install.sh)"`
+See https://cua.ai/docs and https://github.com/trycua/cua.
+
+## Quick Start
+
+```ruby
+require "ask-computer"
+
+# Connect to the local daemon
+driver = Ask::Computer.driver
+driver.start
+
+# Drive the desktop (background — does not steal cursor)
+driver.call_tool("computer_screenshot", {})
+driver.call_tool("computer_click", { x: 120, y: 80 })
+driver.call_tool("computer_type", { text: "Hello" })
+driver.call_tool("computer_key", { key: "Enter" })
+
+# Encrypted Computer History (permission-gated, metadata-only)
+history = Ask::Computer.history
+status = history.status
+# => #<data Status supported=true admitted=true enabled=true ... health="ready">
+
+if status.enabled? && status.healthy?
+  page = history.recent(limit: 20)
+  page.events.each { |e| puts "#{e.type} seq=#{e.data[:sequence]}" }
+end
+
+# Bounded, paginated reads
+history.each_page(limit: 50) do |page|
+  page.events.each { |e| puts e.type }
+end
+
+# Sandbox VMs (requires driver with sandbox tools)
+sandbox = Ask::Computer.sandbox
+sandbox.ephemeral(:linux) do |vm|
+  vm.shell("echo hello")
+  vm.screenshot
+  vm.click(100, 200)
+end
+```
+
+### As Ask::Tool subclasses (for agent sessions)
+
+```ruby
+require "ask-computer"
+
+# HistoryStatus / HistoryQuery map to history.status / history.query
+# Screenshot / Click / Type / Key map to the corresponding Cua tools
+Ask::Tools::Computer::HistoryStatus.new.execute
+Ask::Tools::Computer::HistoryQuery.new.execute(limit: 20, session_id: "abc")
+Ask::Tools::Computer::Screenshot.new.execute
+Ask::Tools::Computer::Click.new.execute(x: 100, y: 200)
+```
+
+## Configuration
+
+```ruby
+Ask::Computer.configure do |c|
+  c.driver_command = "cua-driver"   # binary for stdio transport
+  c.driver_args = ["mcp"]           # extra args (default: ["mcp"])
+  c.driver_url = nil                # if set, uses HTTP transport instead of stdio
+  c.transport = :stdio              # :stdio or :http
+  c.history_default_limit = 50
+end
+
+# Env vars
+# ASK_COMPUTER_DRIVER_COMMAND  — override driver binary (default: cua-driver)
+# ASK_COMPUTER_DRIVER_ARGS     — override driver args (default: mcp)
+# ASK_COMPUTER_DRIVER_URL      — if set, use HTTP transport
+```
+
+## Bundled Skill
+
+The gem ships `lib/ask/skills/computer.use_computer/SKILL.md` (with `references/history.md`). It is auto-discovered by `ask-skills` via `Source::Gems` — no extra dependency needed. Load it in an agent:
+
+```ruby
+Ask::Skills.discover        # finds computer.use_computer
+registry["computer.use_computer"]
+```
+
+## History Contract
+
+- `History#status` → `Ask::Computer::Status` (supported/admitted/enabled/paused/health/retention/quota/bytes_used/dropped_events)
+- `History#query(limit:, session_id:, since_sequence:, until_sequence:)` → `QueryResult` (events/metadata_only/model_context_disclosure)
+- `History#recent` — alias for `query`
+- `History#each_page` — paginates with `until_sequence` (inclusive bounds, handles gaps)
+- Typed errors: `HistoryNotAdmitted`, `HistoryKeyLocked`, `HistoryStorageCorrupt`, `InvalidHistoryQuery`, `PermissionDenied`, etc.
+- Events are CloudEvents 1.0, `dataschema: urn:cua-driver:schema:history-event:v0`, ordered by `data.sequence` ascending. Metadata-only — no screenshots or typed text.
+
+## Full Documentation
+
+The full ask-rb documentation lives at https://ask-rb.github.io/ask-docs.

data/exe/ask-computer

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "ask/computer/cli"
+require "ask-computer"
+
+exit Ask::Computer::CLI.run(ARGV)

data/lib/ask/computer/app.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+module Ask
+  module Computer
+    # High-level facade for driving one desktop app.
+    #
+    # Wraps the four workarounds found live on macOS (Cua Driver 0.21.0):
+    #
+    # 1. `list_windows` only returns a count — probe `get_window_state`
+    #    with small IDs to find the live window.
+    # 2. `press_key`/`type_text` without a pid targets the frontmost app,
+    #    so `bring_to_front` first (falls back to pid-scoped keys when the
+    #    app has multiple windows).
+    # 3. Apps with custom rendering (Calculator) expose `elements=0` — read
+    #    state back through the clipboard (`Cmd+C`) instead of the AX tree.
+    # 4. Every unexpected payload surfaces a typed error that says what to
+    #    try next, instead of a raw `Symbol into Integer` crash.
+    #
+    #   app = Ask::Computer::App.launch("com.apple.calculator")
+    #   app.type("7*8")          # frontmost keystrokes
+    #   app.press("return")
+    #   app.display              # clipboard readback for Calculator-like apps
+    #   app.state                # AX text when the app exposes it
+    #
+    class App
+      attr_reader :driver, :pid, :window_id, :bundle_id, :name
+
+      PROBE_IDS = (1..24).to_a.freeze
+      DISPLAY_CLEAR_KEYS = %w[escape].freeze
+
+      class << self
+        # Launch (or find) an app and resolve its live window.
+        #
+        # @param bundle_id_or_name [String] `com.apple.calculator` or `Calculator`
+        # @param driver [Driver] defaults to `Ask::Computer.driver` (must be started)
+        # @return [App]
+        # @raise [DriverNotAvailable] when no window can be resolved
+        def launch(bundle_id_or_name, driver: nil)
+          drv = driver || Ask::Computer.driver
+          new(pid: resolve_pid(drv, bundle_id_or_name), driver: drv)
+        end
+
+        private
+
+        def resolve_pid(driver, bundle_id_or_name)
+          id = bundle_id_or_name.to_s
+          result = driver.call_tool("launch_app", id.start_with?("com.") || id.include?(".") ? { bundle_id: id } : { name: id })
+          text = content_text(result)
+          pid = text.match(/pid (\d+)/)&.then { _1[1].to_i }
+          return pid if pid
+
+          apps = content_text(driver.call_tool("list_apps", {}))
+          short = id.split(".").last.downcase
+          line = apps.lines.find { |l| l.downcase.include?(short) && l.match(/pid (\d+)/) }
+          found = line&.match(/pid (\d+)/)&.then { _1[1].to_i }
+          return found if found
+
+          raise DriverNotAvailable, "Could not launch or find app #{id.inspect}. Tried bundle_id/name and list_apps."
+        end
+
+        def content_text(result)
+          return result.to_s unless result.is_a?(Array)
+
+          result.map { |c| c[:text] || c["text"] || "" }.join("\n")
+        end
+      end
+
+      def initialize(pid:, driver: nil, window_id: nil, bundle_id: nil, name: nil)
+        @driver = driver || Ask::Computer.driver
+        @pid = Integer(pid)
+        @window_id = window_id && Integer(window_id)
+        @resolved_window = !@window_id.nil?
+        @bundle_id = bundle_id
+        @name = name
+        @mutex = Mutex.new
+      end
+
+      # Resolve (and memoize) the live window for this pid by probing
+      # `get_window_state` — works when `list_windows` only returns a count.
+      #
+      # @return [Integer] the live window id
+      # @raise [DriverNotAvailable] when no live window is found
+      def resolve_window!(ids: PROBE_IDS)
+        @mutex.synchronize do
+          return @window_id if @window_id && @resolved_window
+
+          Array(ids).each do |wid|
+            if live_window?(wid)
+              @window_id = wid
+              @resolved_window = true
+              return @window_id
+            end
+          end
+
+          raise DriverNotAvailable,
+            "No live window for pid #{pid}. The app may not have opened a window yet, " \
+            "or its windows are on another Space. Try `bring_to_front` first."
+        end
+      end
+
+      # Bring the app to the foreground so pid-less keystrokes land.
+      # Falls back gracefully when the app owns several windows.
+      #
+      # @return [String] the driver message
+      def bring_to_front!
+        args = { pid: pid }
+        args[:window_id] = window_id if window_id
+        text = text_of(driver.call_tool("bring_to_front", args))
+        if text.match?(/more than one eligible/i)
+          resolve_window!
+          text = text_of(driver.call_tool("bring_to_front", { pid: pid, window_id: @window_id }))
+        end
+        text
+      end
+
+      # Type text into the app. Prefers the live window's text area when one
+      # is exposed, otherwise sends frontmost keystrokes after `bring_to_front`.
+      def type(text, element_index: nil)
+        bring_to_front!
+        args = { text: text.to_s }
+        args[:pid] = pid
+        args[:window_id] = window_id if window_id
+        args[:element_index] = element_index if element_index
+        text_of(driver.call_tool("type_text", args))
+      rescue Ask::Computer::Error => e
+        if e.message.match?(/more than one eligible/i)
+          resolve_window!
+          retry
+        end
+        raise friendly_error("type_text", e)
+      end
+
+      # Press a single key (`return`, `escape`, `7`, `*`, ...).
+      # Sends pid-scoped first, falls back to frontmost (no pid) when the
+      # driver refuses (e.g. off-Space window).
+      def press(key)
+        wid = window_id || resolve_window!
+        begin
+          return text_of(driver.call_tool("press_key", { pid: pid, window_id: wid, key: key.to_s }))
+        rescue Ask::Computer::Error => e
+          raise friendly_error("press_key", e) unless fallbackable?(e)
+        end
+        bring_to_front!
+        text_of(driver.call_tool("press_key", { key: key.to_s }))
+      rescue Ask::Computer::Error => e
+        raise friendly_error("press_key", e)
+      end
+
+      # Raw AX markdown for the live window. Raises {EmptyAccessibilityTree}
+      # with guidance when the app renders custom content (Calculator).
+      def state(include_screenshot: false)
+        wid = window_id || resolve_window!
+        payload = driver.call_tool(
+          "get_window_state",
+          { pid: pid, window_id: wid, include_screenshot: include_screenshot }
+        )
+        text = text_of(payload)
+        raise EmptyAccessibilityTree.new(self) if text.match?(/elements=0/)
+
+        text
+      end
+
+      # Read the app's visible value via the clipboard (`Cmd+C`).
+      # The Calculator workaround: its display is `AXStaticText` with
+      # `elements=0`, so the AX tree can't be read — copy and read back.
+      #
+      # @return [String] clipboard text after copy
+      def display
+        d = @driver
+        begin
+          attempt_display(d)
+        rescue Ask::Computer::Error => e
+          raise friendly_error("display", e) unless fallbackable?(e)
+
+          @mutex.synchronize { @window_id = nil }
+          resolve_window!
+          attempt_display(d)
+        end
+      end
+
+      # Clear the app's entry field (`escape` by default).
+      def clear(key: "escape")
+        press(key)
+      end
+
+      private
+
+      def attempt_display(driver)
+        wid = window_id || resolve_window!
+        driver.call_tool("hotkey", { pid: pid, window_id: wid, keys: %w[cmd c] })
+        sleep 0.2
+        read = driver.call_tool("clipboard_read", {})
+        clipboard_text(read) || raise(
+          Ask::Computer::Error,
+          "clipboard_read returned no text for pid #{pid}. " \
+          "The app may not support Cmd+C; use #state instead."
+        )
+      end
+
+      def live_window?(wid)
+        return false unless wid
+
+        payload = driver.call_tool(
+          "get_window_state",
+          { pid: pid, window_id: wid, include_screenshot: false }
+        )
+        text_of(payload).match?(/elements=\d+/) &&
+          !text_of(payload).match?(/not a live window|stale/i)
+      rescue Ask::Computer::Error
+        false
+      end
+
+      def fallbackable?(error)
+        error.message.match?(/off_space|not among|more than one eligible|Unknown tool/i)
+      end
+
+      def friendly_error(tool, error)
+        message = error.message.to_s
+        hint =
+          if message.match?(/bare element_index/)
+            " Pass element_index together with the window's snapshot, or use pixel x/y on the window PNG."
+          elsif message.match?(/off_space|not among the process/)
+            " The window may be on another Space. Called bring_to_front first — verify the app is visible."
+          elsif message.match?(/elements=0|empty/i)
+            " The app renders custom content with no AX tree. Use #display (clipboard readback) instead of #state."
+          elsif message.match?(/Unknown tool/i)
+            " The driver build does not advertise this tool (stable vs nightly). Check history_available? / installer status."
+          end
+        Ask::Computer::Error.new("#{tool} failed for pid #{pid}: #{message}#{hint}")
+      end
+
+      def text_of(result)
+        return result.to_s unless result.is_a?(Array)
+
+        result.map { |c| c[:text] || c["text"] || "" }.join("\n")
+      end
+
+      def clipboard_text(result)
+        parts = result.is_a?(Array) ? result : [result]
+        parts.each do |part|
+          next unless part.is_a?(Hash)
+
+          text = part[:text] || part["text"]
+          return text unless text.nil? || text.match?(/omitted|privacy-sensitive/i)
+          sc = part[:structuredContent] || part["structuredContent"]
+          if sc.is_a?(Hash)
+            t = sc[:text] || sc["text"]
+            return t if t && !t.empty?
+          end
+        end
+        nil
+      end
+    end
+
+    # Raised by {App#state} when the app exposes `elements=0`
+    # (custom rendering, e.g. Calculator) — use {App#display} instead.
+    class EmptyAccessibilityTree < Error
+      def initialize(app)
+        super(
+          "pid #{app.pid} exposes elements=0 (custom rendering, e.g. Calculator). " \
+          "Use #display (Cmd+C clipboard readback) or vision on the window PNG instead of #state."
+        )
+      end
+    end
+  end
+end

data/lib/ask/computer/cli.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Ask
+  module Computer
+    module CLI
+      module_function
+
+      def run(argv = ARGV)
+        argv = argv.dup
+        command = argv.shift
+
+        case command
+        when "install" then cmd_install(argv)
+        when "setup" then cmd_setup(argv)
+        when "status" then cmd_status
+        when "history" then cmd_history(argv)
+        when "uninstall" then cmd_uninstall(argv)
+        when "help", "--help", "-h", nil then cmd_help
+        else
+          warn "Unknown command: #{command}"
+          cmd_help
+          1
+        end
+      end
+
+      def cmd_install(argv)
+        opts = { channel: "stable", bin_dir: nil, no_modify_path: false, dry_run: false }
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: ask-computer install [options]"
+          o.on("--channel NAME", "stable or nightly [stable]") { |v| opts[:channel] = v }
+          o.on("--bin-dir PATH", "Install dir (default ~/.local/bin)") { |v| opts[:bin_dir] = v }
+          o.on("--no-modify-path", "Do not append PATH export to shell rc") { opts[:no_modify_path] = true }
+          o.on("--dry-run", "Print the install command without running it") { opts[:dry_run] = true }
+          o.on("-h", "--help", "Show help") { puts o; return 0 }
+        end
+        parser.parse!(argv)
+        result = Installer.install(**opts)
+        puts result.message
+        warn result.stderr unless result.stderr.empty?
+        result.ok? ? 0 : 1
+      end
+
+      def cmd_setup(argv)
+        opts = { channel: "stable", enable_history: false, bin_dir: nil, no_modify_path: false, dry_run: false }
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: ask-computer setup [options]"
+          o.on("--channel NAME", "stable or nightly [stable]") { |v| opts[:channel] = v }
+          o.on("--with-history", "Enable Computer History after install") { opts[:enable_history] = true }
+          o.on("--bin-dir PATH", "Install dir") { |v| opts[:bin_dir] = v }
+          o.on("--no-modify-path", "Do not modify shell rc") { opts[:no_modify_path] = true }
+          o.on("--dry-run", "Print commands without running") { opts[:dry_run] = true }
+          o.on("-h", "--help", "Show help") { puts o; return 0 }
+        end
+        parser.parse!(argv)
+        steps = Installer.setup(**opts)
+        steps.each do |name, result|
+          label = name == :install ? "Install" : "History enable"
+          puts "#{label}: #{result.ok? ? "ok" : "failed"} — #{result.message}"
+          warn result.stderr unless result.stderr.empty?
+        end
+        steps.all? { |_, r| r.ok? } ? 0 : 1
+      end
+
+      def cmd_status
+        s = Installer.status
+        puts "Installed: #{s[:installed] ? "yes (#{s[:bin]})" : "no"}"
+        puts "Version: #{s[:version] || "(unknown)"}" if s[:installed]
+        h = s[:history]
+        if h.is_a?(Hash) && h[:ok] == false
+          puts "History: #{h[:message] || "unavailable"}"
+        elsif h.is_a?(Hash)
+          puts "History: #{h["health"] || h[:health] || h.inspect[0,120]}"
+        else
+          puts "History: #{h.inspect[0,120]}"
+        end
+        0
+      end
+
+      def cmd_history(argv)
+        sub = argv.shift
+        case sub
+        when "enable"
+          r = Installer.enable_history
+          puts r.message
+          r.ok? ? 0 : 1
+        when "disable"
+          r = Installer.disable_history
+          puts r.message
+          r.ok? ? 0 : 1
+        when "status"
+          r = Installer.history_status
+          puts r.stdout.empty? ? r.message : r.stdout
+          warn r.stderr unless r.stderr.empty?
+          r.ok? ? 0 : 1
+        else
+          puts "Usage: ask-computer history <enable|disable|status>"
+          1
+        end
+      end
+
+      def cmd_uninstall(argv)
+        purge = argv.include?("--purge")
+        r = Installer.uninstall(purge: purge)
+        puts r.message
+        r.ok? ? 0 : 1
+      end
+
+      def cmd_help
+        puts <<~HELP
+          ask-computer — Cua Driver helper for the ask-computer gem
+
+          Usage:
+            ask-computer install [--channel stable|nightly] [--dry-run]
+            ask-computer setup [--channel nightly] [--with-history] [--dry-run]
+            ask-computer status
+            ask-computer history <enable|disable|status>
+            ask-computer uninstall [--purge]
+
+          Examples:
+            ask-computer install                          # stable channel
+            ask-computer install --channel nightly        # nightly (for Computer History preview)
+            ask-computer setup --channel nightly --with-history
+            ask-computer status
+            ask-computer history status --json
+
+          Ruby API:
+            Ask::Computer.install(channel: "nightly", dry_run: true)
+            Ask::Computer.setup(channel: "nightly", enable_history: true)
+            Ask::Computer.status
+            Ask::Computer::Installer.version
+        HELP
+        0
+      end
+    end
+  end
+end

data/lib/ask/computer/config.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Ask
+  module Computer
+    class Config
+      attr_accessor :driver_command, :driver_args, :driver_url, :transport
+      attr_accessor :history_default_limit
+
+      def initialize
+        @driver_command = ENV.fetch("ASK_COMPUTER_DRIVER_COMMAND", "cua-driver")
+        @driver_args = ENV["ASK_COMPUTER_DRIVER_ARGS"] ? ENV["ASK_COMPUTER_DRIVER_ARGS"].split : ["mcp"]
+        @driver_url = ENV["ASK_COMPUTER_DRIVER_URL"]
+        @transport = :stdio
+        @history_default_limit = 50
+      end
+
+      def driver_url?
+        driver_url && !driver_url.empty?
+      end
+    end
+  end
+end

data/lib/ask/computer/context.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Ask
+  module Computer
+    DESCRIPTION = "Computer use via Cua Driver — drive desktop apps in the background, " \
+                  "take screenshots, click, type, and query encrypted Computer History"
+    DOCS_URL = "https://cua.ai/docs"
+    DRIVER_INSTALL_URL = "https://cua.ai/driver/install.sh"
+    HISTORY_DOCS_URL = "https://github.com/trycua/cua/blob/main/libs/cua-driver/docs/computer-history-preview.md"
+    AUTH_NAME = :cua_driver
+    AUTH_HOW = "Install Cua Driver: /bin/bash -c \"$(curl -fsSL https://cua.ai/driver/install.sh)\" — " \
+               "see https://cua.ai/docs/tutorials/drive-your-first-app"
+    GEM_NAME = "cua-driver"
+    GEM_DOCS = "https://cua.ai/docs"
+    QUICK_START = <<~RUBY
+      require "ask-computer"
+
+      # Connect to the local Cua Driver daemon
+      driver = Ask::Computer.driver
+      driver.start
+
+      # Drive the desktop
+      driver.call_tool("computer_screenshot", {})
+      driver.call_tool("computer_click", { x: 100, y: 200 })
+
+      # Query encrypted Computer History
+      history = Ask::Computer.history
+      history.status
+      history.recent(limit: 20)
+    RUBY
+  end
+end