graphmind 0.6.0

data/lib/graphmind/api.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+require_relative "session"
+require_relative "wrap"
+
+module Graphmind
+  # One debugger attachment point for a process.
+  #
+  #   gm = Graphmind.configure(app: "support-agent")
+  #
+  #   search = gm.tool("search_flights") { |origin:, destination:| ... }
+  #
+  #   gm.run("handle-ticket") do
+  #     search.call(origin: "LHR", destination: "JFK")
+  #   end
+  #
+  # Everything degrades to a no-op when no debugger is attached, and to
+  # literally nothing when GraphMind is disabled.
+  class Client
+    attr_reader :session
+
+    def initialize(app: nil, sdk: nil, **session_options)
+      @session = Session.new(
+        app_name: app || default_app_name,
+        sdk: sdk || { "name" => "ruby", "version" => Graphmind::VERSION },
+        **session_options
+      )
+      @session_of = -> { @session }
+    end
+
+    # -- attach --------------------------------------------------------------
+
+    def enabled?  = @session.enabled?
+    def attached? = @session.attached?
+    def url       = @session.url
+
+    # Block until the debugger handshake completes (breakpoints armed).
+    # `false` means "carry on detached" — it is never an error.
+    def ready(timeout = Session::DEFAULT_READY_TIMEOUT) = @session.ready(timeout)
+
+    # -- runs & spans --------------------------------------------------------
+
+    # Run boundary: `gm.run("name") { |ctx| ... }`.
+    def run(name, meta: nil, &block)
+      @session.run(name, meta: meta, &block)
+    end
+
+    def current_run = @session.current_run
+    def with_run_context(ctx, &block) = @session.with_run_context(ctx, &block)
+    def clear_run_context = @session.clear_run_context
+
+    # An arbitrary node on the canvas: gated, timed, named. Use it for the
+    # parts of a graph GraphMind cannot see by itself — a retrieval step, a
+    # hand-rolled planner loop, a Sidekiq job body.
+    #
+    # The block's value becomes the node's output and the span's value, unless
+    # `span.output = ...` sets one explicitly.
+    def span(name, kind: "custom", input: nil, parent_id: nil)
+      kind = "custom" unless Protocol::NODE_KINDS.include?(kind)
+      holder = Span.new
+      Wrap.invoke(@session,
+                  node_id: "#{kind}:#{name}", kind: kind, name: name.to_s,
+                  parent_id: parent_id, input: input) do
+        value = yield holder
+        holder.output_set? ? holder.output : value
+      end
+    end
+
+    # -- tools ---------------------------------------------------------------
+
+    # Wrap a block as a gated tool:
+    #
+    #   search = gm.tool("search") { |query:| index.query(query) }
+    #   search.call(query: "flights")
+    def tool(name = nil, kind: "tool", parent_id: nil, &block)
+      raise ArgumentError, "Graphmind#tool needs a block" if block.nil?
+
+      Wrap.gate_callable(block, @session_of, name: name, kind: kind, parent_id: parent_id)
+    end
+
+    # Wrap any callable (Proc, Method, or an object responding to #call).
+    def wrap(callable, name: nil, kind: "tool", node_id: nil, parent_id: nil)
+      Wrap.gate_callable(callable, @session_of, name: name, kind: kind, node_id: node_id,
+                                                parent_id: parent_id)
+    end
+
+    # Wrap a {name => callable} Hash, an Array of callables, or one callable.
+    def wrap_tools(tools) = Wrap.wrap_tools(tools, @session_of)
+
+    # Gate one method on one object, in place.
+    def wrap_method(target, method_name, name: nil, kind: "tool", parent_id: nil)
+      Wrap.wrap_method(target, method_name, @session_of, name: name, kind: kind,
+                                                         parent_id: parent_id)
+    end
+
+    # -- integrations --------------------------------------------------------
+
+    # Instrument a ruby-openai `OpenAI::Client` in place and return it.
+    def instrument_openai(client, **options)
+      require_relative "integrations/ruby_openai"
+      Integrations::RubyOpenAI.instrument(client, @session, **options)
+    end
+
+    # Instrument a `RubyLLM::Chat` (and its tools) in place and return it.
+    def instrument_ruby_llm(chat, **options)
+      require_relative "integrations/ruby_llm"
+      Integrations::RubyLLM.instrument(chat, @session, **options)
+    end
+
+    # -- low level -----------------------------------------------------------
+
+    def emit(type, payload) = @session.emit(type, payload)
+    def gate(point, node) = @session.gate(point, node)
+    def graph_hint(nodes) = @session.graph_hint(nodes)
+    def push_token(node_id, channel, value) = @session.push_token(node_id, channel, value)
+    def stats = @session.stats
+    def dispose = @session.dispose
+
+    private
+
+    def default_app_name
+      if defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application
+        ::Rails.application.class.name.to_s.split("::").first.to_s.downcase
+      else
+        File.basename(Dir.pwd)
+      end
+    rescue StandardError
+      "ruby"
+    end
+  end
+
+  # Yielded by Client#span so the block can name what the node produced.
+  class Span
+    attr_reader :output
+
+    def initialize
+      @output = nil
+      @set = false
+    end
+
+    def output=(value)
+      @output = value
+      @set = true
+    end
+
+    def output_set? = @set
+  end
+
+  # -- module-level default instance -----------------------------------------
+
+  @default = nil
+  @default_mutex = Mutex.new
+
+  class << self
+    # Create (or replace) the process-wide default instance. Accepts
+    # everything Session accepts plus `app:` and `sdk:`.
+    def configure(**options)
+      previous = nil
+      client = nil
+      @default_mutex.synchronize do
+        previous = @default
+        client = Client.new(**options)
+        @default = client
+      end
+      previous&.dispose
+      client
+    end
+    alias init configure
+
+    # The default instance, created with defaults on first use.
+    def instance
+      current = @default
+      return current if current
+
+      @default_mutex.synchronize do
+        @default ||= Client.new
+      end
+    end
+
+    def configured? = !@default.nil?
+
+    # Dispose and forget the default instance (mainly for tests).
+    def reset
+      current = @default_mutex.synchronize do
+        previous = @default
+        @default = nil
+        previous
+      end
+      current&.dispose
+      nil
+    end
+
+    def session = instance.session
+    def enabled? = instance.enabled?
+    def attached? = instance.attached?
+    def ready(timeout = Session::DEFAULT_READY_TIMEOUT) = instance.ready(timeout)
+    def run(name, meta: nil, &block) = instance.run(name, meta: meta, &block)
+    def span(name, **kwargs, &block) = instance.span(name, **kwargs, &block)
+    def tool(name = nil, **kwargs, &block) = instance.tool(name, **kwargs, &block)
+    def wrap(callable, **kwargs) = instance.wrap(callable, **kwargs)
+    def wrap_tools(tools) = instance.wrap_tools(tools)
+    def wrap_method(target, method_name, **kwargs) = instance.wrap_method(target, method_name, **kwargs)
+    def instrument_openai(client, **kwargs) = instance.instrument_openai(client, **kwargs)
+    def instrument_ruby_llm(chat, **kwargs) = instance.instrument_ruby_llm(chat, **kwargs)
+    def emit(type, payload) = instance.emit(type, payload)
+    def graph_hint(nodes) = instance.graph_hint(nodes)
+    def current_run = instance.current_run
+    def with_run_context(ctx, &block) = instance.with_run_context(ctx, &block)
+    def clear_run_context = instance.clear_run_context
+    def stats = instance.stats
+    def dispose = instance.dispose
+  end
+
+  # Class-level macro for gating instance methods:
+  #
+  #   class Tools
+  #     include Graphmind::Instrument
+  #     graphmind_tool :search, :book
+  #
+  #     def search(query) = ...
+  #   end
+  #
+  # Every instance of the class now pauses at `tool:search` / `tool:book`.
+  module Instrument
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def graphmind_tool(*method_names, kind: "tool", session: nil)
+        gates = (@graphmind_gate_module ||= begin
+          mod = Module.new
+          prepend(mod)
+          mod
+        end)
+        method_names.each do |method_name|
+          node_name = method_name.to_s
+          gates.define_method(method_name) do |*args, **kwargs, &block|
+            active = session ? session.call : Graphmind.instance.session
+            body = lambda do
+              kwargs.empty? ? super(*args, &block) : super(*args, **kwargs, &block)
+            end
+            if active.nil? || !active.enabled? || active.disposed?
+              body.call
+            else
+              parameters =
+                begin
+                  method(method_name).super_method&.parameters || []
+                rescue StandardError
+                  []
+                end
+              Graphmind::Wrap.invoke(
+                active,
+                node_id: Graphmind::Ids.tool_node_id(node_name),
+                kind: kind,
+                name: node_name,
+                input: Graphmind::Wrap.describe(parameters, args, kwargs),
+                &body
+              )
+            end
+          end
+        end
+        method_names
+      end
+    end
+  end
+end

data/lib/graphmind/clock.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Graphmind
+  # Duration clock.
+  #
+  # Every GraphMind duration (`durationMs`, `heldMs`) is measured on
+  # `Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond)` —
+  # monotonic and sub-microsecond — never on `Time.now`, which steps under NTP
+  # adjustment and reads a 80µs handler as `0ms`. Wall-clock fields on the wire
+  # (envelope `ts`) stay integer epoch milliseconds; only elapsed-time
+  # measurement lives here.
+  #
+  # Port of packages/client/src/clock.ts. The wire contract for a duration:
+  #   * rounded to 0.01 ms (two decimals),
+  #   * clamped to >= 0,
+  #   * never NaN / infinite (those become 0.0).
+  #
+  # The clock is read through `Clock.now_ms` at call time so tests can
+  # substitute it with `Clock.override=`.
+  module Clock
+    class << self
+      # Installed by tests; nil means the real monotonic clock.
+      attr_accessor :override
+
+      # Milliseconds on the monotonic clock. Fractional; only differences mean anything.
+      def now_ms
+        o = @override
+        return o.call.to_f if o
+
+        Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond)
+      end
+
+      # Coerce a raw millisecond measurement into the wire contract.
+      def normalize_duration_ms(raw)
+        return 0.0 unless raw.is_a?(Numeric)
+
+        value = raw.to_f
+        return 0.0 if value.nan? || value.infinite? || value <= 0.0
+
+        value.round(2)
+      end
+
+      # Elapsed since a `now_ms` reading, normalised for the wire.
+      def elapsed_ms(started_at, now = nil)
+        normalize_duration_ms((now || now_ms) - started_at)
+      end
+    end
+  end
+end

data/lib/graphmind/edit_guard.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "redaction"
+require_relative "shrink"
+
+module Graphmind
+  # The client-side inject guard (0.6.0, contract C2; refute-security C2.3 /
+  # S5): a value that still carries the redaction placeholder or a truncation
+  # marker is a pre-filled copy of a RECORDING its sender never saw in full —
+  # not a result anyone meant to substitute. Refused (the gate stays held) under
+  # every debugger, a 0.5 hub included, whose own guard knows only the
+  # placeholder.
+  #
+  # Port of `proposedValueRefusal` in packages/client/src/edit-input.ts — one
+  # marker list for every SDK and the hub, pinned by the shared fixture
+  # packages/client/test/fixtures/edit-input.json (its `proposedValue`
+  # section). This gem does not announce `edit-input`, so it never runs an
+  # edited input; only injected values need the guard.
+  #
+  # The markers, over the value's compact JSON text:
+  #   * "__REDACTED__" anywhere                               -> placeholder
+  #   * the shrink's `__graphmindTruncated` key and "…[graphmind: truncated]"
+  #     suffix, LangGraph's `"__graphmind":"truncated"` / `"unserializable"`,
+  #     the MCP get_node preview's `"note":"payload truncated: showing first `
+  #   * the Python SDK's recording bounds (`…[truncated]"`, `"<N bytes>"`,
+  #     `"…[depth limit]"`, a `"…"` key holding `"[N more keys]"`, `"…[N more]"`)
+  #                                                            -> truncated
+  module EditGuard
+    # A refusal the client decided (codes and messages never quote values).
+    Refusal = Struct.new(:code, :message)
+
+    ELLIPSIS = "\xE2\x80\xA6".dup.force_encoding(Encoding::UTF_8).freeze
+    MCP_PREVIEW_NOTE_PREFIX = "payload truncated: showing first "
+
+    TRUNCATION_MARKERS = [
+      "__graphmindTruncated",
+      Shrink::TRUNCATION_SUFFIX,
+      '"__graphmind":"truncated"',
+      '"__graphmind":"unserializable"',
+      %("note":"#{MCP_PREVIEW_NOTE_PREFIX})
+    ].map { |marker| marker.dup.force_encoding(Encoding::UTF_8).freeze }.freeze
+
+    # `PYTHON_PREVIEW_MARKERS` in edit-input.ts, verbatim (`\A` / `\z` for its
+    # `^` / `$`, which in Ruby would match at any line; ASCII digits only).
+    E = Regexp.escape(ELLIPSIS)
+    PYTHON_PREVIEW_MARKERS = [
+      Regexp.new(%(#{E}\\[truncated\\]")),
+      Regexp.new(%((?:\\A|[\\[:,])"<[0-9]+ bytes>"(?=[,\\]}]|\\z))),
+      Regexp.new(%((?:\\A|[\\[:,])"#{E}\\[depth limit\\]"(?=[,\\]}]|\\z))),
+      Regexp.new(%([{,]"#{E}":"\\[[0-9]+ more keys\\]"(?=[,}]))),
+      Regexp.new(%((?:\\A|[\\[:,])"#{E}\\[[0-9]+ more\\]"(?=[,\\]}]|\\z)))
+    ].freeze
+
+    PLACEHOLDER_MESSAGE = 'the value contains redacted content ("__REDACTED__"); replace it before running'
+    TRUNCATED_MESSAGE = "the value contains a truncated preview, not the full value; replace it before running"
+    UNREADABLE_MESSAGE = "the value could not be read as JSON"
+
+    module_function
+
+    # How deep a value this guard serialises to check (json's default, 100,
+    # refused values the TypeScript client and the Python SDK inject). Finite
+    # on purpose: json's generator recurses on the machine stack, which on a
+    # thread (the transport's, where this runs) runs out between 1,000 and
+    # 2,000 levels, and running out is not always a catchable
+    # SystemStackError. Deeper, or cyclic, is a `shape` refusal — answered,
+    # never dropped.
+    MAX_NESTING = 512
+
+    # Refusal for a proposed inject output that must never run: `placeholder`,
+    # `truncated`, or `shape` when it cannot be serialised to be checked
+    # (nested past MAX_NESTING included). nil when it is clean. Never raises.
+    def proposed_value_refusal(value)
+      text = JSON.generate(value, max_nesting: MAX_NESTING)
+      text = text.dup.force_encoding(Encoding::UTF_8) unless text.encoding == Encoding::UTF_8
+      return Refusal.new("placeholder", PLACEHOLDER_MESSAGE) if text.include?(Redaction::REDACTED)
+      if TRUNCATION_MARKERS.any? { |marker| text.include?(marker) } ||
+         PYTHON_PREVIEW_MARKERS.any? { |pattern| pattern.match?(text) }
+        return Refusal.new("truncated", TRUNCATED_MESSAGE)
+      end
+
+      nil
+    rescue StandardError, SystemStackError
+      Refusal.new("shape", UNREADABLE_MESSAGE)
+    end
+  end
+end

data/lib/graphmind/env.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Graphmind
+  # Kill switches and environment-derived defaults.
+  #
+  # Precedence for "is GraphMind enabled" (mirrors packages/client/src/env.ts,
+  # with a Ruby-flavoured production check because there is no NODE_ENV):
+  #
+  #   1. GRAPHMIND_DISABLED=1   -> disabled, always. Ops-level kill switch; it
+  #      beats an explicit `enabled: true` passed in code.
+  #   2. explicit `enabled:`    -> as given.
+  #   3. looks like production  -> disabled unless GRAPHMIND=1.
+  #   4. otherwise              -> enabled.
+  #
+  # "Looks like production" is deliberately a boring, documented rule: the
+  # first variable that is *set* out of ENV_VARS decides, and it counts as
+  # production when its value is production/prod (case-insensitive). No
+  # heuristics over hostnames, cloud metadata or TTYs — a debugger that
+  # silently turns itself off for surprising reasons is worse than one you
+  # have to switch on.
+  module Env
+    DEFAULT_URL = "ws://127.0.0.1:4747/ingest"
+
+    # Checked in order; the first one that is set decides the environment.
+    ENV_VARS = %w[
+      GRAPHMIND_ENV
+      ENVIRONMENT
+      APP_ENV
+      RAILS_ENV
+      RACK_ENV
+      ENV
+      NODE_ENV
+    ].freeze
+
+    PRODUCTION_VALUES = %w[production prod].freeze
+
+    module_function
+
+    def source(env)
+      env.nil? ? ENV : env
+    end
+
+    # True when the first *set* variable in ENV_VARS names a production env.
+    def production?(env = nil)
+      src = source(env)
+      ENV_VARS.each do |key|
+        value = src[key]
+        next if value.nil? || value.to_s.empty?
+
+        return PRODUCTION_VALUES.include?(value.to_s.strip.downcase)
+      end
+      false
+    end
+
+    KILL_SWITCH_OFF = ["", "0", "false", "off", "no"].freeze
+
+    # A kill switch or privacy switch read from the environment: on for any
+    # String except empty, `0`, `false`, `off` and `no` (case-insensitive,
+    # surrounding whitespace ignored); nil is off. An unexpected spelling
+    # (`yes`, `on`) must err towards the switch being on. Mirrors
+    # `killSwitchOn` in the TS client.
+    def kill_switch_on?(value)
+      return false unless value.is_a?(String)
+
+      !KILL_SWITCH_OFF.include?(value.strip.downcase)
+    end
+
+    def resolve_enabled(explicit = nil, env = nil)
+      src = source(env)
+      return false if kill_switch_on?(src["GRAPHMIND_DISABLED"])
+      return explicit unless explicit.nil?
+
+      !(production?(src) && src["GRAPHMIND"] != "1")
+    end
+
+    def resolve_url(explicit = nil, env = nil)
+      return explicit unless explicit.nil?
+
+      value = source(env)["GRAPHMIND_URL"]
+      value.nil? || value.empty? ? DEFAULT_URL : value
+    end
+  end
+end

data/lib/graphmind/errors.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Graphmind
+  # Raised into the host **only** when the debugger explicitly aborts a run.
+  # Everything else in this gem degrades to a no-op.
+  class AbortError < StandardError
+    def initialize(message = "Run aborted by the GraphMind debugger")
+      super
+    end
+  end
+
+  module Errors
+    MAX_STACK_FRAMES = 40
+
+    module_function
+
+    def abort_error?(error)
+      return false if error.nil?
+      return true if error.is_a?(Graphmind::AbortError)
+
+      name = error.class.name.to_s
+      name.end_with?("AbortError") || name.end_with?("Abort")
+    end
+
+    # Serialize an exception into the wire contract's ErrorInfo shape.
+    def to_error_info(error)
+      return { "name" => "Error", "message" => error.to_s } unless error.is_a?(Exception)
+
+      info = {
+        "name" => error.class.name.to_s,
+        "message" => error.message.to_s
+      }
+      backtrace = error.backtrace
+      if backtrace.is_a?(Array) && !backtrace.empty?
+        info["stack"] = ([error.message.to_s] + backtrace.first(MAX_STACK_FRAMES)).join("\n")
+      end
+      info
+    end
+  end
+end