ask-rails 0.2.5 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6e0eb7fb3f6797eb16e096b2f2e5b0c79eb002d697be20df6ac0b2bbe5abf3a
-  data.tar.gz: 4c6ffe88deca00e9e43472e286fb37630ba30953a5488d577a37ee805ccd7b73
+  metadata.gz: 862c3a8f40c0b2a6d720ab247ce87caecdfc9e5c9242c1daa386eb09d23fe300
+  data.tar.gz: 942cfdfd66cbc0e36ed56e1bfd16009226d12244cfa558e75facc99ace1c3781
 SHA512:
-  metadata.gz: 3aafbab19ef97841a392242282f19886624412ec92602dfc525dcfd2743f05adc523f2604c139e847a9078ec307f596c85005796d8dab484ca32bb84bcd36e3e
-  data.tar.gz: 0f13102f41d739aa2215684508a8d705df6ef2ad842b2404d4232bf4b689840ec0eca0153ea71f503ce114eadb11bd0396bee6d3d30202e9376caf04ebd506bc
+  metadata.gz: 0e769e86dec70f2a4533f0de007c00e32f63c8d270d2929b29e503c22fa5b4bf780c2464be5b65d30bbb0596a2967d075cf4b122d162169178acc62dece6bf54
+  data.tar.gz: eccd169faf6f16f3e949fe2562e07f46eeaa99d4118bb4c7952526daeeacc6d9337c804640087d1850a6d0ee34efd79aa05e7060889fec2d7b455a62a296b0e5

data/CHANGELOG.md

@@ -1,3 +1,149 @@
+## [0.10.0] — 2026-07-23
+
+### Added
+
+- **Session cleanup** — Auto-prune old or excess sessions via `max_session_age` and `max_sessions` config options. Prunes both `ask_sessions` and `ask_audit_logs` tables.
+  - `config.max_session_age = 7.days` — deletes sessions older than the threshold
+  - `config.max_sessions = 1000` — keeps at most N sessions, deletes oldest
+  - Auto-prunes on every `agent_session` call when configured
+  - Also callable manually: `Ask::Rails.cleanup!`
+  - Rake task: `rails ask_rails:cleanup`
+
+## [0.9.0] — 2026-07-23
+
+### Fixed
+
+- **ReadFile, ReadRoutes, SearchCodebase** — Fixed `ArgumentError: unknown keyword: :data` crash on Ruby 4.0. Tools now return plain Hashes on success instead of using the incompatible `Ask::Result.success` API.
+- **SearchCodebase** — Marked `path` param as optional (was incorrectly required). Added shell escaping for grep patterns.
+
+### Added
+
+- **23 new execution tests** — ReadFile (3), SearchCodebase (3), ReadRoutes (2), ReadModel (6), plus 6 integration tests. Each tool now has real execution tests beyond just param checks.
+- **160 total tests** — 0 failures, 0 errors.
+
+## [0.8.0] — 2026-07-23
+
+### Added
+
+- **SchemaGraph tool** — Full application schema introspection in one call. Returns every model, table, column (with types and nullability), association (belongs_to, has_many, has_one, HABTM, through), validation, index, and polymorphic relationship. The agent gets a complete mental model of the app's data layer — no more reading models one at a time.
+  - `schema_graph(detail: "all")` — everything
+  - `schema_graph(detail: "models")` — just models and columns
+  - `schema_graph(detail: "associations")` — just the association graph
+  - `schema_graph(detail: "tables")` — just tables, columns, and indexes
+
+- **RouteInspector tool** — Parsed Rails route table (not raw routes.rb). Returns every route with HTTP verb, path, controller, action, and name. Supports filtering by controller and path pattern. Replaces the old ReadRoutes which returned raw file content.
+  - `route_inspector` — all routes
+  - `route_inspector(controller: "users")` — routes for a specific controller
+  - `route_inspector(pattern: "admin")` — routes matching a path pattern
+
+- **Core tools auto-discovery** — The 9 built-in Rails tools (ReadFile, RunCommand, SearchCodebase, ReadRoutes, QueryDatabase, ReadModel, ReadLog, SchemaGraph, RouteInspector) are now automatically included in every agent session. Previously they were loaded but not registered.
+
+### Changed
+
+- `discover_tools!` now includes `CORE_RAILS_TOOLS` — all 9 Rails tools are automatically available to the agent.
+
+## [0.7.0] — 2026-07-23
+
+### Added
+
+- **Tool execution visualization** — The chat UI now shows live tool execution cards as the agent runs. Each tool call displays as an expandable card with name, args, and real-time elapsed time. Cards show ✓ for success or ✗ for failure with duration.
+- **Activity panel** — New "Activity" sidebar tab shows the audit log in real-time. Browse recent tool calls across all sessions with status, duration, and timestamp.
+- **Per-session audit view** — Clicking a session loads its audit trail. New `GET /ask/sessions/:session_id/audit` endpoint.
+- **Individual session deletion** — Delete sessions one at a time via the ✕ button in the sidebar. New `DELETE /ask/sessions/:id` route.
+- **Sidebar search** — Filter sessions by text in the sidebar search box.
+- **Session previews** — Sidebar shows the first message as a preview instead of just the session ID.
+- **Keyboard shortcuts** — Ctrl+K / Cmd+K focuses the input. Enter sends (Shift+Enter for newline).
+- **Environment badge** — Current Rails.env shown in both the sidebar footer and chat header.
+- **`destroy_session` action** — New controller action for deleting individual sessions.
+
+### Changed
+
+- **Chat layout** — Complete visual overhaul: darker theme, improved spacing, tool cards, sidebar tabs (Sessions/Activity), session search, and streaming indicator.
+- **`message` SSE stream** — Now emits `tool_start`, `tool_end`, and `tool_update` events alongside `delta` and `thinking` for real-time tool execution visibility.
+- **Controller actions** — `destroy` renamed to `destroy_all` for clarity.
+
+## [0.6.0] — 2026-07-23
+
+### Added
+
+- **Per-environment permissions** — Configure access modes and command allowlists per Rails environment:
+  ```ruby
+  Ask::Rails.configure do |config|
+    config.environment :production do |env|
+      env.mode = :read_only
+      env.allowed_commands = [/^rails routes/]
+      env.denied_commands = [/rm/, /dropdb/]
+    end
+
+    config.environment :development do |env|
+      env.mode = :full_access
+    end
+  end
+  ```
+- **`Ask::Rails::EnvironmentPermissions`** — New config class holding `mode`, `allowed_commands`, and `denied_commands` per environment.
+- **Automatic Permissions wiring** — When an environment `mode` is set, `agent_session` automatically creates an `Ask::Agent::Extensions::Permissions` extension and wires it into the session hooks.
+- **Effective rule resolution** — `Configuration#effective_allowed_commands`, `#effective_denied_commands`, and `#effective_mode` resolve per-environment rules or fall back to global config.
+
+## [0.5.0] — 2026-07-22
+
+### Added
+
+- **Command Allowlist** — `RunCommand` now checks `allowed_commands` and `denied_commands` before executing. Configure with regex patterns:
+  - `Ask::Rails.configuration.allowed_commands = [/^rails /, /^git status/]`
+  - `Ask::Rails.configuration.denied_commands = [/rm /, /dropdb/]`
+  - `denied_commands` takes precedence over `allowed_commands`
+  - When `allowed_commands` is nil (default), all commands pass through (except those in `denied_commands`)
+  - Blocked commands return `Ask::Result.error` with a descriptive message and are recorded in the audit log
+
+- **`allowed_commands` and `denied_commands` configuration options** — Two new arrays of regex patterns on the `Configuration` object.
+
+## [0.4.0] — 2026-07-22
+
+### Added
+
+- **Audit Log** — Every tool call is now recorded in the `ask_audit_logs` table with the intent (sanitized params), outcome (status/timing), and user context. Append-only, never modified. Provides a trustworthy record of what the agent did without storing sensitive data or full results.
+  - `Ask::Rails::AuditLog.log` — logs a tool execution event
+  - Sensitive params (keys matching `password`, `secret`, `token`, `api_key`, `key`) are automatically redacted as `[REDACTED]`
+  - Fires `audit_log.ask_rails` ActiveSupport notification for host app alerting
+  - Results are summarized (row count for queries, exit status for commands, etc.) — full data never stored
+  - Generator creates the `create_ask_audit_logs` migration
+
+- **`current_user` configuration** — `Ask::Rails.configure { |c| c.current_user = -> { Current.user ? { id: Current.user.id, email: Current.user.email } : nil } }` attaches user context to every audit log entry.
+
+- **`Ask::Rails::Tool.session_id`** — Thread-local accessor so tool calls are correlated with their agent session in the audit log.
+
+### Changed
+
+- **Tool base class** — `Ask::Rails::Tool#call` is now instrumented to automatically log every invocation to the audit log. All 7 Rails tools inherit this behavior.
+
+## [0.3.0] — 2026-07-21
+
+### Added
+
+- **Admin chat UI** — Mount `Ask::Rails::Engine` at `/ask` and get a working chat interface with SSE streaming. No generator needed — just mount and go.
+
+  ```
+  GET  /ask                    → Chat UI
+  POST /ask/sessions           → Create new session
+  POST /ask/sessions/:id/messages → Send message (SSE streamed)
+  GET  /ask/sessions/:id/messages → Message history
+  GET  /ask/sessions/:id/stream  → SSE stream for existing session
+  ```
+
+- **`Ask::Rails::ChatController`** — Full controller with actions: `index`, `create`, `message` (SSE streaming), `stream`, `history`, `destroy`. Supports real-time streaming via `Enumerator` + `text/event-stream`.
+
+- **Chat layout and view** — A dark-themed admin chat interface shipped in the gem (not generated). Includes sidebar with session list, message history, SSE streaming, and keyboard navigation.
+
+- **`Ask::Rails::Auth`** — Configurable authentication hook. Set `Ask::Rails::Auth.check = -> { ... }` to protect the chat behind your existing auth system. Runs in controller context — `current_user`, `redirect_to`, etc. are available.
+
+- **Engine routes** — Routes defined in `config/routes.rb` with proper `Ask::Rails::Engine.routes.draw` isolation.
+
+### Changed
+
+- **README** — Rewritten with clear positioning: ask-rails is for internal admin agents. ask-agent is for external-facing agents. Includes comparison table, quick start guide, and tool reference.
+- **Engine** — `isolate_namespace Ask::Rails` for proper route isolation.
+- **Gemspec** — Now includes `app/` and `config/` directories for engine views, controllers, and routes.
+
 ## [0.2.5] - 2026-06-25
 
 ### Changed
@@ -33,3 +179,14 @@
 - Rails Tools — `ReadFile`, `RunCommand`, `SearchCodebase`, `ReadRoutes` (Rails.root-aware)
 - Generators — `rails generate ask_rails:install` creates migration, initializer, `app/tools/`
 - Dependencies: rails >= 7.1, ask-tools, ask-tools-shell, ask-agent, ask-auth
+
+## [0.11.0] — 2026-07-23
+
+### Changed
+
+- **`Persistence` adapter now speaks `State::Adapter` contract** — Added `set(key, value)` and `get(key)` methods delegating to `save`/`load`. This makes it compatible with the new `state:` keyword on `Ask::Agent::Session`. Old `save`/`load` interface preserved for backward compatibility.
+- **`agent_session` uses `state:` keyword** — Changed from `persistence:` to `state:`.
+
+### Added
+
+- **Persistence tests** — New `FakeModel` fixture with 6 real roundtrip tests covering set/get, missing key, delete, list, and old save/load interface.

data/README.md

@@ -1,8 +1,22 @@
 # ask-rails
 
-Rails integration for the ask-rb ecosystem. The only gem a Rails app needs to join
-the ask-rb stack — provides a Railtie, AR session persistence, a session factory,
-automatic service gem discovery, and generators.
+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.
+
+## 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
+
+- **7 Rails-aware tools**: `ReadFile`, `QueryDatabase`, `ReadRoutes`, `ReadModel`, `ReadLog`, `RunCommand`, `SearchCodebase`
+- **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
 
@@ -11,24 +25,94 @@ bundle add ask-rails
 rails generate ask_rails: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::Engine, at: "/ask"
+  end
+end
+```
+
+Then visit `/ask` in your browser.
+
 ## Usage
 
+### Configuration
+
 ```ruby
-# In any Rails context
+# config/initializers/ask_rails.rb
+Ask::Rails.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.agent_session
 session.run("Find all open issues labeled 'bug' in our repo")
 ```
 
-Service gems like `ask-github`, `ask-slack` are auto-discovered — the agent gets their
-context (auth info, quick-start snippets, error guides) in the system prompt automatically.
+### Route Helpers
 
-## Development
+```ruby
+ask_rails.root_path               # => /ask
+ask_rails.sessions_path           # => /ask/sessions
+ask_rails.session_messages_path(session_id) # => /ask/sessions/:id/messages
+```
 
-```bash
-bin/setup
-bundle exec rake test
+### 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.rb
+Ask::Rails::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 |
+
+## 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` |
+|---|---|
+| 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/chat_controller.rb

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ask
+  module Rails
+    class ChatController < ::ActionController::Base
+      layout "ask/rails/application"
+
+      before_action :authenticate!, unless: -> { Ask::Rails::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.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.configuration.persistence_adapter
+        if persistence
+          persistence.list.each { |id| persistence.delete(id) }
+        end
+        redirect_to ask_rails.root_path
+      end
+
+      # DELETE /ask/sessions/:session_id — destroy a specific session
+      def destroy_session
+        persistence = Ask::Rails.configuration.persistence_adapter
+        persistence&.delete(params[:session_id])
+        redirect_to ask_rails.root_path
+      end
+
+      private
+
+      def authenticate!
+        instance_eval(&Ask::Rails::Auth.check) if Ask::Rails::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.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.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.agent_session(persistence: persistence).tap do |s|
+          s.instance_variable_set(:@id, session_id)
+        end
+      end
+
+      def load_sessions
+        persistence = Ask::Rails.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.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.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_model,
+            created_at: Time.now.iso8601,
+            updated_at: Time.now.iso8601
+          }
+        })
+      end
+
+      def ask_rails_model
+        Ask::Rails.configuration.default_model
+      end
+
+      def tool_events_supported?
+        defined?(Ask::Agent::Events::ToolExecutionStart)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Ask
+  module Rails
+    # ActiveRecord model for persisting agent sessions.
+    #
+    # Created by the +ask_rails: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.configure do |config|
+    #     config.persistence_adapter = Ask::Rails::Persistence.new
+    #   end
+    #
+    # Without +model_class:+, +Persistence+ defaults to +Ask::Rails::Session+.
+    class Session < ActiveRecord::Base
+      self.table_name = "ask_sessions"
+    end
+  end
+end

data/app/views/ask/rails/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-data",
+      data: { sessions: @sessions.to_json, active_session_id: @active_session&.dig(:id) } %>