silas 0.1.1

data/lib/silas/tool.rb

@@ -0,0 +1,93 @@
+module Silas
+  # Base class for agent tools. The keyword signature of #call IS the schema:
+  #
+  #   class Agent::Tools::IssueRefund < Silas::Tool
+  #     description "Refund an order."
+  #     param :amount, :integer, desc: "Pence"   # optional type refinement
+  #     approval :always                          # :never | :once | :always | lambda
+  #     transactional!                            # or at_most_once! (default) / idempotent!
+  #
+  #     def call(order_id:, amount:, note: nil)
+  #       ...
+  #     end
+  #   end
+  #
+  # Tool identity is the FILENAME (app/agent/tools/issue_refund.rb -> "issue_refund"),
+  # eve's convention, enforced by the Registry.
+  class Tool
+    class << self
+      def description(text = nil)
+        @description = text if text
+        @description || ""
+      end
+
+      def param(name, type = :string, desc: nil)
+        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
+      end
+      alias approval_policy approval
+
+      def transactional! = @effect_mode = :transactional
+      def idempotent!    = @effect_mode = :idempotent
+      def at_most_once!  = @effect_mode = :at_most_once
+
+      def effect_mode = @effect_mode || :at_most_once
+
+      def tool_name
+        name.demodulize.underscore
+      end
+
+      # {name:, description:, input_schema:} — provider-agnostic JSON schema.
+      def schema
+        validate_signature!
+        properties = {}
+        required = []
+        instance_method(:call).parameters.each do |kind, pname|
+          refinement = param_refinements[pname] || {}
+          properties[pname.to_s] = { "type" => refinement[:type] || "string" }
+          properties[pname.to_s]["description"] = refinement[:desc] if refinement[:desc]
+          required << pname.to_s if kind == :keyreq
+        end
+        {
+          "name" => tool_name,
+          "description" => description,
+          "input_schema" => {
+            "type" => "object",
+            "properties" => properties,
+            "required" => required
+          }
+        }
+      end
+
+      def validate_signature!
+        raise Error, "#{name} must define #call" unless method_defined?(:call)
+
+        kinds = instance_method(:call).parameters.map(&:first)
+        if kinds.any? { |k| %i[req opt rest].include?(k) }
+          raise Error, "#{name}#call must accept keyword arguments only — the signature is the schema"
+        end
+      end
+
+      private
+
+      def param_refinements
+        @param_refinements ||= {}
+      end
+    end
+
+    # Instance-side delegation so a resolved instance answers the Ledger.
+    def approval_policy = self.class.approval_policy
+    def effect_mode     = self.class.effect_mode
+
+    # Execution context, set by the Ledger before #call.
+    attr_accessor :session
+
+    def call(**)
+      raise NotImplementedError, "#{self.class}#call"
+    end
+  end
+end

data/lib/silas/tools/delegate.rb

@@ -0,0 +1,42 @@
+module Silas
+  module Tools
+    # Built-in. Added to the ROOT toolset only when subagents exist; NOT given to
+    # subagents (depth-1, no recursion). The whole delegation is ONE external
+    # effect: at_most_once! means a crash mid-run parks the parent invocation
+    # in-doubt (the exactly-once boundary), never silently re-runs.
+    class Delegate < Silas::Tool
+      at_most_once!
+      approval :never
+      param :subagent, :string, desc: "Which subagent to run (one of the names listed above)."
+      param :input, :string, desc: "Full, self-contained task — the subagent shares NONE of your context."
+
+      def self.tool_name = "delegate"
+
+      # Dynamic description enumerates the roster, so the roster lands in the ROOT
+      # digest (schema -> Registry#definitions -> digest). Adding a subagent
+      # mid-turn => NondeterminismError, exactly like a skill change.
+      def self.description
+        roster = Silas.subagent_index
+        base = "Delegate a self-contained subtask to a specialized subagent that runs with its own " \
+               "instructions, tools, and a fresh context, then returns its final answer."
+        return base if roster.empty?
+
+        base + "\n\nAvailable subagents:\n" + roster.map { |n, d| "- #{n}: #{d}" }.join("\n")
+      end
+
+      # `session` is the PARENT session, set by the Ledger before #call.
+      def call(subagent:, input:)
+        return { "error" => "unknown subagent #{subagent.inspect}" } unless Silas.subagent?(subagent)
+
+        nested = Silas::Session.create!(agent_name: subagent, parent_session_id: session.id,
+                                        metadata: { "delegated_from" => session.id })
+        turn = Silas::NestedRunner.run(nested, input: input)
+        if turn.completed?
+          { "session_id" => nested.id, "answer" => turn.answer_text }
+        else
+          { "session_id" => nested.id, "error" => "subagent did not finish (#{turn.status}: #{turn.failure_reason})" }
+        end
+      end
+    end
+  end
+end

data/lib/silas/tools/load_skill.rb

@@ -0,0 +1,25 @@
+module Silas
+  module Tools
+    # The built-in progressive-disclosure tool (eve's mechanism): skill
+    # descriptions are advertised in the instructions; the body loads on
+    # demand and — because the body IS the tool result — rides the ledger and
+    # replays byte-identically for free. Loading also registers the skill on
+    # the session so subsequent turns inline it directly.
+    class LoadSkill < Tool
+      description "Load the full playbook for a named skill. Use when a task matches a skill description."
+      transactional!
+
+      def self.tool_name = "load_skill"
+
+      def call(name:)
+        skill = Silas.skills.find { |s| s.name == name }
+        return { "error" => "unknown skill #{name.inspect}" } unless skill
+
+        unless session.loaded_skills.include?(name)
+          session.update!(loaded_skills: session.loaded_skills + [ name ])
+        end
+        { "skill" => name, "content" => skill.body }
+      end
+    end
+  end
+end

data/lib/silas/tools/run_code.rb

@@ -0,0 +1,21 @@
+module Silas
+  module Tools
+    # Built-in, added to the toolset only when a sandbox is configured. Runs a
+    # shell command through the configured sandbox. at_most_once! — a sandbox
+    # exec is an external effect, so a crash mid-run parks it in-doubt.
+    class RunCode < Tool
+      description "Run a shell command in an ephemeral, network-isolated sandbox container. " \
+                  "Use for untrusted or model-generated code."
+      param :command, :string, desc: "Shell command run via /bin/sh -c inside the sandbox."
+      param :timeout, :integer, desc: "Max wall-clock seconds before the container is killed."
+      at_most_once!
+
+      def self.tool_name = "run_code"
+
+      def call(command:, timeout: nil)
+        result = Silas.resolved_sandbox.run(command, timeout: timeout || Silas.config.sandbox_timeout)
+        { "stdout" => result.stdout, "stderr" => result.stderr, "exit_status" => result.exit_status }
+      end
+    end
+  end
+end

data/lib/silas/version.rb

@@ -0,0 +1,3 @@
+module Silas
+  VERSION = "0.1.1"
+end

data/lib/silas.rb

@@ -0,0 +1,144 @@
+# Active Job (Continuations) and Active Record are the chassis — load them
+# even in --minimal host apps that skipped the railties.
+require "active_job/railtie" if defined?(::Rails::Railtie)
+require "active_record/railtie" if defined?(::Rails::Railtie)
+
+require "silas/version"
+require "silas/errors"
+require "silas/configuration"
+require "silas/ledger"
+require "silas/tool"
+require "silas/skill"
+require "silas/schedule"
+require "silas/schedule/compiler"
+require "silas/agent_scope"
+require "silas/tools/delegate"
+require "silas/nested_runner"
+require "silas/sandbox"
+require "silas/tools/run_code"
+require "silas/channel"
+require "silas/slack"
+require "silas/mcp/client"
+require "silas/connection"
+require "silas/connections"
+require "silas/inbox"
+require "silas/inbox/cost"
+require "silas/budget"
+require "silas/registry"
+require "silas/agent"
+require "silas/tools/load_skill"
+require "silas/engines/base"
+require "silas/agent_sdk/version_guard"
+require "silas/agent_sdk/stream_parser"
+require "silas/agent_sdk/cli"
+require "silas/mcp/handler"
+require "silas/mcp/server"
+require "silas/engines/agent_sdk"
+require "ruby_llm"
+require "silas/engines/ruby_llm"
+require "silas/message_builder"
+require "silas/instructions"
+require "silas/step_runner"
+require "silas/subprocess_runner"
+require "silas/eval" # after engines (ScriptedEngine < Engines::Base)
+
+module Silas
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+      config.validate!
+      config
+    end
+
+    def reset_configuration! # for specs
+      @config = nil
+      @resolved_engine = nil
+      @resolved_sandbox = nil
+      @agent = nil
+    end
+
+    def sandbox_enabled? = ![ :none, nil ].include?(config.sandbox)
+
+    def resolved_sandbox
+      @resolved_sandbox ||=
+        case config.sandbox
+        when :none, nil then Sandbox::Null.new
+        when :docker
+          Sandbox::Docker.new(image: config.sandbox_image, network: config.sandbox_network,
+                              memory: config.sandbox_memory, cpus: config.sandbox_cpus,
+                              pids: config.sandbox_pids, workdir: config.sandbox_workdir,
+                              docker_bin: config.sandbox_docker_bin)
+        when Symbol then raise Error, "unknown sandbox #{config.sandbox.inspect}"
+        else config.sandbox
+        end
+    end
+
+    def reset_agent_memo! = (@agent = nil) # after Registry.install! swaps dirs
+
+    # The inference adapter instance. config.engine may be a symbol (:ruby_llm,
+    # :agent_sdk) or any object responding to #execute_step (specs, custom).
+    def resolved_engine
+      @resolved_engine ||=
+        case config.engine
+        when :ruby_llm then Engines::RubyLLM.new
+        when :agent_sdk then Engines::AgentSdk.new
+        when Symbol then raise Error, "unknown engine #{config.engine.inspect}"
+        else config.engine
+        end
+    end
+
+    def tool_resolver
+      config.tool_resolver or raise Error, "no tool resolver configured (Registry boots one; specs must inject)"
+    end
+
+    def tool_definitions
+      config.tool_definitions&.call || []
+    end
+
+    def skills
+      config.skills&.call || []
+    end
+
+    def schedules
+      config.schedules&.call || []
+    end
+
+    # The active agent definition. config.agent_override is set during a nested
+    # subagent run; otherwise it's the root app/agent.
+    def agent
+      config.agent_override || (@agent ||= Agent.load)
+    end
+
+    # Subagent roster: [[name, description], ...] (model-visible, so it's in the
+    # root digest via Delegate.description).
+    def subagent_index = config.subagent_index&.call || []
+    def subagent?(name) = subagent_index.any? { |n, _| n == name.to_s }
+    def subagent_scope(name) = config.subagent_scopes&.call&.fetch(name.to_s)
+
+    # Run a block with a subagent's scope swapped in as the active globals,
+    # restoring afterward. Synchronous/depth-1 — safe because delegation runs
+    # inline on one thread while the parent loop is paused in the delegate tool.
+    def with_agent_scope(scope)
+      saved = {
+        tool_resolver: config.tool_resolver, tool_definitions: config.tool_definitions,
+        definitions_digest: config.definitions_digest, skills: config.skills,
+        agent_override: config.agent_override, instructions_dir: config.instructions_dir
+      }
+      config.tool_resolver = scope.resolver
+      config.tool_definitions = -> { scope.definitions }
+      config.definitions_digest = -> { scope.digest }
+      config.skills = -> { scope.skills }
+      config.agent_override = scope.agent
+      config.instructions_dir = scope.dir
+      yield
+    ensure
+      saved.each { |k, v| config.public_send("#{k}=", v) }
+    end
+  end
+end
+
+require "silas/engine" if defined?(::Rails::Engine)

data/lib/tasks/silas_eval.rake

@@ -0,0 +1,20 @@
+namespace :silas do
+  desc "Run agent evals as a deploy gate (exit 1 on failure). SILAS_EVAL_MODE=real for live; EVAL=regex to filter."
+  task eval: :environment do
+    ok = Silas::Eval::Runner.run(
+      dir: ENV["SILAS_EVAL_DIR"] || Silas.config.eval_dir,
+      pattern: (Regexp.new(ENV["EVAL"]) if ENV["EVAL"]),
+      mode: ENV["SILAS_EVAL_MODE"]&.to_sym
+    )
+    exit(1) unless ok
+  end
+
+  namespace :eval do
+    desc "List discovered eval scenarios without running them"
+    task list: :environment do
+      Silas::Eval.reset!
+      Dir[File.join(Silas.config.eval_dir, "**/*_eval.rb")].sort.each { |f| load f }
+      Silas::Eval.scenarios.each { |s| puts "  [#{s.mode}] #{s.name}" }
+    end
+  end
+end

data/lib/tasks/silas_schedules.rake

@@ -0,0 +1,33 @@
+namespace :silas do
+  desc "Compile app/agent/schedules/** into config/recurring.yml (env: RAILS_ENV or ENV[SILAS_SCHEDULE_ENV] or production)"
+  task schedules: :environment do
+    Silas::Registry.install!(root: Rails.root)
+    env = ENV["SILAS_SCHEDULE_ENV"] || "production"
+    schedules = Silas.schedules
+    Silas::Schedule::Compiler.write!(schedules, root: Rails.root, env: env)
+    if schedules.empty?
+      puts "silas: no schedules found under app/agent/schedules/ (managed entries cleared for #{env})"
+    else
+      puts "silas: compiled #{schedules.size} schedule(s) into config/recurring.yml [#{env}]:"
+      schedules.sort_by(&:name).each { |s| puts "  #{s.recurring_key}  #{s.cron}  (#{s.kind})  -> #{s.name}" }
+    end
+  end
+
+  namespace :schedules do
+    desc "Report drift between discovered schedules and config/recurring.yml"
+    task list: :environment do
+      Silas::Registry.install!(root: Rails.root)
+      env = ENV["SILAS_SCHEDULE_ENV"] || "production"
+      drift = Silas::Schedule::Compiler.drift(Silas.schedules, root: Rails.root, env: env)
+      puts "silas schedules [#{env}]:"
+      puts "  discovered: #{Silas.schedules.map(&:name).sort.join(', ').then { |s| s.empty? ? '(none)' : s }}"
+      unless drift[:uncompiled].empty?
+        puts "  NOT COMPILED (run `bin/rails silas:schedules`): #{drift[:uncompiled].join(', ')}"
+      end
+      unless drift[:orphaned].empty?
+        puts "  ORPHANED in recurring.yml (file deleted): #{drift[:orphaned].join(', ')}"
+      end
+      puts "  in sync." if drift[:uncompiled].empty? && drift[:orphaned].empty?
+    end
+  end
+end

metadata

@@ -0,0 +1,232 @@
+--- !ruby/object:Gem::Specification
+name: silas
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Daniel St Paul
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.5.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.5.0
+- !ruby/object:Gem::Dependency
+  name: solid_queue
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.2'
+description: 'An agent framework where your Rails app is the chassis: app/agent/ directory
+  convention, durable runs on Active Job Continuations, exactly-once tool execution
+  via a transactional ledger, approvals that park at zero compute.'
+email:
+- daniel@zerogravity.co.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- app/controllers/silas/channels/approvals_controller.rb
+- app/controllers/silas/channels/base_controller.rb
+- app/controllers/silas/channels/slack_controller.rb
+- app/controllers/silas/inbox/base_controller.rb
+- app/controllers/silas/inbox/invocations_controller.rb
+- app/controllers/silas/inbox/sessions_controller.rb
+- app/helpers/silas/inbox/trace_helper.rb
+- app/jobs/silas/agent_loop_job.rb
+- app/jobs/silas/channel_delivery_job.rb
+- app/jobs/silas/dead_job_rescuer_job.rb
+- app/jobs/silas/schedule_job.rb
+- app/mailboxes/silas/agent_mailbox.rb
+- app/mailers/silas/channel_mailer.rb
+- app/models/concerns/silas/inbox/broadcastable.rb
+- app/models/silas/application_record.rb
+- app/models/silas/session.rb
+- app/models/silas/step.rb
+- app/models/silas/tool_invocation.rb
+- app/models/silas/turn.rb
+- app/views/layouts/silas/inbox.html.erb
+- app/views/silas/channel_mailer/approval.text.erb
+- app/views/silas/channels/approvals/done.html.erb
+- 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/_invocation.html.erb
+- app/views/silas/inbox/sessions/_cost.html.erb
+- app/views/silas/inbox/sessions/index.html.erb
+- app/views/silas/inbox/sessions/show.html.erb
+- app/views/silas/inbox/steps/_step.html.erb
+- app/views/silas/inbox/turns/_header.html.erb
+- app/views/silas/inbox/turns/_turn.html.erb
+- config/routes.rb
+- db/migrate/20260714000001_create_silas_tables.rb
+- db/migrate/20260715000001_add_channel_outbound_markers.rb
+- db/migrate/20260715000002_add_agent_sdk_columns_to_turns.rb
+- db/migrate/20260715000003_add_parent_session_to_silas_sessions.rb
+- lib/generators/silas/install/install_generator.rb
+- lib/generators/silas/install/templates/agent.yml
+- lib/generators/silas/install/templates/bin_ci
+- lib/generators/silas/install/templates/channel_email.rb
+- lib/generators/silas/install/templates/channel_slack.rb
+- lib/generators/silas/install/templates/example_eval.rb
+- lib/generators/silas/install/templates/example_schedule.md
+- lib/generators/silas/install/templates/example_skill.md
+- lib/generators/silas/install/templates/example_tool.rb
+- lib/generators/silas/install/templates/initializer.rb
+- lib/generators/silas/install/templates/instructions.md
+- lib/silas.rb
+- lib/silas/agent.rb
+- lib/silas/agent_scope.rb
+- lib/silas/agent_sdk/cli.rb
+- lib/silas/agent_sdk/stream_parser.rb
+- lib/silas/agent_sdk/version_guard.rb
+- lib/silas/budget.rb
+- lib/silas/channel.rb
+- lib/silas/configuration.rb
+- lib/silas/connection.rb
+- lib/silas/connections.rb
+- lib/silas/engine.rb
+- lib/silas/engines/agent_sdk.rb
+- lib/silas/engines/base.rb
+- lib/silas/engines/ruby_llm.rb
+- lib/silas/errors.rb
+- lib/silas/eval.rb
+- lib/silas/eval/assertions.rb
+- lib/silas/eval/driver.rb
+- lib/silas/eval/dsl.rb
+- lib/silas/eval/grader.rb
+- lib/silas/eval/result.rb
+- lib/silas/eval/runner.rb
+- lib/silas/eval/scripted_engine.rb
+- lib/silas/eval/transcript.rb
+- lib/silas/inbox.rb
+- lib/silas/inbox/cost.rb
+- lib/silas/instructions.rb
+- lib/silas/ledger.rb
+- lib/silas/mcp/client.rb
+- lib/silas/mcp/handler.rb
+- lib/silas/mcp/server.rb
+- lib/silas/message_builder.rb
+- lib/silas/nested_runner.rb
+- lib/silas/registry.rb
+- lib/silas/sandbox.rb
+- lib/silas/sandbox/docker.rb
+- lib/silas/sandbox/null.rb
+- lib/silas/schedule.rb
+- lib/silas/schedule/compiler.rb
+- lib/silas/skill.rb
+- lib/silas/slack.rb
+- lib/silas/step_runner.rb
+- lib/silas/subprocess_runner.rb
+- lib/silas/tool.rb
+- lib/silas/tools/delegate.rb
+- lib/silas/tools/load_skill.rb
+- lib/silas/tools/run_code.rb
+- lib/silas/version.rb
+- lib/tasks/silas_eval.rake
+- lib/tasks/silas_schedules.rake
+homepage: https://github.com/danielstpaul/silas
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/danielstpaul/silas
+  source_code_uri: https://github.com/danielstpaul/silas
+  changelog_uri: https://github.com/danielstpaul/silas/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Durable AI agents on the Rails you already run.
+test_files: []