VSM

https://github.com/sublayerapp/vsm
Admin
VSM is a Ruby gem providing a composable, testable architecture for building agentic systems with...
Tokens:11,254
Snippets:53
Trust Score:6.9
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Running the VSM CLI Application

Source: https://github.com/sublayerapp/vsm/blob/main/README.md

Command to execute the VSM quickstart script and an example interaction.

```bash
ruby quickstart.rb
# You: echo: hello
# Tool> you said: hello
```

--------------------------------

### Install Dependencies

Source: https://github.com/sublayerapp/vsm/blob/main/CLAUDE.md

Installs all necessary project dependencies defined in the Gemfile.

```Bash
bundle install
```

--------------------------------

### Start VSM Runtime with Custom Ports

Source: https://github.com/sublayerapp/vsm/blob/main/README.md

Shows how to start the VSM runtime with a given capsule and a list of custom ports.

```ruby
VSM::Runtime.start(capsule, ports: [MyPort.new(capsule:)])
```

--------------------------------

### Install Gem Locally

Source: https://github.com/sublayerapp/vsm/blob/main/CLAUDE.md

Installs the built VSM gem into the local Ruby environment.

```Bash
bundle exec rake install
```

--------------------------------

### Start IRB with VSM Loaded

Source: https://github.com/sublayerapp/vsm/blob/main/CLAUDE.md

Starts an interactive Ruby console (IRB) with the VSM gem pre-loaded, allowing for immediate experimentation.

```Bash
bundle exec irb -r vsm
```

--------------------------------

### Starting VSM Runtime with StdinPort

Source: https://github.com/sublayerapp/vsm/blob/main/README.md

Initiates the VSM runtime, providing a capsule and configuring it to use the StdinPort for interaction.

```ruby
# 5) Start the runtime
VSM::Runtime.start(capsule, ports: [StdinPort.new(capsule:)])
```

--------------------------------

### Build Gem

Source: https://github.com/sublayerapp/vsm/blob/main/CLAUDE.md

Builds the VSM gem, creating a package for distribution or local installation.

```Bash
bundle exec rake build
```

--------------------------------

### Minimal Agent with Echo Tool

Source: https://github.com/sublayerapp/vsm/blob/main/README.md

A minimal Ruby agent example using VSM. It defines an EchoTool capsule, a DemoIntelligence to handle user input and call the tool, and builds the agent using the VSM DSL.

```Ruby
require "securerandom"
require "vsm"

# 1) Define a tool as a capsule
class EchoTool < VSM::ToolCapsule
  tool_name "echo"
  tool_description "Echoes a message"
  tool_schema({
    type: "object",
    properties: { text: { type: "string" } },
    required: ["text"]
  })

  def run(args)
    "you said: #{args["text"]}"
  end
end

# 2) Define your Intelligence (decides what to do)
class DemoIntelligence < VSM::Intelligence
  def handle(message, bus:,
 **)
    return false unless message.kind == :user

    if message.payload =~ /\Aecho:\s*(.+)\z/
      # User said "echo: something" - call the tool
      bus.emit VSM::Message.new(
        kind: :tool_call,
        payload: { tool: "echo", args: { "text" => $1 } },
        corr_id: SecureRandom.uuid,
        meta: message.meta
      )
    else
      # Just respond
      bus.emit VSM::Message.new(
        kind: :assistant,
        payload: "Try: echo: hello",
        meta: message.meta
      )
    end
    true
  end
end

# 3) Build your agent using the DSL
capsule = VSM::DSL.define(:demo) do
  identity     klass: VSM::Identity,    args: { identity: "demo", invariants: [] }
  governance   klass: VSM::Governance
  coordination klass: VSM::Coordination
  intelligence klass: DemoIntelligence
  operations do
    capsule :echo, klass: EchoTool
  end
end

```

--------------------------------

### Minimal VSM Intelligence Example

Source: https://github.com/sublayerapp/vsm/blob/main/README.md

A basic implementation of the VSM Intelligence role. It handles user messages and tool results, forwarding user input to a 'read_file' tool when a pattern is matched.

```ruby
class MyIntelligence < VSM::Intelligence
  def initialize
    @history = Hash.new { |h,k| h[k] = [] }
  end

  def handle(message, bus:, **)
    return false unless [:user, :tool_result].include?(message.kind)
    sid = message.meta&.dig(:session_id)
    @history[sid] << message

    if message.kind == :user && message.payload =~ /read (.+)/
      bus.emit VSM::Message.new(
        kind: :tool_call,
        payload: { tool: "read_file", args: { "path" => $1 } },
        corr_id: SecureRandom.uuid,
        meta: { session_id: sid }
      )
    else
      bus.emit VSM::Message.new(kind: :assistant, payload: "ok", meta: { session_id: sid })
    end
    true
  end
end
```

--------------------------------

### Implement a Custom VSM Port

Source: https://github.com/sublayerapp/vsm/blob/main/README.md

Provides an example of a custom VSM Port that handles input from stdin and renders output to stdout. It manages session IDs and confirms user requests.

```ruby
class MyPort < VSM::Port
  def loop
    session = SecureRandom.uuid
    while (line = $stdin.gets&.chomp)
      @capsule.bus.emit VSM::Message.new(kind: :user, payload: line, meta: { session_id: session })
      @capsule.roles[:coordination].wait_for_turn_end(session)
    end
  end

  def render_out(msg)
    case msg.kind
    when :assistant_delta then $stdout.print(msg.payload)
    when :assistant       then puts "\nBot: #{msg.payload}"
    when :confirm_request then confirm(msg)
    end
  end

  def confirm(msg)
    print "\nConfirm? #{msg.payload} [y/N] "
    ok = ($stdin.gets || "").strip.downcase.start_with?("y")
    @capsule.bus.emit VSM::Message.new(kind: :confirm_response, payload: { accepted: ok }, meta: msg.meta)
  end
end
```

--------------------------------

### Install VSM Gem

Source: https://github.com/sublayerapp/vsm/blob/main/README.md

Instructions for adding the VSM gem to your Ruby project's Gemfile and installing it using Bundler. Ruby version 3.2+ is recommended.

```Ruby
# Gemfile
gem "vsm", "~> 0.0.1"
```

```Shell
bundle install
```

--------------------------------

### Building Capsules with DSL

Source: https://github.com/sublayerapp/vsm/blob/main/CLAUDE.md

Shows how to use the VSM DSL to declaratively define a capsule, including its five systems and child capsules.

```Ruby
capsule = VSM::DSL.define(:name) do
  identity     klass: VSM::Identity, args: { identity: "name", invariants: [] }
  governance   klass: VSM::Governance
  coordination klass: VSM::Coordination  
  intelligence klass: MyIntelligence
  operations do
    capsule :tool_name, klass: ToolClass
  end
end
```

--------------------------------

### Sublayerapp VSM Change Request Guidelines

Source: https://github.com/sublayerapp/vsm/blob/main/llms.txt

Instructions on how to request changes for the Sublayerapp VSM project, emphasizing concrete goals, unified diffs, README updates, testing, and impact on Lens/TUI rendering.

```General
- Provide concrete goals and constraints (e.g., “Add a `search_repo` tool that scans *.rb files for a pattern; thread executor; unit tests; and show it in Lens with meta.tool”).
- Ask for *unified diffs* with exact file paths under lib/ and spec/. Keep patches minimal and focused.
- Require updates to README snippets if public API changes.
- Have it add/extend tests and run them locally (`bundle exec rspec`).
- If the change affects the message kinds or meta fields, ensure Lens/TUI still render sensibly.
```

--------------------------------

### VSM Testing Strategies

Source: https://github.com/sublayerapp/vsm/blob/main/README.md

Guidelines for testing different components of the VSM framework, including capsules, intelligence, tools, and ports, with specific recommendations for assertion and injection.

```markdown
- **Capsules**: inject fake systems and assert dispatch.
- **Intelligence**: feed `:user` / `:tool_result` messages and assert emitted messages.
- **Tools**: call `#run` directly.
- **Ports**: treat like adapters; they're thin.
```

--------------------------------

### VSM Development Commands

Source: https://github.com/sublayerapp/vsm/blob/main/README.md

Commands for running tests and linting the VSM project using RSpec and RuboCop.

```bash
bundle exec rspec
```

```bash
bundle exec rubocop
```

--------------------------------

### Creating a Tool Capsule

Source: https://github.com/sublayerapp/vsm/blob/main/CLAUDE.md

Demonstrates how to create a custom tool by inheriting from VSM::ToolCapsule, defining metadata, and implementing the run method.

```Ruby
class MyTool < VSM::ToolCapsule
  tool_name "my_tool"
  tool_description "Description"
  tool_schema({ type: "object", properties: { ... }, required: [...] })
  
  def run(args)
    # Tool implementation
  end
  
  def execution_mode = :fiber # or :thread
end
```

--------------------------------

### VSM Extending Framework: Add Provider

Source: https://github.com/sublayerapp/vsm/blob/main/llms.txt

Instructions for adding a new provider to the VSM framework. This involves placing the new driver code under the `lib/vsm/intelligence/<provider>/` directory.

```Markdown
C) Add a provider
- Place a new driver_* under lib/vsm/intelligence/<provider>/
```

--------------------------------

### Implement a Tool as a VSM ToolCapsule

Source: https://github.com/sublayerapp/vsm/blob/main/llms.txt

Demonstrates how to create a custom tool by subclassing VSM::ToolCapsule and including the ActsAsTool module. It shows how to define the tool's name, description, schema, execution mode, and the `run` method for its logic. The schema should be compatible with OpenAI, Anthropic, and Gemini.

```Ruby
class MyTool < VSM::ToolCapsule
  tool_name "search_repo"
  tool_description "Search codebase by regex"
  tool_schema({
    type: "object",
    properties: { pattern: { type: "string" }, path: { type: "string" } },
    required: ["pattern"]
  })

  def execution_mode = :thread  # optional; defaults to :fiber
  def run(args)
    # return a String or small JSON-compatible object
  end
end
```

--------------------------------

### VSM Core Systems and Components

Source: https://github.com/sublayerapp/vsm/blob/main/llms.txt

Outlines the expected file layout for the VSM gem, detailing the purpose of each file and directory, including core components like messages, channels, roles, tools, executors, and drivers.

```Ruby
# lib/vsm.rb
# top-level requires

# lib/vsm/message.rb
# Message struct

# lib/vsm/async_channel.rb
# async bus (fibers)

# lib/vsm/homeostat.rb
# budgets/alerts (minimal)

# lib/vsm/observability/ledger.rb
# Monitoring role: JSONL event ledger

# lib/vsm/roles/
#   operations.rb                 # runs tools (capsules) via executors
#   coordination.rb               # scheduling, floor control, turn end
#   intelligence.rb               # abstract; apps subclass this
#   governance.rb                 # policy/budgets/confirmation hooks
#   identity.rb                   # invariants/escalation

# lib/vsm/tool/
#   descriptor.rb                 # name/description/schema → provider shapes
#   acts_as_tool.rb               # mixin to mark capsules as tools
#   capsule.rb                    # base tool capsule (implements #run)

# lib/vsm/executors/
#   fiber_executor.rb             # default (IO-bound)
#   thread_executor.rb            # CPU-ish or blocking libs
#   # (optional) ractor_executor.rb / subprocess_executor.rb

# lib/vsm/capsule.rb              # Capsule: wires systems, async run loop
# lib/vsm/dsl.rb                  # DSL for composing organisms & children
# lib/vsm/port.rb                 # adapter base (CLI/TUI/HTTP/etc.)
# lib/vsm/runtime.rb              # boot helper: start capsule + ports

# lib/vsm/drivers/
#   family.rb              # returns :openai | :anthropic | :gemini
#   openai/async_driver.rb        # SSE streaming + tools
#   anthropic/async_driver.rb     # SSE streaming + tool_use blocks
#   gemini/async_driver.rb        # non-streaming MVP + functionCall

# lib/vsm/lens.rb                     # Lens.attach!(capsule, ...)
# lib/vsm/lens/event_hub.rb           # ring buffer + fan-out
# lib/vsm/lens/server.rb              # Rack app + SSE + tiny HTML

# spec/                             # RSpec tests (smoke + providers + routing)
# examples/                         # small runnable demos

```

--------------------------------

### Sublayerapp VSM License and Attribution

Source: https://github.com/sublayerapp/vsm/blob/main/llms.txt

Information regarding the licensing and attribution for the Sublayerapp VSM project, defaulting to MIT and respecting third-party licenses, with an emphasis on optional provider SDKs.

```General
- MIT by default (edit gemspec if different). Respect third-party licenses for gems you add.
- Keep provider SDKs optional; current drivers use `async-http` + stdlib only.
```

--------------------------------

### Convert Tool Descriptor to Provider Formats

Source: https://github.com/sublayerapp/vsm/blob/main/README.md

Demonstrates how to convert a VSM tool descriptor into formats compatible with different AI providers like OpenAI, Anthropic, and Gemini.

```ruby
tool = instance.tool_descriptor
tool.to_openai_tool    # => {type:"function", function:{ name, description, parameters }}
tool.to_anthropic_tool # => {name, description, input_schema}
tool.to_gemini_tool    # => {name, description, parameters}
```

--------------------------------

### VSM Provider Configuration

Source: https://github.com/sublayerapp/vsm/blob/main/llms.txt

Lists environment variables used for configuring VSM providers, including API keys and model names for OpenAI, Anthropic, and Gemini, as well as settings for VSM Lens.

```Shell
# OpenAI
OPENAI_API_KEY=...
AIRB_MODEL=gpt-4o-mini

# Anthropic
ANTHROPIC_API_KEY=...
AIRB_MODEL=claude-3-5-sonnet-latest

# Gemini
GEMINI_API_KEY=...
AIRB_MODEL=gemini-2.0-flash-001

# General
AIRB_PROVIDER=openai | anthropic | gemini
VSM_LENS=1
VSM_LENS_PORT=9292
VSM_LENS_TOKEN=...
```

--------------------------------

### Sublayerapp VSM Event Handling and MCP Support

Source: https://github.com/sublayerapp/vsm/blob/main/llms.txt

Details on event yielding (:assistant_delta, :assistant_final, :tool_calls), descriptor conversion for tool shapes, and the future plan for MCP support including server and client implementations.

```General
- Yield the same three events (:assistant_delta, :assistant_final, :tool_calls)
- Add a descriptor conversion if provider needs a special tool shape
- Update DriverFamily.of to map the class → symbol

D) Add MCP support (future plan)
- Implement Ports::MCP::Server to expose tools via MCP spec
- Implement Ports::MCP::Client to consume external MCP tools and wrap as tool capsules
```

--------------------------------

### VSM API Overview

Source: https://github.com/sublayerapp/vsm/blob/main/README.md

A comprehensive overview of the VSM module, including core components like Messages, Bus, Roles, Capsules, Tools, Ports, and Runtime.

```APIDOC
module VSM
  # Messages
  Message(kind:, payload:, path: nil, corr_id: nil, meta: {})

  # Bus
  class AsyncChannel
    def emit(message); end
    def pop; end
    def subscribe(&block); end
    attr_reader :context
  end

  # Roles (named systems)
  class Operations;    end  # routes tool_call -> children
  class Coordination;  end  # scheduling, floor, turn-end
  class Intelligence;  end  # your planning/LLM driver
  class Governance;    end  # policy/safety/budgets
  class Identity;      end  # invariants & escalation
  class Monitoring;    end  # JSONL ledger (observe)

  # Capsules & DSL
  class Capsule; end
  module DSL
    def self.define(:name, &block) -> Capsule
  end

  # Tools
  module Tool
    Descriptor#to_openai_tool / #to_anthropic_tool / #to_gemini_tool
  end
  module ActsAsTool; end
  class ToolCapsule
    # include ActsAsTool
    # def run(args) ...
    # def execution_mode = :fiber | :thread
  end

  # Ports & runtime
  class Port
    def initialize(capsule:); end
    def loop; end           # optional
    def render_out(msg); end
    def egress_subscribe; end
  end

  module Runtime
    def self.start(capsule, ports: [])
  end
end
```

--------------------------------

### VSM DSL for Assembly

Source: https://github.com/sublayerapp/vsm/blob/main/llms.txt

Demonstrates the Domain Specific Language (DSL) for assembling VSM applications. It shows how to define an 'organism' with identity, governance, coordination, intelligence, and monitoring components, and register operations like tool capsules.

```Ruby
org = VSM::DSL.define(:airb) do
  identity     klass: MyIdentity,    args: { identity: "airb", invariants: ["stay in workspace"] }
  governance   klass: MyGovernance,  args: { workspace_root: Dir.pwd }
  coordination klass: VSM::Coordination
  intelligence klass: MyIntelligence, args: { driver: my_driver }
  monitoring   klass: VSM::Monitoring

  operations do
    capsule :list_files, klass: Tools::ListFiles
    capsule :read_file,  klass: Tools::ReadFile
    capsule :edit_file,  klass: Tools::EditFile
  end
end

VSM::Runtime.start(org, ports: [ChatTTY.new(capsule: org)])
```

--------------------------------

### Sublayerapp VSM Known Limitations and TODOs

Source: https://github.com/sublayerapp/vsm/blob/main/llms.txt

Lists current known limitations and future development tasks for the Sublayerapp VSM project, including Ractor/Subprocess executors, Gemini streaming, Homeostat budgets, and Lens UI.

```General
- Ractor/Subprocess executors are stubs in some scaffolds; implement when needed.
- Gemini streaming is not wired yet (MVP uses non-streaming). Add Live/stream endpoints later.
- Homeostat budgets are placeholders; implement counters and algedonic signals as needed.
- Lens has minimal UI; extract richer vsm-lens gem when features grow.
```

--------------------------------

### MyLLMIntelligence Responsibilities

Source: https://github.com/sublayerapp/vsm/blob/main/README.md

Outlines the key responsibilities for a custom `MyLLMIntelligence` class, focusing on managing conversation history, interacting with LLM providers, and handling tool calls and responses.

```ruby
Your `MyLLMIntelligence` would:
1. Maintain conversation history
2. Call your LLM provider with available tools
3. Emit `:tool_call` messages when the LLM wants to use tools
4. Stream `:assistant_delta` tokens as they arrive
5. Emit final `:assistant` message when done
```

--------------------------------

### LLM Provider Driver Integration

Source: https://github.com/sublayerapp/vsm/blob/main/llms.txt

Details the integration with different LLM providers (OpenAI, Anthropic, Gemini) for the Intelligence system. It explains how conversation history is managed, the types of events yielded by drivers, and how to format tool calls and results for each provider. It also covers driver selection and building provider-specific tool arrays.

```APIDOC
Intelligence subclasses handle per-session conversation history and call a driver’s run!(conversation:, tools:, policy:) which yields three events:
  - [:assistant_delta, String]  — stream partial text
  - [:assistant_final, String]  — final text for the turn (may be empty if only tool calls)
  - [:tool_calls, Array<Hash>]  — each { id:, name:, arguments: Hash }

Conversation messages passed into drivers are hashes like:
{ role: "system"|"user"|"assistant"|"tool", content: String, tool_call_id?: String }

Providers:
- OpenAI::DriverAsync — SSE streaming; tools in choices[].delta.tool_calls; pass tools via `[{type:"function", function:{name, description, parameters}}]`.
- Anthropic::DriverAsync — SSE streaming; `tool_use` content blocks with `input_json_delta` fragments; pass tools via `[{name, description, input_schema}]`; tool_result fed back as a user content block `{type:"tool_result", tool_use_id, content}`.
- Gemini::DriverAsync — non-streaming MVP; declare tools via `function_declarations`; receive `functionCall`; reply next turn with `functionResponse`.

Driver selection:
- VSM::Intelligence::DriverFamily.of(@driver) → :openai | :anthropic | :gemini.
- Build provider-specific tool arrays from VSM::Tool::Descriptor:
  - to_openai_tool, to_anthropic_tool, to_gemini_tool.
```

--------------------------------

### Sublayerapp VSM Safety and Security Guidelines

Source: https://github.com/sublayerapp/vsm/blob/main/llms.txt

Essential safety and security practices for the Sublayerapp VSM project, including workspace restrictions, confirmation for risky writes, timeouts, concurrency control, and secrets management.

```General
- Never write outside the workspace. Use Governance.safe_path() in tools.
- Confirm risky writes with :confirm_request → :confirm_response.
- Add timeouts on tool calls and LLM calls (budget via Homeostat or Governance).
- Use semaphores to cap concurrency per tool to avoid resource exhaustion.
- Do not log secrets. Mask API keys and sensitive args before emitting events.
```

--------------------------------

### VSM Coding Standards

Source: https://github.com/sublayerapp/vsm/blob/main/llms.txt

Outlines coding standards for VSM, emphasizing idiomatic Ruby, small objects, Single Responsibility Principle (SRP), explicit dependencies, avoiding global mutable state, non-blocking I/O, and structured commit messages.

```Markdown
- Idiomatic Ruby, small objects, SRP. Keep classes under ~150 LOC when possible.
- Favor explicit dependencies via initializer args.
- Avoid global mutable state. If you add caches, use per-capsule fields.
- Don’t block fibers: for I/O use async-http; for CPU spikes switch to thread executor.
- Tests for every new adapter/driver parser with fixtures; route tests for message sequencing.
- Prefer incremental diffs (unified patches) with file paths and clear commit titles:
  - Title: <module>: <short imperative> (e.g., "intelligence/openai: handle empty delta lines")
  - Body: “Why”, “What changed”, “Tests”.
```

--------------------------------

### VSM Lens Observability

Source: https://github.com/sublayerapp/vsm/blob/main/llms.txt

Details how to enable and use VSM's Lens for observability. Lens is a Rack app that serves an SSE `/events` feed with an HTML viewer. It requires attaching Lens to a capsule with host, port, and token configuration.

```Ruby
VSM::Lens.attach!(capsule, host: "127.0.0.1", port: 9292, token: ENV["VSM_LENS_TOKEN"])
```

--------------------------------

### Alternative Linter Runner

Source: https://github.com/sublayerapp/vsm/blob/main/CLAUDE.md

Uses the Rake task to run the RuboCop linter.

```Bash
rake rubocop
```

--------------------------------

### VSM ChatTTY Port

Source: https://github.com/sublayerapp/vsm/blob/main/llms.txt

Defines the ChatTTY port for VSM, which reads stdin lines, emits user events with session IDs, renders assistant deltas and final responses, and handles confirmation requests.

```Ruby
VSM::Port
  #ingress(event)
  #render_out(message)

ChatTTY port: reads stdin lines, emits :user with meta.session_id; renders :assistant_delta (stream) and :assistant (final), handles :confirm_request → :confirm_response.
```

--------------------------------

### Run Tests and Linter

Source: https://github.com/sublayerapp/vsm/blob/main/CLAUDE.md

Executes both tests and the linter as the default Rake task.

```Bash
rake
```

--------------------------------

### VSM Testing Baseline

Source: https://github.com/sublayerapp/vsm/blob/main/llms.txt

Specifies the minimum baseline tests for VSM, including routing smoke tests, provider parsing tests for different SSE/tool call formats, governance tests for sandbox security, and concurrency tests for parallel tool calls.

```Markdown
- Routing smoke test: :tool_call → :tool_result → :assistant
- Provider parsing tests:
  - OpenAI SSE fixture → emits deltas + final + tool_calls
  - Anthropic SSE fixture with tool_use/input_json_delta → emits tool_calls + final
  - Gemini functionCall fixture → emits tool_calls or final text
- Governance tests: sandbox rejects path traversal; confirm flow produces :confirm_request
- Concurrency tests: parallel tool calls produce paired results (different corr_id), no interleaved confusion in Coordination
```

--------------------------------

### Asynchrony and Parallelism in VSM

Source: https://github.com/sublayerapp/vsm/blob/main/llms.txt

Explains the asynchronous and parallel execution model within the VSM application. It covers the use of fibers for the bus, concurrency management for tool execution using Executors (:fiber, :thread, :ractor/:subprocess), and the role of Async::Semaphore for capping concurrency. It also mentions `Coordination.wait_for_turn_end` for blocking CLI ports.

```APIDOC
The bus is fiber-based (`async` gem). Capsule.run loops on bus.pop and lets Coordination drain/schedule messages.
Operations executes each tool_call concurrently via an Executor:
  - :fiber (default) for IO-aware code
  - :thread for brief CPU spikes or blocking C libs
  - (:ractor/:subprocess) later for isolation or heavy CPU
Use Async::Semaphore to cap per-tool concurrency if needed.
Coordination.wait_for_turn_end(session_id) enables CLI ports to block until the assistant final is emitted for the turn.
```

--------------------------------

### VSM Extending Framework: Add Tool Capsule

Source: https://github.com/sublayerapp/vsm/blob/main/llms.txt

Instructions for adding a new tool capsule to the VSM framework. This involves creating a class inheriting from `VSM::ToolCapsule`, declaring its schema, implementing the `#run` method, and registering it in the operations DSL.

```Markdown
A) Add a new tool capsule
- Create class <YourTool> < VSM::ToolCapsule
- Declare name/description/schema; implement #run; optional #execution_mode
- Register in operations DSL
```

--------------------------------

### VSM CLI Interface with StdinPort

Source: https://github.com/sublayerapp/vsm/blob/main/README.md

Implements a simple command-line interface for VSM, allowing user input via stdin. It emits user messages to the bus and handles assistant and tool result messages for rendering output.

```ruby
class StdinPort < VSM::Port
  def loop
    session = SecureRandom.uuid
    print "You: "
    while (line = $stdin.gets&.chomp)
      @capsule.bus.emit VSM::Message.new(
        kind: :user, 
        payload: line, 
        meta: { session_id: session }
      )
      @capsule.roles[:coordination].wait_for_turn_end(session)
      print "You: "
    end
  end

  def render_out(msg)
    case msg.kind
    when :assistant
      puts "\nBot: #{msg.payload}"
    when :tool_result
      puts "\nTool> #{msg.payload}"
      @capsule.bus.emit VSM::Message.new(
        kind: :assistant, 
        payload: "(done)", 
        meta: msg.meta
      )
    end
  end
end
```

--------------------------------

### VSM Extending Framework: Add Sub-agent Capsule

Source: https://github.com/sublayerapp/vsm/blob/main/llms.txt

Guidance on adding a sub-agent capsule to VSM. This includes providing its own components (Operations, Coordination, etc.) and optionally including `ActsAsTool` to expose itself as a parent tool whose `#run` method orchestrates internal steps.

```Markdown
B) Add a sub-agent capsule
- Provide its own Operations/Coordination/Intelligence/Governance/Identity (recursive)
- Optionally include ActsAsTool and expose itself as a parent tool (its #run orchestrates internal steps and returns a string)
```

--------------------------------

### Run Linter

Source: https://github.com/sublayerapp/vsm/blob/main/CLAUDE.md

Executes the RuboCop linter to check for code style and potential issues.

```Bash
bundle exec rubocop
```

--------------------------------

### VSM Capsule Structure and Dispatch

Source: https://github.com/sublayerapp/vsm/blob/main/llms.txt

Describes the 'ORG' spine of the VSM application, detailing the components within a Capsule, including the bus, homeostat, roles, and children. It also outlines the typical dispatch order for system messages between Operations, Intelligence, and Identity capsules.

```APIDOC
Capsule contains:
- bus: AsyncChannel (fiber-friendly queue + subscribers)
- homeostat: budgets/alerts (minimal for MVP)
- roles: five named systems
  - Operations: runs tools, dispatches to child tool-capsules
  - Coordination: schedules messages; grants floor per session; turn end
  - Intelligence: orchestrates LLM driver; streams deltas; emits tool_calls
  - Governance: policy gates (sandboxing, confirmation, budgets)
  - Identity: invariants, escalation to owner/user
- children: Hash of name → child capsule (often tool capsules)

Dispatch order (typical): Operations → Intelligence → Identity
(Operations consumes :tool_call; Intelligence consumes :user/:tool_result; Identity handles policy updates/broadcasts.)
```

--------------------------------

### VSM Capsule Structure

Source: https://github.com/sublayerapp/vsm/blob/main/README.md

Illustrates the internal structure of a VSM Capsule, detailing its five named systems (Identity, Governance, Coordination, Intelligence, Operations) and its message bus, with an optional Monitoring system.

```ruby
Capsule(:name)
├─ Identity      (purpose & invariants)
├─ Governance    (safety & budgets)
├─ Coordination  (scheduling & "floor")
├─ Intelligence  (planning/deciding)
├─ Operations    (tools/skills)
└─ Monitoring    (event ledger; optional)
```

--------------------------------

### Run All Tests

Source: https://github.com/sublayerapp/vsm/blob/main/CLAUDE.md

Executes all tests within the VSM project using RSpec. This is a fundamental command for verifying the integrity of the codebase.

```Bash
bundle exec rspec
```

--------------------------------

### Governance and Identity System Roles

Source: https://github.com/sublayerapp/vsm/blob/main/llms.txt

Outlines the responsibilities of the Governance and Identity systems within VSM. Governance enforces policies like sandboxing, confirmations, and timeouts, potentially emitting confirmation requests. Identity maintains invariants and handles escalations, broadcasting policy changes received via messages.

```APIDOC
Governance.enforce(message) wraps routing. Add sandboxing, diff previews, confirmations, budgets, and timeouts here.
Emit :confirm_request when needed; the Port must collect a :confirm_response.
Identity holds invariants (e.g., “stay in workspace”), escalates algedonic alerts (homeostat.alarm?).

LLM policy changes should emit a :policy message that Identity can broadcast to children if necessary.
```

--------------------------------

### Alternative Test Runner

Source: https://github.com/sublayerapp/vsm/blob/main/CLAUDE.md

Uses the Rake task to run all tests, providing an alternative to the direct RSpec command.

```Bash
rake spec
```

--------------------------------

### VSM Message Struct

Source: https://github.com/sublayerapp/vsm/blob/main/llms.txt

Defines the structure for messages within the VSM runtime, including kind, payload, path, correlation ID, and metadata. Guidance is provided for LLMs on setting session IDs and tool-related metadata.

```APIDOC
Struct: VSM::Message.new(
  kind: Symbol — :user, :assistant_delta, :assistant, :tool_call, :tool_result, :plan, :policy, :audit, :confirm_request, :confirm_response, :progress
  payload: Object/String — event-specific data
  path: Array<Symbol> — addressing (e.g., [:airb, :operations, :read_file])
  corr_id: String — correlates tool_call <-> tool_result
  meta: Hash — session_id, tool name, budgets, severity, etc.
)

Guidance for LLMs:
- Always set meta.session_id for multi-turn sessions.
- When emitting tool events, fill meta.tool and corr_id for pairing.
- Keep payload compact; include previews for large data.
```

--------------------------------

### Defining a Real Agent with LLM Integration

Source: https://github.com/sublayerapp/vsm/blob/main/README.md

Defines a VSM capsule for a real agent, including identity, governance, coordination, intelligence (LLM integration), and optional monitoring. It also defines available operations (tools).

```ruby
capsule = VSM::DSL.define(:my_agent) do
  identity     klass: VSM::Identity, 
               args: { identity: "my_agent", invariants: ["stay in workspace"] }
  governance   klass: VSM::Governance
  coordination klass: VSM::Coordination
  intelligence klass: MyLLMIntelligence  # Your class that calls OpenAI/Anthropic/etc
  monitoring   klass: VSM::Monitoring    # Optional: writes JSONL event log
  
  operations do
    capsule :list_files, klass: ListFilesTool
    capsule :read_file,  klass: ReadFileTool
    capsule :write_file, klass: WriteFileTool
  end
end
```

--------------------------------

### Run Specific Test File

Source: https://github.com/sublayerapp/vsm/blob/main/CLAUDE.md

Executes tests only for a specific file, useful for targeted testing during development.

```Bash
bundle exec rspec spec/vsm_spec.rb
```

--------------------------------

### Release Gem

Source: https://github.com/sublayerapp/vsm/blob/main/CLAUDE.md

Releases the VSM gem to a gem repository (e.g., RubyGems). This command is typically for maintainers.

```Bash
bundle exec rake release
```

--------------------------------

### Define a VSM Tool Capsule

Source: https://github.com/sublayerapp/vsm/blob/main/README.md

Defines a Ruby class that acts as a VSM tool. It includes a tool name, description, schema for arguments, and a run method. The execution mode can be specified as :fiber or :thread.

```ruby
class ReadFile < VSM::ToolCapsule
  tool_name "read_file"
  tool_description "Read the contents of a UTF-8 text file at relative path."
  tool_schema({
    type: "object",
    properties: { path: { type: "string" } },
    required: ["path"]
  })

  def run(args)
    path = governance_safe_path(args.fetch("path"))
    File.read(path, mode: "r:UTF-8")
  end

  # Optional: choose how this tool executes
  def execution_mode = :fiber   # or :thread
  
  private
  
  def governance_safe_path(rel) = governance.instance_eval { # simple helper
    full = File.expand_path(File.join(Dir.pwd, rel))
    raise "outside workspace" unless full.start_with?(Dir.pwd)
    full
  }
end
```

--------------------------------

### VSM Tool Dispatch Smoke Test

Source: https://github.com/sublayerapp/vsm/blob/main/README.md

A Ruby RSpec test demonstrating how VSM routes tool calls to tool results. It sets up a simple tool capsule and asserts that the correct output is received when a tool call is emitted.

```ruby
require "vsm"

RSpec.describe "tool dispatch" do
  class T < VSM::ToolCapsule
    tool_name "t"; tool_description "d"; tool_schema({ type: "object", properties: {}, required: [] })
    def run(_args) = "ok"
  end

  it "routes tool_call to tool_result" do
    cap = VSM::DSL.define(:test) do
      identity     klass: VSM::Identity, args: { identity: "t", invariants: [] }
      governance   klass: VSM::Governance
      coordination klass: VSM::Coordination
      intelligence klass: VSM::Intelligence
      operations { capsule :t, klass: T }
    end

    q = Queue.new
    cap.bus.subscribe { |m| q << m if m.kind == :tool_result }
    cap.run
    cap.bus.emit VSM::Message.new(kind: :tool_call, payload: { tool: "t", args: {} }, corr_id: "1")
    expect(q.pop.payload).to eq("ok")
  end
end
```

--------------------------------

### VSM Message Structure

Source: https://github.com/sublayerapp/vsm/blob/main/README.md

Defines the structure of a VSM Message, including its kind, payload, optional path and correlation ID, and metadata for additional context.

```ruby
VSM::Message.new(
  kind:    :user | :assistant | :assistant_delta | :tool_call | :tool_result | :plan | :policy | :audit | :confirm_request | :confirm_response,
  payload: "any",
  path:    [:airb, :operations, :fs], # optional addressing
  corr_id: "uuid",                     # correlate tool_call ↔ tool_result
  meta:    { session_id: "uuid", ... } # extra context
)
```

--------------------------------

### VSM Message Structure

Source: https://github.com/sublayerapp/vsm/blob/main/CLAUDE.md

Illustrates the structure of a VSM::Message object, including its kind, payload, correlation ID, and metadata.

```Ruby
VSM::Message.new(
  kind: :user | :assistant | :assistant_delta | :tool_call | :tool_result | :plan | :policy | :audit,
  payload: any_data,
  corr_id: "correlation_id_for_tool_calls",
  meta: { session_id: "uuid", ... }
)
```
Tokens:
Raw