silas 0.5.0 → 0.6.1

data/docs/tutorial.md

@@ -0,0 +1,272 @@
+# Tutorial: build the desk
+
+One running app, eleven short chapters, one new primitive each. You start with
+a working refund-desk agent and finish with a scheduled, Slack-connected,
+memory-having, staff-employing one — with evals gating every change and every
+consequential action holding at the signal until a person clears it.
+
+No API key is needed until chapter 3 (and even then it's optional — everything
+except "talk to a real model" works keyless).
+
+## 1 · Open the desk
+
+```bash
+rails new desk -m https://raw.githubusercontent.com/danielstpaul/silas/main/templates/desk.rb
+cd desk && bin/dev
+```
+
+Open <http://localhost:3000> — the **signal board**:
+
+<img src="https://raw.githubusercontent.com/danielstpaul/silas/main/docs/img/silas-board.png" width="740"
+     alt="The desk's signal board: aspect tiles for held/working/clear/in doubt, the keyless demo banner, the agent card, and try-it prompts">
+
+Then *operator inbox →* and start a session:
+
+> The walnut monitor stand (order R-1002) arrived cracked.
+
+Watch the trace: `lookup_order` clears, then `issue_refund` **holds** — an
+amber card at the top of the session, and the turn costs nothing while it
+waits. Approve it. The turn resumes exactly where it stopped, notifies the
+customer, and answers. Now check the till:
+
+```bash
+bin/rails runner 'puts Refund.count'   # => 1
+```
+
+Try the £18 story too (`order R-1001`) — under the gate, it never holds.
+
+What you just saw is the whole thesis: a **turn** (one request to its answer)
+made of **steps** (model calls) whose tool effects go through a **ledger**;
+anything gated **parks at zero compute** until a human verdict; and a crash
+anywhere in that story resumes from the last completed step. Kill `bin/dev`
+mid-run and restart it if you want to test that claim right now.
+
+## 2 · Read the agent (it's a directory)
+
+```
+app/agent/
+  instructions.md      # the persona — plain markdown, ERB allowed
+  agent.yml            # model + per-turn limits; data only
+  tools/
+    lookup_order.rb    # idempotent!      — read-only, replays freely
+    issue_refund.rb    # transactional!   — DB effect: exactly-once, gated over £25
+    notify_customer.rb # at_most_once!    — external effect: parks IN DOUBT on a crash
+  skills/ schedules/ channels/
+```
+
+Open the three tools. Each declares an **effect mode**, and the mode is the
+entire durability decision:
+
+| The tool… | Declare | Because |
+|---|---|---|
+| writes this app's database | `transactional!` | effect + ledger commit atomically → **exactly-once** |
+| calls anything external | `at_most_once!` (default) | an ambiguous crash **parks for a human**, never re-fires blind |
+| only reads | `idempotent!` | replays may re-run it freely |
+
+Never mark an external call `transactional!` — the ledger cannot roll back a
+sent email. And note `issue_refund`'s approval lambda: policy lives **on the
+tool**, next to the code it gates.
+
+## 3 · Change it: your first tool
+
+The desk can't answer "what did Ada buy this year?" Give it history. Create
+`app/agent/tools/order_history.rb`:
+
+```ruby
+class Agent::Tools::OrderHistory < Silas::Tool
+  description "List a customer's orders by email, newest first."
+  idempotent!
+
+  def call(email:)
+    orders = Order.where(email: email.to_s.strip.downcase).order(created_at: :desc)
+    return { error: "no orders for #{email}" } if orders.none?
+
+    { orders: orders.map { |o| { number: o.number, item: o.item,
+                                 amount_pence: o.amount_pence, status: o.status } } }
+  end
+end
+```
+
+The keyword signature of `#call` **is** the schema the model sees; the
+filename is the tool's name. Restart `bin/dev` (files register at boot), then:
+
+```bash
+bin/rails silas:doctor    # "tools — 4 tool(s) validate"
+bin/rails silas:chat      # you> what has ada@example.com ordered?
+```
+
+(Keyless, the scripted stand-in won't improvise about your new tool — export
+`ANTHROPIC_API_KEY` and restart to watch a real model use it. Everything else
+in this tutorial stays keyless-friendly.)
+
+## 4 · Prove it: evals as the deploy gate
+
+Open `test/agent_evals/refund_desk_eval.rb` — three scenarios already assert
+the desk's contract, including *the refund holds* and *clearing it executes
+exactly once*. Add one for your tool:
+
+```ruby
+Silas::Eval.scenario "order history is grounded in rows" do
+  input "What has ada@example.com ordered?"
+
+  on_step 0, call: { name: "order_history", arguments: { email: "ada@example.com" } }
+  on_step 1, text: "Ada has two orders: the field notebook (£18.00) and the walnut monitor stand (£64.00)."
+
+  expect do
+    assert_tool_called "order_history", times: 1
+    assert_turn_completed
+    assert_no_hallucinated_price   # every £ in the answer must trace to data the agent saw
+  end
+end
+```
+
+```bash
+bin/rails silas:eval      # 4 scenarios, 0 failing
+bin/ci                    # tests + evals — the deploy gate
+```
+
+You script the **model's decisions**; the **real ledger** runs your real
+tools. That's why `assert_parked` and `times: 1` are trustworthy — they read
+durable rows, not mocks. Details: [evals.md](evals.md).
+
+## 5 · Give it a clock: schedules
+
+A schedule is a markdown file whose body becomes the turn input. Create
+`app/agent/schedules/daily_digest.md`:
+
+```markdown
+---
+cron: "0 9 * * *"
+---
+Summarize yesterday's refunds: count, total pence, and anything still held at
+the signal. Keep it to five lines.
+```
+
+```bash
+bin/rails silas:schedules
+```
+
+That **compiles** schedules into `config/recurring.yml` — cron that fires real
+work stays a reviewable git diff, and each tick is a normal durable turn (it
+can hold for approval like any other). Prefer code? Drop a `.rb` subclassing
+`Silas::Schedule::Handler` in the same directory.
+
+## 6 · Give it a doorway: Slack
+
+The installer already scaffolded `app/agent/channels/slack.rb`. Wire
+credentials and it's live:
+
+```bash
+bin/rails credentials:edit    # silas: { slack: { signing_secret: ..., bot_token: ... } }
+```
+
+Point your Slack app's events at `/silas/channels/slack/events` (the mounted
+engine verifies signatures). A new thread starts a session; replies continue
+it; and a held refund renders as **Approve/Decline buttons in Slack** that
+call the exact same `approve!` as the inbox. Any other transport:
+
+```bash
+bin/rails g silas:channel whatsapp
+```
+
+scaffolds the signature-verifying webhook and the outbound half. See
+[channels.md](channels.md).
+
+## 7 · Let it ask: `ask_question`
+
+Approvals are the human saying yes/no. `ask_question` is the reverse — the
+agent needs *information*, not permission. It's built in; instruct it in
+`app/agent/instructions.md`:
+
+```markdown
+- If the customer's request is ambiguous (which order? partial or full?), use
+  ask_question to ask the operator before touching money.
+```
+
+When the model calls it, the turn parks the same way an approval does — zero
+compute, amber card — but the card has a **text box**. Your typed answer
+becomes the tool result and the turn resumes with it. Same TTL, same audit
+trail, same API (`POST .../approvals/:id/answer`).
+
+## 8 · Let it keep notes: memory
+
+Memory is for the fuzzy residue with no natural home in your tables —
+"ada@example.com prefers replacement over refund" — stored as
+`subject · attribute · content` triples with provenance and supersession.
+
+It's already on. Tell the agent when to use it (instructions again):
+
+```markdown
+- When a customer states a durable preference, remember it.
+```
+
+The first time the model calls `remember`, the memory **parks as a card in
+your inbox** — nothing persists until you approve it
+(`config.memory_approval = :always` is the default). Approved memories inject
+into future turns automatically; `recall` digs deeper on demand. Your *domain*
+data stays in your tables, where your tools already read it.
+
+## 9 · Hire staff: named agents and handoffs
+
+One desk, many specialists. A named agent is the same directory shape under
+`app/agents/<name>/`:
+
+```
+app/agents/escalations/
+  instructions.md      # "You handle disputes the desk hands you…"
+  agent.yml
+  tools/               # its own toolset — the desk's tools are NOT inherited
+  schedules/           # its own clock, ticking IT — not the root agent
+```
+
+Restart, and the desk can delegate durably: the built-in `handoff` tool files
+a **self-contained brief** that starts a linked session for the named agent —
+exactly-once-guarded and cycle-checked — instead of two models chatting
+freely (a cost and audit hazard, deliberately unblessed). Talk to a
+specialist directly with `Silas.agent("escalations").start(input: "…")` or
+`bin/rails silas:chat AGENT=escalations`; the inbox filters by agent.
+
+## 10 · Fit the governors: budgets and compaction
+
+Open `app/agent/agent.yml`:
+
+```yaml
+limits:
+  max_steps: 8       # runaway guard — breaching this FAILS the turn
+  max_cost: 0.25     # dollars per turn — breaching PARKS it
+  timeout: 300       # active seconds — held time never counts
+```
+
+A parked budget breach is an amber card with a **raise-budget** control: the
+top-up is recorded per turn, so one exception never loosens the standing
+limits ([budgets.md](budgets.md)). And long conversations don't die at the
+context window: past `config.compact_at` (default 90% of the model's window)
+Silas summarises prior turns — as a **persisted, exactly-once effect**, so a
+crash replay rebuilds byte-identical messages. You configure nothing; it's a
+default.
+
+## 11 · Ship it
+
+```bash
+bin/rails silas:doctor
+```
+
+Work through its checklist for production:
+
+1. A real provider key in the production environment.
+2. Real inbox auth — replace the template's dev-only lambda in
+   `config/initializers/silas.rb` with your `current_user` check.
+3. Keep `silas_dead_job_rescuer` in `config/recurring.yml` — it's part of the
+   crash-recovery contract — and **monitor worker liveness**: the rescuer can
+   requeue work; it cannot conjure a consumer.
+4. `bin/ci` in your pipeline — the evals you wrote are now the gate that stops
+   a deploy from changing the desk's behavior unnoticed.
+5. Deploy with Kamal as usual. The hard-won operational notes (what the chaos
+   harness taught us about dead workers, why you never hand-delete
+   `solid_queue_processes` rows) are in
+   [DEPLOY.md](https://github.com/danielstpaul/silas/blob/main/DEPLOY.md).
+
+Then delete the desk — models, tools, seeds — and build your own agent in the
+hole it leaves. The shape you learned is the whole framework: **a directory of
+plain files, a ledger that makes effects land exactly once, and a signal that
+holds anything consequential until a person clears it.**

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/connection.rb

@@ -51,6 +51,22 @@ module Silas
       raise Error, "connection #{name}: transport #{transport.inspect} unsupported (v1: http)" unless TRANSPORTS.include?(transport)
       raise Error, "connection #{name}: approval #{approval.inspect} invalid" unless APPROVALS.include?(approval)
       raise Error, "connection #{name}: effect #{effect.inspect} invalid" unless EFFECTS.include?(effect)
+      # Never send a credential over plaintext: an auth'd connection must be
+      # https (loopback exempt for local development servers). Boot-time and
+      # loud, like every other connection misconfiguration.
+      if @auth["type"].present? && plaintext_remote?
+        raise Error, "connection #{name}: refusing to send credentials over plaintext http — " \
+                     "use https (localhost/127.0.0.1 are exempt)"
+      end
+    end
+
+    def plaintext_remote?
+      uri = URI(url)
+      # Scheme case-insensitively (HTTP:// is still plaintext); URI#host keeps
+      # brackets on IPv6 literals, so the loopback exemption lists both forms.
+      uri.scheme&.downcase == "http" && !%w[localhost 127.0.0.1 ::1 [::1]].include?(uri.host)
+    rescue URI::InvalidURIError
+      true # an unparseable url with auth configured fails closed
     end
 
     # One remote tool, resolved. Quacks like a resolved Silas::Tool for the

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.1"
 end