wrangle 0.1.0 → 0.2.0

data/lib/wrangle/desktop_session_server.rb

@@ -0,0 +1,374 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "socket"
+
+require_relative "desktop_dispatch"
+require_relative "desktop_effect"
+require_relative "desktop_session_autonomy"
+require_relative "desktop_policy"
+require_relative "desktop_progressive_observation"
+require_relative "desktop_proposal"
+require_relative "event_log"
+require_relative "macos_driver"
+require_relative "provider_factory"
+require_relative "scope_registry"
+require_relative "session_server"
+require_relative "tart_guest_driver"
+
+module Wrangle
+  # Holds one exact macOS root window across short-lived CLI invocations.
+  class DesktopSessionServer
+    include DesktopDispatch
+    include DesktopProgressiveObservation
+    include DesktopSessionAutonomy
+
+    PROPOSAL_TTL = DesktopProposal::TTL
+
+    def self.run(socket_path, options) = new(socket_path, options).run
+
+    def initialize(socket_path, options, driver: nil, scope: nil, policy: DesktopPolicy.new,
+                   registry: nil, log: nil, provider: nil, guest_driver_class: TartGuestDriver)
+      @socket_path = socket_path
+      @options = options
+      @driver = driver
+      @scope = scope
+      @policy = policy
+      @registry = registry
+      @log = log
+      @provider = provider
+      @guest_driver_class = guest_driver_class
+      @autonomy = DesktopAutonomy.new(provider) if provider
+      @observation = nil
+      @view = nil
+      @full_observation = false
+      @proposals = {}
+      @runs = {}
+      @actions = 0
+      @poisoned = nil
+    end
+
+    def run
+      FileUtils.mkdir_p(File.dirname(@socket_path))
+      FileUtils.rm_f(@socket_path)
+      start_runtime(log_session: File.basename(@socket_path, ".sock"))
+      serve(UNIXServer.new(@socket_path))
+    ensure
+      shutdown
+    end
+
+    def run_task(request)
+      start_runtime(log_session: "task")
+      autonomous_task(request)
+    ensure
+      shutdown
+    end
+
+    private
+
+    def start_runtime(log_session:)
+      @driver ||= configured_driver
+      @scope ||= @driver.attach(window_id: @options.fetch("window_id"), app: @options.fetch("app"))
+      @registry ||= ScopeRegistry.new
+      @lease = @registry.acquire(@scope, mode: @options.fetch("concurrency", "exclusive"))
+      @provider ||= ProviderFactory.build(@options) if @options["provider"]
+      @autonomy ||= DesktopAutonomy.new(@provider) if @provider
+      @log ||= EventLog.new(session: log_session)
+      fields = {
+        "scope_id" => @scope.id, "driver" => @options.fetch("driver", "macos"),
+        "concurrency" => @lease.mode
+      }
+      @log.record("attach", fields)
+    end
+
+    def configured_driver
+      name = @options.fetch("driver", "macos")
+      return MacOSDriver.new if name == "macos"
+      raise ConfigurationError, "Unknown desktop driver" unless name == "tart_guest"
+
+      helper = @options.fetch("guest_helper", TartGuestDriver::DEFAULT_HELPER)
+      @guest_driver_class.new(vm_name: @options.fetch("vm"), guest_app: @options.fetch("app"), guest_helper: helper)
+    end
+
+    def serve(server)
+      File.chmod(0o600, @socket_path)
+      loop do
+        client = server.accept
+        line = client.gets
+        next client.close unless line
+
+        request = parse(line)
+        client.puts(JSON.generate(dispatch(request)))
+        client.close
+        break if request["op"] == "close"
+      end
+    ensure
+      server.close
+    end
+
+    def parse(line)
+      JSON.parse(line)
+    rescue JSON::ParserError
+      { "op" => "bad" }
+    end
+
+    def dispatch(request)
+      { "ok" => true, "value" => handle(request) }
+    rescue Wrangle::Error => e
+      terminal = e.is_a?(ScopeLost) || e.is_a?(DeliveryUnknown) || e.is_a?(DriverUnavailable) ||
+                 (e.is_a?(DriverRefusal) && e.delivery_unknown?)
+      log_refusal(request, e)
+      refusal(e.class.name.split("::").last, e.message, terminal:)
+    rescue ArgumentError => e
+      log_refusal(request, e)
+      refusal("ArgumentError", e.message, terminal: false)
+    rescue StandardError => e
+      log_refusal(request, e)
+      refusal(e.class.name, "internal error: #{e.message} (#{e.backtrace&.first})", terminal: true)
+    end
+
+    def handle(request)
+      case request["op"]
+      when "status" then status
+      when "observe" then observe
+      when "drill" then drill(request)
+      when "inspect" then current
+      when "preview" then request["goal"] ? autonomous_preview(request) : preview(request)
+      when "execute" then execute(request)
+      when "continue" then continue_run(request)
+      when "close"
+        { "closing" => true, "root_preserved" => true,
+          "message" => "Wrangle released control; the application window remains open" }
+      else raise ArgumentError, "Unknown op #{request["op"].inspect}"
+      end
+    end
+
+    def status
+      {
+        "pid" => Process.pid, "driver" => @options.fetch("driver", "macos"), "scope_id" => @scope.id,
+        "root" => @scope.root, "app" => @scope.app, "owned" => false,
+        "read_only" => @options["driver"] == "tart_guest",
+        "observed" => !@observation.nil?, "actions_taken" => @actions,
+        "pending_proposals" => @proposals.length, "poisoned" => !@poisoned.nil?,
+        "concurrency" => @lease&.mode || @options.fetch("concurrency", "exclusive"),
+        "provider" => @autonomy&.status
+      }
+    end
+
+    def observe
+      ensure_usable!
+      started = monotonic
+      before = @observation
+      @observation = @driver.observe(@scope)
+      @view = nil
+      @full_observation = false
+      value = compact(@observation, before)
+      @log&.record(
+        "observe", "scope_id" => @scope.id, "revision" => @observation["revision"],
+                   "complete" => @observation["complete"], "candidates" => @observation["candidates"].length,
+                   "ambiguous_actions" => @observation.dig("coverage", "ambiguous_action_count"),
+                   "changed" => !value["changed"].nil?, "elapsed_ms" => elapsed_ms(started)
+      )
+      value
+    end
+
+    def drill(request)
+      ensure_usable!
+      previous = current
+      target = candidate(request["ref"])
+      raise ArgumentError, "DRILL was not offered for this action" unless target["operations"].include?("DRILL")
+      unless DesktopObservation.action_unambiguous?(@observation["candidates"], target, "DRILL")
+        raise ArgumentError, "DRILL target matches multiple visible candidates"
+      end
+
+      started = monotonic
+      view = { ref: target["ref"], snapshot_id: previous.fetch("snapshot_id") }
+      @observation = @driver.drill(@scope, **view)
+      @view = view
+      @full_observation = false
+      @proposals.clear
+      value = compact(@observation, previous)
+      @log&.record(
+        "drill", "scope_id" => @scope.id, "revision" => @observation["revision"],
+                 "complete" => @observation["complete"], "candidates" => @observation["candidates"].length,
+                 "ambiguous_actions" => @observation.dig("coverage", "ambiguous_action_count"),
+                 "elapsed_ms" => elapsed_ms(started)
+      )
+      value
+    end
+
+    def current
+      raise ArgumentError, "Observe before inspecting" unless @observation
+
+      @observation
+    end
+
+    def preview(request)
+      ensure_usable!
+      current
+      if @observation.dig("coverage", "truncated")
+        raise PartialObservation, "Observation has unresolved branches; DRILL before proposing an action"
+      end
+
+      proposal = DesktopProposal.build(
+        scope: @scope, observation: @observation, request:, policy: @policy, created_at: monotonic
+      )
+      @proposals[proposal["id"]] = proposal
+      log_preview(proposal)
+      DesktopProposal.compact(proposal)
+    end
+
+    def execute(request)
+      ensure_usable!
+      proposal = proposal_for(request["proposal_id"])
+      proposal["attempt_started"] = monotonic
+      expired = expire(proposal)
+      return record_run_receipt(proposal, expired) if expired
+
+      if proposal.dig("provider", "qualified") == false
+        @proposals.delete(proposal["id"])
+        denied = receipt(proposal, "refused", "not_applicable", "provider_not_qualified")
+        return record_run_receipt(proposal, denied)
+      end
+      if proposal.dig("policy", "consequential") && request["approve"] != true
+        denied = receipt(proposal, "refused", "not_applicable", "approval_required")
+        return record_run_receipt(proposal, denied)
+      end
+
+      fresh = fresh_observation
+      return record_run_receipt(proposal, refuse_stale(proposal, fresh)) if fresh["revision"] != proposal["revision"]
+
+      record_run_receipt(proposal, deliver_proposal(proposal, fresh))
+    end
+
+    def proposal_for(id)
+      proposal = @proposals[id]
+      raise ArgumentError, "Unknown or consumed proposal" unless proposal
+
+      raise ScopeLost, "The proposal belongs to another scope" unless proposal["scope_id"] == @scope.id
+
+      proposal
+    end
+
+    def expire(proposal)
+      return nil unless monotonic - proposal["created_at"] > PROPOSAL_TTL
+
+      @proposals.delete(proposal["id"])
+      receipt(proposal, "not_delivered", "not_applicable", "proposal_expired")
+    end
+
+    def refuse_stale(proposal, fresh)
+      @observation = fresh
+      @proposals.delete(proposal["id"])
+      receipt(proposal, "not_delivered", "not_applicable", "stale_observation")
+    end
+
+    def revalidated_candidate!(proposal, fresh)
+      action_candidate = fresh["candidates"][proposal["number"] - 1]
+      if same_candidate?(proposal["candidate"], action_candidate) &&
+         DesktopObservation.action_unambiguous?(fresh["candidates"], action_candidate, proposal["operation"])
+        return action_candidate
+      end
+
+      @proposals.delete(proposal["id"])
+      @poisoned = ScopeLost.new("The proposed desktop target became ambiguous during revalidation")
+      raise @poisoned
+    end
+
+    def same_candidate?(before, after)
+      return false unless after
+
+      before.except("ref") == after.except("ref")
+    end
+
+    def candidate(index) = DesktopProposal.candidate(@observation, index)
+
+    def log_preview(proposal)
+      @log&.record(
+        "preview", "proposal_id" => proposal["id"], "scope_id" => @scope.id,
+                   "revision" => proposal["revision"], "operation" => proposal["operation"],
+                   "classification" => proposal.dig("policy", "classification"),
+                   "consequential" => proposal.dig("policy", "consequential")
+      )
+    end
+
+    def observe_after_dispatch
+      [fresh_observation, nil]
+    rescue Error => e
+      @poisoned = e if e.is_a?(ScopeLost)
+      [nil, "#{e.class.name.split("::").last}: #{e.message}"]
+    end
+
+    def receipt(proposal, dispatch, effect, reason = nil, after: nil, verification_error: nil, durable: false)
+      value = {
+        "schema" => "wrangle.receipt.v1", "proposal_id" => proposal["id"],
+        "dispatch" => dispatch, "effect" => effect, "reason" => reason,
+        "scope_id" => @scope.id, "before_revision" => proposal["revision"],
+        "after_revision" => after&.fetch("revision", nil), "verification_error" => verification_error,
+        "terminal" => dispatch == "delivery_unknown" || !@poisoned.nil?
+      }.compact
+      @log&.record(
+        "execute", value.slice("proposal_id", "scope_id", "dispatch", "effect", "reason",
+                               "before_revision", "after_revision", "terminal")
+                        .merge("elapsed_ms" => elapsed_ms(proposal["attempt_started"])),
+        durable:
+      )
+      value
+    end
+
+    def ensure_usable!
+      raise @poisoned if @poisoned
+    end
+
+    def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    def elapsed_ms(started) = started && ((monotonic - started) * 1000).round(1)
+
+    def compact(observation, before)
+      candidates = observation["candidates"].each_with_index.map do |candidate, index|
+        candidate.slice("role", "label", "value", "states", "operations", "children_count")
+                 .merge("ref" => index + 1)
+      end
+      {
+        "schema" => observation["schema"], "driver" => @options.fetch("driver", "macos"),
+        "read_only" => @options["driver"] == "tart_guest",
+        "scope" => observation["scope"].slice("id", "root", "app"),
+        "revision" => observation["revision"], "complete" => observation["complete"],
+        "coverage" => observation["coverage"], "candidates" => candidates,
+        "ambiguous_actions" => observation["ambiguous_actions"],
+        "changed" => changed(before, observation)
+      }
+    end
+
+    def changed(before, after)
+      return nil unless before
+
+      old = before["candidates"].map { |candidate| identity(candidate) }
+      new = after["candidates"].map { |candidate| identity(candidate) }
+      { "same" => before["revision"] == after["revision"],
+        "appeared" => (new - old).first(20), "disappeared" => (old - new).first(20) }
+    end
+
+    def identity(candidate) = "#{candidate["role"]}:#{candidate["label"]}"
+
+    def refusal(name, message, terminal:)
+      { "ok" => false, "class" => name, "error" => message, "terminal" => terminal,
+        "retryable" => !terminal,
+        "hint" => terminal ? "This scope cannot continue. Attach again." : "Observe again." }
+    end
+
+    def log_refusal(request, error)
+      @log&.record("refusal", "operation" => request["op"], "class" => error.class.name.split("::").last)
+    end
+
+    def shutdown
+      @log&.record("close", "scope_id" => @scope&.id, "actions_taken" => @actions)
+      @registry&.release(@lease)
+      @driver&.close
+      return unless @socket_path
+
+      FileUtils.rm_f(@socket_path)
+      FileUtils.rm_f("#{@socket_path}.pid")
+    end
+  end
+end

data/lib/wrangle/desktop_task.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+require_relative "desktop_session_server"
+require_relative "event_log"
+require_relative "macos_driver"
+require_relative "provider_factory"
+require_relative "scope_registry"
+
+module Wrangle
+  # Selects one exact application window and owns one bounded AX → choice → policy → action loop.
+  # The outer agent supplies a natural goal once; low-level refs and proposals never cross this API.
+  class DesktopTask
+    DEFAULT_STEPS = 8
+    MAX_STEPS = 8
+
+    def initialize(driver: MacOSDriver.new, provider: nil, registry: nil, log: nil)
+      @driver = driver
+      @provider = provider
+      @registry = registry
+      @log = log
+      @driver_owned = true
+    end
+
+    def run(app:, goal:, literals: {}, steps: DEFAULT_STEPS, min_confidence: 0.5,
+            concurrency: "exclusive", provider_options: {})
+      app = app.to_s.strip
+      goal = goal.to_s.strip
+      raise ArgumentError, "A macOS application name is required" if app.empty?
+      raise ArgumentError, "A desktop task goal is required" if goal.empty?
+
+      budget = Integer(steps)
+      raise ArgumentError, "Desktop task budget must be between 1 and #{MAX_STEPS}" unless
+        budget.between?(1, MAX_STEPS)
+
+      provider = @provider || ProviderFactory.build(provider_options)
+      window = select_window(app)
+      scope = @driver.attach(window_id: window.fetch("id"), app: window.fetch("app_name"))
+      log = @log || EventLog.new(session: "task-#{SecureRandom.hex(6)}")
+      server = DesktopSessionServer.new(
+        nil, { "concurrency" => concurrency }, driver: @driver, scope:, registry: @registry,
+                                               log:, provider:
+      )
+      @driver_owned = false
+      server.run_task(
+        "goal" => goal, "literals" => literals, "steps" => budget,
+        "min_confidence" => min_confidence
+      )
+    ensure
+      @driver.close if @driver_owned
+    end
+
+    private
+
+    def select_window(app)
+      windows = @driver.windows(app:, titles: true)
+      raise ScopeLost, "No visible #{app} window is available" if windows.empty?
+      return windows.first if windows.one?
+
+      focused = windows.select { |window| window["focused"] == true }
+      return focused.first if focused.one?
+
+      raise ScopeLost, "More than one #{app} window is visible and none is uniquely focused"
+    end
+  end
+end

data/lib/wrangle/errors.rb

@@ -27,6 +27,39 @@ module Wrangle
     def scope? = SCOPE_CODES.include?(code)
   end
 
+  # A platform driver is absent, incompatible, or returned a malformed response.
+  class DriverError < Error; end
+
+  class DriverUnavailable < DriverError; end
+  class DriverTimeout < DriverError; end
+
+  # A platform driver refused an operation. Delivery and retry are separate because an action that
+  # may have landed is terminal even when the driver thinks another attempt might succeed.
+  class DriverRefusal < DriverError
+    attr_reader :code, :delivery, :retry_disposition, :suggestion, :details
+
+    def initialize(code, message, delivery: nil, retry_disposition: nil, suggestion: nil, details: nil)
+      super("#{code}: #{message}")
+      @code = code
+      @delivery = delivery
+      @retry_disposition = retry_disposition
+      @suggestion = suggestion
+      @details = details
+    end
+
+    def delivery_unknown? = delivery == "unknown"
+    def safe_to_retry? = delivery == "not_delivered" && retry_disposition == "safe"
+  end
+
+  # Another exclusive session already controls an overlapping root surface.
+  class ScopeBusy < Error; end
+
+  # A progressive observation has unresolved branches and cannot safely authorize mutation.
+  class PartialObservation < Error; end
+
+  # Deterministic policy denied an otherwise observed action.
+  class PolicyDenied < Error; end
+
   # The bound window, tab, or document is no longer the one this session was handed.
   # A new explicit handoff is required; the session will not look for a substitute.
   class ScopeLost < Error; end
@@ -39,6 +72,9 @@ module Wrangle
 
   # Raised when the decision service is unusable: unreachable, slow, or answering with something it
   # was never offered. A bad answer is a refusal, not a fallback to guessing.
+  # A vendor-neutral decision provider failed negotiation or returned an invalid choice.
+  class ProviderError < Error; end
+
   class JevError < Error
     attr_reader :code
 

data/lib/wrangle/event_log.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "time"
+
+module Wrangle
+  # Compact, owner-only JSONL audit events. Callers pass metadata, never pixels or literal values.
+  class EventLog
+    RETENTION = 7 * 24 * 60 * 60
+
+    def initialize(session:, root: nil, now: Time.now)
+      home = ENV["WRANGLE_HOME"] || File.join(Dir.home, ".wrangle")
+      @root = root || File.join(home, "logs")
+      FileUtils.mkdir_p(@root, mode: 0o700)
+      File.chmod(0o700, @root)
+      prune(now)
+      safe_session = session.to_s.gsub(/[^a-zA-Z0-9_.-]/, "_")[0, 80]
+      @path = File.join(@root, "#{now.utc.strftime("%Y%m%d")}-#{safe_session}-#{Process.pid}.jsonl")
+    end
+
+    attr_reader :path
+
+    def record(type, fields = nil, durable: false, **implicit_fields)
+      fields = (fields || {}).merge(implicit_fields)
+      event = { "at" => Time.now.utc.iso8601(3), "event" => type }.merge(fields.compact)
+      File.open(@path, File::WRONLY | File::CREAT | File::APPEND, 0o600) do |file|
+        file.flock(File::LOCK_EX)
+        file.puts(JSON.generate(event))
+        file.flush
+        file.fsync if durable
+      end
+      File.open(@root, File::RDONLY, &:fsync) if durable
+      event
+    end
+
+    private
+
+    def prune(now)
+      Dir.each_child(@root) do |name|
+        next if name.end_with?(".pinned")
+
+        path = File.join(@root, name)
+        next unless File.file?(path)
+        next unless now - File.mtime(path) > RETENTION
+
+        File.unlink(path)
+      end
+    end
+  end
+end

data/lib/wrangle/jev.rb

@@ -5,6 +5,7 @@ require "net/http"
 require "uri"
 
 require_relative "errors"
+require_relative "timing"
 
 module Wrangle
   # Asks Jev to pick one observed control.
@@ -29,11 +30,12 @@ module Wrangle
 
     attr_reader :model, :endpoint
 
-    def initialize(api_key:, endpoint: DEFAULT_ENDPOINT, model: DEFAULT_MODEL, timeout: 20)
+    def initialize(api_key:, endpoint: DEFAULT_ENDPOINT, model: DEFAULT_MODEL, timeout: 20, timing: Timing)
       @api_key = api_key
       @endpoint = URI.parse(endpoint)
       @model = model
       @timeout = timeout
+      @timing = timing
     end
 
     def ask(state:, questions:)
@@ -60,7 +62,7 @@ module Wrangle
         response = post(body)
         break unless RETRYABLE.include?(response.code.to_i) && attempt < 2
 
-        sleep(0.25 * (2**attempt))
+        @timing.sleep(0.25 * (2**attempt))
       end
       response
     end