silas 0.5.0 → 0.6.0

data/docs/vs-eve.md

@@ -0,0 +1,93 @@
+# Silas vs eve
+
+> Written **2026-07-26** against **eve 0.27.6** and Silas 0.5.x, from eve's
+> published docs and source. Both projects move fast — if you're reading this
+> much later, re-verify before deciding.
+
+Silas and eve share the same organising idea: **an agent is a directory of
+conventional files** — instructions, one file per tool, skills, schedules,
+channels, connections — running on a durable loop. You can build the same
+things with either: support desks, scheduled analysts, Slack copilots,
+back-office automations. eve is TypeScript-native, built by Vercel on the AI
+SDK, and fully self-hostable. Silas is Rails-native, a gem inside your
+existing app.
+
+So the honest first cut is simply your stack: **a TypeScript team should use
+eve; a Rails team should use Silas.** The rest of this page is for people near
+the boundary — and for the differences that go deeper than language.
+
+---
+
+## The comparison
+
+| | Silas | eve (0.27.6) |
+|---|---|---|
+| **Shape** | A gem in your Rails app — your database, your job queue, your auth, one deploy. | A TypeScript service beside your app, with its own workflow store and deploy. |
+| **Authoring** | A directory of plain files. | A directory of plain files — genuinely the same idea. |
+| **Durable loop** | Survives `kill -9`, resumes from the last completed step. Chaos-gated every release: zero duplicate effects, byte-identical replay, SQLite + Postgres. | Workflow-engine replay; interrupted steps re-run. |
+| **Tool-effect semantics** | **Exactly-once** for DB-recorded effects (`transactional!` — effect + ledger in one transaction). Default at-most-once: an ambiguous crash **parks for a human**. | **At-least-once, documented as such** — "make non-idempotent side effects like charges or emails idempotent, or gate them with approval." Dedup is the tool author's job. |
+| **Human-in-the-loop** | Parks at zero compute; cleared from inbox, Slack, signed email, or API; parks expire; `ask_question` for the reverse direction. | `needsApproval` on tools. |
+| **Operator surface** | A production inbox mounted in your app: live traces, approval cards, audit trail, cost accounting, web chat. | A dev TUI ("not a production chat UI or customer-facing dashboard"); production UIs are assembled from templates. |
+| **Memory** | Shipped: approval-gated triples with provenance and supersession. | Deliberately out of scope. |
+| **Ecosystem** | Ruby/Rails. | TypeScript + the AI SDK — a much larger ecosystem, with Vercel's distribution behind it. |
+| **Channels & integrations** | Slack + email built in; a generator scaffolds any transport. | More first-party surfaces, growing quickly. |
+| **Maturity** | Early (0.5.x); the durability contract is chaos-verified on every release. | Weeks old publicly; backed by a platform company, shipping at platform speed. |
+
+---
+
+## Where Silas goes further
+
+**The transaction boundary.** When an agent's consequential action is a row in
+your own database — a refund, a balance move, a ledger entry — Silas commits
+the effect and the ledger's dedup record **in the same transaction**. Crash
+before commit: both roll back. Crash after: the step is skipped on resume.
+No idempotency keys, no reconciliation. This isn't about hosting — it's about
+*whose transaction it is*: any runtime outside your application database,
+self-hosted or not, keeps its "this step ran" record in its own store, and two
+stores can't commit atomically. eve's docs draw the same conclusion from the
+other side: make your side effects idempotent, or gate them. Silas is the
+framework where you don't have to.
+
+**Ambiguity parks.** At-least-once means a crash can re-fire a side effect.
+Silas's default is at-most-once with **in-doubt → human**: it never
+double-fires, and an ambiguous call waits for a person.
+
+**The operator surface ships.** `mount Silas::Engine` and the inbox exists —
+held/working/filed rail, live traces, approval cards, audit trail, cost, web
+chat — behind your app's own auth.
+
+**Memory ships.** Approval-gated, with provenance and supersession. eve
+reasonably says "bring your own"; Silas ships the batteries.
+
+## Where eve goes further
+
+- **The ecosystem.** TypeScript and the AI SDK are where most of the agent
+  world lives — more examples, more integrations, a bigger hiring pool, and
+  Vercel's reach.
+- **Surface breadth and velocity.** More first-party channels and
+  integrations today, with a platform company's release cadence.
+- **Sandboxing posture.** Container sandboxes are integral to eve's design.
+  Silas ships an interim Docker seam and reaches microVM-class isolation via
+  the [hermetic](https://github.com/danielstpaul/hermetic) gem.
+
+---
+
+## Choosing
+
+**Pick Silas** if you're on Rails — your agent's tools are ordinary Ruby
+against your own models, the inbox lives behind your auth, and effects your
+app records in its own database get exactly-once semantics no external
+runtime can match. Especially if your agents move money.
+
+**Pick eve** if you're in TypeScript — it's an excellent framework with the
+same authoring model, the ecosystem's momentum, and Vercel behind it.
+
+Near the boundary (a Rails shop with a TS front-of-house, say): decide by
+where your consequential side effects live. If they're rows in the Rails
+app's database, that's where the agent belongs.
+
+---
+
+*Claims about eve come from its docs and source at 0.27.6, quoted or
+paraphrased in good faith; corrections welcome. Silas's numbers are
+reproducible from `chaos_host/results/`.*

data/docs/why-silas.md

@@ -0,0 +1,87 @@
+# Why Silas
+
+## Build agents the way you build Rails apps
+
+Silas is for the same things every modern agent framework is for: a support
+desk that actually resolves tickets, an analyst that posts the Monday digest,
+an ops copilot in Slack, a back-office agent that chases invoices. An agent is
+a directory of plain files — a persona, a data-only config, one file per tool
+— and the framework supplies the durable loop, the scheduling, the channels,
+the memory, and the operator surface. If you've looked at eve, the authoring
+model will feel immediately familiar; that shape is the category's best idea,
+and Silas embraces it.
+
+What's different is *where it runs*. Silas isn't a second runtime you stand
+beside your app — it's a gem inside the Rails app you already deploy:
+
+- **Your tools are your app.** `Order.find_by!`, `refunds.create!`, your
+  service objects, your validations — no RPC layer between the agent and the
+  domain, because the agent lives where the domain lives.
+- **Your auth is the agent's auth.** The operator inbox mounts as an engine
+  and hides behind whatever `current_user` already means. No second dashboard,
+  no second login, no second audit domain.
+- **Your deploy is the agent's deploy.** One repo, one CI, one Kamal push.
+  The durable substrate — a database, Solid Queue, Active Job Continuations —
+  is already booted.
+
+## The guarantees go further
+
+Every serious framework makes the loop durable. Silas draws the line a step
+past that, and verifies it with a chaos harness that `kill -9`s live agents
+hundreds of times per release (zero duplicate effects, byte-identical replay
+— [guarantees](guarantees.md)):
+
+- **Exactly-once tool effects.** A `transactional!` tool's database write and
+  the ledger's record of it commit in **one transaction**. A crash mid-refund
+  leaves exactly one refund row — never two, never zero — with no idempotency
+  key required. Only a framework *inside* your app can offer this: an external
+  runtime's ledger can never join your database transaction.
+- **Ambiguity waits for a person.** The default mode is at-most-once: a crash
+  that makes "did it send?" unanswerable parks the call **in doubt** for a
+  human verdict instead of re-firing blind. Never double-pay; sometimes ask.
+- **Holds cost nothing.** An approval, a question, or a budget breach parks
+  the turn at zero compute — the job exits, and clearing it resumes from
+  durable rows without re-calling the model.
+
+If your agents only ever read, any durable loop will do. The moment one
+touches money, inventory, or anything you'd hate to see happen twice, this is
+the difference you'll feel.
+
+## Batteries included
+
+A production operator inbox (live traces, approval cards, audit trail, cost
+accounting), approval-gated memory with provenance, deterministic evals as a
+deploy gate, Slack and email channels plus a generator for any transport, a
+JSON API with SSE, per-turn budgets, replay-safe compaction — shipped in the
+gem, not assembled from templates. And one command builds a working agent app
+from nothing:
+
+```bash
+rails new desk -m https://raw.githubusercontent.com/danielstpaul/silas/main/templates/desk.rb
+```
+
+## The honest notes
+
+- **Silas is early** — 0.5.x, and the guarantees are proven by a reproducible
+  chaos harness rather than years of production traffic. The contract is
+  measured on every release, and it's stated precisely so you know exactly
+  what's promised.
+- **Rails-only, on purpose.** If your team lives in TypeScript, eve is
+  excellent and closer to home — the [comparison](vs-eve.md) is honest about
+  that in both directions.
+- **Exactly-once applies to effects in your database.** A raw external call
+  with no idempotency key of its own gets at-most-once + in-doubt parking —
+  strong, but not transactional. Model money as rows (your app probably
+  already does) and you get the full guarantee.
+- **Inference goes to your configured provider.** Agent state stays in your
+  database; prompts still travel to the model you choose.
+- **Untrusted code needs a real sandbox.** The built-in Docker seam is
+  interim; configure [hermetic](https://github.com/danielstpaul/hermetic) for
+  microVM-class isolation before running code you didn't write.
+
+## Try the claim
+
+Run the template, ask for the £64 refund, clear it from the inbox — and while
+the turn is resuming, `kill -9` the worker. Restart it. The turn completes
+from its last checkpoint, and `Refund.count` is exactly 1. That's the pitch,
+reproduced on your laptop in five minutes.

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

@@ -34,6 +34,15 @@ module Silas
         template "channel_email.rb", "app/agent/channels/email.rb"
       end
 
+      # A Claude Code / coding-agent skill: the app/agent/ conventions, the
+      # effect-mode and approval decision rules, and the ledger rules an agent
+      # must never violate — so a coding agent driving this app builds Silas
+      # agents correctly without the human learning the framework first.
+      # Delete the file if you don't use coding agents.
+      def create_claude_skill
+        template "claude_skill.md", ".claude/skills/silas/SKILL.md"
+      end
+
       def mount_engine
         route 'mount Silas::Engine => "/silas"'
       end

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

@@ -0,0 +1,136 @@
+---
+name: silas
+description: Build and modify AI agents in this Rails app with the Silas gem — tools, approvals, effect modes, schedules, channels, evals. Use whenever a task touches app/agent/, app/agents/, a Silas tool, an agent's instructions or limits, or agent durability/approval behaviour.
+---
+
+# Building Silas agents
+
+Silas runs durable AI agents inside this Rails app: every turn survives
+`kill -9` and resumes from its last completed step, tool effects are
+exactly-once, and risky calls park for a human at zero compute. The agent is
+the `app/agent/` directory — you build agents by writing ordinary Ruby files
+there, not by calling a framework API.
+
+**Deep reference lives in the installed gem** — read it from the bundle when
+you need more than this file:
+
+```sh
+bundle show silas   # then read README.md, docs/*.md, DEPLOY.md there
+```
+
+## The directory is the agent
+
+```
+app/agent/
+  instructions.md   # persona (ERB; snapshotted once per turn)
+  agent.yml         # model + limits — data only, no code
+  tools/            # one file per tool; TOOL IDENTITY IS THE FILENAME
+  skills/           # markdown playbooks, loaded on demand (description: frontmatter)
+  schedules/        # cron.md (frontmatter) or .rb handlers -> silas:schedules compiles them
+  channels/         # transports (slack.rb, email.rb; generate more, see below)
+app/agents/<name>/  # NAMED agents: same tree per agent, own tools/skills/schedules
+```
+
+Files register at boot — restart the server after adding one.
+
+## Writing a tool (the part to get right)
+
+```ruby
+# app/agent/tools/issue_refund.rb  ->  tool "issue_refund"
+class Agent::Tools::IssueRefund < Silas::Tool
+  description "Refund part or all of an order."
+  param :amount_pence, :integer, desc: "Amount in pence"
+  approval ->(session:, input:) { input[:amount_pence] > 2000 ? :user_approval : :approved }
+  transactional!
+
+  def call(order_id:, amount_pence:, reason:)
+    Refund.create!(order_id:, amount_pence:, reason:)
+  end
+end
+```
+
+- **The keyword signature of `#call` IS the schema** the model sees. Keywords
+  only — never positional. `param` refines types/descriptions.
+- **Return a Hash** (anything else is wrapped as `{"value" => ...}`). Raising
+  records a failed invocation the model sees — don't rescue-and-swallow.
+- `session` is available inside `call` (the `Silas::Session` row).
+
+### Effect mode — decide by where the side effect lives
+
+| The tool… | Declare | Why |
+|---|---|---|
+| writes this app's database | `transactional!` | effect + ledger row commit atomically: **exactly-once**, even through `kill -9` |
+| calls an external API / sends anything | `at_most_once!` (the default) | a crash mid-call leaves it IN DOUBT → parks for a human verdict, never re-fires blind |
+| only reads, safe to repeat | `idempotent!` | replays re-run it freely |
+
+Never mark an external call `transactional!` — the ledger cannot roll back a
+sent email. Model money as rows in this app's own DB whenever possible; that
+is what upgrades the guarantee to exactly-once.
+
+### Approval — who holds the lever
+
+`approval :never` (default) · `:always` · `:once` (one approval per identical
+(tool, arguments) pair per session) · or a lambda returning `:user_approval`,
+`:approved`, `:not_applicable`, or `{denied: "reason"}`. Approval parks the
+turn at zero compute; a human settles it in the inbox (`/silas/inbox`), Slack,
+email, or the JSON API. Gate anything that moves money or is hard to reverse.
+
+The built-in `ask_question` tool is the reverse direction: the agent parks to
+ask the operator something and resumes with their text as the tool result.
+
+## agent.yml
+
+```yaml
+model: claude-sonnet-4-5   # must exist in ruby_llm's registry
+description: One line, shown in rosters.
+limits:
+  max_steps: 10     # model calls per turn
+  max_cost: 0.25    # dollars per turn
+  timeout: 300      # seconds of ACTIVE work — approval waits don't count
+final_answer:       # optional JSON schema -> Turn#answer_data
+  type: object
+  properties: { verdict: { type: string } }
+```
+
+Budget breaches PARK the turn (a human can top up in the inbox); they don't
+destroy work.
+
+## Rules that protect the durability contract
+
+1. **Solid Queue (or `:inline` for scripts) — never the Async adapter.** Async
+   double-executes continuation steps and silently voids exactly-once. Boot
+   raises in production if misconfigured.
+2. **Don't deploy tool/skill changes while turns are parked.** The definitions
+   digest fails a parked turn loudly on resume rather than running it against
+   a different agent (`NondeterminismError`). Settle parked turns first —
+   the same applies to toggling built-ins like `config.ask_question`.
+3. **Keep `Silas::DeadJobRescuerJob` in `config/recurring.yml`** — it is part
+   of the crash-recovery contract, and monitor worker liveness: the rescuer
+   can requeue work, it cannot conjure a consumer.
+4. **Never hand-delete `solid_queue_processes` rows** — a claimed job whose
+   process row is gone is invisible to every reaper.
+5. Tools must not spawn threads or run work outside `call` — everything the
+   ledger can't see is outside the guarantee.
+
+## Verify your work
+
+```sh
+bin/rails silas:doctor      # key, queue adapter, model, migrations, tools, rescuer
+bin/rails silas:chat        # talk to the agent from the terminal
+bin/rails silas:eval        # run test/agent_evals/*_eval.rb (deploy gate)
+```
+
+Write an eval per behaviour you care about (`Silas::Eval.scenario` — see the
+generated `test/agent_evals/example_eval.rb`). The inbox at `/silas/inbox` is
+deny-by-default: wire `config.inbox_auth` in `config/initializers/silas.rb`
+before expecting to see it.
+
+## More surface, same pattern
+
+- **Another transport**: `bin/rails g silas:channel whatsapp` scaffolds the
+  signature-verifying webhook AND the outbound half (docs/channels.md in the gem).
+- **A staff of agents**: `app/agents/<name>/` with its own tree;
+  `Silas.agent("name").start(input: ...)`; schedules in that directory tick
+  that agent.
+- **Subagents / handoffs / memory / connections (MCP)**: see the gem README —
+  each is a directory or YAML file, never an orchestration graph.

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

@@ -11,9 +11,12 @@ RubyLLM.configure do |c|
   # hasn't migrated yet — see https://rubyllm.com/upgrading-to-1-7/
   c.use_new_acts_as = true if c.respond_to?(:use_new_acts_as=)
 
+  # A nil key is inert (Silas's boot check reports "no provider configured"),
+  # so this needs no ENV guard — and the acts_as opt-in above must run even
+  # on keyless boots, or the deprecation warning returns.
   c.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
   # The per-request timeout (seconds; RubyLLM default 300). Under streaming
   # this is an idle-between-chunks timeout — the hang protection for a stuck
   # provider connection.
   # c.request_timeout = 120
-end if ENV["ANTHROPIC_API_KEY"].present?
+end

data/lib/silas/eval/dsl.rb

@@ -19,13 +19,18 @@ module Silas
       def max_steps(n) = (@max_steps = n)
       def approve(tool:) = (@approvals << tool.to_s)
 
-      # on_step(0, text:, call: {name:, arguments:}, calls: [ {…}, … ])
-      def on_step(index, text: nil, call: nil, calls: [])
+      # on_step(0, text:, call: {name:, arguments:}, calls: [ {…}, … ], data: {…})
+      # `data:` scripts a STRUCTURED answer (the final_answer schema case) —
+      # it becomes the same {"type"=>"structured"} block the real adapter
+      # persists, so assert_answer_data reads it back through Turn#answer_data.
+      # Keys are stringified exactly as a JSON-parsed model response would be.
+      def on_step(index, text: nil, call: nil, calls: [], data: nil)
         tcs = (calls + [ call ].compact).each_with_index.map do |c, n|
           Silas::Adapters::ToolCall.new(id: "eval_s#{index}_#{n}", name: c[:name].to_s,
                                        arguments: (c[:arguments] || {}).stringify_keys)
         end
         blocks = []
+        blocks << { "type" => "structured", "data" => data.deep_stringify_keys } if data
         blocks << { "type" => "text", "text" => text } if text
         @steps[index] = { blocks: blocks, tool_calls: tcs }
       end

data/lib/silas/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: silas
 version: !ruby/object:Gem::Version
-  version: 0.5.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
@@ -147,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
@@ -164,6 +166,22 @@ files:
 - 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
@@ -172,6 +190,7 @@ files:
 - 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
@@ -248,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: