rubino-agent 0.3.0

data/lib/rubino/interaction/image_input.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require_relative "../llm/content_builder"
+
+module Rubino
+  module Interaction
+    # Parses a raw CLI input line and pulls out image attachments so they can
+    # be routed to the model's native vision slot (image_paths) instead of being
+    # sent as literal text.
+    #
+    # Three input shapes are recognised, mirroring how Claude Code lets a user
+    # attach an image from the terminal:
+    #
+    #   1. `@path/to/pic.png` — the composer's `@` file-picker. When the picked
+    #      file is an image it becomes an attachment; a non-image `@file` is left
+    #      in the text untouched (the model reads it via the `read` tool, as
+    #      before).
+    #   2. A dropped / pasted file path — terminals insert an absolute path when
+    #      a file is dragged in, often single/double-quoted or backslash-escaped
+    #      for spaces. An image path (quoted, escaped or bare) is attached.
+    #
+    # Only paths that (a) have a recognised image extension AND (b) exist on disk
+    # are attached; anything else is preserved verbatim in the returned text so
+    # we never silently eat a word that merely looked path-ish.
+    #
+    # Every candidate attachment is then gated through the SAME secure-by-default
+    # attachment layer the server/run path uses (Attachments::Classify + Policy:
+    # lstat/realpath safety pipeline, max_file_bytes cap, magic-byte kind check)
+    # — the CLI used to bypass it entirely, shipping oversize/spoofed files to
+    # the provider and burning the retry budget on the permanent error (#98).
+    # A rejected candidate is consumed from the text and reported in
+    # Result#rejected so the caller can surface a clean one-line error.
+    #
+    # Returns a Result with the cleaned text (image tokens removed, whitespace
+    # collapsed), the de-duplicated, expanded absolute image paths in order, and
+    # any policy rejections as { path:, reason: } hashes.
+    module ImageInput
+      Result = Struct.new(:text, :image_paths, :rejected, keyword_init: true) do
+        def images? = !image_paths.empty?
+      end
+
+      # An `@token`: `@` followed by a run of non-space chars. Quoting inside an
+      # `@` token isn't a terminal convention, so we keep it simple.
+      AT_TOKEN = /(?<![^\s])@(\S+)/
+
+      # A quoted path: '...' or "..." (drag-drop on terminals that quote).
+      QUOTED_PATH = /(?<![^\s])(?:'([^']+)'|"([^"]+)")/
+
+      # A bare / backslash-escaped path token: a leading /, ./, ../ or ~/ then a
+      # run of non-space chars, allowing `\ ` escaped spaces (drag-drop default
+      # on iTerm/Terminal.app). Anchored at a word boundary so it doesn't bite
+      # into the middle of a URL or sentence.
+      BARE_PATH = %r{(?<![^\s])((?:~|\.{0,2})/(?:\\.|\S)+)}
+
+      module_function
+
+      # Extracts image attachments from +input+. +existing+ lets a caller carry
+      # forward images already attached to the pending turn (e.g. a clipboard
+      # paste) so a follow-up line's parse adds to them rather than replacing.
+      def parse(input, existing: [])
+        text = input.to_s
+        paths = []
+        rejected = []
+
+        text = text.gsub(AT_TOKEN) { capture_if_image(Regexp.last_match(1), Regexp.last_match(0), paths, rejected) }
+        text = text.gsub(QUOTED_PATH) do
+          token = Regexp.last_match(1) || Regexp.last_match(2)
+          capture_if_image(token, Regexp.last_match(0), paths, rejected)
+        end
+        text = text.gsub(BARE_PATH) { capture_if_image(Regexp.last_match(1), Regexp.last_match(0), paths, rejected) }
+
+        Result.new(
+          text: text.gsub(/[ \t]{2,}/, " ").strip,
+          image_paths: (Array(existing) + paths).uniq,
+          rejected: rejected.uniq
+        )
+      end
+
+      # If +token+ resolves to an existing image file, record its absolute path
+      # and drop it from the text (returns ""); otherwise leave the original
+      # match (+original+) untouched. +original+ is captured by the caller before
+      # any path work, because #expand runs its own gsub and would clobber
+      # Regexp.last_match here. A candidate that LOOKS like an image but fails
+      # the attachment policy is consumed too — never shipped, never left as a
+      # path the model would chase with tools — and recorded in +rejected+.
+      def capture_if_image(token, original, paths, rejected)
+        path = expand(token)
+        return original unless LLM::ContentBuilder.image_file?(path) && File.file?(path)
+
+        if (reason = attachment_error(path))
+          rejected << { path: path, reason: reason }
+        else
+          paths << path unless paths.include?(path)
+        end
+        ""
+      end
+
+      # Gates one candidate image through the universal attachment layer —
+      # Attachments::Classify (lstat/realpath safety pipeline, max_file_bytes
+      # cap, magic-byte classification) + Policy.allow_kind? — the SAME checks
+      # the server/run path applies (#98). Returns a one-line human reason when
+      # the file must NOT be attached, nil when it is safe to send.
+      def attachment_error(path)
+        cls = Attachments::Classify.call(path)
+        unless cls.safe
+          if cls.reason.to_s.start_with?("exceeds max_file_bytes")
+            return "exceeds the #{Attachments::Policy.max_file_bytes / 1_048_576} MB attachment limit"
+          end
+
+          return cls.reason
+        end
+        return "not a valid image (content is #{cls.mime})" unless cls.kind == :image
+        return "image attachments are disabled by policy (allow_kinds)" unless Attachments::Policy.allow_kind?(:image)
+
+        nil
+      end
+
+      # Normalises a raw token into an absolute filesystem path: strips
+      # backslash escapes (`\ ` → ` `) and expands `~`/relative paths.
+      def expand(token)
+        File.expand_path(token.to_s.gsub(/\\(.)/, '\1'))
+      rescue ArgumentError
+        token.to_s
+      end
+    end
+  end
+end

data/lib/rubino/interaction/input_queue.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Interaction
+    # Thread-safe hand-off of typed-while-busy input to the REPL loop.
+    #
+    # The chat REPL runs one turn synchronously while a background reader
+    # thread keeps accepting keystrokes from the TTY (see
+    # CLI::ChatCommand#run_turn). Each completed line the reader sees is
+    # +push+-ed here; when the turn returns, the REPL +drain+s the queue and
+    # the captured lines become the NEXT user turn — never injected mid-tool.
+    #
+    # Mirrors Run::ApprovalGate's idiom: a plain +::Queue+ guarded by a
+    # +Mutex+ for the multi-line snapshot. Two threads touch it — the reader
+    # (push) and the main loop (drain/pending?) — so every read of the
+    # backing queue happens under the lock to keep +drain+ and +pending?+
+    # consistent against a concurrent +push+.
+    class InputQueue
+      def initialize
+        # An Array (under @mutex) rather than ::Queue: B4 consumes ONE line at a
+        # time (FIFO) and an interrupt line must be able to JUMP ahead of items
+        # explicitly parked earlier in the same turn (#push_front), neither of
+        # which ::Queue supports. The mutex still serialises the reader (push)
+        # against the main loop (shift/drain/pending?).
+        @lines   = []
+        # Deterministic background notices (#push_notice) are held apart from
+        # typed lines: #shift never returns them, so a parked notice can't fire
+        # a standalone model turn at the idle prompt (#13).
+        @notices = []
+        @mutex   = Mutex.new
+      end
+
+      # Records one completed line typed during the turn. Blank/nil lines are
+      # dropped so a stray Enter doesn't manufacture an empty next turn.
+      def push(line)
+        text = normalize(line)
+        return if text.nil?
+
+        @mutex.synchronize { @lines.push(text) }
+      end
+
+      # Records a line at the FRONT of the queue so it is the NEXT one #shift
+      # returns. Used by the interrupt-by-default Enter: the just-submitted line
+      # runs immediately next, AHEAD of any items the user explicitly parked
+      # (Alt+Enter / "/queued") earlier in the same turn, which then run in
+      # their own order behind it.
+      def push_front(line)
+        text = normalize(line)
+        return if text.nil?
+
+        @mutex.synchronize { @lines.unshift(text) }
+      end
+
+      # Records a deterministic background notice (the `[background-task] …
+      # completed/failed/stopped` lines). Notices are NOT user turns: #shift
+      # never returns them, so at the idle prompt a notice doesn't spend a
+      # whole model turn just to restate itself (#13). It rides along on the
+      # NEXT real turn instead — #drain (mid-turn steering boundary) and
+      # #drain_notices (turn start) both deliver it.
+      def push_notice(line)
+        text = normalize(line)
+        return if text.nil?
+
+        @mutex.synchronize { @notices.push(text) }
+      end
+
+      # Removes and returns the OLDEST queued line (FIFO), or nil when empty.
+      # The REPL consumes one queued message per turn so several lines parked
+      # during one turn each run as their OWN turn, in submission order (B4) —
+      # instead of #drain coalescing them into a single newline-joined message.
+      # Atomic against a concurrent #push.
+      def shift
+        @mutex.synchronize { @lines.shift }
+      end
+
+      # Removes and returns every queued line, in arrival order — parked
+      # background notices first, then typed lines. Empty when nothing is
+      # waiting. Atomic against a concurrent #push.
+      def drain
+        @mutex.synchronize do
+          lines    = @notices + @lines
+          @notices = []
+          @lines   = []
+          lines
+        end
+      end
+
+      # Removes and returns only the parked background notices. The turn-START
+      # injection (Loop, iteration 1) folds notices into the turn the user just
+      # submitted without consuming their typed-ahead lines, which must keep
+      # running as their own turns (#13).
+      def drain_notices
+        @mutex.synchronize do
+          notices  = @notices
+          @notices = []
+          notices
+        end
+      end
+
+      # True when at least one line or notice is waiting to be drained.
+      def pending?
+        @mutex.synchronize { !@lines.empty? || !@notices.empty? }
+      end
+
+      private
+
+      # Normalizes a pushed line: nil → nil; blank → nil (dropped so a stray
+      # Enter never manufactures an empty turn); else the stringified line.
+      def normalize(line)
+        return nil if line.nil?
+
+        text = line.to_s
+        text.strip.empty? ? nil : text
+      end
+    end
+  end
+end

data/lib/rubino/interaction/lifecycle.rb

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Interaction
+    # Orchestrates the full lifecycle of a single user interaction.
+    # Coordinates all phases from input to final response and post-turn jobs.
+    class Lifecycle
+      def initialize(session:, event_bus:, ui:, config:, ignore_rules: false,
+                     agent_definition: nil, cancel_token: nil,
+                     model_override: nil, provider_override: nil,
+                     max_tool_iterations: nil)
+        @session = session
+        @event_bus = event_bus
+        @ui = ui
+        @config = config
+        @ignore_rules = ignore_rules
+        @agent_definition = agent_definition
+        @cancel_token = cancel_token
+        @model_override = model_override
+        @provider_override = provider_override
+        # Explicit per-run cap from `--max-turns` (Runner → here → IterationBudget).
+        # nil ⇒ use the configured agent_max_tool_iterations (#141).
+        @max_tool_iterations = max_tool_iterations
+        @state = State.new
+        @session_repo = Session::Repository.new
+        @message_store = Session::Store.new
+      end
+
+      # Executes the full interaction lifecycle for a user input.
+      # image_paths are vision-capable attachments routed natively to the
+      # primary model (ruby_llm `with:` slot); only consumed on the first
+      # iteration of the inner agent loop. Subsequent iterations carry tool
+      # results, not user input, and don't re-attach the images.
+      # +input_queue+ is the optional steering hand-off (Interaction::InputQueue)
+      # for mid-turn injection: when given, the inner agent loop drains any text
+      # the user typed while it was working and folds it into the turn at a safe
+      # iteration boundary. Nil for the API/server path and for nested SUBAGENT
+      # runs, which stay isolated — no user injection, exactly as before.
+      def execute(input, image_paths: [], input_queue: nil, paste_expansions: [])
+        @event_bus.emit(Events::INTERACTION_STARTED, input: input)
+        @state.transition_to!(:receiving_input, event_bus: @event_bus)
+
+        # 1. Persist user message
+        @state.transition_to!(:loading_session, event_bus: @event_bus)
+        persist_user_message(input, paste_expansions: paste_expansions)
+
+        # 2. Load memory (if enabled)
+        @state.transition_to!(:loading_memory, event_bus: @event_bus)
+        memory_context = load_memory(input)
+
+        # 3. Build prompt/context
+        @state.transition_to!(:building_context, event_bus: @event_bus)
+        messages = build_messages(input, memory_context)
+        tools = load_tools
+
+        # 4. Check token budget
+        @state.transition_to!(:checking_budget, event_bus: @event_bus)
+        messages = check_and_compact(messages)
+
+        # 5. Run agent loop
+        @state.transition_to!(:calling_model, event_bus: @event_bus)
+        response = run_agent_loop(messages, tools, image_paths: image_paths,
+                                                   input_queue: input_queue)
+
+        # 6. Persist session state
+        @state.transition_to!(:persisting_session, event_bus: @event_bus)
+        update_session_state
+
+        # 7. Enqueue post-turn jobs
+        @state.transition_to!(:enqueueing_jobs, event_bus: @event_bus)
+        enqueue_post_turn_jobs
+
+        # 8. Finish
+        # Carry the final assistant text as the terminal event's authoritative
+        # output, regardless of streaming mode. Streaming consumers also receive
+        # it incrementally via MODEL_STREAM (message.delta), but the
+        # non-streaming path emits no deltas — so without this, a completed run
+        # would terminate with no final text for clients to display. This makes
+        # run.completed the single source of truth for the answer.
+        @state.transition_to!(:finished, event_bus: @event_bus)
+        @event_bus.emit(Events::INTERACTION_FINISHED, output: response.to_s)
+
+        response
+      rescue StandardError => e
+        @state.transition_to!(:failed, event_bus: @event_bus)
+        @event_bus.emit(Events::INTERACTION_FAILED, error: e.message)
+        raise
+      end
+
+      private
+
+      def persist_user_message(input, paste_expansions: [])
+        # Lazily insert the session row on the first real message (#144). A
+        # session built by the CLI stays in-memory until now, so opening `chat`
+        # and exiting without sending anything never persists an empty row. The
+        # message table has a session_id FK, so the row must exist first.
+        @session_repo.persist!(@session)
+
+        # Persist the user's message verbatim. Image attachments are owned by
+        # the image_paths pipeline (Executor -> Runner -> Loop), routed natively
+        # to the model; we must not strip paths out of the stored/sent text.
+        # +input+ keeps any compact "[Pasted text #N …]" placeholder so the
+        # transcript echo stays clean on resume (#213); the matching expansion
+        # bodies ride as metadata and are folded into the model-facing content
+        # by Message#to_context, so the model still sees the full paste.
+        attrs = { session_id: @session[:id], role: "user", content: input }
+        attrs[:metadata] = { paste_expansions: paste_expansions } unless paste_expansions.empty?
+        @message_store.create(**attrs)
+        @session_repo.increment_message_count!(@session[:id])
+        maybe_set_title(input)
+      end
+
+      # Auto-title a still-untitled session from its first user message (#103),
+      # so `/sessions` is navigable and `--resume <title>` can match. Cheap and
+      # deterministic (no model call). Set once: any session that already has a
+      # title is left alone. Title failures must never break the turn.
+      def maybe_set_title(input)
+        return if @session[:title] && !@session[:title].to_s.strip.empty?
+
+        title = Session::Repository.derive_title(input)
+        return unless title
+
+        @session_repo.update(@session[:id], title: title)
+        @session[:title] = title
+      rescue StandardError
+        nil
+      end
+
+      def load_memory(query = nil)
+        return {} unless @config.memory_enabled?
+
+        # Route through the configured backend. `query` (the current user
+        # message) lets a relevance-aware backend rank recall; the default
+        # backend ignores it and returns "everything that fits", as before.
+        backend = Memory::Backends.build(config: @config)
+        {
+          user_profile: backend.user_profile,
+          project_context: backend.project_context,
+          relevant_memories: backend.retrieve(session_id: @session[:id], query: query)
+        }
+      rescue StandardError
+        {} # Don't fail the interaction if memory loading fails
+      end
+
+      def build_messages(_input, memory_context)
+        assembler = Context::PromptAssembler.new(
+          session: @session,
+          memory_context: memory_context,
+          config: @config,
+          agent_definition: @agent_definition,
+          ignore_rules: @ignore_rules
+        )
+        assembler.build
+      end
+
+      def load_tools
+        return [] if @config.agent_disabled_toolsets.include?("all")
+
+        # Honor the agent definition's tool restrictions (:all, :read_only, or
+        # an explicit list). Falls back to all enabled tools when no definition
+        # is present (e.g. one-shot CLI calls without an explicit agent).
+        if @agent_definition
+          @agent_definition.resolved_tools
+        else
+          Tools::Registry.instance.enabled_tools
+        end
+      end
+
+      def check_and_compact(messages)
+        budget = Context::TokenBudget.new(
+          model_id: @session[:model],
+          config: @config
+        )
+
+        if budget.needs_compaction?(messages)
+          @state.transition_to!(:compressing_context, event_bus: @event_bus)
+          @ui.compression_started
+          @event_bus.emit(Events::COMPRESSION_STARTED, session_id: @session[:id])
+
+          compressor = Context::Compressor.new(session_id: @session[:id])
+          result = compressor.compact!
+
+          @event_bus.emit(Events::COMPRESSION_FINISHED, **result)
+          @ui.compression_finished(result)
+
+          # Reload messages after compaction
+          assembler = Context::PromptAssembler.new(
+            session: @session,
+            memory_context: {},
+            config: @config,
+            agent_definition: @agent_definition,
+            ignore_rules: @ignore_rules
+          )
+          assembler.build
+        else
+          messages
+        end
+      end
+
+      def run_agent_loop(messages, tools, image_paths: [], input_queue: nil)
+        tool_executor = Agent::ToolExecutor.new(
+          registry: Tools::Registry.instance,
+          approval_policy: Security::ApprovalPolicy.new,
+          ui: @ui,
+          config: @config,
+          cancel_token: @cancel_token,
+          # SESSION-scoped read-before-edit tracker (#151): a read in an
+          # earlier turn of this session still satisfies the gate while the
+          # file's mtime is unchanged, so an edit in the next turn doesn't
+          # force a redundant re-read + a second approval round-trip. The
+          # gate itself still re-prompts on any on-disk change.
+          read_tracker: Tools::ReadTracker.for_session(@session[:id]),
+          event_bus: @event_bus
+        )
+
+        # Dispatch through AdapterFactory so a "fake/..." model id (or an
+        # explicit provider: "fake") short-circuits to FakeProvider; every
+        # other model stays on RubyLLMAdapter unchanged.
+        #
+        # Per-run model/provider overrides win over the session defaults so
+        # the HTTP API client can pin a specific FakeProvider scenario (e.g.
+        # "fake/with-approvals") on an existing session without having to
+        # mutate the persisted session row.
+        llm_adapter = LLM::AdapterFactory.build(
+          model_id: @model_override || @session[:model],
+          provider: @provider_override || @config.model_provider,
+          ui: @ui,
+          event_bus: @event_bus,
+          tool_executor: tool_executor,
+          cancel_token: @cancel_token
+        )
+
+        budget = Agent::IterationBudget.new(config: @config, max_tool_iterations: @max_tool_iterations)
+
+        loop_runner = Agent::Loop.new(
+          session: @session,
+          llm_adapter: llm_adapter,
+          tool_executor: tool_executor,
+          message_store: @message_store,
+          budget: budget,
+          ui: @ui,
+          event_bus: @event_bus,
+          config: @config,
+          cancel_token: @cancel_token,
+          initial_image_paths: image_paths,
+          input_queue: input_queue
+        )
+
+        # Bind the parent's steering queue as the background-subagent
+        # notification sink for the duration of this turn. A backgrounded `task`
+        # subagent pushes its completion notice onto this same queue, so the
+        # parent loop folds it in at its next iteration boundary
+        # (Loop#inject_steered_input) — correct ordering for free. Nil queue
+        # (API/server) ⇒ no sink; the result stays reachable via `task_result`.
+        Rubino.with_background_sink(input_queue) do
+          Rubino.with_event_bus(@event_bus) do
+            loop_runner.run(messages: messages, tools: tools)
+          end
+        end
+      end
+
+      def update_session_state
+        token_count = @message_store.token_sum(@session[:id])
+        @session_repo.update_token_count!(@session[:id], token_count)
+        @session_repo.increment_message_count!(@session[:id])
+      end
+
+      def enqueue_post_turn_jobs
+        queue = Jobs::Queue.new
+
+        # Extract memory if enabled
+        if @config.memory_auto_extract?
+          queue.enqueue("ExtractMemoryJob", { session_id: @session[:id] })
+          @event_bus.emit(Events::JOB_ENQUEUED, type: "ExtractMemoryJob")
+        end
+
+        # Variant B — deterministic post-turn skill distillation. Gated exactly
+        # like ExtractMemoryJob above: a dedicated config predicate guards the
+        # enqueue so this aux-spending background job only runs when explicitly
+        # enabled (skills.auto_distill, default true). The job then applies its
+        # own deterministic gate (run succeeded AND >= N tool calls AND not
+        # already covered) before spending one aux-model call. Handler lookup
+        # is load-order independent: Jobs::Registry resolves the class from
+        # the Handlers namespace on demand (#81).
+        if @config.skills_auto_distill?
+          queue.enqueue("DistillSkillJob", { session_id: @session[:id] })
+          @event_bus.emit(Events::JOB_ENQUEUED, type: "DistillSkillJob")
+        end
+
+        # Summarize if session is getting long
+        message_count = @message_store.count(@session[:id])
+        return unless message_count > 20
+
+        queue.enqueue("SummarizeSessionJob", { session_id: @session[:id] })
+        @event_bus.emit(Events::JOB_ENQUEUED, type: "SummarizeSessionJob")
+      end
+    end
+  end
+end

data/lib/rubino/interaction/probe.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Interaction
+    # An ephemeral, read-only side-question against the CURRENT session.
+    #
+    # `probe` is the principal-chat counterpart of the subagent-level probe:
+    # it answers a lateral question from the session's context-so-far and then
+    # VANISHES — neither the question nor the answer is written to the session
+    # transcript, so the next real turn proceeds exactly as if it never happened
+    # (Claude Code's `/btw` semantics).
+    #
+    # Reuse, not reinvention:
+    #   - Context::PromptAssembler.build gives the SAME message array a real
+    #     turn would send (system + summary + history snapshot). We append the
+    #     question as a final user message and call the adapter ONCE.
+    #   - LLM::AdapterFactory.build(...).chat(messages:, tools: nil) is the
+    #     existing one-shot completion seam — no Loop, no tools, no persistence.
+    #
+    # Nothing here touches Session::Store, so the probe is screen-only: the only
+    # artifact is the dim aside the CLI renders.
+    class Probe
+      Result = Struct.new(:question, :answer, keyword_init: true)
+
+      def initialize(session:, config: Rubino.configuration, model_override: nil,
+                     provider_override: nil)
+        @session           = session
+        @config            = config
+        @model_override    = model_override
+        @provider_override = provider_override
+      end
+
+      # Runs the one-shot side-inference over a SNAPSHOT of the session and the
+      # question. Returns a Result(question:, answer:). Read-only: the session's
+      # message store is never written.
+      def ask(question)
+        messages = snapshot_messages
+        messages << { role: "user", content: question }
+
+        adapter  = LLM::AdapterFactory.build(
+          model_id: @model_override || @session[:model],
+          provider: @provider_override || @config.model_provider,
+          config: @config
+        )
+        response = adapter.chat(messages: messages, tools: nil)
+
+        Result.new(question: question, answer: response.content.to_s)
+      end
+
+      private
+
+      # The exact message array a real turn would assemble for this session —
+      # system prompt + summary + the full history so far — minus the new turn.
+      # Memory context is left empty: a probe is a quick aside, and skipping the
+      # memory snapshot keeps it cheap and side-effect-free.
+      def snapshot_messages
+        Context::PromptAssembler.new(
+          session: @session,
+          memory_context: {},
+          config: @config
+        ).build
+      end
+    end
+  end
+end

data/lib/rubino/interaction/state.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Interaction
+    # Tracks the current state of an interaction.
+    # Implements a simple state machine with valid transitions.
+    class State
+      VALID_STATES = %i[
+        idle
+        receiving_input
+        loading_session
+        loading_memory
+        building_context
+        checking_budget
+        compressing_context
+        calling_model
+        persisting_session
+        enqueueing_jobs
+        finished
+        failed
+      ].freeze
+
+      attr_reader :current
+
+      def initialize
+        @current = :idle
+      end
+
+      # Transitions to a new state, emitting an event
+      def transition_to!(new_state, event_bus: nil)
+        raise Error, "Invalid state: #{new_state}" unless VALID_STATES.include?(new_state)
+
+        old_state = @current
+        @current = new_state
+
+        event_bus&.emit(Events::STATUS_CHANGED, from: old_state, to: new_state)
+      end
+
+      def idle?
+        @current == :idle
+      end
+
+      def finished?
+        @current == :finished
+      end
+
+      def failed?
+        @current == :failed
+      end
+
+      def terminal?
+        finished? || failed?
+      end
+    end
+  end
+end