silas 0.5.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f722788fa436905b6ea94ee9666ca71013fa6eace683f7d3dc8eec4f257fbe2
-  data.tar.gz: 85d3ae116127d4b91207526d7936440092250854380938a94eba177cd26f3eeb
+  metadata.gz: d6fb5d6a2e04f91a4bc0ac0569a37da43017f6adae7209148878a2cb8ac41a66
+  data.tar.gz: 9d8ed143aac8d96d264a10ed3cf87c8ecee1ed838ba01ca67075a4a9a07e3b09
 SHA512:
-  metadata.gz: 645b843c5dbde892fa0725c1f33302bf39b3b10eef43ff14b0828efeb0420ead72d82e34b9bb3828cf99aa8f880db4f6017f2913023884a679385ca68a21ae41
-  data.tar.gz: 2b5b8df36d8747fde43b1eccffb466f17a3a9ef430ebc77b055b36c73ff987c4e07c66eb14ef2265d34b37b1ff824cf4681737a2bca1333e4e7dad88c8db142b
+  metadata.gz: e01f7110a093b91b30af1c08d4d8167aaaa24861812702c10ba5078f952e7eea4ddb5851e484f6cb2815d171271de9a45d8b7cc275e3d59dcaa2541ad9731628
+  data.tar.gz: c84142c165b45db56d5761a64a62993e7332a2209593ff1c59afd58723beafc5e2bd2c14f1495fbb8963d664a69469f28829dece7d6e973e8a5e123963ca526b

data/CHANGELOG.md

@@ -1,5 +1,150 @@
 # Changelog
 
+## 0.6.1 (2026-07-26)
+
+Two live-inbox fixes found by driving real apps, a security hardening pass,
+and the polished brand kit.
+
+### Changed
+
+- **Polished brand geometry everywhere.** Lamps sit on a shared r4.8 circle
+  (proceed and held aspects now one geometry), the favicon is redrawn
+  natively at 32px with a heavier housing (it reads at 16px now), and the
+  wordmark lockup is cropped to the ink — re-outlined to font-independent
+  paths on the new geometry. The inbox layout's favicon and header mark
+  carry the new coordinates, as do the templates' landing pages.
+- The docs gained real product imagery: an 18-frame park→approve→clear GIF
+  captured from a genuine template-app run, the held approval card, and the
+  signal board — on the site landing, inbox-and-api, and tutorial pages.
+
+### Fixed
+
+- **The turn pill now flips to held live.** Turbo `replace` swaps the target
+  element itself, but the header's and cost line's broadcast-target ids lived
+  on wrapper divs in the parent views — so the FIRST status broadcast
+  destroyed the target and every later one (including the park that reads
+  **held**) silently no-opped until a reload. The partials now carry their own
+  root ids, with regression specs asserting a replace re-emits its target.
+- **The first broadcast of a fresh worker no longer dies on lazy routes.**
+  Rails 8.1's lazy route set only retries a missing url helper when the app
+  routes were *just* loaded; in a worker's first Turbo render the engine's
+  helper module could predate its route draw, killing the job silently
+  (`undefined method 'cancel_inbox_turn_path'`). `silas_engine_path` now
+  forces the draw once on miss.
+
+### Security
+
+- **Connections refuse credentials over plaintext http.** A connection with
+  `auth:` configured and an `http://` URL to a remote host now fails loudly at
+  parse time (localhost exempt; unparseable URLs with auth fail closed).
+  Finding from the pre-release security audit — which otherwise confirmed the
+  posture: fail-closed HMAC webhook verification with constant-time compare
+  and a replay window, expiring signed approval tokens, deny-by-default
+  inbox/API auth enforced at the base controllers, argv-array sandbox exec
+  (no shell interpolation), timing-safe MCP token compare, restricted ERB
+  bindings, no interpolated SQL, Brakeman and bundler-audit clean.
+
+## 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

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.