xeno 0.0.1 → 0.0.2

data/app/models/xeno/event.rb

@@ -1,12 +1,10 @@
+# frozen_string_literal: true
+
 module Xeno
-  # The append-only session stream — also the audit log. `index` is the
-  # per-session cursor; consumers dedupe
-  # re-emitted events by (session, index).
+  # The append-only session stream — also the audit log. `index` is the per-session cursor;
+  # consumers dedupe re-emitted events by (session, index).
   class Event < ApplicationRecord
-    belongs_to :session, class_name: "Xeno::Session"
-
-    # The fixed vocabulary (docs/runtime.md § Events). Hooks may subscribe
-    # to any of these or "*".
+    # The fixed vocabulary (docs/runtime.md § Events). Hooks may subscribe to any of these or "*".
     TYPES = %w[
       session.started turn.started message.received
       step.started step.completed step.failed
@@ -18,16 +16,16 @@ module Xeno
       session.waiting session.completed session.failed
     ].freeze
 
-    # Hooks fire only after the row is durably committed (and therefore
-    # visible to other processes) — never inside the emitting transaction.
+    belongs_to :session, class_name: "Xeno::Session"
+
+    # Hooks fire only after the row is durably committed (and therefore visible to other processes)
+    # — never inside the emitting transaction.
     after_create_commit { Hooks.dispatch(self) }
 
-    # Appends with a race-safe per-session index: concurrent writers collide
-    # on the unique index and retry with the next slot. The INSERT runs in
-    # its own savepoint (requires_new): emit is routinely called inside
-    # enclosing transactions, and on Postgres a failed INSERT otherwise
-    # aborts the whole transaction — the retry would raise
-    # PG::InFailedSqlTransaction instead of recovering.
+    # Appends with a race-safe per-session index: concurrent writers collide on the unique index and
+    # retry with the next slot. The INSERT runs in its own savepoint because emit is routinely
+    # called inside enclosing transactions, and on Postgres a failed INSERT would otherwise abort
+    # the whole transaction.
     def self.append!(session, event_type, data = {})
       attempts = 0
       begin
@@ -42,11 +40,9 @@ module Xeno
           )
         end
       rescue ActiveRecord::RecordNotUnique
-        # Every collision means a competing append SUCCEEDED, so retries are
-        # bounded by actual contention. SQLite's file lock serializes writers
-        # (collisions are rare); Postgres runs them truly concurrently, so a
-        # burst can cost more than a handful of rounds — back off with jitter
-        # instead of giving up early.
+        # Every collision means a competing append succeeded, so retries are bounded by actual
+        # contention. SQLite's file lock serializes writers; Postgres runs them concurrently, so a
+        # burst can cost several rounds — back off with jitter instead of giving up early.
         attempts += 1
         raise if attempts >= 50
 

data/app/models/xeno/message.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Xeno
   class Message < ApplicationRecord
     acts_as_message chat_class: "Xeno::Chat"

data/app/models/xeno/pending_message.rb

@@ -1,6 +1,8 @@
+# frozen_string_literal: true
+
 module Xeno
-  # Messages that arrived while a turn was running. Drained into the next
-  # turn when the session parks or the turn completes.
+  # Messages that arrived while a turn was running. Drained into the next turn when the session
+  # parks or the turn completes.
   class PendingMessage < ApplicationRecord
     belongs_to :session, class_name: "Xeno::Session"
   end

data/app/models/xeno/session.rb

@@ -1,22 +1,27 @@
+# frozen_string_literal: true
+
 module Xeno
-  # The durable conversation: lives for days or weeks, owns the transcript
-  # chat, the turn ledger, and the append-only event stream. Identified by
-  # id (inspect/stream handle) and at most one continuation_token (the
-  # channel-owned resume handle, unique among active sessions).
+  # = Sessions
+  #
+  # A session is one durable conversation with the agent. It can live for days or weeks and
+  # survive deploys, crashes, and restarts, because everything it is lives in rows: the transcript
+  # chat, the turn ledger, and the append-only event stream.
+  #
+  # A session is identified two ways. The id is the stable handle for inspection and streaming.
+  # The continuation_token is the resume handle a channel owns — this Slack thread, this HTTP
+  # client — unique among active sessions and released when the session ends, so the same token
+  # can start fresh.
   class Session < ApplicationRecord
-    STATUSES = %w[running waiting completed failed].freeze
+    enum :status, %w[running waiting completed failed].index_with(&:itself), validate: true
 
     belongs_to :chat, class_name: "Xeno::Chat"
     has_many :turns, class_name: "Xeno::Turn", dependent: :destroy
     has_many :events, class_name: "Xeno::Event", dependent: :destroy
     has_many :pending_messages, class_name: "Xeno::PendingMessage", dependent: :destroy
 
-    validates :status, inclusion: { in: STATUSES }
-
-    # Opens a session for a first user message: builds the transcript chat
-    # per the resolved agent definition, stamps channel + principal, and
-    # stages turn 1. The caller enqueues the returned turn's job after the
-    # transaction commits (Session.start! does both).
+    # Opens a session for a first user message: builds the transcript chat per the resolved agent
+    # definition, stamps channel + principal, and stages turn 1. The caller enqueues the returned
+    # turn's job after the transaction commits (Session.start! does both).
     def self.open!(message:, channel: nil, principal: nil, continuation_token: nil, definition: Xeno.definition)
       transaction do
         chat = Chat.new
@@ -46,27 +51,22 @@ module Xeno
       session
     end
 
-    # Stages the next turn for one or more messages: persists each user
-    # message into the transcript, refreshes instructions (each turn picks up
-    # edited instructions without a restart), and
-    # appends the turn row. Runs in the caller's process so TurnJob replays
-    # never double-add the user message.
+    # Stages the next turn for one or more messages: persists each user message, refreshes
+    # instructions, and appends the turn row. Runs in the caller's process so TurnJob replays never
+    # double-add the user message.
     #
-    # defer_transcript: the turn row carries the messages but nothing is
-    # written into the transcript yet — the runner stages it when the turn
-    # is claimed. Required whenever an EARLIER turn may still be mid-flight
-    # (drained turns): appending user rows behind a parked turn's unanswered
-    # tool calls would wedge every later generate (providers demand tool
-    # results immediately after the assistant's tool_calls message).
+    # defer_transcript: the turn row carries the messages and the runner writes them at claim time.
+    # Required whenever an earlier turn may still be mid-flight — appending user rows behind
+    # unanswered tool calls would wedge every later generate.
     def stage_turn!(messages, definition: Xeno.definition, emit_received: true, defer_transcript: false)
       contents = Array(messages)
       transaction do
         unless defer_transcript
-          # Finding K: with_instructions triggers the first to_llm build; a
-          # fresh chat record must get its runtime options back first.
+          # with_instructions triggers the first to_llm build, so a fresh chat record must get its
+          # runtime options back first. nil clears: an agent whose instructions were removed sheds
+          # the stale system row.
           chat.apply_runtime_options!(definition.config.model_options)
-          resolved = definition.instructions_for(session: self)
-          chat.with_instructions(resolved) if resolved
+          chat.with_instructions(definition.instructions_for(session: self))
           contents.each { |content| chat.add_message(role: :user, content: content) }
         end
         turn = Turn.append!(self, user_message: { contents: contents }, transcript_deferred: defer_transcript)
@@ -78,19 +78,16 @@ module Xeno
       end
     end
 
-    # The channel entry point for follow-up messages. While a turn is active
-    # (one active turn per session) the message queues in pending_messages
-    # and is folded into the next turn; a PARKED session drains immediately
-    # (the message becomes a visible staged turn instead of sitting invisible
-    # until someone resolves the input — mvp-design's delivery semantics).
-    # An idle session stages and enqueues a turn right away.
+    # The channel entry point for follow-up messages. While a turn is active the message queues in
+    # pending_messages and folds into the next turn; a parked session drains immediately, so the
+    # message becomes a visible staged turn. An idle session stages and enqueues right away.
     def receive_message!(content)
-      if turns.where(status: %w[pending running waiting]).exists?
+      if turns.active.exists?
         transaction do
           pending_messages.create!(payload: { "content" => content })
           emit("message.received", { content: content, queued: true })
         end
-        drain_pending_messages! if reload.status == "waiting"
+        drain_pending_messages! if reload.waiting?
         nil
       else
         turn = stage_turn!(content)
@@ -99,13 +96,10 @@ module Xeno
       end
     end
 
-    # Folds every queued message into ONE next turn. Called when a turn
-    # parks or reaches a terminal status (and on messages to a parked
-    # session). Always defers the transcript: the drained turn may sit
-    # behind a parked turn whose tool calls are still unanswered, so its
-    # user rows are written only when the runner claims it — turn order and
-    # transcript order can never diverge. Row locks make a racing drain
-    # (park vs. incoming message) fold each message exactly once.
+    # Folds every queued message into one next turn, called when a turn parks or ends and on
+    # messages to a parked session. Always defers the transcript: the drained turn may sit behind
+    # unanswered tool calls, so its user rows are written only at claim — turn order and transcript
+    # order can never diverge. Row locks make a racing drain fold each message exactly once.
     def drain_pending_messages!(definition: Xeno.definition)
       turn = nil
       transaction do
@@ -119,19 +113,15 @@ module Xeno
       turn
     end
 
-    # Steering (opt-in per message): stop what the agent is doing and make
-    # THIS message the next turn. The active turn dies safely — a parked or
-    # pending turn settles its dangling tool calls (recorded answers
-    # injected, unapproved gates denied — the H1 machinery) and cancels
-    # immediately; a running turn cancels cooperatively (the steer message
-    # queues and the runner's cancel path folds it into the next turn at the
-    # next step boundary). If the cancel loses the race with a completing
-    # turn, steering degrades to a normal follow-up — never an error.
+    # Steering (opt-in per message): stop what the agent is doing and make this message the next
+    # turn. A parked or pending turn settles its dangling tool calls and cancels immediately; a
+    # running turn cancels cooperatively at the next step boundary. If the cancel loses the race
+    # with a completing turn, steering degrades to a normal follow-up — never an error.
     def steer!(content, definition: Xeno.definition)
-      turn = turns.where(status: %w[pending running waiting]).order(:sequence).first
+      turn = turns.active.order(:sequence).first
 
       case turn&.status
-      when nil # idle: steer is just a message
+      when nil # idle: steer degrades to a plain follow-up message
         staged = stage_turn!(content, definition: definition)
         staged.enqueue!
         staged
@@ -147,7 +137,7 @@ module Xeno
           settle_unanswered_tool_calls!(turn, reason: "steered by user")
           turn.update!(status: "cancelled")
           emit("turn.cancelled", { turn_id: turn.id, steer: true })
-          update!(status: "running") if status == "waiting"
+          update!(status: "running") if waiting?
         end
         staged = stage_turn!(content, definition: definition)
         staged.enqueue!
@@ -155,11 +145,9 @@ module Xeno
       end
     end
 
-    # Stages a compaction turn (summarize-and-replace, executed by the
-    # runner under a normal claim). It queues behind any active or parked
-    # turn via the ordinary session-ordering machinery — the
-    # queued-behind-the-active-turn semantics — and never appends a
-    # synthetic user message.
+    # Stages a compaction turn (summarize-and-replace, executed by the runner under a normal claim).
+    # It queues behind any active or parked turn via the ordinary session-ordering machinery and
+    # never appends a synthetic user message.
     def stage_compaction_turn!(reason:, used: nil, limit: nil)
       transaction do
         request = { "reason" => reason, "used" => used, "limit" => limit }.compact
@@ -174,13 +162,10 @@ module Xeno
       Event.append!(self, event_type, data)
     end
 
-    # Called before a turn dies with tool calls still unanswered (cancel
-    # while parked, schedule park failure): every dangling call gets a tool
-    # result in the transcript. Without this the assistant tool_call rows
-    # stay unanswered forever and every later generate is a provider 400 —
-    # the session is bricked. A completed action (e.g. an answered question
-    # whose resume never ran) injects its recorded output; everything else
-    # gets a denial, recorded on the action row as the audit trail.
+    # Called before a turn dies with tool calls still unanswered: every dangling call gets a tool
+    # result in the transcript. Without this the unanswered rows make every later generate a
+    # provider 400 and the session is bricked. A completed action injects its recorded output;
+    # everything else gets a denial, recorded on the action row.
     def settle_unanswered_tool_calls!(turn, reason:)
       chat_record = Chat.find(chat_id)
       llm = chat_record.to_llm
@@ -212,11 +197,11 @@ module Xeno
     end
 
     def active?
-      %w[running waiting].include?(status)
+      running? || waiting?
     end
 
-    # Terminal states release the continuation token (a finished session must
-    # not squat a channel thread's token); a copy stays in metadata for audit.
+    # Terminal states release the continuation token (a finished session must not squat a channel
+    # thread's token); a copy stays in metadata for audit.
     def finish!(new_status)
       raise ArgumentError, "not a terminal status: #{new_status}" unless %w[completed failed].include?(new_status)
 

data/app/models/xeno/turn.rb

@@ -1,29 +1,27 @@
+# frozen_string_literal: true
+
 module Xeno
-  # One user message and all work until the agent responds. Runs as one
-  # ActiveJob. Correctness lives here, in the database, not in the queue:
+  # One user message and all work until the agent responds, run as one ActiveJob. Correctness lives
+  # in these rows, not in the queue:
   #
-  # 1. Atomic claim (CAS on claim_token) — one worker owns the turn.
-  # 2. Heartbeat — the owner touches heartbeat_at at step boundaries; a
-  #    stale heartbeat lets the next attempt reclaim (checkpoint replay
-  #    makes takeover safe).
-  # 3. Fencing token — every write is conditioned on claim_token = mine, so
-  #    a zombie that wakes up after being reaped affects zero rows.
-  # 4. Max attempts — poison turns become turn.failed, not infinite retries.
+  # 1. Atomic claim (CAS on claim_token): one worker owns the turn.
+  # 2. Heartbeat: a stale heartbeat lets the next attempt reclaim;
+  #    checkpoint replay makes takeover safe.
+  # 3. Fencing token: every write is conditioned on claim_token = mine,
+  #    so a reaped zombie affects zero rows.
+  # 4. Max attempts: poison turns fail instead of retrying forever.
   class Turn < ApplicationRecord
-    STATUSES = %w[pending running waiting completed failed cancelled].freeze
-    KINDS = %w[message compaction].freeze
+    enum :status, %w[pending running waiting completed failed cancelled].index_with(&:itself), validate: true
+    enum :kind, %w[message compaction].index_with(&:itself), prefix: true, validate: true
 
     belongs_to :session, class_name: "Xeno::Session"
     has_many :actions, class_name: "Xeno::Action", dependent: :destroy
 
-    validates :status, inclusion: { in: STATUSES }
-    validates :kind, inclusion: { in: KINDS }
+    scope :active, -> { where(status: %w[pending running waiting]) }
 
-    # Appends the next turn to the session, sequence assigned race-safely.
-    # The INSERT runs in its own savepoint (requires_new): stage_turn! calls
-    # this inside a transaction, and on Postgres a failed INSERT otherwise
-    # aborts the whole transaction — the retry would raise
-    # PG::InFailedSqlTransaction instead of recovering.
+    # Appends the next turn with a race-safely assigned sequence. The INSERT runs in its own
+    # savepoint because stage_turn! calls this inside a transaction, and on Postgres a failed INSERT
+    # would otherwise abort the whole transaction.
     def self.append!(session, user_message:, transcript_deferred: false, kind: "message")
       attempts = 0
       begin
@@ -43,15 +41,13 @@ module Xeno
       TurnJob.perform_later(id)
     end
 
-    # The atomic claim. Returns the fencing token on success, nil when
-    # another worker owns the turn (exit quietly) or it isn't claimable.
-    # Claimable: pending, or running with a stale heartbeat (dead owner).
-    # Poison turns are failed here instead of retrying forever.
+    # The atomic claim. Returns the fencing token, or nil when another worker owns the turn or it
+    # isn't claimable. Claimable: pending, or running with a stale heartbeat. Poison turns fail here
+    # instead of retrying forever.
     #
-    # `attempts` counts FAILURES, not claims: a stale-running reclaim is
-    # crash evidence and counts here; a transient error counts in
-    # release_for_retry!; an approval/question resume counts in `resumes`
-    # and never against the poison ladder (H2).
+    # `attempts` counts failures, not claims: a stale-running reclaim is crash evidence and counts;
+    # a transient error counts in release_for_retry!; an approval or question resume counts in
+    # `resumes`, never against the poison ladder.
     def claim!
       current = self.class.find(id)
 
@@ -60,8 +56,8 @@ module Xeno
                        .where.not(status: %w[completed failed cancelled])
                        .update_all(status: "failed", error: { "message" => "max attempts (#{current.attempts}) exhausted" })
         if poisoned == 1
-          # A poisoned TURN leaves the SESSION running (idle, can take the
-          # next message); settle any dangling tool calls so it stays usable.
+          # A poisoned TURN leaves the SESSION running (idle, can take the next message); settle any
+          # dangling tool calls so it stays usable.
           session.settle_unanswered_tool_calls!(self, reason: "turn failed (max attempts exhausted)")
           session.emit("turn.failed", { turn_id: id, error: "max attempts exhausted" })
         end
@@ -72,7 +68,7 @@ module Xeno
       earlier_active = self.class
         .where(session_id: session_id)
         .where("sequence < ?", sequence)
-        .where(status: %w[pending running waiting])
+        .active
 
       claimed = self.class
         .where(id: id, claim_token: current.claim_token)
@@ -88,9 +84,8 @@ module Xeno
       claimed == 1 ? current.claim_token + 1 : nil
     end
 
-    # Transient failure: record the error, count the failure against the
-    # poison ladder, and hand the claim back (status pending) so the queue
-    # retry can claim immediately.
+    # Transient failure: record the error, count the failure against the poison ladder, and hand the
+    # claim back (status pending) so the queue retry can claim immediately.
     def release_for_retry!(token, error)
       current = self.class.find(id)
       fenced_update!(token,
@@ -99,8 +94,8 @@ module Xeno
         error: { "class" => error.class.name, "message" => error.message })
     end
 
-    # Fenced write: touches the heartbeat iff we still own the claim.
-    # Raises Xeno::Fenced when a zombie discovers it was reaped.
+    # Fenced write: touches the heartbeat iff we still own the claim. Raises Xeno::Fenced when a
+    # zombie discovers it was reaped.
     def heartbeat!(token)
       fenced_update!(token, heartbeat_at: Time.current)
     end

data/config/routes.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 Xeno::Engine.routes.draw do
   scope "v1" do
     get "health", to: "health#show"

data/db/migrate/{20260806000001_move_transcript_support_tables_to_ruby_llm.rb → 20260808000001_create_ruby_llm_tables.rb}

@@ -1,15 +1,16 @@
-# ruby_llm 2aaddf96: models, tool calls, usage, and batches become library
-# records on RubyLLM-owned ruby_llm_* tables (polymorphic toward the app's
-# chat/message classes); message rows stop carrying token/cost accounting
-# (the per-attempt ruby_llm_usage_entries ledger replaces it). Table shapes
-# mirror upstream's install templates.
-#
-# DESTRUCTIVE (pre-release, no installs to migrate): xeno_tool_calls and
-# xeno_models are dropped without moving their rows, and the accounting
-# columns on xeno_messages are removed with their data. Existing chats keep
-# their transcript text but lose tool-call linkage and usage history.
-class MoveTranscriptSupportTablesToRubyLlm < ActiveRecord::Migration[8.1]
+class CreateRubyLlmTables < ActiveRecord::Migration[8.1]
   def change
+    create_models
+    create_tool_calls
+    create_usage_entries
+    create_batches
+  end
+
+  private
+
+  def create_models
+    return if table_exists?(:ruby_llm_models)
+
     create_table :ruby_llm_models do |t|
       t.string :model_id, null: false
       t.string :name, null: false
@@ -29,6 +30,10 @@ class MoveTranscriptSupportTablesToRubyLlm < ActiveRecord::Migration[8.1]
       t.index :provider
       t.index :family
     end
+  end
+
+  def create_tool_calls
+    return if table_exists?(:ruby_llm_tool_calls)
 
     create_table :ruby_llm_tool_calls do |t|
       t.references :message, polymorphic: true, null: false, index: false
@@ -36,6 +41,7 @@ class MoveTranscriptSupportTablesToRubyLlm < ActiveRecord::Migration[8.1]
       t.string :tool_call_id, null: false
       t.string :name, null: false
       t.text :thought_signature
+      t.string :approval
       t.json :arguments, default: {}
       t.timestamps
 
@@ -44,6 +50,10 @@ class MoveTranscriptSupportTablesToRubyLlm < ActiveRecord::Migration[8.1]
       t.index :tool_call_id, unique: true
       t.index :name
     end
+  end
+
+  def create_usage_entries
+    return if table_exists?(:ruby_llm_usage_entries)
 
     create_table :ruby_llm_usage_entries do |t|
       t.references :chat, polymorphic: true, null: false, index: false
@@ -71,6 +81,10 @@ class MoveTranscriptSupportTablesToRubyLlm < ActiveRecord::Migration[8.1]
       t.check_constraint "operation IN ('chat', 'embedding', 'moderation', 'image', 'speech', 'transcription')"
       t.check_constraint "status IN ('pending', 'succeeded', 'failed', 'cancelled')"
     end
+  end
+
+  def create_batches
+    return if table_exists?(:ruby_llm_batches)
 
     create_table :ruby_llm_batches do |t|
       t.string :provider_batch_id, null: false
@@ -86,48 +100,5 @@ class MoveTranscriptSupportTablesToRubyLlm < ActiveRecord::Migration[8.1]
       t.index [ :provider, :provider_batch_id ], unique: true
       t.index :status
     end
-
-    # acts_as_chat hard-wires belongs_to :model with this foreign key.
-    # Upstream's fresh-install template makes it null: false; here it stays
-    # nullable because pre-existing xeno_chats rows have nothing to point at
-    # (the association is optional and resolve_model fills it on save).
-    add_reference :xeno_chats, :ruby_llm_model, foreign_key: { to_table: :ruby_llm_models }
-
-    remove_reference :xeno_messages, :tool_call, foreign_key: { to_table: :xeno_tool_calls }
-    remove_reference :xeno_messages, :model, foreign_key: { to_table: :xeno_models }
-    remove_reference :xeno_chats, :model, foreign_key: { to_table: :xeno_models }
-
-    remove_column :xeno_messages, :thinking_tokens, :integer
-    remove_column :xeno_messages, :input_tokens, :integer
-    remove_column :xeno_messages, :output_tokens, :integer
-    remove_column :xeno_messages, :cache_read_tokens, :integer
-    remove_column :xeno_messages, :cache_write_tokens, :integer
-    remove_column :xeno_messages, :total_cost, :decimal, precision: 16, scale: 10
-    remove_column :xeno_messages, :cost_details, :json
-
-    drop_table :xeno_tool_calls do |t|
-      t.string :tool_call_id, null: false
-      t.string :name, null: false
-      t.text :thought_signature
-      t.json :arguments, default: {}
-      t.references :message, null: false
-      t.timestamps
-    end
-
-    drop_table :xeno_models do |t|
-      t.string :model_id, null: false
-      t.string :name, null: false
-      t.string :provider, null: false
-      t.string :family
-      t.datetime :model_created_at
-      t.integer :context_window
-      t.integer :max_output_tokens
-      t.date :knowledge_cutoff
-      t.json :modalities, default: {}
-      t.json :capabilities, default: []
-      t.json :pricing, default: {}
-      t.json :metadata, default: {}
-      t.timestamps
-    end
   end
 end

data/db/migrate/{20260804000002_create_xeno_orchestration_tables.rb → 20260808000002_create_xeno_tables.rb}

@@ -1,18 +1,36 @@
-# The orchestration layer above the transcript: sessions, turns (claim/
-# heartbeat/fencing), actions (tool-call checkpoint + approval state),
-# events (the append-only session stream), pending messages (drained into
-# the next turn). Per spike #2 there is no steps table — a step's output
-# lives in xeno_messages/xeno_tool_calls.
-class CreateXenoOrchestrationTables < ActiveRecord::Migration[8.1]
+class CreateXenoTables < ActiveRecord::Migration[8.1]
   def change
+    create_table :xeno_chats do |t|
+      t.boolean :cancelled, null: false, default: false
+      t.references :ruby_llm_model, foreign_key: { to_table: :ruby_llm_models }
+      t.timestamps
+    end
+
+    create_table :xeno_messages do |t|
+      t.string :role, null: false
+      t.text :content
+      t.boolean :cache_until_here, null: false, default: false
+      t.text :thinking_text
+      t.text :thinking_signature
+      t.json :citations
+      t.json :server_tool_calls
+      t.json :raw_content
+      t.string :finish_reason
+      t.references :chat, null: false, foreign_key: { to_table: :xeno_chats }
+      t.timestamps
+
+      t.index :role
+    end
+
     create_table :xeno_sessions do |t|
       t.string :agent, null: false
-      t.string :status, null: false, default: "running" # running|waiting|completed|failed
+      t.string :status, null: false, default: "running"
       t.string :channel
       t.string :continuation_token
       t.string :title
       t.json :principal
       t.json :metadata, default: {}
+      t.json :state, null: false, default: {}
       t.references :chat, null: false, foreign_key: { to_table: :xeno_chats }
       t.timestamps
 
@@ -23,11 +41,14 @@ class CreateXenoOrchestrationTables < ActiveRecord::Migration[8.1]
     create_table :xeno_turns do |t|
       t.references :session, null: false, foreign_key: { to_table: :xeno_sessions }
       t.integer :sequence, null: false
-      t.string :status, null: false, default: "pending" # pending|running|waiting|completed|failed|cancelled
+      t.string :status, null: false, default: "pending"
+      t.string :kind, null: false, default: "message"
       t.integer :claim_token, null: false, default: 0
       t.datetime :heartbeat_at
       t.integer :attempts, null: false, default: 0
+      t.integer :resumes, null: false, default: 0
       t.integer :steps_count, null: false, default: 0
+      t.boolean :transcript_deferred, null: false, default: false
       t.json :user_message
       t.json :error
       t.timestamps
@@ -38,14 +59,14 @@ class CreateXenoOrchestrationTables < ActiveRecord::Migration[8.1]
 
     create_table :xeno_actions do |t|
       t.references :turn, null: false, foreign_key: { to_table: :xeno_turns }
-      t.string :tool_call_id, null: false # the provider call id (xeno_tool_calls.tool_call_id)
+      t.string :tool_call_id, null: false
       t.string :tool_name, null: false
-      t.string :kind, null: false, default: "tool" # tool|question
-      t.string :status, null: false, default: "pending" # pending|pending_approval|approved|denied|completed|failed
+      t.string :kind, null: false, default: "tool"
+      t.string :status, null: false, default: "pending"
       t.json :input
       t.json :output
-      t.datetime :resolved_at # when a human approved/denied/answered
-      t.json :resolved_by     # the resolving principal
+      t.datetime :resolved_at
+      t.json :resolved_by
       t.timestamps
 
       t.index [ :turn_id, :tool_call_id ], unique: true
@@ -53,7 +74,7 @@ class CreateXenoOrchestrationTables < ActiveRecord::Migration[8.1]
 
     create_table :xeno_events do |t|
       t.references :session, null: false, foreign_key: { to_table: :xeno_sessions }
-      t.integer :index, null: false # per-session cursor (SSE start_index)
+      t.integer :index, null: false
       t.string :event_type, null: false
       t.json :data
       t.datetime :created_at, null: false
@@ -66,5 +87,14 @@ class CreateXenoOrchestrationTables < ActiveRecord::Migration[8.1]
       t.json :payload, null: false
       t.timestamps
     end
+
+    create_table :xeno_dedups do |t|
+      t.string :scope, null: false
+      t.string :key, null: false
+      t.json :metadata
+      t.datetime :created_at, null: false
+
+      t.index [ :scope, :key ], unique: true
+    end
   end
 end