silas 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9abd9603ae899da9a789ded30f092f11f1881ddc9abd2f0edf2638421f469abb
-  data.tar.gz: 16a684a62b54346ee51d4e7b9f6cb92ec19c2d95e7027667b432044d9a1e7f71
+  metadata.gz: fd68f6d368466b20fbb35f49628f166ac61dd60ace3a8cbd20bbc6e316c1d346
+  data.tar.gz: 94d2a902cd7f364aa33200b1ea1f98446dabee38d9e9f7431df9cd96d1fc7f41
 SHA512:
-  metadata.gz: 9518d703a421ed47d1c59e9cb74cdbd46686b8a783a1f5aea8f90f5911e0e27f5ccc5fc86da22c8ebe870a3d811b7de28e5abfc2ff837ab7dbc47722d13e3dcc
-  data.tar.gz: 954efe8fac65a18a0d936bafda946bcca96e8dda35201d06637d8f6ee5a8ca425ecd50ab322d2f137e7c0d03b2e97321db7d5cedfc5ac7d0a4b016ddf3184b63
+  metadata.gz: c386608b076c2c3dfb23e369c819a7d7b1c4fc6122f0011ea80880a46b158b25549a75388a17de250b200a60e0ada311a73df28b47c67e4007cc9e2ebef8bf3f
+  data.tar.gz: 4216b83c6925605076cb3742286699673e2a18dfd9eab3a3cc6e21479ee64e17de714737e5764acce0f147ca0023ced60ed0864b0836850c771dbab88ea84100

data/CHANGELOG.md

@@ -1,5 +1,216 @@
 # Changelog
 
+## 0.6.0 (2026-07-26)
+
+The brand release: the Signals inbox, the docs surface (site + gem-shipped
+guides + tutorial), the templates family (desk + analyst) with its anti-rot
+CI gate, community files, and the framework-first README.
+
+### Added
+
+- **Docs for the whole surface.** New guides, all shipped in the gem:
+  `tutorial` (build the refund desk outward, one primitive per chapter),
+  `guarantees`, `tools`, `agents`, `memory`, `inbox-and-api`, `sandbox`,
+  `evals`, `budgets`, `cancellation`, `connections`, and a full
+  `configuration` reference. A docs site (Jekyll + just-the-docs, dark-first,
+  Archivo/Space Mono, `early · 0.x` chip) builds from `docs/` in CI and
+  deploys to Pages, with an `llms.txt` for coding agents. Brand assets
+  (`brand/`, hero at `docs/img/`) now live in the repo; the hero image is
+  excluded from the packaged gem.
+- **Rails application templates, as a family** — `templates/desk.rb` and
+  `templates/analyst.rb`, each a single CI-gated `rails new -m` script.
+  `rails new desk -m
+  https://raw.githubusercontent.com/danielstpaul/silas/main/templates/desk.rb`
+  builds a deployable agent app from nothing: a refund desk with one tool per effect
+  mode (`lookup_order` idempotent, `issue_refund` transactional behind a
+  £25 approval gate, `notify_customer` at-most-once), Solid Queue **and** Solid
+  Cable wired in development (the durability contract needs a real worker; live
+  deltas need a cross-process cable), a keyless scripted stand-in so the first
+  `bin/dev` works with zero secrets, three deterministic agent evals asserting
+  the hold and the exactly-once execution, and a Signals-branded signal-board
+  landing page. The template only runs the generators the gem already tests,
+  and the `templates_smoke` workflow regenerates and tests an app from every
+  template on each push — starters that structurally cannot rot. (eve needs
+  template repos because it has no generator story; Rails has application
+  templates.) **The analyst** is the second template: a scheduled reporting
+  agent — `query_metrics` reads, `flag_anomaly` lands rows exactly once,
+  `publish_report` holds at the signal (`approval :always`), a Monday-07:00
+  schedule, and a schema-checked `final_answer` (`Turn#answer_data`). Both
+  templates also wire `ANTHROPIC_API_KEY` into Kamal's secrets so the
+  generated app deploys without a scavenger hunt.
+- **Community files** — `CONTRIBUTING.md` (the deliberate scope no-list, the
+  chaos-gate requirement, how templates are contributed), `SECURITY.md`
+  (private vulnerability reporting; deny-by-default surfaces; contract
+  violations count), and GitHub issue forms.
+- **The gem ships its own docs, and the installer ships a coding-agent skill.**
+  `docs/**` and `DEPLOY.md` are in the packaged gem, so `bundle show silas`
+  gives a coding agent (or an offline human) the real reference — and the
+  README's links stop 404ing for gem-only readers. `rails g silas:install` now
+  also writes `.claude/skills/silas/SKILL.md`: the `app/agent/` conventions,
+  the effect-mode and approval decision rules, and the ledger rules an agent
+  must never violate — so a Claude Code/Codex session building on this app
+  gets the framework's judgment without the human learning it first. Gemspec
+  gains `documentation_uri` and `bug_tracker_uri`.
+
+### Changed
+
+- **The inbox wears the brand** (direction "Signals"). Dark-first — the tokens'
+  base is the night palette and light is the `prefers-color-scheme` override —
+  with a position-light mark, a lowercase wordmark, and one white "lamp" accent
+  that never means state. The seven run states each get their aspect:
+  `in_doubt` its own violet (it is neither waiting-by-design nor failed),
+  `canceled` a dashed quiet (a lamp going out, not turning red), and two
+  UI-only relabels — `waiting` reads **held**, `completed` reads **clear**. The
+  database strings and the JSON API are untouched (`docs/conventions.md`).
+- **Approvals and questions are hoisted to the top of the session** — the
+  operator never scrolls a long trace hunting for the card; the trace keeps a
+  one-line "held at the signal" stub in place. Live parks append their card via
+  the same Turbo broadcasts; settled cards remove themselves. Tool arguments
+  render as key/value rows and results collapse behind a disclosure; the
+  session index groups its rail by who's blocked: **Held / Working / Filed**.
+- The playground's chat page consumes the engine's colour tokens instead of
+  re-hardcoding a palette, and hosts the hoisted approval/question cards above
+  its transcript.
+
+- **README reframed, framework-first** — it now mirrors eve's shape exactly:
+  the mark as the logo (dark/light `<picture>`), badges, a one-paragraph
+  thesis, "The filesystem is the authoring interface" with the tree, quick
+  start, one minimal example, status/community/license. The hero illustration
+  moved to the repo's social-preview role (its inbox panel is a designed
+  idealization, not a screenshot — it shouldn't sit where users compare it to
+  the real `/silas/inbox`). The docs site nav is grouped eve-style — Tutorial
+  and Guarantees up top, then **Core / Advanced / Reference / About**
+  sections — via build-time frontmatter injection (`site/assemble.rb`, which
+  fails the build if a docs page lacks a nav entry), keeping the gem-shipped
+  markdown frontmatter-free. `docs/vs-eve.md` was **factually rewritten**
+  (2026-07-26): the previous revision described eve as a managed-cloud
+  platform; eve is fully self-hostable, and the comparison now rests on what's
+  actually different — exactly-once vs documented at-least-once, a shipped
+  production inbox vs a dev TUI, memory vs none, and the transaction-boundary
+  argument, date-stamped against eve 0.27.6 and framed as siblings (pick by
+  stack). `docs/why-silas.md` rewritten in the same voice — you build the same
+  things with Silas you'd build with any modern agent framework; the
+  guarantees are where it goes further — and DEPLOY.md dropped its stale "eve
+  without the bill" subtitle.
+
+### Fixed
+
+- The generated `config/initializers/ruby_llm.rb` no longer guards its whole
+  configure block behind `ANTHROPIC_API_KEY` — keyless boots skipped the
+  `use_new_acts_as` opt-in, so every demo-mode boot printed RubyLLM's legacy
+  acts_as deprecation warning. A nil key assignment is inert; the block now
+  always runs.
+
+## 0.5.0 (2026-07-26)
+
+Two new loop primitives (replay-safe compaction, ask_question), a whole-channel
+generator, the adapter rebound onto RubyLLM's public single-turn seam, and
+per-agent schedules. Chaos-gated: **295 kill/deploy cycles across both stores —
+zero duplicate side effects, byte-identical replay** — including a new compact
+mode that kills mid-summarisation and asserts the compaction claim is
+exactly-once and the rebuilt provider messages are byte-identical
+(`chaos_host/RESULTS.md`).
+
+### Added
+
+- **Per-agent schedules.** Named agents own their cron the way they own tools
+  and skills: `app/agents/analyst/schedules/monday_kpis.md` is discovered as
+  `agents/analyst/monday_kpis`, compiled by `silas:schedules` under a
+  collision-free recurring key, and its ticks start **the analyst** — a staff
+  member's schedule never wakes the root agent. `.rb` handlers resolve under
+  the agent's namespace (`Agents::Analyst::Schedules::MondayKpis`).
+
+- **`ask_question` — the agent can park to ask a human something.**
+  Information, not permission: the model calls the new builtin with a
+  question, the turn parks at zero compute through the same machinery as
+  approvals (TTL, channel ping, resume gate), and the operator's free-text
+  reply becomes the tool result the model resumes with
+  (`{"answer" => "..."}`). Answer from the inbox (a question card with a text
+  box replaces approve/decline) or the API
+  (`POST /silas/api/v1/approvals/:id/answer {text:}`); `decline!` remains the
+  refusal path, and an unanswered question expires as
+  `{"answer" => nil, "note" => "question expired unanswered"}`. Channels are
+  pinged only if they implement `deliver_question` — buttons are the wrong UI
+  for free text, so transports without it simply leave the question in the
+  inbox. Disable with `config.ask_question = false`.
+
+  **Upgrade note:** adding a builtin changes the definitions digest, so turns
+  parked across the upgrade fail loudly on resume (the nondeterminism guard
+  working as designed). Settle parked turns before upgrading, or set
+  `config.ask_question = false` to keep the old digest.
+
+- **Context compaction that survives replay.** Long sessions used to grow
+  until the provider rejected the prompt and the turn failed. Now, when the
+  measured context passes `config.compact_at` (default 0.9 of the model's
+  registry context window; set an Integer for an absolute token threshold, or
+  nil to disable), Silas summarises all prior turns into a `silas_compactions`
+  row and the conversation continues — the current turn is never compacted.
+
+  The design constraint is the durability contract: replayed executions must
+  see byte-identical message arrays, so a summary can never be computed at
+  build time. Compaction is an *effect*, made exactly-once the way tool
+  effects are — claimed compare-and-swap (unique index per session + span),
+  generated once, then read deterministically from the row forever. A crash
+  mid-summary leaves a pending row the resume finishes; a crash mid-step
+  replays against the identical compacted history. New `compact.silas`
+  instrumentation event (duration = the summarisation call). Chaos-gated with
+  a dedicated mode: kill -9 during the compacting turn, including
+  mid-summarisation.
+
+### Changed
+
+- **The `:ruby_llm` adapter no longer fights the library.** `Chat#complete`
+  runs RubyLLM's whole agentic loop — model, execute tools, feed results back,
+  model again — but Silas needs a single move, because the step boundary *is*
+  the durability boundary. It used to get one by registering tool proxies that
+  threw `RubyLLM::Tool::Halt` to abort the loop from the inside.
+
+  Chat is now used as the builder it is (it owns model resolution, schema
+  normalisation, system instructions and message construction) and execution
+  drops one layer to `RubyLLM::Provider#complete` — the same call Chat makes
+  internally for a single turn. Entirely public API, and the adapter got
+  smaller: no `Tool::Halt`, no hunting back through `chat.messages` for the
+  assistant reply, and the `before_message` streaming-timing oddity is gone in
+  favour of an event Silas emits itself.
+
+  **This removes Silas's exposure to the largest RubyLLM 2.0 breaking change.**
+  2.0 deletes `Tool::Halt` precisely because the loop became caller-controlled;
+  Silas no longer needs it either way. The adapter also now calls `with_tools`
+  (2.0 drops the singular `with_tool`) and its schema proxy answers to both
+  `params_schema` and `parameters_schema` (2.0 renames it), so the tool path is
+  version-agnostic today. No behaviour change for users.
+
+### Added
+
+- **`rails g silas:channel <name>`** — scaffolds a whole channel, not half of
+  one. Channels were reachable before (`Channel.dispatch` is a ~50-line seam)
+  but the engine ships webhook routes for Slack only, so any other transport
+  meant hand-rolling a controller, a route, and signature verification with no
+  documented contract. The generator writes the outbound `Channel` subclass,
+  a signature-verifying inbound controller, and the route that joins them —
+  with the security decisions already made: verify before anything else, sign
+  over the raw body, fail closed on a missing secret, and send approvals to an
+  operator rather than to whoever started the session.
+- **`Silas::Webhook.verify_hmac`** — the parts of webhook verification that are
+  identical for every vendor (constant-time comparison, replay window,
+  fail-closed on a missing secret), with the vendor's shape (`payload`,
+  `prefix`, `digest`) supplied by the caller. `Silas::Slack.verify_signature`
+  now delegates to it and keeps its exact v0 scheme.
+- **`Silas::Channel.approval_url(invocation, action)`** — a signed, expiring
+  one-click approve/decline link for *any* transport, built from the engine's
+  route set and the discovered mount point, so it works from a delivery job
+  with no routing scope. Raises with the fix when no host is configured rather
+  than minting a dead link.
+- `docs/channels.md`: the inbound/outbound contract, a per-vendor signature
+  table, and a worked WhatsApp Cloud API example.
+
+### Removed
+
+- `demo/refund-desk` and `demo/churn-desk`. Both were copy-paste kits whose
+  READMEs instructed deleting a file the generated eval still asserted on —
+  broken on arrival. `examples/playground` is the example; `docs/why-silas.md`
+  and `docs/vs-eve.md` now point at it.
+
 ## 0.4.0
 
 The architecture-and-hardening release: one shipped feature that had never

data/DEPLOY.md

@@ -0,0 +1,111 @@
+# Deploying Silas
+
+A Silas app is an ordinary Rails app, so it deploys the way your Rails apps
+already deploy — a single cheap VPS with Kamal works fine; there is no second
+runtime or control plane to stand up. The one thing you MUST get right: the
+**Solid Queue worker has to run**, because the durability contract (a turn
+surviving a crash / deploy) depends on it. A web-only deploy will accept turns
+and never run them.
+
+> Status: this is the reference configuration. It is correct by construction
+> (worker wired, rescuer active, secrets injected) but has not yet been run
+> against a live VPS end-to-end — that's the final launch step.
+
+## 1. The worker must run
+
+> **Queue adapter: use Solid Queue.** Silas's durability and exactly-once
+> guarantees require a durable, serializing, DB-backed adapter. **Do not run on
+> the in-process `:async` adapter** (Rails' development default) — it runs
+> continuation retries on a thread pool concurrently with the original job,
+> which double-executes steps and breaks exactly-once. Silas warns at boot if it
+> detects the Async adapter. For scripts and single-process demos, the
+> synchronous `:inline` adapter is safe (but has no durability).
+
+`rails g silas:install` already appends the durability rescuer to
+`config/recurring.yml`:
+
+```yaml
+production:
+  silas_dead_job_rescuer:      # retries jobs failed by dead-worker reaping/pruning
+    class: Silas::DeadJobRescuerJob
+    schedule: every 30 seconds
+```
+
+Pick one way to run Solid Queue:
+
+- **Simple (one container):** run the worker inside Puma —
+  set `SOLID_QUEUE_IN_PUMA=true` (Rails 8 default plugin). Fine for a demo box.
+- **Recommended (durable):** a dedicated `bin/jobs` process, so a `kill -9` of the
+  worker is isolated from the web tier and recovery is observable.
+
+## 2. Kamal config (`config/deploy.yml`)
+
+A standard `rails new` ships a Dockerfile and `config/deploy.yml`. Add a **job
+role** so the worker is its own container:
+
+```yaml
+service: my-agent
+image: you/my-agent
+servers:
+  web:
+    - 1.2.3.4          # your £5/month VPS
+  job:
+    hosts:
+      - 1.2.3.4
+    cmd: bin/jobs      # the Solid Queue worker (+ dispatcher + scheduler)
+
+registry:
+  username: you
+  password:
+    - KAMAL_REGISTRY_PASSWORD
+
+env:
+  secret:
+    - RAILS_MASTER_KEY
+    - ANTHROPIC_API_KEY        # the :ruby_llm engine authenticates with this
+  clear:
+    SOLID_QUEUE_IN_PUMA: false # the job role runs the worker instead
+
+# Persist SQLite + Solid Queue on a volume if you're using SQLite (or point at Postgres).
+volumes:
+  - "my_agent_storage:/rails/storage"
+```
+
+Secrets (Slack signing secret / bot token, model keys) go in `.kamal/secrets`
+(pulled from your env or a vault), never in the image.
+
+## 3. Deploy
+
+```sh
+kamal setup     # first time
+kamal deploy    # subsequent
+```
+
+Mid-deploy safety is built in: a turn interrupted by the SIGTERM of a rolling
+deploy re-enqueues and resumes (chaos-gated). Recovery latency after a hard
+crash ≈ `SolidQueue.process_alive_threshold` + the rescuer's 30s cadence.
+
+## 3½. Template apps deploy stock
+
+An app generated from `templates/*.rb` needs no deploy surgery: Rails 8.1's
+generated `config/deploy.yml` already runs Solid Queue inside Puma for the
+single-server SQLite shape (`SOLID_QUEUE_IN_PUMA: true` — that satisfies "the
+worker must run"), the template adds `ANTHROPIC_API_KEY` to Kamal's secret
+list and `.kamal/secrets`, and `config/recurring.yml` already carries the
+rescuer. Set the two secrets in your shell, point `deploy.yml` at your server
+and registry, `kamal setup`. Scale beyond one box by moving to the dedicated
+worker role in §1 and a real Postgres in §2.
+
+## 4. Cost
+
+The whole thing runs on one VPS + your model spend. The engine authenticates
+with an API key for whatever provider you configure through RubyLLM. Your data
+and the ledger never leave your own Postgres, and there is no Silas platform
+bill or per-run metering.
+
+## 5. Local development note (macOS + Postgres)
+
+Solid Queue forks workers, and on macOS the pg gem needs
+`PGGSSENCMODE=disable OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES` in the
+environment or forked workers crash inside libpq. SQLite development needs
+nothing.