ask-coding-harness 0.1.0

data/lib/ask/coding_harness/config.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Ask
+  module CodingHarness
+    # Configuration for the coding harness.
+    #
+    # Global instance: Ask::CodingHarness.config. Settings are read from
+    # environment variables when not set explicitly, so a zero-config
+    # `ach serve` works out of the box.
+    #
+    #   Ask::CodingHarness.configure do |c|
+    #     c.workspace = "/path/to/project"
+    #     c.model = "claude-sonnet-4"
+    #     c.approval = :require
+    #   end
+    class Config
+      # Default tools made available to the agent. All come from
+      # ask-tools-shell and run through Ask::Sandbox.provider.
+      DEFAULT_TOOLS = %w[bash read write edit glob grep code apply_patch].freeze
+
+      # Tools that queue for human approval when approval mode is :require.
+      DEFAULT_APPROVAL_REQUIRED = %w[bash write edit apply_patch code repl].freeze
+
+      # Approval modes:
+      #   :off      — never prompt; everything executes immediately
+      #   :require  — mutating/dangerous tools queue for human approval
+      #   :auto     — auto-approve everything (same as :off, but the queue
+      #               exists and can be inspected)
+      APPROVAL_MODES = %i[off require auto].freeze
+
+      attr_accessor :host, :workspace, :db_path, :model,
+                    :max_turns, :turn_timeout, :approval_required,
+                    :plan_mode, :todos, :tools, :adapter, :adapter_opts
+
+      def initialize
+        @host = ENV.fetch("ACH_HOST", "0.0.0.0")
+        @port = (ENV["ACH_PORT"] || "8080").to_i
+        @workspace = ENV["ACH_WORKSPACE"] || ENV["ASKODA_WORKSPACE"] || Dir.pwd
+        @db_path = ENV["ACH_DB_PATH"] || ENV["ASKODA_DB_PATH"] || default_db_path
+        @model = ENV["ACH_MODEL"] || ENV["ASK_AGENT_MODEL"] || "deepseek-v4-flash"
+        @max_turns = (ENV["ACH_MAX_TURNS"] || ENV["ASK_AGENT_MAX_TURNS"] || "25").to_i
+        @turn_timeout = (ENV["ACH_TURN_TIMEOUT"] || "600").to_i
+        @approval = :require
+        self.approval = (ENV["ACH_APPROVAL"] || "require").to_sym
+        @approval_required = DEFAULT_APPROVAL_REQUIRED.dup
+        @plan_mode = env_flag("ACH_PLAN_MODE", default: false)
+        @todos = env_flag("ACH_TODOS", default: true)
+        @tools = DEFAULT_TOOLS.dup
+        @adapter = ENV["ACH_ADAPTER"] || ENV["CODING_PROVIDER"] || "ask_agent"
+        @adapter_opts = {}
+        validate!
+      end
+
+      def port
+        @port
+      end
+
+      def port=(value)
+        @port = value.to_i
+        raise ArgumentError, "invalid port: #{@port.inspect}" if @port <= 0 || @port > 65_535
+        @port
+      end
+
+      def approval
+        @approval
+      end
+
+      def approval=(value)
+        mode = value.to_sym
+        unless APPROVAL_MODES.include?(mode)
+          raise ArgumentError, "approval must be one of #{APPROVAL_MODES.inspect}, got #{value.inspect}"
+        end
+        @approval = mode
+      end
+
+      # True when the approval queue is active (mode :require or :auto).
+      def approvals?
+        %i[require auto].include?(@approval)
+      end
+
+      # True when mutating tools queue for human approval.
+      def approval_required?
+        @approval == :require
+      end
+
+      # Names of the tools the approval policy gates behind human approval.
+      def approval_policy_tools
+        return [] unless approval_required?
+        Array(@approval_required).map(&:to_s)
+      end
+
+      private
+
+      def env_flag(name, default:)
+        case ENV[name]
+        when "1", "true", "yes" then true
+        when "0", "false", "no" then false
+        else default
+        end
+      end
+
+      def default_db_path
+        File.join(Dir.pwd, "data", "ask-coding-harness.db")
+      end
+
+      def validate!
+        if @port.to_i <= 0 || @port.to_i > 65_535
+          raise ArgumentError, "invalid port: #{@port.inspect}"
+        end
+        if @workspace.to_s.empty?
+          raise ArgumentError, "workspace must not be empty"
+        end
+        if @max_turns.to_i <= 0
+          raise ArgumentError, "max_turns must be positive"
+        end
+      end
+    end
+  end
+end

data/lib/ask/coding_harness/demo_adapter.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+require "find"
+require "json"
+require "thread"
+
+require "ask-coding-providers"
+
+module Ask
+  module CodingHarness
+    # A scripted coding agent for trying the harness without API keys.
+    #
+    # Walks through a realistic turn — todos, tool calls with output, a
+    # diff, and a tool call queued for human approval — waiting on the
+    # approval queue exactly like the real ask_agent adapter. The text and
+    # file contents are generated from the workspace it is pointed at, so
+    # every run feels like the real thing.
+    #
+    #   ach demo            # serve the web UI against the demo agent
+    class DemoAdapter < Ask::CodingProviders::Adapter
+      # @param approval [Symbol] :require waits for human approval on the
+      #   queued tool call; :off/:auto approves it immediately (headless).
+      def initialize(approval: :require, **)
+        @approval = approval.to_sym
+        @pending = {}
+        @next_action_id = 1
+        @mutex = Mutex.new
+        @cv = ConditionVariable.new
+        @aborted = false
+        @sessions = {}
+      end
+
+      def self.from_config(**config)
+        new(**config)
+      end
+
+      def start; end
+      def stop
+        @mutex.synchronize { @aborted = true; @cv.broadcast }
+      end
+
+      def create_session(workspace_path, mode: nil, model: nil)
+        sid = "demo_#{@sessions.size + 1}"
+        @sessions[sid] = workspace_path
+        sid
+      end
+
+      def send_and_stream(session_id, content, turn_timeout: 600.0, &block)
+        workspace = @sessions[session_id] || Dir.pwd
+        emit(block, "turn.started", {})
+
+        emit(block, "model.streaming", { "delta" => "Alright, let me take a look at #{File.basename(workspace)}. " })
+        emit(block, "model.streaming", { "delta" => "I'll start by mapping the project structure.\n\n" })
+
+        emit(block, "todos.updated", {
+          "todos" => [
+            { "id" => "1", "title" => "Inspect the project structure", "status" => "in_progress" },
+            { "id" => "2", "title" => "Find the main entry point", "status" => "pending" },
+            { "id" => "3", "title" => "Propose improvements", "status" => "pending" }
+          ]
+        })
+
+        files = list_files(workspace)
+        emit(block, "tool.use", {
+          "toolName" => "bash", "toolCallId" => "call_1",
+          "input" => { "command" => "find . -type f | head -30" }
+        })
+        emit(block, "tool.result", {
+          "toolName" => "bash", "toolCallId" => "call_1",
+          "output" => files.join("\n"),
+          "isError" => false, "durationMs" => 84
+        })
+
+        readme = read_first(workspace, %w[README.md readme.md])
+        if readme
+          emit(block, "tool.use", {
+            "toolName" => "read", "toolCallId" => "call_2",
+            "input" => { "path" => readme[0] }
+          })
+          emit(block, "tool.result", {
+            "toolName" => "read", "toolCallId" => "call_2",
+            "output" => readme[1],
+            "isError" => false, "durationMs" => 12
+          })
+        end
+
+        emit(block, "todos.updated", {
+          "todos" => [
+            { "id" => "1", "title" => "Inspect the project structure", "status" => "completed" },
+            { "id" => "2", "title" => "Find the main entry point", "status" => "completed" },
+            { "id" => "3", "title" => "Propose improvements", "status" => "in_progress" }
+          ]
+        })
+
+        emit(block, "model.streaming", {
+          "delta" => "I can see the project has #{files.size} files. Here's a diff I'd like to apply — it needs your approval first:\n\n"
+        })
+
+        emit(block, "tool.use", {
+          "toolName" => "apply_patch", "toolCallId" => "call_3",
+          "input" => { "patch" => "diff --git a/README.md b/README.md\nindex 8f1a2b3..c9d4e5f 100644\n--- a/README.md\n+++ b/README.md\n@@ -1,3 +1,4 @@\n # #{File.basename(workspace)}\n \n+Generated by the ask-coding-harness demo agent.\n" }
+        })
+
+        # Queue an approval — the demo pauses here until the user decides
+        # (or auto-approves in headless mode).
+        action_id = queue_action(block, "apply_patch", { "patch" => "…" }, "Applying a patch to README.md requires approval")
+        outcome =
+          if %i[off auto].include?(@approval)
+            @mutex.synchronize do
+              @pending[action_id] = @pending[action_id].merge("status" => "approved")
+            end
+            :approved
+          else
+            wait_for_decision(action_id)
+          end
+
+        case outcome
+        when :approved
+          emit(block, "approval.updated", { "actionId" => action_id, "status" => "approved" })
+          emit(block, "tool.result", {
+            "toolName" => "apply_patch", "toolCallId" => "call_3",
+            "output" => "Patch applied to README.md",
+            "isError" => false, "durationMs" => 5
+          })
+          emit(block, "model.streaming", {
+            "delta" => "Done — README.md now documents that this workspace was demoed by the harness. " \
+                      "Try asking me to do something real: point the harness at a project, add an API key, " \
+                      "and I'll work through it with tools, approvals, and diffs just like this.\n\n" \
+                      "Things to try: run tests, refactor a file, explain an error.\n"
+          })
+          emit(block, "turn.completed", { "response" => "Demo turn completed." })
+        when :rejected
+          emit(block, "approval.updated", { "actionId" => action_id, "status" => "rejected" })
+          emit(block, "model.streaming", {
+            "delta" => "Understood — I won't touch anything. That's the approval flow working: " \
+                      "nothing mutates without your say-so.\n"
+          })
+          emit(block, "turn.completed", { "response" => "Demo turn completed (rejected)." })
+        when :aborted
+          emit(block, "turn.aborted", {})
+        end
+      end
+
+      # ── Approval controls (same duck-typed surface as ask_agent) ──
+
+      def approve_action(_session_id, action_id)
+        @mutex.synchronize do
+          action = @pending[action_id]
+          next [] unless action
+          @pending[action_id] = action.merge("status" => "approved")
+          @cv.broadcast
+        end
+      end
+
+      def reject_action(_session_id, action_id)
+        @mutex.synchronize do
+          action = @pending[action_id]
+          next [] unless action
+          @pending[action_id] = action.merge("status" => "rejected")
+          @cv.broadcast
+        end
+      end
+
+      def approve_all(_session_id)
+        @mutex.synchronize do
+          @pending.each_value { |a| a["status"] = "approved" if a["status"] == "pending" }
+          @cv.broadcast
+        end
+      end
+
+      def pending_approvals(_session_id)
+        @mutex.synchronize do
+          @pending.values.select { |a| a["status"] == "pending" }
+        end
+      end
+
+      def abort(_session_id)
+        @mutex.synchronize { @aborted = true; @cv.broadcast }
+      end
+
+      # ── Registration ──
+
+      def self.install!
+        existing = begin
+          Ask::CodingProviders.resolve_adapter(:demo)
+        rescue Ask::CodingProviders::ConfigurationError
+          nil
+        end
+        Ask::CodingProviders.register_adapter(:demo, self) unless existing
+      end
+
+      private
+
+      def emit(block, type, payload)
+        block.call({ type: type, seq: 0, payload: payload })
+      end
+
+      def queue_action(block, tool_name, args, message)
+        @mutex.synchronize do
+          id = @next_action_id
+          @next_action_id += 1
+          @pending[id] = {
+            "id" => id, "tool_name" => tool_name, "args" => args,
+            "message" => message, "status" => "pending"
+          }
+          emit(block, "approval.required", {
+            "actionId" => id, "toolName" => tool_name, "args" => args,
+            "message" => message, "autoApprovable" => false, "status" => "pending"
+          })
+          id
+        end
+      end
+
+      # Block until the action is approved, rejected, or the turn aborts.
+      def wait_for_decision(action_id)
+        @mutex.synchronize do
+          loop do
+            return :aborted if @aborted
+            action = @pending[action_id]
+            return action["status"].to_sym if action && action["status"] != "pending"
+            @cv.wait(@mutex, 0.5)
+          end
+        end
+      end
+
+      def list_files(workspace)
+        ignore = %w[.git node_modules vendor tmp log coverage data]
+        files = []
+        Find.find(workspace) do |path|
+          rel = path.sub("#{workspace}/", "")
+          next if rel.empty?
+          parts = rel.split("/")
+          next if parts.any? { |p| ignore.include?(p) || p.start_with?(".") }
+          next unless File.file?(path)
+          files << rel
+        end
+        files.sort.first(30)
+      end
+
+      def read_first(workspace, names)
+        names.each do |name|
+          path = File.join(workspace, name)
+          next unless File.file?(path)
+          content = File.read(path, encoding: "UTF-8")
+          return [name, content.lines.first(40).join]
+        end
+        nil
+      end
+    end
+  end
+end
+
+Ask::CodingHarness::DemoAdapter.install!

data/lib/ask/coding_harness/event_translator.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Ask
+  module CodingHarness
+    # Normalizes coding-agent adapter events (ask-coding-providers) into the
+    # harness SSE event schema.
+    #
+    # Two adapter vocabularies exist today:
+    #
+    #   ask_agent (rich):    turn.started, model.streaming, model.thinking,
+    #                        tool.use, tool.delta, tool.result,
+    #                        approval.required, approval.updated,
+    #                        plan.proposed, plan.approved, plan.rejected,
+    #                        todos.updated, turn.completed, turn.failed,
+    #                        turn.aborted, error
+    #
+    #   acp (basic):         turn.started, model.streaming, tool.use,
+    #                        tool.result, turn.completed, turn.failed
+    #
+    # Both translate into one browser-friendly schema (camelCase, flat
+    # payloads, no seq):
+    #
+    #   turn.started, message.delta, message.thinking,
+    #   tool.start {id, name, args}, tool.delta {id, name, partial},
+    #   tool.end {id, name, output, isError, durationMs},
+    #   approval.required {id, toolName, args, message, autoApprovable},
+    #   approval.updated {id, status}, plan.proposed/approved/rejected {plan},
+    #   todos.updated {todos}, turn.completed {response},
+    #   turn.failed {error}, turn.aborted, error {error}
+    class EventTranslator
+      # Translate one adapter event into a harness event Hash, or nil when
+      # the event has no browser representation.
+      #
+      # @param event [Hash] adapter event with :type and :payload
+      # @return [Hash, nil] { type:, data: }
+      def translate(event)
+        payload = event[:payload] || {}
+        case event[:type]
+        when "turn.started" then event("turn.started", {})
+        when "model.streaming" then event("message.delta", { delta: payload["delta"] })
+        when "model.thinking" then event("message.thinking", { delta: payload["delta"] })
+        when "tool.use" then tool_start(payload)
+        when "tool.delta" then event("tool.delta", tool_delta(payload))
+        when "tool.result" then tool_end(payload)
+        when "approval.required" then approval_required(payload)
+        when "approval.updated" then event("approval.updated", { id: payload["actionId"], status: payload["status"] })
+        when "plan.proposed" then event("plan.proposed", { plan: payload["plan"] })
+        when "plan.approved" then event("plan.approved", { plan: payload["plan"] })
+        when "plan.rejected" then event("plan.rejected", { plan: payload["plan"] })
+        when "todos.updated" then event("todos.updated", { todos: payload["todos"] })
+        when "turn.completed" then event("turn.completed", { response: payload["response"] })
+        when "turn.failed" then event("turn.failed", { error: error_message(payload) })
+        when "turn.aborted" then event("turn.aborted", {})
+        when "error" then event("error", { error: error_message(payload) })
+        end
+      end
+
+      private
+
+      def event(type, data)
+        { type: type, data: data }
+      end
+
+      def tool_start(payload)
+        event("tool.start", {
+          id: payload["toolCallId"] || payload["id"],
+          name: payload["toolName"],
+          args: normalize_args(payload["input"] || payload["args"])
+        })
+      end
+
+      # Tool arguments arrive as hashes (ask_agent) or JSON strings
+      # (repair pipeline); the browser wants a plain object.
+      def normalize_args(args)
+        return args unless args.is_a?(String)
+        JSON.parse(args)
+      rescue JSON::ParserError
+        args
+      end
+
+      def tool_delta(payload)
+        {
+          id: payload["toolCallId"] || payload["id"],
+          name: payload["toolName"],
+          partial: payload["partial"]
+        }
+      end
+
+      def tool_end(payload)
+        event("tool.end", {
+          id: payload["toolCallId"] || payload["id"],
+          name: payload["toolName"],
+          output: payload["output"],
+          isError: !!payload["isError"],
+          durationMs: payload["durationMs"]
+        })
+      end
+
+      def approval_required(payload)
+        event("approval.required", {
+          id: payload["actionId"],
+          toolName: payload["toolName"],
+          args: payload["args"],
+          message: payload["message"],
+          autoApprovable: !!payload["autoApprovable"]
+        })
+      end
+
+      def error_message(payload)
+        err = payload["error"]
+        err.is_a?(Hash) ? err["message"] : err.to_s
+      end
+    end
+  end
+end

data/lib/ask/coding_harness/runner.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ask
+  module CodingHarness
+    # Headless run of a prompt against the workspace: drives the same
+    # AgentRunner as the web server, prints a readable transcript, and
+    # returns a Result. This is the dogfooding path — the harness builds
+    # itself with `ach run`.
+    class Runner
+      # Outcome of a headless run.
+      Result = Data.define(:success, :response, :events, :conversation_id, :error) do
+        def success? = success
+      end
+
+      # @param config [Config] harness configuration (duped; approval mode
+      #   is overridden for headless operation)
+      # @param store [Store, nil] conversation store (defaults to a fresh
+      #   Store on config.db_path)
+      # @param runner [AgentRunner, nil] agent runner (defaults to a fresh
+      #   AgentRunner on the store)
+      # @param approval [Symbol] approval mode for headless runs; :off by
+      #   default so nothing blocks on human review
+      def initialize(config:, store: nil, runner: nil, approval: :off)
+        @config = config.dup
+        @config.approval = approval
+        @store = store || Store.new(db_path: @config.db_path)
+        @runner = runner || AgentRunner.new(config: @config, store: @store)
+      end
+
+      # Run a prompt and wait for the turn to finish.
+      #
+      # @param prompt [String] the task
+      # @param workspace [String, nil] override config.workspace
+      # @param model [String, nil] model override
+      # @param quiet [Boolean] suppress the transcript output
+      # @return [Result]
+      def run(prompt, workspace: nil, model: nil, quiet: false)
+        @config.workspace = workspace if workspace
+        conversation = @store.build(directory: @config.workspace)
+        conversation = @store.save(conversation)
+
+        events = []
+        response = +""
+        error = nil
+
+        thread = @runner.start_turn(conversation, prompt, model: model) do |ev|
+          events << ev
+          case ev[:type]
+          when "message.delta" then response << ev[:data][:delta].to_s
+          when "turn.failed" then error = ev[:data][:error]
+          end
+          print_transcript(ev) unless quiet
+        end
+        thread.join
+
+        Result.new(
+          success: error.nil?,
+          response: response,
+          events: events,
+          conversation_id: conversation["id"],
+          error: error
+        )
+      end
+
+      private
+
+      def print_transcript(event)
+        case event[:type]
+        when "turn.started"
+          puts "\e[90m── turn started ──\e[0m"
+        when "message.delta"
+          print event[:data][:delta].to_s
+          $stdout.flush
+        when "message.thinking"
+          print "\e[2m#{event[:data][:delta]}\e[0m"
+          $stdout.flush
+        when "tool.start"
+          args = event[:data][:args]
+          args = JSON.generate(args) if args.is_a?(Hash) || args.is_a?(Array)
+          puts "\n\e[36m› #{event[:data][:name]}\e[0m #{args.to_s[0, 120]}"
+        when "tool.delta"
+          print event[:data][:partial].to_s
+          $stdout.flush
+        when "tool.end"
+          output = event[:data][:output].to_s
+          puts "" unless output.empty?
+          output.lines.first(20).each { |l| puts "  \e[90m#{l.chomp}\e[0m" } unless output.empty?
+          puts "  \e[90m… #{output.lines.size - 20} more lines\e[0m" if output.lines.size > 20
+        when "approval.required"
+          puts "\n\e[33m✋ #{event[:data][:toolName]} requires approval\e[0m"
+        when "approval.updated"
+          puts "\n\e[33m✋ #{event[:data][:toolName]} → #{event[:data][:status]}\e[0m"
+        when "plan.proposed"
+          puts "\n\e[35m📋 Plan:\e[0m #{event[:data][:plan]}"
+        when "todos.updated"
+          # Not printed — the response carries the outcome.
+        when "turn.completed"
+          puts "\n\e[90m── turn completed ──\e[0m"
+        when "turn.failed"
+          puts "\n\e[31m✗ #{event[:data][:error]}\e[0m"
+        when "turn.aborted"
+          puts "\n\e[31m✗ Turn aborted\e[0m"
+        end
+      end
+    end
+  end
+end