silas 0.1.5 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7aa3f984d996b0eee69689f4009e3d43bd46d63caaf2144f0a4082b40d0ae918
-  data.tar.gz: 8c9b38ac7dae0a0ea510375046447442087a3a1536431199a8bf54677fca80b3
+  metadata.gz: ad5ce26e72a73ea83df134c187f8c8dedcfcc35a65f20493f3095abfbfaa7ed8
+  data.tar.gz: ab1989850b2b8c881da660824dcad3f71159cfffcd8648901ec2a06385d8c294
 SHA512:
-  metadata.gz: f3136bfb1276a84217f76733e1c718715b8dbed5794fe766f72383cf58560c50950c6cdb12932d89108c6c6de73bd16b1c2c1b915841bb1829b47c102d03f0f5
-  data.tar.gz: 5af58996877a0bb1bf6d64fbf2ef30c141462c8d00a7f37ebbaaca4dbf3518cd28c4ead9557d4ee2d5a23144748632f053e38b908238b39c64577ce9f0d355fd
+  metadata.gz: fb5da2cdb854533bf68a761582063e8c5b22c2e40fc02cab05240d4ea199554da317bb0509398c81923a312c7b43773834d354ffb6391be549a6254329e3b995
+  data.tar.gz: 57e53d9a3c5b438b941cd599ba805c2c210e303d6362599d757b58b907ea10b9401cbf918cd909d1c53590d8fee4cc9e0fef8a8fb5ccb422c26db5e0abaaf43a

data/CHANGELOG.md

@@ -1,5 +1,70 @@
 # Changelog
 
+## 0.1.7
+
+- **Memory — graph-shaped, not a graph database.** New `silas_memories` table:
+  entity-attributed facts (`subject · attribute · content`) with provenance
+  (session/turn) and **supersession** — a new fact about the same
+  subject+attribute retires the old one. Two built-ins: `remember`
+  (`transactional!`, **approval-gated by default** — the memory card parks in
+  your inbox; `config.memory_approval = :never` opts out) and `recall`
+  (on-demand subject lookup). Recent memories inject into the instructions
+  snapshot (bounded by `config.memory_injection_limit`). Scopes: private
+  per-agent or `shared: true` app-wide. Domain memory stays where it belongs —
+  your own tables; this is for the fuzzy residue with no natural home. Edges
+  are a deliberate not-yet. Upgrade-safe: tools only advertise when the
+  migration has run.
+- **Handoffs — staff composition without agent chatter.** New `handoff`
+  built-in (advertised when `app/agents/` exists): file a self-contained brief
+  that starts another named agent's linked session (`parent_session_id`),
+  async by default, `await: true` for run-now-and-return-answer.
+  `at_most_once!` through the ledger; refuses self-handoffs, unknown targets,
+  cycles, and chains deeper than 3. Free-form agent-to-agent conversation
+  remains deliberately unblessed.
+- `Session#continue(enqueue: false)` for callers that drive the turn
+  themselves. New migration: run `bin/rails silas:install:migrations
+  db:migrate` on upgrade.
+
+## 0.1.6
+
+- **Named agents — the staff pattern.** An app can now employ several
+  top-level agents: `app/agents/<name>/` (instructions.md, agent.yml, tools/,
+  skills/), autoloaded under `Agents::<Name>`, started with
+  `Silas.agent(:clerk).start(input: ...)`. Sessions are stamped with the
+  agent's name and **every turn — including crash resumes — runs under that
+  agent's own scope** (tools, skills, instructions, definitions digest), so a
+  rescued staff member can never wake up holding another agent's tools. The
+  inbox gains per-agent filter chips; `silas:chat` gains `AGENT=name`. The
+  root `app/agent` is unchanged and remains the default.
+- **Scope switching is now execution-isolated (concurrency fix).**
+  `with_agent_scope` previously mutated global config — two Solid Queue
+  threads running different agents (or a delegation racing a parallel job)
+  could see each other's tools. Scopes now live in
+  `ActiveSupport::IsolatedExecutionState` (per-thread *and* per-fiber —
+  Falcon-safe), nestable, with the readers (`Silas.agent`, `tool_resolver`,
+  `tool_definitions`, `skills`, `definitions_digest`, `instructions_dir`)
+  consulting the active scope first. This also fixes a latent bug where a
+  crashed *subagent* turn resumed by the rescuer would run under the ROOT
+  agent's scope.
+
+- **Approval lambdas get indifferent-access input.** Arguments are stored as
+  jsonb (string keys); a lambda writing `input[:amount]` got a silent nil —
+  fail-closed for gates written `nil > 50 ? park : approve`, but a silent
+  always-approve for the inverse. `input` is now
+  `ActiveSupport::HashWithIndifferentAccess`.
+- **Brownfield-safe installer.** `silas:install` now leaves an existing
+  `config/initializers/ruby_llm.rb` completely untouched (no conflict prompt —
+  an accidental Y clobbered production provider config). First generator specs.
+- **hermetic integration.** `config.sandbox = Hermetic.gvisor(image: ...)` is
+  now a documented, spec-covered path (the companion
+  [hermetic](https://github.com/danielstpaul/hermetic) gem: gVisor, Firecracker,
+  hosted E2B, or hardened Docker behind one `run` call, with `trust`/`off_host?`
+  as first-class axes). `sandbox_enabled?` now honors the configured backend's
+  own `enabled?` (a `Hermetic.null` won't advertise `run_code`), and configuring
+  a hermetic backend auto-arms its ledger guard — a sandbox exec inside a ledger
+  transaction fails loud. No new runtime dependency: Silas only duck-types
+  against the seam.
+
 ## 0.1.5
 
 - **Turn cancellation.** `turn.cancel!` — a parked or queued turn settles to

data/README.md

@@ -11,7 +11,9 @@ the durable stack is already booted inside your app. The only new surface is the
 Honestly early and honestly narrow: **v0.1, one maintainer, zero external
 users**, durability proven by an in-repo `kill -9` chaos harness (100/100, zero
 duplicate effects, byte-identical replay), and scoped to **trusted code you write
-yourself** (the sandbox is an interim Docker seam, not a microVM). The full pitch
+yourself** by default — for untrusted or model-generated code, drop in the
+companion gem [hermetic](https://github.com/danielstpaul/hermetic) (gVisor /
+Firecracker / hosted sandboxes behind one call, see below). The full pitch
 and the honest caveats: [Why Silas](docs/why-silas.md) ·
 [Silas vs eve](docs/vs-eve.md).
 
@@ -108,6 +110,74 @@ Inference is one pluggable seam (`config.engine`):
   in api_key mode). v1 is honestly weaker than `:ruby_llm`: exactly-once *within*
   a run, `approval :never` tools only, and fail-closed on a mid-subprocess kill.
 
+## Sandbox: run untrusted code with hermetic
+
+The sandbox is a second pluggable seam (`config.sandbox`). Built-in adapters are
+`:none` (default — code execution off) and `:docker` (hardened container,
+honest-but-interim). For real isolation, the companion gem
+[**hermetic**](https://github.com/danielstpaul/hermetic) drops straight in:
+
+```ruby
+# Gemfile: gem "hermetic"   (zero runtime deps)
+Silas.configure do |c|
+  c.sandbox = Hermetic.gvisor(image: "python:3.12-slim")     # or .docker /
+  # .firecracker(kernel:, rootfs:) / .hosted(:e2b, api_key:) # pick your strength
+end
+```
+
+That's the whole integration. When a sandbox is configured and enabled, the
+`run_code` tool is advertised to the model automatically (`at_most_once!` — an
+exec is an external effect). Two properties carry through the seam:
+
+- **The trust axis is visible**: every hermetic backend exposes `trust`
+  (`:vendor`/`:remote`/`:vm`/`:host`) and `off_host?`, so you can refuse to run
+  untrusted code on the box that holds your `RAILS_MASTER_KEY` — pair any local
+  backend with `executor:` to push execution to a dedicated sandbox host.
+- **The ledger guard is auto-armed**: configuring a hermetic backend loads its
+  Silas shim, so a sandbox exec attempted inside a ledger transaction fails loud
+  (sandbox-backed tools must be `at_most_once!`, never `transactional!`).
+
+## Named agents: the staff pattern
+
+One app can employ several agents, each with its own room:
+
+```
+app/agents/
+  reader/            # Silas.agent(:reader).start(input: "...")
+    instructions.md
+    agent.yml        # model, limits — same keys as the root agent
+    tools/
+    skills/
+  clerk/
+    ...
+```
+
+Sessions are stamped with the agent's name; every turn — including crash
+resumes — runs under that agent's own tools, skills, instructions, and
+definitions digest. The inbox filters by agent; `bin/rails silas:chat
+AGENT=clerk` chats with one staff member. The root `app/agent/` remains the
+default agent, unchanged. (Subagents stay a root-agent delegation feature;
+scope switching is execution-isolated, so concurrent jobs running different
+agents never cross wires.)
+
+## Memory & handoffs
+
+Silas memory is **graph-shaped, not a graph database**: facts as
+`subject · attribute · content` triples with provenance and supersession
+("author:jane · report_format: prefers CSV" — a new value retires the old).
+The `remember` tool is **approval-gated by default** — the memory card parks
+in your inbox before anything persists; `recall` digs deeper than the few
+recent memories injected into each turn. Private per agent, or `shared: true`
+for the whole staff. Your *domain* data does not belong here — it belongs in
+your own tables, which your tools already read; memory is for the fuzzy
+residue with no natural home.
+
+Staff compose through **handoffs, not conversations**: `handoff` files a
+self-contained brief that starts a linked session for another named agent
+(async, or `await: true` for an answer), exactly-once-guarded, cycle-checked.
+Two models chatting freely is a cost and audit hazard — deliberately
+unblessed.
+
 ## Triggers
 
 An agent is reached by more than a method call:

data/app/controllers/silas/inbox/sessions_controller.rb

@@ -3,6 +3,8 @@ module Silas
     class SessionsController < BaseController
       def index
         @sessions = Silas::Session.order(created_at: :desc).limit(100)
+        @sessions = @sessions.where(agent_name: params[:agent]) if params[:agent].present?
+        @agent_names = Silas::Session.distinct.pluck(:agent_name).sort
         @pending_total = Silas::ToolInvocation.where(approval_state: "required").count
       end
 

data/app/jobs/silas/agent_loop_job.rb

@@ -20,6 +20,21 @@ module Silas
       turn = Turn.find(turn_id)
       return if turn.completed? || %w[failed canceled].include?(turn.status)
 
+      # Named-agent / subagent sessions run EVERY turn under their own scope
+      # (tools, skills, instructions, digest) — including resumes: a rescued
+      # turn re-enters here and re-establishes the same scope, so a crashed
+      # staff member never wakes up holding the root agent's tools.
+      scope = Silas.scope_for_session(turn.session)
+      if scope
+        Silas.with_agent_scope(scope) { drive(turn) }
+      else
+        drive(turn)
+      end
+    end
+
+    private
+
+    def drive(turn)
       if Silas.resolved_engine.class.loop_ownership == :engine
         perform_engine_owned(turn)
       else
@@ -27,7 +42,6 @@ module Silas
       end
     end
 
-    private
 
     # :ruby_llm — the framework drives the loop, one model call per step, tools
     # executed through the Ledger. The determinism constraints live here.

data/app/models/silas/memory.rb

@@ -0,0 +1,51 @@
+module Silas
+  # One remembered fact. Triple-ish (subject · attribute · content) with
+  # provenance (which turn wrote it) and supersession: a new fact about the
+  # same (agent, scope, subject, attribute) retires the old one — temporal
+  # versioning without a temporal store. Edges between memories are a
+  # deliberate not-yet: add them when a real agent needs multi-hop.
+  class Memory < ApplicationRecord
+    self.table_name = "silas_memories"
+
+    SCOPES = %w[agent app].freeze
+    validates :scope, inclusion: { in: SCOPES }
+    validates :agent_name, :subject, :content, presence: true
+
+    scope :active, -> { where(status: "active") }
+
+    # Write-through with supersession. attribute nil = free-form note about the
+    # subject (accumulates); attribute present = the triple's slot (supersedes).
+    def self.remember!(agent_name:, subject:, content:, attribute: nil, scope: "agent", turn: nil)
+      transaction do
+        record = create!(agent_name:, scope:, subject: subject.to_s.strip.downcase,
+                         attribute_name: attribute.presence&.strip&.downcase, content:,
+                         session_id: turn&.session_id, turn_id: turn&.id)
+        if record.attribute_name
+          active.where(agent_name:, scope:, subject: record.subject, attribute_name: record.attribute_name)
+                .where.not(id: record.id)
+                .update_all(status: "superseded", superseded_by_id: record.id, updated_at: Time.current)
+        end
+        record
+      end
+    end
+
+    # What an agent can see: its own memories + app-shared ones. Subject-matched
+    # first (when subjects given), then most recent.
+    def self.recall(agent_name:, subjects: [], limit: 10)
+      visible = active.where("agent_name = :a OR scope = 'app'", a: agent_name)
+      if subjects.any?
+        keys = subjects.map { |s| s.to_s.strip.downcase }
+        matched = visible.where(subject: keys).order(created_at: :desc).limit(limit).to_a
+        rest = visible.where.not(subject: keys).order(created_at: :desc).limit(limit - matched.size)
+        matched + rest
+      else
+        visible.order(created_at: :desc).limit(limit).to_a
+      end
+    end
+
+    def to_line
+      head = attribute_name ? "#{subject} · #{attribute_name}: " : "#{subject}: "
+      head + content
+    end
+  end
+end

data/app/models/silas/session.rb

@@ -19,15 +19,17 @@ module Silas
     end
 
     # Enqueue the next turn. One active turn per session — the partial unique
-    # index is the backstop; this is the friendly front door.
-    def continue(input:)
+    # index is the backstop; this is the friendly front door. enqueue: false
+    # creates the turn without scheduling it (callers that drive it themselves,
+    # e.g. an awaited handoff running the loop inline).
+    def continue(input:, enqueue: true)
       if active_turn
         raise TurnInProgressError, "session #{id} already has an active turn (##{active_turn.index})"
       end
 
       next_index = (turns.maximum(:index) || -1) + 1
       turn = turns.create!(index: next_index, input: input)
-      AgentLoopJob.perform_later(turn.id)
+      AgentLoopJob.perform_later(turn.id) if enqueue
       turn
     rescue ActiveRecord::RecordNotUnique
       raise TurnInProgressError, "session #{id} already has an active turn"

data/app/views/layouts/silas/inbox.html.erb

@@ -75,6 +75,10 @@
     .cost { font-family: var(--mono); font-size: 12px; color: var(--muted); }
     .flash { background: var(--red-bg); color: var(--red); padding: 10px 12px; border-radius: 10px; margin-bottom: 12px; }
     .empty { text-align: center; color: var(--muted); padding: 48px 0; }
+    .agent-filter { display: flex; gap: 6px; flex-wrap: wrap; margin-bottom: 14px; }
+    .agent-filter .chip { font-size: 12px; padding: 3px 10px; border: 1px solid #d9dce1;
+      border-radius: 999px; text-decoration: none; color: inherit; }
+    .agent-filter .chip-on { background: #16181d; color: #fff; border-color: #16181d; }
   </style>
 </head>
 <body>

data/app/views/silas/inbox/sessions/index.html.erb

@@ -2,6 +2,16 @@
   <% if @pending_total.positive? %><span class="badge"><%= @pending_total %> awaiting approval</span><% end %>
 <% end %>
 
+<% if @agent_names && @agent_names.size > 1 %>
+  <div class="agent-filter">
+    <%= link_to "all", inbox_sessions_path, class: params[:agent].blank? ? "chip chip-on" : "chip" %>
+    <% @agent_names.each do |name| %>
+      <%= link_to name, inbox_sessions_path(agent: name),
+            class: params[:agent] == name ? "chip chip-on" : "chip" %>
+    <% end %>
+  </div>
+<% end %>
+
 <% if @sessions.empty? %>
   <div class="empty">No agent sessions yet.</div>
 <% else %>

data/db/migrate/20260721000001_create_silas_memories.rb

@@ -0,0 +1,22 @@
+class CreateSilasMemories < ActiveRecord::Migration[8.1]
+  def change
+    # Agent memory: entity-attributed facts with provenance and supersession
+    # (graph-SHAPED — triples, no edges until the need is proven). Domain
+    # memory belongs in YOUR tables; this is only for the fuzzy residue that
+    # has no natural home ("author X prefers CSV", "reports arrive on the 15th").
+    create_table :silas_memories do |t|
+      t.string :agent_name, null: false            # whose memory ("agent" = root)
+      t.string :scope, null: false, default: "agent" # agent (private) | app (shared)
+      t.string :subject, null: false               # entity ref, e.g. "author:jane"
+      t.string :attribute_name                     # optional: triple form
+      t.text :content, null: false                 # the fact, plain prose
+      t.string :status, null: false, default: "active" # active | superseded
+      t.bigint :superseded_by_id
+      t.bigint :session_id                         # provenance
+      t.bigint :turn_id
+      t.timestamps
+    end
+    add_index :silas_memories, [ :agent_name, :scope, :status ]
+    add_index :silas_memories, [ :subject, :status ]
+  end
+end

data/lib/generators/silas/install/install_generator.rb

@@ -8,8 +8,15 @@ module Silas
       def create_initializer
         template "initializer.rb", "config/initializers/silas.rb"
         # ruby_llm reads no provider keys from ENV on its own; without this the
-        # first model call raises ConfigurationError.
-        template "ruby_llm.rb", "config/initializers/ruby_llm.rb"
+        # first model call raises ConfigurationError. Brownfield apps often
+        # already configure ruby_llm themselves — never touch an existing one
+        # (not even a conflict prompt: an accidental Y clobbers production
+        # provider config).
+        if File.exist?(File.join(destination_root, "config/initializers/ruby_llm.rb"))
+          say_status :skip, "config/initializers/ruby_llm.rb exists — left untouched", :yellow
+        else
+          template "ruby_llm.rb", "config/initializers/ruby_llm.rb"
+        end
       end
 
       def create_agent_directory

data/lib/silas/chat.rb

@@ -43,9 +43,15 @@ module Silas
 
     private
 
+    # AGENT=clerk resumes/starts against a named agent (app/agents/clerk/).
+    def agent_handle
+      @agent_handle ||= ENV["AGENT"].present? ? Silas.agent(ENV["AGENT"]) : Silas.agent
+    end
+
     def banner
-      description = Silas.agent.description.presence || "your agent"
-      @out.puts "Silas chat — #{description} (#{Silas.agent.model})."
+      description = agent_handle.description.presence || "your agent"
+      label = ENV["AGENT"].present? ? "#{ENV['AGENT']} — " : ""
+      @out.puts "Silas chat — #{label}#{description} (#{agent_handle.model})."
       @out.puts "Approvals prompt inline. 'exit' or Ctrl-D to quit."
       @out.puts "Resuming session #{@session.id} (#{@session.turns.count} turns)." if @session
     end
@@ -53,7 +59,7 @@ module Silas
     def submit(text)
       turn =
         if @session.nil?
-          @session = Silas.agent.start(input: text)
+          @session = agent_handle.start(input: text)
           @session.turns.first
         else
           @session.continue(input: text)

data/lib/silas/configuration.rb

@@ -26,6 +26,13 @@ module Silas
     # Subagents: the roster (name+description) and per-name scope builders, plus
     # the active-agent overrides swapped in during a nested run.
     attr_accessor :subagent_index, :subagent_scopes, :agent_override, :instructions_dir
+
+    # Named top-level agents (app/agents/<name>/): lambda -> { name => AgentScope }.
+    attr_accessor :named_agent_scopes
+
+    # Memory (silas_memories): memory=false disables entirely; memory_approval
+    # :always parks every remember for a human (default), :never auto-approves.
+    attr_accessor :memory, :memory_approval, :memory_injection_limit
     # Channels: name -> Channel subclass (wired by the Registry). Slack creds
     # default to credentials.dig(:silas, :slack, ...); nil disables Slack.
     attr_accessor :channel_resolver
@@ -92,6 +99,9 @@ module Silas
       @eval_dir = "test/agent_evals"
       @eval_grader = nil
       @sandbox = :none
+      @memory = true
+      @memory_approval = :always
+      @memory_injection_limit = 8
       @sandbox_image = nil
       @sandbox_network = "none"
       @sandbox_memory = "512m"

data/lib/silas/engine.rb

@@ -9,17 +9,28 @@ module Silas
     # Agent::Tools::IssueRefund. Tool identity remains the filename.
     initializer "silas.agent_directory" do |app|
       agent_dir = app.root.join("app/agent")
-      next unless agent_dir.exist?
+      if agent_dir.exist?
+        unless defined?(::Agent)
+          Object.const_set(:Agent, Module.new)
+        end
+        app.autoloaders.main.push_dir(agent_dir, namespace: ::Agent)
 
-      unless defined?(::Agent)
-        Object.const_set(:Agent, Module.new)
+        # Markdown/YAML (instructions.md, agent.yml, skills/*.md) are not Ruby;
+        # keep Zeitwerk away from them. tools/, schedules/ (.rb handlers), and
+        # channels/ all autoload under the Agent namespace via push_dir above.
+        app.autoloaders.main.ignore(agent_dir.join("skills"))
       end
-      app.autoloaders.main.push_dir(agent_dir, namespace: ::Agent)
 
-      # Markdown/YAML (instructions.md, agent.yml, skills/*.md) are not Ruby;
-      # keep Zeitwerk away from them. tools/, schedules/ (.rb handlers), and
-      # channels/ all autoload under the Agent namespace via push_dir above.
-      app.autoloaders.main.ignore(agent_dir.join("skills"))
+      # Named agents: app/agents/<name>/tools/x.rb autoloads as
+      # Agents::<Name>::Tools::X — the staff pattern.
+      agents_dir = app.root.join("app/agents")
+      if agents_dir.exist?
+        unless defined?(::Agents)
+          Object.const_set(:Agents, Module.new)
+        end
+        app.autoloaders.main.push_dir(agents_dir, namespace: ::Agents)
+        Dir[agents_dir.join("*/skills")].each { |d| app.autoloaders.main.ignore(d) }
+      end
     end
 
     initializer "silas.boot_guard", after: :load_config_initializers do
@@ -28,7 +39,7 @@ module Silas
 
     # Registry rebuilds on every code reload in development, once in production.
     initializer "silas.registry" do |app|
-      next unless app.root.join("app/agent").exist?
+      next unless app.root.join("app/agent").exist? || app.root.join("app/agents").exist?
 
       app.config.to_prepare { Silas::Registry.install!(root: Rails.root) }
     end

data/lib/silas/instructions.rb

@@ -12,25 +12,37 @@ module Silas
 
       turn.update!(
         instructions_snapshot: render(turn),
-        definitions_digest: Silas.config.definitions_digest&.call.to_s
+        definitions_digest: Silas.definitions_digest.to_s
       )
     end
 
     def render(turn)
-      [ base_instructions(turn), skill_index_block(turn.session), loaded_skills_block(turn.session) ]
+      [ base_instructions(turn), memory_block(turn.session), skill_index_block(turn.session), loaded_skills_block(turn.session) ]
         .compact.join("\n\n")
     end
 
     def base_instructions(turn)
       # config.instructions_dir points at the active agent's directory (root or a
       # subagent, swapped during a nested run).
-      dir = Silas.config.instructions_dir || Rails.root.join("app/agent")
+      dir = Silas.instructions_dir || Rails.root.join("app/agent")
       path = Pathname(dir).join("instructions.md")
       return default_instructions unless path.exist?
 
       ERB.new(path.read).result_with_hash(session: turn.session, agent_name: turn.session.agent_name)
     end
 
+    # Recent memories surface into the snapshot (bounded; recall digs deeper).
+    def memory_block(session)
+      return nil unless Silas.memory_enabled?
+
+      memories = Silas::Memory.recall(agent_name: session.agent_name,
+                                      limit: Silas.config.memory_injection_limit)
+      return nil if memories.empty?
+
+      "## Memory (most recent — use the recall tool for more)\n\n" +
+        memories.map { |m| "- #{m.to_line}" }.join("\n")
+    end
+
     # Advertise skill descriptions (eve's routing hint); bodies load on demand.
     def skill_index_block(session)
       advertised = Silas.skills.reject { |s| session.loaded_skills.include?(s.name) }

data/lib/silas/ledger.rb

@@ -148,7 +148,10 @@ module Silas
         when :once
           previously_approved?(invocation) ? :approved : :user_approval
         when Proc
-          policy.call(session: invocation.turn.session, input: invocation.arguments)
+          # Indifferent access: arguments are stored as jsonb (string keys),
+          # but a lambda writing input[:amount] must not get a silent nil.
+          policy.call(session: invocation.turn.session,
+                      input: invocation.arguments.with_indifferent_access)
         else
           :not_applicable
         end

data/lib/silas/named_agent.rb

@@ -0,0 +1,32 @@
+module Silas
+  # Handle for a named top-level agent (app/agents/<name>/). Same surface as
+  # the root Agent — #start plus the definition readers — so call sites don't
+  # care which kind they hold. The only difference: sessions it starts are
+  # stamped with the agent's name, and the loop swaps in the agent's scope
+  # (tools, skills, instructions, digest) for every turn of those sessions.
+  class NamedAgent
+    attr_reader :scope
+
+    def initialize(scope)
+      @scope = scope
+    end
+
+    def name = scope.name
+
+    def start(input:, metadata: {}, channel: nil, continuation_token: nil)
+      session = Session.create!(agent_name: name, metadata: metadata,
+                                channel: channel, continuation_token: continuation_token)
+      session.continue(input: input)
+      session
+    end
+
+    # Definition readers delegate to the scope's parsed agent.yml.
+    def model       = scope.agent.model
+    def description = scope.agent.description
+    def limits      = scope.agent.limits
+    def max_steps   = scope.agent.max_steps
+    def max_input_tokens = scope.agent.max_input_tokens
+    def max_cost    = scope.agent.max_cost
+    def timeout     = scope.agent.timeout
+  end
+end

data/lib/silas/nested_runner.rb

@@ -10,8 +10,8 @@ module Silas
   module NestedRunner
     module_function
 
-    def run(session, input:)
-      scope = Silas.subagent_scope(session.agent_name)
+    def run(session, input:, scope: nil)
+      scope ||= Silas.subagent_scope(session.agent_name)
       turn = session.turns.create!(index: 0, input: input)
 
       Silas.with_agent_scope(scope) do

data/lib/silas/registry.rb

@@ -16,6 +16,7 @@ module Silas
       Silas.config.channel_resolver = ->(name) { registry.channels[name] }
       Silas.config.subagent_index = -> { registry.subagent_index }
       Silas.config.subagent_scopes = -> { registry.subagent_scopes }
+      Silas.config.named_agent_scopes = -> { registry.named_agent_scopes }
       Silas.config.agent_override = nil
       Silas.config.instructions_dir = nil
       Silas.reset_agent_memo!
@@ -72,6 +73,11 @@ module Silas
       b["load_skill"] = Silas::Tools::LoadSkill if skills.any?
       b["delegate"] = Silas::Tools::Delegate if subagent_dirs.any?
       b["run_code"] = Silas::Tools::RunCode if Silas.sandbox_enabled?
+      if Silas.memory_enabled?
+        b["remember"] = Silas::Tools::Remember
+        b["recall"] = Silas::Tools::Recall
+      end
+      b["handoff"] = Silas::Tools::Handoff if named_agent_dirs.any?
       b
     end
 
@@ -103,6 +109,31 @@ module Silas
       }))
     end
 
+    # --- named agents (app/agents/<name>/ — the staff pattern) ---------------
+
+    RESERVED_AGENT_NAMES = %w[agent shared].freeze
+
+    def named_agent_dirs
+      @named_agent_dirs ||= Dir[@root.join("app/agents/*")].select { |p| File.directory?(p) }.sort
+    end
+
+    # { "clerk" => AgentScope, ... }. Each named agent is a full top-level
+    # agent: its own instructions.md, agent.yml, tools/, skills/ — autoloaded
+    # under Agents::<Camelized>. Sessions stamped with the name run every turn
+    # under this scope (loop-enforced, resume-safe, thread-isolated).
+    def named_agent_scopes
+      @named_agent_scopes ||= named_agent_dirs.to_h do |dir|
+        name = File.basename(dir)
+        if RESERVED_AGENT_NAMES.include?(name)
+          raise Error, "app/agents/#{name} collides with a reserved name — " \
+                       "'agent' is the root app/agent; rename the directory"
+        end
+
+        [ name, build_agent_scope(Pathname(dir), name, const_base: "Agents::#{name.camelize}",
+                                                       run_code: Silas.sandbox_enabled?, named: true) ]
+      end
+    end
+
     # --- subagents -----------------------------------------------------------
 
     def subagent_dirs
@@ -133,7 +164,15 @@ module Silas
     end
 
     def build_subagent_scope(dir, name)
-      const_base = "Agent::Subagents::#{name.camelize}"
+      build_agent_scope(dir, name, const_base: "Agent::Subagents::#{name.camelize}",
+                                   agent: subagent_agent(dir, name))
+    end
+
+    # Shared scope builder for subagents and named agents: tools by filename
+    # 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).
+    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")
         klass = "#{const_base}::Tools::#{tname.camelize}".constantize
@@ -143,12 +182,19 @@ module Silas
         [ tname, klass ]
       end
       skills = Dir[dir.join("skills/*.md")].sort.map { |f| Skill.parse(f) }
-      builtins = skills.any? ? { "load_skill" => Silas::Tools::LoadSkill } : {}
+      builtins = {}
+      builtins["load_skill"] = Silas::Tools::LoadSkill if skills.any?
+      builtins["run_code"] = Silas::Tools::RunCode if run_code
+      if named && Silas.memory_enabled?
+        builtins["remember"] = Silas::Tools::Remember
+        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)
       digest = Digest::SHA256.hexdigest(JSON.generate(tools: definitions, skills: skills.map { |s| [ s.name, s.description ] }))
 
-      Silas::AgentScope.new(name: name, dir: dir, agent: subagent_agent(dir, name),
+      Silas::AgentScope.new(name: name, dir: dir, agent: agent || Silas::Agent.load(dir: dir),
                             resolver: resolver, definitions: definitions, digest: digest, skills: skills)
     end
   end

data/lib/silas/step_runner.rb

@@ -70,9 +70,9 @@ module Silas
     # A deploy that changes tools/skills mid-turn must fail loudly, never
     # resume into a different agent than the one that started the turn.
     def assert_definitions_unchanged!(turn)
-      return if turn.definitions_digest.blank? || Silas.config.definitions_digest.nil?
+      return if turn.definitions_digest.blank? || Silas.definitions_digest.nil?
 
-      live = Silas.config.definitions_digest.call.to_s
+      live = Silas.definitions_digest.to_s
       return if live == turn.definitions_digest
 
       turn.finish!(:failed, reason: "definitions_changed")

data/lib/silas/tools/handoff.rb

@@ -0,0 +1,68 @@
+module Silas
+  module Tools
+    # Staff-to-staff composition WITHOUT free-form agent chatter: file a brief
+    # that starts (or awaits) another named agent's session, linked to this one.
+    # at_most_once! — the handoff is one external effect; a crash parks it
+    # in-doubt instead of double-starting the colleague.
+    class Handoff < Tool
+      class << self
+        # Roster from DIRECTORY NAMES only — reading scopes here would recurse
+        # (description -> digest -> scope build -> description). Names alone
+        # keep the digest roster-sensitive without the cycle.
+        def description
+          names = Dir[Rails.root.join("app/agents/*")].select { |p| File.directory?(p) }
+                     .map { |p| File.basename(p) }.sort
+          "Hand a task to another staff agent as a self-contained brief (they share none of " \
+          "your context). Async by default; await: true waits for their answer. " \
+          "Staff: #{names.join(', ')}."
+        end
+      end
+
+      param :agent, :string, desc: "Which staff agent takes this."
+      param :brief, :string, desc: "Fully self-contained task brief."
+      param :await, :boolean, desc: "true = run now and return their answer; default fire-and-forget."
+
+      at_most_once!
+
+      MAX_CHAIN = 3
+
+      def call(agent:, brief:, await: nil)
+        target = agent.to_s
+        return { "error" => "unknown agent #{target.inspect}" } unless Silas.named_agent?(target)
+        return { "error" => "an agent cannot hand off to itself" } if target == session.agent_name
+
+        chain = ancestry(session)
+        if chain.include?(target)
+          return { "error" => "handoff cycle: #{[ *chain.reverse, session.agent_name, target ].join(' -> ')}" }
+        end
+        return { "error" => "handoff chain too deep (max #{MAX_CHAIN})" } if chain.size >= MAX_CHAIN
+
+        nested = Session.create!(agent_name: target, parent_session_id: session.id,
+                                 metadata: { "handoff_from" => session.agent_name })
+        if await
+          # Inline drive via NestedRunner (NOT AgentLoopJob.perform_now: a
+          # Continuable job's isolated steps re-enqueue and return early under
+          # production isolate_steps — the await would see a half-run turn).
+          turn = NestedRunner.run(nested, input: brief, scope: Silas.named_agent_scope!(target))
+          { "session_id" => nested.id, "status" => turn.status, "answer" => turn.answer_text.to_s }
+        else
+          turn = nested.continue(input: brief, enqueue: false)
+          AgentLoopJob.perform_later(turn.id)
+          { "session_id" => nested.id, "status" => "queued" }
+        end
+      end
+
+      private
+
+      def ancestry(session)
+        names = []
+        cursor = session
+        while cursor.parent_session_id && names.size <= MAX_CHAIN
+          cursor = Session.find_by(id: cursor.parent_session_id) or break
+          names << cursor.agent_name
+        end
+        names
+      end
+    end
+  end
+end

data/lib/silas/tools/recall.rb

@@ -0,0 +1,18 @@
+module Silas
+  module Tools
+    # Read-side of memory: on-demand subject lookup (the injected snapshot
+    # carries only the most recent few — this digs deeper).
+    class Recall < Tool
+      description "Look up saved memories about a subject (yours + app-shared). Use before " \
+                  "asking a human something the staff may already know."
+      param :subject, :string, desc: "Entity ref to look up, e.g. 'author:jane'."
+      idempotent!
+
+      def call(subject:)
+        memories = Memory.recall(agent_name: session.agent_name, subjects: [ subject ], limit: 20)
+                         .select { |m| m.subject == subject.to_s.strip.downcase }
+        { "subject" => subject, "memories" => memories.map(&:to_line) }
+      end
+    end
+  end
+end

data/lib/silas/tools/remember.rb

@@ -0,0 +1,32 @@
+module Silas
+  module Tools
+    # Built-in, advertised when memory is enabled and the table exists. Writes
+    # are APPROVAL-GATED by default (config.memory_approval = :always) — a
+    # memory card parks in the inbox before anything persists, eve's
+    # user-approved-memory pattern done Rails-style. transactional! — the
+    # memory row and the ledger row commit together, exactly once.
+    class Remember < Tool
+      description "Save a durable memory for future sessions. Use for stable preferences and " \
+                  "facts worth keeping (\"author:jane · report_format: prefers CSV\"), never for " \
+                  "transient task state. Same subject+attribute supersedes the old value."
+      param :subject, :string, desc: "Entity this is about, e.g. 'author:jane' or 'retailer:kdp'."
+      param :content, :string, desc: "The fact, one plain sentence."
+      param :attribute, :string, desc: "Optional slot name (enables supersession), e.g. 'report_format'."
+      param :shared, :boolean, desc: "true = visible to ALL agents (app scope); default private to this agent."
+
+      transactional!
+      approval ->(session:, input:) do
+        Silas.config.memory_approval == :never ? :approved : :user_approval
+      end
+
+      def call(subject:, content:, attribute: nil, shared: nil)
+        memory = Memory.remember!(
+          agent_name: session.agent_name, subject:, content:, attribute:,
+          scope: shared ? "app" : "agent",
+          turn: session.turns.order(:index).last
+        )
+        { "remembered" => memory.to_line, "scope" => memory.scope }
+      end
+    end
+  end
+end

data/lib/silas/version.rb

@@ -1,3 +1,3 @@
 module Silas
-  VERSION = "0.1.5"
+  VERSION = "0.1.7"
 end

data/lib/silas.rb

@@ -12,6 +12,7 @@ require "silas/skill"
 require "silas/schedule"
 require "silas/schedule/compiler"
 require "silas/agent_scope"
+require "silas/named_agent"
 require "silas/tools/delegate"
 require "silas/nested_runner"
 require "silas/sandbox"
@@ -27,6 +28,9 @@ require "silas/budget"
 require "silas/registry"
 require "silas/agent"
 require "silas/tools/load_skill"
+require "silas/tools/remember"
+require "silas/tools/recall"
+require "silas/tools/handoff"
 require "silas/engines/base"
 require "silas/agent_sdk/version_guard"
 require "silas/agent_sdk/stream_parser"
@@ -62,7 +66,13 @@ module Silas
       @agent = nil
     end
 
-    def sandbox_enabled? = ![ :none, nil ].include?(config.sandbox)
+    # A configured-but-disabled backend (e.g. Hermetic.null) must not register
+    # run_code, so the object's own enabled? is the final word.
+    def sandbox_enabled?
+      return false if [ :none, nil ].include?(config.sandbox)
+
+      resolved_sandbox.enabled?
+    end
 
     def resolved_sandbox
       @resolved_sandbox ||=
@@ -74,7 +84,14 @@ module Silas
                               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
+        else
+          # A hermetic backend drops straight in (its Result is a superset of
+          # ours). Auto-arm its ledger guard so a sandbox exec inside a ledger
+          # transaction fails loud — same posture as our own Docker adapter.
+          if defined?(Hermetic::Backends::Base) && config.sandbox.is_a?(Hermetic::Backends::Base)
+            require "hermetic/silas"
+          end
+          config.sandbox
         end
     end
 
@@ -92,26 +109,68 @@ module Silas
         end
     end
 
+    # ---- scope-aware readers -------------------------------------------------
+    # Every reader consults the active AgentScope first (named agent or
+    # subagent), falling back to the boot-time config the Registry installed.
+    # The scope lives in IsolatedExecutionState — per-thread AND per-fiber
+    # (Falcon-safe), so concurrent jobs running different agents in one
+    # process can never see each other's tools.
+
     def tool_resolver
-      config.tool_resolver or raise Error, "no tool resolver configured (Registry boots one; specs must inject)"
+      current_scope&.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 || []
+      current_scope&.definitions || config.tool_definitions&.call || []
     end
 
     def skills
-      config.skills&.call || []
+      current_scope&.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)
+    # The live definitions digest as a String (nil when none configured).
+    def definitions_digest
+      current_scope&.digest || config.definitions_digest&.call&.to_s.presence
+    end
+
+    def instructions_dir
+      current_scope&.dir || config.instructions_dir
+    end
+
+    # The active agent definition — or, given a name, a handle for a NAMED
+    # agent (app/agents/<name>/) whose sessions run under that agent's scope:
+    #
+    #   Silas.agent.start(input: "...")            # the root app/agent
+    #   Silas.agent(:clerk).start(input: "...")    # a named staff member
+    def agent(name = nil)
+      return NamedAgent.new(named_agent_scope!(name)) if name
+
+      current_scope&.agent || config.agent_override || (@agent ||= Agent.load)
+    end
+
+    # Named-agent roster: { "name" => AgentScope }.
+    def named_agent_scopes = config.named_agent_scopes&.call || {}
+
+    # Memory is on when configured AND the table exists (upgrade-safe: an app
+    # that hasn't run the 0.1.7 migration simply doesn't advertise the tools).
+    def memory_enabled?
+      config.memory && Memory.table_exists?
+    rescue ActiveRecord::NoDatabaseError, ActiveRecord::ConnectionNotEstablished
+      false
+    end
+    def named_agent?(name) = named_agent_scopes.key?(name.to_s)
+
+    def named_agent_scope!(name)
+      named_agent_scopes.fetch(name.to_s) do
+        known = named_agent_scopes.keys
+        raise Error, "unknown agent #{name.inspect}" \
+                     "#{known.any? ? " (known: #{known.join(', ')})" : " — no app/agents/ directories found"}"
+      end
     end
 
     # Subagent roster: [[name, description], ...] (model-visible, so it's in the
@@ -120,24 +179,36 @@ module Silas
     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.
+    # The scope a session's turns must run under: nil for the root agent,
+    # otherwise the named-agent or subagent scope matching session.agent_name.
+    # Fails loud on an unknown name — a session pointing at a deleted agent
+    # directory must never silently run with the root agent's tools.
+    def scope_for_session(session)
+      name = session.agent_name.to_s
+      return nil if name.empty? || name == "agent"
+
+      named_agent_scopes[name] || config.subagent_scopes&.call&.[](name) or
+        raise Error, "session #{session.id} belongs to agent #{name.inspect}, " \
+                     "but no app/agents/#{name} or app/agent/subagents/#{name} exists"
+    end
+
+    # ---- scope switching -----------------------------------------------------
+
+    SCOPE_KEY = :silas_agent_scope
+
+    def current_scope
+      ActiveSupport::IsolatedExecutionState[SCOPE_KEY]
+    end
+
+    # Run a block under an AgentScope. Nestable (delegation inside a named
+    # agent restores the outer scope on exit) and isolated per execution
+    # context — no global config is mutated, so concurrent jobs are safe.
     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
+      previous = ActiveSupport::IsolatedExecutionState[SCOPE_KEY]
+      ActiveSupport::IsolatedExecutionState[SCOPE_KEY] = scope
       yield
     ensure
-      saved.each { |k, v| config.public_send("#{k}=", v) }
+      ActiveSupport::IsolatedExecutionState[SCOPE_KEY] = previous
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: silas
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.7
 platform: ruby
 authors:
 - Daniel St Paul
@@ -126,6 +126,7 @@ files:
 - app/mailers/silas/channel_mailer.rb
 - app/models/concerns/silas/inbox/broadcastable.rb
 - app/models/silas/application_record.rb
+- app/models/silas/memory.rb
 - app/models/silas/session.rb
 - app/models/silas/step.rb
 - app/models/silas/tool_invocation.rb
@@ -150,6 +151,7 @@ files:
 - db/migrate/20260715000003_add_parent_session_to_silas_sessions.rb
 - db/migrate/20260716000001_add_budget_overrides_to_silas_turns.rb
 - db/migrate/20260716000002_add_cancel_requested_to_silas_turns.rb
+- db/migrate/20260721000001_create_silas_memories.rb
 - lib/generators/silas/install/install_generator.rb
 - lib/generators/silas/install/templates/agent.yml
 - lib/generators/silas/install/templates/bin_ci
@@ -196,6 +198,7 @@ files:
 - lib/silas/mcp/handler.rb
 - lib/silas/mcp/server.rb
 - lib/silas/message_builder.rb
+- lib/silas/named_agent.rb
 - lib/silas/nested_runner.rb
 - lib/silas/registry.rb
 - lib/silas/sandbox.rb
@@ -209,7 +212,10 @@ files:
 - lib/silas/subprocess_runner.rb
 - lib/silas/tool.rb
 - lib/silas/tools/delegate.rb
+- lib/silas/tools/handoff.rb
 - lib/silas/tools/load_skill.rb
+- lib/silas/tools/recall.rb
+- lib/silas/tools/remember.rb
 - lib/silas/tools/run_code.rb
 - lib/silas/version.rb
 - lib/tasks/silas_chat.rake