vsm 0.0.1 → 0.1.0

data/lib/vsm/roles/intelligence.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+require "set"
+require_relative "../drivers/family"
+
+module VSM
+  # Orchestrates multi-turn LLM chat with native tool-calls:
+  # - Maintains neutral conversation history per session_id
+  # - Talks to a provider driver that yields :assistant_delta, :assistant_final, :tool_calls
+  # - Emits :tool_call to Operations, waits for ALL results, then continues
+  #
+  # App authors can subclass and only customize:
+  #   - system_prompt(session_id) -> String
+  #   - offer_tools?(session_id, descriptor) -> true/false (filter tools)
+  class Intelligence
+    def initialize(driver:, system_prompt: nil)
+      @driver         = driver
+      @system_prompt  = system_prompt
+      @sessions       = Hash.new { |h,k| h[k] = new_session_state }
+    end
+
+    def observe(bus); end
+
+    def handle(message, bus:, **)
+      case message.kind
+      when :user
+        sid = message.meta&.dig(:session_id)
+        st  = state(sid)
+        st[:history] << { role: "user", content: message.payload.to_s }
+        invoke_model(sid, bus)
+        true
+
+      when :tool_result
+        sid = message.meta&.dig(:session_id)
+        st  = state(sid)
+        # map id -> tool name if we learned it earlier (useful for Gemini)
+        name = st[:tool_id_to_name][message.corr_id]
+        
+        # Debug logging
+        if ENV["VSM_DEBUG_STREAM"] == "1"
+          $stderr.puts "Intelligence: Received tool_result for #{name}(#{message.corr_id}): #{message.payload.to_s.slice(0, 100)}"
+        end
+        
+        st[:history] << { role: "tool_result", tool_call_id: message.corr_id, name: name, content: message.payload.to_s }
+        st[:pending_tool_ids].delete(message.corr_id)
+        # Only continue once all tool results for this turn arrived:
+        if st[:pending_tool_ids].empty?
+          # Re-enter model for the same turn with tool results in history:
+          invoke_model(sid, bus)
+        end
+        true
+
+      else
+        false
+      end
+    end
+
+    # --- Extension points for apps ---
+
+    # Override to compute a dynamic prompt per session
+    def system_prompt(session_id)
+      @system_prompt
+    end
+
+    # Override to filter tools the model may use (by descriptor)
+    def offer_tools?(session_id, descriptor)
+      true
+    end
+
+    private
+
+    def new_session_state
+      {
+        history: [],
+        pending_tool_ids: Set.new,
+        tool_id_to_name: {},
+        inflight: false,
+        turn_seq: 0
+      }
+    end
+
+    def state(sid) = @sessions[sid]
+
+    def invoke_model(session_id, bus)
+      st = state(session_id)
+      if st[:inflight] || !st[:pending_tool_ids].empty?
+        if ENV["VSM_DEBUG_STREAM"] == "1"
+          $stderr.puts "Intelligence: skip invoke sid=#{session_id} inflight=#{st[:inflight]} pending=#{st[:pending_tool_ids].size}"
+        end
+        return
+      end
+      st[:inflight] = true
+      st[:turn_seq] += 1
+      current_turn_id = st[:turn_seq]
+
+      # Discover tools available from Operations children:
+      descriptors, name_index = tool_inventory(bus, session_id)
+
+      # Debug logging
+      if ENV["VSM_DEBUG_STREAM"] == "1"
+        $stderr.puts "Intelligence: invoke_model sid=#{session_id} inflight=#{st[:inflight]} pending=#{st[:pending_tool_ids].size} turn_seq=#{st[:turn_seq]}"
+        $stderr.puts "Intelligence: Calling driver with #{st[:history].size} history entries"
+        st[:history].each_with_index do |h, i|
+          $stderr.puts "  [#{i}] #{h[:role]}: #{h[:role] == 'assistant_tool_calls' ? h[:tool_calls].map{|tc| "#{tc[:name]}(#{tc[:id]})"}.join(', ') : h[:content]&.slice(0, 100)}"
+        end
+      end
+
+      task = Async do
+        begin
+          @driver.run!(
+            conversation: st[:history],
+            tools: descriptors,
+            policy: { system_prompt: system_prompt(session_id) }
+          ) do |event, payload|
+            case event
+            when :assistant_delta
+              # optionally buffer based on stream_policy
+              bus.emit VSM::Message.new(kind: :assistant_delta, payload: payload, meta: { session_id: session_id, turn_id: current_turn_id })
+            when :assistant_final
+              unless payload.to_s.empty?
+                st[:history] << { role: "assistant", content: payload.to_s }
+              end
+              bus.emit VSM::Message.new(kind: :assistant, payload: payload, meta: { session_id: session_id, turn_id: current_turn_id })
+            when :tool_calls
+              st[:history] << { role: "assistant_tool_calls", tool_calls: payload }
+              st[:pending_tool_ids] = Set.new(payload.map { _1[:id] })
+              payload.each { |c| st[:tool_id_to_name][c[:id]] = c[:name] }
+              if ENV["VSM_DEBUG_STREAM"] == "1"
+                $stderr.puts "Intelligence: tool_calls count=#{payload.size}; pending now=#{st[:pending_tool_ids].size}"
+              end
+              # Allow next invocation (after tools complete) without waiting for driver ensure
+              st[:inflight] = false
+              payload.each do |call|
+                bus.emit VSM::Message.new(
+                  kind: :tool_call,
+                  payload: { tool: call[:name], args: call[:arguments] },
+                  corr_id: call[:id],
+                  meta: { session_id: session_id, tool: call[:name], turn_id: current_turn_id }
+                )
+              end
+            end
+          end
+        ensure
+          if ENV["VSM_DEBUG_STREAM"] == "1"
+            $stderr.puts "Intelligence: driver completed sid=#{session_id}; pending=#{st[:pending_tool_ids].size}; inflight->false"
+          end
+          st[:inflight] = false
+        end
+      end
+      st[:task] = task
+    end
+
+    # Return [descriptors:Array<VSM::Tool::Descriptor>, index Hash{name=>capsule}]
+    def tool_inventory(bus, session_id)
+      ops = bus.context[:operations_children] || {}
+      descriptors = []
+      index = {}
+      ops.each do |name, capsule|
+        next unless capsule.respond_to?(:tool_descriptor)
+        desc = capsule.tool_descriptor
+        next unless offer_tools?(session_id, desc)
+        descriptors << desc
+        index[desc.name] = capsule
+      end
+      [descriptors, index]
+    end
+  end
+end
+

data/lib/vsm/roles/operations.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "../executors/fiber_executor"
+require_relative "../executors/thread_executor"
+
+module VSM
+  class Operations
+    EXECUTORS = {
+      fiber:  Executors::FiberExecutor,
+      thread: Executors::ThreadExecutor
+    }.freeze
+
+    def observe(bus); end
+
+    def handle(message, bus:, children:, **)
+      return false unless message.kind == :tool_call
+
+      name = message.payload[:tool].to_s
+      tool_capsule = children.fetch(name) { raise "unknown tool capsule: #{name}" }
+      mode = tool_capsule.respond_to?(:execution_mode) ? tool_capsule.execution_mode : :fiber
+      executor = EXECUTORS.fetch(mode)
+
+      Async do
+        result = executor.call(tool_capsule, message.payload[:args])
+        bus.emit Message.new(kind: :tool_result, payload: result, corr_id: message.corr_id, meta: message.meta)
+      rescue => e
+        bus.emit Message.new(kind: :tool_result, payload: "ERROR: #{e.class}: #{e.message}", corr_id: message.corr_id, meta: message.meta)
+      end
+
+      true
+    end
+  end
+end

data/lib/vsm/runtime.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+require "async"
+
+module VSM
+  module Runtime
+    def self.start(capsule, ports: [])
+      Async do |task|
+        capsule.run
+        ports.each do |p|
+          p.egress_subscribe if p.respond_to?(:egress_subscribe)
+          task.async { p.loop } if p.respond_to?(:loop)
+        end
+        task.sleep
+      end
+    end
+  end
+end
+

data/lib/vsm/tool/acts_as_tool.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+module VSM
+  module ActsAsTool
+    def self.included(base) = base.extend(ClassMethods)
+
+    module ClassMethods
+      def tool_name(value = nil);  @tool_name = value if value; @tool_name; end
+      def tool_description(value = nil); @tool_description = value if value; @tool_description; end
+      def tool_schema(value = nil); @tool_schema = value if value; @tool_schema; end
+    end
+
+    def tool_descriptor
+      VSM::Tool::Descriptor.new(
+        name: self.class.tool_name,
+        description: self.class.tool_description,
+        schema: self.class.tool_schema
+      )
+    end
+  end
+end

data/lib/vsm/tool/capsule.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+module VSM
+  class ToolCapsule
+    include ActsAsTool
+    attr_writer :governance
+    def governance = @governance || (raise "governance not injected")
+    # Subclasses implement:
+    # def run(args) ... end
+    # Optional:
+    # def execution_mode = :fiber | :thread
+  end
+end

data/lib/vsm/tool/descriptor.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+module VSM
+  module Tool
+    Descriptor = Struct.new(:name, :description, :schema, keyword_init: true) do
+      def to_openai_tool
+        { type: "function", function: { name:, description:, parameters: schema } }
+      end
+      def to_anthropic_tool
+        { name:, description:, input_schema: schema }
+      end
+      def to_gemini_tool
+        { name:, description:, parameters: schema }
+      end
+    end
+  end
+end

data/lib/vsm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Vsm
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

data/lib/vsm.rb

@@ -1,7 +1,40 @@
 # frozen_string_literal: true
 
+require "async"
+require "async/queue"
+
 require_relative "vsm/version"
 
+require_relative "vsm/message"
+require_relative "vsm/async_channel"
+require_relative "vsm/homeostat"
+require_relative "vsm/observability/ledger"
+
+require_relative "vsm/roles/operations"
+require_relative "vsm/roles/coordination"
+require_relative "vsm/roles/intelligence"
+require_relative "vsm/roles/governance"
+require_relative "vsm/roles/identity"
+
+require_relative "vsm/tool/descriptor"
+require_relative "vsm/tool/acts_as_tool"
+require_relative "vsm/tool/capsule"
+
+require_relative "vsm/executors/fiber_executor"
+require_relative "vsm/executors/thread_executor"
+
+require_relative "vsm/capsule"
+require_relative "vsm/dsl"
+require_relative "vsm/port"
+require_relative "vsm/runtime"
+
+require_relative "vsm/drivers/openai/async_driver"
+require_relative "vsm/drivers/anthropic/async_driver"
+require_relative "vsm/drivers/gemini/async_driver"
+require_relative "vsm/drivers/family"
+
+require_relative "vsm/lens"
+
 module Vsm
   class Error < StandardError; end
   # Your code goes here...

data/llms.txt

@@ -0,0 +1,322 @@
+
+LLMS CONTEXT FILE — VSM (Viable Systems for Agents) GEM
+=======================================================
+
+Audience: Large Language Models (LLMs) acting as coding assistants and human contributors.
+Goal: Provide all key context to safely modify, extend, and use the VSM gem as a framework for agentic CLIs (e.g., `airb`).
+
+— TL;DR —
+- VSM is a small, async, message-driven runtime for building recursive “capsules” that each contain five named systems:
+  Operations, Coordination, Intelligence, Governance, Identity. Monitoring (observability) is also provided.
+- Tools are implemented as *capsules* that *opt-in* to a tool interface (`ActsAsTool`) with JSON Schema descriptors.
+- The runtime is fiber-based (`async` gem). Tool execution can run in parallel via executors (`:fiber`, `:thread`, optional `:ractor`/`:subprocess` later).
+- Intelligence integrates provider drivers (OpenAI, Anthropic, Gemini) that support *structured tool calls* and (for OpenAI/Anthropic) *streaming*.
+- A built-in “Lens” web visualizer (SSE) streams live events from the bus; enable with one call.
+- Use the DSL to assemble a top-level capsule (the “organism”) and optional sub-capsules (recursive sub-agents or tools).
+
+--------------------------------------------------------------------------------
+1) REPO LAYOUT (EXPECTED FILES)
+--------------------------------------------------------------------------------
+lib/
+  vsm.rb                          # top-level requires
+  vsm/message.rb                  # Message struct
+  vsm/async_channel.rb            # async bus (fibers)
+  vsm/homeostat.rb                # budgets/alerts (minimal)
+  vsm/observability/ledger.rb     # Monitoring role: JSONL event ledger
+  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
+  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)
+  vsm/executors/
+    fiber_executor.rb             # default (IO-bound)
+    thread_executor.rb            # CPU-ish or blocking libs
+    # (optional) ractor_executor.rb / subprocess_executor.rb
+  vsm/capsule.rb                  # Capsule: wires systems, async run loop
+  vsm/dsl.rb                      # DSL for composing organisms & children
+  vsm/port.rb                     # adapter base (CLI/TUI/HTTP/etc.)
+  vsm/runtime.rb                  # boot helper: start capsule + ports
+  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
+  vsm/lens.rb                     # Lens.attach!(capsule, ...)
+  vsm/lens/event_hub.rb           # ring buffer + fan-out
+  vsm/lens/server.rb              # Rack app + SSE + tiny HTML
+
+spec/                             # RSpec tests (smoke + providers + routing)
+examples/                         # small runnable demos
+
+
+--------------------------------------------------------------------------------
+2) DESIGN GOALS
+--------------------------------------------------------------------------------
+- Small surface, idiomatic Ruby (SOLID/POODR), high cohesion/low coupling.
+- Recursion-by-default: a Capsule can contain child Capsules.
+- First-class asynchrony: non-blocking I/O; parallel tool calls where safe.
+- Provider-agnostic Intelligence with a stable, minimal event API:
+  :assistant_delta, :assistant_final, :tool_calls.
+- Observability out-of-the-box: JSONL ledger + SSE Lens.
+- Safety hooks live in Governance (path sandbox, confirmations, budgets).
+
+
+--------------------------------------------------------------------------------
+3) MESSAGE MODEL
+--------------------------------------------------------------------------------
+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 (small where possible)
+  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 (full bodies may be written to disk separately if needed).
+
+
+--------------------------------------------------------------------------------
+4) CAPSULE + SYSTEMS (THE “ORG” SPINE)
+--------------------------------------------------------------------------------
+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.)
+
+
+--------------------------------------------------------------------------------
+5) ASYNCHRONY & PARALLELISM
+--------------------------------------------------------------------------------
+- 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.
+
+
+--------------------------------------------------------------------------------
+6) TOOLS AS CAPSULES
+--------------------------------------------------------------------------------
+Implement a tool by subclassing VSM::ToolCapsule and including ActsAsTool:
+
+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
+
+Notes:
+- The JSON Schema should be compact and valid for OpenAI/Anthropic/Gemini.
+- Governance is injected into tool capsules (if they expose #governance=), allowing helpers like safe_path().
+- Keep results small. For big outputs, summarize or write artifacts to files and return a reference.
+
+
+--------------------------------------------------------------------------------
+7) INTELLIGENCE & PROVIDER DRIVERS
+--------------------------------------------------------------------------------
+- 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.
+
+Important rules for LLMs modifying Intelligence:
+- Do not parse tool calls from free-form text. Always use structured tool-calling outputs from drivers.
+- Maintain conversation faithfully; append assistant/tool messages exactly as providers expect.
+- Always emit :assistant_delta before :assistant when streaming text.
+
+
+--------------------------------------------------------------------------------
+8) GOVERNANCE & IDENTITY
+--------------------------------------------------------------------------------
+- 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.
+
+
+--------------------------------------------------------------------------------
+9) PORTS (INTERFACES)
+--------------------------------------------------------------------------------
+- Base: VSM::Port with #ingress(event) and #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.
+- Other ports: CommandTTY (one-shot task), HTTP, WebSocket, MCP client/server ports (planned), TUI.
+
+Guidance for LLMs:
+- Keep ports thin. No policy or LLM logic in ports.
+- Always pass session_id; grant floor in Coordination for deterministic streaming.
+
+
+--------------------------------------------------------------------------------
+10) OBSERVABILITY (MONITORING + LENS)
+--------------------------------------------------------------------------------
+- Monitoring subscribes to the bus and appends JSONL to .vsm.log.jsonl.
+- Lens is a tiny Rack app serving an SSE `/events` feed with a simple HTML viewer.
+- Enable in apps:
+  VSM::Lens.attach!(capsule, host: "127.0.0.1", port: 9292, token: ENV["VSM_LENS_TOKEN"])
+
+Lens best practices:
+- Include meta.session_id, path, corr_id, and meta.tool on events.
+- Keep payload small to avoid UI lag; the server already truncates strings.
+- For multi-process swarms, add a RemotePublisher that forwards events to one hub (future).
+
+
+--------------------------------------------------------------------------------
+11) DSL FOR ASSEMBLY
+--------------------------------------------------------------------------------
+Example organism:
+
+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
+    # capsule :editor,    klass: Capsules::Editor  (full sub-agent capsule)
+  end
+end
+
+Start:
+VSM::Runtime.start(org, ports: [ChatTTY.new(capsule: org)])
+
+
+--------------------------------------------------------------------------------
+12) PROVIDER CONFIG (ENV VARS)
+--------------------------------------------------------------------------------
+- OPENAI_API_KEY, AIRB_MODEL (e.g., "gpt-4o-mini")
+- ANTHROPIC_API_KEY, AIRB_MODEL (e.g., "claude-3-5-sonnet-latest")
+- GEMINI_API_KEY, AIRB_MODEL (e.g., "gemini-2.0-flash-001")
+- AIRB_PROVIDER = openai | anthropic | gemini
+- VSM_LENS=1, VSM_LENS_PORT=9292, VSM_LENS_TOKEN=...
+
+
+--------------------------------------------------------------------------------
+13) CODING STANDARDS (FOR LLM CHANGES)
+--------------------------------------------------------------------------------
+- 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”.
+
+
+--------------------------------------------------------------------------------
+14) TESTING (MINIMUM BASELINE)
+--------------------------------------------------------------------------------
+- 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
+
+
+--------------------------------------------------------------------------------
+15) EXTENDING THE FRAMEWORK
+--------------------------------------------------------------------------------
+A) Add a new tool capsule
+- Create class <YourTool> < VSM::ToolCapsule
+- Declare name/description/schema; implement #run; optional #execution_mode
+- Register in operations DSL
+
+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)
+
+C) Add a provider
+- Place a new driver_* under lib/vsm/intelligence/<provider>/
+- 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
+
+
+--------------------------------------------------------------------------------
+16) SAFETY & SECURITY
+--------------------------------------------------------------------------------
+- 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.
+
+
+--------------------------------------------------------------------------------
+17) KNOWN LIMITATIONS / TODOs
+--------------------------------------------------------------------------------
+- 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.
+
+
+--------------------------------------------------------------------------------
+18) HOW TO ASK THIS LLM FOR CHANGES
+--------------------------------------------------------------------------------
+- 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.
+
+
+--------------------------------------------------------------------------------
+19) LICENSE & ATTRIBUTION
+--------------------------------------------------------------------------------
+- 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.
+
+
+End of llms.txt.