xeno 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '03921563a3c8f8a6ef1a2f6c8274f6851f65daeebe66b617e2fc9729673bd571'
+  data.tar.gz: 51e0a0f0646cc28974e73e8cca0e5c485fc60113c664161a0e31b74d6bfb5201
+SHA512:
+  metadata.gz: 8a5e8aa4d6ce79696fc85275c07ddb4522c2fd18b667120087841367d94a279258763ce9ab45bb7764556e8954b70f1f751f6b88549983c4622ea58eea2a3cc6
+  data.tar.gz: cdb8ceae13f48c5277d9760715021749d6ddfa40fa0a9a7045631c7cbb6323096e17aabd097b3b0b0d37c3513d7a4f9f1e7d4585b654bee683955b56a71bbf46

data/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+Format follows [Keep a Changelog](https://keepachangelog.com); versions follow
+[SemVer](https://semver.org). **xeno is on the `0.0.x` preview line: any release may
+change anything.** `0.1.0` will mark the first release we consider usable in anger —
+after RubyLLM v2 GA is absorbed and the API has held still through early-adopter
+feedback.
+
+## [Unreleased]
+
+## [0.0.1] - 2026-08-07
+
+The first public release of xeno, a framework for durable AI agents built on Rails:
+
+- `agent/` conventions with path-derived names (`agent.rb`, `instructions.md`,
+  dynamic `instructions.rb`, `tools/`, `hooks/`, `schedules/`, `channels/`).
+- Durable session → turn → step runtime on ActiveJob: atomic claims, fencing tokens,
+  heartbeats (including during long calls), checkpoint replay, a reaper for orphaned
+  turns, graceful-shutdown handoff, per-turn step budgets.
+- Human-in-the-loop parking: tool `approval` policies, `ask_question`, crash-safe
+  approve→resume, full text resolution of prompts (labels, indexes, held replies).
+- Append-only event stream (SSE + NDJSON) with cursor replay; the events table doubles
+  as an audit log.
+- Compaction, per-session token budgets, session-scoped state, steering, pending-message
+  queueing with drain-on-park.
+- Channels: HTTP (fail-closed auth, per-principal session ownership) and Slack
+  (signature verification, event dedup, thread sessions, text approvals, optional
+  post-then-edit streaming).
+- Markdown cron schedules compiled to Solid Queue recurring entries, with dedup.
+- Generators (`xeno:install`, `xeno:tool`) and standalone mode: `xeno new my-agent` /
+  `xeno server` — one process, sqlite, zero services. Scaffolds include a pinned
+  `ruby_llm` Gemfile, dotenv, and an AGENTS.md pointing coding agents at the gem docs.
+- Standalone first boot refreshes the model registry after the boot migrations, so
+  current model ids resolve without a manual `RubyLLM.models.refresh!`.
+- Tracks RubyLLM v2 (unreleased) at a pinned git commit: transcript support tables
+  (`ruby_llm_*`), per-attempt usage ledger backing token budgets and compaction.
+- Test suite: 180 runs / 987 assertions on SQLite and PostgreSQL, plus end-to-end
+  kill-and-resume scripts with real processes and real signals.

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Nicolas Erlichman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,211 @@
+# xeno
+
+xeno is a framework for durable AI agents. Built on Rails, it runs standalone (`xeno new my-agent`) or inside the Rails app you already have.
+
+A xeno agent is a session that survives restarts and deploys mid-turn, waits days for a human approval without holding a process, and resumes exactly where it stopped. Under the hood, xeno composes [RubyLLM](https://rubyllm.com) for model calls with ActiveJob and ActiveRecord for durability.
+
+> [!WARNING]
+> xeno currently tracks RubyLLM v2 (unreleased), pinned to git ref [`2aaddf96`](https://github.com/crmne/ruby_llm/commit/2aaddf96). The released `ruby_llm` gem (1.16.0) is not compatible. Standalone apps get the pin from the scaffold's Gemfile. If your Rails app already uses a released `ruby_llm`, xeno cannot run alongside it today. This resolves at RubyLLM v2 GA, when xeno switches to the released gem.
+
+## The filesystem is the authoring interface
+
+A xeno agent is a directory:
+
+```text
+agent/
+├── agent.rb            # optional: model and runtime config
+├── instructions.md     # the always-on system prompt
+├── instructions.rb     # optional: dynamic instructions, resolved per turn
+├── tools/
+│   └── get_weather.rb  # tool "get_weather" (class Xeno::Tools::GetWeather)
+├── hooks/
+│   └── metrics.rb      # observe-only event handlers
+└── schedules/
+    └── weekly_recap.md # cron-triggered agent session
+```
+
+The path supplies the name; there are no `name:` fields. `xeno info` prints the resolved agent and flags anything misplaced.
+
+## Quick start
+
+Standalone, from nothing:
+
+```bash
+xeno new my-agent && cd my-agent
+bundle install
+xeno server
+```
+
+One process: web and jobs in the same Puma, SQLite, no external services. The dev chat UI is at `http://localhost:3000/agent/dev`.
+
+In an existing Rails app:
+
+```bash
+bundle add xeno
+bin/rails g xeno:install
+bin/rails db:migrate
+```
+
+The generator creates `agent/` at your app root and mounts the engine at `/agent`. Tools are your domain code: they call your models, policies, and credentials directly, with no connector layer in between.
+
+## A minimal example
+
+Add a gated tool at `agent/tools/charge_card.rb`:
+
+```ruby
+class Xeno::Tools::ChargeCard < Xeno::Tool
+  description "Charge the customer's card. Irreversible."
+  parameter :amount_cents, type: :integer, description: "Amount in cents"
+
+  approval :always
+
+  def execute(amount_cents:)
+    PaymentService.charge!(amount_cents)
+  end
+end
+```
+
+Send "charge $42 to my card" and the agent decides to call the tool. `approval :always` parks the turn: the job ends, and the pending approval is a database row. Kill the process, deploy, come back tomorrow. When you approve (over HTTP, or one click in the dev UI), the turn resumes from its last checkpoint and the tool runs exactly once.
+
+That arc is the flagship integration test (`test/demo_acceptance_test.rb`, three real processes) and a watchable script (`script/demo.sh`).
+
+## How durability works
+
+Work nests session → turn → step. A turn is one ActiveJob; a step is one model call plus its tool calls, checkpointed in your database:
+
+- A tool execution and its transcript write commit in one transaction, so recorded calls never re-execute. A killed process resumes from the last checkpoint.
+- Turn claims use an atomic compare-and-swap with heartbeats, stale-claim takeover, fencing tokens, and a reaper for orphaned turns. Any ActiveJob backend works; with Solid Queue the whole story is database rows.
+- Parking ends the job. A parked session costs nothing for days; resolving its pending input enqueues the resume.
+- Messages that arrive mid-turn queue up and fold into the next turn.
+
+`docs/runtime.md`, shipped inside the gem, documents the runtime invariants in full.
+
+## Sessions over HTTP
+
+The engine mounts at `/agent`:
+
+```text
+POST /agent/v1/sessions                    create a session          → { session_id, continuation_token }
+POST /agent/v1/sessions/:id/messages       follow-up message         (steer: true replaces the active turn)
+POST /agent/v1/sessions/:id/inputs         approve / deny / answer   (by action_id)
+POST /agent/v1/sessions/:id/cancel         stop the active turn
+POST /agent/v1/sessions/:id/compact        summarize old history
+POST /agent/v1/sessions/:id/reset          retire the session
+GET  /agent/v1/sessions/:id/stream         event stream
+GET  /agent/v1/health
+```
+
+Events are append-only rows with a per-session index. The stream endpoint serves Server-Sent Events (SSE) or NDJSON (`?format=ndjson`) and replays from any cursor (`?start_index=N`); the same table is your audit log.
+
+## Slack
+
+Two credentials and the agent answers mentions in threads:
+
+```ruby
+# agent/channels/slack.rb
+Xeno.channel :slack do
+  signing_secret ENV["SLACK_SIGNING_SECRET"]
+  bot_token     ENV["SLACK_BOT_TOKEN"]
+end
+```
+
+Standalone apps load these from `.env`; in a Rails app, `Rails.application.credentials` works here too.
+
+Point your Slack app's Events API at `POST /agent/v1/channels/slack/events`. xeno verifies signatures in constant time, answers the URL handshake, dedupes retries, and acks inside Slack's 3-second window. Mentions and direct messages start sessions; each thread is one session; replies continue it.
+
+When the agent parks, the prompt lands in the thread, and replies resolve it:
+
+- **approve** or **deny** settles an approval
+- a number ("2") or a label ("tuesday") picks a choice
+- any text answers a free-form question
+- unrelated replies are held as the next message, never treated as an answer
+
+Replies post at turn completion by default; `stream_replies true` in the channel block opts into post-then-edit streaming.
+
+## Schedules
+
+A schedule is a markdown file with a cron line:
+
+```markdown
+---
+cron: "0 9 * * 1"
+---
+Summarize the week's activity and post highlights to the team.
+```
+
+`bin/rails xeno:schedules:sync` compiles `agent/schedules/*.md` into Solid Queue recurring entries; standalone apps sync at boot. Development never fires on cadence: trigger by name via the dev endpoint. Schedule runs execute under the app principal and cannot wait on a human, so a gated tool deterministically fails the run.
+
+## Configuration
+
+Standalone apps configure in `agent/agent.rb`; mounted apps use `config/initializers/xeno.rb`:
+
+```ruby
+Xeno.configure do |config|
+  # Fail closed: every endpoint except health returns 401 until you set this.
+  # The truthy return value becomes the session principal.
+  config.authenticate = ->(request) do
+    token = request.headers["Authorization"]&.delete_prefix("Bearer ")
+    { "user" => "api" } if ActiveSupport::SecurityUtils.secure_compare(
+      token.to_s, ENV["XENO_API_KEY"].to_s
+    )
+  end
+
+  config.max_steps = 20               # per-turn model-call budget
+  config.turn_stale_after = 5.minutes # dead-worker takeover window
+end
+```
+
+Development with no lambda configured stays usable on localhost; everywhere else the absence of a checker is a 401.
+
+The principal is also the ownership boundary: a session belongs to the principal stamped at creation, and every session-scoped endpoint returns 404 for any other principal. See `docs/runtime.md` for the authorization rules.
+
+### Model registry
+
+Model ids resolve against RubyLLM's registry, and models released after the gem's catalog snapshot need a registry refresh before they resolve. Standalone apps refresh automatically on first boot, right after the boot-time migrations (skip with `XENO_SKIP_MODEL_REFRESH=1`). To refresh later, run it manually for now (a friendlier command is planned):
+
+```bash
+# mounted
+bin/rails runner "RubyLLM.models.refresh!"
+```
+
+```bash
+# standalone
+bundle exec ruby -r dotenv/load -r xeno/standalone -e 'Xeno.rails_app; Xeno.definition; RubyLLM.models.refresh!'
+```
+
+Or bypass the registry per model with `model "the-id", provider: :openai, assume_model_exists: true`. Automatic compaction then needs `config.compaction_context_window`, since the registry cannot supply the window.
+
+## Security model
+
+xeno runs tools inside your app on purpose:
+
+- There is no sandbox and no `bash` tool. The model's only execution surface is the tools you write.
+- That power cuts both ways: prompt injection reaches whatever your tools expose. Keep parameters narrow and typed, scope queries to the session's principal, authorize inside tools with your existing layer, and treat tool output fed back to the model as untrusted.
+- Approvals are the guardrail. Gate anything irreversible or externally visible with `:once` or `:always`.
+- Webhooks verify signatures in constant time, HTTP auth fails closed, and dev routes never mount outside development.
+
+## Known limitations
+
+- SSE holds a thread per client, which is fine for dev UIs and small deployments. Catch-up reads are batched so reconnects on long sessions stay bounded.
+- SQLite and PostgreSQL are the tested databases; the suite runs on both. MySQL is untested and has known caveats.
+- Execution is at-least-once: a step interrupted mid-flight re-runs on retry, so tool side effects need idempotency or approval gates. Consumers dedupe events by `(session, index)`.
+- Cancellation is cooperative and lands at the next step boundary; an in-flight model call finishes first. A parked turn cancels instantly.
+- Sessions retire explicitly: `reset` is the only terminal transition.
+- One agent per app.
+
+## Development
+
+```bash
+bin/rails test                     # the whole suite: offline, deterministic fake LLM
+script/demo.sh                     # the kill -9 demo, narrated
+script/verify_generators.sh        # generators against a fresh rails new app
+script/verify_standalone.sh        # the standalone one-process arc
+```
+
+Tests run against a scripted fake server: no network, no keys, no flake. The kill-and-resume arcs use real processes and real signals.
+
+## Status: preview (0.0.x)
+
+xeno is an early preview with no production mileage yet; anything may change between 0.0.x releases. It targets RubyLLM v2 (unreleased, pinned to a known-good commit; see the warning above); the pin drops at v2 GA. `0.1.0` will mark the first release we consider stable enough to build on. See [CHANGELOG.md](CHANGELOG.md).
+
+MIT License.

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"

data/app/assets/stylesheets/xeno/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/app/controllers/xeno/api_controller.rb

@@ -0,0 +1,68 @@
+module Xeno
+  # Base for every engine endpoint. Auth fails closed: without a configured
+  # authenticate lambda, everything is 401. The lambda receives the request;
+  # a falsy return is a 401; its truthy return value is the request
+  # principal (stamped onto sessions by the HTTP channel).
+  class ApiController < ActionController::API
+    before_action :authenticate!
+
+    rescue_from ActiveRecord::RecordNotFound do
+      render json: { error: "not found" }, status: :not_found
+    end
+
+    rescue_from ActionController::ParameterMissing do |error|
+      render json: { error: error.message }, status: :bad_request
+    end
+
+    rescue_from Xeno::Error do |error|
+      render json: { error: error.message }, status: :conflict
+    end
+
+    # The development fallback principal (no auth lambda configured). It
+    # matches every session — in development only — so the dev UI and
+    # localhost curl stay usable.
+    DEV_PRINCIPAL = { "user" => "dev" }.freeze
+
+    private
+
+    def authenticate!
+      checker = Xeno.config.authenticate
+
+      # Development with no auth configured stays usable (the dev UI, curl on
+      # localhost). Everywhere else the absence of a checker is a 401.
+      if checker.nil? && Rails.env.development?
+        @current_principal = DEV_PRINCIPAL
+        return
+      end
+
+      @current_principal = checker && instance_exec(request, &checker)
+      head :unauthorized unless @current_principal
+    end
+
+    def current_principal
+      # Normalize truthy-but-not-descriptive results (true) to nil-principal.
+      @current_principal == true ? nil : @current_principal
+    end
+
+    # Ownership rule: a session belongs to the principal stamped at create.
+    # A non-matching caller gets the same 404 as a nonexistent id (no
+    # existence leak). A lambda that returns bare `true` yields nil
+    # principals everywhere — single-tenant mode, every authenticated
+    # caller matches (documented in docs/runtime.md).
+    def find_owned_session!
+      session = Session.find(params[:id])
+      raise ActiveRecord::RecordNotFound unless owns?(session)
+
+      session
+    end
+
+    def owns?(session)
+      # Object identity on purpose: only the fallback path above grants the
+      # wildcard, never a configured lambda that happens to return the same
+      # hash.
+      return true if Rails.env.development? && @current_principal.equal?(DEV_PRINCIPAL)
+
+      session.principal == current_principal.as_json
+    end
+  end
+end

data/app/controllers/xeno/application_controller.rb

@@ -0,0 +1,4 @@
+module Xeno
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/controllers/xeno/dev_controller.rb

@@ -0,0 +1,24 @@
+module Xeno
+  # Development conveniences. Schedules never fire on cadence in dev; this
+  # endpoint triggers one by name. Refuses to exist outside
+  # development (XENO_DEV_ROUTES=1 lets tests exercise it).
+  class DevController < ApiController
+    before_action :ensure_development
+
+    def dispatch_schedule
+      name = params[:name].to_s
+      unless Xeno.definition.schedules.key?(name)
+        return render json: { error: "unknown schedule: #{name}" }, status: :not_found
+      end
+
+      ScheduleJob.perform_later(name)
+      render json: { dispatched: name }, status: :accepted
+    end
+
+    private
+
+    def ensure_development
+      head :not_found unless Xeno.dev_routes_enabled?
+    end
+  end
+end

data/app/controllers/xeno/dev_ui_controller.rb

@@ -0,0 +1,71 @@
+module Xeno
+  # The mounted dev chat UI: chat with the
+  # agent, watch the event stream live (over xeno's own SSE endpoint), and
+  # approve/deny/answer parked work. Development only.
+  class DevUiController < ApplicationController
+    before_action :ensure_development
+
+    def index
+      @sessions = Session.order(id: :desc).limit(50)
+    end
+
+    def create
+      session_record = Session.start!(
+        message: params.require(:message),
+        channel: "dev",
+        principal: { "user" => "dev-ui" }
+      )
+      redirect_to dev_session_path(session_record)
+    end
+
+    def show
+      @session = Session.find(params[:id])
+      @messages = @session.chat.messages_association.order(:id)
+      @pending_actions = Action.joins(:turn)
+                               .where(xeno_turns: { session_id: @session.id }, status: "pending_approval")
+                               .order(:id)
+      @events = @session.events.order(:index)
+    end
+
+    def message
+      session_record = Session.find(params[:id])
+      content = params.require(:message)
+      if ActiveModel::Type::Boolean.new.cast(params[:steer])
+        session_record.steer!(content)
+      else
+        session_record.receive_message!(content)
+      end
+      redirect_to dev_session_path(session_record)
+    end
+
+    def compact
+      session_record = Session.find(params[:id])
+      unless session_record.turns.where(kind: "compaction", status: %w[pending running]).exists?
+        session_record.stage_compaction_turn!(reason: "manual").enqueue!
+      end
+      redirect_to dev_session_path(session_record)
+    end
+
+    def input
+      session_record = Session.find(params[:id])
+      action = Action.joins(:turn)
+                     .where(xeno_turns: { session_id: session_record.id })
+                     .find(params.require(:action_id))
+
+      principal = { "user" => "dev-ui" }
+      case params[:decision]
+      when "approve" then Inputs.approve!(action, principal: principal)
+      when "deny" then Inputs.deny!(action, reason: params[:reason], principal: principal)
+      else Inputs.answer!(action, params.require(:answer), principal: principal)
+      end
+
+      redirect_to dev_session_path(session_record)
+    end
+
+    private
+
+    def ensure_development
+      head :not_found unless Xeno.dev_routes_enabled?
+    end
+  end
+end

data/app/controllers/xeno/health_controller.rb

@@ -0,0 +1,10 @@
+module Xeno
+  # The one unauthenticated endpoint: liveness only, leaks nothing.
+  class HealthController < ApiController
+    skip_before_action :authenticate!
+
+    def show
+      render json: { status: "ok" }
+    end
+  end
+end

data/app/controllers/xeno/sessions_controller.rb

@@ -0,0 +1,131 @@
+module Xeno
+  # The HTTP channel: always mounted, fail-closed. The channel owns the
+  # continuation token (the resume handle): create returns one, follow-up
+  # messages must present it, terminal states release it, reset retires the
+  # session so the same token can start fresh.
+  class SessionsController < ApiController
+    # POST /v1/sessions { message:, continuation_token: (optional) }
+    # Client-supplied tokens are restricted to the reserved `http:`
+    # namespace — a crafted `slack:<channel>:<ts>` token would otherwise
+    # hijack which Slack thread the agent posts into.
+    def create
+      message = params.require(:message)
+      token = params[:continuation_token].presence
+      if token && !token.start_with?("http:")
+        return render json: { error: "client-supplied continuation_token must use the http: namespace" },
+                      status: :unprocessable_entity
+      end
+      token ||= "http:#{SecureRandom.base58(24)}"
+
+      session = Session.start!(
+        message: message,
+        channel: "http",
+        principal: current_principal,
+        continuation_token: token
+      )
+
+      render json: { session_id: session.id, continuation_token: session.continuation_token },
+             status: :created
+    rescue ActiveRecord::RecordNotUnique
+      render json: { error: "continuation_token already in use by an active session" },
+             status: :conflict
+    end
+
+    # POST /v1/sessions/:id/messages { message:, continuation_token:, steer: }
+    # steer: true stops the active turn (settled safely) and makes this
+    # message the next turn instead of queueing behind the current work.
+    def message
+      session = find_owned_session!
+
+      return render json: { error: "session is finished — start a new one" }, status: :gone unless session.active?
+
+      supplied = params[:continuation_token].to_s
+      unless supplied.present? && session.continuation_token.present? &&
+             ActiveSupport::SecurityUtils.secure_compare(supplied, session.continuation_token)
+        return render json: { error: "continuation_token missing or wrong" }, status: :forbidden
+      end
+
+      content = params.require(:message)
+      steer = ActiveModel::Type::Boolean.new.cast(params[:steer])
+      turn = steer ? session.steer!(content) : session.receive_message!(content)
+      render json: { session_id: session.id, queued: turn.nil?, turn_id: turn&.id, steered: steer || nil }.compact,
+             status: :accepted
+    end
+
+    # POST /v1/sessions/:id/inputs { action_id:, decision: approve|deny, reason: } or { action_id:, answer: }
+    def input
+      session = find_owned_session!
+      action = Action.joins(:turn).where(xeno_turns: { session_id: session.id })
+                     .find(params.require(:action_id))
+
+      if action.kind == "question"
+        Inputs.answer!(action, params.require(:answer), principal: current_principal)
+      else
+        case params.require(:decision)
+        when "approve" then Inputs.approve!(action, principal: current_principal)
+        when "deny" then Inputs.deny!(action, reason: params[:reason], principal: current_principal)
+        else
+          return render json: { error: "decision must be approve or deny" }, status: :unprocessable_entity
+        end
+      end
+
+      render json: { action_id: action.id, status: action.reload.status,
+                     turn_status: action.turn.reload.status }
+    end
+
+    # POST /v1/sessions/:id/cancel — stop the active turn, session intact.
+    # A parked/pending turn cancels immediately (no process holds it); a
+    # running turn is cancelled cooperatively via the persisted flag the
+    # runner's checker polls (takes effect within a chunk or step boundary).
+    def cancel
+      session = find_owned_session!
+      turn = session.turns.where(status: %w[pending running waiting]).order(:sequence).first
+
+      return render json: { error: "no active turn" }, status: :conflict unless turn
+
+      if turn.status == "running"
+        session.chat.cancel!
+        render json: { turn_id: turn.id, cancelling: true }, status: :accepted
+      else
+        # Settle BEFORE cancelling: a parked turn's assistant tool_calls are
+        # still unanswered, and leaving them dangling bricks the session
+        # (every later generate replays the malformed transcript).
+        session.settle_unanswered_tool_calls!(turn, reason: "cancelled by user")
+        turn.update!(status: "cancelled")
+        session.update!(status: "running") if session.status == "waiting"
+        session.emit("turn.cancelled", { turn_id: turn.id })
+        render json: { turn_id: turn.id, cancelled: true }
+      end
+    end
+
+    # POST /v1/sessions/:id/compact — request a manual compaction. It runs
+    # as a claimed turn, so it queues behind any active or parked turn and
+    # executes the moment the session is free. Never appends a user message.
+    def compact
+      session = find_owned_session!
+
+      return render json: { error: "session is finished" }, status: :gone unless session.active?
+      if session.turns.where(kind: "compaction", status: %w[pending running]).exists?
+        return render json: { error: "a compaction is already queued" }, status: :conflict
+      end
+
+      turn = session.stage_compaction_turn!(reason: "manual")
+      turn.enqueue!
+      render json: { session_id: session.id, turn_id: turn.id, status: "requested" }, status: :accepted
+    end
+
+    # POST /v1/sessions/:id/reset — retire the session (the /new command);
+    # releases the continuation token so the same handle can start fresh.
+    def reset
+      session = find_owned_session!
+
+      return render json: { error: "session already finished" }, status: :gone unless session.active?
+
+      session.chat.cancel! if session.turns.where(status: "running").exists?
+      released = session.continuation_token
+      session.finish!("completed")
+
+      render json: { session_id: session.id, released_continuation_token: released }
+    end
+  end
+end

data/app/controllers/xeno/slack_controller.rb

@@ -0,0 +1,48 @@
+module Xeno
+  # The Slack Events API endpoint. The generic auth lambda is skipped —
+  # Slack's own request signature IS the authentication (verified in
+  # constant time), and it fails closed: no configured slack channel = 404,
+  # bad or stale signature = 401.
+  class SlackController < ApiController
+    skip_before_action :authenticate!
+
+    def events
+      channel = Channels.registry[:slack]
+      return head :not_found unless channel
+
+      raw = request.raw_post
+      unless channel.verify_signature(
+        request.headers["X-Slack-Request-Timestamp"],
+        request.headers["X-Slack-Signature"],
+        raw
+      )
+        return head :unauthorized
+      end
+
+      payload = JSON.parse(raw)
+      return render json: { challenge: payload["challenge"] } if payload["type"] == "url_verification"
+
+      enqueue_event(payload)
+      head :ok
+    end
+
+    private
+
+    # Fast ack (Slack retries anything that misses its 3s window) + retry
+    # dedup: the event_id claim and the job enqueue commit together, so a
+    # retry storm yields exactly one processing job — and a crash before
+    # the ack leaves the claim unclaimed for the retry to win. Events
+    # without an event_id (shouldn't happen for event_callback) process
+    # without dedup rather than being dropped.
+    def enqueue_event(payload)
+      event_id = payload["event_id"]
+      if event_id.present?
+        Dedup.transaction do
+          SlackEventJob.perform_later(payload) if Dedup.claim("slack_event", event_id)
+        end
+      else
+        SlackEventJob.perform_later(payload)
+      end
+    end
+  end
+end