rubino-agent 0.3.0

data/lib/rubino/documents/registry.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Documents
+    # Ordered registry of document converters. Mirrors Tools::Registry's shape.
+    # Each converter is a class exposing instance methods:
+    #   accepts?(mime, path) -> Boolean   # by MIME first, extension as tie-break
+    #   available?           -> Boolean   # its optional gem is loadable (true for pure-ruby)
+    #   convert(path)        -> String    # the Markdown
+    #
+    # Order matters: more specific converters come before the plain-text
+    # catch-all so a .json routes to Json, not Plain. The registry never offers
+    # a converter whose optional gem can't load (#available?), so the caller's
+    # fall-through to the shell-hint is exercised when, e.g., `roo` is absent.
+    module Registry
+      module_function
+
+      # Converter classes in priority order. Trivial pure-ruby converters are
+      # always available; gem-backed ones (Xlsx/Docx/Pptx/Pdf) gate on their
+      # optional gem via #available?. Plain is the last-resort text passthrough.
+      def converters
+        [
+          Converters::Csv,
+          Converters::Json,
+          Converters::Xml,
+          Converters::Html,
+          Converters::Xlsx,
+          Converters::Docx,
+          Converters::Pptx,
+          Converters::Pdf,
+          Converters::Plain
+        ]
+      end
+
+      # Returns an instance of the first converter that accepts the pair AND is
+      # available in-process, or nil.
+      def for(mime: nil, path: nil)
+        converters.each do |klass|
+          conv = klass.new
+          return conv if conv.available? && conv.accepts?(mime, path)
+        end
+        nil
+      end
+
+      # The CORE format labels currently supported in-process (their gem is
+      # loadable). Drives the doctor / EnvironmentInspector advertising. Each
+      # entry is [label, available?]; pure-ruby formats are always available.
+      def capabilities
+        {
+          "plain/code" => Converters::Plain.new.available?,
+          "csv" => Converters::Csv.new.available?,
+          "json" => Converters::Json.new.available?,
+          "xml" => Converters::Xml.new.available?,
+          "html" => Converters::Html.new.available?,
+          "xlsx" => Converters::Xlsx.new.available?,
+          "docx" => Converters::Docx.new.available?,
+          "pptx" => Converters::Pptx.new.available?,
+          "pdf" => Converters::Pdf.new.available?
+        }
+      end
+
+      # Just the labels currently available, for a compact one-line advert.
+      def available_formats
+        capabilities.select { |_, ok| ok }.keys
+      end
+    end
+  end
+end

data/lib/rubino/documents/table.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Documents
+    # The ONE Markdown table emitter shared by the csv and xlsx converters (the
+    # reuse seam the plan calls for). Takes an array of rows (each an array of
+    # cell values) and emits a GFM pipe table: the first row is the header, a
+    # `|---|` separator follows, then the body. Pipes and newlines inside cells
+    # are escaped so a cell value can't break the table grid. Rows are capped so
+    # a runaway spreadsheet can't emit a million-line table into context.
+    module Table
+      module_function
+
+      # Hard cap on emitted body rows; over the cap we truncate and note it.
+      MAX_ROWS = 1000
+
+      # rows: Array<Array> -- first row is the header. Returns a GFM table
+      # String, or "" when there are no rows.
+      def emit(rows, max_rows: MAX_ROWS)
+        rows = Array(rows).compact
+        return "" if rows.empty?
+
+        width = rows.map { |r| Array(r).length }.max
+        return "" if width.nil? || width.zero?
+
+        header = pad(rows.first, width)
+        body   = rows.drop(1)
+        truncated = body.length > max_rows
+        body = body.first(max_rows) if truncated
+
+        lines = []
+        lines << row_line(header)
+        lines << separator(width)
+        body.each { |r| lines << row_line(pad(r, width)) }
+        out = lines.join("\n")
+        out += "\n\n_(#{rows.length - 1 - max_rows} more rows truncated)_" if truncated
+        out
+      end
+
+      def pad(row, width)
+        cells = Array(row).map { |c| cell(c) }
+        cells.fill("", cells.length...width)
+      end
+
+      def row_line(cells)
+        "| #{cells.join(" | ")} |"
+      end
+
+      def separator(width)
+        "|#{(["---"] * width).join("|")}|"
+      end
+
+      # Escapes a cell so pipes/newlines can't break the table. nil -> "".
+      def cell(value)
+        value.to_s
+             .gsub("\\", "\\\\\\\\")
+             .gsub("|", "\\|")
+             .gsub(/\r\n?|\n/, "<br>")
+             .strip
+      end
+    end
+  end
+end

data/lib/rubino/documents.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Rubino
+  # In-repo document-to-Markdown conversion -- a focused reimplementation of
+  # markitdown's CORE converters in pure Ruby (issue #6). The public surface is
+  # a single entry point:
+  #
+  #   Rubino::Documents.to_markdown(path, mime: nil) -> String | nil
+  #
+  # Architecture (mirrors markitdown): most converters extract structure via a
+  # mature MIT gem, shape it into an intermediate HTML string, and let ONE
+  # HTML->Markdown core (Documents::Html, built on kramdown which is already a
+  # rubino dependency) emit the final Markdown. csv/xlsx feed ONE Markdown table
+  # emitter (Documents::Table). The per-format converters are therefore thin.
+  #
+  # Extraction gems (roo, docx, pdf-reader, ruby_powerpoint) are OPTIONAL: each
+  # converter `require`s its gem lazily inside a begin/rescue LoadError and a
+  # converter that can't load its gem simply reports itself unavailable. The
+  # module MUST load and run with NONE of the optional gems installed -- callers
+  # then fall back to the existing shell-extraction hint. There is never an
+  # external process and never a hard runtime dependency. That is the whole
+  # point: the original concern was "markitdown isn't installed".
+  module Documents
+    module_function
+
+    # Converts the file at +path+ to Markdown, picking the first registered
+    # converter that accepts the (mime, path) pair and whose optional gem is
+    # loadable. Returns the Markdown String, or nil when no converter can handle
+    # the file (unknown format, or the format's optional gem isn't installed, or
+    # extraction produced nothing). Never raises -- a converter failure degrades
+    # to nil so the caller emits the actionable shell-hint.
+    def to_markdown(path, mime: nil)
+      converter = Registry.for(mime: mime, path: path)
+      return nil unless converter
+
+      out = converter.convert(path)
+      out = out.to_s
+      out.strip.empty? ? nil : out
+    rescue LoadError, StandardError
+      nil
+    end
+
+    # True when at least one converter for the (mime, path) pair is available
+    # in-process (its optional gem, if any, is loadable). Drives the preamble /
+    # environment / doctor advertising without attempting a conversion.
+    def supported?(mime: nil, path: nil)
+      !Registry.for(mime: mime, path: path).nil?
+    end
+  end
+end

data/lib/rubino/errors.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Rubino
+  # HTTP-boundary error hierarchy. Each class maps to a single HTTP status
+  # used by the API layer to translate exceptions to responses.
+  #
+  #   Rubino::Error                       — base class (defined in lib/rubino.rb)
+  #     NotFoundError(resource, id)          — 404
+  #     ValidationError(message, details:)   — 422
+  #     UnauthorizedError(message)           — 401
+  #     ConflictError(message)               — 409
+  #     UpstreamError(message, service:)     — 502
+  #
+  # All message-first classes accept `raise Class, "msg"` (Ruby's idiomatic
+  # form) without losing data. NotFoundError keeps its (resource, id) shape
+  # because the message format depends on both values; always use
+  # +raise NotFoundError.new("session", id)+, not +raise NotFoundError, "..."+.
+  #
+  # Domain errors (ConfigurationError, DatabaseError, SessionError, ToolError,
+  # CompactionError, JobError) also subclass Error and live in lib/rubino.rb.
+
+  # Resource not found. Maps to 404.
+  #
+  # @param resource [String, Symbol] resource type (e.g. "Session", :run)
+  # @param id [String, nil] identifier; when nil only the resource name is shown
+  #
+  # Footgun: `raise NotFoundError, "foo"` skips this initializer (Ruby passes
+  # the string straight to StandardError#initialize), so @resource/@id stay nil.
+  # Always use `raise NotFoundError.new("Session", id)` to capture them.
+  class NotFoundError < Error
+    def initialize(resource, id = nil)
+      msg = id ? "#{resource} not found: #{id}" : "#{resource} not found"
+      super(msg)
+      @resource = resource
+      @id = id
+    end
+    attr_reader :resource, :id
+  end
+
+  # Request body or params failed validation. Maps to 422.
+  class ValidationError < Error
+    def initialize(message = "validation failed", details: {})
+      super(message)
+      @details = details
+    end
+    attr_reader :details
+  end
+
+  # Missing or invalid credentials. Maps to 401.
+  class UnauthorizedError < Error
+    def initialize(message = "unauthorized")
+      super
+    end
+  end
+
+  # State conflict (duplicate, illegal transition). Maps to 409.
+  class ConflictError < Error
+    def initialize(message = "conflict")
+      super
+    end
+  end
+
+  # User interrupted an in-progress LLM turn (Esc / Ctrl+C in the chat TUI).
+  # Caught by the Loop/Lifecycle so partial content can still be persisted
+  # and the UI can return to a ready state cleanly.
+  class Interrupted < Error
+    def initialize(message = "interrupted by user")
+      super
+    end
+  end
+
+  # Request body exceeded the configured byte cap (JSON or multipart upload).
+  # Maps to 413. Details may carry +limit_bytes+ so clients can adapt.
+  class PayloadTooLargeError < Error
+    def initialize(message = "payload too large", details: {})
+      super(message)
+      @details = details
+    end
+    attr_reader :details
+  end
+
+  # Upstream dependency failed (LLM provider, OAuth provider). Maps to 502.
+  # Message-first so +raise UpstreamError, "timeout"+ works; pass +service:+
+  # to tag the failing dependency (it gets prefixed onto the message).
+  class UpstreamError < Error
+    def initialize(message = "upstream error", service: nil)
+      super(service ? "#{service}: #{message}" : message)
+      @service = service
+    end
+    attr_reader :service
+  end
+
+  # The LLM streaming response was cut before a clean completion: upstream closed
+  # the SSE connection without a terminal signal (no finish_reason / no [DONE] /
+  # null usage), leaving only a buffered partial with no tool call. Raised by the
+  # Loop so a truncated turn fails honestly (run.failed) instead of being reported
+  # as a successful "completed" turn carrying empty/partial output. Common trigger:
+  # a provider stream idle-timeout during a long time-to-first-token on a very
+  # large context. Maps to 502 (subclass of UpstreamError).
+  class StreamInterruptedError < UpstreamError
+    def initialize(message = "stream ended before completion", service: "llm")
+      super
+    end
+  end
+
+  # The model returned a degenerate turn — no text AND no tool calls — that
+  # survived the Loop's in-turn retries. Mirrors the reference treating an
+  # empty/invalid response as retryable-then-terminal (such a run is
+  # marked `failed: True`, not `completed`). Raised by Agent::Loop so
+  # the run is marked failed honestly instead of being reported as a successful
+  # "completed" turn carrying empty output (the silent completed-but-empty bug,
+  # observed on MiniMax-M2.7 / api.minimax.io/anthropic). Maps to 502.
+  class EmptyModelResponseError < UpstreamError
+    def initialize(message = "model returned an empty response (no text, no tool calls)",
+                   service: "llm")
+      super
+    end
+  end
+end

data/lib/rubino/files/workspace.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "fileutils"
+require "securerandom"
+
+module Rubino
+  module Files
+    # Sandboxed filesystem access for the agent. Every path coming in from
+    # the HTTP API (read, upload, etc.) must be resolved through #resolve so
+    # the result is guaranteed to live under @root.
+    #
+    # Root defaults to config.paths_home (the agent home); uploads are
+    # written under `<root>/uploads/`. The root is overridable in tests.
+    #
+    # Path-traversal defense:
+    # - Pathname#+ does not normalize: `Pathname.new("/a") + "/b"` returns
+    #   `/b`, so an attacker-supplied absolute path would silently escape.
+    # - We therefore call #expand_path on the joined path and then verify it
+    #   begins with `@root + File::SEPARATOR` (or equals @root). If not,
+    #   we raise Workspace::PathTraversal (a ValidationError subclass).
+    class Workspace
+      class PathTraversal < ::Rubino::ValidationError
+        def initialize(path)
+          super("path escapes workspace: #{path}")
+        end
+      end
+
+      def initialize(root: nil)
+        path = root || ::Rubino.configuration.paths_home
+        expanded = File.expand_path(path)
+        FileUtils.mkdir_p(expanded)
+        # Resolve symlinks (macOS' /tmp → /private/tmp is the usual offender)
+        # so #resolve compares apples to apples. Tools and AttachFileTool
+        # both call File.expand_path on their inputs, which follows OS
+        # symlinks; storing the raw configured root here would then make
+        # every absolute path under /tmp look like an escape, even though
+        # it really points inside the sandbox.
+        @root = Pathname.new(File.realpath(expanded))
+      end
+
+      attr_reader :root
+
+      # Resolves a relative path against the workspace root.
+      # Raises PathTraversal if the resolved path escapes the root.
+      def resolve(relative_path)
+        candidate = (@root + relative_path).expand_path
+        # If the candidate exists on disk, run it through realpath too so
+        # symlink components in the leading path don't make us reject a
+        # path that physically lives under @root. For paths that don't
+        # exist yet (the upload-create case) we keep the expand_path form
+        # — File.realpath would raise on a missing file.
+        candidate = Pathname.new(File.realpath(candidate.to_s)) if candidate.exist?
+
+        unless candidate.to_s.start_with?(@root.to_s + File::SEPARATOR) || candidate == @root
+          raise PathTraversal, relative_path
+        end
+
+        candidate
+      end
+
+      # Reads a file from the sandbox.
+      #
+      # @param relative_path [String] path relative to the workspace root
+      # @return [String] binary contents of the file
+      # @raise [Workspace::PathTraversal] if the path escapes the sandbox
+      # @raise [Rubino::NotFoundError] if no regular file exists at the path
+      def read(relative_path)
+        path = resolve(relative_path)
+        raise ::Rubino::NotFoundError.new("file", relative_path) unless path.file?
+
+        path.binread
+      end
+
+      # Stores an uploaded file under `uploads/<uuid>-<basename>`.
+      # The original filename is reduced to its basename before joining, so
+      # callers cannot influence the destination directory.
+      #
+      # @param filename [String] client-supplied name (basename only is kept)
+      # @param io [IO] readable stream containing the upload body
+      # @return [Hash] descriptor with keys :id, :filename, :size, :path
+      def upload(filename:, io:)
+        uploads_dir = @root + "uploads"
+        FileUtils.mkdir_p(uploads_dir)
+        safe_name = File.basename(filename.to_s)
+        id = SecureRandom.uuid
+        target = uploads_dir + "#{id}-#{safe_name}"
+        size = IO.copy_stream(io, target.to_s)
+        { id: id, filename: safe_name, size: size, path: target.to_s }
+      end
+    end
+  end
+end

data/lib/rubino/interaction/cancel_token.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Interaction
+    # Thread-safe cooperative cancellation flag passed through the interaction
+    # stack (Runner -> Lifecycle -> Loop -> LLM adapter). The chat TUI flips
+    # it on Esc / second Ctrl+C, and the LLM stream callback raises
+    # Rubino::Interrupted at the next chunk boundary so the turn aborts
+    # without leaking the worker thread or losing buffered output.
+    #
+    # Cancellation is one-shot: once cancelled, it stays cancelled. Build a
+    # fresh token per turn rather than reusing across turns.
+    #
+    # No Mutex on purpose. The flag is written exactly once (false -> true,
+    # never back) and only ever read otherwise — a single-writer, monotonic
+    # boolean. Under MRI's GVL a lone ivar read/write is atomic, so no lock
+    # is needed for correctness. Critically, #cancel! runs from a SIGINT
+    # +Signal.trap+ block, and +Mutex#lock+ is forbidden in a trap context
+    # (Ruby bug #14222: "can't be called from trap context"). A mutex here
+    # made the chat trap raise ThreadError, the flag never flipped, and the
+    # turn ran on. Keep this lock-free and trap-safe.
+    class CancelToken
+      def initialize
+        @cancelled = false
+      end
+
+      def cancel!
+        @cancelled = true
+      end
+
+      def cancelled?
+        @cancelled
+      end
+
+      # Raises Interrupted if the token has been cancelled. Used as a poll
+      # point inside hot loops (per-chunk in streams, per-iteration in the
+      # agent loop).
+      def check!
+        raise Rubino::Interrupted if cancelled?
+      end
+    end
+  end
+end

data/lib/rubino/interaction/clipboard_image.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+require "open3"
+
+module Rubino
+  module Interaction
+    # Grabs an image from the system clipboard and writes it to a temp PNG so it
+    # can be attached to a turn's image_paths (the native vision slot). Mirrors
+    # Claude Code's Cmd+V image paste from the terminal.
+    #
+    # Platform tools, best-effort and in priority order:
+    #   - macOS  : `pngpaste` (brew install pngpaste)
+    #   - Wayland: `wl-paste` (wl-clipboard)
+    #   - X11    : `xclip`
+    #
+    # Returns the temp file path on success, or nil when no tool is available or
+    # the clipboard holds no image. #unavailable_reason explains a nil so the CLI
+    # can show an actionable hint instead of a silent no-op.
+    module ClipboardImage
+      module_function
+
+      # Ordered [tool, argv-builder] candidates. The builder takes the dest path
+      # and returns the argv that writes a PNG of the clipboard image to it.
+      def commands(dest)
+        case RbConfig::CONFIG["host_os"]
+        when /darwin/
+          [["pngpaste", [dest]]]
+        when /linux/
+          [
+            ["wl-paste", ["-t", "image/png", "--no-newline"]], # writes to stdout
+            ["xclip", ["-selection", "clipboard", "-t", "image/png", "-o"]]
+          ]
+        else
+          []
+        end
+      end
+
+      # Saves the clipboard image to a temp PNG and returns its path, or nil.
+      def save_to_tempfile
+        dest = File.join(Dir.tmpdir, "rubino_clip_#{Process.pid}_#{rand(1_000_000)}.png")
+        capture(dest) ? dest : nil
+      end
+
+      # Runs the first available tool. macOS pngpaste writes the file directly;
+      # the Linux tools write PNG bytes to stdout which we redirect to +dest+.
+      def capture(dest)
+        commands(dest).each do |tool, args|
+          next unless which(tool)
+
+          if tool == "pngpaste"
+            _out, = Open3.capture2e(tool, *args)
+          else
+            out, status = Open3.capture2(tool, *args)
+            File.binwrite(dest, out) if status.success? && !out.empty?
+          end
+          return true if File.file?(dest) && File.size(dest).positive?
+        end
+        false
+      rescue StandardError
+        false
+      end
+
+      # Human-readable reason a paste produced nothing, for the CLI hint.
+      def unavailable_reason
+        case RbConfig::CONFIG["host_os"]
+        when /darwin/
+          "no image on the clipboard, or `pngpaste` isn't installed (brew install pngpaste)."
+        when /linux/
+          "no image on the clipboard, or neither `wl-paste` nor `xclip` is installed."
+        else
+          "clipboard image paste isn't supported on this platform."
+        end
+      end
+
+      def which(tool)
+        ENV["PATH"].to_s.split(File::PATH_SEPARATOR).any? do |dir|
+          path = File.join(dir, tool)
+          File.executable?(path) && !File.directory?(path)
+        end
+      end
+    end
+  end
+end

data/lib/rubino/interaction/event_bus.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Interaction
+    # Simple pub/sub event bus for decoupling core logic from UI.
+    # Core components emit events; UI adapters and other listeners subscribe.
+    #
+    # Thread-safety: subscriptions are mutated under a mutex, and `emit`
+    # snapshots the listener list under the lock then invokes listeners
+    # OUTSIDE the lock. This keeps concurrent `on`/`off` (e.g. a parent run's
+    # `recorder.detach!` racing a background subagent thread emitting
+    # SUBAGENT_COMPLETED onto the same bus — #136) from mutating the hash
+    # mid-iteration, while still allowing a listener to itself emit/subscribe
+    # without deadlocking.
+    class EventBus
+      def initialize
+        @listeners = Hash.new { |h, k| h[k] = [] }
+        @mutex = Mutex.new
+      end
+
+      # Subscribe to an event type with a callable or block
+      def on(event_type, &block)
+        @mutex.synchronize { @listeners[event_type.to_sym] << block }
+      end
+
+      # Emit an event to all registered listeners
+      def emit(event_type, **payload)
+        listeners = @mutex.synchronize { @listeners[event_type.to_sym].dup }
+        listeners.each { |listener| listener.call(payload) }
+      end
+
+      # Remove all listeners for a given event type
+      def off(event_type)
+        @mutex.synchronize { @listeners.delete(event_type.to_sym) }
+      end
+
+      # Remove all listeners
+      def clear!
+        @mutex.synchronize { @listeners.clear }
+      end
+
+      # Returns the count of listeners for a given event type
+      def listener_count(event_type)
+        @mutex.synchronize { @listeners[event_type.to_sym].size }
+      end
+    end
+  end
+end

data/lib/rubino/interaction/events.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Interaction
+    # Defines all event types used in the system.
+    # Acts as documentation and provides constants for event names.
+    module Events
+      # Interaction lifecycle events
+      INTERACTION_STARTED = :interaction_started
+      INTERACTION_FINISHED = :interaction_finished
+      INTERACTION_FAILED = :interaction_failed
+      # Mid-turn steering: the user typed while the agent was working and the
+      # loop picked the text up at an iteration boundary, injecting it as a
+      # user message into the in-flight turn (Codex "Enter injects into the
+      # current turn"). Payload: { text:, iteration: }.
+      INPUT_INJECTED = :input_injected
+
+      # Status change events
+      STATUS_CHANGED = :status_changed
+
+      # Session events
+      SESSION_LOADED = :session_loaded
+      SESSION_CREATED = :session_created
+      SESSION_PERSISTED = :session_persisted
+
+      # Memory events
+      MEMORY_LOADED = :memory_loaded
+      MEMORY_EXTRACTED = :memory_extracted
+      MEMORY_FLUSHED = :memory_flushed
+
+      # Context events
+      PROMPT_ASSEMBLED = :prompt_assembled
+      CONTEXT_BUDGET_CHECKED = :context_budget_checked
+
+      # Compression events
+      COMPRESSION_STARTED = :compression_started
+      COMPRESSION_FINISHED = :compression_finished
+
+      # LLM events
+      MODEL_CALL_STARTED = :model_call_started
+      MODEL_CALL_FINISHED = :model_call_finished
+      MODEL_STREAM = :model_stream
+      # End of one assistant message (content block). Streamed content deltas
+      # carry a +message_id+; this marks that block complete so a consumer can
+      # group the deltas that belong together instead of splitting them around
+      # tool calls that interleave mid-stream. Mirrors Anthropic's
+      # content_block_stop / the AI SDK text-end{id}.
+      MESSAGE_COMPLETED = :message_completed
+
+      # Tool events
+      TOOL_STARTED = :tool_started
+      # Incremental progress from a long-running tool (e.g. summarize_file's
+      # per-chunk "summarizing chunk N/M" or shell stdout lines). Emitted from
+      # the tool's stream_chunk callback so a tool that runs for minutes
+      # without finishing keeps the API event stream alive — the SSE idle
+      # watchdog only fires when NOTHING flows, so a genuinely hung run is
+      # still caught while a busy-but-silent one heartbeats. Payload:
+      # { name:, chunk: }.
+      TOOL_PROGRESS = :tool_progress
+      TOOL_FINISHED = :tool_finished
+      TOOL_APPROVAL_REQUESTED = :tool_approval_requested
+      TOOL_APPROVAL_GRANTED = :tool_approval_granted
+      TOOL_APPROVAL_DENIED = :tool_approval_denied
+
+      # Job events
+      JOB_ENQUEUED = :job_enqueued
+      JOB_STARTED = :job_started
+      JOB_FINISHED = :job_finished
+      JOB_FAILED = :job_failed
+      JOB_RETRYING = :job_retrying
+
+      # Background subagent (the `task` tool run in the background, the default).
+      # SPAWNED when a backgrounded subagent starts (payload: { task_id:,
+      # subagent:, prompt: }); COMPLETED/FAILED when it finishes (payload:
+      # { task_id:, subagent:, status:, output:|error: }). These let the CLI
+      # surface a completion line and the web UI show in-flight subagents —
+      # parity with how background-shell activity surfaces.
+      SUBAGENT_SPAWNED = :subagent_spawned
+      SUBAGENT_COMPLETED = :subagent_completed
+      SUBAGENT_FAILED = :subagent_failed
+
+      # Skill events
+      # Emitted when the `skill` tool successfully loads a skill's body into
+      # context (the level-2 "Skill 'X' loaded" path), so skill usage is a
+      # first-class signal for the recorder/SSE/metrics — parity with how
+      # TOOL_STARTED/SUBAGENT_* surface lifecycle. Payload: { name: } — the run
+      # association is stamped by the Recorder (run_id), like every other event.
+      SKILL_LOADED = :skill_loaded
+
+      # Emitted when a skill is created inline via skill(action: "create") or by
+      # the post-turn distill job. Payload: { name:, file_path: }.
+      SKILL_CREATED = :skill_created
+
+      # Artifact events
+      # Fired by tools that produce a downloadable user-facing file
+      # (currently AttachFileTool). Payload: { path:, filename:,
+      # content_type:, byte_size: }.
+      ARTIFACT_CREATED = :artifact_created
+    end
+  end
+end