console_agent 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53925e32cd4919e550bfdc081ede866613ce3ea18a585aca6cb81d1687ce3901
-  data.tar.gz: ae601be1b81ff2fcb89addda1c008c0646118f2af21c9009a1792556ffd9b4ed
+  metadata.gz: 661ab1a997f36d2b10ea9649aa41367aca039c859c3e2afa01c3cbf8b8dd9345
+  data.tar.gz: 5cfe513d78a1785b7199fb0ebbbc70e825092e49e4051caf390e3ccb7ccf23c4
 SHA512:
-  metadata.gz: 54ec67e116e4a05de7a5d915f93dc7babf2d64d2b008bc507718dce92d58ad032beeaa1d7710d8190943454f937f91780ff5614e44f5ef173ab5feff6dddb339
-  data.tar.gz: f12af224368e44b149d740f8d0b2dee4a38ce86564ee9337c5a8ed569a83bb387d3edcf2ae76142d4b510f507c5e6d64d82aab70c16eb94f66d83e3811eb0cd6
+  metadata.gz: 0d7fd63a81886c7abbf4f82db677b6b4bb9151760c378901306e789b3619d7ca31b743f7f4a14a9a28335e775877243b0c4ff8b8bd6cc6acee0c8a02c270eccc
+  data.tar.gz: 3e0308bd89e0421a4a29dbe8c7b7be6afd584a504559a456f830e1c9a268517d131d6dcf00417347f5f3ea80a434bf9211e0515771fc3e43686f0117bf401f9b

data/README.md

@@ -1,60 +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.
 
-It's like Claude Code embedded in your Rails Console.
+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.
 
-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.
-
-## 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 (pick one):
-
-```bash
-# Option A: environment variable
-export ANTHROPIC_API_KEY=sk-ant-...
-
-# Option B: in the initializer
-# config.api_key = 'sk-ant-...'
-```
-
-Open a console and go:
+Set your API key in the generated initializer or as an env var (`ANTHROPIC_API_KEY`):
 
 ```ruby
-rails console
-ai "show me all users who signed up this week"
+# config/initializers/console_agent.rb
+ConsoleAgent.configure do |config|
+  config.api_key = 'sk-ant-...'
+end
 ```
 
-You can also set or change your API key at runtime in the console:
+To set up session logging (OPTIONAL), create the table from the console:
 
 ```ruby
-ConsoleAgent.configure { |c| c.api_key = 'sk-ant-...' }
+ConsoleAgent.setup!
+# => ConsoleAgent: created console_agent_sessions table.
 ```
 
-## Console Commands
+To reset the table (e.g. after upgrading), run `ConsoleAgent.teardown!` then `ConsoleAgent.setup!`.
 
-| 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 |
-
-### Example Session
+## Usage
 
 ```
 irb> ai "find the 5 most recent orders over $100"
@@ -63,272 +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.
 
-```
-irb> ai!
-ConsoleAgent interactive mode. Type 'exit' or 'quit' to leave.
-ai> show me all tables
-  Thinking...
-  -> list_tables
-     12 tables: users, orders, line_items, products...
-  ...
-ai> now count orders by status
-  ...
-ai> exit
-[session totals — in: 3,200 | out: 410 | total: 3,610]
-Left ConsoleAgent interactive mode.
-```
+### Commands
 
-### Configuration Status
-
-```
-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
-```
-
-## Configuration
-
-The install generator creates `config/initializers/console_agent.rb`:
-
-```ruby
-ConsoleAgent.configure do |config|
-  # LLM provider: :anthropic or :openai
-  config.provider = :anthropic
-
-  # API key (or set ANTHROPIC_API_KEY / OPENAI_API_KEY env var)
-  # config.api_key = 'sk-...'
-
-  # Model override (defaults: claude-opus-4-6 for Anthropic, gpt-5.3-codex for OpenAI)
-  # config.model = 'claude-opus-4-6'
-
-  # 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
-
-  # Max tokens for LLM response
-  config.max_tokens = 4096
-
-  # Temperature (0.0 - 1.0)
-  config.temperature = 0.2
-
-  # Auto-execute generated code without confirmation
-  config.auto_execute = false
-
-  # Max tool-use rounds per query in :smart mode
-  config.max_tool_rounds = 10
-
-  # HTTP timeout in seconds
-  config.timeout = 30
+| 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 |
 
-  # Debug mode: prints full API requests/responses and tool calls
-  # config.debug = true
-end
-```
+### Multi-Step Plans
 
-All settings can be changed at runtime in the console:
+For complex tasks, the AI builds a plan and executes it step by step:
 
-```ruby
-ConsoleAgent.configure { |c| c.api_key = 'sk-ant-...' }
-ConsoleAgent.configure { |c| c.debug = true }
-ConsoleAgent.configure { |c| c.provider = :openai; c.api_key = 'sk-...' }
 ```
+ai> get the most recent salesforce token and count events via the API
+  Thinking...
+  -> describe_table("oauth2_tokens")
+     28 columns
+  -> read_file("lib/salesforce_api.rb")
+     202 lines
 
-## Context Modes
-
-### Smart Mode (default)
-
-The LLM gets a minimal system prompt and uses tools to look up what it needs:
-
-- **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
-
-This keeps token usage low (~1-3K per query) even for large apps with hundreds of tables.
-
-### Full Mode
+  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")
 
-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.
+  Accept plan? [y/N/a(uto)] a
+  Step 1/2: Find the most recent active Salesforce OAuth2 token
+  ...
+=> #<Oauth2Token id: 1, provider: "salesforce", ...>
 
-```ruby
-ConsoleAgent.configure { |c| c.context_mode = :full }
+  Step 2/2: Query event count via SOQL
+  ...
+=> [{"expr0"=>42}]
 ```
 
-## Tools Available in Smart Mode
-
-| 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 |
-| `ask_user` | Ask the console user a clarifying question |
-| `save_memory` | Persist a learned fact for future sessions |
-| `recall_memories` | Search saved memories |
-| `load_skill` | Load full instructions for a skill |
-
-The LLM decides which tools to call based on your question. You can see the tool calls happening in real time.
+Each step's return value is available to later steps as `step1`, `step2`, etc.
 
-## Memories & Skills
-
-ConsoleAgent can remember what it learns about your codebase across sessions and load reusable skill instructions on demand.
+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
 
 ### Memories
 
-When the AI investigates something complex (like how sharding works in your app), it can save what it learned for next time. Memories are stored in `.console_agent/memories.yml` in your Rails app.
+The AI remembers what it learns about your codebase across sessions:
 
 ```
-ai> how many users are on this shard?
-  Thinking...
-  -> search_code("shard")
-     Found 50 matches
+ai> how does sharding work?
   -> read_file("config/initializers/sharding.rb")
-     202 lines
   -> save_memory("Sharding architecture")
-     Memory saved: "Sharding architecture"
+     Memory saved
 
-Each shard is a separate database. User.count returns the count for the current shard only.
-
-  User.count
-
-[tokens in: 2,340 | out: 120 | total: 2,460]
+  This app uses database-per-shard. User.count returns the current shard only.
 ```
 
-Next session, the AI already knows:
-
-```
-ai> count users on this shard
-  Thinking...
+Next time, it already knows — no re-reading files, fewer tokens.
 
-  User.count
+### Interactive Mode
 
-[tokens in: 580 | out: 45 | total: 625]
 ```
+irb> ai!
+ConsoleAgent interactive mode. Type 'exit' to leave.
+  Auto-execute: OFF (Shift-Tab or /auto to toggle)
 
-The memory file is human-editable YAML:
-
-```yaml
-# .console_agent/memories.yml
-memories:
-  - id: mem_1709123456_42
-    name: Sharding architecture
-    description: "App uses database-per-shard. Each shard is a separate DB. User.count only counts the current shard."
-    tags: [database, sharding]
-    created_at: "2026-02-27T10:30:00Z"
+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
 ```
 
-You can commit this file to your repo so the whole team benefits, or gitignore it for personal use.
+Toggle `/auto` to skip confirmation prompts. `/debug` shows raw API traffic. `/usage` shows token stats.
 
-### Skills
+### Sessions
 
-Skills are reusable instruction files that teach the AI how to handle specific tasks. Store them in `.console_agent/skills/` as markdown files with YAML frontmatter:
+Sessions are saved automatically when session logging is enabled. You can name, list, and resume them.
 
-```markdown
-# .console_agent/skills/sharding.md
----
-name: Sharded database queries
-description: How to query across database shards. Use when user asks about counting records across shards or shard-specific operations.
----
+```
+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.
+```
 
-## Instructions
+List recent sessions:
 
-This app uses Apartment with one database per shard.
-- `User.count` only counts the current shard
-- To count across all shards: `Shard.all.sum { |s| s.switch { User.count } }`
-- Current shard: `Apartment::Tenant.current`
 ```
+irb> ai_sessions
+[Sessions — showing 3]
 
-Only the skill name and description are sent to the AI on every request (~100 tokens per skill). The full instructions are loaded on demand via the `load_skill` tool only when relevant.
-
-### Storage
+  #42 sf_user_123_calendar find user 123 with calendar issues
+     [interactive] 5m ago 2340 tokens
 
-By default, memories and skills are stored on the filesystem at `Rails.root/.console_agent/`. This works for development and for production environments with a persistent filesystem.
+  #41 count all active users
+     [one_shot] 1h ago 850 tokens
 
-For containers or other environments where the filesystem is ephemeral, you have two options:
+  #40 debug_payments explain payment flow
+     [interactive] 2h ago 4100 tokens
 
-**Option A: Commit to your repo.** Create `.console_agent/memories.yml` and `.console_agent/skills/*.md` in your codebase. They'll be baked into your Docker image.
+Use ai_resume(id_or_name) to resume a session.
+```
 
-**Option B: Custom storage adapter.** Implement the storage interface and plug it in:
+Resume a session by name or ID — previous output is replayed, then you continue where you left off:
 
-```ruby
-ConsoleAgent.configure do |config|
-  config.storage_adapter = MyS3Storage.new(bucket: 'my-bucket', prefix: 'console_agent/')
-end
 ```
+irb> ai_resume "sf_user_123_calendar"
+--- Replaying previous session output ---
+ai> find user 123 with calendar issues
+  ...previous output...
+--- End of previous output ---
 
-A storage adapter just needs four methods: `read(key)`, `write(key, content)`, `list(pattern)`, and `exists?(key)`.
+ConsoleAgent interactive mode (sf_user_123_calendar). Type 'exit' to leave.
+ai> now check their calendar sync status
+  ...
+```
 
-To disable memories or skills:
+Name or rename a session after the fact:
 
-```ruby
-ConsoleAgent.configure do |config|
-  config.memories_enabled = false
-  config.skills_enabled = false
-end
+```
+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
 ```
 
-## Local Development
-
-To develop the gem locally against a Rails app, use a path reference in your Gemfile:
-
-```ruby
-gem 'console_agent', path: '/path/to/console_agent'
-```
-
-Switch back to the published gem when you're done:
+For the admin UI, mount the engine:
 
 ```ruby
-gem 'console_agent'
+mount ConsoleAgent::Engine => '/console_agent'
 ```
 
 ## 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 %>