silas 0.4.0 → 0.6.0

data/lib/silas/schedule.rb

@@ -10,33 +10,59 @@ module Silas
   #
   # Identity is the filesystem path under app/agent/schedules (subdirs included):
   # schedules/billing/sweep.rb -> "billing/sweep" -> Agent::Schedules::Billing::Sweep.
-  # Schedules are NOT model-visible capabilities, so they never enter the
-  # definitions digest — adding or removing one cannot diverge an in-flight turn.
+  # Named agents own their schedules the same way they own tools and skills:
+  # app/agents/analyst/schedules/monday_kpis.md -> "agents/analyst/monday_kpis",
+  # and its ticks start THAT agent — a staff member's cron never wakes the root
+  # agent. Schedules are NOT model-visible capabilities, so they never enter
+  # the definitions digest — adding or removing one cannot diverge an
+  # in-flight turn.
   class Schedule
     KINDS = %i[task handler].freeze
 
-    attr_reader :name, :cron, :queue, :kind, :payload
+    attr_reader :name, :cron, :queue, :kind, :payload, :agent_name
 
-    def initialize(name:, cron:, queue:, kind:, payload:)
+    def initialize(name:, cron:, queue:, kind:, payload:, agent_name: nil)
       @name = name
       @cron = cron
       @queue = queue
       @kind = kind
       @payload = payload
+      @agent_name = agent_name
     end
 
     def self.parse(path, root:)
-      rel = path.relative_path_from(root.join("app/agent/schedules"))
-      name = rel.sub_ext("").to_s
+      agents_dir = root.join("app/agents")
+      if path.to_s.start_with?("#{agents_dir}#{File::SEPARATOR}")
+        parse_named(path, agents_dir: agents_dir)
+      else
+        rel = path.relative_path_from(root.join("app/agent/schedules"))
+        name = rel.sub_ext("").to_s
+        case path.extname
+        when ".md" then from_markdown(name, path)
+        when ".rb"
+          const = "Agent::Schedules::" + name.split("/").map(&:camelize).join("::")
+          from_handler(name, const.constantize)
+        end
+      end
+    end
+
+    # app/agents/<agent>/schedules/<rel> — the "agents/" name prefix keeps
+    # names (and therefore recurring keys) collision-free against a root
+    # schedule that happens to share the path shape.
+    def self.parse_named(path, agents_dir:)
+      rel = path.relative_path_from(agents_dir)          # analyst/schedules/monday_kpis.md
+      agent = rel.each_filename.first
+      sched = rel.relative_path_from(Pathname(agent).join("schedules")).sub_ext("").to_s
+      name = "agents/#{agent}/#{sched}"
       case path.extname
-      when ".md" then from_markdown(name, path)
+      when ".md" then from_markdown(name, path, agent_name: agent)
       when ".rb"
-        const = "Agent::Schedules::" + name.split("/").map(&:camelize).join("::")
-        from_handler(name, const.constantize)
+        const = "Agents::#{agent.camelize}::Schedules::" + sched.split("/").map(&:camelize).join("::")
+        from_handler(name, const.constantize, agent_name: agent)
       end
     end
 
-    def self.from_markdown(name, path)
+    def self.from_markdown(name, path, agent_name: nil)
       content = File.read(path)
       # Tolerate leading whitespace/blank lines (e.g. an ERB comment in a
       # generator template renders to an empty first line).
@@ -51,10 +77,10 @@ module Silas
       raise Error, "schedule #{name}: missing `cron:` frontmatter" if cron.nil?
 
       new(name: name, cron: cron.to_s, queue: (frontmatter["queue"] || Silas.config.queue_name).to_s,
-          kind: :task, payload: body.strip)
+          kind: :task, payload: body.strip, agent_name: agent_name)
     end
 
-    def self.from_handler(name, klass)
+    def self.from_handler(name, klass, agent_name: nil)
       unless klass.ancestors.include?(Schedule::Handler)
         raise Error, "#{klass} (schedule #{name}) must inherit Silas::Schedule::Handler"
       end
@@ -62,14 +88,17 @@ module Silas
       raise Error, "schedule #{name}: handler must declare `cron` or `every`" if cron.nil?
 
       new(name: name, cron: cron, queue: (klass.queue || Silas.config.queue_name).to_s,
-          kind: :handler, payload: klass)
+          kind: :handler, payload: klass, agent_name: agent_name)
     end
 
-    # The only behavioural difference between the two forms.
+    # The only behavioural difference between the two forms. A named agent's
+    # task starts THAT agent (its tools, instructions, digest — the loop swaps
+    # the scope in for every turn of the session it creates).
     def trigger!
       case kind
       when :task
-        Silas.agent.start(input: payload, metadata: { "trigger" => "schedule", "schedule" => name })
+        owner = agent_name ? Silas.agent(agent_name) : Silas.agent
+        owner.start(input: payload, metadata: { "trigger" => "schedule", "schedule" => name })
       when :handler
         payload.new(schedule: self).call
       end

data/lib/silas/slack.rb

@@ -43,13 +43,16 @@ module Silas
 
     # Slack signs each request (v0 scheme) — HMAC-SHA256 over "v0:ts:body" plus a
     # 5-minute replay window. Returns true only for a genuine, fresh request.
+    # Slack ALWAYS sends a timestamp, so a missing one is refused here rather
+    # than falling through to Webhook's "no timestamp, no window" default.
     def verify_signature(signing_secret:, timestamp:, body:, signature:, now: Time.current.to_i)
-      return false if signing_secret.blank? || signature.blank? || timestamp.blank?
-      return false if (now - timestamp.to_i).abs > REPLAY_WINDOW
+      return false if timestamp.blank?
 
-      basestring = "v0:#{timestamp}:#{body}"
-      expected = "v0=" + OpenSSL::HMAC.hexdigest("SHA256", signing_secret, basestring)
-      ActiveSupport::SecurityUtils.secure_compare(expected, signature)
+      Silas::Webhook.verify_hmac(
+        secret: signing_secret, signature: signature,
+        payload: "v0:#{timestamp}:#{body}", timestamp: timestamp,
+        window: REPLAY_WINDOW, prefix: "v0=", now: now
+      )
     end
   end
 end

data/lib/silas/step_runner.rb

@@ -51,6 +51,11 @@ module Silas
 
     def execute_model_call(turn, index, step)
       assert_definitions_unchanged!(turn)
+      # Compact BEFORE building messages, inside the isolated step: a crash
+      # anywhere in this step re-runs it, and the compaction claim is
+      # idempotent — a re-executed step sees the identical (compacted) history
+      # its first attempt saw. MessageBuilder reads the row this ensures.
+      Compactor.ensure!(turn)
       engine = Silas.resolved_adapter
       context = {
         turn: turn,

data/lib/silas/tools/ask_question.rb

@@ -0,0 +1,26 @@
+module Silas
+  module Tools
+    # Parks the turn to ask the HUMAN something — information, not permission.
+    #
+    # It rides the approval machinery end to end (park at zero compute, TTL
+    # expiry, channel ping, the resume gate), differing only in the verdict: an
+    # operator ANSWERS, and the answer text becomes the tool result the model
+    # resumes with. Replay determinism is free — the answer is a persisted row
+    # like any other tool result.
+    class AskQuestion < Tool
+      description "Ask the human operator a question and pause until they answer. " \
+                  "Use when you need information only a person has. The run parks at " \
+                  "zero compute until the answer arrives; the answer is returned as this tool's result."
+      param :question, :string, desc: "The question, complete and self-contained — " \
+                                      "the operator sees nothing but this text."
+      approval :always # the park; ToolInvocation#answer!/decline! settle it
+
+      def call(question:)
+        # pending+approved would execute this, but ToolInvocation#approve!
+        # refuses questions (answer! is their verdict) — reaching here is a
+        # framework bug, never a user mistake.
+        raise Error, "ask_question is answered, not executed — ToolInvocation#answer! settles it"
+      end
+    end
+  end
+end

data/lib/silas/version.rb

@@ -1,3 +1,3 @@
 module Silas
-  VERSION = "0.4.0"
+  VERSION = "0.6.0"
 end

data/lib/silas/webhook.rb

@@ -0,0 +1,47 @@
+require "openssl"
+
+module Silas
+  # Inbound webhook signature verification, shared by every channel.
+  #
+  # Vendors differ only in what they sign and how they label it: Slack signs
+  # "v0:#{timestamp}:#{body}" and prefixes "v0=", GitHub signs the raw body and
+  # prefixes "sha256=", Shopify signs the raw body and Base64-encodes it. The
+  # dangerous parts are identical everywhere — constant-time comparison, a
+  # replay window, and failing closed on a missing secret — so they live here
+  # and get tested once, while the caller supplies the vendor's shape.
+  module Webhook
+    module_function
+
+    REPLAY_WINDOW = 300 # seconds
+
+    # Returns true ONLY for a genuine, fresh request. Every failure path returns
+    # false rather than raising: a webhook endpoint answers 401, it does not 500.
+    #
+    #   secret      the shared signing secret. Blank => false (a channel with no
+    #               secret configured must reject, never accept).
+    #   signature   the header value, exactly as sent.
+    #   payload     the bytes the vendor signed — usually request.raw_post,
+    #               sometimes a basestring built from it. NEVER the parsed
+    #               params: re-serializing changes the bytes and the HMAC.
+    #   timestamp   the vendor's request timestamp, if it sends one. Present =>
+    #               anything outside +/- window is refused as a replay.
+    #   prefix      whatever the vendor puts before the digest ("v0=", "sha256=").
+    #   digest      "hex" (nearly everyone) or "base64" (Shopify, Twilio).
+    def verify_hmac(secret:, signature:, payload:, timestamp: nil, window: REPLAY_WINDOW,
+                    prefix: "", algorithm: "SHA256", digest: :hex, now: Time.current.to_i)
+      return false if secret.blank? || signature.blank?
+      return false if timestamp.present? && window && (now - timestamp.to_i).abs > window
+
+      expected = prefix + hmac(algorithm, secret, payload, digest)
+      ActiveSupport::SecurityUtils.secure_compare(expected, signature)
+    end
+
+    def hmac(algorithm, secret, payload, digest)
+      case digest
+      when :hex    then OpenSSL::HMAC.hexdigest(algorithm, secret, payload)
+      when :base64 then Base64.strict_encode64(OpenSSL::HMAC.digest(algorithm, secret, payload))
+      else raise ArgumentError, "digest must be :hex or :base64, got #{digest.inspect}"
+      end
+    end
+  end
+end

data/lib/silas.rb

@@ -19,6 +19,7 @@ require "silas/tools/delegate"
 require "silas/nested_runner"
 require "silas/sandbox"
 require "silas/tools/run_code"
+require "silas/webhook"
 require "silas/channel"
 require "silas/slack"
 require "silas/mcp/client"
@@ -29,8 +30,10 @@ require "silas/inbox/cost"
 require "silas/inbox/delta_broadcaster"
 require "silas/delta_buffer"
 require "silas/budget"
+require "silas/compactor"
 require "silas/registry"
 require "silas/agent"
+require "silas/tools/ask_question"
 require "silas/tools/load_skill"
 require "silas/tools/remember"
 require "silas/tools/recall"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: silas
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Daniel St Paul
@@ -109,6 +109,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
+- DEPLOY.md
 - LICENSE
 - README.md
 - app/controllers/concerns/silas/api/serialization.rb
@@ -133,6 +134,7 @@ files:
 - app/mailers/silas/channel_mailer.rb
 - app/models/concerns/silas/inbox/broadcastable.rb
 - app/models/silas/application_record.rb
+- app/models/silas/compaction.rb
 - app/models/silas/memory.rb
 - app/models/silas/session.rb
 - app/models/silas/step.rb
@@ -146,6 +148,7 @@ files:
 - 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/_row.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
@@ -162,11 +165,32 @@ files:
 - db/migrate/20260721000001_create_silas_memories.rb
 - db/migrate/20260724000001_drop_agent_sdk_columns_from_silas_turns.rb
 - db/migrate/20260725000001_add_provider_to_silas_steps.rb
+- db/migrate/20260725000002_create_silas_compactions.rb
+- docs/agents.md
+- docs/budgets.md
+- docs/cancellation.md
+- docs/channels.md
+- docs/configuration.md
+- docs/connections.md
+- docs/conventions.md
+- docs/evals.md
+- docs/guarantees.md
+- docs/inbox-and-api.md
+- docs/memory.md
+- docs/sandbox.md
+- docs/tools.md
+- docs/tutorial.md
+- docs/vs-eve.md
+- docs/why-silas.md
+- lib/generators/silas/channel/channel_generator.rb
+- lib/generators/silas/channel/templates/channel.rb.tt
+- lib/generators/silas/channel/templates/controller.rb.tt
 - 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/claude_skill.md
 - lib/generators/silas/install/templates/example_eval.rb
 - lib/generators/silas/install/templates/example_schedule.md
 - lib/generators/silas/install/templates/example_skill.md
@@ -182,6 +206,7 @@ files:
 - lib/silas/budget.rb
 - lib/silas/channel.rb
 - lib/silas/chat.rb
+- lib/silas/compactor.rb
 - lib/silas/configuration.rb
 - lib/silas/connection.rb
 - lib/silas/connections.rb
@@ -222,6 +247,7 @@ files:
 - lib/silas/slack.rb
 - lib/silas/step_runner.rb
 - lib/silas/tool.rb
+- lib/silas/tools/ask_question.rb
 - lib/silas/tools/delegate.rb
 - lib/silas/tools/handoff.rb
 - lib/silas/tools/load_skill.rb
@@ -229,6 +255,7 @@ files:
 - lib/silas/tools/remember.rb
 - lib/silas/tools/run_code.rb
 - lib/silas/version.rb
+- lib/silas/webhook.rb
 - lib/tasks/silas_chat.rake
 - lib/tasks/silas_doctor.rake
 - lib/tasks/silas_eval.rake
@@ -240,6 +267,8 @@ 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
+  documentation_uri: https://github.com/danielstpaul/silas/tree/main/docs
+  bug_tracker_uri: https://github.com/danielstpaul/silas/issues
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: