silas 0.1.7 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad5ce26e72a73ea83df134c187f8c8dedcfcc35a65f20493f3095abfbfaa7ed8
-  data.tar.gz: ab1989850b2b8c881da660824dcad3f71159cfffcd8648901ec2a06385d8c294
+  metadata.gz: 187a0730a1a84463f6207060d446c6960946513c0884d708fc0d16c011493a26
+  data.tar.gz: ed9a09b617c7dde80deaf6fe2c460e254cc96487b43eac52f56c6aa7dedecbaa
 SHA512:
-  metadata.gz: fb5da2cdb854533bf68a761582063e8c5b22c2e40fc02cab05240d4ea199554da317bb0509398c81923a312c7b43773834d354ffb6391be549a6254329e3b995
-  data.tar.gz: 57e53d9a3c5b438b941cd599ba805c2c210e303d6362599d757b58b907ea10b9401cbf918cd909d1c53590d8fee4cc9e0fef8a8fb5ccb422c26db5e0abaaf43a
+  metadata.gz: a38278a7020a9282b1ff9aaac7b18da60bd017a001bcc421c6e316d0033b1a4b468cd86c0d4bcdcd869940f7d9c4b953318e84dd626087bef4fee1ee8ea8b87c
+  data.tar.gz: 6f42e1a81bf935ebdbb39c678e46662ab85b9f45bd8293c0e83f4467e7db922e2102087ab62ea7eb8e8b1b3b1d323eba1a5772e997028b3e5838882bda9cfeb3

data/CHANGELOG.md

@@ -1,5 +1,158 @@
 # Changelog
 
+## 0.3.0
+
+- **`bin/rails silas:doctor`** — every known first-run failure mode as one
+  command: provider key, queue adapter (async = red), model resolution with
+  prices, migrations, tool validation, the rescuer recurring entry, the cable
+  adapter for live streaming (async cable can't carry worker deltas), and
+  whether the deny-by-default inbox/API auth has been wired. Exits non-zero
+  on failures, so it slots into CI.
+- **Hard-removed the 0.2 `:agent_sdk` config shims** — `config.auth` and
+  `config.agent_sdk_*` now raise `NoMethodError` (they were warning no-ops
+  for the 0.2 cycle). `config.engine = :agent_sdk` still raises the
+  explanatory `BootGuardError`. Workflows now use `actions/checkout@v5`
+  (Node 20 deprecation).
+- **Inbox at scale + the promised top-up card.** Budget-parked turns now
+  render a **"Budget reached — raise & resume"** card (the UI the 0.1.5
+  changelog promised): one field, one click, `raise_budget!`, completed work
+  replays from rows. The session list pages by keyset (`?before=<id>`, 50 per
+  page — the old hard `limit(100)` made session 101 unreachable forever), and
+  the index renders in **2 queries** instead of ~4 per card.
+- **Cost accounting prices itself from RubyLLM's model registry** (1,100+
+  models, refreshed upstream from models.dev) instead of a five-entry
+  hand-maintained map. Steps stamp the **provider** RubyLLM resolves at
+  persist time, and lookups use the two-arg `find(model, provider)` — 85/1081
+  registry ids exist under multiple providers at different prices, so the
+  bare lookup could silently price the wrong one. `config.model_prices` is
+  now an **override map** (default `{}`) for fine-tunes, custom deployments,
+  and models newer than the installed registry; unknown models stay
+  `unpriced`, never a lying $0.00. Dropped the write-only
+  `silas_turns.cost_microcents` column (declared since 0.1.0, never
+  populated). Default model is now `claude-sonnet-4-5` — in every supported
+  registry, unlike `claude-sonnet-5` (absent from ruby_llm 1.16's shipped
+  registry, which would have broken first runs), and never the priciest
+  model. New migration: `bin/rails silas:install:migrations db:migrate`.
+- **Structured final answers.** Declare a JSON schema under `final_answer:` in
+  agent.yml and the turn's answer comes back as a parsed Hash —
+  `Turn#answer_data` (alongside `answer_text` for prose agents), in the API
+  (`answer_data` on turns, `structured` on steps), the inbox trace, the REPL,
+  and a new `assert_answer_data` eval assertion. Implemented on RubyLLM's
+  `with_schema` (each provider's native structured-output dialect). The schema
+  is model-visible state: it folds into the definitions digest **only when
+  present** — schema-less agents keep a byte-identical digest, so turns parked
+  across the upgrade never trip `NondeterminismError` (pinned by spec); a
+  mid-turn schema change fails loudly by design. Structured answers replay
+  into later turns' history as their JSON text (deterministic).
+
+- **A public HTTP + SSE session API** at `/silas/api/v1` — sessions
+  (create/show, `?trace=1` for the full transcript), turns (create — **409**
+  while one is active — and cancel), and approvals (list / approve / decline,
+  the exact same `approve!`/`decline!` as every other surface, stamped with
+  `config.api_actor`). Deny-by-default via `config.api_auth`, the inbox's
+  contract. `GET .../sessions/:id/stream` is server-sent events at row
+  granularity (turn / completed-step / invocation changes) with
+  `Last-Event-ID` resume — at-least-once, epoch-ms watermark ids, `?poll=1`
+  for a curl-friendly backlog-and-close, self-closing after
+  `api_stream_max_duration` with a `timeout` reconnect event. The AR
+  connection is released between polls; per-token streaming remains the
+  Turbo/browser feature (deltas live in the worker process; the gem takes no
+  cross-process bus dependency). `Session` gains `parent_session` /
+  `child_sessions` associations, and session JSON carries the lineage.
+
+## 0.2.0
+
+- **Token streaming, end to end.** The engine seam's `&on_event` block — dead
+  code since 0.1.0 — is live: the `:ruby_llm` engine streams the model
+  response (`chat.complete` with a block; the assembled message is identical
+  to the sync path, so durability semantics are untouched), `StepRunner`
+  coalesces text deltas into ~10Hz `"silas.delta"` notifications
+  (`Silas::DeltaBuffer`) carrying the accumulated text, and two subscribers
+  render them: the inbox trace (synchronous Turbo `broadcast_update_to` into a
+  stable per-step target — crash-restream overwrites, never duplicates) and
+  the `silas:chat` REPL (tokens print as they arrive). Deltas are decoration
+  over the authoritative rows: never persisted, never fed to the model, and a
+  replayed step emits none. `around_model_call` hooks keep their existing
+  contract and can no longer swallow the stream.
+- **Onboarding fixes.** The generated `bin/ci` can now actually fail on app
+  tests (it silently swallowed them with `|| true`); the generated initializer
+  shows every option the next-steps mention (`inbox_auth`, `sandbox`,
+  `memory_approval`, `model_prices`, `eval_dir`, `approval_ttl`) and defaults
+  to `claude-sonnet-5` instead of handing a first run the most expensive model
+  with no budget set; the rescuer's `recurring.yml` entry is now **idempotent
+  and environment-aware** (injected under every deployable env block —
+  staging included — never blind-appended into whatever block ends the file,
+  never duplicated on a re-run); a missing provider API key is caught **at
+  boot** with the exact fix (warns in development, raises `BootGuardError` in
+  production); and the unsafe Async-adapter warning **raises in production**,
+  where running agents on it silently voids the durability contract.
+- **Model-call resilience: transient provider errors retry from the
+  checkpoint; nothing ever strands in `running`.** Previously a single
+  429/529/timeout failed the loop job permanently and invisibly — the turn sat
+  in `running` forever with no retry and no signal. Now:
+  `resume_errors_after_advancing = false` on the loop job (Active Job
+  Continuations otherwise swallow errors raised after a checkpoint and
+  self-resume unboundedly, bypassing `retry_on` — verified against activejob
+  8.1); transient classes (`RateLimitError`, `OverloadedError`,
+  `ServiceUnavailableError`, `ServerError`, Faraday timeouts) retry with
+  polynomial backoff + jitter and **resume from the last completed step**;
+  exhaustion and permanent rejections (`UnauthorizedError`,
+  `PaymentRequiredError`, …) expire pending approvals and fail the turn
+  loudly. The rescuer now also sweeps **stranded turns** — a loop job that
+  died with an error outside the retry list fails its turn
+  (`reason: "job_failed"`) instead of leaving it running forever. Stale
+  approval cards can no longer zombie-resume a failed turn (`approve!` /
+  `decline!` refuse; `resume_turn!` guards).
+- **The inbox now shows the audit trail it exists to provide.** Tool
+  `arguments` render for every settled invocation (not just parked ones), a
+  failed tool shows its recorded `error` instead of a bare red pill, and
+  `approved_by` / `decline_reason` render on settled approvals — who held the
+  lever, and why it moved. Active turns gain a **Cancel** button (running
+  turns flag for a step-boundary cancel, parked turns cancel immediately),
+  and the "N awaiting approval" badge is now a link filtering the session
+  list to what needs you (`?pending=1`).
+- **Web chat in the inbox.** The session page gains a composer (`POST
+  .../sessions/:id/turns`) and the index a start-a-session form (with a named
+  agent picker) — the browser is now a first-class conversational surface, not
+  just approve/decline. Writes ride `authenticate_write!` exactly like
+  approvals; a turn-in-progress renders as an inline alert; web-chat sessions
+  stay `channel: nil` ("direct"), so no outbound delivery jobs are enqueued.
+
+- **`approval :once` is now scoped to (tool, arguments), not tool name alone.**
+  Name-only matching was a footgun: approving a £5 refund silently
+  auto-approved a £5,000 refund later in the same session. Identical repeat
+  calls still skip re-approval; different arguments park again. Graded gates
+  belong in an approval lambda.
+- **The ledger's checkpoint guard moved to `IsolatedExecutionState`** (from
+  `Thread.current[]`, which is fiber-local) — it now follows the app's
+  configured isolation level exactly like agent scopes, surviving into
+  internally-created fibers where the old flag silently vanished. Nested
+  ledger transactions now save/restore the guard instead of clearing it (the
+  old `ensure` opened a checkpoint-guard hole for the rest of the outer
+  transaction).
+- **Removed the `:agent_sdk` engine** (the `claude -p` subprocess integration).
+  Its differentiating rationale — running on a Claude subscription plan instead
+  of API credits — was structurally unreachable: `--bare` was hardcoded and the
+  engine raised without `ANTHROPIC_API_KEY` regardless of `config.auth`, so the
+  OAuth path could never execute a turn. What remained was a second engine with
+  weaker guarantees on every axis (exactly-once only *within* a run,
+  `approval :never` tools only, fail-closed on any mid-subprocess kill) that
+  made the durability contract conditional. One production path now:
+  `:ruby_llm`.
+  - `config.engine = :agent_sdk` raises a clear `BootGuardError` at configure
+    time. `config.auth` and the `agent_sdk_*` options are warning no-ops for
+    this release (hard removal in 0.3) — an existing initializer won't crash.
+  - The in-process MCP server (`Silas::Mcp::Server`/`Handler`) **survives the
+    cut** — it is the seam for a planned "mount your agent's tools as an MCP
+    server" feature — with its own integration spec. Its bind host moved from
+    `config.agent_sdk_mcp_host` to `config.mcp_server_host`.
+  - New migration drops `silas_turns.cli_session_id` and
+    `silas_turns.mcp_token` (the latter was write-only; tokens are minted and
+    compared in memory). Run `bin/rails silas:install:migrations db:migrate`.
+  - `Silas::Engines::Base.loop_ownership` is gone — every engine executes one
+    model call per step under the framework-owned loop. Custom engines that
+    merely inherited it are unaffected.
+
 ## 0.1.7
 
 - **Memory — graph-shaped, not a graph database.** New `silas_memories` table:

data/README.md

@@ -33,6 +33,7 @@ app/agent/
 bundle add silas
 bin/rails generate silas:install
 bin/rails db:migrate
+bin/rails silas:doctor   # key · queue adapter · model · migrations · tools · rescuer · cable · auth
 ```
 
 ```ruby
@@ -88,6 +89,13 @@ hundreds of times per release (results in `chaos_host/results/`):
 - **Approvals park at zero compute** — the job exits; approving enqueues a fresh
   one that replays completed work from rows, never re-calling the model or
   re-running tools. Parks expire (default 7 days) rather than ghosting forever.
+- **Transient model errors retry from the checkpoint.** A rate limit,
+  overload, or timeout backs off and retries the job — and the continuation
+  resumes from the last completed step, never re-running completed work.
+  Exhausted retries and permanent rejections (bad key, bad request) expire
+  pending approvals and fail the turn loudly. **A turn can never sit in
+  `running` forever**: the rescuer also fails turns stranded by a loop job
+  that died outside the retry list.
 - **The rescuer is part of the contract.** Solid Queue marks a dead worker's
   jobs failed and nothing retries them; the installer wires
   `Silas::DeadJobRescuerJob` as a recurring task (every 30s). Recovery time ≈
@@ -96,19 +104,19 @@ hundreds of times per release (results in `chaos_host/results/`):
   deploy that changes tools/skills mid-turn fails the turn loudly
   (`NondeterminismError`) instead of resuming into a different agent.
 
-## Engines
+## Engine
 
-Inference is one pluggable seam (`config.engine`):
+Inference is one pluggable seam (`config.engine`): `:ruby_llm` — API-key auth
+via [RubyLLM](https://rubyllm.com), any provider it supports — is the default
+and the production path. Compose resilience via `config.around_model_call`, or
+swap in any object responding to `#execute_step` (the eval harness and the
+chaos tests do exactly that).
 
-- `:ruby_llm` — API-key auth via [RubyLLM](https://rubyllm.com); any provider it
-  supports. Canonical, production mode. Compose resilience via
-  `config.around_model_call`.
-- `:agent_sdk` — a `claude -p` subprocess runs the whole turn, calling back into
-  your tools over an in-worker HTTP MCP endpoint whose `tools/call` goes through
-  the same Ledger. Always `--bare` (API-key auth only; the boot guard raises if
-  OAuth is configured with `ANTHROPIC_API_KEY` present, and if the key is missing
-  in api_key mode). v1 is honestly weaker than `:ruby_llm`: exactly-once *within*
-  a run, `approval :never` tools only, and fail-closed on a mid-subprocess kill.
+> The experimental `:agent_sdk` engine (a `claude -p` subprocess) was removed
+> in 0.2: its subscription-auth rationale was structurally unreachable, and it
+> carried weaker guarantees than `:ruby_llm` on every axis. Its in-process MCP
+> server survives and returns as a first-class *mount your tools as MCP*
+> feature.
 
 ## Sandbox: run untrusted code with hermetic
 
@@ -190,12 +198,71 @@ An agent is reached by more than a method call:
   approvals render as Slack buttons / signed email links that call the same
   `approve!`/`decline!`. Outbound delivery is idempotent and off the durable loop.
 
+## Streaming
+
+Turns stream. The `:ruby_llm` engine emits text deltas as the model responds:
+`bin/rails silas:chat` prints tokens as they arrive, and the inbox trace
+renders them live over Turbo (coalesced to ~10Hz). Deltas are decoration over
+the durable rows — never persisted, never fed back to the model, and a
+replayed step renders from its row with no deltas at all, so streaming adds
+zero risk to the durability contract. Custom sinks subscribe to the
+`"silas.delta"` notification (`{ session_id:, turn_id:, step_id:, step_index:,
+text: }`, where `text` is the accumulated string so far — filter by ids;
+notifications are process-global).
+
+## Structured answers
+
+Give the turn's final answer a schema in agent.yml and read it back as a Hash:
+
+```yaml
+final_answer:
+  type: object
+  properties:
+    verdict: { type: string }
+    amount_pence: { type: integer }
+  required: [verdict]
+```
+
+`Turn#answer_data` returns the parsed payload (`answer_text` stays for prose
+agents); the HTTP API carries it as `answer_data`, evals get
+`assert_answer_data(key: :verdict, value: "approve")`. Rendered through
+RubyLLM's `with_schema`, so each provider's native structured-output mode is
+used. The schema is model-visible state — changing it mid-turn fails the turn
+loudly rather than resuming into a different contract.
+
+## The HTTP API
+
+Everything the operator surface can do, over JSON — mounted with the engine at
+`/silas/api/v1`, **deny-by-default** like the inbox (wire `config.api_auth`;
+`config.api_actor` names the identity recorded on approvals):
+
+```sh
+curl -X POST .../silas/api/v1/sessions -d "input=Refund order 42, £12.50"
+curl .../silas/api/v1/sessions/1?trace=1                # turns + steps + tool calls
+curl .../silas/api/v1/sessions/1/approvals              # what's parked
+curl -X POST .../silas/api/v1/approvals/7/approve       # the same approve! as the inbox
+curl -X POST .../silas/api/v1/sessions/1/turns -d "input=Now email them"   # 409 if busy
+curl -X POST .../silas/api/v1/turns/9/cancel
+curl -N .../silas/api/v1/sessions/1/stream              # server-sent events
+```
+
+The stream is SSE at **row granularity** — turn / completed-step / invocation
+changes, at-least-once with `Last-Event-ID` resume (ids are epoch-ms
+watermarks; `?poll=1` returns the backlog and closes, curl-friendly; streams
+close themselves after `api_stream_max_duration` and clients reconnect).
+Per-token streaming is deliberately the browser/Turbo feature — deltas live in
+the worker process, and the gem requires no cross-process bus.
+
 ## The inbox
 
 Mount the engine (the generator does this) and a live inbox appears at
-`/silas/inbox`: a session list, a live step-trace that streams over Turbo
-Streams as the agent runs, approval cards whose Approve/Decline buttons call the
-exact same `approve!`/`decline!` as Slack and email, and per-session token/cost
+`/silas/inbox`: a session list, **web chat** (start a session or reply from
+the browser — same durable loop, no separate surface), a live step-trace that
+streams tokens over Turbo Streams as the agent runs, approval cards whose
+Approve/Decline buttons call the exact same `approve!`/`decline!` as Slack and
+email, a full **audit trail** (every tool call's arguments and its result or
+recorded error; who approved; who declined and why), **cancel** on active
+turns (honored at the next step boundary), and per-session token/cost
 accounting. It's **deny-by-default** — invisible until you wire auth:
 
 ```ruby

data/app/controllers/concerns/silas/api/serialization.rb

@@ -0,0 +1,63 @@
+module Silas
+  module Api
+    # Minimal, dependency-free JSON shapes. Deliberately explicit allowlists —
+    # never as_json a whole row (instruction snapshots and internal columns
+    # don't belong on the wire).
+    module Serialization
+      def session_json(session, include_turns: true, trace: false)
+        base = {
+          id: session.id, agent_name: session.agent_name,
+          channel: session.channel, status: session.status,
+          parent_session_id: session.parent_session_id,
+          child_session_ids: session.child_sessions.ids,
+          cost: Silas::Inbox::Cost.for_session(session),
+          created_at: session.created_at, updated_at: session.updated_at
+        }
+        return base unless include_turns
+
+        base.merge(turns: session.turns.map { |t| turn_json(t, trace: trace) })
+      end
+
+      def turn_json(turn, trace: false)
+        base = {
+          id: turn.id, session_id: turn.session_id, index: turn.index,
+          status: turn.status, input: turn.input,
+          failure_reason: turn.failure_reason,
+          answer_text: (turn.answer_text if turn.completed?),
+          answer_data: (turn.answer_data if turn.completed?),
+          created_at: turn.created_at, updated_at: turn.updated_at
+        }
+        return base unless trace
+
+        base.merge(steps: turn.steps.map do |step|
+          step_json(step).merge(invocations: step.tool_invocations.map { |i| invocation_json(i) })
+        end)
+      end
+
+      def step_json(step)
+        {
+          id: step.id, turn_id: step.turn_id, index: step.index,
+          status: step.status, terminal: step.terminal,
+          model: step.model, provider: step.provider,
+          text: Array(step.response_blocks).select { |b| b["type"] == "text" }
+                                           .map { |b| b["text"] }.join.presence,
+          structured: Array(step.response_blocks).reverse
+                                                 .find { |b| b["type"] == "structured" }&.dig("data"),
+          updated_at: step.updated_at
+        }
+      end
+
+      def invocation_json(invocation)
+        {
+          id: invocation.id, turn_id: invocation.turn_id,
+          tool_name: invocation.tool_name, status: invocation.status,
+          approval_state: invocation.approval_state,
+          arguments: invocation.arguments, result: invocation.result,
+          error: invocation.error, approved_by: invocation.approved_by,
+          decline_reason: invocation.decline_reason,
+          updated_at: invocation.updated_at
+        }
+      end
+    end
+  end
+end

data/app/controllers/silas/api/base_controller.rb

@@ -0,0 +1,24 @@
+module Silas
+  module Api
+    # JSON API base: ActionController::API (no CSRF, no layouts, no cookies),
+    # deny-by-default auth with the inbox's contract — the host lambda DENIES
+    # by rendering (or head-ing) and PASSES by not rendering.
+    class BaseController < ActionController::API
+      before_action :authenticate!
+
+      rescue_from ActiveRecord::RecordNotFound do
+        render json: { error: "not found" }, status: :not_found
+      end
+
+      private
+
+      def authenticate!
+        Silas.config.api_auth.call(self)
+      end
+
+      def current_actor
+        Silas.config.api_actor.call(self)
+      end
+    end
+  end
+end

data/app/controllers/silas/api/v1/approvals_controller.rb

@@ -0,0 +1,35 @@
+module Silas
+  module Api
+    module V1
+      # The headline feature over HTTP: list what's parked, approve or decline
+      # it — the exact same approve!/decline! as the inbox, Slack, and email.
+      class ApprovalsController < Silas::Api::BaseController
+        include Silas::Api::Serialization
+
+        # GET /silas/api/v1/sessions/:session_id/approvals
+        def index
+          session = Silas::Session.find(params[:session_id])
+          render json: { approvals: session.pending_approvals.order(:id).map { |i| invocation_json(i) } }
+        end
+
+        # POST /silas/api/v1/approvals/:id/approve
+        def approve
+          invocation = Silas::ToolInvocation.find(params[:id])
+          invocation.approve!(by: current_actor)
+          render json: invocation_json(invocation.reload)
+        rescue Silas::Error => e
+          render json: { error: e.message }, status: :conflict
+        end
+
+        # POST /silas/api/v1/approvals/:id/decline  { reason: (optional) }
+        def decline
+          invocation = Silas::ToolInvocation.find(params[:id])
+          invocation.decline!(reason: params[:reason].presence || "declined via api", by: current_actor)
+          render json: invocation_json(invocation.reload)
+        rescue Silas::Error => e
+          render json: { error: e.message }, status: :conflict
+        end
+      end
+    end
+  end
+end

data/app/controllers/silas/api/v1/sessions_controller.rb

@@ -0,0 +1,39 @@
+module Silas
+  module Api
+    module V1
+      class SessionsController < Silas::Api::BaseController
+        include Silas::Api::Serialization
+
+        # POST /silas/api/v1/sessions  { input:, agent: (optional), metadata: (optional) }
+        # channel stays nil ("direct") — API consumers read state via GET/stream;
+        # a non-nil channel would enqueue pointless outbound delivery jobs.
+        def create
+          input = params[:input].to_s.strip
+          return render json: { error: "input is required" }, status: :unprocessable_entity if input.empty?
+
+          handle = params[:agent].present? ? Silas.agent(params[:agent]) : Silas.agent
+          session = handle.start(input: input, metadata: metadata_param)
+          render json: session_json(session.reload), status: :created
+        rescue Silas::TurnInProgressError => e
+          render json: { error: e.message }, status: :conflict
+        rescue Silas::Error => e
+          render json: { error: e.message }, status: :unprocessable_entity
+        end
+
+        # GET /silas/api/v1/sessions/:id         — session + turns
+        # GET /silas/api/v1/sessions/:id?trace=1 — plus steps + invocations
+        def show
+          session = Silas::Session.includes(turns: { steps: :tool_invocations }).find(params[:id])
+          render json: session_json(session, trace: params[:trace].present?)
+        end
+
+        private
+
+        def metadata_param
+          raw = params[:metadata]
+          raw.respond_to?(:to_unsafe_h) ? raw.to_unsafe_h : (raw.presence || {})
+        end
+      end
+    end
+  end
+end

data/app/controllers/silas/api/v1/streams_controller.rb

@@ -0,0 +1,117 @@
+require "json"
+
+module Silas
+  module Api
+    module V1
+      # Server-sent events at ROW granularity: turn / completed-step /
+      # invocation changes polled from the durable rows — the same source of
+      # truth as everything else. Deliberately NOT per-token: deltas are
+      # emitted in the worker process and the gem requires no cross-process
+      # bus; per-token streaming is the Turbo/browser feature.
+      #
+      # Delivery is at-least-once with Last-Event-ID resume: event ids are
+      # epoch-millisecond watermarks, each poll re-reads a 1ms overlap, and
+      # clients dedup by (event type, id, status). `?poll=1` emits the backlog
+      # since Last-Event-ID and closes — curl-able, and how the request specs
+      # exercise the cursor without holding a live stream.
+      #
+      # Live actions run on their own thread and hold a Puma thread for the
+      # stream's lifetime — inherent to SSE. The AR connection is NOT held:
+      # each poll checks one out and returns it before sleeping, and the
+      # stream closes itself after api_stream_max_duration (clients reconnect
+      # with Last-Event-ID).
+      class StreamsController < Silas::Api::BaseController
+        include ActionController::Live
+        include Silas::Api::Serialization
+
+        HEARTBEAT_EVERY = 15 # seconds; comment-frames keep proxies alive
+
+        def show
+          session_id = with_connection { Silas::Session.find(params[:id]).id }
+
+          response.headers["Content-Type"] = "text/event-stream"
+          response.headers["Cache-Control"] = "no-cache"
+          response.headers["X-Accel-Buffering"] = "no" # nginx: never buffer SSE
+          # Whatever the router/auth checked out must not stay pinned for the
+          # stream's lifetime.
+          ActiveRecord::Base.connection_handler.clear_active_connections!
+
+          watermark = initial_watermark
+          deadline = clock + Silas.config.api_stream_max_duration
+          last_beat = clock
+
+          loop do
+            events = with_connection { collect_changes(session_id, watermark) }
+            events.each do |type, at, payload|
+              write_event(type, payload, watermark_ms(at))
+              watermark = at if at > watermark
+            end
+
+            break if params[:poll].present? # backlog served; close
+
+            if clock >= deadline
+              write_event("timeout", { reconnect: true }, watermark_ms(watermark))
+              break
+            end
+
+            if clock - last_beat >= HEARTBEAT_EVERY
+              response.stream.write(": hb\n\n")
+              last_beat = clock
+            end
+
+            sleep Silas.config.api_stream_poll_interval
+          end
+        rescue IOError, ActionController::Live::ClientDisconnected
+          # client went away — the normal end of an SSE stream
+        ensure
+          response.stream.close rescue nil
+        end
+
+        private
+
+        # Everything with updated_at at-or-after the watermark (1ms overlap —
+        # at-least-once beats a gap). Steps only when completed: their text is
+        # the payload, and incomplete steps have none.
+        def collect_changes(session_id, watermark)
+          overlap = watermark - 0.001
+          events = []
+
+          Silas::Turn.where(session_id: session_id).where(updated_at: overlap..)
+                     .order(:updated_at, :id).each do |turn|
+            events << [ "turn", turn.updated_at, turn_json(turn) ]
+          end
+          Silas::Step.joins(:turn).where(silas_turns: { session_id: session_id })
+                     .where(status: "completed").where(updated_at: overlap..)
+                     .order(:updated_at, :id).each do |step|
+            events << [ "step", step.updated_at, step_json(step) ]
+          end
+          Silas::ToolInvocation.joins(:turn).where(silas_turns: { session_id: session_id })
+                               .where(updated_at: overlap..)
+                               .order(:updated_at, :id).each do |invocation|
+            events << [ "invocation", invocation.updated_at, invocation_json(invocation) ]
+          end
+
+          events.sort_by { |(_type, at, _payload)| at }
+        end
+
+        def write_event(type, payload, id_ms)
+          response.stream.write("id: #{id_ms}\nevent: #{type}\ndata: #{JSON.generate(payload)}\n\n")
+        end
+
+        # Last-Event-ID (header or param) in epoch ms; absent -> "from now"
+        # (GET /sessions/:id carries current state; the stream carries what
+        # changes next). Last-Event-ID: 0 replays the whole session.
+        def initial_watermark
+          raw = request.headers["Last-Event-ID"].presence || params[:last_event_id].presence
+          raw ? Time.zone.at(raw.to_i / 1000.0) : Time.zone.now
+        end
+
+        def watermark_ms(time) = (time.to_f * 1000).round
+
+        def with_connection(&) = ActiveRecord::Base.connection_pool.with_connection(&)
+
+        def clock = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/app/controllers/silas/api/v1/turns_controller.rb

@@ -0,0 +1,32 @@
+module Silas
+  module Api
+    module V1
+      class TurnsController < Silas::Api::BaseController
+        include Silas::Api::Serialization
+
+        # POST /silas/api/v1/sessions/:session_id/turns  { input: }
+        # 409 when a turn is already active — an API must surface it, not
+        # swallow it the way the webhook channels do.
+        def create
+          session = Silas::Session.find(params[:session_id])
+          input = params[:input].to_s.strip
+          return render json: { error: "input is required" }, status: :unprocessable_entity if input.empty?
+
+          turn = session.continue(input: input)
+          render json: turn_json(turn), status: :created
+        rescue Silas::TurnInProgressError => e
+          render json: { error: e.message }, status: :conflict
+        end
+
+        # POST /silas/api/v1/turns/:id/cancel
+        # Running turns are flagged (honored at the next step boundary);
+        # queued/parked turns cancel immediately — cancel: reflects which.
+        def cancel
+          turn = Silas::Turn.find(params[:id])
+          outcome = turn.cancel!(reason: "canceled via api by #{current_actor}")
+          render json: turn_json(turn.reload).merge(cancel: outcome)
+        end
+      end
+    end
+  end
+end