ask-runtime 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: def95e2bb1bbf6b60a1e635e9d3194b5e4cae9f73cd271eca74e590c092f2505
+  data.tar.gz: e2c50b4ffce5cdd05db02ef3cfc5fb3fd5feaf8f7adb1fa9cbfdd33d18fa6d21
+SHA512:
+  metadata.gz: b40544054745189203090642cdeed9cc05d49c72aae3c58d03c726d414bee0ae5c6b044d13ea5973f6205bd0fa4e63737b70289b71abff0a80cf1ae1e7c4ee4f
+  data.tar.gz: 329b405f2049eb255dbbd0b05f61b815043d61a2dd35fa16b8e42746db12f66568089d2e80e4332237325d31a24bf843f536c9067fc510d2b2ac41442bc63a96

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - Unreleased
+
+### Added
+
+- `Ask::Runtime::ToolCall` — immutable value object for a tool-call request with identity, tool name, input, session/turn correlation, and lifecycle state.
+- `Ask::Runtime::ToolResult` — normalized success/failure/cancelled/timeout result from tool execution, wrapping `Ask::Result`.
+- `Ask::Runtime::ExecutionContext` — immutable context passed to tool execution: session, turn, caller, workspace, capabilities, cancellation, event sink, artifact store, and metadata.
+- `Ask::Runtime::ToolExecutor` — adapter contract (interface) for pluggable tool execution backends.
+- `Ask::Runtime::Canceller` — cooperative cancellation token with `cancelled?` / `cancel` / `on_cancel` callbacks.
+- `Ask::Runtime::EventSink` — simple event emitter contract for execution lifecycle notifications.
+
+### Documentation
+- Added RuntimeAdapter integration section to README showing how to bridge EventSink events to ask-instrumentation.
+- Added the reusable `Ask::Runtime::Testing::ExecutorContract` helper for adapter conformance tests.
+- Added independent CI, setup, and release workflows for the runtime repository.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaka Ruto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,168 @@
+# Ask::Runtime
+
+Tool-call execution kernel for the [ask-rb](https://github.com/ask-rb) ecosystem.
+
+## Installation
+
+```ruby
+gem "ask-runtime"
+```
+
+## Overview
+
+Ask::Runtime provides the foundational value objects and adapter contracts for tool-call execution in ask-rb. It defines the stable public kernel that higher-level gems (ask-agent, ask-session) build on.
+
+### Core Types
+
+- **`ToolCall`** — immutable value object for a tool-call request: identity, tool name, input, session/turn correlation, and lifecycle state (`:pending`, `:running`, `:completed`, `:cancelled`, `:timed_out`).
+- **`ToolResult`** — normalized execution result wrapping `Ask::Result` with `success?`, `failure?`, `cancelled?`, and `timeout?` predicates.
+- **`ExecutionContext`** — immutable context for tool execution: optional session, turn, caller, workspace, capabilities, cancellation token, event sink, artifact store, and metadata.
+- **`ToolExecutor`** — adapter contract (duck-type interface) for pluggable tool execution backends.
+
+### Runtime Events
+
+Immutable event value objects emitted through an `EventSink` during tool execution:
+
+| Event | When | Key Fields |
+|-------|------|------------|
+| `ToolStarted` | Tool begins execution | `tool_call`, `execution_context`, `timestamp` |
+| `ToolCompleted` | Tool finishes successfully | `tool_call`, `tool_result`, `execution_context`, `timestamp`, `duration` |
+| `ToolFailed` | Tool errors | `tool_call`, `tool_result`, `execution_context`, `timestamp`, `duration` |
+| `ToolCancelled` | Cooperative cancellation | `tool_call`, `tool_result`, `execution_context`, `timestamp`, `duration` |
+| `ToolTimedOut` | Execution time exceeded | `tool_call`, `tool_result`, `execution_context`, `timestamp`, `duration` |
+
+### EventSink
+
+Thread-safe pub/sub emitter for lifecycle notifications:
+
+```ruby
+sink = Ask::Runtime::EventSink.new
+
+# Listen for events
+sink.on(:tool_started) { |payload| puts payload[:event].tool_name }
+sink.on(:tool_completed) { |payload| puts payload[:event].duration }
+
+# Emit events (typically done by executors)
+sink.emit(:tool_started, event: Ask::Runtime::Events::ToolStarted.new(...))
+```
+
+#### NullSink
+
+When no observation is needed, use a `NullSink` to avoid allocations and output:
+
+```ruby
+sink = Ask::Runtime::EventSink.null
+sink.emit(:anything)  # no-op
+```
+
+## Example
+
+```ruby
+require "ask-runtime"
+
+call = Ask::Runtime::ToolCall.new(
+  id: "tc_abc123",
+  tool_name: "search",
+  input: { query: "ruby concurrency" },
+  session_id: "s_001",
+  turn: 3
+)
+
+result = Ask::Runtime::ToolResult.success(data: "results here")
+context = Ask::Runtime::ExecutionContext.new(session_id: "s_001", turn: 3)
+
+executor = MyToolExecutor.new
+result = executor.execute(call, context: context)
+```
+
+### Observing Tool Execution
+
+```ruby
+sink = Ask::Runtime::EventSink.new
+
+# Subscribe to terminal events
+sink.on(:tool_completed) do |payload|
+  event = payload[:event]
+  puts "#{event.tool_name} completed in #{event.duration}s"
+  puts "Result: #{event.tool_result.output}"
+end
+
+sink.on(:tool_failed) do |payload|
+  event = payload[:event]
+  puts "#{event.tool_name} failed: #{event.error}"
+end
+
+# Wire into an executor
+context = Ask::Runtime::ExecutionContext.new(
+  session_id: "s_001",
+  turn: 1,
+  event_sink: sink
+)
+```
+
+### Integration with ask-instrumentation
+
+If you use [ask-instrumentation](https://github.com/ask-rb/ask-instrumentation),
+you can bridge runtime events to `ActiveSupport::Notifications`:
+
+```ruby
+require "ask/instrumentation"
+require "ask/instrumentation/runtime_adapter"
+
+sink = Ask::Instrumentation.install_runtime_sink
+
+# All tool lifecycle events are now forwarded as Ask::Instrumentation events:
+#   tool.started.ask, tool.completed.ask, tool.failed.ask,
+#   tool.cancelled.ask, tool.timed_out.ask
+
+context = Ask::Runtime::ExecutionContext.new(
+  session_id: "s_001", turn: 1, event_sink: sink
+)
+```
+
+See the [ask-instrumentation README](https://github.com/ask-rb/ask-instrumentation#runtime-adapter)
+for the full payload schema and event mapping.
+
+## Testing an executor
+
+Adapter gems can reuse the runtime contract assertions instead of defining
+their own compatibility checklist:
+
+```ruby
+require "ask/runtime/testing"
+
+class MyExecutorTest < Minitest::Test
+  include Ask::Runtime::Testing::ExecutorContract
+
+  def test_executor_contract
+    assert_conforms_to_runtime_contract(
+      MyExecutor.new,
+      success_call: build_success_call,
+      failure_call: build_failure_call,
+      cancelled_call: build_cancelled_call,
+      context_factory: ->(event_sink:, canceller: nil) {
+        Ask::Runtime::ExecutionContext.new(
+          event_sink: event_sink, canceller: canceller
+        )
+      }
+    )
+  end
+end
+```
+
+The helper checks the shared `ToolResult` shape, non-negative duration,
+pre-execution cancellation, lifecycle event ordering, terminal state, and
+call correlation. Backend-specific behavior should remain covered by the
+adapter's own tests.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-feature`)
+3. Commit your changes (`git commit -am 'Add feature'`)
+4. Push to the branch (`git push origin my-feature`)
+5. Create a Pull Request
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

data/lib/ask/runtime/canceller.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Ask
+  module Runtime
+    # Cooperative cancellation token for tool execution.
+    #
+    # A {Canceller} starts in an uncancelled state and can be cancelled at any
+    # time. Tools receive the canceller via {ExecutionContext} and may check
+    # +cancelled?+ periodically during long-running work to abort early.
+    #
+    #   canceller = Ask::Runtime::Canceller.new
+    #   canceller.on_cancel { puts "cancelled!" }
+    #   canceller.cancel
+    #   canceller.cancelled? # => true
+    #
+    class Canceller
+      def initialize
+        @cancelled = false
+        @mutex = Mutex.new
+        @callbacks = []
+      end
+
+      # @return [Boolean] true if +cancel+ has been called
+      def cancelled?
+        @mutex.synchronize { @cancelled }
+      end
+
+      # Request cooperative cancellation. Fires registered callbacks exactly once.
+      #
+      # Callbacks are never invoked while the internal mutex is held: the
+      # callback list is snapshotted under the lock and each callback is
+      # invoked after the lock is released.
+      #
+      # @return [self]
+      def cancel
+        callbacks_to_run = @mutex.synchronize do
+          return self if @cancelled
+
+          @cancelled = true
+          snapshot = @callbacks.dup
+          @callbacks.clear
+          snapshot
+        end
+        callbacks_to_run.each(&:call)
+        self
+      end
+
+      # Register a callback to be invoked when cancellation is requested.
+      # If already cancelled, the callback fires immediately (outside the
+      # internal mutex) to preserve immediate already-cancelled semantics
+      # while never invoking user code under the lock.
+      #
+      # @yield [] block to run on cancellation
+      # @return [self]
+      def on_cancel(&block)
+        raise ArgumentError, "block required" unless block
+
+        immediate = @mutex.synchronize do
+          if @cancelled
+            block
+          else
+            @callbacks << block
+            nil
+          end
+        end
+        immediate&.call
+        self
+      end
+
+      def inspect
+        "#<Ask::Runtime::Canceller cancelled=#{cancelled?}>"
+      end
+    end
+  end
+end

data/lib/ask/runtime/event_sink.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Ask
+  module Runtime
+    # Simple event sink contract for tool execution lifecycle notifications.
+    #
+    # Adapters and executors may emit events through the sink so that
+    # higher-level systems (logging, observability, UI) can observe execution
+    # without coupling to specific implementations.
+    #
+    # This is the base contract. Subclass and override +emit+ for concrete
+    # behavior, or use a lambda/proc as a minimal sink.
+    #
+    #   sink = Ask::Runtime::EventSink.new
+    #   sink.on(:tool_execution_start) { |event| puts event }
+    #   sink.emit(:tool_execution_start, name: "search", id: "tc_1")
+    #
+    class EventSink
+      # A sink that discards all events. Use when no observation is needed
+      # but the executor requires a non-nil sink.
+      #
+      #   sink = Ask::Runtime::EventSink.null
+      #   sink.emit(:anything)  # no-op, no allocation, no output
+      #
+      class NullSink
+        def on(_event_type, &_block)
+          self
+        end
+
+        def emit(_event_type, **_payload)
+          self
+        end
+
+        def listening?(_event_type)
+          false
+        end
+
+        def inspect
+          "#<Ask::Runtime::EventSink::NullSink>"
+        end
+      end
+
+      # Return a NullSink that discards all events.
+      #
+      # @return [NullSink]
+      def self.null
+        NullSink.new
+      end
+
+      def initialize
+        @listeners = Hash.new { |h, k| h[k] = [] }
+        @mutex = Mutex.new
+      end
+
+      # Register a listener for a specific event type.
+      #
+      # @param event_type [Symbol] the event name (e.g. +:tool_execution_start+)
+      # @yield [payload] block to invoke when the event fires
+      # @return [self]
+      def on(event_type, &block)
+        raise ArgumentError, "block required" unless block
+
+        @mutex.synchronize { @listeners[event_type] << block }
+        self
+      end
+
+      # Emit an event, notifying all registered listeners for that type.
+      #
+      # Listeners are never invoked while the internal mutex is held: the
+      # listener list is snapshotted under the lock and each listener is
+      # invoked after the lock is released.
+      #
+      # @param event_type [Symbol] the event name
+      # @param payload [Hash] arbitrary event data
+      # @return [self]
+      def emit(event_type, **payload)
+        listeners_to_run = @mutex.synchronize do
+          @listeners[event_type].dup
+        end
+        listeners_to_run.each { |cb| cb.call(payload) }
+        self
+      end
+
+      # @return [Boolean] true if any listeners are registered for +event_type+
+      def listening?(event_type)
+        @mutex.synchronize { @listeners[event_type].any? }
+      end
+
+      def inspect
+        "#<Ask::Runtime::EventSink listeners=#{@mutex.synchronize { @listeners.keys }}>"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+# 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 is cancelled via cooperative
+      # cancellation (Canceller).
+      #
+      # Carries the terminal ToolCall snapshot (state: :cancelled), the
+      # ToolResult with outcome: :cancelled, the ExecutionContext, a monotonic
+      # timestamp, and the wall-clock duration in seconds.
+      #
+      #   event = ToolCancelled.new(
+      #     tool_call: finished_call, tool_result: result,
+      #     execution_context: ctx, timestamp: Time.now, duration: 0.8
+      #   )
+      #   event.cancelled?  #=> true
+      #   event.reason      #=> "Aborted by sibling failure"
+      #
+      class ToolCancelled
+        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 cancelled? = @tool_result.cancelled?
+        def reason = @tool_result.error_message
+
+        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,
+            reason: reason
+          }
+        end
+
+        def inspect
+          "#<ToolCancelled tool=#{tool_name.inspect} id=#{tool_call_id.inspect} reason=#{reason.inspect}>"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# 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 completes successfully.
+      #
+      # Carries the terminal ToolCall snapshot (state: :completed), the
+      # ToolResult with outcome: :success, the ExecutionContext, a monotonic
+      # timestamp, and the wall-clock duration in seconds.
+      #
+      #   event = ToolCompleted.new(
+      #     tool_call: finished_call, tool_result: result,
+      #     execution_context: ctx, timestamp: Time.now, duration: 1.23
+      #   )
+      #   event.success?  #=> true
+      #   event.duration  #=> 1.23
+      #
+      class ToolCompleted
+        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 success? = @tool_result.success?
+
+        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
+          "#<ToolCompleted tool=#{tool_name.inspect} id=#{tool_call_id.inspect} duration=#{@duration}>"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# 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 fails with an error.
+      #
+      # Carries the terminal ToolCall snapshot (state: :failed), the
+      # ToolResult with outcome: :failure, the ExecutionContext, a monotonic
+      # timestamp, and the wall-clock duration in seconds.
+      #
+      #   event = ToolFailed.new(
+      #     tool_call: finished_call, tool_result: result,
+      #     execution_context: ctx, timestamp: Time.now, duration: 0.5
+      #   )
+      #   event.failed?  #=> true
+      #   event.error    #=> "file not found"
+      #
+      class ToolFailed
+        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 failed? = @tool_result.failure?
+        def error = @tool_result.error_message
+
+        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,
+            error: error
+          }
+        end
+
+        def inspect
+          "#<ToolFailed tool=#{tool_name.inspect} id=#{tool_call_id.inspect} error=#{error.inspect}>"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "../tool_call"
+require_relative "../execution_context"
+
+module Ask
+  module Runtime
+    module Events
+      # Immutable event emitted when a tool call begins execution.
+      #
+      # Carries a snapshot of the ToolCall (in :pending or :running state)
+      # and the ExecutionContext for the execution. No ToolResult is present
+      # since the tool has not yet completed.
+      #
+      #   event = ToolStarted.new(
+      #     tool_call: call, execution_context: ctx, timestamp: Time.now
+      #   )
+      #   event.tool_call_id  #=> "tc_abc123"
+      #   event.tool_name     #=> "search"
+      #
+      class ToolStarted
+        attr_reader :tool_call, :execution_context, :timestamp
+
+        def initialize(tool_call:, execution_context:, timestamp:)
+          raise ArgumentError, "tool_call required" unless tool_call.is_a?(Ask::Runtime::ToolCall)
+          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
+          @execution_context = execution_context
+          @timestamp = timestamp
+          freeze
+        end
+
+        def tool_call_id = @tool_call.id
+        def tool_name = @tool_call.tool_name
+
+        def to_h
+          {
+            tool_call: @tool_call,
+            execution_context: @execution_context,
+            timestamp: @timestamp,
+            tool_call_id: tool_call_id,
+            tool_name: tool_name
+          }
+        end
+
+        def inspect
+          "#<ToolStarted tool=#{tool_name.inspect} id=#{tool_call_id.inspect}>"
+        end
+      end
+    end
+  end
+end