@temporalio/core-bridge 0.16.4 → 0.18.0

package/sdk-core/protos/api_upstream/temporal/api/workflowservice/v1/service.proto

@@ -34,17 +34,24 @@ option csharp_namespace = "Temporal.Api.WorkflowService.V1";
 
 import "temporal/api/workflowservice/v1/request_response.proto";
 
-// WorkflowService API is exposed to provide support for long running applications.  Application is expected to call
-// StartWorkflowExecution to create an instance for each instance of long running workflow.  Such applications are expected
-// to have a worker which regularly polls for WorkflowTask and ActivityTask from the WorkflowService.  For each
-// WorkflowTask, application is expected to process the history of events for that session and respond back with next
-// commands.  For each ActivityTask, application is expected to execute the actual logic for that task and respond back
-// with completion or failure.  Worker is expected to regularly heartbeat while activity task is running.
+// WorkflowService API defines how Temporal SDKs and other clients interact with the Temporal server
+// to create and interact with workflows and activities.
+//
+// Users are expected to call `StartWorkflowExecution` to create a new workflow execution.
+//
+// To drive workflows, a worker using a Temporal SDK must exist which regularly polls for workflow
+// and activity tasks from the service. For each workflow task, the sdk must process the
+// (incremental or complete) event history and respond back with any newly generated commands.
+//
+// For each activity task, the worker is expected to execute the user's code which implements that
+// activity, responding with completion or failure.
 service WorkflowService {
 
-    // RegisterNamespace creates a new namespace which can be used as a container for all resources.  Namespace is a top level
-    // entity within Temporal, used as a container for all resources like workflow executions, task queues, etc.  Namespace
-    // acts as a sandbox and provides isolation for all resources within the namespace.  All resources belongs to exactly one
+    // RegisterNamespace creates a new namespace which can be used as a container for all resources.
+    //
+    // A Namespace is a top level entity within Temporal, and is used as a container for resources
+    // like workflow executions, task queues, etc. A Namespace acts as a sandbox and provides
+    // isolation for all resources within the namespace. All resources belongs to exactly one
     // namespace.
     rpc RegisterNamespace (RegisterNamespaceRequest) returns (RegisterNamespaceResponse) {
     }
@@ -57,169 +64,189 @@ service WorkflowService {
     rpc ListNamespaces (ListNamespacesRequest) returns (ListNamespacesResponse) {
     }
 
+    // UpdateNamespace is used to update the information and configuration of a registered
+    // namespace.
+    //
     // (-- api-linter: core::0134::method-signature=disabled
     //     aip.dev/not-precedent: UpdateNamespace RPC doesn't follow Google API format. --)
     // (-- api-linter: core::0134::response-message-name=disabled
     //     aip.dev/not-precedent: UpdateNamespace RPC doesn't follow Google API format. --)
-    // UpdateNamespace is used to update the information and configuration for a registered namespace.
     rpc UpdateNamespace (UpdateNamespaceRequest) returns (UpdateNamespaceResponse) {
     }
 
-    // DeprecateNamespace is used to update state of a registered namespace to DEPRECATED.  Once the namespace is deprecated
-    // it cannot be used to start new workflow executions.  Existing workflow executions will continue to run on
-    // deprecated namespaces.
+    // DeprecateNamespace is used to update the state of a registered namespace to DEPRECATED.
+    //
+    // Once the namespace is deprecated it cannot be used to start new workflow executions. Existing
+    // workflow executions will continue to run on deprecated namespaces.
+    // Deprecated.
     rpc DeprecateNamespace (DeprecateNamespaceRequest) returns (DeprecateNamespaceResponse) {
     }
 
-    // StartWorkflowExecution starts a new long running workflow instance.  It will create the instance with
-    // 'WorkflowExecutionStarted' event in history and also schedule the first WorkflowTask for the worker to make the
-    // first command for this instance.  It will return 'WorkflowExecutionAlreadyStartedFailure', if an instance already
-    // exists with same workflowId.
+    // StartWorkflowExecution starts a new workflow execution.
+    //
+    // It will create the execution with a `WORKFLOW_EXECUTION_STARTED` event in its history and
+    // also schedule the first workflow task. Returns `WorkflowExecutionAlreadyStarted`, if an
+    // instance already exists with same workflow id.
     rpc StartWorkflowExecution (StartWorkflowExecutionRequest) returns (StartWorkflowExecutionResponse) {
     }
 
-    // GetWorkflowExecutionHistory returns the history of specified workflow execution.  It fails with 'NotFoundFailure' if specified workflow
-    // execution in unknown to the service.
+    // GetWorkflowExecutionHistory returns the history of specified workflow execution. Fails with
+    // `NotFound` if the specified workflow execution is unknown to the service.
     rpc GetWorkflowExecutionHistory (GetWorkflowExecutionHistoryRequest) returns (GetWorkflowExecutionHistoryResponse) {
     }
 
-    // PollWorkflowTaskQueue is called by application worker to process WorkflowTask from a specific task queue.  A
-    // WorkflowTask is dispatched to callers for active workflow executions, with pending workflow tasks.
-    // Application is then expected to call 'RespondWorkflowTaskCompleted' API when it is done processing the WorkflowTask.
-    // It will also create a 'WorkflowTaskStarted' event in the history for that session before handing off WorkflowTask to
-    // application worker.
+    // PollWorkflowTaskQueue is called by workers to make progress on workflows.
+    //
+    // A WorkflowTask is dispatched to callers for active workflow executions with pending workflow
+    // tasks. The worker is expected to call `RespondWorkflowTaskCompleted` when it is done
+    // processing the task. The service will create a `WorkflowTaskStarted` event in the history for
+    // this task before handing it to the worker.
     rpc PollWorkflowTaskQueue (PollWorkflowTaskQueueRequest) returns (PollWorkflowTaskQueueResponse) {
     }
 
-    // RespondWorkflowTaskCompleted is called by application worker to complete a WorkflowTask handed as a result of
-    // 'PollWorkflowTaskQueue' API call.  Completing a WorkflowTask will result in new events for the workflow execution and
-    // potentially new ActivityTask being created for corresponding commands.  It will also create a WorkflowTaskCompleted
-    // event in the history for that session.  Use the 'taskToken' provided as response of PollWorkflowTaskQueue API call
-    // for completing the WorkflowTask.
-    // The response could contain a new workflow task if there is one or if the request asking for one.
+    // RespondWorkflowTaskCompleted is called by workers to successfully complete workflow tasks
+    // they received from `PollWorkflowTaskQueue`.
+    //
+    // Completing a WorkflowTask will write a `WORKFLOW_TASK_COMPLETED` event to the workflow's
+    // history, along with events corresponding to whatever commands the SDK generated while
+    // executing the task (ex timer started, activity task scheduled, etc).
     rpc RespondWorkflowTaskCompleted (RespondWorkflowTaskCompletedRequest) returns (RespondWorkflowTaskCompletedResponse) {
     }
 
-    // RespondWorkflowTaskFailed is called by application worker to indicate failure.  This results in
-    // WorkflowTaskFailedEvent written to the history and a new WorkflowTask created.  This API can be used by client to
-    // either clear sticky task queue or report any panics during WorkflowTask processing.  Temporal will only append first
-    // WorkflowTaskFailed event to the history of workflow execution for consecutive failures.
+    // RespondWorkflowTaskFailed is called by workers to indicate the processing of a workflow task
+    // failed.
+    //
+    // This results in a `WORKFLOW_TASK_FAILED` event written to the history, and a new workflow
+    // task will be scheduled. This API can be used to report unhandled failures resulting from
+    // applying the workflow task.
+    //
+    // Temporal will only append first WorkflowTaskFailed event to the history of workflow execution
+    // for consecutive failures.
     rpc RespondWorkflowTaskFailed (RespondWorkflowTaskFailedRequest) returns (RespondWorkflowTaskFailedResponse) {
     }
 
-    // PollActivityTaskQueue is called by application worker to process ActivityTask from a specific task queue.  ActivityTask
-    // is dispatched to callers whenever a ScheduleTask command is made for a workflow execution.
-    // Application is expected to call 'RespondActivityTaskCompleted' or 'RespondActivityTaskFailed' once it is done
+    // PollActivityTaskQueue is called by workers to process activity tasks from a specific task
+    // queue.
+    //
+    // The worker is expected to call one of the `RespondActivityTaskXXX` methods when it is done
     // processing the task.
-    // Application also needs to call 'RecordActivityTaskHeartbeat' API within 'heartbeatTimeoutSeconds' interval to
-    // prevent the Task from getting timed out.  An in memory event 'ActivityTaskStarted' is also written to mutable state
-    // before the ActivityTask is dispatched to application Worker. 'ActivityTaskStarted' and Activity finish event:
-    // 'ActivityTaskCompleted' / 'ActivityTaskFailed' / 'ActivityTaskTimedout' will both be written to Workflow execution 
-    // history when Activity is finished.
+    //
+    // An activity task is dispatched whenever a `SCHEDULE_ACTIVITY_TASK` command is produced during
+    // workflow execution. An in memory `ACTIVITY_TASK_STARTED` event is written to mutable state
+    // before the task is dispatched to the worker. The started event, and the final event
+    // (`ACTIVITY_TASK_COMPLETED` / `ACTIVITY_TASK_FAILED` / `ACTIVITY_TASK_TIMED_OUT`) will both be
+    // written permanently to Workflow execution history when Activity is finished. This is done to
+    // avoid writing many events in the case of a failure/retry loop.
     rpc PollActivityTaskQueue (PollActivityTaskQueueRequest) returns (PollActivityTaskQueueResponse) {
     }
 
-    // RecordActivityTaskHeartbeat is called by application worker while it is processing an ActivityTask.  If worker fails
-    // to heartbeat within 'heartbeatTimeoutSeconds' interval for the ActivityTask, then it will be marked as timedout and
-    // 'ActivityTaskTimedOut' event will be written to the workflow history.  Calling 'RecordActivityTaskHeartbeat' will
-    // fail with 'NotFoundFailure' in such situations.  Use the 'taskToken' provided as response of
-    // PollActivityTaskQueue API call for heart beating.
+    // RecordActivityTaskHeartbeat is optionally called by workers while they execute activities.
+    //
+    // If worker fails to heartbeat within the `heartbeat_timeout` interval for the activity task,
+    // then it will be marked as timed out and an `ACTIVITY_TASK_TIMED_OUT` event will be written to
+    // the workflow history. Calling `RecordActivityTaskHeartbeat` will fail with `NotFound` in
+    // such situations, in that event, the SDK should request cancellation of the activity.
     rpc RecordActivityTaskHeartbeat (RecordActivityTaskHeartbeatRequest) returns (RecordActivityTaskHeartbeatResponse) {
     }
 
+    // See `RecordActivityTaskHeartbeat`. This version allows clients to record heartbeats by
+    // namespace/workflow id/activity id instead of task token.
+    //
     // (-- api-linter: core::0136::prepositions=disabled
     //     aip.dev/not-precedent: "By" is used to indicate request type. --)
-    // RecordActivityTaskHeartbeatById is called by application worker while it is processing an ActivityTask.  If worker fails
-    // to heartbeat within 'heartbeatTimeoutSeconds' interval for the ActivityTask, then it will be marked as timed out and
-    // 'ActivityTaskTimedOut' event will be written to the workflow history.  Calling 'RecordActivityTaskHeartbeatById' will
-    // fail with 'NotFoundFailure' in such situations.  Instead of using 'taskToken' like in RecordActivityTaskHeartbeat,
-    // use Namespace, WorkflowId and ActivityId
     rpc RecordActivityTaskHeartbeatById (RecordActivityTaskHeartbeatByIdRequest) returns (RecordActivityTaskHeartbeatByIdResponse) {
     }
 
-    // RespondActivityTaskCompleted is called by application worker when it is done processing an ActivityTask.  It will
-    // result in a new 'ActivityTaskCompleted' event being written to the workflow history and a new WorkflowTask
-    // created for the workflow so new commands could be made.  Use the 'taskToken' provided as response of
-    // PollActivityTaskQueue API call for completion. It fails with 'NotFoundFailure' if the taskToken is not valid
-    // anymore due to activity timeout.
+    // RespondActivityTaskCompleted is called by workers when they successfully complete an activity
+    // task.
+    //
+    // This results in a new `ACTIVITY_TASK_COMPLETED` event being written to the workflow history
+    // and a new workflow task created for the workflow. Fails with `NotFound` if the task token is
+    // no longer valid due to activity timeout, already being completed, or never having existed.
     rpc RespondActivityTaskCompleted (RespondActivityTaskCompletedRequest) returns (RespondActivityTaskCompletedResponse) {
     }
 
+    // See `RecordActivityTaskCompleted`. This version allows clients to record completions by
+    // namespace/workflow id/activity id instead of task token.
+    //
     // (-- api-linter: core::0136::prepositions=disabled
     //     aip.dev/not-precedent: "By" is used to indicate request type. --)
-    // RespondActivityTaskCompletedById is called by application worker when it is done processing an ActivityTask.
-    // It will result in a new 'ActivityTaskCompleted' event being written to the workflow history and a new WorkflowTask
-    // created for the workflow so new commands could be made.  Similar to RespondActivityTaskCompleted but use Namespace,
-    // WorkflowId and ActivityId instead of 'taskToken' for completion. It fails with 'NotFoundFailure'
-    // if the these Ids are not valid anymore due to activity timeout.
     rpc RespondActivityTaskCompletedById (RespondActivityTaskCompletedByIdRequest) returns (RespondActivityTaskCompletedByIdResponse) {
     }
 
-    // RespondActivityTaskFailed is called by application worker when it is done processing an ActivityTask.  It will
-    // result in a new 'ActivityTaskFailed' event being written to the workflow history and a new WorkflowTask
-    // created for the workflow instance so new commands could be made.  Use the 'taskToken' provided as response of
-    // PollActivityTaskQueue API call for completion. It fails with 'NotFoundFailure' if the taskToken is not valid
-    // anymore due to activity timeout.
+    // RespondActivityTaskFailed is called by workers when processing an activity task fails.
+    //
+    // This results in a new `ACTIVITY_TASK_FAILED` event being written to the workflow history and
+    // a new workflow task created for the workflow. Fails with `NotFound` if the task token is no
+    // longer valid due to activity timeout, already being completed, or never having existed.
     rpc RespondActivityTaskFailed (RespondActivityTaskFailedRequest) returns (RespondActivityTaskFailedResponse) {
     }
 
+    // See `RecordActivityTaskFailed`. This version allows clients to record failures by
+    // namespace/workflow id/activity id instead of task token.
+    //
     // (-- api-linter: core::0136::prepositions=disabled
     //     aip.dev/not-precedent: "By" is used to indicate request type. --)
-    // RespondActivityTaskFailedById is called by application worker when it is done processing an ActivityTask.
-    // It will result in a new 'ActivityTaskFailed' event being written to the workflow history and a new WorkflowTask
-    // created for the workflow instance so new commands could be made.  Similar to RespondActivityTaskFailed but use
-    // Namespace, WorkflowId and ActivityId instead of 'taskToken' for completion. It fails with 'NotFoundFailure'
-    // if the these Ids are not valid anymore due to activity timeout.
     rpc RespondActivityTaskFailedById (RespondActivityTaskFailedByIdRequest) returns (RespondActivityTaskFailedByIdResponse) {
     }
 
-    // RespondActivityTaskCanceled is called by application worker when it is successfully canceled an ActivityTask.  It will
-    // result in a new 'ActivityTaskCanceled' event being written to the workflow history and a new WorkflowTask
-    // created for the workflow instance so new commands could be made.  Use the 'taskToken' provided as response of
-    // PollActivityTaskQueue API call for completion. It fails with 'NotFoundFailure' if the taskToken is not valid
-    // anymore due to activity timeout.
+    // RespondActivityTaskFailed is called by workers when processing an activity task fails.
+    //
+    // This results in a new `ACTIVITY_TASK_CANCELED` event being written to the workflow history
+    // and a new workflow task created for the workflow. Fails with `NotFound` if the task token is
+    // no longer valid due to activity timeout, already being completed, or never having existed.
     rpc RespondActivityTaskCanceled (RespondActivityTaskCanceledRequest) returns (RespondActivityTaskCanceledResponse) {
     }
 
+    // See `RecordActivityTaskCanceled`. This version allows clients to record failures by
+    // namespace/workflow id/activity id instead of task token.
+    //
     // (-- api-linter: core::0136::prepositions=disabled
     //     aip.dev/not-precedent: "By" is used to indicate request type. --)
-    // RespondActivityTaskCanceledById is called by application worker when it is successfully canceled an ActivityTask.
-    // It will result in a new 'ActivityTaskCanceled' event being written to the workflow history and a new WorkflowTask
-    // created for the workflow instance so new commands could be made.  Similar to RespondActivityTaskCanceled but use
-    // Namespace, WorkflowId and ActivityId instead of 'taskToken' for completion. It fails with 'NotFoundFailure'
-    // if the these Ids are not valid anymore due to activity timeout.
     rpc RespondActivityTaskCanceledById (RespondActivityTaskCanceledByIdRequest) returns (RespondActivityTaskCanceledByIdResponse) {
     }
 
-    // RequestCancelWorkflowExecution is called by application worker when it wants to request cancellation of a workflow instance.
-    // It will result in a new 'WorkflowExecutionCancelRequested' event being written to the workflow history and a new WorkflowTask
-    // created for the workflow instance so new commands could be made. It fails with 'NotFoundFailure' if the workflow is not valid
-    // anymore due to completion or doesn't exist.
+    // RequestCancelWorkflowExecution is called by workers when they want to request cancellation of
+    // a workflow execution.
+    //
+    // This result in a new `WORKFLOW_EXECUTION_CANCEL_REQUESTED` event being written to the
+    // workflow history and a new workflow task created for the workflow. Fails with `NotFound` if
+    // the workflow is already completed or doesn't exist.
     rpc RequestCancelWorkflowExecution (RequestCancelWorkflowExecutionRequest) returns (RequestCancelWorkflowExecutionResponse) {
     }
 
-    // SignalWorkflowExecution is used to send a signal event to running workflow execution.  This results in
-    // WorkflowExecutionSignaled event recorded in the history and a workflow task being created for the execution.
+    // SignalWorkflowExecution is used to send a signal to a running workflow execution.
+    //
+    // This results in a `WORKFLOW_EXECUTION_SIGNALED` event recorded in the history and a workflow
+    // task being created for the execution.
     rpc SignalWorkflowExecution (SignalWorkflowExecutionRequest) returns (SignalWorkflowExecutionResponse) {
     }
 
+    // SignalWithStartWorkflowExecution is used to ensure a signal is sent to a workflow, even if
+    // it isn't yet started.
+    //
+    // If the workflow is running, a `WORKFLOW_EXECUTION_SIGNALED` event is recorded in the history
+    // and a workflow task is generated.
+    //
+    // If the workflow is not running or not found, then the workflow is created with
+    // `WORKFLOW_EXECUTION_STARTED` and `WORKFLOW_EXECUTION_SIGNALED` events in its history, and a
+    // workflow task is generated.
+    //
     // (-- api-linter: core::0136::prepositions=disabled
     //     aip.dev/not-precedent: "With" is used to indicate combined operation. --)
-    // SignalWithStartWorkflowExecution is used to ensure sending signal to a workflow.
-    // If the workflow is running, this results in WorkflowExecutionSignaled event being recorded in the history
-    // and a workflow task being created for the execution.
-    // If the workflow is not running or not found, this results in WorkflowExecutionStarted and WorkflowExecutionSignaled
-    // events being recorded in history, and a workflow task being created for the execution
     rpc SignalWithStartWorkflowExecution (SignalWithStartWorkflowExecutionRequest) returns (SignalWithStartWorkflowExecutionResponse) {
     }
 
-    // ResetWorkflowExecution reset an existing workflow execution to WorkflowTaskCompleted event(exclusive).
-    // And it will immediately terminating the current execution instance.
+    // ResetWorkflowExecution will reset an existing workflow execution to a specified
+    // `WORKFLOW_TASK_COMPLETED` event (exclusive). It will immediately terminate the current
+    // execution instance.
+    // TODO: Does exclusive here mean *just* the completed event, or also WFT started? Otherwise the task is doomed to time out?
     rpc ResetWorkflowExecution (ResetWorkflowExecutionRequest) returns (ResetWorkflowExecutionResponse) {
     }
 
-    // TerminateWorkflowExecution terminates an existing workflow execution by recording WorkflowExecutionTerminated event
-    // in the history and immediately terminating the execution instance.
+    // TerminateWorkflowExecution terminates an existing workflow execution by recording a
+    // `WORKFLOW_EXECUTION_TERMINATED` event in the history and immediately terminating the
+    // execution instance.
     rpc TerminateWorkflowExecution (TerminateWorkflowExecutionRequest) returns (TerminateWorkflowExecutionResponse) {
     }
 
@@ -251,20 +278,25 @@ service WorkflowService {
     rpc GetSearchAttributes (GetSearchAttributesRequest) returns (GetSearchAttributesResponse) {
     }
 
-    // RespondQueryTaskCompleted is called by application worker to complete a QueryTask (which is a WorkflowTask for query)
-    // as a result of 'PollWorkflowTaskQueue' API call. Completing a QueryTask will unblock the client call to 'QueryWorkflow'
-    // API and return the query result to client as a response to 'QueryWorkflow' API call.
+    // RespondQueryTaskCompleted is called by workers to complete queries which were delivered on
+    // the `query` (not `queries`) field of a `PollWorkflowTaskQueueResponse`.
+    //
+    // Completing the query will unblock the corresponding client call to `QueryWorkflow` and return
+    // the query result a response.
     rpc RespondQueryTaskCompleted (RespondQueryTaskCompletedRequest) returns (RespondQueryTaskCompletedResponse) {
     }
 
-    // ResetStickyTaskQueue resets the sticky task queue related information in mutable state of a given workflow.
+    // ResetStickyTaskQueue resets the sticky task queue related information in the mutable state of
+    // a given workflow. This is prudent for workers to perform if a workflow has been paged out of
+    // their cache.
+    //
     // Things cleared are:
     // 1. StickyTaskQueue
     // 2. StickyScheduleToStartTimeout
     rpc ResetStickyTaskQueue (ResetStickyTaskQueueRequest) returns (ResetStickyTaskQueueResponse) {
     }
 
-    // QueryWorkflow returns query result for a specified workflow execution
+    // QueryWorkflow requests a query be executed for a specified workflow execution.
     rpc QueryWorkflow (QueryWorkflowRequest) returns (QueryWorkflowResponse) {
     }
 
@@ -272,8 +304,7 @@ service WorkflowService {
     rpc DescribeWorkflowExecution (DescribeWorkflowExecutionRequest) returns (DescribeWorkflowExecutionResponse) {
     }
 
-    // DescribeTaskQueue returns information about the target task queue, right now this API returns the
-    // pollers which polled this task queue in last few minutes.
+    // DescribeTaskQueue returns information about the target task queue.
     rpc DescribeTaskQueue (DescribeTaskQueueRequest) returns (DescribeTaskQueueResponse) {
     }
 

package/sdk-core/protos/local/temporal/sdk/core/activity_result/activity_result.proto

@@ -0,0 +1,78 @@
+syntax = "proto3";
+
+package coresdk.activity_result;
+
+import "google/protobuf/duration.proto";
+import "google/protobuf/timestamp.proto";
+import "temporal/api/failure/v1/message.proto";
+import "temporal/sdk/core/common/common.proto";
+
+/**
+ * Used to report activity completions to core
+ */
+message ActivityExecutionResult {
+    oneof status {
+        Success completed = 1;
+        Failure failed = 2;
+        Cancellation cancelled = 3;
+        WillCompleteAsync will_complete_async = 4;
+    }
+}
+
+// Used to report activity resolutions to lang. IE: This is what the activities are resolved with
+// in the workflow.
+message ActivityResolution {
+    oneof status {
+        Success completed = 1;
+        Failure failed = 2;
+        Cancellation cancelled = 3;
+        DoBackoff backoff = 4;
+    }
+}
+
+/** Used to report successful completion either when executing or resolving */
+message Success {
+    common.Payload result = 1;
+}
+
+/** Used to report activity failure either when executing or resolving */
+message Failure {
+    temporal.api.failure.v1.Failure failure = 1;
+}
+
+/**
+ * Used to report cancellation from both Core and Lang.
+ * When Lang reports a cancelled activity, it must put a CancelledFailure in the failure field.
+ * When Core reports a cancelled activity, it must put an ActivityFailure with CancelledFailure
+ * as the cause in the failure field.
+ */
+message Cancellation {
+    temporal.api.failure.v1.Failure failure = 1;
+}
+
+/**
+ * Used in ActivityExecutionResult to notify Core that this Activity will complete asynchronously.
+ * Core will forget about this Activity and free up resources used to track this Activity.
+ */
+message WillCompleteAsync {
+}
+
+/**
+ * Issued when a local activity needs to retry but also wants to back off more than would be
+ * reasonable to WFT heartbeat for. Lang is expected to schedule a timer for the duration
+ * and then start a local activity of the same type & same inputs with the provided attempt number
+ * after the timer has elapsed.
+ *
+ * This exists because Core does not have a concept of starting commands by itself, they originate
+ * from lang. So expecting lang to start the timer / next pass of the activity fits more smoothly.
+ */
+message DoBackoff {
+    // The attempt number that lang should provide when scheduling the retry. If the LA failed
+    // on attempt 4 and we told lang to back off with a timer, this number will be 5.
+    uint32 attempt = 1;
+    google.protobuf.Duration backoff_duration = 2;
+    // The time the first attempt of this local activity was scheduled. Must be passed with attempt
+    // to the retry LA.
+    google.protobuf.Timestamp original_schedule_time = 3;
+}
+

package/sdk-core/protos/local/temporal/sdk/core/activity_task/activity_task.proto

@@ -0,0 +1,78 @@
+syntax = "proto3";
+
+/**
+ * Definitions of the different activity tasks returned from [crate::Core::poll_task].
+ */
+package coresdk.activity_task;
+
+import "google/protobuf/duration.proto";
+import "google/protobuf/timestamp.proto";
+import "temporal/sdk/core/common/common.proto";
+
+message ActivityTask {
+    /// A unique identifier for this task
+    bytes task_token = 1;
+    oneof variant {
+        /// Start activity execution.
+        Start start = 3;
+        /// Attempt to cancel activity execution.
+        Cancel cancel = 4;
+    }
+}
+
+// Begin executing an activity
+message Start {
+    // The namespace the workflow lives in
+    string workflow_namespace = 1;
+    // The workflow's type name or function identifier
+    string workflow_type = 2;
+    // The workflow execution which requested this activity
+    common.WorkflowExecution workflow_execution = 3;
+    // The activity's ID
+    string activity_id = 4;
+    // The activity's type name or function identifier
+    string activity_type = 5;
+    map<string, common.Payload> header_fields = 6;
+    // Arguments to the activity
+    repeated common.Payload input = 7;
+    // The last details that were recorded by a heartbeat when this task was generated
+    repeated common.Payload heartbeat_details = 8;
+    // When the task was *first* scheduled
+    google.protobuf.Timestamp scheduled_time = 9;
+    // When this current attempt at the task was scheduled
+    google.protobuf.Timestamp current_attempt_scheduled_time = 10;
+    // When this attempt was started, which is to say when core received it by polling.
+    google.protobuf.Timestamp started_time = 11;
+    uint32 attempt = 12;
+
+    // Timeout from the first schedule time to completion
+    google.protobuf.Duration schedule_to_close_timeout = 13;
+    // Timeout from starting an attempt to reporting its result
+    google.protobuf.Duration start_to_close_timeout = 14;
+    // If set a heartbeat must be reported within this interval
+    google.protobuf.Duration heartbeat_timeout = 15;
+    // This is an actual retry policy the service uses. It can be different from the one provided
+    // (or not) during activity scheduling as the service can override the provided one in case its
+    // values are not specified or exceed configured system limits.
+    common.RetryPolicy retry_policy = 16;
+
+    // Set to true if this is a local activity. Note that heartbeating does not apply to local
+    // activities.
+    bool is_local = 17;
+}
+
+/// Attempt to cancel a running activity
+message Cancel {
+    ActivityCancelReason reason = 1;
+}
+
+enum ActivityCancelReason {
+    /// The activity no longer exists according to server (may be already completed)
+    NOT_FOUND = 0;
+    /// Activity was explicitly cancelled
+    CANCELLED = 1;
+    /// Activity timed out
+    TIMED_OUT = 2;
+}
+
+