insika 0.0.1 → 0.1.0

data/lib/insika/context/providers/session.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Insika
+  module Context
+    module Providers
+      # Reads the Session Store. The ONLY history provider: the three transcript
+      # sources converge here — the Executor does not pick a source. Produces
+      # :history fragments (1 per message), with priority scaled by recency
+      # with a CEILING of 79: the budget cut discards the oldest ones first
+      # and history NEVER outranks skills (80) or identity (100).
+      class Session < ContextProvider
+        def initialize(session_store:)
+          @session_store = session_store
+        end
+
+        def call(request)
+          messages = transcript_for(request)
+          return [] if messages.nil? || messages.empty?
+
+          # 1 fragment per EVICTION UNIT (§11 R1): a plain message, OR an
+          # assistant-with-tool_calls together with its tool results. Grouping at
+          # the fragment level means the budget cut (apply_budget) drops a whole
+          # tool cycle atomically — a tool_use is NEVER seeded without its result
+          # (which providers reject), without touching apply_budget itself.
+          eviction_units(messages).each_with_index.map do |unit, idx|
+            ContextFragment.build(
+              # single message stays a Hash (compat with existing fragments); a
+              # multi-message cycle is an Array (seed_history flattens it back).
+              content: unit.size == 1 ? unit.first : unit,
+              placement: :history,
+              # HISTORY_MAX ceiling; idx 0 = oldest (drops first in the cut)
+              priority: [Context::Priority::HISTORY_BASE + idx, Context::Priority::HISTORY_MAX].min,
+              source: id
+            )
+          end
+        end
+
+        private
+
+        # Groups a flat message list into eviction units. An assistant message
+        # carrying tool_calls absorbs the `role: tool` messages that immediately
+        # follow it (its results). Everything else is a unit of one.
+        def eviction_units(messages)
+          normalized = messages.map { |m| normalize(m) }
+          units = []
+          i = 0
+          while i < normalized.length
+            msg = normalized[i]
+            i += 1
+            if msg[:role].to_s == "assistant" && tool_calls?(msg)
+              cycle = [msg]
+              while i < normalized.length && normalized[i][:role].to_s == "tool"
+                cycle << normalized[i]
+                i += 1
+              end
+              units << cycle
+            else
+              units << [msg]
+            end
+          end
+          units
+        end
+
+        # Symbol-keyed message preserving tool_calls / tool_call_id when present
+        # (a plain message keeps just {role, content} — parity with the old shape).
+        def normalize(msg)
+          h = { role: msg[:role] || msg["role"], content: msg[:content] || msg["content"] }
+          tool_calls = msg[:tool_calls] || msg["tool_calls"]
+          tool_call_id = msg[:tool_call_id] || msg["tool_call_id"]
+          h[:tool_calls] = tool_calls if tool_calls
+          h[:tool_call_id] = tool_call_id if tool_call_id
+          h
+        end
+
+        def tool_calls?(msg) = msg[:tool_calls] && !Array(msg[:tool_calls]).empty?
+
+        # Precedence: checkpoint -> explicit history -> store.
+        # The first present source wins; no merge.
+        def transcript_for(request)
+          return request.checkpoint.messages if request.checkpoint
+
+          explicit = explicit_history(request)
+          return explicit if explicit
+          return session_messages(request.session) if request.session
+
+          nil
+        end
+
+        # Source 2 (explicit history): the handler passes it in request.vars[:history].
+        # Isolated in a single method to change the convention with 1 line.
+        def explicit_history(request)
+          vars = request.vars.to_h
+          vars[:history] || vars["history"]
+        end
+
+        # CONDITIONAL requiredness: when a session is requested, a read
+        # failure becomes a ContextError (aborts the turn); the base required?
+        # does not receive the request, so the behavior lives here.
+        def session_messages(session)
+          @session_store.find(session.id)&.messages || []
+        rescue StandardError => e # read failure (exception/StoreError)
+          raise ContextError.new("Session provider failed with a requested session: #{e.message}",
+                                 provider: id)
+        end
+      end
+    end
+  end
+end

data/lib/insika/context/providers/skill.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Insika
+  module Context
+    module Providers
+      # Level 1 (progressive disclosure) of the profile's CANDIDATE skills.
+      # The Executor's LoadSkill does NOT come from here: it is built with
+      # resolution.allowed_skills (a policy decision). Context->Policy order: the
+      # provider produces the candidate; the policy cuts afterwards.
+      class Skill < CatalogProvider
+        # priority 80: above deferred tools (70), below pinned identity.
+        def priority = Context::Priority::SKILL
+
+        private
+
+        def entries(request) = @catalog.effective(request.profile.skills)
+      end
+    end
+  end
+end

data/lib/insika/context/providers/tool_search.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Insika
+  module Context
+    module Providers
+      # Level 1 (progressive disclosure) of the profile's deferred TOOLS. The
+      # slice is `profile.tools_deferred`, known at stage 2 — it may be slightly
+      # over-inclusive (showing a deferred tool the Policy later denies); acceptable,
+      # the real cut happens at PROMOTION (tool_search, `deferred ∩ allowed`).
+      class ToolSearch < CatalogProvider
+        # priority 70: below skills (80) in the sacrifice order.
+        def priority = Context::Priority::TOOL_SEARCH
+
+        private
+
+        def entries(request) = @catalog.subset(request.profile.tools_deferred)
+      end
+    end
+  end
+end

data/lib/insika/delegation_store.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module Insika
+  # Durable record of an ASYNC delegation (RFC-0010 §5, item 21 Phase 2, hermes
+  # "delegation durability"). The synchronous subagent (Phase 1) needs no
+  # record — it lives and dies inside the parent's turn. The ASYNC subagent does:
+  # the parent DISPATCHES and its turn ends; the child runs independently; when the
+  # child finishes, its result is delivered to the parent as a NEW turn (never
+  # spliced mid-turn — preserves role alternation + prompt cache). This record is
+  # what survives a kill -9 so a completed child's result is never lost.
+  #
+  # Lifecycle (never backwards): dispatched -> completed -> delivered.
+  #   dispatched  the child was spawned; result not captured yet.
+  #   completed   the child is terminal; result/error captured durably.
+  #   delivered   the result was handed to the parent session (claimed — the
+  #               claim is what makes delivery AT-MOST-ONCE across crashes).
+  #
+  # Normalizes symbol->string on WRITE (the backend only round-trips JSON types),
+  # like the other domain stores.
+  class DelegationStore
+    include Coercion
+
+    SCOPE = "delegations"
+    KEY_PREFIX = "delegation:"
+
+    STATUSES = %i[dispatched completed delivered].freeze
+
+    Delegation = Data.define(
+      :id, :parent_task_id, :parent_session_id, :parent_agent,
+      :child_agent, :child_task_id, :child_session_id, :depth,
+      :status, :result, :error, :created_at, :updated_at
+    )
+
+    def initialize(store:)
+      @store = store
+    end
+
+    # -> Delegation (:dispatched).
+    def create(parent_task_id:, parent_session_id:, parent_agent:, child_agent:,
+               child_task_id:, child_session_id:, depth:, id: SecureRandom.uuid)
+      record = {
+        "id" => id.to_s,
+        "parent_task_id" => parent_task_id.to_s,
+        "parent_session_id" => parent_session_id&.to_s,
+        "parent_agent" => parent_agent.to_s,
+        "child_agent" => child_agent.to_s,
+        "child_task_id" => child_task_id.to_s,
+        "child_session_id" => child_session_id.to_s,
+        "depth" => depth,
+        "status" => "dispatched",
+        "result" => nil,
+        "error" => nil,
+        "created_at" => timestamp,
+        "updated_at" => timestamp
+      }
+      @store.set(SCOPE, key_for(id), record)
+      to_delegation(record)
+    end
+
+    # -> Delegation | nil
+    def find(id)
+      record = @store.get(SCOPE, key_for(id))
+      record && to_delegation(record)
+    end
+
+    # -> Delegation | nil for a given child task (the terminal hook's lookup). O(n)
+    # scan — single-node, like PendingActionStore#open_for.
+    def find_by_child_task(child_task_id)
+      id = child_task_id.to_s
+      scan { |d| return d if d.child_task_id == id }
+      nil
+    end
+
+    # -> [Delegation] that are NOT delivered yet (boot recovery). completed-but-
+    # undelivered = a crash between capture and delivery; dispatched = the child
+    # may or may not be terminal (the caller checks the child task).
+    def undelivered
+      scan.reject { |d| d.status == :delivered }
+    end
+
+    # dispatched -> completed, capturing the child's result/error. Idempotent: a
+    # second call on an already-completed/delivered record is a no-op (returns the
+    # current record) — the terminal hook and recovery can race.
+    def mark_completed(id, result: nil, error: nil)
+      record = fetch!(id)
+      return to_delegation(record) unless record["status"] == "dispatched"
+
+      record["status"] = "completed"
+      record["result"] = result
+      record["error"] = error
+      touch(id, record)
+    end
+
+    # completed -> delivered, ATOMICALLY (the claim) — across processes, not just
+    # fibers: the read-check-write rides Store#transaction, so two workers racing
+    # the same record serialize on the backend's lock and only one sees
+    # :completed. Returns true only for the caller that won the transition — that
+    # caller (and only it) spawns the delivery turn, so delivery is at-most-once
+    # even if the hook and recovery both fire. A record not in :completed
+    # (already delivered, or still dispatched) -> false.
+    def claim_delivery(id)
+      @store.transaction do
+        record = @store.get(SCOPE, key_for(id))
+        next false unless record && record["status"] == "completed"
+
+        record["status"] = "delivered"
+        record["updated_at"] = timestamp
+        @store.set(SCOPE, key_for(id), record)
+        true
+      end
+    end
+
+    private
+
+    def scan
+      return enum_for(:scan) unless block_given?
+
+      @store.list(SCOPE, KEY_PREFIX).each do |key|
+        record = @store.get(SCOPE, key)
+        yield to_delegation(record) if record
+      end
+    end
+
+    def fetch!(id)
+      @store.get(SCOPE, key_for(id)) ||
+        (raise Insika::NotFoundError, "delegation not found: #{id}")
+    end
+
+    def touch(id, record)
+      record["updated_at"] = timestamp
+      @store.set(SCOPE, key_for(id), record)
+      to_delegation(record)
+    end
+
+    def key_for(id) = "#{KEY_PREFIX}#{id}"
+
+    def to_delegation(record)
+      Delegation.new(
+        id: record["id"], parent_task_id: record["parent_task_id"],
+        parent_session_id: record["parent_session_id"], parent_agent: record["parent_agent"],
+        child_agent: record["child_agent"], child_task_id: record["child_task_id"],
+        child_session_id: record["child_session_id"], depth: record["depth"],
+        status: record["status"].to_sym, result: record["result"], error: record["error"],
+        created_at: record["created_at"], updated_at: record["updated_at"]
+      )
+    end
+
+    def timestamp = Time.now.utc.iso8601
+  end
+end

data/lib/insika/doctor.rb

@@ -0,0 +1,294 @@
+# frozen_string_literal: true
+
+module Insika
+  # `insika doctor` (item 23 / §8.1 — OpenClaw's "strict config + doctor --fix",
+  # "the repo's best productization discipline"). A read-only diagnosis of a
+  # deployment's configuration that turns the scattered, silent boot warnings into
+  # ONE structured report — and, with `--fix`, applies the safe autofixes.
+  #
+  # Every check is DATA (config over convention): an id, a title, and a lambda that
+  # inspects the injected collaborators and returns Findings. A Finding may carry a
+  # `fix` proc; `fix!` runs those and re-diagnoses. Collaborators are optional so the
+  # CLI can build them straight off the durable backend (no full app boot / no
+  # DEEPSEEK) and an env-only caller can skip the store checks entirely.
+  class Doctor
+    # severity: :ok (green) | :info | :warn | :error. `fix` = a 0-arg proc or nil.
+    Finding = Data.define(:check, :severity, :message, :fix) do
+      def fixable? = !fix.nil?
+      def ok? = severity == :ok
+      def error? = severity == :error
+      def to_h = { "check" => check, "severity" => severity.to_s, "message" => message, "fixable" => fixable? }
+    end
+
+    # The outcome of a run: the findings + convenience rollups + renderers.
+    Report = Data.define(:findings) do
+      def ok? = errors.empty?
+      def errors   = findings.select(&:error?)
+      def warnings = findings.select { |f| f.severity == :warn }
+      def fixable  = findings.select(&:fixable?)
+
+      def to_h
+        { "ok" => ok?, "counts" => counts, "findings" => findings.map(&:to_h) }
+      end
+
+      def counts
+        findings.each_with_object(Hash.new(0)) { |f, acc| acc[f.severity.to_s] += 1 }
+      end
+
+      # Human report. `color` wraps severities in ANSI when the sink is a TTY.
+      def to_s(color: false)
+        lines = findings.map { |f| "#{glyph(f.severity, color)} [#{f.check}] #{f.message}#{' (fixable)' if f.fixable?}" }
+        summary =
+          if ok? && warnings.empty? then "config OK"
+          elsif ok? then "config OK — #{warnings.length} warning(s)"
+          else "#{errors.length} error(s), #{warnings.length} warning(s)"
+          end
+        (lines + ["", summary]).join("\n")
+      end
+
+      private
+
+      def glyph(severity, color)
+        sym = { ok: "✓", info: "•", warn: "!", error: "✗" }.fetch(severity, "•")
+        return sym unless color
+
+        code = { ok: 32, info: 36, warn: 33, error: 31 }.fetch(severity, 0)
+        "\e[#{code}m#{sym}\e[0m"
+      end
+    end
+
+    def initialize(env: ENV, settings_store: nil, llm_provider_store: nil, tool_store: nil,
+                   agent_file_store: nil, backend: nil, extra_env_specs: [])
+      @env = env
+      @settings_store = settings_store
+      @llm_provider_store = llm_provider_store
+      @tool_store = tool_store
+      @agent_file_store = agent_file_store
+      @backend = backend
+      @extra_env_specs = extra_env_specs
+    end
+
+    # -> Report. Never raises (a broken check degrades to an :error Finding).
+    def run
+      Report.new(findings: checks.flat_map { |check| safe(check) }.freeze)
+    end
+
+    # Applies every fixable finding, then re-diagnoses. -> [Report before, Report after].
+    def fix!
+      before = run
+      before.fixable.map(&:fix).each(&:call)
+      [before, run]
+    end
+
+    private
+
+    def checks = %i[check_env check_settings_schema check_default_model check_db check_llm_provider
+                    check_admin_token check_data_tools check_prompt_files check_relay_channel
+                    check_web_widget]
+
+    def safe(check)
+      Array(send(check))
+    rescue StandardError => e
+      id = check.to_s.sub(/^check_/, "").tr("_", "-")
+      [Finding.new(check: id, severity: :error, message: "check crashed: #{e.class}: #{e.message}", fix: nil)]
+    end
+
+    # -- checks --------------------------------------------------------
+
+    def check_env
+      findings = Insika::EnvSchema.validate(@env, extra: @extra_env_specs)
+      return [ok("env", "environment: no unknown/invalid keys in owned namespaces")] if findings.empty?
+
+      findings.map { |f| Finding.new(check: "env", severity: f.severity, message: f.message, fix: nil) }
+    end
+
+    def check_settings_schema
+      return [] unless @settings_store
+
+      pending = @settings_store.pending_migrations
+      return [ok("settings-schema", "settings schema at v#{Insika::SettingsStore::SCHEMA_VERSION}")] if pending.empty?
+
+      [Finding.new(check: "settings-schema", severity: :warn,
+                   message: "settings schema at v#{@settings_store.stored_schema_version}, pending migration(s) #{pending.inspect} to v#{Insika::SettingsStore::SCHEMA_VERSION}",
+                   fix: -> { @settings_store.migrate! })]
+    end
+
+    def check_default_model
+      return [] unless @settings_store
+
+      settings = @settings_store.get
+      return [ok("default-model", "platform default model: #{settings['default_model']}")] if Insika::Coercion.present?(settings["default_model"])
+
+      seed = seed_model
+      fix = seed && -> { @settings_store.update("default_model" => seed) }
+      msg = "no platform default_model set (a model-less agent has nothing to resolve; set one in Studio > Settings)"
+      msg += " — fixable from #{seed}" if seed
+      [Finding.new(check: "default-model", severity: :warn, message: msg, fix: fix)]
+    end
+
+    def check_db
+      unless @backend.is_a?(Insika::Stores::SQLite)
+        return [Finding.new(check: "db", severity: :info,
+                            message: "ephemeral backend (INSIKA_DB unset) — config and state do NOT survive a restart", fix: nil)]
+      end
+
+      @backend.get("__doctor__", "probe") # a read round-trips the handle; raises if the file is broken
+      [ok("db", "durable backend: SQLite (readable)")]
+    rescue StandardError => e
+      [Finding.new(check: "db", severity: :error, message: "SQLite backend not usable: #{e.class}: #{e.message}", fix: nil)]
+    end
+
+    def check_llm_provider
+      return [] unless @llm_provider_store
+
+      configured = !Array(@llm_provider_store.apis).empty? || Insika::Coercion.present?(@env["DEEPSEEK_API_KEY"])
+      return [ok("llm-provider", "LLM provider configured")] if configured
+
+      [Finding.new(check: "llm-provider", severity: :warn,
+                   message: "no LLM provider configured (set DEEPSEEK_API_KEY or add one in Studio > LLM providers) — turns will fail", fix: nil)]
+    end
+
+    def check_admin_token
+      return [ok("admin-token", "ADMIN_TOKEN set")] if Insika::Coercion.present?(@env["ADMIN_TOKEN"])
+
+      [Finding.new(check: "admin-token", severity: :warn,
+                   message: "ADMIN_TOKEN unset — /studio is fail-closed (login denied) and the gateway has no fallback token", fix: nil)]
+    end
+
+    # A half-configured relay is the silent kind of broken (RFC-0011 §6): with only
+    # the deliver URL set, nothing is mounted and every inbound POST 404s; with only
+    # the token, the engine accepts turns it can never answer and the customer waits
+    # forever on a reply that is sitting in the outbox. Both halves or neither.
+    def check_relay_channel
+      token = Insika::Coercion.present?(@env["INSIKA_RELAY_TOKEN"])
+      url   = Insika::Coercion.present?(@env["INSIKA_RELAY_DELIVER_URL"])
+      return [] unless token || url
+
+      if token && url
+        [ok("relay-channel", "relay channel mounted at /channels/relay/events")]
+      elsif token
+        [Finding.new(check: "relay-channel", severity: :warn,
+                     message: "INSIKA_RELAY_TOKEN set without INSIKA_RELAY_DELIVER_URL — inbound is accepted but no reply can be delivered", fix: nil)]
+      else
+        [Finding.new(check: "relay-channel", severity: :warn,
+                     message: "INSIKA_RELAY_DELIVER_URL set without INSIKA_RELAY_TOKEN — the relay channel is NOT mounted (the token is the switch)", fix: nil)]
+      end
+    end
+
+    # The widget is the one PUBLIC channel, so its misconfigurations are the ones that
+    # cost money rather than just failing (RFC-0011 §5.3/§5.4). Three of them, in the
+    # order they bite: half the switch set (mounted nowhere, or mounted addressing
+    # nothing), and a mount with no chat rate limit anywhere — which the channel
+    # refuses with a 503 rather than opening, but which reads to an operator as "the
+    # widget is broken" unless something says why.
+    def check_web_widget
+      origins = Insika::Coercion.present?(@env["INSIKA_WIDGET_ORIGINS"])
+      agents  = Insika::Coercion.present?(@env["INSIKA_WIDGET_AGENTS"])
+      return [] unless origins || agents
+
+      unless origins && agents
+        missing = origins ? "INSIKA_WIDGET_AGENTS" : "INSIKA_WIDGET_ORIGINS"
+        return [Finding.new(check: "web-widget", severity: :warn,
+                            message: "#{missing} unset — the web widget is NOT mounted (both allowlists are the switch)", fix: nil)]
+      end
+
+      return [ok("web-widget", "web widget mounted at /channels/web (origins + agents allowlisted, rate limit configured)")] if platform_chat_rate_limit
+
+      # No platform default. A per-agent `limits.chat_rate_limit` still satisfies the
+      # gate, and the profiles are not readable from here, so this is a warning and
+      # not an error — but it is the likeliest reason a widget answers 503.
+      [Finding.new(check: "web-widget", severity: :warn,
+                   message: "no platform edge.chat_rate_limit — the widget answers 503 unless EVERY agent in " \
+                            "INSIKA_WIDGET_AGENTS sets limits.chat_rate_limit (a public channel with no ceiling is not served)", fix: nil)]
+    end
+
+    def platform_chat_rate_limit
+      value = ((@settings_store&.get || {})["edge"] || {})["chat_rate_limit"]
+      value.to_i.positive?
+    end
+
+    # A stored data-tool whose definition no longer builds is INVISIBLE at runtime: the
+    # overlay warns to stderr and drops it, so the agent simply stops seeing the tool.
+    # This check is that drop's only report. The one legacy case is auto-fixable: a
+    # flat param typed bare `array`, which used to mean "list of strings" — the fix
+    # writes that meaning down as `array:string` and changes nothing at runtime.
+# A prompt file holding the Ruby #inspect of a Hash instead of markdown. The write
+# path refuses this now, but a deployment corrupted BEFORE that guard keeps serving
+# the mangled prompt on every turn, and nothing else would ever say so: the file is
+# present, non-empty, and the agent answers — worse than a crash. Found on the pilot
+# by an `insika refine` report, three weeks after the fact.
+def check_prompt_files
+  return [] unless @agent_file_store
+
+  agents = @agent_file_store.agents
+  wrapped = agents.flat_map do |agent|
+    @agent_file_store.list(agent).filter_map do |name|
+      next unless wrapped_content?(@agent_file_store.read(agent, name))
+
+      Finding.new(check: "prompt-files", severity: :error, fix: nil,
+                  message: "agent '#{agent}' file '#{name}' holds a serialized object, not text — " \
+                           "the model receives `{\"content\" => …}` on one line, escapes and all. " \
+                           "Recover the markdown from inside the wrapper and write it back.")
+    end
+  end
+  return wrapped if wrapped.any?
+
+  total = agents.sum { |a| @agent_file_store.list(a).length }
+  [ok("prompt-files", "#{total} prompt file(s) across #{agents.length} agent(s): all text")]
+end
+
+# Cheap and specific: Ruby's inspect of a Hash whose first key is a string. A real
+# prompt does not open with `{"…" =>`.
+def wrapped_content?(content) = /\A\s*\{\s*"[^"]+"\s*=>/.match?(content.to_s)
+
+    def check_data_tools
+      return [] unless @tool_store
+
+      broken = @tool_store.all_raw.filter_map { |raw| broken_tool(raw) }
+      total = @tool_store.names.length
+      return [ok("data-tools", "#{total} data tool(s): every definition valid")] if broken.empty?
+
+      broken
+    end
+
+    def broken_tool(raw)
+      Insika::ToolDefinition.from_h(raw)
+      nil
+    rescue Insika::ValidationError => e
+      name = raw.is_a?(Hash) ? raw["name"].to_s : ""
+      fix = array_sugar_fix(raw)
+      message = "tool '#{name}' is dropped from the catalog: #{e.message}"
+      # The autofix preserves the OLD behaviour, which is not always the INTENDED one:
+      # a list of objects has been reaching the model declared as a list of strings.
+      # Say so, so nobody reads a green doctor as "this tool is right".
+      message += " — the fix only writes down what it has been sending (a list of strings); " \
+                 "if the API expects objects, paste the real JSON Schema in Studio instead" if fix
+      Finding.new(check: "data-tools", severity: :error, fix: fix, message: message)
+    end
+
+    # A fix ONLY when spelling the legacy bare `array` explicitly is enough to make the
+    # definition build — never a guess at a broken definition we don't understand.
+    def array_sugar_fix(raw)
+      params = raw.is_a?(Hash) ? raw["parameters"] : nil
+      return nil unless params.is_a?(Array) && params.any? { |p| p.is_a?(Hash) && p["type"].to_s == "array" }
+
+      candidate = raw.merge("parameters" => params.map do |p|
+        p.is_a?(Hash) && p["type"].to_s == "array" ? p.merge("type" => "array:string") : p
+      end)
+      Insika::ToolDefinition.from_h(candidate)
+      -> { @tool_store.write(candidate) }
+    rescue Insika::ValidationError
+      nil
+    end
+
+    # -- helpers -------------------------------------------------------
+
+    def ok(check, message) = Finding.new(check: check, severity: :ok, message: message, fix: nil)
+
+    # A model to seed the platform default from: DEEPSEEK_MODEL env, else the first
+    # configured provider's default. nil when nothing to seed from.
+    def seed_model
+      Insika::Coercion.presence(@env["DEEPSEEK_MODEL"])
+    end
+  end
+end

data/lib/insika/dsl/definition.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Insika
+  module DSL
+    # The result of `Insika.agent("id") { … }`. Holds the generated Pack and knows
+    # how to run it — but stays gem-free until you actually chat/serve/introspect:
+    # the runtime (ruby_llm + the HTTP server) is required lazily inside Runtime.
+    #
+    # Every runtime path goes through the SAME config-over-code import: the pack is
+    # imported (create_agent + write_agent_file/skill/data_tool) into a StoredProfileSource,
+    # exactly like any other pack. That is what makes `#profile` identical to a
+    # hand-written equivalent pack (the parity spec) — there is only one path.
+    class Definition
+      attr_reader :pack, :runtime_options
+
+      def initialize(pack:, runtime: {})
+        @pack = pack
+        @runtime_options = runtime
+      end
+
+      def id = pack.config[:id].to_s
+
+      # The generated portable artifact — hand it to any PackImporter and you get
+      # this same agent. This is the DSL's real output.
+      def to_pack = @pack
+
+      # The AgentProfile the engine runs, read back from the store after import —
+      # so it is byte-for-byte what a hand-written equivalent pack produces.
+      def profile = runtime.profile
+
+      # One turn, in-process, returns the assistant's text. `session:` threads
+      # multi-turn memory (a session is created on first use); omit it for a
+      # stateless one-shot. Raises on a failed/cancelled turn.
+      def reply(message, session: nil, timeout: nil)
+        runtime.chat(message, session_id: session, timeout: timeout)
+      end
+      alias_method :chat, :reply
+
+      # Boot the control UI (/studio) + the drop-in API (/v1) — the "1 command"
+      # of the quickstart. Blocks (runs the reactor) until interrupted.
+      def serve(port: 9292, host: "localhost", token: nil, **opts)
+        runtime.serve(port: port, host: host, token: token, **opts)
+      end
+
+      # The live runtime graph (Executor + bus + stores) with the pack imported.
+      # Memoized: chat/serve/profile share one graph. Pulls in ruby_llm here.
+      def runtime
+        @runtime ||= begin
+          require_relative "runtime"
+          Runtime.new(self)
+        end
+      end
+    end
+  end
+end