@temporalio/activity 1.12.2 → 1.13.0

package/lib/index.d.ts

@@ -48,7 +48,7 @@
  *
  * 1. `await` on {@link Context.cancelled | `Context.current().cancelled`} or
  *    {@link Context.sleep | `Context.current().sleep()`}, which each throw a {@link CancelledFailure}.
- * 1. Pass the context's {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | `AbortSignal`} at
+ * 2. Pass the context's {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | `AbortSignal`} at
  *    {@link Context.cancellationSignal | `Context.current().cancellationSignal`} to a library that supports it.
  *
  * ### Examples
@@ -69,7 +69,9 @@
  * @module
  */
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { Logger, Duration, MetricMeter, Priority } from '@temporalio/common';
+import { Logger, Duration, MetricMeter, Priority, ActivityCancellationDetails } from '@temporalio/common';
+import { ActivityCancellationDetailsHolder } from '@temporalio/common/lib/activity-cancellation-details';
+import { Client } from '@temporalio/client';
 export { ActivityFunction, ActivityInterface, // eslint-disable-line deprecation/deprecation
 ApplicationFailure, CancelledFailure, UntypedActivities, } from '@temporalio/common';
 /**
@@ -195,12 +197,6 @@ export interface Info {
  * Call `Context.current()` from Activity code in order to get the current Activity's Context.
  */
 export declare class Context {
-    /**
-     * Gets the context of the current Activity.
-     *
-     * Uses {@link https://nodejs.org/docs/latest-v16.x/api/async_context.html#class-asynclocalstorage | AsyncLocalStorage} under the hood to make it accessible in nested callbacks and promises.
-     */
-    static current(): Context;
     /**
      * Holds information about the current executing Activity.
      */
@@ -233,6 +229,10 @@ export declare class Context {
      * The heartbeat implementation, injected via the constructor.
      */
     protected readonly heartbeatFn: (details?: any) => void;
+    /**
+     * The Worker's client, passed down through Activity context.
+     */
+    protected readonly _client: Client | undefined;
     /**
      * The logger for this Activity.
      *
@@ -256,12 +256,85 @@ export declare class Context {
      * intercepts the `getMetricTags()` method.
      */
     readonly metricMeter: MetricMeter;
+    /**
+     * Holder object for activity cancellation details
+     */
+    protected readonly _cancellationDetails: ActivityCancellationDetailsHolder;
+    /**
+     * Gets the context of the current Activity.
+     *
+     * Uses {@link https://nodejs.org/docs/latest-v16.x/api/async_context.html#class-asynclocalstorage | AsyncLocalStorage} under the hood to make it accessible in nested callbacks and promises.
+     */
+    static current(): Context;
     /**
      * **Not** meant to instantiated by Activity code, used by the worker.
      *
      * @ignore
      */
-    constructor(info: Info, cancelled: Promise<never>, cancellationSignal: AbortSignal, heartbeat: (details?: any) => void, log: Logger, metricMeter: MetricMeter);
+    constructor(
+    /**
+     * Holds information about the current executing Activity.
+     */
+    info: Info, 
+    /**
+     * A Promise that fails with a {@link CancelledFailure} when cancellation of this activity is requested. The promise
+     * is guaranteed to never successfully resolve. Await this promise in an Activity to get notified of cancellation.
+     *
+     * Note that to get notified of cancellation, an activity must _also_ {@link Context.heartbeat}.
+     *
+     * @see [Cancellation](/api/namespaces/activity#cancellation)
+     */
+    cancelled: Promise<never>, 
+    /**
+     * An {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | `AbortSignal`} that can be used to react to
+     * Activity cancellation.
+     *
+     * This can be passed in to libraries such as
+     * {@link https://www.npmjs.com/package/node-fetch#request-cancellation-with-abortsignal | fetch} to abort an
+     * in-progress request and
+     * {@link https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options child_process}
+     * to abort a child process, as well as other built-in node modules and modules found on npm.
+     *
+     * Note that to get notified of cancellation, an activity must _also_ {@link Context.heartbeat}.
+     *
+     * @see [Cancellation](/api/namespaces/activity#cancellation)
+     */
+    cancellationSignal: AbortSignal, 
+    /**
+     * The heartbeat implementation, injected via the constructor.
+     */
+    heartbeatFn: (details?: any) => void, 
+    /**
+     * The Worker's client, passed down through Activity context.
+     */
+    _client: Client | undefined, 
+    /**
+     * The logger for this Activity.
+     *
+     * This defaults to the `Runtime`'s Logger (see {@link Runtime.logger}). Attributes from the current Activity context
+     * are automatically included as metadata on every log entries. An extra `sdkComponent` metadata attribute is also
+     * added, with value `activity`; this can be used for fine-grained filtering of log entries further downstream.
+     *
+     * To customize log attributes, register a {@link ActivityOutboundCallsInterceptor} that intercepts the
+     * `getLogAttributes()` method.
+     *
+     * Modifying the context logger (eg. `context.log = myCustomLogger` or by an {@link ActivityInboundLogInterceptor}
+     * with a custom logger as argument) is deprecated. Doing so will prevent automatic inclusion of custom log attributes
+     * through the `getLogAttributes()` interceptor. To customize _where_ log messages are sent, set the
+     * {@link Runtime.logger} property instead.
+     */
+    log: Logger, 
+    /**
+     * Get the metric meter for this activity with activity-specific tags.
+     *
+     * To add custom tags, register a {@link ActivityOutboundCallsInterceptor} that
+     * intercepts the `getMetricTags()` method.
+     */
+    metricMeter: MetricMeter, 
+    /**
+     * Holder object for activity cancellation details
+     */
+    _cancellationDetails: ActivityCancellationDetailsHolder);
     /**
      * Send a {@link https://docs.temporal.io/concepts/what-is-an-activity-heartbeat | heartbeat} from an Activity.
      *
@@ -284,12 +357,30 @@ export declare class Context {
      * subscribe to cancellation notifications.
      */
     readonly heartbeat: (details?: unknown) => void;
+    /**
+     * A Temporal Client, bound to the same Temporal Namespace as the Worker executing this Activity.
+     *
+     * May throw an {@link IllegalStateError} if the Activity is running inside a `MockActivityEnvironment`
+     * that was created without a Client.
+     *
+     * @experimental Client support over `NativeConnection` is experimental. Error handling may be
+     *               incomplete or different from what would be observed using a {@link Connection}
+     *               instead. Client doesn't support cancellation through a Signal.
+     */
+    get client(): Client;
     /**
      * Helper function for sleeping in an Activity.
      * @param ms Sleep duration: number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
      * @returns A Promise that either resolves when `ms` is reached or rejects when the Activity is cancelled
      */
     readonly sleep: (ms: Duration) => Promise<void>;
+    /**
+     * Return the cancellation details for this activity, if any.
+     * @returns an object with boolean properties that describes the reason for cancellation, or undefined if not cancelled.
+     *
+     * @experimental Activity cancellation details include usage of experimental features such as activity pause, and may be subject to change.
+     */
+    get cancellationDetails(): ActivityCancellationDetails | undefined;
 }
 /**
  * The current Activity's context.
@@ -334,6 +425,13 @@ export declare function heartbeat(details?: unknown): void;
  * This is a shortcut for `Context.current().cancelled` (see {@link Context.cancelled}).
  */
 export declare function cancelled(): Promise<never>;
+/**
+ * Return the cancellation details for this activity, if any.
+ * @returns an object with boolean properties that describes the reason for cancellation, or undefined if not cancelled.
+ *
+ * @experimental Activity cancellation details include usage of experimental features such as activity pause, and may be subject to change.
+ */
+export declare function cancellationDetails(): ActivityCancellationDetails | undefined;
 /**
  * Return an {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | `AbortSignal`} that can be used to
  * react to Activity cancellation.
@@ -349,6 +447,19 @@ export declare function cancelled(): Promise<never>;
  * This is a shortcut for `Context.current().cancellationSignal` (see {@link Context.cancellationSignal}).
  */
 export declare function cancellationSignal(): AbortSignal;
+/**
+ * A Temporal Client, bound to the same Temporal Namespace as the Worker executing this Activity.
+ *
+ * May throw an {@link IllegalStateError} if the Activity is running inside a `MockActivityEnvironment`
+ * that was created without a Client.
+ *
+ * This is a shortcut for `Context.current().client` (see {@link Context.client}).
+ *
+ * @experimental Client support over `NativeConnection` is experimental. Error handling may be
+ *               incomplete or different from what would be observed using a {@link Connection}
+ *               instead. Client doesn't support cancellation through a Signal.
+ */
+export declare function getClient(): Client;
 /**
  * Get the metric meter for the current activity, with activity-specific tags.
  *

package/lib/index.js

@@ -49,7 +49,7 @@
  *
  * 1. `await` on {@link Context.cancelled | `Context.current().cancelled`} or
  *    {@link Context.sleep | `Context.current().sleep()`}, which each throw a {@link CancelledFailure}.
- * 1. Pass the context's {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | `AbortSignal`} at
+ * 2. Pass the context's {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | `AbortSignal`} at
  *    {@link Context.cancellationSignal | `Context.current().cancellationSignal`} to a library that supports it.
  *
  * ### Examples
@@ -81,13 +81,16 @@ exports.activityInfo = activityInfo;
 exports.sleep = sleep;
 exports.heartbeat = heartbeat;
 exports.cancelled = cancelled;
+exports.cancellationDetails = cancellationDetails;
 exports.cancellationSignal = cancellationSignal;
+exports.getClient = getClient;
 const node_async_hooks_1 = require("node:async_hooks");
+const common_1 = require("@temporalio/common");
 const time_1 = require("@temporalio/common/lib/time");
 const type_helpers_1 = require("@temporalio/common/lib/type-helpers");
-var common_1 = require("@temporalio/common");
-Object.defineProperty(exports, "ApplicationFailure", { enumerable: true, get: function () { return common_1.ApplicationFailure; } });
-Object.defineProperty(exports, "CancelledFailure", { enumerable: true, get: function () { return common_1.CancelledFailure; } });
+var common_2 = require("@temporalio/common");
+Object.defineProperty(exports, "ApplicationFailure", { enumerable: true, get: function () { return common_2.ApplicationFailure; } });
+Object.defineProperty(exports, "CancelledFailure", { enumerable: true, get: function () { return common_2.CancelledFailure; } });
 /**
  * Throw this error from an Activity in order to make the Worker forget about this Activity.
  *
@@ -128,6 +131,14 @@ exports.asyncLocalStorage = globalThis[asyncLocalStorageSymbol];
  * Call `Context.current()` from Activity code in order to get the current Activity's Context.
  */
 class Context {
+    info;
+    cancelled;
+    cancellationSignal;
+    heartbeatFn;
+    _client;
+    log;
+    metricMeter;
+    _cancellationDetails;
     /**
      * Gets the context of the current Activity.
      *
@@ -140,10 +151,16 @@ class Context {
         }
         return store;
     }
+    /**
+     * **Not** meant to instantiated by Activity code, used by the worker.
+     *
+     * @ignore
+     */
+    constructor(
     /**
      * Holds information about the current executing Activity.
      */
-    info;
+    info, 
     /**
      * A Promise that fails with a {@link CancelledFailure} when cancellation of this activity is requested. The promise
      * is guaranteed to never successfully resolve. Await this promise in an Activity to get notified of cancellation.
@@ -152,7 +169,7 @@ class Context {
      *
      * @see [Cancellation](/api/namespaces/activity#cancellation)
      */
-    cancelled;
+    cancelled, 
     /**
      * An {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | `AbortSignal`} that can be used to react to
      * Activity cancellation.
@@ -167,11 +184,15 @@ class Context {
      *
      * @see [Cancellation](/api/namespaces/activity#cancellation)
      */
-    cancellationSignal;
+    cancellationSignal, 
     /**
      * The heartbeat implementation, injected via the constructor.
      */
-    heartbeatFn;
+    heartbeatFn, 
+    /**
+     * The Worker's client, passed down through Activity context.
+     */
+    _client, 
     /**
      * The logger for this Activity.
      *
@@ -187,26 +208,26 @@ class Context {
      * through the `getLogAttributes()` interceptor. To customize _where_ log messages are sent, set the
      * {@link Runtime.logger} property instead.
      */
-    log;
+    log, 
     /**
      * Get the metric meter for this activity with activity-specific tags.
      *
      * To add custom tags, register a {@link ActivityOutboundCallsInterceptor} that
      * intercepts the `getMetricTags()` method.
      */
-    metricMeter;
+    metricMeter, 
     /**
-     * **Not** meant to instantiated by Activity code, used by the worker.
-     *
-     * @ignore
+     * Holder object for activity cancellation details
      */
-    constructor(info, cancelled, cancellationSignal, heartbeat, log, metricMeter) {
+    _cancellationDetails) {
         this.info = info;
         this.cancelled = cancelled;
         this.cancellationSignal = cancellationSignal;
-        this.heartbeatFn = heartbeat;
+        this.heartbeatFn = heartbeatFn;
+        this._client = _client;
         this.log = log;
         this.metricMeter = metricMeter;
+        this._cancellationDetails = _cancellationDetails;
     }
     /**
      * Send a {@link https://docs.temporal.io/concepts/what-is-an-activity-heartbeat | heartbeat} from an Activity.
@@ -232,6 +253,22 @@ class Context {
     heartbeat = (details) => {
         this.heartbeatFn(details);
     };
+    /**
+     * A Temporal Client, bound to the same Temporal Namespace as the Worker executing this Activity.
+     *
+     * May throw an {@link IllegalStateError} if the Activity is running inside a `MockActivityEnvironment`
+     * that was created without a Client.
+     *
+     * @experimental Client support over `NativeConnection` is experimental. Error handling may be
+     *               incomplete or different from what would be observed using a {@link Connection}
+     *               instead. Client doesn't support cancellation through a Signal.
+     */
+    get client() {
+        if (this._client === undefined) {
+            throw new common_1.IllegalStateError('No Client available. This may be a MockActivityEnvironment that was created without a Client.');
+        }
+        return this._client;
+    }
     /**
      * Helper function for sleeping in an Activity.
      * @param ms Sleep duration: number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
@@ -244,6 +281,15 @@ class Context {
         });
         return Promise.race([this.cancelled.finally(() => clearTimeout(handle)), timer]);
     };
+    /**
+     * Return the cancellation details for this activity, if any.
+     * @returns an object with boolean properties that describes the reason for cancellation, or undefined if not cancelled.
+     *
+     * @experimental Activity cancellation details include usage of experimental features such as activity pause, and may be subject to change.
+     */
+    get cancellationDetails() {
+        return this._cancellationDetails.details;
+    }
 }
 exports.Context = Context;
 /**
@@ -319,6 +365,15 @@ function heartbeat(details) {
 function cancelled() {
     return Context.current().cancelled;
 }
+/**
+ * Return the cancellation details for this activity, if any.
+ * @returns an object with boolean properties that describes the reason for cancellation, or undefined if not cancelled.
+ *
+ * @experimental Activity cancellation details include usage of experimental features such as activity pause, and may be subject to change.
+ */
+function cancellationDetails() {
+    return Context.current().cancellationDetails;
+}
 /**
  * Return an {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | `AbortSignal`} that can be used to
  * react to Activity cancellation.
@@ -336,6 +391,21 @@ function cancelled() {
 function cancellationSignal() {
     return Context.current().cancellationSignal;
 }
+/**
+ * A Temporal Client, bound to the same Temporal Namespace as the Worker executing this Activity.
+ *
+ * May throw an {@link IllegalStateError} if the Activity is running inside a `MockActivityEnvironment`
+ * that was created without a Client.
+ *
+ * This is a shortcut for `Context.current().client` (see {@link Context.client}).
+ *
+ * @experimental Client support over `NativeConnection` is experimental. Error handling may be
+ *               incomplete or different from what would be observed using a {@link Connection}
+ *               instead. Client doesn't support cancellation through a Signal.
+ */
+function getClient() {
+    return Context.current().client;
+}
 /**
  * Get the metric meter for the current activity, with activity-specific tags.
  *

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temporalio/activity",
-  "version": "1.12.2",
+  "version": "1.13.0",
   "description": "Temporal.io SDK Activity sub-package",
   "main": "lib/index.js",
   "types": "./lib/index.d.ts",
@@ -13,7 +13,8 @@
   "author": "Temporal Technologies Inc. <sdk@temporal.io>",
   "license": "MIT",
   "dependencies": {
-    "@temporalio/common": "1.12.2",
+    "@temporalio/client": "1.13.0",
+    "@temporalio/common": "1.13.0",
     "abort-controller": "^3.0.0"
   },
   "engines": {
@@ -35,5 +36,5 @@
     "src",
     "lib"
   ],
-  "gitHead": "98393e00b714b8d44a3dc25714d313d3366f4c50"
+  "gitHead": "cf7c1e7d70f0c775f1382fd335b8bd721495f8cc"
 }

package/src/index.ts

@@ -48,7 +48,7 @@
  *
  * 1. `await` on {@link Context.cancelled | `Context.current().cancelled`} or
  *    {@link Context.sleep | `Context.current().sleep()`}, which each throw a {@link CancelledFailure}.
- * 1. Pass the context's {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | `AbortSignal`} at
+ * 2. Pass the context's {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | `AbortSignal`} at
  *    {@link Context.cancellationSignal | `Context.current().cancellationSignal`} to a library that supports it.
  *
  * ### Examples
@@ -70,9 +70,20 @@
  */
 
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { Logger, Duration, LogLevel, LogMetadata, MetricMeter, Priority } from '@temporalio/common';
+import {
+  Logger,
+  Duration,
+  LogLevel,
+  LogMetadata,
+  MetricMeter,
+  Priority,
+  ActivityCancellationDetails,
+  IllegalStateError,
+} from '@temporalio/common';
 import { msToNumber } from '@temporalio/common/lib/time';
 import { SymbolBasedInstanceOfError } from '@temporalio/common/lib/type-helpers';
+import { ActivityCancellationDetailsHolder } from '@temporalio/common/lib/activity-cancellation-details';
+import { Client } from '@temporalio/client';
 
 export {
   ActivityFunction,
@@ -229,86 +240,82 @@ export class Context {
   }
 
   /**
-   * Holds information about the current executing Activity.
-   */
-  public readonly info: Info;
-
-  /**
-   * A Promise that fails with a {@link CancelledFailure} when cancellation of this activity is requested. The promise
-   * is guaranteed to never successfully resolve. Await this promise in an Activity to get notified of cancellation.
-   *
-   * Note that to get notified of cancellation, an activity must _also_ {@link Context.heartbeat}.
+   * **Not** meant to instantiated by Activity code, used by the worker.
    *
-   * @see [Cancellation](/api/namespaces/activity#cancellation)
+   * @ignore
    */
-  public readonly cancelled: Promise<never>;
+  constructor(
+    /**
+     * Holds information about the current executing Activity.
+     */
+    public readonly info: Info,
 
-  /**
-   * An {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | `AbortSignal`} that can be used to react to
-   * Activity cancellation.
-   *
-   * This can be passed in to libraries such as
-   * {@link https://www.npmjs.com/package/node-fetch#request-cancellation-with-abortsignal | fetch} to abort an
-   * in-progress request and
-   * {@link https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options child_process}
-   * to abort a child process, as well as other built-in node modules and modules found on npm.
-   *
-   * Note that to get notified of cancellation, an activity must _also_ {@link Context.heartbeat}.
-   *
-   * @see [Cancellation](/api/namespaces/activity#cancellation)
-   */
-  public readonly cancellationSignal: AbortSignal;
+    /**
+     * A Promise that fails with a {@link CancelledFailure} when cancellation of this activity is requested. The promise
+     * is guaranteed to never successfully resolve. Await this promise in an Activity to get notified of cancellation.
+     *
+     * Note that to get notified of cancellation, an activity must _also_ {@link Context.heartbeat}.
+     *
+     * @see [Cancellation](/api/namespaces/activity#cancellation)
+     */
+    public readonly cancelled: Promise<never>,
 
-  /**
-   * The heartbeat implementation, injected via the constructor.
-   */
-  protected readonly heartbeatFn: (details?: any) => void;
+    /**
+     * An {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | `AbortSignal`} that can be used to react to
+     * Activity cancellation.
+     *
+     * This can be passed in to libraries such as
+     * {@link https://www.npmjs.com/package/node-fetch#request-cancellation-with-abortsignal | fetch} to abort an
+     * in-progress request and
+     * {@link https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options child_process}
+     * to abort a child process, as well as other built-in node modules and modules found on npm.
+     *
+     * Note that to get notified of cancellation, an activity must _also_ {@link Context.heartbeat}.
+     *
+     * @see [Cancellation](/api/namespaces/activity#cancellation)
+     */
+    public readonly cancellationSignal: AbortSignal,
 
-  /**
-   * The logger for this Activity.
-   *
-   * This defaults to the `Runtime`'s Logger (see {@link Runtime.logger}). Attributes from the current Activity context
-   * are automatically included as metadata on every log entries. An extra `sdkComponent` metadata attribute is also
-   * added, with value `activity`; this can be used for fine-grained filtering of log entries further downstream.
-   *
-   * To customize log attributes, register a {@link ActivityOutboundCallsInterceptor} that intercepts the
-   * `getLogAttributes()` method.
-   *
-   * Modifying the context logger (eg. `context.log = myCustomLogger` or by an {@link ActivityInboundLogInterceptor}
-   * with a custom logger as argument) is deprecated. Doing so will prevent automatic inclusion of custom log attributes
-   * through the `getLogAttributes()` interceptor. To customize _where_ log messages are sent, set the
-   * {@link Runtime.logger} property instead.
-   */
-  public log: Logger;
+    /**
+     * The heartbeat implementation, injected via the constructor.
+     */
+    protected readonly heartbeatFn: (details?: any) => void,
 
-  /**
-   * Get the metric meter for this activity with activity-specific tags.
-   *
-   * To add custom tags, register a {@link ActivityOutboundCallsInterceptor} that
-   * intercepts the `getMetricTags()` method.
-   */
-  public readonly metricMeter: MetricMeter;
+    /**
+     * The Worker's client, passed down through Activity context.
+     */
+    protected readonly _client: Client | undefined,
 
-  /**
-   * **Not** meant to instantiated by Activity code, used by the worker.
-   *
-   * @ignore
-   */
-  constructor(
-    info: Info,
-    cancelled: Promise<never>,
-    cancellationSignal: AbortSignal,
-    heartbeat: (details?: any) => void,
-    log: Logger,
-    metricMeter: MetricMeter
-  ) {
-    this.info = info;
-    this.cancelled = cancelled;
-    this.cancellationSignal = cancellationSignal;
-    this.heartbeatFn = heartbeat;
-    this.log = log;
-    this.metricMeter = metricMeter;
-  }
+    /**
+     * The logger for this Activity.
+     *
+     * This defaults to the `Runtime`'s Logger (see {@link Runtime.logger}). Attributes from the current Activity context
+     * are automatically included as metadata on every log entries. An extra `sdkComponent` metadata attribute is also
+     * added, with value `activity`; this can be used for fine-grained filtering of log entries further downstream.
+     *
+     * To customize log attributes, register a {@link ActivityOutboundCallsInterceptor} that intercepts the
+     * `getLogAttributes()` method.
+     *
+     * Modifying the context logger (eg. `context.log = myCustomLogger` or by an {@link ActivityInboundLogInterceptor}
+     * with a custom logger as argument) is deprecated. Doing so will prevent automatic inclusion of custom log attributes
+     * through the `getLogAttributes()` interceptor. To customize _where_ log messages are sent, set the
+     * {@link Runtime.logger} property instead.
+     */
+    public log: Logger,
+
+    /**
+     * Get the metric meter for this activity with activity-specific tags.
+     *
+     * To add custom tags, register a {@link ActivityOutboundCallsInterceptor} that
+     * intercepts the `getMetricTags()` method.
+     */
+    public readonly metricMeter: MetricMeter,
+
+    /**
+     * Holder object for activity cancellation details
+     */
+    protected readonly _cancellationDetails: ActivityCancellationDetailsHolder
+  ) {}
 
   /**
    * Send a {@link https://docs.temporal.io/concepts/what-is-an-activity-heartbeat | heartbeat} from an Activity.
@@ -335,6 +342,25 @@ export class Context {
     this.heartbeatFn(details);
   };
 
+  /**
+   * A Temporal Client, bound to the same Temporal Namespace as the Worker executing this Activity.
+   *
+   * May throw an {@link IllegalStateError} if the Activity is running inside a `MockActivityEnvironment`
+   * that was created without a Client.
+   *
+   * @experimental Client support over `NativeConnection` is experimental. Error handling may be
+   *               incomplete or different from what would be observed using a {@link Connection}
+   *               instead. Client doesn't support cancellation through a Signal.
+   */
+  public get client(): Client {
+    if (this._client === undefined) {
+      throw new IllegalStateError(
+        'No Client available. This may be a MockActivityEnvironment that was created without a Client.'
+      );
+    }
+    return this._client;
+  }
+
   /**
    * Helper function for sleeping in an Activity.
    * @param ms Sleep duration: number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
@@ -347,6 +373,16 @@ export class Context {
     });
     return Promise.race([this.cancelled.finally(() => clearTimeout(handle)), timer]);
   };
+
+  /**
+   * Return the cancellation details for this activity, if any.
+   * @returns an object with boolean properties that describes the reason for cancellation, or undefined if not cancelled.
+   *
+   * @experimental Activity cancellation details include usage of experimental features such as activity pause, and may be subject to change.
+   */
+  public get cancellationDetails(): ActivityCancellationDetails | undefined {
+    return this._cancellationDetails.details;
+  }
 }
 
 /**
@@ -427,6 +463,16 @@ export function cancelled(): Promise<never> {
   return Context.current().cancelled;
 }
 
+/**
+ * Return the cancellation details for this activity, if any.
+ * @returns an object with boolean properties that describes the reason for cancellation, or undefined if not cancelled.
+ *
+ * @experimental Activity cancellation details include usage of experimental features such as activity pause, and may be subject to change.
+ */
+export function cancellationDetails(): ActivityCancellationDetails | undefined {
+  return Context.current().cancellationDetails;
+}
+
 /**
  * Return an {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | `AbortSignal`} that can be used to
  * react to Activity cancellation.
@@ -445,6 +491,22 @@ export function cancellationSignal(): AbortSignal {
   return Context.current().cancellationSignal;
 }
 
+/**
+ * A Temporal Client, bound to the same Temporal Namespace as the Worker executing this Activity.
+ *
+ * May throw an {@link IllegalStateError} if the Activity is running inside a `MockActivityEnvironment`
+ * that was created without a Client.
+ *
+ * This is a shortcut for `Context.current().client` (see {@link Context.client}).
+ *
+ * @experimental Client support over `NativeConnection` is experimental. Error handling may be
+ *               incomplete or different from what would be observed using a {@link Connection}
+ *               instead. Client doesn't support cancellation through a Signal.
+ */
+export function getClient(): Client {
+  return Context.current().client;
+}
+
 /**
  * Get the metric meter for the current activity, with activity-specific tags.
  *