console_agent 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '09b1eab5b0fd84fb27fe9af623c234da290779f84d5972d4a67bfe000d581ab2'
-  data.tar.gz: 344f3afbc67adc4d87c5c2fb4e11ccc902fca071776a4a3aa6cb160783e22998
+  metadata.gz: 661ab1a997f36d2b10ea9649aa41367aca039c859c3e2afa01c3cbf8b8dd9345
+  data.tar.gz: 5cfe513d78a1785b7199fb0ebbbc70e825092e49e4051caf390e3ccb7ccf23c4
 SHA512:
-  metadata.gz: 73a5c9bd000e30b3cfa63c06efbb0f9619849ec56ca8b4b8f1c71cd7eae29439f9b4ef8d10725950aa8fb813159674820706fa5883784060464f8c9959c914aa
-  data.tar.gz: 4498692aab0860b717b7d309e252cb1b2130b7946a55421f0edd76c3b3469da27c6f8426667e23cf0a2fcab66a356896573f19b819c8ba603f08f50a5e60647d
+  metadata.gz: 0d7fd63a81886c7abbf4f82db677b6b4bb9151760c378901306e789b3619d7ca31b743f7f4a14a9a28335e775877243b0c4ff8b8bd6cc6acee0c8a02c270eccc
+  data.tar.gz: 3e0308bd89e0421a4a29dbe8c7b7be6afd584a504559a456f830e1c9a268517d131d6dcf00417347f5f3ea80a434bf9211e0515771fc3e43686f0117bf401f9b

data/README.md

@@ -1,48 +1,40 @@
 # ConsoleAgent
 
-An AI-powered assistant for your Rails console. Ask questions in plain English, get executable Ruby code.
+Claude Code, embedded in your Rails console.
 
-ConsoleAgent connects your `rails console` to an LLM (Claude or GPT) and gives it tools to introspect your app's database schema, models, and source code. It figures out what it needs on its own, so you don't pay for 50K tokens of context on every query.
+Ask questions in plain English. The AI explores your schema, models, and source code on its own, then writes and runs the Ruby code for you.
 
-## Quick Start
-
-Add to your Gemfile:
+## Install
 
 ```ruby
+# Gemfile
 gem 'console_agent', group: :development
 ```
 
-Run the install generator:
-
 ```bash
 bundle install
 rails generate console_agent:install
 ```
 
-Set your API key and open a console:
+Set your API key in the generated initializer or as an env var (`ANTHROPIC_API_KEY`):
 
-```bash
-export ANTHROPIC_API_KEY=sk-ant-...
-rails console
+```ruby
+# config/initializers/console_agent.rb
+ConsoleAgent.configure do |config|
+  config.api_key = 'sk-ant-...'
+end
 ```
 
-Then:
+To set up session logging (OPTIONAL), create the table from the console:
 
 ```ruby
-ai "show me all users who signed up this week"
+ConsoleAgent.setup!
+# => ConsoleAgent: created console_agent_sessions table.
 ```
 
-## Console Commands
-
-| Command | Description |
-|---------|-------------|
-| `ai "query"` | Ask a question, review generated code, confirm before executing |
-| `ai! "query"` | Ask a question and enter interactive mode for follow-ups |
-| `ai!` | Enter interactive mode (type `exit` to leave) |
-| `ai? "query"` | Explain only — shows code but never executes |
-| `ai_status` | Print current configuration summary |
+To reset the table (e.g. after upgrading), run `ConsoleAgent.teardown!` then `ConsoleAgent.setup!`.
 
-### Example Session
+## Usage
 
 ```
 irb> ai "find the 5 most recent orders over $100"
@@ -51,184 +43,178 @@ irb> ai "find the 5 most recent orders over $100"
      12 tables: users, orders, line_items, products...
   -> describe_table("orders")
      8 columns
-  -> describe_model("Order")
-     4 associations, 2 validations
-
-You can query recent high-value orders like this:
 
   Order.where("total > ?", 100).order(created_at: :desc).limit(5)
 
-[tokens in: 1,240 | out: 85 | total: 1,325]
 Execute? [y/N/edit] y
 => [#<Order id: 4821, ...>, ...]
 ```
 
-### Interactive Mode
+The AI calls tools behind the scenes to learn your app — schema, models, associations, source code — so it writes accurate queries without you providing any context.
+
+### Commands
+
+| Command | What it does |
+|---------|-------------|
+| `ai "query"` | One-shot: ask, review code, confirm |
+| `ai! "query"` | Interactive: ask and keep chatting |
+| `ai? "query"` | Explain only, never executes |
+
+### Multi-Step Plans
+
+For complex tasks, the AI builds a plan and executes it step by step:
 
 ```
-irb> ai!
-ConsoleAgent interactive mode. Type 'exit' or 'quit' to leave.
-ai> show me all tables
+ai> get the most recent salesforce token and count events via the API
   Thinking...
-  -> list_tables
-     12 tables: users, orders, line_items, products...
+  -> describe_table("oauth2_tokens")
+     28 columns
+  -> read_file("lib/salesforce_api.rb")
+     202 lines
+
+  Plan (2 steps):
+  1. Find the most recent active Salesforce OAuth2 token
+     token = Oauth2Token.where(provider: "salesforce", active: true)
+                        .order(updated_at: :desc).first
+  2. Query event count via SOQL
+     api = SalesforceApi.new(step1)
+     api.query("SELECT COUNT(Id) FROM Event")
+
+  Accept plan? [y/N/a(uto)] a
+  Step 1/2: Find the most recent active Salesforce OAuth2 token
   ...
-ai> now count orders by status
+=> #<Oauth2Token id: 1, provider: "salesforce", ...>
+
+  Step 2/2: Query event count via SOQL
   ...
-ai> exit
-[session totals — in: 3,200 | out: 410 | total: 3,610]
-Left ConsoleAgent interactive mode.
+=> [{"expr0"=>42}]
 ```
 
-### Configuration Status
+Each step's return value is available to later steps as `step1`, `step2`, etc.
 
-```
-irb> ai_status
-[ConsoleAgent v0.1.0]
-  Provider:       anthropic
-  Model:          claude-opus-4-6
-  API key:        sk-ant-...a3b4
-  Context mode:   smart
-  Max tokens:     4096
-  Temperature:    0.2
-  Timeout:        30s
-  Max tool rounds:10
-  Auto-execute:   false
-  Debug:          false
-```
+Plan prompt options:
+- **y** — accept, then confirm each step one at a time
+- **a** — accept and auto-run all steps (stays in manual mode for future queries)
+- **N** — decline; you're asked what to change and the AI revises
 
-## Configuration
+### Memories
 
-The install generator creates `config/initializers/console_agent.rb`:
+The AI remembers what it learns about your codebase across sessions:
 
-```ruby
-ConsoleAgent.configure do |config|
-  # LLM provider: :anthropic or :openai
-  config.provider = :anthropic
+```
+ai> how does sharding work?
+  -> read_file("config/initializers/sharding.rb")
+  -> save_memory("Sharding architecture")
+     Memory saved
 
-  # API key (or set ANTHROPIC_API_KEY / OPENAI_API_KEY env var)
-  # config.api_key = 'sk-...'
+  This app uses database-per-shard. User.count returns the current shard only.
+```
 
-  # Model override (defaults: claude-opus-4-6 for Anthropic, gpt-5.3-codex for OpenAI)
-  # config.model = 'claude-opus-4-6'
+Next time, it already knows — no re-reading files, fewer tokens.
 
-  # Context mode:
-  #   :smart - (default) LLM uses tools to fetch schema/model/code on demand
-  #   :full  - sends all schema, models, and routes every time
-  config.context_mode = :smart
+### Interactive Mode
 
-  # Max tokens for LLM response
-  config.max_tokens = 4096
+```
+irb> ai!
+ConsoleAgent interactive mode. Type 'exit' to leave.
+  Auto-execute: OFF (Shift-Tab or /auto to toggle)
 
-  # Temperature (0.0 - 1.0)
-  config.temperature = 0.2
+ai> show me all tables
+  ...
+ai> count orders by status
+  ...
+ai> /auto
+  Auto-execute: ON
+ai> delete cancelled orders older than 90 days
+  ...
+ai> exit
+```
 
-  # Auto-execute generated code without confirmation
-  config.auto_execute = false
+Toggle `/auto` to skip confirmation prompts. `/debug` shows raw API traffic. `/usage` shows token stats.
 
-  # Max tool-use rounds per query in :smart mode
-  config.max_tool_rounds = 10
+### Sessions
 
-  # HTTP timeout in seconds
-  config.timeout = 30
+Sessions are saved automatically when session logging is enabled. You can name, list, and resume them.
 
-  # Debug mode: prints full API requests/responses and tool calls
-  # config.debug = true
-end
 ```
-
-You can also change settings at runtime in the console:
-
-```ruby
-ConsoleAgent.configure { |c| c.debug = true }
-ConsoleAgent.configure { |c| c.provider = :openai }
-ENV['OPENAI_API_KEY'] = 'sk-...'
+ai> /name sf_user_123_calendar
+  Session named: sf_user_123_calendar
+ai> exit
+Session #42 saved.
+  Resume with: ai_resume "sf_user_123_calendar"
+Left ConsoleAgent interactive mode.
 ```
 
-## Context Modes
+List recent sessions:
 
-### Smart Mode (default)
+```
+irb> ai_sessions
+[Sessions — showing 3]
 
-The LLM gets a minimal system prompt and uses tools to look up what it needs:
+  #42 sf_user_123_calendar find user 123 with calendar issues
+     [interactive] 5m ago 2340 tokens
 
-- **list_tables** / **describe_table** — database schema on demand
-- **list_models** / **describe_model** — ActiveRecord associations, validations
-- **list_files** / **read_file** / **search_code** — browse app source code
+  #41 count all active users
+     [one_shot] 1h ago 850 tokens
 
-This keeps token usage low (~1-3K per query) even for large apps with hundreds of tables.
+  #40 debug_payments explain payment flow
+     [interactive] 2h ago 4100 tokens
 
-### Full Mode
+Use ai_resume(id_or_name) to resume a session.
+```
 
-Sends the entire database schema, all model details, and a route summary in every request. Simple but expensive for large apps (~50K+ tokens). Useful if you want everything available without tool-call round trips.
+Resume a session by name or ID — previous output is replayed, then you continue where you left off:
 
-```ruby
-ConsoleAgent.configure { |c| c.context_mode = :full }
 ```
+irb> ai_resume "sf_user_123_calendar"
+--- Replaying previous session output ---
+ai> find user 123 with calendar issues
+  ...previous output...
+--- End of previous output ---
 
-## Tools Available in Smart Mode
+ConsoleAgent interactive mode (sf_user_123_calendar). Type 'exit' to leave.
+ai> now check their calendar sync status
+  ...
+```
 
-| Tool | Description |
-|------|-------------|
-| `list_tables` | All database table names |
-| `describe_table` | Columns, types, and indexes for one table |
-| `list_models` | All model names with association names |
-| `describe_model` | Associations, validations, scopes for one model |
-| `list_files` | Ruby files in a directory |
-| `read_file` | Read a source file (capped at 200 lines) |
-| `search_code` | Grep for a pattern across Ruby files |
+Name or rename a session after the fact:
 
-The LLM decides which tools to call based on your question. You can see the tool calls happening in real time.
+```
+irb> ai_name 41, "active_user_count"
+Session #41 named: active_user_count
+```
 
-## Providers
+Filter sessions by search term:
 
-### Anthropic (default)
+```
+irb> ai_sessions 20, search: "salesforce"
+```
 
-Uses the Claude Messages API. Set `ANTHROPIC_API_KEY` or `config.api_key`.
+If you have an existing `console_agent_sessions` table, run `ConsoleAgent.migrate!` to add the `name` column.
 
-### OpenAI
+## Configuration
 
-Uses the Chat Completions API. Set `OPENAI_API_KEY` or `config.api_key`.
+All settings live in `config/initializers/console_agent.rb` and can be changed at runtime:
 
 ```ruby
 ConsoleAgent.configure do |config|
-  config.provider = :openai
-  config.model = 'gpt-5.3-codex'  # optional, this is the default
+  config.provider = :anthropic       # or :openai
+  config.auto_execute = false         # true to skip confirmations
+  config.max_tokens = 4096             # max tokens per LLM response
+  config.max_tool_rounds = 10         # max tool calls per query
+  config.session_logging = true       # log sessions to DB (run ConsoleAgent.setup!)
 end
 ```
 
-## Docker Setup
-
-If your Rails app runs in Docker, mount the gem source as a volume.
-
-In `docker-compose.yml`:
-
-```yaml
-volumes:
-  - /path/to/console_agent:/console_agent
-```
-
-In `Gemfile`:
+For the admin UI, mount the engine:
 
 ```ruby
-gem 'console_agent', path: '/console_agent', group: :development
+mount ConsoleAgent::Engine => '/console_agent'
 ```
 
-For Docker builds (where the gem source isn't available yet), add a stub to your Dockerfile before `bundle install`:
-
-```dockerfile
-RUN mkdir -p /console_agent/lib/console_agent && \
-    echo "module ConsoleAgent; VERSION = '0.1.0'; end" > /console_agent/lib/console_agent/version.rb && \
-    echo "require 'console_agent/version'" > /console_agent/lib/console_agent.rb && \
-    printf "require_relative 'lib/console_agent/version'\nGem::Specification.new do |s|\n  s.name = 'console_agent'\n  s.version = ConsoleAgent::VERSION\n  s.summary = 'stub'\n  s.authors = ['x']\n  s.files = ['lib/console_agent.rb']\n  s.add_dependency 'rails', '>= 5.0'\n  s.add_dependency 'faraday', '>= 1.0'\nend\n" > /console_agent/console_agent.gemspec
-```
-
-The volume mount overwrites the stub at runtime with the real source.
-
 ## Requirements
 
-- Ruby >= 2.5
-- Rails >= 5.0
-- Faraday >= 1.0
+- Ruby >= 2.5, Rails >= 5.0, Faraday >= 1.0
 
 ## License
 

data/app/controllers/console_agent/application_controller.rb

@@ -0,0 +1,21 @@
+module ConsoleAgent
+  class ApplicationController < ActionController::Base
+    protect_from_forgery with: :exception
+
+    before_action :authenticate!
+
+    private
+
+    def authenticate!
+      username = ConsoleAgent.configuration.admin_username
+      password = ConsoleAgent.configuration.admin_password
+
+      return unless username && password
+
+      authenticate_or_request_with_http_basic('ConsoleAgent Admin') do |u, p|
+        ActiveSupport::SecurityUtils.secure_compare(u, username) &
+          ActiveSupport::SecurityUtils.secure_compare(p, password)
+      end
+    end
+  end
+end

data/app/controllers/console_agent/sessions_controller.rb

@@ -0,0 +1,16 @@
+module ConsoleAgent
+  class SessionsController < ApplicationController
+    PER_PAGE = 50
+
+    def index
+      @page = [params[:page].to_i, 1].max
+      @total = Session.count
+      @total_pages = (@total / PER_PAGE.to_f).ceil
+      @sessions = Session.recent.offset((@page - 1) * PER_PAGE).limit(PER_PAGE)
+    end
+
+    def show
+      @session = Session.find(params[:id])
+    end
+  end
+end

data/app/helpers/console_agent/sessions_helper.rb

@@ -0,0 +1,42 @@
+module ConsoleAgent
+  module SessionsHelper
+    # Convert ANSI escape codes to HTML spans for terminal-style rendering
+    def ansi_to_html(text)
+      return '' if text.nil? || text.empty?
+
+      color_map = {
+        '30' => '#000', '31' => '#e74c3c', '32' => '#2ecc71', '33' => '#f39c12',
+        '34' => '#3498db', '35' => '#9b59b6', '36' => '#1abc9c', '37' => '#ecf0f1',
+        '90' => '#888', '91' => '#ff6b6b', '92' => '#69db7c', '93' => '#ffd43b',
+        '94' => '#74c0fc', '95' => '#da77f2', '96' => '#63e6be', '97' => '#fff'
+      }
+
+      escaped = h(text).to_str
+
+      # Process ANSI codes: colors, bold, dim, reset
+      escaped.gsub!(/\e\[([0-9;]+)m/) do
+        codes = $1.split(';')
+        if codes.include?('0') || $1 == '0'
+          '</span>'
+        else
+          styles = []
+          codes.each do |code|
+            case code
+            when '1' then styles << 'font-weight:bold'
+            when '2' then styles << 'opacity:0.6'
+            when '4' then styles << 'text-decoration:underline'
+            else
+              styles << "color:#{color_map[code]}" if color_map[code]
+            end
+          end
+          styles.empty? ? '' : "<span style=\"#{styles.join(';')}\">"
+        end
+      end
+
+      # Clean up any remaining escape sequences
+      escaped.gsub!(/\e\[[0-9;]*[A-Za-z]/, '')
+
+      escaped.html_safe
+    end
+  end
+end

data/app/models/console_agent/session.rb

@@ -0,0 +1,23 @@
+module ConsoleAgent
+  class Session < ActiveRecord::Base
+    self.table_name = 'console_agent_sessions'
+
+    validates :query, presence: true
+    validates :conversation, presence: true
+    validates :mode, presence: true, inclusion: { in: %w[one_shot interactive explain] }
+
+    scope :recent, -> { order(created_at: :desc) }
+    scope :named, ->(name) { where(name: name) }
+    scope :search, ->(q) { where("name LIKE ? OR query LIKE ?", "%#{q}%", "%#{q}%") }
+
+    def self.connection
+      klass = ConsoleAgent.configuration.connection_class
+      if klass
+        klass = Object.const_get(klass) if klass.is_a?(String)
+        klass.connection
+      else
+        super
+      end
+    end
+  end
+end

data/app/views/console_agent/sessions/index.html.erb

@@ -0,0 +1,57 @@
+<div style="display: flex; justify-content: space-between; align-items: center; margin-bottom: 16px;">
+  <h2 style="font-size: 20px;">Sessions</h2>
+  <span class="text-muted" style="font-size: 14px;"><%= @total %> total</span>
+</div>
+
+<% if @sessions.empty? %>
+  <div class="meta-card">
+    <p class="text-muted">No sessions recorded yet.</p>
+  </div>
+<% else %>
+  <table>
+    <thead>
+      <tr>
+        <th>Time</th>
+        <th>User</th>
+        <th>Name</th>
+        <th>Query</th>
+        <th>Mode</th>
+        <th>Tokens</th>
+        <th>Executed?</th>
+        <th>Duration</th>
+      </tr>
+    </thead>
+    <tbody>
+      <% @sessions.each do |session| %>
+        <tr>
+          <td class="mono"><%= session.created_at.strftime('%Y-%m-%d %H:%M') %></td>
+          <td><%= session.user_name %></td>
+          <td><%= session.name.present? ? session.name : '-' %></td>
+          <td><a href="<%= console_agent.session_path(session) %>"><%= truncate(session.query, length: 80) %></a></td>
+          <td><span class="badge badge-<%= session.mode %>"><%= session.mode %></span></td>
+          <td class="mono"><%= session.input_tokens + session.output_tokens %></td>
+          <td><%= session.executed? ? '<span class="check">Yes</span>'.html_safe : '<span class="cross">No</span>'.html_safe %></td>
+          <td class="mono"><%= session.duration_ms ? "#{session.duration_ms}ms" : '-' %></td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+
+  <% if @total_pages > 1 %>
+    <div class="pagination">
+      <% if @page > 1 %>
+        <a href="<%= console_agent.sessions_path(page: @page - 1) %>">&larr; Newer</a>
+      <% else %>
+        <span class="disabled">&larr; Newer</span>
+      <% end %>
+
+      <span class="page-info">Page <%= @page %> of <%= @total_pages %></span>
+
+      <% if @page < @total_pages %>
+        <a href="<%= console_agent.sessions_path(page: @page + 1) %>">Older &rarr;</a>
+      <% else %>
+        <span class="disabled">Older &rarr;</span>
+      <% end %>
+    </div>
+  <% end %>
+<% end %>

data/app/views/console_agent/sessions/show.html.erb

@@ -0,0 +1,56 @@
+<a href="<%= console_agent.sessions_path %>" class="back-link">&larr; Back to sessions</a>
+
+<div class="meta-card">
+  <div class="meta-grid">
+    <div class="meta-item">
+      <label>Query</label>
+      <span><%= @session.query %></span>
+    </div>
+    <% if @session.name.present? %>
+      <div class="meta-item">
+        <label>Name</label>
+        <span><%= @session.name %></span>
+      </div>
+    <% end %>
+    <div class="meta-item">
+      <label>Mode</label>
+      <span class="badge badge-<%= @session.mode %>"><%= @session.mode %></span>
+    </div>
+    <div class="meta-item">
+      <label>User</label>
+      <span><%= @session.user_name || '-' %></span>
+    </div>
+    <div class="meta-item">
+      <label>Provider / Model</label>
+      <span><%= @session.provider %> / <%= @session.model %></span>
+    </div>
+    <div class="meta-item">
+      <label>Tokens (in / out)</label>
+      <span class="mono"><%= @session.input_tokens %> / <%= @session.output_tokens %></span>
+    </div>
+    <div class="meta-item">
+      <label>Duration</label>
+      <span class="mono"><%= @session.duration_ms ? "#{@session.duration_ms}ms" : '-' %></span>
+    </div>
+    <div class="meta-item">
+      <label>Executed?</label>
+      <span><%= @session.executed? ? '<span class="check">Yes</span>'.html_safe : '<span class="cross">No</span>'.html_safe %></span>
+    </div>
+    <div class="meta-item">
+      <label>Time</label>
+      <span><%= @session.created_at.strftime('%Y-%m-%d %H:%M:%S') %></span>
+    </div>
+  </div>
+</div>
+
+<h3 style="font-size: 16px; margin-bottom: 12px;">Console Output</h3>
+
+<% if @session.console_output.present? %>
+  <div class="terminal">
+    <pre><%= ansi_to_html(@session.console_output) %></pre>
+  </div>
+<% else %>
+  <div class="meta-card">
+    <p class="text-muted">No console output recorded for this session.</p>
+  </div>
+<% end %>