ask-sandbox-providers 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a0d6fd353895bba424a5a181ccf55e6c0da0273dc9a411f65db972830c99516
-  data.tar.gz: 84eb48ca0657db9cf00232559e4ab977fe31c1bb7c530881f59e1f9b0ef70bd1
+  metadata.gz: 8883fc8f89fd8afef751cd38bbd2c22180fc85191176d63a3ff78059e5c638c5
+  data.tar.gz: 710bb7bbda30c7062ab3c3c512693ee56737b5bae3b2c44f80273f1b2d643a26
 SHA512:
-  metadata.gz: c7145f2991c6989fbdd58c70fe301a66a05d2848fe0244059c6d082c7cb75e36089271f1ef02b8d903c538945f6db813b8efbe498513b778663ba5c07623f154
-  data.tar.gz: bd310ad9bb7a8f5ff51e03911856d96348fc4091b824f09e53eca3b3eb32ec0c062e3a1850c0d810caa4399c324771be057ee1d8cfceb9f98d70b965bae8ef2c
+  metadata.gz: 9884fc2a731826b9357577e04f24ed60ccdab668712892f422539af1618a5bf9d2630f8ca675a29fd108bbb4edc4937e5f85c459ac965afdde9dbc367a795901
+  data.tar.gz: 17e5fe56218d7d264dfcbd84786c6bb9e0fa80be2393a4113706889ee9c78c429c6fc83e1913c6b75f0cb198c3c18b3b9dff4f42c35a93129494e6a5b7d58861

data/CHANGELOG.md

@@ -25,6 +25,13 @@
 - Infrastructure: rubocop, overcommit, bin/setup, CI matrix, gemspec test.
 # Changelog
 
+## Unreleased
+
+### Added
+
+- `Ask::Sandbox::RuntimeExecutor` bridges sandbox providers to the
+  `ask-runtime` tool executor contract.
+
 ## [0.1.1] - 2026-06-18
 
 ### Fixed

data/README.md

@@ -44,6 +44,26 @@ Daytona resolves its API key from `Ask::Auth.lookup("DAYTONA_API_KEY")` or `ENV[
 
 Every provider returns `Ask::Sandbox::Result`, a `Data` object with `stdout`, `stderr`, `exit_code`, and `timed_out` fields, plus `#success?` (true when `exit_code == 0`).
 
+## Runtime integration
+
+`Ask::Sandbox::RuntimeExecutor` adapts any configured sandbox provider to the
+`ask-runtime` execution contract:
+
+```ruby
+executor = Ask::Sandbox::RuntimeExecutor.new(Ask::Sandbox.provider)
+call = Ask::Runtime::ToolCall.new(
+  tool_name: "sandbox.execute",
+  input: { command: ["ruby", "-e", "puts 1"] }
+)
+result = executor.execute(call)
+result.output[:stdout] # => "1\n"
+```
+
+The adapter carries `ExecutionContext#workspace` into the provider when no
+explicit `workdir` is supplied, maps non-zero exits and provider exceptions to
+`ToolResult` failures, maps provider timeouts to timed-out results, and emits
+the standard runtime lifecycle events.
+
 ## Full documentation
 
 The full ask-rb documentation lives at https://ask-rb.github.io/ask-docs. [ask-sandbox-providers in depth](https://ask-rb.github.io/ask-docs/core/sandbox) covers each provider and the hardening details. API reference: https://ask-rb.github.io/ask-docs/reference/api.

data/lib/ask/sandbox/runtime_executor.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require "ask/runtime"
+
+module Ask
+  module Sandbox
+    # Adapts a sandbox provider to the ask-runtime tool executor contract.
+    #
+    # The executor accepts a ToolCall whose input contains +command+ and
+    # optional sandbox options (+timeout+, +workdir+, +env+, and +stdin+).
+    # When no workdir is supplied, the execution context's workspace is used.
+    #
+    #   executor = Ask::Sandbox::RuntimeExecutor.new(Ask::Sandbox.provider)
+    #   call = Ask::Runtime::ToolCall.new(
+    #     tool_name: "sandbox.execute",
+    #     input: { command: ["ruby", "-e", "puts 1"] }
+    #   )
+    #   executor.execute(call).output[:stdout] # => "1\n"
+    class RuntimeExecutor
+      include Ask::Runtime::ToolExecutor
+
+      TOOL_NAME = "sandbox.execute"
+
+      attr_reader :provider
+
+      def initialize(provider = nil)
+        @provider = provider || Ask::Sandbox.provider
+      end
+
+      def supported_tools
+        [TOOL_NAME]
+      end
+
+      # Execute a sandbox command and normalize its result for ask-runtime.
+      #
+      # @param tool_call [Ask::Runtime::ToolCall]
+      # @param context [Ask::Runtime::ExecutionContext, nil]
+      # @return [Ask::Runtime::ToolResult]
+      def execute(tool_call, context: nil)
+        context ||= Ask::Runtime::ExecutionContext.new
+        started_at = Time.now
+        started_call = tool_call.with(state: :running, started_at: started_at)
+        emit(Ask::Runtime::Events::ToolStarted, tool_call: started_call, context: context)
+
+        return cancel(started_call, context, started_at, "Cancelled before execution") if context.cancelled?
+
+        result = execute_command(tool_call.input, context)
+        return cancel(started_call, context, started_at, "Cancelled during execution") if context.cancelled?
+
+        finish(started_call, context, result, started_at)
+      rescue StandardError => e
+        finish(started_call, context, Ask::Runtime::ToolResult.failure(
+          "#{e.class}: #{e.message}"
+        ), started_at)
+      end
+
+      private
+
+      def execute_command(input, context)
+        command = input_value(input, :command)
+        raise ArgumentError, "command is required" if command.nil?
+
+        options = {
+          workdir: input_value(input, :workdir) || context.workspace,
+          env: input_value(input, :env) || {},
+          stdin: input_value(input, :stdin)
+        }
+        timeout = input_value(input, :timeout)
+        options[:timeout] = timeout unless timeout.nil?
+
+        sandbox_result = @provider.call(command, **options)
+        metadata = {
+          stdout: sandbox_result.stdout,
+          stderr: sandbox_result.stderr,
+          exit_code: sandbox_result.exit_code,
+          timed_out: sandbox_result.timed_out
+        }
+
+        if sandbox_result.timed_out
+          timeout_result("Sandbox command timed out", metadata)
+        elsif sandbox_result.success?
+          Ask::Runtime::ToolResult.success(data: metadata, metadata: metadata)
+        else
+          Ask::Runtime::ToolResult.failure(
+            "Command exited with status #{sandbox_result.exit_code}", metadata: metadata
+          )
+        end
+      end
+
+      def input_value(input, key)
+        input[key] || input[key.to_s]
+      end
+
+      def timeout_result(message, metadata)
+        Ask::Runtime::ToolResult.new(
+          result: Ask::Result.failure(message, metadata: metadata),
+          outcome: :timeout
+        )
+      end
+
+      def finish(started_call, context, result, started_at)
+        finished_at = Time.now
+        duration = finished_at - started_at
+        result = with_duration(result, duration)
+        state = if result.timeout?
+          :timed_out
+        elsif result.failure?
+          :failed
+        else
+          :completed
+        end
+        terminal_call = started_call.with(
+          state: state,
+          tool_result: result,
+          error: result.error_message,
+          finished_at: finished_at
+        )
+        event_class = {
+          completed: Ask::Runtime::Events::ToolCompleted,
+          failed: Ask::Runtime::Events::ToolFailed,
+          timed_out: Ask::Runtime::Events::ToolTimedOut
+        }.fetch(state)
+        emit(event_class, tool_call: terminal_call, tool_result: result,
+             context: context, timestamp: finished_at, duration: duration)
+        result
+      end
+
+      def cancel(started_call, context, started_at, reason)
+        finished_at = Time.now
+        duration = finished_at - started_at
+        result = with_duration(Ask::Runtime::ToolResult.cancelled(reason), duration)
+        terminal_call = started_call.with(
+          state: :cancelled,
+          tool_result: result,
+          error: result.error_message,
+          finished_at: finished_at
+        )
+        emit(Ask::Runtime::Events::ToolCancelled, tool_call: terminal_call,
+             tool_result: result, context: context, timestamp: finished_at, duration: duration)
+        result
+      end
+
+      def with_duration(result, duration)
+        Ask::Runtime::ToolResult.new(
+          result: result.result,
+          outcome: result.outcome,
+          duration: duration
+        )
+      end
+
+      def emit(event_class, tool_call:, context:, **attrs)
+        event = event_class.new(
+          tool_call: tool_call,
+          execution_context: context,
+          timestamp: attrs.delete(:timestamp) || Time.now,
+          **attrs
+        )
+        event_type = event_class.name.split("::").last
+          .gsub(/([a-z])([A-Z])/, '\\1_\\2').downcase.to_sym
+        context.event_sink.emit(event_type, event: event)
+      end
+    end
+  end
+end

data/lib/ask/sandbox/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Sandbox
-    VERSION = "0.1.4"
+    VERSION = "0.1.5"
   end
 end

data/lib/ask-sandbox-providers.rb

@@ -6,6 +6,7 @@ require_relative "ask/sandbox/local"
 require_relative "ask/sandbox/docker"
 require_relative "ask/sandbox/daytona"
 require_relative "ask/sandbox/cloudflare"
+require_relative "ask/sandbox/runtime_executor"
 
 module Ask
   module Sandbox

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-sandbox-providers
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
 platform: ruby
 authors:
 - Kaka Ruto
@@ -9,6 +9,20 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: ask-runtime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -69,6 +83,7 @@ files:
 - lib/ask/sandbox/daytona.rb
 - lib/ask/sandbox/docker.rb
 - lib/ask/sandbox/local.rb
+- lib/ask/sandbox/runtime_executor.rb
 - lib/ask/sandbox/version.rb
 homepage: https://github.com/ask-rb/ask-sandbox-providers
 licenses:
@@ -91,7 +106,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.18
 specification_version: 4
 summary: Sandbox providers for the ask-rb ecosystem
 test_files: []