ruby_coded 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a1980b8f52a5fefcd383aec24380904430c10654b4cffe7bef6288b1b55e1eed
-  data.tar.gz: 1e54670c24db8f43ce9a0e4391889adf3d2d1c75f0923d43ff3260bc210e2e96
+  metadata.gz: 458d56c13426096bb1d553aad86f7d2502a94022cc53de44ca7c74ab48cf2b5a
+  data.tar.gz: 128c5c97ccf42e93a7671ad5641d85c3f0c80f425c74506f0f22f7a4d4e95652
 SHA512:
-  metadata.gz: c4d75ef0c6c7d0b3d1da17287b08bbdec2d9ee29bcc12c8551409ae2dbf2276562a10fc96294a9685b55a41f36d4711e448a640e97bb2711a9da9e0b1231e5ad
-  data.tar.gz: 75d2f43c84b9c8d027d17ac6d61b2f250fef6ce2dca88463b3ab580f74927bb16933b5a6f96eb7fed6b26e5138c621e9df8b56435f364dcbe3173c72f3a10114
+  metadata.gz: a244f39012eb45e2396f61a94fb2b14f23ffd1269c4b235a1ea7ce456763cd674f13e51c4cc3584f95ab4d15517ce63aaff1c113848b2ff467aae70606770726
+  data.tar.gz: b1ba816f5deb3e7051764602bb2bb3afcac031af219f6523eb1d54f021d77fc97844068952c914a2d7f1bd441f62968141678ec09b169bf6d855cbed3f1c0848

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-04-24
+
+### Added
+
+- **Pro-only Codex model handling**: `gpt-5.3-codex-spark` and `gpt-5.2-codex` are tagged as `pro_only` in the Codex model catalog and render with a `(Pro only)` marker in the `/model` selector. Plus/free JWT plan claims now hide Pro-only models from the selector, while unknown plans keep the previous behavior to avoid breaking Pro users.
+- **Automatic Codex model fallback**: When the Codex backend rejects a model with `not supported when using Codex with a ChatGPT account`, the request is transparently retried against `gpt-5.4` and the user is informed via a system message.
+- **Provider metadata in `/model`**: `CodexModel` now exposes provider metadata so the selector shows `(openai)` instead of `(unknown)`.
+- **Unified command catalog**: New `RubyCoded::Commands` module with a central `Catalog`, `CommandDefinition`, and provider abstraction (`CoreProvider`, `PluginProvider`, `MarkdownProvider`) consolidating all slash commands in a single source of truth, replacing the hand-rolled `help.txt` and ad-hoc registrations.
+- **Markdown custom commands**: Users can now drop `*.md` files under `~/.ruby_coded/commands/` (or the project-local `.ruby_coded/commands/`) to define reusable slash commands with front-matter metadata, loaded via the new `MarkdownLoader` / `MarkdownProvider`.
+- **Context window tracking**: New `State::ContextWindow` module plus status bar integration that shows live context usage per model, driven by per-turn token tracking.
+
+### Changed
+
+- **Status bar polish**: The status bar now renders context window usage alongside the model/auth indicators and hides noisy fields when data is unavailable.
+- **Command handler refactor**: `CommandHandler` is now powered by the unified catalog (core + plugin + markdown providers) and delegates custom command execution to the new `CustomCommands` mixin.
+
+### Fixed
+
+- **Context window indicator for ChatGPT Plus/Pro users**: `CodexBridge` now parses the `response.completed` SSE event and feeds `input`/`output`/`reasoning`/`cached` token usage into `State`, mirroring the API path. `session_context_tokens_used` reflects the last turn's live prompt size via the new `State#last_turn_context_tokens` helper, eliminating the double-counting that happened because both bridges re-send the full history on each request.
+
 ## [0.2.2] - 2026-04-17
 
 ### Fixed

data/README.md

@@ -28,7 +28,7 @@ An AI-powered terminal coding assistant built in Ruby. Chat with LLMs, let an ag
 - **Tool confirmation** — Write and dangerous operations require explicit approval; safe operations (read, list) run automatically
 - **Token & cost tracking** — Live status bar showing token usage, estimated session cost, and auth mode indicator
 - **Plugin system** — Extend the chat with custom state, input handlers, renderer overlays, and commands
-- **Slash commands** — `/agent`, `/plan`, `/model`, `/login`, `/history`, `/tokens`, `/help`, and more
+- **Slash commands** — `/agent`, `/plan`, `/model`, `/login`, `/history`, `/tokens`, `/commands reload`, `/commands list`, `/help`, and more
 
 ## Requirements
 
@@ -62,6 +62,8 @@ On first launch you'll be asked to authenticate with a provider. After that, you
 | `/plan save` | Save the current plan to a file |
 | `/model` | Switch to a different model |
 | `/login` | Authenticate with a provider (OpenAI, Anthropic) |
+| `/commands reload` | Reload custom markdown commands from the current project |
+| `/commands list` | List currently loaded custom markdown commands |
 | `/tokens` | Show detailed token usage breakdown |
 | `/history` | Show conversation history |
 | `/clear` | Clear the conversation |
@@ -87,6 +89,86 @@ Safe tools run without asking. Confirm and dangerous tools show the operation de
 
 Plan mode restricts the model to read-only tools and a planning-oriented system prompt. The model will analyze your project and propose a structured plan. If the model needs clarification, it presents interactive options you can select or answer with custom text.
 
+### Custom commands
+
+You can define your own project-specific slash commands using Markdown files inside:
+
+```bash
+.ruby_coded/commands/
+```
+
+Each `.md` file represents one custom command. RubyCoded loads these commands into:
+
+- the slash-command autocomplete list
+- `/help`
+- command execution
+
+#### File format
+
+Use YAML frontmatter followed by the command body:
+
+```md
+---
+command: /review-auth
+description: Review auth implementation
+usage: /review-auth [file]
+---
+
+Review the authentication implementation and suggest improvements.
+Focus on risks, bugs, and refactoring opportunities.
+```
+
+#### Required fields
+
+- `command` — command name, must start with `/`
+- `description` — short description shown in autocomplete and help
+
+#### Optional fields
+
+- `usage` — custom usage text shown in `/help`
+
+#### How it works
+
+The Markdown body is used as the prompt template for the command. For example:
+
+```bash
+/review-auth lib/ruby_coded/chat/command_handler.rb
+```
+
+RubyCoded will send the command body to the model and append the extra user input as additional context.
+
+#### Managing commands
+
+Custom commands are loaded from the current project. After adding, editing, or deleting command files, you can manage them without restarting the app.
+
+Reload command definitions:
+
+```bash
+/commands reload
+```
+
+The reload command reports:
+
+- how many custom commands were added
+- how many were removed
+- how many are currently available
+- how many invalid files were ignored
+- how many conflicting commands were ignored
+- invalid file names
+- conflicting command names
+
+List currently loaded custom commands:
+
+```bash
+/commands list
+```
+
+#### Notes
+
+- Core commands take precedence over custom commands.
+- Plugin commands also take precedence over custom Markdown commands.
+- Invalid Markdown command files are ignored during reload.
+
 ## Keyboard shortcuts
 
 | Key | Action |
@@ -116,10 +198,9 @@ bundle exec exe/ruby_coded
 
 ## What's next
 
-- Find a way to update the autocomplete plugin when a new command is added
 - Display context window size (depending on the model)
 - UI element to indicate the AI is performing a task
-- Add the possibility to create custom commands
+- Improve custom commands further (validation, conflict reporting, management UX)
 - Skills implementation
 - Implement Google Auth for Gemini
 - Local LLM support

data/lib/ruby_coded/auth/jwt_decoder.rb

@@ -24,6 +24,20 @@ module RubyCoded
         payload = decode(token)
         payload&.dig(JWT_CLAIM_PATH, "chatgpt_account_id")
       end
+
+      PLAN_CLAIM_KEYS = %w[chatgpt_plan_type planType plan_type].freeze
+
+      def self.extract_plan_type(token)
+        payload = decode(token)
+        return nil unless payload
+
+        auth_claims = payload[JWT_CLAIM_PATH].is_a?(Hash) ? payload[JWT_CLAIM_PATH] : {}
+        PLAN_CLAIM_KEYS.each do |key|
+          value = auth_claims[key] || payload[key]
+          return value.to_s.downcase if value
+        end
+        nil
+      end
     end
   end
 end

data/lib/ruby_coded/chat/app.rb

@@ -13,6 +13,7 @@ require_relative "command_handler"
 require_relative "llm_bridge"
 require_relative "codex_bridge"
 require_relative "codex_models"
+require_relative "../commands/catalog"
 require_relative "../auth/credentials_store"
 require_relative "../auth/jwt_decoder"
 require_relative "../auth/pkce"
@@ -40,7 +41,12 @@ module RubyCoded
       end
 
       def build_components!
-        @state = State.new(model: @model)
+        @command_catalog = RubyCoded::Commands::Catalog.new(
+          project_root: Dir.pwd,
+          plugin_registry: RubyCoded.plugin_registry
+        )
+
+        @state = State.new(model: @model, command_catalog: @command_catalog)
         @credentials_store = Auth::CredentialsStore.new(user_config: @user_config)
         @llm_bridge = create_bridge
         @input_handler = InputHandler.new(@state)
@@ -96,8 +102,14 @@ module RubyCoded
       end
 
       def build_command_handler
-        CommandHandler.new(@state, llm_bridge: @llm_bridge, user_config: @user_config,
-                                   credentials_store: @credentials_store, auth_manager: @auth_manager)
+        CommandHandler.new(
+          @state,
+          llm_bridge: @llm_bridge,
+          user_config: @user_config,
+          credentials_store: @credentials_store,
+          auth_manager: @auth_manager,
+          command_catalog: @command_catalog
+        )
       end
 
       def announce_model_fallback
@@ -150,6 +162,7 @@ module RubyCoded
       end
 
       def recreate_bridge!
+        @command_catalog.reload!
         agentic = @llm_bridge.agentic_mode
         plan = @llm_bridge.plan_mode
         @llm_bridge = create_bridge
@@ -157,7 +170,6 @@ module RubyCoded
         @llm_bridge.toggle_plan_mode!(plan) if plan
         @command_handler = build_command_handler
       end
-
     end
   end
 end

data/lib/ruby_coded/chat/codex_bridge/error_handling.rb

@@ -4,12 +4,15 @@ module RubyCoded
   module Chat
     class CodexBridge
       # Retry logic and error message formatting for the Codex API client.
+      # rubocop:disable Metrics/ModuleLength
       module ErrorHandling
         AGENT_SWITCH_PATTERN = /
           \b(implement|go[ ]ahead|proceed|execut|ejecutar?|comenz|
           comienz|hazlo|constru[iy]|adelante|dale|do[ ]it|build[ ]it)\b
         /ix
 
+        UNSUPPORTED_MODEL_PATTERN = /not supported when using Codex with a ChatGPT account/i
+
         private
 
         def build_connection
@@ -43,19 +46,56 @@ module RubyCoded
                              "Plan mode disabled — switching to agent mode to implement the plan.")
         end
 
-        def attempt_with_retries(input, retries = 0)
+        def attempt_with_retries(input, retries = 0, fallback_attempted: false)
           perform_codex_request(input)
         rescue Tools::AgentCancelledError, Tools::AgentIterationLimitError, Tools::ToolRejectedError => e
           @state.add_message(:system, e.message)
         rescue CodexAPIError => e
-          @state.fail_last_assistant(e, friendly_message: codex_error_message(e))
+          handle_codex_api_error(e, input, retries, fallback_attempted)
         rescue Faraday::TooManyRequestsError => e
-          retry if (retries = handle_rate_limit_retry(e, retries))
-          @state.fail_last_assistant(e, friendly_message: rate_limit_message(e))
+          handle_rate_limit_error(e, retries, input, fallback_attempted)
         rescue StandardError => e
           @state.fail_last_assistant(e, friendly_message: "Codex API error: #{e.message}")
         end
 
+        def handle_codex_api_error(error, input, retries, fallback_attempted)
+          return fail_codex_request(error) unless should_fallback_to_default_model?(error, fallback_attempted)
+
+          switch_to_default_model!(error)
+          attempt_with_retries(input, retries, fallback_attempted: true)
+        end
+
+        def fail_codex_request(error)
+          @state.fail_last_assistant(error, friendly_message: codex_error_message(error))
+        end
+
+        def handle_rate_limit_error(error, retries, input, fallback_attempted)
+          next_retries = handle_rate_limit_retry(error, retries)
+          return attempt_with_retries(input, next_retries, fallback_attempted: fallback_attempted) if next_retries
+
+          @state.fail_last_assistant(error, friendly_message: rate_limit_message(error))
+        end
+
+        def should_fallback_to_default_model?(error, already_attempted)
+          return false if already_attempted
+          return false unless error.status == 400
+          return false unless error.message.match?(UNSUPPORTED_MODEL_PATTERN)
+
+          @model != DEFAULT_MODEL
+        end
+
+        def switch_to_default_model!(error)
+          previous_model = @model
+          @model = DEFAULT_MODEL
+          @state.model = DEFAULT_MODEL
+          @state.reset_last_assistant_content
+          @state.add_message(
+            :system,
+            "Model '#{previous_model}' requires ChatGPT Pro. " \
+            "Falling back to #{DEFAULT_MODEL} and retrying. Detail: #{error.message}"
+          )
+        end
+
         def handle_rate_limit_retry(error, retries)
           return unless retries < MAX_RATE_LIMIT_RETRIES && !@cancel_requested
 
@@ -69,18 +109,35 @@ module RubyCoded
         end
 
         def codex_error_message(error)
+          return unsupported_model_message(error) if unsupported_model_error?(error)
+
+          status_message(error) || "Codex API error: #{error.message}"
+        end
+
+        def unsupported_model_error?(error)
+          error.status == 400 && error.message.match?(UNSUPPORTED_MODEL_PATTERN)
+        end
+
+        def unsupported_model_message(error)
+          "The selected model requires ChatGPT Pro. " \
+            "Use /model to pick one without the 'Pro only' tag. (#{error.message})"
+        end
+
+        def status_message(error)
           case error.status
-          when 401
-            "Authentication failed. Your OAuth session may have expired. " \
-            "Try /login to re-authenticate. (#{error.message})"
-          when 403
-            "Access denied. Your ChatGPT subscription may not include Codex access. (#{error.message})"
+          when 400 then "Codex API error: #{error.message}"
+          when 401 then authentication_error_message(error)
+          when 403 then "Access denied. Your ChatGPT subscription may not include Codex access. (#{error.message})"
           when 404 then "Codex endpoint not found. The API may have changed. (#{error.message})"
           when 429 then rate_limit_message(error)
-          else "Codex API error: #{error.message}"
           end
         end
 
+        def authentication_error_message(error)
+          "Authentication failed. Your OAuth session may have expired. " \
+            "Try /login to re-authenticate. (#{error.message})"
+        end
+
         def rate_limit_message(error)
           <<~MSG.strip
             ChatGPT usage limit reached. This may be a 5-hour or weekly limit on your Plus/Pro subscription.
@@ -88,6 +145,7 @@ module RubyCoded
           MSG
         end
       end
+      # rubocop:enable Metrics/ModuleLength
     end
   end
 end

data/lib/ruby_coded/chat/codex_bridge/sse_parser.rb

@@ -5,6 +5,7 @@ module RubyCoded
     class CodexBridge
       # Parses Server-Sent Events from the Codex streaming response and
       # dispatches content deltas, tool calls, and completion signals.
+      # rubocop:disable Metrics/ModuleLength
       module SSEParser
         StreamContext = Struct.new(
           :assistant_text, :pending_tool_calls, :buffer, :raw_body, :status, keyword_init: true
@@ -70,6 +71,7 @@ module RubyCoded
           when "response.function_call_arguments.delta" then handle_function_args_delta(event, pending_tool_calls)
           when "response.function_call_arguments.done" then handle_function_call_done(event, pending_tool_calls)
           when "response.output_item.added" then handle_output_item_added(event, pending_tool_calls)
+          when "response.completed" then handle_response_completed(event)
           end
         end
 
@@ -107,6 +109,23 @@ module RubyCoded
           tc[:arguments] = event["arguments"] || tc[:arguments] if tc
         end
 
+        # The Responses API emits a `response.completed` event at the end of the
+        # stream carrying the `usage` block. We mirror what `LLMBridge` does and
+        # feed those counters into `State` so that the status bar and the
+        # context-window indicator work for ChatGPT Plus/Pro users too.
+        def handle_response_completed(event)
+          usage = event.dig("response", "usage") || event["usage"]
+          return unless usage.is_a?(Hash)
+
+          @state.update_last_message_tokens(
+            model: @model,
+            input_tokens: usage["input_tokens"],
+            output_tokens: usage["output_tokens"],
+            thinking_tokens: usage.dig("output_tokens_details", "reasoning_tokens"),
+            cached_tokens: usage.dig("input_tokens_details", "cached_tokens")
+          )
+        end
+
         def finalize_response(assistant_text)
           @conversation_history << { role: "assistant", content: assistant_text } unless assistant_text.empty?
         end
@@ -131,6 +150,7 @@ module RubyCoded
           nil
         end
       end
+      # rubocop:enable Metrics/ModuleLength
     end
   end
 end

data/lib/ruby_coded/chat/codex_models.rb

@@ -6,23 +6,34 @@ module RubyCoded
     # These models are not listed in RubyLLM.models because they use a
     # different API (Responses API via chatgpt.com/backend-api).
     module CodexModels
-      CodexModel = Struct.new(:id, :display_name, :context_window, :max_output, keyword_init: true) do
+      PROVIDER = :openai
+
+      CodexModel = Struct.new(:id, :display_name, :context_window, :max_output, :pro_only,
+                              keyword_init: true) do
         def to_s
           id
         end
+
+        def provider
+          PROVIDER
+        end
+
+        def pro_only?
+          pro_only == true
+        end
       end
 
       MODELS = [
         CodexModel.new(id: "gpt-5.4", display_name: "GPT 5.4 (Recommended)",
-                       context_window: 272_000, max_output: 128_000),
+                       context_window: 272_000, max_output: 128_000, pro_only: false),
         CodexModel.new(id: "gpt-5.4-mini", display_name: "GPT 5.4 Mini",
-                       context_window: 272_000, max_output: 128_000),
-        CodexModel.new(id: "gpt-5.3-codex-spark", display_name: "GPT 5.3 Codex Spark (Pro only)",
-                       context_window: 272_000, max_output: 128_000),
+                       context_window: 272_000, max_output: 128_000, pro_only: false),
+        CodexModel.new(id: "gpt-5.3-codex-spark", display_name: "GPT 5.3 Codex Spark",
+                       context_window: 272_000, max_output: 128_000, pro_only: true),
         CodexModel.new(id: "gpt-5.2-codex", display_name: "GPT 5.2 Codex",
-                       context_window: 272_000, max_output: 128_000),
+                       context_window: 272_000, max_output: 128_000, pro_only: true),
         CodexModel.new(id: "gpt-5.2", display_name: "GPT 5.2",
-                       context_window: 272_000, max_output: 128_000)
+                       context_window: 272_000, max_output: 128_000, pro_only: false)
       ].freeze
 
       def self.all
@@ -36,6 +47,24 @@ module RubyCoded
       def self.codex_model?(id)
         MODELS.any? { |m| m.id == id }
       end
+
+      def self.pro_only?(id)
+        model = find(id)
+        model ? model.pro_only? : false
+      end
+
+      PRO_TIER_PLANS = %w[pro team enterprise business edu].freeze
+
+      def self.available_for_plan(plan)
+        normalized = plan.to_s.downcase
+        return MODELS if normalized.empty? || PRO_TIER_PLANS.any? { |p| normalized.include?(p) }
+
+        if normalized.include?("plus") || normalized.include?("free")
+          MODELS.reject(&:pro_only?)
+        else
+          MODELS
+        end
+      end
     end
   end
 end

data/lib/ruby_coded/chat/command_handler/custom_commands.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module RubyCoded
+  module Chat
+    class CommandHandler
+      # Slash commands for managing custom markdown commands.
+      module CustomCommands
+        private
+
+        def cmd_commands(rest)
+          case rest&.strip&.downcase
+          when "reload"
+            reload_commands
+          when "list"
+            list_commands
+          else
+            @state.add_message(:system, "Usage: /commands [reload|list]")
+          end
+        end
+
+        def reload_commands
+          return missing_command_catalog unless @command_catalog
+
+          report = @command_catalog.reload!
+          @commands = build_command_map
+          @state.add_message(:system, format_reload_message(report))
+        end
+
+        def list_commands
+          return missing_command_catalog unless @command_catalog
+
+          commands = @command_catalog.definitions_for_source(:markdown)
+          return show_empty_custom_commands if commands.empty?
+
+          @state.add_message(:system, formatted_custom_commands(commands))
+        end
+
+        def missing_command_catalog
+          @state.add_message(:system, "Command catalog is not available.")
+        end
+
+        def show_empty_custom_commands
+          @state.add_message(
+            :system,
+            "No custom commands loaded. Add markdown files under .ruby_coded/commands " \
+            "and run /commands reload."
+          )
+        end
+
+        def formatted_custom_commands(commands)
+          lines = ["Custom commands:"]
+          commands.sort_by { |definition| definition.name.downcase }.each do |definition|
+            lines << formatted_command_line(definition)
+          end
+          lines.join("\n")
+        end
+
+        def format_reload_message(report)
+          message = reload_summary(report)
+          details = reload_details(report)
+          return message if details.empty?
+
+          "#{message}\n#{details.join("\n")}"
+        end
+
+        def reload_summary(report)
+          "Commands reloaded. " \
+            "Added: #{report[:added]}, removed: #{report[:removed]}, " \
+            "total custom commands: #{report[:total]}, " \
+            "invalid files ignored: #{report[:invalid]}, " \
+            "conflicts ignored: #{report[:conflicts]}."
+        end
+
+        def reload_details(report)
+          details = []
+          invalid_files = Array(report[:invalid_files])
+          conflict_commands = Array(report[:conflict_commands])
+
+          details << "Invalid files: #{invalid_files.join(", ")}" if invalid_files.any?
+          details << "Conflicting commands: #{conflict_commands.join(", ")}" if conflict_commands.any?
+          details
+        end
+
+        def formatted_command_line(definition)
+          usage = definition.usage || definition.name
+          "  #{usage.ljust(28)} #{definition.description}"
+        end
+      end
+    end
+  end
+end

data/lib/ruby_coded/chat/command_handler/model_commands.rb

@@ -2,6 +2,7 @@
 
 require_relative "../model_filter"
 require_relative "../codex_models"
+require_relative "../../auth/jwt_decoder"
 
 module RubyCoded
   module Chat
@@ -74,12 +75,18 @@ module RubyCoded
 
         def models_for_provider(name, creds)
           if name == :openai && creds["auth_method"] == "oauth"
-            CodexModels.all
+            codex_models_for_plan(creds)
           else
             RubyLLM.models.by_provider(name).chat_models.to_a
           end
         end
 
+        def codex_models_for_plan(creds)
+          token = creds["access_token"]
+          plan = token ? Auth::JWTDecoder.extract_plan_type(token) : nil
+          CodexModels.available_for_plan(plan)
+        end
+
         def fetch_chat_models
           RubyLLM.models.chat_models.to_a
         rescue StandardError