vsm 0.1.0 → 0.2.0

data/lib/vsm/async_channel.rb

@@ -11,11 +11,34 @@ module VSM
     end
 
     def emit(message)
-      @queue.enqueue(message)
-      @subs.each { |blk| Async { blk.call(message) } }
+      begin
+        @queue.enqueue(message)
+      rescue StandardError
+        # If no async scheduler is available in this thread, best-effort enqueue later.
+      end
+      @subs.each do |blk|
+        begin
+          Async { blk.call(message) }
+        rescue StandardError
+          # Fallback when no Async task is active in this thread
+          begin
+            blk.call(message)
+          rescue StandardError
+            # ignore subscriber errors
+          end
+        end
+      end
     end
 
     def pop = @queue.dequeue
-    def subscribe(&blk) = @subs << blk
+
+    def subscribe(&blk)
+      @subs << blk
+      blk
+    end
+
+    def unsubscribe(subscriber)
+      @subs.delete(subscriber)
+    end
   end
 end

data/lib/vsm/capsule.rb

@@ -11,6 +11,8 @@ module VSM
       ctx = { operations_children: children.transform_keys(&:to_s) }
       @bus = AsyncChannel.new(context: ctx)
       @homeostat = Homeostat.new
+      # Inject bus into children that accept it, to enable richer observability
+      @children.each_value { |c| c.bus = @bus if c.respond_to?(:bus=) }
       wire_observers!
     end
 

data/lib/vsm/cli.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'optparse'
+require_relative 'generator/new_project'
+
+module VSM
+  class CLI
+    def self.start(argv = ARGV)
+      new.run(argv)
+    end
+
+    def run(argv)
+      cmd = argv.shift
+      case cmd
+      when 'new'
+        run_new(argv)
+      when nil, '-h', '--help', 'help'
+        puts help_text
+      else
+        warn "Unknown command: #{cmd}\n"
+        puts help_text
+        exit 1
+      end
+    end
+
+    private
+
+    def run_new(argv)
+      opts = {
+        path: nil,
+        git: false,
+        bundle: false,
+        provider: 'openai',
+        model: nil,
+        force: false
+      }
+      parser = OptionParser.new do |o|
+        o.banner = "Usage: vsm new <name> [options]"
+        o.on('--path PATH', 'Target directory (default: ./<name>)') { |v| opts[:path] = v }
+        o.on('--git', 'Run git init and initial commit') { opts[:git] = true }
+        o.on('--bundle', 'Run bundle install after generation') { opts[:bundle] = true }
+        o.on('--with-llm PROVIDER', %w[openai anthropic gemini], 'LLM provider: openai (default), anthropic, or gemini') { |v| opts[:provider] = v }
+        o.on('--model NAME', 'Default model name') { |v| opts[:model] = v }
+        o.on('--force', 'Overwrite existing directory') { opts[:force] = true }
+        o.on('-h', '--help', 'Show help') { puts o; exit 0 }
+      end
+
+      name = nil
+      begin
+        parser.order!(argv)
+        name = argv.shift
+      rescue OptionParser::ParseError => e
+        warn e.message
+        puts parser
+        exit 1
+      end
+
+      unless name && !name.strip.empty?
+        warn 'Please provide a project name, e.g., vsm new my_app'
+        puts parser
+        exit 1
+      end
+
+      VSM::Generator::NewProject.run(name: name, **opts)
+    end
+
+    def help_text
+      <<~TXT
+        VSM CLI
+
+        Commands:
+          vsm new <name> [options]   Create a new VSM app skeleton
+
+        Run `vsm new --help` for options.
+      TXT
+    end
+  end
+end

data/lib/vsm/dsl.rb

@@ -1,4 +1,6 @@
 # frozen_string_literal: true
+
+require_relative "meta"
 module VSM
   module DSL
     class Builder
@@ -6,40 +8,69 @@ module VSM
         @name = name
         @roles = {}
         @children = {}
+        @after_build = []
       end
 
-      def identity(klass: VSM::Identity, args: {})     = (@roles[:identity]     = klass.new(**args))
-      def governance(klass: VSM::Governance, args: {}) = (@roles[:governance]   = klass.new(**args))
-      def coordination(klass: VSM::Coordination, args: {}) = (@roles[:coordination] = klass.new(**args))
-      def intelligence(klass: VSM::Intelligence, args: {}) = (@roles[:intelligence] = klass.new(**args))
+      def identity(klass: VSM::Identity, args: {})     = assign_role(:identity, klass, args)
+      def governance(klass: VSM::Governance, args: {}) = assign_role(:governance, klass, args)
+      def coordination(klass: VSM::Coordination, args: {}) = assign_role(:coordination, klass, args)
+      def intelligence(klass: VSM::Intelligence, args: {}) = assign_role(:intelligence, klass, args)
       def operations(klass: VSM::Operations, args: {}, &blk)
-        @roles[:operations] = klass.new(**args)
+        @roles[:operations] = instantiate(klass, args)
         if blk
-          builder = ChildrenBuilder.new
+          builder = ChildrenBuilder.new(self)
           builder.instance_eval(&blk)
           @children.merge!(builder.result)
         end
       end
 
-      def monitoring(klass: VSM::Monitoring, args: {}) = (@roles[:monitoring] = klass.new(**args))
+      def monitoring(klass: VSM::Monitoring, args: {}) = assign_role(:monitoring, klass, args)
 
       def build
         # Inject governance into tool capsules if they accept it
         @children.each_value do |child|
           child.governance = @roles[:governance] if child.respond_to?(:governance=)
         end
-        VSM::Capsule.new(name: @name, roles: @roles, children: @children)
+        capsule = VSM::Capsule.new(name: @name, roles: @roles, children: @children)
+        @after_build.each { _1.call(capsule) }
+        capsule
       end
 
       class ChildrenBuilder
-        def initialize; @children = {}; end
+        def initialize(parent)
+          @parent = parent
+          @children = {}
+        end
         def capsule(name, klass:, args: {})
-          @children[name.to_s] = klass.new(**args)
+          instance = klass.new(**args)
+          VSM::Meta::Support.record_constructor_args(instance, args)
+          @children[name.to_s] = instance
+        end
+        def meta_tools(prefix: "", only: nil, except: nil)
+          @parent.__send__(:after_build) do |capsule|
+            VSM::Meta.attach!(capsule, prefix: prefix, only: only, except: except)
+          end
+          result
         end
         def result = @children
         def method_missing(*) = result
         def respond_to_missing?(*) = true
       end
+
+      private
+
+      def after_build(&block)
+        @after_build << block if block
+      end
+
+      def assign_role(key, klass, args)
+        @roles[key] = instantiate(klass, args)
+      end
+
+      def instantiate(klass, args)
+        instance = klass.new(**args)
+        VSM::Meta::Support.record_constructor_args(instance, args)
+      end
     end
 
     def self.define(name, &blk)
@@ -47,4 +78,3 @@ module VSM
     end
   end
 end
-

data/lib/vsm/dsl_mcp.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+require_relative "dsl"
+require_relative "mcp/client"
+require_relative "mcp/remote_tool_capsule"
+
+module VSM
+  module DSL
+    class Builder
+      class ChildrenBuilder
+        # Reflect tools from a remote MCP server and add them as tool capsules.
+        # Options:
+        #   include: Array<String> whitelist of tool names
+        #   exclude: Array<String> blacklist of tool names
+        #   prefix:  String prefix for local names to avoid collisions
+        #   env:     Hash environment passed to the server process
+        #   cwd:     Working directory for spawning the process
+        #
+        # Example:
+        #   mcp_server :smith, cmd: "smith-server --stdio", include: %w[search read], prefix: "smith_"
+        def mcp_server(name, cmd:, env: {}, include: nil, exclude: nil, prefix: nil, cwd: nil)
+          client = VSM::MCP::Client.new(cmd: cmd, env: env, cwd: cwd, name: name.to_s).start
+          tools  = client.list_tools
+          tools.each do |t|
+            tool_name = t[:name]
+            next if include && !Array(include).include?(tool_name)
+            next if exclude &&  Array(exclude).include?(tool_name)
+            local_name = [prefix, tool_name].compact.join
+            capsule = VSM::MCP::RemoteToolCapsule.new(client: client, remote_name: tool_name, descriptor: t)
+            @children[local_name] = capsule
+          end
+        end
+      end
+    end
+  end
+end
+

data/lib/vsm/generator/new_project.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require 'erb'
+require 'fileutils'
+require 'pathname'
+require_relative '../version'
+
+module VSM
+  module Generator
+    class NewProject
+      TemplateRoot = File.expand_path('templates', __dir__)
+
+      def self.run(name:, path: nil, git: false, bundle: false, provider: 'openai', model: nil, force: false)
+        new(name: name, path: path, git: git, bundle: bundle, provider: provider, model: model, force: force).run
+      end
+
+      def initialize(name:, path:, git:, bundle:, provider:, model:, force:)
+        @input_name = name
+        @target_dir = File.expand_path(path || name)
+        @git = git
+        @bundle = bundle
+        @provider = provider
+        @model = model
+        @force = force
+      end
+
+      def run
+        prepare_target_dir!
+
+        # Create directory tree
+        mkdirs(
+          'exe',
+          'bin',
+          "lib/#{lib_name}",
+          "lib/#{lib_name}/ports",
+          "lib/#{lib_name}/tools"
+        )
+
+        # Render files
+        write('README.md', render('README_md.erb'))
+        write('.gitignore', render('gitignore.erb'))
+        write('Gemfile', render('Gemfile.erb'))
+        write('Rakefile', render('Rakefile.erb'))
+        write("#{lib_name}.gemspec", render('gemspec.erb'))
+
+        write("exe/#{exe_name}", render('exe_name.erb'), mode: 0o755)
+        write('bin/console', render('bin_console.erb'), mode: 0o755)
+        write('bin/setup', render('bin_setup.erb'), mode: 0o755)
+
+        write("lib/#{lib_name}.rb", render('lib_name_rb.erb'))
+        write("lib/#{lib_name}/version.rb", render('lib_version_rb.erb'))
+        write("lib/#{lib_name}/organism.rb", render('lib_organism_rb.erb'))
+        write("lib/#{lib_name}/ports/chat_tty.rb", render('lib_ports_chat_tty_rb.erb'))
+        write("lib/#{lib_name}/tools/read_file.rb", render('lib_tools_read_file_rb.erb'))
+
+        post_steps
+
+        puts <<~DONE
+          
+          Created #{module_name} in #{@target_dir}
+          
+          Next steps:
+            cd #{relative_target}
+            bundle install
+            bundle exec exe/#{exe_name}
+          
+          Add tools in lib/#{lib_name}/tools and customize banner in lib/#{lib_name}/ports/chat_tty.rb.
+      DONE
+      end
+
+      private
+
+      def mkdirs(*dirs)
+        dirs.each { |d| FileUtils.mkdir_p(File.join(@target_dir, d)) }
+      end
+
+      def write(rel, content, mode: nil)
+        full = File.join(@target_dir, rel)
+        FileUtils.mkdir_p(File.dirname(full))
+        File.write(full, content)
+        File.chmod(mode, full) if mode
+      end
+
+      def render(template_name)
+        template_path = File.join(TemplateRoot, template_name)
+        erb = ERB.new(File.read(template_path), trim_mode: '-')
+        erb.result(binding)
+      end
+
+      def post_steps
+        Dir.chdir(@target_dir) do
+          if @git
+            system('git', 'init')
+            system('git', 'add', '-A')
+            system('git', 'commit', '-m', 'init')
+          end
+          if @bundle
+            system('bundle', 'install')
+          end
+        end
+      end
+
+      def prepare_target_dir!
+        if Dir.exist?(@target_dir)
+          if !@force && !(Dir.children(@target_dir) - %w[. ..]).empty?
+            raise "Target directory already exists and is not empty: #{@target_dir} (use --force to overwrite)"
+          end
+        else
+          FileUtils.mkdir_p(@target_dir)
+        end
+      end
+
+      # --- Template helpers (available via binding) ---
+
+      def module_name
+        @module_name ||= @input_name.split(/[-_]/).map { |p| p.gsub(/[^a-zA-Z0-9]/, '').capitalize }.join
+      end
+
+      def lib_name
+        @lib_name ||= @input_name.downcase.gsub('-', '_')
+      end
+
+      def exe_name
+        @exe_name ||= @input_name.downcase.gsub('_', '-')
+      end
+
+      def env_prefix
+        @env_prefix ||= @input_name.gsub('-', '_').upcase
+      end
+
+      def vsm_version_constraint
+        parts = Vsm::VERSION.split('.')
+        "~> #{parts[0]}.#{parts[1]}"
+      end
+
+      def provider
+        (@provider || 'openai').downcase
+      end
+
+      def default_model
+        return @model if @model && !@model.empty?
+        case provider
+        when 'anthropic' then 'claude-3-5-sonnet-latest'
+        when 'gemini'    then 'gemini-2.0-flash'
+        else 'gpt-4o-mini'
+        end
+      end
+
+      def relative_target
+        Pathname.new(@target_dir).relative_path_from(Pathname.new(Dir.pwd)).to_s rescue @target_dir
+      end
+    end
+  end
+end

data/lib/vsm/generator/templates/Gemfile.erb

@@ -0,0 +1,9 @@
+source "https://rubygems.org"
+
+gem "vsm", "<%= vsm_version_constraint %>"
+
+group :development do
+  gem "rake"
+  gem "rspec"
+end
+

data/lib/vsm/generator/templates/README_md.erb

@@ -0,0 +1,40 @@
+# <%= module_name %>
+
+A minimal VSM app scaffold. Starts a capsule with a ChatTTY interface, an LLM-backed intelligence (OpenAI by default), and a `read_file` tool.
+
+## Quickstart
+
+```bash
+bundle install
+OPENAI_API_KEY=... bundle exec exe/<%= exe_name %>
+```
+
+Ask the assistant questions, or request reading a file, e.g.:
+
+```
+read README.md
+```
+
+You can customize the banner and prompt in `lib/<%= lib_name %>/ports/chat_tty.rb` and add tools under `lib/<%= lib_name %>/tools`.
+
+## LLM Configuration
+
+This scaffold includes LLM wiring. Configure provider via env vars (or choose at generation time):
+
+- `<%= env_prefix %>_PROVIDER` — `openai` (default), `anthropic`, or `gemini`
+- `<%= env_prefix %>_MODEL` — defaults to `<%= default_model %>` if not set
+- API key env var depends on provider:
+  - `OPENAI_API_KEY`
+  - `ANTHROPIC_API_KEY`
+  - `GEMINI_API_KEY`
+
+Run:
+
+```bash
+<%= env_prefix %>_PROVIDER=<%= provider %> <%= env_prefix %>_MODEL=<%= default_model %> \
+OPENAI_API_KEY=... bundle exec exe/<%= exe_name %>
+```
+
+## Lens (optional)
+
+Set `VSM_LENS=1` to launch the Lens UI and print its URL. You can change `VSM_LENS_PORT` and provide `VSM_LENS_TOKEN`.

data/lib/vsm/generator/templates/Rakefile.erb

@@ -0,0 +1,5 @@
+require "bundler/gem_tasks"
+task :default do
+  sh "bundle exec rspec" if File.exist?("spec")
+end
+

data/lib/vsm/generator/templates/bin_console.erb

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup" if File.exist?(File.expand_path("../Gemfile", __dir__))
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "<%= lib_name %>"
+
+puts "Starting console with <%= module_name %> loaded"
+require 'irb'
+IRB.start
+

data/lib/vsm/generator/templates/bin_setup.erb

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+bundle install
+
+echo "OK"
+

data/lib/vsm/generator/templates/exe_name.erb

@@ -0,0 +1,34 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Keep CLI independent of any project's Bundler context.
+ENV.delete('BUNDLE_GEMFILE')
+ENV.delete('BUNDLE_BIN_PATH')
+if (rubyopt = ENV['RUBYOPT'])
+  ENV['RUBYOPT'] = rubyopt.split.reject { |x| x.include?('bundler/setup') }.join(' ')
+end
+ENV.delete('RUBYGEMS_GEMDEPS')
+
+$stdout.sync = true
+$stderr.sync = true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "vsm"
+require "<%= lib_name %>"
+
+capsule = <%= module_name %>::Organism.build
+
+hub = nil
+if ENV["VSM_LENS"] == "1"
+  hub = VSM::Lens.attach!(
+    capsule,
+    host: "127.0.0.1",
+    port: (ENV["VSM_LENS_PORT"] || 9292).to_i,
+    token: ENV["VSM_LENS_TOKEN"]
+  )
+  puts "Lens: http://127.0.0.1:#{ENV['VSM_LENS_PORT'] || 9292}"
+end
+
+port = <%= module_name %>::Ports::ChatTTY.new(capsule: capsule)
+VSM::Runtime.start(capsule, ports: [port])
+

data/lib/vsm/generator/templates/gemspec.erb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "lib/<%= lib_name %>/version"
+
+Gem::Specification.new do |spec|
+  spec.name        = "<%= lib_name %>"
+  spec.version     = <%= module_name %>::VERSION
+  spec.authors     = ["Your Name"]
+  spec.email       = ["you@example.com"]
+
+  spec.summary     = "VSM app scaffold"
+  spec.description = "A minimal VSM-based agent app with ChatTTY and sample tools."
+  spec.license     = "MIT"
+
+  spec.required_ruby_version = ">= 3.2"
+
+  spec.files       = Dir.chdir(File.expand_path(__dir__)) do
+    Dir["{bin,exe,lib}/**/*", "README.md", "LICENSE.txt", "Rakefile", "Gemfile"].select { |f| File.file?(f) }
+  end
+  spec.bindir      = "exe"
+  spec.executables = ["<%= exe_name %>"]
+  spec.require_paths = ["lib"]
+end
+

data/lib/vsm/generator/templates/gitignore.erb

@@ -0,0 +1,10 @@
+.bundle/
+vendor/bundle/
+pkg/
+.vsm.log.jsonl
+*.gem
+.DS_Store
+/.ruby-version
+/.ruby-gemset
+/.env
+

data/lib/vsm/generator/templates/lib_name_rb.erb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "vsm"
+require_relative "<%= lib_name %>/organism"
+require_relative "<%= lib_name %>/ports/chat_tty"
+
+module <%= module_name %>
+end
+

data/lib/vsm/generator/templates/lib_organism_rb.erb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+require_relative "tools/read_file"
+
+module <%= module_name %>
+  module Organism
+    def self.build
+      # Provider selection via env (default injected at generation time)
+      provider = (ENV["<%= env_prefix %>_PROVIDER"] || "<%= provider %>").downcase
+      driver =
+        case provider
+        when "anthropic"
+          VSM::Drivers::Anthropic::AsyncDriver.new(
+            api_key: ENV.fetch("ANTHROPIC_API_KEY"),
+            model:   ENV["<%= env_prefix %>_MODEL"] || "<%= default_model %>"
+          )
+        when "gemini"
+          VSM::Drivers::Gemini::AsyncDriver.new(
+            api_key: ENV.fetch("GEMINI_API_KEY"),
+            model:   ENV["<%= env_prefix %>_MODEL"] || "<%= default_model %>"
+          )
+        else
+          VSM::Drivers::OpenAI::AsyncDriver.new(
+            api_key: ENV.fetch("OPENAI_API_KEY"),
+            model:   ENV["<%= env_prefix %>_MODEL"] || "<%= default_model %>"
+          )
+        end
+
+      VSM::DSL.define(:<%= lib_name %>) do
+        identity     klass: VSM::Identity,     args: { identity: "<%= lib_name %>", invariants: [] }
+        governance   klass: VSM::Governance
+        coordination klass: VSM::Coordination
+        intelligence klass: VSM::Intelligence, args: { driver: driver, system_prompt: "You are a helpful assistant. Use tools when helpful." }
+        monitoring   klass: VSM::Monitoring
+
+        operations do
+          capsule :read_file, klass: <%= module_name %>::Tools::ReadFile
+        end
+      end
+    end
+  end
+end

data/lib/vsm/generator/templates/lib_ports_chat_tty_rb.erb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module <%= module_name %>
+  module Ports
+    class ChatTTY < VSM::Ports::ChatTTY
+      def banner(io)
+        io.puts "\e[96m<%= lib_name %>\e[0m — Ctrl-C to exit"
+      end
+    end
+  end
+end
+

data/lib/vsm/generator/templates/lib_tools_read_file_rb.erb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module <%= module_name %>
+  module Tools
+    class ReadFile < VSM::ToolCapsule
+      tool_name "read_file"
+      tool_description "Read the contents of a UTF-8 text file at a relative path within the current workspace."
+      tool_schema({
+        type: "object",
+        properties: {
+          path: { type: "string", description: "Relative path to a text file (UTF-8)." }
+        },
+        required: ["path"]
+      })
+
+      def run(args)
+        rel = args["path"].to_s
+        raise "path required" if rel.strip.empty?
+        root = Dir.pwd
+        full = File.expand_path(File.join(root, rel))
+        # Prevent escaping outside workspace root
+        unless full.start_with?(root + File::SEPARATOR) || full == root
+          raise "outside workspace"
+        end
+        File.read(full, mode: "r:UTF-8")
+      rescue Errno::ENOENT
+        raise "file not found: #{rel}"
+      end
+    end
+  end
+end
+

data/lib/vsm/generator/templates/lib_version_rb.erb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module <%= module_name %>
+  VERSION = "0.1.0"
+end
+