silas 0.6.1 → 0.6.3

data/lib/silas/configuration.rb

@@ -50,9 +50,23 @@ module Silas
     # Channels: name -> Channel subclass (wired by the Registry). Slack creds
     # default to credentials.dig(:silas, :slack, ...); nil disables Slack.
     attr_accessor :channel_resolver
+    # Inbound routing: which named agent an external thread wakes. Data only —
+    # { transport => { key => agent_name } }, where transport is the channel's
+    # filename identity and key is whatever that transport calls a destination:
+    #
+    #   config.channel_routes = {
+    #     "slack" => { "C0BILLING" => "bookkeeper" },
+    #     "email" => { "billing@shop.test" => "bookkeeper" }
+    #   }
+    #
+    # Unmatched threads wake the root agent. Names are checked at boot against
+    # app/agents/ (Registry.install!) — a typo fails the deploy, never a
+    # webhook.
+    attr_accessor :channel_routes
     attr_writer :slack_signing_secret, :slack_bot_token
     # Bind host for the in-process MCP server (Mcp::Server — the "mount your
-    # tools as MCP" seam).
+    # tools as MCP" seam). Inert: nothing outside Mcp::Server's own specs calls
+    # .start, so this setting has no effect until a mounted endpoint ships.
     attr_accessor :mcp_server_host
 
     # Renamed in 0.4, removed in 2.0. "engine" meant two unrelated things —
@@ -134,6 +148,7 @@ module Silas
       @agent_override = nil
       @instructions_dir = nil
       @channel_resolver = nil
+      @channel_routes = {}
       @slack_signing_secret = nil
       @slack_bot_token = nil
       @mcp_server_host = "127.0.0.1"

data/lib/silas/doctor.rb

@@ -10,6 +10,35 @@ module Silas
   class Doctor
     Check = Struct.new(:status, :label, :detail) # status: :pass | :warn | :fail
 
+    # Rails defaults development to :async, which the queue_adapter check below
+    # FAILS — so a stock app fails the doctor the installer told it to run. The
+    # remedy travels with the failure, and the install generator prints this
+    # same constant when it detects :async, so the two surfaces can't drift.
+    # Printed, never written: database.yml and cable.yml belong to the host app.
+    ASYNC_QUEUE_REMEDY = <<~MSG.freeze
+      Add to config/environments/development.rb:
+
+          config.active_job.queue_adapter = :solid_queue
+          config.solid_queue.connects_to = { database: { writing: :queue } }
+
+      and a queue database to config/database.yml (SQLite shown — drop the
+      connects_to line above if Solid Queue shares your primary database):
+
+          development:
+            primary:
+              <<: *default
+              database: storage/development.sqlite3
+            queue:
+              <<: *default
+              database: storage/development_queue.sqlite3
+              migrations_paths: db/queue_migrate
+
+      Then `bin/rails db:prepare`, and run the worker next to the server:
+      `bin/jobs`. On an app that predates Rails 8, `bundle add solid_queue &&
+      bin/rails solid_queue:install` first. For scripts and demos `:inline` is
+      also safe — synchronous, no durability.
+    MSG
+
     def self.run(root: Rails.root) = new(root: root).run
 
     def initialize(root:)
@@ -49,11 +78,15 @@ module Silas
       when /AsyncAdapter/
         Check.new(:fail, "queue adapter",
                   "in-process :async double-executes continuation steps and voids the durability " \
-                  "contract — use :solid_queue (see DEPLOY.md)")
+                  "contract — use :solid_queue (see DEPLOY.md)\n\n#{ASYNC_QUEUE_REMEDY.indent(3).chomp}")
       when /InlineAdapter/
         Check.new(:warn, "queue adapter", "inline — fine for scripts and demos, no durability")
       else
-        Check.new(:warn, "queue adapter", "#{name.demodulize} — durability requires a serializing, DB-backed adapter")
+        Check.new(:warn, "queue adapter",
+                  "#{name.demodulize} — no dead-job rescue path: DeadJobRescuerJob sweeps expired approvals " \
+                  "but returns early unless SolidQueue is defined, so a job killed with its worker is never " \
+                  "retried and a turn stranded mid-tool stays running with its in-doubt invocation unswept. " \
+                  "Durability requires a serializing, DB-backed adapter.")
       end
     end
 

data/lib/silas/registry.rb

@@ -20,6 +20,10 @@ module Silas
       Silas.config.agent_override = nil
       Silas.config.instructions_dir = nil
       Silas.reset_agent_memo!
+      # Boot is the last place a bad channel route can fail safely. Directory
+      # names, not built scopes: validation must not force every named agent's
+      # tools to constantize before anything needs them.
+      Silas::Channel.validate_routes!(registry.named_agent_dirs.map { |dir| File.basename(dir) })
       registry
     end
 
@@ -182,6 +186,13 @@ module Silas
     # identity under const_base, skills, the load_skill builtin when skills
     # exist, run_code when asked, and the scope's own digest (the same
     # NondeterminismError guard root turns get).
+    #
+    # A named agent is a full member of staff: it gets ask_question (parking to
+    # ask a person is the premise, not a root-agent privilege) and the shared
+    # remote connections. Connections live in the root app/agent/connections/ —
+    # one set of credentials for the app, reachable by everyone. Subagents get
+    # neither: they run inside a parent's turn, which is where the human contact
+    # and the remote surface belong.
     def build_agent_scope(dir, name, const_base:, agent: nil, run_code: false, named: false)
       tools = Dir[dir.join("tools/*.rb")].sort.to_h do |file|
         tname = File.basename(file, ".rb")
@@ -193,6 +204,7 @@ module Silas
       end
       skills = Dir[dir.join("skills/*.md")].sort.map { |f| Skill.parse(f) }
       builtins = {}
+      builtins["ask_question"] = Silas::Tools::AskQuestion if named && Silas.config.ask_question
       builtins["load_skill"] = Silas::Tools::LoadSkill if skills.any?
       builtins["run_code"] = Silas::Tools::RunCode if run_code
       if named && Silas.memory_enabled?
@@ -200,8 +212,14 @@ module Silas
         builtins["recall"] = Silas::Tools::Recall
       end
       builtins["handoff"] = Silas::Tools::Handoff if named && named_agent_dirs.size > 1
-      resolver = ->(n) { (tools[n] || builtins.fetch(n)).new }
-      definitions = (tools.values + builtins.values).map(&:schema)
+      remote = connections if named
+      resolver = lambda do |n|
+        klass = tools[n] || builtins[n]
+        return klass.new if klass
+
+        remote&.resolve(n) or raise Error, "unknown tool #{n.inspect} for agent #{name.inspect}"
+      end
+      definitions = (tools.values + builtins.values).map(&:schema) + (remote&.definitions || [])
       loaded_agent = agent || Silas::Agent.load(dir: dir)
       payload = { tools: definitions, skills: skills.map { |s| [ s.name, s.description ] } }
       payload[:final_answer] = loaded_agent.final_answer if loaded_agent.final_answer.present?

data/lib/silas/tool.rb

@@ -23,16 +23,16 @@ module Silas
     class << self
       def description(text = nil)
         @description = text if text
-        @description || ""
+        inherited_setting(:@description) || ""
       end
 
       def param(name, type = :string, desc: nil)
-        param_refinements[name.to_sym] = { type: type.to_s, desc: desc }
+        own_param_refinements[name.to_sym] = { type: type.to_s, desc: desc }
       end
 
       def approval(policy = nil, &block)
         @approval_policy = block || policy unless policy.nil? && block.nil?
-        @approval_policy || :never
+        inherited_setting(:@approval_policy) || :never
       end
       alias approval_policy approval
 
@@ -40,7 +40,7 @@ module Silas
       def idempotent!    = @effect_mode = :idempotent
       def at_most_once!  = @effect_mode = :at_most_once
 
-      def effect_mode = @effect_mode || :at_most_once
+      def effect_mode = inherited_setting(:@effect_mode) || :at_most_once
 
       def tool_name
         name.demodulize.underscore
@@ -79,9 +79,42 @@ module Silas
 
       private
 
-      def param_refinements
+      # Ruby does NOT inherit class-level instance variables. Without this walk,
+      # factoring shared declarations into a base class —
+      #
+      #   class MoneyTool < Silas::Tool
+      #     transactional!
+      #     approval :always
+      #   end
+      #   class IssueRefund < MoneyTool; end
+      #
+      # — silently drops both in the subclass, and drops them into the LEAST
+      # safe defaults: no database transaction (:at_most_once) and no human
+      # gate (:never). Silently disarming the two declarations the ledger acts
+      # on is the worst failure this DSL could have, so settings resolve up the
+      # ancestry: nearest explicit declaration wins.
+      def inherited_setting(ivar)
+        klass = self
+        while klass.respond_to?(:inherited_setting, true)
+          value = klass.instance_variable_get(ivar)
+          return value unless value.nil?
+
+          klass = klass.superclass
+        end
+        nil
+      end
+
+      def own_param_refinements
         @param_refinements ||= {}
       end
+
+      # Merged down the ancestry so a base class's `param` refinements survive;
+      # a subclass redeclaring the same param wins.
+      def param_refinements
+        return own_param_refinements unless superclass.respond_to?(:param_refinements, true)
+
+        superclass.send(:param_refinements).merge(own_param_refinements)
+      end
     end
 
     # Instance-side delegation so a resolved instance answers the Ledger.

data/lib/silas/version.rb

@@ -1,3 +1,3 @@
 module Silas
-  VERSION = "0.6.1"
+  VERSION = "0.6.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: silas
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.6.3
 platform: ruby
 authors:
 - Daniel St Paul
@@ -146,7 +146,9 @@ files:
 - app/views/silas/channels/approvals/error.html.erb
 - app/views/silas/channels/approvals/show.html.erb
 - app/views/silas/inbox/invocations/_approval_card.html.erb
+- app/views/silas/inbox/invocations/_detail.html.erb
 - app/views/silas/inbox/invocations/_invocation.html.erb
+- app/views/silas/inbox/sessions/_child.html.erb
 - app/views/silas/inbox/sessions/_cost.html.erb
 - app/views/silas/inbox/sessions/_row.html.erb
 - app/views/silas/inbox/sessions/index.html.erb
@@ -175,10 +177,13 @@ files:
 - docs/conventions.md
 - docs/evals.md
 - docs/guarantees.md
+- docs/headless.md
 - docs/inbox-and-api.md
 - docs/memory.md
+- docs/providers.md
 - docs/sandbox.md
 - docs/tools.md
+- docs/traces.md
 - docs/tutorial.md
 - docs/vs-eve.md
 - docs/why-silas.md