ask-coding-harness 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bb36f1a55f6b263fdbffd97383c1a744d9b4864a74d04d3003270134437bc3fd
+  data.tar.gz: f2a6fd12ffb36d5fff6baf1d59151c913dd5596db22a5d6abd366494d57be328
+SHA512:
+  metadata.gz: 37ba3d010ae2ca1f044e919b2e82f3fc55e82bf96d792c65896e5e4141a225cecbcdc8e82c07d06eca24b12089d4e624b679b2a8fc5bd42d149b7e3047e37333
+  data.tar.gz: 3cd3c97b80c739cd6b9a6182241083856d514a2aee9f1ee6c8758f48671847377efe19f67a3a232c4eb412c725b51b3b3acd0b9f2df59381177bdf21e211643b

data/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+## [0.2.0] - 2026-08-10
+
+### Added
+
+- **Demo adapter and `ach demo`** — a scripted coding agent (todos, tool
+  calls, diffs, approval flow) for trying the harness without API keys.
+- **`ach run --adapter NAME`** — pick the coding agent adapter for headless
+  runs (ask_agent, demo, acp, ...).
+- **Approval-aware external adapters** — the configured approval mode
+  passes through to external coding-agent adapters (the demo adapter
+  auto-approves in headless mode).
+- **Web frontend** — mobile-first PWA built on ask-ui-kit: live tool
+  cards, approvals, todos, plans, diff/terminal viewers, conversation
+  sidebar, settings; installable with service worker + manifest.
+- **ask-ui-kit components** — `ask-diff`, `ask-tool-approval`,
+  `ask-todo-list`, `ask-plan`, `ask-terminal-output`.
+
+### Fixed
+
+- Server startup via Rackup (CLI now wires the server with its own config;
+  flags like `--adapter` previously lost to the module-global config).
+- Frontend turn state: Svelte 5 `$state` does not proxy `Map` mutations —
+  tool cards now render by replacing the map immutably.
+- Duplicate assistant message after turn completion (the finished turn is
+  folded into the message list on the next send).
+
+## [0.1.0] - 2026-08-10
+
+### Added
+
+- **Initial release** — general-purpose coding agent in the browser.
+- **Harness core** — config (approval modes, plan mode, todos), conversation
+  store on ask-state-providers, event translator normalizing adapter events
+  into one browser-friendly SSE schema, agent runner (ask-agent runtime via
+  ask-coding-providers, extensible to ACP/Codex/Claude adapters).
+- **Web server** — Roda REST + SSE: conversations CRUD, streaming turns,
+  approvals, plan approve/reject, abort, SPA fallback, CORS.
+- **CLI** — `ach serve`, `ach run` (headless dogfooding path), `ach
+  sessions`, `ach version`; `ask-coding-harness` executable.
+- **Renamed from askoda** — full git history preserved.

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,120 @@
+# ask-coding-harness
+
+**A general-purpose coding agent in the browser.** Self-hosted, mobile-first,
+and built on the ask-rb ecosystem. Point it at any project directory and let
+the agent fire away — reading, writing, and running commands while you watch
+every tool call, approve what needs approving, and review the diffs.
+
+## Quick start
+
+```bash
+gem install ask-coding-harness
+
+cd /path/to/your/project
+ask-coding-harness          # or: ach serve
+```
+
+Open http://localhost:8080. Set a model via `ACH_MODEL` (or
+`ASK_AGENT_MODEL`) and an API key for the provider (e.g. `OPENCODE_API_KEY`).
+
+**No API key yet?** Try the scripted demo agent:
+
+```bash
+ach demo
+```
+
+## What you get
+
+- **The agent, unleashed** — `ask-agent` runs the loop in-process with the
+  shell toolset (`bash`, `read`, `write`, `edit`, `grep`, `glob`, `code`,
+  `apply_patch`), all routed through `ask-sandbox-providers`.
+- **Live event stream** — text deltas, thinking, tool calls, todos, and
+  plan proposals stream to the browser over SSE as they happen.
+- **Approvals** — mutating tools (`bash`, `write`, `edit`, ...) queue for
+  your approval by default; approve, reject, or approve-all from the UI.
+- **Plan mode** — opt in with `ACH_PLAN_MODE=1`: the agent researches
+  read-only, proposes a plan, and only executes after you approve it.
+- **Conversations** — saved to SQLite, resumable, renameable, archivable.
+- **PWA** — installable on desktop and mobile, works offline for the shell
+  (the agent itself needs the server).
+- **Extensible** — other coding agents (Codex, Claude Code, ACP-based)
+  plug in via `ask-coding-providers` by setting `ACH_ADAPTER=acp`.
+
+## The `ach` CLI
+
+```bash
+ach serve                        # web server (default command)
+ach demo                         # scripted agent — no API key needed
+ach run "refactor the auth flow" # headless run, prints a transcript
+ach sessions                     # list saved conversations
+ach version
+```
+
+`ach run` is the dogfooding path: ask-coding-harness builds itself with it.
+
+## Configuration
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `ACH_WORKSPACE` | current dir | project the agent operates on |
+| `ACH_HOST` / `ACH_PORT` | `0.0.0.0` / `8080` | server bind |
+| `ACH_MODEL` | `deepseek-v4-flash` | default model |
+| `ACH_ADAPTER` | `ask_agent` | coding agent adapter (`ask_agent`, `acp`, ...) |
+| `ACH_APPROVAL` | `require` | `off`, `require`, `auto` |
+| `ACH_PLAN_MODE` | off | plan mode (research first, then execute) |
+| `ACH_TODOS` | on | todo list tool |
+| `ACH_DB_PATH` | `./data/ask-coding-harness.db` | conversation database |
+| `ACH_SYSTEM_PROMPT` | — | extra system prompt lines |
+
+Programmatic use:
+
+```ruby
+require "ask-coding-harness"
+
+Ask::CodingHarness.configure do |c|
+  c.workspace = "/path/to/project"
+  c.model = "claude-sonnet-4"
+  c.approval = :require
+end
+
+result = Ask::CodingHarness.run("Run the test suite and fix failures")
+puts result.response
+```
+
+## Architecture
+
+```
+Browser (PWA) ──SSE──> Server (Roda) ──> AgentRunner ──> ask-coding-providers
+                                                          ├─ ask_agent (default)
+                                                          └─ acp / codex / claude
+                └── SQLite (ask-state-providers) <── Store
+```
+
+The server is a thin shell: conversations live in the Store, turns run in
+the AgentRunner, adapter events normalize through the EventTranslator into
+one browser-friendly schema.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test        # Ruby tests
+(cd web && npm install && npm run build)   # build the PWA into public/
+(cd web && npm test)         # frontend unit tests
+```
+
+The frontend imports `ask-ui-kit` from source (a sibling repo, via a vite
+alias) — keep `ask-ui-kit` next to this repo and rebuild it after changing
+components.
+
+## The ask-rb ecosystem
+
+ask-coding-harness is part of the ask-rb ecosystem: `ask-agent` runs the
+loop, `ask-coding-providers` supplies the adapters, `ask-tools-shell` the
+tools (sandboxed via `ask-sandbox-providers`), `ask-state-providers` the
+storage, and `ask-ui-kit` the reusable web components. See
+https://ask-rb.github.io/ask-docs for the full picture.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/bin/ach

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

data/bin/ask-coding-harness

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

data/lib/ask/coding_harness/agent_runner.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+require "thread"
+
+module Ask
+  module CodingHarness
+    # Runs coding-agent turns for conversations: maps each conversation to
+    # an adapter session, streams translated events, and persists assistant
+    # messages back into the store.
+    #
+    # The default runtime is ask-agent (via the ask_agent adapter). Other
+    # coding agents (Codex, Claude Code, ACP-based agents) plug in through
+    # ask-coding-providers by setting ACH_ADAPTER/CODING_PROVIDER — the
+    # runner only needs the adapter's duck-typed surface:
+    # create_session, send_and_stream, and (when supported) approve_action,
+    # reject_action, approve_all, approve_plan, reject_plan, abort.
+    class AgentRunner
+      # Tool name → ask-tools-shell class, for the ask_agent runtime.
+      TOOL_CLASSES = {
+        "bash" => Ask::Tools::Bash,
+        "read" => Ask::Tools::Read,
+        "write" => Ask::Tools::Write,
+        "edit" => Ask::Tools::Edit,
+        "glob" => Ask::Tools::Glob,
+        "grep" => Ask::Tools::Grep,
+        "code" => Ask::Tools::Code,
+        "apply_patch" => Ask::Tools::ApplyPatch,
+        "repl" => Ask::Tools::Repl
+      }.freeze
+
+      # @param config [Config] harness configuration
+      # @param store [Store] conversation persistence
+      # @param translator [EventTranslator] adapter event → SSE event
+      # @param tool_classes [Hash{String => Class}] tool name → class map;
+      #   overridable so hosts can register custom tools
+      def initialize(config:, store:, translator: EventTranslator.new, tool_classes: TOOL_CLASSES)
+        @config = config
+        @store = store
+        @translator = translator
+        @tool_classes = tool_classes
+        @adapter = nil
+        @mutex = Mutex.new
+        @adapter_mutex = Mutex.new
+        @sessions = {}
+        @turns = {}
+      end
+
+      # The adapter (created lazily on first use). Uses its own mutex so
+      # callers holding @mutex (session_for, stop) can still build it.
+      def adapter
+        @adapter_mutex.synchronize { @adapter ||= build_adapter }
+      end
+
+      # Run a turn for a conversation, streaming harness events to the
+      # block. Runs in a background thread; returns the thread.
+      #
+      # @param conversation [Hash] conversation record (from the store)
+      # @param prompt [String] the user message
+      # @param model [String, nil] model override
+      # @yield [Hash] harness events ({ type:, data: })
+      # @return [Thread]
+      def start_turn(conversation, prompt, model: nil, &on_event)
+        raise ArgumentError, "prompt must not be empty" if prompt.to_s.strip.empty?
+
+        thread = Thread.new do
+          begin
+            run_turn(conversation, prompt, model: model, &on_event)
+          rescue => e
+            emit(on_event, { type: "error", data: { error: e.message } })
+          end
+        end
+        @mutex.synchronize { @turns[conversation["id"]] = thread }
+        thread
+      end
+
+      def running?(conversation_id)
+        thread = @mutex.synchronize { @turns[conversation_id] }
+        thread&.alive? ? true : false
+      end
+
+      # ── Approval / plan controls (no-ops when the adapter lacks them) ──
+
+      def approve(conversation_id, action_id)
+        send_adapter(conversation_id, :approve_action, action_id)
+      end
+
+      def reject(conversation_id, action_id)
+        send_adapter(conversation_id, :reject_action, action_id)
+      end
+
+      def approve_all(conversation_id)
+        send_adapter(conversation_id, :approve_all)
+      end
+
+      def approve_plan(conversation_id)
+        send_adapter(conversation_id, :approve_plan)
+      end
+
+      def reject_plan(conversation_id)
+        send_adapter(conversation_id, :reject_plan)
+      end
+
+      def abort(conversation_id)
+        send_adapter(conversation_id, :abort)
+      end
+
+      def pending_approvals(conversation_id)
+        sid = @mutex.synchronize { @sessions[conversation_id] }
+        return [] unless sid
+        if adapter.respond_to?(:pending_approvals)
+          adapter.pending_approvals(sid)
+        else
+          []
+        end
+      end
+
+      def stop
+        @mutex.synchronize do
+          @turns.each_value { |t| t.kill if t.alive? }
+          @turns.clear
+          @sessions.clear
+          @adapter&.stop if @adapter.respond_to?(:stop)
+          @adapter = nil
+        end
+      end
+
+      private
+
+      def run_turn(conversation, prompt, model: nil, &on_event)
+        sid = session_for(conversation, model: model)
+
+        conv = @store.load(conversation["id"]) || conversation
+        conv["messages"] << { "role" => "user", "content" => prompt, "created_at" => Time.now.iso8601 }
+        @store.save(conv)
+
+        outcome = :completed
+        accumulated = +""
+        adapter.send_and_stream(sid, prompt, turn_timeout: @config.turn_timeout) do |event|
+          translated = @translator.translate(event)
+          next unless translated
+
+          case translated[:type]
+          when "message.delta"
+            accumulated << translated[:data][:delta].to_s
+          when "turn.failed"
+            outcome = :failed
+          when "turn.aborted"
+            outcome = :aborted
+          end
+          emit(on_event, translated)
+        end
+
+        persist_outcome(conversation["id"], accumulated, outcome)
+      end
+
+      # Persist the assistant turn outcome (response, error, or abort) so
+      # the conversation reads correctly when reopened. Best-effort; the
+      # streamed events are the source of truth for the live view.
+      def persist_outcome(conversation_id, accumulated, outcome)
+        conv = @store.load(conversation_id)
+        return unless conv
+        # Only persist when the last message is still the user's prompt.
+        last = conv["messages"].last
+        return if last && last["role"] == "assistant"
+
+        content =
+          case outcome
+          when :aborted then "Turn aborted."
+          when :failed then accumulated.empty? ? "The turn failed." : accumulated
+          else accumulated
+          end
+        conv["messages"] << { "role" => "assistant", "content" => content, "created_at" => Time.now.iso8601 }
+        @store.save(conv)
+      rescue StandardError
+        nil
+      end
+
+      # One adapter session per conversation, created on first use.
+      def session_for(conversation, model: nil)
+        @mutex.synchronize do
+          @sessions[conversation["id"]] ||= adapter.create_session(
+            conversation["directory"] || @config.workspace,
+            model: model || @config.model
+          )
+        end
+      end
+
+      # Dispatch a control to the adapter, returning nil when the adapter
+      # doesn't support it (e.g. external ACP agents without approvals).
+      def send_adapter(conversation_id, method_name, *args)
+        sid = @mutex.synchronize { @sessions[conversation_id] }
+        return nil unless sid
+        return nil unless adapter.respond_to?(method_name)
+        adapter.public_send(method_name, sid, *args)
+      end
+
+      def emit(on_event, event)
+        on_event&.call(event)
+      end
+
+      def build_adapter
+        case @config.adapter.to_s
+        when "ask_agent"
+          build_ask_agent_adapter
+        else
+          build_external_adapter
+        end
+      end
+
+      def build_ask_agent_adapter
+        require "ask-coding-providers"
+        adapter = Ask::CodingProviders::AskAgent::Adapter.new(
+          model: @config.model,
+          provider: ENV.fetch("ASK_AGENT_LLM_PROVIDER", "opencode_go"),
+          tools: resolve_tools,
+          max_turns: @config.max_turns,
+          approval: @config.approval,
+          approval_required: @config.approval_policy_tools,
+          plan_mode: @config.plan_mode,
+          todos: @config.todos,
+          system_prompt: default_system_prompt
+        )
+        adapter.start
+        # Tools operate relative to the process working directory; the
+        # workspace IS the working directory for this server.
+        Dir.chdir(@config.workspace) if File.directory?(@config.workspace)
+        adapter
+      end
+
+      def build_external_adapter
+        require "ask/coding_providers"
+        adapter = Ask::CodingProviders.build_adapter(
+          @config.adapter,
+          workspace_path: @config.workspace,
+          turn_timeout: @config.turn_timeout,
+          approval: @config.approval
+        )
+        adapter.start if adapter.respond_to?(:start)
+        adapter
+      end
+
+      def resolve_tools
+        @config.tools.filter_map do |name|
+          klass = @tool_classes[name.to_s]
+          raise ArgumentError, "Unknown tool: #{name}" unless klass
+          klass.new
+        end
+      end
+
+      def default_system_prompt
+        base = "You are the coding agent for the workspace \"#{File.basename(@config.workspace)}\" " \
+               "at #{@config.workspace}. You can read, write, and edit files, search the codebase, " \
+               "and run shell commands to inspect and modify the project. Work autonomously: " \
+               "investigate, make changes, and verify your work."
+        extra = ENV["ACH_SYSTEM_PROMPT"]
+        extra ? "#{base}\n\n#{extra}" : base
+      end
+    end
+  end
+end

data/lib/ask/coding_harness/cli.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Ask
+  module CodingHarness
+    # Command-line interface for the coding harness.
+    #
+    #   ach serve                Start the web server (default)
+    #   ach run "task"           Run a prompt headlessly against the workspace
+    #   ach sessions             List saved conversations
+    #   ach version              Print the version
+    #   ach help                 Show help
+    #
+    # The `ask-coding-harness` executable runs `serve` by default.
+    class CLI
+      def self.run(argv, stdout: $stdout, stderr: $stderr)
+        new(argv, stdout: stdout, stderr: stderr).run
+      end
+
+      def initialize(argv, stdout: $stdout, stderr: $stderr)
+        @argv = argv.dup
+        @stdout = stdout
+        @stderr = stderr
+        # Fresh config per invocation: the CLI is a process boundary and
+        # must honor the environment at launch, not a memoized global.
+        @config = Ask::CodingHarness::Config.new
+      end
+
+      def run
+        command = @argv.shift || "serve"
+        case command
+        when "serve", "server" then serve
+        when "demo" then serve(demo: true)
+        when "run" then run_headless
+        when "sessions" then list_sessions
+        when "version", "--version", "-v" then @stdout.puts Ask::CodingHarness::VERSION
+        when "help", "--help", "-h" then help
+        else
+          @stderr.puts "Unknown command: #{command}"
+          help
+          exit 1
+        end
+      end
+
+      private
+
+      def serve(demo: false)
+        if demo
+          @config.adapter = "demo"
+          require "ask/coding_harness/demo_adapter"
+          @stdout.puts "demo mode: scripted agent, no API key needed"
+        end
+        options = { host: @config.host, port: @config.port }
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: ach serve [options]"
+          o.on("-H", "--host HOST", "Bind host (default #{@config.host})") { |v| options[:host] = v }
+          o.on("-p", "--port PORT", Integer, "Port (default #{@config.port})") { |v| options[:port] = v }
+          o.on("-w", "--workspace DIR", "Workspace directory (default #{@config.workspace})") { |v| @config.workspace = v }
+          o.on("--model MODEL", "Default model") { |v| @config.model = v }
+          o.on("--approval MODE", "off|require|auto") { |v| @config.approval = v.to_sym }
+          o.on("--plan-mode", "Enable plan mode") { @config.plan_mode = true }
+          o.on("--no-todos", "Disable the todo list") { @config.todos = false }
+          o.on("-h", "--help", "Show help") { puts o; return }
+        end
+        parser.parse!(@argv)
+
+        require "ask/coding_harness/server"
+        require "rackup"
+        @stdout.puts "ask-coding-harness #{Ask::CodingHarness::VERSION}"
+        @stdout.puts "workspace: #{@config.workspace}"
+        @stdout.puts "model:     #{@config.model}"
+        @stdout.puts "approval:  #{@config.approval}"
+        @stdout.puts "listening: http://#{options[:host]}:#{options[:port]}"
+        store = Store.new(db_path: @config.db_path)
+        runner = AgentRunner.new(config: @config, store: store)
+        app = Server.build(config: @config, store: store, runner: runner).freeze.app
+        Rackup::Server.start(app: app, Host: options[:host], Port: options[:port])
+      end
+
+      def run_headless
+        options = { quiet: false, model: nil, workspace: nil, approval: :off, adapter: nil }
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: ach run [options] \"prompt\""
+          o.on("-w", "--workspace DIR", "Workspace directory") { |v| options[:workspace] = v }
+          o.on("--model MODEL", "Model to use") { |v| options[:model] = v }
+          o.on("--adapter NAME", "Coding agent adapter (ask_agent, demo, acp, ...)") { |v| options[:adapter] = v }
+          o.on("--approval MODE", "off|require|auto (default off)") { |v| options[:approval] = v.to_sym }
+          o.on("-q", "--quiet", "Suppress the transcript") { options[:quiet] = true }
+          o.on("-h", "--help", "Show help") { puts o; return }
+        end
+        parser.parse!(@argv)
+        if options[:adapter] == "demo"
+          require "ask/coding_harness/demo_adapter"
+        end
+        @config.adapter = options[:adapter] if options[:adapter]
+
+        prompt = @argv.join(" ").strip
+        if prompt.empty?
+          @stderr.puts "Error: a prompt is required"
+          @stderr.puts "Usage: ach run [options] \"prompt\""
+          exit 1
+        end
+
+        @config.workspace = options[:workspace] if options[:workspace]
+        require "ask/coding_harness/runner"
+        result = Runner.new(config: @config, approval: options[:approval]).run(
+          prompt, model: options[:model], quiet: options[:quiet]
+        )
+        exit(result.success? ? 0 : 1)
+      end
+
+      def list_sessions
+        store = Store.new(db_path: @config.db_path)
+        conversations = store.list
+        if conversations.empty?
+          @stdout.puts "No conversations yet."
+          return
+        end
+        conversations.each do |c|
+          @stdout.puts "#{c["id"][0, 8]}  #{c["title"]}  (#{c["message_count"]} messages, #{c["updated_at"]})"
+        end
+      end
+
+      def help
+        @stdout.puts <<~HELP
+          ask-coding-harness #{Ask::CodingHarness::VERSION} — general-purpose coding agent in the browser.
+
+          Usage:
+            ach serve                Start the web server (default)
+            ach demo                 Serve with the scripted demo agent (no API key)
+            ach run "task"           Run a prompt headlessly in the workspace
+            ach sessions             List saved conversations
+            ach version              Print the version
+            ach help                 Show this help
+
+          Environment:
+            ACH_WORKSPACE     workspace directory (default: current dir)
+            ACH_HOST / ACH_PORT
+            ACH_MODEL         default model
+            ACH_ADAPTER       coding agent adapter: ask_agent (default) or any
+                              ask-coding-providers adapter (acp, codex, claude)
+            ACH_APPROVAL      off | require | auto (default: require)
+            ACH_PLAN_MODE     enable plan mode (1/true)
+            ACH_TODOS         todo list (default: on)
+            ACH_DB_PATH       conversation database path
+        HELP
+      end
+    end
+  end
+end