temporalio 1.4.1 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9ab77e9e3a462220ab99a1eb7814e4e7e6c7f9485487344cda2e12b8f983147
-  data.tar.gz: d3d2f0a9026ec2033de2a367735d9ddffec50ced84c5bd99f049f481ea534b89
+  metadata.gz: 02f37fc5f0253de8502b8f11163f2df6038932aa103d1a6b4cde9e7b744f8db1
+  data.tar.gz: 9fa127403d3ffc13493c155493122eb7bd52eb83aae31f2ba8c32c47a05e5661
 SHA512:
-  metadata.gz: 436ef0cdcbf32fe0c88c719a409dc1707e141df0e8bccb5f024c181f5c41ab7f03a2ccf83e445cf9c1b98e208ef618ad8dcf2715ce767d46b99e903e766eb9c5
-  data.tar.gz: 780131e186208f905023064c38d6298d94f4218909e34ff381261167ea38e7d13754a157a33ff0db2b8de79551827d3dd449dabcd0db66bbfdfc16bcb5c8cd38
+  metadata.gz: 5c06d25a83a29b5a7f1a5d1aa3ae5e83bd7c35155b5d5700d561dd87026b51e020eb0b8db17354e740bba49aee5b36e88e17c40e03ecedfb0aba8435fb4dce33
+  data.tar.gz: 3b6a5ab5a22fc430f27cf664107a7b7b26f17fd59661c6768efb839f1988dda8999eac2ba40d2957894a89fd0a0ca0c482cc53274819df70128584ac145e3c87

data/Cargo.lock

@@ -83,7 +83,7 @@ version = "1.1.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc"
 dependencies = [
- "windows-sys 0.61.2",
+ "windows-sys 0.60.2",
 ]
 
 [[package]]
@@ -94,7 +94,7 @@ checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d"
 dependencies = [
  "anstyle",
  "once_cell_polyfill",
- "windows-sys 0.61.2",
+ "windows-sys 0.60.2",
 ]
 
 [[package]]
@@ -711,7 +711,7 @@ dependencies = [
  "libc",
  "option-ext",
  "redox_users",
- "windows-sys 0.61.2",
+ "windows-sys 0.60.2",
 ]
 
 [[package]]
@@ -811,7 +811,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
 dependencies = [
  "libc",
- "windows-sys 0.61.2",
+ "windows-sys 0.60.2",
 ]
 
 [[package]]
@@ -1755,7 +1755,7 @@ version = "0.50.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7957b9740744892f114936ab4a57b3f487491bbeafaf8083688b16841a4240e5"
 dependencies = [
- "windows-sys 0.61.2",
+ "windows-sys 0.60.2",
 ]
 
 [[package]]
@@ -2721,7 +2721,7 @@ dependencies = [
  "errno",
  "libc",
  "linux-raw-sys",
- "windows-sys 0.61.2",
+ "windows-sys 0.60.2",
 ]
 
 [[package]]
@@ -2780,7 +2780,7 @@ dependencies = [
  "security-framework",
  "security-framework-sys",
  "webpki-root-certs",
- "windows-sys 0.61.2",
+ "windows-sys 0.60.2",
 ]
 
 [[package]]
@@ -3007,7 +3007,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3a766e1110788c36f4fa1c2b71b387a7815aa65f88ce0229841826633d93723e"
 dependencies = [
  "libc",
- "windows-sys 0.61.2",
+ "windows-sys 0.60.2",
 ]
 
 [[package]]
@@ -3100,7 +3100,7 @@ dependencies = [
  "getrandom 0.4.2",
  "once_cell",
  "rustix",
- "windows-sys 0.61.2",
+ "windows-sys 0.60.2",
 ]
 
 [[package]]
@@ -3534,9 +3534,9 @@ checksum = "f17aaa1c6e3dc22b1da4b6bba97d066e354c7945cac2f7852d4e4e7ca7a6b56d"
 
 [[package]]
 name = "tonic"
-version = "0.14.5"
+version = "0.14.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fec7c61a0695dc1887c1b53952990f3ad2e3a31453e1f49f10e75424943a93ec"
+checksum = "ac2a5518c70fa84342385732db33fb3f44bc4cc748936eb5833d2df34d6445ef"
 dependencies = [
  "async-trait",
  "axum",
@@ -4033,7 +4033,7 @@ version = "0.1.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22"
 dependencies = [
- "windows-sys 0.61.2",
+ "windows-sys 0.60.2",
 ]
 
 [[package]]

data/README.md

@@ -1092,6 +1092,63 @@ it will raise the error raised in the activity.
 The constructor of the environment has multiple keyword arguments that can be set to affect the activity context for the
 activity.
 
+#### Standalone Activities
+
+Activities can be started directly from a client, outside the context of any workflow. Standalone activities reuse the
+existing `Activity::Definition` class — the same activity code runs whether invoked from a workflow or as a standalone
+activity. They are addressed by `activity_id` (with an optional `activity_run_id` for disambiguating re-runs).
+
+Start a standalone activity:
+
+```ruby
+handle = client.start_activity(
+  MyActivity,
+  'some-arg',
+  id: 'my-activity-id',
+  task_queue: 'my-task-queue',
+  start_to_close_timeout: 60
+)
+result = handle.result   # blocks until the activity completes
+```
+
+Or use the execute helper to start and wait:
+
+```ruby
+result = client.execute_activity(
+  MyActivity, 'some-arg',
+  id: 'my-activity-id', task_queue: 'my-task-queue', start_to_close_timeout: 60
+)
+```
+
+Get a handle to an existing standalone activity to describe, cancel, terminate, or fetch its result:
+
+```ruby
+handle = client.activity_handle('my-activity-id')
+description = handle.describe       # ActivityExecution::Description
+result = handle.result              # blocks until the activity reaches a terminal state
+handle.cancel('reason for cancel')  # or
+handle.terminate('reason for terminate')
+```
+
+List and count standalone activities (visibility queries):
+
+```ruby
+client.list_activities('ActivityType="MyActivity"').each { |exec| puts exec.activity_id }
+count = client.count_activities('ActivityType="MyActivity"').count
+```
+
+Inside an activity body, `Temporalio::Activity::Context.current.info` exposes whether the activity is standalone
+or workflow-scheduled:
+
+```ruby
+info = Temporalio::Activity::Context.current.info
+if info.in_workflow?
+  # info.workflow_id, info.workflow_run_id, info.workflow_type are set
+else
+  # info.activity_run_id is set; workflow_* fields are nil
+end
+```
+
 ### Telemetry
 
 #### Metrics

data/lib/temporalio/activity/definition.rb

@@ -155,6 +155,28 @@ module Temporalio
         # @return [Object, nil] Result hint
         attr_reader :result_hint
 
+        # Resolve an activity argument into a `[name, arg_hints, result_hint]` triple. Used by
+        # `Client#start_activity` to accept any of: a `Definition` subclass, an instance of one,
+        # an `Info`, a `Symbol` activity name, or a `String` activity name. Class/instance/Info
+        # inputs carry their definition's hints; Symbol/String inputs return `nil` hints.
+        #
+        # @param activity [Class<Definition>, Definition, Info, Symbol, String] Activity argument.
+        # @return [Array(String, Array[Object]?, Object?)] name, arg_hints, result_hint.
+        def self._type_and_hints_from_parameter(activity)
+          case activity
+          when String, Symbol
+            [activity.to_s, nil, nil]
+          when Class, Definition, Info
+            # Return or construct an Info -- needed because we want the checks in Info.initialize.
+            info = from_activity(activity)
+            raise ArgumentError, 'Cannot pass dynamic activity to start_activity' unless info.name
+
+            [info.name.to_s, info.arg_hints, info.result_hint]
+          else
+            raise ArgumentError, "#{activity} is not an activity class, instance, info, symbol, or string"
+          end
+        end
+
         # Obtain definition info representing the given activity, which can be a class, instance, or definition info.
         #
         # @param activity [Definition, Class<Definition>, Info] Activity to get info for.

data/lib/temporalio/activity/info.rb

@@ -7,11 +7,13 @@ module Temporalio
   module Activity
     Info = Data.define(
       :activity_id,
+      :activity_run_id,
       :activity_type,
       :attempt,
       :current_attempt_scheduled_time,
       :heartbeat_timeout,
       :local?,
+      :namespace,
       :priority,
       :retry_policy,
       :raw_heartbeat_details,
@@ -31,16 +33,21 @@ module Temporalio
     #
     # @!attribute activity_id
     #   @return [String] ID for the activity.
+    # @!attribute activity_run_id
+    #   @return [String, nil] Run ID for a standalone activity execution. nil for activities scheduled from a workflow.
+    #     WARNING: Standalone Activities are experimental.
     # @!attribute activity_type
     #   @return [String] Type name for the activity.
     # @!attribute attempt
-    #   @return [Integer] Attempt the activity is on.
+    #   @return [Integer] Attempt the activity is on. Attempts start at 1 and increment on each retry.
     # @!attribute current_attempt_scheduled_time
     #   @return [Time] When the current attempt was scheduled.
     # @!attribute heartbeat_timeout
     #   @return [Float, nil] Heartbeat timeout set by the caller.
     # @!attribute local?
     #   @return [Boolean] Whether the activity is a local activity or not.
+    # @!attribute namespace
+    #   @return [String] Namespace this activity is on.
     # @!attribute priority
     #   @return [Priority] The priority of this activity.
     # @!attribute retry_policy
@@ -64,17 +71,26 @@ module Temporalio
     #   @return [String] Task token uniquely identifying this activity. Note, this is a `ASCII-8BIT` encoded string, not
     #     a `UTF-8` encoded string nor a valid UTF-8 string.
     # @!attribute workflow_id
-    #   @return [String] Workflow ID that started this activity.
+    #   @return [String, nil] Workflow ID that started this activity. nil for standalone activities.
     # @!attribute workflow_namespace
-    #   @return [String] Namespace this activity is on.
+    #   @return [String, nil] Namespace of the workflow that scheduled this activity. Nil for standalone
+    #     activities. Prefer {#namespace}, which is always set.
+    #   @deprecated Use {#namespace} instead.
     # @!attribute workflow_run_id
-    #   @return [String] Workflow run ID that started this activity.
+    #   @return [String, nil] Workflow run ID that started this activity. nil for standalone activities.
     # @!attribute workflow_type
-    #   @return [String] Workflow type name that started this activity.
+    #   @return [String, nil] Workflow type name that started this activity. nil for standalone activities.
     #
     # @note WARNING: This class may have required parameters added to its constructor. Users should not instantiate this
     #   class or it may break in incompatible ways.
     class Info
+      # @return [Boolean] True if this activity was scheduled by a workflow execution; false for standalone activities.
+      #
+      # WARNING: Standalone Activities are experimental.
+      def in_workflow?
+        !workflow_id.nil?
+      end
+
       # Convert raw heartbeat details into Ruby types.
       #
       # Note, this live-converts every invocation.

data/lib/temporalio/client/activity_execution.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+require 'temporalio/api'
+require 'temporalio/client/activity_execution_status'
+require 'temporalio/client/pending_activity_state'
+require 'temporalio/internal/proto_utils'
+require 'temporalio/priority'
+require 'temporalio/retry_policy'
+require 'temporalio/search_attributes'
+require 'temporalio/worker_deployment_version'
+
+module Temporalio
+  class Client
+    # Info for a standalone activity execution. Returned by list_activities; extended by {Description}
+    # for describe results.
+    #
+    # WARNING: Standalone Activities are experimental.
+    class ActivityExecution
+      # @return [Api::Activity::V1::ActivityExecutionListInfo, Api::Activity::V1::ActivityExecutionInfo]
+      #   Underlying protobuf info.
+      attr_reader :raw_info
+
+      # @!visibility private
+      def initialize(raw_info)
+        @raw_info = raw_info
+        @search_attributes = Internal::ProtoUtils::LazySearchAttributes.new(raw_info.search_attributes)
+      end
+
+      # @return [String] ID for the activity.
+      def activity_id
+        @raw_info.activity_id
+      end
+
+      # @return [String] Run ID for this activity execution attempt.
+      def activity_run_id
+        Internal::ProtoUtils.string_or(@raw_info.run_id, nil)
+      end
+
+      # @return [String] Type name of the activity.
+      def activity_type
+        @raw_info.activity_type&.name
+      end
+
+      # @return [Time, nil] When the activity was scheduled.
+      def schedule_time
+        Internal::ProtoUtils.timestamp_to_time(@raw_info.schedule_time)
+      end
+
+      # @return [Time, nil] When the activity reached a terminal state.
+      def close_time
+        Internal::ProtoUtils.timestamp_to_time(@raw_info.close_time)
+      end
+
+      # @return [ActivityExecutionStatus] Overall status for the activity.
+      def status
+        Internal::ProtoUtils.enum_to_int(Api::Enums::V1::ActivityExecutionStatus, @raw_info.status)
+      end
+
+      # @return [SearchAttributes, nil] Search attributes attached to this activity if any.
+      def search_attributes
+        @search_attributes.get
+      end
+
+      # @return [String] Task queue for the activity.
+      def task_queue
+        @raw_info.task_queue
+      end
+
+      # @return [Float, nil] How long this activity has been running across all attempts, in seconds.
+      def execution_duration
+        Internal::ProtoUtils.duration_to_seconds(@raw_info.execution_duration)
+      end
+
+      # Rich description of a standalone activity execution; returned by {ActivityHandle#describe}.
+      #
+      # WARNING: Standalone Activities are experimental.
+      class Description < ActivityExecution
+        # @return [Api::WorkflowService::V1::DescribeActivityExecutionResponse] Underlying protobuf response.
+        attr_reader :raw_description
+
+        # @!visibility private
+        def initialize(raw_description, data_converter)
+          super(raw_description.info)
+          @raw_description = raw_description
+          @data_converter = data_converter
+        end
+
+        # @return [PendingActivityState, nil] More detailed breakdown of the running state when
+        #   the activity's status is RUNNING; nil otherwise.
+        def run_state
+          Internal::ProtoUtils.enum_to_int(Api::Enums::V1::PendingActivityState, @raw_info.run_state,
+                                           zero_means_nil: true)
+        end
+
+        # @return [Float, nil] Schedule-to-close timeout in seconds.
+        def schedule_to_close_timeout
+          Internal::ProtoUtils.duration_to_seconds(@raw_info.schedule_to_close_timeout)
+        end
+
+        # @return [Float, nil] Schedule-to-start timeout in seconds.
+        def schedule_to_start_timeout
+          Internal::ProtoUtils.duration_to_seconds(@raw_info.schedule_to_start_timeout)
+        end
+
+        # @return [Float, nil] Start-to-close timeout in seconds.
+        def start_to_close_timeout
+          Internal::ProtoUtils.duration_to_seconds(@raw_info.start_to_close_timeout)
+        end
+
+        # @return [Float, nil] Heartbeat timeout in seconds.
+        def heartbeat_timeout
+          Internal::ProtoUtils.duration_to_seconds(@raw_info.heartbeat_timeout)
+        end
+
+        # @return [Boolean] Whether the activity has recorded any heartbeat details.
+        def has_heartbeat_details? # rubocop:disable Naming/PredicatePrefix
+          !@raw_info.heartbeat_details&.payloads.nil? && !@raw_info.heartbeat_details.payloads.empty?
+        end
+
+        # Deserialized last-heartbeat details. Empty when no heartbeat has been recorded.
+        #
+        # @param hints [Array<Object>, nil] Hints, if any, to assist conversion.
+        # @return [Array<Object>] Converted details.
+        def heartbeat_details(hints: nil)
+          @data_converter.from_payloads(@raw_info.heartbeat_details, hints:)
+        end
+
+        # @return [RetryPolicy] Retry policy in effect for this activity.
+        def retry_policy
+          RetryPolicy._from_proto(@raw_info.retry_policy)
+        end
+
+        # @return [Time, nil] Time the last heartbeat was recorded.
+        def last_heartbeat_time
+          Internal::ProtoUtils.timestamp_to_time(@raw_info.last_heartbeat_time)
+        end
+
+        # @return [Time, nil] Time the last attempt started.
+        def last_started_time
+          Internal::ProtoUtils.timestamp_to_time(@raw_info.last_started_time)
+        end
+
+        # @return [Integer] Current attempt number. Attempts start at 1 and increment on each retry.
+        def attempt
+          @raw_info.attempt
+        end
+
+        # @return [Error::Failure, nil] Failure of the last failed attempt if any.
+        def last_failure
+          return nil unless @raw_info.last_failure
+
+          @data_converter.from_failure(@raw_info.last_failure)
+        end
+
+        # @return [Time, nil] Schedule time + schedule-to-close timeout.
+        def expiration_time
+          Internal::ProtoUtils.timestamp_to_time(@raw_info.expiration_time)
+        end
+
+        # @return [String, nil] Identity of the worker that last picked up this activity.
+        def last_worker_identity
+          Internal::ProtoUtils.string_or(@raw_info.last_worker_identity, nil)
+        end
+
+        # @return [Float, nil] Time from last attempt failure to next retry, in seconds.
+        def current_retry_interval
+          Internal::ProtoUtils.duration_to_seconds(@raw_info.current_retry_interval)
+        end
+
+        # @return [Time, nil] Time when the last attempt completed.
+        def last_attempt_complete_time
+          Internal::ProtoUtils.timestamp_to_time(@raw_info.last_attempt_complete_time)
+        end
+
+        # @return [Time, nil] Time when the next attempt will be scheduled.
+        def next_attempt_schedule_time
+          Internal::ProtoUtils.timestamp_to_time(@raw_info.next_attempt_schedule_time)
+        end
+
+        # @return [WorkerDeploymentVersion, nil] Worker deployment version this activity was last dispatched to.
+        def last_deployment_version
+          raw = @raw_info.last_deployment_version
+          return nil unless raw
+
+          WorkerDeploymentVersion.new(
+            deployment_name: raw.deployment_name,
+            build_id: raw.build_id
+          )
+        end
+
+        # @return [Priority] Priority of this activity.
+        def priority
+          Priority._from_proto(@raw_info.priority)
+        end
+
+        # @return [String, nil] Reason given when cancellation was requested.
+        def canceled_reason
+          Internal::ProtoUtils.string_or(@raw_info.canceled_reason, nil)
+        end
+
+        # @return [String, nil] Static user-metadata summary on the activity.
+        def static_summary
+          user_metadata.first
+        end
+
+        # @return [String, nil] Static user-metadata details on the activity. May be in markdown format.
+        def static_details
+          user_metadata.last
+        end
+
+        private
+
+        def user_metadata
+          @user_metadata ||= Internal::ProtoUtils.from_user_metadata(
+            @raw_info.user_metadata, @data_converter
+          )
+        end
+      end
+    end
+  end
+end

data/lib/temporalio/client/activity_execution_count.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Temporalio
+  class Client
+    # Result of a {Client#count_activities} call.
+    #
+    # WARNING: Standalone Activities are experimental.
+    class ActivityExecutionCount
+      # @return [Integer] Approximate number of activities matching the query. If the query had a group-by clause,
+      #   this is the sum of all the counts in {groups}.
+      attr_reader :count
+
+      # @return [Array<AggregationGroup>] Groups if the query had a group-by clause, or empty if not.
+      attr_reader :groups
+
+      # @!visibility private
+      def initialize(count, groups)
+        @count = count
+        @groups = groups
+      end
+
+      # Aggregation group if the activity count query had a group-by clause.
+      #
+      # WARNING: Standalone Activities are experimental.
+      class AggregationGroup
+        # @return [Integer] Approximate number of activities matching the query for this group.
+        attr_reader :count
+
+        # @return [Array<Object>] Search attribute values for this group.
+        attr_reader :group_values
+
+        # @!visibility private
+        def initialize(count, group_values)
+          @count = count
+          @group_values = group_values
+        end
+      end
+    end
+  end
+end

data/lib/temporalio/client/activity_execution_status.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'temporalio/api'
+
+module Temporalio
+  class Client
+    # Status of a standalone activity execution.
+    #
+    # WARNING: Standalone Activities are experimental.
+    module ActivityExecutionStatus
+      UNSPECIFIED = Api::Enums::V1::ActivityExecutionStatus::ACTIVITY_EXECUTION_STATUS_UNSPECIFIED
+      RUNNING = Api::Enums::V1::ActivityExecutionStatus::ACTIVITY_EXECUTION_STATUS_RUNNING
+      COMPLETED = Api::Enums::V1::ActivityExecutionStatus::ACTIVITY_EXECUTION_STATUS_COMPLETED
+      FAILED = Api::Enums::V1::ActivityExecutionStatus::ACTIVITY_EXECUTION_STATUS_FAILED
+      CANCELED = Api::Enums::V1::ActivityExecutionStatus::ACTIVITY_EXECUTION_STATUS_CANCELED
+      TERMINATED = Api::Enums::V1::ActivityExecutionStatus::ACTIVITY_EXECUTION_STATUS_TERMINATED
+      TIMED_OUT = Api::Enums::V1::ActivityExecutionStatus::ACTIVITY_EXECUTION_STATUS_TIMED_OUT
+    end
+  end
+end

data/lib/temporalio/client/activity_handle.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require 'temporalio/api'
+require 'temporalio/client/activity_execution'
+require 'temporalio/client/interceptor'
+require 'temporalio/error'
+
+module Temporalio
+  class Client
+    # Handle for interacting with a standalone activity. Usually created via {Client.activity_handle}
+    # or {Client#start_activity}.
+    #
+    # WARNING: Standalone Activities are experimental.
+    class ActivityHandle
+      # @return [String] ID for the activity.
+      attr_reader :id
+
+      # @return [String, nil] Run ID for this activity execution. When nil, this handle targets the latest run.
+      attr_reader :run_id
+
+      # @return [Object, nil] Result hint used when deserializing the activity's result. May be overridden per
+      #   {#result} call.
+      attr_reader :result_hint
+
+      # @!visibility private
+      def initialize(client:, id:, run_id:, result_hint:)
+        @client = client
+        @id = id
+        @run_id = run_id
+        @result_hint = result_hint
+      end
+
+      # Wait for the activity's outcome (result or failure). Internally long-polls
+      # PollActivityExecution and reissues until the activity reaches a terminal state, so this can
+      # block indefinitely for long-running activities.
+      #
+      # @param result_hint [Object, nil] Override the result hint. If nil, uses {#result_hint}.
+      # @param rpc_options [RPCOptions, nil] Advanced RPC options.
+      #
+      # @return [Object, nil] Deserialized activity result.
+      #
+      # @raise [Error::ActivityFailedError] With `cause` populated from the activity failure.
+      # @raise [Error::RPCError] RPC error from call.
+      def result(result_hint: nil, rpc_options: nil)
+        hint = result_hint || @result_hint
+        outcome = @client._impl.fetch_activity_outcome(
+          Interceptor::FetchActivityOutcomeInput.new(
+            activity_id: id,
+            activity_run_id: run_id,
+            rpc_options:
+          )
+        )
+        _process_outcome(outcome, hint)
+      end
+
+      # Describe the activity.
+      #
+      # @param rpc_options [RPCOptions, nil] Advanced RPC options.
+      #
+      # @return [ActivityExecution::Description] Activity description.
+      # @raise [Error::RPCError] RPC error from call.
+      def describe(rpc_options: nil)
+        @client._impl.describe_activity(
+          Interceptor::DescribeActivityInput.new(
+            activity_id: id,
+            activity_run_id: run_id,
+            rpc_options:
+          )
+        )
+      end
+
+      # Request cancellation of the activity.
+      #
+      # @param reason [String, nil] Optional cancellation reason recorded on the server.
+      # @param rpc_options [RPCOptions, nil] Advanced RPC options.
+      # @raise [Error::RPCError] RPC error from call.
+      def cancel(reason = nil, rpc_options: nil)
+        @client._impl.cancel_activity(
+          Interceptor::CancelActivityInput.new(
+            activity_id: id,
+            activity_run_id: run_id,
+            reason:,
+            rpc_options:
+          )
+        )
+        nil
+      end
+
+      # Terminate the activity (force-close).
+      #
+      # @param reason [String, nil] Optional termination reason recorded on the activity's failure outcome.
+      # @param rpc_options [RPCOptions, nil] Advanced RPC options.
+      # @raise [Error::RPCError] RPC error from call.
+      def terminate(reason = nil, rpc_options: nil)
+        @client._impl.terminate_activity(
+          Interceptor::TerminateActivityInput.new(
+            activity_id: id,
+            activity_run_id: run_id,
+            reason:,
+            rpc_options:
+          )
+        )
+        nil
+      end
+
+      private
+
+      def _process_outcome(outcome, hint)
+        raise Error, 'Activity completed but outcome is missing from server response' if outcome.nil?
+
+        case outcome.value
+        when :failure
+          cause = @client.data_converter.from_failure(outcome.failure)
+          raise Error::ActivityFailedError.new, cause: cause
+        when :result
+          @client.data_converter.from_payloads(outcome.result, hints: Array(hint)).first
+        else
+          raise Error, "Unknown activity outcome: #{outcome.value.inspect}"
+        end
+      end
+    end
+  end
+end