init impl of user metadata

Author: THardy98

packages/client/src/schedule-helpers.ts

@@ -1,5 +1,5 @@
 import Long from 'long'; // eslint-disable-line import/no-named-as-default
-import { compileRetryPolicy, decompileRetryPolicy, extractWorkflowType, LoadedDataConverter } from '@temporalio/common';
+import { compileRetryPolicy, decompileRetryPolicy, extractWorkflowType, JsonPayloadConverter, LoadedDataConverter } from '@temporalio/common';
 import {
   encodeUnifiedSearchAttributes,
   decodeSearchAttributes,
@@ -189,8 +189,7 @@ export function decodeOptionalStructuredCalendarSpecs(
 }
 
 export function compileScheduleOptions(options: ScheduleOptions): CompiledScheduleOptions {
-  const workflowTypeOrFunc = options.action.workflowType;
-  const workflowType = extractWorkflowType(workflowTypeOrFunc);
+  const workflowType = extractWorkflowType(options.action.workflowType);
   return {
     ...options,
     action: {
@@ -240,6 +239,7 @@ export async function encodeScheduleAction(
   action: CompiledScheduleAction,
   headers: Headers
 ): Promise<temporal.api.schedule.v1.IScheduleAction> {
+  const jsonConverter = new JsonPayloadConverter()
   return {
     startWorkflow: {
       workflowId: action.workflowId,
@@ -263,6 +263,10 @@ export async function encodeScheduleAction(
             }
           : undefined,
       header: { fields: headers },
+      userMetadata: { 
+        summary: jsonConverter.toPayload(action.staticSummary), 
+        details: jsonConverter.toPayload(action.staticDetails) 
+      }
     },
   };
 }

packages/client/src/schedule-types.ts

@@ -783,6 +783,8 @@ export type ScheduleOptionsStartWorkflowAction<W extends Workflow> = {
   | 'workflowExecutionTimeout'
   | 'workflowRunTimeout'
   | 'workflowTaskTimeout'
+  | 'staticDetails'
+  | 'staticSummary'
 > & {
     /**
      * Workflow id to use when starting. Assign a meaningful business id.
@@ -815,6 +817,8 @@ export type ScheduleDescriptionStartWorkflowAction = ScheduleSummaryStartWorkflo
     | 'workflowExecutionTimeout'
     | 'workflowRunTimeout'
     | 'workflowTaskTimeout'
+    | 'staticSummary'
+    | 'staticDetails'
   >;
 
 // Invariant: an existing ScheduleDescriptionAction can be used as is to create or update a schedule

packages/client/src/types.ts

@@ -65,6 +65,8 @@ export interface CountWorkflowExecution {
 export type WorkflowExecutionDescription = Replace<
   WorkflowExecutionInfo,
   {
+    staticSummary?: string;
+    staticDetails?: string;
     raw: DescribeWorkflowExecutionResponse;
   }
 >;

packages/client/src/workflow-client.ts

@@ -22,6 +22,7 @@ import {
   decodeRetryState,
   encodeWorkflowIdConflictPolicy,
   WorkflowIdConflictPolicy,
+  JsonPayloadConverter,
 } from '@temporalio/common';
 import { encodeUnifiedSearchAttributes } from '@temporalio/common/lib/converter/payload-search-attributes';
 import { composeInterceptors } from '@temporalio/common/lib/interceptors';
@@ -510,7 +511,7 @@ export class WorkflowClient extends BaseClient {
 
   protected async _start<T extends Workflow>(
     workflowTypeOrFunc: string | T,
-    options: WithWorkflowArgs<T, WorkflowOptions>,
+    options: WorkflowStartOptions<T>,
     interceptors: WorkflowClientInterceptor[]
   ): Promise<string> {
     const workflowType = extractWorkflowType(workflowTypeOrFunc);
@@ -1196,6 +1197,7 @@ export class WorkflowClient extends BaseClient {
   protected async _signalWithStartWorkflowHandler(input: WorkflowSignalWithStartInput): Promise<string> {
     const { identity } = this.options;
     const { options, workflowType, signalName, signalArgs, headers } = input;
+    const jsonConverter = new JsonPayloadConverter();
     const req: temporal.api.workflowservice.v1.ISignalWithStartWorkflowExecutionRequest = {
       namespace: this.options.namespace,
       identity,
@@ -1225,6 +1227,10 @@ export class WorkflowClient extends BaseClient {
           : undefined,
       cronSchedule: options.cronSchedule,
       header: { fields: headers },
+      userMetadata: {
+        summary: jsonConverter.toPayload(options?.staticSummary),
+        details: jsonConverter.toPayload(options?.staticDetails)
+      }
     };
     try {
       return (await this.workflowService.signalWithStartWorkflowExecution(req)).runId;
@@ -1265,7 +1271,7 @@ export class WorkflowClient extends BaseClient {
   protected async createStartWorkflowRequest(input: WorkflowStartInput): Promise<StartWorkflowExecutionRequest> {
     const { options: opts, workflowType, headers } = input;
     const { identity, namespace } = this.options;
-
+    const jsonConverter = new JsonPayloadConverter()
     return {
       namespace,
       identity,
@@ -1293,6 +1299,10 @@ export class WorkflowClient extends BaseClient {
           : undefined,
       cronSchedule: opts.cronSchedule,
       header: { fields: headers },
+      userMetadata: {
+        summary: jsonConverter.toPayload(opts?.staticSummary),
+        details: jsonConverter.toPayload(opts?.staticDetails)
+      }
     };
   }
 
@@ -1426,8 +1436,12 @@ export class WorkflowClient extends BaseClient {
           workflowExecution: { workflowId, runId },
         });
         const info = await executionInfoFromRaw(raw.workflowExecutionInfo ?? {}, this.client.dataConverter, raw);
+        const jsonConverter = new JsonPayloadConverter()
+        const userMetadata = raw.executionConfig?.userMetadata
         return {
           ...info,
+          staticDetails: userMetadata?.details ? jsonConverter.fromPayload(userMetadata.details) : undefined,
+          staticSummary: userMetadata?.summary ? jsonConverter.fromPayload(userMetadata.summary) : undefined,
           raw,
         };
       },

packages/common/src/workflow-options.ts

@@ -190,6 +190,21 @@ export interface BaseWorkflowOptions {
    * by {@link typedSearchAttributes}.
    */
   typedSearchAttributes?: SearchAttributePair[] | TypedSearchAttributes;
+
+  /**
+   * General fixed details for this workflow execution that may appear in UI/CLI. 
+   * This can be in Temporal markdown format and can span multiple lines.
+   * 
+   * @experimental 
+   */
+  staticDetails?: string;
+  /**
+   * A single-line fixed summary for this workflow execution that may appear in the UI/CLI.
+   * This can be in single-line Temporal markdown format.
+   * 
+   * @experimental
+   */
+  staticSummary?: string;
 }
 
 export type WithWorkflowArgs<W extends Workflow, T> = T &

packages/workflow/src/interceptors.ts

@@ -7,7 +7,7 @@
  */
 
 import { ActivityOptions, Headers, LocalActivityOptions, Next, Timestamp, WorkflowExecution } from '@temporalio/common';
-import type { coresdk } from '@temporalio/proto';
+import type { coresdk, temporal } from '@temporalio/proto';
 import { ChildWorkflowOptionsWithDefaults, ContinueAsNewOptions } from './interfaces';
 
 export { Next, Headers };
@@ -80,6 +80,7 @@ export interface ActivityInput {
   readonly options: ActivityOptions;
   readonly headers: Headers;
   readonly seq: number;
+  readonly cmdOpts?: WorkflowCommandOptions;
 }
 
 /** Input for WorkflowOutboundCallsInterceptor.scheduleLocalActivity */
@@ -91,6 +92,7 @@ export interface LocalActivityInput {
   readonly seq: number;
   readonly originalScheduleTime?: Timestamp;
   readonly attempt: number;
+  readonly cmdOpts?: WorkflowCommandOptions;
 }
 
 /** Input for WorkflowOutboundCallsInterceptor.startChildWorkflowExecution */
@@ -101,10 +103,33 @@ export interface StartChildWorkflowExecutionInput {
   readonly seq: number;
 }
 
+/**
+ * User metadata that can be attached to workflow commands.
+ * 
+ * Current used for:
+ * - startTimer, scheduleActivity/scheduleLocalActivity commands
+ * - internal metadata query
+ */
+export interface UserMetadata {
+  /** @experimental A single line summary of the command's purpose */
+  summary?: string;
+  /** @experimental Additional details about the command for longer-text description, can span multiple lines */
+  details?: string;
+}
+
+/**
+ * Options that can be attached to workflow commands.
+ */
+export interface WorkflowCommandOptions {
+  /** User metadata for the command that may be persisted to history */
+  readonly userMetadata?: UserMetadata
+}
+
 /** Input for WorkflowOutboundCallsInterceptor.startTimer */
 export interface TimerInput {
   readonly durationMs: number;
   readonly seq: number;
+  readonly cmdOpts?: WorkflowCommandOptions;
 }
 
 /**

packages/workflow/src/internals.ts

@@ -313,6 +313,7 @@ export class Activator implements ActivationHandler {
               signalDefinitions,
               updateDefinitions,
             },
+            currentDetails: this.currentDetails,
           };
         },
         description: 'Returns metadata associated with this workflow.',
@@ -416,6 +417,8 @@ export class Activator implements ActivationHandler {
 
   public readonly registeredActivityNames: Set<string>;
 
+  public currentDetails: string = "";
+
   constructor({
     info,
     now,