graphmind 0.6.0

data/lib/graphmind/gate_engine.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+require_relative "protocol"
+
+module Graphmind
+  # How a gate was released.
+  class GateDecision
+    attr_reader :action, :output
+
+    def initialize(action, output = nil)
+      @action = action
+      @output = output
+      freeze
+    end
+
+    def continue? = @action == "continue"
+    def retry?    = @action == "retry"
+    def inject?   = @action == "inject"
+    def abort?    = @action == "abort"
+
+    def ==(other)
+      other.is_a?(GateDecision) && other.action == @action && other.output == @output
+    end
+    alias eql? ==
+
+    def hash = [@action, @output].hash
+
+    def to_s = @action == "inject" ? "GateDecision(inject, #{@output.inspect})" : "GateDecision(#{@action})"
+    alias inspect to_s
+  end
+
+  # Shared instance returned on every fast path (detached / nothing matching).
+  # Allocating nothing on the hot path is the whole point.
+  CONTINUE = GateDecision.new("continue")
+
+  # The logical node a gate belongs to. `instance_id`: the execution the gate
+  # holds (its node.started instanceId), when the caller knows it — sent as
+  # exec.paused.instanceId (0.6.0) so a debugger can tell parallel calls of one
+  # node apart. Breakpoints never match on it.
+  class GateNode
+    attr_reader :node_id, :kind, :name, :instance_id
+
+    def initialize(node_id, kind, name, instance_id = nil)
+      @node_id = node_id
+      @kind = kind
+      @name = name
+      @instance_id = instance_id
+      freeze
+    end
+
+    def to_s = "GateNode(#{@node_id}, #{@kind}, #{@name})"
+    alias inspect to_s
+  end
+
+  # One held gate. The waiting thread blocks in #wait; the transport thread
+  # calls #settle. A Mutex + ConditionVariable (rather than Queue#pop(timeout:))
+  # keeps the gem usable on Ruby 3.1.
+  class Hold
+    attr_reader :pause_id
+
+    def initialize(pause_id)
+      @pause_id = pause_id
+      @mutex = Mutex.new
+      @cv = ConditionVariable.new
+      @decision = nil
+    end
+
+    # Block up to `timeout` seconds. Returns the decision, or nil on timeout so
+    # the caller can re-check fail-open conditions.
+    def wait(timeout)
+      @mutex.synchronize do
+        @cv.wait(@mutex, timeout) if @decision.nil?
+        @decision
+      end
+    end
+
+    def settle(decision)
+      @mutex.synchronize do
+        return false unless @decision.nil?
+
+        @decision = decision
+        @cv.broadcast
+        true
+      end
+    end
+
+    def settled? = !@mutex.synchronize { @decision }.nil?
+  end
+
+  # Gate engine: cooperative pause points inside the instrumented process.
+  #
+  # Port of packages/client/src/gate-engine.ts, made thread-safe because a Ruby
+  # agent may be running on many threads at once (Puma, Sidekiq) while the
+  # transport lives on its own background thread.
+  #
+  # The session owns the decision of WHETHER to gate (attached? matching
+  # breakpoint? step mode?); this engine owns the bookkeeping of HELD gates:
+  # registration, resume routing, pause timeouts and fail-open release.
+  #
+  # Fail-open invariants:
+  #   * release_all releases every held gate with `continue` (on disconnect,
+  #     on dispose, and from the at_exit hook);
+  #   * an optional per-gate pause timeout auto-continues a gate nobody
+  #     resumes.
+  class GateEngine
+    def initialize(on_paused:, on_resumed:, new_pause_id:, pause_timeout: nil)
+      @on_paused = on_paused
+      @on_resumed = on_resumed
+      @new_pause_id = new_pause_id
+      @pause_timeout = pause_timeout
+      @mutex = Mutex.new
+      @breakpoints = []
+      @mode = "run"
+      @held = {}
+    end
+
+    # -- viewer state --------------------------------------------------------
+
+    # Adopt the viewer's full debug state (from hello.ack).
+    def arm(breakpoints, mode)
+      @mutex.synchronize do
+        @breakpoints = Array(breakpoints).select { |m| m.is_a?(Hash) }.map { |m| normalize(m) }
+        @mode = Protocol::RUN_MODES.include?(mode) ? mode : "run"
+      end
+    end
+
+    # Drop viewer state (on detach). Held gates are released separately.
+    def disarm
+      @mutex.synchronize do
+        @breakpoints = []
+        @mode = "run"
+      end
+    end
+
+    def mode = @mutex.synchronize { @mode }
+
+    def set_mode(mode)
+      return unless Protocol::RUN_MODES.include?(mode)
+
+      @mutex.synchronize { @mode = mode }
+    end
+
+    def add_breakpoint(matcher)
+      return unless matcher.is_a?(Hash)
+
+      normalized = normalize(matcher)
+      @mutex.synchronize do
+        @breakpoints << normalized unless @breakpoints.any? { |m| matcher_equals(m, normalized) }
+      end
+    end
+
+    def remove_breakpoint(matcher)
+      return unless matcher.is_a?(Hash)
+
+      normalized = normalize(matcher)
+      @mutex.synchronize do
+        @breakpoints = @breakpoints.reject { |m| matcher_equals(m, normalized) }
+      end
+    end
+
+    def breakpoints = @mutex.synchronize { @breakpoints.map(&:dup) }
+
+    # -- decisions -----------------------------------------------------------
+
+    # Step mode pauses at every before/error point; run mode only on a matching
+    # breakpoint (`after` always needs an explicit one — decisions.md #2).
+    def should_pause?(point, node)
+      @mutex.synchronize do
+        return true if @mode == "step" && point != "after"
+
+        @breakpoints.any? { |matcher| matcher_matches(matcher, point, node) }
+      end
+    end
+
+    # -- holds ---------------------------------------------------------------
+
+    # Register a held gate. Call only after #should_pause? (or for a built-in
+    # breakpoint such as the loop hold, whose details ride `reason` to
+    # on_paused — handed over per call, never shared between threads).
+    def hold(point, node, run_id, reason = nil)
+      pause_id = @new_pause_id.call
+      hold = Hold.new(pause_id)
+      timer = nil
+      @mutex.synchronize do
+        @held[pause_id] = { hold: hold, node: node, point: point, run_id: run_id }
+      end
+      if @pause_timeout
+        timer = Thread.new(pause_id) do |id|
+          sleep(@pause_timeout)
+          settle(id, CONTINUE, "continue")
+        end
+        timer.name = "graphmind-pause-timeout" if timer.respond_to?(:name=)
+        @mutex.synchronize { @held[pause_id][:timer] = timer if @held.key?(pause_id) }
+      end
+      # Emitted after registration so a resume racing back always finds the gate.
+      safely { @on_paused.call(pause_id, node, point, run_id, reason) }
+      hold
+    end
+
+    # Route a viewer exec.resume to its held gate. Unknown ids are ignored.
+    # `request_id` (0.6.0) is echoed on the exec.resumed this release emits.
+    def resume(pause_id, action, output = nil, request_id: nil)
+      return false unless Protocol::RESUME_ACTIONS.include?(action)
+
+      decision = action == "inject" ? GateDecision.new("inject", output) : GateDecision.new(action)
+      settle(pause_id, decision, action, request_id)
+    end
+
+    # A held gate as the session may inspect it — {pause_id:, node:, point:,
+    # run_id:}, a frozen copy — or nil when no gate has this id.
+    def peek(pause_id)
+      @mutex.synchronize do
+        entry = @held[pause_id]
+        next nil if entry.nil?
+
+        { pause_id: pause_id, node: entry[:node], point: entry[:point], run_id: entry[:run_id] }.freeze
+      end
+    end
+
+    # FAIL-OPEN: release every held gate with `continue`. Returns the count.
+    def release_all
+      ids = @mutex.synchronize { @held.keys }
+      ids.count { |pause_id| settle(pause_id, CONTINUE, "continue") }
+    end
+
+    # Drop a gate whose waiter gave up (fail-open poll, interrupt). Emits
+    # exec.resumed like any other release so the viewer's pause history stays
+    # reconstructable.
+    def discard(pause_id)
+      settle(pause_id, CONTINUE, "continue")
+    end
+
+    def held_count = @mutex.synchronize { @held.size }
+
+    # -- matching ------------------------------------------------------------
+
+    # Every present matcher field must match; absent fields match anything.
+    def matcher_matches(matcher, point, node)
+      return false if (matcher["point"] || "before") != point
+
+      kind = matcher["kind"]
+      return false if kind && kind != node.kind
+
+      name = matcher["name"]
+      name.nil? || name == node.name
+    end
+
+    def matcher_equals(a, b)
+      a["kind"] == b["kind"] && a["name"] == b["name"] && a["point"] == b["point"]
+    end
+
+    private
+
+    def normalize(matcher)
+      out = {}
+      %w[kind name point].each do |key|
+        value = matcher[key] || matcher[key.to_sym]
+        out[key] = value unless value.nil?
+      end
+      out
+    end
+
+    def settle(pause_id, decision, action, request_id = nil)
+      entry = @mutex.synchronize { @held.delete(pause_id) }
+      return false if entry.nil?
+
+      timer = entry[:timer]
+      timer.kill if timer && timer != Thread.current
+      # The callback and the wake-up happen OUTSIDE the lock: the waiting
+      # thread must never contend with the transport to get moving again.
+      released = entry[:hold].settle(decision)
+      safely { @on_resumed.call(pause_id, entry[:node], action, entry[:run_id], request_id) }
+      released
+    end
+
+    def safely
+      yield
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/graphmind/held_ledger.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require_relative "clock"
+
+module Graphmind
+  # Held-time ledger: how much of a node instance's wall-clock duration was the
+  # *debugger* holding it, rather than the node running.
+  #
+  # Port of packages/client/src/held-ledger.ts — read that file's header for
+  # the full rationale. In short: `durationMs` keeps its meaning (wall clock,
+  # held time INCLUDED, so stored runs and importers are unaffected) and the
+  # loose field `heldMs` on `node.finished` / `node.error` is the debugger's
+  # share; "ran" is `durationMs - heldMs`.
+  #
+  # Attribution pins a hold to one of the node's open instances when it opens:
+  #   * `before` / `error` gates -> the most recently started open instance
+  #     (for `error`, an instance `node.error` named is preferred);
+  #   * `after` gates -> the oldest open instance;
+  #   * no open instance -> not attributed (a hold that opens after an instance
+  #     finished is not inside that instance's `durationMs`).
+  # The hold is also pinned to every open *ancestor* instance (following the
+  # `parentId` from `node.started`) and to the run's root instance — the node
+  # whose `instanceId` is the `runId`, which is how every SDK emits the
+  # `agent:<run>` node. Each instance accumulates the UNION of the intervals
+  # during which at least one hold pinned to it was open, so two children held
+  # at the same time do not count twice in their parent.
+  #
+  # Exact whenever executions of one logical node do not overlap; a documented
+  # heuristic for overlapping instances of the same node.
+  #
+  # Thread-safe (one mutex, never held while calling out), bounded, never raises.
+  class HeldLedger
+    DEFAULT_MAX_TRACKED_INSTANCES = 10_000
+    MAX_DEPTH = 64
+
+    Instance = Struct.new(:key, :node_key, :instance_id, :held_ms, :open_holds, :held_since, :errored)
+
+    def initialize(max_instances: DEFAULT_MAX_TRACKED_INSTANCES, clock: nil)
+      @max = [1, max_instances.to_i].max
+      @clock = clock || -> { Clock.now_ms }
+      @mutex = Mutex.new
+      @instances = {}      # key -> Instance, insertion-ordered (oldest first)
+      @by_node = {}        # [run_id, node_id] -> [Instance] in start order
+      @parent_by_node = {} # [run_id, node_id] -> parent node_id
+      @root_by_run = {}    # run_id -> Instance whose instance_id == run_id
+      @holds = {}          # pause_id -> [Instance] (target first, then ancestors)
+    end
+
+    # -- instance lifecycle --------------------------------------------------
+
+    def started(run_id, node_id, instance_id, parent_id = nil)
+      node_key = [run_id, node_id]
+      key = [run_id, node_id, instance_id]
+      @mutex.synchronize do
+        existing = @instances[key]
+        remove(existing) if existing
+        remove(@instances.values.first) if @instances.size >= @max
+        @parent_by_node.clear if @parent_by_node.size >= @max * 4
+        @parent_by_node[node_key] = parent_id if parent_id.is_a?(String) && parent_id != node_id
+        instance = Instance.new(key, node_key, instance_id, 0.0, 0, 0.0, false)
+        @instances[key] = instance
+        @root_by_run[run_id] = instance if instance_id == run_id
+        (@by_node[node_key] ||= []) << instance
+      end
+      nil
+    end
+
+    def errored(run_id, node_id, instance_id)
+      @mutex.synchronize do
+        instance = pick(run_id, node_id, instance_id)
+        instance.errored = true if instance
+      end
+      nil
+    end
+
+    # Held so far for an open instance (a hold open right now included); nil when unknown.
+    def peek(run_id, node_id, instance_id)
+      now = @clock.call
+      @mutex.synchronize do
+        instance = pick(run_id, node_id, instance_id)
+        instance && total(instance, now)
+      end
+    end
+
+    # Close the instance and return its held total; nil when unknown. A hold
+    # still open against it is credited up to now (that time IS inside the
+    # `durationMs` just measured) and unpinned from it.
+    def finished(run_id, node_id, instance_id)
+      now = @clock.call
+      @mutex.synchronize do
+        instance = pick(run_id, node_id, instance_id)
+        return nil unless instance
+
+        held = total(instance, now)
+        remove(instance)
+        held
+      end
+    end
+
+    # -- holds ---------------------------------------------------------------
+
+    def hold_opened(pause_id, run_id, node_id, point)
+      now = @clock.call
+      @mutex.synchronize do
+        instances = @by_node[[run_id, node_id]]
+        target = nil
+        if instances && !instances.empty?
+          if point == "after"
+            target = instances.first
+          else
+            target = instances.reverse.find(&:errored) if point == "error"
+            target ||= instances.last
+            target.errored = false if point == "error" # one hold per failure
+          end
+        end
+        # No open instance of the held node (a callback-style after/error gate
+        # fires AFTER node.finished): the hold is outside every instance of this
+        # node's durationMs and must not be charged to the next one — but the
+        # open ancestors and the run root are still running while the developer
+        # looks, and it IS inside theirs.
+        pinned = target ? [target] : []
+        # Ancestors: the newest open instance of each parent up the chain.
+        current = [run_id, node_id]
+        seen = { current => true }
+        MAX_DEPTH.times do
+          parent_id = @parent_by_node[current]
+          break if parent_id.nil?
+
+          parent_key = [run_id, parent_id]
+          break if seen[parent_key]
+
+          seen[parent_key] = true
+          parents = @by_node[parent_key]
+          pinned << parents.last if parents && !parents.empty?
+          current = parent_key
+        end
+        root = @root_by_run[run_id]
+        pinned << root if root && pinned.none? { |i| i.equal?(root) }
+        return nil if pinned.empty?
+
+        pinned.each do |instance|
+          instance.held_since = now if instance.open_holds.zero?
+          instance.open_holds += 1
+        end
+        @holds[pause_id] = pinned
+      end
+      nil
+    end
+
+    def hold_closed(pause_id)
+      now = @clock.call
+      @mutex.synchronize do
+        pinned = @holds.delete(pause_id)
+        pinned&.each { |instance| release(instance, now) }
+      end
+      nil
+    end
+
+    # -- diagnostics ---------------------------------------------------------
+
+    def tracked_instances = @mutex.synchronize { @instances.size }
+    def open_holds = @mutex.synchronize { @holds.size }
+
+    private
+
+    # Call with the mutex held.
+
+    def total(instance, now)
+      open_ms = instance.open_holds.positive? ? [0.0, now - instance.held_since].max : 0.0
+      Clock.normalize_duration_ms(instance.held_ms + open_ms)
+    end
+
+    def release(instance, now)
+      return if instance.open_holds.zero?
+
+      instance.open_holds -= 1
+      instance.held_ms += [0.0, now - instance.held_since].max if instance.open_holds.zero?
+    end
+
+    # Exact instance when named; otherwise the newest open one for the node.
+    def pick(run_id, node_id, instance_id)
+      instances = @by_node[[run_id, node_id]]
+      return nil if instances.nil? || instances.empty?
+      # An unknown instanceId is not "the newest one".
+      return @instances[[run_id, node_id, instance_id]] unless instance_id.nil?
+
+      instances.last
+    end
+
+    def remove(instance)
+      @instances.delete(instance.key)
+      run_id = instance.node_key[0]
+      @root_by_run.delete(run_id) if @root_by_run[run_id].equal?(instance)
+      siblings = @by_node[instance.node_key]
+      if siblings
+        siblings.delete_if { |i| i.equal?(instance) }
+        @by_node.delete(instance.node_key) if siblings.empty?
+      end
+      return unless instance.open_holds.positive?
+
+      @holds.each_key.to_a.each do |pause_id|
+        pinned = @holds[pause_id]
+        pinned.delete_if { |i| i.equal?(instance) }
+        @holds.delete(pause_id) if pinned.empty?
+      end
+      instance.open_holds = 0
+    end
+  end
+end

data/lib/graphmind/ids.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Graphmind
+  # Node identity (internal/decisions.md #1) and compact unique ids.
+  #
+  # `node_id` is stable per LOGICAL node, so the canvas renders one node per
+  # code location; `instance_id` distinguishes repeated executions. Concurrent
+  # executions of the same logical node are told apart purely by instance id —
+  # which is why every node.started / node.finished / node.error this gem
+  # emits carries one.
+  module Ids
+    # The single logical LLM node of a provider-SDK agent loop. Matches the
+    # TypeScript and Python adapters so the viewer renders every language's
+    # runs identically.
+    LLM_NODE_ID = "llm:step"
+    LLM_NODE_NAME = "step"
+
+    @mutex = Mutex.new
+    @pid = Process.pid
+    @base = SecureRandom.hex(3)
+    @counter = 0
+
+    module_function
+
+    def tool_node_id(name)  = "tool:#{name}"
+    def agent_node_id(name) = "agent:#{name}"
+    def llm_node_id(name)   = "llm:#{name}"
+    def chain_node_id(name) = "chain:#{name}"
+
+    # Globally unique id (runs).
+    def new_id(prefix)
+      "#{prefix}_#{SecureRandom.hex(6)}"
+    end
+
+    # Compact per-process unique id (pauses, node instances). Re-seeded after a
+    # fork so a Puma/Unicorn worker cannot mint ids that collide with its
+    # parent's.
+    def next_id(prefix)
+      @mutex.synchronize do
+        if @pid != Process.pid
+          @pid = Process.pid
+          @base = SecureRandom.hex(3)
+          @counter = 0
+        end
+        @counter += 1
+        "#{prefix}_#{@base}_#{@counter}"
+      end
+    end
+  end
+end