ask-rails-harness 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1c1a8388500ab4366c876be18f2b8fb2fd2c489fcd6c04da90c2a1ee9eea8b59
+  data.tar.gz: 6012eff1acc1cdecd8b606a91027f517a69ddb77d252c0aae8846e23b5e7f15e
+SHA512:
+  metadata.gz: 7492561a0888730defddcff380d3800afefab364f41bf4df2e842a1894cdc4229c08e7d9c249df0b2d8ece1d0e9e345369840434a1af10d8802eb2f9f2fac4c4
+  data.tar.gz: 490b772093ac41af1ca679dfa55af7500ede1c634d01e82a3f7393ba23381fdf30507bf95929d8405e824ab7daf0d05f17052164a41724e8547bf7c4f3848abb

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+## [0.1.0] — 2026-07-25
+
+### Changed
+
+- **Gem renamed from `ask-rails` to `ask-rails-harness`** — The gem has been renamed to better reflect its purpose as an admin AI copilot harness for Rails apps. The old `ask-rails` gem name has been yanked from rubygems.org to make room for a new `ask-rails` gem with a different purpose.
+- **Module namespace moved from `Ask::Rails` to `Ask::Rails::Harness`** — All code now lives under `Ask::Rails::Harness::*` to coexist with the planned `ask-rails` gem.
+- **Engine namespace changed** — `isolate_namespace` updated from `Ask::Rails` to `Ask::Rails::Harness`. Route helpers change from `ask_rails.*` to `ask_rails_harness.*`.
+- **Generator renamed** — Use `rails generate ask_rails_harness:install` instead of `ask_rails:install`.
+- **Initializer renamed** — Generated file is now `config/initializers/ask_rails_harness.rb`.
+- **Rake task renamed** — Use `rails ask_rails_harness:cleanup` instead of `ask_rails:cleanup`.
+- **Notification name changed** — `audit_log.ask_rails` is now `audit_log.ask_rails_harness`.
+- **Log prefix changed** — `[ask-rails]` is now `[ask-rails-harness]`.
+
+### Migration from ask-rails
+
+Existing applications using `ask-rails` should:
+1. Replace `gem "ask-rails"` with `gem "ask-rails-harness"` in your Gemfile
+2. Update `Ask::Rails.configure` → `Ask::Rails::Harness.configure`
+3. Update `mount Ask::Rails::Engine` → `mount Ask::Rails::Harness::Engine`
+4. Update `ask_rails.*` route helpers → `ask_rails_harness.*`
+5. Update `Ask::Rails::Auth` → `Ask::Rails::Harness::Auth`
+6. Rename initializer from `ask_rails.rb` to `ask_rails_harness.rb`
+
+All previous versions (0.1.0–0.11.1) were released under the `ask-rails` gem name. See the [ask-rails CHANGELOG](https://github.com/ask-rb/ask-rails) for history of those releases.

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,122 @@
+# ask-rails-harness
+
+An admin AI agent for your Rails app. Mount the engine, get a chat interface at `/ask` that can inspect your code, query your database, read logs, and help you debug — all through an authenticated admin UI.
+
+> **Previously developed as `ask-rails` (v0.1.0–0.11.1).** Renamed to `ask-rails-harness` for clarity — this gem is the *harness* that wraps an AI agent with Rails-aware tools, environment, state, and feedback for internal/admin use.
+
+## Who is this for?
+
+- **Rails developers** who want an AI co-pilot that understands their app's codebase, schema, routes, and logs
+- **Internal/Admin use only** — the agent has direct access to your database, file system, and shell. Not for external/customer-facing use.
+
+For building customer-facing AI agents, use `ask-agent` directly with your own tools and UI.
+
+## What it gives you
+
+- **9 Rails-aware tools**: `ReadFile`, `QueryDatabase`, `ReadRoutes`, `ReadModel`, `ReadLog`, `RunCommand`, `SearchCodebase`, `SchemaGraph`, `RouteInspector`
+- **Admin chat UI**: Mount the engine, get a working chat at `/ask` with SSE streaming
+- **Auth integration**: Protect `/ask` behind your existing Devise/authentication
+- **AR persistence**: Agent sessions survive server restarts
+- **Service discovery**: Auto-detects installed ask-\* service gems
+- **Skills**: Built-in guides for Rails debugging, deployment, and database performance
+
+## Installation
+
+```bash
+bundle add ask-rails-harness
+rails generate ask_rails_harness:install
+```
+
+## Quick Start
+
+Add the engine mount and auth protection to `config/routes.rb`:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  # ... your routes ...
+
+  authenticate :user, ->(u) { u.admin? } do
+    mount Ask::Rails::Harness::Engine, at: "/ask"
+  end
+end
+```
+
+Then visit `/ask` in your browser.
+
+## Usage
+
+### Configuration
+
+```ruby
+# config/initializers/ask_rails_harness.rb
+Ask::Rails::Harness.configure do |c|
+  c.default_model = "claude-sonnet-4"
+  c.max_turns = 50
+end
+```
+
+### Programmatic Access
+
+```ruby
+# From any controller, view, or job
+session = Ask::Rails::Harness.agent_session
+session.run("Find all open issues labeled 'bug' in our repo")
+```
+
+### Route Helpers
+
+```ruby
+ask_rails_harness.root_path               # => /ask
+ask_rails_harness.sessions_path           # => /ask/sessions
+ask_rails_harness.session_messages_path(session_id) # => /ask/sessions/:id/messages
+```
+
+### Auth
+
+By default, the admin chat is unprotected. Add auth in your routes (as shown above) or set a custom check:
+
+```ruby
+# config/initializers/ask_rails_harness.rb
+Ask::Rails::Harness::Auth.check = -> {
+  redirect_to main_app.login_path unless current_user&.admin?
+}
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `ReadFile` | Read any file (relative to `Rails.root`) |
+| `QueryDatabase` | Run read-only SQL (rejects non-SELECT in production) |
+| `ReadModel` | Inspect AR model schema, associations, validations |
+| `ReadRoutes` | View `config/routes.rb` |
+| `ReadLog` | Read log files with level/search filtering |
+| `RunCommand` | Run shell commands in the app root |
+| `SearchCodebase` | Grep the codebase for patterns |
+| `SchemaGraph` | Full schema introspection — all models, tables, columns, associations |
+| `RouteInspector` | Parsed route table with filters |
+
+## Engine Routes
+
+```
+GET  /ask                    → Chat UI
+POST /ask/sessions           → Create new session
+POST /ask/sessions/:id/messages → Send message (SSE streamed response)
+GET  /ask/sessions/:id/messages → Get message history
+GET  /ask/sessions/:id/stream  → SSE stream for existing session
+```
+
+## Compared to ask-agent
+
+| `ask-agent` | `ask-rails-harness` |
+|---|---|
+| Build external-facing agents | Build an internal admin co-pilot |
+| Bring your own tools | Ships Rails-specific tools |
+| Bring your own UI | Ships an admin chat UI |
+| Any Ruby app | Rails apps only |
+| General purpose | Development, debugging, ops |
+
+## License
+
+MIT

data/app/controllers/ask/rails/harness/chat_controller.rb

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ask
+  module Rails
+    module Harness
+      class ChatController < ::ActionController::Base
+        layout "ask/rails/harness/application"
+
+        before_action :authenticate!, unless: -> { Ask::Rails::Harness::Auth.check.nil? }
+        before_action :set_session, only: [:message, :stream, :history, :show, :audit]
+
+        # GET /ask — main chat interface
+        def index
+          @sessions = load_sessions
+          @active_session = @sessions.first
+          @audit_logs = load_recent_audit_logs
+          render :index
+        end
+
+        # POST /ask/sessions — create a new session
+        def create
+          session_id = SecureRandom.uuid
+
+          agent = build_agent_session
+          agent.save
+
+          store_session_metadata(session_id, agent)
+
+          redirect_to ask_rails_harness.root_path
+        end
+
+        # GET /ask/sessions/:id — show a specific session
+        def show
+          @messages = load_session_messages(@session_id)
+          @audit_logs = load_session_audit_logs(@session_id)
+          render json: { id: @session_id, messages: @messages, audit_logs: @audit_logs }
+        end
+
+        # GET /ask/sessions — list all sessions
+        def index_sessions
+          @sessions = load_sessions
+          render json: @sessions
+        end
+
+        # POST /ask/sessions/:session_id/messages — send a message, get SSE stream
+        def message
+          prompt = params[:message].to_s.strip
+          return head :bad_request if prompt.empty?
+
+          response.headers["Content-Type"] = "text/event-stream"
+          response.headers["Cache-Control"] = "no-cache"
+          response.headers["X-Accel-Buffering"] = "no"
+          response.headers["Last-Modified"] = Time.now.httpdate
+
+          self.response_body = Enumerator.new do |yielder|
+            agent = resume_or_create_session(@session_id)
+
+            # Subscribe to tool execution events
+            tool_sub = subscribe_tool_events(agent, yielder)
+
+            yielder << "data: #{JSON.generate(type: 'start', session_id: @session_id)}\n\n"
+
+            begin
+              agent.run(prompt) do |chunk|
+                if chunk.content&.length&.> 0
+                  yielder << "data: #{JSON.generate(type: 'delta', content: chunk.content)}\n\n"
+                end
+                if chunk.thinking&.length&.> 0
+                  yielder << "data: #{JSON.generate(type: 'thinking', content: chunk.thinking)}\n\n"
+                end
+              end
+
+              agent.save
+              @session = agent
+
+              yielder << "data: #{JSON.generate(type: 'done', session_id: @session_id)}\n\n"
+            rescue Ask::Agent::MaxTurnsExceeded => e
+              yielder << "data: #{JSON.generate(type: 'error', message: "Agent hit the turn limit (#{e.message})")}\n\n"
+            rescue Ask::Auth::MissingCredential => e
+              yielder << "data: #{JSON.generate(type: 'error', message: "Missing API key: #{e.message}. Check your provider configuration.")}\n\n"
+            rescue Ask::Auth::InvalidCredential => e
+              yielder << "data: #{JSON.generate(type: 'error', message: "Invalid API key: #{e.message}. Update your credentials.")}\n\n"
+            rescue StandardError => e
+              yielder << "data: #{JSON.generate(type: 'error', message: "Agent error: #{e.message}")}\n\n"
+            end
+          ensure
+            agent&.remove_event_subscriber(tool_sub) if tool_sub
+          end
+        end
+
+        # GET /ask/sessions/:session_id/stream — SSE stream for an existing session
+        def stream
+          response.headers["Content-Type"] = "text/event-stream"
+          response.headers["Cache-Control"] = "no-cache"
+          response.headers["X-Accel-Buffering"] = "no"
+
+          self.response_body = Enumerator.new do |yielder|
+            messages = load_session_messages(@session_id)
+            audit_logs = load_session_audit_logs(@session_id)
+            yielder << "data: #{JSON.generate(type: 'history', messages: messages, audit_logs: audit_logs)}\n\n"
+
+            sleep 30
+            yielder << "data: #{JSON.generate(type: 'keepalive')}\n\n"
+          end
+        end
+
+        # GET /ask/sessions/:session_id/messages — get message history as JSON
+        def history
+          messages = load_session_messages(@session_id)
+          render json: messages
+        end
+
+        # GET /ask/sessions/:session_id/audit — get audit logs for a session
+        def audit
+          logs = load_session_audit_logs(@session_id)
+          render json: logs
+        end
+
+        # DELETE /ask/sessions — destroy all sessions
+        def destroy_all
+          persistence = Ask::Rails::Harness.configuration.persistence_adapter
+          if persistence
+            persistence.list.each { |id| persistence.delete(id) }
+          end
+          redirect_to ask_rails_harness.root_path
+        end
+
+        # DELETE /ask/sessions/:session_id — destroy a specific session
+        def destroy_session
+          persistence = Ask::Rails::Harness.configuration.persistence_adapter
+          persistence&.delete(params[:session_id])
+          redirect_to ask_rails_harness.root_path
+        end
+
+        private
+
+        def authenticate!
+          instance_eval(&Ask::Rails::Harness::Auth.check) if Ask::Rails::Harness::Auth.check
+        end
+
+        def set_session
+          @session_id = params[:session_id] || params[:id]
+          head :not_found unless @session_id
+        end
+
+        def build_agent_session(**extra)
+          Ask::Rails::Harness.agent_session(**extra)
+        end
+
+        def subscribe_tool_events(agent, yielder)
+          return nil unless agent.respond_to?(:on_event)
+
+          agent.on_event do |event|
+            case event
+            when Ask::Agent::Events::ToolExecutionStart
+              yielder << "data: #{JSON.generate(
+                type: 'tool_start',
+                name: event.name,
+                id: event.id,
+                args: safe_tool_args(event.arguments)
+              )}\n\n"
+            when Ask::Agent::Events::ToolExecutionEnd
+              yielder << "data: #{JSON.generate(
+                type: 'tool_end',
+                name: event.name,
+                id: event.id,
+                duration_ms: event.duration_ms,
+                is_error: event.is_error
+              )}\n\n"
+            when Ask::Agent::Events::ToolExecutionUpdate
+              yielder << "data: #{JSON.generate(
+                type: 'tool_update',
+                id: event.id,
+                content: event.partial_result.to_s.truncate(200)
+              )}\n\n"
+            end
+          end
+        end
+
+        def safe_tool_args(args)
+          return {} unless args.is_a?(Hash)
+
+          safe = args.dup
+          %w[password secret token api_key key auth_token access_token sql command].each do |sensitive|
+            safe[sensitive] = "[REDACTED]" if safe.key?(sensitive)
+          end
+          safe
+        end
+
+        def resume_or_create_session(session_id)
+          persistence = Ask::Rails::Harness.configuration.persistence_adapter
+
+          if persistence
+            data = persistence.load(session_id)
+            if data
+              session = Ask::Agent::Session.load(session_id, adapter: persistence)
+              return session if session
+            end
+          end
+
+          Ask::Rails::Harness.agent_session(persistence: persistence).tap do |s|
+            s.instance_variable_set(:@id, session_id)
+          end
+        end
+
+        def load_sessions
+          persistence = Ask::Rails::Harness.configuration.persistence_adapter
+          return [] unless persistence
+
+          persistence.list.map do |id|
+            data = persistence.load(id) || {}
+            messages = data[:messages] || []
+            { id: id, created_at: data.dig(:metadata, :created_at), message_count: messages.length, preview: messages.first&.dig(:content).to_s.truncate(60) }
+          end.sort_by { |s| s[:created_at] || "" }.reverse
+        end
+
+        def load_session_messages(session_id)
+          persistence = Ask::Rails::Harness.configuration.persistence_adapter
+          return [] unless persistence
+
+          data = persistence.load(session_id)
+          return [] unless data
+
+          (data[:messages] || []).map { |m|
+            { role: m[:role], content: m[:content].to_s }
+          }
+        end
+
+        def load_session_audit_logs(session_id)
+          return [] unless defined?(ActiveRecord::Base)
+
+          ActiveRecord::Base.connection.execute(
+            "SELECT tool_name, status, duration_ms, environment, recorded_at, " \
+            "params, result_summary, error_message, user_context " \
+            "FROM ask_audit_logs WHERE session_id = #{ActiveRecord::Base.connection.quote(session_id.to_s)} " \
+            "ORDER BY recorded_at ASC"
+          ).map do |row|
+            {
+              tool_name: row["tool_name"],
+              status: row["status"],
+              duration_ms: row["duration_ms"],
+              environment: row["environment"],
+              recorded_at: row["recorded_at"],
+              params: parse_json_field(row["params"]),
+              result_summary: parse_json_field(row["result_summary"]),
+              error_message: row["error_message"],
+              user_context: parse_json_field(row["user_context"])
+            }
+          end
+        rescue StandardError
+          []
+        end
+
+        def load_recent_audit_logs
+          return [] unless defined?(ActiveRecord::Base)
+
+          ActiveRecord::Base.connection.execute(
+            "SELECT session_id, tool_name, status, duration_ms, recorded_at " \
+            "FROM ask_audit_logs ORDER BY recorded_at DESC LIMIT 100"
+          ).map do |row|
+            {
+              session_id: row["session_id"].to_s[0..7],
+              tool_name: row["tool_name"],
+              status: row["status"],
+              duration_ms: row["duration_ms"],
+              recorded_at: row["recorded_at"]
+            }
+          end
+        rescue StandardError
+          []
+        end
+
+        def parse_json_field(value)
+          return nil unless value
+          return value if value.is_a?(Hash) || value.is_a?(Array)
+          JSON.parse(value)
+        rescue JSON::ParserError
+          value
+        end
+
+        def store_session_metadata(session_id, agent)
+          persistence = Ask::Rails::Harness.configuration.persistence_adapter
+          return unless persistence
+
+          persistence.save(session_id, {
+            id: session_id,
+            messages: agent.messages.map { |m|
+              { role: m.role, content: m.content.to_s }
+            },
+            metadata: {
+              model: ask_rails_harness_model,
+              created_at: Time.now.iso8601,
+              updated_at: Time.now.iso8601
+            }
+          })
+        end
+
+        def ask_rails_harness_model
+          Ask::Rails::Harness.configuration.default_model
+        end
+
+        def tool_events_supported?
+          defined?(Ask::Agent::Events::ToolExecutionStart)
+        end
+      end
+    end
+  end
+end

data/app/models/ask/rails/harness/session.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Ask
+  module Rails
+    module Harness
+      # ActiveRecord model for persisting agent sessions.
+      #
+      # Created by the +ask_rails_harness:install+ generator. The +ask_sessions+ table
+      # stores session state in a JSONB +data+ column, keyed by a unique
+      # +session_id+ string.
+      #
+      # Used automatically when +persistence_adapter+ is configured with the
+      # default model class:
+      #
+      #   Ask::Rails::Harness.configure do |config|
+      #     config.persistence_adapter = Ask::Rails::Harness::Persistence.new
+      #   end
+      #
+      # Without +model_class:+, +Persistence+ defaults to +Ask::Rails::Harness::Session+.
+      class Session < ActiveRecord::Base
+        self.table_name = "ask_sessions"
+      end
+    end
+  end
+end

data/app/views/ask/rails/harness/chat/index.html.erb

@@ -0,0 +1,6 @@
+<!-- Chat interface rendered by the layout -->
+<!-- The layout handles the full UI. This view is minimal -->
+<!-- since the layout and JavaScript drive the interface. -->
+
+<%= tag.div id: "ask-rails-harness-data",
+      data: { sessions: @sessions.to_json, active_session_id: @active_session&.dig(:id) } %>