insika 0.0.1 → 0.2.0

data/lib/insika/studio/views/tools.erb

@@ -0,0 +1,89 @@
+<%# Tools — drill-down (T2): [data tools + agents] master | agent tool matrix.
+   @sel_agent (from ?a=) drives the detail; data tools link to their editor page. %>
+<div class="drill" data-controller="list-filter">
+  <aside class="drill-pane drill-master">
+    <div class="drill-pane-head">
+      <div class="title"><strong>Tools <span class="count"><%= @tools.size %></span></strong></div>
+      <a class="btn primary btn-sm" href="/studio/tools/def/new">+ data tool</a>
+    </div>
+    <div class="drill-search">
+      <input type="search" class="filter-input" placeholder="Filter agents…" aria-label="Filter agents"
+             data-list-filter-target="query" data-action="input->list-filter#filter keydown->list-filter#clear">
+    </div>
+    <nav class="drill-pane-body drill-list" aria-label="tools and agents">
+      <% unless @data_tool_names.empty? %>
+        <div class="drill-group-label">Data tools · HTTP, editable</div>
+        <% @data_tool_names.sort.each do |name| %>
+          <% dropped = @dropped_tool_names.include?(name) %>
+          <a class="drill-item drill-item-sm" href="/studio/tools/def/<%= Rack::Utils.escape(name) %>"
+             <%== %( title="its definition is invalid — no agent can call it until it is fixed") if dropped %>>
+            <div class="drill-item-name"><span class="txt"><%= name %></span><span class="pill plain">data</span><% if dropped %> <span class="pill locked">dropped</span><% end %></div>
+          </a>
+        <% end %>
+      <% end %>
+      <div class="drill-group-label">Agents · allow / deny</div>
+      <% @agents.each do |a| %>
+        <a class="drill-item<%== ' active' if @sel_agent && @sel_agent.id == a.id %>"
+           href="/studio/tools?a=<%= Rack::Utils.escape(a.id) %>"
+           data-list-filter-target="item" data-filter-text="<%= a.id %>">
+          <div class="drill-item-name"><span class="txt"><%= a.id %></span>
+            <span class="pill plain"><%= a.tools_allow.nil? ? "all" : "#{tools_on_count(a, @tools)}/#{@tools.size}" %></span>
+          </div>
+        </a>
+      <% end %>
+      <div class="empty" data-list-filter-target="empty" hidden>No agents match your filter.</div>
+    </nav>
+  </aside>
+
+  <section class="drill-pane drill-detail">
+    <% if @sel_agent.nil? %>
+      <div class="drill-empty">
+        <div>
+          <h2>Tools</h2>
+          <p>Pick an agent to set which tools it can call — or edit a data tool on the left. <strong>all</strong> = open allowlist (every tool flows through); a <span class="pill locked">locked</span> tool is on the denylist (deny always wins).</p>
+        </div>
+      </div>
+    <% else %>
+      <% a = @sel_agent %>
+      <div class="drill-pane-head">
+        <div class="title">
+          <nav class="crumbs"><a href="/studio/tools">tools</a> / <span><%= a.id %></span></nav>
+          <strong class="mono"><%= a.id %></strong>
+        </div>
+        <button type="submit" form="tools-form" class="btn primary" data-turbo-submits-with="Saving…">Save tools</button>
+      </div>
+      <div class="drill-pane-body" data-controller="toggle-counter">
+        <div class="matrix-topline">
+          <span class="count-badge mono" data-toggle-counter-target="count"><%= a.tools_allow.nil? ? "all" : "#{tools_on_count(a, @tools)}/#{@tools.size} on" %></span>
+          <label class="switch" title="open allowlist — every tool flows through">
+            <input type="checkbox" name="all_tools" value="1" form="tools-form"<%== " checked" if a.tools_allow.nil? %>
+                   data-toggle-counter-target="all" data-action="change->toggle-counter#update">
+            <span class="switch-track" aria-hidden="true"></span>
+            <span class="switch-label">all tools</span>
+          </label>
+        </div>
+        <p class="muted">Checked tools are allowed next turn. A <span class="pill locked">locked</span> tool is on the denylist — deny always wins, so it can't be granted here.</p>
+        <form id="tools-form" method="post" action="/studio/tools/<%= Rack::Utils.escape(a.id) %>">
+          <%== csrf_tag %>
+          <% if @tools.empty? %>
+            <p class="muted">No tools registered in the runtime.</p>
+          <% else %>
+            <div class="check-grid tool-grid<%== " is-open" if a.tools_allow.nil? %>" data-toggle-counter-target="grid">
+              <% @tools.each do |t| %>
+                <% denied = tool_denied_for?(a, t.name) %>
+                <label class="check tool-check<%== " locked" if denied %>" title="<%= denied ? "denied — deny wins" : t.description %>">
+                  <input type="checkbox" name="tools[]" value="<%= t.name %>"
+                         <%== " checked" if tool_allowed_for?(a, t.name) && !denied %>
+                         <%== " disabled" if denied %>
+                         data-toggle-counter-target="tool" data-locked="<%= denied %>"
+                         data-action="change->toggle-counter#update">
+                  <span class="mono"><%= t.name %></span><% if @data_tool_names.include?(t.name) %> <span class="pill plain">data</span><% end %><% if denied %> <span class="pill locked">locked</span><% end %>
+                </label>
+              <% end %>
+            </div>
+          <% end %>
+        </form>
+      </div>
+    <% end %>
+  </section>
+</div>

data/lib/insika/subagent_graph.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Insika
+  # Definition-time integrity of the subagent delegation graph (
+  # A pure function over `{id => [child_ids]}`: detects CYCLES and
+  # computes the max delegation DEPTH, raising a typed SubagentError so the
+  # authoring Command (CreateAgent/UpdateAgent) fails cleanly and boot refuses a
+  # bad static set. Cycle + bounded depth are exactly Flue's definition-time
+  # guarantee (`DelegationDepthExceededError` + anti-circular) — with the graph
+  # acyclic and depth <= cap, the runtime is provably bounded (the guard in
+  # Executor#run_subagent is only belt-and-suspenders for a graph that changed
+  # mid-run).
+  #
+  # UNKNOWN child refs are treated as LEAVES (no outgoing edges), NOT an error:
+  # dynamic authoring must not break by creation order — a not-yet-created child
+  # surfaces as a clean "not found" at runtime (run_subagent), not a boot failure.
+  module SubagentGraph
+    # Longest delegation chain allowed (root counts as depth 0; each spawn +1).
+    # Override with INSIKA_SUBAGENT_DEPTH_CAP.
+    DEFAULT_DEPTH_CAP = 5
+
+    # Max children a single `spawn_subagents` fan-out may run — also the concurrency
+    # bound (N concurrent LLM calls hit the provider rate limit + the per-agent token
+    # ceiling of). Override with INSIKA_SUBAGENT_FANOUT_CAP.
+    DEFAULT_FANOUT_CAP = 8
+
+    module_function
+
+    def depth_cap
+      int_env("INSIKA_SUBAGENT_DEPTH_CAP", DEFAULT_DEPTH_CAP)
+    end
+
+    def fan_out_cap
+      int_env("INSIKA_SUBAGENT_FANOUT_CAP", DEFAULT_FANOUT_CAP)
+    end
+
+    def int_env(name, default)
+      raw = Insika::EnvSchema.read(name)
+      raw && !raw.strip.empty? ? Integer(raw) : default
+    end
+
+    # Validates the whole set. `profiles` is anything enumerable of profiles
+    # responding to #id and #subagents (an Array or a ProfileSource#all result),
+    # OR a plain `{id => [child_ids]}` Hash. Raises on the FIRST violation.
+    def validate!(profiles, cap: depth_cap)
+      map = to_map(profiles)
+      map.each_key { |root| check_from(root, map, cap) }
+      map
+    end
+
+    # Builds the {id => [child_ids]} adjacency map. Absent/nil subagents => [].
+    def to_map(profiles)
+      return normalize(profiles) if profiles.is_a?(Hash)
+
+      each_profile(profiles).each_with_object({}) do |p, acc|
+        acc[p.id.to_s] = Array(p.subagents).map(&:to_s)
+      end
+    end
+
+    # DFS from `root` tracking the recursion stack (cycle) and the longest path
+    # (depth). A ref to an id absent from `map` is a leaf.
+    def check_from(root, map, cap)
+      walk(root, map, cap, [], {})
+    end
+
+    # Returns the max depth of the subtree rooted at `node`. `stack` is the
+    # current path (cycle detection); `memo` caches finished subtrees.
+    def walk(node, map, cap, stack, memo)
+      raise SubagentCycleError.new(cycle: stack + [node]) if stack.include?(node)
+      return memo[node] if memo.key?(node)
+
+      children = map[node] || [] # unknown ref => leaf
+      depth = if children.empty?
+                0
+              else
+                1 + children.map { |c| walk(c, map, cap, stack + [node], memo) }.max
+              end
+      raise SubagentDepthExceeded.new(depth: depth, cap: cap) if depth > cap
+
+      memo[node] = depth
+    end
+
+    def normalize(hash)
+      hash.each_with_object({}) { |(k, v), acc| acc[k.to_s] = Array(v).map(&:to_s) }
+    end
+
+    # Duck-typed enumeration: an Array of profiles, or a ProfileSource exposing
+    # #all. Anything else Enumerable is iterated as-is.
+    def each_profile(profiles)
+      return profiles if profiles.is_a?(Array)
+      return profiles.all if profiles.respond_to?(:all)
+
+      Array(profiles)
+    end
+  end
+end

data/lib/insika/system_file_store.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  # GLOBAL system files. These are prompts/rules
+  # that apply to ALL agents in the deploy — the "house" above each BIA's
+  # individual identity. Unlike the AgentFileStore (per agent), here there is no
+  # tenant: one record per file in the ConfigStore (scope "system_files").
+  #
+  # Context::Providers::Prompt reads these files and injects them BEFORE the
+  # per-agent identity, for every turn. With no system files (empty store),
+  # the prompt is byte-for-byte the one from before (parity preserved) — the global
+  # injection only exists when the operator authors something here.
+  #
+  # Record per file:
+  #   { "content" => str, "updated_at" => iso8601,
+  #     "history" => [ { "content" => str, "at" => iso8601 }, ... ] }
+  #
+  # A write versions (same contract as AgentFileStore): the previous content
+  # goes into `history` (most recent first), capped at HISTORY_MAX; restoring
+  # is a new write (linear history, no destructive "time travel").
+  class SystemFileStore
+    SCOPE = "system_files"
+    HISTORY_MAX = 20
+
+    def initialize(config_store:)
+      @cs = config_store
+    end
+
+    # -> String | nil (current content).
+    def read(filename)
+      entry(filename.to_s)&.fetch("content", nil)
+    end
+
+    # -> [String] file names, lexicographic order.
+    def list
+      @cs.keys(SCOPE).sort
+    end
+
+    # Writes (upsert). create_only: refuses to overwrite. Versions the previous one into
+    # history. -> Hash (the stored entry).
+    def write(filename, content, create_only: false)
+      name = filename.to_s
+      raise Insika::ValidationError, "file is required" if name.empty?
+
+      current = entry(name)
+      if create_only && current
+        raise Insika::ValidationError, "system file '#{name}' already exists"
+      end
+
+      built = build_entry(content.to_s, current)
+      @cs.put(SCOPE, name, built)
+      built
+    end
+
+    # -> bool (did it exist?).
+    def delete(filename)
+      @cs.delete(SCOPE, filename.to_s)
+    end
+
+    # -> [ { "content" =>, "at" => } ] older versions, most recent first.
+    def versions(filename)
+      entry(filename.to_s)&.fetch("history", []) || []
+    end
+
+    # Restores version `index` from history as the current content (a new write).
+    # -> Hash (entry) | raises if index invalid / file nonexistent.
+    def restore(filename, index)
+      name = filename.to_s
+      current = entry(name)
+      raise Insika::NotFoundError, "system file '#{name}' not found" unless current
+
+      hist = current.fetch("history", [])
+      i = Integer(index)
+      raise Insika::ValidationError, "version #{index} does not exist" if i.negative? || i >= hist.length
+
+      write(name, hist[i]["content"])
+    end
+
+    private
+
+    def entry(name)
+      @cs.get(SCOPE, name)
+    end
+
+    def build_entry(content, current)
+      history = current ? current.fetch("history", []) : []
+      if current
+        history = [{ "content" => current["content"], "at" => current["updated_at"] }] + history
+        history = history.first(HISTORY_MAX)
+      end
+      { "content" => content, "updated_at" => Time.now.utc.iso8601, "history" => history }
+    end
+  end
+end

data/lib/insika/task_actor.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "async"
+require "async/queue"
+
+module Insika
+  # Actor model: one Async fiber per Task + a mailbox. The message enum is
+  # `cancel`/`user_message`/`approval`/`pause`/`resume`/`timeout`/`heartbeat`, with
+  # `await` as the cooperative SUSPENSION primitive. Cancellation/suspension only
+  # at stage boundaries — never in the middle of an operation.
+  class TaskActor
+    # `user_message` is posted by `Executor#steer_into_running` and
+    # consumed by `SteerInjector` at a tool-batch boundary. `pause`/`resume` (operator),
+    # `approval` (human-in-the-loop), `timeout`/`heartbeat`
+    # (watchdog/liveness, observation).
+    MESSAGES = %i[cancel user_message approval pause resume timeout heartbeat].freeze
+
+    attr_reader :task_id, :pending_user_messages, :heartbeats
+    # How many messages this run was ASKED to absorb, ever — including the ones
+    # already injected and cleared. It is what bounds steering (`steer_max_messages`),
+    # so it counts posts and never decreases.
+    attr_reader :user_messages_posted
+
+    def initialize(task_id:, parent: Async::Task.current)
+      @task_id = task_id
+      @parent = parent
+      @mailbox = Async::Queue.new
+      @pending_user_messages = []
+      @pause_requested = false
+      @heartbeats = 0
+      @user_messages_posted = 0
+    end
+
+    # Non-blocking. A message outside the enum is a caller bug.
+    def post(message, data = nil)
+      raise ArgumentError, "unknown message: #{message}" unless MESSAGES.include?(message)
+
+      @user_messages_posted += 1 if message == :user_message
+      @mailbox.enqueue([message, data])
+      nil
+    end
+
+    # Runs the block on an Async fiber CHILD of the parent. Returns the Task.
+    def run(&turn_block)
+      @async_task = @parent.async { turn_block.call(self) }
+    end
+
+    # Drains the mailbox WITHOUT blocking (boundaries). `:cancel` raises (the top
+    # of the fiber maps to :cancelled). `:pause` arms the suspension (the Executor
+    # checks `pause_requested?`). Resolutions (`:resume`/`:approval`/`:timeout`)
+    # that arrive here WITH no pending suspension are DISCARDED (idempotent,
+    # no-op).
+    def drain!
+      until @mailbox.empty?
+        route_boundary(*@mailbox.dequeue)
+      end
+      nil
+    end
+
+    # Did the operator request a pause? (consumed by the Executor; `await` clears
+    # the flag).
+    def pause_requested? = @pause_requested
+
+    # takes the steered messages and clears the buffer, WITHOUT
+    # observing anything else in the mailbox: whatever is not a `:user_message` is put
+    # back, in the order it arrived.
+    #
+    # Why not `drain!`: this runs INSIDE RubyLLM's tool loop (a `after_message`
+    # callback), and `drain!` raises on `:cancel`. Cancellation is only ever observed
+    # at the Executor's own stage boundaries — that is what keeps a tool batch one
+    # unit of work (and for the same rule under `turn_timeout`).
+    # Injecting a message must not quietly become a new place a turn can die.
+    def take_user_messages!
+      @mailbox.size.times do
+        message, data = @mailbox.dequeue
+        message == :user_message ? @pending_user_messages << data : @mailbox.enqueue([message, data])
+      end
+      taken = @pending_user_messages.dup
+      @pending_user_messages.clear
+      taken
+    end
+
+    # BLOCKS the turn's fiber until a RESOLUTION (yields the reactor — no spin).
+    # Used by the Executor in :paused (waits for :resume) and by the ToolEnvelope
+    # in :waiting (waits for :approval). Returns [:resume, nil] or [:approval,
+    # data]. `:cancel` -> CancelledError; `:timeout` -> TimeoutError. A legitimate
+    # resolution only arrives WITH the fiber already blocked here (the operator
+    # only resumes/approves what is suspended), so it is consumed by this
+    # `dequeue` — there is no race requiring a buffer. Non-resolution messages
+    # received during the wait are ABSORBED without changing the suspension state
+    # (a redundant :pause does not re-arm the pause).
+    def await(reason:)
+      @pause_requested = false # the pause/wait is being handled now
+      loop do
+        message, data = @mailbox.dequeue
+        case message
+        when :cancel        then raise CancelledError, "task #{@task_id} cancelled"
+        when :timeout       then raise Insika::TimeoutError.new("wait (#{reason}) exceeded", stage: data || reason)
+        when :resume, :approval then return [message, data]
+        when :heartbeat     then @heartbeats += 1
+        when :user_message  then @pending_user_messages << data
+        # :pause during the wait: already suspended, ignore (does not re-arm pause_requested)
+        end
+      end
+    end
+
+    # specs/boot await the fiber's completion.
+    def wait = @async_task&.wait
+
+    private
+
+    # Routing of boundary messages (non-blocking). Orphan resolutions
+    # (`:resume`/`:approval`/`:timeout` with no pending suspension) are DISCARDED —
+    # NEVER buffered: a stored resolution would wrongly resolve a FUTURE `await`
+    # (auto-resume/auto-approve/auto-timeout of a suspension the operator did not
+    # resolve). Legitimate resolutions arrive with the fiber already in `await`
+    # (consumed there), so discarding here is safe and idempotent.
+    def route_boundary(message, data)
+      case message
+      when :cancel then raise CancelledError, "task #{@task_id} cancelled"
+      when :pause then @pause_requested = true
+      when :user_message then @pending_user_messages << data
+      when :heartbeat then @heartbeats += 1
+      when :resume, :approval, :timeout then nil # orphan: discard (see comment)
+      end
+    end
+  end
+end

data/lib/insika/task_store.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module Insika
+  # Domain store for tasks. Persists Tasks over an
+  # injected Insika::Store, with the STATE MACHINE validated here: the store is
+  # the only place status is written, so the
+  # invariants live where the writes live. An invalid transition is a bug and raises
+  # ArgumentError loud and early — this is how logical races are
+  # detected without a lock.
+  #
+  # Each Execution is ONE attempt; retry/resume opens a new entry, never
+  # overwrites.
+  class TaskStore
+    include Coercion
+
+    SCOPE = "tasks"
+    KEY_PREFIX = "task:"
+
+    STATUSES = %i[queued running waiting paused completed failed cancelled].freeze
+
+    # Valid transitions — anything outside this is a bug -> ArgumentError.
+    TRANSITIONS = {
+      # queued -> failed: a turn queued in the SessionActor may fail
+      # at STARTUP (spawn error before the fiber) without ever running.
+      queued: %i[running cancelled failed],
+      running: %i[waiting paused completed failed cancelled],
+      waiting: %i[running cancelled failed],
+      paused: %i[running cancelled],
+      completed: [], failed: [], cancelled: [] # terminal
+    }.freeze
+
+    Task      = Data.define(:id, :status, :command, :session_id, :executions,
+                            :mailbox_state, :created_at, :updated_at)
+    Execution = Data.define(:attempt, :started_at, :finished_at, :outcome, :error)
+
+    def initialize(store:)
+      @store = store
+    end
+
+    # -> Task (status :queued). command: Hash ({type:, payload:, meta:}) or
+    # any object that responds to to_h (e.g. Insika::Command).
+    # ArgumentError if the id already exists. `at` (ISO8601) is injectable for
+    # deterministic tests — the timestamp has SECOND precision, so two tasks created
+    # in the same second are indistinguishable by time to any reader ordering by it
+    # (same rationale as MemoryStore#add_note).
+    def create(command:, session_id: nil, id: SecureRandom.uuid, at: nil)
+      key = key_for(id)
+      raise ArgumentError, "task already exists: #{id}" unless @store.get(SCOPE, key).nil?
+
+      now = at || timestamp
+      record = {
+        "id" => id.to_s,
+        "status" => "queued",
+        "command" => deep_stringify(command.respond_to?(:to_h) ? command.to_h : command),
+        "session_id" => session_id&.to_s,
+        "executions" => [],
+        "mailbox_state" => { "pending" => [] },
+        "created_at" => now,
+        "updated_at" => now
+      }
+      @store.set(SCOPE, key, record)
+      to_task(record)
+    end
+
+    # -> Task | nil
+    def find(id)
+      record = @store.get(SCOPE, key_for(id))
+      record && to_task(record)
+    end
+
+    # -> Task; validates the state machine. NotFoundError if absent,
+    # ArgumentError for a status outside the enum or an invalid transition.
+    # If `error:` is provided AND there is an open Execution, it closes it in the same write
+    # (Recovery path).
+    #
+    # The read-check-write rides Store#transaction because this is also the
+    # dispatch CLAIM: two workers racing queued -> running serialize on the
+    # backend's lock, the loser re-reads :running and gets the loud
+    # ArgumentError instead of a second silent owner.
+    def transition(id, to:, error: nil)
+      target = to.to_sym
+      raise ArgumentError, "invalid status: #{to}" unless STATUSES.include?(target)
+
+      @store.transaction do
+        record = fetch!(id)
+        from = record["status"].to_sym
+        unless TRANSITIONS.fetch(from).include?(target)
+          raise ArgumentError, "invalid transition: #{from} -> #{target}"
+        end
+
+        close_open_execution(record, outcome: target.to_s, error: error) if error
+        record["status"] = target.to_s
+        record["updated_at"] = timestamp
+        @store.set(SCOPE, key_for(id), record)
+        to_task(record)
+      end
+    end
+
+    # -> Task; opens an Execution (attempt N+1). ArgumentError if one is already
+    # open (a double attempt is a bug — one owner per task). Append-only.
+    def begin_execution(id)
+      record = fetch!(id)
+      raise ArgumentError, "an open Execution already exists on task #{id}" if open_execution(record)
+
+      record["executions"] += [{
+        "attempt" => record["executions"].size + 1,
+        "started_at" => timestamp,
+        "finished_at" => nil,
+        "outcome" => nil,
+        "error" => nil
+      }]
+      record["updated_at"] = timestamp
+      @store.set(SCOPE, key_for(id), record)
+      to_task(record)
+    end
+
+    # -> Task; closes the current Execution. ArgumentError if none is open.
+    # Does NOT touch status (that is transition's job).
+    def finish_execution(id, outcome:)
+      record = fetch!(id)
+      open = open_execution(record)
+      raise ArgumentError, "no open Execution on task #{id}" if open.nil?
+
+      open["finished_at"] = timestamp
+      open["outcome"] = outcome.to_s
+      record["updated_at"] = timestamp
+      @store.set(SCOPE, key_for(id), record)
+      to_task(record)
+    end
+
+    # (`collect`): appends a fragment to a task's message while it is
+    # still waiting at the door. -> Task.
+    #
+    # ONLY on :queued, and that guard is the whole safety of the feature: once a
+    # turn is :running its input has been read into the Chat, seeded into the
+    # context and possibly sent to the provider — rewriting it there would mean the
+    # transcript disagrees with what the model actually saw. ArgumentError on any
+    # other status, so a lost race fails loudly instead of corrupting a turn.
+    def append_message(id, text, separator: "\n")
+      fragment = presence(text)
+      return to_task(fetch!(id)) if fragment.nil?
+
+      record = fetch!(id)
+      unless record["status"] == "queued"
+        raise ArgumentError, "task #{id} is #{record['status']}, not queued: its message is already in flight"
+      end
+
+      payload = (record["command"]["payload"] ||= {})
+      current = presence(payload["message"])
+      payload["message"] = current ? "#{current}#{separator}#{fragment}" : fragment
+      record["updated_at"] = timestamp
+      @store.set(SCOPE, key_for(id), record)
+      to_task(record)
+    end
+
+    # -> [Task] with one of the given statuses. O(n) scan at boot;
+    # acceptable (one node, local SQLite).
+    def with_status(*statuses)
+      wanted = statuses.flatten
+      @store.list(SCOPE, KEY_PREFIX).filter_map do |key|
+        record = @store.get(SCOPE, key)
+        next if record.nil?
+
+        task = to_task(record)
+        task if wanted.include?(task.status)
+      end
+    end
+
+    # Interrupted (crashed mid-turn): have a checkpoint -> resume.
+    def running_or_interrupted = with_status(:running, :waiting, :paused)
+
+    # Queued but never started (turn in the SessionActor queue at the
+    # crash) — no checkpoint; recovering = RUN from scratch (Recovery/ResumeTask).
+    def queued = with_status(:queued)
+
+    # -> enumerates ids without the "task:" prefix; without a block returns an Enumerator.
+    def each_id
+      return enum_for(:each_id) unless block_given?
+
+      @store.list(SCOPE, KEY_PREFIX).each do |key|
+        yield key.delete_prefix(KEY_PREFIX)
+      end
+    end
+
+    private
+
+    def key_for(id)
+      "#{KEY_PREFIX}#{id}"
+    end
+
+    # NotFoundError if absent (nonexistent task -> 404). Backend StoreError
+    # propagates without re-wrapping.
+    def fetch!(id)
+      record = @store.get(SCOPE, key_for(id))
+      raise Insika::NotFoundError, "task not found: #{id}" if record.nil?
+
+      record
+    end
+
+    # The open Execution is the last one with finished_at nil (one owner per task, so
+    # there is at most one). Returns the raw Hash (mutable in-place for the RMW).
+    def open_execution(record)
+      last = record["executions"].last
+      last if last && last["finished_at"].nil?
+    end
+
+    def close_open_execution(record, outcome:, error:)
+      open = open_execution(record)
+      return if open.nil? # no open attempt: nowhere to record
+
+      open["finished_at"] = timestamp
+      open["outcome"] = outcome
+      open["error"] = deep_stringify(error)
+    end
+
+    # Materializes Task from the raw Hash (type normalization at the edge):
+    # `status` comes back as a Symbol (domain enum, compared against
+    # STATUSES); `command`/`mailbox_state`/`error` stay as Hashes with string keys
+    # (they are data, not enums).
+    def to_task(record)
+      Task.new(
+        id: record["id"],
+        status: record["status"].to_sym,
+        command: record["command"],
+        session_id: record["session_id"],
+        executions: record["executions"].map { |e| to_execution(e) },
+        mailbox_state: record["mailbox_state"],
+        created_at: record["created_at"],
+        updated_at: record["updated_at"]
+      )
+    end
+
+    def to_execution(hash)
+      Execution.new(
+        attempt: hash["attempt"],
+        started_at: hash["started_at"],
+        finished_at: hash["finished_at"],
+        outcome: hash["outcome"],
+        error: hash["error"]
+      )
+    end
+
+    def timestamp
+      Time.now.utc.iso8601
+    end
+  end
+end