RubyGems - vsm - Versions diffs - 0.0.1 → 0.1.0 - Mend

vsm 0.0.1 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (42) hide show

checksums.yaml +4 -4
data/.claude/settings.local.json +17 -0
data/CLAUDE.md +134 -0
data/README.md +531 -17
data/examples/01_echo_tool.rb +70 -0
data/examples/02_openai_streaming.rb +73 -0
data/examples/02b_anthropic_streaming.rb +61 -0
data/examples/02c_gemini_streaming.rb +60 -0
data/examples/03_openai_tools.rb +106 -0
data/examples/03b_anthropic_tools.rb +96 -0
data/examples/03c_gemini_tools.rb +95 -0
data/lib/vsm/async_channel.rb +21 -0
data/lib/vsm/capsule.rb +44 -0
data/lib/vsm/drivers/anthropic/async_driver.rb +210 -0
data/lib/vsm/drivers/family.rb +16 -0
data/lib/vsm/drivers/gemini/async_driver.rb +149 -0
data/lib/vsm/drivers/openai/async_driver.rb +202 -0
data/lib/vsm/dsl.rb +50 -0
data/lib/vsm/executors/fiber_executor.rb +10 -0
data/lib/vsm/executors/thread_executor.rb +19 -0
data/lib/vsm/homeostat.rb +19 -0
data/lib/vsm/lens/event_hub.rb +73 -0
data/lib/vsm/lens/server.rb +188 -0
data/lib/vsm/lens/stats.rb +58 -0
data/lib/vsm/lens/tui.rb +88 -0
data/lib/vsm/lens.rb +79 -0
data/lib/vsm/message.rb +6 -0
data/lib/vsm/observability/ledger.rb +25 -0
data/lib/vsm/port.rb +11 -0
data/lib/vsm/roles/coordination.rb +49 -0
data/lib/vsm/roles/governance.rb +9 -0
data/lib/vsm/roles/identity.rb +11 -0
data/lib/vsm/roles/intelligence.rb +168 -0
data/lib/vsm/roles/operations.rb +33 -0
data/lib/vsm/runtime.rb +18 -0
data/lib/vsm/tool/acts_as_tool.rb +20 -0
data/lib/vsm/tool/capsule.rb +12 -0
data/lib/vsm/tool/descriptor.rb +16 -0
data/lib/vsm/version.rb +1 -1
data/lib/vsm.rb +33 -0
data/llms.txt +322 -0
metadata +67 -25

data/lib/vsm/lens/event_hub.rb ADDED Viewed

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+require "json"
+require "time"
+require "securerandom"
+module VSM
+  module Lens
+    class EventHub
+      DEFAULT_BUFFER = 500
+      def initialize(buffer_size: DEFAULT_BUFFER)
+        @subs = []                 # Array of SizedQueue
+        @mutex = Mutex.new
+        @buffer = []
+        @buffer_size = buffer_size
+      end
+      def publish(message)
+        event = format_event(message)
+        @mutex.synchronize do
+          @buffer << event
+          @buffer.shift(@buffer.size - @buffer_size) if @buffer.size > @buffer_size
+          @subs.each { |q| try_push(q, event) }
+        end
+      end
+      def subscribe
+        q = SizedQueue.new(100)
+        snapshot = nil
+        @mutex.synchronize do
+          @subs << q
+          snapshot = @buffer.dup
+        end
+        [q, snapshot]
+      end
+      def unsubscribe(queue)
+        @mutex.synchronize { @subs.delete(queue) }
+      end
+      private
+      def try_push(queue, event)
+        queue.push(event)
+      rescue ThreadError
+        # queue full; drop event to avoid blocking the pipeline
+      end
+      def format_event(msg)
+        {
+          id:        SecureRandom.uuid,
+          ts:        Time.now.utc.iso8601(6),
+          kind:      msg.kind,
+          path:      msg.path,
+          corr_id:   msg.corr_id,
+          meta:      msg.meta,
+          # Small preview to avoid huge payloads; the UI can request details later if you add a /event/:id endpoint
+          payload:   preview(msg.payload)
+        }
+      end
+      def preview(payload)
+        case payload
+        when String
+          payload.bytesize > 2_000 ? payload.byteslice(0, 2_000) + "… (truncated)" : payload
+        else
+          payload
+        end
+      end
+    end
+  end
+end

data/lib/vsm/lens/server.rb ADDED Viewed

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+require "rack"
+require "rack/utils"
+module VSM
+  module Lens
+    class Server
+      INDEX_HTML = <<~HTML
+      <!doctype html>
+      <html lang="en">
+      <head>
+        <meta charset="utf-8" />
+        <meta name="viewport" content="width=device-width,initial-scale=1" />
+        <title>VSM Lens</title>
+        <style>
+          :root { font-family: system-ui, -apple-system, Segoe UI, Roboto, Arial, sans-serif; }
+          body { margin: 0; background: #0b0f14; color: #cfd8e3; }
+          header { padding: 12px 16px; background: #111827; border-bottom: 1px solid #1f2937; display:flex; align-items:center; gap:12px;}
+          header .dot { width:10px; height:10px; border-radius:50%; background:#10b981; }
+          main { display: grid; grid-template-columns: 280px 1fr; height: calc(100vh - 50px); }
+          aside { border-right: 1px solid #1f2937; padding: 12px; overflow:auto;}
+          section { padding: 12px; overflow:auto;}
+          h2 { font-size: 14px; color:#93c5fd; margin:0 0 8px 0; }
+          .card { background:#0f172a; border:1px solid #1f2937; border-radius:8px; padding:10px; margin-bottom:8px;}
+          .row { display:flex; align-items:flex-start; gap:8px; padding:8px; border-bottom:1px solid #1f2937; }
+          .row:last-child { border-bottom:none; }
+          .kind { font-weight:600; min-width:120px; color:#e5e7eb; }
+          .meta { color:#9ca3af; font-size:12px; }
+          .payload { white-space: pre-wrap; font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-size:12px; color:#d1fae5; }
+          .pill { display:inline-block; padding:2px 6px; border-radius:999px; font-size:11px; border:1px solid #374151; color:#c7d2fe;}
+          .pill.session { color:#fcd34d; }
+          .pill.tool { color:#a7f3d0; }
+          .toolbar { display:flex; gap:8px; margin-bottom:8px; }
+          input[type="text"] { background:#0b1220; color:#e5e7eb; border:1px solid #374151; border-radius:6px; padding:6px 8px; width:100%; }
+          .small { font-size:11px; color:#9ca3af; }
+        </style>
+      </head>
+      <body>
+        <header><div class="dot"></div><div><strong>VSM Lens</strong> <span class="small">live</span></div></header>
+        <main>
+          <aside>
+            <h2>Sessions</h2>
+            <div id="sessions"></div>
+            <h2>Filters</h2>
+            <div class="card">
+              <label class="small">Search</label>
+              <input id="filter" type="text" placeholder="text, kind, tool, session…" />
+            </div>
+          </aside>
+          <section>
+            <h2>Timeline</h2>
+            <div id="timeline"></div>
+          </section>
+        </main>
+        <script>
+          const params = new URLSearchParams(window.location.search);
+          const es = new EventSource("/events" + (params.get("token") ? ("?token=" + encodeURIComponent(params.get("token"))) : ""));
+          const sessions = {};
+          const timeline = document.getElementById("timeline");
+          const sessionsDiv = document.getElementById("sessions");
+          const filterInput = document.getElementById("filter");
+          let filter = "";
+          filterInput.addEventListener("input", () => { filter = filterInput.value.toLowerCase(); render(); });
+          const ring = [];
+          const RING_MAX = 1000;
+          es.onmessage = (e) => {
+            const ev = JSON.parse(e.data);
+            ring.push(ev);
+            if (ring.length > RING_MAX) ring.shift();
+            const sid = ev.meta && ev.meta.session_id;
+            if (sid) {
+              sessions[sid] = sessions[sid] || { count: 0, last: ev.ts };
+              sessions[sid].count += 1; sessions[sid].last = ev.ts;
+            }
+            render();
+          };
+          function render() {
+            // Sessions
+            sessionsDiv.innerHTML = Object.entries(sessions)
+              .sort((a,b)=> a[1].last < b[1].last ? 1 : -1)
+              .map(([sid, s]) => `<div class="card"><div><span class="pill session">${sid.slice(0,8)}</span></div><div class="small">${s.count} events • last ${s.last}</div></div>`)
+              .join("");
+            // Timeline
+            const rows = ring.filter(ev => {
+              if (!filter) return true;
+              const hay = JSON.stringify(ev).toLowerCase();
+              return hay.includes(filter);
+            }).slice(-200).map(ev => row(ev)).join("");
+            timeline.innerHTML = rows || "<div class='small'>Waiting for events…</div>";
+          }
+          function row(ev) {
+            const sid = ev.meta && ev.meta.session_id ? `<span class="pill session">${ev.meta.session_id.slice(0,8)}</span>` : "";
+            const tool = (ev.kind === "tool_call" && ev.meta && ev.meta.tool) ? `<span class="pill tool">${ev.meta.tool}</span>` : "";
+            const path = ev.path ? `<div class="small">path: ${ev.path.join(" › ")}</div>` : "";
+            const meta = `<div class="meta">${sid} ${tool} corr:${ev.corr_id || "–"} • ${ev.ts}</div>${path}`;
+            const payload = (typeof ev.payload === "string") ? `<div class="payload">${escapeHtml(ev.payload)}</div>` : `<div class="payload">${escapeHtml(JSON.stringify(ev.payload))}</div>`;
+            return `<div class="row"><div class="kind">${ev.kind}</div><div>${meta}${payload}</div></div>`;
+          }
+          function escapeHtml(s) {
+            return s.replace(/[&<>"']/g, m => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[m]));
+          }
+        </script>
+      </body>
+      </html>
+      HTML
+      def initialize(hub:, token: nil, stats: nil)
+        @hub, @token, @stats = hub, token, stats
+      end
+      def rack_app
+        hub   = @hub
+        token = @token
+        stats = @stats
+        Rack::Builder.new do
+          use Rack::ContentLength
+          map "/" do
+            run proc { |_env| [200, {"Content-Type"=>"text/html; charset=utf-8"}, [Server::INDEX_HTML]] }
+          end
+          map "/events" do
+            run proc { |env|
+              req = Rack::Request.new(env)
+              if token && req.params["token"] != token
+                [401, {"Content-Type"=>"text/plain"}, ["unauthorized"]]
+              else
+                queue, snapshot = hub.subscribe
+                headers = {"Content-Type"=>"text/event-stream", "Cache-Control"=>"no-cache", "Connection"=>"keep-alive"}
+                body = SSEBody.new(hub, queue, snapshot)
+                [200, headers, body]
+              end
+            }
+          end
+          map "/state" do
+            run proc { |env|
+              req = Rack::Request.new(env)
+              if token && req.params["token"] != token
+                [401, {"Content-Type"=>"application/json"}, [JSON.dump({error: "unauthorized"})]]
+              else
+                payload = stats ? stats.state : { error: "stats_unavailable" }
+                [200, {"Content-Type"=>"application/json"}, [JSON.dump(payload)]]
+              end
+            }
+          end
+        end
+      end
+    end
+    class SSEBody
+      def initialize(hub, queue, snapshot)
+        @hub, @queue, @snapshot = hub, queue, snapshot
+        @heartbeat = true
+      end
+      def each
+        # Send snapshot first
+        @snapshot.each { |ev| yield "data: #{JSON.generate(ev)}\n\n" }
+        # Heartbeat thread to keep connections alive
+        hb = Thread.new do
+          while @heartbeat
+            sleep 15
+            yield ": ping\n\n"  # SSE comment line
+          end
+        end
+        # Stream live events
+        loop do
+          ev = @queue.pop
+          yield "data: #{JSON.generate(ev)}\n\n"
+        end
+      ensure
+        @heartbeat = false
+        @hub.unsubscribe(@queue) rescue nil
+        hb.kill if hb&.alive?
+      end
+    end
+  end
+end

data/lib/vsm/lens/stats.rb ADDED Viewed

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+require "time"
+module VSM
+  module Lens
+    class Stats
+      def initialize(hub:, capsule:)
+        @sessions = Hash.new { |h,k| h[k] = { count: 0, last: nil, kinds: Hash.new(0) } }
+        @kinds    = Hash.new(0)
+        @capsule  = capsule
+        queue, snapshot = hub.subscribe
+        snapshot.each { |ev| ingest(ev) }
+        @thread = Thread.new do
+          loop do
+            ev = queue.pop
+            ingest(ev)
+          end
+        end
+      end
+      def state
+        {
+          ts: Time.now.utc.iso8601(6),
+          sessions: sort_sessions(@sessions),
+          kinds: @kinds.dup,
+          tools: tool_inventory,
+          budgets: {
+            limits: @capsule.homeostat.limits,
+            usage:  @capsule.homeostat.usage_snapshot
+          }
+        }
+      end
+      private
+      def ingest(ev)
+        @kinds[ev[:kind]] += 1
+        sid = ev.dig(:meta, :session_id)
+        return unless sid
+        @sessions[sid][:count] += 1
+        @sessions[sid][:last]   = ev[:ts]
+        @sessions[sid][:kinds][ev[:kind]] += 1
+      end
+      def sort_sessions(h)
+        h.sort_by { |_sid, s| s[:last].to_s }.reverse.to_h
+      end
+      def tool_inventory
+        ops = @capsule.bus.context[:operations_children] || {}
+        ops.keys.sort
+      end
+    end
+  end
+end

data/lib/vsm/lens/tui.rb ADDED Viewed

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+require "io/console"
+require "json"
+module VSM
+  module Lens
+    module TUI
+      # Start a simple TUI that renders the last N events and sessions.
+      # Usage:
+      #   hub = VSM::Lens.attach!(capsule)
+      #   VSM::Lens::TUI.start(hub)
+      def self.start(hub, ring_max: 500)
+        queue, snapshot = hub.subscribe
+        ring = snapshot.last(ring_max)
+        reader = Thread.new do
+          loop { ring << queue.pop; ring.shift if ring.size > ring_max }
+        end
+        trap("INT")  { exit }
+        trap("TERM") { exit }
+        STDIN.raw do
+          loop do
+            draw(ring)
+            # Non-blocking single-char read; press 'q' to quit
+            ch = if IO.select([STDIN], nil, nil, 0.1) then STDIN.read_nonblock(1) rescue nil end
+            exit if ch == "q"
+          end
+        end
+      ensure
+        reader&.kill
+      end
+      def self.draw(ring)
+        cols, rows = IO.console.winsize.reverse # => [rows, cols]
+        rows ||= 24; cols ||= 80
+        system("printf", "\e[2J\e[H") # clear
+        # Split: left sessions, right timeline
+        left_w  = [28, cols * 0.3].max.to_i
+        right_w = cols - left_w - 1
+        puts header("VSM Lens TUI — press 'q' to quit", cols)
+        # Sessions (left)
+        sessions = Hash.new { |h,k| h[k] = { count: 0, last: "" } }
+        ring.each do |ev|
+          sid = ev.dig(:meta, :session_id) or next
+          sessions[sid][:count] += 1
+          sessions[sid][:last]   = ev[:ts]
+        end
+        sess_lines = sessions.sort_by { |_id, s| s[:last].to_s }.reverse.first(rows-3).map do |sid, s|
+          "#{sid[0,8]}  #{s[:count].to_s.rjust(5)}  #{s[:last]}"
+        end
+        puts box("Sessions", sess_lines, left_w)
+        # Timeline (right)
+        tl = ring.last(rows-3).map do |ev|
+          kind = ev[:kind].to_s.ljust(16)
+          sid  = ev.dig(:meta, :session_id)&.slice(0,8) || "–"
+          txt  = case ev[:payload]
+                 when String then ev[:payload].gsub(/\s+/, " ")[0, right_w-40]
+                 else ev[:payload].to_s[0, right_w-40]
+                 end
+          "#{ev[:ts]}  #{kind} #{sid}  #{txt}"
+        end
+        puts box("Timeline", tl, right_w)
+      end
+      def self.header(text, width)
+        "\e[7m #{text.ljust(width-2)} \e[0m"
+      end
+      def self.box(title, lines, width)
+        out  = +"+" + "-"*(width-2) + "+\n"
+        out << "| #{title.ljust(width-4)} |\n"
+        out << "+" + "-"*(width-2) + "+\n"
+        lines.each do |l|
+          out << "| #{l.ljust(width-4)} |\n"
+        end
+        out << "+" + "-"*(width-2) + "+\n"
+        out
+      end
+    end
+  end
+end

data/lib/vsm/lens.rb ADDED Viewed

@@ -0,0 +1,79 @@
+# lib/vsm/lens.rb
+# frozen_string_literal: true
+require_relative "lens/event_hub"
+require_relative "lens/server"
+require_relative "lens/stats"
+require_relative "lens/tui"
+module VSM
+  module Lens
+    # Starts a tiny Rack server (Puma or WEBrick) and streams events via SSE.
+    # Returns the EventHub so other lenses (e.g., TUI) can also subscribe.
+    def self.attach!(capsule, host: "127.0.0.1", port: 9292, token: nil)
+      hub = EventHub.new
+      capsule.bus.subscribe { |msg| hub.publish(msg) }
+      require_relative "lens/stats"
+      stats  = Stats.new(hub: hub, capsule: capsule)
+      server = Server.new(hub: hub, token: token, stats: stats)
+      Thread.new do
+        app = server.rack_app
+        # Prefer Puma if present:
+        if try_run_puma(app, host, port)
+          # ok
+        elsif try_run_webrick(app, host, port)
+          # ok
+        else
+          warn <<~MSG
+            vsm-lens: no Rack handler found. Install one of:
+              - `bundle add puma`
+              - or `bundle add webrick`
+            Then re-run with VSM_LENS=1.
+          MSG
+        end
+      end
+      hub
+    end
+    def self.try_run_puma(app, host, port)
+      begin
+        require "rack/handler/puma"
+      rescue LoadError
+        return false
+      end
+      Thread.new do
+        Rack::Handler::Puma.run(app, Host: host, Port: port, Silent: true)
+      end
+      true
+    rescue => e
+      warn "vsm-lens: Puma failed to start: #{e.class}: #{e.message}"
+      false
+    end
+    def self.try_run_webrick(app, host, port)
+      begin
+        require "webrick"                 # provide the server
+        require "rack/handler/webrick"    # rack adapter (Rack 3 loads this if webrick gem is present)
+      rescue LoadError
+        return false
+      end
+      Thread.new do
+        Rack::Handler::WEBrick.run(
+          app,
+          Host: host, Port: port,
+          AccessLog: [],
+          Logger: WEBrick::Log.new($stderr, WEBrick::Log::WARN)
+        )
+      end
+      true
+    rescue => e
+      warn "vsm-lens: WEBrick failed to start: #{e.class}: #{e.message}"
+      false
+    end
+  end
+end

data/lib/vsm/message.rb ADDED Viewed

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+module VSM
+  # kind: :user, :assistant_delta, :assistant, :tool_call, :tool_result, :plan, :policy, :audit, :confirm_request, :confirm_response
+  # path: optional addressing, e.g., [:airb, :operations, :fs]
+  Message = Struct.new(:kind, :payload, :path, :corr_id, :meta, keyword_init: true)
+end

data/lib/vsm/observability/ledger.rb ADDED Viewed

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+require "json"
+require "time"
+module VSM
+  class Monitoring
+    LOG = File.expand_path(".vsm.log.jsonl", Dir.pwd)
+    def observe(bus)
+      bus.subscribe do |msg|
+        event = {
+          ts: Time.now.utc.iso8601,
+          kind: msg.kind,
+          path: msg.path,
+          corr_id: msg.corr_id,
+          meta: msg.meta
+        }
+        File.open(LOG, "a") { |f| f.puts(event.to_json) } rescue nil
+      end
+    end
+    def handle(*) = false
+  end
+end

data/lib/vsm/port.rb ADDED Viewed

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+module VSM
+  class Port
+    def initialize(capsule:) = (@capsule = capsule)
+    def ingress(_event) = raise NotImplementedError
+    def egress_subscribe = @capsule.bus.subscribe { |m| render_out(m) if should_render?(m) }
+  def should_render?(message) = [:assistant, :tool_result].include?(message.kind)
+    def render_out(_message) = nil
+  end
+end

data/lib/vsm/roles/coordination.rb ADDED Viewed

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+module VSM
+  class Coordination
+    def initialize
+      @queue = []
+      @floor_by_session = nil
+      @turn_waiters = {} # session_id => Async::Queue
+    end
+    def observe(bus)
+      # Note: staging is handled by the capsule loop, not by subscription
+      # This method exists for consistency but doesn't auto-stage messages
+    end
+    def stage(message) = (@queue << message)
+    def drain(bus)
+      return if @queue.empty?
+      @queue.sort_by! { order(_1) }
+      @queue.shift(@queue.size).each do |msg|
+        yield msg
+        if msg.kind == :assistant && (sid = msg.meta&.dig(:session_id)) && @turn_waiters[sid]
+          @turn_waiters[sid].enqueue(:done)
+        end
+      end
+    end
+    def grant_floor!(session_id) = (@floor_by_session = session_id)
+    def wait_for_turn_end(session_id)
+      q = (@turn_waiters[session_id] ||= Async::Queue.new)
+      q.dequeue
+    end
+    def order(m)
+      base =
+        case m.kind
+        when :user            then 0
+        when :tool_result     then 1
+        when :plan            then 2
+        when :assistant_delta then 3
+        when :assistant       then 4
+        else 9
+        end
+      sid = m.meta&.dig(:session_id)
+      sid == @floor_by_session ? base - 1 : base
+    end
+  end
+end

data/lib/vsm/roles/governance.rb ADDED Viewed

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+module VSM
+  class Governance
+    def observe(bus); end
+    def enforce(message)
+      yield message
+    end
+  end
+end

data/lib/vsm/roles/identity.rb ADDED Viewed

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+module VSM
+  class Identity
+    def initialize(identity:, invariants: [])
+      @identity, @invariants = identity, invariants
+    end
+    def observe(bus); end
+    def handle(message, bus:, **) = false
+    def alert(message); end
+  end
+end