igniter 0.5.0 → 0.5.1

data/{lib/igniter → packages/igniter-core/lib/igniter/core}/runtime/resolver.rb

@@ -25,6 +25,8 @@ module Igniter
                   resolve_branch(node)
                 when :collection
                   resolve_collection(node)
+                when :agent
+                  resolve_agent(node)
                 when :effect
                   resolve_effect(node)
                 when :await
@@ -41,15 +43,20 @@ module Igniter
         emit_resolution_event(node, state)
         state
       rescue PendingDependencyError => e
+        payload = e.deferred_result.payload
+        payload = payload.merge(routing_trace: e.explanation) if e.respond_to?(:explanation) && e.explanation
+
         state = NodeState.new(
           node: node,
           status: :pending,
-          value: Runtime::DeferredResult.build(
+          value: build_pending_value(
+            node,
             token: e.deferred_result.token,
-            payload: e.deferred_result.payload,
+            payload: payload,
             source_node: e.deferred_result.source_node,
             waiting_on: e.deferred_result.waiting_on || node.name
-          )
+          ),
+          details: pending_details(node, payload)
         )
         @execution.cache.write(state)
         @execution.events.emit(:node_pending, node: node, status: :pending, payload: pending_payload(state))
@@ -57,7 +64,7 @@ module Igniter
       rescue StandardError => e
         state = NodeState.new(node: node, status: :failed, error: normalize_error(e, node))
         @execution.cache.write(state)
-        @execution.events.emit(:node_failed, node: node, status: :failed, payload: { error: state.error.message })
+        @execution.events.emit(:node_failed, node: node, status: :failed, payload: failure_payload(state))
         state
       end
 
@@ -100,6 +107,54 @@ module Igniter
         NodeState.new(node: node, status: :succeeded, value: value)
       end
 
+      def resolve_agent(node)
+        inputs = node.input_mapping.each_with_object({}) do |(message_input, dep_name), memo|
+          memo[message_input] = resolve_dependency_value(dep_name)
+        end
+
+        response =
+          if node.mode == :cast
+            @execution.agent_adapter.cast(
+              node: node,
+              inputs: inputs,
+              execution: @execution
+            )
+          else
+            @execution.agent_adapter.call(
+              node: node,
+              inputs: inputs,
+              execution: @execution
+            )
+          end
+
+        case response[:status]
+        when :succeeded
+          validate_agent_success_mode!(node)
+          NodeState.new(
+            node: node,
+            status: :succeeded,
+            value: response.fetch(:output, nil),
+            details: agent_details(response)
+          )
+        when :pending
+          validate_agent_pending_mode!(node)
+          payload = merge_agent_trace(response[:payload] || {}, response[:agent_trace])
+          deferred = normalize_agent_deferred(response, node, payload)
+          raise PendingDependencyError.new(deferred, response[:message] || "Agent node '#{node.name}' is pending")
+        when :failed
+          error_message = response.dig(:error, :message) || response.dig(:error, "message") || "agent call failed"
+          raise ResolutionError.new(
+            "Agent #{node.agent_name}: #{error_message}",
+            context: { agent_trace: response[:agent_trace] }.compact
+          )
+        else
+          raise ResolutionError.new(
+            "Agent #{node.agent_name}: unexpected status '#{response[:status]}'",
+            context: { agent_trace: response[:agent_trace] }.compact
+          )
+        end
+      end
+
       def resolve_await(node)
         deferred = Runtime::DeferredResult.build(
           payload: { event: node.event_name },
@@ -109,61 +164,25 @@ module Igniter
         raise PendingDependencyError.new(deferred, "Waiting for external event '#{node.event_name}'")
       end
 
-      def resolve_remote(node) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
-        unless defined?(Igniter::Server::Client)
-          raise ResolutionError,
-                "remote: nodes require `require 'igniter/server'` (server integration not loaded)"
-        end
-
-        url = resolve_remote_url(node)
-
+      def resolve_remote(node)
         inputs = node.input_mapping.each_with_object({}) do |(child_input, dep_name), memo|
           memo[child_input] = resolve_dependency_value(dep_name)
         end
 
-        client   = Igniter::Server::Client.new(url, timeout: node.timeout)
-        response = client.execute(node.contract_name, inputs: inputs)
+        response = @execution.remote_adapter.call(
+          node: node,
+          inputs: inputs,
+          execution: @execution
+        )
 
         case response[:status]
         when :succeeded
           NodeState.new(node: node, status: :succeeded, value: response[:outputs])
         when :failed
           error_message = response.dig(:error, :message) || response.dig(:error, "message")
-          raise ResolutionError,
-                "Remote #{node.contract_name}@#{url}: #{error_message}"
+          raise ResolutionError, "Remote #{node.contract_name}: #{error_message}"
         else
-          raise ResolutionError,
-                "Remote #{node.contract_name}@#{url}: unexpected status '#{response[:status]}'"
-        end
-      rescue Igniter::Server::Client::ConnectionError => e
-        raise ResolutionError, "Cannot reach #{url}: #{e.message}"
-      end
-
-      # Resolve the target URL for a remote node based on its routing_mode.
-      # :static     → node_url directly
-      # :capability → Mesh::Router selects an alive peer (raises DeferredCapabilityError if none)
-      # :pinned     → Mesh::Router asserts the peer is alive (raises IncidentError if not)
-      def resolve_remote_url(node) # rubocop:disable Metrics/MethodLength
-        case node.routing_mode
-        when :static
-          node.node_url
-        when :capability
-          unless defined?(Igniter::Mesh)
-            raise ResolutionError,
-                  "remote :#{node.name} uses capability routing — add `require 'igniter/mesh'`"
-          end
-          deferred = Runtime::DeferredResult.build(
-            payload: { capability: node.capability },
-            source_node: node.name,
-            waiting_on: node.name
-          )
-          Igniter::Mesh.router.find_peer_for(node.capability, deferred)
-        when :pinned
-          unless defined?(Igniter::Mesh)
-            raise ResolutionError,
-                  "remote :#{node.name} uses pinned routing — add `require 'igniter/mesh'`"
-          end
-          Igniter::Mesh.router.resolve_pinned(node.pinned_to)
+          raise ResolutionError, "Remote #{node.contract_name}: unexpected status '#{response[:status]}'"
         end
       end
 
@@ -318,9 +337,9 @@ module Igniter
 
       def resolve_branch(node)
         selector_value = resolve_dependency_value(node.selector_dependency)
-        selected_case = node.cases.find { |entry| entry[:match] == selector_value }
+        selected_case = node.match_case(selector_value)
         selected_contract = selected_case ? selected_case[:contract] : node.default_contract
-        matched_case = selected_case ? selected_case[:match] : :default
+        matched_case = selected_case ? node.case_payload(selected_case) : :default
 
         raise BranchSelectionError, "Branch '#{node.name}' has no matching case and no default" unless selected_contract
 
@@ -343,6 +362,7 @@ module Igniter
           payload: {
             selector: node.selector_dependency,
             selector_value: selector_value,
+            matcher: selected_case ? selected_case[:matcher] : :default,
             matched_case: matched_case,
             selected_contract: selected_contract.name || "AnonymousContract"
           }
@@ -523,7 +543,8 @@ module Igniter
       end
 
       def normalize_deferred_result(value, node)
-        Runtime::DeferredResult.build(
+        build_pending_value(
+          node,
           token: value.token,
           payload: value.payload,
           source_node: value.source_node || node.name,
@@ -559,6 +580,17 @@ module Igniter
         state.value.to_h
       end
 
+      def pending_details(node, payload)
+        return {} unless node.kind == :agent
+
+        agent_trace = payload[:agent_trace] || payload["agent_trace"]
+        agent_session = payload[:agent_session] || payload["agent_session"]
+        {
+          agent_trace: agent_trace,
+          agent_session: agent_session
+        }.compact
+      end
+
       def pending_context(node)
         {
           graph: @execution.compiled_graph.name,
@@ -570,13 +602,172 @@ module Igniter
       end
 
       def success_payload(node, state)
-        return {} unless %i[composition branch].include?(node.kind)
-        return {} unless state.value.is_a?(Igniter::Runtime::Result)
+        payload = {}
+
+        if %i[composition branch].include?(node.kind) && state.value.is_a?(Igniter::Runtime::Result)
+          payload[:child_execution_id] = state.value.execution.events.execution_id
+          payload[:child_graph] = state.value.execution.compiled_graph.name
+        end
 
+        if node.kind == :agent && state.details[:agent_trace]
+          payload[:agent_trace] = state.details[:agent_trace]
+        end
+
+        payload
+      end
+
+      def failure_payload(state)
+        payload = { error: state.error.message }
+        context = state.error.respond_to?(:context) ? state.error.context : {}
+        payload[:routing_trace] = context[:routing_trace] if context[:routing_trace]
+        payload[:agent_trace] = context[:agent_trace] if context[:agent_trace]
+        payload
+      end
+
+      def agent_details(response)
+        trace = response[:agent_trace]
+        session = response[:agent_session] || response[:session]
         {
-          child_execution_id: state.value.execution.events.execution_id,
-          child_graph: state.value.execution.compiled_graph.name
-        }
+          agent_trace: trace,
+          agent_session: session
+        }.compact
+      end
+
+      def merge_agent_trace(payload, agent_trace)
+        return payload unless agent_trace
+
+        payload.merge(agent_trace: agent_trace)
+      end
+
+      def merge_agent_session(payload, agent_session)
+        return payload unless agent_session
+
+        payload.merge(agent_session: agent_session)
+      end
+
+      def normalize_agent_session(response, node, payload, token:)
+        raw_session = response[:agent_session] || response[:session]
+        default_session = Runtime::AgentSession.new(
+          token: token,
+          node_name: node.name,
+          node_path: node.path,
+          agent_name: node.agent_name,
+          message_name: node.message_name,
+          mode: node.mode,
+          reply_mode: node.reply_mode,
+          finalizer: node.finalizer,
+          tool_loop_policy: node.tool_loop_policy,
+          session_policy: node.session_policy,
+          node_url: node.node_url,
+          capability: node.capability,
+          capability_query: node.capability_query,
+          pinned_to: node.pinned_to,
+          waiting_on: node.name,
+          source_node: node.name,
+          trace: response[:agent_trace],
+          payload: session_payload_from(payload),
+          turn: 1,
+          phase: default_agent_session_phase(node),
+          history: [
+            {
+              turn: 1,
+              event: :opened,
+              token: token,
+              waiting_on: node.name,
+              payload: session_payload_from(payload),
+              phase: default_agent_session_phase(node)
+            }
+          ]
+        )
+
+        if raw_session.respond_to?(:to_h) || raw_session.is_a?(Hash)
+          session_hash = raw_session.respond_to?(:to_h) ? raw_session.to_h : raw_session
+          merged = default_session.to_h.merge(session_hash.transform_keys(&:to_sym))
+          return Runtime::AgentSession.from_h(merged).to_h
+        end
+
+        default_session.to_h
+      end
+
+      def normalize_agent_deferred(response, node, payload)
+        base_deferred = response[:deferred_result]
+        token = base_deferred&.token
+        source_node = base_deferred&.source_node || node.name
+        waiting_on = base_deferred&.waiting_on || node.name
+        base_payload = base_deferred&.payload || payload
+        merged_payload = merge_agent_trace(base_payload, response[:agent_trace])
+
+        deferred = build_pending_value(
+          node,
+          token: token,
+          payload: merged_payload,
+          source_node: source_node,
+          waiting_on: waiting_on
+        )
+
+        session = normalize_agent_session(response, node, deferred.payload, token: deferred.token)
+        final_payload = merge_agent_session(deferred.payload, session)
+
+        build_pending_value(
+          node,
+          token: deferred.token,
+          payload: final_payload,
+          source_node: deferred.source_node,
+          waiting_on: deferred.waiting_on
+        )
+      end
+
+      def session_payload_from(payload)
+        return {} unless payload.is_a?(Hash)
+
+        payload.each_with_object({}) do |(key, value), memo|
+          next if %i[agent_trace agent_session].include?(key.to_sym)
+
+          memo[key] = value
+        end
+      end
+
+      def validate_agent_pending_mode!(node)
+        return unless node.reply_mode == :single
+
+        raise ResolutionError.new(
+          "Agent #{node.agent_name}: reply mode :single cannot return pending. Use reply: :deferred or :stream.",
+          context: {
+            graph: @execution.compiled_graph.name,
+            node_name: node.name,
+            node_path: node.path,
+            agent_reply_mode: node.reply_mode
+          }
+        )
+      end
+
+      def validate_agent_success_mode!(node)
+        return unless node.reply_mode == :stream
+
+        raise ResolutionError.new(
+          "Agent #{node.agent_name}: reply mode :stream requires session-based pending delivery before completion.",
+          context: {
+            graph: @execution.compiled_graph.name,
+            node_name: node.name,
+            node_path: node.path,
+            agent_reply_mode: node.reply_mode
+          }
+        )
+      end
+
+      def default_agent_session_phase(node)
+        node.reply_mode == :stream ? :streaming : :waiting
+      end
+
+      def build_pending_value(node, token:, payload:, source_node:, waiting_on:)
+        result_class = node.kind == :agent && node.reply_mode == :stream ? Runtime::StreamResult : Runtime::DeferredResult
+
+        result_class.build(
+          token: token,
+          payload: payload,
+          source_node: source_node,
+          waiting_on: waiting_on
+        )
       end
 
       def normalize_error(error, node)
@@ -598,7 +789,9 @@ module Igniter
           execution_id: @execution.events.execution_id
         }
 
-        ResolutionError.new(error.message, context: node_context)
+        existing_context = error.respond_to?(:context) ? error.context : {}
+
+        ResolutionError.new(error.message, context: node_context.merge(existing_context))
       end
 
       # ─── Capabilities ──────────────────────────────────────────────────────────

data/{lib/igniter → packages/igniter-core/lib/igniter/core}/runtime/result.rb

@@ -90,6 +90,8 @@ module Igniter
 
       def serialize_output_value(value)
         case value
+        when StreamResult
+          value.as_json
         when DeferredResult
           value.as_json
         when Result

data/packages/igniter-core/lib/igniter/core/runtime/stores/sqlite_store.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module Igniter
+  module Runtime
+    module Stores
+      class SQLiteStore
+        def initialize(path:)
+          require "sqlite3"
+        rescue LoadError
+          raise Igniter::Runtime::ConfigurationError,
+                "`igniter` now ships with a required `sqlite3` dependency. " \
+                "If it is missing in this environment, run bundle install or reinstall the gem."
+        else
+          prepare_path!(path)
+          @mutex = Mutex.new
+          @db = ::SQLite3::Database.new(path)
+          @db.results_as_hash = true
+          create_schema!
+        end
+
+        def save(snapshot, correlation: nil, graph: nil)
+          execution_id = snapshot[:execution_id] || snapshot["execution_id"]
+          resolved_graph = graph || snapshot[:graph] || snapshot["graph"]
+          correlation_json = normalized_correlation_json(correlation)
+          pending = pending_snapshot?(snapshot) ? 1 : 0
+
+          @mutex.synchronize do
+            @db.execute(
+              <<~SQL,
+                INSERT OR REPLACE INTO execution_snapshots
+                  (execution_id, graph, correlation_json, pending, snapshot_json, updated_at)
+                VALUES (?, ?, ?, ?, ?, ?)
+              SQL
+              [execution_id, resolved_graph, correlation_json, pending, JSON.generate(snapshot), Time.now.to_i]
+            )
+          end
+
+          execution_id
+        end
+
+        def find_by_correlation(graph:, correlation:)
+          @mutex.synchronize do
+            row = @db.get_first_row(
+              "SELECT execution_id FROM execution_snapshots WHERE graph = ? AND correlation_json = ?",
+              [graph, normalized_correlation_json(correlation)]
+            )
+            row && row["execution_id"]
+          end
+        end
+
+        def list_all(graph: nil)
+          @mutex.synchronize do
+            rows =
+              if graph
+                @db.execute(
+                  "SELECT execution_id FROM execution_snapshots WHERE graph = ? ORDER BY updated_at ASC",
+                  [graph]
+                )
+              else
+                @db.execute("SELECT execution_id FROM execution_snapshots ORDER BY updated_at ASC")
+              end
+            rows.map { |row| row["execution_id"] }
+          end
+        end
+
+        def list_pending(graph: nil)
+          @mutex.synchronize do
+            rows =
+              if graph
+                @db.execute(
+                  "SELECT execution_id FROM execution_snapshots WHERE graph = ? AND pending = 1 ORDER BY updated_at ASC",
+                  [graph]
+                )
+              else
+                @db.execute("SELECT execution_id FROM execution_snapshots WHERE pending = 1 ORDER BY updated_at ASC")
+              end
+            rows.map { |row| row["execution_id"] }
+          end
+        end
+
+        def fetch(execution_id)
+          @mutex.synchronize do
+            row = @db.get_first_row(
+              "SELECT snapshot_json FROM execution_snapshots WHERE execution_id = ?",
+              [execution_id]
+            )
+            raise Igniter::ResolutionError, "No execution snapshot found for '#{execution_id}'" unless row
+
+            JSON.parse(row["snapshot_json"])
+          end
+        end
+
+        def delete(execution_id)
+          @mutex.synchronize do
+            @db.execute("DELETE FROM execution_snapshots WHERE execution_id = ?", [execution_id])
+          end
+        end
+
+        def exist?(execution_id)
+          @mutex.synchronize do
+            row = @db.get_first_row(
+              "SELECT 1 FROM execution_snapshots WHERE execution_id = ? LIMIT 1",
+              [execution_id]
+            )
+            !row.nil?
+          end
+        end
+
+        private
+
+        def create_schema!
+          @db.execute_batch(<<~SQL)
+            CREATE TABLE IF NOT EXISTS execution_snapshots (
+              execution_id TEXT PRIMARY KEY,
+              graph TEXT,
+              correlation_json TEXT,
+              pending INTEGER NOT NULL DEFAULT 0,
+              snapshot_json TEXT NOT NULL,
+              updated_at INTEGER NOT NULL
+            );
+            CREATE INDEX IF NOT EXISTS idx_execution_snapshots_graph
+              ON execution_snapshots(graph);
+            CREATE INDEX IF NOT EXISTS idx_execution_snapshots_pending
+              ON execution_snapshots(pending, updated_at);
+            CREATE INDEX IF NOT EXISTS idx_execution_snapshots_graph_correlation
+              ON execution_snapshots(graph, correlation_json);
+          SQL
+        end
+
+        def normalized_correlation_json(correlation)
+          return nil if correlation.nil? || correlation.empty?
+
+          JSON.generate(correlation.transform_keys(&:to_s).sort.to_h)
+        end
+
+        def pending_snapshot?(snapshot)
+          states = snapshot[:states] || snapshot["states"] || {}
+          states.any? do |_name, state|
+            status = state[:status] || state["status"]
+            status.to_s == "pending"
+          end
+        end
+
+        def prepare_path!(path)
+          return if path.to_s.empty? || path == ":memory:"
+
+          FileUtils.mkdir_p(::File.dirname(path))
+        end
+      end
+    end
+  end
+end