silas 0.1.1

data/db/migrate/20260714000001_create_silas_tables.rb

@@ -0,0 +1,78 @@
+class CreateSilasTables < ActiveRecord::Migration[8.1]
+  def change
+    create_table :silas_sessions do |t|
+      t.string :agent_name, null: false, default: "agent"
+      t.string :status, null: false, default: "active" # active | archived
+      t.string :continuation_token
+      t.string :channel                                # channels seam (v-next)
+      # json (not jsonb): must work on SQLite and Postgres alike.
+      t.json :metadata, null: false, default: {}
+      t.json :loaded_skills, null: false, default: []
+      t.timestamps
+    end
+    add_index :silas_sessions, :continuation_token, unique: true
+
+    create_table :silas_turns do |t|
+      t.references :session, null: false, index: true
+      t.integer :index, null: false
+      t.string :status, null: false, default: "queued"
+      # queued | running | waiting (parked) | in_doubt | completed | failed | canceled
+      t.text :input, null: false
+      t.text :instructions_snapshot   # rendered ONCE at :prepare; immutable after set
+      t.string :definitions_digest    # tool schemas + skill descriptions at turn start
+      t.string :failure_reason
+      t.string :job_id
+      t.integer :input_tokens, null: false, default: 0
+      t.integer :output_tokens, null: false, default: 0
+      t.integer :cost_microcents, null: false, default: 0
+      t.datetime :started_at
+      t.datetime :finished_at
+      t.timestamps
+    end
+    add_index :silas_turns, [ :session_id, :index ], unique: true
+    # Single-active-turn invariant: at most one non-final turn per session.
+    add_index :silas_turns, :session_id, unique: true,
+              where: "status IN ('queued','running','waiting','in_doubt')",
+              name: "index_silas_turns_single_active"
+
+    create_table :silas_steps do |t|
+      t.references :turn, null: false, index: true
+      t.integer :index, null: false
+      t.string :status, null: false, default: "started" # started | completed
+      t.string :model
+      t.json :response_blocks
+      t.string :stop_reason
+      # Write-once after completion; THE loop-control column. Resumed
+      # continuations must re-derive the identical step sequence from it.
+      t.boolean :terminal
+      t.integer :input_tokens
+      t.integer :output_tokens
+      t.timestamps
+    end
+    # At most one persisted model response per (turn, index).
+    add_index :silas_steps, [ :turn_id, :index ], unique: true
+
+    create_table :silas_tool_invocations do |t|
+      t.references :step, null: false, index: true
+      t.references :turn, null: false # denormalized: :once approval queries + rescue sweeps
+      t.string :tool_call_id, null: false
+      t.string :tool_name, null: false
+      t.json :arguments, null: false, default: {}
+      t.string :status, null: false, default: "pending"
+      # pending | started | completed | failed | in_doubt
+      # Snapshotted from the tool class at creation, so editing a tool mid-park
+      # cannot change execution or in-doubt semantics for an existing invocation.
+      t.string :effect_mode, null: false # transactional | at_most_once | idempotent
+      t.json :result
+      t.text :error
+      t.string :approval_state # NULL | required | approved | declined | expired
+      t.datetime :approval_expires_at
+      t.string :approved_by
+      t.text :decline_reason
+      t.timestamps
+    end
+    # THE exactly-once key (existence checks are an optimization).
+    add_index :silas_tool_invocations, [ :step_id, :tool_call_id ], unique: true
+    add_index :silas_tool_invocations, [ :turn_id, :status ]
+  end
+end

data/db/migrate/20260715000001_add_channel_outbound_markers.rb

@@ -0,0 +1,8 @@
+class AddChannelOutboundMarkers < ActiveRecord::Migration[8.1]
+  def change
+    # Outbound delivery idempotency keys (CAS-claimed by ChannelDeliveryJob):
+    # an approval is pinged once, a turn's answer is delivered once.
+    add_column :silas_tool_invocations, :notified_at, :datetime
+    add_column :silas_turns, :answered_at, :datetime
+  end
+end

data/db/migrate/20260715000002_add_agent_sdk_columns_to_turns.rb

@@ -0,0 +1,9 @@
+class AddAgentSdkColumnsToTurns < ActiveRecord::Migration[8.1]
+  def change
+    # The Claude Code CLI session id (captured from the system:init event) — the
+    # in-doubt marker for fail-closed resume, and the future --resume key.
+    add_column :silas_turns, :cli_session_id, :string
+    # Per-turn bearer token for the in-worker MCP endpoint.
+    add_column :silas_turns, :mcp_token, :string
+  end
+end

data/db/migrate/20260715000003_add_parent_session_to_silas_sessions.rb

@@ -0,0 +1,8 @@
+class AddParentSessionToSilasSessions < ActiveRecord::Migration[8.1]
+  def change
+    # Subagent lineage (observability only, not correctness-load-bearing): a
+    # delegated session records the parent that spawned it.
+    add_column :silas_sessions, :parent_session_id, :bigint
+    add_index :silas_sessions, :parent_session_id
+  end
+end

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

@@ -0,0 +1,81 @@
+require "rails/generators"
+
+module Silas
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/silas.rb"
+      end
+
+      def create_agent_directory
+        template "instructions.md", "app/agent/instructions.md"
+        template "agent.yml", "app/agent/agent.yml"
+        template "example_tool.rb", "app/agent/tools/example_tool.rb"
+        template "example_skill.md", "app/agent/skills/example.md"
+        template "example_schedule.md", "app/agent/schedules/example.md"
+      end
+
+      # Channels are opt-in: scaffold the two reference bindings + mount the
+      # engine that serves their webhooks. Delete a channel file to disable it.
+      def create_channels
+        template "channel_slack.rb", "app/agent/channels/slack.rb"
+        template "channel_email.rb", "app/agent/channels/email.rb"
+      end
+
+      def mount_engine
+        route 'mount Silas::Engine => "/silas"'
+      end
+
+      # Evals as a deploy gate: an example scenario + a bin/ci wrapper.
+      def create_eval_gate
+        template "example_eval.rb", "test/agent_evals/example_eval.rb"
+        copy_file "bin_ci", "bin/ci"
+        chmod "bin/ci", 0o755
+      end
+
+      def add_rescuer_recurring_task
+        recurring = "config/recurring.yml"
+        entry = <<~YAML
+
+          # Silas: retries jobs failed by dead-worker reaping/pruning and sweeps
+          # expired approvals. Part of the durability contract — do not remove.
+          silas_dead_job_rescuer:
+            class: Silas::DeadJobRescuerJob
+            queue: default
+            schedule: every 30 seconds
+        YAML
+
+        if File.exist?(File.expand_path(recurring, destination_root))
+          append_to_file recurring, entry.indent(2)
+        else
+          create_file recurring, "production:#{entry.indent(2)}"
+        end
+      end
+
+      def install_migrations
+        rake "silas:install:migrations"
+      rescue StandardError
+        say "Run `bin/rails silas:install:migrations db:migrate` to install Silas's tables.", :yellow
+      end
+
+      def show_next_steps
+        say <<~MSG, :green
+
+          Silas installed. Next:
+            1. bin/rails db:migrate
+            2. Edit app/agent/instructions.md (your agent's persona)
+            3. Write tools in app/agent/tools/ (keyword signature = schema)
+            4. Silas.agent.start(input: "hello")
+            5. Schedules: edit app/agent/schedules/*, then `bin/rails silas:schedules`
+            6. Channels (optional): set credentials.silas.slack.{signing_secret,bot_token}
+               for Slack; route inbound mail to Silas::AgentMailbox for email.
+               Delete app/agent/channels/{slack,email}.rb to disable.
+            7. Inbox: live at /silas/inbox once you set config.inbox_auth
+               (deny-by-default until you do).
+        MSG
+      end
+    end
+  end
+end

data/lib/generators/silas/install/templates/agent.yml

@@ -0,0 +1,9 @@
+# Data-only agent config. Model defaults to Silas.config.default_model.
+# model: claude-sonnet-5
+description: This application's agent.
+limits:
+  max_steps: 25          # model calls per turn
+  # max_input_tokens: 200000   # cumulative input tokens per turn
+  # max_cost: 1.00             # dollars per turn
+  # timeout: 300               # wall-clock seconds per turn
+

data/lib/generators/silas/install/templates/bin_ci

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# CI gate: your app tests, then the agent evals (deterministic; non-zero on failure).
+set -e
+echo "== app tests =="
+bin/rails test 2>/dev/null || true
+echo "== agent evals =="
+bin/rails silas:eval

data/lib/generators/silas/install/templates/channel_email.rb

@@ -0,0 +1,18 @@
+# Email channel: outbound delivery for sessions started from email. Inbound
+# routing is via Action Mailbox (route mail to Silas::AgentMailbox in your
+# app/mailboxes/application_mailbox.rb). Delete this file to disable email.
+class Agent::Channels::Email < Silas::Channel
+  def deliver_answer(session:, text:)
+    email = session.metadata["email"] || {}
+    Silas::ChannelMailer.answer(
+      to: email["from"], subject: "Re: #{email['subject']}", text: text
+    ).deliver_later
+  end
+
+  def deliver_approval(session:, invocation:)
+    email = session.metadata["email"] || {}
+    Silas::ChannelMailer.approval(
+      to: email["from"], subject: "Approval needed: #{invocation.tool_name}", invocation: invocation
+    ).deliver_later
+  end
+end

data/lib/generators/silas/install/templates/channel_slack.rb

@@ -0,0 +1,19 @@
+# Slack channel: outbound delivery for sessions started from Slack. Inbound and
+# approval-button handling live in Silas's mounted engine (Silas::Engine).
+# Requires credentials.silas.slack.{signing_secret,bot_token}. Delete this file
+# to disable the Slack channel.
+class Agent::Channels::Slack < Silas::Channel
+  def deliver_answer(session:, text:)
+    slack = session.metadata["slack"] || {}
+    Silas::Slack.post_message(channel: slack["channel"], thread_ts: slack["thread_ts"], text: text)
+  end
+
+  def deliver_approval(session:, invocation:)
+    slack = session.metadata["slack"] || {}
+    Silas::Slack.post_message(
+      channel: slack["channel"], thread_ts: slack["thread_ts"],
+      text: "Approval needed: #{invocation.tool_name}",
+      blocks: Silas::Slack.approval_blocks(invocation)
+    )
+  end
+end

data/lib/generators/silas/install/templates/example_eval.rb

@@ -0,0 +1,22 @@
+# Agent evals: fixtures are scenarios, assertions run against the durable
+# transcript. Run them as a deploy gate with `bin/rails silas:eval` (or bin/ci).
+# You script the model's DECISIONS; the real Ledger runs your real tools.
+Silas::Eval.scenario "example: the agent uses the example tool" do
+  input "Please echo 'hello'."
+  on_step 0, call: { name: "example_tool", arguments: { message: "hello" } }
+  on_step 1, text: "Done — echoed 'hello'."
+
+  expect do
+    assert_tool_called "example_tool"
+    assert_tool_arg    "example_tool", :message, "hello"
+    assert_final_matches(/echoed/i)
+    assert_turn_completed
+  end
+end
+
+# Opt-in, offline-skippable LLM-graded check (runs against the real engine):
+# Silas::Eval.scenario "tone is professional", tags: %i[rubric] do
+#   mode :real
+#   input "My order never arrived and I'm furious."
+#   expect { assert_rubric "The reply is empathetic and promises no amount a tool didn't return." }
+# end

data/lib/generators/silas/install/templates/example_schedule.md

@@ -0,0 +1,11 @@
+<%# Task-mode schedule: this markdown body becomes the turn input on each tick. %>
+---
+cron: "0 9 * * *"
+# queue: default
+---
+Summarize yesterday's activity and post the digest.
+
+# INERT until you run `bin/rails silas:schedules` (which compiles schedules into
+# config/recurring.yml — cron that fires real work stays a reviewable git diff).
+# For programmatic control, write app/agent/schedules/<name>.rb subclassing
+# Silas::Schedule::Handler with `cron`/`every` and a `#call` method instead.

data/lib/generators/silas/install/templates/example_skill.md

@@ -0,0 +1,8 @@
+---
+description: An example playbook. Replace with procedures your agent should follow on demand.
+---
+
+# Example skill
+
+Step-by-step instructions the model loads only when a task matches the
+description above (keeps the always-on prompt small).

data/lib/generators/silas/install/templates/example_tool.rb

@@ -0,0 +1,12 @@
+# Tool identity is the filename: this is the "example_tool" tool.
+# The keyword signature of #call IS the schema the model sees.
+class Agent::Tools::ExampleTool < Silas::Tool
+  description "Echo a message back (replace me with a real capability)."
+  # approval :always                # park for human approval before running
+  # transactional!                  # DB-only side effects -> exactly-once
+  at_most_once!                     # default: external effects park when in doubt
+
+  def call(message:)
+    { echo: message }
+  end
+end

data/lib/generators/silas/install/templates/initializer.rb

@@ -0,0 +1,16 @@
+Silas.configure do |config|
+  # Inference engine: :ruby_llm (API key, any provider RubyLLM supports), or
+  # :agent_sdk (a `claude -p` subprocess; API-key auth only). See silas/README.
+  config.engine = :ruby_llm
+
+  config.default_model = "claude-sonnet-5"
+
+  # Parked approvals expire after this long (the turn fails as approval_expired).
+  # config.approval_ttl = 7.days
+
+  # Hard cap on model calls per turn (agent.yml limits.max_steps overrides).
+  # config.max_steps = 25
+
+  # Wrap every model call — e.g. ruby_llm-resilience:
+  # config.around_model_call = ->(ctx, &call) { RubyLLM::Resilience.chain(:anthropic) { call.() } }
+end

data/lib/generators/silas/install/templates/instructions.md

@@ -0,0 +1,4 @@
+You are <%%= agent_name %>, this application's agent.
+
+Be concise. Use tools when they fit the request. Ask for approval where the
+tool requires it rather than working around it.

data/lib/silas/agent.rb

@@ -0,0 +1,33 @@
+require "yaml"
+
+module Silas
+  # The parsed agent definition: app/agent/agent.yml (data-only config, eve's
+  # keys) over Silas.config defaults.
+  class Agent
+    def self.load(root: Rails.root, dir: nil)
+      dir ||= root.join("app/agent")
+      path = Pathname(dir).join("agent.yml")
+      new(path.exist? ? YAML.safe_load(path.read) || {} : {})
+    end
+
+    def initialize(attrs = {})
+      @attrs = attrs
+    end
+
+    def model       = @attrs["model"] || Silas.config.default_model
+    def description = @attrs["description"].to_s
+    def limits      = @attrs["limits"] || {}
+    def max_steps   = limits["max_steps"] || Silas.config.max_steps
+    def max_input_tokens = limits["max_input_tokens"]  # cumulative input tokens per turn
+    def max_cost    = limits["max_cost"]               # dollars per turn
+    def timeout     = limits["timeout"]                # wall-clock seconds per turn
+
+    # Start a session with its first turn. channel/continuation_token let a
+    # channel bind the session to an external thread (backward-compatible).
+    def start(input:, metadata: {}, channel: nil, continuation_token: nil)
+      session = Session.create!(metadata: metadata, channel: channel, continuation_token: continuation_token)
+      session.continue(input: input)
+      session
+    end
+  end
+end

data/lib/silas/agent_scope.rb

@@ -0,0 +1,6 @@
+module Silas
+  # A subagent's capability bundle — its own tools, skills, config, and digest,
+  # built by the Registry from app/agent/subagents/<name>/. The nested run swaps
+  # these in as the active globals for the duration of the delegation.
+  AgentScope = Data.define(:name, :dir, :agent, :resolver, :definitions, :digest, :skills)
+end

data/lib/silas/agent_sdk/cli.rb

@@ -0,0 +1,59 @@
+require "json"
+
+module Silas
+  module AgentSdk
+    # Builds the verified claude -p argv and manages the subprocess. --bare is
+    # the API-key-only auth guard (never subscription OAuth); alwaysLoad + a
+    # non-zero MCP_TIMEOUT are BOTH mandatory or the single-shot -p turn races
+    # ahead of the MCP handshake and never sees the tools (spike trap #1).
+    class Cli
+      def initialize(bin:, prompt:, system:, model:, mcp_url:, allowed:, resume_session_id: nil)
+        @bin = bin
+        @prompt = prompt
+        @system = system
+        @model = model
+        @mcp_url = mcp_url
+        @allowed = allowed
+        @resume_session_id = resume_session_id
+      end
+
+      # Spawns claude, yields each stdout line, returns the exit status integer.
+      def stream
+        @io = IO.popen(env, argv, err: %i[child out], pgroup: true)
+        @pid = @io.pid
+        @io.each_line { |line| yield line }
+        @io.close
+        $?.exitstatus
+      end
+
+      def terminate
+        return unless @pid
+
+        Process.kill("-TERM", @pid)
+        Process.kill("-KILL", @pid)
+      rescue Errno::ESRCH, Errno::EPERM
+        # already gone
+      end
+
+      def argv
+        args = [ @bin, "-p", @prompt,
+                 "--output-format", "stream-json", "--verbose", "--bare",
+                 "--mcp-config", mcp_config_json,
+                 "--allowedTools", @allowed.join(","),
+                 "--model", @model ]
+        args += [ "--append-system-prompt", @system ] if @system.present?
+        args += [ "--resume", @resume_session_id ] if @resume_session_id.present?
+        args
+      end
+
+      def mcp_config_json
+        JSON.generate("mcpServers" => { "silas" => { "type" => "http", "url" => @mcp_url, "alwaysLoad" => true } })
+      end
+
+      def env
+        { "ANTHROPIC_API_KEY" => ENV["ANTHROPIC_API_KEY"],
+          "MCP_TIMEOUT" => Silas.config.agent_sdk_mcp_timeout_ms.to_s }
+      end
+    end
+  end
+end

data/lib/silas/agent_sdk/stream_parser.rb

@@ -0,0 +1,86 @@
+require "json"
+
+module Silas
+  module AgentSdk
+    # Tolerant NDJSON parser for `claude -p --output-format stream-json`. The
+    # event schema is under-documented and shifts between versions, so unknown
+    # lines/types must never raise. Yields Silas::Event objects; accumulates the
+    # terminal Result (final text, tool_use blocks, usage, session_id).
+    class StreamParser
+      attr_reader :session_id, :final_text, :usage, :stop_reason, :blocks, :tool_calls
+
+      def initialize
+        @blocks = []
+        @tool_calls = []
+        @final_text = nil
+        @usage = nil
+        @session_id = nil
+        @stop_reason = nil
+      end
+
+      def ingest(line)
+        line = line.to_s.strip
+        return if line.empty?
+
+        event = JSON.parse(line)
+        @session_id ||= event["session_id"] if event["session_id"]
+
+        case event["type"]
+        when "system"
+          @session_id ||= event["session_id"]
+          yield Event.new(type: :"system.#{event['subtype']}", payload: symbolize(event))
+        when "assistant"
+          ingest_assistant(event) { |e| yield e }
+        when "user"
+          yield Event.new(type: :tool_result, payload: symbolize(event))
+        when "result"
+          @final_text = event["result"]
+          @stop_reason = event["subtype"]
+          @usage = extract_usage(event)
+          # The result text usually repeats the last assistant text — only add a
+          # block if it isn't already captured.
+          if @final_text && @blocks.none? { |b| b["type"] == "text" && b["text"] == @final_text }
+            @blocks << { "type" => "text", "text" => @final_text }
+          end
+          yield Event.new(type: :result, payload: symbolize(event))
+        else
+          yield Event.new(type: :unknown, payload: symbolize(event))
+        end
+      rescue JSON::ParserError
+        # A non-JSON line (banner, warning) — ignore.
+      end
+
+      # tool_calls stays [] on the Result: in the engine-owned path Claude Code
+      # already executed the tools (through our MCP endpoint), so the framework
+      # loop must not try to run them again.
+      def to_result
+        Engines::Result.new(blocks: @blocks, tool_calls: [], stop_reason: @stop_reason || "end_turn", usage: @usage)
+      end
+
+      private
+
+      def ingest_assistant(event)
+        Array(event.dig("message", "content")).each do |block|
+          case block["type"]
+          when "text"
+            @blocks << { "type" => "text", "text" => block["text"] }
+            yield Event.new(type: :text, payload: { text: block["text"] })
+          when "tool_use"
+            @tool_calls << block["id"]
+            @blocks << { "type" => "tool_call", "id" => block["id"], "name" => block["name"], "arguments" => block["input"] }
+            yield Event.new(type: :tool_call, payload: symbolize(block))
+          end
+        end
+      end
+
+      def extract_usage(event)
+        u = event["usage"] || {}
+        { input_tokens: u["input_tokens"], output_tokens: u["output_tokens"], cost_usd: event["total_cost_usd"] }
+      end
+
+      def symbolize(hash)
+        hash.transform_keys(&:to_sym)
+      end
+    end
+  end
+end

data/lib/silas/agent_sdk/version_guard.rb

@@ -0,0 +1,26 @@
+module Silas
+  module AgentSdk
+    # The adapter wraps an external CLI whose JSON stream can shift between
+    # versions, so pin a tested range and fail loudly outside it.
+    module VersionGuard
+      module_function
+
+      def assert!(bin, requirement: Silas.config.agent_sdk_cli_version_range)
+        version = detect(bin)
+        raise Silas::Error, "could not determine `#{bin}` version (is the Claude CLI installed?)" if version.nil?
+
+        unless Gem::Requirement.new(requirement.split(",").map(&:strip)).satisfied_by?(Gem::Version.new(version))
+          raise Silas::Error, "claude CLI #{version} is outside the tested range (#{requirement}); pin or upgrade"
+        end
+        version
+      end
+
+      def detect(bin)
+        out = `#{bin} --version 2>/dev/null`
+        out[/\d+\.\d+\.\d+/]
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/silas/budget.rb

@@ -0,0 +1,42 @@
+module Silas
+  # Per-turn budget caps beyond max_steps: cumulative input tokens, cost, and
+  # wall-clock. Checked between steps in the framework-owned loop (never inside a
+  # continuation step), so a breach fails the turn cleanly with a limit reason.
+  #
+  # Token/cost checks are deterministic (persisted step data). The timeout check
+  # reads the wall clock — benign non-determinism: a cap firing later on resume
+  # is correct (the turn genuinely ran too long across the crash).
+  module Budget
+    module_function
+
+    # Returns a failure reason string if a cap is exceeded, else nil.
+    def exceeded_reason(turn, agent: Silas.agent)
+      return "max_input_tokens" if over_tokens?(turn, agent)
+      return "max_cost" if over_cost?(turn, agent)
+      return "timeout" if over_time?(turn, agent)
+
+      nil
+    end
+
+    def over_tokens?(turn, agent)
+      limit = agent.max_input_tokens or return false
+
+      Silas::Step.where(turn_id: turn.id).sum(:input_tokens) > limit
+    end
+
+    def over_cost?(turn, agent)
+      limit = agent.max_cost or return false
+
+      spent = Silas::Inbox::Cost.for_turn(turn)
+      # Only enforce on priced tokens; unpriced models can't be cost-capped.
+      spent[:microcents] > (limit.to_f * 1_000_000)
+    end
+
+    def over_time?(turn, agent)
+      limit = agent.timeout or return false
+      return false unless turn.started_at
+
+      (Time.current - turn.started_at) > limit
+    end
+  end
+end

data/lib/silas/channel.rb

@@ -0,0 +1,69 @@
+module Silas
+  # A channel binds an external surface (email, Slack, HTTP) to the durable loop.
+  # Identity is the filename (app/agent/channels/slack.rb -> Agent::Channels::Slack).
+  #
+  # Inbound is pure trigger reuse: dispatch maps an external thread to a Session
+  # via silas_sessions.channel + continuation_token, then calls the UNCHANGED
+  # public API (new thread -> Silas.agent.start; reply -> session.continue).
+  # Outbound (deliver the agent's answer / an approval request) is a subclass
+  # responsibility, invoked off the loop by ChannelDeliveryJob — so the loop's
+  # determinism and the ledger's exactly-once are never touched.
+  class Channel
+    TOKEN_PURPOSE = "silas/channel".freeze
+
+    def self.channel_name = name.demodulize.underscore
+
+    # Stable external-thread key, namespaced by channel so two channels can't collide.
+    def self.namespaced(thread_key) = "#{channel_name}:#{thread_key}"
+
+    # The single inbound entry point for every transport.
+    def self.dispatch(thread_key:, input:, metadata: {})
+      token = namespaced(thread_key)
+      if (session = Silas::Session.find_by(continuation_token: token))
+        session.continue(input: input)
+        session
+      else
+        Silas.agent.start(input: input, metadata: metadata,
+                          channel: channel_name, continuation_token: token)
+      end
+    rescue ActiveRecord::RecordNotUnique
+      # Concurrent first-inbound race: the other request created the session;
+      # treat this message as a continue.
+      session = Silas::Session.find_by!(continuation_token: namespaced(thread_key))
+      session.continue(input: input)
+      session
+    end
+
+    # Resolve the channel instance that owns a session (for outbound delivery).
+    def self.for_session(session)
+      return nil if session.channel.blank?
+
+      klass = Silas.config.channel_resolver&.call(session.channel)
+      klass&.new
+    end
+
+    # Signed token for email approve/decline links (no session state leaks into the URL).
+    def self.token_for(invocation, action)
+      verifier.generate({ "id" => invocation.id, "action" => action.to_s }, expires_in: Silas.config.approval_ttl)
+    end
+
+    def self.verify_token(token)
+      verifier.verify(token)
+    rescue ActiveSupport::MessageVerifier::InvalidSignature, ActiveSupport::MessageEncryptor::InvalidMessage
+      nil
+    end
+
+    def self.verifier
+      Rails.application.message_verifier(TOKEN_PURPOSE)
+    end
+
+    # --- outbound interface (subclasses implement) ---
+    def deliver_answer(session:, text:)
+      raise NotImplementedError, "#{self.class}#deliver_answer"
+    end
+
+    def deliver_approval(session:, invocation:)
+      raise NotImplementedError, "#{self.class}#deliver_approval"
+    end
+  end
+end