ask-runtime 0.1.0

data/lib/ask/runtime/events/tool_timed_out.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative "../tool_call"
+require_relative "../tool_result"
+require_relative "../execution_context"
+
+module Ask
+  module Runtime
+    module Events
+      # Immutable event emitted when a tool call exceeds its execution time
+      # limit and is terminated.
+      #
+      # Carries the terminal ToolCall snapshot (state: :timed_out), the
+      # ToolResult with outcome: :timeout, the ExecutionContext, a monotonic
+      # timestamp, and the wall-clock duration in seconds.
+      #
+      #   event = ToolTimedOut.new(
+      #     tool_call: finished_call, tool_result: result,
+      #     execution_context: ctx, timestamp: Time.now, duration: 30.0
+      #   )
+      #   event.timed_out?  #=> true
+      #   event.duration    #=> 30.0
+      #
+      class ToolTimedOut
+        attr_reader :tool_call, :tool_result, :execution_context, :timestamp, :duration
+
+        def initialize(tool_call:, tool_result:, execution_context:, timestamp:, duration:)
+          raise ArgumentError, "tool_call required" unless tool_call.is_a?(Ask::Runtime::ToolCall)
+          raise ArgumentError, "tool_result required" unless tool_result.is_a?(Ask::Runtime::ToolResult)
+          raise ArgumentError, "execution_context required" unless execution_context.is_a?(Ask::Runtime::ExecutionContext)
+          raise ArgumentError, "timestamp required" unless timestamp.is_a?(Time)
+
+          @tool_call = tool_call
+          @tool_result = tool_result
+          @execution_context = execution_context
+          @timestamp = timestamp
+          @duration = duration
+          freeze
+        end
+
+        def tool_call_id = @tool_call.id
+        def tool_name = @tool_call.tool_name
+        def timed_out? = @tool_result.timeout?
+
+        def to_h
+          {
+            tool_call: @tool_call,
+            tool_result: @tool_result,
+            execution_context: @execution_context,
+            timestamp: @timestamp,
+            duration: @duration,
+            tool_call_id: tool_call_id,
+            tool_name: tool_name
+          }
+        end
+
+        def inspect
+          "#<ToolTimedOut tool=#{tool_name.inspect} id=#{tool_call_id.inspect} duration=#{@duration}>"
+        end
+      end
+    end
+  end
+end

data/lib/ask/runtime/events.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "events/tool_started"
+require_relative "events/tool_completed"
+require_relative "events/tool_failed"
+require_relative "events/tool_cancelled"
+require_relative "events/tool_timed_out"
+
+module Ask
+  module Runtime
+    # Immutable event value objects for tool-call lifecycle notifications.
+    #
+    # Each event is a frozen +Data.define+ instance carrying a snapshot of
+    # the ToolCall, ToolResult (when terminal), ExecutionContext, timestamp,
+    # and duration (when terminal).
+    #
+    # Events are emitted through an +EventSink+ and can be observed by
+    # listeners without coupling to the executor implementation.
+    #
+    # @see EventSink
+    # @see ToolCall
+    # @see ToolResult
+    module Events
+      # @!method tool_call
+      #   @return [ToolCall] snapshot of the tool call at the time of the event
+
+      # @!method execution_context
+      #   @return [ExecutionContext] the execution context for this tool call
+
+      # @!method timestamp
+      #   @return [Time] wall-clock time when the event was created
+    end
+  end
+end

data/lib/ask/runtime/execution_context.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require_relative "canceller"
+require_relative "event_sink"
+
+module Ask
+  module Runtime
+    # Immutable context for tool execution.
+    #
+    # ExecutionContext bundles everything a tool executor needs beyond the
+    # ToolCall itself: session/turn correlation, caller identity, workspace,
+    # capabilities, cancellation support, event emission, artifact storage,
+    # and arbitrary metadata.
+    #
+    # All attributes are set at construction time and frozen.
+    #
+    #   ctx = Ask::Runtime::ExecutionContext.new(
+    #     session_id: "s_001",
+    #     turn: 3,
+    #     caller_id: "agent_main",
+    #     workspace: "/tmp/work",
+    #     capabilities: [:file_read, :file_write]
+    #   )
+    #
+    class ExecutionContext
+      # @return [String, nil] session identifier
+      attr_reader :session_id
+
+      # @return [Integer, nil] current turn number
+      attr_reader :turn
+
+      # @return [String, nil] caller identifier
+      attr_reader :caller_id
+
+      # @return [String, nil] workspace root directory
+      attr_reader :workspace
+
+      # @return [Array<Symbol>] capability symbols this execution may use
+      attr_reader :capabilities
+
+      # @return [Canceller] cooperative cancellation token
+      attr_reader :canceller
+
+      # @return [EventSink] event emitter for lifecycle notifications
+      attr_reader :event_sink
+
+      # @return [Hash] artifact store (tool_name => artifact data)
+      attr_reader :artifact_store
+
+      # @return [Hash] arbitrary metadata
+      attr_reader :metadata
+
+      # @return [Time] when this context was created
+      attr_reader :created_at
+
+      def initialize(session_id: nil, turn: nil, caller_id: nil,
+                     workspace: nil, capabilities: [],
+                     canceller: nil, event_sink: nil,
+                     artifact_store: nil, metadata: {},
+                     created_at: Time.now)
+        @session_id = session_id
+        @turn = turn
+        @caller_id = caller_id
+        @workspace = workspace
+        @capabilities = Array(capabilities).freeze
+        @canceller = canceller || Canceller.new
+        @event_sink = event_sink || EventSink.new
+        @artifact_store = artifact_store ? artifact_store.dup.freeze : {}.freeze
+        @metadata = metadata.dup.freeze
+        @created_at = created_at
+        freeze
+      end
+
+      # @return [Boolean] whether this context is correlated to a session
+      def session?
+        !@session_id.nil?
+      end
+
+      # @return [Boolean] whether a specific capability is available
+      def has_capability?(cap)
+        @capabilities.include?(cap)
+      end
+
+      # @return [Boolean] whether the execution has been cancelled
+      def cancelled?
+        @canceller.cancelled?
+      end
+
+      # Return a new ExecutionContext with the given attributes replaced.
+      #
+      # @param attrs [Hash] attributes to override
+      # @return [ExecutionContext] a new frozen instance
+      def with(**attrs)
+        self.class.new(**to_h.merge(attrs))
+      end
+
+      # @return [Hash] serializable representation
+      def to_h
+        {
+          session_id: @session_id,
+          turn: @turn,
+          caller_id: @caller_id,
+          workspace: @workspace,
+          capabilities: @capabilities,
+          canceller: @canceller,
+          event_sink: @event_sink,
+          artifact_store: @artifact_store,
+          metadata: @metadata,
+          created_at: @created_at
+        }
+      end
+
+      def inspect
+        "#<Ask::Runtime::ExecutionContext session=#{@session_id.inspect} turn=#{@turn.inspect} caller=#{@caller_id.inspect}>"
+      end
+    end
+  end
+end

data/lib/ask/runtime/testing/executor_contract.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Ask
+  module Runtime
+    module Testing
+      # Minitest assertions for checking a ToolExecutor implementation.
+      #
+      # Include this module in an adapter test class and call
+      # +assert_conforms_to_runtime_contract+ with representative calls:
+      #
+      #   include Ask::Runtime::Testing::ExecutorContract
+      #
+      #   assert_conforms_to_runtime_contract(
+      #     executor,
+      #     success_call: success_call,
+      #     failure_call: failure_call,
+      #     cancelled_call: cancelled_call,
+      #     context_factory: ->(event_sink:) { build_context(event_sink:) }
+      #   )
+      #
+      # The adapter remains responsible for backend-specific tests; this
+      # helper checks the shared result, cancellation, event, and correlation
+      # contract that every runtime executor must provide.
+      module ExecutorContract
+        def assert_conforms_to_runtime_contract(executor, success_call:, failure_call:,
+                                                cancelled_call:, context_factory:)
+          assert_respond_to executor, :execute
+
+          success_sink = Ask::Runtime::EventSink.new
+          success_events = []
+          observe_events(success_sink, success_events)
+          success_context = context_factory.call(event_sink: success_sink)
+          success_result = executor.execute(success_call, context: success_context)
+
+          assert_instance_of Ask::Runtime::ToolResult, success_result
+          assert_predicate success_result, :success?
+          refute_nil success_result.duration
+          assert_operator success_result.duration, :>=, 0
+          assert_equal %i[tool_started tool_completed], success_events.map(&:first)
+
+          terminal_event = success_events.last.last
+          assert_equal success_call.id, terminal_event.tool_call_id
+          assert_equal success_call.session_id, terminal_event.tool_call.session_id
+          assert_equal :completed, terminal_event.tool_call.state
+
+          failure_sink = Ask::Runtime::EventSink.new
+          failure_events = []
+          observe_events(failure_sink, failure_events)
+          failure_result = executor.execute(
+            failure_call, context: context_factory.call(event_sink: failure_sink)
+          )
+          assert_instance_of Ask::Runtime::ToolResult, failure_result
+          assert_predicate failure_result, :failure?
+          assert_equal %i[tool_started tool_failed], failure_events.map(&:first)
+
+          canceller = Ask::Runtime::Canceller.new
+          canceller.cancel
+          cancellation_sink = Ask::Runtime::EventSink.new
+          cancellation_events = []
+          observe_events(cancellation_sink, cancellation_events)
+          cancellation_context = context_factory.call(event_sink: cancellation_sink, canceller: canceller)
+          cancelled_result = executor.execute(
+            cancelled_call,
+            context: cancellation_context
+          )
+          assert_instance_of Ask::Runtime::ToolResult, cancelled_result
+          assert_predicate cancelled_result, :cancelled?
+          assert_equal %i[tool_started tool_cancelled], cancellation_events.map(&:first)
+        end
+
+        private
+
+        def observe_events(sink, events)
+          %i[tool_started tool_completed tool_failed tool_cancelled tool_timed_out].each do |type|
+            sink.on(type) { |payload| events << [type, payload[:event]] }
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/ask/runtime/testing.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "testing/executor_contract"
+
+module Ask
+  module Runtime
+    # Optional helpers for adapter authors writing runtime contract tests.
+    module Testing
+    end
+  end
+end

data/lib/ask/runtime/tool_call.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require_relative "canceller"
+require_relative "event_sink"
+
+module Ask
+  module Runtime
+    # Immutable value object representing a single tool-call request.
+    #
+    # A ToolCall is created by the LLM (or a caller) to invoke a named tool
+    # with structured input. It carries identity, correlation data, and
+    # lifecycle state that progresses through:
+    #
+    #   :pending → :running → :completed | :failed | :cancelled | :timed_out
+    #
+    # ToolCall instances are frozen after initialization.
+    #
+    #   call = Ask::Runtime::ToolCall.new(
+    #     id: "tc_abc",
+    #     tool_name: "search",
+    #     input: { query: "ruby" },
+    #     session_id: "s_001",
+    #     turn: 2
+    #   )
+    #   call.pending? # => true
+    #
+    class ToolCall
+      STATES = %i[pending running completed failed cancelled timed_out].freeze
+
+      # @return [String] unique identifier for this tool call
+      attr_reader :id
+
+      # @return [String] name of the tool to execute
+      attr_reader :tool_name
+
+      # @return [Hash] the tool's input parameters
+      attr_reader :input
+
+      # @return [String, nil] session identifier for correlation
+      attr_reader :session_id
+
+      # @return [Integer, nil] turn number within the session
+      attr_reader :turn
+
+      # @return [Symbol] lifecycle state (:pending, :running, :completed,
+      #   :cancelled, :timed_out)
+      attr_reader :state
+
+      # @return [String, nil] caller identifier (e.g. agent name or user id)
+      attr_reader :caller_id
+
+      # @return [String, nil] error message when state is :failed
+      attr_reader :error
+
+      # @return [ToolResult, nil] the normalized execution result, set on
+      #   terminal states (:completed, :failed, :cancelled, :timed_out)
+      attr_reader :tool_result
+
+      # @return [Hash] arbitrary metadata
+      attr_reader :metadata
+
+      # @return [Time] when this tool call was created
+      attr_reader :created_at
+
+      # @return [Time, nil] when execution started
+      attr_reader :started_at
+
+      # @return [Time, nil] when execution finished
+      attr_reader :finished_at
+
+      def initialize(id: nil, tool_name:, input: {}, session_id: nil,
+                     turn: nil, state: :pending, caller_id: nil,
+                     error: nil, tool_result: nil,
+                     metadata: {}, created_at: Time.now, started_at: nil,
+                     finished_at: nil)
+        @id = id || "tc_#{SecureRandom.hex(8)}"
+        @tool_name = tool_name.to_s
+        @input = input.dup.freeze
+        @session_id = session_id
+        @turn = turn
+        @state = validate_state!(state)
+        @caller_id = caller_id
+        @error = error
+        @tool_result = tool_result
+        @metadata = metadata.dup.freeze
+        @created_at = created_at
+        @started_at = started_at
+        @finished_at = finished_at
+        freeze
+      end
+
+      # @!group State Predicates
+
+      # @return [Boolean]
+      def pending? = @state == :pending
+
+      # @return [Boolean]
+      def running? = @state == :running
+
+      # @return [Boolean]
+      def completed? = @state == :completed
+
+      # @return [Boolean]
+      def failed? = @state == :failed
+
+      # @return [Boolean]
+      def cancelled? = @state == :cancelled
+
+      # @return [Boolean]
+      def timed_out? = @state == :timed_out
+
+      # @!endgroup
+
+      # Return a new ToolCall with the given attributes replaced.
+      #
+      # @param attrs [Hash] attributes to override
+      # @return [ToolCall] a new frozen instance
+      def with(**attrs)
+        self.class.new(**to_h.merge(attrs))
+      end
+
+      # @return [Hash] representation suitable for Ruby serialization.
+      #   Note: +created_at+, +started_at+, and +finished_at+ are +Time+
+      #   objects and are NOT directly JSON-serializable.  Callers must
+      #   convert them (e.g. +.iso8601+) before encoding to JSON.
+      def to_h
+        {
+          id: @id,
+          tool_name: @tool_name,
+          input: @input,
+          session_id: @session_id,
+          turn: @turn,
+          state: @state,
+          caller_id: @caller_id,
+          error: @error,
+          tool_result: @tool_result&.to_h,
+          metadata: @metadata,
+          created_at: @created_at,
+          started_at: @started_at,
+          finished_at: @finished_at
+        }
+      end
+
+      def inspect
+        "#<Ask::Runtime::ToolCall id=#{@id.inspect} tool=#{@tool_name.inspect} state=#{@state.inspect}>"
+      end
+
+      def ==(other)
+        other.is_a?(self.class) && @id == other.id
+      end
+      alias eql? ==
+
+      def hash
+        @id.hash
+      end
+
+      private
+
+      def validate_state!(state)
+        return state if STATES.include?(state)
+
+        raise ArgumentError, "Invalid state #{state.inspect}. Valid: #{STATES.join(', ')}"
+      end
+    end
+  end
+end

data/lib/ask/runtime/tool_executor.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Ask
+  module Runtime
+    # Adapter contract for tool execution backends.
+    #
+    # ToolExecutor is the duck-type interface that concrete adapters must
+    # implement. It does not depend on any LLM or provider code — adapters
+    # bridge between the runtime kernel and specific tool implementations.
+    #
+    # A minimal adapter:
+    #
+    #   class MyExecutor
+    #     include Ask::Runtime::ToolExecutor
+    #
+    #     def execute(tool_call, context: nil)
+    #       # run the tool, return Ask::Runtime::ToolResult
+    #     end
+    #   end
+    #
+    # Or implement the interface directly without including the module:
+    #
+    #   class MyExecutor
+    #     def execute(tool_call, context: nil)
+    #       # ...
+    #     end
+    #   end
+    #
+    module ToolExecutor
+      # Execute a tool call within the given context.
+      #
+      # @param tool_call [ToolCall] the tool-call request to execute
+      # @param context [ExecutionContext, nil] optional execution context
+      # @return [ToolResult] the normalized execution result
+      # @raise [NotImplementedError] if not overridden
+      def execute(tool_call, context: nil)
+        raise NotImplementedError,
+          "#{self.class} must implement #execute(tool_call, context:)"
+      end
+
+      # Check whether this executor can handle a given tool name.
+      #
+      # @param tool_name [String, Symbol] the tool name to check
+      # @return [Boolean] whether this executor handles the tool
+      def handles?(tool_name)
+        respond_to?(:supported_tools) &&
+          supported_tools.include?(tool_name.to_s)
+      end
+    end
+  end
+end

data/lib/ask/runtime/tool_result.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "ask"
+
+module Ask
+  module Runtime
+    # Normalized result of tool execution.
+    #
+    # ToolResult wraps +Ask::Result+ and adds lifecycle-specific predicates
+    # for cancelled and timed-out states that are not part of the core result
+    # vocabulary but are natural outcomes of the runtime execution model.
+    #
+    # Factory methods produce canonical results:
+    #
+    #   Ask::Runtime::ToolResult.success(data: { "count" => 42 })
+    #   Ask::Runtime::ToolResult.failure("file not found")
+    #   Ask::Runtime::ToolResult.cancelled("user aborted")
+    #   Ask::Runtime::ToolResult.timeout("exceeded 30s limit")
+    #
+    class ToolResult
+      # @return [Ask::Result] the underlying core result
+      attr_reader :result
+
+      # @return [Symbol] normalized outcome (:success, :failure, :cancelled, :timeout)
+      attr_reader :outcome
+
+      # @return [Float, nil] execution duration in seconds
+      attr_reader :duration
+
+      def initialize(result:, outcome:, duration: nil)
+        @result = result
+        @outcome = outcome
+        @duration = duration
+        freeze
+      end
+
+      class << self
+        # Create a successful tool result.
+        #
+        # @param data [Object] the tool's output payload
+        # @param duration [Float, nil] execution time in seconds
+        # @param metadata [Hash] additional metadata
+        # @return [ToolResult]
+        def success(data: nil, duration: nil, metadata: {})
+          result = Ask::Result.ok(data: data, metadata: metadata)
+          new(result: result, outcome: :success, duration: duration)
+        end
+
+        # Create a failed tool result.
+        #
+        # @param message [String] error description
+        # @param duration [Float, nil] execution time in seconds
+        # @param metadata [Hash] additional metadata
+        # @return [ToolResult]
+        def failure(message, duration: nil, metadata: {})
+          result = Ask::Result.error(message: message, metadata: metadata)
+          new(result: result, outcome: :failure, duration: duration)
+        end
+
+        # Create a cancelled tool result (cooperative cancellation).
+        #
+        # @param reason [String] why execution was cancelled
+        # @param duration [Float, nil] execution time before cancellation
+        # @return [ToolResult]
+        def cancelled(reason = "Cancelled", duration: nil)
+          result = Ask::Result.failure(reason)
+          new(result: result, outcome: :cancelled, duration: duration)
+        end
+
+        # Create a timed-out tool result.
+        #
+        # @param message [String] timeout description
+        # @param duration [Float, nil] elapsed time before timeout
+        # @return [ToolResult]
+        def timeout(message = "Execution timed out", duration: nil)
+          result = Ask::Result.failure(message)
+          new(result: result, outcome: :timeout, duration: duration)
+        end
+      end
+
+      # @!group Predicates
+
+      # @return [Boolean]
+      def success? = @outcome == :success
+
+      # @return [Boolean]
+      def failure? = @outcome == :failure
+
+      # @return [Boolean]
+      def cancelled? = @outcome == :cancelled
+
+      # @return [Boolean]
+      def timeout? = @outcome == :timeout
+
+      # @!endgroup
+
+      # @return [Object, nil] the output data when successful
+      def output = @result.output
+
+      # @return [Object, nil] the error message or object
+      def error_message = @result.error_message
+
+      # @return [Hash] serializable representation
+      def to_h
+        {
+          outcome: @outcome,
+          output: output,
+          error: error_message,
+          duration: @duration,
+          result: @result.to_h
+        }
+      end
+
+      def inspect
+        if success?
+          "#<Ask::Runtime::ToolResult outcome=success output=#{output.inspect}>"
+        else
+          "#<Ask::Runtime::ToolResult outcome=#{@outcome.inspect} error=#{error_message.inspect}>"
+        end
+      end
+    end
+  end
+end

data/lib/ask/runtime/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ask
+  module Runtime
+    VERSION = "0.1.0"
+  end
+end

data/lib/ask/runtime.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "runtime/version"
+require_relative "runtime/tool_call"
+require_relative "runtime/tool_result"
+require_relative "runtime/execution_context"
+require_relative "runtime/event_sink"
+require_relative "runtime/events"
+require_relative "runtime/tool_executor"
+
+module Ask
+  # The runtime execution kernel for ask-rb tool calls.
+  #
+  # Provides value objects (ToolCall, ToolResult, ExecutionContext) and
+  # the ToolExecutor adapter contract for pluggable tool execution.
+  #
+  # This gem does not depend on any LLM provider code. It defines the
+  # stable public kernel that higher-level gems build on.
+  module Runtime
+  end
+end

data/lib/ask-runtime.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "ask/runtime"