DhanHQ 3.1.0 → 3.2.0

data/lib/DhanHQ/agent/tool_registry.rb

@@ -2,35 +2,17 @@
 
 module DhanHQ
   module Agent
-    # Machine-readable tool metadata shared by MCP and agent skills.
+    # Registry and dispatcher for the tools exposed to MCP clients and agent skills.
     #
-    # Each tool has:
-    # - name, description, scope, risk, schema (input), handler
-    # - version: semantic version of the tool definition
-    # - output_schema: JSON Schema for the tool's return value
-    # - examples: array of example input/output pairs
-    # rubocop:disable Metrics/ModuleLength
+    # Holds the catalogue (which tools exist, at what scope and risk) and enforces
+    # {DhanHQ::Agent::Policy} on every call. The tools themselves are described by
+    # {DhanHQ::Agent::ToolSchemas} and carried out by {DhanHQ::Agent::ToolHandlers};
+    # each tool is a {DhanHQ::Agent::Tool}.
     module ToolRegistry
-      Tool = Struct.new(:name, :description, :scope, :risk, :schema, :handler,
-                        :version, :output_schema, :examples) do
-        def to_h
-          {
-            name: name,
-            description: description,
-            scope: scope,
-            risk: risk,
-            input_schema: schema,
-            output_schema: output_schema,
-            version: version,
-            examples: examples
-          }.compact
-        end
-      end
-
       module_function
 
       def tools
-        @tools ||= build_tools.freeze
+        @tools ||= ToolCatalogue.all.freeze
       end
 
       def find(name)
@@ -43,12 +25,17 @@ module DhanHQ
 
       def execute(name, arguments = {}, policy: Policy.from_env)
         tool = find(name)
-        if tool.risk.to_s.end_with?("write") || tool.risk == "destructive_write"
-          policy.require_write!(tool.scope)
-        else
-          policy.require!(tool.scope)
-        end
-        tool.handler.call(symbolize(arguments))
+        tool.write? ? policy.require_write!(tool.scope) : policy.require!(tool.scope)
+        tool.handler.call(KeyCoercion.symbolize(arguments))
+      end
+
+      # Coerces JSON-delivered argument keys to symbols.
+      # Part of this module's surface because {DhanHQ::Agent::OrderPreview} calls it.
+      #
+      # @param value [Hash, Array, Object]
+      # @return [Hash, Array, Object]
+      def symbolize(value)
+        KeyCoercion.symbolize(value)
       end
 
       # Returns capability manifest for the agent runtime.
@@ -63,237 +50,6 @@ module DhanHQ
           write_enabled: Policy.from_env.writes_enabled?
         }
       end
-
-      def build_tools
-        (primitive_tools + skill_tools).to_h { |tool_item| [tool_item.name, tool_item] }
-      end
-
-      def primitive_tools
-        [
-          tool("dhan_profile", "Fetch Dhan profile", "portfolio:read", "read_only",
-               object_schema, profile_handler,
-               version: "1.0.0",
-               output_schema: { type: "object", properties: { client_id: { type: "string" } } }),
-          tool("dhan_funds", "Fetch fund limits", "portfolio:read", "read_only",
-               object_schema, funds_handler,
-               version: "1.0.0",
-               output_schema: { type: "object", properties: { available_balance: { type: "number" } } }),
-          tool("dhan_holdings", "List holdings", "portfolio:read", "read_only",
-               object_schema, holdings_handler,
-               version: "1.0.0",
-               output_schema: { type: "array", items: { type: "object" } }),
-          tool("dhan_positions", "List positions", "portfolio:read", "read_only",
-               object_schema, positions_handler,
-               version: "1.0.0",
-               output_schema: { type: "array", items: { type: "object" } }),
-          tool("dhan_orders", "List orders", "orders:read", "read_only",
-               object_schema, orders_handler,
-               version: "1.0.0",
-               output_schema: { type: "array", items: { type: "object" } }),
-          tool("dhan_trades", "List trades", "orders:read", "read_only",
-               object_schema, trades_handler,
-               version: "1.0.0",
-               output_schema: { type: "array", items: { type: "object" } }),
-          tool("dhan_search_instruments", "Resolve symbols to security IDs", "market:read", "read_only",
-               search_schema, search_handler,
-               version: "1.0.0",
-               output_schema: { type: "array", items: { type: "object" } },
-               examples: [
-                 { input: { query: "RELIANCE" }, output: "[{security_id: '2885', symbol_name: 'RELIANCE'}]" }
-               ]),
-          tool("dhan_ltp", "Fetch last traded prices", "market:read", "read_only",
-               feed_schema, ltp_handler,
-               version: "1.0.0",
-               output_schema: { type: "object", additionalProperties: { type: "number" } }),
-          tool("dhan_quote", "Fetch market quotes", "market:read", "read_only",
-               feed_schema, quote_handler,
-               version: "1.0.0",
-               output_schema: { type: "object", additionalProperties: { type: "object" } }),
-          tool("dhan_order_preview", "Validate and summarize an order without placing it", "orders:read",
-               "trade_adjacent_read", order_schema, preview_handler,
-               version: "1.0.0",
-               output_schema: {
-                 type: "object",
-                 properties: {
-                   valid: { type: "boolean" },
-                   errors: { type: "array" },
-                   summary: { type: "string" }
-                 }
-               }),
-          tool("dhan_place_order", "Place an order after external confirmation", "orders:write", "live_write",
-               order_schema, place_order_handler,
-               version: "1.0.0",
-               output_schema: { type: "object", properties: { order_id: { type: "string" } } }),
-          tool("dhan_cancel_order", "Cancel an order", "orders:cancel", "destructive_write",
-               cancel_schema, cancel_order_handler,
-               version: "1.0.0",
-               output_schema: { type: "object", properties: { order_id: { type: "string" }, status: { type: "string" } } })
-        ]
-      end
-
-      # Exposes each registered DhanHQ::Skills::Registry strategy as an MCP tool,
-      # gated by the risk/scope the skill class declares (see DhanHQ::Skills::Base).
-      def skill_tools
-        DhanHQ::Skills::Registry.list.map do |skill|
-          klass = DhanHQ::Skills::Registry.find(skill[:name])
-          tool("dhan_skill_#{skill[:name]}", skill[:description], klass.scope, klass.risk,
-               skill_input_schema(skill[:params]),
-               ->(arguments) { DhanHQ::Skills::Registry.call(skill[:name], arguments) },
-               version: "1.0.0")
-        end
-      end
-
-      def skill_input_schema(params)
-        properties = params.transform_values do |config|
-          { type: skill_param_type(config[:type]) }.tap { |h| h[:description] = config[:description] if config[:description] }
-        end
-        required = params.select { |_, config| config[:required] }.keys.map(&:to_s)
-        { type: "object", properties: properties, required: required, additionalProperties: false }
-      end
-
-      def skill_param_type(type)
-        { string: "string", integer: "integer", number: "number", boolean: "boolean" }.fetch(type.to_sym, "string")
-      end
-
-      # rubocop:disable Metrics/ParameterLists
-      def tool(name, description, scope, risk, schema, handler, version: "1.0.0", output_schema: nil, examples: nil)
-        Tool.new(
-          name: name, description: description, scope: scope, risk: risk,
-          schema: schema, handler: handler, version: version,
-          output_schema: output_schema, examples: examples
-        )
-      end
-      # rubocop:enable Metrics/ParameterLists
-
-      def object_schema
-        { type: "object", properties: {}, additionalProperties: false }
-      end
-
-      def search_schema
-        {
-          type: "object",
-          required: ["query"],
-          properties: {
-            query: { type: "string" },
-            segments: { type: "array", items: { type: "string" } },
-            limit: { type: "integer", minimum: 1, maximum: 100 },
-            exact_match: { type: "boolean" }
-          },
-          additionalProperties: false
-        }
-      end
-
-      def feed_schema
-        {
-          type: "object",
-          required: ["instruments"],
-          properties: {
-            instruments: {
-              type: "object",
-              additionalProperties: { type: "array", items: { type: %w[integer string] } }
-            }
-          },
-          additionalProperties: false
-        }
-      end
-
-      def order_schema
-        {
-          type: "object",
-          required: %w[transaction_type exchange_segment product_type order_type validity security_id quantity],
-          properties: {
-            transaction_type: enum(%w[BUY SELL]),
-            exchange_segment: { type: "string" },
-            product_type: { type: "string" },
-            order_type: { type: "string" },
-            validity: { type: "string" },
-            security_id: { type: "string" },
-            quantity: { type: "integer", minimum: 1 },
-            price: { type: "number" },
-            trigger_price: { type: "number" },
-            correlation_id: { type: "string" }
-          },
-          additionalProperties: true
-        }
-      end
-
-      def cancel_schema
-        {
-          type: "object",
-          required: ["order_id"],
-          properties: { order_id: { type: "string" } },
-          additionalProperties: false
-        }
-      end
-
-      def enum(values)
-        { type: "string", enum: values }
-      end
-
-      def profile_handler = ->(_) { DhanHQ::Models::Profile.fetch }
-
-      def funds_handler = ->(_) { DhanHQ::Models::Funds.fetch }
-
-      def holdings_handler = ->(_) { DhanHQ::Models::Holding.all }
-
-      def positions_handler = ->(_) { DhanHQ::Models::Position.all }
-
-      def orders_handler = ->(_) { DhanHQ::Models::Order.all }
-
-      def trades_handler = ->(_) { DhanHQ::Models::Trade.today }
-
-      def search_handler
-        lambda do |arguments|
-          query = arguments.fetch(:query)
-          options = arguments.except(:query)
-          DhanHQ::Models::Instrument.search(query, **options)
-        end
-      end
-
-      def ltp_handler = ->(arguments) { DhanHQ::Models::MarketFeed.ltp(arguments[:instruments]) }
-
-      def quote_handler = ->(arguments) { DhanHQ::Models::MarketFeed.quote(arguments[:instruments]) }
-
-      def preview_handler = ->(arguments) { OrderPreview.new(arguments).to_h }
-
-      def place_order_handler
-        lambda do |arguments|
-          instrument = DhanHQ::Models::Instrument.find_by_security_id(arguments[:exchange_segment], arguments[:security_id])
-          unless instrument
-            raise DhanHQ::RiskViolation,
-                  "Cannot verify risk for unknown instrument: #{arguments[:exchange_segment]}:#{arguments[:security_id]}"
-          end
-
-          risk_type = instrument.instrument_type.to_s.start_with?("OPT") ? :options : :equity
-          DhanHQ::Risk::Pipeline.run!(instrument: instrument, args: stringify(arguments), type: risk_type)
-
-          DhanHQ::Models::Order.place(arguments)
-        end
-      end
-
-      def cancel_order_handler
-        lambda do |arguments|
-          order = DhanHQ::Models::Order.find(arguments[:order_id])
-          order&.cancel || false
-        end
-      end
-
-      def symbolize(value)
-        case value
-        when Hash then value.each_with_object({}) { |(key, val), hash| hash[key.to_sym] = symbolize(val) }
-        when Array then value.map { |val| symbolize(val) }
-        else value
-        end
-      end
-
-      def stringify(value)
-        case value
-        when Hash then value.each_with_object({}) { |(key, val), hash| hash[key.to_s] = stringify(val) }
-        when Array then value.map { |val| stringify(val) }
-        else value
-        end
-      end
     end
-    # rubocop:enable Metrics/ModuleLength
   end
 end

data/lib/DhanHQ/agent/tool_schemas.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Agent
+    # JSON Schema fragments describing the input each agent tool accepts.
+    #
+    # Pure data: no API calls, no policy, no state. Kept apart from
+    # {DhanHQ::Agent::ToolRegistry} so that adding an endpoint means editing a schema
+    # here and a handler in {DhanHQ::Agent::ToolHandlers}, rather than growing one
+    # module that does registration, schema description and dispatch at once.
+    module ToolSchemas
+      module_function
+
+      def object_schema
+        { type: "object", properties: {}, additionalProperties: false }
+      end
+
+      def search_schema
+        {
+          type: "object",
+          required: ["query"],
+          properties: {
+            query: { type: "string" },
+            segments: { type: "array", items: { type: "string" } },
+            limit: { type: "integer", minimum: 1, maximum: 100 },
+            exact_match: { type: "boolean" }
+          },
+          additionalProperties: false
+        }
+      end
+
+      def feed_schema
+        {
+          type: "object",
+          required: ["instruments"],
+          properties: {
+            instruments: {
+              type: "object",
+              additionalProperties: { type: "array", items: { type: %w[integer string] } }
+            }
+          },
+          additionalProperties: false
+        }
+      end
+
+      def order_schema
+        {
+          type: "object",
+          required: %w[transaction_type exchange_segment product_type order_type validity security_id quantity],
+          properties: {
+            transaction_type: enum(%w[BUY SELL]),
+            exchange_segment: { type: "string" },
+            product_type: { type: "string" },
+            order_type: { type: "string" },
+            validity: { type: "string" },
+            security_id: { type: "string" },
+            quantity: { type: "integer", minimum: 1 },
+            price: { type: "number" },
+            trigger_price: { type: "number" },
+            correlation_id: { type: "string" }
+          },
+          additionalProperties: true
+        }
+      end
+
+      def cancel_schema
+        {
+          type: "object",
+          required: ["order_id"],
+          properties: { order_id: { type: "string" } },
+          additionalProperties: false
+        }
+      end
+
+      # Global Stocks orders carry no exchange segment, product type or validity, and
+      # quantity is fractional. AMOUNT orders replace quantity with a dollar amount.
+      def global_order_schema
+        {
+          type: "object",
+          required: %w[transaction_type order_type security_id],
+          properties: {
+            transaction_type: enum(%w[BUY SELL]),
+            order_type: enum(DhanHQ::Constants::GlobalStocks::OrderType::ALL),
+            security_id: { type: "string" },
+            quantity: { type: "number", exclusiveMinimum: 0 },
+            price: { type: "number", minimum: 0 },
+            trigger_price: { type: "number" },
+            stop_loss_price: { type: "number" },
+            target_price: { type: "number" },
+            amount: { type: "number", description: "Dollar value for AMOUNT orders" },
+            correlation_id: { type: "string" }
+          },
+          additionalProperties: true
+        }
+      end
+
+      def global_estimate_schema
+        {
+          type: "object",
+          required: %w[security_id transaction_type price quantity],
+          properties: {
+            security_id: { type: "string" },
+            transaction_type: enum(%w[BUY SELL]),
+            price: { type: "number", minimum: 0 },
+            quantity: { type: "number", exclusiveMinimum: 0 }
+          },
+          additionalProperties: false
+        }
+      end
+
+      def multi_order_schema
+        {
+          type: "object",
+          required: ["orders"],
+          properties: {
+            orders: {
+              type: "array",
+              minItems: 1,
+              maxItems: DhanHQ::Contracts::MultiOrderContract::MAX_ORDERS,
+              items: {
+                type: "object",
+                required: %w[sequence transaction_type exchange_segment],
+                properties: {
+                  sequence: { type: "string" },
+                  transaction_type: enum(%w[BUY SELL]),
+                  exchange_segment: { type: "string" },
+                  product_type: { type: "string" },
+                  order_type: { type: "string" },
+                  validity: { type: "string" },
+                  security_id: { type: "string" },
+                  quantity: { type: "integer", minimum: 1 },
+                  price: { type: "number" },
+                  trigger_price: { type: "number" }
+                },
+                additionalProperties: true
+              }
+            }
+          },
+          additionalProperties: false
+        }
+      end
+
+      def enum(values)
+        { type: "string", enum: values }
+      end
+
+      def skill_input_schema(params)
+        properties = params.transform_values do |config|
+          { type: skill_param_type(config[:type]) }.tap { |h| h[:description] = config[:description] if config[:description] }
+        end
+        required = params.select { |_, config| config[:required] }.keys.map(&:to_s)
+        { type: "object", properties: properties, required: required, additionalProperties: false }
+      end
+
+      def skill_param_type(type)
+        { string: "string", integer: "integer", number: "number", boolean: "boolean" }.fetch(type.to_sym, "string")
+      end
+    end
+  end
+end

data/lib/DhanHQ/client.rb

@@ -2,6 +2,7 @@
 
 require "faraday"
 require "json"
+require "securerandom"
 require "active_support/core_ext/hash/indifferent_access"
 require_relative "errors"
 require_relative "rate_limiter"
@@ -60,12 +61,19 @@ module DhanHQ
     # @return [HashWithIndifferentAccess, Array<HashWithIndifferentAccess>] Parsed JSON response.
     # @raise [DhanHQ::Error] If an HTTP error occurs.
     def request(method, path, payload, retries: 3)
+      payload = with_correlation_id(method, path, payload)
+      return dry_run.response_for(method, path, payload) if dry_run.simulates?(method, path)
+
       @token_manager&.ensure_valid_token!
       @rate_limiter.throttle!
       refresh_connection!
 
+      # A non-idempotent write is not safely retryable: the API has no idempotency
+      # key, so a request that timed out may already have reached the exchange.
+      effective_retries = retryable_write?(method, path) ? retries : 0
+
       with_auth_retry do
-        with_transient_retry(retries: retries) do
+        with_transient_retry(retries: effective_retries) do
           response = connection.send(method, path) do |req|
             req.headers.merge!(build_headers(path))
             prepare_payload(req, payload, method, path)
@@ -103,7 +111,11 @@ module DhanHQ
         retry
       rescue Faraday::TimeoutError, Faraday::ConnectionFailed => e
         attempt += 1
-        raise DhanHQ::NetworkError, "Request failed after #{retries} retries: #{e.message}" if attempt > retries
+        if attempt > retries
+          raise DhanHQ::NetworkError, "Request failed: #{e.message}" if retries.zero?
+
+          raise DhanHQ::NetworkError, "Request failed after #{retries} retries: #{e.message}"
+        end
 
         backoff = calculate_backoff(attempt)
         DhanHQ.logger&.warn(
@@ -197,6 +209,50 @@ module DhanHQ
 
     private
 
+    # Simulator that answers state-changing requests locally when dry run is on.
+    #
+    # @return [DhanHQ::DryRun::Simulator]
+    def dry_run
+      @dry_run ||= DhanHQ::DryRun::Simulator.new
+    end
+
+    # A write may be auto-retried only when the user has explicitly opted in.
+    def retryable_write?(method, path)
+      return true unless WritePaths.mutating?(method, path)
+
+      DhanHQ.configuration&.retry_non_idempotent_writes? || false
+    end
+
+    # Fills in a +correlationId+ on order placements that lack one, so a caller who
+    # hits a timeout can still discover whether the order reached the exchange via
+    # GET /v2/orders/external/{correlation-id}.
+    def with_correlation_id(method, path, payload)
+      return payload unless WritePaths.order_placement?(method, path)
+      return payload unless payload.is_a?(Hash)
+      return payload unless DhanHQ.configuration&.auto_correlation_id?
+      return payload if correlation_id?(payload)
+
+      inject_correlation_id(payload)
+    end
+
+    # Keys a caller may already have used for the correlation id, in either casing.
+    CORRELATION_ID_KEYS = %i[correlationId correlation_id].flat_map { |key| [key, key.to_s] }.freeze
+    private_constant :CORRELATION_ID_KEYS
+
+    # @return [Boolean] True when the caller supplied their own correlation id.
+    def correlation_id?(payload)
+      CORRELATION_ID_KEYS.any? { |key| payload.key?(key) }
+    end
+
+    # Returns a copy of the payload carrying a generated correlation id, matching the
+    # key type the payload already uses.
+    def inject_correlation_id(payload)
+      correlation_id = "dhq-#{SecureRandom.hex(8)}"
+      out = payload.dup
+      out.keys.any?(String) ? out["correlationId"] = correlation_id : out[:correlationId] = correlation_id
+      out
+    end
+
     def refresh_connection!
       current_url = DhanHQ.configuration.base_url
       return if @last_base_url == current_url

data/lib/DhanHQ/concerns/order_audit.rb

@@ -50,14 +50,21 @@ module DhanHQ
       #
       # Extracts +security_id+ and +exchange_segment+ from the params,
       # resolves the instrument, and calls {DhanHQ::Risk::Pipeline.run!}.
-      # If the instrument cannot be resolved the check is skipped silently
-      # rather than blocking the order.
+      # If the instrument cannot be resolved the check is skipped rather than
+      # blocking the order, since a transient scrip-master lookup failure should not
+      # stop a valid trade.
+      #
+      # Anything other than a lookup failure is logged before being swallowed. This
+      # method used to rescue StandardError silently, which is how a wrong-arity call
+      # to `Instrument.find` went unnoticed long enough for the risk pipeline to never
+      # run for any real order (see CHANGELOG 3.1.0). A skipped check is tolerable; a
+      # skipped check nobody can see is not.
       def run_risk_checks!(params)
         security_id = extract_param(params, :securityId, :security_id)
         exchange_segment = extract_param(params, :exchangeSegment, :exchange_segment)
         return unless security_id && exchange_segment
 
-        instrument = DhanHQ::Models::Instrument.find_by_security_id(exchange_segment, security_id)
+        instrument = resolve_instrument_for_risk(exchange_segment, security_id)
         return unless instrument
 
         DhanHQ::Risk::Pipeline.run!(
@@ -68,10 +75,34 @@ module DhanHQ
         )
       rescue DhanHQ::RiskViolation
         raise
-      rescue StandardError
+      rescue StandardError => e
+        log_risk_check_skipped(e, security_id, exchange_segment)
+        nil
+      end
+
+      # Resolves the instrument the risk pipeline needs, tolerating a lookup failure.
+      #
+      # @return [DhanHQ::Models::Instrument, nil]
+      def resolve_instrument_for_risk(exchange_segment, security_id)
+        DhanHQ::Models::Instrument.find_by_security_id(exchange_segment, security_id)
+      rescue StandardError => e
+        log_risk_check_skipped(e, security_id, exchange_segment)
         nil
       end
 
+      # Records that pre-trade risk checks did not run, and why.
+      def log_risk_check_skipped(error, security_id, exchange_segment)
+        DhanHQ.logger&.error(
+          JSON.generate(
+            event: "DHAN_RISK_CHECK_SKIPPED",
+            security_id: security_id,
+            exchange_segment: exchange_segment,
+            error: error.class.name,
+            message: error.message
+          )
+        )
+      end
+
       # Maps an exchange segment string to a pipeline trade type.
       def trade_type_for(exchange_segment)
         case exchange_segment.to_s