vsm 0.1.0 → 0.2.0

data/lib/vsm/mcp/client.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+require "open3"
+require "shellwords"
+require_relative "jsonrpc"
+
+module VSM
+  module MCP
+    class Client
+      attr_reader :name
+
+      def initialize(cmd:, env: {}, cwd: nil, name: nil)
+        @cmd, @env, @cwd, @name = cmd, env, cwd, (name || cmd.split.first)
+        @stdin = @stdout = @stderr = @wait_thr = nil
+        @rpc = nil
+        @stderr_thread = nil
+      end
+
+      def start
+        opts = {}
+        opts[:chdir] = @cwd if @cwd
+        args = @cmd.is_a?(Array) ? @cmd : Shellwords.split(@cmd.to_s)
+        @stdin, @stdout, @stderr, @wait_thr = Open3.popen3(@env || {}, *args, **opts)
+        # Drain stderr to avoid blocking if the server writes logs
+        @stderr_thread = Thread.new do
+          begin
+            @stderr.each_line { |_line| }
+          rescue StandardError
+          end
+        end
+        @rpc = JSONRPC::Stdio.new(r: @stdout, w: @stdin)
+        self
+      end
+
+      def stop
+        begin
+          @stdin&.close
+        rescue StandardError
+        end
+        begin
+          @stdout&.close
+        rescue StandardError
+        end
+        begin
+          @stderr&.close
+        rescue StandardError
+        end
+        begin
+          @stderr_thread&.kill
+        rescue StandardError
+        end
+        begin
+          @wait_thr&.kill
+        rescue StandardError
+        end
+        nil
+      end
+
+      # Returns Array<Hash> with symbol keys: :name, :description, :input_schema
+      def list_tools
+        raw = @rpc.request("tools/list")
+        arr = (raw && raw["tools"]) || []
+        arr.map do |t|
+          {
+            name: t["name"].to_s,
+            description: t["description"].to_s,
+            input_schema: (t["input_schema"] || {})
+          }
+        end
+      end
+
+      # Returns a String (first text content) or a JSON string fallback
+      def call_tool(name:, arguments: {})
+        res = @rpc.request("tools/call", { "name" => name, "arguments" => arguments })
+        content = Array(res["content"])
+        item = content.find { |c| c["type"] == "text" } || content.first
+        item ? (item["text"] || item.to_s) : res.to_s
+      end
+    end
+  end
+end

data/lib/vsm/mcp/jsonrpc.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+require "json"
+require "monitor"
+
+module VSM
+  module MCP
+    module JSONRPC
+      # Minimal NDJSON (one JSON per line) JSON-RPC transport over IO.
+      # Note: MCP servers often speak LSP framing; we can add that later.
+      class Stdio
+        include MonitorMixin
+
+        def initialize(r:, w:)
+          @r = r
+          @w = w
+          @seq = 0
+          mon_initialize
+        end
+
+        def request(method, params = {})
+          id = next_id
+          write({ jsonrpc: "2.0", id: id, method: method, params: params })
+          loop do
+            msg = read
+            next unless msg
+            if msg["id"].to_s == id.to_s
+              err = msg["error"]
+              raise(err.is_a?(Hash) ? (err["message"] || err.inspect) : err.to_s) if err
+              return msg["result"]
+            end
+          end
+        end
+
+        def notify(method, params = {})
+          write({ jsonrpc: "2.0", method: method, params: params })
+        end
+
+        def read
+          line = @r.gets
+          return nil unless line
+          # Handle LSP-style framing: "Content-Length: N" followed by blank line and JSON body.
+          if line =~ /\AContent-Length:\s*(\d+)\s*\r?\n?\z/i
+            length = Integer($1)
+            # Consume optional additional headers until blank line
+            while (hdr = @r.gets)
+              break if hdr.strip.empty?
+            end
+            body = read_exact(length)
+            $stderr.puts("[mcp-rpc] < #{body}") if ENV["VSM_MCP_DEBUG"] == "1"
+            return JSON.parse(body)
+          end
+          # Otherwise assume NDJSON (one JSON object per line)
+          $stderr.puts("[mcp-rpc] < #{line.strip}") if ENV["VSM_MCP_DEBUG"] == "1"
+          JSON.parse(line)
+        end
+
+        def write(obj)
+          body = JSON.dump(obj)
+          $stderr.puts("[mcp-rpc] > #{body}") if ENV["VSM_MCP_DEBUG"] == "1"
+          synchronize do
+            # Prefer NDJSON for broad compatibility; some servers require LSP.
+            # If VSM_MCP_LSP=1, use Content-Length framing.
+            if ENV["VSM_MCP_LSP"] == "1"
+              @w.write("Content-Length: #{body.bytesize}\r\n\r\n")
+              @w.write(body)
+              @w.flush
+            else
+              @w.puts(body)
+              @w.flush
+            end
+          end
+        end
+
+        private
+
+        def next_id
+          synchronize { @seq += 1; @seq.to_s }
+        end
+
+        def read_exact(n)
+          data = +""
+          while data.bytesize < n
+            chunk = @r.read(n - data.bytesize)
+            break unless chunk
+            data << chunk
+          end
+          data
+        end
+      end
+    end
+  end
+end

data/lib/vsm/mcp/remote_tool_capsule.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+module VSM
+  module MCP
+    class RemoteToolCapsule < VSM::ToolCapsule
+      attr_writer :bus
+
+      def initialize(client:, remote_name:, descriptor:)
+        @client = client
+        @remote_name = remote_name
+        @descriptor = descriptor # { name:, description:, input_schema: }
+      end
+
+      def tool_descriptor
+        VSM::Tool::Descriptor.new(
+          name:        @descriptor[:name],
+          description: @descriptor[:description],
+          schema:      @descriptor[:input_schema]
+        )
+      end
+
+      def execution_mode
+        :thread
+      end
+
+      def run(args)
+        @bus&.emit VSM::Message.new(kind: :progress, payload: "mcp call #{@client.name}.#{@remote_name}", path: [:mcp, :client, @client.name, @remote_name])
+        out = @client.call_tool(name: @remote_name, arguments: args || {})
+        @bus&.emit VSM::Message.new(kind: :progress, payload: "mcp result #{@client.name}.#{@remote_name}", path: [:mcp, :client, @client.name, @remote_name])
+        out.to_s
+      rescue => e
+        "ERROR: #{e.class}: #{e.message}"
+      end
+    end
+  end
+end

data/lib/vsm/meta/snapshot_builder.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+require_relative "support"
+
+module VSM
+  module Meta
+    class SnapshotBuilder
+      ROLE_METHOD_HINTS = {
+        identity: %i[handle alert observe initialize],
+        governance: %i[enforce observe initialize],
+        coordination: %i[stage drain order grant_floor! wait_for_turn_end initialize],
+        operations: %i[handle observe initialize],
+        intelligence: %i[handle system_prompt offer_tools? initialize],
+        monitoring: %i[observe handle initialize]
+      }.freeze
+
+      def initialize(root:)
+        @root = root
+      end
+
+      def call
+        snapshot_capsule(@root, path: [@root.name.to_s])
+      end
+
+      private
+
+      def snapshot_capsule(capsule, path:)
+        {
+          kind: "capsule",
+          name: capsule.name.to_s,
+          class: capsule.class.name,
+          path: path.dup,
+          roles: snapshot_roles(capsule.roles),
+          operations: snapshot_operations(capsule.children, path: path),
+          meta: {}
+        }
+      end
+
+      def snapshot_roles(roles)
+        roles.each_with_object({}) do |(role_name, role_instance), acc|
+          acc[role_name.to_s] = snapshot_role(role_name, role_instance)
+        end
+      end
+
+      def snapshot_role(role_name, role_instance)
+        {
+          class: role_instance.class.name,
+          constructor_args: Support.fetch_constructor_args(role_instance),
+          source_locations: method_locations(role_instance.class, ROLE_METHOD_HINTS[role_name] || %i[initialize]),
+          summary: nil
+        }
+      end
+
+      def snapshot_operations(children, path:)
+        return { children: {} } if children.nil? || children.empty?
+
+        ops = {}
+        children.each do |name, child|
+          ops[name.to_s] = snapshot_child(child, path: path + [name.to_s])
+        end
+        { children: ops }
+      end
+
+      def snapshot_child(child, path:)
+        base = {
+          name: path.last,
+          class: child.class.name,
+          path: path,
+          constructor_args: Support.fetch_constructor_args(child),
+          source_locations: [],
+          roles: nil,
+          operations: nil
+        }
+
+        if child.respond_to?(:roles) && child.respond_to?(:children)
+          base[:kind] = "capsule"
+          base[:roles] = snapshot_roles(child.roles)
+          base[:operations] = snapshot_operations(child.children || {}, path: path)
+          base[:source_locations] = method_locations(child.class, %i[initialize])
+        elsif child.respond_to?(:tool_descriptor)
+          base[:kind] = "tool"
+          descriptor = child.tool_descriptor
+          base[:tool] = {
+            name: descriptor.name,
+            description: descriptor.description,
+            schema: descriptor.schema
+          }
+          base[:source_locations] = method_locations(child.class, %i[run execution_mode initialize])
+        else
+          base[:kind] = "object"
+          base[:source_locations] = method_locations(child.class, %i[initialize])
+        end
+
+        base
+      end
+
+      def method_locations(klass, candidates)
+        candidates.filter_map do |meth|
+          next unless klass.instance_methods.include?(meth)
+          location = klass.instance_method(meth).source_location
+          next if location.nil?
+          { method: meth.to_s, path: relative_path(location[0]), line: location[1] }
+        rescue NameError
+          nil
+        end
+      end
+
+      def relative_path(path)
+        return path if path.nil?
+        root = Pathname.new(Dir.pwd)
+        begin
+          Pathname.new(path).relative_path_from(root).to_s
+        rescue ArgumentError
+          path
+        end
+      end
+    end
+  end
+end

data/lib/vsm/meta/snapshot_cache.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "thread"
+
+module VSM
+  module Meta
+    class SnapshotCache
+      def initialize(builder)
+        @builder = builder
+        @mutex = Mutex.new
+        @snapshot = nil
+      end
+
+      def fetch
+        @mutex.synchronize do
+          @snapshot ||= { generated_at: Time.now.utc, data: @builder.call }
+        end
+      end
+
+      def invalidate!
+        @mutex.synchronize { @snapshot = nil }
+      end
+    end
+  end
+end

data/lib/vsm/meta/support.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module VSM
+  module Meta
+    module Support
+      CONFIG_IVAR = :@__vsm_constructor_args
+
+      module_function
+
+      def record_constructor_args(instance, args)
+        copied = copy_args(args)
+        instance.instance_variable_set(CONFIG_IVAR, copied)
+        instance
+      end
+
+      def fetch_constructor_args(instance)
+        instance.instance_variable_get(CONFIG_IVAR)
+      end
+
+      def copy_args(args)
+        return {} if args.nil?
+        case args
+        when Hash
+          args.transform_values { copy_args(_1) }
+        when Array
+          args.map { copy_args(_1) }
+        when Symbol, Numeric, NilClass, TrueClass, FalseClass
+          args
+        else
+          args.dup rescue args
+        end
+      end
+    end
+  end
+end