vsm 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9bdbe6ab3817a25d90829e9880efb85860948748281eedd885004411ff0221b3
-  data.tar.gz: 7b47991a4af3167b8c3968e41e062dedad7f6050a74af7ad5f4f48952ccedb72
+  metadata.gz: cc432d13c4f757abb289f153f28cfb6c77a2585f5607a135579225009610eac4
+  data.tar.gz: beb5f88da44e032ce7f135c66d2fa0cc314eef3a05c1d76338f6bf8686d4ef41
 SHA512:
-  metadata.gz: 1dd4ee44eaef8be76d7a02890312f7b3a4a99216ddcd613655cd8c47f81c9c188c471f164bfc2bd69071d9a5b392d89dc803e7600ae811f49f2db8b7b55bdc3f
-  data.tar.gz: 7fe63b320f208604cfe40e0440bec76f9ef8dbceb0a419cb2f7501fce7f4d8097c42ce01d6d9e61345e272a3f6d438e663de94ca8af3eee52f44fc8d401780d4
+  metadata.gz: 808ebdb904246a2ef7ed4e6a5e2f6b66792ab8b6794e04e96e56a4ab5eb05be5fbe7d36d1bc1edf2ea87f64a243491151c9478c8eebb813b90fc0847cf1efc74
+  data.tar.gz: 0bd7328481b990604fbc40abe6050ee179734e144d9f6e7f70ace363752e0b245cc2aaf026b2c5175b68a22b175238e83c0570a70a75ee5dd56298ba9395c443

data/README.md

@@ -165,6 +165,28 @@ ruby quickstart.rb
 # Tool> you said: hello
 ```
 
+## Project Generator (CLI)
+
+Scaffold a new VSM app with a ChatTTY interface:
+
+```bash
+gem install vsm   # or build/install locally
+vsm new my_agent
+cd my_agent
+bundle install
+bundle exec exe/my-agent
+```
+
+Options:
+- `--with-llm openai|anthropic|gemini` — choose LLM provider (default: openai)
+- `--model <name>` — default model
+- `--git` — initialize git and commit
+- `--bundle` — run `bundle install`
+- `--path <dir>` — target directory (default: `./<name>`)
+- `--force` — overwrite an existing non-empty directory
+
+Generated layout mirrors the `airb` example: an `Organism.build` to assemble the capsule, a default `ChatTTY` port, and a sample `echo` tool ready to extend.
+
 ## Building a Real Agent
 
 For a real agent with LLM integration:
@@ -225,6 +247,37 @@ Your `MyLLMIntelligence` would:
 - **Observability**: append‑only JSONL ledger you can feed into a UI later
 - **POODR/SOLID**: small objects, high cohesion, low coupling
 
+## Meta Tools
+
+VSM includes a set of read‑only meta tools you can attach to any capsule to inspect its structure and code:
+
+- `meta_summarize_self` — Summarize the current capsule including roles and tools
+- `meta_list_tools` — List all tools available in the organism (descriptors and paths)
+- `meta_explain_tool` — Show code and context for a specific tool
+- `meta_explain_role` — Explain a role implementation for a capsule, with source snippets
+
+Attach them when building your capsule:
+
+```ruby
+capsule = VSM::DSL.define(:my_agent) do
+  identity     klass: VSM::Identity,     args: { identity: "my_agent" }
+  governance   klass: VSM::Governance
+  coordination klass: VSM::Coordination
+  intelligence klass: VSM::Intelligence
+  monitoring   klass: VSM::Monitoring
+  operations do
+    meta_tools  # registers the four meta tools above on this capsule
+  end
+end
+```
+
+Example calls:
+
+- `meta_summarize_self {}` → high‑level snapshot and counts
+- `meta_list_tools {}` → array of tools with descriptors
+- `meta_explain_tool { "tool": "some_tool" }` → code snippet + descriptor
+- `meta_explain_role { "role": "coordination" }` → role class, constructor args, source locations, and code blocks
+
 ## Core Concepts
 
 ### Capsule
@@ -350,6 +403,91 @@ Start everything:
 VSM::Runtime.start(capsule, ports: [MyPort.new(capsule:)])
 ```
 
+### Built-in Ports
+
+- `VSM::Ports::ChatTTY` — A generic, customizable chat terminal UI. Safe to run alongside MCP stdio; prefers `IO.console` so it won’t pollute stdout.
+- `VSM::Ports::MCP::ServerStdio` — Exposes your capsule as an MCP server on stdio implementing `tools/list` and `tools/call`.
+
+Enable them:
+
+```ruby
+require "vsm/ports/chat_tty"
+require "vsm/ports/mcp/server_stdio"
+
+ports = [
+  VSM::Ports::MCP::ServerStdio.new(capsule: capsule),  # machine IO (stdio)
+  VSM::Ports::ChatTTY.new(capsule: capsule)            # human IO (terminal)
+]
+VSM::Runtime.start(capsule, ports: ports)
+```
+
+### MCP Client (reflect and wrap tools)
+
+Reflect tools from an external MCP server and expose them as local tools using the DSL. This uses a tiny stdio JSON‑RPC client under the hood.
+
+```ruby
+require "vsm/dsl_mcp"
+
+cap = VSM::DSL.define(:mcp_client) do
+  identity     klass: VSM::Identity,    args: { identity: "mcp_client", invariants: [] }
+  governance   klass: VSM::Governance
+  coordination klass: VSM::Coordination
+  intelligence klass: VSM::Intelligence # or your own
+  monitoring   klass: VSM::Monitoring
+  operations do
+    # Prefix helps avoid name collisions
+    mcp_server :smith, cmd: "smith-server --stdio", prefix: "smith_", include: %w[search read]
+  end
+end
+```
+
+See `examples/06_mcp_mount_reflection.rb` and `examples/07_connect_claude_mcp.rb`.
+
+Note: Many MCP servers speak LSP-style `Content-Length` framing on stdio. The
+current minimal transport uses NDJSON for simplicity. If a server hangs or
+doesn't respond, switch the transport to LSP framing in `lib/vsm/mcp/jsonrpc.rb`.
+
+### Customizing ChatTTY
+
+You can customize ChatTTY via options or by subclassing to override only the banner and rendering methods, while keeping the input loop.
+
+```ruby
+class FancyTTY < VSM::Ports::ChatTTY
+  def banner(io)
+    io.puts "\e[95m\n ███  CUSTOM CHAT  ███\n\e[0m"
+  end
+
+  def render_out(m)
+    super # or implement your own formatting
+  end
+end
+
+VSM::Runtime.start(capsule, ports: [FancyTTY.new(capsule: capsule, prompt: "Me> ")])
+```
+
+See `examples/08_custom_chattty.rb`.
+
+### LLM-driven MCP tools
+
+Use an LLM driver (e.g., OpenAI) to automatically call tools reflected from an MCP server:
+
+```ruby
+driver = VSM::Drivers::OpenAI::AsyncDriver.new(api_key: ENV.fetch("OPENAI_API_KEY"), model: ENV["AIRB_MODEL"] || "gpt-4o-mini")
+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: "Use tools when helpful." }
+  monitoring   klass: VSM::Monitoring
+  operations do
+    mcp_server :server, cmd: ["claude","mcp","serve"]  # reflect tools
+  end
+end
+VSM::Runtime.start(cap, ports: [VSM::Ports::ChatTTY.new(capsule: cap)])
+```
+
+See `examples/09_mcp_with_llm_calls.rb`.
+
 ## Observability
 
 VSM ships a tiny Monitoring role that writes an append‑only JSONL ledger:
@@ -364,6 +502,12 @@ VSM ships a tiny Monitoring role that writes an append‑only JSONL ledger:
 
 Use it to power a TUI/HTTP "Lens" later. Because everything flows over the bus, you get consistent events across nested capsules and sub‑agents.
 
+### MCP and ChatTTY Coexistence
+
+- MCP stdio port only reads stdin and writes strict JSON to stdout.
+- ChatTTY prefers `IO.console` or falls back to stderr and disables input if no TTY.
+- You can run both in the same process: machine protocol on stdio, human UI on the terminal.
+
 ## Writing an Intelligence
 
 The Intelligence role is where you plan/decide. It might:

data/Rakefile

@@ -5,8 +5,4 @@ require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 
-require "rubocop/rake_task"
-
-RuboCop::RakeTask.new
-
-task default: %i[spec rubocop]
+task default: %i[spec]

data/examples/01_echo_tool.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 $LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
 require "vsm"
+require "vsm/ports/chat_tty"
+require "securerandom"
 
 class EchoTool < VSM::ToolCapsule
   tool_name "echo"
@@ -44,27 +46,6 @@ cap = VSM::DSL.define(:demo) do
   end
 end
 
-# Simple CLI port
-class StdinPort < VSM::Port
-  def loop
-    sid = SecureRandom.uuid
-    print "You: "
-    while (line = $stdin.gets&.chomp)
-      @capsule.bus.emit VSM::Message.new(kind: :user, payload: line, meta: { session_id: sid })
-      @capsule.roles[:coordination].wait_for_turn_end(sid)
-      print "You: "
-    end
-  end
-
-  def render_out(msg)
-    case msg.kind
-    when :assistant
-      puts "\nBot: #{msg.payload}"
-    when :tool_result
-      puts "\nTool> #{msg.payload}"
-    end
-  end
-end
-
-VSM::Runtime.start(cap, ports: [StdinPort.new(capsule: cap)])
-
+# Use the built-in, customizable ChatTTY port
+banner = ->(io) { io.puts "\e[96mEcho demo\e[0m — type 'echo: hello' (Ctrl-C to exit)" }
+VSM::Runtime.start(cap, ports: [VSM::Ports::ChatTTY.new(capsule: cap, banner: banner)])

data/examples/02_openai_streaming.rb

@@ -57,8 +57,9 @@ class StreamTTY < VSM::Port
       print msg.payload
       $stdout.flush
     when :assistant
-      puts "" # end the line
-      puts msg.payload.to_s unless msg.payload.to_s.empty?
+      puts "" # end the line after streaming
+      # The :assistant event carries the full final text again; avoid re-printing it
+      # because we've already streamed the deltas above. Just show the turn marker.
       puts "(turn #{msg.meta&.dig(:turn_id)})"
     when :tool_result
       puts "\nTool> #{msg.payload}"
@@ -70,4 +71,3 @@ end
 
 VSM::Runtime.start(cap, ports: [StreamTTY.new(capsule: cap)])
 
-

data/examples/02b_anthropic_streaming.rb

@@ -10,9 +10,7 @@ MODEL = ENV["AIRB_MODEL"] || "claude-sonnet-4-0"
 
 driver = VSM::Drivers::Anthropic::AsyncDriver.new(
   api_key: ENV.fetch("ANTHROPIC_API_KEY"),
-  model: MODEL,
-  streaming: true,
-  transport: :nethttp
+  model: MODEL
 )
 
 system_prompt = "You are a concise assistant. Answer briefly."
@@ -58,4 +56,3 @@ end
 
 VSM::Runtime.start(cap, ports: [StreamTTY.new(capsule: cap)])
 
-

data/examples/03b_anthropic_tools.rb

@@ -37,9 +37,7 @@ end
 
 driver = VSM::Drivers::Anthropic::AsyncDriver.new(
   api_key: ENV.fetch("ANTHROPIC_API_KEY"),
-  model: MODEL,
-  streaming: true,
-  transport: :nethttp
+  model: MODEL
 )
 
 system_prompt = <<~PROMPT
@@ -93,4 +91,3 @@ end
 
 VSM::Runtime.start(cap, ports: [ToolTTY.new(capsule: cap)])
 
-

data/examples/05_mcp_server_and_chattty.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "vsm"
+require "securerandom"
+require "vsm/ports/chat_tty"
+require "vsm/ports/mcp/server_stdio"
+
+# A simple local tool we can expose to both ChatTTY and MCP stdio.
+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
+
+# Minimal intelligence that triggers the echo tool when user types: echo: ...
+class DemoIntelligence < VSM::Intelligence
+  def handle(message, bus:, **)
+    case message.kind
+    when :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
+    when :tool_result
+      bus.emit VSM::Message.new(kind: :assistant, payload: "(done)", meta: message.meta)
+      true
+    else
+      false
+    end
+  end
+end
+
+cap = VSM::DSL.define(:demo_mcp_server_and_chat) do
+  identity     klass: VSM::Identity,     args: { identity: "demo", invariants: [] }
+  governance   klass: VSM::Governance
+  coordination klass: VSM::Coordination
+  intelligence klass: DemoIntelligence
+  monitoring   klass: VSM::Monitoring
+  operations do
+    capsule :echo, klass: EchoTool
+  end
+end
+
+# Run both ports together: MCP stdio (machine) + ChatTTY (human).
+banner = ->(io) { io.puts "\e[96mVSM demo\e[0m — type 'echo: hi' (Ctrl-C to exit)" }
+ports = [VSM::Ports::MCP::ServerStdio.new(capsule: cap)]
+if $stdout.tty?
+  # Only enable interactive ChatTTY when attached to a TTY to avoid
+  # interfering when this example is spawned as a background MCP server.
+  begin
+    tty = File.open("/dev/tty", "r+")
+  rescue StandardError
+    tty = nil
+  end
+  ports << VSM::Ports::ChatTTY.new(capsule: cap, banner: banner, input: tty, output: tty)
+end
+
+VSM::Runtime.start(cap, ports: ports)

data/examples/06_mcp_mount_reflection.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "vsm"
+require "vsm/dsl_mcp"
+require "vsm/ports/chat_tty"
+require "securerandom"
+
+# This example mounts a remote MCP server (we use example 05 as the server)
+# and exposes its tools locally via dynamic reflection. Type: echo: hello
+
+class DemoIntelligence < VSM::Intelligence
+  def handle(message, bus:, **)
+    case message.kind
+    when :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
+    when :tool_result
+      bus.emit VSM::Message.new(kind: :assistant, payload: "(done)", meta: message.meta)
+      true
+    else
+      false
+    end
+  end
+end
+
+server_cmd = "ruby #{File.expand_path("05_mcp_server_and_chattty.rb", __dir__)}"
+
+cap = VSM::DSL.define(:mcp_mount_demo) do
+  identity     klass: VSM::Identity,     args: { identity: "mcp_mount_demo", invariants: [] }
+  governance   klass: VSM::Governance
+  coordination klass: VSM::Coordination
+  intelligence klass: DemoIntelligence
+  monitoring   klass: VSM::Monitoring
+  operations do
+    # Reflect the remote server's tools; include only :echo and expose as local name "echo"
+    mcp_server :demo_server, cmd: server_cmd, include: %w[echo]
+  end
+end
+
+banner = ->(io) { io.puts "\e[96mMCP mount demo\e[0m — type 'echo: hi' (Ctrl-C to exit)" }
+VSM::Runtime.start(cap, ports: [VSM::Ports::ChatTTY.new(capsule: cap, banner: banner)])

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