insika 0.0.1 → 0.2.0

data/lib/insika/profile_source.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Insika
+  # Source of AgentProfiles. Profiles used to be
+  # a FROZEN Hash injected into the Executor and the turn Commands — static,
+  # defined in Ruby at wiring time. For the Studio to create/edit agents at
+  # runtime, the source needs to be MUTABLE and reloadable, without changing the
+  # consumption contract.
+  #
+  # The consumption contract is minimal and duck-typed: `source[id] -> AgentProfile|nil`
+  # (like a Hash). That's why the refactor in the Executor/Commands is just
+  # normalizing the input (legacy Hash -> StaticProfileSource); the bodies that do
+  # `@profiles[agent]` stay identical. `all`/`ids` are for the Studio to list.
+  #
+  # `nil` from `[]`/`fetch` = agent not configured (the Commands raise
+  # NotFoundError) — NEVER raises (unlike Hash#fetch).
+  module ProfileSource
+    # Hash-compat sugar: `source[id]`.
+    def [](id) = fetch(id)
+
+    # Normalizes the consumers' input: a legacy Hash becomes a StaticProfileSource;
+    # a ProfileSource passes straight through. A single place for the compat seam.
+    def self.coerce(profiles)
+      return profiles if profiles.is_a?(ProfileSource)
+
+      StaticProfileSource.new(profiles || {})
+    end
+
+    # subclasses implement: fetch(id) -> AgentProfile|nil, all -> [AgentProfile], ids -> [String]
+  end
+
+  # Static source (parity): wraps the usual {id => AgentProfile} Hash.
+  # Behavior IDENTICAL to the frozen Hash — zero regression.
+  class StaticProfileSource
+    include ProfileSource
+
+    def initialize(profiles = {})
+      @profiles = profiles
+    end
+
+    def fetch(id) = @profiles[id]
+    def all = @profiles.values
+    def ids = @profiles.keys
+  end
+
+  # Persisted source (Studio): reads/writes profiles in the ConfigStore (scope "agents").
+  # Each `fetch` reads FRESH from the store — an edit via the Studio takes effect on
+  # the next dispatch, without a restart. An in-flight turn keeps the profile it
+  # captured (the Commands resolve at the start of #call), so the turn semantics are
+  # preserved.
+  class StoredProfileSource
+    include ProfileSource
+    include Coercion
+
+    SCOPE = "agents"
+
+    def initialize(config_store:)
+      @cs = config_store
+    end
+
+    def fetch(id)
+      record = @cs.get(SCOPE, id.to_s)
+      record && deserialize(record)
+    end
+
+    def all = @cs.all(SCOPE).map { |r| deserialize(r) }
+    def ids = @cs.keys(SCOPE)
+
+    # Write (used by the :create_agent/:update_agent Commands).
+    def put(profile)
+      @cs.put(SCOPE, profile.id, profile.to_h)
+      profile
+    end
+
+    def delete(id) = @cs.delete(SCOPE, id.to_s)
+
+    private
+
+    # Rebuilds the AgentProfile from the record (the JSON round-trip turns symbols
+    # into strings). Re-symbolizes the fields the runtime consumes as symbols:
+    # provider, policies (names in the PolicyRegistry) and the limits keys (
+    # DEFAULT_LIMITS uses symbols and the merge would break with string keys).
+    def deserialize(record)
+      h = symbolize_top(record)
+      AgentProfile.build(
+        id: h[:id], model: h[:model],
+        provider: presence(h[:provider])&.to_sym,
+        base_prompt: h[:base_prompt].to_s,
+        prompt_files: h[:prompt_files] || [],
+        tools_allow: h[:tools_allow], tools_deny: h[:tools_deny] || [],
+        tools_allow_groups: h[:tools_allow_groups],
+        skills: h[:skills],
+        skills_eager: h[:skills_eager],
+        context_providers: h[:context_providers],
+        workflows_allow: h[:workflows_allow],
+        policies: Array(h[:policies]).map(&:to_sym),
+        prompt_refs: h[:prompt_refs] || [],
+        limits: symbolize_limits(h[:limits]),
+        approvals_required: h[:approvals_required],
+        capabilities: h[:capabilities],
+        # subagents: allowlist of child ids; build re-normalizes to
+        # [String]. nil round-trips as nil (opt-in: NONE).
+        subagents: h[:subagents],
+        tools_deferred: h[:tools_deferred],
+        memory: h[:memory],
+        prompt_caching: h[:prompt_caching],
+        tool_output_compression: h[:tool_output_compression],
+        # params/model_policy: the resolver tolerates string keys from
+        # the JSON round-trip (ModelResolver#normalize_params / ModelPolicy), so no
+        # re-symbolization needed here.
+        params: h[:params] || {},
+        model_policy: h[:model_policy],
+        budget: h[:budget],
+        reliability: h[:reliability],
+        alerts: h[:alerts],
+        stuck_signal: h[:stuck_signal],
+        # guardrails: a plain Hash; Safety::Config tolerates the JSON
+        # round-trip (string keys/values), so no re-symbolization here.
+        guardrails: h[:guardrails],
+        # sandbox: a plain config Hash; Sandbox.build tolerates the JSON
+        # round-trip (string keys), so no re-symbolization here. nil = absent.
+        sandbox: h[:sandbox],
+        # refinement: a plain config Hash read with string keys by the
+        # RunRefinement handler; nil round-trips as nil (= report-only).
+        refinement: h[:refinement],
+        # capabilities_declared: flat [String]; build re-normalizes.
+        capabilities_declared: h[:capabilities_declared],
+        # edge_stream: which internal channels may cross to the customer. {} = neither.
+        edge_stream: h[:edge_stream],
+        metadata: h[:metadata] || {}
+      )
+    end
+
+    def symbolize_top(record) = record.each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+
+    # limits keys -> symbol; numeric values preserved by JSON.
+    def symbolize_limits(limits)
+      return {} if limits.nil?
+
+      limits.each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+    end
+  end
+end

data/lib/insika/prompt_catalog.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Insika
+  # Catalog of prompts: NON-executable content
+  # (it is a Catalog, not a Registry). Mirrors the SkillCatalog: each prompt is a directory
+  # with a PROMPT.md (YAML frontmatter name/description + markdown body).
+  # Source for the Prompt provider when the profile uses prompt_refs.
+  class PromptCatalog
+    Prompt = Data.define(:name, :description, :path, :body)
+
+    # roots ordered by PRECEDENCE (highest first) — same name in more than
+    # one root: the first wins (identical to SkillCatalog).
+    def initialize(roots)
+      @roots = Array(roots)
+      @prompts = load_all
+    end
+
+    def all = @prompts.values
+
+    # -> Prompt | nil (the Prompt provider converts nil into a ContextError; it is not
+    # the catalog's job to raise).
+    def find(name) = @prompts[name.to_s]
+
+    # Rescan + atomic index swap: parity with the SkillCatalog
+    # for reload without a restart when the on-disk seed changes.
+    def reload
+      @prompts = load_all
+      self
+    end
+
+    private
+
+    def load_all
+      found = {}
+      @roots.each do |root|
+        Dir.glob(File.join(root, "**", "PROMPT.md")).sort.each do |file|
+          prompt = parse(file)
+          next unless prompt
+
+          found[prompt.name] ||= prompt # precedence: first root wins
+        end
+      end
+      found
+    end
+
+    def parse(file)
+      raw = File.read(file, encoding: "UTF-8")
+      match = raw.match(/\A---\s*\n(.*?)\n---\s*\n(.*)\z/m)
+      return nil unless match
+
+      meta = YAML.safe_load(match[1]) || {}
+      name = meta["name"]
+      return nil unless name
+
+      Prompt.new(name: name.to_s, description: meta["description"].to_s,
+                 path: file, body: match[2].strip)
+    end
+  end
+end

data/lib/insika/provider_error_classifier.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Insika
+  # Classifies provider/transport failures by ACTION (B9). Four kinds —
+  # the hermes/openclaw structural rule: NON-retryable checked first, so an
+  # error we do not recognize defaults to :fatal (a retry would hammer a
+  # poisoned credential; a fatal is retried only after the operator fixes the
+  # cause):
+  #
+  #   :fatal              401/402/403/400 (auth, billing, permanent quota,
+  #                       bad request, context too long) — retrying does not help.
+  #   :retryable          5xx/529/socket/timeout — the same call may succeed
+  #                       moments later.
+  #   :rate_limited_short a 429 that says "back off briefly" (RPM-scale).
+  #   :rate_limited_long  a 429 with a long retry-after — quota-scale.
+  #
+  # The classification is STRING-based (class names, no constant references):
+  # the core loads without ruby_llm, and the smoke-shim's fake RubyLLM is a
+  # drop-in. `retry_after` is read from the provider's own Retry-After header
+  # when the error carries a response, else a per-kind default.
+  class ProviderErrorClassifier
+    Classification = Data.define(:kind, :retryable, :retry_after) do
+      # the additive envelope fields — compacted so a retry_after-less fatal
+      # never invents one.
+      def to_h
+        { kind: kind, retryable: retryable, retry_after: retry_after }.compact
+      end
+    end
+
+    KINDS = %i[fatal retryable rate_limited_short rate_limited_long].freeze
+
+    # Above this a 429 means quota, not RPM (this is what tells the two apart —
+    # a short 429 wants a quick retry; a long one is a billing event).
+    SHORT_RETRY_LIMIT = 60 # seconds
+
+    DEFAULTS = {
+      retryable: 5,
+      rate_limited_short: 10,
+      rate_limited_long: 300
+    }.freeze
+
+    # RubyLLM's taxonomy (error.rb), matched by class name so the core stays
+    # ruby_llm-free at load time.
+    FATAL_ERROR_NAMES = %w[
+      RubyLLM::ContextLengthExceededError RubyLLM::BadRequestError
+      RubyLLM::UnauthorizedError RubyLLM::PaymentRequiredError RubyLLM::ForbiddenError
+    ].freeze
+    RATE_LIMITED_ERROR_NAME = "RubyLLM::RateLimitError"
+    RETRYABLE_ERROR_NAMES = %w[
+      RubyLLM::ServerError RubyLLM::ServiceUnavailableError RubyLLM::OverloadedError
+    ].freeze
+    RUBY_LLM_ERROR_NAMES = (
+      FATAL_ERROR_NAMES + [RATE_LIMITED_ERROR_NAME] +
+      RETRYABLE_ERROR_NAMES + ["RubyLLM::Error"]
+    ).freeze
+
+    # Transport failures while talking to the provider: connection
+    # refused/reset, DNS, TLS, timeouts (Faraday wraps its own names; the
+    # stdlib ones surface from raw sockets).
+    TRANSPORT_NAME_PATTERNS = [
+      /\AFaraday::/,
+      /\ASocketError\z/,
+      /\AIOError\z/,
+      /\AErrno::/,
+      /\ANet::(Read|Open)Timeout\z/,
+      /\ATimeout::Error\z/,
+      /\AOpenSSL::SSL::SSLError\z/
+    ].freeze
+
+    class << self
+      # -> Classification
+      def classify(error)
+        names = class_names(error)
+
+        # Non-retryable first (the structural rule): a known fatal is NEVER
+        # retried, and an unknown error defaults to fatal — never to retry.
+        return fatal if (names & FATAL_ERROR_NAMES).any?
+
+        return rate_limited(error) if names.include?(RATE_LIMITED_ERROR_NAME)
+
+        return retryable if (names & RETRYABLE_ERROR_NAMES).any?
+        return retryable if transport?(names)
+
+        # A generic RubyLLM::Error (or a raw HTTP error) still carries the
+        # status: 429 and 5xx are retryable regardless of the wrapping class.
+        case http_status(error)
+        when 429      then rate_limited(error)
+        when 500..599 then retryable
+        else fatal
+        end
+      end
+
+      # True when the error came from the provider call itself (RubyLLM
+      # family or transport) — the executor routes these to the :ruby_llm
+      # stage with a wrapped classification instead of :unknown.
+      def provider_error?(error)
+        names = class_names(error)
+        (names & RUBY_LLM_ERROR_NAMES).any? || transport?(names)
+      end
+
+      # The typed ProviderError the executor stores and emits.
+      def wrap(error)
+        c = classify(error)
+        Insika::ProviderError.new(
+          error.message || error.class.name,
+          kind: c.kind, retryable: c.retryable, retry_after: c.retry_after
+        )
+      end
+
+      private
+
+      def fatal
+        Classification.new(kind: :fatal, retryable: false, retry_after: nil)
+      end
+
+      def retryable
+        Classification.new(kind: :retryable, retryable: true,
+                           retry_after: DEFAULTS[:retryable])
+      end
+
+      def rate_limited(error)
+        ra = retry_after_header(error)
+        if ra && ra > SHORT_RETRY_LIMIT
+          Classification.new(kind: :rate_limited_long, retryable: true, retry_after: ra)
+        else
+          Classification.new(kind: :rate_limited_short, retryable: true,
+                             retry_after: ra || DEFAULTS[:rate_limited_short])
+        end
+      end
+
+      def class_names(error)
+        ([error.class.name] + Array(error.class.ancestors).map(&:name)).compact
+      end
+
+      def transport?(names)
+        names.any? { |n| TRANSPORT_NAME_PATTERNS.any? { |p| p.match?(n) } }
+      end
+
+      # The provider's own Retry-After (seconds), when the error carries a
+      # response. All access guarded — a bare double must not raise.
+      def retry_after_header(error)
+        headers = response_headers(error)
+        value = headers && (headers["retry-after"] || headers["Retry-After"])
+        value = value.to_s.strip
+        value.match?(/\A\d+\z/) ? value.to_i : nil
+      end
+
+      def http_status(error)
+        response = error.respond_to?(:response) ? error.response : nil
+        status = response && response.respond_to?(:status) ? response.status : nil
+        status&.to_i
+      end
+
+      def response_headers(error)
+        response = error.respond_to?(:response) ? error.response : nil
+        response && response.respond_to?(:headers) ? response.headers : nil
+      end
+    end
+  end
+end

data/lib/insika/queue_policy.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require_relative "coercion"
+
+module Insika
+  # what happens to an inbound message for a session that is ALREADY
+  # busy. Today the engine has exactly one answer, "it waits in line"; this names
+  # that answer `followup` and adds three others:
+  #
+  #   collect   — the message arrived BEFORE the turn started: merge the fragments
+  #               into one turn (the whole mechanism is a timer at the door).
+  #   steer     — the turn is ALREADY running tools: append the message to the run in
+  #               flight, at a tool-batch boundary, so the customer's correction lands
+  #               before the model's next step instead of after the whole run.
+  #   interrupt — the turn is running and is now answering the wrong question: abandon
+  #               it at its next boundary and let the new message be its own turn.
+  #
+  # They never compete for the same message: `collect` only ever touches a turn that
+  # has not started; `steer` and `interrupt` only a turn that has, and they differ in
+  # whether the run in flight is still worth finishing.
+  #
+  # Resolution per message, the order EdgeLimiter already documents
+  # (`edge_limiter.rb:17`) — configuration over convention:
+  #
+  #   session vars["queue_mode"]   — one conversation pinned by an operator
+  #   profile.limits[:<key>]       — per-agent (a PRESENT key wins, incl. nil/0 = off)
+  #   settings["queue"][<key>]     — platform default, editable in the Studio
+  #   DEFAULTS[<key>]              — = today's behavior
+  #
+  # Every default is off: a bare wiring behaves exactly as it did before this
+  # existed. The knobs live in `profile.limits` next to `tool_concurrency` and
+  # `turn_timeout` because they are bounds on the same thing — how much work one
+  # turn is allowed to absorb.
+  class QueuePolicy
+    # All four of are delivered, so there is no "specified but unshipped"
+    # tier any more — a mode outside this set is a typo, and it is refused rather than
+    # approximated. Treating an unknown mode as `followup` would look exactly like a
+    # mode that never fires.
+    MODES = %i[followup collect steer interrupt].freeze
+
+    DEFAULTS = {
+      queue_mode: :followup,
+      debounce_ms: 0,          # 0 = no window: dequeue immediately, today's path
+      debounce_max_ms: 10_000, # ceiling on the TOTAL deferral (see #debounce_deadline_ms)
+      steer_max_messages: 5,   # how many messages ONE run may absorb; overflow = followup
+      steer_join: nil          # nil = the raw text; a template frames it (see #frame)
+    }.freeze
+
+    # The placeholder `steer_join` must carry, so a template that would silently
+    # drop the customer's message is a config error and not a lost message.
+    JOIN_PLACEHOLDER = "%{message}"
+
+    attr_reader :mode, :debounce_ms, :debounce_max_ms, :steer_max_messages, :steer_join
+
+    # profile: an AgentProfile (or nil); settings_store: nil = no platform layer;
+    # vars: the session's vars Hash (string keys, as the SessionStore returns).
+    def self.resolve(profile, settings_store: nil, vars: nil)
+      platform = ((settings_store&.get || {})["queue"] || {})
+      limits = profile.respond_to?(:limits) ? (profile.limits || {}) : {}
+
+      new(
+        mode: mode!(pick_mode(vars, limits, platform)),
+        debounce_ms: pick(:debounce_ms, limits, platform),
+        debounce_max_ms: pick(:debounce_max_ms, limits, platform),
+        steer_max_messages: pick(:steer_max_messages, limits, platform),
+        steer_join: pick_text(:steer_join, limits, platform)
+      )
+    end
+
+    def initialize(mode:, debounce_ms:, debounce_max_ms:,
+                   steer_max_messages: DEFAULTS[:steer_max_messages], steer_join: nil)
+      @mode = mode
+      @debounce_ms = [debounce_ms.to_i, 0].max
+      # A non-positive ceiling would mean "defer forever", which nobody wants and
+      # which a stray 0 in a config would silently buy. Fall back to the default.
+      max = debounce_max_ms.to_i
+      @debounce_max_ms = max.positive? ? max : DEFAULTS[:debounce_max_ms]
+      # 0 (or a negative) is a legitimate "never steer on this agent" — unlike the
+      # ceiling above, it forbids rather than defers forever, so it is honored.
+      @steer_max_messages = [steer_max_messages.to_i, 0].max
+      @steer_join = join!(steer_join)
+    end
+
+    # Does this policy want messages held at the door at all?
+    def debounce? = @debounce_ms.positive?
+
+    # Does this policy merge into a turn that has not started yet?
+    def collect? = @mode == :collect
+
+    # Does this policy append into a turn that is already running? `steer_max_messages`
+    # of 0 is the agent saying no, so it answers false rather than steering once and
+    # then refusing.
+    def steer? = @mode == :steer && @steer_max_messages.positive?
+
+    # Does this policy abandon the turn in flight? The new message then becomes an
+    # ordinary turn of its own — which is why `interrupt`, unlike the two joining modes,
+    # needs no verdict field and works on every surface.
+    def interrupt? = @mode == :interrupt
+
+    # The content of the injected message. `steer_join` frames it when an agent needs
+    # the model to know this text arrived mid-run ("the customer just added: %{message}");
+    # nil — the default — appends exactly what the person typed. A plain gsub, not
+    # `format`: the text is a customer's, and a stray `%` in it must not raise.
+    def frame(text)
+      return text.to_s if @steer_join.nil?
+
+      @steer_join.gsub(JOIN_PLACEHOLDER, text.to_s)
+    end
+
+    # A mode name -> Symbol, or raise. Blank = the default (an absent key is not
+    # an error; a WRONG key is).
+    def self.mode!(value)
+      return DEFAULTS[:queue_mode] if Coercion.blank?(value)
+
+      name = value.to_s.strip.downcase.to_sym
+      return name if MODES.include?(name)
+
+      raise Insika::ValidationError,
+            "unknown queue_mode: #{value.inspect} (expected #{MODES.join(', ')})"
+    end
+
+    # A present key WINS even carrying nil/0 — "off for this agent", never
+    # "inherit the platform default". Same semantics EdgeLimiter documents at
+    # `edge_limiter.rb:57`, and for the same reason: an imported pack carrying an
+    # explicit null must not silently re-enable a platform behavior.
+    def self.pick(key, limits, platform)
+      return limits[key].to_i if limits.key?(key)
+      return platform[key.to_s].to_i if platform.key?(key.to_s)
+
+      DEFAULTS[key]
+    end
+
+    # Same rule as #pick for a key whose value is TEXT: `to_i` would turn a template
+    # into 0. A present-but-nil key still means "off for this agent".
+    def self.pick_text(key, limits, platform)
+      return limits[key] if limits.key?(key)
+      return platform[key.to_s] if platform.key?(key.to_s)
+
+      DEFAULTS[key]
+    end
+
+    def self.pick_mode(vars, limits, platform)
+      from_vars = (vars || {})["queue_mode"] || (vars || {})[:queue_mode]
+      return from_vars if Coercion.present?(from_vars)
+      return limits[:queue_mode] if limits.key?(:queue_mode)
+
+      platform["queue_mode"]
+    end
+
+    private_class_method :pick, :pick_text, :pick_mode
+
+    private
+
+    # A template that does not carry the placeholder would drop the customer's message
+    # while the turn still looked steered. Refused where the operator is (config time),
+    # not at 14:02 on a live conversation.
+    def join!(value)
+      return nil if Coercion.blank?(value)
+
+      text = value.to_s
+      return text if text.include?(JOIN_PLACEHOLDER)
+
+      raise Insika::ValidationError,
+            "steer_join must contain #{JOIN_PLACEHOLDER} (got #{value.inspect})"
+    end
+  end
+end