vsm 0.0.1 → 0.2.0

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
+

data/lib/vsm/homeostat.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+module VSM
+  class Homeostat
+    attr_reader :limits
+
+    def initialize
+      @limits = { tokens: 8_000, time_ms: 15_000, bytes: 2_000_000 }
+      @usage  = Hash.new(0)
+    end
+
+    def usage_snapshot
+      @usage.dup
+    end
+
+    def alarm?(message)
+      message.meta&.dig(:severity) == :algedonic
+    end
+  end
+end

data/lib/vsm/lens/event_hub.rb

@@ -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

@@ -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

@@ -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

@@ -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
+