vsm 0.0.1 → 0.2.0

data/examples/07_connect_claude_mcp.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "json"
+require "securerandom"
+require "vsm"
+require "vsm/dsl_mcp"
+require "vsm/ports/chat_tty"
+
+# Example: Connect to an external MCP server (Claude Code)
+#
+# Prereqs:
+#   - Install Claude CLI and log in.
+#   - Ensure `claude mcp serve` works in your shell.
+#
+# IMPORTANT: Many MCP servers (including Claude) use LSP-style Content-Length
+# framing over stdio. The minimal transport in this repo currently uses NDJSON
+# (one JSON per line). If this example hangs or fails, it's due to framing
+# mismatch; swap the transport to LSP framing in lib/vsm/mcp/jsonrpc.rb.
+#
+# Usage:
+#   ruby examples/07_connect_claude_mcp.rb
+#   Then type:
+#     list
+#     call: some_tool {"arg1":"value"}
+#
+# This example avoids requiring any LLM API keys by letting you call tools manually
+# via a simple chat convention.
+
+# Intelligence that recognizes two commands:
+# - "list" → prints available tools
+# - "call: NAME {json}" → invokes the reflected tool with JSON args
+class ManualMCPIntelligence < VSM::Intelligence
+  def handle(message, bus:, **)
+    return false unless message.kind == :user
+    line = message.payload.to_s.strip
+    if line == "list"
+      # Inspect operations children for tool descriptors
+      ops = bus.context[:operations_children] || {}
+      tools = ops.values.select { _1.respond_to?(:tool_descriptor) }.map { _1.tool_descriptor.name }
+      bus.emit VSM::Message.new(kind: :assistant, payload: tools.any? ? "tools: #{tools.join(", ")}" : "(no tools)", meta: message.meta)
+      return true
+    elsif line.start_with?("call:")
+      if line =~ /\Acall:\s*(\S+)\s*(\{.*\})?\z/
+        tool = $1
+        json = $2
+        args = json ? (JSON.parse(json) rescue {}) : {}
+        bus.emit VSM::Message.new(kind: :tool_call, payload: { tool: tool, args: args }, corr_id: SecureRandom.uuid, meta: message.meta)
+        return true
+      else
+        bus.emit VSM::Message.new(kind: :assistant, payload: "usage: call: NAME {json}", meta: message.meta)
+        return true
+      end
+    else
+      bus.emit VSM::Message.new(kind: :assistant, payload: "Commands: list | call: NAME {json}", meta: message.meta)
+      return true
+    end
+  end
+end
+
+cap = VSM::DSL.define(:claude_mcp_client) do
+  identity     klass: VSM::Identity,     args: { identity: "claude_mcp_client", invariants: [] }
+  governance   klass: VSM::Governance
+  coordination klass: VSM::Coordination
+  intelligence klass: ManualMCPIntelligence
+  monitoring   klass: VSM::Monitoring
+  operations do
+    # Reflect all available tools from the external server.
+    # Tip: if tool names collide with locals, use prefix: "claude_".
+    mcp_server :claude, cmd: ["claude", "mcp", "serve"]
+  end
+end
+
+banner = ->(io) do
+  io.puts "\e[96mMCP client (Claude)\e[0m"
+  io.puts "Type 'list' or 'call: NAME {json}'"
+end
+
+VSM::Runtime.start(cap, ports: [VSM::Ports::ChatTTY.new(capsule: cap, banner: banner, prompt: "You> ")])

data/examples/08_custom_chattty.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "vsm"
+require "vsm/ports/chat_tty"
+require "securerandom"
+
+# Demonstrates subclassing ChatTTY to customize the banner and output formatting.
+
+class EchoTool < VSM::ToolCapsule
+  tool_name "echo"
+  tool_description "Echoes back the provided text"
+  tool_schema({ type: "object", properties: { text: { type: "string" } }, required: ["text"] })
+  def run(args)
+    "you said: #{args["text"]}"
+  end
+end
+
+class DemoIntelligence < VSM::Intelligence
+  def handle(message, bus:, **)
+    return false unless message.kind == :user
+    if message.payload =~ /\Aecho:\s*(.+)\z/
+      bus.emit VSM::Message.new(kind: :tool_call, payload: { tool: "echo", args: { "text" => $1 } }, corr_id: SecureRandom.uuid, meta: message.meta)
+    else
+      bus.emit VSM::Message.new(kind: :assistant, payload: "Try: echo: hello", meta: message.meta)
+    end
+    true
+  end
+end
+
+class FancyTTY < VSM::Ports::ChatTTY
+  def banner(io)
+    io.puts "\e[95m\n ███  CUSTOM CHAT  ███\n\e[0m"
+  end
+
+  def render_out(m)
+    case m.kind
+    when :assistant_delta
+      @streaming = true
+      @out.print m.payload
+      @out.flush
+    when :assistant
+      @out.puts unless @streaming
+      @streaming = false
+    when :tool_call
+      @out.puts "\n\e[90m→ calling #{m.payload[:tool]}\e[0m"
+    when :tool_result
+      @out.puts "\e[92m✓ #{m.payload}\e[0m"
+    end
+  end
+end
+
+cap = VSM::DSL.define(:fancy_chat) do
+  identity     klass: VSM::Identity,     args: { identity: "fancy_chat", invariants: [] }
+  governance   klass: VSM::Governance
+  coordination klass: VSM::Coordination
+  intelligence klass: DemoIntelligence
+  monitoring   klass: VSM::Monitoring
+  operations do
+    capsule :echo, klass: EchoTool
+  end
+end
+
+VSM::Runtime.start(cap, ports: [FancyTTY.new(capsule: cap, prompt: "Me: ")])

data/examples/09_mcp_with_llm_calls.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "vsm"
+require "vsm/dsl_mcp"
+require "vsm/ports/chat_tty"
+
+# Example: Use an LLM driver (OpenAI) to automatically call tools exposed by an MCP server.
+#
+# Prereqs:
+#   - OPENAI_API_KEY must be set
+#   - An MCP server available on your PATH, e.g. `claude mcp serve`
+#
+# Usage:
+#   OPENAI_API_KEY=... AIRB_MODEL=gpt-4o-mini ruby examples/09_mcp_with_llm_calls.rb
+#   Type a question; the model will choose tools from the reflected MCP server.
+
+MODEL = ENV["AIRB_MODEL"] || "gpt-4o-mini"
+
+driver = VSM::Drivers::OpenAI::AsyncDriver.new(
+  api_key: ENV.fetch("OPENAI_API_KEY"),
+  model: MODEL
+)
+
+system_prompt = <<~PROMPT
+  You are a helpful assistant. You have access to the listed tools.
+  When a tool can help, call it with appropriate JSON arguments.
+  Keep final answers concise.
+PROMPT
+
+cap = VSM::DSL.define(:mcp_with_llm) do
+  identity     klass: VSM::Identity,     args: { identity: "mcp_with_llm", invariants: [] }
+  governance   klass: VSM::Governance
+  coordination klass: VSM::Coordination
+  intelligence klass: VSM::Intelligence, args: { driver: driver, system_prompt: system_prompt }
+  monitoring   klass: VSM::Monitoring
+  operations do
+    # Reflect tools from an external MCP server (e.g., Claude Code).
+    # If your server requires strict LSP framing, run with VSM_MCP_LSP=1.
+    # You can also prefix names to avoid collisions: prefix: "claude_"
+    mcp_server :claude, cmd: ["claude", "mcp", "serve"]
+  end
+end
+
+banner = ->(io) do
+  io.puts "\e[96mLLM + MCP tools\e[0m — Ask a question; model may call tools."
+end
+
+VSM::Runtime.start(cap, ports: [VSM::Ports::ChatTTY.new(capsule: cap, banner: banner, prompt: "You> ")])
+

data/examples/10_meta_read_only.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# Demo: use OpenAI tool-calling to let an LLM inspect the running capsule via
+# the read-only meta tools. Set OPENAI_API_KEY (and optionally AIRB_MODEL) then:
+#   bundle exec ruby examples/10_meta_read_only.rb
+# Ask things like "What can you do?" or "Explain meta_demo_tool" and the model
+# will call the meta tools to gather context before replying.
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "securerandom"
+require "vsm"
+
+MODEL = ENV["AIRB_MODEL"] || "gpt-4o-mini"
+API_KEY = ENV["OPENAI_API_KEY"] or abort "OPENAI_API_KEY required for this demo"
+
+class MetaDemoTool < VSM::ToolCapsule
+  tool_name "meta_demo_tool"
+  tool_description "Simple tool included alongside meta tools"
+  tool_schema({ type: "object", properties: {}, additionalProperties: false })
+
+  def run(_args)
+    "hello from demo tool"
+  end
+end
+
+driver = VSM::Drivers::OpenAI::AsyncDriver.new(api_key: API_KEY, model: MODEL)
+
+SYSTEM_PROMPT = <<~PROMPT
+  You are the steward of a VSM capsule. You have access to built-in reflection
+  tools that describe the organism and its operations:
+    - meta_summarize_self: overview of the current capsule and its roles
+    - meta_list_tools: list available tools with schemas
+    - meta_explain_tool: show implementation details for a named tool
+    - meta_explain_role: show capsule-specific details and code for a VSM role
+  When the user asks about capabilities, available tools, or how something
+  works, call the appropriate meta_* tool first, then respond with a clear,
+  human-friendly summary that cites relevant tool names. Be concise but
+  complete.
+PROMPT
+
+cap = VSM::DSL.define(:meta_demo_llm) do
+  identity     klass: VSM::Identity,     args: { identity: "meta_demo_llm", invariants: [] }
+  governance   klass: VSM::Governance,   args: {}
+  coordination klass: VSM::Coordination, args: {}
+  intelligence klass: VSM::Intelligence, args: { driver: driver, system_prompt: SYSTEM_PROMPT }
+  monitoring   klass: VSM::Monitoring,   args: {}
+  operations do
+    meta_tools
+    capsule :meta_demo_tool, klass: MetaDemoTool
+  end
+end
+
+ports = [VSM::Ports::ChatTTY.new(capsule: cap, banner: ->(io) { io.puts "Meta demo ready. Try asking 'What can you do?'" })]
+
+VSM::Runtime.start(cap, ports: ports)

data/exe/vsm

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Keep CLI independent of any project's Bundler context so we resolve this
+# gem's dependencies rather than a host app's Gemfile.
+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')
+
+require 'vsm'
+require 'vsm/cli'
+
+VSM::CLI.start(ARGV)
+

data/lib/vsm/async_channel.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module VSM
+  class AsyncChannel
+    attr_reader :context
+
+    def initialize(context: {})
+      @queue = Async::Queue.new
+      @subs  = []
+      @context = context
+    end
+
+    def emit(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
+      blk
+    end
+
+    def unsubscribe(subscriber)
+      @subs.delete(subscriber)
+    end
+  end
+end

data/lib/vsm/capsule.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+require "async"
+module VSM
+  class Capsule
+    attr_reader :name, :bus, :homeostat, :roles, :children
+
+    def initialize(name:, roles:, children: {})
+      @name     = name.to_sym
+      @roles    = roles
+      @children = children
+      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
+
+    def run
+      Async do
+        loop do
+          message = @bus.pop
+          roles[:coordination].stage(message)
+          roles[:coordination].drain(@bus) { |m| dispatch(m) }
+        end
+      end
+    end
+
+    def dispatch(message)
+      return roles[:identity].alert(message) if homeostat.alarm?(message)
+      roles[:governance].enforce(message) { route(_1) }
+    end
+
+    def route(message)
+      roles[:operations].handle(message, bus: @bus, children: @children) ||
+      roles[:intelligence].handle(message, bus: @bus) ||
+      roles[:identity].handle(message, bus: @bus)
+    end
+
+    private
+
+    def wire_observers!
+      roles.values.each { |r| r.respond_to?(:observe) && r.observe(@bus) }
+    end
+  end
+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/drivers/anthropic/async_driver.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+require "json"
+require "net/http"
+require "uri"
+require "securerandom"
+
+module VSM
+  module Drivers
+    module Anthropic
+      class AsyncDriver
+        def initialize(api_key:, model:, base_url: "https://api.anthropic.com/v1", version: "2023-06-01")
+          @api_key, @model, @base, @version = api_key, model, base_url, version
+        end
+
+        def run!(conversation:, tools:, policy: {}, &emit)
+          # Always use Net::HTTP with SSE
+          emitted_terminal = false
+
+          headers = {
+            "x-api-key" => @api_key,
+            "anthropic-version" => @version,
+            "content-type" => "application/json",
+            "accept" => "text/event-stream"
+          }
+
+          messages  = to_anthropic_messages(conversation, policy[:system_prompt])
+          tool_list = normalize_anthropic_tools(tools)
+          payload = {
+            model: @model,
+            system: policy[:system_prompt],
+            messages: messages,
+            max_tokens: 512,
+            stream: true
+          }
+          if tool_list.any?
+            payload[:tools] = tool_list
+            payload[:tool_choice] = { type: "auto" }
+          end
+          body = JSON.dump(payload)
+
+          url = URI.parse("#{@base}/messages")
+          http = Net::HTTP.new(url.host, url.port)
+          http.use_ssl = (url.scheme == "https")
+          http.read_timeout = 120
+
+          req = Net::HTTP::Post.new(url.request_uri)
+          headers.each { |k,v| req[k] = v }
+          req.body = body
+
+          res = http.request(req) do |response|
+            ct = response["content-type"]
+            if response.code.to_i != 200
+              err_body = +""
+              response.read_body { |chunk| err_body << chunk }
+              preview = err_body.to_s.byteslice(0, 400)
+              emit.call(:assistant_final, "Anthropic HTTP #{response.code}: #{preview}")
+              emitted_terminal = true
+              next
+            end
+
+            if ct && ct.include?("text/event-stream")
+              buffer = +""
+              textbuf = +""
+              toolbuf = {}
+              tool_calls = []
+
+              response.read_body do |chunk|
+                buffer << chunk
+                while (i = buffer.index("\n"))
+                  line = buffer.slice!(0..i)
+                  line.chomp!
+                  next unless line.start_with?("data:")
+                  data = line.sub("data:","").strip
+                  next if data.empty? || data == "[DONE]"
+                  obj = JSON.parse(data) rescue nil
+                  next unless obj
+                  ev = obj["type"].to_s
+                  if ENV["VSM_DEBUG_STREAM"] == "1"
+                    $stderr.puts "anthropic(nethttp) <= #{ev}: #{data.byteslice(0, 160)}"
+                  end
+
+                  case ev
+                  when "content_block_delta"
+                    idx = obj["index"]; delta = obj["delta"] || {}
+                    case delta["type"]
+                    when "text_delta"
+                      part = delta["text"].to_s
+                      textbuf << part
+                      emit.call(:assistant_delta, part)
+                    when "input_json_delta"
+                      toolbuf[idx] ||= { id: nil, name: nil, json: +"" }
+                      toolbuf[idx][:json] << (delta["partial_json"] || "")
+                    end
+                  when "content_block_start"
+                    # For anthropic, the key can be 'content' or 'content_block'
+                    c = obj["content"] || obj["content_block"] || {}
+                    if c["type"] == "tool_use"
+                      name = c["name"] || obj["name"]
+                      toolbuf[obj["index"]] = { id: c["id"], name: name, json: +"" }
+                    end
+                  when "content_block_stop"
+                    idx = obj["index"]
+                    if tb = toolbuf[idx]
+                      args = tb[:json].empty? ? {} : (JSON.parse(tb[:json]) rescue {"_raw"=>tb[:json]})
+                      # Only enqueue if name is present
+                      if tb[:name].to_s.strip != "" && tb[:id]
+                        tool_calls << { id: tb[:id], name: tb[:name], arguments: args }
+                      end
+                    end
+                  when "message_stop"
+                    if tool_calls.any?
+                      emit.call(:tool_calls, tool_calls)
+                    else
+                      emit.call(:assistant_final, textbuf.dup)
+                    end
+                    emitted_terminal = true
+                  end
+                end
+              end
+
+              unless emitted_terminal
+                # If the stream closed without a terminal, emit final text
+                emit.call(:assistant_final, textbuf)
+                emitted_terminal = true
+              end
+            else
+              # Non-streaming JSON
+              data = ""
+              response.read_body { |chunk| data << chunk }
+              obj = JSON.parse(data) rescue {}
+              parts = Array(obj.dig("content"))
+              calls = []
+              text  = +""
+              parts.each do |p|
+                case p["type"]
+                when "text" then text << p["text"].to_s
+                when "tool_use" then calls << { id: p["id"] || SecureRandom.uuid, name: p["name"], arguments: p["input"] || {} }
+                end
+              end
+              if calls.any?
+                emit.call(:tool_calls, calls)
+              else
+                emit.call(:assistant_final, text)
+              end
+              emitted_terminal = true
+            end
+          end
+
+          :done
+        end
+
+        private
+        # (no IPv6/IPv4 forcing; rely on default Internet)
+        def normalize_anthropic_tools(tools)
+          Array(tools).map { |t| normalize_anthropic_tool(t) }
+        end
+
+        def normalize_anthropic_tool(t)
+          return t.to_anthropic_tool if t.respond_to?(:to_anthropic_tool)
+
+          # Provider-shaped: {name:, description:, input_schema: {…}}
+          if t.is_a?(Hash) && (t[:input_schema] || t["input_schema"])
+            return t
+          end
+
+          # Neutral hash {name:, description:, schema:}
+          if t.is_a?(Hash) && (t[:name] || t["name"])
+            return {
+              name:        t[:name]        || t["name"],
+              description: t[:description] || t["description"] || "",
+              input_schema: t[:schema]     || t["schema"]      || {}
+            }
+          end
+
+          raise TypeError, "unsupported tool descriptor: #{t.inspect}"
+        end
+
+
+        def to_anthropic_messages(neutral, _system)
+          # Build content blocks per message; keep ordering
+          neutral.map do |m|
+            case m[:role]
+            when "user"
+              { role: "user", content: [{ type: "text", text: m[:content].to_s }] }
+            when "assistant"
+              { role: "assistant", content: [{ type: "text", text: m[:content].to_s }] }
+            when "assistant_tool_calls"
+              blocks = Array(m[:tool_calls]).map { |c|
+                { type: "tool_use", id: c[:id], name: c[:name], input: c[:arguments] || {} }
+              }
+              { role: "assistant", content: blocks }
+            when "tool_result"
+              { role: "user", content: [{ type: "tool_result", tool_use_id: m[:tool_call_id], content: m[:content].to_s }] }
+            end
+          end.compact
+        end
+
+        def extract_sse_line!(buffer)
+          if (i = buffer.index("\n"))
+            line = buffer.slice!(0..i)
+            line.chomp!
+            return line
+          end
+          nil
+        end
+      end
+    end
+  end
+end
+

data/lib/vsm/drivers/family.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+module VSM
+  module Drivers
+    module Family
+      def self.of(driver)
+        case driver
+        when VSM::Drivers::OpenAI::AsyncDriver    then :openai
+        when VSM::Drivers::Anthropic::AsyncDriver then :anthropic
+        when VSM::Drivers::Gemini::AsyncDriver    then :gemini
+        else :openai
+        end
+      end
+    end
+  end
+end
+