actionmcp 0.83.4 → 0.90.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 07c0477f4e98cef701c55861a54b06530246aa72aa7e4cb573fbf2d523c0ae54
-  data.tar.gz: 9bdff393572212ee32d0430ba2887292f35b0489a0753399a27a5f7a16aa3fac
+  metadata.gz: f4e55c16fbbaf08a18d98c152d72d152a97170ac81e9f6126b24663f7f53ed14
+  data.tar.gz: 11e2f3cd710ee43e7ef868197bed0221d50da3ea513764a05856afb3334db8fb
 SHA512:
-  metadata.gz: d84067880b719178839887ec9aed55236486a1b8ed60859d1885303ac71b83525c3a52ee4c9267cf1b84044f467668b2a05ec06485d31666d0057838ab789b3a
-  data.tar.gz: b4f687ea0485632c75670c64c9d8953cc340fc45ed774993a0ce2c661c30e05e5429047fb30146c6450e66e1b72ea2be6aae8977127e9cdbedb50e5b578186fd
+  metadata.gz: 4eeca2ab09bb4ee053d575d610fd6f1a236ee1038c008fad9f90b9aa0f78c339e21ceaecdf499d13c885e006e89ea224a74fc326e5d9b3cc091434c17733d50f
+  data.tar.gz: e1c15290f9a862dfb3d37cd8d077b9c3312370dd2e6e12f7bf57c661d5de20a682d1ca7c59e6149bdc94d543a2151cfcc576ede94afab07accdd8fb8ce82bb59

data/app/controllers/action_mcp/application_controller.rb

@@ -271,9 +271,9 @@ module ActionMCP
       header_version = request.headers["MCP-Protocol-Version"] || request.headers["mcp-protocol-version"]
       session = mcp_session
 
-      # If header is missing, assume 2025-03-26 for backward compatibility as per spec
+      # If header is missing, assume 2025-06-18 for backward compatibility as per spec
       if header_version.nil?
-        ActionMCP.logger.debug "MCP-Protocol-Version header missing, assuming 2025-03-26 for backward compatibility"
+        ActionMCP.logger.debug "MCP-Protocol-Version header missing, assuming 2025-06-18 for backward compatibility"
         return true
       end
 

data/app/jobs/action_mcp/tool_execution_job.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  # ActiveJob for executing tools asynchronously in task-augmented mode
+  # Part of MCP 2025-11-25 Tasks specification with ActiveJob::Continuable support
+  class ToolExecutionJob < ActiveJob::Base
+    include ActiveJob::Continuable
+
+    queue_as :mcp_tasks
+
+    # Retry configuration for transient failures
+    retry_on StandardError, wait: :polynomially_longer, attempts: 3
+
+    # Ensure tasks reach terminal state on permanent failure
+    discard_on StandardError do |job, error|
+      handle_job_discard(job, error)
+    end
+
+    # @param task_id [String] Task ID
+    # @param tool_name [String] Name of the tool to execute
+    # @param arguments [Hash] Tool arguments
+    # @param meta [Hash] Request metadata
+    def perform(task_id, tool_name, arguments, meta = {})
+      @task = step(:load_task, task_id)
+      return if @task.nil? || @task.terminal?
+
+      @session = step(:validate_session, @task)
+      return unless @session
+
+      @tool = step(:prepare_tool, @session, tool_name, arguments)
+      return unless @tool
+
+      step(:execute_tool) do
+        result = execute_with_reloader(@tool, @session)
+        update_task_result(@task, result)
+      end
+    end
+
+    private
+
+    def load_task(task_id)
+      task = Session::Task.find_by(id: task_id)
+      unless task
+        Rails.logger.error "[ToolExecutionJob] Task not found: #{task_id}"
+        return nil
+      end
+
+      task.record_step!(:job_started)
+      task
+    end
+
+    def validate_session(task)
+      session = task.session
+      unless session
+        task.update(status_message: "Session not found")
+        task.mark_failed!
+        return nil
+      end
+
+      session
+    end
+
+    def prepare_tool(session, tool_name, arguments)
+      tool_class = session.registered_tools.find { |t| t.tool_name == tool_name }
+      unless tool_class
+        @task.update(status_message: "Tool '#{tool_name}' not found")
+        @task.mark_failed!
+        return nil
+      end
+
+      # Create and configure tool instance
+      tool = tool_class.new(arguments)
+      tool.with_context({
+        session: session,
+        request: {
+          params: @task.request_params
+        }
+      })
+
+      tool
+    end
+
+    def execute_with_reloader(tool, session)
+      if Rails.env.development?
+        # Preserve Current attributes across reloader boundary
+        current_user = ActionMCP::Current.user
+        current_gateway = ActionMCP::Current.gateway
+
+        Rails.application.reloader.wrap do
+          ActionMCP::Current.user = current_user
+          ActionMCP::Current.gateway = current_gateway
+          tool.call
+        end
+      else
+        tool.call
+      end
+    end
+
+    def update_task_result(task, result)
+      return if task.terminal? # Guard against double-complete
+
+      if result.is_error
+        task.result_payload = result.to_h
+        task.status_message = result.respond_to?(:error_message) ? result.error_message : "Tool returned error"
+        task.mark_failed!
+      else
+        task.result_payload = result.to_h
+        task.record_step!(:completed)
+        task.complete!
+      end
+    end
+
+    def self.handle_job_discard(job, error)
+      task_id = job.arguments.first
+      task = Session::Task.find_by(id: task_id)
+      return unless task&.persisted?
+      return if task.terminal?
+
+      Rails.logger.error "[ToolExecutionJob] Discarding job for task #{task_id}: #{error.class} - #{error.message}"
+      Rails.logger.error error.backtrace&.first(10)&.join("\n")
+
+      task.update(
+        status_message: "Job failed: #{error.message}",
+        continuation_state: {
+          step: :failed,
+          error: { class: error.class.name, message: error.message },
+          timestamp: Time.current.iso8601
+        }
+      )
+      task.mark_failed!
+    end
+  end
+end

data/app/models/action_mcp/session/task.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require "state_machines-activerecord"
+
+module ActionMCP
+  class Session
+    # Represents a Task in an MCP session as per MCP 2025-11-25 specification.
+    # Tasks provide durable state machines for tracking async request execution.
+    #
+    # State Machine:
+    #   working -> input_required -> working (via resume)
+    #   working -> completed | failed | cancelled
+    #   input_required -> completed | failed | cancelled
+    #
+    class Task < ApplicationRecord
+      self.table_name = "action_mcp_session_tasks"
+
+      attribute :id, :string, default: -> { SecureRandom.uuid_v7 }
+
+      belongs_to :session, class_name: "ActionMCP::Session", inverse_of: :tasks
+
+      # JSON columns are handled natively by Rails 8.1+
+      # No serialize needed for json column types
+
+      # Validations
+      validates :status, presence: true
+      validates :last_updated_at, presence: true
+
+      # Scopes - state_machines >= 0.100.0 auto-generates .with_status(:state) scopes
+      scope :terminal, -> { with_status(:completed, :failed, :cancelled) }
+      scope :non_terminal, -> { with_status(:working, :input_required) }
+      scope :recent, -> { order(created_at: :desc) }
+
+      # State machine definition per MCP spec
+      state_machine :status, initial: :working do
+        # Terminal states
+        state :completed
+        state :failed
+        state :cancelled
+
+        # Non-terminal states
+        state :working
+        state :input_required
+
+        # Transition to input_required when awaiting user/client input
+        event :require_input do
+          transition working: :input_required
+        end
+
+        # Resume from input_required back to working
+        event :resume do
+          transition input_required: :working
+        end
+
+        # Complete the task successfully
+        event :complete do
+          transition %i[working input_required] => :completed
+        end
+
+        # Mark the task as failed due to an error
+        # Note: Using 'mark_failed' instead of 'fail' to avoid conflict with Object#fail
+        event :mark_failed do
+          transition %i[working input_required] => :failed
+        end
+
+        # Cancel the task
+        event :cancel do
+          transition %i[working input_required] => :cancelled
+        end
+
+        # After any transition, update timestamp and broadcast
+        after_transition do |task, transition|
+          task.update_column(:last_updated_at, Time.current)
+          task.broadcast_status_change(transition)
+        end
+      end
+
+      # Callbacks
+      before_validation :set_last_updated_at, on: :create
+
+      # TTL management
+      # @return [Boolean] true if task has exceeded its TTL
+      def expired?
+        return false if ttl.nil?
+
+        # TTL is stored in milliseconds (MCP spec)
+        created_at + (ttl / 1000.0).seconds < Time.current
+      end
+
+      # Check if task is in a terminal state
+      def terminal?
+        status.in?(%w[completed failed cancelled])
+      end
+
+      # Check if task is in a non-terminal state
+      def non_terminal?
+        !terminal?
+      end
+
+      # Convert to task data format per MCP spec
+      # @return [Hash] Task data for JSON-RPC responses
+      def to_task_data
+        data = {
+          id: id,
+          status: status,
+          lastUpdatedAt: last_updated_at.iso8601(3)
+        }
+        data[:statusMessage] = status_message if status_message.present?
+
+        # Add progress if available (ActiveJob::Continuable support)
+        if progress_percent.present? || progress_message.present?
+          data[:progress] = {}.tap do |progress|
+            progress[:percent] = progress_percent if progress_percent.present?
+            progress[:message] = progress_message if progress_message.present?
+          end
+        end
+
+        data
+      end
+
+      # Convert to full task result format
+      # @return [Hash] Complete task with result for tasks/result response
+      def to_task_result
+        {
+          task: to_task_data,
+          result: result_payload
+        }
+      end
+
+      # Broadcast status change notification to the session
+      # @param transition [StateMachines::Transition] The state transition that occurred
+      def broadcast_status_change(transition = nil)
+        return unless session
+
+        handler = ActionMCP::Server::TransportHandler.new(session)
+        handler.send_task_status_notification(self)
+      rescue StandardError => e
+        Rails.logger.warn "Failed to broadcast task status change: #{e.message}"
+      end
+
+      # Continuation State Management (for ActiveJob::Continuable support)
+
+      # Record step execution state for job resumption
+      # @param step_name [Symbol] Name of the step
+      # @param cursor [Integer, String] Optional cursor for resuming iteration
+      # @param data [Hash] Additional step data to persist
+      def record_step!(step_name, cursor: nil, data: {})
+        update!(
+          continuation_state: {
+            step: step_name,
+            cursor: cursor,
+            data: data,
+            timestamp: Time.current.iso8601
+          },
+          last_step_at: Time.current
+        )
+      end
+
+      # Store partial result fragment (for streaming/incremental results)
+      # @param result_fragment [Hash] Partial result to append
+      def store_partial_result!(result_fragment)
+        payload = result_payload || {}
+        payload[:partial] ||= []
+        payload[:partial] << result_fragment
+        update!(result_payload: payload)
+      end
+
+      # Update progress indicators for long-running tasks
+      # @param percent [Integer] Progress percentage (0-100)
+      # @param message [String] Optional progress message
+      def update_progress!(percent:, message: nil)
+        update!(
+          progress_percent: percent.clamp(0, 100),
+          progress_message: message,
+          last_step_at: Time.current
+        )
+      end
+
+      # Transition to input_required state and store pending input prompt
+      # @param prompt [String] The prompt/question for the user
+      # @param context [Hash] Additional context about the input request
+      def await_input!(prompt:, context: {})
+        record_step!(:awaiting_input, data: { prompt: prompt, context: context })
+        require_input!
+      end
+
+      # Resume task from input_required state and re-enqueue job
+      # @return [void]
+      def resume_from_continuation!
+        return unless input_required?
+
+        resume!
+        # Re-enqueue the job to continue execution
+        ActionMCP::ToolExecutionJob.perform_later(id, request_name, request_params, {})
+      end
+
+      private
+
+      def set_last_updated_at
+        self.last_updated_at ||= Time.current
+      end
+    end
+  end
+end

data/app/models/action_mcp/session.rb

@@ -79,6 +79,12 @@ module ActionMCP
              dependent: :delete_all,
              inverse_of: :session
 
+    has_many :tasks,
+             class_name: "ActionMCP::Session::Task",
+             foreign_key: "session_id",
+             dependent: :delete_all,
+             inverse_of: :session
+
     scope :pre_initialize, -> { where(status: "pre_initialize") }
     scope :closed, -> { where(status: "closed") }
     scope :without_messages, -> { includes(:messages).where(action_mcp_session_messages: { id: nil }) }

data/db/migrate/20250715070713_add_consents_to_action_mcp_sess.rb

@@ -2,6 +2,8 @@
 
 class AddConsentsToActionMCPSess < ActiveRecord::Migration[8.0]
   def change
+    return if column_exists?(:action_mcp_sessions, :consents)
+
     add_column :action_mcp_sessions, :consents, :json, default: {}, null: false
   end
 end

data/db/migrate/20251125000001_create_action_mcp_session_tasks.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+class CreateActionMCPSessionTasks < ActiveRecord::Migration[8.0]
+  def change
+    create_table :action_mcp_session_tasks, id: :string do |t|
+      t.references :session, null: false,
+                             foreign_key: { to_table: :action_mcp_sessions,
+                                            on_delete: :cascade,
+                                            on_update: :cascade,
+                                            name: 'fk_action_mcp_session_tasks_session_id' },
+                             type: :string
+      t.string :status, null: false, default: 'working'
+      t.string :status_message
+      t.string :request_method, comment: 'e.g., tools/call, prompts/get'
+      t.string :request_name, comment: 'e.g., tool name, prompt name'
+      t.json :request_params, comment: 'Original request params'
+      t.json :result_payload, comment: 'Final result data'
+      t.integer :ttl, comment: 'Time to live in milliseconds'
+      t.integer :poll_interval, comment: 'Suggested polling interval in milliseconds'
+      t.datetime :last_updated_at, null: false
+
+      t.timestamps
+
+      t.index :status
+      t.index %i[session_id status]
+      t.index :created_at
+    end
+  end
+end

data/db/migrate/20251126000001_add_continuation_state_to_action_mcp_session_tasks.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+class AddContinuationStateToActionMCPSessionTasks < ActiveRecord::Migration[8.1]
+  def change
+    add_column :action_mcp_session_tasks, :continuation_state, :json, default: {}
+    add_column :action_mcp_session_tasks, :progress_percent, :integer
+    add_column :action_mcp_session_tasks, :progress_message, :string
+    add_column :action_mcp_session_tasks, :last_step_at, :datetime
+  end
+end

data/exe/actionmcp_cli

@@ -62,7 +62,7 @@ end
 
 # Function to generate a unique request ID
 def generate_request_id
-  SecureRandom.uuid
+  SecureRandom.uuid_v7
 end
 
 # Function to parse command shortcuts and return a Request object

data/lib/action_mcp/capability.rb

@@ -11,6 +11,7 @@ module ActionMCP
     include Renderable
 
     class_attribute :_capability_name, instance_accessor: false
+    class_attribute :_registered_name, instance_accessor: false
     class_attribute :_description, instance_accessor: false, default: ""
 
     attr_reader :execution_context

data/lib/action_mcp/client/base.rb

@@ -187,7 +187,7 @@ module ActionMCP
         params[:sessionId] = @session_id if @session_id
 
         # Use a unique request ID (not session ID since we don't have one yet)
-        request_id = SecureRandom.uuid
+        request_id = SecureRandom.uuid_v7
         send_jsonrpc_request("initialize", params: params, id: request_id)
       end
 

data/lib/action_mcp/configuration.rb

@@ -48,7 +48,11 @@ module ActionMCP
                   :max_threads,
                   :max_queue,
                   :polling_interval,
-                  :connects_to
+                  :connects_to,
+                  # --- Tasks Options (MCP 2025-11-25) ---
+                  :tasks_enabled,
+                  :tasks_list_enabled,
+                  :tasks_cancel_enabled
 
     def initialize
       @logging_enabled = false
@@ -65,7 +69,12 @@ module ActionMCP
 
       @sse_heartbeat_interval = 30
       @post_response_preference = :json
-      @protocol_version = "2025-03-26" # Default to legacy for backwards compatibility
+      @protocol_version = "2025-06-18"  # Default to stable version for backwards compatibility
+
+      # Tasks defaults (MCP 2025-11-25)
+      @tasks_enabled = false
+      @tasks_list_enabled = true
+      @tasks_cancel_enabled = true
 
       # Resumability defaults
       @sse_event_retention_period = 15.minutes
@@ -224,6 +233,18 @@ module ActionMCP
 
       capabilities[:elicitation] = {} if @elicitation_enabled
 
+      # Tasks capability (MCP 2025-11-25)
+      if @tasks_enabled
+        tasks_cap = {
+          requests: {
+            tools: { call: {} }
+          }
+        }
+        tasks_cap[:list] = {} if @tasks_list_enabled
+        tasks_cap[:cancel] = {} if @tasks_cancel_enabled
+        capabilities[:tasks] = tasks_cap
+      end
+
       capabilities
     end
 

data/lib/action_mcp/engine.rb

@@ -61,6 +61,14 @@ module ActionMCP
 
     # Configure autoloading for the mcp/tools directory and identifiers
     initializer "action_mcp.autoloading", before: :set_autoload_paths do |app|
+      # Ensure ActionMCP base constants exist before Zeitwerk indexes app/mcp
+      # This prevents NameError when dependent gems have app/mcp
+      # directories with classes inheriting from ActionMCP::Tool, etc.
+      require "action_mcp/tool"
+      require "action_mcp/prompt"
+      require "action_mcp/resource_template"
+      require "action_mcp/gateway"
+
       mcp_path = app.root.join("app/mcp")
       identifiers_path = app.root.join("app/identifiers")
 

data/lib/action_mcp/json_rpc_handler_base.rb

@@ -34,6 +34,16 @@ module ActionMCP
 
       # Elicitation methods
       ELICITATION_CREATE = "elicitation/create"
+
+      # Task methods (MCP 2025-11-25)
+      TASKS_GET = "tasks/get"
+      TASKS_RESULT = "tasks/result"
+      TASKS_LIST = "tasks/list"
+      TASKS_CANCEL = "tasks/cancel"
+      TASKS_RESUME = "tasks/resume"
+
+      # Task notifications
+      NOTIFICATIONS_TASKS_STATUS = "notifications/tasks/status"
     end
 
     delegate :initialize!, :initialized?, to: :transport

data/lib/action_mcp/prompt.rb

@@ -18,11 +18,27 @@ module ActionMCP
     def self.prompt_name(name = nil)
       if name
         self._capability_name = name
+        re_register_if_needed
+        name
       else
         _capability_name || default_prompt_name
       end
     end
 
+    # Re-registers the prompt if it was already registered under a different name
+    # @return [void]
+    def self.re_register_if_needed
+      return if abstract?
+      return unless _registered_name # Not yet registered
+
+      new_name = capability_name
+      return if _registered_name == new_name # No change
+
+      ActionMCP::PromptsRegistry.re_register(self, _registered_name)
+    end
+
+    private_class_method :re_register_if_needed
+
     # Returns the default prompt name based on the class name.
     #
     # @return [String] The default prompt name.

data/lib/action_mcp/registry_base.rb

@@ -21,7 +21,29 @@ module ActionMCP
       def register(klass)
         return if klass.abstract?
 
-        items[klass.capability_name] = klass
+        name = klass.capability_name
+        items[name] = klass
+        klass._registered_name = name if klass.respond_to?(:_registered_name=)
+      end
+
+      # Re-register an item under its current capability_name
+      # Removes old entry if name changed
+      #
+      # @param klass [Class] The class to re-register
+      # @param old_name [String] The previous registered name
+      # @return [void]
+      def re_register(klass, old_name)
+        return if klass.abstract?
+
+        new_name = klass.capability_name
+
+        # Remove old entry if it exists and points to this class
+        if old_name && items[old_name] == klass
+          items.delete(old_name)
+        end
+
+        items[new_name] = klass
+        klass._registered_name = new_name if klass.respond_to?(:_registered_name=)
       end
 
       # Unregister an item

data/lib/action_mcp/server/handlers/router.rb

@@ -18,6 +18,8 @@ module ActionMCP
             @handler.process_resources(rpc_method, id, params)
           when %r{^tools/}
             @handler.process_tools(rpc_method, id, params)
+          when %r{^tasks/}
+            @handler.process_tasks(rpc_method, id, params)
           when "completion/complete"
             @handler.process_completion_complete(id, params)
           else

data/lib/action_mcp/server/handlers/task_handler.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module Server
+    module Handlers
+      # Handler for MCP 2025-11-25 Tasks feature
+      # Tasks provide durable state machines for tracking async request execution
+      module TaskHandler
+        include ErrorAware
+
+        def process_tasks(rpc_method, id, params)
+          params ||= {}
+
+          with_error_handling(id) do
+            handler = task_method_handlers[rpc_method]
+            if handler
+              send(handler, id, params)
+            else
+              Rails.logger.warn("Unknown tasks method: #{rpc_method}")
+              raise JSON_RPC::JsonRpcError.new(:method_not_found, message: "Unknown tasks method: #{rpc_method}")
+            end
+          end
+        end
+
+        private
+
+        def task_method_handlers
+          {
+            JsonRpcHandlerBase::Methods::TASKS_GET => :handle_tasks_get,
+            JsonRpcHandlerBase::Methods::TASKS_RESULT => :handle_tasks_result,
+            JsonRpcHandlerBase::Methods::TASKS_LIST => :handle_tasks_list,
+            JsonRpcHandlerBase::Methods::TASKS_CANCEL => :handle_tasks_cancel,
+            JsonRpcHandlerBase::Methods::TASKS_RESUME => :handle_tasks_resume
+          }
+        end
+
+        def handle_tasks_get(id, params)
+          task_id = validate_required_param(params, "taskId", "Task ID is required")
+          task = find_task_or_error(id, task_id)
+          return unless task
+
+          transport.send_tasks_get(id, task_id)
+        end
+
+        def handle_tasks_result(id, params)
+          task_id = validate_required_param(params, "taskId", "Task ID is required")
+          task = find_task_or_error(id, task_id)
+          return unless task
+
+          transport.send_tasks_result(id, task_id)
+        end
+
+        def handle_tasks_list(id, params)
+          cursor = params["cursor"]
+          transport.send_tasks_list(id, cursor: cursor)
+        end
+
+        def handle_tasks_cancel(id, params)
+          task_id = validate_required_param(params, "taskId", "Task ID is required")
+          task = find_task_or_error(id, task_id)
+          return unless task
+
+          transport.send_tasks_cancel(id, task_id)
+        end
+
+        def handle_tasks_resume(id, params)
+          task_id = validate_required_param(params, "taskId", "Task ID is required")
+          input = params["input"]
+          task = find_task_or_error(id, task_id)
+          return unless task
+
+          transport.send_tasks_resume(id, task_id, input)
+        end
+
+        def find_task_or_error(id, task_id)
+          task = transport.session.tasks.find_by(id: task_id)
+          unless task
+            transport.send_jsonrpc_error(id, :invalid_params, "Task '#{task_id}' not found")
+            return nil
+          end
+          task
+        end
+      end
+    end
+  end
+end

data/lib/action_mcp/server/json_rpc_handler.rb

@@ -7,6 +7,7 @@ module ActionMCP
       include Handlers::ToolHandler
       include Handlers::PromptHandler
       include Handlers::LoggingHandler
+      include Handlers::TaskHandler
       include ErrorHandling
       include ErrorAware
 
@@ -54,6 +55,8 @@ module ActionMCP
           process_resources(rpc_method, id, params)
         when %r{^tools/}
           process_tools(rpc_method, id, params)
+        when %r{^tasks/}
+          process_tasks(rpc_method, id, params)
         when Methods::COMPLETION_COMPLETE
           process_completion_complete(id, params)
         when Methods::LOGGING_SET_LEVEL

data/lib/action_mcp/server/simple_pub_sub.rb

@@ -36,7 +36,7 @@ module ActionMCP
       # @param success_callback [Proc] Callback for successful subscription
       # @return [String] Subscription ID
       def subscribe(channel, message_callback, success_callback = nil)
-        subscription_id = SecureRandom.uuid
+        subscription_id = SecureRandom.uuid_v7
 
         @subscriptions[subscription_id] = {
           channel: channel,

data/lib/action_mcp/server/solid_mcp_adapter.rb

@@ -21,7 +21,7 @@ module ActionMCP
       # @param success_callback [Proc] Callback for successful subscription
       # @return [String] Subscription ID
       def subscribe(channel, message_callback, success_callback = nil)
-        subscription_id = SecureRandom.uuid
+        subscription_id = SecureRandom.uuid_v7
         session_id = extract_session_id(channel)
 
         @subscriptions[subscription_id] = {

data/lib/action_mcp/server/tasks.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module Server
+    # Tasks module for MCP 2025-11-25 specification
+    # Provides methods for handling task-related requests:
+    # - tasks/get: Get task status and data
+    # - tasks/result: Get task result (blocking until terminal state)
+    # - tasks/list: List tasks for the session
+    # - tasks/cancel: Cancel a task
+    module Tasks
+      # Get task status and metadata
+      # @param request_id [String, Integer] JSON-RPC request ID
+      # @param task_id [String] Task ID to retrieve
+      def send_tasks_get(request_id, task_id)
+        task = find_task(task_id)
+        return unless task
+
+        send_jsonrpc_response(request_id, result: { task: task.to_task_data })
+      end
+
+      # Get task result, blocking until task reaches terminal state
+      # @param request_id [String, Integer] JSON-RPC request ID
+      # @param task_id [String] Task ID to get result for
+      def send_tasks_result(request_id, task_id)
+        task = find_task(task_id)
+        return unless task
+
+        # If task is not in terminal state, wait for it
+        # In async execution, client should poll or use SSE for notifications
+        unless task.terminal?
+          send_jsonrpc_error(request_id, :invalid_request,
+                             "Task is not yet complete. Current status: #{task.status}")
+          return
+        end
+
+        send_jsonrpc_response(request_id, result: task.to_task_result)
+      end
+
+      # List tasks for the session with optional pagination
+      # @param request_id [String, Integer] JSON-RPC request ID
+      # @param cursor [String, nil] Pagination cursor
+      def send_tasks_list(request_id, cursor: nil)
+        # Parse cursor if provided
+        offset = cursor.to_i if cursor.present?
+        offset ||= 0
+        limit = 50
+
+        tasks = session.tasks.recent.offset(offset).limit(limit + 1)
+        has_more = tasks.length > limit
+        tasks = tasks.first(limit)
+
+        result = {
+          tasks: tasks.map(&:to_task_data)
+        }
+        result[:nextCursor] = (offset + limit).to_s if has_more
+
+        send_jsonrpc_response(request_id, result: result)
+      end
+
+      # Cancel a task
+      # @param request_id [String, Integer] JSON-RPC request ID
+      # @param task_id [String] Task ID to cancel
+      def send_tasks_cancel(request_id, task_id)
+        task = find_task(task_id)
+        return unless task
+
+        if task.terminal?
+          send_jsonrpc_error(request_id, :invalid_params,
+                             "Cannot cancel task in terminal status: #{task.status}")
+          return
+        end
+
+        task.cancel!
+        send_jsonrpc_response(request_id, result: { task: task.to_task_data })
+      end
+
+      # Resume a task from input_required state
+      # @param request_id [String, Integer] JSON-RPC request ID
+      # @param task_id [String] Task ID to resume
+      # @param input [Object] Input data for the task
+      def send_tasks_resume(request_id, task_id, input)
+        task = find_task(task_id)
+        return unless task
+
+        unless task.input_required?
+          send_jsonrpc_error(request_id, :invalid_params,
+                             "Task is not awaiting input. Current status: #{task.status}")
+          return
+        end
+
+        # Store input in continuation state
+        continuation = task.continuation_state || {}
+        continuation[:input] = input
+        task.update!(continuation_state: continuation)
+
+        # Resume task and re-enqueue job
+        task.resume_from_continuation!
+
+        send_jsonrpc_response(request_id, result: { task: task.to_task_data })
+      end
+
+      # Send task status notification
+      # @param task [ActionMCP::Session::Task] Task to notify about
+      def send_task_status_notification(task)
+        send_jsonrpc_notification(
+          JsonRpcHandlerBase::Methods::NOTIFICATIONS_TASKS_STATUS,
+          { task: task.to_task_data }
+        )
+      end
+
+      private
+
+      def find_task(task_id)
+        task = session.tasks.find_by(id: task_id)
+        unless task
+          Rails.logger.warn "Task not found: #{task_id}"
+          # Note: we need the request_id to send error, but this is called from handler
+          # The handler should handle the nil return
+        end
+        task
+      end
+    end
+  end
+end

data/lib/action_mcp/server/tools.rb

@@ -58,6 +58,20 @@ module ActionMCP
           return
         end
 
+        # Check for task-augmented execution (MCP 2025-11-25)
+        task_params = _meta["task"] || _meta[:task]
+        if task_params && tasks_enabled?
+          handle_task_augmented_tool_call(request_id, tool_name, arguments, _meta, task_params)
+          return
+        end
+
+        # Standard synchronous execution
+        execute_tool_synchronously(request_id, tool_class, tool_name, arguments, _meta)
+      end
+
+      private
+
+      def execute_tool_synchronously(request_id, tool_class, tool_name, arguments, _meta)
         begin
           # Create tool and set execution context with request info
           tool = tool_class.new(arguments)
@@ -106,7 +120,39 @@ module ActionMCP
         end
       end
 
-      private
+      # Handle task-augmented tool calls per MCP 2025-11-25 specification
+      # Creates a Task record and executes the tool asynchronously
+      def handle_task_augmented_tool_call(request_id, tool_name, arguments, _meta, task_params)
+        # Extract task configuration
+        ttl = task_params["ttl"] || task_params[:ttl] || 60_000
+        poll_interval = task_params["pollInterval"] || task_params[:pollInterval] || 5_000
+
+        # Create task record
+        task = session.tasks.create!(
+          request_method: "tools/call",
+          request_name: tool_name,
+          request_params: {
+            name: tool_name,
+            arguments: arguments,
+            _meta: _meta
+          },
+          ttl: ttl,
+          poll_interval: poll_interval
+        )
+
+        # Return CreateTaskResult immediately
+        send_jsonrpc_response(request_id, result: { task: task.to_task_data })
+
+        # Execute tool asynchronously via ActiveJob
+        ToolExecutionJob.perform_later(task.id, tool_name, arguments, _meta)
+      rescue StandardError => e
+        Rails.logger.error "Failed to create task: #{e.class} - #{e.message}"
+        send_jsonrpc_error(request_id, :internal_error, "Failed to create task")
+      end
+
+      def tasks_enabled?
+        ActionMCP.configuration.tasks_enabled
+      end
 
       def format_registry_items(registry, protocol_version = nil)
         registry.map { |item| item.klass.to_h(protocol_version: protocol_version) }

data/lib/action_mcp/server/transport_handler.rb

@@ -19,6 +19,7 @@ module ActionMCP
       include  Sampling
       include  Roots
       include  Elicitation
+      include  Tasks
       include  ResponseCollector # Must be included last to override write_message
 
       # @param [ActionMCP::Session] session

data/lib/action_mcp/tool.rb

@@ -29,6 +29,8 @@ module ActionMCP
     class_attribute :_output_schema_builder, instance_accessor: false, default: nil
     class_attribute :_additional_properties, instance_accessor: false, default: nil
     class_attribute :_cached_schema_property_keys, instance_accessor: false, default: nil
+    class_attribute :_task_support, instance_accessor: false, default: :forbidden
+    class_attribute :_resumable_steps_block, instance_accessor: false, default: nil
 
     # --------------------------------------------------------------------------
     # Tool Name and Description DSL
@@ -40,11 +42,27 @@ module ActionMCP
     def self.tool_name(name = nil)
       if name
         self._capability_name = name
+        re_register_if_needed
+        name
       else
         _capability_name || default_tool_name
       end
     end
 
+    # Re-registers the tool if it was already registered under a different name
+    # @return [void]
+    def self.re_register_if_needed
+      return if abstract?
+      return unless _registered_name # Not yet registered
+
+      new_name = capability_name
+      return if _registered_name == new_name # No change
+
+      ActionMCP::ToolsRegistry.re_register(self, _registered_name)
+    end
+
+    private_class_method :re_register_if_needed
+
     # Returns a default tool name based on the class name.
     #
     # @return [String] The default tool name.
@@ -178,6 +196,60 @@ module ActionMCP
         _requires_consent
       end
 
+      # --------------------------------------------------------------------------
+      # Task Support DSL (MCP 2025-11-25)
+      # --------------------------------------------------------------------------
+      # Sets or retrieves the task support mode for this tool
+      # @param mode [Symbol, nil] :required, :optional, or :forbidden (default)
+      # @return [Symbol] The current task support mode
+      def task_support(mode = nil)
+        if mode
+          unless %i[required optional forbidden].include?(mode)
+            raise ArgumentError, "task_support must be :required, :optional, or :forbidden"
+          end
+
+          self._task_support = mode
+        else
+          _task_support
+        end
+      end
+
+      # Convenience methods for task support
+      def task_required!
+        self._task_support = :required
+      end
+
+      def task_optional!
+        self._task_support = :optional
+      end
+
+      def task_forbidden!
+        self._task_support = :forbidden
+      end
+
+      # Returns the execution metadata including task support
+      def execution_metadata
+        {
+          taskSupport: _task_support.to_s
+        }
+      end
+
+      # --------------------------------------------------------------------------
+      # Resumable Steps DSL (ActiveJob::Continuable support)
+      # --------------------------------------------------------------------------
+      # Defines resumable execution steps for long-running tools
+      # @param block [Proc] Block containing step definitions
+      # @return [void]
+      def resumable_steps(&block)
+        self._resumable_steps_block = block
+      end
+
+      # Checks if tool has resumable steps defined
+      # @return [Boolean]
+      def resumable_steps_defined?
+        _resumable_steps_block.present?
+      end
+
       # Sets or retrieves the additionalProperties setting for the input schema
       # @param enabled [Boolean, Hash] true to allow any additional properties,
       #   false to disallow them, or a Hash for typed additional properties
@@ -322,6 +394,12 @@ module ActionMCP
       annotations = annotations_for_protocol(protocol_version)
       result[:annotations] = annotations if annotations.any?
 
+      # Add execution metadata (MCP 2025-11-25)
+      # Only include if not default (forbidden) to minimize payload
+      if _task_support && _task_support != :forbidden
+        result[:execution] = execution_metadata
+      end
+
       # Add _meta if present
       result[:_meta] = _meta if _meta.any?
 
@@ -438,6 +516,28 @@ module ActionMCP
       raise NotImplementedError, "Subclasses must implement the perform method"
     end
 
+    # Request user/client input and pause execution
+    # @param prompt [String] The prompt/question for the user
+    # @param context [Hash] Additional context about the input request
+    # @return [void]
+    def request_input!(prompt:, context: {})
+      @_input_required = { prompt: prompt, context: context }
+      throw :halt_execution # Use throw to exit perform block
+    end
+
+    # Report progress for long-running tool operations
+    # Only available when tool is running in task-augmented mode
+    # @param percent [Integer] Progress percentage (0-100)
+    # @param message [String] Optional progress message
+    # @param cursor [Integer, String] Optional cursor for iteration state
+    # @return [void]
+    def report_progress!(percent:, message: nil, cursor: nil)
+      return unless @_task # Only available in task-augmented mode
+
+      @_task.update_progress!(percent: percent, message: message)
+      @_task.record_step!(:in_progress, cursor: cursor) if cursor
+    end
+
     private
 
     # Helper method for tools to manually report errors

data/lib/action_mcp/version.rb

@@ -2,7 +2,7 @@
 
 require_relative "gem_version"
 module ActionMCP
-  VERSION = "0.83.4"
+  VERSION = "0.90.0"
 
   class << self
     alias version gem_version

data/lib/action_mcp.rb

@@ -34,12 +34,12 @@ module ActionMCP
 
   # Protocol version constants
   SUPPORTED_VERSIONS = [
-    "2025-06-18", # Dr. Identity McBouncer - elicitation, structured output, resource links
-    "2025-03-26"  # The Persistent Negotiator - StreamableHTTP, resumability, audio support
+    "2025-11-25", # The Task Master - Tasks, icons, tool naming, polling SSE
+    "2025-06-18"  # Dr. Identity McBouncer - elicitation, structured output, resource links
   ].freeze
 
   LATEST_VERSION = SUPPORTED_VERSIONS.first.freeze
-  DEFAULT_PROTOCOL_VERSION = "2025-03-26" # Default to initial stable version for backwards compatibility
+  DEFAULT_PROTOCOL_VERSION = "2025-06-18" # Default to previous stable version for backwards compatibility
   class << self
     # Returns a Rack-compatible application for serving MCP requests
     # This makes ActionMCP.server work similar to ActionCable.server

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: actionmcp
 version: !ruby/object:Gem::Version
-  version: 0.83.4
+  version: 0.90.0
 platform: ruby
 authors:
 - Abdelkader Boudih
@@ -9,20 +9,34 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.0
 - !ruby/object:Gem::Dependency
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 8.0.4
+        version: 8.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 8.0.4
+        version: 8.1.0
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
   requirement: !ruby/object:Gem::Requirement
@@ -71,14 +85,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 8.0.4
+        version: 8.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 8.0.4
+        version: 8.1.0
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -93,6 +107,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.6'
+- !ruby/object:Gem::Dependency
+  name: state_machines-activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.100.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.100.0
 - !ruby/object:Gem::Dependency
   name: json_schemer
   requirement: !ruby/object:Gem::Requirement
@@ -121,6 +149,7 @@ files:
 - README.md
 - Rakefile
 - app/controllers/action_mcp/application_controller.rb
+- app/jobs/action_mcp/tool_execution_job.rb
 - app/models/action_mcp.rb
 - app/models/action_mcp/application_record.rb
 - app/models/action_mcp/session.rb
@@ -128,12 +157,15 @@ files:
 - app/models/action_mcp/session/resource.rb
 - app/models/action_mcp/session/sse_event.rb
 - app/models/action_mcp/session/subscription.rb
+- app/models/action_mcp/session/task.rb
 - app/models/concerns/action_mcp/mcp_console_helpers.rb
 - app/models/concerns/action_mcp/mcp_message_inspect.rb
 - config/routes.rb
 - db/migrate/20250512154359_consolidated_migration.rb
 - db/migrate/20250715070713_add_consents_to_action_mcp_sess.rb
 - db/migrate/20250727000001_remove_oauth_support.rb
+- db/migrate/20251125000001_create_action_mcp_session_tasks.rb
+- db/migrate/20251126000001_add_continuation_state_to_action_mcp_session_tasks.rb
 - exe/actionmcp_cli
 - lib/action_mcp.rb
 - lib/action_mcp/base_response.rb
@@ -223,6 +255,7 @@ files:
 - lib/action_mcp/server/handlers/prompt_handler.rb
 - lib/action_mcp/server/handlers/resource_handler.rb
 - lib/action_mcp/server/handlers/router.rb
+- lib/action_mcp/server/handlers/task_handler.rb
 - lib/action_mcp/server/handlers/tool_handler.rb
 - lib/action_mcp/server/json_rpc_handler.rb
 - lib/action_mcp/server/messaging_service.rb
@@ -237,6 +270,7 @@ files:
 - lib/action_mcp/server/session_store_factory.rb
 - lib/action_mcp/server/simple_pub_sub.rb
 - lib/action_mcp/server/solid_mcp_adapter.rb
+- lib/action_mcp/server/tasks.rb
 - lib/action_mcp/server/test_session_store.rb
 - lib/action_mcp/server/tools.rb
 - lib/action_mcp/server/transport_handler.rb