From cd79d6d60e1376c3a83e0a45e2c8680847550707 Mon Sep 17 00:00:00 2001
From: Seth Foster <seth@opentrons.com>
Date: Mon, 11 Mar 2024 15:46:19 -0400
Subject: [PATCH] chore(api): define command note in engine (#14614)

The CommandNote is a piece of data that may be attached to a Command
instance. It will also be exported in CommandSummaries.

Notes are data that are attached to commands by the code that executes
them or the code that dispatches them. They aren't created by authorship
software.

Commands are intended for consumption as part of a run record - the
long-lasting record of what actions the robot took. For instance, the
desktop app or the ODD might consume them to display information about
commands that have been executed.

Notes have very little structure to them, which is on purpose for
robustness of serialization especially across versions. Most fields are
strings, and the model bakes in no references to other pieces of data.
Instead, notes might be attached to other things - Commands might get an
array of notes, for instance. This means that a single note will relate
to exactly one other thing - one command might have 0 or more notes, but
one Note will only ever refer to one Command.

Closes EXEC-287
---
 .../protocol_engine/commands/command.py       | 33 ++++++++++++++++++-
 shared-data/command/types/index.ts            |  7 +++-
 2 files changed, 38 insertions(+), 2 deletions(-)

diff --git a/api/src/opentrons/protocol_engine/commands/command.py b/api/src/opentrons/protocol_engine/commands/command.py
index f8f48bba67c..c2314aab579 100644
--- a/api/src/opentrons/protocol_engine/commands/command.py
+++ b/api/src/opentrons/protocol_engine/commands/command.py
@@ -6,7 +6,15 @@
 from abc import ABC, abstractmethod
 from datetime import datetime
 from enum import Enum
-from typing import TYPE_CHECKING, Generic, Optional, TypeVar, Tuple
+from typing import (
+    TYPE_CHECKING,
+    Generic,
+    Optional,
+    TypeVar,
+    Tuple,
+    Union,
+    Literal,
+)
 
 from pydantic import BaseModel, Field
 from pydantic.generics import GenericModel
@@ -27,6 +35,29 @@
 
 CommandPrivateResultT = TypeVar("CommandPrivateResultT")
 
+NoteKind = Union[Literal["warning", "information"], str]
+
+
+class CommandNote(BaseModel):
+    """A note about a command's execution or dispatch."""
+
+    noteKind: NoteKind = Field(
+        ...,
+        description="The kind of note this is. Only the literal possibilities should be"
+        " relied upon programmatically.",
+    )
+    shortMessage: str = Field(
+        ...,
+        description="The accompanying human-readable short message (suitable for display in a single line)",
+    )
+    longMessage: str = Field(
+        ...,
+        description="A longer message that may contain newlines and formatting characters describing the note.",
+    )
+    source: str = Field(
+        ..., description="An identifier for the party that created the note"
+    )
+
 
 class CommandStatus(str, Enum):
     """Command execution status."""
diff --git a/shared-data/command/types/index.ts b/shared-data/command/types/index.ts
index d3994fc5337..144efa2f46a 100644
--- a/shared-data/command/types/index.ts
+++ b/shared-data/command/types/index.ts
@@ -31,7 +31,12 @@ export * from './timing'
 // NOTE: these key/value pairs will only be present on commands at analysis/run time
 // they pertain only to the actual execution status of a command on hardware, as opposed to
 // the command's identity and parameters which can be known prior to runtime
-
+export interface CommandNote {
+  noteKind: 'warning' | 'information' | string
+  shortMessage: string
+  longMessage: string
+  source: string
+}
 export type CommandStatus = 'queued' | 'running' | 'succeeded' | 'failed'
 export interface CommonCommandRunTimeInfo {
   key?: string